API の安定性、バージョニング、非推奨化、サンセット

このページは、コントロールプレーンに対してプログラムするすべてのものに対する 安定性契約 です。何が安定しているか、互換性を壊す変更がどのようにシグナリングされるか、非推奨化されたサーフェスがどのくらいの間機能し続けるかを定めます。その強制は散文ではなくコードベースの中にあります。非推奨化テーブル、レスポンスヘッダ、OpenAPI マーカー、そして以下の期間チェックは、すべて単一のコード内宣言（core/api/stability.go）から駆動されており、ポリシーが許す期間より早くスケジュールされたサンセットは ビルドを失敗させます。

カバーされるサーフェスとティア

サーフェス	バージョニングの単位	現在のティア
REST コア契約 — 提供される OpenAPI ドキュメント内のパス	URL メジャー（`/v1/…`）	stable
gRPC ミラー — proto パッケージ `olivares.api.v1` 内の `ControlPlane`	proto パッケージメジャー	stable（凍結されたミラー）
ライブインジェスト / コネクタ wire — proto パッケージ `olivares.sdk.v1`	proto パッケージメジャー + プラグイン `ProtocolVersion`	stable（凍結済み）
コネクタ SDK（Go）— モジュール `sdk`、`sdk/plugin`（作成者サーフェス）	モジュール semver — 最初の公開リリース以降のタグ `sdk/v`、`sdk/plugin/v`	stable v1（Go 契約。wire は上の行）
イベントバス契約（AsyncAPI 3.0）— そのイベントタイプは、イベンティングプラットフォームが外部 webhook サブスクリプションに配信するものでもある。サブスクリプション管理ルートはモジュールルート（`/v1/m/eventing/`、契約外）だが、各イベントタイプはコード内カタログから自身の安定性ティアを持つ	`info.version`（`1.0.0-preview`）	beta（ドキュメント）。イベントタイプにはタイプごとのティア
Terraform プロバイダ	独自の semver（`terraform-provider-v*` タグ）	stable、MAJOR は API v1 を追従
クライアント SDK（Go / Java / Python / TypeScript）	独自の semver。MAJOR は GA 以降に API メジャーを追従	beta（1.0 以前のパッケージ）
列挙されていないもの — `/v1/m/<ns>/` モジュールルート、SCIM、フェデレーション、内部実装	—	out of contract

ティア。 stable なサーフェスは、そのメジャーバージョン内で互換性を壊す形で変化しません。それを削除または変更するには、以下の非推奨化プロセスが必要です。 beta なサーフェスは依然として形が変わる可能性がありますが、同じシグナリングとより短い期間が適用されます。out-of-contract なサーフェス（特に、OpenAPI ドキュメントから意図的に外されているモジュールルート — リファレンス概要を参照）は互換性の約束を持ちません。その契約は、製品に同梱される型付きインターフェースの中に存在します。

OpenAPI ドキュメント内のすべての操作は機械可読な x-stability マーカーを持ち、ドキュメント自体が info.x-stability-policy でこのページにリンクします。

互換性を壊す変更とは何か

stable なサーフェスについて、以下はすべて互換性を壊す変更であり、以下のプロセスでゲートされます。

パス、メソッド、リクエストフィールド、レスポンスフィールド、またはエラー code の削除または改名。
フィールドの型または意味の変更、あるいはオプショナルなリクエストフィールドを必須にすること。
以前は有効だった呼び出しが失敗するように認証／認可を厳格化すること。
gRPC/protobuf について：buf breaking（FILE ルールセット）が拒否するもの全般。

以下は互換性を壊す変更では ありません：エンドポイントの追加、オプショナルなリクエストパラメータの追加、レスポンスフィールドの追加、新たな失敗モードに対する新しいエラーコードの追加、レスポンスヘッダの追加。クライアントは未知の JSON フィールドを許容しなければなりません。

バージョニング

REST は URL でバージョニングされます。安定契約全体が /v1/ の下に存在します。互換性を壊す変更は /v2/ の下で出荷され、/v1/ が非推奨化に入ります — その場での破壊は決して行いません。
gRPC は proto パッケージでバージョニングされます：olivares.api.v1 / olivares.sdk.v1。互換性を壊す変更には新しいパッケージメジャー（…v2）が必要です。両方の契約は main に対して buf breaking で守られます（task proto:breaking）。
Terraform プロバイダ は独立してリリースされます（terraform-provider-v* タグ）。その MAJOR は、それが話す API メジャーを追従します。
クライアント SDK は API_VERSION（生成元となった契約メジャー）と SPEC_HASH（正確な OpenAPI スナップショット）を埋め込みます — Go では APIVersion と SpecHash。GA 以降、その MAJOR は API メジャーを追従します。
コネクタ SDK（サードパーティのコネクタがビルド対象とする Go 契約）はモジュールごとの semver タグ（sdk/vX.Y.Z、 sdk/plugin/vX.Y.Z）でバージョニングされ、その wire に対して同じ buf breaking の壁でゲートされます。作成者が実装するインターフェースは、メジャー内でメソッドを増やすことは決してありません。新しい機能は新しいオプショナルなインターフェースとして到来します。完全なポリシーはモジュールに同梱されます（sdk/VERSIONING.md）。作成者向けのライフサイクルはコネクタをビルドして出荷するにあります。

非推奨化プロセスとシグナリング

非推奨化は、コード内テーブルに宣言された 1 つのエントリと移行ガイド 1 つから成ります。それ以外のすべては、そこから機械的に従います。

アナウンス。 エントリは、そのアナウンス日付と移行ガイドの URL とともに着地します。その瞬間から、非推奨化されたルートのすべてのレスポンスは RFC 9745 ヘッダとガイドへのリンクを持ち、OpenAPI 操作は deprecated: true、 x-deprecated-at、x-migration-guide を得ます：
```
Deprecation: @1780272000
Link: <https://olivares.ai/docs/how-to/migrate-example/>; rel="deprecation"
```
サンセットのスケジュール。 廃止日付がコミットされると、レスポンスは RFC 8594 ヘッダを追加します（そしてスペックは x-sunset-at を得ます）：
```
Sunset: Thu, 01 Jun 2028 00:00:00 GMT
Link: <https://olivares.ai/docs/how-to/migrate-example/>; rel="sunset"
```
削除 — 最も早くてサンセット日付に、通常は次の API メジャーとともに行います。

最小サポート期間（非推奨化アナウンス → サンセット）：

ティア	最小期間
stable	24 か月
beta	12 か月

これらの期間は、宣言テーブルに対するテストによって強制されます。サンセットがそのティアの期間に違反するエントリ、または存在しないルートを指すエントリはビルドされません。

gRPC について、非推奨化は protobuf の deprecated オプション（生成コードに現れます）に加えて同じ期間で表現されます。wire 契約はそれ以外は凍結されており、buf breaking が互換性を壊す編集を即座に拒否します。

クライアントが見るもの

Terraform プロバイダ — コントロールプレーンのレスポンスが非推奨化シグナルを持つとき、実行ごとに一意のメソッドとリクエストパスごとに 1 回、 tflog の WARN（メソッド、エンドポイント、日付、ガイド）を出します（非推奨化されたパラメータ化ルートは、それが触れるリソースごとに 1 回警告します）。また、非推奨化されたクライアントの利用がサーバー側で帰属可能になるよう、バージョン付きの User-Agent を送信します。
Go SDK — エンドポイントごとに 1 回 DeprecationNotice を表面化します（デフォルト： slog 警告。WithDeprecationHandler でオーバーライド）。非推奨化された操作は Go の // Deprecated: マーカーを持つため、エディタと staticcheck が開発時にそれらをフラグ付けします。
Python SDK — エンドポイントごとに 1 つの DeprecationWarning（またはあなたの on_deprecation コールバック）。非推奨化された操作は docstring 内でマークされます。
TypeScript SDK — エンドポイントごとに 1 つの console.warn（またはあなたの onDeprecation コールバック）。非推奨化された操作は @deprecated JSDoc を持ちます。