Pipeline de compilación (visión general)
Este capítulo detalla la física interna del compilador Go y define cómo se traduce el YAML abstracto en configuraciones físicas a lo largo del pipeline de compilación, el grafo de representación intermedia (IR) y los sockets de ejecución de WebAssembly (Wasm).
El pipeline de compilación y el flujo de ejecución
Aggrega ejecuta un pipeline de compilador anticipado (AOT, Ahead-of-Time) estricto y de orden fijo en lugar de una lógica de orquestación codificada de forma fija. Activado por aggrega build, el compilador pasa el grafo plano entre sockets aislados de WebAssembly (Wasm) para evaluar la arquitectura antes de renderizar los artefactos físicos.
Los sockets Wasm se ejecutan en un host embebido — el kit de herramientas Extism sobre el motor Wazero — detrás de un cortafuegos de pureza AOT que niega a un plugin cualquier capacidad de acceso en tiempo de ejecución (red, sistema de archivos, reloj de pared, entorno, E/S estándar), de modo que un plugin no puede romper la garantía determinista y anticipada. El host ejecuta el linter de publicación fuera de banda, mediante aggrega lint. Las compuertas en banda descritas a continuación — el rol de transformación de etiquetas del socket de gobernanza durante la construcción de la topología y su rol de veredicto sobre el IR durante el análisis estático, además del pipeline de plugins que cierra el renderizado — se ejecutan en cada build: un rol de gobernanza dondequiera que el espacio de trabajo le adjunte un plugin, y el pipeline de plugins para cada Recipe que declara pasos. Estado del lenguaje registra el estado de cada fase del pipeline.
El pipeline se ejecuta íntegramente en memoria en un orden estricto y fijo:
Resolución — El resolvedor y validador de sintaxis
- Mecanismo: fusión por herencia, interpolación de plantillas Go y validación con JSON Schema 2020-12.
- Acción: La CLI obtiene todas las entidades solicitadas (Components, Features, Releases). Primero comprueba en estas definiciones la palabra clave
extends. Para las entidades del catálogo, fusiona en profundidad los metadatos YAML, y los dos tipos se separan en los pilares de datos: elschema:de una Feature se compone con el de su base según la composición de JSON Schema 2020-12, mientras que un Component que extiende compone solo la estructura — sus ranuras de adjunto, sus sockets de topología, su lista de autoinyección permitida y sus aserciones con nombre — y recibe el bloqueschema:de su base exactamente como la base lo escribió. UnaReleaseque extiende se pliega con la misma regla: el valor del hijo gana clave por clave, hasta el primer valor indivisible — un escalar, una lista, una plantilla —, que se reemplaza entero, y una clave que el hijo escribe comonullse elimina. Así viaja toda su superficie de autoría — el árbol de fronteras con suinfrapor componente y sus adjuntos de Feature, el bloqueparameters, las anotaciones y el puntero al Manifest —, mientras que ningún campometadatalo hace, ya que la identidad y la procedencia son propias de cada Release. A continuación, realiza una interpolación en memoria en tres subpasos: validación del contrato de parámetros frente a las declaraciones tipadasparameters:del Aggregate; interpolación de los valores resueltos en las cadenasvalues:circundantes; retirada del mapa.parametersde todo contexto de plantilla de valores, dejándolo legible solo para las plantillas de ruta escritas por el operador. Por último, inyecta los bloquesinfraresueltos en las cargas útiles de los componentes de destino. Una vez que el plano es completamente concreto, el compilador usa la declaración unificadaschema:del catálogo (forma compacta o JSON Schema 2020-12 completo) para validar estrictamente, de forma local, las configuracionesvalueseinfradel desarrollador.- Validación de esquemas de las Features de la Release: Las Features adjuntadas mediante la Release (tanto las de toda la frontera como las específicas de un componente) se resuelven frente a sus entidades del catálogo durante este paso. El compilador valida los bloques
infraproporcionados por la Release frente a la declaraciónschema:de cada Feature inmediatamente después de la resolución del catálogo, lo que garantiza la seguridad de tipos antes de construir la topología. - Subfase de expansión de Feature dirigida por anotaciones: Tras la resolución del Manifest, la vinculación de Recipe/Provider y la validación de los destinos de vinculación del Manifest (que las rutas declaradas bajo
mappings.features.annotations.<key>.mapsexistan en elspec.schemade la Feature referenciada), el compilador ejecuta una subfase de expansión de anotaciones antes del constructor de la topología. La subfase recorre las fronteras de la Release de fuera hacia dentro y los subsistemas del Aggregate de fuera hacia dentro, calculando el conjunto efectivo de anotaciones por componente mediante una fusión de cascada + sobrescritura + exclusión por null; analiza cada valor de anotación como YAML en un escalar, un valor estructurado o null; encamina cada valor (escalar, o estructurado por subclave) a través de la declaraciónmapsde la vinculación del Manifest hasta el pilar de esquema de la Feature de destino, imponiendo la correspondencia entre lado y pilar (el lado del Aggregate activamaps.values; el lado de la Release activamaps.infra); valida los tipos de cada hoja frente alspec.schemade la Feature; e inyecta adjuntos de Feature sintéticos, que el grafo IR marca conorigin: annotation. Los esquemas se compilan una vez por compilación y se reutilizan entre recorridos de cascada. La expansión se ejecuta tras la validación de los destinos de vinculación y antes de la construcción de la topología, de modo que las etapas posteriores tratan los adjuntos sintéticos de forma estructuralmente idéntica a los explícitos (salvo mediante la inspección de la procedencia). Consulta 13-catalog-and-registry.md §«Expansión de Feature dirigida por anotaciones» ylanguage-reference/providers/well-known-annotations.mdpara la forma de la vinculación, la semántica de la cascada y las reglas de composición entre lados.
- Validación de esquemas de las Features de la Release: Las Features adjuntadas mediante la Release (tanto las de toda la frontera como las específicas de un componente) se resuelven frente a sus entidades del catálogo durante este paso. El compilador valida los bloques
Construcción de la topología — El constructor de la topología y la compuerta de mutación
- Mecanismo: expansión del AST + el rol
label-transformdel socket de gobernanza. - Acción: El compilador lee de forma nativa los bloques
usesdeclarados explícitamente en los componentes validados para trazar de forma determinista las aristas topológicas entre los nodos del grafo, dejando el bloquevaluescompletamente opaco. A continuación evalúa la compuerta de mutación, pasando una proyección del grafo —las etiquetas de cada nodo y losvaluesque declara su instancia, que el compilador entrega sin leerlos— junto con el nombre y el entorno de la Release a un plugin de gobernanza adjuntado en el rollabel-transform. El plugin evalúa el contexto y devuelve JSONPatches para etiquetar automáticamente el grafo de forma dinámica (p. ej., inyectando la etiquetacompliance.aggrega.ai/data-class: restricteden función del entorno de la Release, odatastore.aggrega.ai/engine: vectoren función de las extensiones declaradas de una base de datos); los parches solo alcanzan las etiquetas.
Finalización del grafo
- Mecanismo: normalización.
- Acción: El compilador finaliza el grafo plano de representación intermedia (IR), conservando las aristas topológicas explícitas que trazó el constructor de la topología. Después normaliza las Features adjuntadas y sus cargas útiles
valuesen un diccionario plano indexado por ID de nodo, preparando para la validación el grafo agnóstico respecto a las capacidades.- Normalización de la carga útil del IR: La forma estructural del IR impone una única fuente de verdad para la configuración: la capa de topología solo lleva la estructura del grafo (identidad de los nodos, aristas, etiquetas de metadatos), y el estado normalizado de la configuración reside en un diccionario en memoria separado que el compilador pasa a los plugins posteriores. Los mutadores que cambian la configuración la cambian en un solo lugar; el proveedor lee el estado normalizado sin riesgo de divergencia por almacenamiento redundante.
Análisis estático — El analizador estático y la compuerta de validación
- Mecanismo: comprobaciones de pureza topológica + el rol
ir-verdictdel socket de gobernanza. - Acción: El compilador ejecuta un análisis estático abstracto sobre el grafo IR. Primero, extrae las cadenas
selectorde las definicionesusesSchemay las evalúa con un motor nativo de coincidencia de etiquetas en Go (que admite la semántica de estilo Kubernetes deAND,ORmediantein()yNOTmediante!=) sobre las aristas del grafo definidas explícitamente, para garantizar la seguridad de tipos entre nodos en los sockets declarados. Una arista en un socket ad hoc — uno que nombró el autor de un Aggregate y que el catálogo no declaró — no tiene entrada de catálogo y, por tanto, tampoco selector, así que no hay nada que esta comprobación deba evaluar ni nada que falte; cada arista registra cuál de los dos casos es, y lo que puede transportar una arista ad hoc queda acotado, en cambio, por losprovidesdeclarados del destino. También evalúa los selectoresappliesToyappliesToAnyOfde las Features para verificar que las funcionalidades adjuntadas sean compatibles con las etiquetas de su componente de destino, y el propioselectorde cada ranura de adjunto ocupada frente a las etiquetas de la Feature que la ocupa. Segundo, evalúa cada mandato de presencia que declara el Component de un nodo — cada anotaciónfeatures.aggrega.ai/requiredType.<label>— frente al conjunto final de adjuntos de ese nodo. El analizador es donde corresponde esta comprobación porque es la primera etapa que dispone de las dos mitades de la regla: las anotaciones de la entidad Component resuelta y el conjunto de adjuntos que produjo la cascada de 5 niveles, contando por igual los adjuntos del Aggregate, de los subsistemas, de la Release y los expandidos por anotaciones. Un mandato que ningún adjunto satisface detiene la compilación; un mandato cuya declaración está mal formada la detiene con un diagnóstico distinto, de modo que una declaración rota nunca se lee como un requisito satisfecho. Tercero, ejecuta la compuerta de validación, pasando la estructura completa del grafo (incluidos todos los nodos, las aristas, las funcionalidades adjuntadas y las rutas DFS precalculadas) a un plugin de gobernanza adjuntado en el rolir-verdict. La política Wasm personalizada de la empresa evalúa la topología. Si el plugin Wasm devuelve un array de fallos (p. ej., al detectar una ruta continua desde un nodopublichasta un nodorestrictedsin una funcionalidad de proxy específica), la compilación se detiene.
Renderizado
- Mecanismo: interceptación previa al renderizado (
injectMapping), vinculación tardía (valuesMapping) y sockets de renderizado Wasm (pipeline). - Acción: La fase final de generación de artefactos se divide en subfases temporales estrictas que se ejecutan en un orden fijo, lo que mantiene determinista la ejecución:
- Mapeo de inyección (interceptación previa al renderizado): El compilador Go resuelve el contrato abstracto
.context.injectdel desarrollador. A continuación ejecuta las plantillas GoinjectMappingde todas lasFeatureRecipesadjuntadas siguiendo el estricto orden de ejecución del modelo de cebolla de 5 niveles (Sub-Aggregate — los adjuntos propios de un componente de módulo, luego los que declaran los subsistemas de su módulo, de fuera hacia dentro → componente del Aggregate raíz → subsistema del Aggregate raíz → frontera de la Release de fuera hacia dentro → específico de componente de la Release). El compilador fusiona en profundidad de forma nativa los diccionarios resultantes sobre la tubería de memoria.context.injectdel llamador. Esto reescribe de forma segura las variables de entorno y las cadenas de conexión del llamador antes de que la Recipe base las vea. Un mapeo puede reescribir lo que entregó el propio bloqueinject:del llamador o una de sus conexiones; una clave que otra Feature adjuntada ya entregó — mediante su propio mapeo o su propio bloqueinject:— detiene la compilación nombrando ambos adjuntos, de modo que el orden de ejecución nunca decide entre los valores de dos adjuntos. - Preámbulo de locals: Antes de que se ejecute cualquier plantilla
provides, el compilador evalúa las entradas.localsde la Recipe en el orden en que están escritas, cada una frente a un contexto autocontenido local al nodo —.context.instance_id,.values,.infray las entradas del mismo bloque resueltas hasta ese momento, pero no.context.injectni.context.uses. Por tanto, una entrada puede leer una hermana definida por encima de ella y recibe el valor resuelto de esa hermana; el orden de autoría forma parte del contrato siempre que una entrada lea otra, y el bloque nunca se reordena para que una referencia se resuelva. Resolver primero los locals es lo que permite que una plantillaprovideslea.locals. La plantilla.sourcede la Recipe se evalúa frente al mismo contexto una vez resueltos esos locals, lo que mantiene.localsreutilizable como abreviatura en todas las plantillas de una Recipe y permite a los autores parametrizar.source(versión del chart, ruta, registro) por frontera. - Renderizado base (
valuesMappingde la Recipe base): El compilador evalúa la plantillavaluesMappingde la Recipe base. La plantilla lee las cadenas interceptadas de la tubería.context.inject(reescritas durante el mapeo de inyección), y el diccionario de valores resultante se entrega al proveedor que nombra lacapabilityde la Recipe — los proveedores helm y helm-chart renderizan ambos a través de Helm — para renderizar los artefactos de infraestructura base. - Análisis y validación del Workload: Una Recipe que declara
workload:— contenido de bloque en línea, oworkload: { $import: <path> }que nombra un archivo — hace que ese documento se evalúe como plantilla frente al contexto de renderizado del nodo y después se analice como YAML en la forma de Workload y se compruebe: los bytes renderizados se validan frente al esquema de Workload, el valor decodificado también se valida frente a él (los bytes llevan claves que la decodificación descarta, y la decodificación omite un campo suministrado vacío, así que cada uno rechaza lo que el otro no puede ver), cada entrada deattachmentsse comprueba frente a las ranuras que declara elfeaturesSchemadel Component vinculado, y cada referencia a un recurso se comprueba frente a losprovidesresueltos de la ranura que nombra. Un fallo aquí detiene la compilación. El Workload analizado se coloca en el contexto de plantilla como.workload, de modo que una plantilla evaluada más tarde en el mismo nodo pueda leerlo. - Evaluación de artefactos: Cada entrada que una Recipe declara bajo
artifacts:— contenido en línea, o un archivo nombrado por el propio$import:de esa entrada — se lee, se analiza como plantilla, se evalúa frente al contexto de plantilla completo y lleva la procedencia de la compilación. La proyección resultante se entrega al proveedor, que decide el formato de salida, dónde va la procedencia, la ruta de salida y los bytes finales. Cada archivo emitido registra de qué forma de autoría procede, de modo que una colisión de nombres de archivo puede nombrar a cada contribuyente. - Síntesis del Workload: El Workload analizado se entrega al proveedor que nombra la
capabilityde la Recipe, que lo traduce a los recursos nativos de ese proveedor. Una Recipe que no declaraworkload:no tiene nada que sintetizar aquí; sus archivos proceden, en cambio, del renderizado de la fuente. - Renderizado de Feature (generación de recursos de la FeatureRecipe): Cada adjunto del nodo cuya FeatureRecipe vinculada lleva sus propios
source,workload,artifactsy/ovaluesMapping— el patrón de generación de recursos, usado para manifiestos auxiliares como un ServiceMonitor, una NetworkPolicy, un ConfigMap de sidecar o un recurso de entrega de credenciales — se evalúa en una sola pasada, en el mismo orden del modelo de cebolla de 5 niveles que sigue el mapeo de inyección. Hay una única secuencia sobre un único conjunto de adjuntos: una Feature operativa y una Feature de credenciales recorren el mismo camino, y lo que las diferencia es lo que emite su FeatureRecipe. Los.valuesy.infrade cada adjunto se sustituyen por los de su propio ámbito; hereda los.localsevaluados de la Recipe base;.attachment_namenombra la instancia que se renderiza y.provideslleva los provides resueltos del propio adjunto, la misma bolsa que lee el consumidor. El diccionario de valores resultante se entrega al proveedor que nombra la propia capability de la FeatureRecipe, y los archivos renderizados se añaden a la salida de la frontera con dos coordenadas — el componente al que está adjuntada la Feature y, después, el nombre con el que está adjuntada —, de modo que un mismo nombre de Feature adjuntado a varios componentes mantiene cada uno separado. La forma que adoptan esas coordenadas se deriva de la propia disposición del proveedor anfitrión: un directorio<component>--<instance>/junto al del propio componente, donde el destino da a cada contribuyente una posición propia, y un prefijo de nombre de archivo<component>--<instance>--donde solo lee los archivos situados directamente en un directorio. Las FeatureRecipes solo de inyección — las que llevan únicamenteinjectMapping, ya tratadas durante el mapeo de inyección — se omiten aquí. Como las subfases anteriores, el renderizado de funcionalidades se ejecuta para un componente cada vez, de modo que un adjunto se evalúa normalmente justo después del componente al que está adjuntado. Un adjunto cuya FeatureRecipe declarareadsCallerRenderFacts: trueoreadsTargetRenderFacts: truese evalúa, en cambio, una vez que todos los componentes, y todos los adjuntos que no declaran ninguno de los dos, se han renderizado — de modo que cada componente que se conecta a su anfitrión, y cada uno al que está conectado su anfitrión, ya se ha renderizado para entonces —, y su salida va a parar donde habría ido de otro modo. - El pipeline de plugins (ejecución de pasos Wasm): El compilador lee el array
pipelinede la Recipe y ejecuta sus pasos en el orden declarado. Despacha el plugin Wasm nombrado de cada paso sobre los documentos renderizados del nodo, aplica las operaciones JSON Patch de RFC 6902 que devuelve el paso a los documentos a los que se dirigen esas operaciones y emite junto a ellos los efectos secundarios del paso — la superficie que hay detrás de mutaciones quirúrgicas como inyectar un sidecar de Envoy o montar un VolumeMount de secreto. Un paso cuya compuertawhen:se renderiza como falsa se omite como paso directo, dejando el conjunto de documentos sin cambios para el paso siguiente. El URIpluginde cada paso se resuelve antes de la ejecución en los bytes del artefacto verificado que el lockfile fija por digest. Los pasospipelinede una FeatureRecipe se ejecutan de la misma forma, sobre los documentos renderizados del propio adjunto y, para un adjunto de ámbito de componente, también sobre los del componente anfitrión.
- Mapeo de inyección (interceptación previa al renderizado): El compilador Go resuelve el contrato abstracto
Los tres tipos de entrada de Recipe llegan al compilador: source: + valuesMapping: a través del renderizado base, workload: a través del análisis y la síntesis del workload, y artifacts: a través de la evaluación de artefactos. Cuáles de ellos pueden entregarse a un proveedor dado no se decide subetapa por subetapa — se establece una vez por nodo, antes de cualquier despacho de renderizado, a partir del contrato declarado del propio proveedor, de modo que una Recipe cuyo tipo de entrada no acepta el proveedor vinculado se rechaza ahí y no a mitad del renderizado. Consulta 16-recipe-input-composition.md para el modelo de composición de los tres tipos de entrada, el tipo Workload y el mecanismo de Artifacts, y Estado del lenguaje para saber qué proveedor acepta qué tipo.
Salida nativa de GitOps
Para mantenerse estrictamente sin opiniones propias sobre cómo se aplica su salida, los plugins de renderizado escriben los artefactos generados en una estructura de directorios limpia y aislada por frontera (p. ej., dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Esto permite que controladores GitOps externos (como ArgoCD o Flux) sincronicen y apliquen la infraestructura sin que el compilador de Aggrega necesite nunca credenciales de la API de un clúster en vivo.
graph TD
subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
direction TB
A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
end
graph LR
E["Rendering"]
E -->|"Stringified Artifacts"| F["Helm Charts"]
E -->|"Stringified Artifacts"| G["Docker Compose"]
E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
E -->|"Stringified Artifacts"| I["Terraform Configuration"]
E -->|"Stringified Artifacts"| J["CloudFormation Templates"]
Mapa de fuentes de la infraestructura
Aggrega compila un Aggregate.yaml de unas 30 líneas en miles de líneas de configuración física JSON o YAML. Sin una forma de rastrear un recurso en ejecución hasta su origen, depurar un fallo en «main.tf.json línea 4,032» obliga a los desarrolladores a reconstruir la correspondencia manualmente. Los plugins de renderizado de Aggrega lo resuelven fusionando identificadores de traza en la superficie de metadatos nativa del proveedor — metadata.labels y metadata.annotations para Kubernetes, un comentario de procedencia para Terraform y convenciones equivalentes para cada proveedor —, de modo que cada objeto renderizado lleva un puntero de vuelta a la fuente de la que procede. La etiqueta aggrega.ai/compiler-version (documentada en gobernanza y cumplimiento §5) es una clave de traza de esta familia; junto a ella, el sello lleva aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri y aggrega.ai/environment, y los proveedores helm, helm-chart, compose, terraform y cloudformation lo emiten cada uno —el proveedor helm-chart en los archivos de plantilla que una Recipe añade a un chart, ya que copia sin cambios las plantillas propias del chart.
El sello no lleva ninguna clave que identifique el origen de la funcionalidad ni el tipo de catálogo.
Con el compilador se distribuyen otras dos superficies de depuración. aggrega build --trace escribe el estado intermedio de cada nodo, pasada a pasada, en .trace/ junto a dist/, para el autor de una Recipe que inspecciona lo que cada etapa recibió y produjo; y un diagnóstico que detiene la build lleva la categoría de la superficie de autoría a la que pertenece —DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR y las demás— siempre que el fallo tenga una, de modo que señala al autor correcto. Los errores que remontan un campo fallido de un manifiesto generado hasta la línea de plantilla que lo produjo no forman parte del compilador.
El pipeline de validadores
La fase de validación de esquemas de la resolución se apoya en un pipeline de validadores que convierte el contenido de las especificaciones de entidades (forma compacta, JSON Schema en YAML o mixto) en un documento JSON Schema 2020-12 unificado con procedencia por hoja, y luego valida contra él el contenido de instancia escrito por los desarrolladores. Cinco etapas se ejecutan en orden como transformaciones puras; cada una es una función determinista de sus entradas declaradas.
Etapa 1 — Compilación de la forma compacta. El compilador recorre el árbol YAML del contenido de schema:, parameters: y SchemaLibrary; despacha por nodo (hoja en forma compacta, JSON Schema en YAML, referencia $ref: o composición); emite JSON Schema 2020-12 resuelto. La forma compacta y el JSON Schema en YAML pueden mezclarse en cualquier límite de nodo mediante el escape $jsonschema:; el compilador resuelve el caso mixto recorriendo el árbol y despachando por nodo. La transformación es una función pura: la misma entrada en forma compacta produce siempre la misma salida JSON Schema. Consulta language-reference/vocabulary/compact-form-authoring.md para el vocabulario de palabras clave.
Etapa 2 — Resolución de spec.templates y $instantiate:. Para las entradas de SchemaLibrary escritas como referencias a plantillas, el compilador recorre cada entrada de la biblioteca que invoca $instantiate: con $args:, sustituye los valores de los parámetros como reemplazo de escalares literales y produce entradas de esquema concretas. La sustitución se ejecuta una vez por carga de la biblioteca; las entradas resueltas se almacenan en caché. Consulta language-reference/entities/schemalibrary.md para la forma de escritura de la entidad biblioteca.
Etapa 3 — Expansión de $ref: entre documentos. Para las referencias a SchemaLibrary mediante $ref: (la forma de identidad <Library>#/schemas/<entry>), el compilador recorre la cadena de referencias en tiempo de compilación propagando una pila de resolución; el contenido referenciado se incorpora en el esquema del consumidor. La expansión conserva la detección de ciclos (los ciclos detienen la compilación con un error que nombra la cadena), la salvaguarda de identidad-no-ubicación (una referencia que lleva un host de registro detiene la compilación y orienta hacia la forma de identidad — las referencias identifican las bibliotecas por su identidad, no por su ubicación física) y la composición de fuente única (los bloques $ref: solo aceptan la referencia desnuda; las sobrescrituras del lado del consumidor se componen mediante allOf: de JSON Schema). Consulta language-reference/vocabulary/cross-document-ref.md para la semántica de resolución.
Etapa 4 — Síntesis del puente para featuresSchema:. El compilador recorre el contenido featuresSchema: de cada entidad en el orden del autor y emite un fragmento JSON Schema que describe la forma de un relleno que puede enlazar cada slot de adjunto, con una palabra clave de extensión x-aggrega-inject: en un slot que declara una lista de permitidos inject. Ese fragmento se compila y se comprueba por separado, contra el bloque de adjuntos escrito, en lugar de incorporarse al contenido schema: orientado al desarrollador; la palabra clave de extensión es metadato que la validación JSON Schema ignora, y ninguna etapa posterior la vuelve a leer del fragmento — una comprobación que necesita la lista de permitidos de un slot lee el slot. La tabla de sockets usesSchema: no se proyecta en ningún fragmento: el selector: y el inject: de un socket se leen como el YAML tipado que escribió el arquitecto, y el valueSchema: / infraSchema: por arista de un socket se compila por separado. La síntesis es una función pura de sus entradas.
Etapa 5 — Fusionador propio con procedencia. Para las entidades que declaran extends:, el compilador recorre la cadena de padres; el JSON Schema resuelto del padre se convierte en la base; las sobrescrituras del hijo se aplican encima. Cada hoja del esquema resuelto lleva una etiqueta de procedencia por hoja (ruta del archivo, número de línea, origen padre o hijo). La salida del fusionador es lo que consume el motor de validación; el motor de validación es una implementación de terceros sin modificar conforme a JSON Schema 2020-12, con un recorredor determinista a su alrededor para emitir los hallazgos en orden.
Las cinco etapas se ejecutan antes de que el motor de validación vea el esquema. El motor recibe un único documento JSON Schema 2020-12 resuelto más el contenido de instancia del desarrollador; produce un informe de validación. El formateador de errores consulta las etiquetas de procedencia para emitir diagnósticos para el usuario que nombran con claridad las posiciones en el código fuente — incluido el archivo de origen de una restricción que una Feature heredó de su base en lugar de escribirla ella misma.
El pipeline del validador se ejecuta allí donde cada carga útil está completa por primera vez —los values y la infra de un componente durante la resolución, los componentes de un subagregado a medida que la construcción de la topología los incorpora, y la carga útil de un adjunto en la finalización del grafo—, de modo que un hallazgo de esquema detiene la build antes de que el análisis estático evalúe ningún selector, y antes de la evaluación de las aserciones, lo que permite a las plantillas de aserción apoyarse en cargas útiles validadas.
Preservación del determinismo a lo largo del pipeline
Cada etapa del pipeline de compilación preserva el invariante de salida determinista: con los mismos archivos fuente, el mismo lockfile y la misma versión del compilador, la compilación produce una salida idéntica byte a byte. El invariante es fundamental — el direccionamiento por contenido en el lockfile requiere digests de artefactos estables; las compilaciones reproducibles requieren que una release escrita en el portátil del desarrollador A compile a la misma salida en el portátil del desarrollador B y en CI; la revisabilidad de los diffs requiere que los cambios en el código fuente aparezcan como los únicos cambios en la salida compilada.
El determinismo se preserva mediante un pequeño número de disciplinas que toda transformación respeta:
- Orden de iteración fijo. Todo recorrido sobre YAML con forma de mapa itera en un orden fijo, porque la iteración nativa de mapas en Go es aleatoria. El compilador ordena antes de iterar en la mayoría de las etapas (compilador de forma compacta, fusionador, resolvedor de
spec.templates, formateador de errores, serializador YAML); la proyección de los slots de adjuntos, en cambio, conserva el orden del autor, de modo que el orden de las propiedades de una tabla de slots es el orden en que se escribió. - Sin marcas de tiempo incrustadas. La compilación no incrusta marcas de tiempo en la salida. Una compilación a las 14:00 produce el mismo artefacto que una a las 2:00. Los metadatos de procedencia del fusionador usan archivo:línea, no archivo:marca de tiempo.
- Rutas relativas al espacio de trabajo. Todas las rutas de la salida resuelta son relativas al espacio de trabajo; la capa de resolución de rutas las normaliza antes de que entren en cualquier salida.
- Sin fuentes aleatorias ni estado externo. Las transformaciones son funciones puras de sus entradas declaradas (contenido de la entidad, cadena de padres, lockfile). El estado externo solo se consulta durante la resolución (obtención de artefactos OCI), y el contenido resuelto se direcciona por contenido mediante su digest.
- Serialización YAML canónica. La salida se escribe en una única forma fija para cada entrada: el mismo orden de claves en todos los niveles en cada ejecución, con los arrays y los arrays
enum:en el orden de entrada; sangría de 2 espacios; finales de línea Unix LF; cadenas sin comillas donde YAML lo permite; forma booleanatrue/false; null omitido para los campos ausentes. - Orden alfabético de
$defs:. Las entradas$defs:de un esquema se emiten en orden alfabético de clave en el JSON Schema resuelto.$defs:es conceptualmente un diccionario, no una lista ordenada; el orden alfabético hace que los diffs sean predecibles entre reorganizaciones del código fuente. - El paralelismo no aflora en la salida. El compilador puede paralelizar unidades independientes (entidades distintas pueden compilarse de forma concurrente). Los resultados paralelos se reúnen en una estructura determinista (p. ej., ordenada por nombre de entidad) antes de serializarse.
Las pruebas de extremo a extremo del compilador compilan cada fixture varias veces dentro de una misma prueba y comprueban que cada ejecución emite los mismos archivos con contenidos idénticos byte a byte. Repetir la compilación es lo que detecta una fuga del orden de iteración de mapas o una iteración sobre un conjunto sin ordenar, que produce una salida estable en la mayoría de las ejecuciones y diverge ocasionalmente. Las pruebas se ejecutan con el resto del conjunto de pruebas del compilador.
El invariante de salida determinista se aplica en tiempo de compilación: los mismos archivos fuente + el mismo lockfile + la misma versión del compilador dan una salida idéntica byte a byte. La propiedad complementaria en tiempo de bloqueo (los mismos archivos fuente + el mismo estado del registro dan el mismo lockfile) es más débil — los registros son mutables (pueden publicarse nuevas versiones; pueden añadirse sidecars; los metadatos por componente pueden evolucionar), de modo que dos invocaciones de bloqueo sobre los mismos archivos fuente en momentos distintos pueden producir lockfiles distintos. Ese es el propósito del lockfile, en línea con las convenciones de npm, Cargo y Go. A partir de un lockfile nuevo, la compilación produce una salida determinista. La separación entre los dos momentos es lo que hace tolerable la mutabilidad del lado del registro: un sidecar publicado en el tiempo T2 cambia la siguiente invocación de bloqueo; no cambia las compilaciones contra el lockfile generado en T1.