Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Pipeline de compilação (visão geral)

Este capítulo detalha a física interna do compilador Go, definindo como o YAML abstrato é traduzido em configurações físicas ao longo do pipeline de compilação, do grafo de Representação Intermediária (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 artefatos físicos.

Os sockets Wasm rodam em um host embarcado — o toolkit Extism sobre o engine Wazero — por trás de um firewall de pureza AOT que nega a um plugin qualquer capacidade de acesso em tempo de execução (rede, sistema de arquivos, relógio de parede, ambiente, E/S padrão), de modo que um plugin não pode quebrar a garantia determinística e ahead-of-time. O host executa o publishing linter fora de banda, via aggrega lint. Os gates em banda descritos abaixo — o papel de transformação de labels do socket de governança na construção da topologia e seu papel de veredito sobre a IR na análise estática, além do pipeline de plugins que encerra a renderização — são executados em todo build: um papel de governança onde quer que o workspace anexe um plugin a ele, e o pipeline de plugins para toda Recipe que declara etapas. Status da linguagem acompanha o status de cada fase do pipeline.

O pipeline é executado inteiramente em memória, em uma ordem estrita e fixa:

Resolução — O resolvedor e validador de sintaxe

  • Mecanismo: merge de herança, interpolação de templates Go e validação JSON Schema 2020-12.
  • Ação: a CLI busca todas as entidades solicitadas (Components, Features, Releases). Primeiro, verifica essas definições em busca da palavra-chave extends. Para as entidades do catálogo, faz um deep merge dos metadados YAML, e os dois tipos se separam nos pilares de dados: o schema: de uma Feature se compõe com o de sua base segundo a composição do JSON Schema 2020-12, enquanto um Component que estende compõe apenas a estrutura — seus slots de anexo, sockets de topologia, allowlist de autoinjeção e asserções nomeadas — e recebe o bloco schema: de sua base exatamente como a base o escreveu. Uma Release que estende é combinada pela mesma regra: o valor do filho prevalece chave por chave, até o primeiro valor indivisível — um escalar, uma lista, um template —, que é substituído por inteiro, e uma chave que o filho escreve como null é removida. Assim, toda a sua superfície de autoria é transferida — a árvore de fronteiras com seus infra por componente e anexos de Feature, o bloco parameters, as anotações e o ponteiro para o Manifest —, enquanto nenhum campo de metadata é, já que identidade e proveniência são por Release. Em seguida, realiza uma interpolação em memória em três subetapas: validação do contrato de parâmetros contra as declarações tipadas parameters: do Aggregate; interpolação dos valores resolvidos nas strings values: ao redor; retirada do mapa .parameters de todo contexto de template de valor, deixando-o legível apenas para templates de caminho escritos pelo operador. Por fim, injeta os blocos infra resolvidos nos payloads dos componentes de destino. Quando o blueprint está totalmente concreto, o compilador usa a declaração unificada schema: do catálogo (forma compacta ou JSON Schema 2020-12 completo) para validar estritamente, de forma local, as configurações values e infra do desenvolvedor.
    • Validação de schema de Feature da Release: as Features anexadas por meio da Release (tanto as de toda a fronteira quanto as específicas de componente) são resolvidas contra suas entidades do catálogo durante esta etapa. O compilador valida os blocos infra fornecidos pela Release contra a declaração schema: de cada Feature imediatamente após a resolução do catálogo, garantindo a segurança de tipos antes que a topologia seja construída.
    • Subfase de expansão de Feature orientada por anotações: após a resolução do Manifest, o binding de Recipe/Provider e a validação dos alvos de binding do Manifest (os caminhos declarados em mappings.features.annotations.<key>.maps existem no spec.schema da 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 por meio de um merge de cascata + override + opt-out por null; interpreta cada valor de anotação como YAML em um escalar, um valor estruturado ou null; encaminha cada valor (escalar ou estruturado por subchave) pela declaração maps do binding do Manifest até o pilar de schema da Feature de destino, com imposição de lado versus pilar (o lado do Aggregate aciona maps.values; o lado da Release aciona maps.infra); valida os tipos de cada folha contra o spec.schema da Feature; e injeta anexos sintéticos de Feature, que o grafo IR marca com origin: annotation. Os schemas são compilados uma vez por build e reutilizados entre os percursos da cascata. A expansão é executada após a validação dos alvos de binding e antes da construção da topologia, de modo que as etapas seguintes tratam os anexos sintéticos de forma estruturalmente idêntica aos explícitos (exceto por meio da inspeção de proveniência). Consulte 13-catalog-and-registry.md §“Expansão de Feature orientada por anotações” e language-reference/providers/well-known-annotations.md para o formato do binding, a semântica da cascata e as regras de composição entre os lados.

Construção da topologia — O construtor de topologia e o portão de mutação

  • Mecanismo: expansão da AST + o papel label-transform do socket de governança.
  • Ação: o compilador lê nativamente os blocos uses declarados explicitamente nos componentes validados para desenhar de forma determinística as arestas topológicas entre os nós do grafo, deixando o bloco values completamente opaco. Em seguida, avalia o portão de mutação, passando uma projeção do grafo — os labels de cada nó e os values que sua instância declara, que o compilador entrega sem ler — com o nome e o ambiente da Release, para um plugin de governança anexado no papel label-transform. O plugin avalia o contexto e retorna JSONPatches para marcar o grafo dinamicamente de forma automática (por exemplo, injetando o label compliance.aggrega.ai/data-class: restricted com base no ambiente da Release, ou datastore.aggrega.ai/engine: vector com base nas extensões declaradas de um banco de dados); os patches alcançam apenas labels.

Finalização do grafo

  • Mecanismo: normalização.
  • Ação: o compilador finaliza o grafo plano de Representação Intermediária (IR), preservando as arestas topológicas explícitas que o construtor de topologia desenhou. Em seguida, normaliza as Features anexadas e seus payloads values em um dicionário plano mapeado por ID de nó, preparando para a validação o grafo agnóstico em relação às capacidades.
    • Normalização do payload da IR: a forma estrutural da IR impõe uma fonte única de verdade para a configuração: a camada de topologia carrega apenas a estrutura do grafo (identidade dos nós, arestas, labels de metadados), e o estado normalizado da configuração vive em um dicionário separado em memória que o compilador passa aos plugins seguintes. Os mutadores que alteram a configuração a alteram em um único lugar; o provedor lê o estado normalizado sem risco de divergência causada por armazenamento redundante.

Análise estática — O analisador estático e o portão de validação

  • Mecanismo: verificações de pureza topológica + o papel ir-verdict do socket de governança.
  • Ação: o compilador executa uma análise estática abstrata sobre o grafo IR. Primeiro, extrai as strings selector das definições usesSchema e as avalia usando um mecanismo nativo de correspondência de labels em Go (com suporte à semântica no estilo Kubernetes de AND, OR via in() e NOT via !=) ao longo das arestas do grafo definidas explicitamente, para garantir a segurança de tipos entre nós sobre sockets declarados. Uma aresta em um socket ad hoc — um que o autor de um Aggregate nomeou e que o catálogo não declarou — não tem entrada no catálogo e, portanto, nenhum seletor, de modo que não há nada para essa verificação avaliar e nada faltando; cada aresta registra qual dos dois ela é, e o que uma aresta ad hoc pode carregar é limitado, em vez disso, pelo provides declarado do alvo. Também avalia os seletores appliesTo e appliesToAnyOf de Feature para verificar se as funcionalidades anexadas são compatíveis com os labels do componente de destino, e o próprio selector de cada slot de anexo preenchido contra os labels da Feature que o preenche. Segundo, avalia cada mandato de presença que o Component de um nó declara — cada anotação features.aggrega.ai/requiredType.<label> — contra o conjunto final de anexos desse nó. O analisador é o lugar a que essa verificação pertence porque é a primeira etapa que detém as duas metades da regra: as anotações da entidade Component resolvida e o conjunto de anexos que a cascata de 5 camadas produziu, contando igualmente os anexos feitos no Aggregate, no subsistema, na Release e os expandidos de anotações. Um mandato que nenhum anexo satisfaz interrompe o build; um mandato cuja declaração está malformada interrompe o build com um diagnóstico distinto, de modo que uma declaração quebrada nunca é lida como um requisito satisfeito. Terceiro, executa o portão de validação, passando a estrutura completa do grafo (incluindo todos os nós, arestas, funcionalidades anexadas e caminhos DFS pré-calculados) para um plugin de governança anexado no papel ir-verdict. A política Wasm personalizada da empresa avalia a topologia. Se o plugin Wasm retornar um array de falhas (por exemplo, ao detectar um caminho contínuo de um nó public até um nó restricted sem uma funcionalidade de proxy específica), o build é interrompido.

Renderização

  • Mecanismo: interceptação pré-renderização (injectMapping), late binding (valuesMapping) e sockets de renderização Wasm (pipeline).
  • Ação: a fase final de geração de artefatos é dividida em subfases temporais estritas que são executadas em uma ordem fixa, o que mantém a execução determinística:
    • Inject mapping (interceptação pré-renderização): o compilador Go resolve o contrato abstrato .context.inject do desenvolvedor. Em seguida, executa os templates Go de injectMapping de todas as FeatureRecipes anexadas, seguindo a ordem de execução estrita do Modelo em Cebola de 5 Camadas (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 de componente da Release). O compilador faz nativamente o deep merge dos dicionários resultantes sobre o pipe de memória .context.inject do chamador. Isso reescreve com segurança as variáveis de ambiente e as strings de conexão do chamador antes que a Recipe base as veja. Um mapping pode reescrever o que o próprio bloco inject: do chamador ou uma de suas conexões entregou; uma chave que outra Feature anexada já entregou — por meio de seu próprio mapping ou de seu próprio bloco inject: — interrompe o build nomeando os dois anexos, de modo que a ordem de execução nunca decide entre os valores de dois anexos.
    • Preâmbulo de locals: antes que qualquer template provides seja executado, o compilador avalia as entradas .locals da Recipe na ordem em que foram escritas, cada uma contra um contexto autocontido e local ao nó — .context.instance_id, .values, .infra e as entradas do mesmo bloco resolvidas até então, mas não .context.inject nem .context.uses. Uma entrada pode, portanto, ler uma irmã definida acima dela e recebe o valor resolvido dessa irmã; a ordem de autoria faz parte do contrato sempre que uma entrada lê outra, e o bloco nunca é reordenado para fazer uma referência ser resolvida. Resolver os locals primeiro é o que permite que um template provides leia .locals. O template .source da Recipe é avaliado contra o mesmo contexto depois que esses locals são resolvidos, o que mantém .locals reutilizável como atalho entre os templates de uma Recipe e permite que os autores parametrizem .source (versão do chart, caminho, registry) por fronteira.
    • Renderização base (valuesMapping da Recipe base): o compilador avalia o template valuesMapping da Recipe base. O template lê as strings interceptadas do pipe .context.inject (reescritas durante o inject mapping), e o dicionário de valores resultante é passado ao provedor que a capability da Recipe nomeia — os provedores helm e helm-chart renderizam ambos por meio do Helm — para renderizar os artefatos de infraestrutura base.
    • Parsing e validação do Workload: uma Recipe que declara workload: — conteúdo de bloco inline, ou workload: { $import: <path> } nomeando um arquivo — tem esse documento avaliado como template contra o contexto de renderização do nó, depois interpretado como YAML no formato do Workload e verificado: os bytes renderizados são validados contra o schema do Workload, o valor decodificado também é validado contra ele (os bytes carregam chaves que a decodificação descarta, e a decodificação omite um campo fornecido vazio, de modo que cada um rejeita o que o outro não consegue ver), cada entrada de attachments é verificada contra os slots que o featuresSchema do Component vinculado declara, e cada referência de recurso é verificada contra o provides resolvido do slot que ela nomeia. Uma falha aqui interrompe o build. O Workload interpretado é colocado no contexto de template como .workload, de modo que um template avaliado depois no mesmo nó possa lê-lo.
    • Avaliação de artefatos: cada entrada que uma Recipe declara em artifacts: — conteúdo inline, ou um arquivo nomeado pelo próprio $import: dessa entrada — é lida, interpretada como template, avaliada contra o contexto de template completo e carrega a proveniência do build. A projeção resultante é entregue ao provedor, que decide o formato de saída, onde a proveniência é colocada, o caminho de saída e os bytes finais. Cada arquivo emitido registra de qual forma de autoria veio, para que uma colisão de nomes de arquivo possa nomear todos os contribuidores.
    • Síntese do Workload: o Workload interpretado é entregue ao provedor que a capability da Recipe nomeia, que o traduz nos recursos nativos desse provedor. Uma Recipe que não declara workload: não tem nada a sintetizar aqui; seus arquivos vêm, em vez disso, da renderização da fonte.
    • Renderização de Feature (geração de recursos da FeatureRecipe): cada anexo no nó cuja FeatureRecipe vinculada carrega seus próprios source, workload, artifacts e/ou valuesMapping — 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 em uma única passagem, na mesma ordem do Modelo em Cebola de 5 Camadas que o inject mapping segue. Há uma única sequência sobre um único conjunto de anexos: uma Feature operacional e uma Feature de credenciais percorrem o mesmo caminho, e o que as diferencia é o que sua FeatureRecipe emite. Os .values e .infra de cada anexo são trocados para seu próprio escopo; ele herda os .locals avaliados da Recipe base; .attachment_name nomeia a instância sendo renderizada e .provides carrega os provides resolvidos do próprio anexo, o mesmo conjunto que o consumidor lê. O dicionário de valores resultante é passado ao provedor nomeado pela própria capability da FeatureRecipe, e os arquivos renderizados são acrescentados à saída da fronteira com duas coordenadas — o componente ao qual a Feature está anexada e, em seguida, o nome sob o qual está anexada —, de modo que um mesmo nome de Feature anexado a vários componentes mantém cada um separado. A forma que essas coordenadas assumem decorre do layout do próprio provedor host: um diretório <component>--<instance>/ ao lado do diretório do próprio componente, onde o alvo dá a cada contribuidor uma posição própria, e um prefixo de nome de arquivo <component>--<instance>-- onde ele lê apenas os arquivos que ficam diretamente em um diretório. As FeatureRecipes apenas de injeção — aquelas que carregam somente injectMapping, já tratadas durante o inject mapping — são ignoradas aqui. Como as subfases anteriores, a renderização de features é executada um componente por vez, de modo que um anexo normalmente é avaliado logo após o componente ao qual está anexado. Um anexo cuja FeatureRecipe declara readsCallerRenderFacts: true ou readsTargetRenderFacts: true é avaliado, em vez disso, depois que todos os componentes, e todos os anexos que não declaram nenhum dos dois, foram renderizados — de modo que cada componente que se conecta ao seu host, e cada um ao qual seu host está ligado, já foi renderizado — e sua saída vai para onde teria ido de outra forma.
    • O pipeline de plugins (execução de etapas Wasm): o compilador lê o array pipeline da Recipe e executa suas etapas na ordem declarada. Despacha o plugin Wasm nomeado de cada etapa contra os documentos renderizados do nó, aplica as operações JSON Patch RFC 6902 que a etapa retorna aos documentos que essas operações endereçam e emite os efeitos colaterais da etapa junto com eles — a superfície por trás de mutações cirúrgicas como injetar um sidecar Envoy ou montar um VolumeMount de secret. Uma etapa cujo gate when: renderiza um valor falso é ignorada como pass-through, deixando o conjunto de documentos inalterado para a próxima etapa. O URI plugin de cada etapa é resolvido antes da execução para os bytes do artefato verificado que o lockfile fixa por digest. As etapas de pipeline de uma FeatureRecipe são executadas da mesma forma, sobre os próprios documentos renderizados do anexo e, para um anexo com escopo de componente, também sobre os do componente host.

Os três tipos de entrada de Recipe chegam ao compilador: source: + valuesMapping: por meio da renderização base, workload: por meio do parsing e da síntese de workload, e artifacts: por meio da avaliação de artefatos. Quais deles podem ser entregues a um determinado provedor não é decidido subetapa por subetapa — é definido uma vez por nó, antes de qualquer despacho de renderização, a partir do contrato declarado do próprio provedor, de modo que uma Recipe cujo tipo de entrada o provedor vinculado não aceita é recusada ali, e não no meio da renderização. Consulte 16-recipe-input-composition.md para o modelo de composição dos três tipos de entrada, o tipo Workload e o mecanismo de artefatos, e Status da linguagem para saber qual provedor aceita qual tipo.

Saída nativa para GitOps

Para permanecer estritamente sem opiniões próprias quanto à forma como sua saída é aplicada, os plugins de renderização gravam os artefatos gerados em uma estrutura de diretórios limpa e isolada por fronteira (por exemplo, dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Isso permite que controladores GitOps externos (como ArgoCD ou Flux) sincronizem e apliquem a infraestrutura sem que o compilador do Aggrega jamais precise de credenciais da API de um cluster ativo.

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 desenvolvedores a reconstruir o mapeamento manualmente. Os plugins de renderização do Aggrega resolvem isso mesclando identificadores de rastreamento na superfície de metadados nativa do provedor — metadata.labels e metadata.annotations para o Kubernetes, um comentário de proveniência para o Terraform e convenções equivalentes por provedor —, de modo que cada objeto renderizado carregue um ponteiro de volta para a fonte de onde veio. O label aggrega.ai/compiler-version (documentado em governance-and-compliance §5) é uma chave de rastreamento dessa família; ao lado dele, o carimbo traz aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri e aggrega.ai/environment, e os provedores helm, helm-chart, compose, terraform e cloudformation o emitem cada um — o provedor helm-chart nos arquivos de template que uma Recipe adiciona a um chart, já que ele copia sem alterações os templates próprios do chart.

O carimbo não traz nenhuma chave que identifique a origem da funcionalidade ou o tipo de catálogo.

Duas outras superfícies de depuração acompanham o compilador. aggrega build --trace grava o estado intermediário de cada nó, passagem a passagem, em .trace/ ao lado de dist/, para o autor de uma Recipe que inspeciona o que cada etapa recebeu e produziu; e um diagnóstico que interrompe o build traz a categoria da superfície de autoria à qual pertence — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR e as demais — sempre que a falha tiver uma, de modo que aponta para o autor certo. Erros que rastreiam um campo com falha de um manifesto gerado até a linha do template que o produziu não fazem parte do compilador.

O pipeline de validadores

A fase de validação de esquemas da resolução se apoia em um pipeline de validadores que converte o conteúdo das especificações de entidades (forma compacta, JSON Schema em YAML ou misto) em um documento JSON Schema 2020-12 unificado com proveniência por folha e, em seguida, valida contra ele o conteúdo de instância escrito pelos desenvolvedores. Cinco estágios são executados em ordem como transformações puras; cada um é uma função determinística de suas entradas declaradas.

Estágio 1 — Compilação da forma compacta. O compilador percorre a árvore YAML do conteúdo de 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 se misturar em qualquer fronteira de nó por meio do escape $jsonschema:; o compilador trata o caso misto percorrendo a árvore e despachando por nó. A transformação é uma função pura: a mesma entrada em forma compacta sempre produz a mesma saída JSON Schema. Consulte language-reference/vocabulary/compact-form-authoring.md para o vocabulário de palavras-chave.

Estágio 2 — Resolução de spec.templates e $instantiate:. Para 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 é executada uma vez por carregamento da biblioteca; as entradas resolvidas são armazenadas em cache. Consulte language-reference/entities/schemalibrary.md para a forma de escrita da entidade biblioteca.

Estágio 3 — Expansão de $ref: entre documentos. Para referências a SchemaLibrary via $ref: (a forma de identidade <Library>#/schemas/<entry>), o compilador percorre a cadeia de referências em tempo de compilação propagando uma pilha de resolução; o conteúdo referenciado é incorporado ao esquema do consumidor. A expansão preserva a detecção de ciclos (ciclos interrompem o build com um erro que nomeia a cadeia), a proteção identidade-e-não-localização (uma referência que carrega um host de registry interrompe o build orientando 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 (blocos $ref: aceitam apenas a referência pura; sobrescritas do lado do consumidor se compõem via allOf: do JSON Schema). Consulte language-reference/vocabulary/cross-document-ref.md para a semântica de resolução.

Estágio 4 — Síntese da ponte para featuresSchema:. O compilador percorre o conteúdo featuresSchema: de cada entidade na ordem do autor e emite um fragmento JSON Schema que descreve a forma de um preenchimento que pode vincular cada slot de anexo, com uma palavra-chave de extensão x-aggrega-inject: em um slot que declara uma allowlist inject. Esse fragmento é compilado e verificado à parte, contra o bloco de anexos escrito, em vez de ser incorporado ao conteúdo schema: voltado ao desenvolvedor; a palavra-chave de extensão é metadado que a validação JSON Schema ignora, e nenhum estágio posterior a lê de volta do fragmento — uma verificação que precisa 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 arquiteto escreveu, e o valueSchema: / infraSchema: por aresta de um socket é compilado à parte. A síntese é uma função pura de suas entradas.

Estágio 5 — Mesclador próprio com proveniência. Para entidades que declaram extends:, o compilador percorre a cadeia de pais; o JSON Schema resolvido do pai se torna a base; as sobrescritas do filho são aplicadas por cima. Cada folha do esquema resolvido carrega uma tag de proveniência por folha (caminho do arquivo, número da linha, origem pai ou filho). A saída do mesclador é o que o motor de validação consome; o motor de validação é uma implementação de terceiros não modificada em conformidade com JSON Schema 2020-12, com um percorredor determinístico ao redor para emitir os resultados em ordem.

Os cinco estágios são executados antes que o motor de validação veja o esquema. O motor recebe um único documento JSON Schema 2020-12 resolvido mais o conteúdo de instância do desenvolvedor; ele produz um relatório de validação. O formatador de erros consulta as tags de proveniência para emitir diagnósticos voltados ao usuário que nomeiam claramente as posições no código-fonte — incluindo o arquivo de origem de uma restrição que uma Feature herdou de sua base em vez de escrevê-la ela mesma.

O pipeline do validador é executado 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 —, de modo que um achado de schema interrompe o build antes que a análise estática avalie qualquer seletor, e antes da avaliação das asserções, o que permite que os templates de asserção confiem em payloads validados.

Preservação do determinismo ao longo do pipeline

Cada estágio do pipeline de compilação preserva o invariante de saída determinística: com os mesmos arquivos-fonte, o mesmo lockfile e a mesma versão do compilador, o build produz uma saída idêntica byte a byte. O invariante é fundamental — o endereçamento por conteúdo no lockfile exige digests de artefatos estáveis; builds reproduzíveis exigem que uma release escrita no notebook do desenvolvedor A compile para a mesma saída no notebook do desenvolvedor B e na CI; a revisabilidade de diffs exige que as mudanças no código-fonte apareçam como as únicas mudanças na saída compilada.

O determinismo é preservado por um pequeno número de disciplinas que toda transformação respeita:

  • Ordem de iteração fixa. Todo percurso sobre YAML em forma de mapa itera em uma ordem fixa, porque a iteração nativa de mapas em Go é aleatória. O compilador ordena antes de iterar na maioria dos estágios (compilador da forma compacta, mesclador, resolvedor de spec.templates, formatador de erros, serializador YAML); a projeção dos slots de anexo, em vez disso, mantém a ordem do próprio autor, de modo que a ordem das propriedades de uma tabela de slots é a ordem em que ela foi escrita.
  • Nenhum carimbo de tempo incorporado. A compilação não incorpora carimbos de tempo na saída. Um build às 14h produz o mesmo artefato que um build às 2h. Os metadados de proveniência do mesclador usam arquivo:linha, não arquivo:carimbo de tempo.
  • Caminhos relativos ao workspace. Todos os caminhos na saída resolvida são relativos ao workspace; a camada de resolução de caminhos os normaliza antes que entrem em qualquer saída.
  • Nenhuma fonte aleatória, nenhum estado externo. As transformações são funções puras de suas entradas declaradas (conteúdo da entidade, cadeia de pais, lockfile). O estado externo é consultado apenas durante a resolução (obtenção de artefatos OCI), e o conteúdo resolvido é endereçado por conteúdo via digest.
  • Serialização YAML canônica. A saída é gravada em uma única forma fixa para cada entrada: a mesma ordem de chaves em todos os níveis em toda execução, com arrays e arrays enum: na ordem de entrada; indentação de 2 espaços; finais de linha Unix LF; strings sem aspas onde o YAML permite; forma booleana true/false; null omitido para campos ausentes.
  • Ordem alfabética de $defs:. As entradas $defs: de um esquema são emitidas em ordem alfabética de chave no JSON Schema resolvido. $defs: é conceitualmente um dicionário, não uma lista ordenada; a ordem alfabética torna os diffs previsíveis entre reorganizações do código-fonte.
  • O paralelismo não aparece na saída. O compilador pode paralelizar unidades independentes (entidades diferentes podem ser compiladas de forma concorrente). Os resultados paralelos são reunidos em uma estrutura determinística (por exemplo, ordenada por nome de entidade) antes de serem serializados.

Os testes de ponta a ponta do compilador compilam cada fixture várias vezes dentro de um mesmo teste e verificam que toda execução emite os mesmos arquivos com conteúdo idêntico byte a byte. Repetir a compilação é o que detecta um vazamento da ordem de iteração de mapas ou uma iteração sobre um conjunto não ordenado, que produz saída estável na maioria das execuções e diverge ocasionalmente. Os testes são executados com o restante da suíte de testes do compilador.

O invariante de saída determinística se aplica em tempo de build: os mesmos arquivos-fonte + o mesmo lockfile + a mesma versão do compilador resultam em saída idêntica byte a byte. A propriedade complementar em tempo de lock (os mesmos arquivos-fonte + o mesmo estado do registry resultam no mesmo lockfile) é mais fraca — registries são mutáveis (novas versões podem ser publicadas; sidecars podem ser adicionados; metadados por componente podem evoluir), então duas invocações de lock sobre os mesmos arquivos-fonte em momentos diferentes podem produzir lockfiles diferentes. Esse é o propósito do lockfile, espelhando as convenções de npm, Cargo e Go. A partir de um lockfile novo, o build produz saída determinística. A separação entre os dois momentos é o que torna tolerável a mutabilidade do lado do registry: um sidecar publicado no tempo T2 altera a próxima invocação de lock; ele não altera builds feitos contra o lockfile gerado em T1.