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 pelaRelease(CI/CD) inline emparameters:ou através deparameters: { $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: 2paraworkers: 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 inlineparameters:. A sobreposição de vários ficheiros exprime-se através de cadeiasextends:da Release.
- Âmbito: Definido na raiz do
values(a intenção cognitiva - detida pelo programador)- Âmbito: Usado uniformemente dentro de
componentse das respetivas anexaçõesfeaturesnoAggregate, 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).
- Âmbito: Usado uniformemente dentro de
uses(a topologia estrutural - estado declarativo)- Âmbito: Usado uniformemente dentro de
componentse das respetivas anexaçõesfeaturesnoAggregate, 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
usesSchemaunificada do Catálogo para impor a segurança de tipos entre nós.
- Âmbito: Usado uniformemente dentro de
infra(a realidade física - detida pelo Ops)- Âmbito: Usado uniformemente dentro dos
componentsde uma fronteira e das respetivas anexaçõesfeaturesnaRelease. - 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çõesfeaturesnão incluem um campoinfrae, combinadas comadditionalProperties: false, rejeitaminfrana validação de esquemas. Validado pela declaraçãoschema:unificada do Catálogo.
- Âmbito: Usado uniformemente dentro dos
inject(o contrato de entrega - comando imperativo)- Âmbito: Usado numa instância de componente, dentro de definições de destino explícitas em
usese nasfeaturesanexadas, 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,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 na Recipe de Ops subjacente. Cada mecanismo é uma lista de entradas ([{ in: API_HOST, from: "host" }]), cada uma a nomear o seu identificador local comin:e a transportar exatamente um defrom:ouvalue:.
- Âmbito: Usado numa instância de componente, dentro de definições de destino explícitas em
.context(o pipe genérico de metadados)- Âmbito: Injetado silenciosamente pelo compilador nos templates da
Recipede 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.
- Âmbito: Injetado silenciosamente pelo compilador nos templates da
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 tipadoparameters:e depois interpola as variáveis de template Go resolvidas antes de executar a validação de esquemavalues:a jusante.- Utilização recomendada: os
parametersestã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 blocoinfradaReleasee das sobreposições de fronteira, mantendo oAggregatedo 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
parameterspodem 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.
- Utilização recomendada: 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 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 (
valuesem 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 transportavaluesdo programador: as operações anexam-na na Release, com o seuinfra(Fluxo 4). - Fluxo 4: Dimensionamento da infraestrutura física (
infra): Contornando totalmente o programador, o dimensionamento físicoinfraé projetado explicitamente a partir daReleaseespecí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 dimensionamentoinfraé 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 camposinfralocais 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 payloadsvaluesdo 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
portna declaraçãoschema:. 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çãoschema: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 versaComportamento 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,| quotee| 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 usandosubsystems. Os subsistemas atuam como pastas recursivas no plano lógico/de intenção, fazendo descer em cascataannotationspara o bucket.context.annotations.aggregatee 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 (suportandotype,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.
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 contratoexportedComponents:, estabelecendo um nome de interface pública estável. O pai só chega aos componentes do módulo através desta interface: um destinouses: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.
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-
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/typeindica 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
usede 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ãospec.aggregates+exportedComponentsmostrado 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.componentssemsubsystems. O compilador coloca-os num subsistemadefaultsintetizado 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.componentssemboundaries. O compilador coloca-os numa fronteiradefaultsintetizada cuja saída é plana — os artefactos ficam diretamente emdist/(por fornecedor:dist/compose/,dist/helm/, …), sem segmento com o nome da fronteira. Este é o caso mais simples:aggrega buildsobre um destino Compose plano ou de cluster único, sem nomear fronteiras. (Uma fronteira que um programador declara e a que chamadefaulté 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 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
subsystemsexplícitos, ou o Ops introduzboundariesexplí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.
8. Restrições arquiteturais e padrões recomendados
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 blocovalues, sem aspas, para que o valor chegue como o inteiro que foi declarado. - Porquê: Se o Aggregate declarar
env_workerscomo 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 esquemavalues:envolvente. Isto preserva a reutilização do Aggregate: o Ops fornece o inteiro através dosparameters:daRelease, o compilador valida-o contra a declaração tipadaparameters:, substitui o valor resolvido no documento, e a declaraçãoschema:do Component valida com êxito o inteiro resultante.
- Exemplo: O programador escreve
-
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 umtypede Feature de credenciais (uma com a etiquetafeature.aggrega.ai/kind: secret) e usando os própriosvaluesdessa 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 folhavaluese transporta um literal inline tal como está. A superfície de anexação é o que torna disponível e tipada a forma bem criada.
- Padrão desaconselhado: O programador 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. - 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
.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: O Ops escreve
{{ if eq .context.labels.gpu "true" }}numaRecipepara alterar fundamentalmente a estratégia de implantação. - Porquê: O pipe
.contextcontorna a validaçãoschema:por pilar. Depender de etiquetas não validadas para a lógica central de infraestrutura torna a plataforma frágil. O objeto.contexttransporta etiquetagem de metadados (por exemplo, faturação, SOC2); o encaminhamento estrutural pertence aos pilares validados por esquema.
- Padrão não suportado: O Ops escreve
-
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: 4paraworkers: 10) a partir daRelease. - Porquê: O
Aggregateé a fonte única de verdade da intenção do programador. Se um valor estiver codificado noAggregate, é imutável entre ambientes. Se um valor tiver de mudar por ambiente, o programador usa Parameter Hoisting. O esquema daReleaseimpõe isto proibindo blocosvalues, limitando o Ops a cumprir o contratoparameterse a definir oinfrafísico.
- Padrão não suportado: O Ops tenta substituir a lógica cognitiva de um programador (por exemplo, mudar
-
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 doAggregate. - 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 aninharinfrae substituições de funcionalidades por componente, sem misturar a autoria de etiquetas no Aggregate do programador.
- Padrão não suportado: O programador escreve
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 arrayparameters.approved_egressdo 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 emhelmumaNetworkPolicydo 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 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. A compilação é interrompida a menos que a Release afirme, cominfra.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; emcompose, 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-externalno 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 key2. 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/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", o seuprimary_endpointéoracle://10.0.4.55:1521/PROD_DB. - Em
helm, o Workload de referência renderiza um Service ExternalName,legacy-oracle, comexternalName: 10.0.4.55e a porta1521; emcompose, não renderiza nada. - O compilador renderiza depois a Recipe de
my-agent. O seu pipe.context.usestransporta osprovidesdo nó Oracle, e o contrato de injeção já resolveuORACLE_DSNcom 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.
- O Aggregate de plataforma: A equipa de infraestrutura escreve um
Aggregate.yamlpadrão em que os componentes sãocore/aws-vpc,core/eks-clusterecore/istio-base. - 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.
- 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
Releaseda aplicação.