言語リファレンス
Aggrega の「何であるか」と「どう使うか」を扱います。構文、CLI の呼び出し方、エラーカタログ、実例を収録しています。
初めて理解する際は、以下の章を順番に読んでください。リファレンスのサブディレクトリは各章の下に一覧されています。特定のエンティティ、キーワード、プロバイダ、CLI コマンド、またはエラーを調べる場合は、直接そこへ移動してください。
章を順に読む前に、現在の準備状況について 言語のステータス を参照してください。どの言語機能が現時点で利用可能か、どれが受け付けられるもののまだコンパイラによって処理されないか、どれが今後のイテレーションで予定されているかが記載されています。互換性 には、リリースがスキーマ、コマンドライン、アシスタントツール、エラーコード、プラグインキットについて何を約束するかが記載されています。
エンティティのティアモデル
Aggrega のオーサリング用エンティティ種別は、導入の進み具合を反映した 3 つのティアに整理されています(下表)。これらと並んで、プラットフォームが所有する Workload があります。Workload はそれ自体がオーサリング種別ではなく、Recipe の合成された入力がとる形であり、form: の語彙(stateless、stateful、daemon、scheduled、task、reference)によってコンピュートの形を表します。ティア分けはドキュメントとオンボーディングのための仕組みであり、実行時の制約ではありません。すべてのエンティティ種別は言語の第一級の要素であり、コンパイラはそれらを一様に扱い、オープンソースの Aggrega はライセンスや機能による制限なしにすべてのティアをサポートします。ティアの表示は、ナビゲーションのために「上級者向け。不要なら読み飛ばしてよい」ことを示すものであり、機能の有無を示すものではありません。
| ティア | エンティティ種別 | 導入の時期 |
|---|---|---|
| ティア 1 — 最小限の実用的な範囲 | Aggregate, Component, Recipe, Manifest, Release | 1 日目 — 個人の創業者や小規模なチームは、ティア 1 だけで動くソフトウェアを出荷できます。メンタルモデルは「アプリがある。それをデプロイしたい。その方法はこう。」です。 |
| ティア 2 — 役割の分離 | Feature, FeatureRecipe, Plugin | 30 日目 — 役割が分かれる小規模なチーム(開発者 + Ops + 場合によっては Security)。ティア 2 は、プロバイダのレンダリングを行う Plugins(Ops が Helm、helm-chart、Compose、Terraform、CloudFormation の中から選ぶ)、Features(Security が資格情報をアプリの設定とは別に管理する)、FeatureRecipes(プロバイダごとのバインド時のカスタマイズ)を通じて導入されます。 |
| ティア 3 — Component をまたぐ再利用 | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | 365 日目 — 共通の形が多数のエンティティにわたって繰り返し現れる、成熟したカタログ。しきい値は厳密なものではありません。ある形(例: PodResources)が 5 つ以上の Components に現れ、更新の調整が負担になったときに、SchemaLibrary のエントリを作る価値が生じます。 |
各段階への移行はオプトインです。個人の創業者がティア 3 を見ることを強いられることはなく、エンタープライズのカタログは必要に応じてティア 3 をすべて利用できます。ティア 1 は個人の創業者のユースケースにとって完結しており、開発者はティア 1 のエンティティだけを使って動くアプリケーションを出荷できます。これは設計上の重要な特性です。ティア 1 は「コンパイルできるサブセット」ではなく、「ソフトウェアを出荷できるサブセット」です。
5 つのエンティティからなるティア 1 の範囲には導入コストがあります。Aggregate + Component + Recipe + Manifest + Release は、「YAML ファイルを置けば動くサービスができる」よりも手順が多くなります。このコストは、Aggrega を素の Helm や素の Terraform と異なるものにしている、4 つのドメインによるオーサリングの分離(Developer Intent / Platform Catalog / Platform Ops / Routing)の代償です。ティア 1 のチュートリアルでは、5 つのエンティティの設定を明示的に順を追って説明します。
ティア 3 の中でも、spec.templates / $instantiate: の仕組み(SchemaLibrary におけるパラメトリックなヘルパー)は、さらに上級のサブ機能として説明しています。ティア 3 を導入する人の多くは、最初は spec.templates を使いません。しきい値は「ライブラリに、パラメータ化された構造を共有するスキーマが 6 つ以上あるとき」です。
読む順序
- このリファレンスの使い方
- 命名の慣例
- エンティティリファレンスの概要
- Tier 1: aggregate、component、recipe、manifest、release
- Tier 2: feature、featurerecipe、plugin
- Tier 3: schemalibrary、mappinglibrary、workloadlibrary、artifactlibrary
- 横断的なもの: workload(Recipe の
workload:内で使われる、プラットフォーム所有のコンパイラ種別)
- 語彙の概要
- 語彙リファレンス: topology-triad (provides, inject, uses)、data-pillars (values, infra, parameters, locals)、inheritance-and-interface (extends, implements)、modifier-system (appliesTo, selectors)、compact-form-authoring、cross-document-ref、labels-and-annotations、publishing-surface、social-contracts、validation-surface、output-composition、uri-grammar、version-resolution
- テンプレートの概要
- Providers の概要
- Providers リファレンス: architecture、well-known-annotations、reference-matrix、helm、helm-chart、compose、terraform、cloudformation
- CLI の概要
- CLI リファレンス: aggrega-build、aggrega-inspect、aggrega-pull、aggrega-lint、aggrega-auth、aggrega-cache、aggrega-config、aggrega-deprecate、aggrega-edit-document、aggrega-explain、aggrega-get-schema、aggrega-import とインポートの回答ファイル、aggrega-login、aggrega-logout、aggrega-mcp、aggrega-pin、aggrega-plugin、aggrega-push、aggrega-push-artifact、aggrega-registry、aggrega-scaffold、aggrega-search、aggrega-serve、aggrega-sign、aggrega-skills、aggrega-validate、aggrega-version、global-flags、configuration、environment-variables、workspace-boundary
- エラーの概要
- エラーリファレンス: fatal-halts、warnings、sentinels、error-translation
- 例の概要
Plugin 作成リファレンス
Wasm プラグインのインターフェースは、章の流れの中ではなくその横に位置します。プラグイン作成者は、エンティティ作成の流れとは独立してこれを読みます。plugin エンティティのページはカタログ作成のインターフェースを扱い、以下のページはソケット、ペイロード、作成者のワークフローを扱います。
- plugin-contract — プラグインが接続するソケット、パイプライン内での位置、各ソケットの入力と出力の形。
- plugin-developer-guide — 作成者のエンドツーエンドのワークフロー:
describe()、ケイパビリティの宣言、ランタイムの制限、publish/pull/build のライフサイクル、署名、バージョニング。 - policy-socket — ガバナンスソケットの詳細:その 4 つのロール、判定の重大度、オペレーターの入力チャネル、コンパイラに同梱されるいずれかのエンジン向けのポリシーの書き方。
- governance-attachment-facts — ガバナンスポリシーがビルドグラフから読み取るアタッチメントごとのファクト。機密性マーキングの 3 つの単位と、マーキングがないことが許可を意味しない理由を含みます。
- when-to-use-a-pipeline-step — パイプラインステップとテンプレート化された FeatureRecipe のどちらを選ぶか。
- embedded-plugins — コンパイラのバイナリに同梱されるプラグイン。
- tagging-plugins — ポリシーなしでラベルを書き込む 2 つの組み込みガバナンスプラグイン、
governance/label-injectorとgovernance/selector-taggerの設定と、それぞれが書き込む内容です。 - core-importers — Langflow、Flowise、n8n から Compose、MCP、エージェントフレームワークまで、コンパイラの 10 個のインポーター:それぞれが読み取るものと下書きするもの、その設定、コンパイラの各リリースでの公開。
- authoring-a-provider-walkthrough — プロバイダーのゲストを作成する手順を、空のディレクトリから、プロバイダーがレンダリングしたファイルを書き出すビルドまで、実例に沿って説明します。
- writing-a-governance-plugin — プラグインキットのアダプタースケルトンから独自のガバナンスプラグインを作成します。1 つのルール、各ロールのエクスポートの手動実行、ワークスペースのカタログ内の
Pluginエンティティ、そしてそのプラグインが拒否するビルドを扱います。 - compatibility — プラグインキットのバージョン管理の方法:キットのパッチリリースとマイナーリリースで何が変わりうるか、そしてビルド済みのプラグインを引き続き読み込めるようにするものは何か。