Invariantes arquiteturais
Estes oito invariantes são as regras fundadoras do Aggrega. Mantêm-se de versão para versão, no núcleo do compilador, na camada de esquemas, no catálogo e na superfície de plugins Wasm. Cada decisão de design, cada funcionalidade e cada entidade criada respeita-os.
Os invariantes são referidos por número noutros capítulos de arquitetura. Quando um capítulo posterior diz «segundo o Invariante 2» ou «pela regra do String Pipe (Invariante 3)», aponta para aqui.
1. O compilador é neutro quanto ao conteúdo, sem opiniões próprias e agnóstico em relação à intenção do utilizador
O compilador Aggrega é um encaminhador de texto Ahead-Of-Time (AOT). Analisa YAML, percorre grafos, avalia interseções de etiquetas e encaminha cadeias de origens para destinos. Não policia o que os autores colocam em values, parameters, infra, provides ou locals. Não impõe convenções de nomenclatura, convenções de portas nem as etiquetas semânticas que um arquiteto inventa.
Muitas regras que soam a regras do compilador — o Zero-Port Contract, o estilo de catálogo Naked-Base / Flavored-Edges, a escolha da primitiva operacional que se adequa a um dado componente — são contratos sociais: boas práticas com vias de escape, mantidas pelos arquitetos de plataforma que criam o catálogo da biblioteca padrão. O compilador não as interpreta.
Este invariante diz respeito ao que o compilador infere do conteúdo criado pelo utilizador, e esse âmbito é tudo o que abrange. Algumas chaves são do próprio Aggrega — reservadas, com os valores que aceitam escritos no esquema publicado — e o esquema verifica-as da mesma forma que verifica qualquer outro campo declarado. component.aggrega.ai/type é uma delas: o seu conjunto de valores é fechado, e um documento com um valor fora dele é recusado quando é carregado. Trata-se da plataforma a declarar o que significa a sua própria chave, não do compilador a ler significado numa cadeia escrita pelo utilizador, e deixa todas as chaves próprias do utilizador exatamente tão livres de policiamento como este invariante diz. Um catálogo que classifique componentes num eixo que o Aggrega não define cria a sua própria chave de etiqueta, que o esquema aceita com qualquer valor de cadeia e que todas as superfícies de seletores leem de forma idêntica.
O que o compilador impõe é restrito: validação de esquemas, análise de YAML, construção do grafo, avaliação de templates e o simples encaminhamento de texto do contrato de injeção. Tudo o resto é convenção, imposta no momento da criação do catálogo ou dentro do socket de governação Wasm opcional.
As empresas que criam os seus próprios catálogos internos são explicitamente livres de quebrar as convenções da biblioteca padrão. O compilador aceita o que escreverem, desde que passe a validação de esquemas. A arquitetura promove boas práticas; não constrói prisões.
2. Pureza AOT: o compilador não tem acesso a informação de tempo de execução
O Aggrega é um compilador Ahead-Of-Time. Em tempo de compilação:
- Não se autentica em APIs cloud.
- Não obtém endereços IP ativos, nomes DNS nem URL gerados pela cloud.
- Não resolve segredos em texto simples — os segredos permanecem ponteiros de metadados ao longo de toda a Representação Intermédia.
- Não conhece o estado de execução dos clusters ou serviços de destino.
- Não pode obter dados que ainda não existem (endpoints pós-aprovisionamento, portas atribuídas dinamicamente, nomes de recursos gerados automaticamente).
Tudo o que depende do estado de execução é expresso como uma cadeia de ponteiro determinística — um nome DNS estável, uma cadeia de interpolação Terraform, uma referência a um recurso CloudFormation — fornecida pela Recipe de Ops. O compilador encaminha o ponteiro sem o resolver. O ambiente de execução (o cluster, o gestor de estado de IaC) resolve os dados físicos finais.
Esta é a verdadeira inversão de controlo: os programadores ditam um contrato de injeção no Aggregate, o compilador liga ponteiros determinísticos antecipadamente e o ambiente de execução resolve os dados físicos finais. Os requisitos que precisam genuinamente de resolução em tempo de execução pertencem à pipeline Wasm de uma Recipe de Ops, não ao núcleo do compilador.
3. O String Pipe: o compilador não pode inferir significado
O compilador não interpreta o que significam os valores encaminhados. Quando o Component A usa o Component B, o compilador pega no escalar que a Recipe do Component B produz através de provides — uma cadeia, um número ou um booleano — e encaminha-o para o contexto da Recipe do Component A, convertido em cadeia de forma determinística na fronteira de injeção. Seja esse valor um FQDN, um nome de anfitrião local, um literal IP, um número de porta ou um DSN formatado por Wasm, não faz diferença: o compilador não valida a encaminhabilidade, a correção do protocolo nem a adequação semântica.
Daqui decorrem duas consequências:
- O compilador não adivinha a finalidade de um componente a partir do nome. Um componente chamado
database-productionnão é reconhecido como base de dados. As etiquetas de tipo semântico comocomponent.aggrega.ai/type(quando presentes) são metadados opacos consumidos para a correspondência de etiquetas, não lógica de ramificação do compilador. - O compilador não distingue um nome de anfitrião de um nome de base de dados, de um número de porta ou de um valor opaco arbitrário. São todos entradas escalares no contexto de injeção, entregues como cadeias.
A tríade de topologia — provides na Recipe produtora, uses no Aggregate consumidor, inject na aresta — é o contrato de injeção. O compilador avalia etiquetas e passa cadeias; a interpretação é o contrato de criação entre a Recipe e o Component.
4. Sem infraestrutura fantasma: o compilador nunca inventa computação nem funcionalidades
O compilador nunca injeta silenciosamente computação, Features, anotações, proxies de encaminhamento ou qualquer outro recurso que o autor não tenha declarado explicitamente. As violações de políticas produzem barreiras de proteção ruidosas — a compilação interrompe-se com um erro específico que indica ao autor o que corrigir, no documento que escreveu — e não mutações silenciosas que produzem mistérios de infraestrutura no momento da depuração.
Os recursos entram no grafo através de declarações explícitas no momento da criação:
- O Aggregate do programador (componentes, arestas
uses, anexações de Feature). - As anexações de Feature da Release (adições ao nível do operador).
- A expansão orientada por anotações (o Manifest declara vinculações anotação → Feature; a anotação num Component ou numa fronteira é uma declaração explícita).
- A produção de recursos ao nível da Recipe: a renderização de
sourceda Recipe produz o artefacto principal; a síntese deworkloademite a forma de implantação específica do fornecedor (Pod spec, serviço Compose, etc.); as entradasartifacts:(inline ou carregadas com$import:) emitem manifestos auxiliares intrínsecos à Recipe; a geração de recursos da FeatureRecipe emite recursos auxiliares por Feature, desencadeados por uma anexação explícita de Feature.
Os caminhos ao nível da Recipe são declarações do momento da criação a um passo de distância: o autor da Recipe escreve source / workload / artifacts / valuesMapping contra um contrato de Component, e o Aggregate do programador seleciona os Components que participam. Um recurso que apareça na saída renderizada remonta a uma declaração no Aggregate, na Release, numa vinculação de anotação ou na criação da Recipe que os tipos de componentes do Aggregate selecionaram.
A síntese transforma formas declaradas pelo autor em formatos de saída específicos do fornecedor. Uma especificação de Workload criada como um mapa de contentores pode ser renderizada como uma Pod spec Kubernetes, um bloco de serviço Compose ou um módulo Terraform — a transformação é orientada pelo fornecedor, mas os recursos remontam à declaração de Workload do autor.
O socket de governação transporta um papel por anexação, e é o papel — não o tipo do plugin — que fixa o que uma anexação pode fazer a uma compilação. Um plugin de governação anexado num papel de veredicto — que analisa o grafo da IR (ir-verdict) ou os artefactos renderizados (render-verdict) — pode rejeitar uma compilação, mas não a pode alterar. Se esse veredicto quiser que seja adicionado um recurso, faz falhar a compilação com uma indicação de correção, para que o próprio autor adicione o recurso; o host lê a saída de um veredicto apenas como aceitar-ou-rejeitar e nunca a aplica como alteração, pelo que uma reescrita não solicitada do grafo para o pôr em conformidade — exatamente a infraestrutura fantasma que este invariante proíbe — não pode vir de um papel de veredicto. Um plugin de governação anexado num papel de transformação (label-transform ou annotation-transform) é a exceção restrita e explícita: um operador que anexa um — de forma opcional, através da configuração plugins.governance do espaço de trabalho — declarou essa transformação, pelo que as alterações que faz são declaração explícita, com o mesmo estatuto que a expansão orientada por anotações, e não injeção silenciosa. A distinção é o convite: um veredicto não solicitado não pode reescrever a compilação, enquanto uma transformação anexada explicitamente pode, porque o operador a pediu. Como uma transformação molda a saída renderizada, é fixada no lockfile como qualquer plugin que molde a saída — a transformação aplicada fica fixa no momento do pull, pelo que alterá-la implica voltar a fazer pull, e não uma mudança silenciosa entre compilações; um veredicto não molda nenhuma saída e não é fixado.
5. O Aggregate é a superfície de criação; a Release não pode declarar values:
O esquema da Release proíbe mecanicamente um bloco values:. Os operadores não podem escrever values num Component nem numa Feature a partir de uma Release. Trata-se de imposição de esquema ao nível do JSON Schema — não de um contrato social, nem de uma convenção — e é ruidosa: cada documento de entidade é validado contra o esquema do seu tipo quando é carregado, pelo que uma Release que contenha values: interrompe a compilação com um diagnóstico que indica o ficheiro e a chave infratora, em vez de ser ignorada silenciosamente.
Isto não significa que os valores sejam idênticos entre ambientes. O caminho suportado para a variação por ambiente é o Parameter Hoisting:
- O programador expõe um campo tipado
parameters.*no Aggregate. - O template
valuesdo Component referencia-o:storage_size: "{{ .parameters.db_size }}". - A Release cumpre o parâmetro:
parameters: { db_size: "100Gi" }. - A saída renderizada reflete o valor específico do ambiente.
O Aggregate permanece a fonte única de verdade quanto aos valores expostos para variação entre ambientes (a declaração parameters) e à forma como fluem para os valores dos componentes (a referência no template). A Release cumpre; não substitui.
Duas outras restrições protegem o mesmo invariante:
- Quando uma Release usa
extends, declarar um ponteiroaggregate:é proibido pelo esquema. A Release filha tem de implantar a mesma intenção do programador que a sua mãe. - A Release não pode introduzir computação que o Aggregate não declarou, nem pode redirecionar uma aresta que o programador declarou. Dentro dos sockets que o arquiteto declarou, a Release pode ligar e configurar arestas entre componentes existentes: define o
infrapor aresta numa aresta que o programador ligou, ou liga uma aresta, num socket declarado mas não vinculado, a um componente existente. Não pode declararvaluespor aresta (esses ficam no Aggregate), vincular um socket que ousesSchemado Component não declara, nem apontar uma aresta para um componente que não existe — cada um destes casos interrompe a compilação. Atenção à declaração a que se refere essa oração do meio: o socket tem de aparecer nousesSchemado Component do catálogo. Um autor de Aggregate pode nomear um socket que o seu tipo de componente não declara, e a superfície da Release não é deliberadamente aberta da mesma forma — um operador liga e configura dentro de uma arquitetura, em vez de inventar uma.
A configuração de ligação por aresta tem âmbito no consumidor: os values e o infra transportados numa aresta só aparecem no contexto de renderização do nó que criou a aresta, nunca no contexto do destino. A saída renderizada de um componente é, portanto, invariante em relação às ligações que outros componentes lhe fazem — ligar ou configurar uma aresta para um destino nunca perturba o que a Recipe do destino renderiza. O único sítio onde essas ligações são visíveis é uma Feature anexada ao destino: a sua FeatureRecipe pode ler que componentes usam o destino, pelo que os recursos que emite — uma política que admita exatamente os chamadores declarados, por exemplo — seguem as ligações, enquanto a saída do próprio destino não. Mesmo aí, os values e o infra por aresta ficam com o consumidor.
6. A fronteira da ABI WebAssembly: a inteligência específica do domínio vive em Wasm
O binário host Go não contém nenhuma lógica específica de cloud ou de infraestrutura. Toda a inteligência específica do domínio, a renderização de templates e a formatação vivem estritamente dentro de plugins WebAssembly executados pelo runtime Wazero incorporado. O host Go orquestra a pipeline e passa payloads através da ABI para os guests Wasm como ponteiros de memória, na codificação que cada socket transporta.
Daqui decorrem dois corolários:
- A lógica específica de cada Provider (renderização específica do Helm, formatação específica do Terraform, fusão específica do Compose) nunca reside no núcleo do compilador Go. O compilador resolve o nome do provider que uma Recipe declara em
spec.capabilitypara o Plugin de renderização de providers que o serve e despacha o nó para esse plugin; a tradução em si corre inteiramente no convidado Wasm. O anfitrião não contém código Go por provider para um provider normal, pelo que não há nada em processo a que recorrer — um nome de provider que não resolve para nenhum Plugin que o sirva interrompe a compilação em vez de renderizar alguma predefinição incorporada. - A lógica de políticas (regras de segurança, verificações de conformidade, cálculos FinOps) nunca vive no núcleo do compilador Go. As políticas pertencem ao socket de governação Wasm que as empresas escolhem ativar — um plugin anexado num papel de veredicto (
ir-verdict/render-verdict) para aceitar ou rejeitar uma compilação, ou num papel de transformação (label-transform/annotation-transform) para moldar etiquetas ou anotações.
A fronteira da ABI mantém o núcleo Go compacto, auditável e agnóstico em relação à cloud. Trocar a lógica de renderização de um fornecedor é uma troca de artefacto Wasm, não uma recompilação do próprio Aggrega.
7. Separação de responsabilidades (divisão em quatro domínios) — orientação, não prisão
A orientação de design do Aggrega separa a criação em quatro domínios:
- Intenção do programador — Aggregate.
- Arquiteto de plataforma — entidades de catálogo Component e Feature.
- Platform Ops — Recipe, FeatureRecipe, Plugin (incluindo o Plugin de renderização de fornecedor).
- Operador de plataforma — Manifest, Release.
A implantação típica que funciona bem segue esta divisão: os programadores escrevem intenção de aplicação, não infraestrutura física; o Ops escreve infraestrutura física, não lógica de aplicação. O Aggrega foi concebido para ser usado desta forma, e a documentação oficial, os exemplos e o catálogo da biblioteca padrão são criados de acordo com esta divisão.
A divisão em quatro domínios é orientação e enquadramento de design, não imposição do compilador. O compilador (segundo o Invariante 1) é sem opiniões próprias. Os utilizadores são livres de:
- Fundir papéis (uma pessoa a escrever tanto Aggregates como Recipes).
- Misturar responsabilidades (arquitetos a codificar etiquetas de conformidade diretamente em Components
core/*quando os catálogos empresariais o exigem). - Atravessar fronteiras de domínio (programadores a usar Parameter Hoisting para injetar preocupações de infraestrutura no Aggregate quando o código legado o exige).
O compilador aceita qualquer padrão de criação que passe a validação de esquemas. A arquitetura promove boas práticas; as restrições a nível de esquema (como a proibição de values: na Release, no Invariante 5) são os únicos cruzamentos de domínio que o compilador efetivamente rejeita. Toda a restante separação é um contrato social mantido pelos autores do catálogo e, quando as empresas optam por isso, pelo socket de governação Wasm.
8. Saída determinística
Perante uma entrada idêntica, o compilador produz uma saída idêntica byte a byte. Duas compilações do mesmo Aggregate + Release + Manifest contra o mesmo catálogo produzem artefactos renderizados iguais byte a byte.
Este é o contrato de que dependem as ferramentas GitOps e os fluxos de revisão baseados em diff. Um pull request que não alterou a entrada não deve produzir nenhum diff na saída renderizada. Um pull request que alterou a entrada deve mostrar apenas o diff implicado por essa alteração — sem reordenações espúrias, sem variações de timestamps, sem artefactos de iteração de mapas.
A saída determinística é mantida através de três disciplinas:
- Mapas ordenados pelo autor: todo o mapa cuja ordem de iteração possa afetar a saída renderizada usa um contentor de mapa ordenado, para que a iteração siga a ordem de declaração do autor e não a ordem de hash.
- Nenhum conteúdo de relógio de parede ou aleatório nos artefactos renderizados, a menos que o autor o tenha injetado explicitamente através da entrada do template.
- A renderização é pura: a mesma invocação do guest Wasm com a mesma entrada produz a mesma saída.
A flag --trace do compilador (ver language-reference/cli/aggrega-build.md) dá aos autores e operadores uma superfície de verificação para este invariante. Duas compilações da mesma entrada com --trace ativado produzem dumps de rastreio idênticos byte a byte; qualquer diff por passagem localiza uma regressão. O determinismo não é apenas uma propriedade do momento do lançamento — é observável em cada estado intermédio do compilador através da disposição do rastreio por nó.
A saída determinística é o contrato que torna o Aggrega seguro para usar como fonte de verdade num ciclo GitOps.
Âmbito da invariância entre os níveis de resolução
A garantia de saída idêntica byte a byte abrange os artefactos fixados no lockfile — entidades resolvidas através de artefactos de registo cujos digests o lockfile regista (o nível de registo do modelo de resolução de entidades em três níveis). Quando uma compilação lê os ficheiros que uma Release nomeia por caminho (caminhos locais que começam por ./ ou ../) ou entidades em diretórios de catálogo do espaço de trabalho (catalog_dirs:, no nível do espaço de trabalho e da cache), a invariância depende de esses ficheiros permanecerem inalterados entre compilações. O lockfile regista uma entidade num diretório de catálogo do espaço de trabalho pelo digest do seu documento e dos ficheiros que declara, pelo que uma compilação se interrompe numa entidade que tenha mudado desde o pull, em vez de a renderizar — com uma exceção: uma Recipe ou FeatureRecipe que o Manifest nomeia através de uma referência que é também o nome de um Component ou de uma Feature é registada sob essa referência como o Component ou a Feature, pelo que as suas entradas são mantidas apenas pelas fixações no lock ao lado dela, e uma edição ao seu próprio documento não é detetada. Manter os ficheiros como estavam é responsabilidade do sistema de controlo de versões (normalmente o Git).
Uma referência a um caminho local cujo ficheiro subjacente muda entre duas compilações produz um diff legítimo na saída renderizada, mesmo que a forma da entrada do compilador não tenha mudado — a garantia de saída determinística é preservada (a mesma entrada em bytes → a mesma saída em bytes), mas as entradas diferem porque o ficheiro local mudou. Os catálogos que precisam de invariância entre compilações para todas as origens fazem pull dos artefactos de um registo para a cache fixada no lockfile, em vez de os lerem de um caminho local ou de um diretório do espaço de trabalho; o lockfile é a âncora da identidade byte a byte.