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

社会契約

Aggrega は、設計上、主張を持たないコンパイラです。architecture/05-invariants.md に記載された基本不変条件のとおり、コンパイラは YAML を解析し、グラフを走査し、ラベルの交差を評価し、コンポーネント間で文字列を受け渡します。しかし、開発者が values、parameters、infra、provides、locals に何を記述するかは取り締まりません。命名の慣例、ポートの慣例、Architect が考案するセマンティックなラベルを強制することもありません。名前からコンポーネントの目的を推測することもありません。コンパイラの規則のように聞こえる多くの規律は、実際には 社会契約 です。つまり、スキーマや実行時の強制ではなく、記述上の慣例によって維持されるベストプラクティスです。

この中立性がどこで止まるかは、はっきり述べておく価値があります。境界は一本の線であり、読み込みすぎやすいためです。 いくつかのキーは Aggrega 自身のものです。これらは予約されており、取りうる値が公開スキーマに記述されています。こうしたキーについては、スキーマが他の宣言済みフィールドと同じように検査を行います。プラットフォーム自身が定義するキーの値集合を宣言することは、コンパイラが記述内容に意味を読み込むことではありません。プラットフォームが自身のキーの意味を述べているにすぎません。独自のキーの下に記述するものはすべて、このページで説明するとおり、まったく取り締まられないままです。

このページは、この言語の社会契約の正式な一覧です。このページで契約を学んだ作成者は、コンパイラが慣例上不正なビルドを受け入れる理由(実際に受け入れます。コンパイラは慣例を解釈しません)と、違反を検出する責任がどこにあるか(記述上の規律、レビュアーの注意、または aggrega lint が実行するリンタープラグイン)を理解できます。

規律の 3 つのクラス

Aggrega の規律は、その規律がどのように強制されるかによって 3 つのクラスに分かれます。この分類が重要なのは、規律に違反したときの失敗のしかたがクラスごとに異なるためです。

スキーマによる強制

この規律は、ロード時の JSON Schema 2020-12 による検証で強制されます(エンティティエンベロープの JSON Schema に加え、Component エンティティと Feature エンティティ上のピラーレベルの schema: 宣言)。違反するとビルドが進む前に致命的な停止が発生し、コンパイラは処理を続行しません。スキーマで強制される規律に違反しようとした作成者には、フィールドと制約を示す明示的な検証エラーが表示されます。

例:エンティティエンベロープの必須フィールド(apiVersion / kind / metadata.name / metadata.version)、metadata.version に対する SemVer 正規表現、予約済みの component.aggrega.ai/type ラベルの閉じた値セット、Release スキーマによる values: ブロックの機械的な禁止(Invariant 5 による)、Release における extends と aggregate の併用の拒否(Single Source of Truth の不変条件)、入力種別の合成契約を強制する Recipe の形状ルール。

スキーマで強制される規律は、この言語が持つ最も強い保証です。コンパイラは、これに違反するものを一切レンダリングしません。

ポリシープラグインによる強制

この規律は、文書化されたソケットポイントのいずれかで実行される Wasm プラグインによって強制されます(トポロジー構築時のガバナンス label-transform ロール、静的解析時のガバナンス ir-verdict ロール、帯域外の linter ソケット)。違反すると、ソケットのゲーティングのセマンティクスに応じて、ビルドを停止させるポリシー違反(帯域内ソケット)または助言的な警告(帯域外ソケット)が発生します。

規律がこの方法で強制されるのは、それをチェックするプラグインが実行される場合に限られます。Wasm ランタイムは文書化されたソケットポイントでプラグインを呼び出し、どのプラグインもチェックしない規律は慣例のままです。aggrega lint が実行する公開用リンターは、このページの 1 つの慣例の一部をチェックします。リンタールールがチェックする慣例を参照してください。公開用リンターのどのルールも、ハーメティシティ(templates/sprig-functions.md の決定性に関する注意事項にあるとおり、Sprig FuncMap は出力の決定性を損なうヘルパーを公開しています)や、クラウドリソースの命名(entities/recipe.md の「Cloud-resource naming discipline」に従った release_name / instance_id の補間なしにクラウドリソース名フィールドを参照する valuesMapping: 出力を持つ Recipes)をチェックしません。独自のリンタープラグインであれば、そのどちらもチェックできます。

Wasm プラグインの契約インターフェースと配置の基準(リンターソケットとガバナンスの判定ロールの違い)については、plugins/plugin-contract.md を参照してください。

慣例による維持

この規律は、作成時の規律とレビュアーの注意によってのみ維持されます。コンパイラは強制せず、違反を拒否するスキーマもなく、違反を検出する Wasm プラグインもありません。作成者はドキュメントから規律を学び、アーキテクチャの形がそれに依存しているためにそれに従い、見落としの発見は PR レビューに頼ります。違反してもコンパイル時のシグナルは発生しません。ビルドは成功し、レンダリングされた出力もコンパイラが知る限りでは正しく動作し、規律違反が表面化するのは、下流のツールやランタイムの動作がその慣例に依存したときだけです。

慣例によって維持される規律は、作成者がドキュメントから学ばなければならない、重要な役割を担う一覧です。コンパイラはこれらを解釈しません。誤ってもビルドは壊れませんが、Aggrega が依存するアーキテクチャの形が壊れます。このページの大部分は、これらを記述しています。

慣例

以下の社会契約は、慣例によって維持されています。各項目では、規律の内容、その慣例が記載されている箇所、違反した場合の障害モードを示します。各項目は、どこに置かれていても番号を保ちます。契約 3 の予約プレフィックスの規律は、アノテーションキーについてリンタールールがチェックし、リンタールールがチェックする慣例で説明しています。

1. コンポーネントに合った運用タイプの選択

予約済みの component.aggrega.ai/type ラベルは、コンポーネントがどのような種類のものかを示します。値は、普遍的なクラウドプリミティブからなる閉じた集合 server、worker、task、function、stateful-server、resource から選びます。この集合に含まれるかどうかは、慣例によって維持されるのではなく、スキーマによって強制されます。 このキーと受け付ける値は Aggrega が定義しており、Component スキーマがそれらを列挙しています。それ以外の値を持つドキュメントは読み込み時に拒否されます。E0215(entity-envelope-invalid 条件)がそのラベルを示し、受け付ける値を一覧表示します。この拒否は、この項目が対象としない部分です。

慣例として残るのは、目の前のコンポーネントに値のどれが合うかです。リレーショナルデータベースに server ではなく stateful-server が付けられているか、キューのコンシューマが task ではなく worker になっているかを確認する仕組みはありません。セレクターは、見つけた値に意味を読み込むことなくそのまま評価します。Component を作成する Architect は、インフラストラクチャがそれをどう扱うべきかを表す値を選びます。下流のセレクター、ポリシープラグイン、Wasm レンダリングプラグインはすべて、その選択が正直であることに依存しています。

独自の軸での分類。 閉じた集合が管理するのはこの 1 つの予約済みキーだけです。Aggrega が定義していない分類(ティア、データゾーン、サービスクラス、運用プリミティブのより細かい分割など)を必要とするカタログは、予約済みキーの隣に独自のラベルキーを追加します。Component スキーマは文字列値を持つ任意の追加ラベルキーを受け付け、同じセレクターの仕組みがそれを読み取ります。そのため、acme.aggrega.ai/storage-tier: oltp を component.aggrega.ai/type: stateful-server と並べて置くことができ、Feature の appliesTo やソケットの selector はどちらも対象にできます。拡張は独自のキーで行い、Aggrega のキー内の値で行うことはありません。

記載箇所: architecture/02-ecosystem-philosophy.md(運用オントロジー)+ labels-and-annotations.md(プレフィックスの規律)+ errors/sentinels.md(E0215)。

障害モード: 集合内の値であってもコンポーネントに合わないものは、そのラベルを読むすべてのものを誤らせます。server と付けられたデータストアは、stateful-server を選択する Feature やソケットから拒否されます。この停止が示すのは誤ったラベルではなくセレクターです。また、そのラベルを読むポリシープラグインやレンダリングプラグインは、それをステートレスなコンピュートとして扱います。そうした読み手しかそれを見ない場合、ビルドは成功し、誤りはレンダリングされた成果物がクラスターに届いて初めて表面化します。

2. .context.annotations.* の 3 バケット分離

カスケードされたアノテーションは、.context.annotations.release、.context.annotations.catalog、.context.annotations.aggregate という 3 つの名前付きバケットに入り、それぞれ異なる意図を持ちます。規律の目標は次のとおりです。release は「このコンポーネントがどこで実行されるか(Ops が管理)」、catalog は「このコンポーネントが何であるか(Architect が作成)」、aggregate は「このコンポーネントが何をするか(Developer が作成)」です。

コンパイラはバケットの境界を強制しません。3 つのバケットはフラットな string → string の形を共有しており、Recipe のテンプレートは 3 つすべてを読み取れます。Release の境界アノテーションが認知メタデータとして解釈されることや、カタログのアノテーションが infra: にルーティングされることを妨げるものはありません。この分離は、作成者がアノテーションを正しいバケットに書き込み、レビュアーがバケット間の漏れを見つけることで守られます。

記載箇所: labels-and-annotations.md(3 バケット分離は Social Contract です)。

障害モード: バケットの意図の区別に依存するルーティングロジック(例: .context.annotations.release.aggrega.ai/region を Terraform の region フィールドにルーティングする Recipe)は、作成時の意図にかかわらず、そのバケットに現れたアノテーションを黙って消費します。ビルドは成功しますが、レンダリングされた出力に意味的に誤った値が含まれる可能性があります。

4. Recipe の provides: の自己完結性

Recipe の provides: テンプレートが閉包として参照するのは、ノード自身のデータのみです。すなわち .values、.infra、.context.instance_id、ノードの Provider が報告する場合の .context.rendered_name、ノードの解決済み .locals、および静的文字列です。.context.inject と .context.uses への参照は禁止されています。provides の評価はこれらのテンプレートを任意の順序で実行するため、ノード間のデータを読み取るとトポロジー上の反復順序に結合してしまい、設計はそれを意図的に避けているからです。.locals は対象外ではなく対象に含まれます。ノードの locals は同じステージのプリアンブルで provides より先に解決され、ノードローカルであるため、読み取っても順序上のコストは生じません。locals ブロックで宣言されていないキーを指定すると停止します。

これは 2 つの部分からなるルールで、それぞれがどこでチェックされるかを示します。前半はコンパイラがチェックします。provides の評価では、テンプレートの実行前に、そのコンテキストが定義するルートの肯定的な許可リストに照らして各テンプレートを検査します。そのため、.context.inject / .context.uses の読み取りは空としてレンダリングされるのではなく、明示的なエラーで停止します。このルールは templates/expansion-matrix.md の 6 行目にも記載されています。後半は慣例が維持します。より広いパターン(provides は公開、locals は非公開)は慣例に基づいています。

記載箇所: templates/expansion-matrix.md の 6 行目 + vocabulary/data-pillars.md 「provides: と locals: — 公開の顔と非公開の顔」。

障害モード: 禁止された参照が provides: に直接現れた場合、コンパイラはテンプレート評価時にそれを検出してビルドを停止します。より広い公開と非公開の規律(内部状態を provides: のキーで公開しない)は慣例のみです。provides: を Recipe 内部の名前空間として扱う作成者は、呼び出し側が依存する契約を生み出し、リファクタリングが破壊的変更になります。

5. 決定性 — レンダーパスのテンプレートにおける非ハーメチックなヘルパー

Aggrega の決定的出力不変条件(architecture/05-invariants.md の不変条件 8)は、バイト単位で同一の入力に対してバイト単位で同一の出力を求めます。Sprig の完全な FuncMap は、周囲の状態を読み取るヘルパーを公開しています(実時間を読む now / date、乱数生成器 randAlpha / uuidv4、環境を読む env / expandenv、ネットワークを解決する getHostByName)。レンダリング出力に寄与するテンプレートからこれらのヘルパーを呼び出すと、決定性の契約が破られます。

コンパイラは非ハーメチックなヘルパーの使用を検出もブロックもしません。Sprig FuncMap は templates/sprig-functions.md の「Determinism caveat」に従ってそれらを公開しています。この規律は、作成者がレンダーパスのテンプレートでこれらのヘルパーを避け、レビュアーが PR レビューでその使用を見つけることによって維持されます。

記載箇所: templates/sprig-functions.md の「Determinism caveat」。

違反時の障害: 同じ入力に対する実行ごとにビルド出力が異なります。この不一致は、下流のツール(ArgoCD、Flux)がコミット済みのマニフェストとクラスタの状態の間に予期しないドリフトを検出する GitOps の差分時、または同じ入力の 2 回のコンパイルが異なる成果物を生成する監査時に表面化します。

公開用リンターのどのルールも、テンプレート内の非ハーメティックなヘルパーの呼び出しをチェックしません。ヘルパーの名前はテンプレートに書かれているため、独自のリンタープラグインであればそれを見つけられます(リンタールールがチェックする慣例を参照)。

6. ピラーの境界(壁ではなく道標)

ピラーの境界は作成上の規律であり、言語による強制ではありません。テンプレートエンジンは、自己完結性のルール(例: Recipe の provides: と source: が .context.inject / .context.uses を読むこと)で明示的に禁止されていない限り、すべての箇所でピラーをまたぐ読み取りを許可します。作成者は次のようにすべきです。

  • 認知的なペイロード(開発者が作成した意図)には .values を読みます。
  • 物理的なサイジング(Ops が作成したサイジング)には .infra を読みます。
  • コンポーネント間のポインタ文字列には .context.uses.<alias>.provides.<key> を読みます。
  • ハイドレーション後の配信パイプには .context.inject を読みます。

テンプレートエンジンは読み取りを制限しません。.infra.replicas を読んで values: のフィールドを駆動する Recipe テンプレートは動作し、ピラーをまたぐ経路を妨げるものはありません。この規律が目指すのは道標です。境界は実行時の制限ではなく、作成上の意図(誰がデータを所有するか)を表します。

記載箇所: vocabulary/data-pillars.md の「Pillar boundaries and authoring discipline」。

違反時の障害: ピラー間の漏れ — 開発者の認知的なペイロードに物理的なサイジングの詳細が含まれる、あるいは Ops が作成したサイジングに認知的なメタデータが含まれます。ビルドは成功しますが、作成者がピラーを近道するにつれて 4 領域の作成分担は時間とともに曖昧になり、ピラーとデータフローの対応が弱まるにつれて下流の保守は難しくなります。

7. Workload の containers.<name>.variables の二重ソースのセマンティクス

variables: マップは、Go テンプレート式を介して 2 つの異なるデータソースを混在させます。開発者ピラーのリテラル(.values / .infra / .locals を読むエントリ)と、コンポーネント間パイプのデータ(.context.inject.env.<KEY> を読むエントリ)です。作成者は、値がコンポーネントローカルか、コンポーネント間から導出されたものかに基づいて、エントリごとに 1 つのソースを選びます。

コンパイラは 2 つのソースを区別しません。どちらもレンダリングされた Deployment 上の同じ Kubernetes の env: リストに流れ込みます。二重ソースのセマンティクスは作成時のみのものです。この規律は意図を名指すこと(このエントリはコンポーネントローカル、あのエントリはコンポーネント間から導出)であり、将来の保守担当者がどのエントリがどの inject ハイドレーション出力に依存しているかを読み取れるようにします。

記載箇所: entities/workload.md の「Field-semantics essentials」(variables)。

違反時の障害: 2 つのソースを区別しない作成者は、「どのエントリがどのターゲットの provides: に結合しているか」の追跡を失います。ターゲットの provides: キーをリファクタリングすると、inject パイプ経由で読み取っていた呼び出し側のすべての variables: エントリが暗黙のうちに壊れます。

8. クラウドリソースの命名規律

クラウドリソース名(S3 バケット名、RDS データベース識別子、IAM ロール名、CloudFormation スタック名など、値がクラウドプロバイダでグローバルな名前空間を占めるあらゆるフィールド)を出力する Recipes は、同じ Recipe が複数の Releases やコンポーネントインスタンスにわたって実行される際の衝突を避けるため、レンダリングされる名前に {{ .metadata.release_name }} および/または {{ .context.instance_id }} を連結する必要があります。

コンパイラは、これらの補間を含まないクラウドリソース名フィールドがないか valuesMapping: の出力を検査しません。この規律は、Recipe の作成者(ターゲットプロバイダでどのフィールドがグローバルに一意なリソースを命名するかを知っている)とレビュアー(PR レビューで名前付けされていないリソースのパターンを見つける)によって維持されます。

記載箇所: entities/recipe.md の「Cloud-resource naming discipline」。

違反時の障害: 同じ Aggregate の 2 つの Releases(prod-billing と staging-billing)が、どちらも同じグローバル名を持つリソースをデプロイしようとし、2 回目のデプロイは実行時にクラウド側の拒否によって失敗します。Aggrega のビルドは成功し、デプロイの失敗は 2 つ目の Release が適用されたときに初めて表面化します。

公開用リンターのどのルールも、クラウドリソース名フィールドに必要な補間があるかをチェックしません。独自のリンタープラグインであればチェックできます(リンタールールがチェックする慣例を参照)。

9. Component の粒度 — Component ごとに 1 つのまとまったサービス

Component は 1 つのまとまったサービスをモデル化します。単一の公開サービス、または 1 つのサービスのワークロードとその内部専用のヘルパーワークロードの組です。チャートが、他のコンポーネントが単独で意味のある形で use できるサービス — 特に、Aggrega がすでに独自の Component としてモデル化しているデータベース、キャッシュ、メッセージブローカーなどの外部インフラストラクチャ — を束ねている場合、標準ライブラリは製品全体を 1 つの不透明な Component として包むのではなく、サービスごとの Components をサブ aggregate のモジュール(spec.aggregates + exportedComponents)に合成します。規律としては、Component 内でのマルチワークロードは問題なく、独立した利用可能性が 1 つの Component をスタックに分割する境界線です。

コンパイラはこの粒度に依存しません。スキーマ検証を通過したものは何でもレンダリングし、Component の Recipe がいくつのサービスを束ねているか、そのうちの 1 つが独立して利用可能かどうかは検査しません。5 つのサービスからなる製品を単一の Component として包む作成者は、コンパイラが受け入れ、問題なくレンダリングする Component を生成します。この慣例は、作成上の規律とレビュアーの注意によって維持されます。

記載箇所: ../../architecture/06-data-taxonomy-and-composition.md(One coherent service per Component — the single-workload boundary)。

違反時の障害: モノリシックなマルチサービスのラップはビルドに成功しますが、束ねられたサービスはトポロジ、セレクタ、ポリシーから見えず、独立してスケール、置き換え、依存することができません。後からモノリスをサービスごとの Components にリファクタリングすると、単一のラップされたノードを参照していたすべての利用側にとって破壊的変更になります。

慣例が存在する理由

これらの慣例はいずれも、スキーマや Wasm のポリシーで強制することもできますが、設計上オーサリング上の規律とされています。契約の種類ごとの理由は次のとおりです。

拡張性。 予約プレフィックスの規律(契約 3)は、標準ライブラリの語彙を記述するものであり、有効な語彙の全体を記述するものではありません。エンタープライズのカタログは、標準ライブラリを拡張するために独自のプレフィックスやラベルキーを作成します。プレフィックスの慣例をスキーマで強制すると、「標準ライブラリの規律」が「言語で唯一許される形」に変わってしまいます。これこそ、アーキテクチャが意図的に避けている壁です。運用タイプの軸(契約 1)は、別の面で同じ拡張性を保ちます。Aggrega が定義する予約キーは、閉じたスキーマ強制の集合を持ち、カタログは Aggrega の値の中に値を追加するのではなく、その横に独自のラベルキーを追加することで拡張します。スキーマが検査するのは、スキーマ自身が所有する 1 つのキーの値集合であり、開かれたまま残るのはそれ以外のすべてのキーで、そこにカタログ独自の語彙が置かれます。

AOT の純粋性。 クラウドリソースの命名規律(契約 8)と決定性の規律(契約 5)では、フィールドがクラウドリソース名なのか、非ハーメティックなヘルパーの呼び出しなのかを判定するために、テンプレートの内容を検査する必要があります。AOT の純粋性(Invariant 2)により、コンパイラはランタイムの状態に依存しません。テンプレートの静的な検査は実現可能です(リンタープラグインはエンティティのテンプレートを書かれたとおりに読みます)が、それをコアコンパイラ内で行うと、コンパイラ内部のロジックがドメインごとのオーサリング上の関心事と結合してしまいます。アーキテクチャは、Invariant 6(Wasm ABI Boundary)に従い、これらの検査をコンパイラの外に出し、Wasm プラグインに移します。

オーサリングの柔軟性。 ピラー境界の規律(契約 6)と二重ソースの variables セマンティクス(契約 7)は、ランタイムの制約ではなくオーサリングのパターンを記述します。同じテンプレート構文で、規律に沿ったパターンも規律に反するパターンも表現できます。規律をランタイムチェックにすると、コンパイラがアクセスできないオーサリングの意図を解釈する必要が生じます。アーキテクチャは、この慣例をランタイムの不変条件ではなく、作成者が学ぶためのドキュメントとして扱います。Component の粒度(契約 9)もここに含まれます。エンタープライズは自社のカタログが好む任意の粒度で製品をラップでき、Invariant 1 に従って内容に対して中立で主張を持たないコンパイラには、バンドルされたワークロードが独立して利用可能かどうかを知る手段がありません。そのため、1 つのまとまったサービスという境界は、スキーマの壁ではなくオーサリング上の規律のままです。運用タイプの選択(契約 1)も同じ形です。スキーマはどの値が存在するかを確定しますが、どの値が特定のコンポーネントを記述するかは、インフラストラクチャがそれをどう扱うべきかについてのモデリング上の判断であり、Recipe や values ブロックのどこにも、その判断が正しかったかどうかをコンパイラに伝えるものはありません。

2 つに分かれた強制。 Recipe の provides: の自己完結性(契約 4)は、部分的にコンパイラによって強制されます。レンダーパスは provides: テンプレート内の .context.inject / .context.uses の読み取りを検出し、停止します。より広い公開と非公開の規律(内部状態を公開しないこと)は慣例に基づいています。オーサリングの意図なしには、どの文字列を Recipe 内部に留めるべきかをコンパイラが判断できないためです。

この 3 つの経路が重要なのは、それぞれが違反を検出する責任がどこにあるかを示すからです。スキーマによる強制:コンパイラ。ポリシープラグインによる強制:それをチェックするプラグイン(実行される場合)。慣例による維持:作成者とレビュアー。これらの経路を理解した作成者は、どの誤りをコンパイラが検出し、どの誤りが下流のツールやランタイムまで黙って通過するかを把握できます。

リンタールールがチェックする慣例

aggrega lint が実行する公開用リンターは、このページの 1 つの慣例を部分的にチェックします。以下の契約 3 のアノテーションキーです。その検出結果は助言的なものであり、慣例のうちリンターが及ばない部分は、上記の各項目と同様に慣例によって維持されます。

公開用リンターのどのルールも、このページの他の慣例をチェックしません。そのうち 2 つは、違反がエンティティに書かれているため、リンタールールでチェックできます。決定性(契約 5)、つまり非ハーメティックなヘルパーを呼び出すテンプレートと、クラウドリソースの命名(契約 8)、つまり release_name / instance_id の補間なしにクラウドリソースを命名する valuesMapping: 出力です。予約プレフィックス配下のラベルキー(契約 3)も同様です。ワークスペースは、公開用リンターと並べて plugins.linter の下に独自のリンタープラグインをアタッチし、これらのいずれもチェックできます。The discipline rules に、公開用リンターが持つルールが一覧されています。

その他の慣例(1、2、4、6、7、9)は作成者の意図に左右され、どのルールも書かれた内容からそれを読み取れません。バケットの分離は拡張性に基づくもの(エンタープライズのカタログが上書きする)であり、スキーマによる強制はその柔軟性と衝突します。スキーマが値の集合を確定した後に運用タイプ軸に残るもの、つまりコンポーネントに合ったプリミティブを選ぶことは、作成者の意図に基づきます。適切に選ばれた運用タイプと不適切に選ばれた運用タイプは、どちらもコンパイラが受け入れる値であるため、コンパイラには区別できません。ピラー境界の規律と二重ソースの variables セマンティクスは作成者の意図に基づくものであり、コンパイラはテンプレート構文だけから意図を判断できません。Recipe の provides: の自己完結性は部分的に強制されています。より広い公開と非公開の規律は、作成者がどのキーを内部に留めるつもりだったかに左右され、Recipe のどこにもそれは記述されていません。Component の粒度も作成者の意図に基づきます。バンドルされたワークロードが独立して利用可能かどうかはモデリング上の判断であり、コンパイラは Recipe の内容からそれを読み取ることができません。

3. 予約済みプレフィックスの規律

アノテーションとラベルのキーは <namespace>/<name> の形に従います。5 つの予約済みプレフィックスには、それぞれ固有の作成ルールがあります。aggrega.ai/(プラットフォーム専用)、feature.aggrega.ai/(公式 Feature のショートカット)、component.aggrega.ai/(Component 固有の特性)、aggregate.aggrega.ai/(Aggregate モジュールの識別)、<any-other-domain>/(エンタープライズ/コミュニティ)です。

コンパイラは、カタログエンティティや Release 上で予約プレフィックスの下に記述されたアノテーションを拒否しません。ビルドを停止させるのは、aggrega.ai/ 配下のキーを主張する Manifest のアノテーションバインディングまたは Recipe の出力ラベルだけです。プラットフォームの語彙の外で aggrega.ai/internal-billing-tag: "..." を宣言したエンタープライズは、コンパイラが受け付けてバケットシステムを通じてカスケードするアノテーションを生成します。後のプラットフォーム更新で本物の aggrega.ai/internal-billing-tag が導入されると、黙って衝突します。

記載箇所: labels-and-annotations.md(プレフィックスの規律)+ providers/well-known-annotations.md。

障害モード: 予約済みプレフィックス下の独自アノテーションが、同じ名前の将来のプラットフォームアノテーションと衝突します。順序によって、プラットフォームの想定する動作がエンタープライズの作成した値を黙って上書きするか、共存します。

aggrega lint が実行する公開用リンターは、カタログエンティティのアノテーションキーのうち、aggrega.ai/ 配下でプラットフォームの既知のアノテーションに含まれないものと、Feature 以外のエンティティ上の feature.aggrega.ai/ 配下のものを、助言的な検出結果(E0277)として報告します。ラベルキー、その他の予約プレフィックス、およびエンティティの metadata.annotations の外にあるアノテーション(たとえば Release が書くもの)はチェックされないため、それらについてこの規律は慣例のままです。

相互参照