id: ADR-015 title: 統合機能カタログは正規の所有者に対する読み取り専用のプロジェクションです date: 2026-08-22 status: 提案 relates-to:
- https://github.com/zeroclaw-labs/zeroclaw/issues/9346
- https://github.com/zeroclaw-labs/zeroclaw/issues/6489
- https://github.com/zeroclaw-labs/zeroclaw/issues/8908
- https://github.com/zeroclaw-labs/zeroclaw/issues/8850
- https://github.com/zeroclaw-labs/zeroclaw/issues/8367
- docs/book/src/plugins/index.md
- crates/zeroclaw-plugins/src/config.rs
ADR-015: 統合機能カタログは正規の所有者に対する読み取り専用プロジェクションである
コンテキスト
ZeroClaw には、機能を説明する複数の表示領域があります。組み込みのチャネルとツール、インストール済みのプラグインパッケージ、レジストリで利用可能なパッケージ、設定済みのプロバイダーおよびチャネルのエイリアス、ゲートウェイの Integration エントリ、CLI プラグインコマンド、Web ダッシュボードのビュー、ZeroCode、エージェント向けのセットアップガイダンスです。これらの表示領域は現在、それぞれ異なる問いに答えており、「インストール済み」「設定済み」「有効」「アクティブ」「正常」といった重複する用語を使用しています。
#6489 で示された製品の方向性は、インテグレーション、組み込み機能、インストール可能なパッケージ、構成済みインスタンス、ランタイムでの観測結果を横断する、信頼できる単一のカタログです。この方向性は「すべてがプラグイン」と要約されることがありますが、長期的に維持されるアーキテクチャはより限定的です。つまり、単一の実装メカニズムではなく、単一のカタログです。組み込み実装とパッケージベースの実装は、無期限に共存できます。
承認済みの RFC #9346 は、欠落していた契約を定義します。カタログでは、パッケージに関する事実、機能に関する事実、実装に関する事実、構成済みインスタンスに関する事実、実行時の観測結果を分離して保持する必要があります。各事実は、別の永続化されたライフサイクルレジストリを作成するのではなく、正規の所有元から導出する必要があります。また、ルートの廃止、移行、または安定した公開 API の確約を行う前に、既存のパッケージおよび Integration プロジェクションとの互換性も維持する必要があります。
この記録は、その目標アーキテクチャを記録したものです。統合カタログ投影、互換性ブリッジ、またはランタイム観測モデルがリリース済みであると主張するものではありません。
決定
5 つのアイデンティティを分離しておく
統合カタログでは、異なる事実ごとに別々のアイデンティティを使用します：
- パッケージアーティファクト: パッケージソース、名前空間/名前、バージョン、およびアーティファクトが存在する場合は不変のコンテンツまたは受け入れリビジョンによって識別される、組み込み、インストール済み、またはレジストリで利用可能なアーティファクト。
- 機能:
channel:discord、provider:ollama、tool:web_search、メモリーバックエンド、スキル、オブザーバー、プラットフォーム統合などの、型付きの動作。 - 実装: 機能を提供する、組み込みの実装またはパッケージによって提供される実装。
- 設定済みインスタンス: 所有元サブシステムの正規構成でオペレーターが定義したエイリアス。
- ランタイム観測: ランタイム所有者がランタイム世代について報告する、一時的なアクティベーション、健全性、または障害の証拠。
これらのアイデンティティはいずれも、別のアイデンティティの代替にはなりません。パッケージは複数の機能を公開できます。1 つの機能には、組み込み、インストール済み、レジストリから利用可能な実装が存在する場合があります。構成済みのインスタンスは、アクティブなランタイムインスタンスがなくても存在できます。ランタイムの観測結果は、インストール、構成、または有効化を変更しなくても古くなることがあります。
識別子には、シークレット、生の設定値、アクセストークン、ホスト名、ユーザー名、絶対パス、変更可能な表示ラベルを含めてはなりません。パッケージが提供する機能と実行時の観測結果は、正確なアーティファクトの来歴に紐付けられるため、インストール済みバージョンとレジストリのバージョンが統合されることはなく、アップグレードによって有効化や健全性の証拠が曖昧になることもありません。
所有者を介して機能の識別情報を宣言する
機能の識別子は、機能ファミリの所有者が、型付きの組み込みインベントリ フィールドまたは受理済みの package-manifest スキーマを通じて宣言します。カタログは、アーティファクトと実装をそれらの宣言に紐付けます。呼び出し可能なツール名、広範な PluginCapability 種別、表示名、または別個のグループ化テーブルから論理的な識別子を推測してはなりません。
所有者が提供する型付き宣言を持たないファミリーは、その所有者が宣言を追加するまで、カタログのケイパビリティ・アイデンティティを持ちません。これにより、グループ化の権限はカタログ投影に移されず、ケイパビリティを理解するサブシステムに留まります。
プロジェクトの信頼できる唯一の情報源に基づく証拠であり、ライフサイクルによる書き込みではない
カタログは読み取り指向です。リクエスト時に正規の所有元からビューを具体化するか、それ自体を無効化するのに十分なソース世代情報を保持する派生キャッシュからビューを具体化します。ライフサイクルに関する書き込みを受け付けず、別の有効化、受け入れ、構成、アクティベーション、準備状態、または正常性のテーブルも永続化しません。
各状態軸には 1 人の所有者がいます:
| 事実 | 所有者 |
|---|---|
| レジストリの可用性 | 設定済みのレジストリまたはインデックスクライアント |
| 組み込みの可用性 | コンパイル済みの組み込みインベントリ |
| インストール済みパッケージとアドミッション状態 | パッケージのインストールとアドミッションインベントリ |
| Capability の識別情報、エクスポート、実装元 | 型付きインベントリまたは承認済みマニフェスト宣言によるケイパビリティファミリーの所有者 |
| 設定済みのインスタンス | 所有するサブシステムの正規の Config セクション |
| 有効状態 | 正規構成と、管理元サブシステムの有効化ポリシー |
| アクティブ状態 | そのインスタンスを生成または登録したランタイム レジストリ |
| 健全性または失敗 | 機能固有のランタイム所有者またはプローブ |
| エージェント向けの準備状況 | #8367 のようなオンデマンドプロジェクションであり、カタログの識別子と証拠を使用しつつ、別のライフサイクル所有者にはならないもの |
証拠が欠落している場合は unknown であり、false ではありません。状態の判定結果では、既知の true、既知の false、unknown、not applicable を区別します。ヘルスは所有者が定義する観測結果であり、healthy と failed を同時に示し得る独立したブール値ではありません。ランタイムの観測結果には、観測時刻、ランタイム世代、選択された実装、パッケージに基づく場合のアーティファクトの来歴、および鮮度ルールが含まれます。古くなると、更新されるまでヘルスは unknown に戻ります。
プロジェクションは、独立したオーナー間にまたがるアトミックなトランザクションではありません。公開ペイロードには generated_at と、必要に応じて関与したオーナーの世代情報または出所情報が含まれるため、利用者はパッケージ、設定、ランタイムに関する情報が同時に観測されたと推測できません。
リゾルバーの権限をファミリー固有に保つ
ネイティブ/プラグインの衝突と優先順位は、グローバルカタログのポリシーではありません。RFC #8850 は、チャネルとツールに対するネイティブ/プラグインの衝突動作を定めます。カタログはその結果を channel:* と tool:* に投影します。
所有者定義のリゾルバーがないプロバイダー、メモリーバックエンド、オブザーバー、スキル、プラットフォーム統合について、カタログは一致するすべての実装を、競合が未解決または不明であることを示す明示的な情報とともに報告し、暗黙の順序付けは適用しません。後から所有者定義のリゾルバーをそのファミリーのソースにすることはできますが、カタログがリゾルバーに変わるわけではありません。
可視性と権限を分離する
カタログの可視性によって、ユーザー、UI、API、またはエージェントに表示される内容を絞り込めます。呼び出し権限を付与することはできません。
Agent ツールレジストリ、リスクプロファイル、実行ごとの絞り込み、宛先ポリシー、権限付与、承認、主体スコープの認可は、引き続きカタログの対象外です。#8367 のような利用側は、カタログの根拠と主体固有のポリシーから、その時点での指針を導出できますが、その指針は投影です。それによってアクションが認可されたり、ライフサイクル状態が書き込まれたり、設定済みインスタンスの事実になったりすることはありません。
公開プロジェクションでは、認証情報、シークレット参照、生の設定値、レジストリ認証、ホスト ID、制限のないファイルシステムパス、生のランタイムエラー、非公開のマニフェストフィールドは除外されます。レジストリとマニフェストのテキストは信頼できないメタデータであり、命令ではなくデータとしてレンダリングする必要があります。
収束前に互換性を維持する
GET /api/plugins は、パッケージ関連の作業が安定するまで、パッケージ中心のプロジェクションであり続けます。/api/integrations は、別途の互換性判断によって廃止、リダイレクト、または安定版 API の破壊的変更が承認されるまで、共有カタログに対する互換性プロジェクションであり続けます。
CLI、web、ZeroCode、ゲートウェイ、およびエージェント向けの準備状況は、同じコントラクトからバージョン管理されたプロジェクションを利用します。追加フィールドは、互換性を維持したまま導入できます。識別子の変更、ルートの廃止、構成の移行、安定したパブリック API のコミットメント、およびマーケットプレイスの信頼ポリシーには、ロールバック計画と互換性計画を含む個別のレビューが必要です。
パッケージの識別情報は、別の無関係な座標系を新たに作るのではなく、既存のレジストリの方針に合わせて対応付ける必要があります。2つ目の利用者がそれらに依存する前に、実装作業では、パッケージの座標を既存のMCP形式のパッケージ識別情報と、別途提案されているOCIレジストリの方針に整合させる必要があります。
証拠の語彙は、確立された分散状態の慣行に意図的に従っています。つまり、既知・未知・観測済みの事実に対する Kubernetes 形式の条件セマンティクスと、有効化の意図とアクティブな実行時状態を区別する systemd の考え方です。ZeroClaw はこれらのシステムを丸ごと取り込む必要はありませんが、カタログではその分離を維持する必要があります。
受け入れゲート
この ADR は、以下の条件をすべて満たすまで提案中のままです：
- パッケージ成果物、機能、実装、構成済みインスタンス、実行時の観測結果、および状態の証拠は、チャネル、プロバイダー、ツール、プラットフォーム、および複数機能パッケージの代表的な例とともに文書化されます;
- すべての論理的な機能の識別情報は所有者が提供する型付き宣言に由来し、カタログは呼び出し可能な名前や大まかな機能種別からそれを推測できません;
- 投影状態の各フィールドは正となる情報源を示し、既知、未知、非該当のセマンティクスを正しく使用している;
- パッケージの可用性、インストール、受け入れ、構成、有効化、アクティベーション、健全性、およびエージェント向けの準備状態は、カタログを通じて引き続きそれぞれ独立して表現でき、書き込みはできない。
- チャネルとツールの組み込み/プラグインの衝突動作は #8850 と同じですが、その他の機能ファミリは、その所有者がリゾルバーを定義しない限り、明示的に未解決のままです;
- パッケージが提供する機能とランタイムの観測結果は、インストール済みバージョンと利用可能なバージョンの違い、アップグレード、再読み込み、ランタイム世代をまたいでも、正確なアーティファクトの出所に紐付いたままになります;
- 公開プロジェクションは生成または来歴メタデータを公開するものであり、独立した所有者間でのアトミックな整合性を意味しません;
- カタログの可視性によって、呼び出し権限を付与したり、エージェント、ターン、宛先、付与、承認、またはポリシーのチェックをバイパスしたりすることはできません;
/api/pluginsと/api/integrationsには、ルートの統合、廃止、または安定版 API の確約に先立つ追加的な互換性ブリッジがあり、そして- 複数のパッケージコンシューマーが依存する前に、パッケージ座標の識別情報を既存の MCP および OCI レジストリの方針と整合させる。
結果
肯定的な結果:
- コントリビューターは、ある事実がパッケージの利用可能性、インストール、設定、有効化、アクティベーション、健全性、または準備状況のいずれに関するものかを判断できます。
- CLI、ゲートウェイ、Web、ZeroCode、およびエージェント向けのガイダンスでは、ライフサイクル状態をそのままコピーせずに、統一された語彙を使用できます。
- 組み込み実装とプラグイン実装は、すべての組み込み実装が WASM に移行済みであるかのように装わずに共存できます。
- ランタイムの健全性とアクティベーションに関する主張は、設定やパッケージの存在から推測されるのではなく、証拠に基づくものになります。
- 公開ルートや用語を変更する前に、互換性対応を追加する形で進めることができます。
否定的な結果:
- カタログコントラクトは、単一の
status列挙型よりも複雑です。 - Capability ファミリの所有者は、各ケイパビリティが問題なく参加できるように、型付き宣言を追加する必要があります。
- ランタイム所有者は、カタログがアクティブ状態または健全性の証拠を報告できるようになる前に、世代スコープの観測結果を公開する必要があります。
- API の統合が遅いのは、
/api/pluginsと/api/integrationsが互換性スライスを介して連携する必要があるためです。 - 別のレジストリ識別システムが必要になるのを避けるため、パッケージ座標の照合は早い段階で行う必要があります。