Resolução de dependências
Resolução de dependências do Aggrega e o pilar da topologia estrutural
Na arquitetura Aggrega, as dependências topológicas são mapeadas explicitamente através do pilar de esquema uses, para manter um payload values totalmente opaco. Resolver «quem fala com quem» apresenta um desafio específico: topologias de aplicações complexas, com vários nós, têm de ser mapeadas sem obrigar o programador a escrever encaminhamento de rede explícito, ordens de execução ao nível do orquestrador ou dependências de infraestrutura.
1. A filosofia central: porquê uses?
O bloco uses declara dependências entre componentes como topologia pura: o Component A depende do contrato público provides do Component B, não do endereço físico nem dos detalhes de ligação do Component B. A topologia vive em uses; a configuração vive em values. A separação permite ao compilador ver explicitamente todas as arestas entre componentes, sem as inferir do conteúdo de values.
O Aggrega resolve isto elevando a topologia a um pilar de esquema de primeira classe chamado uses.
- O argumento do proxy semântico: A palavra-chave
usesrepresenta intenção semântica L7. Se um agenteusesuma base de dados, isso permanece semanticamente verdadeiro mesmo que o Platform Ops injete malhas de proxy Wasm transparentes entre eles. - Neutralidade matemática: O compilador Go analisa nativamente a estrutura
usespara desenhar o grafo da Representação Intermédia (IR). Nunca tenta analisar nem consultar a lógica da aplicação do programador (values). - Atomicidade da Feature: O pilar
usesaplica-se de forma idêntica aos Components e às Features (incluindo as Features de credenciais). Isto permite que um proxy sidecar (uma Feature) ou um obtentor de credenciais declare autonomamente as suas próprias dependências de rede, sem poluir a configuração do Component pai.
2. A mecânica do contrato de esquema unificado
Para extrair instruções operacionais sem analisar o payload da aplicação, o sistema depende de declarações JSON Schema 2020-12 estritas que governam estruturas YAML explicitamente separadas.
Domínio 2: o esquema dividido (usesSchema e schema) Para evitar que o Catálogo da Plataforma se fragmente em ficheiros de esquema impossíveis de gerir, o Aggrega utiliza um motor de esquema dividido. O usesSchema em YAML nativo define e valida estritamente a topologia, enquanto schema: (JSON Schema 2020-12 — normalmente criado com a abreviatura de forma compacta) valida o conteúdo dos pilares values e infra e declara a forma do pilar provides. Os values que um programador cria e o infra que um operador define são verificados contra os tipos declarados; o subesquema provides declara os nomes das chaves e os tipos do contrato a jusante que uma Recipe produz, e o compilador verifica que cada referência inject nomeia uma chave provides declarada — mas os próprios valores provides produzidos viajam a jusante como cadeias opacas que o compilador encaminha sem interpretação, e não como valores cujo tipo verifique, porque o núcleo não interpreta o que significa um valor encaminhado. O usesSchema é onde um socket é declarado, e declará-lo é o que lhe dá um contrato. Um socket que a entidade do catálogo declara transporta as restrições dessa entidade: um seletor que diz que destinos pode alcançar, uma allowlist inject e valueSchema / infraSchema por aresta. Dentro do usesSchema, os arquitetos de plataforma usam o campo selector: — lido como a cadeia que o arquiteto escreveu, e não copiado para nenhum esquema gerado — e o motor de seletores Go nativo avalia-o para impor a segurança de tipos entre nós sobre os sockets declarados. Garante que, se um socket exigir uma base de dados, o programador não pode ligar um servidor web.
O seletor é sujeito à sua gramática no momento em que é avaliado, o que acontece uma vez por cada aresta ligada através do socket. Um seletor que o motor não consiga ler como uma das suas seis formas de requisito — um requisito vazio deixado por uma vírgula perdida, uma chave com espaços em branco ou com um dos caracteres que a gramática usa para distinguir as suas formas (=, !, (, ) e a vírgula), ou um conjunto sem o parêntese de fecho — interrompe a compilação nessa aresta, indicando o requisito, em vez de ser lido como outro seletor. É o rigor que mantém a verificação honesta: lido de forma tolerante, !tier=frontend, escrito para manter os frontends de fora, pediria apenas que nenhuma etiqueta se chamasse tier=frontend, e todos os destinos — frontends incluídos — passariam. A mesma gramática rege os seletores de slots de anexação e o appliesTo de uma Feature; a gramática dos seletores lista todas as formas e todas as recusas. Uma compilação nunca avalia um socket através do qual nenhuma aresta está ligada, pelo que aggrega validate — sobre todo o catálogo, ou sobre o Component ou a Feature que declara o socket — lê o seletor de cada socket declarado e recusa aí um seletor malformado, com o código e nas palavras usados por uma compilação que ligue o socket.
Declarar o socket não é, contudo, a única forma de desenhar uma aresta. Um autor de Aggregate pode nomear, no seu próprio componente, um socket que a entidade do catálogo não declara — incluindo num tipo de componente que não declara nenhum usesSchema — e a aresta é construída. Um catálogo que não declara nenhuma entrada para um socket não anteviu a ligação, o que não é o mesmo que proibi-la, e o programador é dono da topologia da aplicação. Esse socket chama-se ad hoc, e o que custa é exatamente o que declará-lo compra: não há entrada no catálogo, pelo que não há seletor nem contrato por aresta, e a segurança de tipos entre nós não tem nada para avaliar. O que a aresta pode transportar não muda — cada chave que injeta tem ainda de nomear uma chave que o provides do destino declara, e o destino tem ainda de existir. Cada aresta no grafo emitido regista qual dos dois casos é, pelo que um consumidor nunca tem de adivinhar; ver governance-and-compliance para saber como um operador proíbe por completo os sockets ad hoc.
Duas superfícies não estão deliberadamente abertas desta forma, porque não criam a topologia da aplicação. O uses de uma anexação de Feature só pode nomear um socket que a Feature anexada declara, e o uses por aresta de uma Release só pode nomear um socket que a entidade de catálogo do componente consumidor declara no seu usesSchema, nunca um que o Aggregate tenha criado ad hoc — um operador configura e liga dentro de uma arquitetura, e uma Feature participa na topologia que a sua própria entidade de catálogo declara. Declarar o socket no catálogo continua também a ser o melhor caminho, e é o que o catálogo da biblioteca padrão faz: um socket ad hoc é uma via de escape, não uma nova predefinição.
Domínio 1: a experiência do programador (polimorfismo) Os programadores escrevem uses: como irmão de values: e features:. Para garantir uma UX sem atritos, o esquema suporta polimorfismo de forma nativa:
- Arrays de cadeias: Usados para referências lógicas simples a componentes (por exemplo,
tools: ["search-api"]) quando o encaminhamento padrão é suficiente. - Mapas de objetos: Usados quando são necessários contratos de entrega estritos (por exemplo,
databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }). - Sem caracteres universais: Não existe forma com caráter universal, o que evita «dependências fantasma» e ligações automáticas não autorizadas: cada entrada nomeia um único componente, pelo que
["*"]interrompe a compilação como um destino inexistente — nenhum nome de componente pode conter*.
Domínio 3: a realidade de Ops (normalização) Para manter templates Go previsíveis, o compilador Go normaliza as entradas polimórficas de uses. Os arrays de referências lógicas a componentes são convertidos em objetos padrão antes de serem passados para o dicionário plano e estrito conhecido como .context.uses.
3. Exemplos de ponta a ponta
Os dois exemplos seguintes demonstram as duas propriedades distintas do pilar de topologia explícito: o Exemplo A prova se uma ligação está autorizada (segurança de tipos entre nós), e o Exemplo B prova como os dados da ligação são entregues fisicamente (polimorfismo e normalização).
Exemplo A: validação topológica e segurança de tipos entre nós
Este cenário mostra como o seletor de um socket declarado deteta que um agente de IA está prestes a ligar-se a uma base de dados sem as etiquetas de conformidade exigidas, e interrompe a compilação. O compilador avalia o seletor de etiquetas que o arquiteto escreveu face às etiquetas do destino, como cadeias; não interpreta o que uma etiqueta significa, e nenhum plugin de políticas está envolvido.
1. A biblioteca padrão (o schema: unificado no Catálogo) O arquiteto de plataforma define a estrutura do esquema, separando nativamente a lógica cognitiva dos destinos topológicos.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/enterprise-agent version: 1.0.0 labels: component.aggrega.ai/type: "worker"spec: usesSchema: datastores: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema: # 1. The Cognitive Intent values: system_prompt: { type: string, required: true }2. A intenção do programador (o Aggregate) O programador separa claramente o que o agente faz (values) daquilo a que o agente se liga (uses).
components: my_secure_vector_db: type: core/qdrant-secure:1.0.0 values: collection_name: finance_data
auditing_agent: type: core/enterprise-agent:1.0.0 values: system_prompt: "You are a financial auditing AI..." uses: datastores: finance_memory: { target: "my_secure_vector_db" }3. Execução do compilador e validação topológica
- Validação local: O compilador Go avalia o objeto inteiro contra o JSON Schema resolvido, no momento da resolução. Verifica as etiquetas de catálogo subjacentes de
my_secure_vector_db. Se a base de dados não tivesse a etiquetarestricted, o compilador interromperia imediatamente a compilação com uma violação de segurança de tipos. - Desenho do grafo: Na construção da topologia, o compilador Go ignora completamente o conteúdo validado por esquema. Lê
uses.datastores.finance_memory.targetnativamente a partir do YAML e desenha a aresta explícita no grafo da IR.
Exemplo B: polimorfismo e o .context.uses normalizado
Este cenário demonstra como o compilador trata tanto uma ferramenta de IA caixa-negra (passada como array) como uma base de dados relacional legada (que exige um mapa com um contrato inject).
1. O Catálogo (Domínio 2): a declaração schema: O arquiteto permite arrays polimórficos para as ferramentas, mas exige objetos estritos para as bases de dados.
spec: usesSchema: # Polymorphic Array Socket (No injection needed) tools: selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract) databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file"]
schema: values: system_prompt: { type: string, required: true }2. A intenção do programador (Domínio 1): o Aggregate O programador usa um array limpo para a ferramenta e um mapa explícito para a base de dados.
components: my-agent: type: core/python-worker:1.0.0 values: system_prompt: "You are an HR bot."
uses: # 1. Polymorphic Array: Simple logical component reference tools: - "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery databases: hr_db: target: corporate-hr-db inject: env: - in: HR_DATABASE_URI # Local env var from: "host" # Target provides key3. A realidade de Ops (Domínio 3): a Recipe O compilador Go normaliza o polimorfismo. O Ops recebe um dicionário .context.uses plano e previsível. Limita-se a percorrer o pipe .context.inject nas secções relevantes do seu template.
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: generic-worker version: 1.0.0spec: capability: helm implements: core/python-worker:1.0.0 source: "./charts/internal/python-runner"
locals: primary_compute: worker-container
valuesMapping: | env: # Ops uses the pre-resolved inject map, kept apart from values and topology loops {{- range $key, $value := .context.inject.env }} - name: {{ $key }} value: "{{ $value }}" {{- end }}