リファレンス

リファレンスは情報指向である。その仕事は正確かつ完全であることであって、教えることや説得することでは ない: インターフェースが何であるか、その入力と出力が何であるか、デフォルトが何であるかを述べる —— そしてそこで止まる。散文は意図的に無味乾燥である。実際に手を動かしてシステムを学びたいなら、 チュートリアル から始めること。特定のタスクを達成したいなら、 ハウツーガイド を使うこと。なぜシステムがこのように構築されているか理由を 理解したいなら、解説 を読むこと。このセクションは、製品に対して 構築していて正確な契約が必要なときのためのものである。

以下のほとんどは製品自身のソース成果物から直接生成または手作業で導出されているため、リファレンスが エンジンが実際に提供するものから静かに乖離することはありえない。能力が設計段階または v1 以降である場合、 該当ページが平易にそう述べる。全体的な契約については 正直さと限界 を参照。

リファレンス領域

領域	何を文書化するか	真実の源
REST API	control-plane HTTP API: auth、setup、テナンシー、エージェント、R/RW access map、トークン、監査台帳。	本製品の OpenAPI 3.1 契約（53 のコアパス）。実ファイルからビルド時にレンダリングされる —— コピーではない。
モジュールルート（beta）	製品のモジュールルート（/v1/m/<ns>/…）—— FinOps、compliance、governance、sessions、models、knowledge、… —— を独立した beta OpenAPI ドキュメントとして公開する。	同じ OpenAPI 3.1 契約。モジュールが登録するルートからビルド時に反映される。
安定性ポリシー	バージョニング、安定性階層、非推奨/サンセットのシグナリング、そして API・プロバイダ・クライアント SDK の最小サポートウィンドウ。	コード内の非推奨テーブルと、ビルドを失敗させるウィンドウテスト。
gRPC	エンジンの gRPC ミラーと、すべてのプロセス外コネクタおよびモジュールが使用するバージョン管理された plugin wire 契約。	サーバーが gRPC に渡す grpc.ServiceDesc 登録テーブル。
イベントバス	内部イベントバス: イベントエンベロープ、ファーストパーティのイベント型、そしてコネクタがそこに持ち上げる観測ペイロード。	AsyncAPI 3.0 契約。Go SDK から手作業で導出。
コンソール画面	コンソールが公開するすべてのルート、そのルートが要求する RBAC permission、製品内ヘルプリンクが開くリファレンスページ。	ビルド済み router に固定されたコンソールの route census。
モジュールカタログ	30 の製品モジュール —— それぞれが何であるか、そのステータス、そして（もしあれば）コア API の外にどのルートを公開するか。	製品の能力カタログと型付きモジュールインターフェース。
CLI	olivares バイナリとそのサブコマンド —— serve、collector、audit、license、openapi、version —— とそれらのフラグ。	コンパイルされたコマンド定義。
設定	環境変数とランタイムオプション: データディレクトリ、ソース配線、認可エンジン、台帳署名。	エンジンの設定ローダー。

REST API

REST API リファレンス は、本製品の OpenAPI 3.1 契約からビルド時にレンダリング される —— エンジンが自身の /openapi.json エンドポイントで提供するのと同じドキュメントである。手作業で 転記されるものは何もないため、レンダリングされたリファレンスが契約そのものである。これは、クレデンシャル 不要の初回ブートフロー（POST /v1/setup をワンタイムセットアップトークンとともに、続いて POST /v1/auth/login）、アイデンティティとテナンシー、エージェント、読み取り/書き込み access map （GET /v1/access-edges。その reconcile された least-privilege drift はコア面ではなく access-map モジュールが提供する）、トークン管理、監査台帳をカバーする。

契約は 53 のコアパスを記述する。これは意図的である: それは control plane の安定したバージョン管理 された面であって、エンジンが応答できるすべてのルートではない。「stable」が約束するもの —— バージョニング、 非推奨シグナリング、最小サポートウィンドウ —— は API 安定性ポリシー である。

モジュールルートは独立した beta 契約

モジュールルート —— 例えば access-map モジュールの /v1/m/accessmap/graph、 /v1/m/accessmap/neighbors、/v1/m/accessmap/drift —— は、53 パスの安定コアドキュメントには 含まれない。これらは独立した beta OpenAPI ドキュメント /reference/api-beta/（/openapi.beta.json で提供され、モジュールが実際に 登録するルートから反映される）として公開されるため、安定サーフェスを識別可能に保ちながら、製品全体の サーフェスも引き続きプログラムできる。beta は形状が予告のうえ変更されうること（stable より短い サポートウィンドウ）を意味する。フィールドレベルの詳細は引き続き型付き Go と TypeScript の インターフェースにある。least-privilege の結果は drift ルートである。別個の diff エンドポイントは 存在しない。

gRPC ミラー（olivares.api.v1）

control plane は gRPC 面も公開する —— バージョン管理された proto パッケージ olivares.api.v1 の ControlPlane サービス。これは上記 REST 契約のサブセットの焦点を絞った凍結ミラー（サーバー情報、 エージェントの list/get/create、audit verify）であり、型付きバイナリ契約が好まれる場面（例えば コレクター）で使われる。これは REST 契約を拡張するのではなくミラーする。OpenAPI ドキュメントが完全な API の正準の面のままである。

イベントバス

イベントバスリファレンス は AsyncAPI 3.0 契約である。バスはデフォルトで プロセス内である —— コネクタは正規化された観測を型付きイベントとしてそこに持ち上げ、モジュールと出力 コネクタはイベント型でサブスクライブして反応する。それらが互いを直接呼び出すことは一切ない。NATS 上の 分散バインディングはオプションであり、必須ではない。

契約は生成されるのではなく Go SDK から手作業で導出される: 権威ある定義はイベントエンベロープ、 ファーストパーティのイベント型、そして観測ペイロード（agent→resource のアクセス観測、コストサンプル、 finding レポート）である。バスがまだ何かを形式化していない場合、リファレンスはそれを発明するのではなく そう述べる。

モジュールカタログ

モジュールカタログ は、コアエンジンの上に座る 30 のモジュールを、 9 つの能力領域にわたって列挙する。最も有用なものの 1 つは、Permitted-vs-Observed diff を持つ R/RW access map である: それはデータパスに座るのではなく、ログ、OTEL、そして（非協調的バックストップ として）eBPF から読み取り、どのエージェントがどのリソースを読み書きできるかという関係のみを保存する —— ペイロード、シークレット、PII は決して保存しない。

カタログはステータスとカバレッジについて正直である。各モジュールは独自の成熟度を持つ —— ほとんどは エンドツーエンドでライブかつ配線済み、一部は部分的またはオプトイン。受動的観測はストア型によって 階層化される —— SQL、オブジェクト、ウェアハウスのストアは clean、ドキュメントとベクトルのストアは lossy、インメモリまたは組み込みストアは協調なしには impossible —— そしてカタログはモジュールが設計段階で ある箇所をマークする。自前モデルのレジストリとファインチューニングは計画された能力であって、出荷済みの 30 モジュールの 1 つではない。

CLI

CLI リファレンス は単一の olivares バイナリとそのサブコマンドを文書化する。 control plane を運用するために実行するものは serve であり、HTTP（REST + 組み込み web UI）と gRPC のリスナーを起動する。TLS はデフォルトで有効である。他のサブコマンドはコレクター、監査台帳 （verify、checkpoint、export）、ライセンスツール、OpenAPI ドキュメントの出力をカバーする。

まずビルド、それから実行

task run や素の docker run のショートカットは存在しない。バイナリを直接ビルドして起動する —— task setup、task build、その後 ./bin/olivares serve —— か、提供される Compose ファイルで立ち上げ、 ログからワンタイムセットアップトークンを読む。CLI ページは検証済みの serve フラグとそのデフォルトを 列挙する。

設定

設定リファレンス は、デプロイを形作る環境変数とランタイムオプションを列挙する。 重要なものは、データディレクトリ（OLIVARES_DATA_DIR）、エンジン起動前に OLIVARES_SOURCES_CONFIG から 読まれる実（非デモ）ソース配線、そして認可エンジンセレクタ OLIVARES_PDP_ENGINE（cedar、opa、または none）である。

2 つの設計ルールが設定面全体に貫かれている。未設定のソースはエンジンを失敗させるのではなく正直に警告 する。 そして認可 seam は決して広げず、常に制限するのみである: RBAC は deny-by-default、access graph の閲覧は特権アクションであり、そのような読み取りはすべて監査される。