Resolução de dependências
Resolução de dependências do Aggrega & o pilar da topologia estrutural
Na arquitetura do Aggrega, as dependências topológicas são mapeadas explicitamente por meio 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ção complexas e com vários nós precisam ser mapeadas sem obrigar o desenvolvedor a escrever roteamento de rede explícito, ordens de execução no nível do orquestrador ou dependências de infraestrutura.
1. A filosofia central: por que 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 ou dos detalhes de conexão do Component B. A topologia vive em uses; a configuração vive em values. A separação permite que o compilador veja explicitamente todas as arestas entre componentes sem inferi-las do conteúdo de values.
O Aggrega resolve isso elevando a topologia a um pilar de esquema de primeira classe chamado uses.
- O argumento do proxy semântico: a palavra-chave
usesrepresenta a intenção semântica L7. Se um agenteusesum banco de dados, isso continua semanticamente verdadeiro mesmo que Platform Ops injete malhas de proxies Wasm transparentes entre eles. - Neutralidade matemática: o compilador Go analisa nativamente a estrutura
usespara desenhar o grafo da representação intermediária (IR). Ele nunca tenta analisar ou consultar a lógica de aplicação do desenvolvedor (values). - Atomicidade da Feature: o pilar
usesse aplica de forma idêntica a Components e Features (incluindo Features de credenciais). Isso permite que um proxy sidecar (uma Feature) ou um buscador de credenciais declare de forma autônoma suas próprias dependências de rede sem poluir a configuração do seu 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 se apoia em declarações estritas de JSON Schema 2020-12 que regem estruturas YAML explicitamente separadas.
Domínio 2: o esquema dividido (usesSchema & schema) Para evitar que o catálogo da plataforma se fragmente em arquivos de esquema impossíveis de gerenciar, o Aggrega utiliza um mecanismo de esquema dividido. O usesSchema em YAML nativo define e valida estritamente a topologia, enquanto schema: (JSON Schema 2020-12 — normalmente escrito por meio da abreviação em forma compacta) valida o conteúdo dos pilares values e infra e declara a forma do pilar provides. Os values que um desenvolvedor escreve e a infra que um operador define são verificados em relação aos seus tipos declarados; o subesquema provides declara os nomes de chave e os tipos do contrato downstream 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 trafegam downstream como strings opacas que o compilador encaminha sem interpretação, não como valores cujo tipo ele verifica, porque o núcleo não interpreta o que um valor encaminhado significa. O usesSchema é onde um socket é declarado, e declará-lo é o que lhe dá um contrato. Um socket que a entidade do catálogo declara carrega as restrições dessa entidade: um seletor que diz quais destinos ele pode alcançar, uma allowlist inject e valueSchema / infraSchema por aresta. Dentro do usesSchema, os arquitetos da plataforma usam o campo selector: — lido como a string que o arquiteto escreveu, não copiado para nenhum esquema gerado — e o mecanismo de seletores nativo em Go o avalia para impor a segurança de tipos entre nós sobre os sockets declarados. Ele garante que, se um socket exige um banco de dados, o desenvolvedor não consiga conectar um servidor web.
O seletor é submetido à sua gramática no momento em que é avaliado, ou seja, uma vez para cada aresta ligada através do socket. Um seletor que o mecanismo não consegue ler como uma de suas seis formas de requisito — um requisito vazio deixado por uma vírgula a mais, uma chave com espaço em branco ou com um dos caracteres que a gramática usa para distinguir suas formas (=, !, (, ) e a vírgula), ou um conjunto sem o parêntese de fechamento — interrompe o build nessa aresta, nomeando o requisito, em vez de ser lido como outro seletor. É esse rigor que mantém a verificação honesta: lido de forma tolerante, !tier=frontend, escrito para excluir frontends, pediria apenas que nenhum rótulo se chamasse tier=frontend, e todos os destinos — frontends incluídos — passariam. A mesma gramática rege os seletores de slots de anexo e o appliesTo de uma Feature; a gramática de seletores lista cada forma e cada recusa. Um build nunca avalia um socket através do qual nenhuma aresta é ligada, então 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 ali um seletor malformado, com o código e nas palavras usados por um build que ligue o socket.
Declarar o socket não é, porém, a única forma de traçar uma aresta. O autor de um Aggregate pode nomear em seu próprio componente um socket que a entidade do catálogo não declara — inclusive em um 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 previu a conexão, o que não é o mesmo que proibi-la, e a topologia da aplicação pertence ao desenvolvedor. Um socket assim é chamado de ad hoc, e o que ele custa é exatamente o que a declaração oferece: não há entrada de catálogo, portanto 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 ela injeta ainda deve nomear uma chave que o provides do destino declara, e o destino ainda deve existir. Cada aresta no grafo emitido registra qual dos dois casos ela é, para que um consumidor nunca precise adivinhar; consulte governance-and-compliance para ver como um operador proíbe totalmente os sockets ad hoc.
Duas superfícies não são abertas dessa forma deliberadamente, porque não escrevem a topologia da aplicação. O uses de um anexo 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 em seu usesSchema, nunca um que o Aggregate escreveu ad hoc — um operador configura e liga dentro de uma arquitetura, e uma Feature participa da topologia que sua própria entidade de catálogo declara. Declarar o socket no catálogo também continua sendo o melhor caminho e é o que o catálogo da biblioteca padrão faz: um socket ad hoc é uma via de escape, não um novo padrão.
Domínio 1: a experiência do desenvolvedor (polimorfismo) Os desenvolvedores escrevem uses: no mesmo nível de values: e features:. Para garantir uma UX sem atritos, o esquema oferece suporte nativo a polimorfismo:
- Arrays de strings: usados para referências lógicas simples a componentes (por exemplo,
tools: ["search-api"]) quando o roteamento padrão é suficiente. - Mapas de objetos: usados quando contratos de entrega estritos são necessários (por exemplo,
databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }). - Sem curingas: não existe forma com curinga, o que evita “dependências fantasma” e a conexão automática não autorizada: cada entrada nomeia um único componente, então
["*"]interrompe o build como um destino inexistente — nenhum nome de componente pode conter*.
Domínio 3: a realidade de Ops (normalização) Para manter os templates Go previsíveis, o compilador Go normaliza as entradas polimórficas de uses. 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 a seguir demonstram as duas propriedades distintas do pilar explícito de topologia: o exemplo A prova se uma conexão está autorizada (segurança de tipos entre nós), e o exemplo B prova como os dados da conexão são entregues fisicamente (polimorfismo & 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 detecta que um agente de IA está prestes a se conectar a um banco de dados sem os rótulos de conformidade exigidos, e interrompe o build. O compilador avalia o seletor de rótulos que o arquiteto escreveu em relação aos rótulos do destino, como strings; ele não interpreta o que um rótulo significa, e nenhum plugin de política está envolvido.
1. A biblioteca padrão (o schema: unificado no catálogo) O Platform Architect define a estrutura do schema, 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 desenvolvedor (o Aggregate) O desenvolvedor separa de forma limpa o que o agente faz (values) daquilo a que o agente se conecta (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 em relação ao JSON Schema resolvido durante a resolução. Ele verifica os rótulos de catálogo subjacentes de
my_secure_vector_db. Se o banco de dados não tivesse o rótulorestricted, o compilador interromperia imediatamente o build com uma violação de segurança de tipos. - Desenho do grafo: na construção da topologia, o compilador Go ignora totalmente o conteúdo validado pelo schema. Ele lê
uses.datastores.finance_memory.targetnativamente do YAML e desenha a aresta explícita no grafo IR.
Exemplo B: polimorfismo e o .context.uses normalizado
Este cenário mostra como o compilador lida tanto com uma ferramenta de IA caixa-preta (passada como array) quanto com um banco de dados relacional legado (que exige um mapa com um contrato inject).
1. O catálogo (domínio 2): a declaração schema: O Architect permite arrays polimórficos para ferramentas, mas exige objetos estritos para bancos 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 desenvolvedor (domínio 1): o Aggregate O desenvolvedor usa um array simples para a ferramenta e um mapa explícito para o banco 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. Ops recebe um dicionário .context.uses plano e previsível. Basta percorrer o pipe .context.inject nas seções relevantes do 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 }}