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

コンパイルパイプライン(概要)

この章では、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 を参照してください。

トポロジー構築 — 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 の injectMapping Go テンプレートを、厳密な 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: ゲートが偽としてレンダリングされたステップはパススルーとしてスキップされ、ドキュメント集合は変更されないまま次のステップに渡されます。各ステップの plugin URI は、実行前に、ロックファイルがダイジェストで固定している検証済みアーティファクトのバイト列に解決されます。FeatureRecipe の pipeline ステップも同じ方法で、アタッチメント自身のレンダリング済みドキュメントに対して実行されます。コンポーネントスコープのアタッチメントの場合は、ホストコンポーネントのドキュメントも併せて対象になります。

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 に生成されたロックファイルに対するビルドは変えません。