Invariantes arquitectónicas
Estos ocho invariantes son las reglas fundacionales de Aggrega. Se mantienen en todas las versiones, en el núcleo del compilador, la capa de esquemas, el catálogo y la superficie de plugins Wasm. Cada decisión de diseño, cada funcionalidad y cada entidad escrita los respeta.
Los demás capítulos de arquitectura hacen referencia a las invariantes por su número. Cuando un capítulo posterior dice «según la invariante 2» o «por la regla del String Pipe (invariante 3)», remite aquí.
1. El compilador es neutral respecto al contenido, sin opiniones propias y agnóstico respecto a la intención del usuario
El compilador de Aggrega es un enrutador de texto Ahead-Of-Time (AOT). Analiza YAML, recorre grafos, evalúa intersecciones de etiquetas y canaliza cadenas desde los orígenes hasta los destinos. No vigila lo que los autores ponen en values, parameters, infra, provides o locals. No impone convenciones de nombres, convenciones de puertos ni las etiquetas semánticas que inventa un Architect.
Muchas reglas que parecen reglas del compilador — el contrato Zero-Port, el estilo de catálogo Naked-Base / Flavored-Edges, la elección de qué primitiva operativa conviene a un componente dado — son contratos sociales: buenas prácticas con vías de escape, sostenidas por los arquitectos de plataforma que escriben el catálogo de la biblioteca estándar. El compilador no las interpreta.
Esta invariante trata de lo que el compilador infiere del contenido que escribes, y ese alcance es todo lo que abarca. Un puñado de claves son propias de Aggrega — reservadas, con los valores que aceptan escritos en el esquema publicado — y el esquema las comprueba como comprueba cualquier otro campo declarado. component.aggrega.ai/type es una de ellas: su conjunto de valores es cerrado, y un documento que lleve un valor fuera de él se rechaza al cargarse. Es la plataforma que declara lo que significa su propia clave, no el compilador que lee un significado en una cadena que escribiste, y deja cada una de tus claves exactamente tan sin vigilancia como dice esta invariante. Un catálogo que clasifica componentes según un eje que Aggrega no define escribe su propia clave de etiqueta, que el esquema acepta con cualquier valor de cadena y que todas las superficies de selección leen de forma idéntica.
Lo que el compilador sí impone es acotado: la validación de esquemas, el análisis de YAML, la construcción del grafo, la evaluación de plantillas y el simple enrutamiento de texto del contrato de inyección. Todo lo demás es convención, impuesta al escribir el catálogo o dentro del socket de gobernanza Wasm opcional.
Las empresas que escriben sus propios catálogos internos son explícitamente libres de romper las convenciones de la biblioteca estándar. El compilador acepta lo que escriban siempre que supere la validación de esquemas. La arquitectura promueve buenas prácticas; no construye prisiones.
2. Pureza AOT: el compilador no tiene acceso a información de tiempo de ejecución
Aggrega es un compilador Ahead-Of-Time. En tiempo de compilación:
- No se autentica con las API de la nube.
- No obtiene direcciones IP activas, nombres DNS ni URL generadas por la nube.
- No resuelve los secretos en texto plano: los secretos siguen siendo punteros de metadatos en toda la representación intermedia (Intermediate Representation).
- No conoce el estado de ejecución de los clústeres o servicios de destino.
- No puede obtener datos que aún no existen (endpoints posteriores al aprovisionamiento, puertos asignados dinámicamente, nombres de recursos generados automáticamente).
Todo lo que depende del estado de ejecución se expresa como una cadena puntero determinista — un nombre DNS estable, una cadena de interpolación de Terraform, una referencia a un recurso de CloudFormation — que proporciona la Ops Recipe. El compilador canaliza el puntero sin resolverlo. El entorno de ejecución (el clúster, el gestor de estado de IaC) resuelve los datos físicos finales.
Esta es la verdadera inversión de control (True Control Inversion): los desarrolladores dictan un Injection Contract en el Aggregate, el compilador conecta punteros deterministas de antemano y el entorno de ejecución resuelve los datos físicos finales. Los requisitos que realmente necesitan resolución en tiempo de ejecución pertenecen al pipeline Wasm de una Ops Recipe, no al núcleo del compilador.
3. El String Pipe: el compilador no puede inferir el significado
El compilador no interpreta qué significan los valores que canaliza. Cuando el Component A usa el Component B, el compilador toma el escalar que la Recipe del Component B produce mediante provides — una cadena, un número o un booleano — y lo canaliza al contexto de la Recipe del Component A, convertido en cadena de forma determinista en el límite de inyección. Que ese valor sea un FQDN, un nombre de host local, una IP literal, un número de puerto o un DSN con formato de Wasm no supone ninguna diferencia: el compilador no valida la enrutabilidad, la corrección del protocolo ni la adecuación semántica.
De ello se derivan dos consecuencias:
- El compilador no adivina el propósito de un componente por su nombre. Un componente llamado
database-productionno se reconoce como una base de datos. Las etiquetas de tipo semántico comocomponent.aggrega.ai/type(cuando están presentes) son metadatos opacos que se usan para la coincidencia de etiquetas, no lógica de ramificación del compilador. - El compilador no distingue un nombre de host de un nombre de base de datos, de un número de puerto o de un valor opaco arbitrario. Todos son entradas escalares del contexto de inyección, entregadas como cadenas.
La tríada de la topología — provides en la Recipe productora, uses en el Aggregate consumidor, inject en la arista — es el Injection Contract. El compilador evalúa etiquetas y pasa cadenas; la interpretación es el contrato de autoría entre Recipe y Component.
4. Sin infraestructura fantasma: el compilador nunca inventa cómputo ni funcionalidades
El compilador nunca inyecta en silencio cómputo, Features, anotaciones, proxies de enrutamiento ni ningún otro recurso que el autor no haya declarado explícitamente. Las infracciones de políticas producen barreras de protección ruidosas (Loud Guardrails) — la compilación se detiene con un error específico que indica al autor qué corregir, en el documento que escribió — y no mutaciones silenciosas que generan misterios de infraestructura en el momento de depurar.
Los recursos entran en el grafo mediante declaraciones explícitas en tiempo de autoría:
- El Aggregate del desarrollador (componentes, aristas
uses, vinculaciones de Feature). - Las vinculaciones de Feature de la Release (añadidos a nivel de operador).
- La expansión impulsada por anotaciones (el Manifest declara vinculaciones anotación → Feature; la anotación en un Component o en un límite es una declaración explícita).
- La producción de recursos a nivel de Recipe: el renderizado de
sourcede la Recipe produce el artefacto principal; la síntesis deworkloademite la forma de despliegue específica del proveedor (especificación de Pod, servicio de Compose, etc.); las entradas deartifacts:(en línea o cargadas con$import:) emiten manifiestos auxiliares intrínsecos a la Recipe; la generación de recursos de las FeatureRecipe emite recursos auxiliares por cada Feature, activados por una vinculación explícita de Feature.
Las rutas a nivel de Recipe son declaraciones en tiempo de autoría a un paso de distancia: el autor de la Recipe escribe source / workload / artifacts / valuesMapping contra un contrato de Component, y el Aggregate del desarrollador selecciona qué Components participan. Un recurso que aparece en la salida renderizada se remonta a una declaración en el Aggregate, la Release o una vinculación de anotación, o bien a la autoría de la Recipe que seleccionaron los tipos de componente del Aggregate.
La síntesis transforma las formas declaradas por el autor en formatos de salida específicos del proveedor. Una especificación de Workload escrita como un mapa de contenedores puede renderizarse como una especificación de Pod de Kubernetes, un bloque de servicio de Compose o un módulo de Terraform: la transformación la impulsa el proveedor, pero los recursos se remontan a la declaración de Workload del autor.
El socket de gobernanza lleva un rol por vinculación, y es el rol — no el tipo del plugin — lo que fija qué puede hacer una vinculación con una compilación. Un plugin de gobernanza vinculado en un rol de veredicto — que revisa el grafo IR (ir-verdict) o los artefactos renderizados (render-verdict) — puede rechazar una compilación, pero no puede cambiarla. Si ese veredicto quiere que se añada un recurso, hace fallar la compilación con una indicación de corrección para que el autor añada el recurso por sí mismo; el host lee la salida de un veredicto solo como aceptación o rechazo y nunca la aplica como cambio, de modo que una reescritura no solicitada del grafo para hacerlo conforme — exactamente la infraestructura fantasma que esta invariante prohíbe — no puede provenir de un rol de veredicto. Un plugin de gobernanza vinculado en un rol de transformación (label-transform o annotation-transform) es la excepción limitada y explícita: un operador que vincula uno — de forma opcional, mediante la configuración plugins.governance del espacio de trabajo — ha declarado esa transformación, por lo que los cambios que realiza son una declaración explícita, con la misma categoría que la expansión impulsada por anotaciones, no una inyección silenciosa. La diferencia es la invitación: un veredicto no solicitado no puede reescribir la compilación, mientras que una transformación vinculada explícitamente sí puede, porque el operador la pidió. Como una transformación da forma a la salida renderizada, queda fijada en el lockfile como todo plugin que da forma a la salida: la transformación que se aplica se fija en el momento del pull, de modo que cambiarla implica volver a hacer pull en lugar de un desplazamiento silencioso entre compilaciones; un veredicto no da forma a ninguna salida y no se fija.
5. El Aggregate es la superficie de autoría; la Release no puede declarar values:
El esquema de la Release prohíbe mecánicamente un bloque values:. Los operadores no pueden escribir values en un Component o en una Feature desde una Release. Se trata de una imposición del esquema a nivel de JSON Schema — no un contrato social ni una convención — y es ruidosa: cada documento de entidad se valida contra el esquema de su tipo al cargarse, de modo que una Release que lleve values: detiene la compilación con un diagnóstico que nombra el archivo y la clave infractora, en lugar de ignorarse en silencio.
Esto no significa que los valores sean idénticos en todos los entornos. La vía admitida para la variación por entorno es la elevación de parámetros (Parameter Hoisting):
- El desarrollador expone un campo tipado
parameters.*en el Aggregate. - La plantilla
valuesdel Component lo referencia:storage_size: "{{ .parameters.db_size }}". - La Release satisface el parámetro:
parameters: { db_size: "100Gi" }. - La salida renderizada refleja el valor específico del entorno.
El Aggregate sigue siendo la única fuente de verdad sobre qué valores se exponen para la variación por entorno (la declaración parameters) y cómo fluyen hacia los valores del componente (la referencia de la plantilla). La Release satisface; no sobrescribe.
Otras dos restricciones protegen la misma invariante:
- Cuando una Release usa
extends, declarar un punteroaggregate:está prohibido por el esquema. La Release hija debe desplegar la misma intención del desarrollador (Developer Intent) que su Release padre. - La Release no puede introducir cómputo que el Aggregate no declaró ni redirigir una arista que el desarrollador declaró. Dentro de los sockets que declaró el Architect, la Release puede conectar y configurar aristas entre componentes existentes: establece el
infrapor arista en una arista que conectó el desarrollador, o conecta con un componente existente una arista hacia un socket declarado pero no vinculado. No puede declararvaluespor arista (esos permanecen en el Aggregate), vincular un socket que elusesSchemadel Component no declara ni apuntar una arista a un componente que no existe: cada uno de estos casos detiene la compilación. Observa qué declaración significa esa cláusula intermedia: el socket debe aparecer en elusesSchemadel Component del catálogo. El autor de un Aggregate puede nombrar un socket que su tipo de componente no declara, y la superficie de la Release deliberadamente no se abre de la misma manera: un operador conecta y configura dentro de una arquitectura en lugar de inventar una.
La configuración de conexión por arista tiene como ámbito el consumidor: los values y el infra que lleva una arista solo aparecen en el contexto de renderizado del nodo que escribió la arista, nunca en el contexto del destino. Por tanto, la salida renderizada de un componente es invariante respecto de las conexiones que otros componentes hacen hacia él: conectar o configurar una arista hacia un destino nunca altera lo que renderiza la Recipe del destino. El único lugar donde esas conexiones son visibles es una Feature vinculada al destino: su FeatureRecipe puede leer qué componentes usan el destino, de modo que los recursos que emite — por ejemplo, una política que admite exactamente a los llamadores declarados — siguen la conexión, mientras que la salida propia del destino no lo hace. Incluso allí, los values y el infra por arista permanecen con el consumidor.
6. El límite ABI de WebAssembly: la inteligencia específica del dominio vive en Wasm
El binario host de Go no contiene ninguna lógica específica de la nube ni de la infraestructura. Toda la inteligencia específica del dominio, el renderizado de plantillas y el formateo viven estrictamente dentro de plugins WebAssembly ejecutados por el runtime Wazero integrado. El host de Go orquesta el pipeline y pasa las cargas útiles a través de la ABI a los invitados Wasm como punteros de memoria, en la codificación que lleva cada socket.
De ello se derivan dos corolarios:
- La lógica específica del Provider (renderizado específico de Helm, formateo específico de Terraform, fusión específica de Compose) nunca vive en el núcleo del compilador de Go. El compilador resuelve el nombre del proveedor que una Recipe declara en
spec.capabilityal Plugin de renderizado del proveedor que lo atiende y despacha el nodo a ese plugin; la traducción en sí se ejecuta íntegramente en el invitado Wasm. El host no contiene código Go por proveedor para un proveedor estándar, así que no hay nada en el proceso a lo que recurrir: un nombre de proveedor que no se resuelve en ningún Plugin que lo atienda detiene la compilación en lugar de renderizar algún valor predeterminado integrado. - La lógica de políticas (reglas de seguridad, comprobaciones de cumplimiento, cálculos de FinOps) nunca vive en el núcleo del compilador de Go. Las políticas pertenecen al socket de gobernanza Wasm que las empresas activan de forma opcional: un plugin vinculado en un rol de veredicto (
ir-verdict/render-verdict) para aceptar o rechazar una compilación, o en un rol de transformación (label-transform/annotation-transform) para dar forma a las etiquetas o las anotaciones.
El límite ABI mantiene el núcleo de Go compacto, auditable e independiente de la nube. Cambiar la lógica de renderizado de un proveedor es cambiar un artefacto Wasm, no recompilar el propio Aggrega.
7. Separación de responsabilidades (división en cuatro dominios): una guía, no una prisión
Las pautas de diseño de Aggrega separan la autoría en cuatro dominios:
- Developer Intent — Aggregate.
- Platform Architect — entidades de catálogo Component y Feature.
- Platform Ops — Recipe, FeatureRecipe, Plugin (incluido el Plugin de renderizado del proveedor).
- Platform Operator — Manifest, Release.
El despliegue típico que funciona bien sigue esta división: los desarrolladores escriben la intención de la aplicación, no la infraestructura física; los equipos de Ops escriben la infraestructura física, no la lógica de la aplicación. Aggrega está diseñado para usarse así, y la documentación oficial, los ejemplos y el catálogo de la biblioteca estándar están escritos conforme a esta división.
La división en cuatro dominios es una guía y un marco de diseño, no una imposición del compilador. El compilador (según la invariante 1) es sin opiniones propias. Los usuarios son libres de:
- Fusionar roles (una sola persona que escribe tanto Aggregates como Recipes).
- Mezclar responsabilidades (Architects que codifican etiquetas de cumplimiento directamente en Components
core/*cuando los catálogos empresariales lo exigen). - Cruzar los límites entre dominios (desarrolladores que usan la elevación de parámetros para inyectar aspectos de infraestructura en el Aggregate cuando el código heredado lo exige).
El compilador acepta cualquier patrón de autoría que supere la validación de esquemas. La arquitectura promueve buenas prácticas; las restricciones a nivel de esquema (como la prohibición de values: en la Release de la invariante 5) son los únicos cruces de dominio que el compilador realmente rechaza. Toda otra separación es un contrato social que sostienen los autores de catálogos y, donde las empresas lo activan, el socket de gobernanza Wasm.
8. Salida determinista
Ante una entrada idéntica, el compilador produce una salida idéntica byte a byte. Dos compilaciones del mismo Aggregate + Release + Manifest contra el mismo catálogo producen artefactos renderizados que coinciden byte a byte.
Este es el contrato del que dependen las herramientas de GitOps y los flujos de revisión basados en diffs. Una pull request que no cambió la entrada no debería producir ningún diff en la salida renderizada. Una pull request que sí cambió la entrada solo debería mostrar el diff que implica ese cambio: sin reordenaciones espurias, sin variaciones de marcas de tiempo, sin artefactos de iteración de mapas.
La salida determinista se mantiene mediante tres disciplinas:
- Mapas ordenados por el autor: cada mapa cuyo orden de iteración podría afectar a la salida renderizada usa un contenedor de mapa ordenado, de modo que la iteración sigue el orden de declaración del autor en lugar del orden del hash.
- Ningún contenido de reloj ni aleatorio en los artefactos renderizados, salvo que el autor lo haya inyectado explícitamente mediante la entrada de la plantilla.
- El renderizado es puro: la misma invocación de un invitado Wasm con la misma entrada produce la misma salida.
La opción --trace del compilador (consulta language-reference/cli/aggrega-build.md) ofrece a autores y operadores una superficie de verificación para esta invariante. Dos compilaciones de la misma entrada con --trace activado producen volcados de traza idénticos byte a byte; cualquier diff en una pasada localiza una regresión. El determinismo no es solo una propiedad del momento de la publicación: es observable en cada estado intermedio del compilador mediante la disposición de trazas por nodo.
La salida determinista es el contrato que hace que Aggrega sea seguro de usar como fuente de verdad en un ciclo de GitOps.
Alcance de la invariancia en los niveles de resolución
La garantía de salida idéntica byte a byte abarca los artefactos fijados en el lockfile: entidades resueltas mediante artefactos de registro cuyos digests registra el lockfile (el nivel de registro del modelo de resolución de entidades en tres niveles). Cuando una compilación lee los archivos que una Release nombra por ruta (rutas locales que empiezan por ./ o ../) o entidades en directorios de catálogo del espacio de trabajo (catalog_dirs:, en el nivel de espacio de trabajo y caché), la invariancia depende de que esos archivos no cambien entre compilaciones. El lockfile registra una entidad de un directorio de catálogo del espacio de trabajo mediante el digest de su documento y de los archivos que declara, de modo que una compilación se detiene ante una entidad que cambió desde el pull en lugar de renderizarla, con una excepción: una Recipe o FeatureRecipe que el Manifest nombra mediante una referencia que también es el nombre de un Component o de una Feature se registra bajo esa referencia como el Component o la Feature, por lo que sus entradas solo quedan fijadas por los pines del lock que la acompañan, y una edición de su propio documento no se detecta. Mantener los archivos como estaban es responsabilidad del sistema de control de versiones (normalmente Git).
Una referencia a una ruta local cuyo archivo subyacente cambia entre dos compilaciones produce un diff legítimo en la salida renderizada aunque la forma de la entrada del compilador no haya cambiado: la garantía de salida determinista se mantiene (misma entrada en bytes → misma salida en bytes), pero las entradas difieren porque el archivo local cambió. Los catálogos que necesitan invariancia entre compilaciones para cada origen traen los artefactos desde un registro a la caché fijada por el lockfile en lugar de leerlos desde una ruta local o un directorio del espacio de trabajo; el lockfile es el ancla de la identidad byte a byte.