コンパイルパイプライン(概要)
この章では、Go コンパイラの内部の仕組みを詳しく説明し、抽象的な YAML がコンパイルパイプライン、中間表現 (IR) グラフ、および WebAssembly (Wasm) 実行ソケットを通じてどのように物理的な構成へと変換されるかを定義します。
コンパイルパイプラインと実行フロー
Aggrega は、ハードコードされたオーケストレーションロジックではなく、厳格な固定順序の Ahead-of-Time (AOT) コンパイラパイプラインを実行します。aggrega build によって起動されたコンパイラは、物理的な成果物をレンダリングする前にアーキテクチャを評価するため、フラットなグラフを分離された WebAssembly (Wasm) ソケット間で受け渡します。
Wasm ソケットは組み込みホスト(Wazero エンジン上の Extism ツールキット)で実行され、プラグインにあらゆるランタイムアクセス機能(ネットワーク、ファイルシステム、実時間クロック、環境、標準 I/O)を与えない AOT 純粋性ファイアウォール の背後に置かれます。そのため、プラグインが決定的で事前コンパイル型の保証を破ることはできません。ホストは publishing-linter を帯域外で aggrega lint を介して実行します。以下で説明する帯域内のゲート(トポロジー構築時のガバナンスソケットの label-transform ロールと静的解析時の IR-verdict ロール、およびレンダリングを締めくくるプラグインパイプライン)は、すべてのビルドで実行されます。ガバナンスロールはワークスペースがそのロールにプラグインをアタッチしている場合に実行され、プラグインパイプラインはステップを宣言するすべての Recipe について実行されます。各パイプラインフェーズの状況は Status of the Language で追跡しています。
パイプラインは完全にメモリ内で、厳格な固定順序で実行されます。
解決 — Resolver と Syntax Validator
- メカニズム: 継承マージ、Go テンプレート補間、JSON Schema 2020-12 検証。
- 処理: CLI は要求されたすべてのエンティティ(Components、Features、Releases)を取得します。まず、これらの定義に
extendsキーワードがあるかを確認します。Catalog エンティティについては YAML メタデータをディープマージし、2 つの種類はデータの柱において扱いが分かれます。Feature のschema:は JSON Schema 2020-12 の合成によってベースのものと合成されますが、継承する Component は構造のみ(アタッチメントスロット、トポロジーソケット、自己注入の許可リスト、名前付きアサーション)を合成し、ベースのschema:ブロックはベースが記述したとおりにそのまま受け取ります。継承するReleaseも同じ規則で畳み込まれます。子の値がキーごとに優先され、最初の分割不能な値(スカラー、リスト、テンプレート)まで下り、その値は丸ごと置き換えられます。また、子がnullと記述したキーは削除されます。したがって、その記述面全体(コンポーネントごとのinfraと Feature アタッチメントを含む境界ツリー、parametersブロック、アノテーション、Manifest ポインタ)が引き継がれますが、metadataフィールドは一切引き継がれません。アイデンティティと来歴は Release ごとのものだからです。 次に、メモリ内での補間を 3 つのサブステップで実行します。Aggregate の型付きparameters:宣言に対するパラメータ契約の検証、解決された値を周囲のvalues:文字列へ補間すること、そしてすべての値テンプレートコンテキストから.parametersマップを取り除き、オペレーターが記述したパステンプレートからのみ読み取れるようにすることです。最後に、解決されたinfraブロックを対象コンポーネントのペイロードに注入します。ブループリントが完全に具体化されると、コンパイラは Catalog の統合されたschema:宣言(コンパクト形式または完全な JSON Schema 2020-12)を使用して、開発者のvaluesとinfraの設定をローカルで厳密に検証します。- Release Feature スキーマ検証: Release を介してアタッチされた Features(境界全体のものとコンポーネント固有のものの両方)は、このステップで Catalog エンティティに対して解決されます。コンパイラはカタログ解決の直後に、Release が提供する
infraブロックを各 Feature のschema:宣言に対して検証し、トポロジーが構築される前に型安全性を確保します。 - アノテーション駆動の Feature 展開サブフェーズ: Manifest の解決、Recipe/Provider のバインディング、Manifest のバインディングターゲット検証(
mappings.features.annotations.<key>.mapsの下で宣言されたパスが、参照される Feature のspec.schemaに存在すること)の後、コンパイラはトポロジービルダーの前にアノテーション展開サブフェーズを実行します。このサブフェーズは Release の境界を外側から内側へ、Aggregate のサブシステムを外側から内側へ走査し、カスケード + オーバーライド + null によるオプトアウトのマージによって、コンポーネントごとの有効なアノテーション集合を計算します。各アノテーション値を YAML としてスカラー、構造化値、または null にパースし、各値(スカラー、またはサブキーごとの構造化値)を Manifest バインディングのmaps宣言を通じて対象 Feature のスキーマの柱へ、側と柱の対応を強制しながら振り分けます(Aggregate 側はmaps.valuesを発火し、Release 側はmaps.infraを発火します)。リーフごとの型を Feature のspec.schemaに対して検証し、IR グラフがorigin: annotationでマークする合成 Feature アタッチメントを注入します。スキーマはビルドごとに一度だけコンパイルされ、カスケードの走査間で再利用されます。展開はバインディングターゲット検証の後、トポロジー構築の前に実行されるため、後続のステージは合成アタッチメントを明示的なものと構造的に同一に扱います(来歴の検査による場合を除く)。バインディングの形、カスケードのセマンティクス、側をまたぐ合成規則については、13-catalog-and-registry.md §「Annotation-driven Feature expansion」 とlanguage-reference/providers/well-known-annotations.mdを参照してください。
- Release Feature スキーマ検証: Release を介してアタッチされた Features(境界全体のものとコンポーネント固有のものの両方)は、このステップで Catalog エンティティに対して解決されます。コンパイラはカタログ解決の直後に、Release が提供する
トポロジー構築 — Topology Builder と Mutation Gate
- メカニズム: AST 展開 + ガバナンスソケットの
label-transformロール。 - 処理: コンパイラは、検証済みのコンポーネントから明示的に宣言された
usesブロックをネイティブに読み取り、グラフ内のノード間にトポロジー上のエッジを決定的に描画します。その際、valuesブロックは完全に不透明なままにします。次に Mutation Gate を評価し、グラフの射影(各ノードのラベルと、そのインスタンスが宣言するvaluesで、コンパイラはこれを読まずに渡します)を、Release の名前と環境とともに、label-transformロールにアタッチされたガバナンスプラグインに渡します。プラグインはコンテキストを評価し、グラフを動的に自動タグ付けするための JSONPatch を返します(例: Release の環境に基づいてラベルcompliance.aggrega.ai/data-class: restrictedを注入する、またはデータベースが宣言する拡張機能に基づいてdatastore.aggrega.ai/engine: vectorを注入する)。パッチが及ぶのはラベルだけです。
グラフの確定
- メカニズム: 正規化。
- 処理: コンパイラは、トポロジービルダーが描画した明示的なトポロジー上のエッジを保持したまま、フラットな中間表現 (IR) グラフを確定します。次に、アタッチされた Features とその
valuesペイロードをノード ID でマップされたフラットな辞書に正規化し、機能に依存しないグラフを検証に備えます。- IR ペイロードの正規化: IR の構造的な形は、設定について Single Source of Truth を強制します。トポロジー層はグラフ構造(ノードのアイデンティティ、エッジ、メタデータラベル)のみを保持し、正規化された設定状態は、コンパイラが後続のプラグインに渡す別のメモリ内辞書に置かれます。設定を変更するミューテーターは、それを 1 か所で変更します。provider は、冗長な保存による乖離のおそれなしに正規化された状態を読み取ります。
静的解析 — Static Analyzer と Validation Gate
- メカニズム: トポロジー純粋性チェック + ガバナンスソケットの
ir-verdictロール。 - Action: コンパイラは IR グラフに対して抽象的な静的解析を実行します。まず、
usesSchema定義からselector文字列を抽出し、ネイティブな Go のラベルマッチングエンジン(Kubernetes 形式のAND、in()によるOR、!=によるNOTのセマンティクスをサポート)を使って、明示的に定義されたグラフのエッジ全体でそれらを評価し、宣言されたソケットに対するノード間の型安全性を保証します。アドホックなソケット(Aggregate の作成者が名前を付け、カタログが宣言していないソケット)上のエッジにはカタログエントリがなく、したがってセレクタもないため、このチェックで評価するものはなく、欠けているものもありません。各エッジは自身が 2 つのどちらであるかを記録し、アドホックなエッジが運べるものは、代わりにターゲットが宣言したprovidesによって制限されます。また、Feature のappliesToおよびappliesToAnyOfセレクタを評価して、アタッチされた feature がターゲットの component のラベルと互換性があることを検証し、埋められた各アタッチメントスロット自身のselectorを、そのスロットを埋める Feature のラベルに対して評価します。次に、ノードの Component が宣言するすべての存在義務(各features.aggrega.ai/requiredType.<label>アノテーション)を、そのノードの最終的なアタッチメントセットに対して評価します。このチェックがアナライザに置かれるのは、ルールの両方の要素、すなわち解決済みの Component エンティティのアノテーションと、5 層カスケードが生成したアタッチメントセット(Aggregate でアタッチされたもの、subsystem でアタッチされたもの、Release でアタッチされたもの、アノテーション展開されたものを等しく数えます)の両方を保持する最初のステージだからです。どのアタッチメントも満たさない義務はビルドを停止させます。宣言の形式が不正な義務は別の診断で停止するため、壊れた宣言が満たされた要件として扱われることはありません。第三に、Validation Gate を実行し、完全なグラフ構造(すべてのノード、エッジ、アタッチされた feature、事前計算された DFS パスを含む)をir-verdictロールにアタッチされたガバナンスプラグインに渡します。企業独自の Wasm ポリシーがトポロジーを評価します。Wasm プラグインが失敗配列を返した場合(例:特定のプロキシ feature を経由せずにpublicノードからrestrictedノードへ連続するパスを検出した場合)、ビルドは停止します。
レンダリング
- Mechanism: レンダリング前のインターセプト(
injectMapping)、遅延バインディング(valuesMapping)、Wasm レンダリングソケット(pipeline)。 - Action: 最終的なアーティファクト生成フェーズは、固定された順序で実行される厳密な時間順のサブフェーズに分割され、これにより実行が決定論的に保たれます。
- Inject mapping(レンダリング前のインターセプト): Go コンパイラは、開発者の抽象的な
.context.injectコントラクトを解決します。次に、アタッチされたすべてのFeatureRecipesのinjectMappingGo テンプレートを、厳密な 5 層オニオンモデルの実行順序(Sub-Aggregate:モジュールの component 自身のアタッチメント、次にそのモジュールの subsystem が宣言するアタッチメントを外側から内側へ → Root Aggregate の component → Root Aggregate の subsystem → Release の boundary(外側から内側へ) → Release の component 固有)に従って実行します。コンパイラは、得られた辞書を Caller の.context.injectメモリパイプの上にネイティブにディープマージします。これにより、Base Recipe がそれらを参照する前に、Caller の環境変数と接続文字列が安全に書き換えられます。マッピングは、Caller 自身のinject:ブロックまたはその接続の 1 つが渡したものを書き換えることができます。別のアタッチされた Feature が(自身のマッピングまたは自身のinject:ブロックを通じて)すでに渡したキーについては、両方のアタッチメントを示してビルドが停止するため、実行順序が 2 つのアタッチメントの値のどちらを採るかを決めることはありません。 - Locals プリアンブル:
providesテンプレートが実行される前に、コンパイラは Recipe の.localsエントリを記述された順に評価します。各エントリは、自己完結したノードローカルなコンテキスト(.context.instance_id、.values、.infra、および同じブロック内でそれまでに解決されたエントリ。ただし.context.injectや.context.usesは含みません)に対して評価されます。したがって、エントリは自身より上で定義された兄弟エントリを読み取ることができ、その兄弟の解決済みの値を受け取ります。あるエントリが別のエントリを読み取る箇所では、記述順序はコントラクトの一部であり、参照を解決させるためにブロックが並べ替えられることはありません。locals を先に解決することで、providesテンプレートが.localsを読み取れるようになります。Recipe の.sourceテンプレートは、それらの locals が解決された後に同じコンテキストに対して評価されます。これにより、.localsを Recipe のテンプレート全体で再利用可能な省略記法として保ち、作成者は boundary ごとに.source(チャートのバージョン、パス、レジストリ)をパラメータ化できます。 - ベースレンダリング(base Recipe の
valuesMapping): コンパイラは Base Recipe のvaluesMappingテンプレートを評価します。テンプレートは.context.injectパイプ(inject mapping の間に書き換えられたもの)からインターセプトされた文字列を読み取り、得られた値の辞書は Recipe のcapabilityが指定する provider に渡され(helm および helm-chart の provider はどちらも Helm を通じてレンダリングします)、ベースのインフラストラクチャアーティファクトがレンダリングされます。 - Workload のパースと検証:
workload:を宣言する Recipe(インラインのブロック内容、またはファイルを指定するworkload: { $import: <path> })では、そのドキュメントがノードのレンダーコンテキストに対してテンプレートとして評価され、次に YAML として Workload の形にパースされてチェックされます。レンダリングされたバイト列が Workload スキーマに対して検証され、デコードされた値も同様に検証されます(バイト列にはデコードで破棄されるキーが含まれ、デコードでは空で指定されたフィールドが省かれるため、それぞれがもう一方では見えないものを拒否します)。すべてのattachmentsエントリは、バインドされた Component のfeaturesSchemaが宣言するスロットに対してチェックされ、すべてのリソース参照は、それが指すスロットの解決済みprovidesに対してチェックされます。ここで失敗するとビルドは停止します。パースされた Workload はテンプレートコンテキストに.workloadとして配置されるため、同じノードで後から評価されるテンプレートがそれを読み取ることができます。 - Artifacts の評価: Recipe が
artifacts:の下に宣言するすべてのエントリ(インラインの内容、またはそのエントリ自身の$import:が指定するファイル)は、読み込まれ、テンプレートとしてパースされ、完全なテンプレートコンテキストに対して評価され、ビルドの来歴を持ちます。得られたプロジェクションは provider に渡され、provider が出力形式、来歴の配置先、出力パス、最終的なバイト列を決定します。出力される各ファイルは、どの記述形式から生成されたかを記録するため、ファイル名の衝突時にはすべての寄与元を示すことができます。 - Workload の合成: パースされた Workload は Recipe の
capabilityが指定する provider に渡され、provider はそれを自身のネイティブなリソースに変換します。workload:を宣言しない Recipe には、ここで合成するものはありません。そのファイルは代わりにソースのレンダリングから生成されます。 - Feature レンダリング(FeatureRecipe によるリソース生成): ノード上のアタッチメントのうち、バインドされた FeatureRecipe が独自の
source、workload、artifacts、valuesMappingのいずれか(または複数)を持つもの(ServiceMonitor、NetworkPolicy、サイドカー ConfigMap、認証情報配布用リソースなどの補助マニフェストに使われるリソース生成パターン)は、inject mapping と同じ 5-Tier Onion Model の順序で、1 回のパスで評価されます。1 つのアタッチメント集合に対して 1 つのシーケンスがあるだけです。運用系の Feature と認証情報の Feature は同じ経路をたどり、両者の違いはそれぞれの FeatureRecipe が何を出力するかにあります。各アタッチメントの.valuesと.infraはそのアタッチメント自身のスコープに切り替えられます。アタッチメントはベース Recipe の評価済み.localsを継承し、.attachment_nameはレンダリング中のインスタンスを指し、.providesにはアタッチメント自身の解決済み provides(コンシューマーが読むものと同じバッグ)が入ります。生成された値の辞書は FeatureRecipe 自身の capability が指定するプロバイダーに渡され、レンダリングされたファイルは 2 つの座標(Feature がアタッチされているコンポーネント、次にアタッチ時の名前)を持ってバウンダリの出力に追加されます。これにより、複数のコンポーネントにアタッチされた同じ Feature 名もそれぞれ区別されます。座標の形式はホストプロバイダー自身のレイアウトに従います。ターゲットが各コントリビューターに固有の位置を与える場合はコンポーネント自身のディレクトリの隣に<component>--<instance>/ディレクトリを置き、ディレクトリ直下のファイルしか読まない場合は<component>--<instance>--というファイル名プレフィックスを付けます。inject のみの FeatureRecipes(injectMappingだけを持ち、inject mapping の段階で処理済みのもの)はここではスキップされます。それ以前のサブフェーズと同様に、Feature レンダリングは一度に 1 つのコンポーネントについて実行されるため、アタッチメントは通常、アタッチ先のコンポーネントの直後に評価されます。FeatureRecipe がreadsCallerRenderFacts: trueまたはreadsTargetRenderFacts: trueを宣言しているアタッチメントは、代わりにすべてのコンポーネントと、どちらも宣言していないすべてのアタッチメントのレンダリングが終わった後に評価されます。そのため、その時点でホストに接続する各コンポーネントと、ホストの接続先の各コンポーネントはレンダリング済みです。その出力は、本来配置されるはずだった場所に配置されます。 - プラグインパイプライン(Wasm ステップの実行): コンパイラは Recipe の
pipeline配列を読み込み、宣言された順序でステップを実行します。各ステップで指定された Wasm プラグインをノードのレンダリング済みドキュメントに対してディスパッチし、ステップが返す RFC 6902 JSON Patch 操作をその操作の対象ドキュメントに適用し、ステップの副作用をそれらと並べて出力します。これは、Envoy サイドカーの注入やシークレットの VolumeMount のマウントといった精密な変更を支える仕組みです。when:ゲートが偽としてレンダリングされたステップはパススルーとしてスキップされ、ドキュメント集合は変更されないまま次のステップに渡されます。各ステップのpluginURI は、実行前に、ロックファイルがダイジェストで固定している検証済みアーティファクトのバイト列に解決されます。FeatureRecipe のpipelineステップも同じ方法で、アタッチメント自身のレンダリング済みドキュメントに対して実行されます。コンポーネントスコープのアタッチメントの場合は、ホストコンポーネントのドキュメントも併せて対象になります。
- Inject mapping(レンダリング前のインターセプト): Go コンパイラは、開発者の抽象的な
3 種類の Recipe 入力はいずれもコンパイラに届きます。source: + valuesMapping: はベースレンダリングを通じて、workload: は Workload の解析と Workload の合成を通じて、artifacts: は artifacts の評価を通じて処理されます。あるプロバイダーにどの入力を渡せるかは、サブステージごとに決まるのではなく、レンダリングのディスパッチより前にノードごとに 1 回、プロバイダー自身が宣言した契約に基づいて確定します。そのため、バインドされたプロバイダーが受け付けない入力種別を持つ Recipe は、レンダリングの途中ではなくその時点で拒否されます。3 種類の入力の合成モデル、Workload 種別、Artifacts の仕組みについては 16-recipe-input-composition.md を、どのプロバイダーがどの種別を受け付けるかについては 言語のステータス を参照してください。
GitOps ネイティブな出力
出力がどのように適用されるかについて厳密に主張を持たないままでいるために、レンダリングプラグインは生成したアーティファクトを、バウンダリごとに分離された整然としたディレクトリ構造(例: dist/boundaries/aws-core-cluster/、dist/boundaries/gcp-data-cluster/)に出力します。これにより、外部の GitOps コントローラー(ArgoCD や Flux など)がインフラストラクチャを同期・適用でき、Aggrega コンパイラがライブクラスターの API 認証情報を必要とすることはありません。
graph TD
subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
direction TB
A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
end
graph LR
E["Rendering"]
E -->|"Stringified Artifacts"| F["Helm Charts"]
E -->|"Stringified Artifacts"| G["Docker Compose"]
E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
E -->|"Stringified Artifacts"| I["Terraform Configuration"]
E -->|"Stringified Artifacts"| J["CloudFormation Templates"]
インフラストラクチャのソースマップ
Aggrega は約 30 行の Aggregate.yaml を、数千行に及ぶ物理的な JSON または YAML の設定にコンパイルします。実行中のリソースからそのソースをたどる手段がなければ、「main.tf.json の 4,032 行目」での障害をデバッグする際に、開発者は対応関係を手作業で再構築しなければなりません。Aggrega のレンダリングプラグインは、トレース識別子をプロバイダーのネイティブなメタデータ面(Kubernetes では metadata.labels と metadata.annotations、Terraform では来歴コメント、その他プロバイダーごとの同等の慣例)にマージすることでこれに対処し、レンダリングされた各オブジェクトが生成元のソースへのポインターを持つようにします。aggrega.ai/compiler-version ラベル(governance-and-compliance §5 に記載)はこの系列のトレースキーの一つです。スタンプにはこれと並んで aggrega.ai/aggregate-name、aggrega.ai/component-id、aggrega.ai/boundary-path、aggrega.ai/recipe-uri、aggrega.ai/environment が含まれ、helm、helm-chart、compose、terraform、cloudformation の各プロバイダーがこれを出力します。helm-chart プロバイダーは chart 自身のテンプレートを変更せずにコピーするため、Recipe が chart に追加するテンプレートファイルに出力します。
スタンプには、フィーチャーの由来やカタログの型を識別するキーは含まれません。
コンパイラには、さらに 2 つのデバッグ手段が同梱されています。aggrega build --trace は、各ノードの中間状態をパスごとに .trace/(dist/ の隣)に書き出し、Recipe の作成者が各ステージが何を受け取り何を生成したかを調べられるようにします。また、停止を伴う診断は、障害に所属するオーサリング面がある場合はそのカテゴリ(DEVELOPER_ERROR、OPS_ERROR、CATALOG_ERROR など)を持つため、適切な作成者を指し示します。失敗した生成マニフェストのフィールドを、それを生成したテンプレートの行までたどるエラーは、コンパイラには含まれません。
バリデータパイプライン
解決処理のスキーマ検証フェーズは、バリデータパイプラインに基づいています。このパイプラインは、エンティティ仕様の内容(コンパクト形式、JSON Schema YAML、またはその混在)を、リーフごとの来歴を持つ単一の JSON Schema 2020-12 ドキュメントに変換し、開発者が記述したインスタンスの内容をそのドキュメントに対して検証します。5 つのステージが純粋な変換として順に実行され、各ステージは宣言された入力に対する決定的な関数です。
ステージ 1 — コンパクト形式のコンパイル。 コンパイラは schema:、parameters:、および SchemaLibrary の内容の YAML ツリーを走査し、ノードごとに処理を振り分け(コンパクト形式のリーフ、JSON Schema YAML、$ref: 参照、合成のいずれか)、解決済みの JSON Schema 2020-12 を出力します。コンパクト形式と JSON Schema YAML は、$jsonschema: エスケープを介して任意のノード境界で混在できます。コンパイラはツリーを走査してノードごとに振り分けることで、混在のケースを処理します。この変換は純粋関数であり、同じコンパクト形式の入力からは常に同じ JSON Schema が出力されます。キーワードの語彙については language-reference/vocabulary/compact-form-authoring.md を参照してください。
ステージ 2 — spec.templates と $instantiate: の解決。 テンプレート参照として記述された SchemaLibrary のエントリについて、コンパイラは $args: を伴って $instantiate: を呼び出すすべてのライブラリエントリを走査し、パラメータ値をリテラルのスカラー置換として代入して、具体的なスキーマエントリを生成します。この代入はライブラリの読み込みごとに 1 回実行され、解決済みのエントリはキャッシュされます。ライブラリエンティティの記述形式については language-reference/entities/schemalibrary.md を参照してください。
ステージ 3 — ドキュメント間の $ref: 展開。 $ref: による SchemaLibrary 参照(識別子形式 <Library>#/schemas/<entry>)について、コンパイラはコンパイル時に解決スタックを引き回しながら参照チェーンを走査し、参照先の内容を利用側のスキーマにインライン展開します。この展開では、循環検出(循環はチェーンを示すエラーでビルドを停止します)、場所ではなく識別子によるガードレール(レジストリホストを含む参照は識別子形式への誘導とともに停止します。参照はライブラリを物理的な場所ではなく識別子で指定します)、および単一ソースの合成($ref: ブロックは参照単体のみを受け付け、利用側でのオーバーライドは JSON Schema の allOf: で合成します)が維持されます。解決のセマンティクスについては language-reference/vocabulary/cross-document-ref.md を参照してください。
ステージ 4 — featuresSchema: のブリッジ合成。 コンパイラは各エンティティの featuresSchema: の内容を記述順に走査し、各アタッチメントスロットにバインドできる値の形状を記述する JSON Schema フラグメントを出力します。inject 許可リストを宣言するスロットには、拡張キーワード x-aggrega-inject: が付きます。このフラグメントは、開発者向けの schema: の内容に組み込まれるのではなく、単独でコンパイルされ、記述されたアタッチメントブロックに対してチェックされます。拡張キーワードは JSON Schema の検証では無視されるメタデータであり、後続のステージがフラグメントからこれを読み戻すことはありません。スロットの許可リストを必要とするチェックはスロット自体を読みます。usesSchema: のソケットテーブルは、どのフラグメントにも射影されません。ソケットの selector: と inject: は Architect が記述した型付き YAML としてそのまま読まれ、ソケットのエッジごとの valueSchema: / infraSchema: は単独でコンパイルされます。この合成は入力に対する純粋関数です。
ステージ 5 — 来歴付きのカスタムマージャー。 extends: を宣言するエンティティについて、コンパイラは親チェーンを走査します。親の解決済み JSON Schema がベースとなり、その上に子のオーバーライドが適用されます。解決済みスキーマのすべてのリーフは、リーフごとの来歴タグ(ファイルパス、行番号、親由来か子由来か)を持ちます。マージャーの出力はバリデータエンジンが取り込むものです。バリデータエンジンは改変されていないサードパーティの JSON Schema 2020-12 準拠実装であり、検出結果を順序どおりに出力するための決定的なウォーカーで包まれています。
5 つのステージは、バリデータエンジンがスキーマを参照する前に実行されます。エンジンは単一の解決済み JSON Schema 2020-12 ドキュメントと開発者のインスタンス内容を受け取り、検証レポートを生成します。エラーフォーマッタは来歴タグを参照し、ソース上の位置を明確に示すユーザー向けの診断を出力します。これには、Feature が自身で記述したのではなくベースから継承した制約について、その由来となるファイルも含まれます。
バリデーターパイプラインは、各ペイロードが初めて完全になる地点で実行されます。解決中のコンポーネントの values と infra、トポロジー構築がサブアグリゲートを取り込む際のそのコンポーネント、そしてグラフ確定時のアタッチメントのペイロードです。そのため、スキーマの検出結果は、静的解析がセレクターを評価する前、そしてアサーションの評価の前にビルドを停止し、アサーションのテンプレートは検証済みのペイロードに依拠できます。
パイプライン全体での決定性の維持
コンパイルパイプラインのすべての段階は、Deterministic Output Invariant(決定的出力の不変条件)を維持します。同じソースファイル、同じロックファイル、同じコンパイラバージョンが与えられれば、ビルドはバイト単位で同一の出力を生成します。この不変条件は基盤となるものです。ロックファイルにおけるコンテンツアドレッシングには安定したアーティファクトダイジェストが必要であり、再現可能なビルドには、開発者 A のラップトップで作成された release が開発者 B のラップトップや CI でも同じ出力にコンパイルされることが必要であり、差分レビューのしやすさには、ソースの変更がコンパイル出力における唯一の変更として現れることが必要です。
決定性は、すべての変換が守る少数の規律によって維持されます。
- 固定された反復順序。 Go のネイティブなマップ反復はランダム化されているため、マップ形式の YAML に対するすべての走査は固定された順序で反復します。コンパイラはほとんどの段階(compact form コンパイラ、マージャー、
spec.templatesリゾルバ、エラーフォーマッタ、YAML シリアライザ)で反復の前にソートします。一方、アタッチメントスロットの射影は作成者自身の順序をそのまま引き継ぐため、スロットテーブルのプロパティ順序は記述された順序になります。 - 時刻を埋め込まない。 コンパイルは出力にタイムスタンプを埋め込みません。午後 2:00 のビルドは、午前 2:00 のビルドと同じアーティファクトを生成します。マージャーの来歴メタデータは file:timestamp ではなく file:line を使用します。
- ワークスペース相対パス。 解決済み出力内のすべてのパスはワークスペース相対です。パス解決レイヤーは、パスがいずれかの出力に入る前に正規化します。
- ランダムなソースも外部状態も使わない。 変換は、宣言された入力(エンティティの内容、親チェーン、ロックファイル)に対する純粋関数です。外部状態は解決時(OCI アーティファクトの取得)にのみ参照され、解決された内容はダイジェストによってコンテンツアドレスされます。
- 正規の YAML シリアライズ。 出力は、同じ入力に対して 1 つの固定された形で書き出されます。すべての深さで毎回同じキー順序を使い、配列と
enum:配列は入力順序を保ちます。インデントは 2 スペース、改行は Unix LF、YAML が許す箇所では引用符なしの文字列、ブール値はtrue/false形式、存在しないフィールドの null は省略されます。 $defs:のアルファベット順。 スキーマの$defs:エントリは、解決済み JSON Schema においてアルファベット順のキー順序で出力されます。$defs:は概念的には順序付きリストではなく辞書であり、アルファベット順にすることでソースの再編成をまたいで差分が予測可能になります。- 並列性は出力に現れない。 コンパイラは独立した単位を並列化できます(異なるエンティティを並行してコンパイルできます)。並列の結果は、シリアライズされる前に決定的な構造(例:エンティティ名でソート)に集約されます。
コンパイラのエンドツーエンドテストは、1 つのテストの中で各フィクスチャを複数回コンパイルし、すべての実行が同じファイルをバイト単位で同一の内容で出力することを検証します。コンパイルを繰り返すことで、マップの反復順序の漏れやソートされていない集合に対する反復を捕捉できます。これらは大半の実行では安定した出力を生みますが、ときおり食い違います。これらのテストはコンパイラの他のテストスイートとともに実行されます。
Deterministic Output Invariant は ビルド時 に適用されます。同じソースファイル + 同じロックファイル + 同じコンパイラバージョンが与えられれば、出力はバイト単位で同一です。ロック時 の対応する性質(同じソースファイル + 同じレジストリ状態が与えられれば、同じロックファイル)はより弱いものです。レジストリは変更可能であり(新しいバージョンが公開されることがあり、サイドカーが追加されることがあり、コンポーネントごとのメタデータが変化することがあります)、そのため同じソースファイルに対する 2 回のロック実行が、異なる時点では異なるロックファイルを生成することがあります。それこそがロックファイルの目的であり、npm、Cargo、Go の慣例に倣っています。新しいロックファイルからは、ビルドは決定的な出力を生成します。この 2 つの時点の分離により、レジストリ側の変更可能性が許容できるものになります。時刻 T2 に公開されたサイドカーは次のロック実行を変えますが、T1 に生成されたロックファイルに対するビルドは変えません。