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

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 pela Release (CI/CD) inline em parameters: ou via parameters: { $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: 2 para workers: 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 inline parameters:. O empilhamento de vários arquivos é expresso por cadeias extends: da Release.
  • values (a intenção cognitiva - de propriedade do desenvolvedor)
    • Escopo: usados de forma uniforme dentro de components e de seus anexos features no Aggregate, 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).
  • uses (a topologia estrutural - estado declarativo)
    • Escopo: usados de forma uniforme dentro de components e de seus anexos features no Aggregate, 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 usesSchema do catálogo para impor a segurança de tipos entre nós.
  • infra (a realidade física - de propriedade de Ops)
    • Escopo: usado de forma uniforme dentro dos components de uma fronteira e de seus anexos features na Release.
    • 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 anexos features não incluem um campo infra e, combinadas com additionalProperties: false, rejeitam infra na validação de schema. Validado pela declaração unificada schema: do catálogo.
  • inject (o contrato de entrega - comando imperativo)
    • Escopo: usado em uma instância de componente, dentro de definições de destino explícitas em uses e nas features anexadas, 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, arg ou 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 com in: e carregando exatamente um entre from: e value:.
  • .context (o pipe genérico de metadados)
    • Escopo: injetado silenciosamente pelo compilador nos templates da Recipe de 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.

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 tipado parameters: e, em seguida, interpola as variáveis de template Go resolvidas antes de executar a validação posterior do schema values:.
    • Uso recomendado: os parameters sã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 bloco infra da Release e pelas sobreposições das fronteiras, mantendo o Aggregate do 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 parameters podem 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.
  • Fluxo 2: intenção cognitiva da aplicação (values nos Components): define a lógica intrínseca da aplicação. A declaração schema: 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 (values em 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 carrega values do desenvolvedor: a equipe de operações a anexa na Release, com seu infra (fluxo 4).
  • Fluxo 4: dimensionamento da infraestrutura física (infra): contornando totalmente o desenvolvedor, o dimensionamento físico infra é projetado explicitamente da Release especí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 dimensionamento infra é 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 campos infra locais 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 payloads values do 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 port na declaração schema:. 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ção schema: 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 versa

Comportamento 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, | quote e | 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 usando subsystems. Os subsistemas atuam como pastas recursivas no plano lógico/de intenção, propagando annotations em cascata para baixo no compartimento .context.annotations.aggregate e 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 a type, 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.
aggregate.yaml
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 parameters para ele. Para evitar acoplamento forte, os Aggregates filhos expõem um contrato exportedComponents:, 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 destino uses: 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.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/type nomeia 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ão spec.aggregates + exportedComponents mostrado 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, sem subsystems. O compilador os incorpora a um subsistema default sintetizado 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, sem boundaries. O compilador os incorpora a uma fronteira default sintetizada cuja saída é plana — os artefatos ficam diretamente sob dist/ (por provedor: dist/compose/, dist/helm/, …), sem nenhum segmento com o nome da fronteira. Esse é o caso mais simples: aggrega build sobre um destino Compose plano ou de cluster único sem nomear fronteiras. (Uma fronteira que um desenvolvedor declara e nomeia como default é uma fronteira nomeada comum e, sem um directory: próprio, emite para dist/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 subsystems explícitos, ou Ops introduz boundaries explí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.

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 bloco values, sem aspas, para que o valor chegue como o inteiro que foi declarado.
    • Por quê: se o Aggregate declara env_workers como 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 esquema values: ao redor. Isso preserva a reutilização do Aggregate: Ops fornece o inteiro por meio dos parameters: da Release, o compilador o valida em relação à declaração tipada parameters:, substitui o valor resolvido no documento, e a declaração schema: do Component valida com sucesso o inteiro resultante.
  • 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 um type de Feature de credencial (um rotulado feature.aggrega.ai/kind: secret) e usando os próprios values desse 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 de values significa e transporta literalmente um literal inline. É a superfície de anexos que torna a forma bem escrita disponível e tipada.
  • Restrição 2: Components agnósticos em relação às capacidades

    • Padrão não suportado: o arquiteto escreve aws_instance_type: string na declaração schema: 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 .context genéricas, não dentro da lógica cognitiva central da aplicação.
  • Restrição 3: lógica condicional sobre metadados

    • Padrão não suportado: Ops escreve {{ if eq .context.labels.gpu "true" }} em uma Recipe para mudar fundamentalmente a estratégia de deployment.
    • Por quê: o canal .context contorna a validação schema: de cada pilar. Depender de rótulos não validados para a lógica central de infraestrutura torna a plataforma frágil. O objeto .context carrega marcação de metadados (por exemplo, faturamento, SOC2); o roteamento estrutural pertence aos pilares validados por esquema.
  • 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: 4 para workers: 10) a partir da Release.
    • Por quê: o Aggregate é a fonte única da verdade para a intenção do desenvolvedor. Se um valor está fixado no código do Aggregate, ele é imutável entre ambientes. Se um valor precisa mudar por ambiente, o desenvolvedor usa a elevação de parâmetros. O esquema da Release impõe isso proibindo blocos values, limitando Ops a cumprir o contrato parameters e a definir a infra física.
  • 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 do Aggregate.
    • 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 aninhar infra e sobrescritas de funcionalidades por componente sem misturar a autoria de rótulos no Aggregate do desenvolvedor.

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 array parameters.approved_egress do 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 no helm uma NetworkPolicy do Kubernetes por workload que esse componente renderiza, admitindo egress apenas para seus próprios pods, para os pods dos destinos de suas arestas uses nas 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, com infra.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; no compose, 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-external no 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 key

2. 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. Execução do compilador na renderização (a passagem)

  1. O compilador avalia a Recipe de legacy-oracle. Para uma Release que fornece legacy_oracle_ip: "10.0.4.55", seu primary_endpoint é oracle://10.0.4.55:1521/PROD_DB.
  2. No helm, o Workload de referência renderiza um Service ExternalName, legacy-oracle, com externalName: 10.0.4.55 e a porta 1521; no compose, não renderiza nada.
  3. Em seguida, o compilador renderiza a Recipe de my-agent. Seu canal .context.uses carrega os provides do nó Oracle, e o contrato de injeção já resolveu ORACLE_DSN com 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.

  1. O Aggregate de plataforma: a equipe de infraestrutura escreve um Aggregate.yaml padrão cujos componentes são core/aws-vpc, core/eks-cluster e core/istio-base.
  2. 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.
  3. 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 Release da aplicação.