Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Component

El papel conceptual de la entidad Component (la interfaz abstracta de nodo de cómputo del Dominio 2) se encuentra en architecture/04-entity-taxonomy.md. Esta página cubre la superficie de autoría del Component: la taxonomía de etiquetas semánticas que los arquitectos usan para superponer una identidad cognitiva sobre la ontología operativa base, la declaración schema: para los pilares de datos, las tablas declarativas usesSchema y featuresSchema para los sockets de topología y las ranuras de vinculación, los mandatos de presencia, el mecanismo de herencia extends: y el bloque de reglas entre campos assertions:.

La taxonomía de etiquetas semánticas (la convención de la biblioteca estándar)

Si los tipos base son puramente cloud-native, la inteligencia operativa y cognitiva de la arquitectura se superpone por completo mediante duck typing semántico.

El compilador Go central no interpreta estas etiquetas. El compilador construye el grafo plano de la representación intermedia (IR) sin interpretar la semántica de las etiquetas. Estas etiquetas representan la convención de la biblioteca estándar—«marcadores genéticos» inmutables creados por el arquitecto de plataforma en el dominio 2. Proporcionan los hooks semánticos explícitos que los validadores de políticas Wasm y las Recipes físicas de Ops usan para gobernar la arquitectura.

(A) La capa cloud genérica Estas etiquetas describen comportamientos universales y permiten que los motores de políticas y los proxies L7 generados gobiernen arquitecturas empresariales estándar sin necesidad de comprender de forma nativa los frameworks de IA.

Prefijo de la etiquetaValores permitidos (convención)Por qué lo necesita Platform Ops (el hook de política)
tool.aggrega.ai/impactread-only, mutatingPermite a los motores de políticas evaluar la autorización de mínimo privilegio (Least-Privilege AuthZ). Las herramientas que modifican datos pueden activar automáticamente políticas que exigen adjuntar sidecars de puerta de aprobación estricta.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (conjunto de valores en proceso de estabilización frente al catálogo poblado)Permite a los motores de políticas imponer la seguridad de tipos entre nodos (por ejemplo, impidiendo que un agente intente enviar payloads SQL a una base de datos vectorial).
gateway.aggrega.ai/intelligencesemantic, l4-meshDetermina qué funcionalidades puede admitir físicamente un router (por ejemplo, impidiendo que una Feature que enruta según el modelo que nombra una solicitud, como una cadena de fallback, se adjunte a una malla TCP estándar).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledPermite que una Feature que copia tráfico en vivo a un segundo destino seleccione un proxy que realmente pueda copiar, y distinga uno que copia cada solicitud coincidente de otro cuya proporción de solicitudes copiadas es configurable.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerPermite que una Feature que necesita que el llamante original se identifique ante el servicio que está detrás del proxy seleccione un componente capaz de transmitir esa identidad, y lea qué mecanismo la transmite — los detalles del propio certificado TLS del cliente, reenviados, o un encabezado que el proxy compone por sí mismo tras autenticar al llamante.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listPermite que una Feature que enmascara texto sensible seleccione un componente capaz de reemplazarlo por un marcador de posición en el payload de chat y completion que enruta, antes de que el texto siga avanzando. El valor indica la fidelidad: con entity-recognition el componente reemplaza las coincidencias de patrones indicados en su configuración y, además, los tipos de entidad que detecta un servicio de reconocimiento al que llama; con pattern-list reemplaza solo las coincidencias de patrones indicados en su configuración y no llama a ningún servicio de reconocimiento.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierPermite que una Feature que filtra prompts de modelo seleccione un componente capaz de inspeccionar el payload de chat y completion que enruta y de rechazar una solicitud por su contenido. El valor indica la fidelidad: con pattern-list la coincidencia se busca contra patrones indicados en su configuración, sobre el payload del modelo y no sobre un cuerpo HTTP arbitrario; con classifier el veredicto es el de un clasificador de texto entrenado, al que se llega a través de un servicio de detección al que llama el componente, frente a un umbral indicado en su configuración.
dataplane.aggrega.ai/upstream-tlstrust-anchorPermite que una Feature que exige que el proxy compruebe con quién se comunica seleccione un componente capaz de verificar el certificado de un upstream frente a un ancla de confianza que proporciona la Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyPermite que una Feature que fija qué clave puede presentar un upstream seleccione un componente capaz de rechazar un upstream salvo que un certificado que presente contenga una de las claves públicas que proporciona la Release. Una aserción distinta de upstream-tls: un pin dice qué clave debe ser un certificado; un ancla, qué debe decir.
dataplane.aggrega.ai/period-budgetcost, tokensPermite que una Feature que limita lo que el tráfico puede consumir en un periodo seleccione un componente capaz de rechazar solicitudes al modelo una vez que lo que ha contado en el periodo supera un límite establecido en su configuración. El valor indica qué cuenta: cost, lo que costó el tráfico, con precio según una tabla que el componente mantiene por modelo; tokens, los tokens que la respuesta de cada modelo declara haber leído, escrito o ambos, que el componente cuenta sin asignar ningún precio.
dataplane.aggrega.ai/concurrency-captotal, per-targetPermite que una Feature que limita cuántas solicitudes gestiona un componente a la vez seleccione un componente capaz de retener o rechazar una solicitud que supere un límite establecido en su configuración. El valor indica qué cuenta un límite: total, cada solicitud que el componente reenvía, frente a un único límite; per-target, las solicitudes en curso hacia cada destino upstream al que envía, con un límite para cada uno y ninguno sobre su total.

Las claves dataplane.aggrega.ai/ nombran una posición en la ruta del tráfico en lugar de un tipo de componente, de modo que un proxy, un gateway de ingress y una service mesh se describen todos con un único vocabulario en vez de necesitar cada uno el suyo. Dos propiedades de esta familia merecen una lectura atenta, porque ambas son fáciles de invertir:

  • El valor lleva la fidelidad, no solo la presencia de la capacidad. Dos componentes pueden reflejar solicitudes y aun así diferir de una manera que le importa a una Feature, así que la distinción viaja en el valor y una Feature selecciona la fidelidad que necesita. Un componente que ofrece una fidelidad mayor lleva el valor más fuerte y ningún otro.
  • Un valor afirma lo que el producto es capaz de hacer, nunca lo que un despliegue ha activado. Ambas cosas se leen igual y solo la primera es una propiedad del componente. Un proxy capaz de verificar el certificado de un upstream lleva upstream-tls: trust-anchor tanto si un despliegue determinado habilita la comprobación como si no, porque la etiqueta es aquello sobre lo que una Feature selecciona antes de que se configure nada.

Un componente que no tiene nada que describir en uno de estos ejes no lleva ningún valor en él, en lugar de uno mínimo, exactamente como en el resto de la taxonomía: la ausencia significa que el eje no tiene objeto en ese componente, de modo que una Feature que exige cualquier valor en él, correctamente, no se adjunta.

(B) La capa de IA especializada (la identidad cognitiva) Estas etiquetas describen la identidad cognitiva de la carga de trabajo y permiten que la arquitectura proteja los frameworks de IA modernos.

Prefijo de la etiquetaValores permitidos (convención)Por qué lo necesita Platform Ops (el hook de política)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionLo usan las cadenas de selector de usesSchema (evaluadas de forma nativa por el compilador Go durante el análisis estático) para garantizar que un desarrollador no enrute por accidente un payload de texto generativo a un endpoint de embeddings.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeIndica qué API de modelo responde en la dirección que publica un componente: openai cuando es la API de OpenAI, la del propio proveedor o la implementación de un servidor, anthropic cuando es la Messages API de Anthropic, la del propio proveedor o la implementación de un servidor, gemini cuando es la Gemini API de Google, y native cuando es la API propia del producto y ninguna de esas. Todo componente de modelo la lleva, y también un gateway capaz de servir una API de modelo, de modo que un socket que selecciona component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api acepta un modelo o un gateway de ese tipo y rechaza un gateway que no sirve ninguna, mientras que un socket que nombra un solo valor, como model.aggrega.ai/api=anthropic, acepta solo lo que sirve esa API. Indica lo que el producto sirve, no lo que conecta una Release concreta: un gateway cuyos modelos se conectan a un socket propio la lleva también sin nada conectado. La etiqueta es una cadena con la que el selector busca coincidencias; nada comprueba qué responde realmente en la dirección.
agent.aggrega.ai/autonomyautonomous, copilotIdentifica el riesgo de ejecución del bucle cognitivo y permite que las políticas exijan funcionalidades de aprobación humana para los agentes totalmente autónomos.

(C) Los elementos transversales (gobernanza, estado y hardware) Representan las etiquetas empresariales fundamentales que impulsan la validación Zero-Trust y el enrutamiento hacia el hardware.

Prefijo de la etiquetaValores permitidos (convención)Por qué lo necesita Platform Ops (el hook de política)
component.aggrega.ai/hostingself-hosted, managed, external, mixedRegistra quién opera el recurso subyacente de un componente — el eje de la frontera de confianza. Los motores de políticas la leen para calcular el riesgo de exfiltración de datos (por ejemplo, los datos internos enrutados a una API de terceros managed salen de la frontera del operador). Transversal: los mismos valores describen por igual una base de datos gestionada, una API de modelo gestionada y un servidor de inferencia autogestionado. mixed marca un componente cuyas Recipes abarcan más de una modalidad — un almacén de datos autoalojado por sus Recipes de Helm y Compose y gestionado por sus Recipes de RDS — de modo que la modalidad de una Release sigue a la Recipe que selecciona su Manifest.
compliance.aggrega.ai/data-classpublic, internal, restrictedLa clase de los datos que contiene un componente. El compilador la lleva al grafo de build como una cadena y no establece ningún orden; una política que un operador adjunta en el rol ir-verdict da a las clases su orden en su propia configuración y lee la etiqueta a lo largo de las rutas que enumera el compilador — deteniendo, por ejemplo, un build en el que un componente restricted alcanza un componente de otra clase sin ninguna Feature de desclasificación adjunta en la ruta (policy-data-class-route). Ningún Component de la biblioteca estándar la lleva: la clase es una afirmación sobre cómo una organización usa un componente, que lleva el Component propio de esa organización — una especialización mediante extends, por ejemplo.
compliance.aggrega.ai/contains-piitrue, falseMarca explícitamente las cargas de trabajo dentro del ámbito de GDPR/CCPA. Una política que adjunta un operador puede leerla para exigir Features específicas en las rutas que sigue el tráfico de esa carga de trabajo — core/data-masking en un gateway de IA a través del cual envía tráfico de modelos, por ejemplo, la forma que policy-data-class-route comprueba para una clase de datos. Ningún Component de la biblioteca estándar la lleva; como la clase de datos, es una afirmación de una organización sobre sus propios componentes.
hardware.aggrega.ai/acceleratorgpu, tpu, npuLo usa DevOps en el archivo Release. Allí enrutan explícitamente estos componentes hacia fronteras físicas de pools de hardware (por ejemplo, un clúster con GPU) mediante el mapa components: {}, mientras que un rol verdict de gobernanza puede imponer que los componentes etiquetados como GPU nunca se coloquen en fronteras sin GPU.
state.aggrega.ai/retentionretain, deleteResuelve la brecha de eliminación AOT. Si un desarrollador elimina una base de datos de su Aggregate, un orquestador GitOps eliminará físicamente el disco. Un paso pipeline: de una Recipe puede leer la etiqueta retain y añadir protección nativa del orquestador a los artefactos renderizados (por ejemplo, helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralHook de disponibilidad SOC2. Indica a la FeatureRecipe de Ops si debe generar físicamente configuraciones automatizadas de Snapshot/Volume Backup para el recurso.

(D) El contexto de negocio dinámico (anotaciones en cascada) Mientras que las labels definen el ADN inmutable del catálogo, los contextos de negocio dinámicos (como el alcance de auditoría SOC2 o el seguimiento de costes de FinOps) cambian según quién despliega la aplicación y dónde se ejecuta. Se rigen por anotaciones inyectadas dinámicamente por los subsystems del desarrollador, las fronteras de la Release de Ops o un plugin de gobernanza adjunto en el rol annotation-transform.

Prefijo de la anotaciónValores permitidos (convención)Por qué lo necesita Platform Ops (el hook de política)
business.aggrega.ai/cost-centerp. ej., finance, ai-researchLo requieren los plugins de renderizado Wasm para inyectar etiquetado físico (por ejemplo, tags de AWS o labels de K8s) en los artefactos finales generados para los paneles de facturación cloud.
business.aggrega.ai/ownerp. ej., team-alpha@corp.comEnrutamiento de la respuesta a incidentes. Garantiza que la infraestructura esté asociada a un equipo humano.
compliance.aggrega.ai/frameworksp. ej., soc2, hipaaDisparador del ámbito SOC2. Se inyecta a través de la Release del entorno. Los plugins Wasm leen esta cadena para generar automáticamente sidecars rígidos de registro de auditoría y deshabilitar los puertos de depuración cuando una aplicación entra en una frontera de cumplimiento de producción.

La taxonomía es una convención del catálogo, no una regla del compilador. Las empresas pueden ignorarla, eliminarla o inventar su propio vocabulario de etiquetas (mycompany.com/custom-trait). Los plugins Wasm evalúan cualquier clave de etiqueta que defina la empresa.

Autoría de esquemas

El esquema Component (y su contraparte Feature, incluidas las Features de credenciales etiquetadas feature.aggrega.ai/kind: secret) declara el contrato de validación de los values creados por el desarrollador mediante un bloque spec.schema:. El bloque acepta JSON Schema 2020-12 expresado en la notación abreviada YAML compacta (la predeterminada; unas 15 palabras clave, transformadas mecánicamente a JSON Schema en tiempo de compilación) o en YAML de JSON Schema completo (la forma detallada), con referencias entre documentos mediante $ref: para entradas de SchemaLibrary compartidas entre varios Components.

  • Forma compacta inline (superficie de autoría predeterminada): un bloque YAML incrustado que lleva hojas en forma compacta directamente en el YAML del Component. Cubre la gran mayoría del contenido de esquemas del catálogo con una fracción de las líneas de un JSON Schema completo. Consulta vocabulary/compact-form-authoring.md para el vocabulario de palabras clave y las convenciones de autoría.
  • YAML de JSON Schema inline: la forma detallada, adecuada cuando el esquema necesita palabras clave de JSON Schema 2020-12 que la forma compacta no lleva directamente ($dynamicRef, unevaluatedProperties profundos, composición not: compleja). La forma compacta y JSON Schema se pueden combinar en cualquier frontera de nodo dentro de un único bloque schema: mediante la vía de escape $jsonschema:.
  • Referencia entre documentos ($ref: a una entrada de SchemaLibrary): un $ref: nativo de JSON Schema que apunta a una entrada de SchemaLibrary por identidad (Datastores#/schemas/MariaDBValues o similar). Los esquemas empresariales que abarcan cientos de líneas y se reutilizan en varios Components residen en entidades SchemaLibrary; el Component consumidor referencia la entrada sin incrustar su contenido. Consulta entities/schemalibrary.md y vocabulary/cross-document-ref.md para la entidad de biblioteca y la semántica de resolución.

Las tres formas anteriores crean contenido de pilares, y están disponibles para un Component que no extiende nada. Un Component que declara extends: no crea ningún contenido de pilares: escribe el marcador literal schema: inherited y recibe el bloque de pilares de su base exactamente como la base lo creó. Ese marcador es el único valor que schema: admite en un Component así. Consulta «Autoría del catálogo: extender Components base» más abajo.

El compilador resuelve el bloque schema: — expandiendo la forma compacta, desreferenciando las URL $ref:, aplicando las cadenas de biblioteca a biblioteca de SchemaLibrary — y unifica el JSON Schema resultante con las bases generadas automáticamente a partir de usesSchema y featuresSchema (consulta la sección siguiente) durante la pasada de validación del Component. La validación se ejecuta contra el esquema resuelto; la ruta de autoría es opaca para las etapas posteriores del pipeline.

Las instancias creadas se validan contra este esquema resuelto en tiempo de build: los values creados por el desarrollador de una instancia de componente y la infra resuelta del operador, más los values/infra de cualquier adjunto de Feature, deben ajustarse a los pilares declarados — un valor de tipo incorrecto, un número fuera de rango, una cadena que no tiene su format declarado, un campo obligatorio ausente o (para values, validado de forma cerrada) una propiedad no declarada detiene el build en su origen creado en lugar de producir un manifiesto roto en tiempo de despliegue. Un pilar cuyo esquema nombra un format que el compilador no comprueba — cualquiera fuera de email, uri, hostname, ipv4, ipv6, uuid, date-time y date, password incluido — se rechaza al cargar el catálogo, con la lista de los nombres admitidos; consulta vocabulary/compact-form-authoring.md para saber qué comprueba cada nombre. Una instancia de un Component que extiende una base con extends: se valida contra el bloque de pilares de la base, que el Component que la extiende hereda sin cambios — así una instancia de la base y una instancia de cualquier cosa que la extienda se enfrentan al mismo contrato de pilares. Consulta errors/fatal-halts.md §«Authored values or infra do not conform to the declared schema (Los values o la infra creados no se ajustan al esquema declarado)» para los diagnósticos y las reglas por pilar (incluido cómo se valida infra contra la unión de claves del Component y del provider).

Los valores predeterminados declarados se materializan en los pilares renderizados. Además de la validación, un default: declarado en un campo de values (o en un campo de infra) se rellena en el pilar renderizado en tiempo de build para cada clave que el autor omite — de modo que una plantilla de Recipe que lee {{ .values.charset }} recibe el utf8mb4 declarado en el esquema en lugar de un valor vacío. Los valores proporcionados por el autor siempre prevalecen; los objetos anidados se completan por cada hijo omitido. Como la materialización usa la misma resolución de esquema que la validación, también se materializan los valores predeterminados alcanzados mediante un $ref: entre documentos hacia una SchemaLibrary — tanto una referencia al pilar completo (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) como la forma base más variante (un $ref: base junto a properties hermanas, cada una con sus propios valores predeterminados). Los valores predeterminados declarados solo dentro de una referencia local en el mismo documento #/$defs/, o bajo una rama allOf / oneOf / anyOf, no se materializan; la biblioteca estándar compone los pilares mediante $ref: entre documentos, que sí se materializa.

El pilar values

El esquema del Component separa tres pilares según su propietario: values lo completa el desarrollador en el Aggregate (intención cognitiva — nombre de la base de datos, versión, charset), infra lo completa el operador en la Release (dimensionamiento operativo — cómputo, almacenamiento, HA) y provides lo establece la Recipe (el contrato de la API pública — host, puerto, protocolo). El desarrollador nunca ve infra; el operador nunca ve values. Las Recipes consumen ambos pilares durante el renderizado base y asignan los pilares abstractos a la forma concreta que espera su provider de destino. Esta sección trata la superficie de autoría del pilar values. Consulta vocabulary/data-pillars.md para la taxonomía más amplia de los pilares y la disciplina de cascada entre pilares.

values lleva la intención cognitiva del desarrollador — las decisiones que describen qué es o qué hace la aplicación, no cómo se dimensiona o se ejecuta. El nombre de la base de datos, el charset, la versión del motor, el nivel de log, los indicadores de funcionalidad y los ajustes de la capa de aplicación que cambian entre versiones de la aplicación pero permanecen estables entre entornos son contenido típico de values. El operador nunca sobrescribe values: (el esquema de la Release rechaza mecánicamente un bloque values: según architecture/06-data-taxonomy-and-composition.md §8 Restricción 4); la variación por entorno fluye a través del Parameter Hoisting — el Aggregate expone parameters.* tipados, la plantilla values del Component los referencia y la Release cumplimenta los parámetros.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Consumo del lado de la Recipe. Las Recipes leen los valores resueltos mediante .values.<field> en valuesMapping:, provides:, assertions: y las demás superficies de plantilla — consulta entities/recipe.md para la matriz de disponibilidad por plantilla. El compilador unifica el esquema values del Component con cualquier esquema values: de los attachments de Feature en el mismo nodo del Component, de modo que el contexto de plantilla resuelto contenga todos los campos aplicables.

Disciplina entre pilares. values es el único pilar que el desarrollador escribe en el Aggregate. Los campos estrictamente orientados al desarrollador van aquí; los ajustes operativos (número de réplicas, límites de CPU/memoria) van en el pilar infra del Component para que residan en la Release; la salida pública (host, puerto) va en el provides de la Recipe. Mezclarlos rompe el invariante de propiedad; consulta vocabulary/data-pillars.md «Mecánica entre pilares» para los raros casos en los que está justificado un paso deliberado entre pilares.

El pilar infra

El esquema del Component separa tres pilares según su propietario: values lo completa el desarrollador en el Aggregate (intención cognitiva — nombre de la base de datos, versión, charset), infra lo completa el operador en la Release (dimensionamiento operativo — cómputo, almacenamiento, HA; la copia de seguridad de un almacén de datos no se dimensiona aquí, sino que es la Feature core/backup que el operador adjunta en la Release) y provides lo establece la Recipe (el contrato de la API pública — host, puerto, protocolo). El desarrollador nunca ve infra; el operador nunca ve values. Las Recipes consumen ambos durante el renderizado base y asignan los pilares abstractos a la forma concreta que espera su provider de destino.

Tres convenciones de infra importan en cada Component agnóstico respecto a la capacidad de la biblioteca estándar: una vía de escape de estructura abierta para los ajustes específicos del provider, una sustitución opcional de la versión del artefacto upstream y un vocabulario basado en la intención para los campos de alta disponibilidad. El Component de referencia canónico es core/datastore/mariadb en el catálogo de la biblioteca estándar — implementable por Recipes de Helm que ejecutan la imagen oficial mariadb o entregan un recurso personalizado de MariaDB al controlador mariadb-operator, por Recipes de Terraform sobre AWS RDS, por Recipes de CloudFormation sobre la misma superficie de RDS y por Recipes de Compose sobre un contenedor local — y su bloque infra ilustra la primera y la tercera.

infra.overrides

Los campos universales de infra — compute, storage, ha — cubren la mayor parte del dimensionamiento operativo entre providers. La parte restante es irreductiblemente específica del provider: una Recipe de Kubernetes necesita un nodeSelector, una Recipe de Terraform para RDS necesita un instance_class, una Recipe de CloudFormation para RDS necesita un DBInstanceClass, una Recipe de Compose necesita una sustitución de image. El esquema del Component expone un mapa realmente abierto como vía de escape para que estos ajustes pasen sin inflar el esquema:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

El type: object explícito con additionalProperties: true activa la semántica de mapa abierto. El compilador deja pasar la estructura intacta; el cuerpo de la plantilla de la Recipe lee las claves que conoce e ignora el resto. Cada Recipe documenta la ontología de sus claves de sustitución en su comentario de cabecera, de modo que un operador que escribe una Release para una combinación concreta de Component × Recipe sepa qué ajustes expone la Recipe.

Un fragmento de Release que usa sustituciones:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

El desarrollador nunca ve overrides: reside en la Release, que es el dominio del operador.

infra.source_version

El campo source de una Recipe hace referencia a un artefacto upstream en una versión específica (chart de Helm 25.0.8, módulo de Terraform 4.2.0, etiqueta de imagen OCI). Fijar la versión en el código de la Recipe obliga al mantenedor del catálogo a publicar una nueva Recipe con cada subida de versión upstream compatible. El esquema del Component expone una sustitución opcional:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

La Recipe lo lee mediante el helper optional en su bloque source, de modo que, si no hay versión fijada, se recurre a la versión para la que se escribió la Recipe:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Las cadenas source de una Recipe (y los subcampos con valor de cadena de un mapa source: estructurado) se evalúan como plantillas Go. Una coordenada remota — como la version anterior — se evalúa cuando aggrega pull fija el artefacto, sobre .values, .infra y .locals, sin raíz .context; una source que nombra una ruta del espacio de trabajo se evalúa al renderizar la entidad, sobre el mismo contexto autónomo que los locals de la Recipe — .context.instance_id, .values, .infra y la totalidad de los .locals resueltos del nodo. .context.inject, .context.uses y .provides están prohibidos en ambos casos. Que .infra esté en ese contexto es lo que hace funcionar la sustitución anterior, y .locals permite a una Recipe calcular una vez un fragmento de source y volver a leerlo aquí. Una plantilla de source nunca lee los provides de su propio nodo: ese pilar no forma parte del contexto, y una plantilla que intente acceder a él detiene el build — una propiedad fija de la superficie y no una carencia a la espera de trabajo futuro. Consulta la fila n.º 5 de la matriz de expansión de plantillas para las reglas de disponibilidad completas. Cambiar infra.source_version respecto al valor predeterminado de la Recipe no garantiza que el valuesMapping de la Recipe sea compatible a nivel de formato de transmisión con la nueva versión upstream; la description de la declaración source_version en el esquema del Component contiene esa advertencia.

infra.ha.*

Los campos de alta disponibilidad usan vocabulario de intención, no de mecanismo:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled dice «haz que este Component sea altamente disponible» e infra.ha.read_replicas dice «quiero N copias de solo lectura». Cada Recipe decide en qué se convierte la intención en su provider. Las Recipes de la biblioteca estándar para core/datastore/mariadb, con los nombres con los que un Manifest las asigna:

Recipeha.enabled: true se traduce enha.read_replicas: N se traduce en
helm/mariadb (un StatefulSet sobre la imagen oficial mariadb)ejecuta un solo servidor, por lo que el build se detiene indicando la claveejecuta un solo servidor, por lo que un N mayor que 0 detiene el build
helm/mariadb-cluster (un recurso personalizado de MariaDB que el controlador mariadb-operator reconcilia)activa la conmutación por error automática (replication.primary.autoFailover: true); la conmutación se hace a una réplica de lectura, por lo que un N de 0 detiene el buildestablece spec.replicas en N + 1 y activa la replicación; provides.host pasa a ser el Service <name>-primary
terraform/mariadb-rds (AWS RDS)establece multi_az = true en la aws_db_instance primariacrea N recursos de réplica de lectura aws_db_instance independientes
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS mediante un módulo)pasa multi_az = true al móduloaprovisiona una sola instancia, por lo que un N mayor que 0 detiene el build
cloudformation/mariadb-rds (AWS RDS)establece MultiAZ: true en el AWS::RDS::DBInstanceaprovisiona una sola instancia, por lo que un N mayor que 0 detiene el build
compose/mariadb (contenedor de desarrollo local)ejecuta un solo servidor, por lo que el build se detiene indicando la claveejecuta un solo servidor, por lo que un N mayor que 0 detiene el build

El vocabulario de mecanismo (infra.primary.replicas) resulta natural para un provider (los pods de Kubernetes son réplicas de un StatefulSet) y un error de categoría en los demás — RDS no tiene un concepto de «réplicas» en la instancia primaria, CloudFormation replica a RDS, Compose no tiene ninguna abstracción de réplicas horizontales. El vocabulario de intención se traslada: cada provider tiene algún concepto de «hacer que esta base de datos sea altamente disponible» y algún concepto de «quiero N copias de solo lectura», y la Recipe lleva la traducción para cada provider. Donde una realización no tiene tal mecanismo, su Recipe puede detener el build indicando la clave, como hacen helm/mariadb y compose/mariadb para ambas claves y las Recipes de RDS de instancia única para las réplicas de lectura.

infra.ha.read_replicas: 0 es el valor predeterminado; con ambas claves en sus valores predeterminados, helm/mariadb-cluster renderiza un MariaDB de instancia única sin bloque replication, en lugar de una replicación sobre una sola instancia. compose/mariadb ejecuta un solo servidor en el host Docker local, por lo que infra.ha.enabled: true o un infra.ha.read_replicas distinto de cero detiene el build indicando la clave, y el mensaje remite a helm/mariadb-cluster, que ofrece conmutación por error y réplicas de lectura.

El pilar provides

provides es la API pública escrita por la Recipe — los valores que la Recipe resuelta de un Component aporta a los llamadores posteriores a través de su superficie .context.uses.<alias>.provides.<provided-name> (o, cuando el llamador declara una lista de permitidos inject: en la arista, a través de su canal .context.inject). El esquema del Component declara la forma (nombres de clave y tipos); el bloque provides: de la Recipe vinculada suministra los valores. El desarrollador que escribe un Aggregate ve la forma de provides en la página del Component como el contrato con el que los llamadores pueden contar; el autor de la Recipe cumple el contrato para la implementación concreta que envuelve.

El cumplimiento se impone como Loud Guardrail: una Recipe vinculada debe producir cada clave de provides que declara su Component. Si la Recipe vinculada omite una clave declarada, el build se detiene e indica la clave que falta, en lugar de no entregar nada en silencio a los llamadores que la referencian. Se permite producir claves adicionales más allá del conjunto declarado. Solo se comprueba la presencia de las claves — los valores producidos son cadenas opacas que el compilador deja pasar, por lo que sus tipos declarados siguen siendo un contrato que leen los llamadores, no un valor que el compilador valide.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

La separación de la evaluación entre provides e inject. El compilador evalúa las plantillas provides: en la evaluación de provides, sobre el contexto de plantilla autónomo (.context.instance_id, .context.rendered_name cuando el provider del nodo informa uno, .values, .infra y los locals: resueltos de la Recipe en el mismo nodo) — no hay ningún estado de los llamadores visible. Los locals del nodo se resuelven en el preámbulo de esa etapa, antes de sus provides, y eso es lo que permite que una plantilla provides: lea .locals. En la hidratación de inject, que se ejecuta a continuación, el compilador recorre las aristas uses: y resuelve el .context.uses.<alias>.provides.<provided-name> de cada llamador contra los valores de provides resueltos. Separar ambas cosas garantiza una resolución acíclica: provides: no puede referenciar a un llamador, y el inject: de un llamador no puede referenciar la salida de un provider aún no resuelto hasta que se ejecute la hidratación de inject.

Evolución del contrato. Renombrar o eliminar un campo de provides es un cambio incompatible para cada llamador que dependa del nombre anterior. La metadata.version del Component (y la declaración implements: de la Recipe) lleva la señal de evolución del contrato; los llamadores posteriores fijados a una versión mayor concreta ven una forma de provides estable.

Enseñanza del lado de la Recipe. Para la gramática de autoría de las plantillas provides:, la matriz de disponibilidad por plantilla y ejemplos completos de enrutamiento entre namespaces y entre regiones, consulta entities/recipe.md «El bloque provides:» y architecture/06-data-taxonomy-and-composition.md §3.

Obligaciones de presencia: features.aggrega.ai/requiredType.<label>

Un Component puede declarar que cada una de sus instancias debe llevar un attachment de un tipo de Feature dado. Esto es una obligación de presencia, y se escribe como una anotación repetible en los metadatos propios del Component:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

La clave es el prefijo features.aggrega.ai/requiredType. seguido de una etiqueta que eliges; el valor es la URI del tipo de Feature que al menos un attachment debe llevar. La etiqueta nombra el requisito en el diagnóstico que produce una obligación incumplida — audit y compliance arriba — y esa es toda su función. Las claves con etiqueta son la forma en que un Component declara más de una obligación a la vez: las anotaciones son un mapa plano de cadenas y no pueden contener una clave duplicada.

El compilador evalúa cada obligación contra el conjunto final de attachments de la instancia, después de que la cascada del 5-Tier Onion Model haya plegado cada ámbito: los bloques features: de nivel de componente y de nivel de subsistema del Aggregate, los bloques features: de nivel de frontera y de nivel de componente de la Release, y los attachments producidos por la expansión guiada por anotaciones. Cualquiera de ellos cumple la obligación — la regla comprueba lo que está presente, nunca cómo llegó ahí. Así, un Component cuya obligación se cumple solo porque un operador estableció una anotación de monitorización en la Release pasa exactamente igual que uno al que el desarrollador adjuntó la Feature a mano.

Una obligación que ningún attachment cumple detiene el build con un diagnóstico que indica la instancia del componente, la etiqueta del requisito y el tipo requerido. El valor de una anotación es una cadena opaca, por lo que nada valida su forma antes de que el compilador la lea; un valor que no es una URI de tipo de Feature, o una clave sin etiqueta tras el prefijo, detiene por tanto el build con un diagnóstico separado que indica que la declaración está mal formada. Ambos son deliberadamente distintos: una declaración errónea se corrige en la entidad del catálogo, mientras que un requisito incumplido se resuelve adjuntando la Feature — y una errata nunca debe leerse como un requisito cumplido.

Ambos diagnósticos están documentados en errors/fatal-halts.md «Required feature not attached (funcionalidad requerida no adjuntada)».

Una obligación no es un slot. Las dos superficies responden a preguntas distintas y la diferencia no es cosmética:

slot featuresSchemaobligación de presencia
Declaraun punto de vinculación con nombreuna restricción sobre lo que debe estar presente
El nombre es desreferenciablesí — from: <slot> y .features.<slot>.provides.*no — la etiqueta nombra el requisito, nada más
Cardinalidadexactamente un relleno por slotal menos un attachment del tipo
Restringe el rellenoselector, inject, sensitivenada más allá del tipo
Se cumple con un attachment libreno — un slot se rellena por nombresí — en cualquier ámbito, con cualquier nombre
Cuando la exigencia no se cumplese detiene cuando required: true y nada vincula el nombre del slotse detiene cuando ningún attachment lleva el tipo

Ambas exigencias se comprueban contra la misma entrada — el conjunto final de attachments de la instancia — y ambas detienen el build con su propio diagnóstico, porque le plantean preguntas distintas: si un punto de vinculación con nombre está vinculado, frente a si algún attachment lleva un tipo con nombre. Ninguna responde por la otra.

Recurre a un slot cuando la Recipe necesita leer lo que se adjuntó. Recurre a una obligación cuando el contrato del Component exige que una capacidad esté presente y no le importa qué instancia la aporte. Un Component de procesamiento de pagos que exige core/audit-logging obtiene registro de auditoría en cada despliegue, tanto si el desarrollador recordó adjuntarlo como si no; un Component conforme a PCI que exige core/pci-compliance no puede entregarse sin que la Feature de cumplimiento esté adjuntada en algún lugar del despliegue.

Herencia. Una obligación declarada en un Component base la hereda cada Component que lo extiende con extends:, porque las anotaciones de los metadatos se fusionan a lo largo de la cadena de extends y, por cada clave, prevalece el hijo. Por tanto, un hijo puede redirigir una obligación heredada volviendo a declarar la misma etiqueta con un tipo diferente, o añadir obligaciones propias con nuevas etiquetas; no puede eliminar una que haya declarado la base.

Sockets de topología: usesSchema

Un Component puede declarar sockets topológicos mediante un bloque usesSchema: — un mapa YAML declarativo paralelo a featuresSchema. Cada entrada nombra un socket a través del cual el Component acepta dependencias entre componentes y determina qué formas de Component puede conectar el desarrollador al socket. El compilador genera automáticamente reglas de validación de JSON Schema 2020-12 a partir de los sockets declarados y las unifica con el schema: del Component durante la resolución del Component; los desarrolladores no escriben a mano un pilar uses: dentro de schema:, porque la estructura proviene de usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Formas de conexión — un socket acepta uno o varios destinos. Los ejemplos anteriores conectan cada socket a un único destino, pero un socket puede ramificarse hacia varios. El valor de un socket se escribe en una de dos formas:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Un alias siempre se asigna a un objeto de entrada, nunca a un simple nombre de destino: databases: { primary: orders-db } se rechaza al cargar, al igual que un objeto de entrada que omite target:. Para conectar un único destino sin tener que inventar un alias, usa la forma compacta — primary_datastore: [vector-db-instance] —, que nombra el destino una vez y deriva de él el alias.

Cada entrada — elemento de lista o alias de mapa — se convierte en una arista, que se conserva en el orden de escritura. El selector: del socket se aplica a cada destino conectado a través de él (cada arista se comprueba en tipos de forma independiente durante el análisis estático), y required: true significa que debe conectarse al menos un destino.

Semántica de los campos:

CampoTipoPredeterminadoSignificado
requiredboolfalseCuando es true, el desarrollador debe conectar al menos una dependencia a este socket. Cuando es false, el socket es opcional.
selectorstring—Un selector de etiquetas, en la gramática que usa appliesTo de una Feature, que el destino de cada arista conectada a través de este socket debe satisfacer. Se lee como la cadena escrita aquí y se evalúa contra las etiquetas del destino durante el análisis estático: un destino cuyas etiquetas no lo satisfacen detiene la compilación, y también lo hace un selector que la gramática rechaza, nombrando el requisito que no pudo leer. Un selector vacío no impone ninguna restricción al destino.
injectstring[]—Lista de permitidos de los mecanismos de entrega inject admitidos (paralela a featuresSchema[].inject). Ausente, o [] (vacía), significa caja negra — no se permite ningún bloque inject: en la entrada uses: del desarrollador; la Recipe controla la entrega. [env, file, arg] (no vacía) significa transparente — el desarrollador puede imponer qué mecanismo entrega los valores provides de la dependencia. Se aplica: consulta «Dónde se aplica la lista de permitidos inject de un socket» más abajo.
valueSchemaobject—Contrato opcional por arista para los values escritos por el desarrollador en una arista conectada a través de este socket (escritos en el Aggregate). JSON Schema 2020-12 en las mismas formas de escritura que schema:. Si se omite, el socket no declara ningún contrato values.
infraSchemaobject—Contrato opcional por arista para el infra escrito por el operador en una arista conectada a través de este socket (escrito en la Release). Las mismas formas de escritura que valueSchema. Si se omite, el socket no declara ningún contrato infra.
featuresSchemamap—Los slots de acoplamiento que cada conexión establecida a través de este socket puede llenar, indexados por nombre de slot, cada uno con las claves que admite un slot a nivel de Component. Si se omite, una conexión a través de este socket no lleva ningún acoplamiento. Consulta «Slots que llena cada conexión» más abajo.

Dónde se aplica la lista de permitidos inject de un socket. La lista de permitidos es la declaración del socket sobre si un consumidor puede elegir la forma de entrega y, en tal caso, cuáles — por eso se comprueba contra cada arista uses: conectada a través del socket, una vez que se dispone tanto de la arista como de la declaración del socket. De una sola regla se derivan dos rechazos, y ambos detienen la compilación:

  • Una arista que impone un mecanismo que la lista de permitidos no incluye detiene la compilación, nombrando el socket, el mecanismo infractor y lo que el socket sí permite. Todos los mecanismos infractores de la arista se informan juntos.
  • Una arista que impone cualquier entrega a través de un socket cuya lista de permitidos está ausente o vacía también detiene la compilación. Es la declaración de caja negra cumpliendo su función: dice «la Recipe entrega esto internamente; no impongas la entrega», y una lista de permitidos vacía no permite nada en lugar de permitirlo todo.

El socket se lee en la entidad que lo declaró, que no siempre es el componente del que cuelga la arista: una arista escrita en el uses: de un acoplamiento de Feature se resuelve contra el usesSchema de la Feature acoplada, y cualquier otra arista — escrita en el Aggregate, conectada desde la Release o alcanzada a través de un subaggregate — contra el del Component consumidor. Un socket heredado mediante extends se lee exactamente como uno que la entidad escribió por sí misma.

Una arista que no impone nada no se ve afectada por ninguno de los dos rechazos, declare lo que declare el socket: leer los valores de una dependencia desde .context.uses.<alias>.provides.<name> en la Recipe consumidora no requiere ningún bloque inject: y siempre está disponible. Consulta errors/fatal-halts.md para ambos diagnósticos.

Contratos de conexión por arista — valueSchema e infraSchema. Además de determinar qué Components pueden conectarse a un socket, un socket puede declarar qué configuración lleva cada conexión. Dos esquemas opcionales por socket validan la configuración de ámbito de conexión en cada arista conectada a través del socket:

  • valueSchema es el contrato para el bloque values escrito por el desarrollador en una arista uses — el ajuste por conexión que el desarrollador expresa en el Aggregate (por ejemplo, el tamaño de un pool de conexiones o un modo de cliente).
  • infraSchema es el contrato para el bloque infra escrito por el operador en una arista uses — el dimensionamiento operativo por conexión que el operador expresa en la Release.

Ambos aceptan JSON Schema 2020-12 en las mismas formas de contenido que el campo schema: — forma compacta en línea, JSON Schema YAML en línea o un $ref: entre documentos hacia una entrada de una SchemaLibrary. Son contratos por arista que se validan contra la configuración de cada arista de forma independiente; no se componen en el esquema values propio del Component consumidor. Un socket que omite un esquema por arista para un pilar no declara ningún contrato en él, y cualquier configuración escrita para ese pilar queda sin validar. La configuración por arista se valida de forma cerrada, y la validación tiene en cuenta los valores por defecto en ambos pilares: una clave a la que el esquema asigna un default: cuenta como proporcionada aunque el autor la omita.

Un default: declarado también se materializa, en ambos pilares. Una clave que el autor omite llega al contexto de renderizado de la Recipe consumidora con su valor por defecto declarado, exactamente como ocurre con una clave value o infra de componente omitida — así que basta con declarar el valor por defecto en el socket, y la plantilla de la Recipe no necesita ninguna expresión alternativa para ella. Un valor escrito siempre prevalece sobre el valor por defecto declarado, y solo llena la clave que proporciona: una arista que escribe una clave del contrato de un socket sigue recibiendo los valores por defecto declarados para las demás claves de ese contrato. Los valores por defecto se asocian a las aristas, por lo que un socket que queda sin conectar no aporta nada.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Con ese socket declarado, una arista cuyo Aggregate omite pool_size renderiza 10, y una arista cuya Release omite storage_class renderiza standard. Lo escrito prevalece clave por clave, dentro de su propio pilar: un Aggregate que establece pool_size: 42 renderiza 42 mientras tls_mode sigue llenándose con require, y una Release que establece storage_class: gp3 renderiza gp3 sin alterar ninguna de las dos claves del desarrollador.

Una Recipe para el Component consumidor lee la configuración por arista resuelta desde el canal de topología enriquecido en .context.uses.<alias>.values.<key> y .context.uses.<alias>.infra.<key> — consulta vocabulary/topology-triad.md.

Slots que llena cada conexión — el featuresSchema de un socket. Un socket también puede declarar slots de acoplamiento, y entonces cada conexión establecida a través de él puede llevar su propio acoplamiento en cada uno de ellos: un gateway que alcanza varios modelos tiene una credencial distinta para cada uno, porque la credencial está en la conexión y no en el gateway.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Una conexión llena un slot llevando un acoplamiento con el nombre del slot en su propio features: — en la entrada de conexión del Aggregate (Aggregate) o en la de la Release (Release) — y el acoplamiento pasa a ser uno de los acoplamientos del componente consumidor, con el nombre <alias>.<slot>.

Qué hace la declaración, dicho con exactitud:

  • Los nombres de slot son un conjunto cerrado. A diferencia del featuresSchema propio del Component, que admite un acoplamiento libre con cualquier nombre, los slots de un socket son los únicos nombres que puede llevar una conexión a través de él: cualquier otro nombre detiene la compilación al cargarse, y un socket que no declara ningún featuresSchema no admite ningún acoplamiento en sus conexiones. Un socket ad hoc — uno que este usesSchema no declara — no declara slots, así que sus conexiones tampoco llevan ninguno. Cada conexión llena sus slots por sí misma: un acoplamiento en un ámbito más amplio nunca se propaga en cascada a una conexión, y una clave de Release que escribe el nombre compuesto del acoplamiento de una conexión detiene la compilación.
  • Las demás claves someten cada conexión al slot. Aquí un slot admite las mismas claves que un slot a nivel de Component — required, selector, inject, sensitive, description — y cada conexión queda sujeta a ellas por separado. selector se compara con las etiquetas de la Feature con la que una conexión llena el slot, y un relleno que no admite detiene la compilación, situado en la entrada de esa conexión en el documento que escribió el relleno. required: true se exige a cada conexión establecida a través del socket: una conexión que deja el slot vacío detiene la compilación, nombrando esa conexión, mientras que una conexión contigua que llena el slot pasa. sensitive se lee exactamente como en un slot a nivel de Component: el acoplamiento que llena el slot se marca como sensible en el grafo de compilación y en aggrega inspect. En una conexión, como en un componente, qué valores de un acoplamiento se retienen como sensibles lo decide únicamente el esquema propio de la Feature acoplada. inject rige la entrada de Workload que entrega el material del slot: el acoplamiento de una conexión no lleva ningún bloque inject: propio — ninguno de los dos documentos admite uno en una entrada de conexión —, así que un Workload lo entrega nombrando la conexión junto al slot, y esa entrada queda sujeta a la lista de permitidos del slot del socket exactamente como una entrada que nombra un slot a nivel de Component queda sujeta a la de ese slot.

El usesSchema de una Feature no admite featuresSchema: una conexión que traza una Feature no lleva acoplamientos, y una Feature que declara slots en un socket se rechaza al cargarse. Una credencial que necesite una conexión de ese tipo es un slot en el featuresSchema propio de la Feature.

Generación del esquema a partir de usesSchema. El compilador genera un fragmento base de JSON Schema 2020-12 a partir de los sockets declarados y lo compone con la declaración schema: del usuario — el mismo patrón que usa featuresSchema. El esquema generado nunca toca el disco; solo existe en memoria durante la pasada de validación del Component. El mapa uses: del desarrollador en el Aggregate se valida contra el esquema combinado; el selector: de cada socket se evalúa contra las etiquetas de cada Component candidato durante el análisis estático, como comprobación de seguridad de tipos entre nodos.

Semántica de los selectores — el mecanismo del esquema dividido. usesSchema[].selector: es lo que hace que la topología de Aggrega sea más que un paso de cadenas sin tipo. Un socket que declara selector: "datastore.aggrega.ai/engine=vector" solo acepta conexiones a Components etiquetados con el par clave-valor correspondiente; un agente que intenta conectar su socket primary_datastore a un Component relational falla en el Static Analyzer con un diagnóstico claro de violación del selector. El selector es una cadena de selector de etiquetas al estilo de Kubernetes — requisitos combinados con Y mediante comas, en las formas =, !=, in (...), notin (...), clave sola y !key —, la misma gramática que usa appliesTo de una Feature; consulta vocabulary/modifier-system.md para la gramática y architecture/13-catalog-and-registry.md §2 «Selectores al estilo de Kubernetes» para la semántica del motor. Un requisito fuera de esas formas se rechaza en lugar de leerse como otro selector: un requisito vacío (una coma inicial, final o duplicada), una clave que contiene espacios en blanco o cualquiera de =, !, (, ) y la coma, o un conjunto sin su paréntesis de cierre detiene toda compilación que conecte una arista a través del socket, nombrando el requisito. Así, un socket pensado para excluir los frontends se escribe selector: "tier!=frontend"; "!tier=frontend" se rechaza, porque ! nombra una clave de etiqueta y nada más.

Sockets ad hoc — lo que aporta declarar un socket y lo que un autor puede hacer sin ello. El autor de un Aggregate puede escribir una entrada uses: en su propio componente con un nombre de socket que este usesSchema no declara, incluso en un Component que no declara ningún usesSchema. La arista se construye. Que el catálogo no diga nada sobre un socket significa que la conexión no se previó, no que esté prohibida, y la topología de la aplicación pertenece al desarrollador.

Aquello a lo que renuncia un socket ad hoc es precisamente lo que proporciona uno declarado, porque todo ello reside en la entrada de usesSchema: ningún selector, de modo 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 por arista, de modo que los values: por arista no tienen un contrato con el que comprobarse ni valores por defecto declarados que heredar. También renuncia a infraSchema, aunque en un socket así ese contrato no se alcanza de todos modos: el infra por arista se escribe en una entrada de arista de una Release, y una entrada de Release solo puede nombrar un socket que declara el Component consumidor. Lo que no cambia es lo que la arista puede llevar: el from: de cada entrada inject debe seguir nombrando una clave que declara el schema.provides del Component de destino, y el destino debe seguir existiendo — ambos detienen la compilación igual que en un socket declarado.

Interpreta «ninguna lista de permitidos inject:» como la ausencia de una restricción y no como una declaración de caja negra, porque ambas se parecen y se comportan de forma opuesta. Una arista a través de un socket ad hoc puede imponer la entrega libremente: no hay ninguna lista de permitidos de la que un mecanismo pueda quedar fuera, y ninguna entidad se comprometió a tratar los valores internamente. El rechazo de caja negra descrito arriba se aplica a un socket que la entidad sí declaró y dejó sin lista de permitidos inject: — esa omisión es una declaración sobre una conexión que la entidad previó, y un socket ad hoc no hace tal declaración.

La entrega sigue el mismo camino, y el artefacto renderizado no registra ninguna diferencia. El bloque inject de una arista ad hoc se resuelve y entrega exactamente como el de un socket declarado: cada clave from: se lee de los provides evaluados del destino y llega al contexto de inyección del nodo consumidor bajo la clave de entrega que eligió el autor, alcanzando desde allí el artefacto renderizado. Hay un único camino de entrega y nada en él se bifurca según si el socket se declaró. Lo que un socket declarado puede añadir es contenido — valores por defecto por arista que su valueSchema o infraSchema rellena —, así que, donde un socket declarado no lleva ningún contrato de ese tipo, la misma arista se renderiza de forma idéntica con cualquiera de los dos tipos de socket. La declaración es un hecho sobre la conexión, no una entrada de lo que se renderiza.

Los values: por arista en un socket ad hoc se aceptan y llegan a la Recipe consumidora en .context.uses.<alias>.values, sin validar: sin un valueSchema con el que medirlos, no se comprueba ninguna clave ni se rechaza ninguna. Esto no es exclusivo de los sockets ad hoc — un socket declarado que no escribe ningún contrato para el pilar trata su configuración por arista de la misma manera. Lo que cambia con un socket ad hoc es que el contrato no puede añadirse sin declarar el socket. .context.uses.<alias>.infra está vacío en una arista así, porque la superficie que proporciona el infra por arista no puede nombrar un socket no declarado.

Cada arista del grafo emitido registra cuál de los dos tipos es, de modo que un consumidor nunca tiene que deducirlo, y una organización que quiera que cada conexión pase por un socket declarado puede exigirlo como política de gobernanza. Declarar el socket aquí 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 por defecto y una descripción — una declaración revisable de una conexión prevista, versionada junto con la entidad que la hace. La forma ad hoc es una vía de escape, no un nuevo comportamiento por defecto. Dos superficies no están abiertas de esta forma deliberadamente — los uses de un acoplamiento de Feature solo pueden nombrar un socket que declara la Feature acoplada, y los uses por arista de una Release solo pueden nombrar un socket que declara el Component consumidor.

El ejemplo práctico examples/adhoc-uses-socket/ construye ambos tipos de arista en un mismo consumidor y muestra los dos valores entregados uno al lado del otro en la salida renderizada, junto con la detención que produce una clave from: no declarada.

Las erratas en los nombres de socket aparecen como una advertencia, no como una detención. Como un nombre de socket no declarado es legal, un nombre de socket mal escrito se convierte en una conexión ad hoc propia en lugar de conectar el socket que el autor pretendía — y la compilación sigue en verde mientras nada fluye por ella. El compilador informa como advertencia de un nombre de socket que está a una edición de un nombre que declara este usesSchema, nombrando ambas grafías — consulta errors/warnings.md «Uses-socket near-miss lint (Lint de casi coincidencias en nombres de socket uses)». La advertencia nunca cambia el veredicto de la compilación; el compilador no vigila cómo nombra un autor un socket.

La relación entre usesSchema y featuresSchema. Ambas son tablas declarativas y ambas llevan una lista de permitidos inject: con semántica idéntica, pero un socket y un slot son cosas distintas y no son intercambiables. usesSchema rige las aristas entre componentes — el grafo de topología — declarando qué sockets llevan un contrato. featuresSchema rige los slots de acoplamiento, y un slot es un punto de enlace con nombre, no una enumeración: un acoplamiento con un nombre que ningún slot declara es legal en el bloque propio del componente. (Los slots que un socket declara para sus conexiones son el único conjunto cerrado, como se indica arriba en «Slots que llena cada conexión».) Las dos superficies han convergido en ese punto — la entrada uses: propia de un componente con un nombre de socket no declarado también es legal —, pero siguen siendo distintas: un slot no declarado es un acoplamiento libre en un Component cuyos slots declarados no se ven afectados, mientras que un socket no declarado es una arista sin selector y sin contrato por arista. Muchos Components declaran ambas; las dos tablas se componen de forma independiente.

Slots de asociación: featuresSchema

Un Component puede declarar slots de asociación mediante un bloque featuresSchema. Cada slot nombra un punto de enlace en el que el Component espera que se asocie una Feature — una contraseña de root, una clave de API, un token de autenticación, un enlace de identidad — y restringe qué Feature puede ocuparlo y cómo puede entregarse el material del relleno.

Esta sección trata de los slots propios del Component. Los slots que un socket declara para cada conexión son, en cambio, un conjunto cerrado — consulta «Slots que llena cada conexión» en Sockets de topología.

Declarar un slot no cierra la superficie de asociación. Un autor puede asociar una Feature con un nombre que ningún slot declara, y esa asociación es una asociación libre: perfectamente legal, simplemente no vinculada a un slot declarado. Esta apertura es lo que permite que una misma entidad del catálogo sirva a dos formas de despliegue distintas sin bifurcar el catálogo:

  • Por consumidor. Cada instancia llena el slot con su propia Feature, de modo que cada consumidor obtiene su propia credencial renderizada.
  • Compartida. Ninguna instancia llena el slot; en su lugar, una credencial se asocia una sola vez en un ámbito más amplio (un subsistema, o un límite de Release) y se propaga en cascada a cada componente que contiene, de modo que cada consumidor se llena a partir de esa única declaración. Lo que se renderiza sigue a la realización: un Secret por consumidor, cada uno con el mismo material, con una realización que renderiza un Secret; ninguno con una que apunta a cada consumidor a un Secret que ya existe.

El autor elige entre ambas según lo que asocia. La entidad del catálogo es la misma en ambos casos.

En esa superficie abierta, una sola forma provoca una detención: un relleno escrito en el componente con otro nombre. Cuando una asociación escrita en el propio componente — en su propio bloque features: del Aggregate, o en la entrada de la Release para ese único componente — lleva un nombre que ningún slot declara, y su Feature satisface el selector de un slot que nada ocupa en ese componente una vez plegados todos los ámbitos, el build se detiene. Esa es la forma que adopta un relleno destinado al slot cuando se escribe con el nombre equivocado: si se dejara así, sería una asociación libre mientras el slot sigue vacío, y un slot opcional que se deja vacío produce un build en verde y no entrega nada. El mensaje nombra la asociación, el componente, la Feature y cada slot vacío al que corresponde esa Feature, y el remedio es asociarla con el nombre del slot. Vale para toda Feature, no solo para las credenciales. Todo lo demás en la superficie sigue siendo libre: una asociación cuya Feature no corresponde a ningún slot declarado, una asociación adicional una vez ocupado cada slot al que corresponde, y una asociación que el componente hereda de un subsistema o de un límite de Release — de modo que la forma compartida descrita arriba no se ve afectada. Un slot que no declara ningún selector no dice nada sobre a qué Feature está destinado, así que ninguna asociación se mide contra él de este modo. La detención se describe en errors/fatal-halts.md bajo «An attachment written under another name fits a slot its component leaves empty (Una asociación escrita con otro nombre corresponde a un slot que su componente deja vacío)».

Las dos formas se combinan, y gana la más cercana. Un autor puede hacer ambas cosas a la vez: asociar una Feature en un ámbito más amplio para que llegue a cada componente de ese ámbito, y llenar el slot en el único componente que necesita algo distinto. Gana el relleno con ámbito de componente — campo por campo, de modo que solo necesita volver a indicar los campos que cambia y el resto sigue proviniendo de la asociación más amplia. Los componentes hermanos que no llenaron el slot conservan intacta la asociación más amplia. La regla de precedencia completa, incluida su interacción con las asociaciones impulsadas por anotaciones y con los Aggregates compuestos, está en vocabulary/labels-and-annotations.md «Precedencia de las asociaciones».

Definición del esquema en el Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Semántica de los campos:

CampoTipoPredeterminadoSignificado
requiredboolfalseDeclara que el slot debe terminar ocupado. El build se detiene cuando nada ocupa el nombre del slot en una instancia de este Component, comprobado contra el conjunto de asociaciones que la instancia tiene tras toda la cascada de asociaciones — así, una asociación declarada en un ámbito del que la instancia hereda satisface el slot exactamente igual que un relleno escrito en la propia instancia. El diagnóstico nombra el componente y el slot.
injectstring[]—Lista de permitidos de los mecanismos de entrega inject admitidos. [] (vacía) significa caja negra — la Recipe controla la entrega internamente y el material nunca se entrega al workload. [env, file] significa transparente — el material del relleno puede entregarse mediante los mecanismos listados. La misma semántica que usesSchema[].inject.
descriptionstring—Documentación para personas, renderizada por el IDE y el hub.
selectorstring—Selector de etiquetas opcional al estilo de Kubernetes que restringe qué Feature puede llenar este slot — el análogo, para el slot, del selector de un socket de usesSchema, con la misma gramática y el mismo motor nativo de coincidencia de etiquetas. Se evalúa contra las etiquetas propias de la Feature asociada durante el análisis estático; un relleno cuyas etiquetas no lo satisfacen provoca una detención, y lo mismo ocurre con un selector que la gramática rechaza, nombrando el requisito que no pudo leer. Omítelo para no imponer ninguna restricción al relleno.
sensitiveboolfalseDeclara que lo que ocupe este slot maneja material secreto. Es una afirmación sobre el punto de enlace, no sobre un relleno concreto; consulta «Declarar un slot sensible» más abajo.

Un slot restringe qué relleno puede ocuparlo, no lo que el relleno configura. Deliberadamente no existe un contrato values o infra a nivel de slot: el schema: propio de la Feature asociada es dueño de esos pilares, de modo que cada contrato tiene exactamente un hogar.

El selector del slot es la forma en que un Component restringe qué Feature puede llenar un slot — por ejemplo, a una Feature de credencial específica de un provider (feature.aggrega.ai/kind=secret, provider=helm) — sin nombrar una FeatureRecipe, exactamente como un selector de socket de usesSchema restringe el destino de una arista de dependencia. El compilador evalúa el selector contra las etiquetas de la Feature asociada y nada más: lee las etiquetas que lleva el relleno e informa de si el selector las admite. Qué etiquetas tiene sentido exigir es una elección de autoría del catálogo, no una regla que el compilador imponga.

Las erratas en los nombres de slot aparecen como aviso, no como detención. Como un nombre de asociación no declarado es legal, un nombre de slot mal escrito se convierte en una asociación libre en lugar de llenar el slot que el autor pretendía. El compilador informa de un nombre de asociación que está a una sola edición de un nombre de slot declarado con una advertencia que nombra ambas grafías — consulta errors/warnings.md «Attachment-slot near-miss lint (Lint de casi coincidencias en slots de asociación)». La advertencia nunca cambia el veredicto del build; el compilador no vigila cómo nombra un autor una asociación. Un nombre a una edición de un slot cuyo selector satisface la Feature de la asociación no genera ninguna advertencia: donde ese slot queda vacío, es la detención descrita arriba la que informa de la asociación, y donde otra cosa ocupa el slot, la asociación es una asociación adicional corriente.

Declarar un slot sensible

sensitive: true en un slot expresa la exigencia propia del consumidor: lo que ocupe este punto maneja material secreto.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Es una información realmente distinta del sensitive: true de una hoja del esquema, no un duplicado de conveniencia, y el catálogo de la biblioteca estándar necesita ambos. Una credencial referenciable publica provides.name y provides.key — el localizador del recurso y la clave de datos dentro de él — y ninguno de los dos es sensible: el nombre de un Secret de Kubernetes es público, y también lo es la clave que contiene. Sin embargo, el slot que llena esa credencial maneja sin duda material secreto. Una hoja dice este dato es material secreto; un slot dice este punto de enlace maneja material secreto; las dos afirmaciones tratan de cosas distintas y pueden cumplirse de forma independiente.

La consecuencia práctica es que la exigencia viaja con el punto de enlace y no con el relleno. Una Feature que no declara ninguna hoja sensible — porque el motor de destino es dueño de la credencial y el autor no escribe nada — ocupa igualmente un slot sensible como asociación sensible, porque así lo dijo el slot. También vale lo contrario: un relleno que declara una hoja sensible es una asociación sensible incluso cuando ocupa un slot que no hizo tal declaración, o cuando es una asociación libre que no ocupa ningún slot.

La declaración sigue la cascada de asociaciones y no un único bloque escrito. La exigencia de un slot se aplica al relleno que termine ocupándolo una vez plegados todos los ámbitos, de modo que un relleno a nivel de componente que desplaza a uno más amplio hereda la exigencia sin cambios.

sensitive en un slot tiene el mismo límite que la palabra clave a nivel de hoja — anota; no cifra, no valida, no rechaza, no impone un mecanismo de entrega ni cambia un byte renderizado. La formulación completa está en vocabulary/compact-form-authoring.md «Lo que la palabra clave no hace».

sensitive y compliance.aggrega.ai/data-class son dos ejes distintos, documentados uno junto al otro y nunca confundidos. sensitive es un booleano en una hoja o en un slot: este dato, o este punto de enlace, maneja material secreto. compliance.aggrega.ai/data-class es una etiqueta graduada sobre un nodo entero — public, internal, restricted — que da a los datos que guarda un componente una identidad de gobernanza. Uno es por dato y binario, la otra por nodo y ordenada; ninguno sustituye al otro, y una entidad puede llevar ambos. La etiqueta se trata en vocabulary/labels-and-annotations.md y en architecture/08-credential-model.md «Gobernanza de datos en torno a las credenciales».

Proyección del esquema a partir de featuresSchema

Los slots declarados se proyectan en un fragmento de JSON Schema 2020-12 que describe la forma del bloque de asociaciones. Contra él se validan dos clases de relleno: el bloque de asociaciones de un componente que aporta un módulo importado, una vez construida la composición que lo importa, y una asociación declarada en un ámbito más amplio, contra el slot de cada componente al que llega. El bloque de asociaciones de un componente que declara el propio Aggregate se mide en cambio con el esquema de documento del Aggregate y con la lista de permitidos inject del slot (ver más abajo), y el fragmento está construido para que ambos lleguen al mismo veredicto sobre cualquier relleno. La proyección nunca toca el disco; existe solo en memoria, y el schema: de un Component nunca necesita escribir a mano el pilar de asociaciones.

featuresSchema de entrada:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Fragmento proyectado (en memoria; representación en forma compacta):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Las dos profundidades son independientes. El objeto externo es abierto, de modo que un slot declarado nunca prohíbe las asociaciones que la entidad no enumeró. El fragmento propio de cada slot declarado es cerrado, de modo que un relleno que sí ocupa un slot declarado sigue restringido a la forma de ese slot.

El fragmento describe solo la FORMA. No contiene ninguna afirmación sobre qué slots deben ocuparse, porque un slot marcado como required puede ocuparlo una asociación que llega en cascada desde un ámbito más amplio — lo que deja vacío el bloque que describe este fragmento. Por eso el requisito se comprueba contra el conjunto de asociaciones con el que termina un componente y no contra lo que declara un único bloque, y las dos preguntas nunca se contradicen porque solo una de ellas se plantea alguna vez al bloque escrito.

Las claves permitidas reflejan las claves que una asociación puede llevar en cualquier lugar, de modo que una clave legal en una asociación libre sigue siendo legal en el relleno de un slot. Cada mecanismo de entrega de la lista de permitidos es una lista de entradas de entrega — la misma forma que inject: adopta en todas partes; el slot restringe qué NOMBRES de mecanismo pueden aparecer, no el aspecto de una entrada.

Dónde se aplica la lista de permitidos inject

La lista de permitidos vincula ambos lados del slot, en dos pasos distintos.

Frente al Workload de la Recipe, en el paso de renderizado: un Workload que hace referencia a un slot mediante las entradas de asociación de su contenedor debe nombrar un slot que la entidad declara, y debe seleccionar un mecanismo de entrega que la lista de permitidos inject del slot admite; una referencia a un slot de caja negra (inject: []), a un mecanismo fuera de la lista de permitidos o a un slot que la entidad nunca declaró detiene el build. El diagnóstico nombra la Recipe, la ruta del contenedor y el slot infractor, y se clasifica como un fallo del catálogo — es la Recipe la que se equivocó.

Frente a la asociación propia del Aggregate, cuando se resuelven sus asociaciones y antes de cualquier renderizado: un bloque inject: en un relleno que ocupa un slot declarado solo puede nombrar mecanismos que la lista de permitidos del slot admite, y un slot de caja negra no admite ninguno — su lista de permitidos vacía dice «la Recipe entrega esto internamente; no dictes la entrega», y escribir una entrega para él detiene el build. El diagnóstico se sitúa en la asociación y nombra el slot y el mecanismo infractor, junto con los mecanismos que el slot admite cuando admite alguno; se clasifica como un fallo del desarrollador, porque es el Aggregate el que se equivocó. Un bloque inject: {} vacío no nombra ningún mecanismo, así que no dicta ninguna entrega y se acepta en cualquier slot, incluido un slot de caja negra — igualmente en un componente que declara el Aggregate, en uno que aporta un módulo importado y en una asociación declarada en un ámbito más amplio. Una asociación libre — con un nombre que ningún slot declara — no tiene tal restricción, porque la lista de permitidos pertenece al slot y no al bloque.

El flujo de extremo a extremo a través del pipeline de compilación — cómo una asociación del Aggregate se conecta a una Feature de credencial (como core/secret-value) y luego a una FeatureRecipe específica del provider que entrega la credencial al workload en ejecución — se desarrolla en examples/05-credential-features.

Una clave que el llamador presenta y una clave que el servidor verifica

Cuando un componente llama a otro que verifica una clave, cada extremo guarda la clave de su propio lado, en un slot que declara él mismo. Esta es una convención que sigue el catálogo de la biblioteca estándar; el compilador no aplica nada de ello — comprueba los slots de cada componente contra las asociaciones propias de ese componente, hace pasar sus cadenas y nunca compara lo que guarda un componente con lo que guarda otro.

  • La clave que presenta un llamador es del llamador. Se encuentra en un slot que el socket del llamador declara para cada conexión — consulta «Slots que llena cada conexión» arriba — de modo que un llamador que alcanza varios destinos guarda una clave para cada uno. El socket model de core/ai-agent/crewai declara ese slot como credential, y sus Recipes entregan lo que lo llene como OPENAI_API_KEY. Los sockets models de core/gateway/litellm, core/gateway/kong y core/gateway/apisix también lo declaran, y sus Recipes entregan la clave de cada conexión en una variable propia, nombrada según el alias de la conexión, de modo que cada modelo que sirve el gateway tiene una clave propia. Una clave que un Component declara en cambio en un slot propio es una única clave para todas las conexiones que establece.
  • La clave que verifica un servidor es un slot propio del servidor. core/ai-model/vllm, core/ai-model/tei y core/ai-model/tgi declaran cada uno un api_key opcional, y cada una de sus Recipes entrega lo que lo llene como la variable de la que el servidor lee su clave. El modelo y el gateway de LiteLLM declaran api_key para la clave que LiteLLM llama su clave maestra.
  • Ningún extremo ve las asociaciones del otro. Una asociación en una conexión es una de las asociaciones del llamador y solo llega al renderizado del llamador, y la salida renderizada de un servidor es la misma sea lo que sea lo que lleven las conexiones que lo alcanzan. Un slot marcado como required lo debe el componente que lo declara, nunca los componentes conectados a él, y llenar el slot de un extremo no llena nada en el otro — así que declarar la clave en ambos extremos es el mínimo y no un duplicado.
  • Ambos extremos leen un mismo parámetro, de modo que la clave que presenta el llamador y la clave que verifica el servidor no pueden escribirse por separado.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Un servidor que verifica una sola clave no puede distinguir a sus llamadores: vLLM, TEI y TGI verifican cada uno una única clave, de modo que cada llamador presenta la misma, por muchas conexiones que alcancen el servidor. Que los dos extremos hagan referencia a un mismo secreto o que cada uno guarde el suyo depende de dónde resuelve cada provider un secreto por referencia, y el Manifest elige la realización de cada extremo — Modelo de credenciales desarrolla ambos casos.

Una credencial que un componente guarda para sí mismo — una clave con la que firma sus propias sesiones, por ejemplo — es un slot de su propio featuresSchema: como cualquier otro. Una contraseña que presenta a un almacén de datos al que llega por uno de sus sockets es la clave del llamador descrita arriba, así que se encuentra en esa conexión como credential: el socket backend de core/gateway/kong la declara, y sus Recipes de síntesis de workload la entregan como KONG_PG_PASSWORD, y el socket cache_store de core/gateway/litellm la declara para la contraseña que su caché semántica presenta al almacén, entregada como REDIS_PASSWORD. Cuando una conexión presenta un par — un identificador de clave de acceso y su secreto — la mitad secreta es credential y la mitad identificador credential_id, como en el socket store de core/ai-agent/agenta-api.

Autoinyección: spec.inject

Un Component puede declarar un array de nivel superior spec.inject: que enumera los mecanismos de entrega permitidos para la autoinyección. Cuando está presente, los desarrolladores pueden usar un bloque inject: a nivel de componente en el Aggregate para inyectar las claves values: o provides: del propio Component directamente en su propio canal de entrega (las variables de entorno de su contenedor, los archivos montados o los argumentos del proceso). Cuando spec.inject: está ausente o vacío, la autoinyección a nivel de componente está prohibida: la Recipe controla todo el cableado interno, siguiendo el patrón Black-Box que usesSchema[].inject: [] y featuresSchema[].inject: [] aplican a la entrega entre componentes y a la entrega de credenciales, respectivamente.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Cada plantilla value: empieza con {{"{{"}} en lugar de {{. Todo el texto del Aggregate se lee una vez como plantilla, para la interpolación de parámetros, antes de que se ejecute la resolución de la autoinyección, y .values no existe en ese momento; el escape vuelve a colocar {{ para que la resolución de la autoinyección lo evalúe. Consulta Texto que contiene sus propias llaves dobles.

Semántica del campo. spec.inject: es un array de nombres de mecanismos. Se definen tres valores:

  • env — variables de entorno en el contenedor.
  • file — rutas de archivos montados.
  • arg — argumentos de línea de comandos del proceso.

La semántica replica exactamente la de usesSchema[].inject y featuresSchema[].inject: mismo vocabulario, mismo patrón Black-Box cuando se omite, misma forma de autoría en el lado del Aggregate. La diferencia es el origen: usesSchema[].inject rige cómo los provides de una dependencia entre componentes fluyen hacia el canal de entrega del consumidor; featuresSchema[].inject rige cómo una credencial llega a un contenedor; spec.inject rige cómo los values y provides propios del Component llegan al propio contenedor del Component.

Disciplina de autoría. Un Component core/web-server que declara spec.inject: [env, file] opta por la entrega transparente: el autor del Aggregate dicta qué nombres de variables de entorno llevan qué valores. Un Component que declara spec.inject: [] (u omite el campo) mantiene la entrega opaca: el valuesMapping: de la Recipe decide qué campos fluyen hacia qué variables del contenedor, y el desarrollador no puede sobrescribirlo en el Aggregate. El patrón Black-Box se adapta a Components con un contrato estable (un Component core/postgres-db cuya Recipe sabe cómo conectar la contraseña de la base de datos a una variable de entorno POSTGRES_PASSWORD); el patrón transparente se adapta a Components en los que la intención del desarrollador nombra legítimamente detalles de entrega (un core/web-server cuya aplicación lee LOG_LEVEL desde un nombre de variable no estándar que el desarrollador quiere personalizar).

Modos de error. Un Aggregate de un desarrollador que usa un bloque inject: en un Component cuyo spec.inject: falta o está vacío detiene la compilación al cargar el espacio de trabajo («Self-inject on a component without an allowlist» (Autoinyección en un componente sin lista de permitidos)). Un bloque inject: que usa un mecanismo que no está en la lista de permitidos se detiene con la misma condición, nombrando el mecanismo y los que la lista permite («Self-inject mechanism not in the component’s allowlist» (Mecanismo de autoinyección que no está en la lista de permitidos del componente)). Una colisión de claves de entrega entre la autoinyección, la inyección entre componentes y la inyección de credenciales también detiene la compilación («Duplicate delivery key across inject sources» (Clave de entrega duplicada entre fuentes de inyección)). Consulta errors/fatal-halts.md para ver la forma del mensaje de cada error.

Autoría del catálogo: extender Components base

Los Platform Architects usan la palabra clave extends para superponer interfaces especializadas sobre líneas base corporativas o de la comunidad. Extender compone la estructura y hereda los pilares de datos completos. El compilador recorre la cadena desde la base hacia abajo; las dos mitades se comportan de forma distinta, y esa diferencia es todo el modelo de autoría.

Qué compone la extensión. Estas superficies se fusionan a lo largo de la cadena: el Component que extiende prevalece clave por clave y las listas se concatenan empezando por la base, sin duplicados:

SuperficieCómo se compone
metadata.labelsfusión clave por clave; el valor del Component que extiende prevalece en una clave compartida
metadata.annotationsfusión clave por clave, con la misma precedencia; por eso el mandato de presencia de una base alcanza a todo Component que la extiende
spec.featuresSchemaunión de las ranuras de adjunción; una ranura que el Component que extiende vuelve a declarar sustituye la entrada de la base con ese nombre
spec.usesSchemaunión de los sockets de topología, con la misma regla de sustitución por nombre
spec.injectlas dos listas de permitidos de autoinyección se concatenan, primero las entradas de la base, con los duplicados descartados
spec.assertionslas reglas con nombre se acumulan, primero las de la base, y esta única superficie no admite ninguna sustitución por nombre; consulta «La herencia de aserciones es aditiva» más abajo

Un socket que añade el Component que extiende puede llevar sus propios valueSchema e infraSchema por arista; son contratos sobre las aristas de ese socket, no añadidos a los pilares propios del Component.

El resto de metadata: permanece con el documento que lo declara. labels y annotations son los únicos metadatos que descienden por la cadena. name, version, description, maintainers, license, repository, home y keywords son propios del Component que extiende y se leen exactamente como los escribió: un Component que omite description: no tiene ninguna, en lugar de tomar prestada la de su base. La identidad y la procedencia pertenecen al documento que estás leyendo, de modo que un envoltorio nunca se confunde con lo que envuelve.

Qué hereda completo la extensión. Los tres pilares de datos —values, infra, provides— no se componen. Un Component que extiende no escribe contenido de pilares: escribe el marcador literal schema: inherited y recibe el bloque schema: de su base exactamente como la base lo escribió. A lo largo de una cadena de cualquier profundidad, cada Component de ella lleva sin cambios el bloque de la raíz de la cadena, de modo que aggrega inspect --resolved sobre una hoja muestra los mismos pilares que la raíz.

El schema Component publicado determina cuál de los tres resultados posibles es válido y rechaza los otros dos al cargar el documento, con un diagnóstico distinto para cada uno, porque son errores distintos:

  • extends: con contenido de pilares bajo schema: se rechaza. El contrato del Component es el de su base; un segundo contrato divergente no tiene dónde existir.
  • extends: con schema: omitido por completo se rechaza. Una omisión impediría al lector distinguir un bloque de pilares heredado de uno olvidado.
  • schema: inherited sin extends: se rechaza. El marcador indica de dónde vienen los pilares, y este Component no tiene una base de la que tomarlos.

Un Component que extiende no puede remodelar el conjunto de claves. No declara claves de pilares, por lo que no puede ocultar, eliminar ni cambiar el tipo de una clave que declara su base, y no añade ninguna propia. Una nueva clave de pilar pertenece al Component cuyo contrato la posee. Lo que la base exponga, todo lo que la extiende lo expone de forma idéntica.

Una especialización se restringe mediante assertions:. Cuando una especialización debe admitir menos de lo que admiten los pilares de su base —un rango numérico más estrecho, un subconjunto de un enum: heredado—, lo indica en su propio bloque assertions:: una regla allí rechaza un valor que el schema heredado acepta. Esa es la superficie donde reside la restricción; consulta «El bloque assertions:» más abajo.

Esos dos últimos párrafos son una sola regla, y cada mitad por separado induce a error: reducir el conjunto de claves es imposible, endurecer las restricciones es posible. Si se toma solo la primera, se concluye que una especialización no puede restringir nada; si se toma solo la segunda, se concluye que puede remodelar el contrato. Ninguna de las dos cosas es cierta: el conjunto de claves lo fija la base, y los valores admitidos dentro de él pueden restringirse mediante un predicado.

La herencia de aserciones es aditiva, y la acumulación empieza por la raíz. Una instancia de un Component que extiende se comprueba frente a cada regla que declara su cadena, además de las reglas que declara el propio Component, evaluando primero las heredadas. A lo largo de una cadena de cualquier profundidad, las reglas se acumulan desde la raíz de la cadena hacia abajo, de modo que, cuando una instancia incumpliría más de una regla, se informa la declarada más arriba en la cadena: responde primero el contrato más fundamental.

Como la herencia añade en lugar de sustituir, un Component que extiende no puede reutilizar el nombre de una regla heredada para declarar una regla diferente: eso se rechaza cuando la cadena de extends se resuelve frente al catálogo, con un diagnóstico que nombra ambos Components y el nombre compartido. La comprobación necesita tener a mano el Component base, por lo que se informa cuando se valida el catálogo o una compilación resuelve la cadena; validar por sí solo el documento que extiende no puede detectarlo. El nombre de la regla es un identificador estable, así que ni eliminar la regla de la base ni renombrarla en silencio es una opción, y la corrección es un cambio de nombre en el Component que extiende. Repetir una regla heredada byte a byte con su propio nombre se acepta como la operación nula que es.

aggrega pull obtiene la base. Una base es una dependencia de cada Release que alcanza un Component que la extiende, la nombre o no cualquier otra cosa. aggrega pull sigue cada extends: hasta el final de la cadena, obtiene del registro una base que ningún directorio de catálogo contiene y registra cada base en el lockfile de la Release, referenciada desde el spec.extends del Component que la nombra; una compilación lee la base desde allí. Así, un Manifest mapea el tipo propio de un envoltorio y nada más — la base necesita una línea de mapeo propia solo donde un Aggregate también declara una instancia de la base. Un aggrega validate de todo el catálogo lee una base de la misma manera, por lo que allí se rechaza una base publicada en un registro, nombrando aggrega pull, hasta que un pull la haya obtenido.

Consulta architecture/13-catalog-and-registry.md §3 para conocer los formatos de contenido de los schemas.

Ejemplo A: el Component base (la línea base corporativa) El Platform Architect define un servidor empresarial fundamental. Esta base establece la etiqueta obligatoria de primitiva operativa de nube y fija las restricciones de seguridad en el schema. Como el bloque de pilares se hereda sin cambios, cada restricción de aquí llega a cada Component que extiende exactamente como se escribió.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Ejemplo B: el Component que extiende (especializar la línea base) Un gateway se especializa a partir de esa línea base. Toma completos los pilares de la base, añade estructura propia —una etiqueta, un mecanismo de autoinyección, un socket de topología con una ranura de adjunción— y restringe el tiempo de espera heredado mediante una aserción. No repite la regla audit-window-is-observable de la línea base: esa regla se hereda y se evalúa primero, por lo que una instancia de este gateway debe satisfacer ambos límites: al menos 100 y como máximo 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Para la Recipe que implementa esta interfaz core/gateway/kong sobre un chart de Helm físico, consulta entities/recipe, ejemplo C (kong-gateway).

El bloque assertions:

Component.spec.assertions: es un mapa opcional de reglas con nombre que expresan invariantes arquitectónicos del contrato del Component: reglas entre campos que la autoría del desarrollador debe cumplir independientemente de qué Recipe se vincule al Component. Cada clave es un identificador de regla que aparece en el mensaje de fallo; cada valor es el cuerpo de una plantilla Go. El compilador las evalúa por instancia después de la validación del schema y antes de la vinculación de la Recipe, en el orden en que están escritas, y la primera regla que falla detiene la compilación con el mensaje de error propio de esa regla, según el contrato Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

La regla anterior es una propiedad del contrato del Component: sea cual sea la Recipe que se vincule (chart de Bitnami, alternativa hecha a mano, implementación futura), el modo de replicación requiere al menos dos réplicas secundarias.

assertions: es donde un Component que extiende se restringe. Un Component que usa extends: sobre una base hereda literalmente el bloque de pilares de la base y no declara contenido de pilares propio, por lo que una especialización que debe admitir menos que el schema heredado expresa aquí la restricción como un predicado en lugar de como una hoja de schema reducida: una regla que rechaza un valor que los pilares heredados aceptan. El par de ejemplos y el comportamiento completo de la herencia están en «Autoría del catálogo: extender Components base» más arriba: las reglas se acumulan a lo largo de la cadena empezando por la raíz, y reutilizar el nombre de una regla heredada para una regla diferente se rechaza en lugar de permitir que la sustituya.

El compilador no comprueba si dos reglas pueden cumplirse a la vez. Una regla es un predicado de plantilla, no una restricción sobre la que el compilador razone, por lo que un par de reglas que ningún valor puede satisfacer a la vez —una base que exige al menos 100 y una especialización que exige como máximo 50— no produce ninguna advertencia al cargar el catálogo. Aflora de la forma habitual: se escribe una instancia, la compilación se detiene en la primera de las dos que se active, y el mensaje de esa regla es lo que lee el autor. No esperes que una contradicción se informe de antemano; comprueba la restricción de una especialización frente a lo que su base ya exige.

Usa assertions: para reglas genuinamente entre campos. Las restricciones por campo (rango, patrón, enum) corresponden a palabras clave de schema:; los predicados personalizados por campo corresponden a validate: de la forma compacta; la forma condicional (si se aplican las restricciones de un subárbol) corresponde a when:. Para la gramática de autoría completa —campos del contexto de plantilla, la convención de mensajes de {{ fail }}, la fase de evaluación y ejemplos desarrollados que abarcan los roles de Component y Recipe—, consulta templates/assertions-block.md.