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

Taxonomia de dados e composição

A taxonomia de dados unificada e as regras de composição

Para estabelecer um esquema previsível e eliminar fricção cognitiva, 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 mapa de 5 palavras-chave e a simetria total dos esquemas

O vocabulário estrutural direto: Uma regra fundamental do design de esquemas é que as estruturas de dados raiz têm de ser palavras-chave estruturais únicas. Embora o uso de expressões coloquiais em inglês (como depends_on ou runs_within) possa tornar uma DSL YAML mais natural para um programador, introduz complexidade estrutural ao mapear essas chaves para templates Go programáticos. Para manter um mapeamento de variáveis 1:1 direto e evitar a fragmentação da linguagem específica de domínio (DSL), os esquemas JSON das entidades centrais do catálogo (Component, Feature) exprimem uma simetria estrutural quase total, assente no mesmo conjunto central de palavras-chave estruturais usado nos slots de instâncias criados. As Features de credenciais (com a etiqueta feature.aggrega.ai/kind: secret) partilham este paradigma idêntico — não existe um esquema separado para segredos.

  • parameters (o contrato global de ambiente)
    • Âmbito: Definido na raiz do Aggregate; cumprido pela Release (CI/CD) inline em parameters: ou através de parameters: { $import: <path> }, que aponta para um ficheiro 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). Suporta um contrato tipado (ver data-pillars para a sintaxe completa do contrato tipado) validado antes da interpolação. Para fluxos GitOps que mantêm os valores dos parâmetros num ficheiro separado, a Release usa a forma $import:; o compilador carrega o conteúdo do ficheiro e substitui o mapa inline parameters:. A sobreposição de vários ficheiros exprime-se através de cadeias extends: da Release.
  • values (a intenção cognitiva - detida pelo programador)
    • Âmbito: Usado uniformemente dentro de components e das respetivas anexações features no Aggregate, incluindo as Features de credenciais.
    • Significado: O estado cognitivo central, a lógica de negócio e a configuração operacional. Opaco para o compilador Go, mas validado estritamente pela declaração schema: unificada do Catálogo (forma compacta ou JSON Schema 2020-12).
  • uses (a topologia estrutural - estado declarativo)
    • Âmbito: Usado uniformemente dentro de components e das respetivas anexações features no Aggregate, incluindo as Features de credenciais.
    • Significado: Uma afirmação declarativa de facto que define arestas de rede e dependências (por exemplo, «Este agente usa esta base de dados»). Analisado nativamente pelo compilador Go para desenhar o grafo da Representação Intermédia (IR). Validado pela declaração usesSchema unificada do Catálogo para impor a segurança de tipos entre nós.
  • infra (a realidade física - detida pelo Ops)
    • Âmbito: Usado uniformemente dentro dos components de uma fronteira e das respetivas anexações 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 componentes do Aggregate e as respetivas anexações features não incluem um campo infra e, combinadas com additionalProperties: false, rejeitam infra na validação de esquemas. Validado pela declaração schema: unificada do Catálogo.
  • inject (o contrato de entrega - comando imperativo)
    • Âmbito: Usado numa instância de componente, dentro de definições de destino explícitas em uses e nas features anexadas, incluindo as Features de credenciais.
    • Significado: Um comando explícito e imperativo que dita a intenção da entrega (por exemplo, «Compilador, injeta este valor mapeado como variável de ambiente»). 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 na Recipe de Ops subjacente. Cada mecanismo é uma lista de entradas ([{ in: API_HOST, from: "host" }]), cada uma a nomear o seu identificador local com in: e a transportar exatamente um de from: ou value:.
  • .context (o pipe genérico de metadados)
    • Âmbito: Injetado silenciosamente pelo compilador nos templates da Recipe de Ops.
    • Significado: Transporta o que o compilador montou para o nó a partir do resto do grafo (como .context.uses), passado diretamente ao motor de templates de Ops.

A realidade do mapeamento 1:1

Ao substituir preposições coloquiais por palavras-chave de infraestrutura estritas, consegue-se um mapeamento 1:1 direto. O engenheiro de Ops não tem de traduzir gramática; basta-lhe referenciar as chaves exatas que o programador escreveu.

Formas estruturais: mapas na raiz, arrays nos payloads. Os blocos de topologia raiz — components, features, aggregates, subsystems, boundaries — são mapas YAML com chaves criadas pelo utilizador que servem de IDs de instância estáveis. Os arrays não são válidos nestas posições; a chave do mapa é a identidade que o compilador usa para referências cruzadas (target: my-db), para a construção de nós do grafo e para a resolução do Manifest. Dentro dos blocos de payload opacos (values, infra, parameters), os arrays são totalmente permitidos — os programadores podem escrever tools_allowed: ["sql", "web"] ou hostnames: ["stripe.com", "twilio.com"] nos values de um Component. O esquema do Aggregate declara estes blocos de payload como additionalProperties: true, pelo que são opacos para o compilador Go e validados inteiramente pela declaração schema: incorporada do Catálogo. Isto coloca a volatilidade das frameworks (novas formas de API de IA, novos formatos de payload cloud-native) dentro do domínio do Catálogo, onde pode evoluir de forma independente, enquanto o compilador Go se mantém apenas com chaves endereçáveis na raiz estrutural.

2. Os fluxos de informação: quem, quando e para quê?

Para evitar colisões de namespaces de templates e a fuga 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 ambiental (parameters): A pipeline de CI/CD injeta realidades de implantação. O compilador valida cada valor fornecido pela Release contra o contrato tipado parameters: e depois interpola as variáveis de template Go resolvidas antes de executar a validação de esquema values: a jusante.
    • Utilização recomendada: os parameters estão reservados para a lógica cognitiva da aplicação que varia entre ambientes (por exemplo, LOG_LEVEL=debug, ENABLE_BETA=true). O dimensionamento operacional e as preocupações de infraestrutura física — réplicas, limites de CPU, ARN da AWS, nomes de anfitrião de ingress — fluem através do bloco infra da Release e das sobreposições de fronteira, mantendo o Aggregate do programador focado na intenção da aplicação.
    • Via de escape pragmática: Para equipas mais pequenas, prototipagem rápida ou integrações de CI/CD legadas em que a separação estrita não é prática, os parameters podem transportar configurações globais de ambiente ao longo da stack. O compilador aceita o que passar a validação de esquemas; 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 este payload, dando feedback «Shift-Left» imediato aos programadores e garantindo que as configurações pedidas correspondem à API de infraestrutura subjacente.
  • Fluxo 3: Intenção operacional das funcionalidades (values em Features): No Aggregate, o programador pede 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 transporta values do programador: as operações anexam-na na Release, com o seu infra (Fluxo 4).
  • Fluxo 4: Dimensionamento da infraestrutura física (infra): Contornando totalmente o programador, o dimensionamento físico infra é projetado explicitamente a partir da Release específica do ambiente diretamente sobre os Components de âmbito local e as respetivas Features anexadas, incluindo as Features de credenciais. Para evitar colisões de validação de esquemas fechados ao difundir dicionários tal como estão, o dimensionamento infra é estritamente localizado no componente explícito que o visa. Isto mantém os limites de computação, as réplicas e os requisitos mecânicos de recursos no domínio de Ops.
  • Fluxo 5: Anotações em cascata (metadados contextuais): Os dados contextuais amplos (como domínios operacionais, namespaces ou códigos de faturação) são tratados através de anotações em cascata, evitando a poluição pela difusão de infra. Estas são segregadas em buckets com base na sua origem, e o uso previsto de cada bucket abaixo é um contrato social: um template de Recipe pode ler os três, e o compilador não impõe a separação (ver labels-and-annotations):
    • .context.annotations.release (fronteiras do Domínio 4): Usadas exclusivamente para governar realidades físicas. O Ops encaminha explicitamente estas anotações para campos infra locais estritos através de 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. Estas anotações são explicitamente encaminhadas para os payloads values do componente (por exemplo, fazendo descer em cascata um código de faturação da equipa até uma configuração da aplicação).
    • .context.annotations.catalog (Catálogo do Domínio 2): Traços intrínsecos imutáveis criados pelo arquiteto, usados sobretudo para a avaliação programática de políticas Wasm.
  • Fluxo 6: O pipe de metadados (.context): Aplica requisitos empresariais globais (etiquetas SOC2) diretamente aos templates de infraestrutura física.

3. Abstração de rede: a convenção «Zero-Port»

  • A boa prática: Os programadores devem omitir as portas do Aggregate. A Recipe de Ops trata o encaminhamento interno de forma dinâmica.
  • A via de escape: Se o código interno de uma aplicação não puder ser alterado, o arquiteto de plataforma expõe explicitamente um campo port na declaração schema:. Nota arquitetural: A convenção «Zero-Port» é o exemplo mais proeminente da separação de responsabilidades mais ampla da plataforma. Esta mesma filosofia — abstrair a mecânica física do programador — aplica-se a pedidos de CPU, limites de memória, domínios operacionais e dimensionamento de discos. Sempre que uma restrição de infraestrutura física tenha de passar para o payload da aplicação do programador (devido a código legado ou a requisitos de hardware estritos), deve ser sempre governada por uma «via de escape» explícita na declaração schema: do arquiteto, a declaração com base na qual o payload do programador é validado.

O nome «Zero-Port» designa esta convenção; o princípio generaliza-se a qualquer restrição de infraestrutura física que uma aplicação legada codifique. O esquema abaixo usa tcp_keepalive_seconds como exemplo trabalhado — uma temporização de kernel/rede que a aplicação espera na camada de sockets — porque se situa claramente no eixo da fuga de infra.

O esquema (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 programador (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 lê depois {{ .values.tcp_keepalive_seconds }} para configurar a pod spec do Kubernetes ou o tempo limite de inatividade do balanceador de carga do fornecedor cloud, colmatando com êxito a lacuna legada sem violar o esquema.

4. O contrato de injeção e o mapa pré-resolvido

Entre as cinco palavras-chave estruturais, inject tem uma forma diferente das restantes. parameters, values, uses e infra são estado declarativo — o programador escreve factos sobre o que a aplicação é e de que depende. inject é um comando imperativo — o programador dita como um valor deve ser entregue ao contentor em execução, mapeando origens de dados abstratas (as chaves provides de um destino, os próprios valores do componente, a resposta do cofre de uma Feature de credenciais) para mecanismos de entrega concretos (env, file, arg ou um mecanismo personalizado que o Component declara).

Este desacoplamento é estrutural. O Aggregate do programador diz «injeta o anfitrião da base de dados como a variável de ambiente DB_HOST» sem nomear o endereço físico da base de dados, o caminho do cofre de segredos nem o formato de nome de anfitrião do fornecedor cloud. A Recipe de Ops recebe a cadeia resolvida através de .context.inject e consome-a sem criar a cadeia de pesquisa.

O mapa pré-resolvido. Durante a renderização, o compilador resolve cada origem de injeção — literais de autoinjeção e referências from: contra os próprios provides do componente, referências entre componentes através de uses[].inject, interceções injectMapping de FeatureRecipe — num único dicionário plano em .context.inject. Quando o template valuesMapping da Recipe base é executado, cada chave de injeção já tem o seu valor de cadeia final. As Recipes iteram diretamente sobre o mapa ({{ range $k, $v := .context.inject.env }}) sem percorrer a cadeia de resolução.

Os nomes que o programador dá aos valores próprios do componente. Quando o Component declara spec.inject, o bloco inject: do próprio programador escolhe os nomes sob os quais os valores próprios e os provides do componente chegam ao canal de entrega. O compilador indica à Recipe, em .context.self_inject, o único valor próprio que o template de cada entrada lê — por mecanismo, cada nome associado a provides.<key>, a values.<key> para um template que lê exatamente um valor próprio e nada mais, ou a uma cadeia vazia — na forma que os nomes de uma ligaçã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 programador é tratar como predefinições os nomes que, de outro modo, escolheria para os valores próprios do componente, entregando um valor próprio sob o seu nome predefinido apenas quando nenhuma entrada já o associa. Trata-se de uma convenção do catálogo, não de uma regra do compilador: um catálogo empresarial pode entregar os valores próprios dos seus componentes como entender. O compilador lê o mapa a partir do texto que o programador escreveu e não atribui qualquer 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 interceção da FeatureRecipe e exemplos trabalhados — encontra-se em topology-triad.

5. O motor de templates (DX de Ops)

Os engenheiros de Platform Ops criam os templates de tradução e precisam de todo o poder dos templates de infraestrutura padrão, sem uma linguagem de templates proprietária. Os templates do Aggrega são Go text/template:

  • Sem cadeias «mágicas»: O compilador preserva as chaves de mapa exatas do programador. O Ops acede às funcionalidades de forma segura através da indexação padrão de mapas Go: {{ (index .features "public-route").infra.hostname }}.
  • A biblioteca Sprig: O compilador regista nativamente a biblioteca Sprig, padrão no Helm, dando acesso imediato a pipelines como | default, | quote e | toYaml.
  • Fragmentos de MappingLibrary: Um fragmento de mapeamento que várias Recipes reutilizam reside numa MappingLibrary e é trazido para cada Recipe com $import:. Os helpers de templates de charts do Helm (include, tpl, required, warn) não estão registados; sprig-functions lista os que estão.

6. Regras de composição: Aggregates, subsistemas e Components

  • Agrupamento lógico (o array subsystems): Os programadores podem aplicar metadados lógicos (propriedade de equipa, etiquetas de conformidade) e funcionalidades transversais a dezenas de componentes em simultâneo usando subsystems. Os subsistemas atuam como pastas recursivas no plano lógico/de intenção, fazendo descer em cascata annotations para o bucket .context.annotations.aggregate e anexando funcionalidades a todos os componentes contidos, sem ditar fronteiras físicas. As funcionalidades ao nível do subsistema seguem o mesmo esquema que as funcionalidades ao nível do componente (suportando type, values, uses, inject) porque estão no Domínio 1 (intenção do programador). O compilador achata as funcionalidades do subsistema na lista de funcionalidades de cada componente contido na finalização do grafo, posicionadas depois das funcionalidades próprias do componente e antes de quaisquer funcionalidades anexadas 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
  • Os Aggregates compostos SÃO SUPORTADOS (o padrão de módulo): Os Aggregates funcionam tanto como o Aggregate raiz que uma Release constrói como módulos reutilizáveis. Um Aggregate pai pode declarar um Aggregate filho exatamente como um componente, passando-lhe parameters. Para evitar acoplamento forte, os Aggregates filhos expõem um contrato exportedComponents:, estabelecendo um nome de interface pública estável. O pai só chega aos componentes do módulo através desta interface: um destino uses: nomeia o módulo e um dos seus aliases exportados, e o compilador liga a aresta ao componente interno que o alias nomeia, enquanto um destino que entre num módulo por qualquer outro nome interrompe a compilação, indicando o módulo e os aliases que exporta. Um módulo pode ele próprio reexportar o componente exportado de um módulo aninhado sob o seu próprio nome de interface — opcionalmente renomeando-o — e o compilador resolve essa cadeia de reexportação de forma transitiva até ao nó interno subjacente, pelo que os módulos se compõem a qualquer profundidade sem que um pai precise de saber a que profundidade o destino está aninhado. Um destino que não se resolve para nenhum nó interno continua a interromper a compilação de forma ruidosa, 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
  • Os Components não podem conter subcomponentes: Os Components são blocos de construção atómicos. A composição acontece ao nível do Aggregate, através de subsistemas e subaggregates. Se uma aplicação precisar de vários contentores físicos (como uma API + um sidecar), esse aninhamento físico vive dentro do template da Recipe de Ops, não na definição do Component.

  • Um serviço coerente por Component — a fronteira de carga de trabalho única: Um Component modela um serviço coerente — um único serviço exposto, ou a(s) carga(s) de trabalho de um serviço juntamente com as suas cargas de trabalho auxiliares apenas internas. A sua etiqueta component.aggrega.ai/type indica a forma operacional desse serviço. Várias cargas de trabalho físicas dentro de um único Component são aceitáveis quando formam um produto coerente sem partes utilizáveis de forma independente: um serviço cujo chart executa um controlador, um webhook e um injetor continua a ser um Component. O critério não é haver várias cargas de trabalho; é a utilização independente.

    A fronteira traça-se onde um pacote contém algo de que outro componente poderia fazer use de forma significativa por si só — sobretudo infraestrutura externa, como uma base de dados, uma cache ou um message broker, que o Aggrega já modela como Component próprio. Esse pacote não é um Component; é um módulo de subaggregate — o padrão spec.aggregates + exportedComponents mostrado acima — que compõe um Component por serviço, para que cada serviço seja um nó endereçável com o seu próprio tipo, as suas próprias arestas e a sua própria superfície de políticas e de escala.

    A heurística, enunciada como regra clara: O chart contém algo que outro componente poderia usar de forma significativa por si só, ou para o qual o Aggrega já tem um Component? Se sim, modelar como uma stack — um módulo de subaggregate que compõe Components por serviço. Se só alguma vez serve este serviço, modelar como um Component.

    Envolver todo um produto multisserviço como um único Component opaco é um antipadrão documentado. O compilador é sem opiniões próprias e aceita-o — renderiza o que passar a validação de esquemas —, mas a biblioteca padrão compõe Components por serviço num módulo, porque um envolvimento monolítico esconde os serviços modeláveis de forma independente da topologia, do seletor e das políticas e da escala por serviço. Esta disciplina de granularidade é um contrato social — ver ../language-reference/vocabulary/social-contracts.md (granularidade do Component).

7. O âmbito predefinido — divulgação progressiva do agrupamento

subsystems (no Aggregate) e boundaries (na Release) são as construções de agrupamento, mas um programador não tem de as declarar logo de início. Cada entidade oferece duas formas de criação, e são mutuamente exclusivas: criar componentes agrupados sob âmbitos nomeados, ou criar componentes diretamente no nível superior — nunca ambos ao mesmo tempo. Um documento que declare tanto components de nível superior como âmbitos nomeados interrompe-se no carregamento com um erro de envelope.

Para a forma plana (components de nível superior), o compilador sintetiza um âmbito default real no carregamento e coloca nele os componentes de nível superior, para que cada passagem a jusante veja uma estrutura uniforme com âmbitos. O âmbito sintetizado não é um contentor oculto: é um nó genuíno da IR, marcado com a sua proveniência, distinguível de um âmbito a que um programador chame explicitamente default. Só está oculto onde o autor lê caminhos — os diagnósticos e o endereçamento apresentam o .spec.components[…] com forma de raiz que o programador efetivamente escreveu.

  • Aggregate plano (componentes de nível superior): Criar componentes em spec.components sem subsystems. O compilador coloca-os num subsistema default sintetizado no carregamento. As anotações de âmbito de subsistema e as funcionalidades ao nível do subsistema aplicam-se apenas a subsistemas declarados; a forma plana não tem nenhum.
  • Release plana (componentes de nível superior): Criar componentes em spec.components sem boundaries. O compilador coloca-os numa fronteira default sintetizada cuja saída é plana — os artefactos ficam diretamente em dist/ (por fornecedor: dist/compose/, dist/helm/, …), sem segmento com o nome da fronteira. Este é o caso mais simples: aggrega build sobre um destino Compose plano ou de cluster único, sem nomear fronteiras. (Uma fronteira que um programador declara e a que chama 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 para uma que precisa de agrupamento (namespaces diferentes, agrupamentos lógicos separados, implantação em várias fronteiras), o programador move os componentes de nível superior para subsystems explícitos, ou o Ops introduz boundaries explícitas. Como as duas formas são mutuamente exclusivas, trata-se de passar da forma plana para a forma com âmbitos — não de misturar ambas — e a identidade dos nós é preservada na transição.

O raciocínio é a divulgação progressiva: exigir agrupamento obrigatório para casos de uso triviais (uma demonstração de serviço único, um protótipo local rápido) cria fricção desnecessária. O teste de integração «do zero ao funcionamento em 10 minutos» exige que um programador possa escrever um Aggregate mínimo com um componente, um Manifest e uma Release e obter uma saída funcional sem antes compreender subsistemas ou fronteiras. O âmbito predefinido é a rampa de acesso; os âmbitos 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 esquemas 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 restantes são convenções que o compilador não verifica.

  • Padrão recomendado: Parameter Hoisting através de cadeias de template

    • Exemplo: O programador escreve workers: {{ .parameters.env_workers }} no seu bloco values, sem aspas, para que o valor chegue como o inteiro que foi declarado.
    • Porquê: Se o Aggregate declarar env_workers como parâmetro tipado (type: integer), o compilador valida primeiro o valor fornecido pela Release contra o contrato. A validação do contrato de parâmetros acontece antes da interpolação; a interpolação acontece antes da validação de esquema values: envolvente. Isto preserva a reutilização do Aggregate: o Ops fornece o inteiro através dos parameters: da Release, o compilador valida-o contra a declaração tipada parameters:, substitui o valor resolvido no documento, e a declaração schema: do Component valida com êxito o inteiro resultante.
  • Restrição 1: as credenciais são anexações, não valores

    • Padrão desaconselhado: O programador escreve values: { password: "123" } num componente.
    • Porquê: a convenção da biblioteca padrão é que uma credencial é pedida como anexação em features:, nomeando um type de Feature de credenciais (uma com a etiqueta feature.aggrega.ai/kind: secret) e usando os próprios values dessa anexação para descrever a consulta a um cofre de segredos. Isto é uma convenção, não uma verificação do compilador — o compilador não interpreta o que significa uma folha values e transporta um literal inline tal como está. A superfície de anexação é o que torna disponível e tipada a forma bem criada.
  • 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.
    • Porquê: Os Components são agnósticos em relação às capacidades por convenção. Os alvos de hardware físico vivem 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: O Ops escreve {{ if eq .context.labels.gpu "true" }} numa Recipe para alterar fundamentalmente a estratégia de implantação.
    • Porquê: O pipe .context contorna a validação schema: por pilar. Depender de etiquetas não validadas para a lógica central de infraestrutura torna a plataforma frágil. O objeto .context transporta etiquetagem de metadados (por exemplo, faturação, SOC2); o encaminhamento estrutural pertence aos pilares validados por esquema.
  • Restrição 4: a Release não pode substituir os valores do programador

    • Padrão não suportado: O Ops tenta substituir a lógica cognitiva de um programador (por exemplo, mudar workers: 4 para workers: 10) a partir da Release.
    • Porquê: O Aggregate é a fonte única de verdade da intenção do programador. Se um valor estiver codificado no Aggregate, é imutável entre ambientes. Se um valor tiver de mudar por ambiente, o programador usa Parameter Hoisting. O esquema da Release impõe isto proibindo blocos values, limitando o Ops a cumprir o contrato parameters e a definir o infra físico.
  • Restrição 5: etiquetas ao nível da instância no Aggregate

    • Padrão não suportado: O programador escreve labels: {} numa instância de componente dentro do Aggregate.
    • Porquê: As etiquetas são traços imutáveis ao nível do Catálogo, criados pelo arquiteto de plataforma — a identidade semântica que os motores de políticas e os seletores leem. A Release encaminha componentes para fronteiras através de uma seleção explícita por ID baseada em mapas (components: { "my-agent": {} }), o que preserva a possibilidade de aninhar infra e substituições de funcionalidades por componente, sem misturar a autoria de etiquetas no Aggregate do programador.

9. O perímetro de segurança e as barreiras explícitas de saída (destinos fora do perímetro)

Nenhuma aplicação existe no vácuo. Uma arquitetura Aggrega compilada representa um grafo estritamente mapeado. No entanto, os sistemas de IA modernos interagem constantemente com entidades fora deste perímetro compilado — como LLM SaaS públicos (Anthropic, OpenAI), APIs públicas genéricas (Stripe, Twilio) ou bases de dados brownfield legadas (Oracle on-premises).

Para integrar estes sistemas externos de forma segura, o Aggrega separa estritamente a fronteira de segurança da mecânica de execução. A fronteira de segurança é governada pela regra universal do Component e pela barreira explícita de saída.

1. A regra universal do Component

Se uma aplicação interage com uma entidade — seja uma base de dados local, um recurso cloud gerido, um LLM SaaS ou um endpoint de API pública genérica —, essa entidade TEM de ser declarada como um Component distinto no Aggregate. Esta regra é uma convenção: o compilador não consegue ver uma chamada que a aplicação faz, pelo que nada a verifica.

Ao tratar as APIs SaaS externas e as bases de dados legadas como nós de primeira classe no grafo da Representação Intermédia (IR), os programadores ganham a possibilidade 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 programador pode anexar-lhe uma funcionalidade header-injector, garantindo que a configuração gerada impede que o agente chamador guarde o token de API em bruto na sua própria memória.

2. A barreira explícita de saída (conformidade da infraestrutura)

Em vez de depender de lógica codificada no compilador para governar a saída de rede, o Aggrega delega a segurança do perímetro inteiramente nos motores de políticas agnósticos e nos plugins de renderização Wasm da empresa. Isto garante que as configurações geradas estão estritamente em conformidade com as aprovações explícitas de saída.

  • O gancho do catálogo (Domínio 2): Quando um arquiteto define um componente SaaS público (por exemplo, core/external-service), anexa-lhe uma etiqueta corporativa imutável (por exemplo, security.enterprise.com/zone: "untrusted-external").
  • A barreira de políticas (tempo de compilação): Antes de ser gerada qualquer configuração, o motor de políticas OPA ou Kyverno avalia o grafo. A empresa cria uma regra simples: «Se um nó interno se ligar a um nó com a etiqueta untrusted-external, o ID desse nó de destino tem de estar listado explicitamente no array parameters.approved_egress do ambiente.» Se um programador tentar encaminhar dados para um destino externo não aprovado, o motor de políticas interrompe a compilação.
  • A geração da configuração (no momento da renderização): Se a política for aprovada, a regra de saída é renderizada a partir do que o operador anexou. A Feature core/egress-allowlist, anexada ao componente chamador na Release, renderiza em helm uma NetworkPolicy do Kubernetes por cada workload que esse componente renderiza, admitindo saída apenas para os seus próprios pods, para os pods dos destinos das 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. A compilação é interrompida a menos que a Release afirme, com infra.control_plane_present: true, que o plugin de rede do cluster aplica network policies, e é interrompida indicando qualquer ligação externa desse tipo sem intervalo de endereços listado; em compose, que não tem network policy, a anexação interrompe a compilação. O programador nunca escreve uma regra de firewall.

Isto garante — através de um papel de veredicto de governação que avalia a topologia declarada — que a infraestrutura declarada explicitamente está em conformidade com a política de saída, sem que o compilador Go central precise de compreender o que significa «externo». (Nota: a verdadeira saída zero-trust depende de o cluster de destino executar uma CNI Default Deny em tempo de execução; as configurações geradas limitam-se a mapear as exceções autorizadas).

Um Component por serviço externo

Cada serviço externo é declarado como um componente distinto, não reunido num array com vários destinos. Se uma aplicação chamar cinco APIs de terceiros diferentes, o programador declara cinco componentes core/external-service distintos. É esta declaração por serviço que permite aos motores de políticas e aos plugins Wasm visar individualmente cada destino de saída — anexando políticas de saída diferentes, funcionalidades de proxy diferentes ou ganchos de observabilidade diferentes a cada dependência externa.

Desacoplar a segurança da execução (o cenário «brownfield»)

É fundamental notar que a etiqueta semântica (por exemplo, untrusted-external) dita a política de segurança de rede, não a execução. É independente de o Aggrega renderizar ou não artefactos que aprovisionam o recurso.

  • Cenário A (API SaaS pública): Com a etiqueta untrusted-external no Catálogo (aciona as barreiras de saída das políticas). Realizado por uma carga de trabalho de referência (sem computação aprovisionada; ver §10).
  • Cenário B (base de dados legada interna): Com a etiqueta internal-trusted (contorna as barreiras de saída, fica dentro da VPC). Realizado por uma carga de trabalho de referência (sem computação aprovisionada; ver §10).
  • Cenário C (base de dados autoalojada): Com a etiqueta internal-trusted. Executado através do plugin de renderização Helm (aprovisionado fisicamente como um StatefulSet Kubernetes).

10. Serviços que a compilação não aprovisiona: Workloads de referência

Quando uma aplicação interage com uma base de dados legada on-premises ou com uma API SaaS pública (como o Stripe), a regra universal do Component dita que estas entidades externas têm de ser declaradas como componentes distintos no Aggregate. No entanto, o Aggrega não deve tentar gerar para elas um artefacto físico de Pod Kubernetes ou de instância AWS RDS.

A Recipe que realiza um componente deste tipo declara um Workload de form: reference: um endpoint — um host ou um URL —, opcionalmente uma port, e nenhum contentor. O compilador faz passar ambos como cadeias de ponteiros determinísticos e nunca os resolve. O que um fornecedor renderiza para um Workload de referência é da responsabilidade do próprio fornecedor: helm emite um Service ExternalName que transporta o host do endpoint, para que as cargas de trabalho no cluster possam chegar a um serviço cujo endpoint é um nome DNS através de um nome estável interno ao cluster; compose não renderiza nada para ele. O Kubernetes trata um externalName como um nome DNS, pelo que um endpoint escrito como endereço IP é alcançado no endereço que um consumidor recebe, e não através do Service.

Em ambos os fornecedores, os provides: da Recipe chegam a cada consumidor através de .context.uses e do contrato inject exatamente como os de um componente aprovisionado. A ligação de um consumidor não muda, portanto, quando o seu destino passa de aprovisionado a referenciado: muda apenas a Recipe para a qual o Manifest mapeia o destino.

A pipeline de execução passo a passo

1. Domínio 1 (o Aggregate): intenção do programador O programador pede uma base de dados Oracle legada. Não lhe interessa onde vive; limita-se a ditar que o seu agente chamador espera que a cadeia de ligação seja entregue como variável de ambiente. Como o IP é estático e conhecido antecipadamente, passa-o através 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 encaminhamento O Ops mapeia o tipo da base de dados legada para a Recipe que formata a sua cadeia de ligação. O Manifest nomeia uma Recipe e nada mais; a Recipe que nomeia declara um Workload de form: reference, e é essa forma que impede o nó de aprovisionar computação. O encaminhamento mantém-se 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): estruturar a passagem O engenheiro de Ops escreve a Recipe. Esta constrói a cadeia de ligação primary_endpoint a partir dos values do programador no seu bloco locals, publica-a em provides e declara um Workload de referência que aponta para o host da base 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", o seu primary_endpoint é oracle://10.0.4.55:1521/PROD_DB.
  2. Em helm, o Workload de referência renderiza um Service ExternalName, legacy-oracle, com externalName: 10.0.4.55 e a porta 1521; em compose, não renderiza nada.
  3. O compilador renderiza depois a Recipe de my-agent. O seu pipe .context.uses transporta 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): cumprir o contrato A receita Helm padrão do worker Python lê o mapa de injeção que recebeu, exatamente como faria para uma base de dados que a compilação aprovisiona.

# 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. Encaminhamento entre pilares por ponte de esquema: ligar a intenção à infraestrutura

Ver inheritance-and-interface para o padrão de ponte de esquema que expõe com segurança controlos de infraestrutura especializados através de componentes filhos — um campo values: visível para o programador, declarado no schema: do Component, que o template valuesMapping: da Recipe encaminha para a saída renderizada com a forma de infra:.

12. Aprovisionamento greenfield («Aggregates de plataforma»)

Uma armadilha recorrente na engenharia de plataformas é obrigar o encaminhador (o ficheiro Release) a tratar o pesado aprovisionamento de clusters do Dia 0 (por exemplo, criar um novo cluster AWS EKS antes de implantar a aplicação nele). Isto cria ficheiros de encaminhamento longos e difíceis de ler.

O Aggrega trata isto com o princípio «tartarugas até ao fundo» (Turtles All the Way Down). O esquema da Release não tem nenhum bloco para instalar infraestrutura; o aprovisionamento de clusters é modelado com Aggregates de plataforma.

Como um cluster AWS EKS, um plano de controlo Istio e uma VPC AWS são, em última análise, apenas recursos cloud físicos, são modelados exatamente como componentes de aplicação.

  1. O Aggregate de plataforma: A equipa de infraestrutura escreve um Aggregate.yaml padrão em que os componentes são core/aws-vpc, core/eks-cluster e core/istio-base.
  2. A Release de plataforma: A equipa implanta este aggregate. O renderizador vinculado a estes componentes de plataforma produz os artefactos necessários para pôr de pé a infraestrutura base.
  3. A Release da aplicação: Quando o programador de aplicações está pronto para implantar o seu agente de IA, a equipa de Ops limita-se a visar o cluster recém-criado com uma fronteira no próprio ficheiro Release da aplicação.