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

Wasm プラグイン開発者ガイド

本ページは、Aggrega の WebAssembly (Wasm) プラグインを作成し、カタログエンティティとして公開するための正規のガイドです。プラグイン作成者の契約を最初から最後まで説明します。プラグインとは何か、プラグインがホストに対して自身をどのように記述するか、エクスポートとケイパビリティ宣言をどのように作成するか、ホストが適用するランタイム制限とホスト関数、プラグインをカタログに載せる Plugin エンティティ、Recipe または FeatureRecipe がプラグインをどのように参照するか、そしてディスク上の .wasm ファイルからビルドが利用する検証済みでダイジェスト固定されたアーティファクトまでプラグインを導く publish→pull→build のライフサイクルです。

関連ページの plugin-contract.md は ソケット、つまりプラグインが接続するパイプライン上の位置と、各ソケットが受け取り生成する入出力の形を説明しています。本ガイドは プラグイン、つまりエンティティ、ケイパビリティの範囲、ライフサイクルを説明します。プラグインがどのソケットを対象とするかは契約のページで確認し、それを作成して出荷する方法は本ページで確認してください。

リファレンスではなく作業全体を通した実例については、プロバイダーの作成で小さなプロバイダーゲストを一つ、最初から最後まで構築します。記述子、ビルド、エンティティ、アタッチ、そして出力を読める形でのレンダリングまでを扱い、最初の草稿が通常受ける拒否とその読み方も含みます。

1. Wasm プラグインとは

Wasm プラグインは、指定されたソケットでコンパイラを拡張する WebAssembly モジュールです。Go のホストバイナリには、クラウド固有のロジックやインフラストラクチャのロジックは含まれていません。テンプレートのレンダリング、フォーマット変換、ポリシー評価、リントといったドメイン固有の処理はすべてプラグイン内にあります。ホストはパイプラインを統括し、各ソケットのペイロードを ABI 境界を越えてゲストに渡します。ゲストはドメインの処理を行い、そのソケットの結果の形を返します。各ソケットのペイロードと結果はすべて正規形の CBOR でやり取りされますが、例外が 2 つあります。CLI プラグインは引数ベクトルを JSON テキストとして受け取り、終了コードとストリーム出力するテキストで応答します。また、describe の自己申告は JSON テキストです。各ソケットのエンコーディングはプラグイン契約の該当ソケットのセクションに記載されており、ゲストはキットのペイロード型がすでに備えているエントリポイントを通じて読み書きするため、ゲストがバイトを手作業で解析することはありません。

プラグインは事前(AOT)純粋性のファイアウォールの内側で実行されます。ホストは、ケイパビリティを拒否する設定のもとで、組み込みの Wasm ランタイムを通じてモジュールをロードし実行します。ネットワークソケット、ファイルシステム、環境変数はいずれも使用できず、標準入出力は破棄され、観測可能な実時間クロックはビルドに依存しない時刻に固定されます。ゲストが試みる I/O 呼び出しはすべて呼び出し境界で失敗するため、プラグインがランタイムの状態に手を伸ばすことはできません。このファイアウォールを念頭に置いてプラグインを作成してください。プラグインは渡されたペイロードを変換し、ホストがそのまま利用する結果を返します。決定性は作成者の責任であり、同一の入力は同一の出力バイトを生成しなければなりません。リモートのコンテンツを扱う唯一の正式な経路は、ホストが仲介する外部入力の取得(セクション 4)です。これはゲストにライブのネットワークアクセスを与えるのではなく、ダイジェストで固定する規律のもとでバイトを提供します。

プラグインが対象にできるソケット(トポロジー構築時のミューテーションゲート、静的解析時のバリデーションゲート、FeatureRecipe パイプライン、帯域外のリンター、プロバイダーのレンダリングソケットなど)と、ソケットごとの入出力の形は plugin-contract.md に記載されています。プラグインがどのソケットを担うかは、metadata.pluginType で宣言する 1 つの値で決まり、このフィールドが受け付ける値の全体は entities/plugin.md §「metadata.pluginType」のリファレンス項目に記載されています。このガイドの例では、provider(IR ノードをプロバイダー固有の成果物にレンダリングする)、linter(作成されたコンテンツを検査して診断を出す)、pipeline-step(FeatureRecipe または Recipe の pipeline: 内で、レンダリング済みドキュメントセットにパッチを当てるステップ)を使用します。

ゲストは、Go、Rust、TypeScript の 3 言語に対応したプラグイン開発キット(PDK)を使って、ホストに対して作成します。PDK は基盤となる Wasm ツールチェーンをラップし、各ソケットが扱う入出力の形に対応する Aggrega 型付きのビルダーを提供します。

2. describe() による自己申告

すべてのプラグインは、プラグインの自己申告を返す describe() 関数をエクスポートします。自己申告には、実装するソケットタイプ、対象とする ABI バージョン、主張するケイパビリティ(ソケットタイプに応じて解釈され、プロバイダーやパイプラインステップではケイパビリティ名、パーサーやインポーターではプレフィックス付きのソース形式となります)、インポートするホスト関数、そして提供する各エントリポイントのエクスポートごとのケイパビリティが含まれます。describe() は、プラグインが何であり何を行うかについてのプラグイン自身による説明です。

自己申告は信頼モデルの基盤です。プラグインをカタログに取り込む Plugin エンティティ(セクション 5)は、同じ事実を記述された主張として再度述べます。ホストは、エンティティの主張をプラグインの describe() の出力と 2 つの時点で照合します。1 つはパブリッシュ時で、レジストリにバイトが格納される前です。もう 1 つはロード時で、プラグインが実行される前です。不一致があると、明示的に処理が停止します。エンティティは人間が読める、カタログ上で参照できる表層であり、describe() はホストがそれを検証する際の正式な記録です。両者が一致するように記述してください。この照合は、まさに両者が食い違うケースを検出するために存在します。照合されるのはエンティティが主張する内容であり、主張から漏れている内容ではありません。バイナリが報告するよりも少ない内容しか主張しないエンティティ(たとえば、エクスポートを追加した再ビルドの後に取り残されたもの)は、バイナリが行うすべてをもはや記述していなくても、引き続きロードされます。

3. エクスポートとその機能クレームの記述

プラグインは 1 つ以上のエクスポートを提供します。エクスポートとは、ホストがディスパッチする名前付きのエントリポイントです(例: render_node、lint_naming、step)。各エクスポートは機能ブロックを持ちます。これは、そのエクスポートが何を行うかについての作成者のクレームです。エクスポートの機能には 4 つのフィールドがあります。

  • name — エクスポートの ABI 名で、ホストがディスパッチする先の名前です。必須です。
  • operates — エクスポートが実行するパイプライン操作です。patch(既存のレンダリング済みドキュメントを変更する)または emit(新しいドキュメントを追加する)のいずれかです。これは宣言された機能クレームです。ホストは公開時とロード時に、これをプラグインの describe() 自己申告と照合するため、エンティティに記述されたクレームとプラグイン自身の申告は一致している必要があります。これはエクスポートについての検証されるクレームであり、ディスパッチの切り替えではありません。レンダリング時にステップが実際に実行する操作は、ゲストが返す結果によって伝えられ、このフィールドから選択されるわけではありません。省略した場合、操作のクレームはありません。
  • scope — エクスポートが操作するドキュメントのルートです。own(ノード自身のレンダリング済みドキュメント)または host(コンポーネントスコープの FeatureRecipe がアタッチされているコンポーネントのドキュメント)のいずれかです。パイプラインステップのプラグインが実行される前に、ホストはステップで宣言されたエクスポートスコープを読み取り、そのスコープのドキュメントをレンダリングする provider がプラグインの spec.pipelineStep.capabilities(セクション 5)に含まれていることを強制します。own スコープのエクスポートはノード自身のドキュメントをレンダリングする provider と照合され、host スコープのエクスポートはホストコンポーネントの provider と照合されます。スコープが空の場合、このチェックでは own が既定となります。これが provider 互換性ゲートで、ステップより前に実行されます。ゲストの操作が実際に扱うドキュメントは、ゲストが返す結果の中で操作ごとに指定され、この宣言フィールドから選択されるわけではありません。省略した場合の既定は own です。
  • selector — エクスポートが何に作用するかを記述した、自由形式で人間が読める説明です(例: workloads carrying a pod template)。カタログの読者と aggrega inspect の表示のためのドキュメントであり、コンパイラはこれを解釈しません。

エクスポートは読ませたい順序で記述してください。エントリはエンティティ上でも inspect でも作成者の順序を保持します。エクスポートが記述されていないプラグインは、エクスポートの表面を宣言しません。これは、ソケットがエクスポートごとの機能クレームを必要としないプラグインでは有効です。

4. ランタイムの制限とホスト関数

plugin エンティティは、ホストがプラグインをロードして実行する方法を制約する、省略可能な runtime ブロックを持つことができます。

メモリと時間の制限。 maxMemoryPages はプラグインの線形メモリを Wasm ページ単位(1 ページあたり 64 KiB)で制限します。timeoutMs は、1 回の呼び出し中にプラグイン自身のコードが実行できる時間をミリ秒単位で制限します。プラグインが呼び出すホスト関数の内部で費やされた時間はこれに含まれません。Linux では、ゲストを実行するスレッドのプロセッサ時間で計測されるため、負荷の高いマシンでゲストがプロセッサを待つ時間も含まれません。その他のシステムでは経過時間で計測されます。新たにロードされたプラグインへの最初の呼び出しには、ゲスト言語ランタイムの 1 回限りの初期化も含まれます。この初期化はその呼び出しの中で実行されるためです。どちらの制限もデフォルト値付きの省略可能な項目で、ゼロまたは省略の場合はプラットフォームのデフォルト上限が適用されます。エンティティが何も宣言しない場合、ローダーはすべてのプラグインにプラットフォームのデフォルト上限を適用するため、ロードが無制限になることはなく、呼び出しがキャンセル不能になることもありません。アタッチメントがデフォルトで許容される以上のメモリや時間を本当に必要とする場合は、エンティティで制限を引き上げてください。

ホスト関数。 hostFunctions は、プラグインがインポートするホスト関数名を記録します。これは機械的に導出されるフィールドであり、記述しないでください。 aggrega plugin sync は .wasm のインポートセクションからホスト関数を直接読み取り、そのフィールドをエンティティファイルに自動で記録します。publish はバイナリからホスト関数を再導出し、記録が異なるエンティティを拒否します。そのため、プラグインはそのバイナリが実際にインポートするホスト関数をちょうどそのまま得ます。これは厳選された許可リストに照らして検証されます(許可リスト外のインポートは明示的に拒否されます)。この記録は公開されたバイナリのスナップショットであり、コンテンツアドレス方式の plugin: 参照が公開されたバイト列のスナップショットであるのと同じです。publish 時点のバイナリを反映し、プラグインが pull されるときに再導出されて検証されます。公開前にローカルの .wasm がインポートするホスト関数(aggrega plugin sync が記録する値)を確認するには、aggrega inspect --plugin <file.wasm> を実行します。

厳選されたホストサーフェス。 ホスト関数のうち 3 つは汎用です。aggrega_log(レベルとメッセージを受け取り、ホストのログ出力先に 1 行のログとして出力します)、aggrega_emit_warning(コード、メッセージ、パスを受け取り、呼び出し後にホストが提示する構造化された警告として蓄積します)、aggrega_fetch_external_input(URL を受け取り、後述のピン留めの規律のもとで入力のバイト列を返します)です。PDK はこの 3 つを各言語でラップしています。Go: aggrega.Log、aggrega.EmitWarning、aggrega.FetchExternalInput、Rust: log、emit_warning、fetch_external_input、TypeScript: log、emitWarning、fetchExternalInput です。これにより、ゲストは生の ABI ではなく型付きの関数を呼び出します。ソースとパースのコールバック(取得したソースのスライスを読み取る、またはホストを通じてパース済みツリーを取得するゲスト向け)と、各コールバックのスロットが持つエンコーディングは、plugin-contract.md に記載されています。

ローカルのソースコンテンツはホストを通じて渡され、ファイルシステムからは決して読み取られません。 provider の render プラグインがソースをディスクから読むことはなく、ファイルシステム呼び出しは呼び出し境界で失敗します。ホストは render ペイロードの中でソース一覧をゲストに渡します。これは、各エントリのソースルートからの相対パスとそれがディレクトリかどうかをソート順に並べたもので、ファイルの内容は含みません。ゲストはそれに独自のレイアウトロジックを適用し、選択したファイルだけをソースコールバックを通じて読み戻します。コールバックは、ホストがソースルート配下で読み取ったバイト列を返します。ソケットごとのペイロードの形とコールバックは plugin-contract.md に記載されています。

リモートコンテンツは外部入力フェッチを通じて取得されます。 リモートコンテンツ(チャートアーカイブ、リモートのスキーマドキュメントなど)を必要とするプラグインは、PDK のフェッチラッパーを呼び出します。ワイヤ上では、ゲストは URL を UTF-8 テキストとして aggrega_fetch_external_input に渡し、正規 CBOR の応答を 1 つ受け取ります。応答には、取得した生のバイト列か、機械で照合可能なコードを伴うエラーメッセージのいずれかが含まれます。ラッパーはこの応答をバイト列またはエラーにデコードします。バイト列は取得されたとおりに届き、有効な UTF-8 でないペイロードも含まれます。長さゼロのペイロードはエラーではなく空のバイト列として返されます。ホストは外部入力のピン留めの規律のもとで URL を提供します。

  • Release のロックファイルですでにピン留めされている URL は、ローカルのコンテンツアドレス方式ストアから提供され、読み取りのたびに記録されたダイジェストに照らして検証されます。ストアに blob がない場合は、記録されたダイジェストによりネットワークから再取得されます。ダイジェストで検証された再取得が出力を変えることはありません。
  • ピン留めされていない URL は、その URL と対処方法を示すエラーとともに拒否されます。ビルドはロックファイルが記録するクロージャをレンダリングするため、ピン留めされていない参照をフェッチするビルドはなく、それを可能にする設定もありません。
  • ピン留めは Release の依存関係を解決するときに行われます。aggrega pull は Release をレンダリングしてそのレンダリングがどの外部入力を要求するかを調べ、それぞれをフェッチして、依存関係のピンと並べてロックファイルに記録します。したがって、プラグイン作成者の作業ループは、一度解決し、その後は何度でもオフラインでビルドする、というものになります。

許可されるスキームは、https、ループバックホストに限った http、および oci(manifest ダイジェストでピン留め)です。ロックファイルはピン留めされたすべての入力(URL、sha256 ダイジェスト、サイズ、それを必要としたプラグイン)を記録するため、再ビルドではローカルストアから同じバイト列が提供されます。再現可能であり、一度ピン留めすればオフラインで動作します。

Go PDK の場合:

import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")
if err != nil {
// The error names the URL and the remedy — an unpinned URL reports exactly
// what to pin and how. Surface it as a render failure; do not mask it.
return fmt.Errorf("fetching chart archive: %w", err)
}

何が失敗し、なぜ失敗するか。

  • ファイルシステムやネットワークの呼び出しは呼び出し境界で失敗します。ゲストは事前オープンされたディレクトリもソケットも持たないためです。これはファイルを読もうとするライブラリ依存関係を含め、すべてのコードパスに当てはまります。代わりにソースコールバックを通じてソースを読んでください。
  • wasi_snapshot_preview1、extism:host/env、extism:host/user 以外のモジュールに属するインポートは、モジュールとインポートを示す診断とともにロード時に失敗します。許可されたモジュール内の個々の WASI 関数名が検閲されることはありません。静的リンクされた言語ランタイムの未使用のファイルシステムやソケットのインポートは問題ありません。インポートを名指しすること自体は何の権限も与えないためです。
  • ロックファイルがピン留めしていない URL のフェッチは、その URL を示すエラーで失敗します。対処方法は、Release のレンダリングが使用するすべての外部入力をピン留めする aggrega pull --release <release> を実行してからビルドすることです。

外向きのネットワークアクセスのためのホスト許可リストのフィールドはありません。プラグインがビルド時にネットワークに到達することはなく(これが事前コンパイルの境界です)、したがって記述すべきそのようなフィールドは存在しません。リモートコンテンツは、上記のホストが仲介するダイジェストでピン留めされた外部入力チャネルを通じて届き、環境的なネットワークアクセスを通じて届くことはありません。

設定。 configKV は、ランタイムが開始時にプラグインに渡す文字列から文字列へのマップです。エントリは記述順を保持するため、出力されるレコードは実行ごとにバイト単位で同一になります。省略した場合は、ランタイムのデフォルトの空の設定が有効なままになります。

5. Plugin エンティティ

プラグインは Plugin エンティティとしてカタログに登録されます。これはプラグインのオーサリングとメタデータの窓口です。エンティティはプラグインが何であるかを宣言し、.wasm アーティファクトを指し示します。コンパイラはプラグインの振る舞いを解釈せず、固定された参照を受け渡すだけであり、バイト列は Wasm ランタイムが実行します。

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

フィールド:

  • アーティファクトの場所を示すフィールドは、意図的に存在しません。 エンティティは .wasm へのポインタを持たず、スキーマもそれを受け付けません。プラグインのアーティファクトの場所は、そのアイデンティティ、すなわちリポジトリパス plugin/<pluginType>/<name> を構成する metadata.pluginType/metadata.name の座標と、ワークスペースが設定されているレジストリとから導出されます。そのため、記述すべき場所も、誤る余地のある場所もありません。解決されたコンテンツダイジェストは Release ごとにその Release のロックファイルに記録され、ビルドは取得したバイト列をそれに照らして検証します。アイデンティティはエンティティに、検証済みのバイト列はロックファイルにあります。
  • metadata.version — エンティティが公開するリリースです。describe() で報告されるゲスト自身のビルド来歴バージョンと一致している必要があります。プラグイン作成者はビルド時に .wasm にバージョンを付けます。ビルドはゲストにバージョンを刻み込み、リリースタグからバージョンを取得するビルドは、そのタグが指すコミットでのみリリースバージョンを刻みます。そしてエンティティの metadata.version は同じリリースを指します。公開の入口では両者が照合され、食い違いがあれば停止するため、エンティティは常に、自身が配布するバイナリの正確なバージョンを指します。aggrega plugin gen-catalog --plugin(後述)は、ゲストが報告するバージョンを生成するエンティティにコピーします。ゲストがタグ付きコミットからビルドされていれば、これはリリースバージョンになります。必須です。
  • metadata.pluginType — このプラグインが実装するソケットの種類で、provider、linter、pipeline-step、governance、cli、parser、importer から選びます。プラグインはちょうど 1 つを実装します。アドレス指定ブロック内で name と version の隣に置かれ、導出される座標の <pluginType> セグメントを提供します。必須です。
  • spec.abiVersion — プラグインが対象とするホスト/ゲスト間の ABI バージョンです。受け付けられる値は v1beta1 です。将来の ABI 改訂で受け付けられる値が追加されます。必須です。
  • ソケットの種類に対応するブロック(capabilities を持つ) — プラグインは、自身の metadata.pluginType に属するブロックの中で何を提供するかを宣言し、エントリの意味はそのブロックによって決まります。spec.provider.capabilities はプロバイダが提供するケイパビリティ(helm や compose などのケイパビリティ名)を挙げます。spec.pipelineStep.capabilities は、ステップがレンダリング出力と互換性を持つプロバイダを挙げます。spec.parser.capabilities はパーサーが読み取るソース形式を挙げ、各エントリは parse:<format> と書きます。spec.importer.capabilities はインポーターがエンティティの下書きを作成する外部形式を挙げ、各エントリは import:<format> と書きます。Go で書かれたインポーターは、形式に依存しないすべての部分(スコアリング、参照するか下書きするかの判断、下書きとそのレンダリング、および設定)を Go キットのインポーターパッケージ github.com/aggrega-ai/aggrega-pdk/go/pkg/importer から利用できます。linter、governance、cli のプラグインはケイパビリティを提供せず、4 つのブロックのいずれも持ちません。エントリは記述順を保持し、すべてのリストは明示的でテスト済みの主張です。利用者はリストに記載されたものに対してそのまま解決するため、実際にビルドしてテストした対象を宣言してください。パイプラインステップの場合、この主張はレンダリング時に強制されます。ステップがあるスコープに触れると、そのスコープのドキュメントをレンダリングするプロバイダがプラグインの主張するものに含まれていない限り、ビルドは停止します。したがって、空のリストはどのプロバイダにも一致せず、ステップはどこにも受け入れられません。
  • spec.signature — プラグインに添付された署名(セクション 8)を指す、任意の記述的なポインタです。このブロックはドキュメントとしてのみ機能し、署名の所在と生成方法をカタログの読み手のために記録します。このブロック自体がプラグインを受け入れるわけではありません。強制力を持つチェックは、プル時に適用されるレジストリごとの信頼ポリシーです。
  • spec.runtime — セクション 4 で説明した任意の実行制約ブロックです。作成者は maxMemoryPages、timeoutMs、configKV を記述します。hostFunctions は機械的に導出され、aggrega plugin sync によって記録されて publish が検証するもので、作成者が記述するものではありません。
  • spec.exports — セクション 3 で説明したエクスポートごとのケイパビリティの主張(name、operates、scope、selector)です。

.wasm からのエンティティの生成。 エンティティのうち機械が管理する部分を手書きする必要はありません。aggrega plugin gen-catalog --plugin <file.wasm> はゲストの describe() 自己報告を読み取り、それと、利用者が用意する小さな記述済みオーバーレイ(アイデンティティ、ランタイム制限、およびプロバイダブロック)から、公開可能な Plugin エンティティを生成します。ジェネレーターは、バイナリが信頼できる情報源となるフィールド(エクスポートの主張、ケイパビリティの契約、コマンドのミラー、ホスト関数の記録)を刻み込み、metadata.version をゲストの describe() のビルド来歴バージョンからコピーします。オーバーレイはバイナリが報告しないものだけを提供します。これはサードパーティのプラグイン作成者向けのサポートされた手順です。.wasm をビルドしてバージョンを付け、その後エンティティを再生成することで、機械が管理するフィールドをバイナリと常に一致させます。バージョンは、バイト列に関する事実ではなくリリースを指す唯一のコピーされるフィールドです。そのため、リリースのタグが指すコミットのビルドから生成するか、開発ビルドから始める場合は、エンティティを含むコミットにタグを付ける前に、生成されたエンティティの metadata.version をリリースに設定してください。ビルド来歴バージョンを持たないゲストからは、バージョン付きのエンティティを生成できません。まずビルド時にゲストにバージョンを付けてください。

エンティティの隣にある .wasm。 プラグインを作成している間は、ビルドが取得できるものはまだ何も公開されていないため、ビルドはカタログディレクトリ内の Plugin エンティティの隣から、エンティティのプラグインタイプと名前から導かれる名前でプラグインの .wasm を読み取ります。pipeline-step/patch の場合は pipeline-step--patch.wasm です。小文字、数字、ほとんどのハイフンはそのままその名前に書き込まれます。それ以外の文字はエスケープされた形で書き込まれ、いくつかの位置にあるハイフンも同様です — そのため、問題になる場合には、.wasm が見つからないときの拒否である A plugin’s .wasm is not on this machine (プラグインの Wasm モジュールがこのマシン上にありません) が名前を完全な形で示します。aggrega lint <plugin.yaml> は、バイナリ自体がそのプラグインを持っている場合を除き、同じ場所 — 渡されたエンティティファイルの隣、そのファイルがどのディレクトリにあっても — から .wasm を読み取り、.wasm が報告するのにエンティティが省いているエクスポート、ケイパビリティ、コントラクトごとに通知を出力します。そこに .wasm がない場合、lint はそのレポートをスキップしたことを、探したファイルとディレクトリを示して伝え、その結果は変わりません。

フィールドごとのリファレンスについては、エンティティのページ ../entities/plugin.md を参照してください。

6. プラグインの参照

パイプラインステップやプラグインソケットは、プラグインを Plugin エンティティ URI で参照します。これはエンティティのアイデンティティであり、.wasm アーティファクトを直接参照するものではありません。エンティティはダイジェストの固定、ケイパビリティの主張、ランタイム制限、署名を持つ層であり、エンティティを参照することで、利用者はそれらすべてを取り込みます。

plugin フィールドに素の .wasm パスや生のアーティファクト参照を記述すると、ロード時に拒否されます。それに一致する Plugin エンティティが存在しないため、プラグインの解決は明示的に失敗します。エンティティ URI は必須です。エンティティを介した間接参照こそが契約であり、任意の利便機能ではありません。FeatureRecipe のパイプラインステップは pipeline[].plugin でエンティティを指定します。パイプラインのオーサリングについては ../entities/featurerecipe.md を参照してください。

2 つ以上のプラグインが結合している場合、つまり、一方のプラグインの出力が他方の入力となる Fetcher と Injector の組のように、共有の受け渡し契約について合意する必要がある場合(plugin-contract.md で説明されている Two-Part Plugin Principle)、その契約を一度だけ記述し、各プラグインがその単一の定義に依存するようにしてください。各プラグインで JSON の受け渡し形状を個別に書き直すべきではありません。共有される形状はプラグイン間でやり取りされる JSON 構造であり、両方のプラグインが参照する単一の SchemaLibrary エントリに置くことができます。契約の情報源を 1 つにすることで、契約が進化しても結合したプラグインの同期が保たれます。個別に書き直した定義は乖離し、その乖離は実行時に両者が一致しなくなって初めて表面化します。推奨されるのは契約を共有することであり、Wasm コードを共有することではありません。各プラグインはそれぞれ独立したアーティファクトのままです。

7. publish → pull → build のライフサイクル

プラグインは、ディスク上の .wasm ファイルから、ビルドで利用可能な検証済みアーティファクトへと 3 つの段階を経て移行します。

Publish. aggrega push は、Plugin エンティティとその .wasm を、metadata.version でタグ付けされた単一の OCI マニフェストとしてまとめて公開します。エンティティの YAML はマニフェストの config blob となり、.wasm は同じマニフェストのレイヤーとして含まれます。この組を 1 つのタグ付きマニフェストとして公開することで push がアトミックになります。一方だけが公開され、もう一方が公開されていない期間は存在しません。また、そのマニフェストに対する 1 つの署名で両方がカバーされるのもこのためです。両方ともマニフェスト上で名前が付けられているため、バージョンタグを pull する汎用の OCI クライアントは、エンティティを entity.yaml に、実行ファイルを entity.wasm に書き出します。

バイトが書き込まれる前に、publish はチェックを実行します。まずエンティティが、カタログのロード時と同じ方法で Plugin スキーマに照らして読み込まれます。そのため、セマンティックバージョンでない metadata.version、またはその他のスキーマからの逸脱は、.wasm が読み込まれる前に拒否されます。次に .wasm がロードされ、その describe() の自己申告が、エンティティに記述された機能宣言と照合されます。不一致があれば明示的に停止するため、公開されたエンティティが、同梱するプラグインの報告しない内容を主張することはありません。describe() のビルド来歴バージョンに、未コミットの変更を含むワーキングツリーからのビルドに付与される -dirty マークが付いているゲストは拒否されます。そのバージョンが指すコミットには、実際にビルドされた内容が含まれていないためです。コミットからビルドされた開発バージョン(1.0.0-3-g1a2b3c4)とプレリリース(1.0.0-rc.1)は公開されます。記録された metadata.version はゲストの describe() のビルド来歴バージョンと照合され、相違があれば publish は停止するため、両者は一致している必要があります。どちらの拒否も同じ方法で解消します。リリースのタグが指すコミットのクリーンなチェックアウトからプラグインをビルドし、リリースバージョンそのものを報告させます。新しいリリースの場合は、先にエンティティをそれがリリースするソースとともにコミットし、そのコミットにタグを付けます。開発ビルドが報告するバージョンをエンティティにコピーしても修正にはなりません。どのリリースタグも指さないバージョンでそのビルドを公開することになるためです。.wasm がインポートするホスト関数はバイナリから導出され、spec.runtime.hostFunctions にコミットされた記録と比較されます。相違があれば publish は停止し、このフィールドを再記録する aggrega plugin sync を案内します。このフィールドは機械が管理するものであり、publish がコミット済みのエンティティファイルを書き換えることはないためです。公開されたエンティティには、付与されたホスト関数の記録が含まれます。.wasm のコンテンツダイジェストは、この組が公開されるマニフェストの属性であり、エンティティに書き込まれるのではなく、利用側のために Release のロックファイルに記録されます。

Pull. aggrega pull は Release のすべての依存関係を解決し、すべてのカタログエンティティとリモートアーティファクトをバージョンとコンテンツダイジェストに固定する Release ごとのロックファイルを書き出します。公開された Plugin はこの依存関係解決によって解決されます。その .wasm はそれを含むマニフェストとともに取得され、バイトはロックファイルに記録されたコンテンツダイジェストに照らして検証されます。pull はさらに、検証済みの .wasm からホスト関数を再導出し、付与された hostFunctions の記録と照合して、両者が一致しなければ停止します。これはダイジェスト固定に重ねた多層防御のチェックであり、記録が自身のインポートから生成されていないバイナリを検出します。レジストリのトラストポリシーが署名を要求する場合、エンティティの署名はこの段階で取得・検証され、検証済みの事実としてロックファイルに記録されます(セクション 8)。検証は pull 時に行われ、build 時には決して行われません。これによりビルドは事前(ahead-of-time)に純粋なまま保たれます。

Build. aggrega build は、解決済みの依存関係から固定・検証済みのプラグインを利用します。コンパイラがダイジェストで固定された参照をルーティングし、Wasm ランタイムがバイトを実行します。ロードゲートは、プラグインの実行前に describe() の照合と、ホスト関数およびランタイム制限の適用を再実行します。

8. 署名と信頼

Plugin エンティティは、他のすべてのカタログエンティティとまったく同じ方法で署名されます。マニフェストのダイジェストが署名され、OCI のリファラーとして添付されます。.wasm アーティファクトは個別には署名されず、個別の署名も必要ありません。これは署名対象のダイジェストを持つマニフェストそのもののレイヤーであるため、署名がそれを直接カバーします。.wasm を改ざんするとマニフェストのダイジェストが変わり、署名が無効になります。

署名は publish 時のオプトインです。検証は pull 時にレジストリごとの信頼ポリシーによって強制されます。署名を必須とするよう設定されたレジストリでは、必要な署名が欠落している場合、信頼されていない場合、または無効な場合に pull が停止します。エンティティの spec.signature ブロックは、署名の所在とその作成方法を示すドキュメント上のポインタです。カタログの読み手のために事実を記録するものであり、それ自体が受け入れを制御するものではありません。制御を行うのは pull 時のポリシーです。

コマンドとそのフラグは、公開および利用のインターフェースとあわせて文書化されています。../cli/aggrega-sign.md、../cli/aggrega-push.md、../cli/aggrega-pull.md を参照してください。本ガイドではフラグの表を再掲しません。コマンドのインターフェースについては、これらのページが唯一の参照先です。

9. エンティティのバージョニング

Plugin エンティティは、metadata.version に厳密なセマンティックバージョンを持ちます。公開済みのバージョンはイミュータブルです。レジストリにすでに存在するバージョンを異なる内容で再公開すると、公開ゲートで拒否されます。

プラグインエンティティを変更して再公開すると、公開の規律によって、その変更が以前に公開されたバージョンと比較して分類され、バージョンの引き上げがその分類に一致することが求められます。分類はバージョン引き上げの基準に従います。ドキュメントまたはコメントのみの変更は PATCH、厳密に追加的な変更(新しい任意フィールド、新しいエントリ)は MINOR、削除、型の絞り込み、または以前は任意だったフィールドが必須になる変更は MAJOR です。必要以上の引き上げは常に許可されます。不足する引き上げは、必要な引き上げを示す診断とともに停止します。エンティティの初回公開では引き上げのチェックが省略され、検証が行われなかったことを示す警告が表示されます。公開前に aggrega lint --pre-publish でチェックを実行してください。基準の全体とルールごとの設定については ../cli/aggrega-lint.md を参照してください。

Plugin には extends の仕組みがないため、カタログの Components と Features に適用される継承ルールは及びません。プラグインエンティティに適用されるバージョニングの規律は、バージョン引き上げの基準とイミュータビリティです。

10. 相互参照

  • authoring-a-provider-walkthrough.md — 1 つの provider ゲストを、空のディレクトリからレンダリング出力まで一貫して構築する手順です。
  • plugin-contract.md — plugin が対象とするソケットポイントと、ソケットごとの入出力の形です。
  • policy-socket.md — ガバナンスソケットの詳細です。4 つのロール、判定の重大度、オペレーター入力チャネル、コンパイラに同梱される 2 つのエンジンのいずれか向けのポリシーの書き方、およびリファレンスポリシーゲストを扱います。
  • core-importers.md — Go キットの importer パッケージ上に構築された、コンパイラ自身のインポーター(読み取る形式ごとに 1 つ)です。それぞれが読み込む内容、設定、およびコンパイラの各リリースでの公開について説明します。
  • ../compatibility.md — プラグインキットのバージョニングの仕組みと、あるリリースを対象にビルドしたプラグインが次のリリースでも読み込まれ続ける理由を説明します。
  • ../entities/plugin.md — Plugin エンティティのフィールドごとのリファレンスです。
  • ../entities/featurerecipe.md — エンティティ URI で plugin を参照する、FeatureRecipe の pipeline: オーサリングサーフェスです。
  • ../cli/aggrega-lint.md — 公開用リンター、バージョンバンプの基準、および不変性の強制です。
  • ../cli/aggrega-inspect.md — Plugin エンティティのケイパビリティ、ランタイム制限、署名の確認方法です。
  • ../cli/aggrega-push.md、../cli/aggrega-pull.md、../cli/aggrega-sign.md — 公開、利用、署名のコマンドサーフェスです。