provides, inject, uses
O contrato de injeção e o mapa pré-resolvido
Como o Aggrega é um compilador estático de compilação antecipada (AOT), nenhum dado flui de volta da infraestrutura em execução durante a compilação. É mecanicamente impossível o compilador buscar ativamente uma credencial física (como um segredo da AWS) e passá-la “de volta” ao ambiente do contêiner do Desenvolvedor.
Em vez disso, a plataforma se apoia na verdadeira inversão de controle. Quando um desenvolvedor escreve inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] }, ele não está iniciando uma busca de dados; está ditando um contrato estrito à infraestrutura.
- A intenção (Domínio 1): O Desenvolvedor declara uma interface abstrata: “Preciso de um segredo. Não sei onde ele fica. Apenas injete-o no meu ambiente como
ORACLE_PASSWORD, mapeado para a chavepassworddo catálogo.” - A transferência do compilador (na renderização): O compilador Go pega a entrada
{ in: ORACLE_PASSWORD, from: "password" }e a entrega à Recipe de Ops. Nenhum segredo físico é buscado. - A saída do Plugin (Domínio 3): O pipeline Wasm da FeatureRecipe de credenciais gera os artefatos precisos e interligados exigidos pela infraestrutura de destino. Por exemplo, no Kubernetes, ele gera o CRD
ExternalSecret(instruindo o cluster a buscar os dados do vault) E executa um JSONPatch no Pod de destino para mapear o Secret local do K8s resultante especificamente para a variável de ambiente"ORACLE_PASSWORD"solicitada pelo desenvolvedor. - A realidade em tempo de execução: Em tempo de execução, um operador no cluster simplesmente executa esses artefatos gerados—buscando a credencial e montando-a fisicamente no contêiner—, desacoplando completamente a mecânica física de segurança do compilador AOT.
Para entregar essa realidade física à aplicação sem violar a separação de responsabilidades, o Aggrega utiliza o Injection Contract. No entanto, esse contrato diferencia estritamente o código de aplicação personalizado da infraestrutura comercial pronta para uso (COTS):
- White-Box (código personalizado): O componente é um worker genérico (por exemplo, um agente Python personalizado). O compilador Go e a Recipe de Ops não fazem ideia de quais variáveis o script personalizado do desenvolvedor espera. Por isso, o Desenvolvedor dita a entrega por meio do bloco
inject:onde quer que o código leia nomes que sua Recipe não entrega por padrão — tanto para dependências entre componentes (viauses[].injectcomfrom:referenciando osprovidesdo destino) quanto para os valores próprios do componente (viainjectno nível do componente com literaisvalue:oufrom:referenciando seus própriosprovides). Quais mecanismos são permitidos é declarado por superfície, e as duas declarações são separadas: os valores próprios do componente são regidos pela allowlistspec.inject(por exemplo,inject: ["env", "file"]), enquanto uma arestauses:é regida pela allowlist do socket pelo qual ela é conectada,spec.usesSchema.<socket>.inject. Ditar um mecanismo que a allowlist aplicável não nomeia interrompe o build em qualquer uma das superfícies. - Black-Box (computação empacotada): O componente é um sistema fechado (por exemplo, Redis, um API Gateway gerenciado). A Recipe de Ops já sabe exatamente como o sistema consome seus dados. Por isso, a entidade de catálogo do Component omite a allowlist, o que proíbe o ditado por completo em vez de restringi-lo — omitir
spec.injectproíbe o self-inject no nível do componente, e um socket declarado sem uma allowlistinject:proíbe qualquer blocoinject:em uma aresta conectada por meio dele. O Desenvolvedor simplesmente fornece o destino da dependência viauses, e a plataforma cuida da conexão interna nativamente via ovaluesMappingda Recipe.
A regra de endereçamento determinístico (física da rede interna) O pipe .context.uses do Aggrega injeta dinamicamente strings de destino nos contêineres em tempo de compilação. Como o compilador Go central é totalmente agnóstico em relação à rede física, o que conta como string de endereço válida depende inteiramente de um contrato social mantido por Platform Ops, não de uma função do compilador — o compilador canaliza qualquer string de ponteiro determinística que a Recipe de Ops tenha produzido para o contexto de template posterior, sem interpretá-la.
A regra: a Recipe de Ops deve exportar um ponteiro de endereço determinístico e estável. O provedor não calcula IPs. Em vez disso, a Recipe de Ops do destino deveria formular uma string previsível e expô-la por meio de seu contrato provides: (por exemplo, publicando provides.internal_host: "http://agent-b.namespace.svc.cluster.local" no Kubernetes, ou uma string de interpolação como "${module.db.endpoint}" no Terraform, em que o módulo declara um output correspondente para o valor).
Depender do compilador para buscar IPs dinâmicos pós-provisionamento viola diretamente o modelo de execução AOT. Como o compilador avalia a topologia antes que a nuvem provisione qualquer computação real, ele não pode buscar fisicamente dados que ainda não existem. Se um serviço exige um IP aleatório que só é gerado depois que a computação inicializa, o compilador não pode buscá-lo fisicamente. A única tarefa do compilador é canalizar a string de ponteiro determinística fornecida pela Recipe de Ops, literalmente, para as variáveis de ambiente do contêiner chamador, deixando a resolução final para o DNS do cluster ou para o gerenciador de estado de IaC ativo.
Impor nativamente o endereçamento determinístico resolve dependências cíclicas (por exemplo, o Agente A delega ao Agente B, e o Agente B delega de volta ao Agente A). Como a URL estável ou o ponteiro de IaC pode ser calculado como string antes que qualquer um dos contêineres realmente inicie, o compilador conecta os dois agentes com segurança, sem introduzir condições de corrida temporais.
(Observação: esta regra também se aplica ao ingress externo. Se uma arquitetura expõe um API Gateway público e exige que essa URL seja injetada de volta em um contêiner interno, o compilador Go não consegue buscar a URL aleatória gerada pela nuvem (por exemplo, xyz123.execute-api.aws.com) porque ela não existe em tempo de compilação. Ops precisa escrever sua Recipe para mapear um domínio personalizado determinístico (por exemplo, api.enterprise.com) ou exportar a string de interpolação nativa de IaC, garantindo que o compilador AOT tenha uma referência conhecida para injetar com segurança).
A mecânica de implementação (o catálogo como contrato de API) Para implementar isso sem acoplar fortemente os Desenvolvedores a Ops, o Aggrega usa o catálogo da plataforma (Domínio 2) como contrato de API estrito, utilizando três camadas distintas de validação:
- O schema da Feature de credenciais (rotulado
feature.aggrega.ai/kind: secret): Valida APENAS a consulta ao vault (path,key). Ele é totalmente agnóstico em relação a como o contêiner consome os dados. - O schema
Component(allowlistspec.inject): Impõe a regra Black-Box/White-Box por meio do campospec.inject. Sespec.injectestiver presente (por exemplo,inject: ["env", "file"]), o desenvolvedor pode usar self-inject no nível do componente com esses mecanismos de entrega. Sespec.injectfor omitido, o compilador proíbe estruturalmente o self-inject — componentes Black-Box dependem inteiramente dovaluesMappingda Recipe para a conexão interna. O build impõe isso quando resolve o Aggregate, recusando o blocoinject:do componente e nomeando o mecanismo, separadamente da validação de conteúdo por pilar emschema:. - O mapa
featuresSchema: Definido no catálogo do Component, declara explicitamente os slots de credenciais que o Desenvolvedor deve (ou pode) usar. Cada entrada especificarequired(padrãofalse), a allowlistinject([]= blackbox,[env, file]= transparente) edescription. Como essas chaves são estáveis e garantidas por contrato, o engenheiro de Ops pode confiar diretamente nelas para ditar de forma confiável destinos determinísticos em seu template Go (por exemplo,existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}"no destinohelm), exportando explicitamente o sufixo do nome por meio de.locals— um local não pode ler.context.rendered_name—, de modo que a FeatureRecipe de credenciais posterior junta as mesmas duas partes e cumpre o requisito sem violar a ordem de execução AOT. Vejaentities/component.mdpara o design completo defeaturesSchema.
A regra de posicionamento estrito: O mecanismo inject: está disponível em três locais no Aggregate do Desenvolvedor:
- Self-inject no nível do Component: Como irmão direto de
values:em uma instância de componente. Injeta os valores literais do próprio componente ou suas próprias chavesprovidesno pipe de entrega. Permitido somente se o catálogo do Component declararspec.injectcom os mecanismos correspondentes. - Cross-inject no nível de uses: Dentro de definições explícitas de destino no bloco
uses:. Injeta as chavesprovidesde um destino de dependência no pipe de entrega. - Inject no nível de Feature/secret: Como irmão de
values:ao anexar funcionalidades e segredos. Injeta as chavesprovidesresolvidas do próprio anexo — a credencial resolvida para um segredo, ou os valores fornecidos por uma funcionalidade — no pipe de entrega.
As três formas preenchem o mesmo pipe .context.inject. A Recipe lê um único pipe unificado, independentemente de quantas fontes contribuíram para ele.
O schema de inject define enums padrão (env, file, arg) para as ferramentas, mas deixa additionalProperties aberto, de modo que um mecanismo personalizado pode ser nomeado (por exemplo, ssm_param para o AWS Systems Manager Parameter Store). Um nome já está reservado: all é a visão mesclada de todos os mecanismos que uma Recipe lê em .context.inject.all, então um bloco inject que nomeia um mecanismo all interrompe o build no envelope do documento, informando isso.
Sintaxe das entradas de inject: Sob um bloco inject, cada mecanismo de entrega — env, file, arg ou um personalizado — é uma lista de entradas, e todo posicionamento usa a mesma forma de entrada. É a palavra-chave que uma entrada carrega, e não o posicionamento em que ela está, que diz o que sua string é, de modo que uma entrada se lê da mesma forma onde quer que apareça. Um mecanismo escrito como mapa em vez de lista, ou uma entrada que carrega as duas palavras-chave, interrompe o build no envelope do documento do Aggregate, nomeando o caminho no Aggregate onde a forma está errada.
Palavras-chave das entradas (from: e value:): Cada entrada usa a palavra-chave in para o identificador local — um nome de variável de ambiente, um caminho de arquivo, um flag de argumento — mais exatamente um entre from: (referência a uma chave de provides) ou value: (string literal). Um from: é resolvido em relação aos provides do nó que seu posicionamento nomeia: os do próprio componente em component.inject, os do destino em uses[target].inject e os do próprio anexo em features[<name>].inject:
| Palavra-chave | Significado | Permitido em component.inject | Permitido em uses[].inject | Permitido em features[<name>].inject |
|---|---|---|---|---|
from: | É resolvido em relação a provides | ✅ provides do próprio nó | ✅ provides do nó de destino | ✅ provides do próprio anexo |
value: | String literal (suporta templates Go) | ✅ | ❌ (value: não é válido em uses[].inject; use inject no nível do componente para self-inject) | ❌ (value: interrompe o build no inject de um anexo; use inject no nível do componente para self-inject) |
Exemplos:
# Component-level self-inject (White-Box custom code)components: my-worker: type: core/python-worker:1.0.0 values: app_token: "xyz" inject: env: - in: MY_TOKEN value: "xyz" # Literal value - in: LOG_LEVEL value: "debug" # Literal value - in: CALLBACK_HOST from: "host" # From own provides (already evaluated) - in: APP_VERSION value: '{{"{{"}} .values.app_token }}' # Go template expanding own values uses: databases: my_db: target: postgres-db inject: env: - in: DB_HOST from: "host" # Provides key from target - in: DB_PORT from: "port" # Provides key from target - in: DB_URL from: "dsn" # From target's providesO template no value: de APP_VERSION começa com {{"{{"}} em vez de {{: o texto inteiro do Aggregate é lido uma vez como template, para a interpolação de parâmetros, antes de a resolução do self-inject ser executada, e .values não existe nesse momento, então o escape devolve {{ para que a resolução do self-inject o avalie. Veja Texto que contém suas próprias chaves duplas.
Nota específica do Provider (compose). Quando arestas uses: são resolvidas entre nós voltados para compose, o provedor compose deriva entradas depends_on dessas arestas. Essas entradas sempre usam a semântica service_started, independentemente do bloco health: de qualquer destino; condicioná-las à saúde do destino não está implementado. Veja providers/compose.md para as regras completas de inferência.
A regra de colisão de chaves de inject: Um desenvolvedor que solicita a mesma chave de entrega (por exemplo, o mesmo nome de variável de ambiente) de duas fontes diferentes é um erro fatal, não uma mesclagem. O compilador detecta a colisão e interrompe o build:
| Fonte A | Fonte B | Resultado |
|---|---|---|
component.inject | uses[].inject | ❌ parada fatal — chave de entrega duplicada |
uses[target_A].inject | uses[target_B].inject | ❌ parada fatal — chave de entrega duplicada |
component.inject | features[<name>].inject | ❌ parada fatal — chave de entrega duplicada |
uses[].inject | features[<name>].inject | ❌ parada fatal — chave de entrega duplicada |
features[A].inject | features[B].inject | ❌ parada fatal — chave de entrega duplicada |
component.inject (a mesma chave duas vezes) | — | ❌ parada fatal — chave de entrega duplicada |
injectMapping da FeatureRecipe de features[A] | injectMapping da FeatureRecipe de features[B] | ❌ parada fatal — chave de entrega duplicada entre dois anexos |
features[A].inject | injectMapping da FeatureRecipe de features[B] | ❌ parada fatal — chave de entrega duplicada entre dois anexos |
component.inject ou uses[].inject | injectMapping da FeatureRecipe | ✅ Legal — interceptação por design: o valor do mapeamento substitui essa entrada |
A tabela vale da mesma forma para toda Feature anexada, onde quer que tenha sido anexada — no componente, em um subsistema ou em uma fronteira da Release, pela expansão de uma anotação, ou em uma conexão. O injectMapping de uma FeatureRecipe é renderizado depois que todo bloco inject: fez sua entrega, então ele é sempre a última de duas reivindicações: pode reescrever o que o componente ou uma de suas conexões entregou, e pode reescrever o que o bloco inject: do seu próprio anexo entregou, mas uma chave que outra Feature anexada já entregou interrompe o build, nomeando ambas.
Uma Feature anexada a uma fronteira da Release cuja FeatureRecipe é renderizada uma vez para a fronteira (executionScope: boundary) alcança os componentes que a fronteira contém pela mesma rota: seu injectMapping é executado uma vez para cada um deles, no contexto daquele componente, e está sujeito às linhas acima como qualquer outro mapeamento. A ponte do compose que reescreve a variável de host de um consumidor para alcançar seu destino por meio de seu gateway é um desses mapeamentos, então outra Feature anexada que entregou a mesma variável interrompe o build, nomeando ambas.
Para evitar boilerplate de template Go nas Recipes, o compilador fornece ambos:
.context.uses: O mapa enriquecido de arestas topológicas (para lógica complexa, referências a segredos e rastreamento de origem)..context.inject: Um dicionário pré-resolvido e achatado no qual o compilador já resolveu todas as fontes de inject (literais de self-inject, referências a provides de self-inject e referências a provides entre componentes) em valores de string finais e, em seguida, aplicou as interceptaçõesinjectMappingde FeatureRecipe.
O contexto de injeção de estado duplo (segurança contra nulos vs. pureza da intenção) Ao gerar configurações para os Modificadores (a FeatureRecipe vinculada a qualquer anexo, de credencial ou não), o compilador precisa equilibrar a segurança contra ponteiros nulos para templates Go, o roteamento dinâmico de rede e a preservação de um grafo agnóstico em relação a capacidades. Para isso, o compilador fornece ao template um contexto de estado duplo:
.inject_raw(a intenção imutável): Representa o blocoinject:do próprio componente exatamente como o desenvolvedor o escreveu no Domínio 1. É imutável. Se o desenvolvedor omitiu o bloco, ele é avaliado comonull. Ops o utiliza especificamente para verificações lógicas (por exemplo,{{ if not .inject_raw }}para aplicar comportamentos de fallback). Por ser imutável, protege os templates de Ops contra falsos positivos se funcionalidades de roteamento interceptarem e modificarem o pipe de entrega físico..context.inject(o pipe pré-hidratado e interceptado): Uma struct paralela, gerada pelo compilador, que representa a realidade física da entrega. Ela começa como um mapa pré-hidratado (por exemplo, mapeandoAPI_HOSTpara a string base do destino"backend-instance"). Fundamentalmente, esse pipe foi projetado para ser interceptado e mesclado em profundidade pelas Features (por exemplo, roteamento de rede) que utilizam o blocoinjectMapping. Quando a Recipe base é renderizada, esse pipe contém as strings totalmente formatadas e fisicamente corretas (por exemplo, um nome de rede completo e correto como"backend-instance.backend-zone.svc.cluster.local"). Seu conteúdo é estruturado comoenv,file,arg(mais quaisquer mecanismos de entrega personalizados permitidos pelas allowlists de inject do Component), com um dicionário.allpré-mesclado que combina todos os mecanismos para uma serialização conveniente do pipe inteiro..context.self_inject(Qual valor próprio cada nome entrega): Lido do mesmo blocoinject:no nível do componente que.inject_raw, no formato em que.context.uses.<alias>.injectfornece os nomes de uma conexão: por mecanismo, cada nome que o desenvolvedor escreveu é mapeado para a chave própria do componente que sua entrada entrega —provides.<key>para uma entradafrom:,values.<key>para um templatevalue:que lê exatamente um dos valores próprios do componente e nada mais, e uma string vazia para qualquer outra coisa (um literal, dois valores, uma leitura de qualquer coisa além dos valores). Isso permite que uma Recipe que executa a imagem própria do desenvolvedor trate seus próprios nomes de variáveis como padrões — entregando um valor próprio sob seu nome padrão somente quando nenhuma entrada já está mapeada paravalues.<key>, de modo que um desenvolvedor que renomeia um valor mantém todos os outros padrões. Essa é a convenção do catálogo da biblioteca padrão, não uma regra do compilador; um catálogo corporativo pode entregar os valores próprios de seus componentes como preferir.
Ops utiliza a struct .context.inject exclusivamente para a serialização segura (por exemplo, {{ toJson .context.inject.all }}) e a geração do roteamento, garantindo que a infraestrutura física receba as coordenadas totalmente resolvidas enquanto a intenção original do desenvolvedor permanece perfeitamente intacta em .inject_raw.
Exemplo de YAML do desenvolvedor (mapa granular):
uses: databases: my-postgres-cluster: target: db-main inject: ssm_param: # Agnostic injection paradigm (AWS Systems Manager) - in: MY_DB_HOST # Local identifier from: "host" # Target provides keyO compilador resolve isso em tempo de compilação (mapeando para strings estáticas ou nomes DNS internos) e passa os dois objetos para a Recipe:
"context": { "uses": { ... raw graph ... }, "inject": { "all": { "MY_DB_HOST": "db-main.internal" }, "ssm_param": { "MY_DB_HOST": "db-main.internal" } }}Configuração com escopo de conexão (values e infra). Além de entregar os provides de um destino via inject, uma aresta pode carregar sua própria configuração — definições por conexão que a Recipe consumidora lê do pipe de topologia enriquecido:
.context.uses.<alias>.values— escrito pelo desenvolvedor, declarado na entradausesdetalhada do Aggregate, validado em relação aovalueSchemado socket..context.uses.<alias>.infra— escrito pelo operador, declarado na Release, validado em relação aoinfraSchemado socket.
O socket (usesSchema[<socket>]) é o contrato do Arquiteto sobre quais conexões são possíveis e que configuração elas podem carregar; values e infra dividem essa configuração por domínio de autoria, espelhando a divisão values/infra nos componentes. Assim, uma aresta tem dois autores: o desenvolvedor conecta a topologia e a ajusta com values no Aggregate, enquanto o operador define infra por conexão na Release, dentro dos sockets que o Arquiteto declarou. A Release também pode conectar uma aresta a um socket declarado, mas não vinculado, apontando para um componente existente; ela não pode redirecionar uma aresta declarada pelo desenvolvedor — veja entities/release.md §“Per-edge connection configuration (Configuração de conexão por aresta)”.
A configuração por aresta tem escopo do consumidor: ela aparece apenas no contexto do nó que escreveu a aresta (a origem da conexão), nunca no contexto do destino. A saída renderizada do próprio destino é, portanto, invariante em relação aos consumidores que se conectam a ele. Uma Feature anexada ao destino é o único lugar em que as conexões são visíveis: sua FeatureRecipe lê quais componentes usam o destino em .context.used_by — de cada um, a identidade, o socket, os provides publicados, o namespace e a fronteira em que está posicionado e, para uma FeatureRecipe que declara que os lê, os fatos de renderização que seus provedores informaram — nunca os values ou a infra da própria conexão. Uma Feature anexada ao consumidor lê, da mesma forma, o que as renderizações de cada um de seus destinos informaram, na entrada dessa conexão em .context.uses.<alias>.render_facts, onde sua FeatureRecipe declara que os lê.
Anexos de conexão (features). Uma conexão também pode carregar anexos próprios — uma credencial que o consumidor apresenta ao componente que essa conexão alcança, por exemplo — em features: na sua entrada, indexados por um slot que o socket declara em seu featuresSchema. Os mesmos dois autores os dividem: o desenvolvedor anexa na entrada de conexão do Aggregate com type e values, e o operador dimensiona esse anexo com infra, ou anexa um próprio com type e infra, na entrada da Release. Um anexo em uma conexão não carrega nenhum bloco inject próprio, e é por isso que ele está ausente da regra de posicionamento acima: não é um dos lugares em que um desenvolvedor dita a entrega.
Cada um se torna um anexo do componente consumidor chamado <alias>.<slot>, de modo que tem escopo do consumidor exatamente como a configuração por aresta: sua FeatureRecipe é renderizada do lado do consumidor, e a saída do destino não muda com ele. Ele é mantido fora dos .features da Recipe consumidora, que contém apenas os anexos que o bloco do próprio componente declara; em vez disso, a Recipe o lê sob sua conexão, em .context.uses.<alias>.features.<slot>. Uma conexão traçada por um anexo de Feature não carrega anexos. Veja entities/aggregate.md §“A connection’s own attachments (Os anexos próprios de uma conexão)” e entities/component.md §“Topology Sockets (Sockets de topologia)”.
A. Variáveis de ambiente (env) e resolução dinâmica de destino O mecanismo de entrega padrão para aplicações cloud-native modernas. Para arestas topológicas explícitas (por exemplo, um agente que se comunica com um banco de dados), o Aggrega usa .context.uses para injetar o mapeamento de variáveis de ambiente.
- Caso de uso: Receber nomes DNS internos determinísticos, strings de interpolação de Infrastructure-as-Code (por exemplo,
${module.db.endpoint}) ou ponteiros estáticos do Vault. O compilador conecta essas referências estáticas de forma AOT para que a infraestrutura de runtime ou o controlador GitOps possa resolver os valores reais.
B. Montagens de arquivo (file) Muitos frameworks corporativos de IA esperam que um config.json estruturado ou um certificado .pem exista em um caminho específico no disco, em vez de depender de variáveis de ambiente.
-
Caso de uso: Injetar configurações JSON complexas ou atender SDKs legados que leem do disco.
-
Intenção do desenvolvedor:
features:openai_key:type: core/aws-secrets-managervalues:path: /prod/ai/openaikey: "api_token"inject:file:- in: "/etc/secrets/openai.json" # Local pathfrom: "api_token" # The attachment's provides key -
Realidade de Ops: A Recipe de Ops gera dinamicamente os
Volume,VolumeMounteExternalSecretdo Kubernetes necessários para obter com segurança os dados do cofre e montá-los em/etc/secrets/openai.json.
C. Argumentos de linha de comando (arg) Binários pré-compilados (como nós worker em Rust ou Go) muitas vezes ignoram totalmente as variáveis de ambiente, esperando que os valores sejam passados como flags de runtime em seu comando de execução.
-
Caso de uso: Acrescentar realidades físicas ao comando de inicialização do contêiner.
-
Intenção do desenvolvedor:
features:public-ingress:type: core/external-ingressinject:arg:- in: "--callback-url=" # Local flagfrom: "hostname" # The attachment's provides key -
Realidade de Ops: O hostname é o nome que o ambiente dá ao componente, então o operador o escreve,
api.enterprise.com, nainfradeste anexo na entrada da Release para o componente. O plugin Wasm da Feature recebe a URL pública resolvida por meio do Injection Contract e emite um JSONPatch para acrescentar dinamicamente elementos ao arrayargsdo Kubernetes:["/app/binary", "--callback-url=https://api.enterprise.com"], contornando completamente a Recipe base do Component.