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

Wasm プラグインコントラクト

Aggrega のコンパイルパイプラインには、WebAssembly (Wasm) プラグインがコンパイラの動作を拡張するための指定されたソケットポイントがあります。ガバナンスソケットの 4 つのロール(その中にはトポロジー構築時の Mutation Gate と静的解析時の Validation Gate があります)、FeatureRecipe と Recipe のステップのためのレンダリング後プラグインパイプライン、プロバイダーレンダリングソケット、パーサーソケット、インポーターソケット、そして帯域外のリンティングソケットです。このページでは、公開されている Wasm プラグインコントラクトについて説明します。どのソケットが存在するか、各ソケットが何を受け取り何を生成するか、各ソケットがコンパイルパイプラインのどこに位置するか、そしてすべてのプラグインが実行されるサンドボックスについてです。

このページではソケット、つまりパイプライン上のポイントとその入出力の形を扱います。プラグイン、つまり Plugin エンティティ、エクスポートごとのケイパビリティ宣言、ランタイム制限、publish→pull→build のライフサイクルについては、Wasm プラグイン開発者ガイドを参照してください。

Aggrega は Wasm ホストランタイム(Wazero エンジン上の Extism)を組み込んでおり、AOT 純粋性ファイアウォールの背後でプラグインをロードし実行します。ホストはゲストにアンビエント権限を一切与えません。ネットワークなし、ファイルシステムなし、環境変数なし、stdio は破棄され、観測可能な壁時計はビルド不変の時刻に固定されます。そのため、プラグインがコンパイラの事前(ahead-of-time)保証を破ることはできません。権限サーフェス全体(ロード時のインポートモジュール規則、インスタンス化時の拒否、厳選されたホスト関数)は、後述のサンドボックス契約にまとめています。Plugin の作成者は、3 言語の PDK(Go、Rust、TypeScript)を通じてホストを対象にします。aggrega lint は、linter ソケット(標準の publishing-linter)をホストを通じてディスパッチします。aggrega build は、ワークスペースが設定している場合にガバナンスソケットのビルド時ロールをディスパッチします。解決中の annotation-transform ロールとトポロジー構築時の label-transform ロール(いずれも出力を整形します)、さらに静的解析時の IR 判定と、レンダリングされた成果物に対するレンダー判定です。いずれも、そのロールにプラグインが接続されていなければ何もしないため、ガバナンス設定のないビルドは変わりません。aggrega build はまた、レンダリングを締めくくるプラグインパイプラインで FeatureRecipe と Recipe の pipeline: をディスパッチします。宣言された各ステップは、レンダリングされたドキュメントセットに対してホストを通じて実行され、そのステップの RFC 6902 パッチを適用し、副作用を出力します。言語のステータス → コンパイルパイプラインのフェーズを参照してください。

サンドボックス契約

すべてのソケットは、同じホストサンドボックスを通じてプラグインをディスパッチします。サンドボックスには 2 つの独立した層、すなわちロード時の構造チェックとインスタンス化時のケイパビリティ拒否があり、両者を合わせて、プラグインが到達できるもの、到達できないもの、そしてプラグインが責任を負うものが定義されます。

インポートモジュール規則(ロード時)。 ローダーはプラグインバイナリのインポートセクションを走査し、関数インポートを 3 つのモジュール名前空間の下でのみ許可します。wasi_snapshot_preview1(ゲスト言語ランタイムがリンクする WASI preview-1 ランタイム)、extism:host/env(Extism ランタイム ABI、つまり PDK 自身のメモリおよび IO 組み込み関数)、そして extism:host/user(Aggrega が厳選したホスト関数)です。ゲストは許可されたモジュールの下で任意の関数名をインポートできます。それ以外のモジュールの下のインポートはホストが提供しないサーフェスを指すため、プラグインはロード時に、そのモジュールとインポートを示す診断とともに拒否されます。この規則は意図的に個々の WASI 関数名を検閲しません。静的リンクされた言語ランタイムは、実際に動作するコードパスが決して呼び出さないファイルシステム関数やソケット関数を、依存関係を通じて推移的にインポートしますが、インポートを名指しすること自体は何も付与しないためです。I/O が発生しないことを保証するのは、インポートの検閲ではなく、インスタンス化時のケイパビリティ拒否です。

アンビエントケイパビリティゼロ(インスタンス化)。 ホストは、実際の WASI の動作とアンビエント権限ゼロでゲストをインスタンス化します。

  • ファイルシステムなし — 事前オープンされたディレクトリがないため、ファイルシステム呼び出しは呼び出し境界で失敗します。
  • ネットワークソケットなし。
  • 空の環境。
  • 破棄される stdio — ゲストが stdout や stderr に書き込んだものは、ホストのストリームに届きません。
  • ビルド不変の時点に固定された、凍結された観測可能なウォールクロック。これにより、時刻を読み取るゲストがビルド時刻を出力に漏らすことはありません。
  • 実際に進行する単調クロック — ゲスト言語ランタイムは起動にこれを必要とし、単調時間はウォールクロックの時点ではなく経過時間を測定します。
  • 実際のホストエントロピー — エントロピーを固定すると、言語ランタイムの内部ハッシュシードが安定し、ゲストの非決定性が異なる出力として表面化せずに隠されてしまいます。
  • argv としての単一の合成プログラム名。

ゲストが実際に行う I/O 呼び出し(ファイルを開く、ソケットに接続するなど)は、呼び出し境界で失敗します。これは WASI 自体のケイパビリティベースのセキュリティモデルであり、サンドボックスはコードを取り締まるのではなく、ケイパビリティを拒否します。

入力はペイロードと厳選されたホスト関数を通じてのみ届きます。 プラグインは、レンダリングまたは評価するものすべてを、そのソケットが運ぶペイロード(グラフとノードのプロジェクション、値、レンダーコンテキスト)で受け取ります。ペイロードがどのエンコーディングで届くかはソケットごとに固定されており、以下の各ソケットのセクションで示されます。公開されている各ペイロード型には、そのソケットのエンコーディング用のエンコードとデコードのエントリポイントが付属しているため、ゲストはパーサーを選ぶのではなく 1 つの関数を呼び出します。ソース付きの provider レンダーでは、ペイロードはソースバイトではなくソースリスティングを運びます。これはノードのソースルート下にある {path, is_dir} エントリのソート済みセットであり、ホストによる provider レイアウトの解釈は含まれません。ゲストは独自のレイアウトロジック(単一の compose ファイルを選択する、チャートルートまで降りる、Chart.yaml を要求する、モジュールを再帰的にベンダリングする)を適用し、選択したスライスだけをホストコールバックを通じて読み戻します。ペイロード以外に、ホストは厳選された最小権限のホスト関数セットをバインドし、プラグインのバイナリがインポートするものだけをそのプラグインに付与します。

  • aggrega_log — ホストのログ出力先へのログ行。
  • aggrega_emit_warning — 呼び出し後にホストが表示する構造化された警告。
  • aggrega_fetch_external_input — 外部入力取得チャネル(後述)。
  • aggrega_pack_source — ソース選択コールバック。ゲストがソースルート下の {file | dir | tree, path} 選択を指定すると、ホストはパスをルート下で解決し .. を拒否するサンドボックスのもとで、まさにその選択を読み取ってパックします。
  • aggrega_read_source_file — 内容に依存したソース選択のための、同じサンドボックス下での単一ファイルの内容読み取り。
  • aggrega_parse_source — プロデューサー消費コールバック。ゲストが構文フォーマットを指定してソースバイトを渡すと、ホストはそのフォーマットのパーサーを解決して実行し、生成された正規ツリーを返します。これは、コンシューマーがプロデューサーのゲストを自ら呼び出すのではなく、ホストを通じてプロデューサーの出力を得る方法です。ホストはこれを 1 段階に制限しており、この方法で到達したプロデューサーが再度呼び出すと拒否されます。そのため、コンシューマーはソースごとに 1 回呼び出し、複数のソースを順に消費できます。

ホストは、プラグインがインポートするセットをその .wasm バイナリから導出し、厳選された許可リストに照らして検証し、ゲストの describe() が宣言するホスト関数と照合します。aggrega plugin sync はそのセットをエンティティの spec.runtime.hostFunctions に記録し、公開時には記録がバイナリと異なるエンティティが拒否されます。これにより、すべてのプラグインのホストサーフェスがカタログ上で可視化され、バイナリとずれることはありません。

コールバックの失敗は、hostfunc_error_code の下に機械照合可能なコードを伴います。 応答を返すホストコールバック(aggrega_fetch_external_input、aggrega_pack_source、aggrega_read_source_file、およびプロデューサー消費コールバック aggrega_parse_source)は、失敗をインバンドで伝えます。応答エンベロープは人が読めるメッセージと、その横に閉じた語彙から取られる任意の機械照合可能なコードを hostfunc_error_code の下に持ちます。メッセージは人向けの自由形式の文章であり、コードはゲストがメッセージを解析せずに分岐に使う安定した識別子です。成功時にはコードは存在せず、失敗時にはホストが両方を設定します。PDK はこの組を型付きエラーとして提供し、そのテキストはメッセージ、コードフィールドはゲストが言語ごとに再エクスポートされたコード定数と照合するものです。ゲストは、コードがない場合や認識できないコードの場合にはメッセージにフォールバックします。したがって、コードによる照合は常に存在するメッセージの上に重ねたベストエフォートの絞り込みであり、メッセージの代わりには決してなりません。閉じた値の集合は ホスト関数エラーコードスキーマ です。

🔴 この境界では 2 つの異なる語彙が失敗を指し、読み取るキーによってどちらを扱っているかがわかります。 両者の混同は、ここで特に指摘しておくべき唯一の誤りです。どちらの値も単なる文字列であり、ホストもゲストもそれがどちらの集合から来たかを確認しないためです。

  • hostfunc_error_code は、ホストがゲストに送る応答に含まれます。 その値は上でリンクした閉じたカタログのメンバーであり、ホストコールバックが失敗しうる仕方を示す、固定的でゆっくりとしか変わらないリストです。集合が閉じているため、ゲストは値をキットが再エクスポートする名前付き定数と照合し、その結果で分岐できます。
  • condition_code と condition_short_code は、ゲストがホストに返すソケット出力に含まれます。 これらはゲスト自身が発生させた停止条件の 2 つの識別子であり、カタログからではなく、コンパイラが登録する開いた、拡大し続ける条件の集合から取られます。condition_code は条件が登録されている説明的なコードであり、condition_short_code はその短縮形(文字 E と 4 桁の数字)で、読者が引用し、検索し、レポートに貼り付けるものです。ホストは、レンダリングする診断の角括弧付きの先頭部分に短縮コードを出力するため、ゲストが発生させた条件もコンパイラが発生させた条件とまったく同じように引用できます。ホストはどちらの値も導出しませんが、確認は行います。このコンパイラが宣言するどの条件にも解決されない短縮コードや、番号が廃止された条件に解決される短縮コードは、何にも解決されない識別子として読者に届く代わりに、ビルドを停止させます。

ゲスト側の 2 つの識別子は一緒に報告されます。一方だけを設定したゲストは、ホストが解決できない条件を指定したことになり、その場合ホストは代わりに自身の汎用的なプラグイン失敗条件を報告します。このとき、メッセージには引き続き失敗の全容が含まれます。また、condition_code がホスト関数のカタログのメンバーになることはないため、再エクスポートされた定数と比較しても一致することはありません。これが、各キーが失敗一般ではなく自身の語彙を名指す理由です。

各コールバックのスロットには定められたエンコーディングがあり、ペイロードドキュメントを保持するスロットはすべてそれをバイナリとして保持します。 ホストコールバックが受け取る引数は、aggrega_log の数値レベルを除き、すべてゲストメモリへのポインタです。応答を返すコールバックもポインタで応答します。それぞれのスロットが何を保持するかは、コールバックごとに固定されています。

コールバック引数スロット応答スロット
aggrega_log, aggrega_emit_warningUTF-8 テキスト — ペイロードドキュメントなし応答なし
aggrega_fetch_external_input裸の UTF-8 URL — ペイロードドキュメントなし正規 CBOR
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source正規 CBOR(RFC 8949 §4.2.1)正規 CBOR

この表は、コールバックの種類ではなく、各スロットが何を保持するかで分かれています。ペイロードドキュメントを保持するスロットは正規 CBOR を運び、裸の文字列(ログ行、診断フィールド、URL)を保持するスロットは UTF-8 テキストを運びます。2 つのスロットが異なるのは aggrega_fetch_external_input だけです。その引数は UTF-8 テキストとして読まれる裸の URL で、応答は正規 CBOR のペイロードドキュメントです。

ペイロードを運ぶスロットでゲストが行うこと、行ってはならないこと。 🔴 ペイロードドキュメントを保持するスロットは、UTF-8 テキストではなく不透明なバイト列を保持します。したがって、これはゲストがそこに置くバイトだけでなく、ゲストが宣言する形でもあります。そのようなリクエストを文字列として確保したり、そのような応答を文字列として読んだりするゲストは相互運用できません。どちらの方向でもテキスト変換はバイナリのバイトを破壊します。この失敗は部分的ではなく明白に現れます。ホストがデコードできないリクエストは、他のコールバック失敗と同じインバンドの形で、request_undecodable コードを持つ応答エンベロープとして返されるため、ゲストは半端に読んだペイロードで処理を続けるのではなく、それを報告します。ペイロード型は、aggrega_pack_source では SourcePackRequest と SourcePackResponse、aggrega_read_source_file では SourceFileRequest と SourceFileResponse、aggrega_parse_source では ParseInput と ParseSourceResponse で、aggrega_fetch_external_input では応答型 FetchExternalInputResponse のみです(その URL はテキストとして確保されます)。キットごとの具体例は次のとおりです。

  • Go — リクエスト型の EncodeCBOR() でリクエストを構築し、pdk.AllocateBytes(pdk.AllocateString ではなく)で確保し、応答ポインタが指すメモリに対して ReadBytes() で応答を読み、応答型の DecodeCBOR に渡します。リクエスト側ではフェッチ URL が例外で、pdk.AllocateString で確保します。その応答は他と同様に読みます。//go:wasmimport 宣言はどちらの場合もポインタなので、シグネチャには形が現れません。形が表れるのは確保と読み取りの箇所です。
  • Rust — #[host_fn] 宣言が形を直接示します。3 つのペイロードコールバックはそれぞれ fn <callback>(request: Vec<u8>) -> Vec<u8>; となり、フェッチコールバックは fn aggrega_fetch_external_input(url: String) -> Vec<u8>; となります。リクエスト型の encode_cbor() でリクエストを構築し、応答型の decode_cbor(&raw) で応答を読みます。
  • TypeScript — リクエスト型の encodeCBOR… 関数でリクエストを構築し、Memory.fromBuffer(Memory.fromString ではなく)で確保し、readBytes() で応答を読んで応答型の decodeCBOR… 関数に渡します。フェッチ URL は Memory.fromString で確保します。その応答は他と同様に readBytes() で読みます。Go と同じく、declare module のエントリはどちらの場合もポインタです。

PDK のラッパーを呼び出すゲストにはそのいずれも不要です。 ラッパー(各言語の表記で FetchExternalInput、PackSource、ReadSourceFile、ParseSource)は確保とエンコードを行い、そのシグネチャはいずれもワイヤ型を名指しません。そのため、キットを通じてこれらのコールバックに到達するゲストは自ら何も確保もデコードもしません。ホスト関数を自ら宣言して呼び出すゲストは、上述のとおりメモリを確保して読みます。テキストとして確保されたリクエストは半端に処理されるのではなく拒否され、テキストとして読まれた応答はデコードできないため、両側の食い違いは気付かれずに済むことはなく、はっきりと表に出ます。

頼りにしてよい性質が 2 つあります。応答は成功でも失敗でも同じエンコーディングを持ちます。ゲストは 1 つのスロットを読み、デコードする前にどちらを保持しているかを知ることはできないため、1 つのデコードエントリポイントで両方を読み、上述のエラーコードとメッセージもそれを通じて届きます。また、ゲストはバイト値のフィールドをキット自身のフィールド型で埋めます(Go ではバイトスライス、Rust と TypeScript では base64 文字列)。バイナリエンコーディングが運ぶ生のバイト列への変換は生成されたエンコーダの仕事で、送信時に行われ、受信時に逆変換されるからです。これには ParseInput のソースバイト、aggrega_read_source_file が返すファイル内容、aggrega_fetch_external_input がフェッチした内容、pack-source 応答の各パック済みファイルの内容が含まれます。これらのバイトは二重にエンコードされることなく一度だけ境界を越え、エンコーダがこれから base64 デコードするものをゲストが base64 エンコードすることはありません。read-source-file とフェッチの応答の content フィールドは空の場合に省略されるため、空ファイルや長さ 0 のフェッチペイロードに対する応答は内容をまったく持ちません。そのような応答も成功です。失敗には必ずメッセージとコードが含まれるからであり、各キットのラッパーはそれに対して空のバイトを返します。aggrega_parse_source が返すツリーは、自身の JSON ドキュメントをそのまま保持するバイト列として運ばれ、ホストはそれを読むことも形を変えることもありません。パーサーは自身の parse エクスポートで、同じエンコーディングの同じ ParseInput を読みます。パーサーソケットを参照してください。

正規とは、同一の入力がすべての側で同一のバイトを生成することを意味します。これにより、ペイロードを往復させるだけでなく 3 つのプラグインキット間で比較でき、ビルドの出力がバイト単位で同一に保たれます。ゲストに CBOR ライブラリは不要で、バイトを手作業で解析することもありません。公開される各ペイロード型は、そのスロットのエンコーディングが必要とするエンコードとデコードのエントリポイントを備えています。

決定性はプラグイン作成者の責任です。 ホストはゲストの出力バイトをそのまま消費し、シリアライザーを一切通さないため、すべてのプラグインが守るべき契約は「同一の入力は同一の出力バイトを生成する」ことです。サンドボックスは非決定性の環境的な発生源(壁時計時刻、環境変数、ファイルシステムの状態)を取り除きますが、それ以外は意図的に隠しません。エントロピーや経過したモノトニック時間を出力にエンコードするゲストは、安定して隠れた欠陥ではなく、実行ごとに目に見えて異なるバイトを生成します。

外部入力フェッチチャネル。 aggrega_fetch_external_input はリモートコンテンツのための唯一の公認チャネルであり、ゲストによるネットワークアクセスではなくホストが仲介します。ゲストが URL を指定し、ホストは外部入力のピン規律のもとでバイトを提供します。Release のロックファイルでピン留めされた URL は、ローカルのコンテンツアドレス指定ストアから提供され、記録されたダイジェストに対して検証されます。ピン留めされていない URL は、その URL とピン留めを行う手順を示す診断とともに拒否されます。レンダーはロックファイルが記録するクロージャを消費し、決してそれを広げないからです。ピンは Release の依存関係が解決されるときに書き込まれ、それが何かがピン留めされる唯一の時点です。作成手順とピン規律の全容は開発者ガイドにあります。

順序を保持するマップ

ペイロードが運ぶマップの一部は、ソケットのスキーマで順序保持としてマークされています。エントリの順序が、そのマップが運ぶ内容の一部だからです。ビルドのノード、ノードのラベル、ノード上のアタッチメント、パイプラインステップの入力と出力、provider が宣言するキー空間がこれに当たります。公開されたペイロード型は、こうしたマップをそれぞれ、エントリを設定された順序のまま保持するコンテナに格納します。

キットコンテナ
Goaggrega.OrderedMap[V] — ABI パッケージの abi.OrderedMap[V] に対するキットでの名前
Rustaggrega-abi クレートの OrderedMap<V>。キットが再エクスポートします
TypeScript言語自体の Map<string, V>

Go と Rust のコンテナはマップの操作を備えています。キーの検索、設定、削除、キーの読み取り、エントリの順序どおりの走査、件数の取得です。コンテナがすでに保持しているキーを設定すると、値が置き換わり、位置は維持されます。新しいキーは既存のすべてのキーの後ろに入ります。

順序は両方のエンコーディングで保持されます。 バイナリエンコーディングでは、マークされたマップはエントリの順序付きリストとして、コンテナの順序で書き出されます。各エントリはキー、次に値の 2 要素リストです。正規エンコーディングであれば、本来はキーをソートしたマップとして書き出すところです。テキストエンコーディングでは、メンバーをコンテナの順序で書き出した JSON オブジェクトになります。どちらのエンコーディングでも、デコーダはキーが重複するマップを拒否し、そのキーを示します。スキーマがマークしていないマップは、バイナリエンコーディングではソート済みのマップ形式のままであり、公開された型では言語の通常のマップ型になります。

ゲストにとっての帰結は 3 つあります。

  • 順序は出力の一部です。 マークされたマップは埋められた順序で書き出されるため、順序が固定されていないソース(たとえば Go の組み込みマップの反復)から埋めるゲストは、同一の入力に対して実行ごとに異なるバイト列を書き出します。固定された順序で埋めてください。
  • 順序が保持されるのは、マップがコンテナ内にある間だけです。 ペイロードを自身の言語の汎用値型に変換するゲストは、その型の順序を受け取ることになります。Go の map[string]any には順序がなく、Rust の serde_json::Value は、クレートを preserve_order フィーチャー付きでビルドしない限りオブジェクトのキーをソートしたまま保持します。
  • TypeScript では、生成された関数を通じて読み書きしてください。 マークされたマップを持つ型は JSON をメンバーごとにデコードするため、"8080" のように配列インデックスとして読めるキーも位置が保たれます。JSON.parse ではオブジェクトの先頭に移動してしまいます。また、そのエンコーダは各 Map をオブジェクトとして書き出しますが、JSON.stringify は Map を {} として書き出します。Map の Object.keys も空です。Map のキーは、それ自身の keys() で読み取ってください。

入力が機密とマークする値

プラグインは、返す拒否や警告の中で、入力が機密とマークする値を決して引用しません。キーによるマークであっても、ペイロード全体へのマークの一部であっても同様です。 拒否とは出力が持つ error のことであり、警告とは出力が持つ Diagnostic(重大度を問いません)、または aggrega_emit_warning を通じて発行されたものです。ホストはそのテキストを報告するあらゆる場所(コマンドライン、言語サーバーとエディターの問題一覧、アシスタントツール)で変更せずに伝え、そこから値を読み取ることはありません。そのため、値を除外できるのはプラグインだけです。代わりにキー、設定、または位置を示してください。読み手はそこから値を見つけられます。

この規則は、プラグイン自身が書くテキストと同様に、ライブラリがプラグインのために書くテキストにも適用されます。テンプレートエンジンは評価中だったデータを報告し、スキーマバリデーターは pattern に失敗した値を引用し、パーサーは読み取れなかったトークンを引用します。そうした失敗が入力のマークする値に対して発生した場合は、値を含めずに報告してください。たとえば、マークされたすべての値をプレースホルダーに置き換えて同じステップを再実行し、同じ箇所で失敗した場合はその実行の失敗を報告し、そうでない場合は失敗テキストを伏せた旨を伝えます。ペイロード全体がマークされている場合、そのペイロード内のすべての値はマークされた値ですが、キー(ドキュメントの形)は読み取り可能なままです。

入力がキーまたはペイロードを機密とマークする箇所(ワイヤー上の名前で表記):

ソケットとエクスポートマークが読み取られる場所
provider の render_node と validate_node_input(RenderNodeInput)node.sensitive_rendered_keys: 各キーは、値が Component 自身のもので、それが宣言するリーフをキーとしている場合の node.values のエントリ(Recipe の valuesMapping はどの宣言も名指ししないキーを書き込むため、ここではそのいずれもマークされません)、または機密と宣言されたスロットを読み取る、ワークロードコンテナの attachments マップのエントリを指します。node.sensitive_values は node.values 全体をマークします。valuesMapping(Recipe のもの、またはアタッチメントの FeatureRecipe のもの)がそれらの値を生成し、作成者が機密と宣言した値を読み取る場合に true になります。workload_projection.sensitive_workload は、ワークロードのテンプレートがそのような値を読み取る場合に、同じ方法でワークロードのすべての値をマークします。また artifacts_projection.entries の各エントリは、自身のコンテンツについて sensitive_content を持ち、そのコンテンツに関するパーサーのメッセージもこれに含まれます。omits の各エントリは、その kind、name、namespace のいずれかを生成するテンプレートがそのような値を読み取る場合に sensitive を持ち、その場合そのエントリのすべてのフィールドがマークされた値になります。node.features の各エントリは、自身のアタッチメントのマーキングを持ちます: sensitive_payload_leaves(その Feature が機密と宣言する values.<path> と infra.<path> のリーフ)、sensitive_inject(その Feature が機密と宣言する provides キーを読み取る inject 配信キー)、sensitive(アタッチメントがそもそも機密と宣言された素材を扱うかどうか)。
governance ir-verdict(PolicyInput)graph:各ノードの sensitive_payload_leaves、および各アタッチメントの sensitive_payload_leaves、sensitive_inject、sensitive。これらのマークが示す値はすべて、伏せ字マーカー {"aggrega_withheld": "declared"} としてすでに届くため、値そのものがプラグインに到達することはありません。

これ以外のソケット入力、および provider の他のエクスポートの入力は、マークを持ちません。キーのマークは宣言に完全に結び付けられるものだけを示すため、キーがないことは値を引用しても安全であることを意味しません。そのキーに結び付けられる宣言がなかったことを意味します。ペイロードのマークは、ペイロードを生成したテンプレートの参照(宣言された値に到達する参照、データ全体を引き渡すテンプレート、またはパースできないテンプレート)から読み取られ、値から読み取られることはありません。そのため、マークがないことは、参照から分かる限りそのテンプレートが宣言された値を読み取っていないこと、またはペイロードを生成したテンプレートがないことを意味します。ペイロードが機密を何も含まないという表明ではありません。

Wasm ソケットのパイプライン上の配置

コンパイルパイプラインは、以下のソケットポイントを予約しています。形状ラベルは Status ページの 4 ラベル分類に従います。

ソケットパイプライン上の配置現在のステータス
ガバナンスソケット、annotation-transform ロール解決(アノテーション展開の前)利用可能 — ワークスペースが annotation-transform プラグインをアタッチしたときにディスパッチされます。展開によって Feature アタッチメントに変換されるアノテーションを注入します
ガバナンスソケット、label-transform ロールトポロジー構築(Topology Builder)利用可能 — ワークスペースが label-transform プラグインをアタッチしたときにディスパッチされます。JSON Patch によってノードラベルを自動付与します
ガバナンスソケット、ir-verdict ロール静的解析(Static Analyzer、IR グラフに対して)利用可能 — ワークスペースが ir-verdict プラグインをアタッチしたときにディスパッチされます。halt の判定はビルドを停止します
ガバナンスソケット、render-verdict ロールレンダリング(レンダリング済みアーティファクトに対して)利用可能 — ワークスペースが render-verdict プラグインをアタッチしたときにディスパッチされます。halt の判定はビルドを停止します
FeatureRecipe と Recipe の pipeline: プラグインプラグインパイプライン(レンダリング後の変更)利用可能 — 宣言された各ステップがレンダリング済みドキュメントセットに対して実行され、RFC 6902 パッチを適用し、副作用を発生させます
Provider レンダリングプラグイン(helm、helm-chart、compose、terraform、cloudformation)ベースレンダリング(プロバイダー)利用可能 — すべてのプロバイダーは Wasm ゲストを通じてレンダリングします。レンダリングは Wasm のみで行われ、ホスト内レンダラーへのフォールバックはありません
パーサープラグイン(parse:<format>)レンダリング(render-verdict ポリシー向け)、および帯域外(インポート向け)利用可能 — render-verdict ポリシーがネイティブに読めないフォーマットのアーティファクトに対して、aggrega_parse_source を通じてインポーターのために、そしてフォーマットを指定しないインポートのフォーマットを認識するために呼び出されます
インポータープラグイン(import:<format>)帯域外(aggrega import)利用可能 — aggrega import、エディターセッション、アシスタント向けツールによってディスパッチされます
リンタープラグイン(linter/publishing)帯域外(aggrega lint)利用可能 — publishing-linter は同梱されており、aggrega lint によってホストを通じて実行されます

解決の一部であるアノテーション駆動の Feature 展開サブフェーズは、Wasm ソケットではなく、ネイティブの Go パイプラインパスです。このサブフェーズは、対象 Feature の spec.schema に対してアノテーション値を検証し、IR 構築時に合成された Feature アタッチメントを注入します。アノテーションとラベルを持つ 6 つのサーフェスについては vocabulary/labels-and-annotations.md を、バインディングの形状とオーサリングの解説については providers/well-known-annotations.md を参照してください。

出力形状の契約 — 現在存在するもの

governance ソケットは 4 つのロールのそれぞれで型付きの契約サーフェスを持ち、どのサーフェスになるかはロールによって決まります。Plugin の作成者は、ドキュメント化された形を生成するゲスト側のコードを実装します。ホストは、ワークスペースがそのロールにプラグインをアタッチしたときに、構成されたプラグインごとに 1 回、ビルド時にそれを読み取ります。以下のサブセクションは、パイプラインがそれらをディスパッチする順序に従います。

annotation-transform ロール — アノテーション注入の出力

パイプライン上の配置。 解決フェーズ。コンポーネントが解決された後、アノテーション駆動の Feature 展開が実行される前です。

入力形状(ホスト → ゲスト)。 次の内容を持つ AnnotationTransformInput ドキュメントです。

  • targets — 注入先です。ゲストがアノテーションを付与できる解決済みのコンポーネント(境界が直接指定するものと、境界の aggregates: の下のルーティングエントリがルーティングして取り込むすべてのコンポーネントで、エントリがそれを指定しているかどうかは問いません)で、それぞれが boundary_path、component_name(ルーティングされたコンポーネントの場合は、metrics.query のようなビルドグラフ内のドット区切りの ID)、および Release がそこに書いた annotations を持ちます。これにより、ゲストは作成者が記述した値を置き換えることなく、何を追加するかを判断できます。各アノテーションの値は書かれたとおりに届きます。文字列、サブキーのオブジェクト、またはコンポーネントが継承するはずのアノテーションをオプトアウトする場合は null です。コンポーネントが持つすべてのキーは、その値にかかわらず存在します。ホストによって決定的な順序で並べられます。
  • binding_keys — Manifest がバインディングを登録しているアノテーションキーで、作成者の記述順に並びます。登録済みのキーでの注入は Feature のアタッチメントへと展開されるため、ゲストはこのリストを読んで効果を持つキーを注入します。ホストは注入に登録済みのキーを指定することを要求しません。登録されていないキーで注入されたアノテーションは、作成者が記述したバインドされていないアノテーションとまったく同じように振る舞います。
  • sources — アタッチメントが with.sources に宣言した定義ファイルです。それぞれがベース名のパスと内容を持ち、パス順にソートされます。
  • settings — アタッチメントが with.settings に宣言した自由形式の設定オブジェクトで、そのままゲストに渡されます。

settings と sources は、他のすべてのロールが読むものと同じ、エンジンに依存しない with チャネルであり、アタッチメントが何も宣言しない場合はどちらも存在しません。このロールの出力はビルドを形作るため、アタッチメントの設定とソースの内容は pull 時にリリースのロックファイルに固定され、ビルド時にそこから再構築されます。

出力形状(ゲスト → ホスト)。 次の内容を持つ AnnotationTransformOutput ドキュメントです。

  • injections — 追加するアノテーションで、順序付きです。それぞれが既存のターゲット座標(boundary_path と component_name)と、annotation_key およびその annotation_value を指定します。値は文字列、またはサブキーのオブジェクトで、後者は複数のサブキーを一度にルーティングするバインディングに渡されます。

ホストが適用するのはアノテーションの追加のみで、自身が提供した座標に対してのみ、かつそれぞれ作成者がそのアノテーションに書けるような値に限られます。注入された値は、Release に書かれた同じ値を読むのとまったく同じように読まれます(オブジェクトのサブキーはゲストが書いた順序で読まれます)。そのため、展開はそれを作成者が書いたアノテーションと同じように扱います。ペイロードが持たない座標を指定する注入や、null、リスト、数値、真偽値、サブキーのないオブジェクトを持つ注入は、黙って破棄されたり適用されたりするのではなく、座標とアノテーションを示すメッセージとともにビルドを停止させます。出力のいずれかを適用する前に、出力全体が検査されます。この制限がロールの範囲を定めます。ここにプラグインをアタッチするオペレーターは、アノテーションの注入を宣言したのであり、それ以上のものではありません。後でビルドが、注入されたアノテーションをそのルーティングの仕方、バインドされた Feature のスキーマが認めないサブキーの値、または Release 側のアノテーションが使えないピラーを理由に拒否する場合、そのメッセージは注入したプラグインとそのアタッチ先のロールを示します。

ワイヤエンコーディング。 このロールのペイロードと結果は、両方向とも canonical CBOR(RFC 8949 §4.2.1)としてやり取りされます。ゲストは、ペイロード型が持つエントリポイント(Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では decodeCBORAnnotationTransformInput と encodeCBORAnnotationTransformOutput)を通じて読み書きするため、CBOR ライブラリは不要で、バイトを手作業でパースすることもありません。Rust ではエクスポートが Vec<u8> を受け取って返し、TypeScript では Host.inputBytes() を読んで Host.outputBytes(...) に書き込みます。各ターゲットの annotations はスキーマが順序保持とマークしたマップであるため、ターゲットが保持する順序でエントリの順序付きリストとして渡され、ゲストはキットの順序保持コンテナを通じてそれを読みます。各値はその JSON のバイト列として渡され、これは逆方向で注入の annotation_value が渡されるのと同じです。settings は JSON ドキュメントのバイト列として渡され、ゲストは中身を見るために JSON としてパースします。このエンコーディングによる AnnotationTransformOutput ではない応答(JSON で書かれたもの、または形状が宣言していないトップレベルのフィールドを持つもの)は、空の注入リストとして読まれるのではなく、プラグインとそのエクスポートを示してビルドを停止させます。aggrega plugin run-local --export transform_annotations で直接呼び出した場合、ゲストには作成者が記述した JSON ペイロードをこのエンコーディングに変換したものが渡され、その応答はエクスポートの出力形状として読まれて JSON で出力されます。その形状でない応答は、ビルドと同様に、エクスポートを示して拒否されます。

型定義。 annotation-transform のワイヤ型(AnnotationTransformInput、AnnotationTransformOutput、AnnotationTarget、AnnotationInjection、AnnotationSource)は 3 つすべての ABI パッケージで公開されており、1 つのコーデックから生成されるため、3 つは常に同期した状態に保たれます。

label-transform ロール — JSONPatch 出力

パイプライン上の位置。 トポロジー構築時、グラフがフラット化された後、IR グラフが構築される前です。そのため、アナライザーが評価するソケットセレクターと Feature セレクターは、このロールが残したラベルを読みます。

入力の形(ホスト → ゲスト)。 次を含む MutatorInput ドキュメントです。

  • compilation_context — リリースの識別情報(release_name、environment)。
  • graph — トポロジーノードの MutatorGraph 射影。各ノードの Component、解決済みバージョン、ラベル、そしてそのインスタンスが宣言する values を含みます。
  • settings — アタッチメントが with.settings に宣言した自由形式の設定オブジェクトで、そのままゲストに渡されます。
  • sources — アタッチメントが with.sources の下に宣言した定義ファイル。それぞれベース名のパスと内容を持つため、ミューテーターをインラインの設定ではなく、チェックインされたルールファイルやマッピングファイルで駆動できます。

グラフは IR グラフではなく射影です。各ノードは解決済みのラベルセットと、そのインスタンスが Aggregate で宣言する値を持ち、エッジと feature のペイロードはコンパイラ内部にとどまります。値は Aggregate 自身のもので、そのテンプレートはすでにパラメーターに対して評価されています。そのため、パラメーターに引き上げられた値は Release が与えた値として届きます。Component のスキーマが宣言するデフォルトや、Recipe や Feature が寄与するものはそこに含まれず、値を宣言しないノードは values キーを持ちません。ノードの Component が機密と宣言する値は、グラフに対する判定が伏せるのとまったく同じように伏せられ、{"aggrega_withheld": "declared"} として読まれます。一方、どの宣言も及ばない兄弟の値はすべて書かれたとおりに届きます。これにより、開発者が宣言した設定がラベルを決められます。たとえば、値でベクトル拡張を有効にするデータベースを datastore.aggrega.ai/engine: vector に昇格させる、といったことです。settings と sources は verdict ロールが読むのと同じ、エンジンに依存しない with チャネルであり、ホストはこれらをそのまま渡し、その内容を解釈することはありません。ミューテーターの出力はビルドを形作るため、アタッチメントの設定とソース内容は pull 時にリリースのロックファイルに固定され、ビルド時にそこから再構築されます。そのため、ミューテーターの入力は、pull 後にどちらかが変更されても、次の pull まで変わりません。

出力の形(ゲスト → ホスト)。 次を含む MutatorOutput ドキュメントです。

  • patches — ホストがノードのラベルのみに適用する、不透明な JSONPatch ドキュメント(RFC 6902)の配列。入力が持っていた値は読み取り専用です。

各パッチは JSON Pointer (RFC 6901) で特定のノードのラベルを指定します。ホストはパッチを配列の順に適用し、変更されたラベルセットを IR グラフに再取り込みします。label-transform ロールの役割はエンタープライズの自動タグ付けです。つまり、カタログの内容を変更せずに、エンタープライズのポリシーが宣言するコンプライアンス/オブザーバビリティ/コスト配分のラベルを追加します。このロールが認められている対象はラベルのみです。ラベル以外のノードフィールドに触れるパッチ、ノードを追加または削除するパッチ、文字列以外のラベル値を設定するパッチは、黙って吸収されるのではなくビルドを停止します。RFC 6901 は Aggrega のあらゆるドキュメントパスの面におけるパス文法のベースラインです。ここでの Wasm プラグイン契約に加え、.locals の *_path エクスポート、コーパスの他の箇所にある *Path スキーマフィールドが該当します。正規のベースライン宣言と、2 つの記述側を区別する *Path / *_path 接尾辞の規律については、02-naming-conventions.md の「Document-path naming-suffix discipline」を参照してください。

ワイヤエンコーディング。 このロールのペイロードと結果は、双方向とも canonical CBOR(RFC 8949 §4.2.1)でやり取りされます。canonical とは、同一の入力がどの側でも同一のバイト列を生むという意味です。これにより、ペイロードを往復させるだけでなく 3 つのプラグインキット間で比較でき、ビルドの出力がバイト単位で同一に保たれます。ゲストは、キットのペイロード型がすでに備えているエントリポイント — Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では decodeCBORMutatorInput と encodeCBORMutatorOutput — を通じて読み書きするため、CBOR ライブラリは不要で、バイト列を手作業で解析することもありません。Rust ではエクスポートは Vec<u8> を受け取って返し、TypeScript では Host.inputBytes() を読み、Host.outputBytes(...) に書き込みます。グラフの nodes、各ノードの labels、各ノードの values は、スキーマが順序保持と指定するマップであるため、エントリの順序付きリストとして渡されます。ノードはビルドが保持する順(作成者の順)で、各ノードのラベルはノードが持つ順で、各ノードの値は Aggregate が書いた順で渡され、ゲストは 3 つともキットの順序保持コンテナを通じて読みます。各値はその JSON ドキュメントのバイト列として渡されます。Go と Rust のキットはそれをその JSON のままゲストに渡し、ルールが必要とする範囲でパースさせます。TypeScript のキットはパース済みの値として渡します。

これによって変わらないことが 2 つあります。patches 配列は JSON のままです。ソケットは各パッチドキュメントを不透明な内容としてそのまま運び、どちらの側もその中身を読まないため、パッチドキュメント自体の形はソケットが運ぶエンコーディングとは無関係です。また、settings と sources は引き続きそのまま渡されます。settings はアタッチメントが記述したバイト列として届き、ゲストは中身を見る必要があれば JSON として解析します。

他のすべてのガバナンスロールも同じエンコーディングを使います。annotation-transform ロールと2 つの verdict ロールは、それぞれのセクションでその旨を記しています。そのため、複数のロールを担うゲストは、担うすべてのロールで canonical CBOR を使い、各ペイロードをそれぞれの型のデコードエントリポイントを通じて読みます。

型定義。 ミューテーターのワイヤ型 — MutatorInput、MutatorOutput、CompilationContext、MutatorGraph、MutatorNode — は、3 つの ABI パッケージ(github.com/aggrega-ai/aggrega-abi/go、aggrega-abi クレート、@aggrega-ai/aggrega-abi)のすべてで公開されており、1 つのコーデックから生成されるため、3 つは常に同期しています。ホストは入力を組み立て、ゲストが返したパッチを適用します。

verdict ロール — verdict 配列の出力

ポリシーゲストはビルドを検査し、verdict のリストを返します。ホストは各 verdict の severity に基づいて動作し、ポリシーそのものを解釈することはありません。4 つのロール、severity、 オペレーターが提供する入力チャネル、コンパイラに同梱される 2 つのエンジンのいずれか向けの ポリシーの書き方、外部ポリシーエンジンのラップ、リファレンスゲスト、オペレーターによる ポリシーのアタッチ方法といった詳細な説明は、ガバナンスソケットのページにあります。このセクションでは、 パイプライン上の配置と型付きのワイヤ形状を記録します。

パイプライン上の配置。 ポリシーはちょうど 1 つの verdict ロールにアタッチされ、それによって評価される位置が決まります。

  • ir-verdict — 静的解析の時点、ベースレンダリングの前に評価されます。アナライザーはすべてのビルドでペイロードを組み立てます。
  • render-verdict — レンダリング後に、出力されたアーティファクトに対して評価されます。

ワークスペースが verdict ロールのプラグインをアタッチすると、パイプラインはそのロールのペイロードをプラグインにマーシャリングし、返された verdict を読み取ります。

入力形状(ホスト → ゲスト)。 ロールによってペイロードが選ばれます。

  • ir-verdict の PolicyInput は、graph(ケイパビリティに依存しない完全な IR グラフで、Topology Builder が出力するものと同じ形状であり、コンパイラが保持するすべてのノード、エッジ、アタッチメントの詳細を含みます。ただし、作成者が機密と宣言した値は伏せられた状態で届きます。Values an input marks sensitive を参照)と、precalculated_paths(アナライザーが併せて列挙するルーティングパス)を運びます。これにより、ポリシーはグラフを再走査せずに到達可能性を推論できます。グラフはバージョン管理された IR グラフで、ir-v1beta1 スキーマを唯一のソースとしています。IR の形状は秘密ではなく(aggrega inspect が出力するのと同じグラフです)、その中のシークレットはポインタであり、平文になることはありません。
  • render-verdict の RenderPolicyInput は artifacts を運びます。これはパス順にソートされたレンダリング済みの出力ファイルであり、同一の入力に対する実行間でワイヤーがバイト単位で同一になります。各エントリは成果物の出力 path とレンダリングされた content を運びます。また、生成元の provider がフォーマットを宣言している場合はレンダリングに使われた format を、さらに tree も運びます。これはゲストがネイティブに読まないフォーマットをパースした正準ビューであり、ホストが解決済みのパーサーでパースし、中身に立ち入らずにそのまま渡します。いずれも該当しない場合は存在しません。ゲストがネイティブに読むフォーマット(JSON、YAML)はパースされずに残され、ゲストが content から読み取ります。

どちらのロールも、さらにアタッチメントの sources(ホストがビルド時に読み取りゲストにそのまま渡すポリシー定義ファイル。パスはベース名、内容は不透明)と settings(手を加えずに渡される自由形式のオブジェクト)を運びます。アタッチメントがこれらを宣言しない場合、どちらも存在しません。

出力形状(ゲスト → ホスト)。 次を運ぶ PolicyOutput ドキュメントです。

  • results — Diagnostic エントリの配列で、各エントリは severity(halt、warn、info のいずれか)と message 文字列を持ちます。verdict は同じエントリに code、rule_id、classification、source_ref、location、suggest を設定することもでき、ホストはどの severity のルートでも、verdict が持っていたものをレンダリングされた verdict に付加します。

発火した verdict だけが現れ、許可する評価は空の配列を返します。ホストは verdict を走査し、各 severity をアクションに対応付けます。halt はビルドを停止し(すべての halt メッセージを表示します)、warn は verdict を警告としてフラグ付けしてビルドを続行させ、info は結果に影響を与えずに記録します。halt は、セレクターや appliesTo の違反と同じゲートを通じて停止します。

ワイヤエンコーディング。 両ロールのペイロードと、どちらかでゲストが返す PolicyOutput は、正準 CBOR(RFC 8949 §4.2.1)として送受信されます。ゲストはペイロード型が持つエントリポイント(Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では decodeCBORPolicyInput、decodeCBORRenderPolicyInput、encodeCBORPolicyOutput)を通じてこれを読み書きするため、CBOR ライブラリは不要で、バイトを手作業で解析することもありません。Rust では各エクスポートが Vec<u8> を受け取って返し、TypeScript では Host.inputBytes() を読み取り Host.outputBytes(...) に書き込みます。グラフの順序を保持するマップ(nodes や各ノードの labels など)は、ビルドが保持する順序でエントリの順序付きリストとして渡され、ゲストはキットの順序を保つコンテナを通じて読み取ります。各ポリシーエンジンの下でポリシーがどの順序でそれらに出会うかは、ガバナンスソケットのページにあります。settings とアーティファクトの解析済み tree は JSON ドキュメントのバイトとして渡され、ゲストは中身を見るために JSON として解析します。このエンコーディングの PolicyOutput ではない応答(JSON で書かれたもの、または形状が宣言しないトップレベルフィールドを持つもの)は、空の verdict リストとして読まれるのではなく、プラグインとそのエクスポートを示してビルドを停止させます。aggrega plugin run-local --export verdict_ir または --export verdict_render で直接呼び出すと、ゲストにはこのエンコーディングに変換された作成済みの JSON ペイロードが渡され、その応答はエクスポートの出力形状として読まれて JSON で出力されます。その形状でない応答は、ビルドと同様に、エクスポートを示して拒否されます。

型定義。 ポリシーのワイヤ型は、同じ 3 つの ABI パッケージで公開されています。PolicyInput(ir-verdict ロール)、RenderPolicyInput(render-verdict ロール)、共有の PolicySource、そして PolicyOutput で、その results のエントリは Diagnostic 値です。診断の severity はすべてのソケットが共有する 3 つの値(halt、warn、info)のいずれかで、この 3 つは 3 つのパッケージそれぞれでワイヤ型と並んで定数として公開されているため、ゲストはホストがルーティングに用いるのと同じ閉じた集合から報告します。それ以外の値を返すゲストは、プラグインと返した値を示すメッセージとともにビルドを停止させます。ルーティングできない severity は、ホストが破棄する診断ではなく、ホストが報告するプラグインの欠陥です。

出力形状の契約 — FeatureRecipe パイプラインと provider ソケット

以下のソケットは、コンパイラがビルド時にディスパッチする型付きの契約サーフェスを持ちます。FeatureRecipe と Recipe の pipeline: ステップは、レンダリング済みドキュメントセットに対してプラグインパイプライン内で実行されます。provider レンダリングソケットはベースレンダリング時に実行され、publishing-linter は帯域外で実行されます。

RFC 6902 パッチ(プラグインパイプライン)

プラグインパイプラインで実行される FeatureRecipe と Recipe の pipeline: ステップは、レンダリング済みドキュメントセットに対して RFC 6902 JSON Patch 操作を出力します。ホストはキー付きドキュメントセット全体を各ステップに渡します。ステップは対象とするドキュメントを内容によって選択し、キーでアドレス指定されたパッチを返します。適用エンジンはそれらを指定されたドキュメントに適用します。典型的には、サイドカーコンテナの追加、シークレットボリュームのマウント、環境変数の書き換えなどです。ステップはさらに side_effects(後述)、diagnostics(各エントリは、すべてのソケットが問題の報告に用いる共有の Diagnostic 形状と同じです)、および outputs(後述)を返します。examples/04-secrets.md で説明しています。

現在の状況: 利用可能。宣言された各ステップは aggrega build の実行中に実行されます。

ワイヤエンコーディング。 ステップの入力(FRPStepInput)とその応答(FRPStepOutput)は、双方向とも canonical CBOR(RFC 8949 §4.2.1)として送受信されます。ゲストは、ペイロード型が持つエントリポイント(Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor(aggrega-abi クレートが公開する型上)、TypeScript では decodeCBORFRPStepInput と encodeCBORFRPStepOutput)を通じて入力をデコードし応答をエンコードし、バイト列(Rust では Vec<u8>、TypeScript では Host.inputBytes() と Host.outputBytes(...))を読み書きします。CBOR ライブラリは不要で、バイト列を手作業でパースする箇所はありません。ステップの with 入力(step_input)、返される outputs、および own と host のドキュメントセットは、スキーマが順序保持とマークしたマップであるため、パイプラインが保持する順序でエントリの順序付きリストとして送受信されます。ゲストはキットの順序保持コンテナを通じてこれらを読み書きします。これにより、ステップの出力は、ステップが返した順序で .steps.<id>.outputs に届きます。各ユニットの tree、step_input と outputs の各値、パッチの value、サイドエフェクトの crd、およびレンダーの context は、それぞれの JSON ドキュメントのバイト列として送受信され、ゲストは中身を見るために JSON としてパースします。ユニットの bytes は生のバイト列として送受信され、生成されたデコーダがキット固有のフィールド型(Go ではバイトスライス、Rust と TypeScript では base64 文字列)に格納します。各診断は共有の Diagnostic 形状で送受信されます。このエンコーディングの FRPStepOutput ではない応答(JSON で書かれたもの、または形状が宣言していないトップレベルフィールドを持つもの)は、実行する関数を名指ししてステップを失敗させ、ステップが optional でない限りビルドを停止します。aggrega plugin run-local --export step で直接呼び出した場合、ステップには作成された JSON ペイロードをこのエンコーディングに変換したものが渡され、その応答はエクスポートの出力形状として読まれて JSON で出力されます。その形状でない応答は、ビルドと同様に、エクスポートを示して拒否されます。

サイドエフェクト — リソースの出力(プラグインパイプライン内のクレデンシャルプラグイン)

クレデンシャル FeatureRecipe パイプライン(Two-Part Plugin Principle: Fetcher + Injector)は、ステップの side_effects を通じて、パッチと並んで完全なリソースを出力します。それぞれがコントラクトの定義する 2 種類のうち 1 つを宣言します。emit_crd は、クラスタが実行時に取得する ExternalSecret や VaultSecret の CRD などのカスタムリソースドキュメント、emit_file は書き出されるファイルです。それ以外の種類を返すステップは、ノード、サイドエフェクトのインデックス、宣言した種類を示してビルドを停止させます。Fetcher のステップは完全なリソースを出力し、Injector のステップは生成された Kubernetes Secret をマウントするパッチを返します。examples/04-secrets.md で説明しています。

現在の状況: 利用可能。

ステップ出力(pipeline: ステップの outputs マップ)

プラグインパイプラインのステップは名前付きの出力を公開し、後続のステップは {{ .steps.<id>.outputs.<key> }} を通じてそれを利用します。出力の形状はプラグインごとに提供側が定義します。ステップ出力のスコープは同じパイプラインに限られ、宣言順で後続のステップからのみ参照できます。templates/expansion-matrix.md の 10 行目に記載しています。

現在の状況: 利用可能。

Provider レンダリング — ゲスト駆動のソケット

provider は Wasm ゲストです。レンダリングは Wasm のみで行われます。Recipe の capability: 名は、その名前を spec.provider.capabilities に列挙し render_node エクスポートを公開している provider レンダリング Plugin(pluginType: provider)に解決され、そのプラグインのゲストがノードをレンダリングします。フォールバック先となるホスト内レンダラーはありません。対応する Plugin に解決されない provider 名は、ルーティング時にビルドを停止します。標準の provider を追加するとは、.wasm ゲストとカタログの Plugin エンティティを配布することです。ホストは provider ごとのコードを持ちません。

provider が提供する capability にはコロンを含めません。パイプラインステップが互換性を宣言する capability も同様です。 Recipe の capability: は、最後のコロンまでを capability、その後をバージョン指定として読み取ります。helm:1.0.0 は 1.0.0 の helm を要求します。そのため、コロンを含む名前はどの Recipe からも要求できません。ホストは、provider または pipeline-step ゲストの describe() の capabilities にそのような名前があると、ゲストのロード時および公開用にエンティティを生成する時に、ゲストとその名前を示して拒否します。パーサーの parse:<format> とインポーターの import:<format> はコロンを保持します。これらはフォーマットで検索され、Recipe の capability: を通じて検索されることはありません。

ホストは汎用のルーターです。ゲストの describe() による自己申告(render-behavior 契約を含む)を読み取り、provider のフォーマットを一切理解せずにゲストのエクスポートをディスパッチします。この契約はデータとしてディスパッチを駆動します。

  • input_kinds(sourced、synthesized、artifacts_standalone)— ゲストがレンダリングする Recipe の入力種別です。ホストはノードの入力種別をこのセットと照合します。
  • boundary_assembly(none | merge | nest)— ゲストがディスパッチグループの出力をどう結合するかを示します。merge はノードごとの出力を、アセンブラが 1 つのアーティファクトにマージするフラグメントとして分類します。nest はノードごとのファイルを組み立てられたラッパーの下に入れ子にします。none は各ノードの出力をそのまま書き出します。
  • nest_segment(省略可)— nest アセンブリにおいて、各コントリビューター自身のサブディレクトリを配置するディレクトリで、1 つのディレクトリ名として書きます。ない場合、各コントリビューターのサブディレクトリはディスパッチ位置の直下に置かれます。
  • assembly_name_annotation(省略可)— 境界アノテーションで、その解決済みの値が、ゲストがディスパッチグループから組み立てるアーティファクトの名前になります。ない場合、ゲストはディスパッチパスのみからアセンブリの名前を付けます。
  • cross_boundary_linking(省略可)— ゲストが境界をまたぐ uses エッジを link_publish と link_resolve のエクスポートを通じて接続するかどうか。ゲストは両方をエクスポートする場合に限り true と宣言し、フラグとエクスポートが一致しないゲストはロード時に拒否されます。
  • artifact_delimiters(任意)— ゲストがアーティファクト本体に適用する Go テンプレートの区切り文字の組です。
  • reusable_instance(任意)— ロードされた 1 つのインスタンスがビルドのすべての呼び出しを処理できるかどうかを示します(後述の決定性とインスタンスの再利用を参照)。
  • omits(任意)— ソースレンダーが持つ除外エントリをゲストが尊重するかどうかを示します(後述のレンダリング済みユニットの除外を参照)。
  • boundary_artifacts(任意)— Recipe が境界の共有出力に提供するファイルを、ゲストのターゲットが受け入れるかどうかを示します(後述のRecipe が境界に提供するファイルの受け入れを参照)。
  • source_ignore(任意)— ゲストのエコシステムが、レンダリングするソースと並べて配布することのないファイルです(後述のソースのエコシステムが配布しないものの宣言を参照)。

このソケットは固定のエクスポートセットです。1 つは必須で、残りは任意であり describe() で公開されます。

  • render_node(必須)— 1 つの IR ノードを provider ネイティブのファイルにレンダリングします。
  • assemble_boundary(任意)— ディスパッチグループのノードごとの出力を、パスごとに 1 つのアーティファクトへマージします(boundary_assembly が merge または nest の場合に存在します)。
  • validate_node_input(任意)— ノードの入力に対するレンダリング前の構造検証です。halt の診断はビルドを停止し、warn はビルド結果に表示されます。
  • carve / reassemble(任意、対)— レンダリング後のパイプラインステップ向けの、ゲスト独自のバイト忠実なパッチコーデックです。両方が公開されている場合にのみ使用されます。
  • name_bound(省略可能)— ホストが component の識別子として提案する名前から、ターゲットが受け入れる名前が得られるかどうかをゲストが判定し、独自の名前ではなく制約で応答します。
  • rendered_name(省略可能)— ノードに対してレンダリングするリソースにターゲットが付ける名前をゲストが報告します。
  • link_publish / link_resolve(省略可能、対で使用)— ゲストがバウンダリをまたぐ uses エッジを接続します。消費される側のエンドポイントがハンドルを公開し、消費する側のエンドポイントがそれを自身のアセンブル済み出力の中で解決します。

Recipe の artifacts: は、入力上の artifacts 射影を通じて render_node に組み込まれます。ホストが $import の読み込み、Go テンプレートの評価、来歴のキー/値の計算を行い、各エントリを読み込みと評価が済んだ状態でゲストに渡します。配置と、ゲストだけが知る形式での出力はゲストが担います。architecture/13-catalog-and-registry.md に記載されています。

ソースレンダーの入力はノードの値を node.values に持ち、node.values_mapped はそれらの値の由来を示します。値が Recipe の valuesMapping の出力である場合(アタッチメント自身のレンダーではその FeatureRecipe の valuesMapping の出力である場合)は true となり、コンポーネント自身の値が書かれたまま渡された場合は存在しません。ゲストがこれを読むかどうかは、そのゲスト自身のコントラクトです。cloudformation プロバイダは、ソースとなるテンプレートの Parameters をマッピングが生成した値からのみバインドします。コンポーネント自身の値は Recipe の他の入力のために書かれている可能性があるためです。terraform プロバイダは、ソースとなるモジュールの引数をそのアセンブリが受け取る値から書き出し、このフラグは読みません。これらの値は、ソースからレンダリングされたノードについて、assemble_boundary の入力の各レンダリング済みノード上で渡されます。コンポーネントの値はマッピングが生成したかどうかにかかわらず渡され、アタッチされた Feature の値はその FeatureRecipe の値マッピングが生成した場合にのみ渡されます。同じフラグもそれらの値と並んで、値が渡される場合にのみ渡されるため、アセンブラはノード自身のレンダーと同じ答えを読み取ります。cloudformation プロバイダはそこでこのフラグを読み、ノードのバインディングがどのパラメータを埋めたかを把握し、スタック内の他の場所(アタッチされた Feature のホストを含む)からそのパラメータへの参照を拒否します。このフラグは値がどのように生成されたかを記録するものであり、キーや値から導出されることはありません。

ワイヤエンコーディング。 このソケットのすべてのエクスポートは、入力の受け取りと出力の返却を、双方向とも canonical CBOR(RFC 8949 §4.2.1)で行います。ゲストは、ペイロード型がすでに備えるエントリポイントを通じて入力をデコードし出力をエンコードします。Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では各型の decodeCBOR 関数と encodeCBOR 関数(decodeCBORRenderNodeInput や encodeCBORRenderNodeOutput など)で、バイト列を読み書きします(Rust では Vec<u8>、TypeScript では Host.inputBytes() と Host.outputBytes(...))。CBOR ライブラリは不要で、バイト列を手作業で解析する箇所もありません。レンダリングされたファイルの content をはじめとするすべてのバイトフィールドは、生のバイト列として渡され、生成されたデコーダがキット固有のフィールド型に格納します。Go ではバイトスライス、Rust と TypeScript では base64 文字列です。スキーマが順序保持とマークしたマップ(ノードの values、features、uses、応答の derived_keys、アセンブリのコントリビュータの values など)は、ビルドが保持する順序でエントリの順序付きリストとして渡され、ゲストはキットの順序保持コンテナを通じて読み取ります。ノードの values の各値はそれ自身の JSON ドキュメントのバイト列として渡されるため、値内部のキーは記述された順序を保ちます。features の各アタッチメントエントリ、レンダーコンテキスト、解析済み workload、各拡充済みエッジ、各 carve 済みユニット、各パッチ操作も同様で、ゲストは中身を見るためにそれらを JSON として解析します。各診断は共有の Diagnostic 形式で渡されます。このエンコーディングでエクスポートの出力形式になっていない応答(JSON で書かれたものや、形式が宣言していないトップレベルフィールドを持つもの)は、呼び出したエクスポートを示してビルドを停止させます。このページのペイロード例は、読みやすさのため JSON で記述しています。aggrega plugin run-local --export render_node やこのソケットの他のエクスポートで直接呼び出した場合、ゲストには記述された JSON ペイロードがこのエンコーディングに変換されて渡され、その応答はエクスポートの出力形式として読み取られて JSON として出力されます。その形式でない応答は、ビルドが拒否するのと同様に、エクスポートを示して拒否されます。

現在のステータス: 5 つの provider すべてで 利用可能 です。helm ゲストは、ソース指定されたチャート(チャートルートを解決)、合成された workload、スタンドアロンのアーティファクトをフラットな Kubernetes マニフェストとしてレンダリングします。helm-chart ゲストはアンブレラチャートをアセンブルし、各ノードのソース指定チャートをサブチャートとしてネストし、バイト忠実なパッチコーデックとブラケット([[ ]])のアーティファクト区切り文字を備えます。compose ゲストは、ソース指定された compose ファイルと合成された workload をレンダリングし、ディスパッチグループを 1 つの docker-compose.yaml にマージし、サービスをその x-aggrega-networks-of が指定する component のネットワークに参加させます。terraform ゲストは、Terraform 設定を(HCL または JSON で)そのまま出力するか、ソース指定されたモジュールをベンダリングしてその入力を当該 component のモジュールブロック引数として与えます。また、ソース指定されたモジュールの HCL をレンダリング前に構造的に検証し、バウンダリを 1 つのルート設定に構成して、各 component を、その component 自身のサブディレクトリをソースとするモジュールブロックとして宣言します。cloudformation ゲストは、ソース指定されたテンプレートとスタンドアロンのスタックフラグメントをレンダリングし、ディスパッチグループを 1 つのスタックテンプレートにマージし、バウンダリをまたぐ uses エッジを link_publish と link_resolve を通じて配線します。いずれもオフラインかつ決定的にレンダリングします。

ゲストが導出する名前の宣言

プロバイダーのゲストは通常、出力に必要でありながら誰も記述していない名前(ターゲットが 1 つのリソースを指す識別子や、ある出力を別の出力から参照できるよう公開する名前など)を、ノードのアイデンティティと出力中のリソースから導出します。導出元の要素が一致すれば 2 つのノードが同じ名前に行き着くことがあり、その名前はホストがそのまま書き込むファイルのバイト列の中にあるため、ホストはこの衝突を検出できません。検出するにはプロバイダーの形式をパースする必要があり、それはまさにゲストの中にとどまる知識です。

そのため render_node は出力に省略可能な derived_keys を返し、方向は逆になります。ホストが出力を検査するのではなく、ゲストが宣言し、ホストが検査します。

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"derived_keys": {
"logical-ids": ["paymentsapiQueue", "paymentsapiTopic"],
"export-names": ["aggrega--prod--api--orders-db--host"]
}
}

derived_keys の各キーはゲストが名付けるキー空間であり、各空間にはゲストがそこに導出した名前が導出順に入ります。空間名もその中の名前も、利用者側の語彙です。ホストはそれらを、1 つの空間内で等価性を比較する文字列としてのみ読み取ります。名前をパースすることも、空間や名前の意味を知ることもなく、自ら名前を導出することもありません。そのため 1 つの検査で、あらゆるプロバイダーが導出するあらゆる種類の名前を扱え、新しいプロバイダーに新しいホストコードは不要です。公開されている型では derived_keys は順序を保持するマップであるため、空間はゲストが設定した順序で渡されます。

ホストがそれらを使って行うことは、ただ 1 つの問いです。1 つの空間内で、出力が 1 つのアセンブリにマージされるコントリビューター間で、宣言されたすべての名前が互いに異なっているか。2 つのコントリビューターが 1 つの空間で同じ名前を宣言するとビルドは停止し、その停止では空間、名前、両方のコントリビューターが示されるため、作成者はプロバイダーを読まずに対処できます。異なる名前、および 2 つの異なる空間の間でたまたま一致する名前は通過します。

何を宣言するかを決める際には、次の 3 つの性質を知っておくと役立ちます。

  • スコープは 1 つのアセンブルされた出力です。つまり、ファイルがまとめてマージされるコントリビューターの集合です。それより狭い、または広いスコープで一意性を求めるゲストは、宣言する空間名でそのスコープを表現します。これにより、その選択はホストではなく利用者側に委ねられます。
  • 1 つのコントリビューターは名前を自由に繰り返せます。 1 つのノードは複数の受け渡し(ソースのレンダリング、ワークロードの合成、アーティファクトの配置)にわたってレンダリングされることがあり、宣言はマージされます。1 つのコントリビューターが同じ名前を 2 回宣言しても、それはそのコントリビューターが 1 つのリソースを 2 回記述しているだけであり、衝突ではありません。
  • 宣言してもバイト列は変わりません。 このフィールドはゲストが導出したものについての表明であり、出力したものを変更することは決してないため、ゲストのレンダリング出力は宣言の有無にかかわらず同一です。derived_keys を省略することは有効であり、そのゲストについては検査が働きません。

ゲストが出力したものに関する事実の報告

ノードのレンダリングについて、それを生成したプロバイダーにしか見えない事柄があります。書き出したドキュメントに何が含まれるか、どの名前を定義しているか、何かをいくつ出力したか、などです。ファイルのバイト列からそれらを読み取るにはプロバイダーの形式を理解する必要があるためです。render_node は、そうした事柄を自ら、ファイルと並ぶ省略可能な render_facts リストで報告できます。

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

各事実は name と value から成り、どちらもそのプロバイダーに属します。どの事実を報告するか、各名前が何を意味するか、各エントリが何を保持するかは、プロバイダー自身の文書化された契約の一部です。それを読む作成者のために文書化してください。

エントリが 1 つしかない場合でも、すべての事実の値はリスト(JSON 配列)として報告してください。 1 つの名前は、コンポーネントの複数のレンダリングから報告されることがあります。コンポーネント自身のレンダリングは複数回の呼び出し(たとえばチャートのレンダリングとアーティファクトの配置)にわたることがあり、コンポーネントにアタッチされた各 Feature はそれぞれ独自のプロバイダー呼び出しでレンダリングされます。どのプロバイダーも、レンダリング時に自分の報告がその名前の下で唯一のものになるかを知ることはできないため、報告はすべてリストとし、コンパイラは 1 つの名前に集まったリストを 1 つのリストに結合します。値がそれ以外のもの(オブジェクト、文字列、数値、真偽値、null)である事実は、ゲストが返した時点で拒否されます。ビルドは短いコード E0325 で停止し、事実、ノード、ゲストを示し、値が何であったかを伝えます。リスト内のエントリは、文書化した形の任意の JSON 値です。

値がリストであることは、コンパイラがその値について知る唯一のことです。コンパイラは事実を名前でキー付けし、各リストをそれを読むテンプレートに渡します。ホストコンポーネントの事実はそれにアタッチされたすべての Feature に、各呼び出し元の事実は呼び出し元のレンダリング事実を読むと宣言した Feature に、各ターゲットの事実はホストが接続されたコンポーネントのレンダリング事実を読むと宣言した Feature に渡されます。これはテンプレートコンテキストの説明のとおりで、各リストはテンプレートが range で反復できる値にデコードされます。コンパイラは名前やエントリの意味を知ることはなく、自ら事実を導出することもないため、新しいプロバイダーはコンパイラ側に一切の変更なしに新しい事実を報告できます。ノードにアタッチされた Feature が自身のレンダリングから報告する事実は、ノード自身のレンダリングが報告した事実とは区別して保持されます。

何を報告するかを決める際には、次の 4 つの性質を知っておくと役立ちます。

  • 順序は利用者側が決めます。 事実はゲストが列挙した順序を保ち、各値は自身のバイト列を保ちます。リストのエントリの順序や各オブジェクトのキーの順序は、ゲストが書いた順序です。同一の入力が同一のバイト列を生むよう、事実は固定の順序で列挙し、各エントリは固定のキー順序で書いてください。事実がマップではなくリストであるのは、まさに、何も印を付けずにあらゆるキットのシーケンス型で順序が保たれるようにするためです。マップの場合、ゲストが書いた順序が保たれるのは、スキーマがそのマップを順序保持と指定し、ゲストがキットの順序を保持するコンテナに値を入れたときだけです。
  • 報告してもバイト列は変わりません。 コンパイラが書き出すファイルは、事実が付随するかどうかにかかわらず、ゲストが返したファイルそのものです。
  • 1 つのノードは複数の受け渡しにわたって報告できます。 ノードはソースのレンダリング、ワークロードの合成、アーティファクトの配置としてレンダリングされることがあります。それぞれが報告する事実は受け渡しが実行された順序で保持され、複数から報告された名前は、それらをその順序で結合した 1 つのリストとして読まれます。
  • 何も報告しなくても完全です。 render_facts を省略することは有効であり、何も報告しないプロバイダーは、このフィールドがない場合とまったく同じようにレンダリングします。

RenderFact 型は 3 つの ABI パッケージで公開され、各言語のプラグイン開発キットから再エクスポートされています。キットのレンダリング例では、ファイルと並べて 2 つの事実を報告しています。Go では、値はゲストが書く JSON です。マップではなく構造体のスライスをマーシャリングすることで、各エントリのキーが宣言した順序に保たれます。

type stackFact struct {
Name string `json:"name"`
Resources int `json:"resources"`
}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})
if err != nil {
pdk.SetError(err)
return 1
}
out := aggrega.RenderNodeOutput{
Files: files,
RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},
}

レンダリングされたユニットを除外する

ソースのレンダリングでは、プロバイダーがレンダリング結果から除外すべきユニットを指定できます。たとえば、取得したチャートがレンダリングのたびに新たに生成する Secret などです。エントリがどのレンダリング済みユニットを指すかを知っているのはプロバイダーだけなので、エントリはゲストに渡され、除外はゲストが行います。エントリは render_node の入力に、source_listing と並ぶ省略可能な omits リストとして届きます。

{
"node": { "id": "payments-api" },
"context": { },
"source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] },
"omits": [
{ "kind": "Secret", "name": "payments-api-token", "namespace": "payments" },
{ "kind": "ConfigMap", "name": "payments-api-dashboards" }
]
}

各エントリは kind、name、省略可能な namespace から成り、すでにプレーンな文字列に解決され、作成者が宣言した順序で並んでいます。ビルドに該当しないエントリは渡されません。3 つのフィールドが何を選択するかはプロバイダー自身の契約、つまりターゲットの形式におけるリソースの kind、name、namespace です。そのため、エントリを書く作成者向けに文書化してください。

作成者は、機密と宣言した値からエントリのフィールドを組み立てることができます。たとえば、機密設定にちなんで名付けられたリソースなどです。そのようなエントリは "sensitive": true 付きで届き、ゲストはレンダリング入力が運ぶ他のマーク付きの値と同じように扱います(入力が機密とマークする値を参照)。つまり、エントリの目的どおりフィールドによる照合とカウントは行いつつ、そのフィールドをどれも拒否、警告、ログ行に含めません。コンパイラはどのフィールドがその値から生じたかを示さないため、マークはエントリ全体に及びます。そのような値から組み立てられたフィールドがない場合、マークはありません。

エントリに従うゲストは、次の 3 つを行います。

  • すべてのエントリをレンダリング結果と照合します。照合は形式の用語で行います。
  • 一致した各ユニットを返すものすべてから除外します。つまり files、derived_keys で宣言する名前、render_facts で報告するファクトから除外し、コンパイラが受け取るものにそのユニットを記述するものが残らないようにします。
  • エントリごとに 1 つのカウントを報告します。出力の省略可能な omitted リストに、エントリが届いた順序で、各エントリが一致したユニット数を記録します。他のエントリも同じユニットに一致したかどうかにかかわらずカウントします。
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

ゼロも完全な回答であり、そのエントリがゲストのレンダリング結果の何にも一致しなかったことを意味します。除外されたものについて返されるのはカウントだけで、ユニット自体はゲストが返したものに単に存在しません。

この 3 つすべてを行うプロバイダーは、契約で omits: true を宣言します。Plugin エンティティは同じ主張を spec.provider.contract.omits として記録します。エンティティがレンダリング動作の契約を持つ場合、describe() が異なる値を報告するゲストはロード時に拒否されます。エントリはソースリスティングにのみ付随し、合成された workload や artifact セットのレンダリングには渡されません。

エントリを持たないレンダリングは、これらのフィールドの影響を受けません。 どちらのフィールドも省略可能で、空の場合は存在しないため、エントリを持たないレンダリングはフィールドが存在しない場合とバイト単位で同じようにソケットを通過し、それらを読まないゲストは影響を受けません。OmitEntry 型は 3 つの ABI パッケージで公開され、各言語のプラグイン開発キットで再エクスポートされています。

コンパイラが回答をどう扱うか。 エントリは、作成者が Recipe または FeatureRecipe に書く omits: キーに由来します(Recipe → omits: フィールド)。コンパイラは各エントリのテンプレートを評価し、該当するものをゲストに渡します。その後、カウントを読み取ります。読むのはカウントだけで、検証のために返されたファイルの中を見ることはありません。

  • 渡したエントリごとに負でないカウントが 1 つずつになっていないカウントリストは、ビルドを停止します。欠落している、短すぎる、長すぎる、またはゼロ未満のカウントを含む場合です。停止はノード、プロバイダー、渡したエントリ数、返ってきたカウント数を示します。対応の取れない報告では、どのエントリが何を除外したかを判別できません。A provider’s omitted counts do not match the omits entries it was handed(プロバイダーの omitted カウントが渡された omits エントリと一致しない)を参照してください。
  • ゼロはビルドを停止します。停止は、作成者の順序でカウントがゼロである最初のエントリを示します。つまり、ノード、プロバイダー、そのドキュメントが宣言するリスト内でのエントリの位置、解決された kind、name、namespace です。ゼロを報告するのはゲストで、停止するのはコンパイラです。An omits entry left out nothing the source rendered(omits エントリがソースのレンダリング結果から何も除外しなかった)を参照してください。
  • プロバイダーが omits: true を主張していないのに omits: を宣言するドキュメントは、何もレンダリングされる前に拒否されます。そのため作成者は、出力にドキュメントが現れて気づくのではなく、キーが効果を持たないことをすぐに知ることができます。コンパイラは、ビルド内のすべての Recipe と FeatureRecipe がバインドされた時点で describe() から主張を読み取り、最初のコンポーネントがレンダリングされる前に拒否します。したがって、キーを主張しないゲストにエントリが渡されることはありません。拒否は、プロバイダーと、ドキュメントがレンダリング対象とするコンポーネントを示します。境界に対して一度だけ生成する FeatureRecipe の場合は、境界とアタッチメントを示します。The provider does not support omits(プロバイダーが omits をサポートしていない)を参照してください。

現在の状況: 利用可能。コンパイラに同梱される helm、compose、cloudformation のゲストは主張を宣言し、エントリに従います。helm ゲストは、返すテキストにエントリのどのフィールドも書き込みません。compose と cloudformation のゲストは、エントリを拒否する際にはエントリの kind、name、namespace を示し、除外されたユニットをまだ参照しているファイルやテンプレートを拒否する際にはそのユニットを示し、その場合マーク付きエントリのフィールドはすべて <redacted> と表示します。helm-chart と terraform のゲストは主張を宣言しないため、それらがレンダリングする omits: 宣言付きドキュメントは拒否されます。

Recipe が境界に提供するファイルを受け入れる

ファイルの中には、境界のコンポーネントの 1 つではなく境界全体に属するものがあります。たとえば、ターゲットが境界でデプロイするすべてのものに対して一度だけ読むプロバイダー設定などです。Recipe はそれらを spec.boundary.artifacts の下に書き、処理はゲストではなくコンパイラが行います。コンパイラは各ファイルを artifacts: エントリと同じコンテキストで評価し、ディスパッチグループのすべての提供者が宣言したファイルを名前でマージし、グループの組み立て済み出力を収めるディレクトリに、assemble_boundary が返すものと並べて各ファイルを一度だけ書き込みます。ゲストはどのエクスポートでもこれらのファイルを渡されず、問い合わせられることもないため、実装すべきものはなく、ターゲットについての表明が必要なだけです。

"contract": {
"input_kinds": { "sourced": true, "artifacts_standalone": true },
"boundary_assembly": "nest",
"boundary_artifacts": true
}

boundary_artifacts: true は、ターゲットがそのディレクトリに置かれたファイルを境界の出力の一部として読む場合にのみ宣言してください。Plugin エンティティは同じ主張を spec.provider.contract.boundaryArtifacts として記録します。エンティティがレンダリング動作の契約を持つ場合、describe() が異なる値を報告するゲストはロード時に拒否されます。プロバイダーが主張していないのにこのブロックを宣言する Recipe は、何もレンダリングされる前に拒否され、プロバイダーとコンポーネントが示されます。The provider does not support boundary artifacts(プロバイダーが境界 artifacts をサポートしていない)を参照してください。これらのマージによって、アセンブリも書き込む名前でファイルが配置されると、two contributors writing one output path(2 つの提供者が同じ出力パスに書き込む)としてビルドが停止します。そのため、アセンブリが書き込む名前は作成者向けに文書化する内容の一部です。

現在の状況: 利用可能。コンパイラに同梱される terraform ゲストは主張を宣言し、Terraform は各ファイルを境界のルート設定と並べて読み込みます。helm、compose、helm-chart、cloudformation のゲストは宣言しません。

ソースのエコシステムが決して配布しないものを宣言する

Recipe のローカルソースディレクトリ(同じ場所に置かれたチャートやモジュール)は Recipe とともに公開されますが、その中のすべてのファイルが Recipe に属するわけではありません。provider のゲストは、自身のエコシステムが決して配布しないものを、コントラクトの source_ignore を通じて、.gitignore と同じ構文の無視ルールとして示します。

"contract": {
"input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false },
"boundary_assembly": "none",
"source_ignore": {
"patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"],
"files": [".helmignore"]
}
}
  • patterns は、ソースディレクトリのルートから読まれるルールで、順に適用され、後のマッチが前のマッチを上書きします。
  • files は、エコシステムがソース内で尊重する無視ファイルを指定します。ソースの走査中にそのファイルに出会うと、その行は、パターンの後に、そのファイルを含むディレクトリに対する追加のルールとして読まれます。

この宣言は、エンティティがレンダリングされるときではなく、ピン留めされるときに読まれます。 作成者のピン留めステップは、作成者のワークスペースでエンティティのケイパビリティを提供するプラグインを解決し、プラグインのルールを作成者自身の .aggregaignore(その行は最後に来るため、指定したパスについては常に優先されます)と合成し、プラグインの名前をバージョンなしで、合成されたルールそのものとともに、エンティティの entity.lock に記録します。以後のそのエンティティの公開、比較、レンダリングはすべて、記録されたルールを適用します。ホストはそれらをマッチさせるだけで、どのエコシステムについても独自の見解を持ちません。したがって、レンダリング時にゲストに渡されるファイル(一覧、およびゲストがホストにパックや読み取りを求めるすべてのファイル)は、エンティティの公開物が持つファイルと完全に一致し、ルールが除外したファイルは、そのファイル名を示したうえで存在しないものとして応答されます。ソース配下のシンボリックリンクは、ゲストが呼び出される前に拒否されます。

互換性は、記録された内容から決まります。 ゲストは、同じ ABI バージョンを話し、コントラクトがエンティティの宣言と一致し、公開されたセットの外のファイルを必要としない場合に、自身のケイパビリティ向けに公開された Recipe をレンダリングできます。セットが除外したファイルを必要とするゲストは、そのファイル名を示して明示的にビルドを失敗させなければなりません。ホストによるパックや読み取りの拒否はそのファイル名を示すので、ゲストはそれを自身の失敗に引き継ぎます。利用者のワークスペースがあるケイパビリティにバインドするプラグインが、エンティティのロックに記録されたものとは異なるルールを宣言している場合、利用者の pull は両方のプラグインと差分を示す警告を出力します。これによって停止することはありません。

source_ignore を省略するとルールは何も宣言されず、レンダリングするソースは、作成者自身のルールが残すすべてのファイルを残します。このフィールドは任意であり、独自の ABI バージョンを必要としません。これを省略したゲストは、何も宣言しないゲストとしてロードされます。Plugin エンティティは同じ宣言を spec.provider.contract.sourceIgnore として記録します。記録している場合、ロード時に、describe() が異なる内容を報告するゲストは拒否されます。

決定性とインスタンスの再利用

ホストはゲストの出力バイトをそのまま使用するため、ゲストは同一の入力から同一の出力を生成しなければなりません。デフォルトでは、ゲストはノードごとに新たにロードされ、構造上、ノード間で状態は一切引き継がれません。reusable_instance を自己宣言したゲストは、代わりにビルドごとに一度だけロードされ、その単一のインスタンスがすべての呼び出しを処理します。これにより、支配的なノードごとのインスタンス化コストを回避できます。再利用はステートレスなゲストでのみ安全なため、aggrega build --verify-determinism は各ノードを同じインスタンスで2回レンダリングし、いずれかのノードの2回のレンダリング結果が異なればビルドを停止します。デフォルトのビルドは1回だけレンダリングし、宣言を信頼します。Wasm のコンパイルキャッシュはディスクに保存されプロセス全体で共有されるため、ゲストは一度だけコンパイルされ、ウォームビルドでは再コンパイルが省略されます。

リンターソケット — 公開用リンター

リンターソケットは、標準の publishing-linter として配布されます。これは、コンパイル時ではなく aggrega lint を通じて実行される、帯域外のゲートです。カタログエンティティ(--pre-publish モードでは、そのエンティティの現在公開されているバージョンも)を受け取り、それぞれ重大度とメッセージを持つ指摘の一覧を返します。--pre-publish モードでは、バージョンバンプの分類も返します。ホストは、他のすべてのソケットと同じ AOT 純粋性のファイアウォールの背後で、組み込みの Wasm ランタイムを通じてこれをディスパッチします。ルールの全一覧、重大度、ルールごとのオプトアウトは cli/aggrega-lint.md に記載されています。

linter はオプトインのカタログ規律です。コンパイラは aggrega build の間にこれを実行しません(唯一の例外は x-aggrega-* の非推奨勧告で、ビルド中は warn の重大度で、aggrega lint --pre-publish では halt の重大度で表示されます)。ルールはプラグインに含まれているため、企業は独自の規律を適用するために aggrega lint を別の linter プラグインに向けることができます。

aggrega lint がどのスコープで実行されても、パラメータ値が linter プラグインに届くことはありません。ドキュメントを渡す前に、ホストは Aggregate のパラメータのデフォルト値、インポートする各モジュールに渡す値、および Release のパラメータを差し控えます。その際、各パラメータ宣言のコントラクト(宣言に書かれたキーのみ、ネストのすべてのレベルで)と、パラメータを読むテンプレートテキストは保持します。パラメータの値はそれ自体が認証情報である可能性があり、ここにアタッチされるプラグインはワークスペースが書いたものではないコードである可能性があるためです。各ドキュメントが持つ内容は linter プラグインに渡されるもの に記載されています。

ワイヤエンコーディング。 入力と出力はいずれも 正準 CBOR(RFC 8949 §4.2.1)として送られます。ゲストは、キットの LinterInput と LinterOutput がすでに備えるエントリポイント(Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では decodeCBORLinterInput と encodeCBORLinterOutput)を通じて入力をデコードし出力をエンコードし、バイト(Rust では Vec<u8>、TypeScript では Host.inputBytes() と Host.outputBytes(...))を読み書きします。CBOR ライブラリは不要で、バイトを手作業でパースすることもありません。エンティティのドキュメント(proposed、previous、implemented_component、release)と components の各値は、それぞれの JSON ドキュメントのバイトとして渡されるため、ゲストは中身を見るためにそれらを JSON としてパースします。components はスキーマが順序保持とするマップであるため、Release 全体を読むルールの入力では、Aggregate がコンポーネントインスタンスを宣言する順序でのエントリの順序付きリストとして渡され、ゲストはキットの順序保持コンテナを通じてそれを読みます。policies は設定されたフラグのみを持つマップとして渡されるため、含まれていないフラグは false として読まれます。各指摘は共通の Diagnostic の形で渡されます。このエンコーディングでの LinterOutput ではない応答(JSON で書かれたもの、あるいはその形が宣言しないトップレベルのフィールドを持つもの)は、何も見つからなかった実行として読まれるのではなく、呼び出したエクスポート名を示して lint を失敗させます。aggrega plugin run-local --export lint_rules で直接呼び出された場合、linter には作成された JSON ペイロードをこのエンコーディングに変換したものが渡され、その応答はエクスポートの出力形式として読み取られて JSON として出力されます。その形式でない応答は、ビルドが拒否するのと同様に、エクスポートを示して拒否されます。

現在の状況: 利用可能。publishing-linter は配布されており、aggrega lint を介してホスト経由で実行されます。

parser ソケット — 正規ツリー出力

parser は、コンパイラがネイティブに読み取らない形式で書かれたソースを正規の構造化ツリーに変換します。これにより、利用側は独自の parser を持つ代わりにそのツリーを読み取ります。ホストは、要求された形式を parse:<format> として公開している parser を解決し、その parse エクスポートを 3 つの場面で呼び出します。1 つは render-verdict ポリシーが、ネイティブに読み取らない形式のレンダリング済みアーティファクトを渡されたとき、もう 1 つは importer が aggrega_parse_source を通じてホストにツリーを要求したとき、そして形式を指定しないインポートの形式を認識するとき(後述の importer ソケットを参照)です。ゲストが parser を直接呼び出すことはありません。

入力の形(ホスト → ゲスト)。 次の内容を持つ ParseInput ドキュメントです。

  • format — 要求された形式です。parser の parse:<format> ケイパビリティのいずれかから接頭辞を除いたものです。
  • bytes — ソースのバイト列です。
  • options — parser 固有の動作のために利用側が指定するオプションドキュメントで、そのまま渡されます。利用側が指定しない場合は存在しません。

出力の形(ゲスト → ホスト)。 tree(パースされたソースを表す JSON ドキュメントで、トップレベルはオブジェクト、配列、スカラーのいずれでもかまいません)、共通の Diagnostic 形式の診断、元のバイト列におけるツリーノードの位置を示す任意のソーススパン、およびパースを完了できなかった場合の失敗 error を持つ ParseOutput ドキュメントです。すべてのフィールドとその制約は、生成された parser ソケットのスキーマリファレンスに記載されています。

ワイヤエンコーディング。 入力と出力はどちらも canonical CBOR(RFC 8949 §4.2.1)として送られます。これは、ゲストが aggrega_parse_source に同じ ParseInput を渡すときのエンコーディングと同じです。ゲストは、各キットの ParseInput と ParseOutput がすでに備えるエントリポイント(Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では decodeCBORParseInput と encodeCBORParseOutput)を通じて入力をデコードし出力をエンコードし、バイト列を読み書きします(Rust では Vec<u8>、TypeScript では Host.inputBytes() と Host.outputBytes(...))。CBOR ライブラリは不要で、バイト列を手作業でパースすることもありません。ソースのバイト列は生のバイト列として渡され、生成されたデコーダがそれをキット固有のフィールド型に格納します。Go ではバイトスライス、Rust と TypeScript では base64 文字列です。options と tree はそれぞれの JSON ドキュメントのバイト列として渡されるため、parser が書いたツリーはそのまま利用側に届きます。完了できない parser は出力の error に理由を記述し、パースは parser とそのメッセージを示して失敗します。このエンコーディングの ParseOutput ではない応答(JSON で書かれたもの、または形式が宣言していないトップレベルフィールドを持つもの)も、parser とその parse エクスポートを示してパースを失敗させます。パースが失敗すると、render-verdict ロールではビルドが停止し、importer には aggrega_parse_source が返す失敗として届きます。parser が拒否するソース、つまりツリーと並べて halt 診断を返すソースも同様です。importer の呼び出しは、そのような各診断のメッセージを parser の順序で示して失敗し、ツリーが渡されることはありません。aggrega plugin run-local --export parse で直接呼び出した場合、parser には作成された JSON ペイロードをこのエンコーディングに変換したものが渡され(そのペイロード内のソースは、JSON が任意のバイトフィールドを書くのと同様に base64 で記述されます)、その応答はエクスポートの出力形式として読み取られて JSON として出力されます。その形式でない応答は、ビルドが拒否するのと同様に、エクスポートを示して拒否されます。

型定義。 parser のワイヤ型(ParseInput、ParseOutput、NodeSpan、SourceSpan)は 3 つの ABI パッケージすべてで公開され、各言語のプラグイン開発キットで再エクスポートされています。これらは 1 つのコーデックから生成されるため、3 つは常に一致します。各キットの parse サンプルはこの方法で入力を読み取り出力を書き込みます。バイナリに同梱されている HCL、TOML、YAML、JSON、およびコメント付き JSON の parser も同様です。

現在の状況: 利用可能。ポリシーがネイティブに読み取らない形式のアーティファクトに対しては render-verdict ロールで、importer に対しては aggrega_parse_source を通じてディスパッチされ、形式を指定しないインポートの形式の認識にも使われます。

インポーターソケット — ドラフトのオーサリング出力

インポーターは、別のツール向けに書かれたソース(たとえばエージェントビルダーからエクスポートされたフロー)を、Aggrega のドラフトのオーサリングファイルに変換します。インポーターはビルドとは別に実行されます。aggrega import、エディタセッションの aggrega/import メソッド、アシスタント向けの import ツールが、要求されたフォーマットを import:<format> として公開するインポーターを解決し、インポートごとに一度その import エクスポートを呼び出します。ビルドがインポーターをディスパッチすることはありません。どのインポーターが実行され、オペレーターが何を渡すかは、Which importer turns a source into drafts で説明しています。コンパイラ自身のインポーター(読み込む各フォーマットに 1 つずつ)は Core importers で説明しています。そこでは、それがどのフォーマットか、それぞれが何を読み、何をドラフトし、どの設定を受け取るか、コンパイラの各リリースでの公開、そしてマシンがまだ保持していないインポーターをインポートがどのように取得して検証するかを扱います。

入力の形(ホスト → ゲスト)。 次を持つ ImportInput ドキュメントです。

  • format — インポートが要求したフォーマットで、インポーターの import:<format> ケイパビリティのいずれかからプレフィックスを除いたものです。
  • bytes — ソースのバイト列です。ファイルのインポートではファイル全体、ディレクトリのインポートでは空になり、その場合ファイルは sources の下に届きます。
  • name — ソースの名前で、前にディレクトリを含みません。これにより importer は、報告する内容と作成する内容の中でソースを示せます。ファイルのインポートでは、bytes の読み取り元ファイルのベース名です。ディレクトリのインポートでは、ディレクトリ自身のベース名で、そのフルパスから読み取られます。そのため aggrega import . は実行されたディレクトリの名前を渡し、ディレクトリの各ファイルは引き続きそれぞれ固有の名前で渡されます。ソースに与える名前がない場合は存在しません。
  • sources — 名前付きのソースで、それぞれが名前とバイト列を持ち、名前順にソートされた 1 つのリストに入ります。ディレクトリのインポートでは、インポーターが宣言したファイルパターンが選択するそのディレクトリのすべてのファイルが、ワークスペースのビルド出力フォルダーを除いて、ディレクトリ内のスラッシュ区切りのパスを名前として含まれます。また、このインポーターをアタッチする plugins.importer エントリが with.sources の下で宣言するファイルが、それぞれベース名で含まれます。同じ名前のディレクトリのファイルと with.sources のファイルがある場合、一方が他方を隠すのではなく、インポートが拒否されます。ソースがない場合は存在しません。
  • settings — そのエントリが with.settings の下で宣言する設定オブジェクトで、キーをソートした JSON ドキュメントとして、そのまま渡されます。インポーターをアタッチするエントリがない場合、またはエントリが何も宣言しない場合は存在しません。
  • catalog — ワークスペース自身のカタログが保持する Components のビューです。インポーター自体が選択されたカタログ(ワークスペースのカタログフォルダ、またはワークスペースがそれを指定しない場合は、そのデフォルトレジストリが公開してこのマシン上に保持されているカタログスナップショット)を示し、ビュー自体のためには何も取得しません。その components リストは Component 名ごとに 1 エントリを持ち、名前順にソートされます。カタログが Component の複数のバージョンを保持する場合、エントリは、バージョンを指定せずにその名前を参照したときに解決されるバージョンを記述します。各エントリは、Component の name と version、その labels、その values と provides が宣言するトップレベルのキー名(values と provides、それぞれソート済み)、およびその sockets(それぞれソケットの name と、そこを通して配線される依存関係が満たすべきラベルの selector)を Component が宣言する順に持ちます。別の Component を拡張する Component は、宣言するものに加えて継承するものも持ち、継承するソケットが先に来ます。ビューが保持するのは名前、バージョン、ラベル、セレクターのみで、値、デフォルト、シークレットは決して含まず、順序は固定されているため、1 つのカタログからは 1 つのバイト列が得られます。カタログが Component を保持しない場合は存在しません。

出力の形(ゲスト → ホスト)。 インポートが生成したエンティティ(それぞれ既存のカタログエンティティへの参照か、ドラフトされた本体)、その背後にあるマッピングの判断、共有の Diagnostic の形での診断、書き出すスキャフォールドファイル、およびインポートを完了できなかった場合の失敗の error を持つ ImportOutput ドキュメントです。すべてのフィールドとその制約は、生成されたインポーターソケットのスキーマリファレンスにあります。

ワイヤエンコーディング。 入力と出力はどちらも canonical CBOR(RFC 8949 §4.2.1)として送られます。ゲストは、キットの ImportInput と ImportOutput がすでに持つエントリポイント(Go では DecodeCBOR と EncodeCBOR、Rust では decode_cbor と encode_cbor、TypeScript では decodeCBORImportInput と encodeCBORImportOutput)を通して入力をデコードし、出力をエンコードし、バイト列を読み書きします(Rust では Vec<u8>、TypeScript では Host.inputBytes() と Host.outputBytes(...))。CBOR ライブラリは不要で、バイト列を手作業でパースすることもありません。settings はバイナリドキュメントの中で JSON ドキュメントのバイト列として渡されるため、ゲストは他のすべてのソケットと同様に、中身を見るには JSON としてパースします。完了できないインポーターは出力の error で理由を示し、インポートはそのインポーターとメッセージを示して停止します。このエンコーディングの ImportOutput ではない応答(JSON で書かれたもの、または形が宣言しないトップレベルフィールドを持つもの)も、インポーターとその import エクスポートを示してインポートを停止させます。aggrega plugin run-local --export import で直接呼び出すと、インポーターには記述された JSON ペイロードをこのエンコーディングに変換したものが渡され、その応答はエクスポートの出力形式として読み取られて JSON として出力されます。その形式でない応答は、ビルドが拒否するのと同様に、エクスポートを示して拒否されます。

自分のフォーマットのソースがどのように認識されるか。 インポートがフォーマットを指定しないこともあり、その場合ホストは、自身はフォーマットを何も知らずに、インポーターが宣言する内容からフォーマットを認識します。インポーターは describe() の自己報告の importer(ImporterContract)の下に、そのフォーマットのソースを認識するためのシグネチャの detect リストを宣言します。各 DetectSignature は次を指定します。

  • syntax — ソースをパースする構文上のフォーマットで、パーサープラグインが parse:<syntax> として公開するフォーマットです(json や yaml など)。
  • files — ソースの名前の末尾に対して照合される、省略可能なファイル名パターンです。1 つのセグメントはファイル自身の名前に対して、スラッシュ区切りの複数のセグメントはパスの末尾の同数のセグメントに対して照合され、*、?、[...] はセグメント内で照合します。何も宣言しないシグネチャは、名前にかかわらず 1 つのファイルであるソースに適用され、ディレクトリのファイルには適用されません。
  • match — パースされたツリーがすべて満たすべき述語で、それぞれが PathMatch です。ツリーの最上位からドットでつないだキーの path(整数のセグメントは配列の位置を選択します)、present、absent、object、array、string、number、boolean のいずれかである is、そして省略可能な equals 文字列または prefix 文字列(2 つのうち最大 1 つ)を持ちます。

インポートがフォーマットを指定しない場合、ホストは、インポートが選択対象とするすべてのインポーター(ワークスペースのカタログにあるものと、コンパイラの core importers)のシグネチャを、ID とバージョンの順に照合します。ホストは、構文ごとにカタログが提供するパーサー(カタログがパーサーを提供しない構文については、コンパイラ自身が持つもの)で、構文ごとに最大 1 回ソースをパースし、ツリーに対して述語を評価し、シグネチャが一致した唯一のインポーターのフォーマットとしてソースを読みます。インポーターの aggrega_parse_source 呼び出しに応答するのも同じパーサーであるため、インポーターは認識に使われたパーサーを通してソースを読みます。ある構文でパースできないソースは、その構文を指定するどのシグネチャにも一致しません。カタログもコンパイラもパーサーを提供しない構文は、パーサーがないことを示して認識を停止させます。どのシグネチャにも一致しないソースはフォーマットの指定を求めて拒否され、複数のフォーマットとして認識されたソースはそれらを示して拒否されます。シグネチャは、そのインポーターが公開するすべてのフォーマットとしてソースを認識するため、ソースを認識させたいインポーターは 1 つのフォーマットを提供し、シグネチャを宣言しないインポーターにはフォーマットを指定することでのみ到達できます。

インポーターの Plugin エンティティは同じリストを spec.importer.detect として記録します。これは、エンティティがゲストから生成される際に describe() から導出されます。認識処理はこの記録を読むため、フォーマットが確定するまでゲストはロードされません。ゲストのロードおよび公開では、自己報告がエンティティの記録と異なるものは importer.detect を示して拒否され、何も記録していないエンティティは何も主張しません。ディスクリプタは、インポーターではないプラグインにこのコントラクトが宣言されている場合、シグネチャが構文を示していないか不正なファイルパターンを示している場合、そして述語がパスを示していない場合、7 種類以外の is を示している場合、または equals と prefix の両方を示している場合に、ロード時に拒否されます。

コンパイラのコアインポーターと Go キットの import サンプルは、このようにシグネチャを宣言しています。Langflow インポーターはソースを JSON として読み、data.nodes に配列を求めます。Flowise インポーターは nodes と edges に配列を、data.nodes には何もないことを求めます。n8n インポーターは nodes に配列、connections にオブジェクト、edges と data.nodes には何もないことを求めます。MCP インポーターはクライアント設定ごとに、そのファイルを示すシグネチャを 1 つずつ宣言します。.mcp.json、claude_desktop_config.json、.cursor/mcp.json は JSON として読まれ mcpServers にオブジェクトを求め、.vscode/mcp.json は Visual Studio Code が読むのと同様にコメント付き JSON として読まれ servers にオブジェクトを求めます。さらに、ファイルを示さず、https://static.modelcontextprotocol.io/schemas/ で始まる $schema 文字列を求めるシグネチャを 1 つ宣言します。Compose インポーターはソースを YAML として読み、Compose がデフォルトで読むファイル(compose.yaml、compose.yml、docker-compose.yml、docker-compose.yaml とその 4 つのオーバーライドファイル)を示し、services にオブジェクトを求めます。Dify インポーターはソースを YAML として読み、ファイルを示さず、kind に文字列 app を、app.mode と version に何らかの値を求めます。CrewAI インポーターは、ツリーに何も求めない YAML として読む config/agents.yaml と config/tasks.yaml、agents にリストを求めるコメント付き JSON として読む crew.jsonc と crew.json、role に何らかの値を求めるコメント付き JSON として読む agents/*.jsonc と agents/*.json を示します。そのため、これらのうち 2 つが同じソースに一致することはなく、フォーマットを指定せずに単独でインポートされたファイルは JSON としてだけでなく YAML としても読まれます。LangGraph インポーターは、graphs にオブジェクトを求める JSON として読む langgraph.json を示し、ファイルを示さず graphs にオブジェクトを、$schema に文字列 https://langgra.ph/schema.json を求めるシグネチャを 1 つ宣言し、環境ファイルは示しません。認識処理はいずれかのインポーターのパターンが選択するすべてのファイルを読むため、環境ファイルを示すパターンがあると、フォーマットを指定せずにインポートされるすべてのディレクトリの環境ファイルが開かれてしまうからです。Google ADK インポーターは、name と instruction に何らかの値があるか、agent_class に文字列があり name に何らかの値がある YAML として読む root_agent.yaml を示し、それ以外のファイルは示しません。サブエージェントの設定ファイルはどのような名前でもよく、すべての YAML ファイルを示すパターンがあると、フォーマットを指定せずにインポートされるすべてのディレクトリの YAML ファイルがそれぞれ開かれてしまうからです。Agent Framework インポーターはソースを YAML として読み、ファイルを示さず、kind に文字列 Prompt を、model にオブジェクトを求めます。Go キットの import サンプルはソースを YAML として読み、kind に文字列 DemoSource を求めます。Go では次のとおりです。

Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{
Syntax: "json",
Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},
}}},

ディレクトリのインポートで読まれるもの。 ソースはディレクトリでもよく、何を読むかはインポーターが宣言したファイルパターンが決めます。ホストは、ディレクトリ内の任意の深さにあるファイルのうち、インポーターのシグネチャの files パターンのいずれかが選択するもの(それぞれディレクトリ内でのスラッシュ区切りパスの末尾と照合されます)だけを読み、bytes を空にし、ディレクトリ自身の名前を name として、名前順に sources として渡します。ディレクトリのそれ以外のファイルは開かれません。ワークスペースのビルドがレンダリング済みファイルを書き込むフォルダ(ワークスペースのルート直下の dist/)は、それを含むディレクトリの一部としては読まれません。そのファイルは 1 つも渡されず、認識にも使われず、そこへ通じるリンクは飛ばされます。そのため、ビルド済みのディレクトリはその中のプロジェクトとして読まれ、そのフォルダ自体であるディレクトリやその内部にあるディレクトリは、指定されたとおりに読まれます。files パターンを宣言していないシグネチャはディレクトリのファイルを 1 つも選択しないため、パターンを宣言していないインポーターは 1 つのファイルを読み、ディレクトリは拒否します。また、パターンが選択するファイルを 1 つも含まないディレクトリも拒否されます。ディレクトリはその内部に閉じられます。読み込む対象のファイルの中にあるリンク、またはディレクトリへのリンクのうち、ディレクトリの外に出るものは、何かが読まれる前に拒否されます。ディレクトリへのリンクがたどられることはなく、どのパターンにも選択されないファイルへのリンクは読まれずに飛ばされます。ディレクトリのフォーマットの認識も同じ規則に従います。各シグネチャは、そのパターンが選択するファイルに対して名前順に試され、各ファイルは構文ごとに最大 1 回だけ読まれて解析されます。パターンを宣言していないシグネチャはそのいずれにも適用されません。ホストは何も上限を設けません。インポーターにとって大きすぎるディレクトリは、インポーター自身のランタイム制限によって拒否されます。コンパイラの Langflow、Flowise、n8n、Dify、Agent Framework の各インポーターはいずれも files パターンを宣言しないため、それぞれ 1 つのファイルを読みます。MCP インポーターは 4 つのクライアント設定の名前を宣言するため、ディレクトリが含むそれらすべてを読みます。Compose インポーターは 8 つの Compose ファイル名を宣言するため、ディレクトリが含むすべての Compose ファイルを渡され、Compose が読むものをマージします。CrewAI インポーターは CrewAI プロジェクトの宣言が書かれる 6 つの名前を宣言するため、プロジェクトの宣言を渡され、プログラムは一切渡されません。LangGraph インポーターは langgraph.json を宣言するため、アプリケーションの設定を渡され、コードや環境ファイルは一切渡されません。環境ファイルは、アタッチメントの with.sources の下でのみ渡されます。Google ADK インポーターは root_agent.yaml を宣言するため、アプリケーションのルートエージェント設定を渡され、コードや環境ファイルは一切渡されません。サブエージェントが示す設定は、アタッチメントの with.sources の下でのみ渡されます。

型定義。 インポーターのワイヤ型(ImportInput、ImportSource、CatalogProjection、CatalogComponent、CatalogSocket、ImportOutput、およびそれが運ぶエンティティ、決定、スキャフォールドの形)は、3 つすべての ABI パッケージで公開され、各言語のプラグイン開発キットから再エクスポートされます。これらは 1 つのコーデックから生成されるため、3 つは常に一致します。describe の自己報告が運ぶ認識用の型 ImporterContract、DetectSignature、PathMatch も同様です。Go キットのインポーターパッケージ github.com/aggrega-ai/aggrega-pdk/go/pkg/importer は、フォーマットにかかわらずインポーターが行うすべてを備えており、すべてこれを基に構築されたコンパイラのコアインポーターは、この方法で入力を読み、出力を書きます。

Go キットを基に構築されたインポーターが何に対してスコアを付けるか。 キットのスコアラーは、各ソースノードを catalog ビューの Components に対してのみ評価し、それ以外には評価しません。候補はワークスペース自身のカタログ(エンタープライズカタログの Components も標準ライブラリのものとまったく同様に扱われます)であり、キットは独自の候補を持ちません。各 Component からは、名前、component.aggrega.ai/category ラベルが示すカテゴリ、ラベル、および values が宣言するキー名を読みます。provides のキーとソケットは評価されません。カタログに追加された Component は、インポーターを再ビルドすることなく、次回のインポートから候補になります。カタログに Component がないためにビューが存在しない場合、どのノードにも候補はありません。参照もヒントもされず、ドラフトが独自の Component を与えるすべてのノードはドラフトされます。キットを通じてスコアを付けるすべてのインポーター(コンパイラの Langflow、Flowise、n8n、Compose の各インポーターを含む)はこの方法でスコアを付けます。一方、MCP インポーターは候補を評価しません。キットを使用しないインポーターは、ビューを任意の方法で読みます。

Go kit 上に構築された importer がプラットフォームのソケットを読む目的。 ソケットはスコアには一切影響しませんが、kit はドラフトをレイアウトするためにそれらを読みます。プラットフォームがフローを記述されたとおりに実行する形式(Langflow、Flowise、n8n の形式がそうです)は、デフォルトでは、フローを保持するそのプラットフォームの Component の 1 つのインスタンスとしてドラフトされます。フローの各部分は、プラットフォームの catalog エントリが sockets を列挙する順序で、その部分の Component のラベルが(ビューが保持するラベルとして)selector を満たす最初のソケットに接続されます。読まれるのはセレクタとラベルのみで、kit は独自のセレクタ文法を持たないため、セレクタは importer が提供する関数によって照合されます。ビューにプラットフォームの名前を持つ Component が含まれない場合、どの部分も接続されません。コア importer では、コンパイラの Langflow、Flowise、n8n の各 importer がこの方法で作成するドラフトと、代わりにすべてのノードをそれぞれ独自の Component としてドラフトする layout 設定について説明しています。

現在のステータス: 利用可能 — aggrega import、およびエディタセッションとアシスタント向けツールにおける同じ操作によってディスパッチされます。

配置基準: linter ソケットとガバナンス判定ロール

文書化されているソケットのうち 2 つは似たインターフェースを持ち、どちらもルールごとの結果を出力しますが、パイプライン内の配置とゲーティングのセマンティクスが異なります。ある検査をどちらのソケットが担うかを決める基準は次のとおりです。

  • ガバナンス判定ロール(インバンド、ビルドを停止する)。 ビルドを停止するポリシーのために予約されています。halt 判定はコンパイルパイプラインを停止し、ビルドは成果物を生成しません。ユースケースは、違反すると出力を適用することが安全でなくなるポリシーです。コンプライアンスゲート(PCI / SOC2 の境界配置)、トポロジーの不変条件(ゼロトラストのイングレス、境界をまたぐ認証)、認証情報フローの形(IR に平文のシークレットがないこと)などがあります。ポリシーは IR グラフ(ir-verdict、レンダリング前)またはレンダリングされた成果物(render-verdict、レンダリング後)を対象に推論します。
  • リンターソケット(アウトオブバンド、CI / IDE、助言)。 ベストプラクティスと発見性の検査のために予約されています。違反が疑わしいものの安全でないわけではないルールです。孤立したシークレット、未使用のパラメータ、非推奨のラベル語彙、コスト配分のためのタグの網羅性、命名の慣例からの逸脱などがあります。失敗すると助言の出力が生成されますが、ビルドは引き続き成果物を生成します。

配置基準を 1 つのルールで表すと次のようになります。検査がビルドを停止すべきなら、それはガバナンス判定ロールに属します。検査がパイプラインをブロックせずに作成者やレビュアーに警告すべきなら、それはリンターソケットに属します。

どちらも現在利用できます。リンターソケットは aggrega lint を通じて publishing-linter を実行します。ガバナンス判定ロールは、ワークスペースが判定ロールのプラグインを接続している場合に aggrega build の実行中にインバンドでディスパッチされます。判定ロールは独自の重大度を持つことに注意してください。ポリシー自体が、停止せずに助言する warn や info の判定を出力することもあります。そのため、上記の停止か助言かの線引きは検査全体の配置に関する指針であり、ポリシーが停止しかできないという意味ではありません。重大度モデルについてはガバナンスソケットのページを参照してください。

相互参照

  • policy-socket.md — governance ソケットの包括的な解説:4 つのロール、verdict の重大度、オペレーター入力チャネル、コンパイラに同梱される 2 つのエンジンのいずれかに向けたポリシーの記述、外部ポリシーエンジンのラップ、およびリファレンスゲスト。
  • core-importers.md — コンパイラ自身のインポーター(読み取る形式ごとに 1 つ):それぞれが読み取る内容、設定、およびコンパイラの各リリースに合わせた公開。
  • 10-status.md#compilation-pipeline-phases — ステータスページにおけるプラグインパイプラインの分類(Wasm プラグインパイプラインのランタイム準備状況)。
  • architecture/04-entity-taxonomy.md §「Domain 3: Infrastructure Base」 — 認証情報 FeatureRecipes のための Two-Part Plugin Principle(Fetcher + Injector パターン)。
  • architecture/13-catalog-and-registry.md — provider セグメントを先頭に置く OCI 分類体系。
  • entities/featurerecipe.md — FeatureRecipe の pipeline: 記述インターフェース。
  • when-to-use-a-pipeline-step.md — 判断ガイド:パイプラインステップとテンプレート化された FeatureRecipe の比較。
  • templates/expansion-matrix.md — プラグインパイプラインの pipeline: with: ブロックにおけるテンプレート評価ルールと .steps アクセスのセマンティクス。
  • examples/04-secrets.md — 認証情報 FeatureRecipe が取りうる Fetcher + Injector のパイプライン形状。
  • errors/error-translation.md — プラグインゲストが参加するエラー変換の規律。