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

Taxonomía de datos y composición

La taxonomía unificada de datos y las reglas de composición

Para establecer un esquema predecible y eliminar la fricción cognitiva, la plataforma utiliza exactamente cinco palabras clave universalmente comprendidas y una estructura YAML estrictamente basada en mapas (diccionarios), con mapas en lugar de arrays anidados en la raíz estructural.

1. El estándar de mapas de 5 palabras clave y la simetría total de los esquemas

El vocabulario estructural directo: una regla fundamental del diseño de los esquemas es que las estructuras de datos raíz deben ser palabras clave únicas y estructurales. Aunque usar expresiones coloquiales en inglés (como depends_on o runs_within) puede hacer que un DSL de YAML resulte más natural de leer para un desarrollador, introduce complejidad estructural al mapear esas claves en plantillas Go programáticas. Para mantener un mapeo directo 1:1 de variables y evitar la fragmentación del lenguaje específico de dominio (DSL), los esquemas JSON de las entidades centrales del catálogo (Component, Feature) expresan una simetría estructural casi total, impulsada por el mismo conjunto central de palabras clave estructurales que se usa en todas las ranuras de instancia escritas. Las Features de credenciales (etiquetadas feature.aggrega.ai/kind: secret) comparten este mismo paradigma — no existe un esquema separado para los secretos.

  • parameters (el contrato de entorno global)
    • Ámbito: se definen en la raíz del Aggregate; la Release (CI/CD) los satisface en línea bajo parameters: o mediante parameters: { $import: <path> } apuntando a un archivo de parámetros externo.
    • Significado: argumentos externos que alteran dinámicamente el estado cognitivo o lógico de la aplicación entre entornos (p. ej., cambiar workers: 2 a workers: 10). Admite un contrato tipado (consulta data-pillars para ver la sintaxis completa del contrato tipado) que se valida antes de la interpolación. Para los flujos de trabajo GitOps que mantienen los valores de los parámetros en un archivo separado, la Release usa la forma $import:; el compilador carga el contenido del archivo y reemplaza el mapa en línea parameters:. La superposición de varios archivos se expresa mediante cadenas extends: de Release.
  • values (la intención cognitiva - propiedad del desarrollador)
    • Ámbito: se usan de forma uniforme dentro de components y de sus vinculaciones features en el Aggregate, incluidas las Features de credenciales.
    • Significado: el estado cognitivo central, la lógica de negocio y la configuración operativa. Opacos para el compilador Go, pero validados estrictamente por la declaración unificada schema: del catálogo (forma compacta o JSON Schema 2020-12).
  • uses (la topología estructural - estado declarativo)
    • Ámbito: se usan de forma uniforme dentro de components y de sus vinculaciones features en el Aggregate, incluidas las Features de credenciales.
    • Significado: una afirmación declarativa de hechos que define aristas de red y dependencias (p. ej., «Este agente usa esta base de datos»). El compilador Go la analiza de forma nativa para trazar el grafo de la representación intermedia (IR). Se valida mediante la declaración unificada usesSchema del catálogo para imponer la seguridad de tipos entre nodos.
  • infra (la realidad física - propiedad de Ops)
    • Ámbito: se usa de forma uniforme dentro de los components de un límite y de sus vinculaciones features en la Release.
    • Significado: la huella física y el dimensionamiento mecánico que se inyectan durante el Late Binding (p. ej., cpu_limit: "4", port: 5432). Las instancias de componente del Aggregate y sus vinculaciones features no incluyen un campo infra y, combinadas con additionalProperties: false, rechazan infra en la validación del esquema. Se valida mediante la declaración unificada schema: del catálogo.
  • inject (el contrato de entrega - comando imperativo)
    • Ámbito: se usa en una instancia de componente, dentro de definiciones de destino explícitas en uses y en las features vinculadas, incluidas las Features de credenciales.
    • Significado: un comando explícito e imperativo que dicta la intención de la entrega (p. ej., «Compilador, inyecta este valor mapeado como variable de entorno»). Establece el contrato abstracto (env, file, arg o mecanismos personalizados) para una salida física, un endpoint resuelto o una credencial recuperada, mientras que la mecánica física de cómo se ejecuta exactamente ese montaje se delega por completo a la Recipe de Ops subyacente. Cada mecanismo es una lista de entradas ([{ in: API_HOST, from: "host" }]), cada una de las cuales nombra su identificador local con in: y lleva exactamente uno de from: o value:.
  • .context (la tubería genérica de metadatos)
    • Ámbito: el compilador lo inyecta silenciosamente en las plantillas de la Recipe de Ops.
    • Significado: lleva lo que el compilador ensambló para el nodo a partir del resto del grafo (como .context.uses), que se pasa directamente al motor de plantillas de Ops.

La realidad del mapeo 1:1

Al sustituir las preposiciones coloquiales por palabras clave de infraestructura estrictas, se logra un mapeo 1:1 directo. El ingeniero de Ops no tiene que traducir gramática; simplemente hace referencia a las claves exactas que escribió el desarrollador.

Formas estructurales: mapas en la raíz, arrays en los payloads. Los bloques de topología raíz — components, features, aggregates, subsystems, boundaries — son mapas YAML cuyas claves, escritas por el usuario, sirven como ID de instancia estables. Los arrays no son válidos en estas posiciones; la clave del mapa es la identidad que el compilador usa para las referencias cruzadas (target: my-db), la construcción de los nodos del grafo y la resolución del Manifest. Dentro de los bloques de payload opacos (values, infra, parameters), los arrays están plenamente permitidos — los desarrolladores pueden escribir tools_allowed: ["sql", "web"] o hostnames: ["stripe.com", "twilio.com"] dentro de los values de un Component. El esquema del Aggregate declara estos bloques de payload como additionalProperties: true, de modo que son opacos para el compilador Go y los valida por completo la declaración schema: incrustada en el catálogo. Esto sitúa la volatilidad de los frameworks (nuevas formas de API de IA, nuevos formatos de payload cloud-native) dentro del dominio del catálogo, donde puede evolucionar de forma independiente, mientras el compilador Go se limita a claves direccionables en la raíz estructural.

2. Los flujos de información: ¿quién, cuándo y para qué?

Para evitar colisiones de espacios de nombres en las plantillas y la filtración involuntaria de configuraciones de infraestructura física en la lógica cognitiva de la aplicación, la arquitectura separa explícitamente los datos en seis flujos distintos:

  • Flujo 1: la inyección del entorno (parameters): el pipeline de CI/CD inyecta las realidades del despliegue. El compilador valida cada valor suministrado por la Release frente al contrato tipado parameters: y luego interpola las variables de plantilla Go resueltas antes de ejecutar la validación posterior del esquema values:.
    • Uso recomendado: los parameters se reservan para la lógica cognitiva de la aplicación que varía entre entornos (p. ej., LOG_LEVEL=debug, ENABLE_BETA=true). El dimensionamiento operativo y los aspectos de infraestructura física — réplicas, límites de CPU, ARN de AWS, nombres de host de ingress — fluyen por el bloque infra de la Release y las superposiciones de los límites, lo que mantiene el Aggregate del desarrollador centrado en la intención de la aplicación.
    • Vía de escape pragmática: para equipos pequeños, prototipado rápido o integraciones de CI/CD heredadas en las que una separación estricta no es práctica, los parameters pueden llevar configuraciones globales del entorno a través de la pila. El compilador acepta todo lo que supera la validación del esquema; la recomendación anterior es un contrato social, no una regla del compilador.
  • Flujo 2: intención cognitiva de la aplicación (values en los Components): define la lógica intrínseca de la aplicación. La declaración schema: del Component (forma compacta o JSON Schema 2020-12) proporciona una comprobación de tipos y una validación estrictas para este payload, ofrece a los desarrolladores una retroalimentación «Shift-Left» inmediata y garantiza que las configuraciones solicitadas coincidan con la API de infraestructura subyacente.
  • Flujo 3: intención operativa de la Feature (values en Features): en el Aggregate, el desarrollador solicita las capacidades de infraestructura cuyo comportamiento es intención de la aplicación y consulta credenciales estrictamente tipadas, sin modificar el código interno. Una Feature cuyas entradas son todas operativas no lleva values del desarrollador: operaciones la vincula en la Release, con su infra (flujo 4).
  • Flujo 4: dimensionamiento de la infraestructura física (infra): sin pasar en absoluto por el desarrollador, el dimensionamiento físico infra se proyecta explícitamente desde la Release específica del entorno directamente sobre los Components de ámbito local y sus Features vinculadas, incluidas las Features de credenciales. Para evitar colisiones de validación de esquemas cerrados por difundir diccionarios tal cual, el dimensionamiento infra se localiza estrictamente en el componente explícito que lo tiene como destino. Esto mantiene los límites de cómputo, las réplicas y los requisitos mecánicos de recursos en el dominio de Ops.
  • Flujo 5: anotaciones en cascada (metadatos contextuales): los datos contextuales amplios (como dominios operativos, namespaces o códigos de facturación) se gestionan mediante anotaciones en cascada, lo que evita la contaminación por difusión de infra. Se separan en contenedores según su origen, y el uso previsto de cada contenedor que se describe a continuación es un contrato social: una plantilla de Recipe puede leer los tres, y el compilador no impone la separación (consulta labels-and-annotations):
    • .context.annotations.release (límites del dominio 4): se usan exclusivamente para gobernar realidades físicas. Ops enruta explícitamente estas anotaciones a campos infra locales estrictos mediante plantillas Go (p. ej., mapeando un namespace regional a un componente de cómputo).
    • .context.annotations.aggregate (subsistemas del dominio 1): se usan exclusivamente para gobernar la lógica cognitiva y operativa. Estas anotaciones se enrutan explícitamente a los payloads values del componente (p. ej., propagando en cascada el código de facturación de un equipo hasta una configuración de la aplicación).
    • .context.annotations.catalog (catálogo del dominio 2): rasgos intrínsecos inmutables escritos por el arquitecto, usados principalmente para la evaluación programática de políticas Wasm.
  • Flujo 6: la tubería de metadatos (.context): aplica requisitos empresariales globales (etiquetas SOC2) directamente a las plantillas de la infraestructura física.

3. Abstracción de red: la convención «Zero-Port»

  • La buena práctica: los desarrolladores deberían omitir los puertos del Aggregate. La Recipe de Ops gestiona dinámicamente el enrutamiento interno.
  • La vía de escape: si el código interno de una aplicación no puede cambiarse, el arquitecto de plataforma expone explícitamente un campo port en la declaración schema:. Nota de arquitectura: la convención «Zero-Port» es el ejemplo más destacado de la separación de responsabilidades más amplia de la plataforma. Esta misma filosofía — abstraer la mecánica física y alejarla del desarrollador — se aplica a las solicitudes de CPU, los límites de memoria, los dominios operativos y el dimensionamiento de discos. Siempre que una restricción de infraestructura física deba filtrarse en el payload de la aplicación del desarrollador (por código heredado o requisitos de hardware estrictos), debe regirse siempre por una «vía de escape» explícita en la declaración schema: del arquitecto, la declaración con la que se valida el payload del desarrollador.

El nombre «Zero-Port» designa esta convención; el principio se generaliza a cualquier restricción de infraestructura física que una aplicación heredada codifique de forma fija. El esquema siguiente usa tcp_keepalive_seconds como ejemplo práctico — una temporización de kernel/red que la aplicación espera en la capa de sockets — porque se sitúa claramente en el eje de la filtración de infra.

El esquema (dominio 2):

values:
image: { type: string, required: true }
# The architect explicitly allows the developer to declare a hardcoded constraint
tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }

El YAML del desarrollador (dominio 1):

components:
legacy-payment-engine:
type: core/java-tomcat:1.0.0
values:
image: "corp/payments:v4"
tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versa

Comportamiento del compilador: el compilador Go pasa tcp_keepalive_seconds: 120 al grafo de la IR. Luego, la Recipe de Ops lee {{ .values.tcp_keepalive_seconds }} para configurar la especificación del pod de Kubernetes o el tiempo de inactividad del balanceador de carga del proveedor de nube, salvando así la brecha con lo heredado sin infringir el esquema.

4. El contrato de inyección y el mapa prerresuelto

Entre las cinco palabras clave estructurales, inject tiene una forma distinta de la de sus hermanas. parameters, values, uses e infra son estado declarativo — el desarrollador escribe hechos sobre qué es la aplicación y de qué depende. inject es un comando imperativo — el desarrollador dicta cómo debe entregarse un valor al contenedor en ejecución, mapeando fuentes de datos abstractas (las claves provides de un destino, los valores propios del componente, la respuesta del vault de una Feature de credenciales) a mecanismos de entrega concretos (env, file, arg o un mecanismo personalizado que declara el Component).

Este desacoplamiento es estructural. El Aggregate del desarrollador dice «inyecta el host de la base de datos como la variable de entorno DB_HOST» sin nombrar la dirección física de la base de datos, la ruta del vault en el almacén de secretos ni el formato de nombre de host del proveedor de nube. La Recipe de Ops recibe la cadena resuelta a través de .context.inject y la consume sin escribir la cadena de búsqueda.

El mapa prerresuelto. Durante el renderizado, el compilador resuelve cada fuente de inyección — los literales de autoinyección y las referencias from: contra los provides del propio componente, las referencias entre componentes a través de uses[].inject, las intercepciones injectMapping de la FeatureRecipe — en un único diccionario aplanado en .context.inject. Cuando se ejecuta la plantilla valuesMapping de la Recipe base, cada clave de inyección ya lleva su valor de cadena final. Las Recipes iteran el mapa directamente ({{ range $k, $v := .context.inject.env }}) sin recorrer la cadena de resolución.

Los nombres que el desarrollador da a los valores propios del componente. Donde el Component declara spec.inject, el bloque inject: propio del desarrollador elige los nombres con los que los valores propios y los provides del componente llegan al canal de entrega. El compilador indica a la Recipe, en .context.self_inject, el único valor propio que lee la plantilla de cada entrada —por mecanismo, cada nombre asociado a provides.<key>, a values.<key> para una plantilla que lee exactamente un valor propio y nada más, o a una cadena vacía— con la forma que adoptan los nombres de una conexión en .context.uses.<alias>.inject. La convención del catálogo de la biblioteca estándar para una Recipe que ejecuta la imagen del desarrollador es tratar como valores predeterminados los nombres que de otro modo elegiría para los valores propios del componente, y entregar un valor propio con su nombre predeterminado solo cuando ninguna entrada se asocia ya a él. Es una convención del catálogo, no una regla del compilador: un catálogo empresarial puede entregar los valores propios de sus componentes como prefiera. El compilador lee el mapa del texto que escribió el desarrollador y no atribuye ningún significado a los nombres.

La especificación completa del contrato de inyección — semántica del contexto de doble estado, reglas de colisión de claves, el modelo de intercepción de la FeatureRecipe y ejemplos prácticos — se encuentra en topology-triad.

5. El motor de plantillas (DX de Ops)

Los ingenieros de Platform Ops escriben las plantillas de traducción y necesitan toda la potencia de las plantillas de infraestructura estándar, sin un lenguaje de plantillas propietario. Las plantillas de Aggrega son Go text/template:

  • Sin cadenas «mágicas»: el compilador conserva las claves de mapa exactas del desarrollador. Ops accede a las features de forma segura mediante la indexación estándar de mapas de Go: {{ (index .features "public-route").infra.hostname }}.
  • La biblioteca Sprig: el compilador registra de forma nativa la biblioteca Sprig, estándar en Helm, lo que da acceso inmediato a pipelines como | default, | quote y | toYaml.
  • Fragmentos de MappingLibrary: un fragmento de mapeo que reutilizan varias Recipes reside en una MappingLibrary y se incorpora a cada Recipe con $import:. Los helpers de plantillas de charts de Helm (include, tpl, required, warn) no están registrados; sprig-functions enumera los que sí lo están.

6. Reglas de composición: Aggregates, subsistemas y Components

  • Agrupación lógica (el array subsystems): los desarrolladores pueden aplicar metadatos lógicos (propiedad del equipo, etiquetas de cumplimiento) y features transversales a decenas de componentes a la vez usando subsystems. Los subsistemas actúan como carpetas recursivas en el plano lógico/de intención, propagan en cascada las annotations hacia abajo al contenedor .context.annotations.aggregate y vinculan features a todos los componentes contenidos sin dictar límites físicos. Las features de nivel de subsistema siguen el mismo esquema que las features de nivel de componente (admiten type, values, uses, inject) porque pertenecen al dominio 1 (intención del desarrollador). Al finalizar el grafo, el compilador aplana las features del subsistema en la lista de features de cada componente contenido, colocándolas después de las features propias del componente y antes de cualquier feature vinculada por la Release en el orden de ejecución.
aggregate.yaml
subsystems:
finance-module:
annotations:
"billing.corp.com/team": "payments"
features:
audit-logging:
type: core/audit-logger:1.0.0
values: { log_level: "verbose" }
components:
ledger-api:
type: core/python-worker:1.0.0
ledger-db:
type: core/postgres:1.0.0
  • Los Aggregates compuestos ESTÁN ADMITIDOS (el patrón de módulos): los Aggregates actúan tanto como el Aggregate raíz que construye una Release como módulos reutilizables. Un Aggregate padre puede declarar un Aggregate hijo exactamente igual que un componente, pasándole parameters. Para evitar un acoplamiento estrecho, los Aggregates hijos exponen un contrato exportedComponents:, que establece un nombre de interfaz pública estable. El padre llega a los componentes del módulo solo a través de esta interfaz: un destino uses: nombra el módulo y uno de sus alias exportados, y el compilador conecta la arista al componente interno que nombra el alias, mientras que un destino que entra en un módulo con cualquier otro nombre detiene la compilación, indicando el módulo y los alias que exporta. Un módulo puede, a su vez, reexportar el componente exportado de un módulo anidado bajo su propio nombre de interfaz — opcionalmente renombrándolo — y el compilador resuelve esa cadena de reexportación de forma transitiva hasta el nodo interno subyacente, de modo que los módulos se componen a cualquier profundidad sin que un padre necesite saber a qué profundidad está anidado el destino. Un destino que no se resuelve en ningún nodo interno sigue deteniendo la compilación de forma explícita, y una cadena de reexportación que se cierra sobre sí misma se rechaza en lugar de seguirse indefinidamente.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: my-catalog/child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db
  • Los Components no pueden contener subcomponentes: los Components son bloques de construcción atómicos. La composición ocurre a nivel de Aggregate mediante subsistemas y subagregados. Si una aplicación requiere varios contenedores físicos (como una API + un sidecar), ese anidamiento físico vive dentro de la plantilla de la Recipe de Ops, no en la definición del Component.

  • Un servicio coherente por Component — el límite de carga de trabajo única: un Component modela un servicio coherente — un único servicio expuesto, o la carga o cargas de trabajo de un servicio junto con sus cargas de trabajo auxiliares solo internas. Su etiqueta component.aggrega.ai/type nombra la forma operativa de ese único servicio. Varias cargas de trabajo físicas dentro de un solo Component están bien cuando forman un producto coherente sin piezas utilizables de forma independiente: un servicio cuyo chart ejecuta un controlador más un webhook más un inyector sigue siendo un solo Component. La prueba no es tener varias cargas de trabajo; es la utilidad independiente.

    El límite se traza donde un bundle contiene algo que otro componente podría usar (use) por sí solo con sentido — en especial infraestructura ajena como una base de datos, una caché o un broker de mensajes que Aggrega ya modela como su propio Component. Un bundle así no es un solo Component; es un módulo subagregado — el patrón spec.aggregates + exportedComponents mostrado arriba — que compone un Component por servicio, de modo que cada servicio sea un nodo direccionable con su propio tipo, sus propias aristas y su propia superficie de políticas y de escalado.

    La heurística, enunciada como una regla nítida: ¿Contiene el chart algo que otro componente podría usar por sí solo con sentido, o para lo que Aggrega ya tiene un Component? Si es así, modélalo como una pila — un módulo subagregado que compone Components por servicio. Si solo sirve a este único servicio, modélalo como un solo Component.

    Envolver todo un producto de varios servicios como un único Component opaco es un antipatrón documentado. El compilador funciona sin opiniones propias y lo aceptará — renderiza todo lo que supera la validación del esquema —, pero la biblioteca estándar compone en su lugar Components por servicio en un módulo, porque un envoltorio monolítico oculta los servicios modelables de forma independiente a la topología, al selector y a las políticas y el escalado por servicio. Esta disciplina de granularidad es un contrato social — consulta ../language-reference/vocabulary/social-contracts.md (granularidad del Component).

7. El ámbito predeterminado — divulgación progresiva de la agrupación

subsystems (en el Aggregate) y boundaries (en la Release) son las construcciones de agrupación, pero un desarrollador no tiene que declararlas de antemano. Cada entidad ofrece dos formas de escritura, y son mutuamente excluyentes: escribir los componentes agrupados bajo ámbitos con nombre, o escribir los componentes directamente en el nivel superior — nunca ambas a la vez. Un documento que declara tanto components de nivel superior como ámbitos con nombre se detiene al cargarse con un error de envoltorio.

Para la forma plana (components de nivel superior), el compilador sintetiza un ámbito default real al cargar e integra en él los componentes de nivel superior, de modo que cada pasada posterior ve una estructura uniforme con ámbitos. El ámbito sintetizado no es un contenedor oculto: es un nodo genuino de la IR, marcado con su procedencia, distinguible de un ámbito que un desarrollador llama explícitamente default. Solo se oculta donde el autor lee rutas — los diagnósticos y el direccionamiento muestran la ruta con forma de raíz .spec.components[…] que el desarrollador escribió realmente.

  • Aggregate plano (componentes de nivel superior): los componentes se escriben bajo spec.components, sin subsystems. El compilador los integra en un subsistema default sintetizado al cargar. Las anotaciones de ámbito de subsistema y las funcionalidades de nivel de subsistema se aplican solo a los subsistemas declarados; la forma plana no lleva ninguna.
  • Release plana (componentes de nivel superior): los componentes se escriben bajo spec.components, sin boundaries. El compilador los integra en un límite default sintetizado cuya salida es plana — los artefactos quedan directamente bajo dist/ (por proveedor: dist/compose/, dist/helm/, …), sin ningún segmento con el nombre del límite. Es el caso más sencillo: aggrega build sobre un destino Compose plano o de un solo clúster sin nombrar límites. (Un límite que un desarrollador declara y llama default es un límite con nombre corriente y, sin un directory: propio, emite a dist/boundaries/default/ como cualquier otro.)
  • La ruta de evolución: cuando una arquitectura plana crece hasta necesitar agrupación (espacios de nombres distintos, agrupaciones lógicas separadas, despliegue en varios límites), el desarrollador mueve los componentes de nivel superior a subsystems explícitos, u Ops introduce boundaries explícitos. Como las dos formas son mutuamente excluyentes, se trata de pasar de la forma plana a la forma con ámbitos — no de mezclar ambas — y la identidad de los nodos se conserva durante la transición.

El motivo es la divulgación progresiva: exigir una agrupación obligatoria para casos de uso triviales (una demo de un solo servicio, un prototipo local rápido) genera una fricción innecesaria. La prueba de incorporación «de cero a funcionando en 10 minutos» exige que un desarrollador pueda escribir un Aggregate mínimo con un componente, un Manifest y una Release y obtener una salida funcional sin entender antes los subsistemas ni los límites. El ámbito predeterminado es la vía de acceso; los ámbitos declarados son adonde va una arquitectura a medida que crece.

Las entradas siguientes son un patrón recomendado y cinco restricciones. Los esquemas imponen las restricciones 4 y 5 — la Release no tiene bloque values y la instancia de componente de un Aggregate no tiene clave labels; las demás son convenciones que el compilador no comprueba.

  • Patrón recomendado: elevación de parámetros mediante cadenas de plantilla

    • Ejemplo: el desarrollador escribe workers: {{ .parameters.env_workers }} en su bloque values, sin comillas, para que el valor llegue como el entero que se declaró.
    • Por qué: si el Aggregate declara env_workers como parámetro tipado (type: integer), el compilador valida primero el valor proporcionado por la Release frente al contrato. La validación del contrato de parámetros ocurre antes de la interpolación; la interpolación ocurre antes de la validación del esquema values: circundante. Esto preserva la reutilización del Aggregate: Ops proporciona el entero a través de los parameters: de la Release, el compilador lo valida frente a la declaración tipada parameters:, sustituye el valor resuelto en el documento, y la declaración schema: del Component valida correctamente el entero resultante.
  • Restricción 1: las credenciales son adjuntos, no valores

    • Patrón desaconsejado: el desarrollador escribe values: { password: "123" } en un componente.
    • Por qué: la convención de la biblioteca estándar es que una credencial se solicita como adjunto bajo features:, nombrando un type de Feature de credencial (uno etiquetado feature.aggrega.ai/kind: secret) y usando los propios values de ese adjunto para describir la consulta a un almacén de secretos. Es una convención, no una comprobación del compilador — el compilador no interpreta qué significa una hoja de values y transportará literalmente un literal en línea. La superficie de adjuntos es lo que hace disponible y tipada la forma bien escrita.
  • Restricción 2: Components agnósticos respecto a las capacidades

    • Patrón no admitido: el arquitecto escribe aws_instance_type: string en la declaración schema: del Component.
    • Por qué: por convención, los Components son agnósticos respecto a las capacidades. Los destinos de hardware físico residen en las Recipes de Ops o en anotaciones .context genéricas, no dentro de la lógica cognitiva central de la aplicación.
  • Restricción 3: lógica condicional sobre metadatos

    • Patrón no admitido: Ops escribe {{ if eq .context.labels.gpu "true" }} en una Recipe para cambiar de forma fundamental la estrategia de despliegue.
    • Por qué: el canal .context elude la validación schema: de cada pilar. Depender de etiquetas no validadas para la lógica central de infraestructura hace frágil la plataforma. El objeto .context transporta etiquetado de metadatos (p. ej., facturación, SOC2); el enrutamiento estructural corresponde a los pilares validados por esquema.
  • Restricción 4: la Release no puede sobrescribir los valores del desarrollador

    • Patrón no admitido: Ops intenta sobrescribir la lógica cognitiva de un desarrollador (p. ej., cambiar workers: 4 por workers: 10) desde la Release.
    • Por qué: el Aggregate es la fuente única de verdad de la intención del desarrollador. Si un valor está fijado en el código del Aggregate, es inmutable entre entornos. Si un valor debe cambiar según el entorno, el desarrollador usa la elevación de parámetros. El esquema de la Release lo impone prohibiendo los bloques values, lo que limita a Ops a cumplir el contrato parameters y a definir la infra física.
  • Restricción 5: etiquetas a nivel de instancia en el Aggregate

    • Patrón no admitido: el desarrollador escribe labels: {} en una instancia de componente dentro del Aggregate.
    • Por qué: las etiquetas son rasgos inmutables a nivel de catálogo escritos por el arquitecto de la plataforma — la identidad semántica que leen los motores de políticas y los selectores. La Release enruta los componentes a los límites mediante una selección explícita por ID basada en mapas (components: { "my-agent": {} }), lo que preserva la posibilidad de anidar infra y sobrescrituras de funcionalidades por componente sin mezclar la autoría de etiquetas en el Aggregate del desarrollador.

9. El perímetro de seguridad & las salvaguardas explícitas de egress (destinos fuera del perímetro)

Ninguna aplicación existe en el vacío. Una arquitectura Aggrega compilada representa un grafo mapeado de forma estricta. Sin embargo, los sistemas de IA modernos interactúan constantemente con entidades fuera de este perímetro compilado — como LLM SaaS públicos (Anthropic, OpenAI), API públicas genéricas (Stripe, Twilio) o bases de datos brownfield heredadas (Oracle local).

Para integrar estos sistemas externos de forma segura, Aggrega separa estrictamente el límite de seguridad de la mecánica de ejecución. El límite de seguridad se rige por la regla universal del Component y la salvaguarda explícita de egress.

1. La regla universal del Component

Si una aplicación interactúa con una entidad — ya sea una base de datos local, un recurso gestionado en la nube, un LLM SaaS o un endpoint de API pública genérica —, esa entidad DEBE declararse como un Component distinto en el Aggregate. Esta regla es una convención: el compilador no puede ver una llamada que hace la aplicación, así que nada la comprueba.

Al tratar las API SaaS externas y las bases de datos heredadas como nodos de primera clase en el grafo de la representación intermedia (IR), los desarrolladores pueden adjuntar configuraciones de proxy Zero-Trust directamente a la llamada saliente. Por ejemplo, al modelar la API de Stripe como un nodo distinto, un desarrollador puede adjuntarle una funcionalidad header-injector, garantizando que la configuración generada impida que el agente que llama guarde el token en bruto de la API en su propia memoria.

2. La salvaguarda explícita de egress (conformidad de la infraestructura)

En lugar de depender de lógica fija en el compilador para gobernar el egress de red, Aggrega delega por completo la seguridad del perímetro en los motores de políticas agnósticos de la empresa y en los plugins de renderizado Wasm. Así se garantiza que las configuraciones generadas se ajusten estrictamente a las aprobaciones explícitas de egress.

  • El enganche del catálogo (dominio 2): cuando un arquitecto define un componente SaaS público (p. ej., core/external-service), le adjunta una etiqueta corporativa inmutable (p. ej., security.enterprise.com/zone: "untrusted-external").
  • La salvaguarda de políticas (en tiempo de compilación): antes de generar cualquier configuración, el motor de políticas OPA o Kyverno evalúa el grafo. La empresa escribe una regla sencilla: «Si un nodo interno se conecta a un nodo etiquetado untrusted-external, el ID de ese nodo de destino debe figurar explícitamente en el array parameters.approved_egress del entorno». Si un desarrollador intenta enrutar datos a un destino externo no aprobado, el motor de políticas detiene la compilación.
  • La generación de la configuración (en tiempo de renderizado): si la política se cumple, la regla de egress se renderiza a partir de lo que el operador vinculó. La Feature core/egress-allowlist, vinculada al componente que llama en la Release, renderiza en helm una NetworkPolicy de Kubernetes por cada workload que ese componente renderiza, y admite egress solo hacia sus propios pods, hacia los pods de los destinos de sus aristas uses en los puertos que esos pods declaran, hacia el DNS del clúster y hacia los rangos de direcciones que la vinculación enumera para un destino que el clúster no ejecuta, como una API SaaS pública. La compilación se detiene a menos que la Release afirme, con infra.control_plane_present: true, que el plugin de red del clúster aplica las network policies, y se detiene nombrando cualquier conexión externa de ese tipo sin rango de direcciones enumerado; en compose, que no tiene network policy, la vinculación detiene la compilación. El desarrollador nunca escribe una regla de firewall.

Esto garantiza — mediante un rol de veredicto de gobernanza que evalúa la topología declarada — que la infraestructura declarada explícitamente cumple la política de egress sin que el compilador Go central necesite entender qué significa «externo». (Nota: un egress zero-trust real depende de que el clúster de destino ejecute una CNI Default Deny en tiempo de ejecución; las configuraciones generadas solo mapean las excepciones autorizadas).

Un Component por servicio externo

Cada servicio externo se declara como un componente distinto, no agrupado en un array de varios destinos. Si una aplicación llama a cinco API de terceros diferentes, el desarrollador declara cinco componentes core/external-service distintos. Esta declaración por servicio es lo que permite a los motores de políticas y a los plugins Wasm dirigirse a cada destino saliente de forma individual — adjuntando a cada dependencia externa políticas de egress diferentes, funcionalidades de proxy diferentes o enganches de observabilidad diferentes.

Desacoplar la seguridad de la ejecución (el escenario «brownfield»)

Es fundamental señalar que la etiqueta semántica (p. ej., untrusted-external) determina la política de seguridad de red, no la ejecución. Es independiente de que Aggrega renderice o no artefactos que aprovisionen el recurso.

  • Escenario A (API SaaS pública): etiquetada untrusted-external en el catálogo (activa las salvaguardas de egress de la política). Se realiza mediante un workload de referencia (sin cómputo aprovisionado; véase §10).
  • Escenario B (base de datos heredada interna): etiquetada internal-trusted (omite las salvaguardas de egress, permanece dentro de la VPC). Se realiza mediante un workload de referencia (sin cómputo aprovisionado; véase §10).
  • Escenario C (base de datos autoalojada): etiquetada internal-trusted. Se ejecuta mediante el plugin renderizador de Helm (aprovisionada físicamente como un StatefulSet de Kubernetes).

10. Servicios que la compilación no aprovisiona: Workloads de referencia

Cuando una aplicación interactúa con una base de datos heredada local o con una API SaaS pública (como Stripe), la regla universal del Component dicta que estas entidades externas deben declararse como componentes distintos en el Aggregate. Sin embargo, Aggrega no debe intentar generar para ellas un artefacto físico de Pod de Kubernetes ni de instancia de AWS RDS.

La Recipe que realiza un componente así declara un Workload de form: reference: un endpoint — un host o una URL —, opcionalmente un port, y ningún contenedor. El compilador canaliza ambos como cadenas de punteros deterministas y nunca los resuelve. Lo que un provider renderiza para un Workload de referencia es cosa del propio provider: helm emite un Service ExternalName que lleva el host del endpoint, para que los workloads del clúster puedan llegar a un servicio cuyo endpoint es un nombre DNS mediante un nombre estable dentro del clúster; compose no renderiza nada para él. Kubernetes trata un externalName como un nombre DNS, por lo que un endpoint escrito como dirección IP se alcanza en la dirección que recibe un consumidor y no a través del Service.

En ambos providers, los provides: de la Recipe llegan a cada consumidor a través de .context.uses y el contrato inject exactamente igual que los de un componente aprovisionado. Por tanto, la conexión de un consumidor no cambia cuando su destino pasa de aprovisionado a referenciado: solo cambia la Recipe a la que el Manifest asigna el destino.

La canalización de ejecución paso a paso

1. Dominio 1 (el Aggregate): la intención del desarrollador El desarrollador solicita una base de datos Oracle heredada. No le importa dónde reside; solo establece que su agente llamante espera recibir la cadena de conexión como variable de entorno. Como la IP es estática y se conoce de antemano, la pasa mediante parámetros.

components:
legacy-oracle:
type: core/legacy-database:1.0.0
values:
host: "{{ .parameters.legacy_oracle_ip }}"
sid: "PROD_DB"
my-agent:
type: core/python-worker:1.0.0
values: {}
uses:
databases:
legacy_db:
target: legacy-oracle
inject:
env:
- in: ORACLE_DSN # Local env var
from: "primary_endpoint" # Target provides key

2. Dominio 4 (el Manifest): el enrutamiento Ops asigna el tipo de base de datos heredada a la Recipe que formatea su cadena de conexión. El Manifest nombra una Recipe y nada más; la Recipe que nombra declara un Workload de form: reference, y esa forma es lo que impide que el nodo aprovisione cómputo. El enrutamiento sigue siendo perfectamente plano y predecible porque el mapa tiene exactamente una forma, sea cual sea el destino.

spec:
mappings:
components:
type:
"core/legacy-database": "oracle-dsn-formatter:1.0.0"

3. Dominio 3 (la Recipe de referencia): estructurar el traspaso El ingeniero de Ops escribe la Recipe. Esta construye la cadena de conexión primary_endpoint a partir de los values del desarrollador en su bloque locals, la publica bajo provides y declara un Workload de referencia que apunta al host de la base de datos.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
capability: helm
implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values
locals:
primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads
provides:
primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: reference
endpoint: "{{ .values.host }}"
port: 1521

4. Ejecución del compilador durante el renderizado (el traspaso)

  1. El compilador evalúa la Recipe de legacy-oracle. Para una Release que proporciona legacy_oracle_ip: "10.0.4.55", su primary_endpoint es oracle://10.0.4.55:1521/PROD_DB.
  2. En helm, el Workload de referencia renderiza un Service ExternalName, legacy-oracle, con externalName: 10.0.4.55 y el puerto 1521; en compose, no renderiza nada.
  3. A continuación, el compilador renderiza la Recipe de my-agent. Su canal .context.uses lleva los provides del nodo Oracle, y el contrato de inyección ya ha resuelto ORACLE_DSN a partir de ellos.

5. Dominio 3 (la Recipe llamante): cumplir el contrato La receta Helm estándar del worker de Python lee el mapa de inyección que recibió, exactamente igual que lo haría para una base de datos que la compilación aprovisiona.

# Inside python-worker-helm (The calling agent's recipe)
env:
# The compiler pre-resolved the target's provides into the inject map
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }} # Renders: ORACLE_DSN
value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB
{{- end }}

11. Canalización entre pilares mediante schema-bridge: puente entre la intención y la infraestructura

Consulta inheritance-and-interface para conocer el patrón schema-bridge, que expone de forma segura controles de infraestructura especializados a través de componentes hijos — un campo values: orientado al desarrollador, declarado en el schema: del Component, que la plantilla valuesMapping: de la Recipe canaliza hacia la salida renderizada con forma de infra:.

12. Aprovisionamiento greenfield («Aggregates de plataforma»)

Una trampa recurrente en la ingeniería de plataformas es obligar al enrutador (el archivo Release) a encargarse del pesado aprovisionamiento de clústeres del día 0 (p. ej., levantar un nuevo clúster de AWS EKS antes de desplegar la aplicación en él). Esto crea archivos de enrutamiento largos y difíciles de leer.

Aggrega lo aborda con el principio «tortugas hasta el fondo». El esquema de la Release no tiene ningún bloque para instalar infraestructura; el aprovisionamiento de clústeres se modela con Aggregates de plataforma.

Como un clúster de AWS EKS, un plano de control de Istio y una VPC de AWS son, en última instancia, solo recursos físicos en la nube, se modelan exactamente igual que los componentes de aplicación.

  1. El Aggregate de plataforma: el equipo de infraestructura escribe un Aggregate.yaml estándar cuyos componentes son core/aws-vpc, core/eks-cluster y core/istio-base.
  2. La Release de plataforma: el equipo despliega este agregado. El renderizador vinculado a estos componentes de plataforma genera los artefactos necesarios para levantar la infraestructura base.
  3. La Release de aplicación: cuando el desarrollador de la aplicación está listo para desplegar su agente de IA, el equipo de Ops simplemente apunta al clúster recién creado con un límite en el propio archivo Release de la aplicación.