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

誰も宣言していないソケットが実際の値を届ける

この例が教えるのは 1 行の内容と、その両面です。

利用側は接続を自ら作り出せます。ただし消費できるのは、提供側が宣言したものだけです。

Aggregate の作成者は、どのカタログエンティティも宣言していないソケット名で、 自分のコンポーネントに uses: エントリを書きます。エッジは構築され、値を届けます。 値は、宣言済みのソケットを通した場合とまったく同じように、レンダリングされた成果物に到達します。しかし、 そのエッジが運べるキーを宣言するのは依然としてターゲット側です。ターゲットが宣言していないキーを指定すると、 ビルドは停止します。

ここにあるものはすべて標準ライブラリのカタログから解決されます。ワークスペースは 独自の Component、Feature、Recipe を一切作成しません。

スタック

コンポーネントは 3 つで、そのうち 1 つは 2 通りの方法で接続されます。

インスタンス型内容
dbcore/datastore/mariadbデータベース
modelcore/ai-model/anthropicモデルのエンドポイント。参照形式の実現なので、これのために動作するコンピュートはありません
webcore/devtool/adminer両方を消費するコンソール

core/devtool/adminer が宣言するソケットはちょうど 1 つです。

usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]

それが作成者の想定したすべてです。データベースの前段に立つコンソールは 作成者が念頭に置いていた接続ですが、モデルのエンドポイントを環境に持つコンソールは そうではありません。

Aggregate が書く内容

aggregate-delivers.yaml は、1 つの uses: ブロックから両方のエッジを接続します。

web:
type: core/devtool/adminer
uses:
databases: # DECLARED — the socket the Component's usesSchema names
db:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER
from: host
assistant: # AD-HOC — declared nowhere
model:
target: model
inject:
env:
- in: ASSISTANT_ENDPOINT
from: endpoint
- in: ASSISTANT_MODEL
from: model

assistant は、この Component にも他のどこにも、どの usesSchema にも現れません。 それでも正当です。カタログがソケットについて何も述べていないことは、その接続が 想定されていなかったことを意味し、禁止されていることを意味しません。また、開発者は自分の アプリケーションのトポロジーを所有します。

アドホックなソケットが失うのは、欠けている usesSchema エントリが 運ぶはずだったものそのものです。selector がないため、エッジがどのコンポーネントに 到達できるかを制約するものはなく、ノード間の型安全性チェックには評価対象がありません。 inject: 許可リストもありません。エッジごとの valueSchema や infraSchema もないため、エッジごとの values: と infra: には照合すべき契約も継承すべき宣言済みデフォルトもありません。このようなソケットに書かれた エッジごとの設定は受け入れられ、チェックされずに運ばれます。これは、その柱について契約を持たない すべてのソケットと同じ振る舞いで、valueSchema を作成していない宣言済みソケットも同じ 立場にあります。

失わないのは、エッジが運べるものです。endpoint と model はどちらも、core/ai-model/anthropic が provides の柱で宣言しているキーです。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example adhoc-uses-socket

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd adhoc-uses-socket

ビルド

Terminal window
aggrega build --release release-delivers.yaml --auto-pull

レンダリングされた出力とロックファイルは生成されるもので、同梱されていません。この例は入力をコミットし、それ以外はすべて再生成します。--auto-pull はビルド中にロックファイルを解決します。事前に一度 aggrega pull --release release-delivers.yaml を実行しても同じ結果になり、以降のビルドはフラグなしで実行できます。カタログのエンティティは .aggrega-config.yaml が指定するデフォルトレジストリ hub.aggrega.ai から解決されるため、ビルドも aggrega inspect も --catalog フラグを必要としません。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `adhoc-uses-socket` フォルダーがない場合は、`example` を `adhoc-uses-socket` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `adhoc-uses-socket` フォルダーに書き出されます。次に、`workspace_root` を `adhoc-uses-socket`、`release` を `release-delivers.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `adhoc-uses-socket/dist/` の下にあります。

出力を読む

dist/compose/docker-compose.yaml の web サービス:

web:
image: adminer:4
environment:
ADMINER_DESIGN: pepa-linha-dark
ADMINER_DEFAULT_SERVER: db
ASSISTANT_ENDPOINT: https://api.anthropic.com
ASSISTANT_MODEL: claude-sonnet-4-5
[… omitted: the service's ports, provenance labels, networks, depends_on and healthcheck]

変数は 4 つで、そのうち 3 つはエッジを通じて届けられたものです。そして出力には、どのソケットが 宣言されていたかは記録されません。

  • ADMINER_DEFAULT_SERVER: db は、宣言済みのソケットである databases を通じて届きました。その 値はデータベース Recipe の provides.host、つまり Compose のサービス名です。
  • ASSISTANT_ENDPOINT と ASSISTANT_MODEL は、アドホックな ソケットである assistant を通じて届き、モデル Recipe の provides.endpoint と provides.model を運んでいます。

これらは 1 つのマップに、作成者が書いた順序で並び、両者の間にマーカーも注釈も 順序の違いもありません。それが要点です。アドホックなソケットは 宣言 のしかたが異なるだけで、 届け方 が異なるわけではありません。届ける経路は 1 つで、両方のエッジがそれを通ります。

ASSISTANT_ENDPOINT は、AOT コンパイルの事実として読む価値もあります。 コンパイラは https://api.anthropic.com を見つけるために Anthropic に接続したわけではありません。 Recipe がモデルコンポーネントの infra.endpoint を源とする決定的なポインタ文字列としてそれを出力し、 コンパイラはその文字列を解釈せずにルーティングしました。Adminer 自体はどちらの ASSISTANT_* 変数も読みません。 それらの配送キーを選んだのは開発者であり、コンソールのコンテナは、そこでそれらを読む何かのために それらを保持しています。

レンダリングされた成果物には記録されなくても、ビルドが出力するグラフにはこの区別が 記録されます。すべてのエッジは declared または ad-hoc を値とする socket_declaration フィールドを持つため、 すべての接続を自社の Architect が宣言したソケット経由にしたい組織は、コンパイラに主張を持たせることに 頼るのではなく、それをガバナンスポリシーとして表現します。 architecture/11-governance-and-compliance.md を参照してください。

対照実験: 利用側が依然として作り出せないもの

aggregate-undeclared-key.yaml は、aggregate-delivers.yaml に 1 か所だけ編集を加えたものです。 アドホックなエッジが 3 つ目のキーを要求します。

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic は provides の柱で endpoint と model を宣言しており、それ以外は宣言していません。このビルドは失敗することが想定されています。

Terminal window
aggrega build --release release-negative-undeclared-key.yaml --auto-pull
# [… omitted: a refused: line carrying the message below]
# [DEVELOPER_ERROR E0156] .spec.components.web.uses.assistant.model
# invalid inject key: the from-key must name a provides key its source publishes
# (Aggregate adhoc-uses-socket-undeclared-key,
# at .spec.components.web.uses.assistant.model, "env", "ASSISTANT_API_KEY", "api_key",
# "core/ai-model/anthropic", "endpoint", "model")

この停止こそが教訓であり、注目すべきはそれが どこで 発生するかです。 問題のパスはアドホックなソケット uses.assistant を指し、その内部の配送エントリではなく 接続のところで止まります。from: キーはすべてのエッジでターゲット Component が宣言した provides と照合され、 ソケットがアドホックであってもそのチェックは何も変わりません。ソケット名を作り出せる作成者であっても、 他者のコンポーネントの出力キーを作り出すことはできません。

まず拒否が示され、次に Aggregate とエッジが作成されたパス、 メカニズムとエントリが書かれた配送キー、問題のキー、解決対象となったコンポーネント型、 そしてその型の宣言済みキーがソート順で示されます。そのため、メッセージだけで修正方法がわかります。 provides をまったく宣言していないターゲット Component も、同様にそれへのすべての from: 参照を拒否します。 その場合は列挙する宣言済みキーがないだけなので、メッセージはコンポーネント型の後で終わります。

どちらを書くべきか

カタログでソケットを宣言するほうが依然としてより良い方法であり、標準ライブラリのカタログもそうしています。 宣言済みのソケットは、エッジが到達できるコンポーネントを制約する selector、inject: 許可リスト、 独自のデフォルトを持つエッジごとの契約、そして説明を持ちます。これは想定された接続についての レビュー可能な記述であり、それを行うエンティティとともにバージョン管理されます。 アドホックなソケットはそのいずれも持たず、エッジの安全性はそれを書いた作成者次第です。

アドホック形式はエスケープハッチであり、この例が示すケース、つまりカタログ作成者が想定しておらず、 1 つのデプロイメントが必要とし、カタログの変更を待つことが出荷を待つことを意味する接続のためのものです。 その代償を理解したうえで使ってください。

はっきり述べておくべき代償が 2 つあります。

  • ソケット名のスペルミスは正当なアドホックソケットになります。エラーにはなりません。 databases のつもりで databses と書くと、意図したソケットを何も流れないままビルドは成功します。 コンパイラは、宣言済みのソケット名から 1 編集以内のソケット名を、両方の綴りを示す勧告として報告します (errors/warnings.md の「Uses-socket near-miss lint」を参照)。 ただしこれは警告であり、ビルドの判定を変えることはありません。
  • 2 つの面は意図的にこの方法では開かれていません。 Feature のアタッチメントの uses は、アタッチされた Feature が宣言するソケットしか指定できず、Release の エッジごとの uses は、利用側の Component が宣言するソケットしか指定できません。 オペレーターはアーキテクチャの中で設定と接続を行いますが、アーキテクチャを作成はしません。 したがって release-delivers.yaml は infra: を持ち、ソケットについては何も持ちません。 assistant ソケットは Aggregate の作成者のものであり、その作成者だけのものです。

完全な契約については、 entities/component.md の「Topology Sockets: usesSchema」と architecture/07-dependency-resolution.md を参照してください。