依存関係の解決
Aggrega の依存関係解決と構造トポロジーの柱
Aggrega のアーキテクチャでは、values ペイロードを完全に不透明なまま保つため、トポロジー上の依存関係は uses スキーマの柱を通じて明示的にマッピングされます。「誰が誰と通信するか」の解決には特有の難しさがあります。開発者に明示的なネットワークルーティング、オーケストレーターレベルの実行順序、インフラの依存関係を書かせることなく、複雑な複数ノードのアプリケーショントポロジーをマッピングしなければなりません。
1. 基本思想:なぜ uses なのか
uses ブロックは、コンポーネント間の依存関係を純粋なトポロジーとして宣言します。Component A は Component B の公開 provides 契約に依存し、Component B の物理アドレスや接続情報には依存しません。トポロジーは uses に、設定は values に置かれます。この分離により、コンパイラは values の内容から推測することなく、コンポーネント間のすべてのエッジを明示的に把握できます。
Aggrega は、トポロジーを uses という第一級のスキーマの柱に昇格させることでこれを解決します。
- セマンティックプロキシの論拠: キーワード
usesは L7 のセマンティックな意図を表します。エージェントがデータベースをusesする場合、Platform Ops が両者の間に透過的な Wasm プロキシメッシュを挿入しても、その意味は変わらず真のままです。 - 数学的中立性: Go コンパイラは
uses構造体をネイティブに解析して中間表現(IR)グラフを描きます。開発者のアプリケーションロジック(values)を解析したり照会したりすることは決してありません。 - Feature の原子性:
usesの柱は Components と Features(認証情報の Features を含む)に同一に適用されます。これにより、サイドカープロキシ(Feature)や認証情報フェッチャーは、親 Component の設定を汚すことなく、自身のネットワーク依存関係を自律的に宣言できます。
2. 統合スキーマ契約の仕組み
アプリケーションのペイロードを解析せずに運用上の指示を取り出すため、システムは明示的に分離された YAML 構造を統制する厳密な JSON Schema 2020-12 の宣言に依拠します。
ドメイン 2:分割スキーマ(usesSchema と schema)
プラットフォームカタログが管理不能なスキーマファイルに断片化するのを防ぐため、Aggrega は分割スキーマエンジンを使用します。ネイティブ YAML の usesSchema がトポロジーを厳密に定義・検証し、schema:(JSON Schema 2020-12。通常はコンパクト形式の省略記法で記述)が values と infra の柱の内容を検証し、provides の柱の形状を宣言します。開発者が記述する values とオペレーターが設定する infra は、宣言された型に照らして検査されます。provides のサブスキーマは Recipe が生成する下流契約のキー名と型を宣言し、コンパイラはすべての inject 参照が宣言済みの provides キーを指していることを検査します。ただし、生成された provides の値そのものは、コンパイラが解釈せずに受け渡す不透明な文字列として下流に流れ、型検査される値ではありません。コアは受け渡される値の意味を解釈しないからです。ソケットが宣言されるのは usesSchema であり、宣言することがソケットに契約を与えます。 カタログエンティティが宣言するソケットは、そのエンティティの制約を持ちます。到達できるターゲットを示すセレクター、inject の許可リスト、エッジごとの valueSchema / infraSchema です。usesSchema 内で Platform Architect は selector: フィールドを使用し(Architect が書いた文字列として読まれ、生成されるスキーマにはコピーされません)、ネイティブの Go セレクターエンジンがそれを評価して、宣言済みソケットに対するノード間の型安全性を強制します。これにより、ソケットがデータベースを要求している場合、開発者が Web サーバーを接続することはできません。
セレクターは評価される時点、つまりソケットを通じて配線される各エッジにつき 1 回、その文法に照らされます。エンジンが 6 つの要件形式のいずれとしても読めないセレクター(余分なカンマによって残った空の要件、空白や文法が形式の区別に使う文字(=、!、(、)、カンマ)を含むキー、閉じ括弧のない集合)は、別のセレクターとして読まれるのではなく、要件を示したうえでそのエッジでビルドを停止させます。この厳密さが検査を誠実に保ちます。寛容に読めば、フロントエンドを排除するために書かれた !tier=frontend は、tier=frontend という名前のラベルがないことだけを求めることになり、フロントエンドを含むすべてのターゲットが通過してしまいます。同じ文法がアタッチメントスロットのセレクターと Feature の appliesTo にも適用されます。すべての形式と拒否の一覧はセレクターの文法にあります。ビルドはエッジが 1 つも配線されていないソケットを評価しないため、aggrega validate は、カタログ全体に対しても、ソケットを宣言する Component または Feature に対しても、宣言されたすべてのソケットのセレクターを読み取り、不正なセレクターをその時点で拒否します。その際のコードと文言は、そのソケットを配線するビルドが使うものと同じです。
ただし、ソケットの宣言だけがエッジを描く唯一の方法ではありません。Aggregate の作成者は、カタログエンティティが宣言していないソケットを自分のコンポーネント上で指定でき(usesSchema をまったく宣言しないコンポーネント型も含みます)、そのエッジは構築されます。ソケットのエントリを宣言していないカタログは、その接続を想定していなかっただけで、禁止しているわけではなく、アプリケーションのトポロジーは開発者が所有します。このようなソケットはアドホックと呼ばれ、その代償はちょうど宣言によって得られるものです。カタログエントリがないため、セレクターもエッジごとの契約もなく、ノード間の型安全性には評価する対象がありません。エッジが運べるものは変わりません。注入するすべてのキーは依然としてターゲットの provides が宣言するキーを指さなければならず、ターゲットも存在しなければなりません。出力されるグラフのすべてのエッジは、2 つのどちらであるかを記録するため、利用者が推測する必要はありません。オペレーターがアドホックソケットを全面的に禁止する方法は governance-and-compliance を参照してください。
2 つの面は、アプリケーションのトポロジーを記述するものではないため、意図的にこの方法では開かれていません。Feature アタッチメントの uses は、アタッチされる Feature が宣言するソケットしか指定できず、Release のエッジごとの uses は、消費側のコンポーネントのカタログエンティティが usesSchema で宣言するソケットしか指定できず、Aggregate がアドホックに記述したソケットは指定できません。オペレーターはアーキテクチャの中で設定と配線を行い、Feature は自身のカタログエンティティが宣言するトポロジーに参加します。また、カタログでソケットを宣言することは引き続きより良い方法であり、標準ライブラリのカタログもそうしています。アドホックソケットはエスケープハッチであり、新しいデフォルトではありません。
ドメイン 1:開発者体験(ポリモーフィズム)
開発者は uses: を values: や features: と同じ階層に書きます。摩擦のない UX を確保するため、スキーマはポリモーフィズムをネイティブにサポートします。
- 文字列の配列: 標準のルーティングで十分な、単純な論理コンポーネント参照に使用します(例:
tools: ["search-api"])。 - オブジェクトのマップ: 厳密な配信契約が必要な場合に使用します(例:
databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } })。 - ワイルドカードなし: ワイルドカード形式は存在せず、これにより「ゴースト依存関係」や無許可の自動配線が防がれます。各エントリは 1 つのコンポーネントを指定するため、
["*"]は存在しないターゲットとしてビルドを停止します。どのコンポーネント名にも*は含められません。
ドメイン 3:運用の実際(正規化)
Go テンプレートを予測可能に保つため、Go コンパイラはポリモーフィックな uses の入力を正規化します。論理コンポーネント参照の配列は標準オブジェクトに変換され、そのうえで .context.uses と呼ばれる厳密でフラットな辞書に渡されます。
3. エンドツーエンドの例
以下の 2 つの例は、明示的なトポロジーの柱が持つ 2 つの異なる性質を示します。例 A は接続が認可されているかどうか(ノード間の型安全性)を、例 B は接続データが物理的にどのように配信されるか(ポリモーフィズムと正規化)を示します。
例 A:トポロジー検証とノード間の型安全性
このシナリオでは、宣言されたソケット上のセレクターが、AI エージェントが必要なコンプライアンスラベルを持たないデータベースに接続しようとしていることを検出し、ビルドを停止する流れを追います。コンパイラは Architect が書いたラベルセレクターを、文字列としてターゲットのラベルに対して評価します。ラベルの意味は解釈せず、ポリシープラグインも関与しません。
1. 標準ライブラリ(カタログ内の統合 schema:)
プラットフォームアーキテクトがスキーマ構造を定義し、認知ロジックとトポロジー上のターゲットをネイティブに分離します。
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/enterprise-agent version: 1.0.0 labels: component.aggrega.ai/type: "worker"spec: usesSchema: datastores: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema: # 1. The Cognitive Intent values: system_prompt: { type: string, required: true }2. 開発者の意図(Aggregate)
開発者は、エージェントが行うこと(values)とエージェントの接続先(uses)を明確に分離します。
components: my_secure_vector_db: type: core/qdrant-secure:1.0.0 values: collection_name: finance_data
auditing_agent: type: core/enterprise-agent:1.0.0 values: system_prompt: "You are a financial auditing AI..." uses: datastores: finance_memory: { target: "my_secure_vector_db" }3. コンパイラの実行とトポロジー検証
- ローカル検証: Go コンパイラは解決時に、解決済みの JSON Schema に照らしてオブジェクト全体を評価します。
my_secure_vector_dbの基になるカタログラベルを確認します。データベースにrestrictedラベルがなければ、コンパイラは型安全性違反として直ちにビルドを停止します。 - グラフの描画: トポロジー構築時、Go コンパイラはスキーマ検証済みのコンテンツを完全に無視します。YAML から
uses.datastores.finance_memory.targetをネイティブに読み取り、IR グラフに明示的なエッジを描きます。
例 B:ポリモーフィズムと正規化された .context.uses
このシナリオでは、コンパイラがブラックボックスの AI ツール(配列として渡される)と、レガシーのリレーショナルデータベース(inject 契約を持つマップが必要)の両方を扱う方法を示します。
1. カタログ(ドメイン 2):schema: 宣言
アーキテクトは、ツールにはポリモーフィックな配列を許可しますが、データベースには厳密なオブジェクトを要求します。
spec: usesSchema: # Polymorphic Array Socket (No injection needed) tools: selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract) databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file"]
schema: values: system_prompt: { type: string, required: true }2. 開発者の意図(ドメイン 1):Aggregate 開発者は、ツールには簡潔な配列を、データベースには明示的なマップを使用します。
components: my-agent: type: core/python-worker:1.0.0 values: system_prompt: "You are an HR bot."
uses: # 1. Polymorphic Array: Simple logical component reference tools: - "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery databases: hr_db: target: corporate-hr-db inject: env: - in: HR_DATABASE_URI # Local env var from: "host" # Target provides key3. Ops の現実(ドメイン 3):Recipe Go コンパイラがポリモーフィズムを正規化します。Ops はフラットで予測可能な .context.uses 辞書を受け取ります。テンプレートの該当箇所で .context.inject パイプをループするだけです。
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: generic-worker version: 1.0.0spec: capability: helm implements: core/python-worker:1.0.0 source: "./charts/internal/python-runner"
locals: primary_compute: worker-container
valuesMapping: | env: # Ops uses the pre-resolved inject map, kept apart from values and topology loops {{- range $key, $value := .context.inject.env }} - name: {{ $key }} value: "{{ $value }}" {{- end }}