言語のステータス
このページは、Aggrega のどのサーフェスが現在使用可能か、どれがドキュメント化されているもののまだコンパイラによって処理されないか、どれが今後のイテレーションで予定されているかについての正式なリファレンスです。言語全体の準備状況を 1 か所にまとめて示すことで、ドメインごとの章を補完します。
このページを参照する読者は 2 種類います。初めてのオーサーは、馴染みのないサーフェスに対してオーサリングする前にこのページを確認し、そのサーフェスが現在レンダリング出力を生成することを確かめます。リファレンスを探す読者は、使用しているサーフェスが予期しない動作をしたときにこのページを確認します。たとえば、YAML の検証は通るのに出力が生成されない場合、まずこのページでそのサーフェスのステータスを調べます。再訪する読者も、前回読んだ後にステータスラベルが変わったサーフェスを把握するためにこのページを参照します。ドメインごとの章とエンティティリファレンスはサーフェスがどのように動作することを意図しているかを説明し、このページはそれがすでに動作するかどうかを説明します。
ステータスの分類
このページに掲載する言語機能には、それぞれ次の 4 つのステータスラベルのいずれかが付きます。
-
available. スキーマがこの機能を受け付け、コンパイラがこれを処理し、動作はドキュメントに記載された契約と一致します。
availableの機能を使う作成者は、ドキュメントに記載されたとおりの契約を得られます。 -
accepted but inert. スキーマはこの機能を受け付けます(これに対して記述すると検証は通ります)が、コンパイラはまだこれに基づく処理を行いません。
accepted but inertの機能を記述すると、構文的には有効なビルドが生成されますが、その機能によるレンダリング結果は生じません。コンパイラはこの無効な機能を名指しする警告を出す場合があります(推奨されるパターン)が、現在の一部の機能は警告なしに黙ってスキップされます。具体的な動作は、以下の各セクションの項目に記載しています。 -
accepted but blocked. スキーマはこの機能を受け付けます(これに対して記述すると検証は通ります)が、コンパイラはこれをレンダリングせずにビルドを停止します。
accepted but blockedの機能に対して記述すると、レンダリング時に、代わりに何を書くべきかを示す明示的なエラーで失敗します。ブロックは恒久的な場合があります。これは、記述された内容がコンパイラが作成者に代わって解決しない曖昧さである場合で、作成者の代わりに一方の解釈を選ぶと、求めていないものが出荷されるおそれがあるためです。あるいは、その機能の背後にある動作が出荷されるまでの一時的なものである場合もあります。いずれの場合も、このラベルが約束する内容は同じです。スキーマは受け付け、ビルドは拒否し、エラーが修正方法を示します。 -
planned. この機能は設計どおりにドキュメント化されていますが、スキーマもコンパイラもまだこれを受け付けません。
plannedの機能に対して記述すると、スキーマ検証で失敗します。このページでは planned の項目を示すことで、作成者がビルド時に欠落に気づくのではなく、それがないことを前提に計画を立てられるようにしています。
ステータスラベルは現在のコンパイラを基準に評価されます。活発に開発中の機能は、ラベル間で移行する場合があります。移行計画がわかっている場合は、各セクションの項目にその計画を記載しています。
Recipe の入力種別
Recipe は、3 つの入力種別(sourced、synthesized、artifacts)から出力を構成します。詳細は 16-recipe-input-composition.md を参照してください。入力種別ごとのステータスは次のとおりです。
-
source:+valuesMapping:(sourced)— available。 コンパイラはsource:の URI を解決し、valuesMappingテンプレート(インライン、ファイルの$import:、またはライブラリの$import:)を評価して、その結果をレンダリングのために対象の provider に渡します。helm、helm-chart、compose、terraform、cloudformation の各 provider が使用します。 -
workload:(synthesized)— available。 Recipe はworkload:を、インライン(Workload の YAML を保持するブロックスカラー)または$import:(ファイルパス)のいずれかで宣言します。コンパイラはテンプレート化された Workload を解析し、組み込みの Workload スキーマに対して検証したうえで、対象 provider の workload シンセサイザーにディスパッチします。helm と compose の各 provider が使用します。helm-chart provider は、合成された K8s マニフェストについては作成者を明示的に helm provider へ誘導します。workload の合成を実装していない provider に対してworkload:を宣言した Recipe は、レンダリング時にCATALOG_ERRORで停止します。 -
artifacts:(artifacts)— available。 このフィールドは名前付きエントリのマップで、各エントリはインラインで記述するか、エントリごとの$import:で読み込みます。エントリは Workload の解析とソースの解決の後に評価されるため、.workloadと.sourceを含むテンプレートコンテキスト全体をエントリから利用できます。メタデータを持つドキュメントでは、エントリの来歴情報がmetadata.labelsとmetadata.annotationsにマージされ(文字セット上安全でないキー、すなわち recipe-uri、boundary-path、sync-wave はアノテーションとして扱われます。これは helm プロバイダーが適用するのと同じ振り分けです)、Recipe のソースからレンダリングされた出力、または Workload から合成された出力と並んで、別個のファイルとして出力されます。Provider ごとのディスパッチは次のとおりです。フラットな helm プロバイダーは、境界の出力ディレクトリ内で、エントリを宣言したコンポーネントにちなんで名付けられたディレクトリの下に独立したファイルを出力します。キーはファイル名を示すだけで、どのコンポーネントがそれを書いたかを示さないためです。compose プロバイダーは、出力を Release 終端のマージャーに送ります。helm-chart プロバイダーは、同じファイル内の Helm の{{ }}構文が下流のレンダリングまで残るように、すべてのエントリを[[ ]]の Aggrega 区切り文字で評価し、その後、各エントリを記述形式に応じて配置します。$import:で読み込まれたエントリは、ソースのチャート自身のテンプレートと並んでboundaries/<bp>/charts/<nodeID>/templates/<authored-key>(バンドルのファイルはそのキーの下にネストされます)に、インラインコンテンツのエントリはチャートのルートであるboundaries/<bp>/charts/<nodeID>/<authored-key>に配置され、チャート自身のテンプレートが.Files.Get/.Files.Globを通じてそれを読み取ります。terraform プロバイダーは、各エントリを境界のmodules/ツリーの下にあるコンポーネント自身のディレクトリにそのまま書き込みます。cloudformation プロバイダーは、スタックフラグメントである各エントリを、その出力ディレクトリ用に組み立てられる単一のスタックにマージします。入力種別の出自(ソースからのレンダリング、Workload からの合成、artifact としての出力)をまたぐファイル名の衝突は、レンダリング時にクロスオリジン衝突検出器によって検出され、すべての寄与元を示す CATALOG_ERROR を生成します。
Recipe の記述方法と入力種別の構成規則については entities/recipe.md を、Recipe の形状規則については errors/fatal-halts.md を、provider ごとの対応表については下記の Providers セクションを参照してください。
マッピング言語
Recipes(および FeatureRecipes)は、Aggrega のコンテキストを基盤となる provider が消費する values 辞書へ変換するための単一のマッピングフィールドにバインドされます。valuesMapping: フィールドは、内容の形状によって振り分けられる 3 つの記述モードをサポートします。
valuesMapping:— モード 1〜3 が利用可能です。 モード 1:インラインの Go テンプレート(ブロックスカラー)。モード 2:ファイルの$import:(ローカルファイルパスを持つ$import:のみを含むマップ)。モード 3:ライブラリの$import:(MappingLibrary のエントリへのベア名によるアイデンティティ参照<Library>#/mappings/<entry>を持つ$import:のみを含むマップ。任意で:<version>の下限を指定できます)。コンパイラは内容の形状で振り分けます。ブロックスカラーはモード 1 に、ファイルパスを持つ$import:はモード 2 に、ベア名のライブラリ参照を持つ$import:はモード 3 に振り分けられます。3 つのモードはいずれも、values マッピングの際に、解決された Go テンプレートを Recipe のテンプレートコンテキストに対して評価します(Sprig ヘルパーライブラリは事前登録されています)。モード 3 はローカルカタログとロックファイルで固定されたライブラリに対してエントリを解決し、ホストを含む参照は拒否されます。振り分けの仕組みと実例については、entities/recipe.mdの「ThevaluesMappingfield — three authoring modes」を参照してください。
Recipe の記述インターフェースとマッピング言語の設計については entities/recipe.md を、モード 3 を支えるライブラリエンティティについては entities/mappinglibrary.md を参照してください。
Inject 構文
inject: ブロックの構文は、どの配置でも 1 つです。コンポーネント自身の inject、uses 接続のもの、アタッチメントのもの、いずれも同じです。
-
メカニズムごとのエントリのリスト(
[{in: ..., from: ...}]、[{in: ..., value: ...}])— 利用可能。 各配信メカニズムはリストです。各エントリはin:でローカル識別子(環境変数名、ファイルパス、引数フラグ)を指定し、from:(provides キーの参照)またはvalue:(リテラル文字列)のどちらか一方だけを持ちます。リストではなくマップとして記述されたメカニズムや、両方のキーワードを持つエントリは、Aggregate のドキュメントエンベロープでビルドを停止させ、そのパスを示します。 -
value:はコンポーネント自身のinjectでのみ使用します。 リテラルはコンポーネント自身のinjectに記述し、そこから届けられます。uses接続では、Aninject:entry on a connection carries a literal(接続上のエントリがリテラルを持っている) で説明するとおり、value:はビルドを停止させます。アタッチメント自身のinjectでも、Aninject:entry on an attached Feature carries a literal(アタッチされた Feature 上のエントリがリテラルを持っている) で説明するとおり、同様にビルドを停止させます。どちらも、別のエンティティが公開しfrom:で指定されたキーだけを届けます。
二重状態のコンテキストの意味、キー衝突のルール、実例を含む Injection Contract の完全な仕様については、vocabulary/topology-triad.md を参照してください。
テンプレートエンジン
Aggrega の Go テンプレートエンジンは、Recipe と FeatureRecipe のテンプレートを、Template Expansion Matrix(テンプレート展開マトリクス) が記述するサイトごとのフェーズでテンプレートコンテキストに対して評価します。Sprig ヘルパーライブラリは、レンダラーが評価するすべてのサーフェスで Aggrega 独自のヘルパーとともに事前登録されていますが、例外が 1 つあります。構造化された source: 座標の解決では Aggrega のヘルパーのみが登録されます。そこでは optional と capitalizedWords は利用できますが Sprig の関数は利用できないため、source: フィールド内、または構造化された source: を持つエンティティの locals: エントリ内の Sprig 呼び出しは、パース時に停止します。このサーフェスについては専用のセクションを設けている errors/fatal-halts.md を参照してください。評価、パース、Sprig との統合は現在利用可能です。
キー欠落時の挙動 — 値テンプレートでは許容、パステンプレート、アサーション、source: 座標では厳格な missingkey=error。 値テンプレートは Go の missingkey=zero オプションで評価されるため、未バインドのキー(例: .values.unset_field)を参照するテンプレートはエラーを発生させず、その読み取りは何もレンダリングしません。{{ .values.optional_field | default "fallback" }} のようなカタログのイディオムは、このポリシーの下でも引き続き機能します。未設定の値は default にとって空として扱われるためです。パステンプレート(Release 境界上の directory: / subDirectory:)は、閉じた許可リストに対して missingkey=error で評価されます。パスのサイレントな失敗は、オペレーターがビルド後にしか気付かない壊れたファイルシステムレイアウトを生み出すため、厳格さによってエラーをより早く捕捉します。さらに 2 つのサーフェスが同じ理由で同じ厳格なポリシーを採用しています。そこでは空のレンダリングは、作成者が読み返せるフィールドではなく、誤った判定や誤ったピンを生み出してしまうためです。それらは、Component、Feature、Recipe、FeatureRecipe 上の assertions: エントリと、Recipe または FeatureRecipe 上の構造化された source: ブロックのテンプレート化されたフィールドです。errors/fatal-halts.md では、各サーフェスのポリシーを 1 つずつ説明し、厳格なポリシーの下で機能する存在判定型の書き方を示しています。
optional による存在判定型フォールバック。 Recipe の作成者が「キーが存在しない」と「キーが存在し、値がゼロ / 空 / false である」を区別する必要がある場合(Sprig の default ではできない判別です)、レンダラーは optional ヘルパーを提供します。{{ optional .infra "replicas" 1 }} は、キーが存在する場合は作成者が記述した infra.replicas(記述された 0 を含む)を返し、キーが存在しない場合にのみ 1 にフォールバックします。完全なセマンティクスについては templates/sprig-functions.md を参照してください。
capitalizedWords による名前の折りたたみ。 ターゲットがリソースを指定する名前に英字と数字しか受け付けない場合、{{ capitalizedWords .context.instance_id }} は ID をそのアルファベット以外の文字で区切られた単語として読み取り、各単語の先頭文字を大文字にします。そのため payments-db は PaymentsDb になります。この折りたたみはすべての区切り文字を取り除くため、句読点だけが異なる 2 つの ID は同じ名前になります。1 つの名前で 2 つのリソースを出力することになるビルドは停止し、両方の ID を示します。完全なセマンティクスについては templates/sprig-functions.md を参照してください。
宣言レイヤーでのパラメーター契約の強制。 Release が指定しない必須パラメーターは、解決が最初にチェックするパラメーター契約レイヤーで明示的なエラーとなり、そのパラメーターと契約を示す file:line の出所情報が付与されます。型 / 制約の違反も同じように報告されます。これが実質的なキー欠落の強制です。型は、下流のテンプレート評価時ではなく、開発者の意図が存在する場所(Aggregate の parameters: 宣言)でチェックされます。entities/aggregate.md の §「Typed parameter contracts」を参照してください。
Aggregate の parameters: の単一の宣言文法。 各パラメータースロットは、型付き契約オブジェクト(key: { type: <type>, default: <value>, ... })として記述します。裸のスカラーによる省略記法(key: <value>)は Aggregate のドキュメントエンベロープで拒否され、そのパラメーターを示し、オブジェクトが期待されていたことを伝えるエラーが出力されます。型付き契約の語彙により、type:、required:、および制約のセマンティクスが宣言レイヤーで明示されます。Release での値の充足では、引き続き契約で宣言された型に従ったスカラー値を使用します。
テンプレートサイトごとの評価マトリクスについては templates/expansion-matrix.md を、テンプレートの概要については 05-templates.md を参照してください。
コンパイルパイプラインのフェーズ
Aggrega のコンパイルパイプラインは ../architecture/10-compilation-pipeline.md に記載されています。フェーズごとのステータス:
- 解決、トポロジー構築、グラフの確定、静的解析、レンダリング — 利用可能。
- inject マッピング(
injectMappingによるレンダリング前のインターセプト)と、ベースレンダリングのすべてのサブステージ — locals の公開、values のマッピング、ワークロードの合成、アーティファクトの評価、プロバイダーのレンダリング、フィーチャーのレンダリング、認証情報 FeatureRecipe のリソース生成 — 利用可能。 - プラグインパイプライン(
pipeline:による Wasm 実行) — 利用可能。 空でないpipeline:ステップを宣言する Recipe または FeatureRecipe では、各ステップが宣言順に実行されます。コンパイラは、ステップで指定された Wasm プラグインをレンダリング済みの出力に対してディスパッチし、返された JSON Patch 操作を対象のドキュメントに適用し、ステップの副作用を出力します。when:ゲートが falsy にレンダリングされるステップはパススルーとしてスキップされ、ドキュメントセットは変更されません。JSONPatch 形式の変更(Envoy サイドカーの注入、シークレットの VolumeMount など)を目的とする作成者は、このサーフェスを通じてそれを実現します。
Providers
Aggrega 標準ライブラリには、5 つのレンダリングプロバイダー(helm、helm-chart、compose、terraform、cloudformation)が含まれています。プロバイダーごとのステータス:
helm— 利用可能。 ソースモード(Helm SDK による Helm チャートのレンダリング)と合成モード(Workload → Workload のformによって選択されるコントローラーオブジェクト(Deployment、StatefulSet、DaemonSet、Job、または CronJob)に加えて Services と PVC)の両方が提供されています。helm-chart— 利用可能。 ソースモード(アンブレラチャートの構成)が提供されています。合成入力の種類はこのプロバイダーには適用されません。K8s マニフェストの合成が必要な作成者は、helmプロバイダーをworkload:とともに使用します。compose— 利用可能。 ソースモード(compose フラグメントのオーバーレイ)と合成モード(Workload → compose サービス + ボリューム + ネットワーク)の両方が提供されています。境界ごとのdocker-compose.yaml出力は、Release レベルのコンポーザーによって組み立てられます。terraform— 利用可能。 ソースモードとアーティファクトの両方が提供されています。各境界には 1 つのルート設定aggrega.modules.tfが作られ、すべてのコンポーネントをmoduleブロックとして宣言します。そのファイルはmodules/の下にあるコンポーネント自身のディレクトリに置かれます。合成の入力種別はこのプロバイダーには適用されません。cloudformation— 利用可能。 ソースモードとアーティファクト(スタックフラグメント)の両方が提供されています。1 つの出力ディレクトリにレンダリングされるすべてのコンポーネントは 1 つのスタックテンプレートに組み立てられ、純粋な JSON として出力されます。合成の入力種別はこのプロバイダーには適用されません。
Provider のレンダリングは、pluginType: provider を持つ Plugin によって提供されます。プロバイダーレンダリング用 Plugin の作成方法については entities/plugin.md を、プロバイダーごとのリファレンスページについては 06-providers.md を参照してください。
アノテーション駆動の展開
Manifests は、アノテーションキーを Feature 型にマッピングする features.annotations: バインディングセクションと、各バインディングがどの Feature スキーマプロパティを設定できるかを示すピラー別のルーティングテーブル(maps.infra / maps.values)を持ちます。entities/manifest.md および providers/well-known-annotations.md に記載されています。パイプライン内の位置は ../architecture/10-compilation-pipeline.md に、カタログ読み込み時および inspect 時の仕組みは ../architecture/13-catalog-and-registry.md の §“Annotation-driven Feature expansion” に記載されています。
- Manifest の
features.annotationsバインディング — 利用可能。 解決処理のアノテーション展開サブステージは、エンドツーエンドで提供されています。このステージは、Release の境界(外側から内側へ)と Aggregate のサブシステム(外側から内側へ)を走査し、値全体およびサブキー単位の null によるオプトアウトを伴うカスケードとオーバーライドによって、コンポーネントごとの有効なアノテーションセットを算出します。さらに、各アノテーション値をスカラー、構造化されたマップ、または明示的なnullとしてパースし、サイドとピラーの対応を強制しながら(Aggregate 側はmaps.valuesを、Release 側はmaps.infraを発火します)バインディングのmaps宣言を通じてサブキー単位でルーティングし、対象 Feature のspec.schemaに対してリーフ単位の型を検証したうえで、合成 Feature アタッチメントを注入します。IR グラフはこれらをorigin: annotationでマークします。サイドをまたぐ合成は、IR 構築時にピラー単位・フィールド単位でマージされ、フィールドごとに明示的な指定が優先されます。aggrega inspectは、リーフごとに来歴を括弧で表示します。カタログ読み込み時のバインディング対象の検証、schema-pillar-overlap リント、binding-map-overlap リントがこの経路を制御します。接頭辞aggrega.ai/単体をバインディングキーとして使用すると、Manifest の読み込み時に拒否されます。この接頭辞はプラットフォームネイティブのアノテーション用に予約されているため、バインディングにはfeature.aggrega.ai/または独自のドメインを使用します。
バージョンマッチング
Recipes と FeatureRecipes は、implements: キーワードによって、実装する Component または Feature のインターフェースを宣言します。implements: が Recipe を選択することはありません。選択するのは Manifest のマッピングであり、どのマッピングも型をカバーしていないインスタンスは、その型を実装できる implements: を持つ Recipes を候補として列挙するエラーで停止します。implements: が駆動するのは、各 Manifest マッピングエントリの Recipe が、マッピングされた型、またはその型が extends するベースを実装しているかどうかの検査です。マッピングされた型とはエントリのキーであり、components.type キーの場合は、キーが指定していないバージョンでそのキーが到達する各コンポーネントインスタンスの型でもあります(バージョンなしで記述されたキーの場合は、到達するすべてのインスタンス)。そのバージョンは、ビルドがそのインスタンスをコンパイルするバージョン、つまりインスタンスが指定するバージョン、またはバージョンを指定しないインスタンスの場合はカタログが保持するその Component の最高バージョンです。形式ごとのステータス:
- 完全一致(
core/api-server:1.0.0)— 利用可能。 マッピングされた型はそのバージョンでなければなりません。 - メジャー互換範囲(
core/api-server:^1.0.0)— 利用可能。 キャレット形式は SemVer 制約(この例では>=1.0.0, <2.0.0)であり、マッピングされた型のバージョンはこれを満たさなければなりません。 - バージョンなし(
core/api-server)— 利用可能。 その型のどのバージョンでも条件を満たします。
Recipe の implements: が、マッピングされた型にもそのいずれのベースにも一致しないマッピングエントリは、そのエントリ、Recipe、およびその implements: の値を示す OPS_ERROR でビルドを停止させます。キーが別のバージョンで到達するコンポーネントインスタンスのバージョンを Recipe の implements: が満たさない場合、ビルドは同じ OPS_ERROR で停止し、そのインスタンス、その型(バージョンを指定しないインスタンスの場合は、コンパイルされたバージョンも)、キー、Recipe、およびその implements: の値を示します。キャレット形式は、メジャー互換の照合のための標準的な記述方法です。
implements: の設計については vocabulary/inheritance-and-interface.md を、Manifest ごとのマッピング層の構造については entities/manifest.md を参照してください。
メタデータエンベロープ
カタログエンティティのエンベロープは、metadata.labels、metadata.annotations、および(Release では)metadata.environment を持ちます。サーフェスごとのステータス:
metadata.labels と metadata.annotations の利用可否 — 7 種類で利用可能。 これらのフィールドを持つエンティティエンベロープは、Component(labels は必須で、必須キー component.aggrega.ai/type を含み、annotations は任意)、Feature(いずれも任意)、4 つのライブラリ種別 SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary(いずれも任意)、および Aggregate(labels のみ、任意)です。残りのエンティティ — Recipe、FeatureRecipe、Manifest、Release、Plugin — は、エンベロープレベルで metadata.labels も metadata.annotations も受け付けません。
Release の metadata.environment — 必須。 Release スキーマは environment を必須の metadata フィールドとして定めています。ビルドはその値を、レンダリング出力に aggrega.ai/environment ラベルとして刻印します。Environment Metadata セクションの 5 つの実用的なユースケース(OTel/FinOps のコスト配分、OTel のトレース/ログのフィルタリング、Kubernetes オペレーターのターゲティング、マルチリージョンの本番環境の区別、コンプライアンスのスコープ設定)については entities/release.md を参照してください。
metadata キーに適用されるフィールドの大文字・小文字の規律については 02-naming-conventions.md を、各エンティティが現在受け付けるエンベロープの形状についてはエンティティごとのリファレンスページを参照してください。
CLI コマンド
Aggrega CLI は、ビルドパイプラインとイントロスペクションを登録します。コマンドごとのステータス:
aggrega build— 利用可能。 Release ファイルを読み込み、Aggregate と Manifest を解決し、コンパイルパイプラインを実行して、レンダリングされた成果物を境界の出力ディレクトリに書き出します。ロックファイルが存在する場合は依存関係をそれに照らして検証します。存在しない場合は pull を求めて停止するか、--auto-pullまたはauto_pullが指定されている場合は先にロックファイルを作成します。aggrega inspect— 利用可能。 カタログエンティティ、エンティティファイル、レジストリに公開されたエンティティ、または Release を検査し、その解決済みの形を報告します。cli/aggrega-inspect.mdを参照してください。aggrega pull— 利用可能。 Release のすべての依存関係を解決し、Release ごとのロックファイルを書き出します。このロックファイルは、すべてのカタログエンティティとソース成果物をバージョンとコンテンツダイジェストに、Release のレンダリングが要求するすべての外部入力をコンテンツダイジェストに固定します。取得したコンテンツは.aggrega/cache以下にキャッシュします。--verifyは既存のロックファイルを現在の状態と照合します。cli/aggrega-pull.mdを参照してください。aggrega push— 利用可能。 カタログエンティティを OCI レジストリに公開します。aggrega push --list-kindsは受け付ける種類を報告します。cli/aggrega-push.mdを参照してください。aggrega lint— 利用可能。 カタログ全体、Release の依存関係のクロージャ、または 1 つのエンティティに対して、公開規律のルールをwarnの重大度で実行します。1 つのエンティティに対しては、--pre-publishがエンティティの現在公開されているバージョンに対するバージョン引き上げのチェックを追加し、不一致があると停止します。これらのルールはオプトインの Wasm プラグインとして提供されます。cli/aggrega-lint.mdを参照してください。aggrega serve— 利用可能。 エディタや IDE との統合のために、stdin/stdout 上で JSON-RPC 2.0 を話す、常駐型のサービスとしてのコンパイラのデーモンです。提供するメソッドについてはcli/aggrega-serve.mdを参照してください。aggrega version— 利用可能。 CLI のバージョンを出力します。-o jsonは機械可読なバージョンオブジェクトを出力します。aggrega validate— 利用可能。 カタログ全体、Release、または単一のエンティティにわたって正しさをチェックし、成果物をレンダリングせずに診断を報告します。aggrega search— 利用可能。 設定されたレジストリのローカルインデックスから公開済みエンティティを検索します。インデックスはaggrega registry updateによって構築・更新されます。aggrega registry— 利用可能。 レジストリとその署名信頼ポリシーを管理します。registry addはレジストリを登録し、registry updateはaggrega searchが照会するローカルインデックスを構築します。aggrega push-artifact— 利用可能。 エンティティを公開するpushとは別に、単独のデータ成果物(ドキュメントバンドルなど)を OCI レジストリに公開します。aggrega sign— 利用可能。 公開済みの 1 つ以上の成果物に署名し、その署名を添付します。aggrega deprecate— 利用可能。 公開済みの成果物に、署名付きの非推奨マーカーを添付します。aggrega loginとaggrega logout— 利用可能。 OCI レジストリに認証して資格情報を保存するか、保存された資格情報を削除します。aggrega auth— 利用可能。 成果物の署名に使うローカルの署名 ID を管理します。aggrega config— 利用可能。 ワークスペースの設定を検査・管理します。サブコマンドは、マージ後の有効な設定と各設定の由来を表示し、レジストリとその署名信頼ポリシーを含む作業用の設定を作成し、ビルドに不可欠な有効設定をワークスペースに固定して、マシンのグローバル設定に依存せず同一にビルドできるようにします。aggrega get-schema— 利用可能。 エンティティまたはコントラクトの種類の JSON Schema を出力します。aggrega plugin— 利用可能。 CLI が解決できる Wasm プラグインを検査します。サブコマンドは、それらの一覧表示、設定済みプラグインの追加と削除、プラグインの機械管理レコードの同期、およびそれらのカタログビューの生成を行います。aggrega cache— 利用可能。 ディスク上のキャッシュを検査・保守します。サブコマンドはステータスの報告、prune、evict、clear を行います。aggrega mcp— 利用可能。 stdio 上、または別のマシンのクライアント向けには HTTPS 上で Model Context Protocol サーバーを実行し、コンパイラのイントロスペクションを AI アシスタントとの統合に公開します。aggrega completion— 利用可能。 CLI のシェル自動補完スクリプトを生成します。- CLI 拡張サブコマンド — 利用可能。
pluginType: cliゲストとして公開された Wasm プラグインは解決されてaggregaのサブコマンドとして登録されるため、インストールされた拡張は組み込みコマンドと並んでaggrega <extension>として実行されます。 aggrega import— 利用可能。 外部の宣言的なエージェント定義ソース(Langflow、Flowise、n8n)を、Aggregate と Component のドラフトのオーサリングファイルに変換し、ノードごとに決定的で信頼度スコア付きのカタログ再利用の判断を記録します。フォーマット固有のマッピングは、ワークスペースがソースフォーマットに対して解決するインポータープラグインが提供します。これはカタログが保持するもの、またはコンパイラの各リリースとともにビルド・公開されるLangflow、Flowise、n8n のインポーターのいずれかです。バイナリはそれらの Plugin エンティティを含みますがモジュールは含まないため、それらはすべてのワークスペースで各フォーマットを扱えます。マシンが保持していないものを必要とする最初のインポートで、ワークスペースのデフォルトレジストリから取得して検証し、以降のすべてのインポートのためにコンテンツキャッシュに保持します。ソースは、ワークスペースのカタログがその構文に対して提供するパーサー、またはカタログが何も提供しない場合はコンパイラが含むパーサーで解析されるため、カタログにパーサーがないワークスペースでもいずれかを通じてインポートできます。aggrega scaffold— 利用可能。 任意のエンティティ種別について、その種別のスキーマから初期ドキュメントの下書き(必須のすべてのフィールドを含み、値が必要な箇所にはプレースホルダーを置いたもの)を作成し、標準出力に書き出します。--exampleを指定すると、署名済みのドキュメントバンドルから読み取った、ドキュメントの実行可能な例の 1 つを新しいディレクトリに書き出します。aggrega explain— 利用可能。 短いコード(E0007など)または説明的なコードが示す停止条件を説明します。aggrega edit-document— 利用可能。 ドキュメントに範囲を限定した構造化編集(コンポーネントの追加、Feature のアタッチ、接続の配線、1 つの値の設定)を 1 つ適用し、変更しないバイトはすべてそのまま保持します。aggrega pin— 利用可能。 Recipe または FeatureRecipe の横にあるentity.lockに、そのエンティティが自身のドキュメントの外から読み取るすべての入力のコンテンツピンを記録します。aggrega skills— 利用可能。 Aggrega のスキルを AI アシスタントにインストールします。
CLI の概要については 07-cli.md を、コマンドごとのリファレンスページについては言語リファレンスの索引を参照してください。
エディターとその他のフロントエンド
どのフロントエンドも aggrega バイナリがコンパイルした結果を表示し、独自のコンパイラを持つものはありません。サーフェスごとの状況:
- IR グラフコントラクト — 利用可能。 IR グラフスキーマは、すべてのフロントエンドがグラフを読み取る際に準拠するコントラクトであり、Aggrega スキーマ配布物の一部として提供されています。IR スキーマリファレンスを参照してください。
- コマンドからのグラフの読み取り — 利用可能。
aggrega buildは--ir-graphを受け付けます。Release を指定したaggrega inspectとaggrega validate --releaseも同様です。このフラグは、コマンドが本来生成する出力に加えて、その実行で解決されたグラフを JSON として stdout に書き出します。デーモンセッションは同じグラフをaggrega/irGraphで読み取り、MCP サーバーのcli-inspect、cli-build、cli-validateツールはこれをir_graph引数として受け付けます。 - Visual Studio Code でのトポロジーグラフ — 利用可能。 Visual Studio Code 用 Aggrega 拡張機能は、選択した Release の IR グラフをインタラクティブなグラフとして描画し、そこから Features をアタッチします。どちらも
aggrega serveデーモンに要求します。 - ヘッドレス CLI ストリーミングモード — 計画中。 ヘッドレスモードは、トポロジーの変化に応じてフロントエンドが利用できるよう、IR グラフを改行区切り JSON として stdout に出力します。現時点で提供されているのはストリームではなく呼び出しごとに 1 つのドキュメントです。トポロジーの変化に応じて単一の stdout にグラフの列を出力するコマンドはありません。
エディター、アシスタント、デーモンがどのようにコンパイラに到達するかについては、../architecture/15-editors-assistants-and-frontends.md を参照してください。
設計の方向性
上記のステータス分類は言語全体のサーフェスごとの状態を分類するものですが、このセクションではアーキテクチャの各章に記載された、より広範な設計の方向性のステータスを記録します。
エステート全体のコンプライアンスは計画中の方向性ではありません。ガバナンスルールを一度記述するだけでワークスペース内のすべてのビルドに適用させる機能は、ガバナンスソケットを通じて現在利用可能です。ワークスペース設定の plugins.governance キーに接続されたプラグインは、そのワークスペース内のすべてのビルドを評価します。判定ロールはルールに違反するグラフやレンダリング済みアーティファクトを拒否し、変換ロールは開発者が入力することのない派生メタデータを供給します。../architecture/11-governance-and-compliance.md を参照してください。
- インターフェースの同等性と自動実装 — 利用可能。 ベースの Component に対して記述された Recipe は、継承チェーンの深さにかかわらず、それを拡張するすべての Component に対応するため、Architect が重複した Recipe を作成する必要はありません。拡張する Component は
schema: inheritedと記述するため、ベースの Recipe が扱えないルートキーをvalues/infra/providesに追加することはありません。独自のスキーマを持ちながらextendsを宣言する Component は、そのドキュメントエンベロープで拒否されます。Manifest は引き続き、拡張する型を独自のエントリでマッピングし、マッピングされた Recipe のimplementsがその型、またはその型が拡張するいずれかのベースを指していれば、マッピングの検査はそれを受け入れます。../architecture/02-ecosystem-philosophy.mdに記載されています。 - Ghost Infrastructure Tracker — 利用可能。 レンダリングフェーズのガードレールで、作成者が宣言したキーがノードに届いたのに、バインドされた Recipe が宣言するどのテンプレートもそれを読み取らない場合に警告を出力します。これにより、作成者が宣言しテンプレートが暗黙的に破棄した値は、失われるのではなく名指しされます。同じ形状一致設計のうち、レンダリングフェーズを担う半分です。
errors/warnings.mdを参照してください。
アーキテクチャの各章は設計サーフェスを説明し、このページは実装ステータスを追跡します。