Un socket que personne n’a déclaré, qui livre de vraies valeurs
Cet exemple enseigne une ligne de partage, et ses deux moitiés :
Un consommateur peut inventer la connexion. Il ne peut consommer que ce que le producteur déclare.
L’auteur d’un Aggregate écrit une entrée uses: sur son propre composant sous un nom de socket qu’aucune entité du catalogue ne déclare. L’arête est construite et elle livre — la valeur atteint l’artefact rendu exactement comme elle le ferait par un socket déclaré. Mais les clés que cette arête peut porter restent à déclarer par la cible : nommez-en une que la cible ne déclare pas, et le build s’arrête.
Tout ici se résout depuis le catalogue de la bibliothèque standard. Le workspace ne rédige aucun Component, aucune Feature ni aucune Recipe qui lui soit propre.
La pile
Trois composants, dont l’un est câblé de deux manières différentes :
| instance | type | ce que c’est |
|---|---|---|
db | core/datastore/mariadb | la base de données |
model | core/ai-model/anthropic | un endpoint de modèle ; une réalisation sous forme de référence, donc aucune ressource de calcul ne s’exécute pour lui |
web | core/devtool/adminer | la console, qui consomme les deux |
core/devtool/adminer déclare exactement un socket :
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]C’est tout ce que son auteur avait anticipé. Une console placée devant une base de données est la connexion qu’il avait en tête ; une console portant un endpoint de modèle dans son environnement ne l’est pas.
Ce qu’écrit l’Aggregate
aggregate-delivers.yaml câble les deux arêtes depuis un seul bloc 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 n’apparaît dans aucun usesSchema, ni sur ce Component ni sur aucun autre. C’est néanmoins légal : le silence du catalogue sur un socket signifie que la connexion n’a pas été anticipée, non qu’elle est interdite, et le développeur est maître de la topologie de sa propre application.
Ce à quoi renonce le socket ad hoc est exactement ce qu’aurait porté l’entrée usesSchema manquante — pas de selector, donc rien ne contraint le composant que l’arête peut atteindre et la vérification de sûreté de typage entre nœuds n’a rien à évaluer ; pas de liste d’autorisation inject: ; pas de valueSchema ni de infraSchema par arête, de sorte que les values: et infra: par arête n’ont aucun contrat par rapport auquel être vérifiés ni aucune valeur par défaut déclarée à hériter. La configuration par arête écrite sur un tel socket est acceptée et circule sans vérification, ce qui est le comportement de tout socket sans contrat pour ce pilier — un socket déclaré qui ne rédige aucun valueSchema est dans la même situation.
Ce à quoi il ne renonce pas, c’est ce que l’arête peut porter. endpoint et model sont toutes deux des clés que core/ai-model/anthropic déclare dans son pilier provides.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example adhoc-uses-socketElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd adhoc-uses-socketBuild
aggrega build --release release-delivers.yaml --auto-pullLa sortie rendue et le lockfile sont générés, non livrés : cet exemple versionne ses entrées et régénère tout le reste. --auto-pull résout le lockfile pendant le build ; exécuter une fois au préalable aggrega pull --release release-delivers.yaml produit le même effet et permet aux builds ultérieurs de s’exécuter sans aucun flag. Les entités du catalogue se résolvent depuis hub.aggrega.ai, le registre par défaut que nomme .aggrega-config.yaml, de sorte que ni le build ni aggrega inspect n’ont besoin d’un flag --catalog.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `adhoc-uses-socket`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `adhoc-uses-socket` et sans `dir` : il écrit l’exemple dans un nouveau dossier `adhoc-uses-socket`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `adhoc-uses-socket`, `release` défini sur `release-delivers.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `adhoc-uses-socket/dist/`.Lire la sortie
dist/compose/docker-compose.yaml, le service 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]Quatre variables, dont trois livrées par des arêtes, et la sortie n’enregistre pas quel socket était déclaré :
ADMINER_DEFAULT_SERVER: dbest arrivée pardatabases, le socket déclaré. Sa valeur est leprovides.hostde la Recipe de la base de données — un nom de service Compose.ASSISTANT_ENDPOINTetASSISTANT_MODELsont arrivées parassistant, le socket ad hoc, portant leprovides.endpointet leprovides.modelde la Recipe du modèle.
Elles figurent dans une même map, dans l’ordre de l’auteur, sans marqueur, sans annotation et sans différence d’ordre entre elles. C’est tout l’enjeu : un socket ad hoc est une chose différente à déclarer, pas une chose différente à livrer. Il n’existe qu’un seul chemin de livraison et les deux arêtes l’empruntent.
ASSISTANT_ENDPOINT mérite aussi d’être lu comme un fait de compilation ahead-of-time. Le compilateur n’a pas contacté Anthropic pour découvrir https://api.anthropic.com ; la Recipe l’a émis comme une chaîne de pointeur déterministe issue de l’infra.endpoint du composant du modèle, et le compilateur a acheminé cette chaîne sans l’interpréter. Adminer lui-même ne lit aucune des variables ASSISTANT_* — le développeur a choisi ces clés de livraison, et le conteneur de la console les porte pour ce qui les y lit.
Le graphe qu’émet le build enregistre la distinction même si l’artefact rendu ne le fait pas : chaque arête porte un champ socket_declaration valant declared ou ad-hoc, de sorte qu’une organisation qui veut que chaque connexion passe par un socket déclaré par ses architectes l’exprime sous forme de politique de gouvernance plutôt que de compter sur le compilateur pour avoir une opinion. Voir architecture/11-governance-and-compliance.md.
Le contrôle : ce que le consommateur ne peut toujours pas inventer
aggregate-undeclared-key.yaml est aggregate-delivers.yaml avec une seule modification. L’arête ad hoc demande une troisième clé :
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic déclare endpoint et model dans son pilier provides, et rien d’autre. Le build doit échouer :
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’arrêt est la leçon, et l’endroit où il se déclenche est la partie à remarquer : le chemin fautif nomme le socket ad hoc, uses.assistant, et s’arrête à la connexion plutôt qu’à l’entrée de livraison qu’elle contient. La clé from: est vérifiée par rapport aux provides déclarés du Component cible sur chaque arête, et le fait que le socket soit ad hoc ne change rien à cette vérification. Un auteur qui peut inventer un nom de socket ne peut toujours pas inventer une clé de sortie sur le composant de quelqu’un d’autre.
Le refus vient en premier, puis l’Aggregate et le chemin où l’arête a été écrite, le mécanisme et la clé de livraison sous laquelle l’entrée a été écrite, la clé en cause, le type de composant par rapport auquel elle a été résolue, et les clés déclarées de ce type dans l’ordre trié — de sorte que la correction est visible à partir du seul message. Un Component cible qui ne déclare aucun provides rejette de la même manière toute référence from: vers lui ; il n’y a simplement aucune clé déclarée à lister, donc le message se termine après le type de composant.
Laquelle écrire
Déclarer le socket dans le catalogue reste la meilleure voie, et c’est ce que fait le catalogue de la bibliothèque standard. Un socket déclaré porte un selector qui contraint les composants que l’arête peut atteindre, une liste d’autorisation inject:, un contrat par arête avec ses propres valeurs par défaut, et une description — un énoncé révisable d’une connexion anticipée, versionné avec l’entité qui l’établit. Un socket ad hoc ne porte rien de tout cela, et l’arête n’est sûre que dans la mesure où l’est l’auteur qui l’a écrite.
La forme ad hoc est une porte de sortie, pour le cas que montre cet exemple : une connexion que l’auteur du catalogue n’avait pas anticipée, nécessaire à une seule Release, où attendre une modification du catalogue reviendrait à attendre pour livrer. Recourez-y en connaissant son coût.
Deux coûts méritent d’être énoncés clairement :
- Un nom de socket mal orthographié est un socket ad hoc légal, et non une erreur. Écrire
databseslà oùdatabasesétait voulu produit un build vert dans lequel rien ne circule par le socket prévu. Le compilateur signale un nom de socket à une modification près d’un nom déclaré par un avertissement qui nomme les deux orthographes — voir errors/warnings.md « Uses-socket near-miss lint (Lint de quasi-correspondance des sockets uses) » — mais c’est un avertissement et il ne change jamais le verdict du build. - Deux surfaces ne sont délibérément pas ouvertes de cette manière. Le
usesd’un rattachement de Feature ne peut nommer qu’un socket que déclare la Feature rattachée, et leusespar arête d’une Release ne peut nommer qu’un socket que déclare le Component consommateur. Un opérateur configure et câble au sein d’une architecture ; il ne la rédige pas.release-delivers.yamlporte doncinfra:et rien concernant les sockets — le socketassistantappartient à l’auteur de l’Aggregate, et à lui seul.
Pour le contrat complet, voir entities/component.md « Topology Sockets: usesSchema (Sockets de topologie) » et architecture/07-dependency-resolution.md.