Taxonomia de dados e composição
A taxonomia unificada de dados e as regras de composição
Para estabelecer um schema previsível e eliminar o atrito cognitivo, a plataforma utiliza exatamente cinco palavras-chave universalmente compreendidas e uma estrutura YAML estritamente baseada em mapas (dicionários), com mapas em vez de arrays aninhados na raiz estrutural.
1. O padrão de mapas com 5 palavras-chave e a simetria total dos schemas
O vocabulário estrutural direto: uma regra fundamental do design de schemas é que as estruturas de dados raiz devem ser palavras-chave únicas e estruturais. Embora usar expressões coloquiais em inglês (como depends_on ou runs_within) possa tornar uma DSL em YAML mais natural de ler para um desenvolvedor, isso introduz complexidade estrutural ao mapear essas chaves em templates Go programáticos. Para manter um mapeamento direto 1:1 de variáveis e evitar a fragmentação da linguagem específica de domínio (DSL), os schemas JSON das entidades centrais do catálogo (Component, Feature) expressam uma simetria estrutural quase total, conduzida pelo mesmo conjunto central de palavras-chave estruturais usado em todos os slots de instância escritos. As Features de credencial (com o label feature.aggrega.ai/kind: secret) compartilham exatamente esse paradigma — não existe um schema separado para segredos.
parameters(o contrato de ambiente global)- Escopo: definidos na raiz do
Aggregate; atendidos pelaRelease(CI/CD) inline emparameters:ou viaparameters: { $import: <path> }apontando para um arquivo de parâmetros externo. - Significado: argumentos externos que alteram dinamicamente o estado cognitivo ou lógico da aplicação entre ambientes (por exemplo, mudar
workers: 2paraworkers: 10). Oferece suporte a um contrato tipado (veja data-pillars para a sintaxe completa do contrato tipado) validado antes da interpolação. Para fluxos de trabalho GitOps que mantêm os valores de parâmetros em um arquivo separado, a Release usa a forma$import:; o compilador carrega o conteúdo do arquivo e substitui o mapa inlineparameters:. O empilhamento de vários arquivos é expresso por cadeiasextends:da Release.
- Escopo: definidos na raiz do
values(a intenção cognitiva - de propriedade do desenvolvedor)- Escopo: usados de forma uniforme dentro de
componentse de seus anexosfeaturesnoAggregate, incluindo as Features de credencial. - Significado: o estado cognitivo central, a lógica de negócio e a configuração operacional. Opacos para o compilador Go, mas estritamente validados pela declaração unificada
schema:do catálogo (forma compacta ou JSON Schema 2020-12).
- Escopo: usados de forma uniforme dentro de
uses(a topologia estrutural - estado declarativo)- Escopo: usados de forma uniforme dentro de
componentse de seus anexosfeaturesnoAggregate, incluindo as Features de credencial. - Significado: uma declaração de fato que define arestas de rede e dependências (por exemplo, “Este agente usa este banco de dados”). Analisada nativamente pelo compilador Go para desenhar o grafo da representação intermediária (IR). Validada pela declaração unificada
usesSchemado catálogo para impor a segurança de tipos entre nós.
- Escopo: usados de forma uniforme dentro de
infra(a realidade física - de propriedade de Ops)- Escopo: usado de forma uniforme dentro dos
componentsde uma fronteira e de seus anexosfeaturesnaRelease. - Significado: a pegada física e o dimensionamento mecânico injetados durante o Late Binding (por exemplo,
cpu_limit: "4",port: 5432). As instâncias de componente do Aggregate e seus anexosfeaturesnão incluem um campoinfrae, combinadas comadditionalProperties: false, rejeitaminfrana validação de schema. Validado pela declaração unificadaschema:do catálogo.
- Escopo: usado de forma uniforme dentro dos
inject(o contrato de entrega - comando imperativo)- Escopo: usado em uma instância de componente, dentro de definições de destino explícitas em
usese nasfeaturesanexadas, incluindo as Features de credencial. - Significado: um comando explícito e imperativo que dita a intenção da entrega (por exemplo, “Compilador, injete este valor mapeado como uma variável de ambiente”). Ele estabelece o contrato abstrato (
env,file,argou mecanismos personalizados) para uma saída física, um endpoint resolvido ou uma credencial obtida, enquanto a mecânica física de como exatamente essa montagem é executada é delegada inteiramente à Recipe de Ops subjacente. Cada mecanismo é uma lista de entradas ([{ in: API_HOST, from: "host" }]), cada uma nomeando seu identificador local comin:e carregando exatamente um entrefrom:evalue:.
- Escopo: usado em uma instância de componente, dentro de definições de destino explícitas em
.context(o pipe genérico de metadados)- Escopo: injetado silenciosamente pelo compilador nos templates da
Recipede Ops. - Significado: carrega o que o compilador montou para o nó a partir do restante do grafo (como
.context.uses), passado diretamente ao mecanismo de templates de Ops.
- Escopo: injetado silenciosamente pelo compilador nos templates da
A realidade do mapeamento 1:1
Ao substituir preposições coloquiais por palavras-chave de infraestrutura estritas, obtém-se um mapeamento 1:1 direto. O engenheiro de Ops não precisa traduzir gramática; basta referenciar as chaves exatas que o desenvolvedor escreveu.
Formas estruturais: mapas na raiz, arrays nos payloads. Os blocos de topologia raiz — components, features, aggregates, subsystems, boundaries — são mapas YAML cujas chaves, escritas pelo usuário, servem como IDs de instância estáveis. Arrays não são válidos nessas posições; a chave do mapa é a identidade que o compilador usa para referências cruzadas (target: my-db), construção de nós do grafo e resolução do Manifest. Dentro dos blocos de payload opacos (values, infra, parameters), arrays são totalmente permitidos — os desenvolvedores podem escrever tools_allowed: ["sql", "web"] ou hostnames: ["stripe.com", "twilio.com"] nos values de um Component. O schema do Aggregate declara esses blocos de payload como additionalProperties: true, de modo que eles são opacos para o compilador Go e validados inteiramente pela declaração schema: incorporada no catálogo. Isso coloca a volatilidade dos frameworks (novos formatos de APIs de IA, novos formatos de payload cloud-native) dentro do domínio do catálogo, onde ela pode evoluir de forma independente, enquanto o compilador Go permanece restrito a chaves endereçáveis na raiz estrutural.
2. Os fluxos de informação: quem, quando e para quê?
Para evitar colisões de namespace nos templates e o vazamento não intencional de configurações de infraestrutura física para a lógica cognitiva da aplicação, a arquitetura separa explicitamente os dados em seis fluxos distintos:
- Fluxo 1: a injeção do ambiente (
parameters): o pipeline de CI/CD injeta as realidades da implantação. O compilador valida cada valor fornecido pela Release em relação ao contrato tipadoparameters:e, em seguida, interpola as variáveis de template Go resolvidas antes de executar a validação posterior do schemavalues:.- Uso recomendado: os
parameterssão reservados à lógica cognitiva da aplicação que varia entre ambientes (por exemplo,LOG_LEVEL=debug,ENABLE_BETA=true). O dimensionamento operacional e as questões de infraestrutura física — réplicas, limites de CPU, ARNs da AWS, hostnames de ingress — passam pelo blocoinfradaReleasee pelas sobreposições das fronteiras, mantendo oAggregatedo desenvolvedor focado na intenção da aplicação. - Via de escape pragmática: para equipes menores, prototipagem rápida ou integrações de CI/CD legadas em que uma separação estrita não é prática, os
parameterspodem levar configurações globais de ambiente pela stack. O compilador aceita tudo o que passa na validação de schema; a recomendação acima é um contrato social, não uma regra do compilador.
- Uso recomendado: os
- Fluxo 2: intenção cognitiva da aplicação (
valuesnos Components): define a lógica intrínseca da aplicação. A declaraçãoschema:do Component (forma compacta ou JSON Schema 2020-12) fornece verificação de tipos e validação estritas para esse payload, oferecendo aos desenvolvedores um feedback “Shift-Left” imediato e garantindo que as configurações solicitadas correspondam à API de infraestrutura subjacente. - Fluxo 3: intenção operacional da Feature (
valuesem Features): no Aggregate, o desenvolvedor solicita as capacidades de infraestrutura cujo comportamento é intenção da aplicação e consulta credenciais estritamente tipadas, sem modificar o código interno. Uma Feature cujas entradas são todas operacionais não carregavaluesdo desenvolvedor: a equipe de operações a anexa na Release, com seuinfra(fluxo 4). - Fluxo 4: dimensionamento da infraestrutura física (
infra): contornando totalmente o desenvolvedor, o dimensionamento físicoinfraé projetado explicitamente daReleaseespecífica do ambiente diretamente sobre os Components de escopo local e suas Features anexadas, incluindo as Features de credencial. Para evitar colisões de validação de schemas fechados causadas pela difusão literal de dicionários, o dimensionamentoinfraé estritamente localizado no componente explícito que o tem como alvo. Isso mantém limites de computação, réplicas e requisitos mecânicos de recursos no domínio de Ops. - Fluxo 5: anotações em cascata (metadados contextuais): dados contextuais amplos (como domínios operacionais, namespaces ou códigos de faturamento) são tratados por anotações em cascata, evitando a poluição pela difusão de
infra. Eles são segregados em compartimentos de acordo com sua origem, e o uso pretendido de cada compartimento abaixo é um contrato social: um template de Recipe pode ler os três, e o compilador não impõe a separação (veja labels-and-annotations):.context.annotations.release(fronteiras do domínio 4): usadas exclusivamente para governar realidades físicas. Ops roteia explicitamente essas anotações para camposinfralocais estritos via templates Go (por exemplo, mapeando um namespace regional para um componente de computação)..context.annotations.aggregate(subsistemas do domínio 1): usadas exclusivamente para governar a lógica cognitiva e operacional. Essas anotações são roteadas explicitamente para os payloadsvaluesdo componente (por exemplo, propagando em cascata o código de faturamento de uma equipe até uma configuração da aplicação)..context.annotations.catalog(catálogo do domínio 2): traços intrínsecos imutáveis escritos pelo arquiteto, usados principalmente para a avaliação programática de políticas Wasm.
- Fluxo 6: o pipe de metadados (
.context): aplica requisitos corporativos globais (tags SOC2) diretamente aos templates da infraestrutura física.
3. Abstração de rede: a convenção “Zero-Port”
- A boa prática: os desenvolvedores devem omitir as portas do
Aggregate. A Recipe de Ops cuida do roteamento interno de forma dinâmica. - A via de escape: se o código interno de uma aplicação não pode ser alterado, o arquiteto de plataforma expõe explicitamente um campo
portna declaraçãoschema:. Nota de arquitetura: a convenção “Zero-Port” é o exemplo mais evidente da separação de responsabilidades mais ampla da plataforma. Exatamente a mesma filosofia — abstrair a mecânica física para longe do desenvolvedor — se aplica a solicitações de CPU, limites de memória, domínios operacionais e dimensionamento de disco. Sempre que uma restrição de infraestrutura física precisar vazar para o payload da aplicação do desenvolvedor (por causa de código legado ou de requisitos de hardware estritos), ela deve sempre ser governada por uma “via de escape” explícita na declaraçãoschema:do arquiteto, a declaração com base na qual o payload do desenvolvedor é validado.
O nome “Zero-Port” designa essa convenção; o princípio se generaliza para qualquer restrição de infraestrutura física que uma aplicação legada codifica de forma fixa. O schema abaixo usa tcp_keepalive_seconds como exemplo prático — um tempo de kernel/rede que a aplicação espera na camada de sockets — porque ele se situa claramente no eixo do vazamento de infra.
O schema (domínio 2):
values: image: { type: string, required: true } # The architect explicitly allows the developer to declare a hardcoded constraint tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }O YAML do desenvolvedor (domínio 1):
components: legacy-payment-engine: type: core/java-tomcat:1.0.0 values: image: "corp/payments:v4" tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versaComportamento do compilador: o compilador Go passa tcp_keepalive_seconds: 120 para o grafo da IR. A Recipe de Ops então lê {{ .values.tcp_keepalive_seconds }} para configurar a especificação do pod do Kubernetes ou o tempo limite de ociosidade do balanceador de carga do provedor de nuvem, superando a lacuna legada sem violar o schema.
4. O contrato de injeção e o mapa pré-resolvido
Entre as cinco palavras-chave estruturais, inject tem uma forma diferente das demais. parameters, values, uses e infra são estado declarativo — o desenvolvedor escreve fatos sobre o que a aplicação é e do que ela depende. inject é um comando imperativo — o desenvolvedor dita como um valor deve ser entregue ao contêiner em execução, mapeando fontes de dados abstratas (as chaves provides de um destino, os próprios valores do componente, a resposta do vault de uma Feature de credencial) para mecanismos de entrega concretos (env, file, arg ou um mecanismo personalizado que o Component declara).
Esse desacoplamento é estrutural. O Aggregate do desenvolvedor diz “injete o host do banco de dados como a variável de ambiente DB_HOST” sem nomear o endereço físico do banco de dados, o caminho do vault no repositório de segredos nem o formato de hostname do provedor de nuvem. A Recipe de Ops recebe a string resolvida por meio de .context.inject e a consome sem escrever a cadeia de consulta.
O mapa pré-resolvido. Durante a renderização, o compilador resolve cada fonte de injeção — literais de autoinjeção e referências from: aos provides do próprio componente, referências entre componentes via uses[].inject, interceptações injectMapping da FeatureRecipe — em um único dicionário achatado em .context.inject. Quando o template valuesMapping da Recipe base é executado, cada chave de injeção já carrega seu valor de string final. As Recipes iteram o mapa diretamente ({{ range $k, $v := .context.inject.env }}) sem percorrer a cadeia de resolução.
Os nomes que o desenvolvedor dá aos valores próprios do componente. Onde o Component declara spec.inject, o bloco inject: do próprio desenvolvedor escolhe os nomes sob os quais os valores próprios e os provides do componente chegam ao canal de entrega. O compilador informa à Recipe, em .context.self_inject, o único valor próprio que o template de cada entrada lê — por mecanismo, cada nome mapeado para provides.<key>, para values.<key> no caso de um template que lê exatamente um valor próprio e nada mais, ou para uma string vazia — no formato que os nomes de uma conexão assumem em .context.uses.<alias>.inject. A convenção do catálogo da biblioteca padrão para uma Recipe que executa a imagem do desenvolvedor é tratar como padrões os nomes que ela escolheria de outra forma para os valores próprios do componente, entregando um valor próprio sob seu nome padrão apenas quando nenhuma entrada já o mapeia. Essa é uma convenção do catálogo, não uma regra do compilador: um catálogo corporativo pode entregar os valores próprios de seus componentes como preferir. O compilador lê o mapa a partir do texto que o desenvolvedor escreveu e não atribui nenhum significado aos nomes.
A especificação completa do contrato de injeção — semântica de contexto de estado duplo, regras de colisão de chaves, o modelo de interceptação da FeatureRecipe e exemplos práticos — está em topology-triad.
5. O mecanismo de templates (DX de Ops)
Os engenheiros de Platform Ops escrevem os templates de tradução e precisam de todo o poder do templating de infraestrutura padrão, sem uma linguagem de templates proprietária. Os templates do Aggrega são Go text/template:
- Sem strings “mágicas”: o compilador preserva as chaves de mapa exatas do desenvolvedor. Ops acessa as features com segurança pela indexação padrão de mapas do Go:
{{ (index .features "public-route").infra.hostname }}. - A biblioteca Sprig: o compilador registra nativamente a biblioteca Sprig, padrão do Helm, dando acesso imediato a pipelines como
| default,| quotee| toYaml. - Fragmentos de MappingLibrary: um fragmento de mapeamento que várias Recipes reutilizam fica em uma MappingLibrary e é trazido para cada Recipe com
$import:. Os helpers de templates de chart do Helm (include,tpl,required,warn) não são registrados; sprig-functions lista os que são.
6. Regras de composição: Aggregates, subsistemas e Components
- Agrupamento lógico (o array
subsystems): os desenvolvedores podem aplicar metadados lógicos (propriedade da equipe, labels de conformidade) e features transversais a dezenas de componentes ao mesmo tempo usandosubsystems. Os subsistemas atuam como pastas recursivas no plano lógico/de intenção, propagandoannotationsem cascata para baixo no compartimento.context.annotations.aggregatee anexando features a todos os componentes contidos sem ditar fronteiras físicas. As features de nível de subsistema seguem o mesmo schema das features de nível de componente (com suporte atype,values,uses,inject) porque estão no domínio 1 (intenção do desenvolvedor). Na finalização do grafo, o compilador achata as features do subsistema na lista de features de cada componente contido, posicionando-as depois das features próprias do componente e antes de qualquer feature anexada pela Release na ordem de execução.
subsystems: finance-module: annotations: "billing.corp.com/team": "payments" features: audit-logging: type: core/audit-logger:1.0.0 values: { log_level: "verbose" } components: ledger-api: type: core/python-worker:1.0.0 ledger-db: type: core/postgres:1.0.0- Aggregates compostos são SUPORTADOS (o padrão de módulos): os Aggregates atuam tanto como o Aggregate raiz que uma Release constrói quanto como módulos reutilizáveis. Um Aggregate pai pode declarar um Aggregate filho exatamente como um componente, passando
parameterspara ele. Para evitar acoplamento forte, os Aggregates filhos expõem um contratoexportedComponents:, que estabelece um nome de interface pública estável. O pai alcança os componentes do módulo apenas por meio dessa interface: um destinouses:nomeia o módulo e um de seus aliases exportados, e o compilador conecta a aresta ao componente interno que o alias nomeia, enquanto um destino que entra em um módulo por qualquer outro nome interrompe o build, indicando o módulo e os aliases que ele exporta. Um módulo pode, por sua vez, reexportar o componente exportado de um módulo aninhado sob seu próprio nome de interface — opcionalmente renomeando-o — e o compilador resolve essa cadeia de reexportação de forma transitiva até o nó interno subjacente, de modo que os módulos se compõem em qualquer profundidade sem que um pai precise saber a que profundidade o destino está aninhado. Um destino que não se resolve em nenhum nó interno ainda interrompe o build de forma explícita, e uma cadeia de reexportação que se fecha sobre si mesma é rejeitada em vez de ser seguida indefinidamente.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: my-catalog/child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_db-
Components não podem conter subcomponentes: os Components são blocos de construção atômicos. A composição acontece no nível do Aggregate, por meio de subsistemas e subagregados. Se uma aplicação requer vários contêineres físicos (como uma API + um sidecar), esse aninhamento físico fica dentro do template da Recipe de Ops, não na definição do Component.
-
Um serviço coeso por Component — a fronteira da carga de trabalho única: um Component modela um serviço coeso — um único serviço exposto, ou a carga ou cargas de trabalho de um serviço junto com suas cargas de trabalho auxiliares apenas internas. Seu label
component.aggrega.ai/typenomeia a forma operacional desse único serviço. Várias cargas de trabalho físicas dentro de um único Component são aceitáveis quando formam um produto coeso sem partes utilizáveis de forma independente: um serviço cujo chart executa um controller mais um webhook mais um injector continua sendo um único Component. O teste não é haver várias cargas de trabalho; é a usabilidade independente.A fronteira é traçada onde um bundle contém algo que outro componente poderia usar (
use) por conta própria de forma significativa — especialmente infraestrutura externa, como um banco de dados, um cache ou um message broker que o Aggrega já modela como seu próprio Component. Esse bundle não é um único Component; é um módulo subagregado — o padrãospec.aggregates+exportedComponentsmostrado acima — que compõe um Component por serviço, de modo que cada serviço seja um nó endereçável com seu próprio tipo, suas próprias arestas e sua própria superfície de políticas e de escalonamento.A heurística, formulada como uma regra clara: O chart contém algo que outro componente poderia usar por conta própria de forma significativa, ou para o qual o Aggrega já tem um Component? Se sim, modele-o como uma stack — um módulo subagregado que compõe Components por serviço. Se ele só serve a este único serviço, modele-o como um único Component.
Empacotar um produto inteiro de vários serviços como um único Component opaco é um antipadrão documentado. O compilador funciona sem opiniões próprias e vai aceitá-lo — ele renderiza tudo o que passa na validação de schema —, mas a biblioteca padrão compõe Components por serviço em um módulo, porque um empacotamento monolítico esconde os serviços modeláveis de forma independente da topologia, do seletor e das políticas e do escalonamento por serviço. Essa disciplina de granularidade é um contrato social — veja
../language-reference/vocabulary/social-contracts.md(granularidade do Component).
7. O escopo padrão — revelação progressiva do agrupamento
subsystems (no Aggregate) e boundaries (na Release) são as construções de agrupamento, mas um desenvolvedor não precisa declará-las de antemão. Cada entidade oferece duas formas de escrita, e elas são mutuamente exclusivas: escrever os componentes agrupados sob escopos nomeados, ou escrever os componentes diretamente no nível superior — nunca as duas ao mesmo tempo. Um documento que declara tanto components de nível superior quanto escopos nomeados é interrompido no carregamento com um erro de envelope.
Para a forma plana (components de nível superior), o compilador sintetiza um escopo default real no carregamento e incorpora a ele os componentes de nível superior, de modo que cada passagem posterior vê uma estrutura uniforme com escopos. O escopo sintetizado não é um contêiner oculto: é um nó genuíno da IR, marcado com sua procedência, distinguível de um escopo que um desenvolvedor nomeia explicitamente como default. Ele fica oculto apenas onde o autor lê caminhos — os diagnósticos e o endereçamento exibem o caminho em forma de raiz .spec.components[…] que o desenvolvedor realmente escreveu.
- Aggregate plano (componentes de nível superior): os componentes são escritos sob
spec.components, semsubsystems. O compilador os incorpora a um subsistemadefaultsintetizado no carregamento. As anotações de escopo de subsistema e as funcionalidades de nível de subsistema se aplicam apenas a subsistemas declarados; a forma plana não carrega nenhuma. - Release plana (componentes de nível superior): os componentes são escritos sob
spec.components, semboundaries. O compilador os incorpora a uma fronteiradefaultsintetizada cuja saída é plana — os artefatos ficam diretamente sobdist/(por provedor:dist/compose/,dist/helm/, …), sem nenhum segmento com o nome da fronteira. Esse é o caso mais simples:aggrega buildsobre um destino Compose plano ou de cluster único sem nomear fronteiras. (Uma fronteira que um desenvolvedor declara e nomeia comodefaulté uma fronteira nomeada comum e, sem umdirectory:próprio, emite paradist/boundaries/default/como qualquer outra.) - O caminho de evolução: quando uma arquitetura plana cresce a ponto de precisar de agrupamento (namespaces diferentes, agrupamentos lógicos separados, deployment em várias fronteiras), o desenvolvedor move os componentes de nível superior para
subsystemsexplícitos, ou Ops introduzboundariesexplícitos. Como as duas formas são mutuamente exclusivas, trata-se de uma passagem da forma plana para a forma com escopos — não de uma mistura das duas — e a identidade dos nós é preservada na transição.
O motivo é a revelação progressiva: exigir agrupamento obrigatório para casos de uso triviais (uma demonstração com um único serviço, um protótipo local rápido) cria atrito desnecessário. O teste de integração “do zero ao funcionamento em 10 minutos” exige que um desenvolvedor consiga escrever um Aggregate mínimo com um componente, um Manifest e uma Release e obter uma saída funcional sem antes entender subsistemas ou fronteiras. O escopo padrão é a rampa de acesso; os escopos declarados são para onde uma arquitetura vai à medida que cresce.
8. Restrições arquiteturais e padrões recomendados
As entradas abaixo são um padrão recomendado e cinco restrições. Os schemas impõem as restrições 4 e 5 — a Release não tem bloco values, e a instância de componente de um Aggregate não tem chave labels; as demais são convenções que o compilador não verifica.
-
Padrão recomendado: elevação de parâmetros por meio de strings de template
- Exemplo: o desenvolvedor escreve
workers: {{ .parameters.env_workers }}em seu blocovalues, sem aspas, para que o valor chegue como o inteiro que foi declarado. - Por quê: se o Aggregate declara
env_workerscomo parâmetro tipado (type: integer), o compilador primeiro valida o valor fornecido pela Release em relação ao contrato. A validação do contrato de parâmetros acontece antes da interpolação; a interpolação acontece antes da validação do esquemavalues:ao redor. Isso preserva a reutilização do Aggregate: Ops fornece o inteiro por meio dosparameters:daRelease, o compilador o valida em relação à declaração tipadaparameters:, substitui o valor resolvido no documento, e a declaraçãoschema:do Component valida com sucesso o inteiro resultante.
- Exemplo: o desenvolvedor escreve
-
Restrição 1: credenciais são anexos, não valores
- Padrão desaconselhado: o desenvolvedor escreve
values: { password: "123" }em um componente. - Por quê: a convenção da biblioteca padrão é que uma credencial seja solicitada como anexo sob
features:, nomeando umtypede Feature de credencial (um rotuladofeature.aggrega.ai/kind: secret) e usando os própriosvaluesdesse anexo para descrever a consulta a um armazenamento de segredos. Isso é uma convenção, não uma verificação do compilador — o compilador não interpreta o que uma folha devaluessignifica e transporta literalmente um literal inline. É a superfície de anexos que torna a forma bem escrita disponível e tipada.
- Padrão desaconselhado: o desenvolvedor escreve
-
Restrição 2: Components agnósticos em relação às capacidades
- Padrão não suportado: o arquiteto escreve
aws_instance_type: stringna declaraçãoschema:do Component. - Por quê: por convenção, os Components são agnósticos em relação às capacidades. Os destinos de hardware físico ficam nas Recipes de Ops ou em anotações
.contextgenéricas, não dentro da lógica cognitiva central da aplicação.
- Padrão não suportado: o arquiteto escreve
-
Restrição 3: lógica condicional sobre metadados
- Padrão não suportado: Ops escreve
{{ if eq .context.labels.gpu "true" }}em umaRecipepara mudar fundamentalmente a estratégia de deployment. - Por quê: o canal
.contextcontorna a validaçãoschema:de cada pilar. Depender de rótulos não validados para a lógica central de infraestrutura torna a plataforma frágil. O objeto.contextcarrega marcação de metadados (por exemplo, faturamento, SOC2); o roteamento estrutural pertence aos pilares validados por esquema.
- Padrão não suportado: Ops escreve
-
Restrição 4: a Release não pode sobrescrever os valores do desenvolvedor
- Padrão não suportado: Ops tenta sobrescrever a lógica cognitiva de um desenvolvedor (por exemplo, mudando
workers: 4paraworkers: 10) a partir daRelease. - Por quê: o
Aggregateé a fonte única da verdade para a intenção do desenvolvedor. Se um valor está fixado no código doAggregate, ele é imutável entre ambientes. Se um valor precisa mudar por ambiente, o desenvolvedor usa a elevação de parâmetros. O esquema daReleaseimpõe isso proibindo blocosvalues, limitando Ops a cumprir o contratoparameterse a definir ainfrafísica.
- Padrão não suportado: Ops tenta sobrescrever a lógica cognitiva de um desenvolvedor (por exemplo, mudando
-
Restrição 5: rótulos no nível da instância no Aggregate
- Padrão não suportado: o desenvolvedor escreve
labels: {}em uma instância de componente dentro doAggregate. - Por quê: rótulos são características imutáveis no nível do catálogo escritas pelo arquiteto da plataforma — a identidade semântica que os mecanismos de políticas e os seletores leem. A Release roteia os componentes para as fronteiras por meio de direcionamento explícito por ID baseado em mapas (
components: { "my-agent": {} }), o que preserva a possibilidade de aninharinfrae sobrescritas de funcionalidades por componente sem misturar a autoria de rótulos no Aggregate do desenvolvedor.
- Padrão não suportado: o desenvolvedor escreve
9. O perímetro de segurança & as salvaguardas explícitas de egress (destinos fora do perímetro)
Nenhuma aplicação existe no vácuo. Uma arquitetura Aggrega compilada representa um grafo mapeado de forma estrita. No entanto, os sistemas de IA modernos interagem constantemente com entidades fora desse perímetro compilado — como LLMs SaaS públicos (Anthropic, OpenAI), APIs públicas genéricas (Stripe, Twilio) ou bancos de dados brownfield legados (Oracle on-premise).
Para integrar esses sistemas externos com segurança, o Aggrega separa estritamente a fronteira de segurança da mecânica de execução. A fronteira de segurança é regida pela regra universal do Component e pela salvaguarda explícita de egress.
1. A regra universal do Component
Se uma aplicação interage com uma entidade — seja um banco de dados local, um recurso de nuvem gerenciado, um LLM SaaS ou um endpoint de API pública genérica —, essa entidade DEVE ser declarada como um Component distinto no Aggregate. Essa regra é uma convenção: o compilador não consegue ver uma chamada que a aplicação faz, então nada a verifica.
Ao tratar APIs SaaS externas e bancos de dados legados como nós de primeira classe no grafo da representação intermediária (IR), os desenvolvedores ganham a capacidade de anexar configurações de proxy Zero-Trust diretamente à chamada de saída. Por exemplo, ao modelar a API do Stripe como um nó distinto, um desenvolvedor pode anexar a ela uma funcionalidade header-injector, garantindo que a configuração gerada impeça o agente chamador de manter o token bruto da API em sua própria memória.
2. A salvaguarda explícita de egress (conformidade da infraestrutura)
Em vez de depender de lógica fixa no compilador para governar o egress de rede, o Aggrega delega inteiramente a segurança do perímetro aos mecanismos de políticas agnósticos da empresa e aos plugins de renderização Wasm. Isso garante que as configurações geradas estejam estritamente em conformidade com as aprovações explícitas de egress.
- O gancho do catálogo (domínio 2): quando um arquiteto define um componente SaaS público (por exemplo,
core/external-service), ele anexa a esse componente um rótulo corporativo imutável (por exemplo,security.enterprise.com/zone: "untrusted-external"). - A salvaguarda de política (em tempo de compilação): antes que qualquer configuração seja gerada, o mecanismo de políticas OPA ou Kyverno avalia o grafo. A empresa escreve uma regra simples: “Se um nó interno se conectar a um nó rotulado
untrusted-external, o ID desse nó de destino deve estar listado explicitamente no arrayparameters.approved_egressdo ambiente.” Se um desenvolvedor tentar rotear dados para um destino externo não aprovado, o mecanismo de políticas interrompe o build. - A geração da configuração (em tempo de renderização): se a política for aprovada, a regra de egress é renderizada a partir do que o operador anexou. A Feature
core/egress-allowlist, anexada ao componente chamador na Release, renderiza nohelmumaNetworkPolicydo Kubernetes por workload que esse componente renderiza, admitindo egress apenas para seus próprios pods, para os pods dos destinos de suas arestasusesnas portas que esses pods declaram, para o DNS do cluster e para os intervalos de endereços que a anexação lista para um destino que o cluster não executa, como uma API SaaS pública. O build é interrompido a menos que a Release afirme, cominfra.control_plane_present: true, que o plugin de rede do cluster aplica network policies, e é interrompido nomeando qualquer conexão externa desse tipo sem intervalo de endereços listado; nocompose, que não tem network policy, a anexação interrompe o build. O desenvolvedor nunca escreve uma regra de firewall.
Isso garante — por meio de um papel de veredito de governança que avalia a topologia declarada — que a infraestrutura declarada explicitamente esteja em conformidade com a política de egress sem que o compilador Go principal precise entender o que “externo” significa. (Observação: um egress zero-trust real depende de o cluster de destino executar uma CNI Default Deny em tempo de execução; as configurações geradas apenas mapeiam as exceções autorizadas).
Um Component por serviço externo
Cada serviço externo é declarado como um componente distinto, não agrupado em um array com vários destinos. Se uma aplicação chama cinco APIs de terceiros diferentes, o desenvolvedor declara cinco componentes core/external-service distintos. É essa declaração por serviço que permite aos mecanismos de políticas e aos plugins Wasm direcionar cada destino de saída individualmente — anexando a cada dependência externa políticas de egress diferentes, funcionalidades de proxy diferentes ou ganchos de observabilidade diferentes.
Desacoplando a segurança da execução (o cenário “brownfield”)
É fundamental observar que o rótulo semântico (por exemplo, untrusted-external) determina a política de segurança de rede, não a execução. Ele independe de o Aggrega renderizar ou não artefatos que provisionam o recurso.
- Cenário A (API SaaS pública): rotulada
untrusted-externalno catálogo (aciona as salvaguardas de egress da política). Realizada por um workload de referência (nenhum recurso de computação provisionado; veja §10). - Cenário B (banco de dados legado interno): rotulado
internal-trusted(contorna as salvaguardas de egress, permanece dentro da VPC). Realizado por um workload de referência (nenhum recurso de computação provisionado; veja §10). - Cenário C (banco de dados auto-hospedado): rotulado
internal-trusted. Executado por meio do plugin renderizador Helm (provisionado fisicamente como um StatefulSet do Kubernetes).
10. Serviços que o build não provisiona: Workloads de referência
Quando uma aplicação interage com um banco de dados legado on-premise ou com uma API SaaS pública (como a do Stripe), a regra universal do Component determina que essas entidades externas devem ser declaradas como componentes distintos no Aggregate. No entanto, o Aggrega não deve tentar gerar para elas um artefato físico de Pod do Kubernetes ou de instância do AWS RDS.
A Recipe que realiza um componente desse tipo declara um Workload de form: reference: um endpoint — um host ou uma URL —, opcionalmente uma port, e nenhum contêiner. O compilador repassa ambos como strings de ponteiros determinísticos e nunca os resolve. O que um provider renderiza para um Workload de referência é responsabilidade do próprio provider: o helm emite um Service ExternalName que carrega o host do endpoint, para que workloads no cluster possam alcançar um serviço cujo endpoint é um nome DNS por meio de um nome estável dentro do cluster; o compose não renderiza nada para ele. O Kubernetes trata um externalName como um nome DNS, então um endpoint escrito como endereço IP é alcançado no endereço que um consumidor recebe, e não por meio do Service.
Nos dois providers, os provides: da Recipe chegam a cada consumidor por meio de .context.uses e do contrato inject exatamente como os de um componente provisionado. Por isso, a conexão de um consumidor não muda quando seu destino passa de provisionado a referenciado: muda apenas a Recipe para a qual o Manifest mapeia o destino.
O pipeline de execução passo a passo
1. Domínio 1 (o Aggregate): intenção do desenvolvedor O desenvolvedor solicita um banco de dados Oracle legado. Não importa para ele onde o banco fica; ele apenas determina que seu agente chamador espera receber a string de conexão como variável de ambiente. Como o IP é estático e conhecido de antemão, ele o passa por meio de parâmetros.
components: legacy-oracle: type: core/legacy-database:1.0.0 values: host: "{{ .parameters.legacy_oracle_ip }}" sid: "PROD_DB"
my-agent: type: core/python-worker:1.0.0 values: {} uses: databases: legacy_db: target: legacy-oracle inject: env: - in: ORACLE_DSN # Local env var from: "primary_endpoint" # Target provides key2. Domínio 4 (o Manifest): o roteamento Ops mapeia o tipo de banco de dados legado para a Recipe que formata sua string de conexão. O Manifest nomeia uma Recipe e nada mais; a Recipe que ele nomeia declara um Workload de form: reference, e é essa forma que impede o nó de provisionar computação. O roteamento permanece perfeitamente plano e previsível porque o mapa tem exatamente uma forma, qualquer que seja o destino.
spec: mappings: components: type: "core/legacy-database": "oracle-dsn-formatter:1.0.0"3. Domínio 3 (a Recipe de referência): estruturando a passagem O engenheiro de Ops escreve a Recipe. Ela monta a string de conexão primary_endpoint a partir dos values do desenvolvedor em seu bloco locals, publica-a em provides e declara um Workload de referência que aponta para o host do banco de dados.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: capability: helm implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values locals: primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads provides: primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: reference endpoint: "{{ .values.host }}" port: 15214. Execução do compilador na renderização (a passagem)
- O compilador avalia a Recipe de
legacy-oracle. Para uma Release que fornecelegacy_oracle_ip: "10.0.4.55", seuprimary_endpointéoracle://10.0.4.55:1521/PROD_DB. - No
helm, o Workload de referência renderiza um Service ExternalName,legacy-oracle, comexternalName: 10.0.4.55e a porta1521; nocompose, não renderiza nada. - Em seguida, o compilador renderiza a Recipe de
my-agent. Seu canal.context.usescarrega osprovidesdo nó Oracle, e o contrato de injeção já resolveuORACLE_DSNcom base neles.
5. Domínio 3 (a Recipe chamadora): cumprindo o contrato A receita Helm padrão do worker Python lê o mapa de injeção que recebeu, exatamente como faria para um banco de dados que o build provisiona.
# Inside python-worker-helm (The calling agent's recipe)env: # The compiler pre-resolved the target's provides into the inject map {{- range $key, $value := .context.inject.env }} - name: {{ $key }} # Renders: ORACLE_DSN value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB {{- end }}11. Encadeamento entre pilares por schema-bridge: ligando a intenção à infraestrutura
Consulte inheritance-and-interface para o padrão schema-bridge, que expõe com segurança controles de infraestrutura especializados por meio de componentes filhos — um campo values: voltado ao desenvolvedor, declarado no schema: do Component, que o template valuesMapping: da Recipe encaminha para a saída renderizada no formato de infra:.
12. Provisionamento greenfield (“Aggregates de plataforma”)
Uma armadilha recorrente na engenharia de plataforma é forçar o roteador (o arquivo Release) a lidar com o pesado provisionamento de clusters do Dia 0 (por exemplo, subir um novo cluster AWS EKS antes de implantar a aplicação nele). Isso gera arquivos de roteamento longos e difíceis de ler.
O Aggrega trata disso com o princípio “tartarugas até lá embaixo”. O esquema da Release não tem nenhum bloco para instalar infraestrutura; o provisionamento de clusters é modelado com Aggregates de plataforma.
Como um cluster AWS EKS, um control plane do Istio e uma VPC da AWS são, no fim das contas, apenas recursos físicos de nuvem, eles são modelados exatamente como componentes de aplicação.
- O Aggregate de plataforma: a equipe de infraestrutura escreve um
Aggregate.yamlpadrão cujos componentes sãocore/aws-vpc,core/eks-clusterecore/istio-base. - A Release de plataforma: a equipe implanta esse agregado. O renderizador vinculado a esses componentes de plataforma gera os artefatos necessários para subir a infraestrutura base.
- A Release da aplicação: quando o desenvolvedor da aplicação está pronto para implantar seu agente de IA, a equipe de Ops simplesmente aponta para o cluster recém-criado com uma fronteira no próprio arquivo
Releaseda aplicação.