カタログとレジストリ
この章では、Open Container Initiative (OCI) カタログによってプラットフォームがエンタープライズ全体にどのようにスケールするかを定義します。カタログのレイアウト、参照の解決方法、エンティティの公開と固定の方法、そしてカタログエンティティが従う名前の形を扱います。
Aggrega カタログ: レジストリの分類体系と解決
Aggrega コンパイラは、抽象的な開発者の意図(Domain 1)を具体的な運用の実態(Domain 3)へ解決するために、厳密に型付けされた OAM 由来のレジストリに依存します。開かれた分散エコシステムを支えつつシームレスな開発者体験を維持するため、すべてのスキーマ、インフラストラクチャバインディング、プログラム可能なポリシー、アダプタプラグインは、標準化された Open Container Initiative(OCI)URI 分類体系に従います。すべてのカタログエンティティは URI でアドレス指定できるため、aggrega pull は Release が必要とするものをキャッシュに取得してロックファイルに固定し、ビルドはそこからそれらを読み取ります。開発者のローカルワークスペースに含まれるのは Aggregate ファイルと Release ファイルのみで、カタログのコピーは含まれません。
1. コアディレクトリ構造(カタログ)
標準ライブラリの aggrega-catalog フォルダー(および準拠するサードパーティのカタログ)は、関心の分離を物理的に強制するように構成されています。この構造は、抽象的なインターフェースを具体的なインフラストラクチャ実装から明示的に分離します。
Components と Features では、URI セグメントがファイルシステムのパスセグメントに 1:1 で対応します。Components は 3 セグメントの URI({publisher}/{category}/{name})を使用し、category セグメントは閉じた集合であるコグニティブカテゴリのいずれかを持ちます。これはコンポーネントの component.aggrega.ai/category ラベルと同じ語です(1:1 のディレクトリミラーであり、公開リンターの category-matches-directory ルールで検査されます)。Features はフラット({publisher}/{name})のままです。これは小さな集合で、ゆっくりと増えていきます。運用オントロジーの分類(stateful-server、server など)は component.aggrega.ai/type ラベルに置かれ、ディレクトリ構造には決して置かれません。コグニティブな能力ラベル(datastore.aggrega.ai/engine、agent.aggrega.ai/autonomy、…)は、その上に振る舞いのサブセットを重ねます。ハブの Web UI はフィルタリングと検索にラベルを使用し、カテゴリはファイルシステムのナビゲーションとカタログの閲覧軸の両方に役立ちます。
以下のツリーは、内容は例示ですが、形は正確です。エンティティが完全に描かれている箇所ではリーフファイルまで続いているため、実際のパス全体を図から読み取れます。どのディレクトリ階層がどの URI セグメントを担うか、必須のバージョンセグメントがどこに位置するか、各エンティティ種別がリーフでどのファイル名を使うかがわかります。カタログの全内容ではなく、各階層につき数件のエントリを示しています。... は省略を示し、その横に書かれた名前は同じ階層のさらなるエントリです。
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformコンポーネントのカテゴリは閉じた集合です。カテゴリの権威はファイルシステムではなくその集合です。まだエンティティを持たないカテゴリ値は予約語彙です。閲覧軸は安定したまま保たれ、作成者は将来のコンポーネントがどこに置かれるかを把握できるため、空の棚は埋めるべき空席ではなく正しい状態です。カタログにはプレースホルダーファイルが含まれないため、そのような値のディレクトリは最初のエンティティが置かれたときに作成されます。
権威ある一覧(すべてのカテゴリ、その内容、そのエンティティが通常持つ運用上の type 値、存在するディレクトリ)は、カタログ慣例ガイドの Component Categories セクションにあり、このガイドは対象とする標準ライブラリカタログとともに公開されています。
type 軸が持つのは運用上のプリミティブのみです。コグニティブな語彙がそこに現れることはなく、公開された Component スキーマがその予約キーの取る値を列挙しているため、そこに書かれたコグニティブな語はドキュメントの読み込み時に拒否されます。3 軸の分割は次のとおりです。運用上の type(インフラストラクチャがコンポーネントをどう扱うか)、コグニティブな category(それが何であるか。ディレクトリに反映されます)、そしてロールごとの能力ラベル(振る舞いのサブセット。エンティティは category: datastore に加えて、自身の製品としての性質が持つ datastore.aggrega.ai/engine 値を持ちます。したがって core/datastore/qdrant は vector を、core/datastore/redis は kv を持ち、両方の軸を照会できます)。真偽が作成者の設定に依存する能力は、カタログにはまったく持たせません。それはコンパイル時にガバナンスソケットの label-transform ロールによって注入され、このロールは開発者が宣言した values を読み取ります。AI 専用のカテゴリには ai- 接頭辞が付きます。両用のカテゴリは接頭辞なしで現れ、AI としての性格は能力ラベルで表現されます。カテゴリは、コンパイラがどう分類するかではなく、ユーザーがどうナビゲートし閲覧するかに基づいて選ばれます。カテゴリ語彙と能力ラベルは、コンパイラがセレクターを照合する対象であり、コンパイラはそこに意味を読み取りません。コンポーネントの名前はカテゴリを繰り返しません。標準ライブラリの OpenAI モデルは core/ai-model/openai であり、core/ai-model/openai-model ではありません。
2. 分割スキーマとブリッジ合成パイプライン
トポロジーソケット宣言にまつわる Component ごとのボイラープレートをなくすため、Aggrega は検証を 2 つに分割し、それぞれをその対象が存在する場所で検査します。
usesSchema(宣言的 YAML)。 カタログエンティティが提供するトポロジーソケットを宣言し、それぞれに契約を与えます。Go CLI はこれをネイティブに読み取り、静的解析中のラベルマッチングに使うselector:文字列を抽出し、許可されたinjectメカニズムを検証します。各ソケットエントリはオプションのrequired: trueフィールド(デフォルトはfalse)をサポートします。これを設定すると、そのソケットに依存関係が宣言されていない場合にコンパイラが検証エラーを出します。これはfeaturesSchemaエントリにおけるrequired: trueのセマンティクスのソケット版であり、どちらもビルドを停止します。ここでソケットを宣言するのは標準ライブラリのカタログが行っていることであり、引き続きより良い方法ですが、開発者がエッジを引く唯一の方法ではありません。Aggregate の作成者は、このusesSchemaが宣言していないソケットを自身のコンポーネント上で指定できます。usesSchemaをまったく宣言していないエンティティ上でも同様です。このようなアドホックなソケットには、selector もinjectの許可リストもエッジごとのスキーマもありません。それらを保持するエントリがここに存在しないためです。Feature アタッチメントのusesと Release のエッジごとのusesはこのように開かれてはおらず、どちらも宣言済みのソケットしか指定できません。完全な契約とアドホックなソケットが失うものについては、dependency-resolution §「Domain 2: The Split Schema」を参照してください。- 脱糖。 開発者が YAML の配列省略記法(
uses: databases: ["db1"])を使うと、CLI はそれをマップ({"db1": {"target": "db1"}})に正規化します。 - ブリッジ合成。 コンパイラは
featuresSchema:のスロットテーブルを JSON Schema 2020-12 のフラグメントに射影します。アタッチメントスロットごとに 1 つのプロパティがあり、それをバインドできるフィルの形状を記述します。injectの許可リストを宣言するスロットにはx-aggrega-inject:拡張キーワードが付きます。JSON Schema の検証は構造検証の際に拡張キーワードを無視し、フラグメントからそれを読み戻すものもありません。スロットの許可リストを必要とするチェックは、スロットそのものを読み取ります。usesSchema:のソケットテーブルはどのフラグメントにも射影されません。ソケットのselector:とinject:は Architect が書いた型付き YAML のまま残り、そこから読み取られます。ソケットのエッジごとのvalueSchema:/infraSchema:はラップされて単独でコンパイルされ、その周囲に制約が作り出されることはありません。 - 合成。 プラットフォームアーキテクトは、
values、infra、providesを定義する厳密なschema:宣言(コンパクト形式または完全な JSON Schema 2020-12)を書きます。この宣言はエンティティ自身の契約であり、単独でコンパイルされます。スロットのフラグメントもソケットテーブルもそこには組み込まれません。各サーフェスはその対象が存在する場所で検査されるため、ソケットの不備はschema:ブロック内のパスではなく、アーキテクトが書いたソケットエントリに対して報告されます。それでもアーキテクトがusesのボイラープレートを書くことはありません。
例:ソケット宣言と、コンパイラがそれをどう扱うか: Platform Architect の YAML
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}コンパイラがそれをどう扱うか
ソケットテーブルはそのまま型付き YAML として読み取られます。selector: 文字列はネイティブのラベルマッチングエンジンに渡され、inject: リストはそのソケットを通るエッジが指定できる配信メカニズムを制約します。schema: ブロックは、エンティティ自身の values / infra / provides 契約として別途コンパイルされます。Static Analyzer は、Architect が書いたソケットエントリから selector: 文字列を読み取り、Feature エンティティの appliesTo / appliesToAnyOf とあわせて、各ターゲットの metadata.labels に対するラベルマッチングを評価し、ノード間の型安全性を検証します。
usesSchema における Kubernetes スタイルのセレクター
Go コンパイラのネイティブなラベルマッチングエンジンは、標準的な Kubernetes スタイルの選択セマンティクス(カンマによる AND、in() による OR、!=/notin() による NOT)を使ってセレクター文字列を評価します。この同じエンジンと同じセレクター文字列の文法が、Feature アタッチメントのセレクター(appliesTo、および appliesToAnyOf の各項目)も評価します。セレクター層は厳密にトポロジーのゲートであり、ピラーごとの schema: 宣言が values、infra、provides の内容を独立して検証します。Go コンパイラがトポロジー構築時にトポロジー上のエッジを引いた後、Static Analyzer は Architect が作成したソケットエントリから selector 文字列を読み取り、ターゲットノードの Catalog labels に対して評価して、ノード間の型安全性を検証します。
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"エンジンが 6 つの要件形式のいずれとしても読み取れないセレクター(空の要件、空白や =、!、(、)、カンマのいずれかを含むキー、閉じられていない集合)は、別のセレクターとして読み取られることはなく、それが守る各エッジでビルドを停止させます。セレクターの文法に、各形式とすべての拒否のケースが記載されています。
3. スキーマ形式と合成
厳密な検証と標準的なカタログメタデータ(作成者、バージョン、説明)の両方を提供するため、Domain 2(インターフェース)と Domain 3(実装)の定義は YAML エンベロープとして記述されます。Domain 2 は、コンパクト形式(デフォルト。約 15 個のキーワードで、JSON Schema 2020-12 に機械的に変換されます)または完全な JSON Schema YAML で表現された埋め込みの schema: 宣言を使用します。
すべてのカタログ YAML がエンベロープを繰り返す理由。 エンベロープ(apiVersion、kind、metadata ブロック)は、本体の長さにかかわらず、すべてのカタログファイル(Component、Feature、Recipe、FeatureRecipe、Aggregate、Manifest、Release、Plugin)の先頭に現れます。この繰り返しは意図的なものです。各ファイルは、単独の成果物として解析、検証、lint、検査できるように設計されています。OCI レジストリから取得した単一のファイル、CI サンドボックスに置かれたファイル、サードパーティのエディタで開かれたファイルは、下流のツールがそれがどの種類のエンティティを表し、どのスキーマバージョンが適用されるかを識別できるだけの自己記述を備えている必要があります。ディレクトリの位置がエンベロープの代わりになることはありません。すべてのパーサー、バリデーター、リンターは、エンティティの種類とスキーマバージョンをエンベロープから読み取ります。代償はファイルごとの機械的な定型記述であり、利点は単独ツールでの保証が OCI 配布面、ローカルファイルシステム、および IDE / CI / inspect の各面にわたって成り立つことです。作成者は新しいカタログコンテンツを作成する際に既存ファイルからエンベロープをコピーするか、aggrega scaffold <kind> から始めます。これは、apiVersion と kind が記入済みのその種類のスターター文書を出力します。
DRY(Don’t Repeat Yourself)原則を維持するため、Catalog は 2 つの異なる合成メカニズムを採用しています。
- 共有 SchemaLibrary エントリ(ドキュメント間
$ref:): 再利用可能な JSON Schema 定義は、SchemaLibrary カタログエンティティ(Tier 3)に格納されます。これらは、任意の利用側の Component または Feature のスキーマから、ドキュメント間$ref:(<library>#/schemas/<entry>、ホストなし。バージョンはロックファイルから取得されます)によって識別子で参照されます。この連鎖はコンパイル時にたどられます。ライブラリエンティティの記述形式については entities/schemalibrary を、解決のセマンティクスについては vocabulary/cross-document-ref を参照してください。 - 単一継承(
extends): 完全なコンポーネントのベースラインには、エンティティはextends: "URI"プロパティを使用できます。Go コンパイラは親の連鎖を再帰的に読み取り、YAML メタデータをディープマージします(競合時はラベルを上書きし、配列は追加します)。データの柱については、2 つのカタログ種別で扱いが分かれます。Feature のschema:は、JSON Schema 2020-12 の合成によってベースのものと合成されます。拡張する Component は柱の内容をまったく記述しません。リテラルのマーカーschema: inheritedを書き、連鎖のどの深さでも、ベースが記述したとおりのベースのschema:ブロックを受け取ります。そのような Component が代わりに合成するのは構造です。アタッチメントスロット(featuresSchema)、トポロジーソケット(usesSchema)、自己注入の許可リスト(inject)、名前付きのassertionsはすべて連鎖に沿ってマージされます。ベースと子のコンポーネント拡張の例については entities/component を、継承が構造上確定させるものと公開規律のルールとして残るものについては governance-and-compliance §“Inheritance and publishing discipline” を参照してください。
ベースと子のコンポーネント拡張の例については entities/component を、完全な例を含む Recipe のポインターとマッパーの記述については entities/recipe を参照してください。
4. ワークスペース設定(.aggrega-config.yaml)
ワークスペースルートにある .aggrega-config.yaml ファイルは、プロジェクトのワークスペース設定です。これはワークスペース自身の宣言であり、go.mod や package.json と同様にソース管理に適しています。.aggrega/ ディレクトリは慣例としてソース管理の対象外とします。node_modules/ や .terraform/ と同様に、.gitignore に記載します。
workspace セクションはルートマーカーです。その存在がワークスペースルートを示し、ルートを定義するカタログディレクトリのみを持ちます。すなわち catalog_dirs と、Release に独自のカタログディレクトリを与える releases マップです。その他の設定はすべてトップレベルに置かれます。多くは単一の値で、その他は 1 つの関心事の設定を単一のキーの下にまとめたセクションです。すべてのフィールドは任意で、デフォルト値が文書化されています。トップレベルキーの完全かつ最新の一覧は、それぞれの型、デフォルト、意味とともに、スキーマから schema/other/aggrega-config に生成されています。以下の例は、ルートマーカーといくつかの単一値の設定を示しています。
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootsigning: ブロックは、aggrega push --sign と aggrega sign が使用する成果物署名のデフォルトを、トップレベル(グローバル)とレジストリごとの両方で保持します。
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemフィールドごとの優先順位は、CLI フラグ > レジストリごとの signing > グローバルの signing > public-good のデフォルトです。Fulcio と Rekor はデフォルトで public-good の Sigstore インスタンスを使うため、指定は任意です。timestamp_url にはデフォルトがありません。キーレスの信頼されたタイムスタンプは Rekor の透明性ログへの登録から得られ、RFC3161 タイムスタンプ局はオプトインです(有効にするには、timestamp_url または --timestamp-url に完全なエンドポイントを設定します)。セキュリティ: signing: ブロックは秘密情報を持ちません。OIDC ID トークンが設定フィールドになることはなく(短命な秘密であり、署名時に渡されます。対話型ターミナルではブラウザフローで、GitHub Actions ではワークフローから取得され、それ以外の場合は --identity-token で渡すか、AGGREGA_IDENTITY_TOKEN または SIGSTORE_ID_TOKEN としてエクスポートします)、秘密鍵がインラインで書かれることもありません。key_path は鍵ファイルへのパスです。これは検証側との意図的な非対称性であり、検証側はインラインの公開鍵を固定しますが、署名側では常に鍵のパスのみを扱います。
ベンダリングされたカタログを持たないルートは、workspace: {} と書いて示します。catalog_dirs リストは、共有カタログが兄弟ディレクトリにあるモノレポ構成をサポートします。コンパイラは各ディレクトリを順に確認します。offline: true フラグはあらゆるネットワークアクセスを防ぎます。コンパイラはローカルパスとキャッシュのみを使い、エンティティがローカルに見つからない場合は停止します。セクション化された設定は、それぞれ 1 つの関心事をまとめます。その中には、ビルド時の厳密さの調整と作成時のヒント、ワークスペースレベルの Wasm アタッチメントソケット(governance、linter、importer、providers、cli。それぞれプラグイン参照のリストを取ります)、公開規律のポリシースイッチを含むルールごとの lint の厳密さ、デーモンの解析キャッシュの調整とリクエストディスパッチのワーカープールのサイズ、そしてマシン全体のコンパイル済みモジュールストアのサイズ上限があります。さらに別のものは、署名と署名信頼のデフォルト、およびデーモン自身の動作を保持します。すべてのトップレベルキーは schema/other/aggrega-config で完全に文書化されています。
設定可能なキャッシュは 3 つあり、名前は似ていてもスコープが異なるため、区別しておく価値があります。artifact_cache_dir は、後述するワークスペースごとのディスク上のコンテンツキャッシュを指定します。parse_cache は、デーモンが動作している間だけ存在するデーモンのメモリ内解析キャッシュの上限を設定します。compiled_module_cache は、コンパイル済みプラグインのマシンコードを格納するディスク上のストアの上限を設定します。これはマシン上のすべてのワークスペースで共有されるキャッシュの 1 つです。プラグインのコンパイル済み形式はプラグインに依存し、それを使うプロジェクトには依存しないためです。
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capマシン上のすべてのプロジェクトが共有するキャッシュのうち、ディスク上のキャッシュ使用量の大半を占めるようになり得るのはこのストアです。マシンが実行するすべてのプラグインが一度ここにコンパイルされて保持されるためであり、そのため常設のサイズ上限を持つのはこのキャッシュだけです。ストアを開くすべての呼び出しは、何かをコンパイルする前に上限を適用し、残りが収まるまで、コンパイルが古いものから順にエントリ全体を削除します。(--disable-plugin-cache を指定して実行したビルドは代わりにメモリ上にコンパイルするため、ストアを増やすことも削ることもありません。)エントリの削除にかかるコストは後の再コンパイルだけであり、それ以外にはありません。このため、上限を下げることも、同じマシン上で他のビルドが実行中に上限を適用することも安全です。上限は単一のビルドがコンパイルする量より大きく設定してください。上限はコンパイルの前に適用されるため、1 回のビルド自体の作業セットを下回る上限では、すべてのビルドが同じモジュールを破棄して再コンパイルすることになります。また同じ理由で、ビルドとビルドの間はストアが上限を超えた状態になることがあり、次のビルドの開始時に再び削られます。aggrega cache status はストアのサイズを報告し、aggrega cache evict --max-size はコマンドラインで指定した上限までストアを必要に応じて削ります。
artifact_cache_dir のルートには 3 つの並列なサブツリーがあり、1 回の aggrega pull の呼び出しがそれらを一様に作成します。ピン留めされた依存関係のクラスごとに 1 つです。カタログエンティティ(Components、Features、Recipes、FeatureRecipes、Aggregates、各ライブラリ、および公開する実行可能ファイルを伴う Plugins)用の <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/(ここでの種類はエンティティが公開されるときの種類であるため、参照とバージョンを共有する異なる種類の 2 つのエンティティ、つまり同じ名前の Component と Recipe は 2 つのスロットになります)、Recipe / FeatureRecipe の spec.source フィールドから取得したソースアーティファクト(Helm チャート、compose フラグメント)用の <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/、そして外部入力用の <artifact_cache_dir>/inputs/sha256/<hex-digest> です。外部入力とは、provider がレンダリング中にホストに要求するリモートドキュメントであり、たとえばチャートの values.schema.json 内で URL を指す $ref がこれにあたります。各ソースアーティファクトのキャッシュスロットには、正となる .tgz アーカイブ、ビルドで読み取るたびに再生成される派生ディレクトリ extracted/、そしてアーティファクトの {kind, url, version, digest, mediatype, pulled_at} という識別情報を記録する metadata.yaml ファイルが含まれます。各エンティティのキャッシュスロットには、取得されたままの公開アーティファクトと、その検証に使われる OCI マニフェストが含まれます。ドキュメントが隣にファイルを指定できる種類のスロット(Recipe、FeatureRecipe、Component、Feature)には、さらに派生ディレクトリ extracted/ も含まれます。ここには、アーティファクトのコンテンツダイジェストで名付けられたディレクトリに、そのアーティファクトが持つファイルが置かれます。アーカイブとして公開された場合はドキュメントとエンティティが宣言したファイル、ドキュメントとして公開された場合はドキュメントのみです(§6)。エンティティのディレクトリは、ソースアーティファクトのファイルと同じく、読み取りのたびに検証済みのアーティファクトからそこに展開されます。すべてのファイルはアーティファクトと照合され、そのディレクトリで手作業により変更または追加されたファイルは読み取られずに破棄され、extracted/ 配下のそれ以外のものは読み取られず、検証に失敗したアーティファクトは何かが展開される前に拒否されます。読み取りはアーティファクトと異なる部分だけを書き換えるため、同時に 1 つのキャッシュを読むビルド(aggrega serve が並行して処理するリクエストや、1 つのワークスペースに対する 2 つのコマンド)は、それぞれ渡されたファイルを完全な状態で見つけます。12 文字の <digest-prefix> セグメントは、上流で異なるダイジェストに再タグ付けされた同じ {kind, url, version} を別々のスロットに名前空間分けします。外部入力にはこのようなスロットは不要です。lockfile がピン留めしたコンテンツダイジェストで名付けられた単一のファイルとして保存されるため、後のビルドが読むものはバイト列の取得元 URL ではなくピンによってアドレス指定されます。これにより、そのビルドはネットワークを拒否した状態でも入力を提供できます。
これら 3 つの隣にさらに 3 つのディレクトリが現れることがありますが、いずれもピン留めされた依存関係のコンテンツは保持しません。index/ は aggrega registry update が書き込むレジストリごとの検索可能なスナップショットを持ち(§8)、signatures/ は検証済みの各署名バンドルをそれ自身のダイジェストの下にキャッシュします。そのため、後の読み取りではバンドルを再取得するのではなく、キャッシュされた blob を記録時のダイジェストと照合し直します。また、catalog-snapshots/ はインポートが読み込んだ公開済みカタログスナップショットをそれぞれ保持します(§8)。アーカイブとそのマニフェストはマニフェストのダイジェストで命名されたスロットに置かれ、カタログツリーは読み取りのたびにアーカイブから展開されます。さらに、他に指定がない場合にワークスペースが読み込むスナップショットを示す current ファイルも置かれます。
ドキュメントバンドルはこれらに含まれません。そのバイト列は公開先のレジストリと公開時のバージョンだけに依存するため、マシンごとに 1 つだけ、コンパイル済みモジュールストアの隣、同じユーザーごとのキャッシュルートの下の docs-bundles/<encoded-reference>/<encoded-version>/ に保持されます。内容はバンドル、その検証に使われるマニフェスト、そして取得時に検証された署名です。artifact_cache_dir はここには及びません。ページを読み取る前に、それらの署名は、読み取る側のワークスペース自身のバンドルのレジストリに対する署名チェックのもとで再び検証されます。そのため、あるワークスペースの緩い設定で取り込まれたコピーが、そのチェックで拒否するワークスペースに提供されることはありません。詳しくは aggrega-explain と aggrega-cache を参照してください。
artifact_cache_dir はワークスペースルートからの相対パスで記述し、コマンドをどのディレクトリから呼び出しても、どのカタログディレクトリを走査していても、同じディレクトリを意味します。絶対パスの値は、設定の読み込み時にそのフィールドを示す診断とともに拒否されます。この設定を読む側はすべてワークスペースルートを基準に解決するため、絶対パスはどの読み手も到達しない場所を指すことになり、そうでなければ失敗は気付かれません。pull が書き込むキャッシュが、ビルドが読むキャッシュではなくなってしまうのです。キャッシュはカタログディレクトリの内部に置いてかまいません。デフォルトのレイアウトではそうなっており、カタログディレクトリは一般にワークスペースルートそのものだからです。してはならないのは、キャッシュがカタログディレクトリそのものになることです。カタログ走査はキャッシュを飛ばすため、カタログディレクトリでもあるキャッシュディレクトリは、そのディレクトリの内容全体をあらゆる走査から除外してしまいます。artifact_cache_dir: . はワークスペースルートを指し、デフォルトのレイアウトではまさにこれに該当するため、設定の読み込み時にフィールドを示す診断とともに拒否されます。ワークスペースルートに帰着する他の書き方も同様です。この 2 つの形と前述の絶対パスが、設定チェックが単独で認識できるものです。他のカタログディレクトリを指す値(catalog_dirs に sub を列挙しているワークスペースでの sub)は問題なく読み込まれ、唯一の症状はその配下のエンティティが見つからなくなることです。したがって、workspace.catalog_dirs に列挙されたどのディレクトリにもキャッシュを置かないようにすることは、設定がチェックしてくれることではなく、設定を書く作業の一部です。
キャッシュを飛ばすことで、解決の成果物が作成者の書いたものとして読まれることを防いでいます。キャッシュスロットが保持するのはレジストリからの取得が置いたバイト列であり、取得時の座標の下に保存され、lockfile のダイジェストによって保証されています。これを作成されたカタログコンテンツとして拾い上げる走査は、何も検証していないバイト列を、作成者が編集できないパスから取り込むことになります。その帰結の 1 つは明確に述べておく価値があります。どの lockfile もピン留めしていないエンティティがキャッシュにある場合(中断された pull が残したもの、手作業でコピーされたもの、Release が参照しなくなって取り残されたものなど)、そのエンティティはカタログ走査からは見えず、それに依存するビルドや検証はエンティティが見つからないとして停止します。対処法は Release を再度 pull することで、これによりエンティティは lockfile を通じて解決され、そのダイジェストが記録されます。停止時にはエンティティ名が示されるため、欠けているピンを特定できます。それでも解決するという代替策は、キャッシュを飛ばす仕組みが防ぐために存在する、未検証の読み取りそのものです。
lockfile は Release ごとに存在します。release.yaml を解決すると、その隣に release.lock(Release ファイルのステムに .lock を付けたもの)が書き込まれます。aggrega pull は依存関係を解決して lockfile を書き込み、aggrega build はそれを読み込んで、ビルド時点のレジストリの状態にかかわらず固定されたバージョンを使用します。マシン間でのビルドの再現性が重要な場合、ワークスペースは lockfile をコミットします。ワークスペース内でエンティティ、ライブラリ、プラグイン、または Release 自体が変更された後は、aggrega pull --release <release> で lockfile を更新します。これは他のすべての固定を保ったまま、変更された部分を再解決します。レジストリが新たに提供するバージョンを採用するには aggrega pull --upgrade --release <release> を使用します。lockfile は、解決されたすべてのエンティティについて、種類、記述されたとおりの URI、解決されたバージョン、コンテンツダイジェスト、および参照箇所を記録します。種類と URI の組み合わせでエントリが識別されるため、Aggregate と Manifest が同じ名前を持つ Release では、それぞれに 1 つずつエントリが記録され、どちらかを編集すると、pull がそれを記録するまで次のビルドは停止します:
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1固定された各エントリは、種類、URI、解決されたバージョン、コンテンツアドレス可能なダイジェストを持ちます。ダイジェストはフェッチのたびに検証され、固定されたダイジェストと一致しないバイトは整合性エラーでビルドを停止させます。エンティティのダイジェストは、転送される際のバイトではなく、その公開物が運ぶもの、つまりドキュメントと、その隣に宣言されたすべてのファイル(それぞれのパスとバイト)に対して計算されます。そのため、同じエンティティは、カタログディレクトリから読み込まれてもレジストリからフェッチされても、アーカイブの圧縮方法や、チェックアウトがファイルに与えたパーミッションビット(実行ビットを含む)にかかわらず、同じダイジェストを記録します。フェッチが最初に照合されるのは、公開されたバイトに対するレジストリ自身のダイジェストであり、これはマニフェストを通じて行われます。レジストリで解決されたエントリは、そのマニフェストのダイジェストを自身のダイジェストの隣に記録します。
5. 3 層のエンティティ解決モデル
コンパイラは、コンパイル中に出現するすべてのエンティティ参照を、厳密なカスケード検索によって解決します。3 つの層(ローカルパス、ワークスペースとキャッシュ、レジストリ)は、健全な Aggrega プロジェクトで共存する 3 つの作成ワークフローに対応しています。隣にあるファイルを指定する Release、チェックインされたカタログと以前にプルしたキャッシュを利用するチーム、そして未取得のアーティファクトのためにレジストリにアクセスするプルです。同じカスケードのうちワークスペースとキャッシュの層とレジストリの層が、Aggregates の type フィールド、Manifest マッピングの URI 値、Recipes と FeatureRecipes の implements 宣言、Recipe と FeatureRecipe のパイプライン内の plugin 参照を評価します。ローカルパスの層に到達するのは、Release とその Manifest が指定するファイルだけです。
ローカルパス。 Release の aggregate、manifest、extends 参照、または Manifest の extends が ./ または ../(POSIX の相対パス接頭辞)で始まる場合、Release からの相対位置でディスクから直接読み込まれます。カタログ検索もレジストリ呼び出しも行われません。明示的な接頭辞により、ローカルパスの意図と名前の検索が構文レベルで区別されます。aggregate: ./aggregate.yaml と書く Release はファイルを指定し、aggregate: checkout は metadata.name によって Aggregate を指定します。リゾルバは、どの層を適用するかを決めるために文字列の内容を推測することはありません。接頭辞が判別子です。それ以外のすべての参照は、Aggregate 内の Component の type も含め、ワークスペースとキャッシュの層およびレジストリの層を通じて解決されます。ローカルで作成したエンティティはワークスペースルートの catalog/ の下か、workspace.catalog_dirs に列挙されたディレクトリに置きます。相対ファイルパスとして書かれた type は、どのカタログにも存在しないエンティティとしてビルドを停止させます。
ワークスペースとキャッシュ。 明示的なローカルパス接頭辞を持たない参照は、まず workspace.catalog_dirs に列挙されたディレクトリ(リポジトリ内で作成またはベンダリングされたプロジェクトローカルのカタログツリー。設定の形式は §4 を参照)に対して検索されます。設定が workspace.releases の下で独自のディレクトリを与えている Release の場合は、その Release のディレクトリに対して検索されます。次にワークスペースルートの catalog/ ディレクトリ、そして artifact_cache_dir(以前のレジストリ解決でプルされたアーティファクトを保持する、gitignore された .aggrega/cache/ の場所。そのサブツリーは §4 で説明しています)に対して検索されます。2 回目以降のビルドでのキャッシュヒットにより、プロジェクトがリモートのカタログコンテンツに依存していても、内側のループはネットワーク不要に保たれます。
レジストリ。 ワークスペースとキャッシュの層で一致が見つからない場合、aggrega pull(または --auto-pull かワークスペースの auto_pull 設定付きで実行されたビルド)は default_registry(デフォルトは hub.aggrega.ai)に対して ORAS ベースの OCI プルを発行し、後続のビルドのためにアーティファクトをキャッシュに展開して、解決されたエンティティで処理を続けます。どちらも持たないビルドはロックファイルが固定するものだけを読み取り、ロックファイルがない場合は aggrega pull を示して停止します。レジストリ呼び出しが構築する OCI URI の形式は、§6(アーティファクトのパッケージングと OCI タクソノミー)で説明するエンティティ型のタクソノミーに従います。Aggregates と Manifests 内の短縮 URI は、レジストリ呼び出しの前に完全な OCI 形式に展開されます。この展開を行う推論規則は、Manifest の Context-Aware Shorthand URIs リファレンスと後述の §8 にあります。
優先順位とシャドーイング。 解決の優先順位は厳密にローカルパス > ワークスペースとキャッシュ > レジストリです。ローカルのカタログディレクトリにあり、レジストリのエンティティと同じ識別子を持つエンティティは、レジストリのエンティティをシャドーイングします。これは意図的なもので、カタログ作成者が公開前に変更を試せるようにしています。同じシャドーイングは catalog_dirs とキャッシュの間にも適用されます。ワークスペースのカタログディレクトリに存在するエンティティはキャッシュされたコピーより優先されるため、ベンダリングされたカタログへのローカルな編集は即座に反映されます。
ワークスペースとキャッシュの層内で、catalog_dirs は順序付きの先勝ちの優先順位スタックです。同じエンティティの識別子が複数の列挙されたカタログディレクトリに現れた場合、先に列挙されたディレクトリが勝ち、後の出現はシャドーイングされます。つまり上書きされ、読み込まれず、エラーにもなりません。これにより、プロジェクトは共有またはベンダリングされたディレクトリの前に独自のカタログディレクトリを重ね、選択したエンティティを識別子単位で上書きしつつ、残りを共有ディレクトリにフォールスルーさせることができます。この上書きは観測可能です。解決の詳細はどのディレクトリが勝ち、どれがシャドーイングされたかを報告するため、重ね合わせが黙って行われることはありません。シャドーイングはディレクトリ間にのみ適用されます。単一のディレクトリ内で同じ識別子を主張する 2 つのファイルは作成上の誤りであり、読み込みを停止させます。複数回指定されたディレクトリ(--catalog フラグと catalog_dirs の両方、またはリスト内で 2 回)は、スタックの 1 つのエントリであり、最初に指定された位置で 1 回だけ検索されます。そのため、シャドーは常に 2 つの異なるファイル間で起こり、ディレクトリが自分自身と照合されることはありません。優先順位は作成者が制御するディレクトリ順に従うため、解決される集合は決定的です。
ワークスペースルートの catalog/ ディレクトリは、そのスタックの先頭ではなく末尾に、そのディレクトリが存在する場合にのみ加わります。そのため、プロジェクトが列挙したものは衝突時に常にこれより優先され、無関係なディレクトリを 1 つ列挙しても、これが黙って読まれなくなることはありません。列挙されたエントリがすでにこれに到達している場合はスキップされます。列挙されたディレクトリの走査は再帰的であり、ワークスペースルートを指定したスタックはすでにこれを読み込んでいるためです。catalog_dirs を省略することと、空のリストとして書くことは異なる意味を持ちます。省略した場合、ワークスペースは引き続き catalog/ を読み込みます。[] と書いた場合はローカルカタログを一切読み込みません。これはワークスペースがカタログを持たないことを宣言する方法です。
エアギャップ環境でのビルド。 offline: true(§4)を設定するとレジストリの層は完全にスキップされます。ローカルパスの層またはワークスペースとキャッシュの層で解決できなかった参照は、黙ってネットワーク呼び出しを試みるのではなく、エンティティ欠落エラーを発生させます。これにより、法的にネットワークにアクセスできない CI パイプラインに、決定的なフェイルファストの契約が提供されます。
カスケードが作用する範囲。 カスケードはエンティティをメモリにフェッチします。その上に重ねられるさらなる解決の仕組み、すなわち Manifest の 2 層の type 対 name 検索、vocabulary/inheritance-and-interface にある implements の 3 形式のバージョンマッチング(完全一致 / メジャー互換範囲 / バージョンなし)、およびプロバイダとコンポーネントインスタンスによる軸ごとの Recipe 選択は、リゾルバがこのカスケードを通じてすでにプルしたエンティティに対して作用します。
6. アーティファクトのパッケージングと OCI タクソノミー(先頭セグメントとしてのケイパビリティ)
Aggrega は、Docker がコンテナイメージを扱うのと同じ方法でインフラストラクチャのロジックを扱い、ORAS(OCI Registry As Storage)を介して Open Container Initiative(OCI)標準を利用します。ユーザーは Aggrega カタログを任意の標準レジストリ(GHCR、AWS ECR、Aggrega Hub)でホストできます。
Recipes は厳密にレンダリングケイパビリティと 1:1 であるため(Recipe は spec.capability で 1 つのケイパビリティを指定し、2 つを対象にすることはできません)、OCI レジストリでそれらを整理する最もすっきりした方法は、ケイパビリティを先頭のリポジトリセグメントに置くことです。
OCI タクソノミーはすべてのエンティティ種別を対象とします。リポジトリ名は kind セグメント(エンティティの kind を小文字にしたもの)の後にエンティティの識別子を続けたもので、全体が小文字になります:
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component、パブリッシャーcore、カテゴリdatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component、パブリッシャーcore、カテゴリcomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature、パブリッシャーcore(フラット、カテゴリなし)hub.aggrega.ai/aggregate/core/db-module:1.0.0— 再利用可能な Aggregate モジュールhub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe、ケイパビリティhelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe、ケイパビリティhelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe、ケイパビリティcomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe、ケイパビリティhelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary、共有スキーマ定義。PascalCase のmetadata.nameAIDatastoresは小文字化されてリポジトリ名になりますhub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary、共有の Go テンプレートマッピング断片hub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin、ソケットタイプprovider(metadata.pluginTypeセグメント)
公開可能な kind は、カタログ作成用の kind に加えて、再利用可能なモジュールである Aggregate(後で Release のトップレベルの spec.aggregate として参照されるか、別の Aggregate の aggregates: ブロックにネストされるかを問わず公開可能)と、コンパイラがルーティングしランタイムが実行する WebAssembly アーティファクトへのコンテンツアドレス参照である Plugin です。Plugin はカタログ作成用の kind ではなく、構造上の公開可能なアーティファクトです。Release と Manifest はソース管理に置かれるデプロイ側の入力であり、プッシュされることはありません(aggrega push はこれらを拒否します)。そのため公開用のメディアタイプを持ちません。aggrega push --list-kinds は、インストールされたバイナリが公開する kind の集合を 1 行に 1 つずつ報告します。公開可能な各 kind は、公開がとる 2 つの形それぞれについて固有の OCI メディアタイプを持ちます。
| エンティティの kind | ドキュメントとして公開 | 宣言したファイルとともに公開 |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — ファイルを宣言しない |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — ファイルを宣言しない |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — ファイルを宣言しない |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — ファイルを宣言しない |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — ファイルを宣言しない |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — 独自のマニフェストを通じて公開 |
公開が運ぶもの、したがってその形は、エンティティが宣言するものから決まります。kind からでも、ディレクトリに置かれているものからでもありません。 公開は、エンティティのドキュメントと、エンティティ自身がその横に指定するファイルを運びます。すなわち、Recipe または FeatureRecipe のローカルの source:(ディレクトリの場合は、その entity.lock に記録された除外ルールが残す配下のすべてのファイルとともに運ばれます)、valuesMapping:、workload:、artifacts: の各エントリが $import: でインポートする各ファイル、ピン留めステップが書き出した entity.lock、そして Component または Feature がインポートする各スキーマファイル(インポートチェーンのすべてのファイルを含む)です。ディレクトリ内のそれ以外のものは運ばれません。エンティティの横にあるメモ、README、ビルドの出力は、名前が何であれ公開されるものの一部ではなく、公開の形も変えません。何も指定しないエンティティは、作成されたドキュメントのままバイト単位で、その kind の +yaml メディアタイプで公開されます。ファイルを指定するエンティティは、ドキュメントとそれらのファイルの gzip 圧縮 tar として、その kind の +tar+gz メディアタイプで公開されます。Aggregate、Plugin、ライブラリ系の kind はドキュメントの横にファイルを宣言しないため、常にドキュメントとして公開されます。ワークスペースルートにある Aggregate も同様で、宣言するパスはすべて運ぶファイルではなく別のエンティティを指すからです。内容がすべてインラインの Recipe も同様です。リモートソースはファイルではなく参照なので何も運びませんが、そのピンを記録する entity.lock があるため、そのような Recipe はアーカイブになります。各メディアタイプのバージョンセグメントはすべての公開可能な kind で共通であり、エンコーディングセグメントがバイト列が 2 つの形のどちらであるかを示します。下流のツールは、kind、バージョン、エンコーディングを合わせた完全なメディアタイプ文字列で処理を振り分けます。
作成形式のうち 1 つだけ、公開が知り得るディレクトリを指定しないものがあります。テンプレートとして書かれたローカルソースです。 そのディレクトリは Release がテンプレートを埋めた時点で初めて決まるため、エンティティは記録された除外ルールが残す自身のディレクトリ内のすべてのファイルを運び、Release がどのディレクトリを選んでも運ばれているようにします。この場合、aggrega push はその旨を表示します。指定されたものだけを運ぶことにはコストがあり、それは利用者側が負います。エンティティが読み込むのにどこにも指定していないファイルは運ばれず、その欠落に直面するのは公開者のプッシュではなく利用者のビルドであり、キャッシュスロット内で欠けているパスが示されます。
ソースディレクトリのどのファイルがエンティティに属するかは、エンティティのピン留め時に一度だけ決定され、記録されます。 作成者のワークスペースでエンティティのケイパビリティを担うプラグインが、そのエコシステムが決して出荷しないもの(チャートプラグインのバージョン管理ディレクトリとチャートの .helmignore の尊重、モジュールプラグインの .terraform/)を宣言し、エンティティの横にある作成者の .aggregaignore が最終的な決定権を持ちます。ピン留めステップはそのプラグインと合成されたルールを entity.lock に記録し、公開、ソースのピンのあらゆる比較、エンティティのロックファイル行、レンダリングはいずれも、プラグインに再度問い合わせるのではなく記録されたルールを適用します。そのため公開されるものは作成者自身のビルドがレンダリングするものと一致し、バインディングの変更や新しいバイナリは、エンティティが再びピン留めされるまでダイジェストを変えません。コンパイラはどのエコシステムについても見解を持ちません。ルールはプラグインと作成者から与えられ、コンパイラはそれを照合するだけです。エンティティのファイル中のシンボリックリンクは、たどられずに拒否されます。リンク先がその名前で運ばれてしまうためです。ルールの詳細は aggrega pin で説明しています。
Recipe の名前にはドメインのプレフィックスもケイパビリティも含めません。エンティティ種別ディレクトリとケイパビリティのセグメントが、すでにその両方を示しています。
命名の慣例: Components(ドメイン 2)は {publisher}/{category}/{name} を使用し、Features(ドメイン 2)と再利用可能な Aggregates(ドメイン 1)は {publisher}/{name} を使用します。パブリッシャーセグメントはベンダー/作成者を示します(core = 公式標準ライブラリ、acme = エンタープライズ)。ドメイン 3 のエンティティ(Recipe、FeatureRecipe)は {capability}/{name} を使用し、ケイパビリティはエンティティが spec.capability で宣言する provider です。参照ではエンティティをリーフのみの素の名前で指定することもできます。Recipe 名にはケイパビリティも含めません。すでに正規 URI の先頭セグメントになっているためです。
Recipes は implements キーワードを使用して、自身が満たすインターフェースにバインドします。implements フィールドは、完全一致、メジャー互換の範囲、バージョンなしのマッチングをサポートします(implements のバージョンマッチングについては vocabulary/inheritance-and-interface を参照してください)。Manifest のマッピングエントリの Recipe は、マップ先の型、またはその型が extends するベースを実装していなければなりません。つまり、エントリのキーと、キーがバージョンを指定せずに到達する各コンポーネントインスタンスの型(ビルドがそのインスタンスをコンパイルするバージョンにおけるもの)です。そのため、キーがインスタンスを、その型の別のバージョン向けに書かれた Recipe に送ることはできません。
Ops エンジニアが aggrega push を実行すると、CLI はエンティティをその形で、そのバージョンにおいてイミュータブルに公開します。利用者は 3 層解決モデルを通じてそれを取得し、ローカルの .aggrega/cache/ にキャッシュし、運ばれてきたもの(アーカイブのファイル、またはドキュメントのみ)をエンティティのキャッシュスロット(§4)に展開します。
プルされたエンティティは、自身が運ぶファイルを、カタログディレクトリ内でその隣にあるファイルを読むのとまったく同じように読みます。 エンティティは展開されたツリー内のその位置から読まれるため、エンティティが宣言する相対的な source: や $import: は、直接書かれたものでもテンプレートで生成されたものでも、公開された内容の内部で解決されます。また、エンティティ自身のディレクトリから出るパスは、カタログディレクトリの場合と同様にそこで拒否されます。ツリーの外部にあるものが代わりに読まれることはありません。ビルドを実行するディレクトリも、キャッシュスロットに置かれたファイルも読まれません。スキーマをファイルからインポートする Component または Feature はそのファイルを運ぶため、プルされたコピーは公開された契約を読み込み、それに対して記述された値を、カタログディレクトリから読まれたコピーとまったく同じように検証します。
パッケージからエンティティを読み戻すのは逆の手順であり、エンティティはドキュメントの名前ではなく、ドキュメントが何であるかによって識別されます。つまり、パッケージの最上位にあり、kind: が公開可能なエンティティ種別であるドキュメントです。エンティティファイルの名前はカタログの慣例であって契約ではありません。そのため recipe.yaml は標準ライブラリのカタログが書く名前であってフォーマットが要求するものではなく、エンティティの隣に運ばれるファイル(チャートテンプレートや compose フラグメントなど)がエンティティと取り違えられることはありません。このルールを逆にして、利用者が求める種別をキーにすることはできません。種別はパッケージ内にあるエンティティから読まれるため、パッケージを開く時点ではキーにする種別が存在しないからです。パッケージの最上位に 2 つのエンティティドキュメントがある場合、読み取り側は選択せずに停止します。これは、2 つのエンティティを含むディレクトリ全体をパックする別のクライアントが生成するパッケージであり、そのままでは公開された各座標の下に 1 つのアーティファクトとして置かれてしまいます。本製品の公開ではこれは生成されません。各エンティティは宣言したものだけを運ぶうえ、公開側もそのようなディレクトリを拒否するためです。Aggregate、Release、Manifest を除くすべての種別は専用のディレクトリを持ち、aggrega pin と aggrega push はそれ以外の種別のエンティティの隣に別のエンティティがある場合に拒否します。一方、カタログの読み込み、lint、ビルドはそのディレクトリに手を加えません。ディレクトリの名前はどちらの側でも判定されません。<name>/<version>/ というレイアウトは標準ライブラリのカタログの慣例です。
公開されたエンティティも同じ手順で読まれます。 座標はエンティティのコピーをちょうど 1 つ、その宣言が与えた形で運びます。人がそれを確認するには、隣に公開された可読コピーではなく aggrega inspect oci://<registry>/<repository>:<tag> を使います。そのため、ビルドが解決するコピーと食い違いうる 2 つ目のコピーは存在しません。このコマンドは上記のルールでアーカイブを展開し、Plugin のエンティティを一緒に公開された実行ファイルからではなくそのマニフェストから読み、その種別のファイルが表示されるのと同じように結果を表示します。公開されたエンティティの読み取りを参照してください。
検索可能なマニフェストアノテーション。 公開のたびに、アーティファクトの OCI マニフェストに少数の検索可能なアノテーションが付与されます。これにより、レジストリのインデックスやカタログブラウザは、各エンティティ本体を取得・解析することなく、カタログメタデータでアーティファクトを絞り込めます。すべてのエンティティは、人が読める説明(標準の OCI description アノテーション)に加えて、カタログのカテゴリと種別を持ちます。Plugin はさらに、ソケットタイプと提供するケイパビリティを持ちます。これらのアノテーションは、aggrega registry update がローカルの検索可能インデックス(§8)に読み戻すものです。
公開されるすべてのファイルには名前が付きます。 公開が運ぶ各ファイルには、マニフェスト上で標準の org.opencontainers.image.title アノテーションにより名前が付けられます。これは、汎用 OCI クライアントがアーティファクトをディレクトリにプルする際にそのファイルを書き出す名前です。名前はそのファイルが何であるかを示し、拡張子はファイルのメディアタイプに従います。
| 公開されるもの | 汎用 OCI クライアントが書き出すファイル |
|---|---|
| ドキュメントとして公開されるエンティティ | entity.yaml |
| 宣言するファイルと共に公開されるエンティティ | entity.tar.gz |
| Plugin | エンティティである entity.yaml と、その隣の実行ファイル entity.wasm |
| アーティファクトに添付された署名 | signature.json |
| アーティファクトに添付された非推奨マーカー | deprecation.json |
aggrega push-artifact で公開されたデータアーティファクト | --name で指定した名前 |
したがって、oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server は、公開されたエンティティを公開時とバイト単位で同一のまま ./server/entity.yaml に置きます。oras は名前のない記述子をスキップしたうえで成功を報告するため、公開がパックするすべての記述子には名前が付いています。名前はメディアタイプのみから導出され、公開されたファイルの名前からは導出されないため、異なる名前のファイルから公開された同じバイト列は同じマニフェストを生成します。ファイルと共に公開されたエンティティはパッケージとして届きます。entity.tar.gz がパッケージの名前であり、その中のエンティティはファイル名ではなく上記のルールで見つけられます。Aggrega 自身の解決処理はこれらの名前を読みません。各ファイルをメディアタイプで選択し、ダイジェストで信頼します。したがって、これらの名前は他のすべてのクライアントのために存在します。
7. Recipe のアーキテクチャ:ポインタとマッパー
Recipe の記述方法の全体については entities/recipe を参照してください。source:(ポインタ)、valuesMapping:(マッパー。インラインのブロックスカラー、ファイルの $import:、MappingLibrary エントリへのライブラリ $import: の 3 つの記述モードがあります)、Wasm 駆動のソーススキーマ、ネイティブ IaC サポート、および実例を扱っています。
8. デフォルトレジストリとコンテキスト対応の短縮 URI
YAML の肥大化をなくすため、コンパイラは短縮 URI を、それが現れるスキーマ上の位置に応じてコンテキスト対応で解決します。デフォルトレジストリは .aggrega-config.yaml で設定します(デフォルトは hub.aggrega.ai)。
レジストリホストの読み方は 1 つだけです。各 registries[].host はホストそのものとして記述します。すなわち、ドットを含む小文字のホスト名、localhost、ポートが続く単一の名前、IPv4 アドレス、または角括弧で囲んだ IPv6 アドレスのいずれかで、それぞれ任意で :port を付けられ、スキーム、パス、認証情報、大文字は含みません。この表記が、レジストリごとのすべての信頼ポリシーを見つけるためのキーであり、公式ハブに組み込まれた署名要件は hub.aggrega.ai をキーとしているためです。default_registry も同じ方法でホストを指定し、その後に ghcr.io/acme のようなリポジトリパスを続けることができます。この場合、デフォルトを通じて公開されるものはすべてそのパスの下に配置され、すべての短縮参照はその下で解決されますが、信頼は引き続きホストのみで決まります。default_registry は代わりに registries エントリの name: として記述することもでき、その場合はそのエントリのホストを表します。この名前は、設定が解決される際に、すべての設定ファイルと環境を適用した後に有効なエントリに対して一度だけ読まれます。そのため、デフォルトを読むすべての処理(公開、ロケーションのバインド、署名検証、すべての信頼の参照)はその 1 つのエントリのホストを読み、名前と同じ綴りのホストに到達するものはありません。名前の後にパスが続くものは拒否されます。名前はロケーションではなくエントリを表すためです。名前はホスト表記より先に照合され、2 つのエントリが持つ名前は曖昧であるとして拒否されます。同じ読み方によって、プルがホストに関して行う 3 つのことが決まります。ホストを持たないカタログ識別子がバインドされるレジストリのロケーション、取得したアーティファクトが署名を検査されるレジストリを指すかどうか、そしてその検査がどの信頼ポリシーに対して実行されるかです。レジストリには到達できてもそのポリシーを取り逃しうる表記(大文字、明示的なデフォルトの HTTPS ポート、スキーム、認証情報、registries エントリのホスト上のパス)は、設定された箇所で、書くべき表記を示したうえで拒否されます。ポートがなくどのエントリも指さない単一の名前も同様に拒否されます。これはホストではなく、カタログ識別子の最初のセグメントの形だからです。この拒否は、値を設定できるすべての層に適用されます。すなわち、スキーマが各 registries[].host のパターンとして同じ形を規定している設定ファイル、AGGREGA_DEFAULT_REGISTRY 環境変数、そしてコマンドラインです。したがって、設定が指定できるすべてのホストは、そのために書かれたポリシーの下でアーティファクトが検証されるホストです。ホストはその表記のみで判断されます。名前が解決されるかどうか、またはそこでレジストリが応答するかどうかは、コンパイラが決して取得しない実行時の状態です。受け付けられる形式は、configuration で例とともに詳しく説明しています。
短縮 URI は Manifest に対してコンテキスト対応で解決されます。具体的な推論規則については、../language-reference/entities/manifest.md の §Context-Aware Shorthand URIs を参照してください。
レジストリの管理
aggrega registry は、ワークスペースが認識しているレジストリとその署名信頼ポリシーを管理します。レジストリの識別子はそのホストであり、各サブコマンドは 1 つのアドレス指定モデルを共有します。
aggrega registry add <host>はレジストリを登録してその信頼ポリシーを固定します。信頼フラグで手動でポリシーを与えない限り、最初の接続時にレジストリが公開しているポリシーを取得します。任意の--name <alias>は、ホストをキーとする同じエントリにわかりやすいエイリアスを付けます。識別子はホストのままであり、エイリアスはレジストリが指定されるあらゆる箇所でそのホストに解決されます。エイリアスはレジストリ間で一意です。aggrega registry listは、設定されているすべてのレジストリを、ホスト、エイリアス、信頼状態の短い要約、デフォルトを示すマーカーとともに、ホストの昇順で出力します。解決済みの設定を読み、ネットワークには接続しません。aggrega registry remove <name|host>は、ホストまたはエイリアスで指定したレジストリの信頼ポリシーエントリを削除します。削除するのは信頼ポリシーのみです。default_registryのポインタはそのまま残り、そのホストへのプッシュ機能にも影響しないため、ホストは到達不能になるのではなく、デフォルトの信頼に戻ります。削除されたエントリの名前として記述されたdefault_registryは、その後何も指さなくなり、書き直されるまで拒否されます。aggrega registry updateは、後述するローカルの検索可能インデックスを更新します。
レジストリが指定されるあらゆる箇所(registry サブコマンドの引数、または aggrega push と aggrega push-artifact の --registry フラグ)で、同じリゾルバがトークンを解釈します。設定済みのエイリアスはそのホストに解決され、それ以外のトークンは、参照のスキーム、パス、認証情報を取り除いたうえで、それが指すホストとして読まれます。そのホストが署名の判断の対象となる箇所(aggrega push または aggrega push-artifact の宛先、あるいは aggrega registry add がエントリを書き込むキー)では、上記の唯一の読み方が適用され、その形で書かれていない場合は、書くべき表記を示したうえで拒否されます。その形で書かれた未登録のホストは正当な宛先であり、受け付けられます。
ローカルの検索可能インデックス
aggrega registry update [<name|host>] は、ワークスペースが認識しているレジストリのローカルな検索可能インデックスを構築します。設定済みの各レジストリのリポジトリを走査し、それぞれの最も高いリリース済みバージョンを選び、そのバージョンの検索可能なマニフェストアノテーション(§6)を読み取り、レジストリごとのインデックスをアーティファクトキャッシュに書き込みます。引数がない場合は設定済みのすべてのレジストリをインデックス化し、単一のレジストリ引数(ホストまたはエイリアス)を指定した場合はそのレジストリのみをインデックス化します。
このインデックスは、パッケージマネージャーでおなじみの明示的な更新モデルに従います。registry update はレジストリに接続するコマンドであり、その後の aggrega search は書き込まれたインデックスをオフラインで読みます。レジストリのレコードファイルは決定的です。同じレジストリ状態に対する 2 回の更新はバイト単位で同一の内容を生成し、鮮度を示すタイムスタンプは隣接する別ファイルに置かれるため、レコードを乱すことはありません。リリース済みバージョンのないリポジトリや読み取れないリポジトリはスキップされるため、読み取れないリポジトリが 1 つあってもインデックス全体が放棄されることはありません。
公開されたカタログスナップショット
標準ライブラリのカタログが公開されるたびに、カタログ全体も公開されます。これは 1 つの OCI アーティファクトで、その公開が公開したコミット時点でカタログツリーが保持するすべてのファイルを gzip 圧縮した tar であり、カタログの公開先レジストリの catalog/snapshot に置かれます。公式ハブでは hub.aggrega.ai/catalog/snapshot です。これはその公開のすべてのエンティティがレジストリに置かれた後にのみプッシュされるため、レジストリが保持していないエンティティを指すことはありません。ビルド元のコミットと latest でタグ付けされ、その公開の各エンティティと同様に公開者によってキーレスで署名されるため、公開者の ID によってレジストリの信頼ポリシーのもとで検証されます。latest がスナップショットに移るのは、そのスナップショットが署名された後に限られます。アーカイブは 1 つの固定レイアウトで書き込まれます(エントリは名前の昇順に並び、それぞれ同じモード、所有者、更新時刻を持ちます)。そのため、1 つのコミットからは常に同じ tar が生成されます。
これを読み込むのは、ワークスペースがカタログフォルダを指定していないインポートだけです。つまり、workspace.catalog_dirs も AGGREGA_CATALOG_DIRS もなく、ワークスペースルートに catalog/ ディレクトリもない場合です。aggrega import、エディターセッションのインポート、アシスタントのインポートツールは同じ操作を実行するため、いずれも同じ方法でスナップショットを取得します。インポートは、pull と同じ送信トラフィックのゲートとサインインを通じてワークスペースのデフォルトレジストリからスナップショットを取得し、何かを保持する前にそのレジストリの信頼ポリシーのもとで署名を検証し、ワークスペースのアーティファクトキャッシュに保持して、そこでダイジェストに固定したままカタログフォルダとして読み込みます。そのため、インポーターにはカタログの Components が提示され、--target はその Recipes から Manifest をドラフトします。その経路はカタログフォルダの場合とまったく同じです。インポートがドラフトの隣に書き込む記録はマニフェストのダイジェストでスナップショットを示すため、同じドラフトを後でインポートするときはリクエストなしで同じカタログを読み込みます。また、aggrega import --upgrade は最新のスナップショットを取得し、以降はそれに対してインポートします。オフラインの設定では、スナップショットを取得する必要があるインポートは停止し、実行すべきものを示します。カタログフォルダを指定しているワークスペースはそれに対してインポートし、スナップショットは取得しません。スナップショットを読み込むコマンドは他にありません。pull、ビルド、検証は §5 の階層を通じて各エンティティを解決してロックファイルに固定し、インポートのドラフトはカタログエンティティを名前で参照するため、それらをビルドするときも同じ方法でそれらのエンティティが解決されます。
9. ロックファイルによる固定とアーティファクトの不変性
ロックファイルによる固定の規律は、すべての依存関係を特定のコンテンツアドレス指定可能なアーティファクトに結び付けます。最初のロックファイル解決(aggrega pull)の際、リゾルバはレジストリを参照し、URI の 3 形式の制約(完全一致 / 範囲 / バージョン指定なし)に従ってバージョンを選び、固定したバージョンとダイジェストを Release の <release-stem>.lock に書き込みます。以降の aggrega build の呼び出しは、レジストリの変更可能性にかかわらず固定された値を使用します。新しいバージョンは既存のロックファイルに影響を与えずに公開できます。
この固定モデルには、要となる規則が 1 つあります。ある name:version がレジストリに公開され、ダイジェスト D に解決されると、その対応は永続的です。同じ name:version を異なる内容で再公開することは、プッシュ時に拒否されます。 aggrega push 自体がすべての公開でこれを強制します。対象レジストリ内の name:version にある既存のアーティファクトを解決し、存在してダイジェストがこれからプッシュする内容と一致する場合、プッシュは何もアップロードせず、その公開にまだ欠けているもの(公開日、およびプッシュが署名する場合はその署名)のみを付加します。存在してダイジェストが異なる場合、プッシュは両方のダイジェストを示す不変性違反エラーで停止します。
不変性が重要なのは、次の 2 つの帰結のためです。
- ロックファイルの固定が信頼できます。 ロックファイルが
mariadb:1.0.0をダイジェストDで記録している場合、ダイジェストで取得するビルドはDのバイト列を受け取ります。不変性がなければ、レジストリ側の変更によってロックファイルの固定の下でDのバイト列が置き換えられ、ロック時からビルド時までの安定性が損なわれる可能性があります。再現可能なビルドはこの保証の上に成り立っています。 - 公開後のメタデータ変更には明確な経路があります。 公開済みバージョンを非推奨としてマークすること、署名鍵のローテーション、アテステーションの修正は、公開済みアーティファクトを変更することでは行えません(この規則が禁止しています)。新しいパッチバージョンを公開するか、メタデータの変更を別途記録するサイドカーアーティファクトを公開することで行う必要があります。どちらの経路も監査可能であり(新しいバージョンまたはサイドカーは独立したレジストリエントリとして現れます)、どちらも元のアーティファクトのバイト列を変更しません。
この不変性の規則は、OCI で公開されるすべての Aggrega アーティファクト(エンティティ、SchemaLibrary、MappingLibrary、Recipe の pipeline[].plugin: / FeatureRecipe の pipeline[].plugin: / ワークスペース設定の plugins.{governance,linter,importer}[]: から参照される Wasm プラグイン)に一律に適用されます。ロックファイル内で name:version とコンテンツダイジェストによって固定されるものはすべて不変性の対象です。
不変性は無条件であり、どの設定でも緩和されません。 上書きを許可するフラグやワークスペース設定は存在しません。レジストリが、運用者がオプトインできる上書きの経路を提供していないためです。変更された内容は新しいバージョンで公開し、aggrega lint --pre-publish がバージョンの引き上げが変更の分類と一致することを検証します。
新しいバージョンへの再解決には、ユーザーの明示的な操作が必要です。aggrega pull --upgrade --release <release> <uri> は他のすべての固定を維持したまま単一の依存関係を再解決し、aggrega pull --upgrade --release <release> はすべての依存関係を現在のレジストリ状態に対して再解決します。範囲形式とバージョン指定なし形式の依存関係は、一致する最新バージョンに再解決されます。完全一致形式の固定は、ユーザーが明示的に別の完全一致バージョンにアップグレードしない限り変わりません。ロックファイルはビルドにおける信頼できる唯一の情報源であり、ユーザーが記述した形式はオーサリング時のバージョン制約を表します。
10. カタログエンティティの名前形状の検査
カタログエンティティの名前は、エンティティの種類ごとのパターンに従います。パターンは以下に列挙し、種類ごとの詳細はエンティティリファレンスの概要にあります。これは、開発者が Aggregate や Release に記述するインスタンス名とは別の対象です。インスタンス名は種類に関係なく 1 つのパターンを共有し、そのパターンは ../language-reference/02-naming-conventions.md の「Instance Names」にあります。カタログの YAML が宣言する metadata.name フィールドは、エンティティの正規の参照 URI と常に同一とは限りません。Component と Feature は、パブリッシャーとグループ化のセグメントを metadata.name に直接埋め込みます。Recipe と FeatureRecipe はリーフのみの metadata.name を宣言し、その正規の 2 セグメント URI は、そのリーフとエンティティが宣言する spec.capability を組み合わせたものです。すべてのライブラリ種類は metadata.name に PascalCase のトークンを宣言します。
エンティティの種類ごとの形状:
- Component —
metadata.nameに宣言する 3 つの kebab-case セグメント{publisher}/{category}/{name}。例:core/datastore/postgres。 - Feature —
metadata.nameに宣言する 2 つの kebab-case セグメント{publisher}/{name}。例:core/data-masking。 - Recipe —
metadata.name内の単一の kebab-case リーフ(例:postgres)。正規の参照 URI{capability}/{name}(上記 §6 のとおり)は、エンティティが宣言するspec.capabilityとそのリーフを組み合わせます。先頭セグメントはディスク上のエンティティの場所ではなくspec.capabilityと照合されるため、recipe.yamlを移動しても参照方法は変わりません。標準ライブラリのカタログは、ツリーが座標を反映するようにエンティティを<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlに配置しますが、この反映はカタログの慣例であり、URI の出所ではありません。参照では recipe をベアで指定することもできます。これは capability セグメントを持たないリーフ単体の形で、実際には最も一般的な形であり、カタログ内でその名前を持つ recipe が 1 つだけであれば解決されます。Recipe の URI にパブリッシャーのセグメントは現れず、3 つ目のセグメントを持つ参照はどの recipe にも一致しません。 - FeatureRecipe —
metadata.name内の単一の kebab-case リーフ(例:k8s-secret-from-parameter)で、Recipe と対称です。正規の URI{capability}/{name}は宣言されたspec.capabilityとリーフから構成され、ベアのリーフも同様に受け付けられ、<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlのツリーが慣例により座標を反映します。 - ライブラリ種類 — SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary —
metadata.name内の、^[A-Z][A-Za-z0-9]*$に一致する PascalCase の単一トークン(例:BaseComponents、AIDatastores、BaseWorkloads)。形状はすべてのライブラリ種類で同じなので、ライブラリ間でエントリを移動しても、別の慣例に合わせて名前を変更する必要はありません。各ライブラリ種類の JSON Schema エンベロープも、以下で説明する検査に加えて、このパターンを宣言しています。
Component、Feature、Recipe、FeatureRecipe については、metadata.name の JSON Schema は空でない任意の文字列を受け付けるため、これらの種類では形状に関して構造的なものは何もありません。文書化されたすべての形状は、エンベロープでもパターンを宣言しているライブラリ種類を含め、publishing-discipline プラグインによって検査されます。このプラグインは、コンパイラのディストリビューションと共有する正規表現の信頼できる情報源としてパターンを保持しています。ここで形状を与えられながらプラグインに無視される種類はありません。
この検査はオプトインです。検査を行うコマンドは 1 つだけで、作成者が要求したときにのみ実行されます。検査を行うと最もよく思われている 2 つのコマンドは、検査を行いません:
aggrega lintは名前形状の違反を報告します。 プラグインは、各エンティティのmetadata.nameをその種類のパターンと比較します。検査は作成者がaggrega lintを呼び出したときに実行されます。対象は単一のエンティティ、--releaseを指定した場合は Release の依存関係の閉包、引数なしで呼び出した場合はすべてのカタログエンティティです。同じルールセットは、CLI が公開するエディタ向けのツールからも利用できます。検出結果は助言的なもので、warnの重大度で報告され、処理を停止させません。
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)検出結果は、その重大度と、ルールが登録されている短いコードで始まります。このコードは aggrega explain E0278 で詳細を表示できます。問題のあるファイルのパスが検出結果の上に表示され、カタログ全体の実行では、検査したエンティティの数と発生した助言的な検出結果の数で締めくくられます。
aggrega buildは名前形状を検査しません。 レンダリングされる出力は Aggrega のエンティティ名に依存しないため、準拠しない名前を含むカタログに対するビルドは警告も診断も出さず、そうでない場合とまったく同じように成功します。aggrega pushも名前形状を検査しません。 公開は別の理由で拒否されます。最も顕著なのは上記の不変性ルールで、既存のname:versionを異なる内容で再公開すると停止します。拒否のメッセージがaggrega lint --pre-publishに言及している場合、それは作成者に実行すべきコマンドを伝えているのであり、push 自体がそれを実行するわけではありません。
ビルドも公開も形状を検査しないため、慣例を守らせたいカタログは、pre-commit フックやパイプラインのステップとして、意図的に aggrega lint を実行します。名前形状の検出結果は助言的なものである点に注意してください。aggrega lint はそれを報告しても正常に終了するため、慣例に基づいてゲートを設けたいパイプラインは、終了ステータスに頼るのではなく、報告された検出結果を読み取ります。
ワークスペースごとのポリシーでこのルールを抑制できます:
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseポリシーを設定すると、名前形状ルールは何も報告しなくなります。aggrega lint --allow-nonstandard-names で単一の呼び出しに対して設定することも、--no-allow-nonstandard-names で再び強制的に無効にすることもできます。正当な用途は、公開されることのないカタログ、複数パブリッシャーの実験、および特殊用途のエンティティです。
11. アノテーション駆動の Feature 展開
Manifest の mappings.features.annotations ブロックは、アノテーションキーと Feature 型の間のバインディングに加え、各アノテーションが設定できる Feature スキーマのプロパティを指定する、ピラーごとにグループ化されたルーティングテーブル(maps.infra、maps.values)を宣言します。解決処理のアノテーション展開サブフェーズは、Release の境界を外側から内側へ、Aggregate のサブシステムを外側から内側へとたどり、カスケードとオーバーライド(値全体およびサブキー単位の null によるオプトアウトを含む)によってコンポーネントごとの実効アノテーションセットを計算し、IR の来歴に origin: annotation を持つ合成 Feature アタッチメントを注入します。バインディングの形と記述方法の詳しい解説は language-reference/entities/manifest.md と language-reference/providers/well-known-annotations.md にあります。このセクションでは、展開処理が依存するカタログ読み込み時および inspect 時の仕組みを説明します。
スキーマのコンパイルキャッシュ。 各 Feature の spec.schema.{infra,values} は、ビルドごとに一度だけコンパイルされ、カスケードの走査間で再利用されます。同じ Feature スキーマに対してサブキー単位の型検証を繰り返す場合(コンポーネントごとに 1 つのカスケードスコープ、それが数百のコンポーネント分)、再びコンパイルせずにコンパイル済みのスキーマを読み取ります。ビルド間では何も保持されないため、変更された Feature スキーマは次のビルドで新たにコンパイルされます。
バインディング対象の検証(カタログ読み込み時)。 カタログ読み込み時に、コンパイラはすべての Manifest の features.annotations バインディングを走査し、maps.infra と maps.values の下で宣言されたすべてのドット区切りパスが、参照先の Feature の spec.schema.<pillar> が実際に宣言しているプロパティに対応することを検証します。Feature スキーマに記載のないパスにルーティングするバインディングがあると、バインディングキー、存在しないパス、Feature の URI、ソースの位置を示す明確な OPS_ERROR によってカタログの読み込みが停止します。
スキーマピラー重複の lint(カタログ読み込み時)。 Feature の spec.schema が infra と values の両方のピラーで同じプロパティ名を宣言している場合、助言的な警告が出されます。この重複が意図的であることはまれです。ピラー間で同名のプロパティがあると記述の意図が曖昧になり(アノテーションが共有された名前を対象とするとき、どちらのピラーが適用されるのか)、診断メッセージも複雑になります。この警告は処理を妨げず、オプトアウトもありません。重複を意図している作成者は重複と警告をそのまま残し、意図していない作成者は一方のピラーでプロパティ名を変更します。
バインディングマップ重複の lint(解決時)。 Manifest のバインディング全体で、あるサブキーのパスが maps.infra と maps.values の両方に現れる場合、助言的な警告が出されます。両方のピラーリストに現れるパスは一貫性がありません。1 つのアノテーションのサブキーが両方のピラーに同時にルーティングされることはできず、コンパイラが適用する決定的なタイブレーク(両方のリストに現れるパスは infra にルーティングされます。Aggregate で記述されたアノテーションは values を通してのみルーティングできるため、そこでそのパスに対して記述されたものは拒否されます)は安全策であって、意図された記述の形ではありません。この警告は処理を妨げません。警告を無視して実行してもビルドは問題なく成功し、タイブレークの結果は IR の来歴で確認できます。
aggrega inspect による来歴の表示。 inspect コマンドは、Feature アタッチメントごとに 1 つのブラケットを表示し、設定された各リーフの出所を記録します。
[explicit]— Feature が Aggregate または Release のfeatures:ブロックによって明示的にアタッチされました。[annotation: <key> from <source>]— 設定されたすべてのリーフが同じアノテーションキーに由来します。ブラケットにはキーと、アノテーションが宣言された場所、つまりファイルとその中のドット区切りのキーパスが示されます。- リーフ単位のブラケット — 設定された各リーフがそれぞれのソースブラケット(一部は
[explicit]、一部は[annotation: <key> from <source>])付きで表示される、両側にまたがる合成です。この形は、フィールド単位で明示指定を優先するマージを表します。明示的なアタッチメントとアノテーションからの寄与が同じ Component 上の同じ Feature インスタンスを対象とし、異なるリーフに書き込む場合、両方の寄与がそれぞれのリーフに残り、inspect の出力は各リーフの出所を個別に示します。
inspect の表示は、IR のピラーごとの values_provenance と infra_provenance のマップを読み取ります。これらはアノテーション展開時に合成アタッチメントの注入と並行して設定されます。そのうえで、リーフ全体の出所を最もよく要約するブラケット形式を出力します。inspect の仕組みは、ある Feature アタッチメントがなぜ特定の Component に適用されたのか、その値がどこから来たのかを理解するための正規のイントロスペクション手段です。