Un socket che nessuno ha dichiarato, che consegna valori reali
Questo esempio insegna una linea di demarcazione, in entrambe le sue metà:
Un consumatore può inventare la connessione. Può consumare solo ciò che il produttore dichiara.
L’autore di un Aggregate scrive una voce uses: sul proprio componente sotto un nome di socket che nessuna entità del catalogo dichiara. L’arco viene costruito e consegna — il valore raggiunge l’artefatto renderizzato esattamente come farebbe attraverso un socket dichiarato. Ma dichiarare le chiavi che quell’arco può trasportare spetta ancora alla destinazione: nominane una che la destinazione non dichiara, e il build si arresta.
Tutto qui si risolve dal catalogo della libreria standard. Il workspace non scrive alcun Component, Feature o Recipe proprio.
Lo stack
Tre componenti, e uno di essi è cablato in due modi diversi:
| istanza | tipo | che cosa è |
|---|---|---|
db | core/datastore/mariadb | il database |
model | core/ai-model/anthropic | un endpoint di modello; una realizzazione in forma di riferimento, quindi per esso non viene eseguita alcuna risorsa di calcolo |
web | core/devtool/adminer | la console, che li consuma entrambi |
core/devtool/adminer dichiara esattamente un socket:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]Questo è tutto ciò che il suo autore aveva previsto. Una console davanti a un database è la connessione che aveva in mente; una console che porta un endpoint di modello nel proprio ambiente non lo è.
Che cosa scrive l’Aggregate
aggregate-delivers.yaml cabla entrambi gli archi da un unico blocco 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: modelassistant non compare in alcun usesSchema, né su questo Component né su alcun altro. È comunque lecito: il silenzio del catalogo su un socket significa che la connessione non era stata prevista, non che sia vietata, e lo sviluppatore è il proprietario della topologia della propria applicazione.
Ciò a cui il socket ad hoc rinuncia è esattamente ciò che la voce usesSchema mancante avrebbe portato — nessun selector, quindi nulla vincola quale componente l’arco possa raggiungere e il controllo di sicurezza dei tipi tra nodi non ha nulla da valutare; nessuna allowlist inject:; nessun valueSchema o infraSchema per arco, quindi values: e infra: per arco non hanno alcun contratto rispetto a cui essere verificati né valori predefiniti dichiarati da ereditare. La configurazione per arco scritta su un socket di questo tipo viene accettata e viaggia senza verifica, che è il modo in cui si comporta ogni socket privo di un contratto per quel pilastro — un socket dichiarato che non scrive alcun valueSchema si trova nella stessa posizione.
Ciò a cui non rinuncia è ciò che l’arco può trasportare. endpoint e model sono entrambe chiavi che core/ai-model/anthropic dichiara nel suo pilastro provides.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example adhoc-uses-socketPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd adhoc-uses-socketBuild
aggrega build --release release-delivers.yaml --auto-pullL’output renderizzato e il lockfile sono generati, non distribuiti: questo esempio esegue il commit dei propri input e rigenera tutto il resto. --auto-pull risolve il lockfile durante il build; eseguire una volta in anticipo aggrega pull --release release-delivers.yaml fa lo stesso e permette ai build successivi di essere eseguiti senza alcun flag. Le entità del catalogo si risolvono da hub.aggrega.ai, il registry predefinito che .aggrega-config.yaml indica, quindi né il build né aggrega inspect hanno bisogno di un flag --catalog.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `adhoc-uses-socket`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `adhoc-uses-socket` e senza `dir`: scrive l’esempio in una nuova cartella `adhoc-uses-socket`. Poi chiama lo strumento `build` con `workspace_root` impostato su `adhoc-uses-socket`, `release` impostato su `release-delivers.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `adhoc-uses-socket/dist/`.Leggere l’output
dist/compose/docker-compose.yaml, il servizio 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]Quattro variabili, tre delle quali consegnate tramite archi, e l’output non registra quale socket fosse dichiarato:
ADMINER_DEFAULT_SERVER: dbè arrivata tramitedatabases, il socket dichiarato. Il suo valore è ilprovides.hostdella Recipe del database — il nome di un servizio Compose.ASSISTANT_ENDPOINTeASSISTANT_MODELsono arrivate tramiteassistant, il socket ad hoc, portando ilprovides.endpointe ilprovides.modeldella Recipe del modello.
Si trovano in un’unica mappa, nell’ordine dell’autore, senza alcun marcatore, alcuna annotazione e alcuna differenza di ordinamento tra loro. È proprio questo il punto: un socket ad hoc è una cosa diversa da dichiarare, non una cosa diversa da consegnare. Esiste un solo percorso di consegna ed entrambi gli archi lo percorrono.
ASSISTANT_ENDPOINT merita anche di essere letto come un fatto della compilazione ahead-of-time. Il compilatore non ha contattato Anthropic per scoprire https://api.anthropic.com; la Recipe l’ha emesso come stringa puntatore deterministica ricavata dall’infra.endpoint del componente del modello, e il compilatore ha instradato quella stringa senza interpretarla. Adminer stesso non legge nessuna delle due variabili ASSISTANT_* — lo sviluppatore ha scelto quelle chiavi di consegna, e il container della console le porta per qualunque cosa le legga lì.
Il grafo che il build emette registra la distinzione anche se l’artefatto renderizzato non lo fa: ogni arco porta un campo socket_declaration che vale declared o ad-hoc, così un’organizzazione che vuole che ogni connessione passi attraverso un socket dichiarato dai suoi architetti lo esprime come policy di governance anziché affidarsi al compilatore perché abbia un’opinione. Vedi architecture/11-governance-and-compliance.md.
Il controllo: ciò che il consumatore non può comunque inventare
aggregate-undeclared-key.yaml è aggregate-delivers.yaml con una sola modifica. L’arco ad hoc richiede una terza chiave:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic dichiara endpoint e model nel suo pilastro provides, e nient’altro. Il build dovrebbe fallire:
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")L’arresto è la lezione, e dove scatta è la parte che vale la pena notare: il percorso incriminato nomina il socket ad hoc, uses.assistant, e si ferma alla connessione anziché alla voce di consegna al suo interno. La chiave from: viene verificata rispetto ai provides dichiarati del Component di destinazione su ogni arco, e il fatto che il socket sia ad hoc non cambia nulla di quel controllo. Un autore che può inventare il nome di un socket non può comunque inventare una chiave di output sul componente di qualcun altro.
Prima viene il rifiuto, poi l’Aggregate e il percorso in cui l’arco è stato scritto, il meccanismo e la chiave di consegna sotto cui è stata scritta la voce, la chiave in errore, il tipo di componente rispetto a cui è stata risolta e le chiavi dichiarate di quel tipo in ordine — così la correzione è visibile dal solo messaggio. Un Component di destinazione che non dichiara alcun provides rifiuta allo stesso modo ogni riferimento from: a esso; semplicemente non ci sono chiavi dichiarate da elencare, quindi il messaggio termina dopo il tipo di componente.
Quale scrivere
Dichiarare il socket nel catalogo resta la strada migliore, ed è ciò che fa il catalogo della libreria standard. Un socket dichiarato porta un selector che vincola quali componenti l’arco può raggiungere, una allowlist inject:, un contratto per arco con i propri valori predefiniti e una descrizione — un’affermazione revisionabile di una connessione prevista, versionata con l’entità che la stabilisce. Un socket ad hoc non porta nulla di tutto ciò, e l’arco è sicuro solo quanto l’autore che lo ha scritto.
La forma ad hoc è una via d’uscita, per il caso che questo esempio mostra: una connessione che l’autore del catalogo non aveva previsto, richiesta da una sola Release, dove attendere una modifica del catalogo significherebbe attendere per distribuire. Ricorrici sapendo quanto costa.
Vale la pena dichiarare apertamente due costi:
- Un nome di socket scritto male è un socket ad hoc lecito, non un errore. Scrivere
databsesdove si intendevadatabasesproduce un build verde in cui nulla fluisce attraverso il socket previsto. Il compilatore segnala un nome di socket a una modifica di distanza da uno dichiarato con un avviso che nomina entrambe le grafie — vedi errors/warnings.md «Uses-socket near-miss lint (Lint di quasi corrispondenza dei socket uses)» — ma si tratta di un avviso e non cambia mai il verdetto del build. - Due superfici, deliberatamente, non sono aperte in questo modo. Gli
usesdi un’associazione di Feature possono nominare solo un socket dichiarato dalla Feature associata, e gliusesper arco di una Release possono nominare solo un socket dichiarato dal Component consumatore. Un operatore configura e collega all’interno di un’architettura; non la scrive.release-delivers.yamlporta quindiinfra:e nulla sui socket — il socketassistantè dell’autore dell’Aggregate, e solo suo.
Per il contratto completo, vedi entities/component.md «Topology Sockets: usesSchema (Socket di topologia)» e architecture/07-dependency-resolution.md.