公開サーフェス
すべての Aggrega カタログ YAML は、カタログ配布のためにエンティティを記述する統一されたメタデータフィールド群を持ちます。誰がメンテナンスしているか、どのライセンスで提供されるか、ソースがどこにあるか、発見のためにどのキーワードで表示されるか、といった情報です。これらのフィールドが合わさって 公開サーフェス を構成します。これはカタログ公開者とツールの利用者が依拠するメタデータ語彙であり、labels-and-annotations.md で説明しているコンテンツ側の metadata.labels / metadata.annotations の仕組みとは別のものです。
このページでは、公開サーフェスのフィールド、コーパス全体における description フィールドの一覧(エンベロープ、インスタンス、フィールドレベルの各 description)、maintainer フィールドの想定用途と確認済みの利用者、そしてエンティティごとの必須フィールドの非対称性(各エンティティが現在どのフィールドを必須とし、どこで非対称性が意図的なものか)を説明します。
公開サーフェスのフィールド
以下のフィールドは、Domain 2(Component、Feature)および Domain 3(Recipe、FeatureRecipe、Plugin)のすべてのエンティティに現れ、再利用可能なモジュールとしての Aggregate にも現れます。Manifest と Release にも現れますが、意味は限定されます(カタログ公開ではなくワークスペースの帰属)。
| フィールド | 種類 | 目的 | 利用者 |
|---|---|---|---|
description | string | エンティティの人間が読める要約 | エディタのホバーカード(aggrega serve)、アシスタントが呼び出す describe ツール(aggrega mcp)、公開されたアーティファクト上の検索可能なアノテーション(aggrega push)、aggrega inspect |
maintainers | オブジェクトの配列 | エンティティの所有者(name、email、url) | IR 内のノードごとの catalog_metadata(Component ノード上) |
license | string | 法令遵守(通常は SPDX 識別子) | IR 内のノードごとの catalog_metadata(Component ノード上) |
repository | string(URL) | ソースが置かれている Git リポジトリ | IR 内のノードごとの catalog_metadata(Component ノード上)。ほかに読むものはありません |
home | string(URL) | ドキュメント / wiki の URL | IR 内のノードごとの catalog_metadata(Component ノード上)。ほかに読むものはありません |
keywords | 文字列の配列 | 検索用タグ | IR 内のノードごとの catalog_metadata(Component ノード上)。検索インデックスはこれを利用しません |
6 つのフィールドはすべて、それを持つどのエンティティでも省略可能です。一式すべてを省略したカタログ作成者も有効な YAML を生成します。公開サーフェスはカタログ配布を意図したエンティティのためのものであり、内部利用のエンティティは何の影響もなく省略できます。
利用者の列は現在出荷されているものについて網羅的です。そこから導かれる 2 つの帰結は、何を記述する価値があるかを変えるため、はっきり述べておく価値があります。
descriptionは、複数の読み手を持つ唯一のフィールドです。aggrega serveは、Aggregate、Component、Feature、Recipe、FeatureRecipe、Manifest、および 4 つのライブラリ種別(SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary)のホバーカードにこれを表示します。Plugin と Release には表示しません。aggrega mcpが公開するdescribeツールは、どの種別のエンティティについてもこれを返します。aggrega pushは、公開されたアーティファクトに検索可能なアノテーションとしてこれを付与します。aggrega inspectは、すべての種別についてエンティティのヘッダーの下にこれを出力し、ほかの公開サーフェスのフィールドは出力しません。repository、home、keywordsは検証されて引き継がれますが、IR より先でこれらを読むものはありません。 一覧表示のサーフェス、カタログサイト、検索インデックスのいずれもこれらを利用しません。これらを記述すると、エンティティとともに移動し、IR 出力とガバナンスポリシーから読み取れる来歴が記録されますが、エンティティがどこかで見つけやすくなるわけではありません。
非推奨は公開サーフェスのフィールドではありません。 エンティティは、公開後にレジストリでそのエンティティに対するマーカーを記録することで非推奨になります。これは重大度(warning、error、retracted)、理由、代替を持つ署名付きマーカーで、pull 時に検証されます。ロックファイルを読むすべてのサーフェスがそれを報告し、build.halt_on_deprecated_severity はビルドも停止するかどうかだけを決めます。マーカーがエンティティ自身の YAML に記述されることはなく、その理由は構造的なものです。公開されたアーティファクトは不変であるため、公開時にそこへ固定されたフラグでは、後で下された決定を表現できません。aggrega inspect がカタログエンティティについて出力する非推奨の通知は、名前で解決するすべての種別について、マーカーから得られます。
IR での利用 — ノードごとの catalog_metadata
コンパイラは、各 Component の公開サーフェスのフィールドを、そのノードの catalog_metadata ブロックに引き継ぎます。これは実行が返す IR グラフ(aggrega inspect <release> --ir-graph)で確認できます。このブロックには maintainers、license、repository、home、keywords が入ります。これが IR の引き継ぐ 5 つのフィールドで、description は含まれません。IR グラフの契約に基づいて作られたツールは、カタログの YAML を読み直すのではなく、ここからメタデータを読み取ります。
Component ノードのみ。 このブロックは、ノードのコンポーネント型をカタログ内で Component として検索することで設定されます。そのため、Feature、Recipe、FeatureRecipe、Plugin の公開サーフェスが IR に届くことはありません。これらのエンティティはフィールドを持ち、フィールドは検証されますが、そこから IR ノードは生じません。
ソースの Component の公開サーフェスのフィールドがすべて空またはゼロの場合、catalog_metadata は IR JSON から完全に除かれます。ブロックは空の値で出力されるのではなく省略されます。したがって同じ入力からは同じ簡潔な出力が得られ、実行間で IR の差分が安定します。
ガバナンスポリシーはこのブロックを読み取れます。plugins.governance の下に ir-verdict ロールで接続されたプラグインは、各 Component ノードの catalog_metadata を含む IR グラフ全体をノード単位で受け取ります。そのため、ポリシーはノードの license、repository、home、keywords、maintainers に基づいてビルドを受け入れたり拒否したりできます。この到達範囲はガバナンスのソケットに固有のものです。プロバイダのレンダリングプラグインが受け取るのは catalog_metadata を含まない範囲限定のノードごとの射影であるため、レンダリングプラグインはこれらのフィールドを読み取れません。
3 種類の description
description フィールドはエンベロープに一様に現れますが、コーパスにはスキーマ宣言の内部(フィールドごとの説明)やピラー本体の内部(インスタンスごとの説明)にも説明形式の文字列があります。3 つの異なる種類の説明が共存しており、以下の表でそれらを区別します。
| 種類 | 記述場所 | 記述者 | 目的 |
|---|---|---|---|
| エンベロープの説明 | すべてのエンティティの metadata.description | カタログの公開者 | エンティティ全体の概要。エディタのホバーカードに表示され、公開されたアーティファクトに付与されます |
| インスタンスの説明 | インスタンスごとの宣言の隣にある description フィールド(例: featuresSchema.<slot>.description、usesSchema.<socket>.description) | スキーマの作成者 | スロットごと・ソケットごと・ポートごとの説明。宣言を読む、利用側エンティティの作成者向けです |
| フィールドの説明 | schema: / featuresSchema: / usesSchema: の内容(コンパクト形式または完全な JSON Schema YAML)内にある JSON Schema 2020-12 の description: アノテーション | スキーマの作成者 | スキーマとともに伝わるフィールドごとのドキュメント |
3 つの種類は「description」という語を共有していますが、構造的に異なるレベルに存在します。エンベロープの説明はエンティティ全体に、インスタンスの説明はスキーマスロット内の宣言に、フィールドの説明は型付きスキーマ内の特定の値に適用されます。Component を書く作成者は次のようにします。
- Component エンティティ自体に対して
metadata.descriptionを 1 回設定します。 - Component が宣言する認証情報スロットごとに
featuresSchema.admin_password.descriptionを 1 回設定します。 schema:ブロック内にフィールドごとのdescription:アノテーションを、コンパクト形式(port: { type: integer, description: "..." })または完全な JSON Schema YAML で設定し、Component のスキーマを読む人のために各フィールドを文書化します。
3 つの種類はカスケードせず、衝突もせず、それぞれ異なる表示先に届きます(あるいはどこにも届きません)。
- エンベロープの説明 — 上記の Consumer 列のとおり、エディタのホバーカード、公開されたアーティファクトの検索可能なアノテーション、および
aggrega inspectです。 - フィールドの説明 — Component または Feature のホバーカードが表示するスキーマ抜粋にそのまま現れます。抜粋は
spec.schemaのみを対象とし、冒頭の数行に切り詰められるため、ブロックのより深い位置にある説明や、featuresSchema:またはusesSchema:内の説明はそこに現れません。 - インスタンスの説明 — 宣言され、エンティティとともに伝わりますが、出荷されているどの表示先もそれ単独では表示しません。
aggrega inspectは Component のソケットとフィーチャースロットを、その説明なしで一覧表示します。
maintainer フィールドの意図
maintainers フィールドはオブジェクトの配列を保持し、各オブジェクトは name、email、url を持ちます。意図と確認済みの利用先は次のとおりです。
意図(情報提供 + IR の来歴)。 このフィールドはカタログ公開のための情報提供用です。アーキテクチャ上の意図は「このカタログエンティティの責任者は誰か」であり、エンティティとともに伝わる所有権のシグナルです。これを連絡先リストとして提示するサーフェスはなく、何かと照合する組み込みのチェックもありません。
確認済みの利用先(ノードごとの catalog_metadata)。 コンパイラは各 Component の metadata.maintainers を、IR 内のそのノードの catalog_metadata.maintainers に引き継ぎます。ソースの Component が maintainer を宣言している場合、これは aggrega inspect <release> --ir-graph が返すグラフで確認できます。これがこのフィールドの唯一の読み手です。ir-verdict ロールで plugins.governance の下に接続されたガバナンスポリシーはそこでこのフィールドを参照できるため、所有権のルール(すべてのエンティティが少なくとも 1 人の maintainer を挙げる、maintainer のドメインが承認済みの集合に一致する、など)をカタログの YAML ではなく IR に対して表現できます。そのようなルールは同梱されていません。ソケットはそうしたルールを置く場所です。
コンパイラは、JSON Schema の構造上の形(name は必須、email と url は任意でいずれも文字列)を超えて maintainer の内容を強制したり検証したりしません。挙げられた maintainer が実際にエンティティを所有しているか、メールアドレスに到達できるか、リポジトリのコミットがそのいずれかによって署名されているか、といった点はカタログガバナンスの関心事であり、同梱のチェックはそのいずれも評価しません。これらはコンパイラではなく、運用者が接続するガバナンスポリシーの役割です。
必須フィールドの非対称性
Aggrega のエンティティ種別は、JSON Schema で定める必須フィールドの組み合わせがわずかに異なります。ほとんどの非対称性は意図的なもので、エンティティの役割を反映しています。
エンティティごとの必須フィールドは次のとおりです(すべてのエンティティが一律に必須とする apiVersion / kind / metadata.name / metadata.version は除きます)。
| エンティティ | 追加の必須フィールド | 根拠 |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | このラベルの要件はセレクターのマッチングを支えるものです。usesSchema の x-aggrega-selector: アノテーションは、このラベルによって対象の Components を絞り込みます。ラベルがない場合、その Component は読み込み時に拒否されます |
| Feature | — | 予約ラベルの要件はありません。Features は名前と発行者で識別されます |
| Recipe | spec.capability, spec.implements | capability が provider のディスパッチを制御し、implements が Component へのバインディングを制御します |
| FeatureRecipe | spec.capability, spec.implements | Recipe と同じ |
| Plugin | metadata.pluginType, spec.abiVersion | プラグインが実装するソケットの型(アドレッシングブロックの一部で、導出される plugin/<pluginType>/<name> 座標の <pluginType> セグメントを与えます)と、対象とする ABI バージョン。.wasm の場所は記述されるのではなく、その ID から導出されます。provider レンダリング用のプラグイン(pluginType: provider)は、さらに spec.provider の下に変換契約を持ちます |
| Aggregate | — | components、subsystems、aggregates のいずれも宣言しない Aggregate は、読み込まれてビルドされ、何もレンダリングしません |
| Manifest | spec.mappings | マッピング階層が Manifest の唯一の目的です |
| Release | spec.aggregate、spec.manifest(extends を宣言する Release は aggregate を書かず、manifest を省略できます)、metadata.environment | 最初の 2 つはビルドを特定の Aggregate と Manifest に結び付けます。environment はレンダリングされた出力に aggrega.ai/environment ラベルとして付与されます |
Component のラベル要件は不可欠なものです
component.aggrega.ai/type ラベルは、Aggrega がいずれかのエンティティに必須とする唯一のラベルです。この要件が存在するのは、標準ライブラリの usesSchema の仕組みが、"component.aggrega.ai/type=database" のようなセレクター文字列を持つ x-aggrega-selector: アノテーションによって対象の候補を絞り込むためです。セレクターは対象のラベルを参照し、その型がソケットの受け入れる型に一致するかを判定します。Component スキーマがこれを強制します。このラベルを省略した Component は読み込み時に拒否され(E0215)、欠けているキーが示されます。
したがって、この要件は公開サーフェスの関心事(このラベルはカタログでの発見のためのものではありません)ではなく、トポロジーの関心事です。カタログでの配布を想定しない内部用の Components も含め、すべての Component がこのラベルを持ちます。
Release の metadata.environment は必須です
Release スキーマは metadata.environment を必須とします。これは文字列で、ビルドはレンダリングされた出力に aggrega.ai/environment ラベルとして付与します。
その他の非対称性
残りの非対称性(Recipe と Component の必須フィールドの違い、Manifest の mappings の要件)は各エンティティの役割を反映したものです。すべてのエンティティ種別にわたって統一された必須フィールドの契約を求める作成者は、それを見つけることはできません。これらの非対称性は、役割主導の設計に従った意図的なものです。
相互参照
labels-and-annotations.md— 公開サーフェスを補完する、コンテンツ側のメタデータの仕組み。entities/component.md— Component のmetadata.labels.component.aggrega.ai/typeの要件と、schema/usesSchema/featuresSchemaの宣言。entities/release.md— Release のmetadata.environmentフィールドと、その必須要件。10-status.md— メタデータエンベロープのステータス。architecture/02-ecosystem-philosophy.md— 厳格な API 分割(Strict API Partitioning)と Enterprise Metadata Suite の設計上の位置付け。architecture/13-catalog-and-registry.md§「Lockfile pinning and artifact immutability」+ §「Catalog entity name-shape enforcement」 — 不変性ルールが公開時に拒否するもの、およびエンティティ種別ごとの名前の形式がどこでチェックされるか。publishing-discipline プラグインは、作成者がaggrega lintを実行したときにそれらを助言として報告し、ビルドでも公開でもチェックされません。architecture/11-governance-and-compliance.md§「Inheritance and publishing discipline」 — どのガバナンスルールが publishing-discipline プラグインに属し、どのルールが代わりに拡張する Component の継承によって構造的に解決されるか。