Un socket que nadie declaró, que entrega valores reales
Este ejemplo enseña una línea divisoria, y sus dos mitades:
Un consumidor puede inventar la conexión. Solo puede consumir lo que el productor declara.
El autor de un Aggregate escribe una entrada uses: en su propio componente bajo un nombre de socket que ninguna entidad del catálogo declara. La arista se construye y entrega — el valor llega al artefacto renderizado exactamente como lo haría a través de un socket declarado. Pero declarar las claves que esa arista puede transportar sigue correspondiendo al destino: nombra una que el destino no declare, y la compilación se detiene.
Todo aquí se resuelve desde el catálogo de la biblioteca estándar. El workspace no crea ningún Component, Feature ni Recipe propio.
La pila
Tres componentes, y uno de ellos está cableado de dos formas distintas:
| instancia | tipo | qué es |
|---|---|---|
db | core/datastore/mariadb | la base de datos |
model | core/ai-model/anthropic | un endpoint de modelo; una realización en forma de referencia, así que no se ejecuta ningún cómputo para él |
web | core/devtool/adminer | la consola, que consume ambos |
core/devtool/adminer declara exactamente un socket:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]Eso es todo lo que su autor previó. Una consola delante de una base de datos es la conexión que tenía en mente; una consola que lleva un endpoint de modelo en su entorno no lo es.
Lo que escribe el Aggregate
aggregate-delivers.yaml cablea ambas aristas desde un único bloque 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 no aparece en ningún usesSchema, ni en este Component ni en ningún otro. Aun así es válido: el silencio del catálogo sobre un socket significa que la conexión no se previó, no que esté prohibida, y el desarrollador es dueño de la topología de su propia aplicación.
Lo que el socket ad hoc pierde es exactamente lo que habría aportado la entrada usesSchema que falta — ningún selector, así que nada restringe a qué componente puede llegar la arista y la comprobación de seguridad de tipos entre nodos no tiene nada que evaluar; ninguna lista de permitidos inject:; ningún valueSchema ni infraSchema por arista, así que los values: e infra: por arista no tienen ningún contrato contra el que comprobarse ni valores predeterminados declarados que heredar. La configuración por arista escrita en un socket así se acepta y viaja sin comprobar, que es como se comporta todo socket sin contrato para ese pilar — un socket declarado que no define ningún valueSchema está en la misma situación.
Lo que no pierde es lo que la arista puede transportar. endpoint y model son ambas claves que core/ai-model/anthropic declara en su pilar provides.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example adhoc-uses-socketDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd adhoc-uses-socketCompilación
aggrega build --release release-delivers.yaml --auto-pullLa salida renderizada y el lockfile se generan, no se distribuyen: este ejemplo confirma en el repositorio sus entradas y regenera todo lo demás. --auto-pull resuelve el lockfile durante la compilación; ejecutar una vez antes aggrega pull --release release-delivers.yaml hace lo mismo y permite que las compilaciones posteriores se ejecuten sin ningún flag. Las entidades del catálogo se resuelven desde hub.aggrega.ai, el registro predeterminado que nombra .aggrega-config.yaml, así que ni la compilación ni aggrega inspect necesitan un flag --catalog.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `adhoc-uses-socket`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `adhoc-uses-socket` y sin `dir`: escribe el ejemplo en una nueva carpeta `adhoc-uses-socket`. Después llama a la herramienta `build` con `workspace_root` establecido en `adhoc-uses-socket`, `release` establecido en `release-delivers.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `adhoc-uses-socket/dist/`.Leer la salida
dist/compose/docker-compose.yaml, el servicio 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]Cuatro variables, tres de ellas entregadas a través de aristas, y la salida no registra qué socket estaba declarado:
ADMINER_DEFAULT_SERVER: dbllegó a través dedatabases, el socket declarado. Su valor es elprovides.hostde la Recipe de la base de datos — un nombre de servicio de Compose.ASSISTANT_ENDPOINTyASSISTANT_MODELllegaron a través deassistant, el socket ad hoc, llevando elprovides.endpointy elprovides.modelde la Recipe del modelo.
Están en un mismo mapa, en el orden del autor, sin marcador, sin anotación y sin diferencia de orden entre ellas. Esa es la clave: un socket ad hoc es algo distinto al declarar, no algo distinto al entregar. Hay una sola ruta de entrega y ambas aristas la toman.
ASSISTANT_ENDPOINT también merece leerse como un hecho de la compilación ahead-of-time. El compilador no contactó con Anthropic para descubrir https://api.anthropic.com; la Recipe lo emitió como una cadena de puntero determinista obtenida del infra.endpoint del componente del modelo, y el compilador encaminó esa cadena sin interpretarla. El propio Adminer no lee ninguna de las variables ASSISTANT_* — el desarrollador eligió esas claves de entrega, y el contenedor de la consola las lleva para lo que las lea allí.
El grafo que emite la compilación registra la distinción aunque el artefacto renderizado no lo haga: cada arista lleva un campo socket_declaration con valor declared o ad-hoc, así que una organización que quiere que toda conexión pase por un socket declarado por sus arquitectos lo expresa como una política de gobernanza en lugar de confiar en que el compilador tenga una opinión. Consulta architecture/11-governance-and-compliance.md.
El control: lo que el consumidor sigue sin poder inventar
aggregate-undeclared-key.yaml es aggregate-delivers.yaml con una sola modificación. La arista ad hoc pide una tercera clave:
- in: ASSISTANT_API_KEY from: api_keycore/ai-model/anthropic declara endpoint y model en su pilar provides, y nada más. La compilación debería fallar:
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")La detención es la lección, y dónde se produce es la parte que merece atención: la ruta infractora nombra el socket ad hoc, uses.assistant, y se detiene en la conexión en lugar de en la entrada de entrega que contiene. La clave from: se comprueba contra los provides declarados del Component de destino en cada arista, y que el socket sea ad hoc no cambia nada de esa comprobación. Un autor que puede inventar un nombre de socket sigue sin poder inventar una clave de salida en el componente de otra persona.
Primero viene el rechazo, luego el Aggregate y la ruta en la que se escribió la arista, el mecanismo y la clave de entrega bajo la que se escribió la entrada, la clave errónea, el tipo de componente contra el que se resolvió y las claves declaradas de ese tipo en orden — así que la corrección se ve solo con el mensaje. Un Component de destino que no declara ningún provides rechaza igualmente toda referencia from: a él; simplemente no hay claves declaradas que enumerar, así que el mensaje termina después del tipo de componente.
Cuál escribir
Declarar el socket en el catálogo sigue siendo el mejor camino, y es lo que hace el catálogo de la biblioteca estándar. Un socket declarado lleva un selector que restringe a qué componentes puede llegar la arista, una lista de permitidos inject:, un contrato por arista con sus propios valores predeterminados y una descripción — una declaración revisable de una conexión prevista, versionada con la entidad que la establece. Un socket ad hoc no lleva nada de eso, y la arista es tan segura como el autor que la escribió.
La forma ad hoc es una vía de escape, para el caso que muestra este ejemplo: una conexión que el autor del catálogo no previó, necesaria para una sola Release, en la que esperar un cambio del catálogo significaría esperar para publicar. Recurre a ella sabiendo lo que cuesta.
Vale la pena enunciar claramente dos costes:
- Un nombre de socket mal escrito es un socket ad hoc válido, no un error. Escribir
databsesdonde se quería decirdatabasesproduce una compilación verde en la que nada fluye por el socket previsto. El compilador señala un nombre de socket a una edición de distancia de uno declarado con un aviso que nombra ambas grafías — consulta errors/warnings.md «Uses-socket near-miss lint (Lint de casi coincidencia de sockets uses)» — pero es una advertencia y nunca cambia el veredicto de la compilación. - Dos superficies no están abiertas de este modo a propósito. El
usesde una vinculación de Feature solo puede nombrar un socket que declare la Feature vinculada, y elusespor arista de una Release solo puede nombrar un socket que declare el Component consumidor. Un operador configura y cablea dentro de una arquitectura; no la crea. Por esorelease-delivers.yamlllevainfra:y nada sobre sockets — el socketassistantes del autor del Aggregate, y solo suyo.
Para el contrato completo, consulta entities/component.md «Topology Sockets: usesSchema (Sockets de topología)» y architecture/07-dependency-resolution.md.