Pipeline de compilação (visão geral)
Este capítulo detalha a física interna do compilador Go, definindo a forma como o YAML abstrato é traduzido em configurações físicas ao longo do pipeline de compilação, do grafo de Representação Intermédia (IR) e dos sockets de execução WebAssembly (Wasm).
O pipeline de compilação e o fluxo de execução
O Aggrega executa um pipeline de compilador Ahead-of-Time (AOT) estrito e de ordem fixa em vez de lógica de orquestração codificada. Acionado por aggrega build, o compilador passa o grafo plano entre sockets WebAssembly (Wasm) isolados para avaliar a arquitetura antes de renderizar artefactos físicos.
Os sockets Wasm correm num anfitrião incorporado — o toolkit Extism sobre o motor Wazero — por trás de uma firewall de pureza AOT que nega a um plugin qualquer capacidade de acesso em tempo de execução (rede, sistema de ficheiros, relógio de parede, ambiente, E/S padrão), pelo que um plugin não pode quebrar a garantia determinística e ahead-of-time. O anfitrião executa o linter de publicação fora de banda, através de aggrega lint. As barreiras em banda descritas abaixo — o papel label-transform do socket de governação na construção da topologia e o seu papel IR-verdict na análise estática, além do pipeline de plugins que fecha a renderização — correm em todas as compilações: um papel de governação sempre que o workspace lhe anexa um plugin, e o pipeline de plugins para cada Recipe que declara passos. O Estado da linguagem acompanha o estado de cada fase do pipeline.
O pipeline é executado inteiramente em memória, numa ordem estrita e fixa:
Resolução — o resolvedor e o validador de sintaxe
- Mecanismo: fusão por herança, interpolação de templates Go e validação JSON Schema 2020-12.
- Ação: a CLI obtém todas as entidades pedidas (Components, Features, Releases). Primeiro, verifica nessas definições a palavra-chave
extends. Para as entidades de catálogo, funde em profundidade os metadados YAML, e os dois tipos separam-se nos pilares de dados: oschema:de uma Feature compõe-se com o da sua base segundo a composição JSON Schema 2020-12, enquanto um Component que estende compõe apenas estrutura — os seus slots de anexo, sockets de topologia, allowlist de autoinjeção e asserções nomeadas — e recebe o blocoschema:da sua base exatamente como a base o escreveu. UmaReleaseque estende combina-se pela mesma regra: o valor do filho prevalece chave a chave, até ao primeiro valor indivisível — um escalar, uma lista, um template —, que substitui por inteiro, e uma chave que o filho escreve comonullé removida. Assim, toda a sua superfície de autoria é transmitida — a árvore de fronteiras com oinfrapor componente e os anexos de Features, o blocoparameters, as anotações e o ponteiro para o Manifest —, enquanto nenhum campometadatao é, uma vez que a identidade e a proveniência são por Release. Em seguida, realiza uma interpolação em memória em três subpassos: validação do contrato de parâmetros face às declaraçõesparameters:tipadas do Aggregate; interpolação dos valores resolvidos nas cadeiasvalues:envolventes; retirada do mapa.parametersde todos os contextos de templates de valores, deixando-o legível apenas para os templates de caminhos escritos pelo operador. Por fim, injeta os blocosinfraresolvidos nos payloads dos componentes de destino. Quando o blueprint está totalmente concreto, o compilador utiliza a declaraçãoschema:unificada do catálogo (forma compacta ou JSON Schema 2020-12 completo) para validar estritamente, localmente, as configuraçõesvalueseinfrado programador.- Validação do esquema das Features da Release: as Features anexadas através da Release (tanto ao nível da fronteira como específicas de um componente) são resolvidas face às suas entidades de catálogo durante este passo. O compilador valida os blocos
infrafornecidos pela Release face à declaraçãoschema:de cada Feature imediatamente após a resolução do catálogo, garantindo a segurança de tipos antes de a topologia ser construída. - Subfase de expansão de Features guiada por anotações: após a resolução do Manifest, a associação de Recipe/Provider e a validação dos destinos de associação do Manifest (os caminhos declarados em
mappings.features.annotations.<key>.mapsexistem nospec.schemada Feature referenciada), o compilador executa uma subfase de expansão de anotações antes do construtor de topologia. A subfase percorre as fronteiras da Release de fora para dentro e os subsistemas do Aggregate de fora para dentro, calculando o conjunto efetivo de anotações por componente através de uma fusão por cascata + substituição + exclusão por null; analisa cada valor de anotação como YAML num escalar, num valor estruturado ou em null; encaminha cada valor (escalar, ou estruturado por subchave) através da declaraçãomapsda associação do Manifest para o pilar do esquema da Feature de destino, com imposição de lado-versus-pilar (o lado do Aggregate acionamaps.values; o lado da Release acionamaps.infra); valida os tipos por folha face aospec.schemada Feature; e injeta anexos de Features sintéticos, que o grafo IR marca comorigin: annotation. Os esquemas são compilados uma vez por compilação e reutilizados entre percursos de cascata. A expansão corre após a validação dos destinos de associação e antes da construção da topologia, pelo que as fases seguintes tratam os anexos sintéticos de forma estruturalmente idêntica aos explícitos (exceto através da inspeção da proveniência). Ver 13-catalog-and-registry.md §«Expansão de Features guiada por anotações» elanguage-reference/providers/well-known-annotations.mdpara a forma da associação, a semântica da cascata e as regras de composição entre lados.
- Validação do esquema das Features da Release: as Features anexadas através da Release (tanto ao nível da fronteira como específicas de um componente) são resolvidas face às suas entidades de catálogo durante este passo. O compilador valida os blocos
Construção da topologia — o construtor de topologia e a barreira de mutação
- Mecanismo: expansão da AST + o papel
label-transformdo socket de governação. - Ação: o compilador lê nativamente os blocos
usesdeclarados explicitamente nos componentes validados para traçar de forma determinística arestas topológicas entre nós do grafo, deixando o blocovaluescompletamente opaco. Em seguida, avalia a barreira de mutação, passando uma projeção do grafo — as etiquetas de cada nó e osvaluesque a sua instância declara, que o compilador entrega sem os ler — com o nome e o ambiente da Release, a um plugin de governação anexado no papellabel-transform. O plugin avalia o contexto e devolve JSONPatches para etiquetar dinamicamente o grafo (por exemplo, injetando a etiquetacompliance.aggrega.ai/data-class: restrictedcom base no ambiente da Release, oudatastore.aggrega.ai/engine: vectorcom base nas extensões declaradas de uma base de dados); os patches só alcançam etiquetas.
Finalização do grafo
- Mecanismo: normalização.
- Ação: o compilador finaliza o grafo plano de Representação Intermédia (IR), preservando as arestas topológicas explícitas que o construtor de topologia traçou. Em seguida, normaliza as Features anexadas e os seus payloads
valuesnum dicionário plano indexado pelo ID do nó, preparando o grafo agnóstico em relação às capacidades para a validação.- Normalização dos payloads da IR: a forma estrutural da IR impõe uma fonte única de verdade para a configuração: a camada de topologia transporta apenas a estrutura do grafo (identidade dos nós, arestas, etiquetas de metadados), e o estado de configuração normalizado vive num dicionário em memória separado que o compilador passa aos plugins seguintes. Os mutadores que alteram a configuração alteram-na num único local; o provider lê o estado normalizado sem risco de divergência por armazenamento redundante.
Análise estática — o analisador estático e a barreira de validação
- Mecanismo: verificações de pureza topológica + o papel
ir-verdictdo socket de governação. - Ação: o compilador executa uma análise estática abstrata sobre o grafo IR. Primeiro, extrai as cadeias
selectordas definiçõesusesSchemae avalia-as com um motor nativo de correspondência de etiquetas em Go (que suporta a semântica ao estilo Kubernetes deAND,ORatravés dein()eNOTatravés de!=) sobre as arestas do grafo definidas explicitamente, para garantir a segurança de tipos entre nós nos sockets declarados. Uma aresta num socket ad hoc — um que um autor de Aggregate nomeou e que o catálogo não declarou — não tem entrada de catálogo e, portanto, não tem seletor, pelo que não há nada que esta verificação avalie e nada em falta; cada aresta regista de qual dos dois tipos é, e o que uma aresta ad hoc pode transportar é limitado, em vez disso, peloprovidesdeclarado do destino. Também avalia os seletoresappliesToeappliesToAnyOfdas Features para verificar que as features anexadas são compatíveis com as etiquetas do seu componente de destino, e o próprioselectorde cada slot de anexo preenchido face às etiquetas da Feature que o preenche. Segundo, avalia cada obrigação de presença que o Component de um nó declara — cada anotaçãofeatures.aggrega.ai/requiredType.<label>— face ao conjunto final de anexos desse nó. O analisador é o lugar desta verificação porque é a primeira fase que dispõe das duas metades da regra: as anotações da entidade Component resolvida e o conjunto de anexos que a cascata de 5 níveis produziu, contando por igual os anexos feitos no Aggregate, no subsistema, na Release e os expandidos a partir de anotações. Uma obrigação que nenhum anexo satisfaça interrompe a compilação; uma obrigação cuja declaração esteja malformada interrompe-a com um diagnóstico distinto, para que uma declaração defeituosa nunca seja lida como um requisito satisfeito. Terceiro, executa a barreira de validação, passando a estrutura completa do grafo (incluindo todos os nós, arestas, features anexadas e caminhos DFS pré-calculados) a um plugin de governação anexado no papelir-verdict. A política Wasm personalizada da empresa avalia a topologia. Se o plugin Wasm devolver um array de falhas (por exemplo, ao detetar um caminho contínuo de um nópublicpara um nórestrictedsem uma feature de proxy específica), a compilação é interrompida.
Renderização
- Mecanismo: interceção pré-renderização (
injectMapping), associação tardia (valuesMapping) e sockets de renderização Wasm (pipeline). - Ação: a fase final de geração de artefactos divide-se em subfases temporais estritas que correm numa ordem fixa, o que mantém a execução determinística:
- Mapeamento de injeção (interceção pré-renderização): o compilador Go resolve o contrato abstrato
.context.injectdo programador. Em seguida, executa os templates GoinjectMappingde todas asFeatureRecipesanexadas, seguindo a ordem de execução estrita do modelo em cebola de 5 níveis (Sub-Aggregate — os anexos próprios de um componente de módulo, depois os que os subsistemas do seu módulo declaram, de fora para dentro → componente do Aggregate raiz → subsistema do Aggregate raiz → fronteira da Release de fora para dentro → específico do componente na Release). O compilador funde nativamente em profundidade os dicionários resultantes sobre o canal de memória.context.injectdo chamador. Isto reescreve em segurança variáveis de ambiente e cadeias de ligação para o chamador antes de a Recipe base alguma vez as ver. Um mapeamento pode reescrever o que o próprio blocoinject:do chamador ou uma das suas ligações entregou; uma chave que uma Feature anexada diferente já tenha entregado — através do seu próprio mapeamento ou do seu próprio blocoinject:— interrompe a compilação nomeando ambos os anexos, pelo que a ordem de execução nunca decide entre os valores de dois anexos. - Preâmbulo de locals: antes de correr qualquer template
provides, o compilador avalia as entradas.localsda Recipe pela ordem em que estão escritas, cada uma face a um contexto local ao nó e autocontido —.context.instance_id,.values,.infrae as entradas do mesmo bloco já resolvidas, mas não.context.injectnem.context.uses. Uma entrada pode, portanto, ler uma entrada irmã definida acima dela e recebe o valor resolvido dessa irmã; a ordem do autor faz parte do contrato sempre que uma entrada lê outra, e o bloco nunca é reordenado para que uma referência se resolva. Resolver primeiro os locals é o que permite a um templateprovidesler.locals. O template.sourceda Recipe é avaliado face ao mesmo contexto assim que esses locals estão resolvidos, o que mantém.localsreutilizável como abreviatura entre os templates de uma Recipe e permite aos autores parametrizar.source(versão do chart, caminho, registo) por fronteira. - Renderização base (
valuesMappingda Recipe base): o compilador avalia o templatevaluesMappingda Recipe base. O template lê as cadeias intercetadas do canal.context.inject(reescritas durante o mapeamento de injeção), e o dicionário de valores resultante é entregue ao provider que ocapabilityda Recipe nomeia — os providers helm e helm-chart renderizam ambos através do Helm — para renderizar os artefactos de infraestrutura base. - Análise e validação do Workload: uma Recipe que declare
workload:— conteúdo em bloco inline, ouworkload: { $import: <path> }a nomear um ficheiro — tem esse documento avaliado como template face ao contexto de renderização do nó, depois analisado como YAML na forma de Workload e verificado: os bytes renderizados são validados face ao esquema de Workload, o valor descodificado também é validado face a ele (os bytes contêm chaves que a descodificação descarta, e a descodificação omite um campo fornecido vazio, pelo que cada um rejeita o que o outro não consegue ver), cada entradaattachmentsé verificada face aos slots que ofeaturesSchemado Component associado declara, e cada referência de recurso é verificada face aoprovidesresolvido do slot que nomeia. Uma falha aqui interrompe a compilação. O Workload analisado é colocado no contexto de templates como.workload, para que um template avaliado mais tarde no mesmo nó o possa ler. - Avaliação de artefactos: cada entrada que uma Recipe declara em
artifacts:— conteúdo inline, ou um ficheiro nomeado pelo próprio$import:dessa entrada — é lida, analisada como template, avaliada face ao contexto de templates completo e transporta a proveniência da compilação. A projeção resultante é entregue ao provider, que decide o formato de saída, onde fica a proveniência, o caminho de saída e os bytes finais. Cada ficheiro emitido regista de que forma de autoria proveio, para que uma colisão de nomes de ficheiro possa nomear todos os contribuidores. - Síntese do Workload: o Workload analisado é entregue ao provider que o
capabilityda Recipe nomeia, que o traduz nos recursos nativos desse provider. Uma Recipe que não declareworkload:não tem aqui nada a sintetizar; os seus ficheiros provêm, em vez disso, da renderização da fonte. - Renderização de Features (geração de recursos pela FeatureRecipe): cada anexo do nó cuja FeatureRecipe associada transporte o seu próprio
source,workload,artifactse/ouvaluesMapping— o padrão de geração de recursos, usado para manifestos auxiliares como um ServiceMonitor, uma NetworkPolicy, um ConfigMap de sidecar ou um recurso de entrega de credenciais — é avaliado numa única passagem, pela mesma ordem do modelo em cebola de 5 níveis que o mapeamento de injeção segue. Há uma sequência sobre um conjunto de anexos: uma Feature operacional e uma Feature de credenciais percorrem o mesmo caminho, e o que as distingue é o que a sua FeatureRecipe emite. O.valuese o.infrade cada anexo são trocados para o seu próprio âmbito; herda os.localsavaliados da Recipe base;.attachment_namenomeia a instância a renderizar e.providestransporta os provides resolvidos do próprio anexo, o mesmo conjunto que o consumidor lê. O dicionário de valores resultante é entregue ao provider nomeado pela própria capacidade da FeatureRecipe, e os ficheiros renderizados são acrescentados à saída da fronteira com duas coordenadas — o componente a que a Feature está anexada e, depois, o nome sob o qual está anexada —, para que um mesmo nome de Feature anexado a vários componentes mantenha cada um separado. A forma que essas coordenadas assumem decorre da própria organização do provider anfitrião: um diretório<component>--<instance>/ao lado do diretório do próprio componente, quando o destino dá a cada contribuidor uma posição própria, e um prefixo de nome de ficheiro<component>--<instance>--quando lê apenas os ficheiros que estão diretamente num diretório. As FeatureRecipes apenas de injeção — as que transportam apenasinjectMapping, já tratadas durante o mapeamento de injeção — são aqui ignoradas. Tal como as subfases anteriores, a renderização de Features corre um componente de cada vez, pelo que um anexo é normalmente avaliado logo a seguir ao componente a que está anexado. Um anexo cuja FeatureRecipe declarereadsCallerRenderFacts: trueoureadsTargetRenderFacts: trueé, em vez disso, avaliado depois de todos os componentes, e de todos os anexos que não declaram nenhum dos dois, terem sido renderizados — para que cada componente que se liga ao seu anfitrião, e cada um a que o seu anfitrião está ligado, já tenha sido renderizado nessa altura — e a sua saída fica onde teria ficado de outro modo. - O pipeline de plugins (execução de passos Wasm): o compilador lê o array
pipelineda Recipe e executa os seus passos pela ordem declarada. Despacha o plugin Wasm nomeado de cada passo sobre os documentos renderizados do nó, aplica as operações JSON Patch RFC 6902 que o passo devolve aos documentos a que essas operações se dirigem e emite os efeitos secundários do passo ao lado deles — a superfície por trás de mutações cirúrgicas, como injetar um sidecar Envoy ou montar um VolumeMount de segredo. Um passo cuja barreirawhen:renderize um valor falso é ignorado como passagem direta, deixando o conjunto de documentos inalterado para o passo seguinte. O URIpluginde cada passo resolve-se, antes da execução, para os bytes de artefacto verificados que o lockfile fixa por digest. Os passospipelinede uma FeatureRecipe são executados da mesma forma, sobre os documentos renderizados do próprio anexo e, para um anexo de âmbito de componente, também sobre os do componente anfitrião.
- Mapeamento de injeção (interceção pré-renderização): o compilador Go resolve o contrato abstrato
Os três tipos de input de uma Recipe chegam ao compilador: source: + valuesMapping: através da renderização base, workload: através da análise e da síntese do Workload, e artifacts: através da avaliação de artefactos. Quais deles podem ser entregues a um dado provider não é decidido subfase a subfase — é determinado uma vez por nó, antes de qualquer despacho de renderização, a partir do contrato declarado do próprio provider, pelo que uma Recipe cujo tipo de input o provider associado não aceita é recusada aí, e não a meio da renderização. Ver 16-recipe-input-composition.md para o modelo de composição dos três tipos de input, o tipo Workload e o mecanismo de Artifacts, e o Estado da linguagem para saber que provider aceita que tipo.
Saída nativa de GitOps
Para se manterem estritamente sem opiniões próprias quanto à forma como a sua saída é aplicada, os plugins de renderização escrevem os artefactos gerados numa estrutura de diretórios limpa e isolada por fronteira (por exemplo, dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Isto permite a controladores GitOps externos (como o ArgoCD ou o Flux) sincronizar e aplicar a infraestrutura sem que o compilador Aggrega alguma vez precise de credenciais da API do cluster em direto.
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 origem da infraestrutura
O Aggrega compila um Aggregate.yaml de ~30 linhas em milhares de linhas de configuração física em JSON ou YAML. Sem uma forma de rastrear um recurso em execução até à sua origem, depurar uma falha em «main.tf.json linha 4.032» obriga os programadores a reconstruir manualmente o mapeamento. Os plugins de renderização do Aggrega resolvem isto fundindo identificadores de rastreio na superfície de metadados nativa do provider — metadata.labels e metadata.annotations para o Kubernetes, um comentário de proveniência para o Terraform e convenções equivalentes por provider —, para que cada objeto renderizado transporte um ponteiro para a origem de onde veio. A etiqueta aggrega.ai/compiler-version (documentada em governance-and-compliance §5) é uma chave de rastreio desta família; ao lado dela, o carimbo transporta aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri e aggrega.ai/environment, e os providers helm, helm-chart, compose, terraform e cloudformation emitem-no cada um — o provider helm-chart nos ficheiros de template que uma Recipe acrescenta a um chart, já que copia sem alterações os templates próprios do chart.
O carimbo não contém nenhuma chave que identifique a origem da funcionalidade ou o tipo de catálogo.
Acompanham o compilador mais duas superfícies de depuração. aggrega build --trace escreve o estado intermédio de cada nó, passagem a passagem, em .trace/ ao lado de dist/, para o autor de uma Recipe que inspeciona o que cada fase recebeu e produziu; e um diagnóstico que interrompe a compilação transporta a categoria da superfície de autoria a que pertence — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR e as restantes — sempre que a falha tenha uma, para que aponte para o autor certo. Os erros que reconduzem um campo com falha de um manifesto gerado à linha do template que o produziu não fazem parte do compilador.
O pipeline do validador
A fase de validação de esquemas da resolução assenta num pipeline de validação que converte o conteúdo de especificação das entidades (forma compacta, JSON Schema em YAML ou misto) num documento JSON Schema 2020-12 unificado com proveniência por folha e, depois, valida face a ele o conteúdo de instância escrito pelo programador. Cinco fases correm como transformações puras, por ordem; cada uma é uma função determinística sobre os inputs que declara.
Fase 1 — Compilação da forma compacta. O compilador percorre a árvore YAML do conteúdo schema:, parameters: e SchemaLibrary; despacha por nó (folha em forma compacta vs JSON Schema em YAML vs referência $ref: vs composição); emite JSON Schema 2020-12 resolvido. A forma compacta e o JSON Schema em YAML podem misturar-se em qualquer fronteira de nó através do escape $jsonschema:; o compilador trata o caso misto percorrendo a árvore e despachando por nó. A transformação é uma função pura: o mesmo input em forma compacta produz sempre o mesmo output em JSON Schema. Ver language-reference/vocabulary/compact-form-authoring.md para o vocabulário de palavras-chave.
Fase 2 — Resolução de spec.templates e $instantiate:. Para as entradas de SchemaLibrary escritas como referências a templates, o compilador percorre cada entrada da biblioteca que invoca $instantiate: com $args:, substitui os valores dos parâmetros como substituição de escalares literais e produz entradas de esquema concretas. A substituição corre uma vez por carregamento da biblioteca; as entradas resolvidas ficam em cache. Ver language-reference/entities/schemalibrary.md para a forma de autoria da entidade de biblioteca.
Fase 3 — Expansão de $ref: entre documentos. Para as referências a SchemaLibrary através de $ref: (a forma de identidade <Library>#/schemas/<entry>), o compilador percorre a cadeia de referências em tempo de compilação através do encadeamento de uma pilha de resolução; o conteúdo referenciado é incorporado no esquema do consumidor. A expansão preserva a deteção de ciclos (os ciclos interrompem a compilação com um erro que nomeia a cadeia), a salvaguarda identidade-e-não-localização (uma referência que transporte um host de registo interrompe a compilação com uma indicação para a forma de identidade — as referências endereçam bibliotecas pela identidade, não pela localização física) e a composição de fonte única (os blocos $ref: aceitam apenas a referência simples; as substituições do lado do consumidor compõem-se através do allOf: do JSON Schema). Ver language-reference/vocabulary/cross-document-ref.md para a semântica da resolução.
Fase 4 — Síntese da ponte para featuresSchema:. O compilador percorre o conteúdo featuresSchema: de cada entidade pela ordem do autor e emite um fragmento JSON Schema que descreve a forma de um preenchimento que pode associar cada slot de anexo, com uma palavra-chave de extensão x-aggrega-inject: num slot que declare uma allowlist inject. Esse fragmento é compilado e verificado por si, face ao bloco de anexos escrito, em vez de ser incorporado no conteúdo schema: voltado para o programador; a palavra-chave de extensão é um metadado que a validação JSON Schema ignora, e nenhuma fase posterior a volta a ler do fragmento — uma verificação que precise da allowlist de um slot lê o slot. A tabela de sockets usesSchema: não é projetada em nenhum fragmento: o selector: e o inject: de um socket são lidos como o YAML tipado que o Architect escreveu, e o valueSchema: / infraSchema: por aresta de um socket é compilado por si. A síntese é uma função pura sobre os seus inputs.
Fase 5 — Fusão personalizada com proveniência. Para as entidades que declaram extends:, o compilador percorre a cadeia de pais; o JSON Schema resolvido do pai torna-se a base; as substituições do filho aplicam-se por cima. Cada folha do esquema resolvido transporta uma etiqueta de proveniência por folha (caminho do ficheiro, número de linha, origem pai-versus-filho). O resultado da fusão é o que o motor de validação consome; o motor de validação é uma implementação de terceiros não modificada e conforme ao JSON Schema 2020-12, com um percurso determinístico à sua volta para a emissão ordenada de resultados.
As cinco fases correm antes de o motor de validação ver o esquema. O motor recebe um único documento JSON Schema 2020-12 resolvido mais o conteúdo de instância do programador; produz um relatório de validação. O formatador de erros consulta as etiquetas de proveniência para emitir diagnósticos voltados para o utilizador que nomeiam claramente as posições de origem — incluindo o ficheiro de origem de uma restrição que uma Feature herdou da sua base em vez de a escrever ela própria.
O pipeline do validador corre onde cada payload fica completo pela primeira vez — os values e o infra de um componente durante a resolução, os componentes de um subagregado à medida que a construção da topologia os incorpora, e o payload de um anexo na finalização do grafo —, pelo que uma constatação de esquema interrompe a compilação antes de a análise estática avaliar qualquer seletor, e antes da avaliação das asserções, o que permite aos templates de asserção confiar em payloads validados.
Preservação do determinismo ao longo do pipeline
Cada fase do pipeline de compilação preserva o invariante de saída determinística: com os mesmos ficheiros de origem, mais o mesmo lockfile, mais a mesma versão do compilador, a compilação produz uma saída idêntica byte a byte. O invariante é fundamental — o endereçamento por conteúdo no lockfile exige digests de artefactos estáveis; as compilações reproduzíveis exigem que uma release escrita no portátil do programador A compile para a mesma saída no portátil do programador B e na CI; a revisibilidade por diff exige que as alterações à origem apareçam como as únicas alterações na saída compilada.
O determinismo é preservado por um pequeno número de disciplinas que todas as transformações respeitam:
- Ordem de iteração fixa. Cada percurso sobre YAML em forma de mapa itera numa ordem fixa, porque a iteração nativa de mapas em Go é aleatória. O compilador ordena antes de iterar na maioria das fases (compilador de forma compacta, fusão, resolvedor de
spec.templates, formatador de erros, serializador YAML); a projeção dos slots de anexo, em vez disso, preserva a ordem do próprio autor, pelo que a ordem das propriedades de uma tabela de slots é a ordem em que foi escrita. - Sem incorporação de tempo. A compilação não incorpora carimbos temporais na saída. Uma compilação às 14:00 produz o mesmo artefacto que uma compilação às 2:00. Os metadados de proveniência da fusão usam ficheiro:linha, não ficheiro:carimbo temporal.
- Caminhos relativos ao espaço de trabalho. Todos os caminhos na saída resolvida são relativos ao espaço de trabalho; a camada de resolução de caminhos normaliza-os antes de entrarem em qualquer saída.
- Sem fontes aleatórias, sem estado externo. As transformações são funções puras sobre os inputs que declaram (conteúdo da entidade, cadeia de pais, lockfile). O estado externo só é consultado durante a resolução (obtenção de artefactos OCI), e o conteúdo resolvido é endereçado por conteúdo através do digest.
- Serialização YAML canónica. A saída é escrita numa única forma fixa para cada input: a mesma ordem das chaves a todas as profundidades em cada execução, com os arrays e os arrays
enum:na ordem de input; indentação de 2 espaços; fins de linha Unix LF; cadeias sem aspas onde o YAML o permite; forma booleanatrue/false; null omitido nos campos ausentes. - Ordem alfabética de
$defs:. As entradas$defs:de um esquema são emitidas por ordem alfabética das chaves no JSON Schema resolvido.$defs:é conceptualmente um dicionário, não uma lista ordenada; a ordem alfabética torna os diffs previsíveis entre reorganizações da origem. - O paralelismo não chega à saída. O compilador pode paralelizar unidades independentes (entidades diferentes podem ser compiladas em simultâneo). Os resultados paralelos são reunidos numa estrutura determinística (por exemplo, ordenada pelo nome da entidade) antes de serem serializados.
Os testes ponta a ponta do compilador compilam cada fixture várias vezes num mesmo teste e verificam que cada execução emite os mesmos ficheiros com conteúdo idêntico byte a byte. É a repetição da compilação que deteta uma fuga da ordem de iteração de mapas ou uma iteração sobre um conjunto não ordenado, que produz uma saída estável na maioria das execuções e diverge ocasionalmente. Os testes correm com o resto do conjunto de testes do compilador.
O invariante de saída determinística aplica-se em tempo de compilação: com os mesmos ficheiros de origem + o mesmo lockfile + a mesma versão do compilador, saída idêntica byte a byte. A propriedade complementar em tempo de bloqueio (com os mesmos ficheiros de origem + o mesmo estado do registo, o mesmo lockfile) é mais fraca — os registos são mutáveis (podem ser publicadas novas versões; podem ser acrescentados sidecars; os metadados por componente podem evoluir), pelo que duas invocações de bloqueio sobre os mesmos ficheiros de origem em momentos diferentes podem produzir lockfiles diferentes. É esse o propósito do lockfile, à semelhança das convenções do npm, do Cargo e do Go. A partir de um lockfile novo, a compilação produz uma saída determinística. A separação entre os dois momentos é o que torna tolerável a mutabilidade do lado do registo: um sidecar publicado no momento T2 altera a invocação de bloqueio seguinte; não altera as compilações feitas com o lockfile gerado em T1.