A taxonomia de entidades
A arquitetura do Aggrega é organizada em quatro domínios, cada um de propriedade de uma persona diferente e abrigando tipos de entidade específicos, além de uma camada de bibliotecas de nível 3 — o terceiro nível do modelo de níveis de entidades da referência da linguagem — que contém conteúdo reutilizável de esquemas, mapeamentos, workloads e artefatos. A visão geral abaixo mostra como os quatro domínios e as bibliotecas de nível 3 se relacionam entre si; cada seção a seguir começa com um diagrama de suas próprias entidades, em que uma entidade de outro domínio é desenhada com um contorno tracejado. As superfícies de autoria detalhadas (campos, esquemas, exemplos) de cada entidade ficam no catálogo de entidades da referência da linguagem.
graph TD
Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
Libs["<b>Tier 3: Libraries</b>"]
Intent -->|"requests, attaches"| Catalog
Intent -->|"binds via"| Routing
Routing -->|"attaches"| Catalog
Catalog -->|"resolved to"| Infra
Routing -->|"resolves, renders via"| Infra
Catalog -.->|"$ref"| Libs
Infra -.->|"$import"| Libs
O corpus abrange quatro domínios mais a camada de bibliotecas de nível 3:
| # | Entidade | Domínio | Papel |
|---|---|---|---|
| 1 | Aggregate | Domínio 1 — Intenção do desenvolvedor | Planta da topologia da aplicação |
| 2 | Component | Domínio 2 — Platform Catalog | Interface abstrata de nó de computação |
| 3 | Feature | Domínio 2 — Platform Catalog | Traço operacional (incluindo Features de credenciais) |
| 4 | Recipe | Domínio 3 — Base de infraestrutura | Implementação de um Component, por provedor |
| 5 | FeatureRecipe | Domínio 3 — Base de infraestrutura | Implementação de uma Feature, por provedor |
| 6 | Plugin | Domínio 3 — Base de infraestrutura | Plugin WebAssembly endereçado por conteúdo (renderização de provedores, etapas de pipeline, linting) |
| 7 | Manifest | Domínio 4 — Roteamento e políticas | Lockfile de dependências que mapeia interfaces para Recipes |
| 8 | Release | Domínio 4 — Roteamento e políticas | Roteador de implantação que vincula o Aggregate ao Manifest |
| 9 | SchemaLibrary | Nível 3 — Bibliotecas | Definições reutilizáveis de JSON Schema 2020-12 |
| 10 | MappingLibrary | Nível 3 — Bibliotecas | Fragmentos reutilizáveis de templates Go |
| 11 | WorkloadLibrary | Nível 3 — Bibliotecas | Fragmentos reutilizáveis de templates de Workload |
| 12 | ArtifactLibrary | Nível 3 — Bibliotecas | Pacotes reutilizáveis de artefatos nomeados |
Essa tabela é o conjunto completo dos tipos de entidade de autoria, os tipos que um autor declara em um campo kind:. O tipo Workload é conteúdo de propriedade da plataforma incorporado na entrada sintetizada de uma Recipe, e não uma entidade de catálogo independente (veja o capítulo 16), por isso está deliberadamente ausente da tabela acima.
O Plugin é uma entidade de autoria de primeira classe — com seu próprio kind, seu próprio JSON Schema e seu próprio diretório de catálogo — de propriedade do Platform Ops no domínio 3. Um Plugin é uma referência endereçada por conteúdo a um artefato WebAssembly, que declara o único tipo de socket que implementa. A taxonomia tem sete membros: provider (renderiza nós da IR em artefatos nativos do provedor), linter (emite diagnósticos sobre o conteúdo escrito), pipeline-step (uma etapa de uma feature-recipe-pipeline), governance (cumpre um papel de governança — transformar labels ou anotações, ou retornar um veredito de aceitação ou rejeição sobre o grafo da IR ou sobre os artefatos renderizados), cli (contribui com um subcomando aggrega que um operador invoca na linha de comando), parser (transforma um texto-fonte externo em uma árvore estruturada canônica) e importer (transforma uma fonte externa de infraestrutura ou de definição de agentes em rascunhos de arquivos de autoria do Aggrega). Um Plugin de renderização de provedor (pluginType: provider) é a unidade que atende à renderização de provedor: ele declara em spec.provider.capabilities o nome ou os nomes de provedor que renderiza e carrega o restante dos metadados do seu socket de provedor nesse mesmo bloco spec.provider. O compilador fixa e roteia a referência; o runtime WebAssembly executa os bytes; o compilador não interpreta o que o plugin faz — o plugin é o transporte da inteligência específica do domínio que vive no WebAssembly. Sua superfície de autoria e de metadados está documentada em language-reference/entities/plugin.md.
Domínio 1: intenção do desenvolvedor (o “quê”)
graph LR
classDef ext stroke-dasharray:5 4;
A["Aggregate<br/>The 'What'"]
CC["Component"]:::ext
CapC["Feature"]:::ext
EB["Release"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
A -->|"Binds via"| EB
- Papel: o desenvolvedor. Concentra-se exclusivamente na arquitetura de IA, nos ciclos cognitivos e nos requisitos de sobrevivência da aplicação. Não precisa conhecer CEL, OPA ou portas físicas.
- 1. Aggregate: a planta declarativa baseada em mapas da topologia da aplicação. Servindo como o Aggregate raiz que uma Release constrói ou como módulo parametrizado e reutilizável, ele define
componentslógicos e anexa, emfeatures, as Features cujo comportamento é intenção da aplicação, com seusvalues; uma Feature cujas entradas são todas operacionais é anexada pelo operador na Release (veja o domínio 4). Uma credencial é solicitada nessa mesma superfície de anexaçãofeatures, por meio de uma Feature de credencial — não há um bloco separado para isso. Ele define requisitos de capacidade abstratos viaparameters(contratos tipados escritos no vocabulário da forma compacta) e o estado do payload viavalues. Instâncias de Component suportam um campodescriptionopcional para documentação e renderização no Studio. Ele promove a convenção “Zero-Port” (abstrair as portas de rede, a menos que sejam explicitamente exigidas por código preexistente), sem plataforma de destino ou namespace fixados no código.
Domínio 2: Platform Catalog (as “interfaces e inteligência”)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release"]:::ext
CC["Component<br/>The Compute Interface"]
CapC["Feature<br/>The Operational Trait"]
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
EB -.->|"Attaches"| CapC
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
- Papel: o Platform Architect. O “programador” da plataforma. Ele posiciona cada componente na ontologia operacional, escreve as políticas programáveis (mutadores e validadores Wasm) e estabelece os rótulos semânticos de duck typing.
- 2. Component: a interface abstrata de um nó de computação. Ele declara sua forma base por meio da ontologia de nuvem operacional (por exemplo,
component.aggrega.ai/type: server) e sobrepõe sua identidade cognitiva por meio de rótulos de duck typing (por exemplo,model.aggrega.ai/capability: generative). Ele declara slots de credenciais viafeaturesSchema(obrigatórios/opcionais, caixa-preta/transparentes) e usaschema:(JSON Schema 2020-12, normalmente escrito com a notação abreviada da forma compacta) para validar estritamente o blocovaluesopaco do desenvolvedor. - 3. Feature: um traço operacional modular (por exemplo, mascaramento de dados, roteamento DNS, gerenciamento de segredos). Ela usa seletores de rótulos
appliesTopara se vincular dinamicamente a rótulos semânticos específicos. Assim como os Components, ela declara slots de credenciais viafeaturesSchemapara impor o provisionamento de chaves de API. Crucialmente, ela usametadata.annotationspara marcar explicitamente elementos no grafo IR plano, o que informa aos validadores de políticas Wasm e aos plugins de renderização a jusante como tratar o payload de configuração da Feature.- Features de credenciais: a plataforma unifica o gerenciamento de credenciais na entidade Feature: uma Feature com o rótulo
feature.aggrega.ai/kind: secreté uma feature de credencial — ela define uma interface de consulta para um cofre de segredos (por exemplo, AWS Secrets Manager, HashiCorp Vault). Ela é anexada emfeatures:como qualquer outra Feature, na mesma superfície e com a mesma forma; o rótulo é um metadado que o catálogo carrega para descrever o que a anexação produz, e nenhum ramo do compilador o lê. Não existe um kind separado de cofre de segredos ou de recipe de segredos: uma FeatureRecipe de credencial tem a mesma forma que qualquer outra FeatureRecipe, o pipeline de busca e entrega é o mesmo para ambas e o contrato de entregainject(env,file,arg) é compartilhado. Uma entidade, uma palavra-chave de anexação, um caminho de execução de modificadores ao longo da renderização — e as credenciais são mapeadas emfeatures.typeno Manifest.
- Features de credenciais: a plataforma unifica o gerenciamento de credenciais na entidade Feature: uma Feature com o rótulo
A ontologia como rótulo. A ontologia de nuvem operacional é declarada em metadata.labels["component.aggrega.ai/type"], e não como um campo spec.type de nível superior. Essa escolha permite que o mecanismo de seletores de rótulos do compilador tenha como alvo direto os valores da ontologia — uma Feature declara appliesTo: "component.aggrega.ai/type in (server, worker)" para se anexar dinamicamente a todo componente server ou worker sem nenhuma lógica Go nova no compilador central. O mesmo mecanismo de seletores se aplica a todo rótulo do Aggrega, de modo que uma Feature, um seletor de socket ou um mapeamento de fronteiras de uma Release lê a chave de rótulo própria de um catálogo exatamente como lê esta.
component.aggrega.ai/type é a chave do Aggrega, e seu conjunto de valores é fechado: o esquema publicado do Component enumera as primitivas, e um documento que traga qualquer outro valor é recusado ao ser carregado, com E0215 nomeando o rótulo e listando o que ele aceita. Um catálogo que precisa de uma classificação que o Aggrega não define adiciona sua própria chave de rótulo ao lado dela — o esquema do Component aceita qualquer chave de rótulo adicional com valor de string —, de modo que um novo eixo custa uma chave sua e nenhuma nova versão do compilador, enquanto a chave reservada mantém um único significado em todo lugar. É isso que faz uma Feature escrita para component.aggrega.ai/type in (stateful-server) funcionar com Components de autores que nunca se conheceram.
Domínio 3: base de infraestrutura (as “implementações”)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
ENV["Manifest"]:::ext
EB["Release"]:::ext
CD["Recipe<br/>The Implementation"]
CapD["FeatureRecipe<br/>The Binding"]
T["Plugin<br/>The Wasm Plugin"]
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
EB -->|"Renders via"| T
- Papel: o engenheiro de infraestrutura / Ops. É responsável pela realidade física, pela atribuição de portas de rede e pela lógica de templates.
- 4. Recipe: o template de tradução multiprovedor (por exemplo, Helm ou Docker Compose). Ela estabelece um contrato de API estrito 1:1 com o componente do catálogo por meio da palavra-chave
implements. A Recipe mapeia os.valuesdo desenvolvedor para o formato físico. Ela fixa no código as portas de rede físicas (por exemplo,5432) e lê osprovidesdo alvo pelo pipe.context.uses, satisfazendo o contrato de injeção sem fixar no código os nomes dos bancos de dados. - 5. FeatureRecipe: mapeia explicitamente uma
Featurepara uma implementação de infraestrutura concreta por meio da palavra-chaveimplements. Ela exige uma capacidade do provedor de destino emcapability(por exemplo,helm,compose). Como a plataforma unifica o gerenciamento de credenciais na entidade Feature, as FeatureRecipes tratam tanto funcionalidades operacionais (mascaramento de dados, roteamento DNS, injeção de sidecar) quanto funcionalidades de credenciais (geração de CRDs de cofre, montagem de volumes de segredos). Para cobrir todo esse espectro, ela suporta três blocos de execução distintos:pipeline: um array sequencial de plugins WebAssembly (Wasm) para a mutação do Workload após a renderização (por exemplo, injetar um sidecar Envoy via JSONPatch ou montar um volume de segredos).sourceevaluesMapping,workload,artifacts: os mesmos três tipos de entrada que uma Recipe carrega, usados para a geração de recursos; permitem que Ops renderize templates estáticos nativamente (por exemplo, gerando uma nova CRDHTTPRouteou uma CRDExternalSecret) ao lado do componente base.injectMapping(interceptação antes da renderização): um bloco de template Go nativo executado antes da renderização da Recipe base. Ele gera um dicionário JSON que o compilador mescla nativamente em profundidade sobre o pipe de memória.context.injectdo chamador, permitindo a mutação de variáveis de ambiente e strings de conexão no lado do chamador, sem Wasm.
- O padrão de FeatureRecipe de credencial: quando uma FeatureRecipe implementa uma Feature de credencial (com o rótulo
feature.aggrega.ai/kind: secret), aplica-se o princípio padrão do Plugin em duas partes: opipelineencadeia um plugin Fetcher (que gera a CRD específica do cofre) seguido de um plugin Injector (que monta o segredo no contêiner de destino). A separação Fetcher/Injector maximiza a reutilização — trocar o AWS Secrets Manager pelo HashiCorp Vault exige apenas substituir o plugin Fetcher; o Injector permanece idêntico.
- 6. Plugin: o plugin WebAssembly endereçado por conteúdo. Um Plugin de renderização de provedor (
pluginType: provider) é a unidade que transforma os tipos de entrada de uma Recipe no formato de arquivo final serializado como string: ele declara emspec.provider.capabilitieso nome ou os nomes dos provedores que atende (por exemplo,helm), anunciando uma exportaçãorender_nodepara a qual o compilador despacha, e carrega o restante dos metadados do seu socket de provedor (workloadSchema,wellKnownAnnotations) nesse mesmo blocospec.provider. Os outros tipos de socket que um Plugin pode declarar sãopipeline-step,linter,governance,cli,parsereimporter. O compilador roteia a referência fixada; o runtime WebAssembly executa os bytes.
Domínio 4: roteamento e políticas (a “cola”)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release<br/>The Deployment Router"]
ENV["Manifest<br/>The Dependency Lockfile"]
CapC["Feature"]:::ext
T["Plugin"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -->|"Binds via"| EB
EB -.->|"Attaches"| CapC
EB -->|"Uses"| ENV
EB -->|"Renders via"| T
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
- Papel: o Platform Operator / DevOps.
- 7. Manifest: o lockfile de dependências. Ele usa um mapeamento de URI plano: um dicionário
components.typemapeia tipos de componentes do catálogo para URIs de Recipe, e um dicionáriofeatures.typemapeia tipos de Feature para URIs de FeatureRecipe. A resolução é uma busca direta de URI no lockfile e no catálogo; a determinação da capacidade decorre do campospec.capabilityde cada Recipe resolvida no momento do build. Após a resolução, toda entidade deve ter um mapeamento, ou o compilador para. Para manter um ecossistema DRY, os Manifests suportam um padrão de composição no estilo Kustomize por meio da palavra-chaveextends, permitindo que manifestos específicos de ambiente (como local ou staging) herdem de forma limpa de um manifesto base global e declarem apenas suas sobrescritas específicas. - 8. Release: o roteador. Ela vincula um
aggregatea ummanifeste mapeia componentes para fronteiras físicas (por exemplo,aws-eks-production). Para manter um fluxo de trabalho DRY, as Releases suportam herança por meio da palavra-chaveextends, permitindo que releases específicas de ambiente herdem de forma limpa de uma release base global. Ela cumpre o contrato abstrato do aggregate injetando as realidades físicas estritamente no blocoparameters, e injeta o dimensionamento físico (como CPUs ou portas) por meio do namespace paraleloinfra. Para proteger o Aggregate como fonte única da verdade, o esquema da Release proíbe mecanicamente um blocovalues:— Ops não pode declararvaluesem nenhum Component ou Feature a partir de uma Release. A variação por ambiente dos valores voltados ao desenvolvedor passa pelo Parameter Hoisting: o desenvolvedor expõe um campo tipadoparameters.*no Aggregate, o templatevaluesdo Component o referencia e a Release preenche o parâmetro para o seu ambiente. Os valores renderizados diferem entre ambientes, enquanto o Aggregate — a superfície de autoria que define quais valores existem e como fluem — permanece a fonte única da verdade. Veja a restrição 4, “A Release não pode sobrescrever os valores do desenvolvedor”, em Restrições arquiteturais e padrões recomendados para a proibição em nível de esquema declarada explicitamente. Crucialmente, para impedir Releases não rastreáveis que “alteram o aggregate”, quando uma Release usaextends, a declaração de umaggregateé rejeitada pelo esquema da Release (a restrição do esquema não permite declararaggregatequandoextendsé usado). A release filha deve corresponder exatamente à mesma intenção do desenvolvedor que sua release pai. Omanifest, porém, torna-se opcional, liberando a “vinculação tardia” — permitindo que Ops herde toda a topologia física, mas troque cirurgicamente o lockfile de dependências.- Anexação de Feature: a Release também anexa Features, em
featuresem uma fronteira ou em um único componente. Uma Feature cujas entradas são todas operacionais ela anexa diretamente, com seutypee seuinfra; uma Feature que o Aggregate anexou ela dimensiona, escrevendo oinfradessa anexação sob o mesmo nome.
- Anexação de Feature: a Release também anexa Features, em
Por que separar o Manifest da Release. Separar o lockfile de software (Manifest) do roteador de implantação (Release) possibilita uma forma que nenhuma das duas entidades conseguiria produzir sozinha: DevOps implanta uma única aplicação em vários roteadores de implantação regionais — diferentes Releases visando diferentes regiões de nuvem, todas referenciando o mesmo Manifest — sem duplicar vinculações de Recipe entre ambientes. Cada Release regional carrega seu layout de fronteiras e seus parâmetros específicos de ambiente enquanto consome o mesmo lockfile de software que o Manifest fornece. A escalabilidade multirregião decorre da separação de domínios, não da duplicação do Manifest.
Nível 3: bibliotecas (reutilização do catálogo)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
SL["SchemaLibrary<br/>JSON Schema definitions"]
ML["MappingLibrary<br/>Go template fragments"]
WL["WorkloadLibrary<br/>Workload template fragments"]
AL["ArtifactLibrary<br/>Named artifact bundles"]
CC -.->|"$ref"| SL
CapC -.->|"$ref"| SL
CD -.->|"valuesMapping $import"| ML
CapD -.->|"$import"| ML
CD -.->|"workload $import"| WL
CD -.->|"artifacts $import"| AL
CapD -.->|"$import"| AL
- Papel: o Platform Architect (a mesma persona do domínio 2), mas o papel só entra em ação quando o conteúdo do catálogo cresce o suficiente para se beneficiar da reutilização de esquemas entre um Component e outro ou da reutilização, entre uma Recipe e outra, de templates, formas de workload ou pacotes de artefatos. Autores individuais e catálogos pequenos funcionam sem nenhuma entidade de nível 3.
- 9. SchemaLibrary: definições reutilizáveis de JSON Schema 2020-12. Uma biblioteca declara esquemas nomeados em
spec.schemas:e helpers parametrizados opcionais emspec.templates:(com declarações$params:e referências$instantiate:para reutilização paramétrica). As entidades do catálogo consomem as entradas da biblioteca por meio da palavra-chave padrão$ref:do JSON Schema, que aponta para a entrada da biblioteca por identidade — a forma sem host<library>#/schemas/<name>(a versão vem do lockfile, não da referência). Nomes em PascalCase, distribuição via OCI, versão fixada no lockfile. Opcional, para catálogos que precisam reutilizar esquemas entre um Component e outro — formas comuns comoPodResources,PersistenceSpec,NodePool,MetricsServiceMonitorse repetem em todo Component de datastore e em todo Component de workload, e as entradas de uma SchemaLibrary eliminam essa repetição da autoria de cada Component. - 10. MappingLibrary: fragmentos reutilizáveis de templates Go. Uma biblioteca declara templates nomeados em
spec.mappings:. Recipes e FeatureRecipes consomem as entradas da biblioteca por identidade viavaluesMapping: { $import: <library>#/mappings/<name> }. Um único modo de autoria (apenas templates Go); nenhum caminho de autoria paralelo em Jsonnet. Opcional, para catálogos que precisam reutilizar mapeamentos entre uma Recipe e outra — padrões comuns, como a lógica dos helpers dos charts Bitnami ou padrões compartilhados de templates de pod, se repetem em toda Recipe de datastore voltada ao mesmo provedor, e as entradas de uma MappingLibrary eliminam essa repetição da autoria de cada Recipe. - 11. WorkloadLibrary: fragmentos reutilizáveis de templates de Workload. Uma biblioteca declara entradas de workload nomeadas em
spec.workloads:. Uma Recipe consome uma entrada por identidade viaworkload: { $import: <library>#/workloads/<entry> }, e o corpo importado é validado contra o esquema de Workload de propriedade da plataforma exatamente como um blocoworkload:inline — assim, um workload importado de uma biblioteca é renderizado de forma idêntica ao equivalente inline. Um único modo de autoria (apenas templates Go). Opcional, para catálogos que precisam reutilizar workloads entre uma Recipe e outra, quando várias Recipes compartilham uma mesma forma de implantação e só diferem nos valores. - 12. ArtifactLibrary: pacotes reutilizáveis de artefatos nomeados. Uma biblioteca declara pacotes nomeados em
spec.artifacts:, cada um agrupando os arquivos de saída que andam juntos — uma CRD, seu RBAC e um ConfigMap, por exemplo — e importado como uma única unidade. Recipes e FeatureRecipes consomem um pacote por identidade viaartifacts.<name>: { $import: <library>#/artifacts/<name> }. Um único modo de autoria (apenas templates Go). Opcional, para catálogos que precisam reutilizar artefatos entre uma Recipe e outra, quando o mesmo conjunto de recursos auxiliares acompanha muitas Recipes.
Toda biblioteca é publicada via OCI, fixada no lockfile (as seções schema_libraries:, mapping_libraries:, workload_libraries: e artifact_libraries:) e aparece na interface do Hub com conhecimento dos consumidores (quais Components referenciam quais entradas de biblioteca; quais Recipes consomem quais entradas de biblioteca).