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

Invariantes arquiteturais

Estas oito invariantes são as regras fundadoras do Aggrega. Elas valem em todas as versões, no núcleo do compilador, na camada de schemas, no catálogo e na superfície de plugins Wasm. Toda decisão de design, toda funcionalidade e toda entidade escrita as respeitam.

Os demais capítulos de arquitetura fazem referência aos invariantes pelo número. Quando um capítulo posterior diz “conforme o Invariante 2” ou “pela regra do String Pipe (Invariante 3)”, ele aponta para cá.

1. O compilador é neutro quanto ao conteúdo, sem opiniões próprias e agnóstico em relação à intenção do usuário

O compilador do Aggrega é um roteador de texto Ahead-Of-Time (AOT). Ele analisa YAML, percorre grafos, avalia interseções de rótulos e canaliza strings das origens para os destinos. Ele não fiscaliza o que os autores colocam em values, parameters, infra, provides ou locals. Ele não impõe convenções de nomenclatura, convenções de portas nem os rótulos semânticos que um Architect inventa.

Muitas regras que parecem regras do compilador — o contrato Zero-Port, o estilo de catálogo Naked-Base / Flavored-Edges, a escolha de qual primitiva operacional se ajusta a um determinado componente — são contratos sociais: boas práticas com vias de escape, mantidas pelos arquitetos de plataforma que escrevem o catálogo da biblioteca padrão. O compilador não as interpreta.

Este invariante trata do que o compilador infere do conteúdo que você escreve, e esse escopo é tudo o que ele abrange. Um punhado de chaves pertence ao próprio Aggrega — reservadas, com os valores que aceitam escritos no schema publicado — e o schema as verifica da mesma forma que verifica qualquer outro campo declarado. component.aggrega.ai/type é uma delas: seu conjunto de valores é fechado, e um documento que traga um valor fora dele é recusado ao ser carregado. É a plataforma declarando o que sua própria chave significa, não o compilador atribuindo significado a uma string que você escreveu, e isso deixa cada chave sua exatamente tão sem fiscalização quanto este invariante diz. Um catálogo que classifica componentes em um eixo que o Aggrega não define escreve sua própria chave de rótulo, que o schema aceita com qualquer valor de string e que toda superfície de seletor lê da mesma forma.

O que o compilador de fato impõe é restrito: validação de schema, parsing de YAML, construção do grafo, avaliação de templates e o simples roteamento de texto do contrato de injeção. Todo o resto é convenção, imposta no momento da escrita do catálogo ou dentro do socket de governança Wasm opcional.

Empresas que escrevem seus próprios catálogos internos são explicitamente livres para quebrar as convenções da biblioteca padrão. O compilador aceita o que elas escreverem, desde que passe na validação de schema. A arquitetura promove boas práticas; ela não constrói prisões.

2. Pureza AOT: o compilador não tem acesso a informações de runtime

O Aggrega é um compilador Ahead-Of-Time. Em tempo de compilação:

  • Ele não se autentica em APIs de nuvem.
  • Ele não busca endereços IP ativos, nomes DNS nem URLs geradas pela nuvem.
  • Ele não resolve segredos em texto puro — os segredos permanecem como ponteiros de metadados em toda a representação intermediária (Intermediate Representation).
  • Ele não conhece o estado de runtime dos clusters ou serviços de destino.
  • Ele não pode buscar dados que ainda não existem (endpoints posteriores ao provisionamento, portas atribuídas dinamicamente, nomes de recursos gerados automaticamente).

Tudo o que depende do estado de runtime é expresso como uma string de ponteiro determinística — um nome DNS estável, uma string de interpolação do Terraform, uma referência a recurso do CloudFormation — fornecida pela Ops Recipe. O compilador repassa o ponteiro sem resolvê-lo. O ambiente de runtime (o cluster, o gerenciador de estado de IaC) resolve os dados físicos finais.

Esta é a verdadeira inversão de controle (True Control Inversion): os desenvolvedores ditam um Injection Contract no Aggregate, o compilador conecta ponteiros determinísticos antecipadamente e o ambiente de runtime resolve os dados físicos finais. Requisitos que realmente precisam de resolução em runtime pertencem ao pipeline Wasm de uma Ops Recipe, não ao núcleo do compilador.

3. O String Pipe: o compilador não consegue inferir significado

O compilador não interpreta o significado dos valores que canaliza. Quando o Component A usa o Component B, o compilador pega o escalar que a Recipe do Component B produz via provides — uma string, um número ou um booleano — e o canaliza para o contexto da Recipe do Component A, convertido em string de forma determinística na fronteira de injeção. Se esse valor é um FQDN, um hostname local, um IP literal, um número de porta ou um DSN formatado pelo Wasm, não faz diferença: o compilador não valida a roteabilidade, a correção do protocolo nem a adequação semântica.

Daí decorrem duas consequências:

  • O compilador não adivinha a finalidade de um componente pelo nome. Um componente chamado database-production não é reconhecido como banco de dados. Rótulos de tipo semântico como component.aggrega.ai/type (quando presentes) são metadados opacos usados na correspondência de rótulos, não lógica de ramificação do compilador.
  • O compilador não distingue um hostname de um nome de banco de dados, de um número de porta ou de um valor opaco arbitrário. Todos são entradas escalares no contexto de injeção, entregues como strings.

A tríade de topologia — provides na Recipe produtora, uses no Aggregate consumidor, inject na aresta — é o Injection Contract. O compilador avalia rótulos e repassa strings; a interpretação é o contrato de autoria entre Recipe e Component.

4. Nenhuma infraestrutura fantasma: o compilador nunca inventa computação nem funcionalidades

O compilador nunca injeta silenciosamente computação, Features, anotações, proxies de roteamento ou qualquer outro recurso que o autor não tenha declarado explicitamente. Violações de política produzem guardrails ruidosos (Loud Guardrails) — o build é interrompido com um erro específico que diz ao autor o que corrigir, no documento que ele escreveu — e não mutações silenciosas que produzem mistérios de infraestrutura na hora da depuração.

Os recursos entram no grafo por meio de declarações explícitas em tempo de autoria:

  • O Aggregate do desenvolvedor (componentes, arestas uses, vinculações de Feature).
  • As vinculações de Feature da Release (acréscimos no nível do operador).
  • A expansão orientada por anotações (o Manifest declara vinculações anotação → Feature; a anotação em um Component ou em uma fronteira é uma declaração explícita).
  • A produção de recursos no nível da Recipe: a renderização de source da Recipe produz o artefato principal; a síntese de workload emite o formato de implantação específico do provedor (spec de Pod, serviço do Compose etc.); as entradas de artifacts: (inline ou carregadas via $import:) emitem manifestos auxiliares intrínsecos à Recipe; a geração de recursos das FeatureRecipe emite recursos auxiliares por Feature, acionados por uma vinculação explícita de Feature.

Os caminhos no nível da Recipe são declarações em tempo de autoria a um passo de distância: o autor da Recipe escreve source / workload / artifacts / valuesMapping contra um contrato de Component, e o Aggregate do desenvolvedor seleciona quais Components participam. Um recurso que aparece na saída renderizada remonta a uma declaração no Aggregate, na Release ou em uma vinculação de anotação, ou à autoria da Recipe que os tipos de componente do Aggregate selecionaram.

A síntese transforma formatos declarados pelo autor em formatos de saída específicos do provedor. Uma spec de Workload escrita como um mapa de contêineres pode ser renderizada como uma spec de Pod do Kubernetes, um bloco de serviço do Compose ou um módulo do Terraform — a transformação é orientada pelo provedor, mas os recursos remontam à declaração de Workload do autor.

O socket de governança carrega um papel por vinculação, e é o papel — não o tipo do plugin — que define o que uma vinculação pode fazer com um build. Um plugin de governança vinculado em um papel de veredito — que revisa o grafo de IR (ir-verdict) ou os artefatos renderizados (render-verdict) — pode rejeitar um build, mas não pode alterá-lo. Se esse veredito quiser que um recurso seja adicionado, ele faz o build falhar com uma indicação de correção para que o próprio autor adicione o recurso; o host lê a saída de um veredito apenas como aceitação ou rejeição e nunca a aplica como alteração, de modo que uma reescrita não solicitada do grafo para torná-lo conforme — exatamente a infraestrutura fantasma que este invariante proíbe — não pode vir de um papel de veredito. Um plugin de governança vinculado em um papel de transformação (label-transform ou annotation-transform) é a exceção restrita e explícita: um operador que vincula um — de forma opcional, pela configuração plugins.governance do workspace — declarou essa transformação, então as alterações que ela faz são uma declaração explícita, com o mesmo status da expansão orientada por anotações, e não uma injeção silenciosa. A distinção é o convite: um veredito não solicitado não pode reescrever o build, enquanto uma transformação vinculada explicitamente pode, porque o operador a pediu. Como uma transformação molda a saída renderizada, ela é fixada no lockfile como todo plugin que molda a saída — a transformação aplicada é definida no momento do pull, então alterá-la significa fazer um novo pull, e não uma mudança silenciosa entre builds; um veredito não molda nenhuma saída e não é fixado.

5. O Aggregate é a superfície de autoria; a Release não pode declarar values:

O schema da Release proíbe mecanicamente um bloco values:. Os operadores não podem escrever values em um Component ou em uma Feature a partir de uma Release. Trata-se de imposição do schema no nível do JSON Schema — não um contrato social, não uma convenção — e ela é ruidosa: todo documento de entidade é validado contra o schema do seu tipo ao ser carregado, de modo que uma Release que traga values: interrompe o build com um diagnóstico que indica o arquivo e a chave problemática, em vez de ser ignorada silenciosamente.

Isso não significa que os valores sejam idênticos em todos os ambientes. O caminho suportado para a variação por ambiente é o içamento de parâmetros (Parameter Hoisting):

  1. O desenvolvedor expõe um campo tipado parameters.* no Aggregate.
  2. O template values do Component faz referência a ele: storage_size: "{{ .parameters.db_size }}".
  3. A Release preenche o parâmetro: parameters: { db_size: "100Gi" }.
  4. A saída renderizada reflete o valor específico do ambiente.

O Aggregate continua sendo a fonte única da verdade sobre quais valores são expostos para variação por ambiente (a declaração parameters) e como eles fluem para os valores do componente (a referência no template). A Release preenche; ela não sobrescreve.

Duas outras restrições protegem o mesmo invariante:

  • Quando uma Release usa extends, declarar um ponteiro aggregate: é proibido pelo schema. A Release filha deve implantar a mesma intenção do desenvolvedor (Developer Intent) que sua Release pai.
  • A Release não pode introduzir computação que o Aggregate não declarou, nem redirecionar uma aresta que o desenvolvedor declarou. Dentro dos sockets que o Architect declarou, a Release pode conectar e configurar arestas entre componentes existentes: ela define o infra por aresta em uma aresta que o desenvolvedor conectou, ou conecta a um componente existente uma aresta para um socket declarado mas não vinculado. Ela não pode declarar values por aresta (esses permanecem no Aggregate), vincular um socket que o usesSchema do Component não declara nem apontar uma aresta para um componente que não existe — cada um desses casos interrompe o build. Observe qual declaração essa cláusula do meio quer dizer: o socket deve aparecer no usesSchema do Component do catálogo. O autor de um Aggregate pode nomear um socket que seu tipo de componente não declara, e a superfície da Release propositalmente não é aberta da mesma forma — um operador conecta e configura dentro de uma arquitetura, em vez de inventar uma.

A configuração de conexão por aresta tem escopo no consumidor: os values e o infra carregados em uma aresta aparecem apenas no contexto de renderização do nó que escreveu a aresta, nunca no contexto do destino. A saída renderizada de um componente é, portanto, invariante em relação às conexões que outros componentes fazem com ele — conectar ou configurar uma aresta para um destino nunca altera o que a Recipe do destino renderiza. O único lugar em que essas conexões são visíveis é uma Feature vinculada ao destino: sua FeatureRecipe pode ler quais componentes usam o destino, de modo que os recursos que ela emite — por exemplo, uma política que admite exatamente os chamadores declarados — acompanham a conexão, enquanto a saída do próprio destino não. Mesmo ali, os values e o infra por aresta ficam com o consumidor.

6. A fronteira ABI do WebAssembly: a inteligência específica do domínio vive no Wasm

O binário host em Go não contém nenhuma lógica específica de nuvem 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 embutido. O host Go orquestra o pipeline e passa os payloads através da ABI para os convidados Wasm como ponteiros de memória, na codificação que cada socket carrega.

Daí decorrem dois corolários:

  • A lógica específica do Provider (renderização específica do Helm, formatação específica do Terraform, mesclagem específica do Compose) nunca vive no núcleo do compilador Go. O compilador resolve o nome do provedor que uma Recipe declara em spec.capability para o Plugin de renderização de provedor que o atende e despacha o nó para esse plugin; a tradução em si roda inteiramente no convidado Wasm. O host não contém código Go por provedor para um provedor padrão, então não há nada no processo a que recorrer — um nome de provedor que não se resolve em nenhum Plugin que o atenda interrompe o build em vez de renderizar algum padrão embutido.
  • A lógica de políticas (regras de segurança, verificações de conformidade, cálculos de FinOps) nunca vive no núcleo do compilador Go. As políticas pertencem ao socket de governança Wasm que as empresas optam por ativar — um plugin vinculado em um papel de veredito (ir-verdict / render-verdict) para aceitar ou rejeitar um build, ou em um papel de transformação (label-transform / annotation-transform) para moldar rótulos ou anotações.

A fronteira ABI mantém o núcleo Go compacto, auditável e agnóstico em relação à nuvem. Trocar a lógica de renderização de um provedor é trocar um artefato Wasm, não recompilar o próprio Aggrega.

7. Separação de responsabilidades (divisão em quatro domínios) — orientação, não prisão

As diretrizes de design do Aggrega separam a autoria em quatro domínios:

  • Developer Intent — Aggregate.
  • Platform Architect — entidades de catálogo Component e Feature.
  • Platform Ops — Recipe, FeatureRecipe, Plugin (incluindo o Plugin de renderização de provedor).
  • Platform Operator — Manifest, Release.

A implantação típica e que funciona bem segue essa divisão: os desenvolvedores escrevem a intenção da aplicação, não a infraestrutura física; o time de Ops escreve a infraestrutura física, não a lógica da aplicação. O Aggrega foi projetado para ser usado assim, e a documentação oficial, os exemplos e o catálogo da biblioteca padrão são escritos de acordo com essa divisão.

A divisão em quatro domínios é orientação e enquadramento de design, não imposição do compilador. O compilador (conforme o Invariante 1) é sem opiniões próprias. Os usuários são livres para:

  • Acumular papéis (uma só pessoa escrevendo tanto Aggregates quanto Recipes).
  • Misturar responsabilidades (Architects fixando rótulos de conformidade diretamente em Components core/* quando os catálogos corporativos exigem).
  • Cruzar fronteiras de domínio (desenvolvedores usando o içamento de parâmetros para injetar aspectos de infraestrutura no Aggregate quando o código legado exige).

O compilador aceita qualquer padrão de autoria que passe na validação de schema. A arquitetura promove boas práticas; restrições no nível do schema (como a proibição de values: na Release do Invariante 5) são os únicos cruzamentos de domínio que o compilador de fato rejeita. Toda outra separação é um contrato social mantido pelos autores de catálogos e, onde as empresas optam por ativá-lo, pelo socket de governança Wasm.

8. Saída determinística

Dada 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 geram artefatos renderizados que são iguais byte a byte.

Esse é o contrato em que se apoiam as ferramentas de 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ção espúria, sem oscilação de timestamps, sem artefatos de iteração de mapas.

A saída determinística é mantida por meio de três disciplinas:

  • Mapas ordenados pelo autor: todo mapa cuja ordem de iteração possa afetar a saída renderizada usa um contêiner de mapa ordenado, de modo que a iteração siga a ordem de declaração do autor e não a ordem do hash.
  • Nenhum conteúdo baseado em relógio ou aleatório nos artefatos renderizados, a menos que o autor o tenha injetado explicitamente pela entrada do template.
  • A renderização é pura: a mesma invocação de um convidado Wasm com a mesma entrada produz a mesma saída.

A flag --trace do compilador (veja language-reference/cli/aggrega-build.md) dá a autores e operadores uma superfície de verificação para este invariante. Duas compilações da mesma entrada com --trace ativado produzem dumps de trace idênticos byte a byte; qualquer diff em uma passagem localiza uma regressão. O determinismo não é apenas uma propriedade do momento da liberação — ele é observável em todo estado intermediário do compilador por meio do layout de trace por nó.

A saída determinística é o contrato que torna o Aggrega seguro para uso como fonte da verdade em um ciclo de GitOps.

Escopo da invariância entre os níveis de resolução

A garantia de saída idêntica byte a byte abrange os artefatos fixados no lockfile — entidades resolvidas por meio de artefatos de registry cujos digests o lockfile registra (o nível de registry do modelo de resolução de entidades em três níveis). Quando um build lê os arquivos que uma Release nomeia por caminho (caminhos locais que começam com ./ ou ../) ou entidades em diretórios de catálogo do workspace (catalog_dirs:, no nível de workspace e cache), a invariância depende de esses arquivos permanecerem inalterados entre builds. O lockfile registra uma entidade em um diretório de catálogo do workspace pelo digest do seu documento e dos arquivos que ela declara, de modo que um build é interrompido diante de uma entidade alterada desde o pull, em vez de renderizá-la — com uma exceção: uma Recipe ou FeatureRecipe que o Manifest nomeia por uma referência que também é o nome de um Component ou de uma Feature é registrada sob essa referência como o Component ou a Feature, então suas entradas ficam presas apenas pelos pins do lock ao lado dela, e uma edição em seu próprio documento não é detectada. Manter os arquivos como estavam é responsabilidade do sistema de controle de versão (normalmente o Git).

Uma referência a um caminho local cujo arquivo 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 (mesma entrada em bytes → mesma saída em bytes), mas as entradas diferem porque o arquivo local mudou. Catálogos que precisam de invariância entre builds para toda origem trazem os artefatos de um registry para o cache fixado pelo lockfile, em vez de lê-los de um caminho local ou de um diretório do workspace; o lockfile é a âncora da identidade byte a byte.