コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

Manifest

Manifest エンティティの概念上の役割(ドメイン 4 — 抽象インターフェースを具体的な Recipes にバインドするマッピングテーブル)は architecture/04-entity-taxonomy.md で説明しています。このページでは Manifest の記述面を扱います。Release との関係、フラットな URI マッピングの形式、extends による合成、URI の短縮表記の規則、アノテーション駆動の Feature バインディング、そしてプラットフォームが予約している aggrega.ai/ プレフィックスについて説明します。

Manifest と Release:関心の分離

Manifest と Release は、重複しない責務を担います。

  • Manifest は、カタログの型ごとにどの Recipe がそれを実現するかを指定し、その Recipe の spec.capability を通じて、それをレンダリングする provider(例:Helm、Helm-chart、Compose)を指定します。これはマッピングテーブルであり、各抽象インターフェースをどの具体的な Recipe が実装するかを記録する、プロジェクトごとに Git にコミットされる記録です。ビルドがそれらの Recipes に求めるバージョンとダイジェストは、各 Release のロックファイルで別途固定されます。
  • Release は、出力先(例:GitOps アーティファクト生成のための物理的な出力フォルダ)を指定します。これはデプロイメントルーターであり、コンパイルされたアーティファクトがどこに配置されるかを記述する、環境ごとの記述です。

Release のスキーマは、どのネストレベルにも provider フィールドを持ちません。provider のディスパッチは Manifest だけが担います。

コンパイルの流れ。 ユーザーが aggrega build --release release.yaml を実行すると、コンパイラは両方のソースを結合して物理的なアーティファクトを解決します。

  1. 出力先の読み取り。 コンパイラは Release の境界をスキャンします。たとえば、境界 ovh-cluster-3 にはコンポーネント user-db(型:core/postgres:1.0.0)が含まれます。
  2. Manifest のスキャン。 Release が manifest: フィールドで指す Manifest を開きます。
  3. 2 段階のルックアップ。 まず name 階層で "user-db" を確認します。見つからない場合は、type 階層で "core/postgres:1.0.0"(バージョン付き)、次に "core/postgres"(バージョンなし)を確認します。
  4. Recipe の解決。 一致したエントリの値は Recipe URI です。その URI が指す Recipe は、どの provider がそれをレンダリングするかを spec.capability で宣言しています。
  5. 出力の生成。 これでコンパイラは、出力先フォルダ(dist/boundaries/ovh-cluster-3/)、provider(Wasm による Helm レンダリング)、およびアーティファクト(Recipe のソースコード)を把握します。事前(ahead-of-time)の GitOps の境界が端から端まで守られます。

フラットな URI マッピング

Manifest の mappings: ブロックは、コンポーネントタイプ URI から Recipe URI へ(および フィーチャータイプ URI から FeatureRecipe URI へ)のフラットなマップです。マッピングは Manifest レベルではケイパビリティに依存しません。ケイパビリティの決定は、Manifest の構造的な形からではなく、レンダリング時に解決された各 Recipe の spec.capability フィールドから導かれます。このブロックはマッピングを 2 つのトップレベルキーの下に整理します。

  • components.type は、コンポーネントタイプ URI を Recipe URI にマッピングします。宣言されたタイプのすべてのコンポーネントインスタンスは、指定された Recipe に解決されます。マッピングはコンポーネントタイプごとに 1 対 1 です。インスタンスの正確なタイプを指定していないキーでも、その正確なタイプを指定するキーがなく、同じベースに対して他のキーが書かれていない場合は、タイプのベースによってそのインスタンスに到達します。そのため、バージョンなしで書かれたキー(core/postgres)や別のバージョンを指定するキー(core/postgres:1.0.0)が core/postgres:2.0.0 のインスタンスに到達することがあります。ただし、そのキーが指定する Recipe は、そうした各インスタンス自身のバージョンを実装していなければなりません。このようにして到達し、implements: core/postgres:1.0.0 を宣言する Recipe にマッピングされた core/postgres:2.0.0 のインスタンスは、ビルドを停止させます。そのようなインスタンスは、そのバージョンを指定するキー(core/postgres:2.0.0)で、それを実装する Recipe にマッピングしてください。
  • features.type は、フィーチャータイプ URI を FeatureRecipe URI にマッピングします。宣言されたタイプのすべての Feature アタッチメントは、指定された FeatureRecipe に解決されます。認証情報の Features(feature.aggrega.ai/kind: secret のラベルが付いたもの)は、運用上の Features と同じ features.type マップに置かれます。これが統一された Feature エンティティモデルです。

各ブロックは type と並んで name ティアも受け付け、特定のインスタンス名を Recipe(または FeatureRecipe)URI にマッピングします。name ティアは type ティアより優先されます。components.name で名前を指定されたインスタンスはその Recipe に解決され、同じタイプの他のすべてのインスタンスは components.type を通じて解決されます。これによりインスタンスごとのオーバーライドを表現できます。1 つのコンポーネントタイプの 2 つのインスタンスを、コンポーネントタイプをフォークしたり Manifest を複製したりせずに、2 つの異なる Recipes でデプロイできます(たとえば、ほとんどのデータベースインスタンスは一括マッピングされた Recipe を使い、1 つのインスタンスだけを別の物理実装に固定する場合)。オーバーライドは一様に適用されます。名前を指定されたインスタンスは、オーバーライド先の Recipe を通じてレンダリングされ、そのソースもその Recipe から固定されます。features.name は Feature アタッチメントに対応する対称的なティアで、アタッチメント自身の名前、つまりコンポーネントの features: でそれが書かれているキーをキーとし、アタッチ先のコンポーネントの名前をキーとすることはありません。インスタンスごとの Recipe オーバーライドの例では、最小限の 2 インスタンスのケースを最初から最後まで説明しています。

接続が持つアタッチメントは、消費側コンポーネント上でそれが取る名前、すなわち <alias>.<slot>(接続が記述されるエイリアス、ドット、アタッチメントが埋めるスロット)をキーとします(Aggregate の接続エントリを参照)。そのため、ある接続の認証情報を、同じタイプの他のすべてのアタッチメントとは異なる方法で実現できます。

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

このエントリは、次の段落で説明するとおり、他の name ティアのエントリと同様に固定され検証されます。アタッチメントが指定する Feature も、コンポーネント自体に記述されたアタッチメントの Feature とまったく同じように、その作成者が記述した接続エントリの下で固定され検証されます。ロックファイルを参照してください。

name キーは、ビルドが保持するものを指定しなければなりません。 このティアは正確な名前で照合されるため、ビルド内のコンポーネントインスタンスではない components.name キーや、ビルド内のアタッチメントではない features.name キー(多くの場合、アタッチメント自身の名前を書くべき場所に書かれた、アタッチメントが置かれているコンポーネントの名前)は何からも参照されず、それが対象としていたインスタンスは黙って type ティアを通じて解決されてしまいます。そこでビルドは、何かがレンダリングされる前に、そのようなキーで停止し、Manifest、キー、ビルドが実際に保持するその種類の名前、そしておそらく意図していた名前を示します。A Manifest name mapping names nothing in the build(Manifest のマッピングがビルド内の何も指定していない) を参照してください。

名前でバインドされた実現は、タイプでバインドされたものと同様に固定され検証されます。 aggrega pull は、いずれかのティアがバインドするすべての Recipe と FeatureRecipe をカタログディレクトリ、キャッシュ、またはレジストリから取得し、それぞれを解決済みのバージョンとコンテンツダイジェストとともに、それをバインドするマッピングエントリの下で Release のロックファイルに記録します。name ティアのエントリでは manifest.spec.mappings.components.name.<instance>、type ティアのエントリでは manifest.spec.mappings.components.type.<type> の隣です。aggrega build はそれらすべてをその固定に従わせます。Manifest がバインドする実現の行を記録していないロックファイルは、古いものとしてビルドを停止し、その実現とそれをバインドするエントリを示します。pull 以降にコンテンツが変更された実現も同様にビルドを停止し、両方のダイジェストを示します。いずれの場合も、aggrega pull --release <release> が現在の状態のまま実現を記録します。type エントリと同様に、name エントリは Release がその名前のインスタンスを宣言しているかどうかにかかわらず固定されるため、どのカタログやレジストリにも存在しない Recipe を指定する name エントリは pull を停止します。ビルドが保持するどのインスタンスも指定しない name エントリも固定され、前の段落で説明したとおりビルドを停止させます。

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

レンダリング時のケイパビリティ決定。 Manifest エントリは、コンポーネントタイプを Recipe URI にバインドします。Recipe URI は最大 2 つのセグメント(省略可能な先頭のケイパビリティ、続いて Recipe 名)と、省略可能な :version を持ちます。リゾルバーは最初の / でのみ分割するため、3 番目のセグメントを持つ参照はどの Recipe も指さず、解決を停止します。レンダリング時、リゾルバーはロックファイルとカタログに対する直接 URI ルックアップで Recipe を読み込み、各 Recipe の spec.capability フィールドが(パス、ケイパビリティ)ごとのディスパッチのグループ化を決定します。より広いカタログがいくつの Providers をサポートしていても、Manifest の構造的な形はフラットなままです。

直接 URI ルックアップ

Manifest のマッピング値は Recipe URI です。コンパイラは URI をロックファイルとカタログに対して直接解決し、一致する Recipe を返します。コンパイラは、コンポーネントタイプを「実装する」Recipe を見つけるために spec.implements 宣言を反復しません。各 Manifest エントリは、開発者が作成したコンポーネントタイプを特定の Recipe URI にバインドします。その選択は Manifest の内容において明示的で曖昧さがありません。

spec.implements はマッピングテーブルに対する整合性チェックです。 解決された Recipe の spec.implements の値は、そのマッピングエントリの Manifest のコンポーネントタイプキーと一致しなければなりません。あるいは、そのキーが extends するベース(チェーンのどの深さでもよい)と一致しなければなりません。ベースに対して書かれた Recipe は、それを拡張するすべてのものを実装するためです。どちらにも一致しない値は OPS_ERROR を生成し、Manifest エントリ、解決された Recipe、および競合する spec.implements の値を示す明確な診断を出します。このチェックは Manifest のマッピングエントリごとに 1 回、合成された Manifest に対して、いずれかの Recipe が解決される前に実行されます。静的かつ決定的で、マッピングされたタイプ自身の extends チェーン以外は何も走査しません。components.type キーが、そのキーの指定していないバージョンのコンポーネントインスタンスに到達する場合、そのインスタンスについて同じ方法でもう一度判定されます。このとき、キーの位置には、ビルドがそのインスタンスをコンパイルするバージョンでのインスタンス自身のタイプが置かれます。詳しくは フラット URI マッピング を参照してください。ベースの Recipe が特殊化に対して何を省き、何を省かないかについては、../vocabulary/inheritance-and-interface.md を参照してください。

Release の依存関係を読み取るすべてのコマンドがこのチェックを実行し、検出結果が何を意味するかは各コマンドが独自に判断します。aggrega build と aggrega pull は、どちらもその後に使用するものを生成するため停止します。一方、aggrega validate と aggrega lint は他の検出結果とともに報告して非ゼロで終了し、エディターは他の診断と並ぶ 1 つの診断として公開します。インスタンスに対する判定については aggrega lint が例外です。このコマンドはマッピングエントリを判定し、それらが到達するインスタンスは判定しないため、これを報告しません。一方、aggrega build、aggrega pull、aggrega validate --release は報告します。診断とその修正方法については、../errors/fatal-halts.md を参照してください。

整合性チェックは、extends チェーンを読み取る唯一のマッピング面です。Recipe の選択はマッピングキーに対して厳密なままです。マッピングされたベースを拡張するコンポーネントタイプにも、ここに独自のエントリが必要であり、継承によってエントリを得ることはありません。

spec.implements は候補の提示にも使われます。 タイプに Manifest マッピングがないインスタンスは OPS_ERROR でビルドを停止し、その spec.implements がそのタイプを実装できる Recipe を固定候補として一覧表示します。マッピング値に対するエディターの補完も、同じ一致する Recipe を最初に順位付けします。どちらの面も要求されたタイプ自体に対して spec.implements を読み取るため、そのタイプのベースの 1 つを実装する Recipe は、マッピングとしては整合すると判断される場合でも候補として提示されません。このように spec.implements は、Recipe が何を実装できるかを宣言し、整合性チェック、マッピングなしの診断、補完において人間の選択に情報を与えますが、ビルドを解決することは決してありません。Manifest マッピングはユーザーの明示的なデプロイの選択であり、再現性のためにロックファイルに固定されます。カタログがユーザーに代わってデプロイを選択することはありません。

URI のバージョンセグメントの 3 つの形式

Manifest 内の Recipe URI は、次の 3 つの形式のいずれかでバージョンを指定できます。

  • 完全一致 — helm/postgres:1.2.0。ロックファイルはこのバージョンを正確に固定する必要があります。最初のロックファイル解決時に、リゾルバはこのバージョンを固定します。解決時にカタログまたはレジストリにこのバージョンが含まれていない場合、ワークスペースの読み込みはエラーで停止します。
  • 範囲 — helm/postgres:^1.2.0。標準の MVS ルールに従う Semver の範囲です。最初のロックファイル解決時に、リゾルバは範囲を満たす利用可能な最も高いバージョンを固定します。
  • バージョンなし — helm/postgres。:version サフィックスはありません。最初のロックファイル解決時に、リゾルバは利用可能な最新バージョンを固定します。

以降のビルドでは、ユーザーが記述した形式にかかわらず、ロックファイルで固定されたバージョンを使用します。より新しいバージョンへ再解決するには、ユーザーによる明示的な操作が必要です。aggrega pull --upgrade --release <release> <uri> は他のすべての固定を保持したまま単一の依存関係を再解決し、aggrega pull --upgrade --release <release> はすべてを再解決します。ロックファイルはビルドにおける信頼できる情報源であり、ユーザーが記述した形式は、作成時にユーザーがバージョン制約を表現する手段です。

ケイパビリティで修飾された参照

カタログ内の Recipe の識別はケイパビリティ単位です。2 つの recipe は、異なる spec.capability 値を宣言しつつ、同じ metadata.name とバージョンを共有できます。レジストリ上の識別子は recipe/{capability}/{name}:{version} で、recipe の kind、spec.capability(それが持つバージョン固定は除く)、名前から導出されます。標準ライブラリのカタログツリーは、慣例により recipe/{capability}/{name}/ でその座標を反映します。Manifest のマッピング値は、次のいずれかの精度で recipe を指定します。

  • 修飾なし — mariadb:1.0.0。カタログ内でその名前を持つ recipe が正確に 1 つだけの場合に解決されます。実際に主に使われる形式です。
  • ケイパビリティ修飾 — compose/mariadb:1.0.0。最初の / より前のセグメントが recipe の spec.capability を、そのバージョン固定なしで指定します。参照にバージョン固定を書くと拒否されます(E0095)。同じ名前の recipe が複数提供されている場合に必要です。2 つの recipe に一致する修飾なしの参照は曖昧であり、黙って一方を選ぶのではなく、解決時に明示的に停止します。

Recipe URI にはこれ以上の位置はありません。リゾルバは最初の / でのみ分割するため、compose/mariadb はケイパビリティ compose と recipe mariadb を指定し、3 セグメントの参照はどちらの精度でも recipe に一致しません。

上記のバージョンセグメントの形式は、両方の形に適用されます。

マッピングにおけるレジストリ公開エンティティ

ローカルカタログではなくレジストリから利用するエンティティも、ローカルのものとまったく同じ識別子で参照します。参照にはレジストリのホストもエンティティ kind のセグメントも含まれません。リゾルバが両方を補います。ホストはワークスペースで設定されたデフォルトのレジストリから、kind セグメントはスキーマ内で参照が置かれている位置から、後述の Context-Aware Shorthand URIs の規則に従って導出されます。ローカルのカタログディレクトリにもキャッシュにもコピーがない場合、aggrega pull(または --auto-pull を付けて実行したビルド)が導出した場所からエンティティを取得してキャッシュし、解決したバージョンとコンテンツダイジェストをロックファイルに固定します。以降のビルドはネットワークにアクセスせずキャッシュを利用します。

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

ホストとエンティティ kind のセグメントは記述されるのではなく導出されるため、 いずれかを参照に書き込んでも公開されたエンティティを指すことにはならず、 どのカタログエントリも持たない識別子になります。 Component または Feature の参照は、そのエンティティがローカルカタログ、 キャッシュ、レジストリのいずれから解決される場合でも、metadata.name そのものに 省略可能な :version を付けたものです。プライベート レジストリを利用するワークスペースは、各参照ではなく自身の設定で そのホストを指定します。

完全性チェック

すべてのマッピングが解決された後、コンパイラは、開発者の Aggregate 内のすべての component およびアタッチメントのインスタンス(資格情報の Feature も他と同じくアタッチメントです)に、解決済みの Recipe または FeatureRecipe があることを検証します。マッピングされていないエンティティは致命的な停止を引き起こし、不足しているすべてのエンティティを列挙して、欠落を埋めるために追加すべき components.type または features.type のキーを提示する明示的な診断が出力されます。

DRY な manifest のための YAML アンカー

大規模なマッピングセットで YAML が肥大化するのを避けるため、Manifest は標準の YAML アンカー(& と *)用に、省略可能な defs: ブロックをサポートします。

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Feature のネゴシエーション

ケイパビリティのハンドシェイクは、同じフラットな URI マッピングを使用します。

  1. 開発者は Aggregate 内の component に core/data-masking をアタッチします。その component の features: マップ内で、独自の名前を付けてアタッチします。
  2. コンパイラは Manifest の features.type マップで core/data-masking を検索します。
  3. 検索結果が FeatureRecipe URI(例: helm/data-masking-litellm:1.0.0)に解決された場合、そのケイパビリティは存在し、FeatureRecipe のパイプラインが定義された順序で実行されます。
  4. features.type に一致するエントリがない場合、コンパイラはビルドを停止し、マッピングされていない Feature を列挙します。

Manifest は features.annotations ブロックも受け付けます。これは、Release または Aggregate のサブシステムが、component ごとの宣言ではなくアノテーションキーによって Features をアタッチできる、並行する記述手段です。バインディングの形、どの記述手段がどのルーティングパスを使うかを決める side と pillar の区分、明示的なアタッチメントを優先する規律、およびスキーマのデフォルトに関する規則は、後述の専用セクション Annotation-Driven Feature Bindings で説明します。

extends による合成

Manifest は、mappings を継承するベースの Manifest を指定する extends: 参照を 1 つだけ宣言できます。この参照は URI ではなく、カタログを通じて解決されることはありません: Manifest はデプロイ側のものであり、公開されるのではなく Release のそばで記述されるため、この値は Manifest ファイルへの相対パス(./base-manifest.yaml)か、Release 自身のディレクトリにある Manifest の素の metadata.name のいずれかです。相対パスはワークスペース内の Manifest を指す必要があります。ただし、Release がワークスペースの外で指定された場合(コマンドライン上、またはワークスペースの設定によって)はその Release を含むディレクトリ内、ワークスペースの外にある Manifest をコマンドライン上で単独で指定した場合はその Manifest を含むディレクトリ内の Manifest を指す必要があります。ディレクトリの外へ出るパス、またはシンボリックリンクによって外へ出るパスは、指す先のファイルが読み込まれる前に拒否されます(errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside(別のファイルへの参照が、留まるべきディレクトリの外へ出ています)” を参照)。キーが衝突した場合は子のマッピングがベースを上書きするため、環境オーバーレイのパターン(環境ごとの最小限の差分によるステージングと本番の同等性)やローカル開発のパターンを、全体をコピーして記述することなく実現できます。

マージのセマンティクス。 ローカルの Manifest がベースの Manifest を拡張する場合、コンパイラは階層ごとに浅いキー置換を行います。type と name の辞書はそれぞれ独立してマージされ、深いマージは行われません。これにより O(1) の辞書検索が保証され、継承の動作が予測しやすくなります。各階層の中では、子のキーが親のキーを上書きします。

ローカル開発のブリッジパターン。 extends の一般的な用途は、Aggregate に手を加えずに、ローカルでのプロトタイピング用に認証情報の FeatureRecipe を差し替えることです。本番環境では、ベースの Manifest が features.type 階層で認証情報の Feature core/aws-secrets-manager を本番用の FeatureRecipe にマッピングします。ローカルでのプロトタイピング用には、プラットフォームチームがベースを拡張する local-manifest を提供し、認証情報の Feature のマッピングだけを上書きして host-env-injector を使うようにします。これは、認証情報を ${SECRET_NAME} のような変数参照として Compose ファイルに渡すローカルの FeatureRecipe で、スタックの起動時に Docker Compose がシェル環境または .env ファイルから値を代入します。開発者は標準的なローカルワークフローを利用でき、Aggregate は本番環境に向けてケイパビリティに依存しないままです。

コンテキスト認識型の短縮 URI

Aggrega コンパイラは、Manifests 内の OCI URI を解決する際に コンテキスト認識型推論(Context-Aware Inference) を使用します。エンジニアが完全修飾ドメイン名(FQDN)とアーキテクチャ上のエンティティ型を省略した場合、コンパイラは自動的にデフォルトレジストリ(.aggrega-config.yaml で設定)にフォールバックし、スキーマ内で文字列が置かれている位置に基づいてエンティティ型を推論します。

推論ルール:

  1. ドメインのデフォルト: ドメインを持たない URI(例: python-worker-helm:1.0)には、設定された default_registry(デフォルト: hub.aggrega.ai/)がプレフィックスとして付加されます。
  2. コンテキストに基づくエンティティ展開: コンパイラは、厳密なスキーマ辞書に基づいて正しいエンティティパスを付加します。
    • Aggregate.spec.components[].type 配下の文字列は /component/ に展開されます。
    • Aggregate.spec.aggregates[].type 配下の文字列は /aggregate/ に展開されます。
    • Manifest.spec.mappings.components.type または Manifest.spec.mappings.components.name 配下の文字列は /recipe/ に展開されます。
    • Manifest.spec.mappings.features.type または Manifest.spec.mappings.features.name 配下の文字列は /featurerecipe/ に展開されます。これには認証情報の Features(feature.aggrega.ai/kind: secret というラベルが付いたもの)も含まれ、同じ FeatureRecipe のパスを使用します。
    • pipeline[].plugin に割り当てられた文字列は /plugin/ に展開されます。
  3. 3 層の優先順位: OCI 推論を適用する前に、コンパイラは 3 層エンティティ解決モデル で定義されているとおり、ワークスペースのカタログディレクトリとアーティファクトキャッシュ(ワークスペースとキャッシュの層)を検索します。OCI 推論が適用されるのは、エンティティがレジストリの層に到達した場合のみです。マッピングのキーや値がファイルパスとして読まれることはありません。ローカルで作成された Recipe や FeatureRecipe はカタログディレクトリ(ワークスペースルートの catalog/、または workspace.catalog_dirs に列挙されたディレクトリ)に置かれ、その参照によって指定されます。

短縮記法の実例:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

ops/ プレフィックスは付きません。 Recipe 名には ops/ プレフィックスは付きません。OCI 分類体系における recipe/ エンティティ型ディレクトリがすでにドメインを識別しており、Recipes は追加のプレフィックスなしに recipe/{capability}/{name} 配下で配布されます。Manifests は Recipes を {capability}/{name} で参照するか、コンテキスト認識型推論のために名前のみで参照します。OCI 分類体系の全体については architecture/13-catalog-and-registry.md §6 を参照してください。

アノテーション駆動の Feature バインディング

Manifest の features.annotations ブロックは、アノテーションキーと Feature 型の間のバインディングと、各バインディングがアノテーション値を送るルーティングパスを宣言します。バインディングは、コンポーネントごとに繰り返される Feature のアタッチ(境界をまたぐ数十のコンポーネントがそれぞれ同一の features: ブロックを持つパターン)を、Release の境界や Aggregate のサブシステム上の単一のアノテーション宣言に圧縮するための記述面です。

スキーマの形:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

バインディングは、対象の Feature 型を指定する feature フィールドと、ドット区切りパスのサブキールートを対象の柱ごとにまとめる maps ブロックを持ちます。feature フィールドが参照する Feature 型は、兄弟の features.type セクション(FeatureRecipe のバージョンバインディングが置かれる場所)にも現れる必要があります。maps ブロックは柱をキーとする 2 つのリスト maps.infra と maps.values を宣言し、それぞれが対象 Feature の spec.schema.<pillar>.<path> プロパティを指すドット区切りパス文字列を持ちます。バインディングは 2 つのリストを合わせて少なくとも 1 つのパスを宣言する必要があります(JSON Schema が maps に minProperties: 1 を強制します)。

同じアノテーションキーに対する Provider ポリモーフィズム(たとえば、feature.aggrega.ai/rewrite-host を Kubernetes のデプロイでは core/k8s-dns-resolver にバインドし、ローカルの Compose のデプロイでは core/compose-bridge にバインドする場合)は、異なる Manifests で異なる Feature 型を選択することで表現します。各 Manifest はアノテーションを 1 つの Feature にバインドし、選択された Feature の FeatureRecipe がプロバイダー固有の実装を持ちます。

側と柱の分割。 Aggregate-as-Authoring-Surface 不変条件は、各記述側を 1 つの柱のルーティングパスに制限します。Aggregate 側のアノテーションは maps.values のパスのみを通り、Release 側のアノテーションは maps.infra のパスのみを通ります。両方の柱にパスを宣言するバインディングは側をまたぐ合成をサポートします。Aggregate 側のアノテーションは values 柱のサブセットを発火させ、同じキーに対する Release 側のアノテーションは infra 柱のサブセットを発火させ、両方の寄与は (Component, Feature) ペアごとに両方の柱が埋まった 1 つの Feature アタッチに合成されます。側と柱の不一致(たとえば maps.infra のみを宣言するバインディングに対する Aggregate 側のアノテーション)は、アノテーションキー、ルーティングされた柱、記述側、ソースの位置を示す明確な診断とともにビルドを停止し、その診断はアノテーション値が記述されたドキュメントのドメインに分類されます。

パスターゲットの検証。 カタログの読み込み時に、コンパイラは maps.infra と maps.values の下に宣言されたすべてのドット区切りパスが、対象 Feature の spec.schema.<pillar> が実際に宣言するプロパティに対応することを検証します。Feature のスキーマに記載されていないパスへルーティングするバインディングは、バインディング、対象の Feature、ルーティングに使われた柱とパスを示す明確な OPS_ERROR とともにカタログの読み込みを停止します。単純なプロパティ走査を逃れるスキーマの形($ref、patternProperties、oneOf / anyOf / allOf の合成)では、その分岐で静的チェックを終了し、不一致は下流のスキーマ検証に任せます。

アノテーション値の形。 バインディングはアノテーション値を 3 つの形で受け取ります。スカラー:単一の YAML 値(文字列、数値、真偽値)です。両方の柱を合わせてちょうど 1 つのパスを宣言するバインディングと組み合わせたスカラーは、その単一のパスに値をルーティングします。2 つ以上のパスを宣言するバインディングと組み合わせたスカラーは曖昧なルーティングであり、明確な診断とともにビルドを停止し、その診断はアノテーション値が記述されたドキュメントのドメインに分類されます。構造化:トップレベルの各サブキーが maps.infra または maps.values の下のドット区切りパスのエントリに一致する YAML マップです。各サブキーは宣言された柱へ独立にルーティングされ、側と柱の分割はサブキーごとに適用されます。明示的な YAML null:カスケードのスコープで継承されたバインディングをオプトアウトします(構造化値の中のサブキーごとの null は、兄弟を残したまま個々のサブキーをオプトアウトします)。構造化値に関する正規の記述ガイド(サブキーごとのカスケードマージ、側をまたぐ合成、サブキーごとの型検証、type が宣言されていないスキーマフィールドに対する緩和されたデフォルトの規律)については、providers/well-known-annotations.md の §“Structured annotation values” を参照してください。

キーが衝突した場合は明示的なアタッチが優先されます。 Release のコンポーネントまたは Aggregate のコンポーネントが、明示的な features: エントリと、同じ Feature キーに展開されるアノテーションの両方を持つ場合、明示的なエントリが保持され、そのコンポーネント上のそのキーに対するアノテーション展開は何も行いません。合成アタッチが作成者の宣言した Feature インスタンスを上書きすることはありません。したがって作成者は、大部分のコンポーネントにはアノテーション展開を使い、同じキーの明示的な features: エントリを書くことで個々のコンポーネントをピンポイントで上書きできます。明示的なエントリがコンポーネントごとのカスタマイズを持ち、アノテーションは他のすべてのコンポーネントにそのままカスケードします。

側をまたぐ合成ではリーフごとに明示的なものが優先されます。 明示的なアタッチとアノテーションの寄与が同じ Feature インスタンスを埋めるものの異なるリーフに書き込む場合、両方の寄与が残り、結果の Feature は両方のリーフを持ち、リーフごとのプロベナンスが各リーフのソースを記録します。明示的なアタッチとアノテーションの寄与が同じ柱の中の同じリーフを対象とする場合、明示的な寄与が優先され、IR は抑制されたアノテーションのプロベナンスをそのリーフ上のオーバーライドマーカーとして記録します。カタログの読み込みでは、抑制されたアノテーションキーとソースを示す助言的な lint 警告によって、ビルド時にこのオーバーライドを表面化します。

展開時のスキーマデフォルト。 アノテーション展開によって生成される合成 Feature アタッチは、アノテーション値がバインディングの宣言されたパスを通じて埋めるリーフのみを持ちます。対象 Feature の spec.schema に宣言されたスキーマデフォルトは、展開時に合成アタッチへマージされません。デフォルト値の具体化は FeatureRecipe のレンダリング層の責務であり、明示的なアタッチと合成アタッチに一様に適用されるため、同じ実効設定に対して 2 つの経路は同じ下流の出力を生成します。

アノテーションの名前空間の分離:

プレフィックス所有者目的
aggrega.ai/Aggrega プラットフォームのみプロバイダーが直接読み取るプラットフォームネイティブのアノテーション(例:aggrega.ai/namespace)。
feature.aggrega.ai/公式標準ライブラリManifest でバインドされる Feature アノテーションのショートカット。
{any-other-domain}/エンタープライズ / コミュニティカスタムの Feature アノテーションのショートカット。

aggrega.ai/ プレフィックスの予約

Manifest の features.annotations バインディングでは、単独の aggrega.ai/ プレフィックスは使用できません。このプレフィックスは、コンパイラが出力するプラットフォームネイティブのアノテーション(OTel/来歴ラベルなど)用に予約されています。スコープ付きのサブプレフィックス(component.aggrega.ai/*、compliance.aggrega.ai/*、エンタープライズ向けの acme.aggrega.ai/*)は、引き続きユーザーが記述に使用できます。プラットフォームで予約されているアノテーションの一覧については、providers/well-known-annotations を参照してください。