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

Component

O papel conceitual da entidade Component (a interface abstrata de nó de computação no Domínio 2) está em architecture/04-entity-taxonomy.md. Esta página cobre a superfície de autoria do Component: a taxonomia de labels semânticos que os arquitetos usam para sobrepor uma identidade cognitiva à ontologia operacional de base, a declaração schema: para os pilares de dados, as tabelas declarativas usesSchema e featuresSchema para sockets de topologia e slots de vinculação, os mandatos de presença, o mecanismo de herança extends: e o bloco de regras entre campos assertions:.

A taxonomia de rótulos semânticos (a convenção da biblioteca padrão)

Se os tipos base são puramente cloud-native, a inteligência operacional e cognitiva da arquitetura é sobreposta inteiramente por meio de duck typing semântico.

O compilador Go central não interpreta esses rótulos. O compilador constrói o grafo plano da Representação Intermediária (IR) sem interpretar a semântica dos rótulos. Esses rótulos representam a convenção da biblioteca padrão—“marcadores genéticos” imutáveis criados pelo arquiteto de plataforma no Domínio 2. Eles fornecem os hooks semânticos explícitos que os validadores de políticas Wasm e as Recipes físicas de Ops usam para governar a arquitetura.

(A) A camada de nuvem genérica Esses rótulos descrevem comportamentos universais, permitindo que motores de políticas e proxies L7 gerados governem arquiteturas corporativas padrão sem precisar entender nativamente frameworks de IA.

Prefixo do rótuloValores permitidos (convenção)Por que o Platform Ops precisa dele (o hook de política)
tool.aggrega.ai/impactread-only, mutatingPermite que motores de políticas avaliem a autorização de privilégio mínimo (Least-Privilege AuthZ). Ferramentas que modificam dados podem disparar automaticamente políticas que exigem a anexação de sidecars de aprovação rigorosos.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (conjunto de valores em estabilização em relação ao catálogo populado)Permite que motores de políticas imponham segurança de tipos entre nós (por exemplo, impedindo que um agente tente enviar payloads SQL para um banco de dados vetorial).
gateway.aggrega.ai/intelligencesemantic, l4-meshDetermina quais recursos um roteador pode suportar fisicamente (por exemplo, impedindo que uma Feature que roteia com base no modelo indicado por uma requisição, como uma cadeia de fallback, seja anexada a uma malha TCP padrão).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledPermite que uma Feature que copia o tráfego real para um segundo destino selecione um proxy que de fato consiga copiar, e distinga um que copia toda requisição correspondente de outro cuja fração de requisições copiadas é configurável.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerPermite que uma Feature que precisa que o chamador original seja identificado perante o serviço atrás do proxy selecione um componente capaz de transmitir essa identidade, e leia qual mecanismo a transmite — os detalhes do próprio certificado TLS do cliente, repassados adiante, ou um header que o proxy compõe por conta própria após autenticar o chamador.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listPermite que uma Feature que mascara texto sensível selecione um componente capaz de substituí-lo por um placeholder no payload de chat e completion que ele roteia, antes que o texto siga adiante. O valor indica a fidelidade: com entity-recognition o componente substitui as correspondências de padrões fornecidos em sua configuração e também os tipos de entidade que um serviço de reconhecimento chamado por ele detecta; com pattern-list ele substitui apenas as correspondências de padrões fornecidos em sua configuração e não chama nenhum serviço de reconhecimento.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierPermite que uma Feature que filtra prompts de modelo selecione um componente capaz de inspecionar o payload de chat e completion que ele roteia e de recusar uma requisição com base em seu conteúdo. O valor indica a fidelidade: com pattern-list a correspondência é feita com padrões fornecidos em sua configuração, sobre o payload do modelo e não sobre um corpo HTTP arbitrário; com classifier o veredito é o de um classificador de texto treinado, alcançado por meio de um serviço de detecção que o componente chama, em relação a um limiar fornecido em sua configuração.
dataplane.aggrega.ai/upstream-tlstrust-anchorPermite que uma Feature que exige que o proxy verifique com quem está se comunicando selecione um componente capaz de verificar o certificado de um upstream em relação a uma âncora de confiança fornecida pela Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyPermite que uma Feature que fixa qual chave um upstream pode apresentar selecione um componente capaz de recusar um upstream a menos que um certificado apresentado por ele contenha uma das chaves públicas fornecidas pela Release. Uma asserção diferente de upstream-tls: um pin diz qual chave um certificado deve ser; uma âncora, o que ele deve dizer.
dataplane.aggrega.ai/period-budgetcost, tokensPermite que uma Feature que limita o que o tráfego pode consumir em um período selecione um componente capaz de recusar requisições ao modelo assim que o que ele contou no período ultrapassa um limite definido em sua configuração. O valor indica o que ele conta: cost, quanto o tráfego custou, precificado a partir de uma tabela que o componente mantém por modelo; tokens, os tokens que a resposta de cada modelo informa ter lido, escrito ou ambos, que o componente conta sem precificar nada.
dataplane.aggrega.ai/concurrency-captotal, per-targetPermite que uma Feature que limita quantas requisições um componente processa ao mesmo tempo selecione um componente capaz de reter ou recusar uma requisição além de um limite definido em sua configuração. O valor indica o que um limite conta: total, toda requisição que o componente encaminha, em relação a um único limite; per-target, as requisições em andamento para cada destino upstream ao qual ele envia, com um limite para cada um e nenhum sobre o total.

As chaves dataplane.aggrega.ai/ indicam uma posição no caminho do tráfego em vez de um tipo de componente, de modo que um proxy, um gateway de ingress e uma service mesh se descrevem todos em um único vocabulário em vez de cada um precisar do seu. Duas propriedades dessa família merecem leitura atenta, porque ambas são fáceis de inverter:

  • O valor carrega a fidelidade, não apenas a presença da capacidade. Dois componentes podem ambos espelhar requisições e ainda assim diferir de um modo que importa para uma Feature, então a distinção vai no valor e uma Feature seleciona a fidelidade de que precisa. Um componente que oferece uma fidelidade maior carrega o valor mais forte e nenhum outro.
  • Um valor afirma o que o produto é capaz de fazer, nunca o que uma implantação ativou. As duas coisas se leem de forma parecida e só a primeira é uma propriedade do componente. Um proxy capaz de verificar o certificado de um upstream carrega upstream-tls: trust-anchor quer uma determinada implantação habilite a verificação, quer não, porque o rótulo é aquilo sobre o qual uma Feature faz a seleção antes que qualquer coisa seja configurada.

Um componente que não tem nada a descrever em um desses eixos não carrega nenhum valor nele, em vez de um valor mais fraco, exatamente como em outras partes da taxonomia: a ausência significa que o eixo não tem objeto naquele componente, de modo que uma Feature que exige qualquer valor nele, corretamente, não é anexada.

(B) A camada de IA especializada (a identidade cognitiva) Esses rótulos descrevem a identidade cognitiva da carga de trabalho, permitindo que a arquitetura proteja frameworks de IA modernos.

Prefixo do rótuloValores permitidos (convenção)Por que o Platform Ops precisa dele (o hook de política)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionUsado pelas strings de seletor de usesSchema (avaliadas nativamente pelo compilador Go durante a análise estática) para garantir que um desenvolvedor não roteie acidentalmente um payload de texto generativo para um endpoint de embedding.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeIndica qual API de modelo responde no endereço que um componente publica: openai quando é a API da OpenAI, a do próprio fornecedor ou a implementação de um servidor, anthropic quando é a Messages API da Anthropic, a do próprio fornecedor ou a implementação de um servidor, gemini quando é a Gemini API do Google, e native quando é a API própria do produto e nenhuma dessas. Todo componente de modelo o carrega, assim como um gateway capaz de servir uma API de modelo, de modo que um socket que seleciona component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api aceita um modelo ou um gateway desse tipo e recusa um gateway que não serve nenhuma, enquanto um socket que indica um único valor, como model.aggrega.ai/api=anthropic, aceita apenas o que serve essa API. Indica o que o produto serve, não o que uma Release específica conecta: um gateway cujos modelos são conectados a um socket próprio o carrega mesmo sem nada conectado. O rótulo é uma string com a qual o seletor faz a correspondência; nada verifica o que de fato responde no endereço.
agent.aggrega.ai/autonomyautonomous, copilotIdentifica o risco de execução do loop cognitivo, permitindo que políticas exijam recursos de aprovação humana para agentes totalmente autônomos.

(C) Os elementos transversais (governança, estado e hardware) Representam as tags corporativas fundamentais que orientam a validação Zero-Trust e o roteamento para o hardware.

Prefixo do rótuloValores permitidos (convenção)Por que o Platform Ops precisa dele (o hook de política)
component.aggrega.ai/hostingself-hosted, managed, external, mixedRegistra quem opera o recurso subjacente de um componente — o eixo da fronteira de confiança. Motores de políticas o leem para calcular o risco de exfiltração de dados (por exemplo, dados internos roteados para uma API de terceiros managed saem da fronteira do operador). Transversal: os mesmos valores descrevem igualmente um banco de dados gerenciado, uma API de modelo gerenciada e um servidor de inferência autogerenciado. mixed marca um componente cujas Recipes abrangem mais de uma modalidade — um datastore auto-hospedado por suas Recipes de Helm e Compose e gerenciado por suas Recipes de RDS — de modo que a modalidade de uma Release segue a Recipe que seu Manifest seleciona.
compliance.aggrega.ai/data-classpublic, internal, restrictedA classe dos dados que um componente armazena. O compilador a leva ao grafo de build como uma string e não ordena nada; uma política que um operador anexa no papel ir-verdict dá às classes sua ordem em suas próprias configurações e lê o rótulo ao longo das rotas que o compilador enumera — interrompendo, por exemplo, um build em que um componente restricted alcança um componente de outra classe sem nenhuma Feature de desclassificação anexada na rota (policy-data-class-route). Nenhum Component da biblioteca padrão o carrega: a classe é uma afirmação sobre como uma organização usa um componente, carregada pelo próprio Component dessa organização — uma especialização por meio de extends, por exemplo.
compliance.aggrega.ai/contains-piitrue, falseSinaliza explicitamente cargas de trabalho no escopo da GDPR/CCPA. Uma política que um operador anexa pode lê-lo para exigir Features específicas nas rotas que o tráfego dessa carga de trabalho percorre — core/data-masking em um gateway de IA pelo qual ela envia tráfego de modelos, por exemplo, a forma que policy-data-class-route verifica para uma classe de dados. Nenhum Component da biblioteca padrão o carrega; assim como a classe de dados, é uma afirmação de uma organização sobre seus próprios componentes.
hardware.aggrega.ai/acceleratorgpu, tpu, npuUsado pelo DevOps no arquivo Release. Ali eles roteiam explicitamente esses componentes para fronteiras físicas de pools de hardware (por exemplo, um cluster com GPU) por meio do mapa components: {}, enquanto um papel verdict de governança pode impor que componentes rotulados como GPU nunca sejam colocados em fronteiras sem GPU.
state.aggrega.ai/retentionretain, deleteResolve a lacuna de exclusão AOT. Se um desenvolvedor exclui um banco de dados do seu Aggregate, um orquestrador GitOps removerá fisicamente o disco. Uma etapa pipeline: de uma Recipe pode ler o rótulo retain e adicionar proteção nativa do orquestrador aos artefatos renderizados (por exemplo, helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralHook de disponibilidade SOC2. Indica à FeatureRecipe de Ops se deve gerar fisicamente configurações automatizadas de Snapshot/Volume Backup para o recurso.

(D) O contexto de negócio dinâmico (anotações em cascata) Enquanto as labels definem o DNA imutável do catálogo, os contextos de negócio dinâmicos (como o escopo de auditoria SOC2 ou o acompanhamento de custos de FinOps) mudam conforme quem implanta a aplicação e onde ela é executada. Eles são governados por anotações injetadas dinamicamente pelos subsystems do desenvolvedor, pelas fronteiras da Release de Ops ou por um plugin de governança anexado no papel annotation-transform.

Prefixo da anotaçãoValores permitidos (convenção)Por que o Platform Ops precisa dele (o hook de política)
business.aggrega.ai/cost-centerex.: finance, ai-researchExigido pelos plugins de renderização Wasm para injetar tags físicas (por exemplo, tags da AWS ou labels do K8s) nos artefatos finais gerados, para os painéis de faturamento de nuvem.
business.aggrega.ai/ownerex.: team-alpha@corp.comRoteamento da resposta a incidentes. Garante que a infraestrutura esteja associada a uma equipe humana.
compliance.aggrega.ai/frameworksex.: soc2, hipaaGatilho de escopo SOC2. Injetado por meio da Release do ambiente. Os plugins Wasm leem essa string para gerar automaticamente sidecars rígidos de registro de auditoria e desabilitar portas de depuração quando uma aplicação entra em uma fronteira de conformidade de produção.

A taxonomia é uma convenção do catálogo, não uma regra do compilador. As empresas podem ignorá-la, excluí-la ou inventar seu próprio vocabulário de rótulos (mycompany.com/custom-trait). Os plugins Wasm avaliam quaisquer chaves de rótulo que a empresa defina.

Autoria de esquemas

O esquema Component (e sua contraparte Feature, incluindo as Features de credenciais rotuladas feature.aggrega.ai/kind: secret) declara o contrato de validação para os values criados pelo desenvolvedor por meio de um bloco spec.schema:. O bloco aceita JSON Schema 2020-12 expresso na notação abreviada YAML compacta (o padrão; cerca de 15 palavras-chave, transformadas mecanicamente em JSON Schema em tempo de compilação) ou em YAML de JSON Schema completo (a forma detalhada), com referências entre documentos via $ref: para entradas de SchemaLibrary compartilhadas entre vários Components.

  • Forma compacta inline (superfície de autoria padrão): um bloco YAML embutido que carrega folhas em forma compacta diretamente no YAML do Component. Cobre a grande maioria do conteúdo de esquemas do catálogo com uma fração das linhas de um JSON Schema completo. Consulte vocabulary/compact-form-authoring.md para o vocabulário de palavras-chave e as convenções de autoria.
  • YAML de JSON Schema inline: a forma detalhada, adequada quando o esquema precisa de palavras-chave de JSON Schema 2020-12 que a forma compacta não carrega diretamente ($dynamicRef, unevaluatedProperties profundos, composição not: complexa). A forma compacta e o JSON Schema podem ser combinados em qualquer fronteira de nó dentro de um único bloco schema: por meio da via de escape $jsonschema:.
  • Referência entre documentos ($ref: para uma entrada de SchemaLibrary): um $ref: nativo de JSON Schema que aponta para uma entrada de SchemaLibrary por identidade (Datastores#/schemas/MariaDBValues ou similar). Esquemas corporativos que se estendem por centenas de linhas e são reutilizados em vários Components ficam em entidades SchemaLibrary; o Component consumidor referencia a entrada sem incorporar o conteúdo. Consulte entities/schemalibrary.md e vocabulary/cross-document-ref.md para a entidade de biblioteca e a semântica de resolução.

As três formas acima criam conteúdo de pilares e estão disponíveis para um Component que não estende nada. Um Component que declara extends: não cria nenhum conteúdo de pilares: ele escreve o marcador literal schema: inherited e recebe o bloco de pilares da sua base exatamente como a base o criou. Esse marcador é o único valor que schema: aceita em um Component desse tipo. Consulte “Autoria do catálogo: estendendo Components base” abaixo.

O compilador resolve o bloco schema: — expandindo a forma compacta, desreferenciando URLs $ref:, aplicando as cadeias de biblioteca para biblioteca de SchemaLibrary — e unifica o JSON Schema resultante com as bases geradas automaticamente a partir de usesSchema e featuresSchema (consulte a seção abaixo) durante a passagem de validação do Component. A validação é executada contra o esquema resolvido; o caminho de autoria é opaco para as etapas seguintes do pipeline.

As instâncias criadas são validadas contra esse esquema resolvido em tempo de build: os values criados pelo desenvolvedor de uma instância de componente e a infra resolvida do operador, além dos values/infra em qualquer anexação de Feature, devem estar em conformidade com os pilares declarados — um valor de tipo errado, um número fora do intervalo, uma string que não tem seu format declarado, um campo obrigatório ausente ou (para values, validado de forma fechada) uma propriedade não declarada interrompe o build na sua origem criada em vez de produzir um manifesto quebrado em tempo de implantação. Um pilar cujo esquema indica um format que o compilador não verifica — qualquer um fora de email, uri, hostname, ipv4, ipv6, uuid, date-time e date, password incluído — é recusado quando o catálogo é carregado, com a lista dos nomes suportados; consulte vocabulary/compact-form-authoring.md para saber o que cada nome verifica. Uma instância de um Component que estende uma base com extends: é validada contra o bloco de pilares da base, que o Component que a estende herda sem alterações — assim, uma instância da base e uma instância de qualquer coisa que a estenda enfrentam o mesmo contrato de pilares. Consulte errors/fatal-halts.md §“Authored values or infra do not conform to the declared schema (Os values ou a infra criados não estão em conformidade com o esquema declarado)” para os diagnósticos e as regras por pilar (incluindo como infra é validada contra a união de chaves do Component e do provider).

Os padrões declarados se materializam nos pilares renderizados. Além da validação, um default: declarado em um campo de values (ou em um campo de infra) é preenchido no pilar renderizado em tempo de build para cada chave que o autor omite — assim, um template de Recipe que lê {{ .values.charset }} recebe o utf8mb4 declarado no esquema em vez de um valor vazio. Valores fornecidos pelo autor sempre prevalecem; objetos aninhados são preenchidos para cada filho omitido. Como a materialização usa a mesma resolução de esquema que a validação, os padrões alcançados por meio de um $ref: entre documentos para uma SchemaLibrary também se materializam — tanto uma referência ao pilar inteiro (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) quanto a forma base mais variante (um $ref: base ao lado de properties irmãs, cada uma com seus próprios padrões). Padrões declarados apenas dentro de uma referência local no mesmo documento #/$defs/, ou sob um ramo allOf / oneOf / anyOf, não são materializados; a biblioteca padrão compõe os pilares por meio de $ref: entre documentos, que é materializado.

O pilar values

O esquema do Component separa três pilares por propriedade: values é preenchido pelo desenvolvedor no Aggregate (intenção cognitiva — nome do banco de dados, versão, charset), infra é preenchido pelo operador na Release (dimensionamento operacional — computação, armazenamento, HA) e provides é definido pela Recipe (o contrato da API pública — host, porta, protocolo). O desenvolvedor nunca vê infra; o operador nunca vê values. As Recipes consomem ambos os pilares durante a renderização base, mapeando os pilares abstratos para a forma concreta que o provider de destino espera. Esta seção cobre a superfície de autoria do pilar values. Consulte vocabulary/data-pillars.md para a taxonomia mais ampla dos pilares e a disciplina de cascata entre pilares.

values carrega a intenção cognitiva do desenvolvedor — as escolhas que descrevem o que a aplicação é ou faz, não como ela é dimensionada ou executada. Nome do banco de dados, charset, versão do mecanismo, nível de log, sinalizadores de funcionalidade e ajustes da camada de aplicação que mudam entre versões da aplicação, mas permanecem estáveis entre ambientes, são conteúdo típico de values. O operador nunca sobrescreve values: (o esquema da Release rejeita mecanicamente um bloco values: conforme architecture/06-data-taxonomy-and-composition.md §8 Restrição 4); a variação por ambiente flui pelo Parameter Hoisting — o Aggregate expõe parameters.* tipados, o template values do Component os referencia e a Release preenche os parâmetros.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Consumo do lado da Recipe. As Recipes leem os valores resolvidos via .values.<field> em valuesMapping:, provides:, assertions: e nas demais superfícies de template — consulte entities/recipe.md para a matriz de disponibilidade por template. O compilador unifica o esquema values do Component com quaisquer esquemas values: de attachments de Feature no mesmo nó do Component, de modo que o contexto de template resolvido contenha todos os campos aplicáveis.

Disciplina entre pilares. values é o único pilar que o desenvolvedor escreve no Aggregate. Campos estritamente voltados ao desenvolvedor pertencem aqui; ajustes operacionais (contagem de réplicas, limites de CPU/memória) pertencem ao pilar infra do Component, para que fiquem na Release; a saída pública (host, porta) pertence ao provides da Recipe. Misturá-los quebra o invariante de propriedade; consulte vocabulary/data-pillars.md “Mecânica entre pilares” para os raros casos em que um encaminhamento deliberado entre pilares se justifica.

O pilar infra

O esquema do Component separa três pilares por propriedade: values é preenchido pelo desenvolvedor no Aggregate (intenção cognitiva — nome do banco de dados, versão, charset), infra é preenchido pelo operador na Release (dimensionamento operacional — computação, armazenamento, HA; o backup de um datastore não é dimensionado aqui, mas é a Feature core/backup que o operador anexa na Release) e provides é definido pela Recipe (o contrato da API pública — host, porta, protocolo). O desenvolvedor nunca vê infra; o operador nunca vê values. As Recipes consomem ambos durante a renderização base, mapeando os pilares abstratos para a forma concreta que o provider de destino espera.

Três convenções de infra importam em todo Component agnóstico em relação à capacidade da biblioteca padrão: uma via de escape de estrutura aberta para ajustes específicos do provider, uma substituição opcional da versão do artefato upstream e um vocabulário baseado em intenção para os campos de alta disponibilidade. O Component de referência canônico é core/datastore/mariadb no catálogo da biblioteca padrão — implementável por Recipes Helm que executam a imagem oficial mariadb ou entregam um recurso personalizado do MariaDB ao controlador mariadb-operator, por Recipes Terraform para AWS RDS, por Recipes CloudFormation para a mesma superfície do RDS e por Recipes Compose para um contêiner local — e seu bloco infra ilustra a primeira e a terceira.

infra.overrides

Os campos universais de infra — compute, storage, ha — cobrem a maior parte do dimensionamento operacional entre providers. A parte restante é irredutivelmente específica do provider: uma Recipe Kubernetes precisa de um nodeSelector, uma Recipe Terraform para RDS precisa de um instance_class, uma Recipe CloudFormation para RDS precisa de um DBInstanceClass, uma Recipe Compose precisa de uma substituição de image. O esquema do Component expõe um mapa genuinamente aberto como via de escape para que esses ajustes passem sem inchar o esquema:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

O type: object explícito com additionalProperties: true ativa a semântica de mapa aberto. O compilador repassa a estrutura intacta; o corpo do template da Recipe lê as chaves que conhece e ignora o resto. Cada Recipe documenta a ontologia de suas chaves de substituição no comentário de cabeçalho, para que um operador que escreve uma Release para uma combinação específica de Component × Recipe saiba quais ajustes a Recipe expõe.

Um fragmento de Release usando substituições:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

O desenvolvedor nunca vê overrides — ele fica na Release, que é o domínio do operador.

infra.source_version

O campo source de uma Recipe referencia um artefato upstream em uma versão específica (chart Helm 25.0.8, módulo Terraform 4.2.0, tag de imagem OCI). Fixar a versão no código da Recipe obriga o mantenedor do catálogo a publicar uma nova Recipe a cada atualização compatível de versão upstream. O esquema do Component expõe uma substituição opcional:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

A Recipe lê isso por meio do helper optional em seu bloco source, de modo que, sem uma versão fixada, vale a versão para a qual a Recipe foi escrita:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

As strings source de uma Recipe (e os subcampos com valor string de um mapa source: estruturado) são avaliadas como templates Go. Uma coordenada remota — como a version acima — é avaliada quando aggrega pull fixa o artefato, em relação a .values, .infra e .locals, sem raiz .context; uma source que indica um caminho no workspace é avaliada quando a entidade é renderizada, em relação ao mesmo contexto autocontido dos locals da Recipe — .context.instance_id, .values, .infra e a totalidade dos .locals resolvidos do nó. .context.inject, .context.uses e .provides são proibidos em ambos os casos. O fato de .infra estar nesse contexto é o que faz a substituição acima funcionar, e .locals permite que uma Recipe calcule um fragmento de source uma vez e o leia de volta aqui. Um template de source nunca lê os provides do próprio nó: esse pilar não faz parte do contexto, e um template que tente acessá-lo interrompe o build — uma propriedade fixa da superfície, e não uma lacuna à espera de trabalho futuro. Consulte a linha nº 5 da matriz de expansão de templates para as regras de disponibilidade completas. Alterar infra.source_version em relação ao padrão da Recipe não garante que o valuesMapping da Recipe seja compatível no nível de transmissão com a nova versão upstream; a description da declaração source_version no esquema do Component traz esse aviso.

infra.ha.*

Os campos de alta disponibilidade usam vocabulário de intenção, não de mecanismo:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled diz “torne este Component altamente disponível” e infra.ha.read_replicas diz “quero N cópias somente leitura”. Cada Recipe decide em que a intenção se transforma no seu provider. As Recipes da biblioteca padrão para core/datastore/mariadb, nomeadas como um Manifest as mapeia:

Recipeha.enabled: true corresponde aha.read_replicas: N corresponde a
helm/mariadb (um StatefulSet sobre a imagem oficial mariadb)executa um único servidor, então o build é interrompido indicando a chaveexecuta um único servidor, então N acima de 0 interrompe o build
helm/mariadb-cluster (um recurso personalizado do MariaDB que o controlador mariadb-operator reconcilia)ativa o failover automático (replication.primary.autoFailover: true); o failover ocorre para uma réplica de leitura, então N igual a 0 interrompe o builddefine spec.replicas como N + 1 e ativa a replicação; provides.host passa a ser o Service <name>-primary
terraform/mariadb-rds (AWS RDS)define multi_az = true na aws_db_instance primáriacria N recursos de réplica de leitura aws_db_instance separados
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS por meio de um módulo)passa multi_az = true ao móduloprovisiona uma única instância, então N acima de 0 interrompe o build
cloudformation/mariadb-rds (AWS RDS)define MultiAZ: true no AWS::RDS::DBInstanceprovisiona uma única instância, então N acima de 0 interrompe o build
compose/mariadb (contêiner de desenvolvimento local)executa um único servidor, então o build é interrompido indicando a chaveexecuta um único servidor, então N acima de 0 interrompe o build

O vocabulário de mecanismo (infra.primary.replicas) soa natural para um provider (pods Kubernetes são réplicas de um StatefulSet) e como um erro de categoria nos demais — o RDS não tem o conceito de “réplicas” no primário, o CloudFormation espelha o RDS, o Compose não tem nenhuma abstração de réplicas horizontais. O vocabulário de intenção se traduz: todo provider tem algum conceito de “tornar este banco de dados altamente disponível” e algum conceito de “quero N cópias somente leitura”, e a Recipe carrega a tradução por provider. Onde uma realização não tem esse mecanismo, sua Recipe pode interromper o build indicando a chave, como fazem helm/mariadb e compose/mariadb para ambas as chaves e as Recipes RDS de instância única para réplicas de leitura.

infra.ha.read_replicas: 0 é o padrão; com ambas as chaves nos padrões, helm/mariadb-cluster renderiza um MariaDB de instância única sem bloco replication, em vez de replicação sobre uma única instância. compose/mariadb executa um único servidor no host Docker local, então infra.ha.enabled: true ou um infra.ha.read_replicas diferente de zero interrompe o build indicando a chave, e a mensagem aponta para helm/mariadb-cluster, que oferece failover e réplicas de leitura.

O pilar provides

provides é a API pública escrita pela Recipe — os valores que a Recipe resolvida de um Component fornece aos chamadores downstream por meio da superfície .context.uses.<alias>.provides.<provided-name> deles (ou, quando o chamador declara uma allowlist inject: na aresta, por meio do pipe .context.inject dele). O esquema do Component declara a forma (nomes de chave e tipos); o bloco provides: da Recipe vinculada fornece os valores. O desenvolvedor que escreve um Aggregate vê a forma de provides na página do Component como o contrato com que os chamadores podem contar; o autor da Recipe cumpre o contrato para a implementação específica que encapsula.

O cumprimento é imposto como um Loud Guardrail: uma Recipe vinculada deve produzir cada chave de provides que seu Component declara. Se a Recipe vinculada omitir uma chave declarada, o build é interrompido e indica a chave ausente, em vez de silenciosamente não entregar nada aos chamadores que a referenciam. Produzir chaves extras além do conjunto declarado é permitido. Só a presença das chaves é verificada — os valores produzidos são strings opacas que o compilador repassa, então seus tipos declarados continuam sendo um contrato que os chamadores leem, e não um valor que o compilador valida.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

A divisão da avaliação entre provides e inject. O compilador avalia os templates provides: na avaliação de provides, em relação ao contexto de template autocontido (.context.instance_id, .context.rendered_name quando o provider do nó informa um, .values, .infra e os locals: resolvidos da Recipe no mesmo nó) — nenhum estado de chamador é visível. Os locals do nó são resolvidos no preâmbulo dessa etapa, antes dos seus provides, e é isso que permite a um template provides: ler .locals. Na hidratação de inject, que é executada em seguida, o compilador percorre as arestas uses: e resolve o .context.uses.<alias>.provides.<provided-name> de cada chamador em relação aos valores de provides resolvidos. Separar os dois garante uma resolução acíclica: provides: não pode referenciar um chamador, e o inject: de um chamador não pode referenciar a saída de um provider ainda não resolvido até que a hidratação de inject seja executada.

Evolução do contrato. Renomear ou remover um campo de provides é uma mudança incompatível para todo chamador que depende do nome antigo. A metadata.version do Component (e a declaração implements: da Recipe) carrega o sinal de evolução do contrato; chamadores downstream fixados em uma versão major específica veem uma forma de provides estável.

Material do lado da Recipe. Para a gramática de autoria dos templates provides:, a matriz de disponibilidade por template e exemplos completos de roteamento entre namespaces e entre regiões, consulte entities/recipe.md “O bloco provides:” e architecture/06-data-taxonomy-and-composition.md §3.

Obrigações de presença: features.aggrega.ai/requiredType.<label>

Um Component pode declarar que toda instância dele deve ter um attachment de um determinado tipo de Feature. Isso é uma obrigação de presença, e é escrita como uma anotação repetível nos metadados do próprio Component:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

A chave é o prefixo features.aggrega.ai/requiredType. seguido de um rótulo que você escolhe; o valor é o URI do tipo de Feature que pelo menos um attachment deve ter. O rótulo nomeia o requisito no diagnóstico que uma obrigação não cumprida produz — audit e compliance acima — e essa é toda a sua função. Chaves com rótulo são a forma de um Component declarar mais de uma obrigação ao mesmo tempo: anotações são um mapa plano de strings e não podem conter uma chave duplicada.

O compilador avalia cada obrigação em relação ao conjunto final de attachments da instância, depois que a cascata do 5-Tier Onion Model consolidou todos os escopos: os blocos features: de nível de componente e de nível de subsistema do Aggregate, os blocos features: de nível de fronteira e de nível de componente da Release e os attachments produzidos pela expansão orientada por anotações. Qualquer um deles cumpre a obrigação — a regra testa o que está presente, nunca como chegou lá. Assim, um Component cuja obrigação só é cumprida porque um operador definiu uma anotação de monitoramento na Release passa exatamente como um a que o desenvolvedor anexou a Feature manualmente.

Uma obrigação que nenhum attachment cumpre interrompe o build com um diagnóstico que indica a instância do componente, o rótulo do requisito e o tipo exigido. O valor de uma anotação é uma string opaca, então nada valida sua forma antes que o compilador o leia; um valor que não é um URI de tipo de Feature, ou uma chave sem rótulo após o prefixo, portanto interrompe o build com um diagnóstico separado informando que a declaração está malformada. Os dois são deliberadamente distintos: uma declaração quebrada é corrigida na entidade do catálogo, enquanto um requisito não cumprido é resolvido anexando a Feature — e um erro de digitação nunca deve ser lido como um requisito cumprido.

Ambos os diagnósticos estão documentados em errors/fatal-halts.md “Required feature not attached (funcionalidade obrigatória não anexada)”.

Uma obrigação não é um slot. As duas superfícies respondem a perguntas diferentes, e a diferença não é cosmética:

slot featuresSchemaobrigação de presença
Declaraum ponto de vinculação nomeadouma restrição sobre o que deve estar presente
O nome é desreferenciávelsim — from: <slot> e .features.<slot>.provides.*não — o rótulo nomeia o requisito, nada mais
Cardinalidadeexatamente um preenchimento por slotpelo menos um attachment do tipo
Restringe o preenchimentoselector, inject, sensitivenada além do tipo
Cumprido por um attachment livrenão — um slot é preenchido pelo nomesim — em qualquer escopo, sob qualquer nome
Quando a exigência não é cumpridainterrompe quando required: true e nada vincula o nome do slotinterrompe quando nenhum attachment tem o tipo

Ambas as exigências são verificadas em relação à mesma entrada — o conjunto final de attachments da instância — e ambas interrompem o build com seu próprio diagnóstico, porque fazem perguntas diferentes a ela: se um ponto de vinculação nomeado está vinculado, ou se algum attachment tem um tipo nomeado. Nenhuma responde pela outra.

Use um slot quando a Recipe precisa ler o que foi anexado. Use uma obrigação quando o contrato do Component exige que uma capacidade esteja presente e não importa qual instância a fornece. Um Component de processamento de pagamentos que exige core/audit-logging recebe log de auditoria em todo deployment, quer o desenvolvedor tenha lembrado de anexá-lo, quer não; um Component em conformidade com PCI que exige core/pci-compliance não pode ser entregue sem a Feature de conformidade anexada em algum lugar do deployment.

Herança. Uma obrigação declarada em um Component base é herdada por todo Component que o estende com extends:, porque as anotações de metadados se mesclam ao longo da cadeia de extends, com o filho prevalecendo por chave. Um filho pode, portanto, redirecionar uma obrigação herdada declarando novamente o mesmo rótulo com um tipo diferente, ou adicionar obrigações próprias sob novos rótulos; ele não pode remover uma que a base declarou.

Sockets de topologia: usesSchema

Um Component pode declarar sockets topológicos por meio de um bloco usesSchema: — um mapa YAML declarativo paralelo a featuresSchema. Cada entrada nomeia um socket pelo qual o Component aceita dependências entre componentes e determina quais formatos de Component o desenvolvedor pode conectar ao socket. O compilador gera automaticamente regras de validação em JSON Schema 2020-12 a partir dos sockets declarados e as unifica com o schema: do Component durante a resolução do Component; os desenvolvedores não escrevem à mão um pilar uses: dentro de schema:, porque a estrutura vem de usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Formas de conexão — um socket aceita um ou vários destinos. Os exemplos acima conectam cada socket a um único destino, mas um socket pode se ramificar para vários. O valor de um socket é escrito em uma de duas formas:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Um alias sempre aponta para um objeto de entrada, nunca para um simples nome de destino: databases: { primary: orders-db } é rejeitado no carregamento, assim como um objeto de entrada que omite target:. Para conectar um único destino sem precisar inventar um alias, use a forma compacta — primary_datastore: [vector-db-instance] —, que nomeia o destino uma vez e deriva dele o alias.

Cada entrada — elemento de lista ou alias de mapa — se torna uma aresta, preservada na ordem de escrita. O selector: do socket se aplica a cada destino conectado por meio dele (cada aresta passa por verificação de tipos de forma independente durante a análise estática), e required: true significa que pelo menos um destino deve ser conectado.

Semântica dos campos:

CampoTipoPadrãoSignificado
requiredboolfalseQuando true, o desenvolvedor deve conectar pelo menos uma dependência a este socket. Quando false, o socket é opcional.
selectorstring—Um seletor de labels, na gramática que appliesTo de uma Feature usa, que o destino de cada aresta conectada por este socket deve satisfazer. Ele é lido como a string escrita aqui e avaliado em relação aos labels do destino durante a análise estática: um destino cujos labels não o satisfazem interrompe o build, assim como um seletor que a gramática recusa, nomeando o requisito que ela não conseguiu ler. Um seletor vazio não impõe nenhuma restrição ao destino.
injectstring[]—Lista de permissões dos mecanismos de entrega inject permitidos (paralela a featuresSchema[].inject). Ausente, ou [] (vazia), significa caixa-preta — nenhum bloco inject: permitido na entrada uses: do desenvolvedor; a Recipe controla a entrega. [env, file, arg] (não vazia) significa transparente — o desenvolvedor pode determinar qual mecanismo entrega os valores provides da dependência. Aplicado: veja “Onde a lista de permissões inject de um socket é aplicada” abaixo.
valueSchemaobject—Contrato opcional por aresta para os values escritos pelo desenvolvedor em uma aresta conectada por este socket (escritos no Aggregate). JSON Schema 2020-12 nas mesmas formas de escrita que schema:. A omissão significa que o socket não declara nenhum contrato values.
infraSchemaobject—Contrato opcional por aresta para o infra escrito pelo operador em uma aresta conectada por este socket (escrito na Release). As mesmas formas de escrita que valueSchema. A omissão significa que o socket não declara nenhum contrato infra.
featuresSchemamap—Os slots de acoplamento que cada conexão feita por este socket pode preencher, indexados pelo nome do slot, cada um aceitando as chaves que um slot no nível do Component aceita. A omissão significa que uma conexão por este socket não carrega nenhum acoplamento. Veja “Slots que cada conexão preenche” abaixo.

Onde a lista de permissões inject de um socket é aplicada. A lista de permissões é a declaração do socket sobre se um consumidor pode escolher a forma de entrega e, em caso afirmativo, quais formas — por isso ela é verificada em relação a cada aresta uses: conectada pelo socket, assim que a aresta e a declaração do socket estiverem ambas disponíveis. Duas recusas decorrem de uma única regra, e ambas interrompem o build:

  • Uma aresta que determina um mecanismo que a lista de permissões não inclui interrompe o build, nomeando o socket, o mecanismo infrator e o que o socket permite. Todos os mecanismos infratores da aresta são relatados juntos.
  • Uma aresta que determina qualquer entrega por um socket cuja lista de permissões está ausente ou vazia também interrompe o build. É a declaração de caixa-preta cumprindo seu papel: ela diz “a Recipe entrega isto internamente; não determine a entrega”, e uma lista de permissões vazia não permite nada em vez de permitir tudo.

O socket é lido na entidade que o declarou, que nem sempre é o componente do qual a aresta parte: uma aresta escrita no uses: de um acoplamento de Feature é resolvida em relação ao usesSchema da Feature acoplada, e toda outra aresta — escrita no Aggregate, conectada a partir da Release ou alcançada por meio de um subaggregate — em relação ao do Component consumidor. Um socket herdado por meio de extends é lido exatamente como um que a própria entidade escreveu.

Uma aresta que não determina nada não é afetada por nenhuma das duas recusas, seja o que for que o socket declare: ler os valores de uma dependência a partir de .context.uses.<alias>.provides.<name> na Recipe consumidora não exige nenhum bloco inject: e está sempre disponível. Veja errors/fatal-halts.md para ambos os diagnósticos.

Contratos de conexão por aresta — valueSchema e infraSchema. Além de determinar quais Components podem ser conectados a um socket, um socket pode declarar qual configuração cada conexão carrega. Dois esquemas opcionais por socket validam a configuração no escopo da conexão em cada aresta conectada pelo socket:

  • valueSchema é o contrato para o bloco values escrito pelo desenvolvedor em uma aresta uses — o ajuste por conexão que o desenvolvedor expressa no Aggregate (por exemplo, o tamanho de um pool de conexões ou um modo de cliente).
  • infraSchema é o contrato para o bloco infra escrito pelo operador em uma aresta uses — o dimensionamento operacional por conexão que o operador expressa na Release.

Ambos aceitam JSON Schema 2020-12 nas mesmas formas de conteúdo que o campo schema: — forma compacta inline, JSON Schema YAML inline ou um $ref: entre documentos para uma entrada de uma SchemaLibrary. São contratos por aresta, validados em relação à configuração de cada aresta de forma independente; eles não são compostos no esquema values próprio do Component consumidor. Um socket que omite um esquema por aresta para um pilar não declara nenhum contrato ali, e qualquer configuração escrita para esse pilar fica sem validação. A configuração por aresta é validada de forma fechada, e a validação leva em conta os valores padrão nos dois pilares: uma chave à qual o esquema atribui um default: conta como fornecida mesmo quando o autor a omite.

Um default: declarado também se materializa, nos dois pilares. Uma chave que o autor omite chega ao contexto de renderização da Recipe consumidora carregando seu valor padrão declarado, exatamente como acontece com uma chave value ou infra de componente omitida — então declarar o valor padrão no socket é suficiente, e o template da Recipe não precisa de nenhuma expressão de fallback para ela. Um valor escrito sempre prevalece sobre o valor padrão declarado, e preenche apenas a chave que fornece: uma aresta que escreve uma chave do contrato de um socket ainda recebe os valores padrão declarados para as demais chaves desse contrato. Os valores padrão se vinculam às arestas, então um socket deixado sem conexão não contribui com nada.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Com esse socket declarado, uma aresta cujo Aggregate omite pool_size renderiza 10, e uma aresta cuja Release omite storage_class renderiza standard. O que é escrito prevalece chave a chave, dentro do próprio pilar: um Aggregate que define pool_size: 42 renderiza 42 enquanto tls_mode continua sendo preenchido com require, e uma Release que define storage_class: gp3 renderiza gp3 sem alterar nenhuma das duas chaves do desenvolvedor.

Uma Recipe para o Component consumidor lê a configuração por aresta resolvida a partir do pipe de topologia enriquecido em .context.uses.<alias>.values.<key> e .context.uses.<alias>.infra.<key> — veja vocabulary/topology-triad.md.

Slots que cada conexão preenche — o featuresSchema de um socket. Um socket também pode declarar slots de acoplamento, e então cada conexão feita por ele pode carregar seu próprio acoplamento em cada um deles: um gateway que alcança vários modelos mantém uma credencial diferente para cada um, porque a credencial está na conexão e não no gateway.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Uma conexão preenche um slot carregando um acoplamento com o nome do slot em seu próprio features: — na entrada de conexão do Aggregate (Aggregate) ou na da Release (Release) — e o acoplamento se torna um dos acoplamentos do componente consumidor, com o nome <alias>.<slot>.

O que a declaração faz, dito com exatidão:

  • Os nomes de slot são um conjunto fechado. Diferentemente do featuresSchema próprio do Component, que admite um acoplamento livre com qualquer nome, os slots de um socket são os únicos nomes que uma conexão por ele pode carregar: qualquer outro nome interrompe o build no carregamento, e um socket que não declara nenhum featuresSchema não admite nenhum acoplamento em suas conexões. Um socket ad hoc — um que este usesSchema não declara — não declara slots, então suas conexões também não carregam nenhum. Cada conexão preenche seus próprios slots: um acoplamento em um escopo mais amplo nunca se propaga em cascata para uma conexão, e uma chave de Release que escreve o nome composto do acoplamento de uma conexão interrompe o build.
  • As outras chaves vinculam cada conexão ao slot. Aqui um slot aceita as mesmas chaves que um slot no nível do Component — required, selector, inject, sensitive, description — e cada conexão é submetida a elas individualmente. selector é comparado com os labels da Feature com que uma conexão preenche o slot, e um preenchimento que ele não admite interrompe o build, posicionado na entrada dessa conexão no documento que escreveu o preenchimento. required: true é exigido de cada conexão feita pelo socket: uma conexão que deixa o slot vazio interrompe o build, nomeando essa conexão, enquanto uma conexão ao lado que preenche o slot passa. sensitive é lido exatamente como em um slot no nível do Component: o acoplamento que preenche o slot é marcado como sensível no grafo de build e em aggrega inspect. Em uma conexão, como em um componente, quais valores de um acoplamento são retidos como sensíveis é decidido apenas pelo esquema próprio da Feature acoplada. inject rege a entrada de Workload que entrega o material do slot: o acoplamento de uma conexão não carrega nenhum bloco inject: próprio — nenhum dos dois documentos admite um em uma entrada de conexão —, então um Workload o entrega nomeando a conexão ao lado do slot, e essa entrada é submetida à lista de permissões do slot do socket exatamente como uma entrada que nomeia um slot no nível do Component é submetida à desse slot.

O usesSchema de uma Feature não aceita featuresSchema: uma conexão que uma Feature traça não carrega acoplamentos, e uma Feature que declara slots em um socket é recusada no carregamento. Uma credencial de que essa conexão precise é um slot no featuresSchema próprio da Feature.

Geração de esquema a partir de usesSchema. O compilador gera um fragmento base de JSON Schema 2020-12 a partir dos sockets declarados e o compõe com a declaração schema: do usuário — o mesmo padrão que featuresSchema usa. O esquema gerado nunca toca o disco; ele existe apenas em memória durante a etapa de validação do Component. O mapa uses: do desenvolvedor no Aggregate é validado em relação ao esquema mesclado; o selector: de cada socket é avaliado em relação aos labels de cada Component candidato durante a análise estática, como verificação de segurança de tipos entre nós.

Semântica dos seletores — o mecanismo do esquema dividido. usesSchema[].selector: é o que torna a topologia do Aggrega mais do que uma passagem de strings sem tipo. Um socket que declara selector: "datastore.aggrega.ai/engine=vector" só aceita conexões com Components rotulados com o par chave-valor correspondente; um agente que tenta conectar seu socket primary_datastore a um Component relational falha no Static Analyzer com um diagnóstico claro de violação do seletor. O seletor é uma string de seletor de labels no estilo do Kubernetes — requisitos combinados com E por vírgulas, nas formas =, !=, in (...), notin (...), chave simples e !key —, a mesma gramática que appliesTo de uma Feature usa; veja vocabulary/modifier-system.md para a gramática e architecture/13-catalog-and-registry.md §2 “Seletores no estilo do Kubernetes” para a semântica do mecanismo. Um requisito fora dessas formas é recusado em vez de ser lido como outro seletor: um requisito vazio (uma vírgula inicial, final ou duplicada), uma chave que contém espaços em branco ou qualquer um de =, !, (, ) e a vírgula, ou um conjunto sem o parêntese de fechamento interrompe todo build que conecta uma aresta pelo socket, nomeando o requisito. Assim, um socket destinado a excluir frontends é escrito selector: "tier!=frontend"; "!tier=frontend" é recusado, porque ! nomeia uma chave de label e nada mais.

Sockets ad hoc — o que declarar um socket proporciona e o que um autor pode fazer sem isso. O autor de um Aggregate pode escrever uma entrada uses: em seu próprio componente sob um nome de socket que este usesSchema não declara, inclusive em um Component que não declara nenhum usesSchema. A aresta é construída. O silêncio do catálogo sobre um socket significa que a conexão não foi prevista, não que ela seja proibida, e a topologia da aplicação pertence ao desenvolvedor.

Aquilo de que um socket ad hoc abre mão é precisamente o que um socket declarado oferece, porque tudo isso reside na entrada de usesSchema: nenhum selector, de modo que nada restringe qual componente a aresta pode alcançar e a verificação de segurança de tipos entre nós não tem nada a avaliar; nenhuma lista de permissões inject:; nenhum valueSchema por aresta, de modo que os values: por aresta não têm contrato em relação ao qual ser verificados nem valores padrão declarados a herdar. Ele abre mão também de infraSchema, embora esse contrato não seja alcançado de qualquer forma em um socket assim: o infra por aresta é escrito em uma entrada de aresta de uma Release, e uma entrada de Release só pode nomear um socket que o Component consumidor declara. O que não muda é o que a aresta pode carregar: o from: de cada entrada inject ainda deve nomear uma chave que o schema.provides do Component de destino declara, e o destino ainda deve existir — ambos interrompem o build como em um socket declarado.

Leia “nenhuma lista de permissões inject:” como a ausência de uma restrição e não como uma declaração de caixa-preta, porque as duas se parecem e se comportam de forma oposta. Uma aresta por um socket ad hoc pode determinar a entrega livremente: não há lista de permissões da qual um mecanismo possa ficar de fora, e nenhuma entidade se comprometeu a tratar os valores internamente. A recusa de caixa-preta descrita acima se aplica a um socket que a entidade de fato declarou e deixou sem lista de permissões inject: — essa omissão é uma declaração sobre uma conexão que a entidade previu, e um socket ad hoc não faz tal declaração.

A entrega segue o mesmo caminho, e o artefato renderizado não registra nenhuma diferença. O bloco inject de uma aresta ad hoc é resolvido e entregue exatamente como o de um socket declarado: cada chave from: é lida dos provides avaliados do destino e chega ao contexto de injeção do nó consumidor sob a chave de entrega escolhida pelo autor, alcançando dali o artefato renderizado. Há um único caminho de entrega e nada nele se ramifica conforme o socket tenha sido declarado ou não. O que um socket declarado pode acrescentar é conteúdo — valores padrão por aresta que seu valueSchema ou infraSchema preenche —, então, onde um socket declarado não carrega nenhum contrato desse tipo, a mesma aresta é renderizada de forma idêntica com qualquer um dos dois tipos de socket. A declaração é um fato sobre a conexão, não uma entrada do que é renderizado.

Os values: por aresta em um socket ad hoc são aceitos e chegam à Recipe consumidora em .context.uses.<alias>.values, sem validação: sem um valueSchema com que compará-los, nenhuma chave é verificada e nenhuma é rejeitada. Isso não é exclusivo dos sockets ad hoc — um socket declarado que não escreve nenhum contrato para o pilar trata sua configuração por aresta da mesma forma. O que um socket ad hoc muda é que o contrato não pode ser adicionado sem declarar o socket. .context.uses.<alias>.infra fica vazio em uma aresta assim, porque a superfície que fornece o infra por aresta não pode nomear um socket não declarado.

Cada aresta no grafo emitido registra qual dos dois tipos ela é, para que um consumidor nunca precise deduzi-lo, e uma organização que queira que toda conexão passe por um socket declarado pode exigir isso como política de governança. Declarar o socket aqui continua sendo o melhor caminho e é o que o catálogo da biblioteca padrão faz: um socket declarado traz um selector que restringe quais componentes a aresta pode alcançar, uma lista de permissões inject:, um contrato por aresta com seus próprios valores padrão e uma descrição — uma declaração revisável de uma conexão prevista, versionada com a entidade que a faz. A forma ad hoc é uma via de escape, não um novo padrão. Duas superfícies deliberadamente não são abertas dessa forma — os uses de um acoplamento de Feature só podem nomear um socket que a Feature acoplada declara, e os uses por aresta de uma Release só podem nomear um socket que o Component consumidor declara.

O exemplo prático examples/adhoc-uses-socket/ constrói os dois tipos de aresta em um único consumidor e mostra os dois valores entregues lado a lado na saída renderizada, junto com a interrupção que uma chave from: não declarada produz.

Erros de digitação em nomes de socket aparecem como aviso, não como interrupção. Como um nome de socket não declarado é válido, um nome de socket digitado errado se torna uma conexão ad hoc própria em vez de conectar o socket que o autor pretendia — e o build continua verde enquanto nada passa por ela. O compilador relata como aviso um nome de socket que está a uma edição de um nome que este usesSchema declara, nomeando as duas grafias — veja errors/warnings.md “Uses-socket near-miss lint (Lint de quase coincidências em nomes de socket uses)”. O aviso nunca muda o veredito do build; o compilador não fiscaliza como um autor nomeia um socket.

A relação entre usesSchema e featuresSchema. Ambos são tabelas declarativas e ambos carregam uma lista de permissões inject: com semântica idêntica, mas um socket e um slot são coisas diferentes e não são intercambiáveis. usesSchema rege as arestas entre componentes — o grafo de topologia — declarando quais sockets carregam um contrato. featuresSchema rege os slots de acoplamento, e um slot é um ponto de vinculação nomeado, não uma enumeração: um acoplamento com um nome que nenhum slot declara é válido no bloco próprio do componente. (Os slots que um socket declara para suas conexões são o único conjunto fechado, como indicado acima em “Slots que cada conexão preenche”.) As duas superfícies convergiram nesse ponto — a entrada uses: própria de um componente sob um nome de socket não declarado também é válida —, mas continuam distintas: um slot não declarado é um acoplamento livre em um Component cujos slots declarados não são afetados, enquanto um socket não declarado é uma aresta sem seletor e sem contrato por aresta. Muitos Components declaram ambos; as duas tabelas se compõem de forma independente.

Slots de associação: featuresSchema

Um Component pode declarar slots de associação por meio de um bloco featuresSchema. Cada slot nomeia um ponto de vinculação no qual o Component espera que uma Feature seja associada — uma senha de root, uma chave de API, um token de autenticação, uma vinculação de identidade — e restringe qual Feature pode ocupá-lo e como o material do preenchimento pode ser entregue.

Esta seção trata dos slots do próprio Component. Os slots que um socket declara para cada conexão são, em vez disso, um conjunto fechado — veja “Slots que cada conexão preenche” em Sockets de topologia.

Declarar um slot não fecha a superfície de associação. Um autor pode associar uma Feature com um nome que nenhum slot declara, e essa associação é uma associação livre: perfeitamente válida, apenas não vinculada a um slot declarado. Essa abertura é o que permite que uma mesma entidade do catálogo atenda a duas formas de implantação diferentes sem um fork do catálogo:

  • Por consumidor. Cada instância preenche o slot com sua própria Feature, de modo que cada consumidor recebe sua própria credencial renderizada.
  • Compartilhada. Nenhuma instância preenche o slot; em vez disso, uma credencial é associada uma única vez em um escopo mais amplo (um subsistema, ou um limite de Release) e se propaga em cascata para cada componente abaixo dele, de modo que cada consumidor é preenchido a partir dessa única declaração. O que é renderizado segue a realização: um Secret por consumidor, cada um com o mesmo material, com uma realização que renderiza um Secret; nenhum com uma que aponta cada consumidor para um Secret que já existe.

O autor escolhe entre as duas pelo que associa. A entidade do catálogo é a mesma nos dois casos.

Nessa superfície aberta, uma única forma causa uma interrupção: um preenchimento escrito no componente com outro nome. Quando uma associação escrita no próprio componente — em seu próprio bloco features: no Aggregate, ou na entrada da Release para esse único componente — tem um nome que nenhum slot declara, e sua Feature satisfaz o selector de um slot que nada ocupa nesse componente depois que todos os escopos são consolidados, o build é interrompido. Essa é a forma que um preenchimento destinado ao slot assume quando é escrito com o nome errado: deixado como está, seria uma associação livre enquanto o slot permanece vazio, e um slot opcional deixado vazio gera um build verde e não entrega nada. A mensagem nomeia a associação, o componente, a Feature e cada slot vazio ao qual essa Feature corresponde, e a solução é associá-la com o nome do slot. Isso vale para toda Feature, não apenas para credenciais. Todo o resto na superfície continua livre: uma associação cuja Feature não corresponde a nenhum slot declarado, uma associação adicional depois que cada slot ao qual ela corresponde está ocupado, e uma associação que o componente herda de um subsistema ou de um limite de Release — portanto a forma compartilhada descrita acima não é afetada. Um slot que não declara nenhum selector não diz nada sobre a qual Feature se destina, então nenhuma associação é confrontada com ele dessa maneira. A interrupção é descrita em errors/fatal-halts.md em “An attachment written under another name fits a slot its component leaves empty (Uma associação escrita com outro nome corresponde a um slot que seu componente deixa vazio)”.

As duas formas se combinam, e a mais próxima vence. Um autor pode fazer as duas coisas ao mesmo tempo: associar uma Feature em um escopo mais amplo para que ela alcance cada componente desse escopo, e preencher o slot no único componente que precisa de algo diferente. O preenchimento com escopo de componente vence — campo a campo, de modo que ele só precisa redeclarar os campos que altera e o restante continua vindo da associação mais ampla. Os componentes irmãos que não preencheram o slot mantêm a associação mais ampla intacta. A regra de precedência completa, incluindo como ela interage com associações orientadas por anotações e com Aggregates compostos, está em vocabulary/labels-and-annotations.md “Precedência de associações”.

Definição do schema no Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Semântica dos campos:

CampoTipoPadrãoSignificado
requiredboolfalseDeclara que o slot precisa terminar ocupado. O build é interrompido quando nada ocupa o nome do slot em uma instância deste Component, verificado em relação ao conjunto de associações que a instância possui após toda a cascata de associações — assim, uma associação declarada em um escopo do qual a instância herda satisfaz o slot exatamente como um preenchimento escrito na própria instância. O diagnóstico nomeia o componente e o slot.
injectstring[]—Lista de permitidos dos mecanismos de entrega inject aceitos. [] (vazia) significa caixa-preta — a Recipe controla a entrega internamente e o material nunca é entregue ao workload. [env, file] significa transparente — o material do preenchimento pode ser entregue pelos mecanismos listados. A mesma semântica de usesSchema[].inject.
descriptionstring—Documentação para pessoas, renderizada pelo IDE e pelo hub.
selectorstring—Seletor de labels opcional no estilo Kubernetes que restringe qual Feature pode preencher este slot — o análogo, para o slot, do selector de um socket de usesSchema, com a mesma gramática e o mesmo mecanismo nativo de correspondência de labels. É avaliado em relação às labels da própria Feature associada durante a análise estática; um preenchimento cujas labels não o satisfazem causa uma interrupção, assim como um seletor que a gramática recusa, nomeando o requisito que não conseguiu ler. Omita-o para não impor nenhuma restrição ao preenchimento.
sensitiveboolfalseDeclara que o que quer que ocupe este slot lida com material secreto. Uma afirmação sobre o ponto de vinculação, não sobre um preenchimento específico; veja “Declarar um slot como sensível” abaixo.

Um slot restringe qual preenchimento pode ocupá-lo, não o que o preenchimento configura. Deliberadamente não existe um contrato values ou infra no nível do slot: o próprio schema: da Feature associada é dono desses pilares, de modo que cada contrato tem exatamente um lugar.

O selector do slot é a forma como um Component restringe qual Feature pode preencher um slot — por exemplo, a uma Feature de credencial específica de um provider (feature.aggrega.ai/kind=secret, provider=helm) — sem nomear uma FeatureRecipe, exatamente como um seletor de socket de usesSchema restringe o destino de uma aresta de dependência. O compilador avalia o seletor em relação às labels da Feature associada e a nada mais: ele lê as labels que o preenchimento carrega e informa se o seletor as admite. Quais labels faz sentido exigir é uma escolha de autoria do catálogo, não uma regra que o compilador impõe.

Erros de digitação em nomes de slot aparecem como aviso, não como interrupção. Como um nome de associação não declarado é válido, um nome de slot digitado errado se torna uma associação livre em vez de preencher o slot que o autor pretendia. O compilador informa um nome de associação que está a uma única edição de um nome de slot declarado com um aviso que nomeia as duas grafias — veja errors/warnings.md “Attachment-slot near-miss lint (Lint de quase correspondências em slots de associação)”. O aviso nunca altera o veredito do build; o compilador não fiscaliza como um autor nomeia uma associação. Um nome a uma edição de um slot cujo selector a Feature da associação satisfaz não gera aviso: onde esse slot fica vazio, é a interrupção descrita acima que informa a associação, e onde outra coisa ocupa o slot, a associação é uma associação adicional comum.

Declarar um slot como sensível

sensitive: true em um slot expressa a exigência do próprio consumidor: o que quer que ocupe este ponto lida com material secreto.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Essa é uma informação realmente diferente do sensitive: true de uma folha do schema, não uma duplicata de conveniência, e o catálogo da biblioteca padrão precisa de ambos. Uma credencial referenciável publica provides.name e provides.key — o localizador do recurso e a chave de dados dentro dele — e nenhum dos dois é sensível: o nome de um Secret do Kubernetes é público, assim como a chave dentro dele. Ainda assim, o slot que essa credencial preenche sem dúvida lida com material secreto. Uma folha diz este dado é material secreto; um slot diz este ponto de vinculação lida com material secreto; as duas afirmações tratam de coisas diferentes e podem valer de forma independente.

A consequência prática é que a exigência acompanha o ponto de vinculação, e não o preenchimento. Uma Feature que não declara nenhuma folha sensível — porque o mecanismo de destino é dono da credencial e o autor não escreve nada — ainda ocupa um slot sensível como associação sensível, porque o slot assim declarou. O inverso também vale: um preenchimento que declara uma folha sensível é uma associação sensível mesmo quando ocupa um slot que não fez tal declaração, ou quando é uma associação livre que não ocupa nenhum slot.

A declaração segue a cascata de associações, e não um único bloco escrito. A exigência de um slot se aplica ao preenchimento que acabar ocupando-o depois que todos os escopos forem consolidados, de modo que um preenchimento no nível do componente que substitui um mais amplo herda a exigência sem alterações.

sensitive em um slot tem o mesmo limite da palavra-chave no nível da folha — ela anota; não criptografa, não valida, não rejeita, não impõe um mecanismo de entrega nem altera um byte renderizado. A formulação completa está em vocabulary/compact-form-authoring.md “O que a palavra-chave não faz”.

sensitive e compliance.aggrega.ai/data-class são dois eixos diferentes, documentados lado a lado e nunca confundidos. sensitive é um booleano em uma folha ou em um slot: este dado, ou este ponto de vinculação, lida com material secreto. compliance.aggrega.ai/data-class é uma label graduada em um nó inteiro — public, internal, restricted — que dá aos dados mantidos por um componente uma identidade de governança. Um é por dado e binário, a outra por nó e ordenada; nenhum substitui o outro, e uma entidade pode ter ambos. A label é tratada em vocabulary/labels-and-annotations.md e em architecture/08-credential-model.md “Governança de dados em torno de credenciais”.

Projeção do schema a partir de featuresSchema

Os slots declarados são projetados em um fragmento de JSON Schema 2020-12 que descreve a forma do bloco de associações. Dois tipos de preenchimento são validados em relação a ele: o bloco de associações de um componente que um módulo importado fornece, assim que a composição que o importa é construída, e uma associação declarada em um escopo mais amplo, em relação ao slot de cada componente que ela alcança. O bloco de associações de um componente que o próprio Aggregate declara é avaliado, em vez disso, pelo esquema de documento do Aggregate e pela lista de permitidos inject do slot (veja abaixo), e o fragmento tem uma forma que faz com que ambos cheguem ao mesmo veredito sobre qualquer preenchimento. A projeção nunca toca o disco; ela existe apenas em memória, e o schema: de um Component nunca precisa escrever à mão o pilar de associações.

featuresSchema de entrada:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Fragmento projetado (em memória; representação em forma compacta):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

As duas profundidades são independentes. O objeto externo é aberto, de modo que um slot declarado nunca proíbe as associações que a entidade não enumerou. O fragmento próprio de cada slot declarado é fechado, de modo que um preenchimento que de fato ocupa um slot declarado continua restrito à forma desse slot.

O fragmento descreve apenas a FORMA. Ele não contém nenhuma afirmação sobre quais slots precisam ser ocupados, porque um slot marcado como required pode ser ocupado por uma associação que chega em cascata de um escopo mais amplo — o que deixa vazio o bloco que este fragmento descreve. Por isso o requisito é verificado em relação ao conjunto de associações com que um componente termina, e não em relação ao que um único bloco declara, e as duas perguntas nunca se contradizem porque apenas uma delas é feita ao bloco escrito.

As chaves permitidas espelham as chaves que uma associação pode ter em qualquer lugar, de modo que uma chave válida em uma associação livre continua válida no preenchimento de um slot. Cada mecanismo de entrega da lista de permitidos é uma lista de entradas de entrega — a mesma forma que inject: assume em todo lugar; o slot restringe quais NOMES de mecanismo podem aparecer, não a aparência de uma entrada.

Onde a lista de permitidos inject é aplicada

A lista de permitidos vincula os dois lados do slot, em duas etapas diferentes.

Em relação ao Workload da Recipe, na etapa de renderização: um Workload que referencia um slot por meio das entradas de associação do seu contêiner precisa nomear um slot que a entidade declara, e precisa selecionar um mecanismo de entrega que a lista de permitidos inject do slot aceita; uma referência a um slot caixa-preta (inject: []), a um mecanismo fora da lista de permitidos ou a um slot que a entidade nunca declarou interrompe o build. O diagnóstico nomeia a Recipe, o caminho do contêiner e o slot problemático, e é classificado como uma falha do catálogo — foi a Recipe que errou.

Em relação à associação do próprio Aggregate, quando suas associações são resolvidas e antes de qualquer renderização: um bloco inject: em um preenchimento que ocupa um slot declarado só pode nomear mecanismos que a lista de permitidos do slot aceita, e um slot caixa-preta não aceita nenhum — sua lista de permitidos vazia diz “a Recipe entrega isto internamente; não determine a entrega”, e escrever uma entrega para ele interrompe o build. O diagnóstico é posicionado na associação e nomeia o slot e o mecanismo problemático, junto com os mecanismos que o slot aceita, quando aceita algum; é classificado como uma falha do desenvolvedor, porque foi o Aggregate que errou. Um bloco inject: {} vazio não nomeia nenhum mecanismo, portanto não determina nenhuma entrega e é aceito em qualquer slot, inclusive em um slot caixa-preta — seja em um componente que o Aggregate declara, em um que um módulo importado fornece ou em uma associação declarada em um escopo mais amplo. Uma associação livre — com um nome que nenhum slot declara — não tem essa restrição, porque a lista de permitidos pertence ao slot, e não ao bloco.

O fluxo de ponta a ponta pelo pipeline de compilação — como uma associação do Aggregate se conecta a uma Feature de credencial (como core/secret-value) e depois a uma FeatureRecipe específica do provider que entrega a credencial ao workload em execução — é detalhado em examples/05-credential-features.

Uma chave que o chamador apresenta e uma chave que o servidor verifica

Quando um componente chama outro que verifica uma chave, cada ponta mantém a chave do seu próprio lado, em um slot que ela mesma declara. Esta é uma convenção que o catálogo da biblioteca padrão segue; o compilador não aplica nada disso — ele verifica os slots de cada componente em relação às associações do próprio componente, repassa suas strings e nunca compara o que um componente mantém com o que outro mantém.

  • A chave que um chamador apresenta é do chamador. Ela fica em um slot que o socket do chamador declara para cada conexão — veja “Slots que cada conexão preenche” acima — de modo que um chamador que alcança vários destinos mantém uma chave para cada um. O socket model de core/ai-agent/crewai declara esse slot como credential, e suas Recipes entregam o que o preencher como OPENAI_API_KEY. Os sockets models de core/gateway/litellm, core/gateway/kong e core/gateway/apisix também o declaram, e suas Recipes entregam a chave de cada conexão em uma variável própria, nomeada conforme o alias da conexão, de modo que cada modelo servido pelo gateway tem uma chave própria. Uma chave que um Component declara, em vez disso, em um slot próprio é uma única chave para todas as conexões que ele estabelece.
  • A chave que um servidor verifica é um slot do próprio servidor. core/ai-model/vllm, core/ai-model/tei e core/ai-model/tgi declaram cada um um api_key opcional, e cada uma de suas Recipes entrega o que o preencher como a variável da qual o servidor lê sua chave. O modelo e o gateway LiteLLM declaram api_key para a chave que o LiteLLM chama de chave mestra.
  • Nenhuma ponta vê as associações da outra. Uma associação em uma conexão é uma das associações do chamador e alcança apenas a renderização do chamador, e a saída renderizada de um servidor é a mesma, seja o que for que as conexões que o alcançam carreguem. Um slot marcado como required é devido pelo componente que o declara, nunca pelos componentes conectados a ele, e preencher o slot de uma ponta não preenche nada na outra — portanto, declarar a chave nas duas pontas é o mínimo, e não uma duplicata.
  • As duas pontas leem um mesmo parâmetro, de modo que a chave que o chamador apresenta e a chave que o servidor verifica não podem ser escritas de forma divergente.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Um servidor que verifica uma única chave não consegue distinguir seus chamadores: vLLM, TEI e TGI verificam cada um uma única chave, de modo que todo chamador apresenta a mesma, não importa quantas conexões alcancem o servidor. Se as duas pontas referenciam um mesmo secret ou se cada uma mantém o seu depende de onde cada provider resolve um secret por referência, e o Manifest escolhe a realização de cada ponta — Modelo de credenciais detalha os dois casos.

Uma credencial que um componente mantém para si mesmo — uma chave com a qual assina suas próprias sessões, por exemplo — é um slot do seu próprio featuresSchema: como qualquer outro. Uma senha que ele apresenta a um armazenamento de dados que alcança por um de seus sockets é a chave do chamador descrita acima, portanto fica nessa conexão como credential: o socket backend de core/gateway/kong a declara, e suas Recipes de síntese de workload a entregam como KONG_PG_PASSWORD, e o socket cache_store de core/gateway/litellm a declara para a senha que seu cache semântico apresenta ao armazenamento, entregue como REDIS_PASSWORD. Quando uma conexão apresenta um par — um identificador de chave de acesso e seu segredo — a metade secreta é credential e a metade identificadora credential_id, como no socket store de core/ai-agent/agenta-api.

Autoinjeção: spec.inject

Um Component pode declarar um array de nível superior spec.inject: que lista os mecanismos de entrega permitidos para autoinjeção. Quando presente, os desenvolvedores podem usar um bloco inject: no nível do componente no Aggregate para injetar as chaves values: ou provides: do próprio Component diretamente em seu próprio canal de entrega (as variáveis de ambiente do seu contêiner, arquivos montados ou argumentos do processo). Quando spec.inject: está ausente ou vazio, a autoinjeção no nível do componente é proibida — a Recipe controla toda a conexão interna, seguindo o padrão Black-Box que usesSchema[].inject: [] e featuresSchema[].inject: [] aplicam, respectivamente, à entrega entre componentes e à entrega de credenciais.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Cada template value: começa com {{"{{"}} em vez de {{. Todo o texto do Aggregate é lido uma vez como template, para a interpolação de parâmetros, antes de a resolução da autoinjeção ser executada, e .values não existe nesse momento; o escape devolve {{ para que a resolução da autoinjeção o avalie. Veja Texto que carrega suas próprias chaves duplas.

Semântica do campo. spec.inject: é um array de nomes de mecanismos. Três valores são definidos:

  • env — variáveis de ambiente no contêiner.
  • file — caminhos de arquivos montados.
  • arg — argumentos de linha de comando do processo.

A semântica espelha exatamente usesSchema[].inject e featuresSchema[].inject — mesmo vocabulário, mesmo padrão Black-Box quando omitido, mesma forma de autoria no lado do Aggregate. A diferença é a origem: usesSchema[].inject governa como os provides de uma dependência entre componentes fluem para o canal de entrega do consumidor; featuresSchema[].inject governa como uma credencial chega a um contêiner; spec.inject governa como os values e provides do próprio Component chegam ao próprio contêiner do Component.

Disciplina de autoria. Um Component core/web-server que declara spec.inject: [env, file] opta pela entrega transparente — o autor do Aggregate dita quais nomes de variáveis de ambiente carregam quais valores. Um Component que declara spec.inject: [] (ou omite o campo) mantém a entrega opaca — o valuesMapping: da Recipe decide quais campos fluem para quais variáveis do contêiner, e o desenvolvedor não pode sobrescrever isso no Aggregate. O padrão Black-Box é adequado a Components de contrato estável (um Component core/postgres-db cuja Recipe sabe como conectar a senha do banco de dados a uma variável de ambiente POSTGRES_PASSWORD); o padrão transparente é adequado a Components em que a intenção do desenvolvedor nomeia legitimamente detalhes de entrega (um core/web-server cuja aplicação lê LOG_LEVEL de um nome de variável fora do padrão que o desenvolvedor quer personalizar).

Modos de erro. Um Aggregate de um desenvolvedor que usa um bloco inject: em um Component cujo spec.inject: está ausente ou vazio interrompe o build no carregamento do workspace (“Self-inject on a component without an allowlist” (Autoinjeção em um componente sem lista de permissões)). Um bloco inject: que usa um mecanismo fora da lista de permissões é interrompido com a mesma condição, nomeando o mecanismo e os que a lista permite (“Self-inject mechanism not in the component’s allowlist” (Mecanismo de autoinjeção fora da lista de permissões do componente)). Uma colisão de chaves de entrega entre autoinjeção, injeção entre componentes e injeção de credenciais também interrompe o build (“Duplicate delivery key across inject sources” (Chave de entrega duplicada entre fontes de injeção)). Veja errors/fatal-halts.md para a forma da mensagem de cada erro.

Autoria de catálogo: estendendo Components base

Os Platform Architects usam a palavra-chave extends para sobrepor interfaces especializadas a linhas de base corporativas ou da comunidade. Estender compõe a estrutura e herda os pilares de dados por inteiro. O compilador percorre a cadeia da base para baixo; as duas metades se comportam de forma diferente, e essa diferença é todo o modelo de autoria.

O que a extensão compõe. Estas superfícies são mescladas ao longo da cadeia, com o Component que estende prevalecendo chave a chave e as listas sendo concatenadas a partir da base, sem duplicatas:

SuperfícieComo se compõe
metadata.labelsmesclagem chave a chave; o valor do Component que estende prevalece em uma chave compartilhada
metadata.annotationsmesclagem chave a chave, com a mesma precedência — por isso o mandato de presença de uma base alcança todo Component que a estende
spec.featuresSchemaunião dos slots de anexação; um slot que o Component que estende declara novamente substitui a entrada da base com esse nome
spec.usesSchemaunião dos sockets de topologia, com a mesma regra de substituição por nome
spec.injectas duas listas de permissões de autoinjeção são concatenadas, entradas da base primeiro, duplicatas descartadas
spec.assertionsas regras nomeadas se acumulam, regras da base primeiro — e esta única superfície não admite substituição por nome; veja “A herança de asserções é aditiva” abaixo

Um socket que o Component que estende adiciona pode ter seus próprios valueSchema e infraSchema por aresta; esses são contratos sobre as arestas desse socket, não adições aos pilares do próprio Component.

O restante de metadata: fica com o documento que o declara. labels e annotations são os únicos metadados que descem pela cadeia. name, version, description, maintainers, license, repository, home e keywords são do próprio Component que estende e são lidos exatamente como ele os escreveu — um Component que omite description: não tem nenhuma, em vez de tomar emprestada a de sua base. Identidade e procedência pertencem ao documento que você está lendo, de modo que um wrapper nunca é confundido com aquilo que ele envolve.

O que a extensão herda por inteiro. Os três pilares de dados — values, infra, provides — não são compostos. Um Component que estende não escreve conteúdo de pilares: ele escreve o marcador literal schema: inherited e recebe o bloco schema: de sua base exatamente como a base o escreveu. Ao longo de uma cadeia de qualquer profundidade, cada Component nela carrega inalterado o bloco da raiz da cadeia, de modo que aggrega inspect --resolved em uma folha mostra os mesmos pilares que a raiz.

O schema Component publicado determina qual dos três resultados possíveis é válido e rejeita os outros dois quando o documento é carregado — com um diagnóstico diferente para cada um, porque são erros diferentes:

  • extends: com conteúdo de pilares sob schema: é rejeitado. O contrato do Component é o de sua base; um segundo contrato divergente não tem onde existir.
  • extends: com schema: totalmente omitido é rejeitado. Uma omissão deixaria o leitor sem como distinguir um bloco de pilares herdado de um esquecido.
  • schema: inherited sem extends: é rejeitado. O marcador indica de onde vêm os pilares, e este Component não tem uma base de onde tirá-los.

Um Component que estende não pode remodelar o conjunto de chaves. Ele não declara chaves de pilares, então não pode ocultar, remover ou mudar o tipo de uma chave que sua base declara, e não adiciona nenhuma própria. Uma nova chave de pilar pertence ao Component cujo contrato a possui. O que quer que a base exponha, tudo o que a estende expõe de forma idêntica.

Uma especialização se restringe por meio de assertions:. Quando uma especialização precisa admitir menos do que os pilares de sua base — um intervalo numérico mais estreito, um subconjunto de um enum: herdado —, ela o declara em seu próprio bloco assertions:: uma regra ali rejeita um valor que o schema herdado aceita. Essa é a superfície onde a restrição reside; veja “O bloco assertions:” abaixo.

Esses dois últimos parágrafos são uma única regra, e cada metade isolada induz ao erro: estreitar o conjunto de chaves é impossível, endurecer as restrições é possível. Quem toma só a primeira conclui que uma especialização não pode restringir nada; quem toma só a segunda conclui que ela pode remodelar o contrato. Nenhuma das duas coisas é verdade — o conjunto de chaves é fixado pela base, e os valores admitidos dentro dele podem ser restringidos por predicado.

A herança de asserções é aditiva, e o acúmulo começa pela raiz. Uma instância de um Component que estende é verificada em relação a cada regra que sua cadeia declara, além das regras que o próprio Component declara, sendo as herdadas avaliadas primeiro. Ao longo de uma cadeia de qualquer profundidade, as regras se acumulam a partir da raiz da cadeia para baixo, de modo que, quando uma instância violaria mais de uma regra, é relatada a declarada mais acima na cadeia — o contrato mais fundamental responde primeiro.

Como a herança adiciona em vez de substituir, um Component que estende não pode reutilizar o nome de uma regra herdada para declarar uma regra diferente: isso é rejeitado quando a cadeia de extends é resolvida em relação ao catálogo, com um diagnóstico que nomeia os dois Components e o nome compartilhado. A verificação precisa do Component base em mãos, então ela é relatada quando o catálogo é validado ou quando um build resolve a cadeia — validar isoladamente o documento que estende não consegue detectá-la. O nome da regra é um identificador estável, então nem remover a regra da base nem renomeá-la silenciosamente é uma opção, e a correção é uma renomeação no Component que estende. Repetir uma regra herdada byte a byte sob o próprio nome é aceito como a operação nula que é.

aggrega pull busca a base. Uma base é uma dependência de toda Release que alcança um Component que a estende, quer algo mais a nomeie ou não. aggrega pull segue cada extends: até o fim da cadeia, busca no registry uma base que nenhum diretório de catálogo contém e registra cada base no lockfile da Release, referenciada a partir do spec.extends do Component que a nomeia; um build lê a base dali. Assim, um Manifest mapeia o tipo próprio de um wrapper e nada mais — a base precisa de uma linha de mapeamento própria apenas onde um Aggregate também declara uma instância da base. Um aggrega validate do catálogo inteiro lê uma base da mesma forma, de modo que uma base publicada em um registry é recusada ali, nomeando aggrega pull, até que um pull a tenha buscado.

Veja architecture/13-catalog-and-registry.md §3 para os formatos de conteúdo de schema.

Exemplo A: o Component base (a linha de base corporativa) O Platform Architect define um servidor corporativo fundamental. Essa base define o rótulo obrigatório de primitiva operacional de nuvem e estabelece as restrições de segurança no schema. Como o bloco de pilares é herdado inalterado, cada restrição aqui chega a cada Component que estende exatamente como foi escrita.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Exemplo B: o Component que estende (especializando a linha de base) Um gateway é especializado a partir dessa linha de base. Ele recebe os pilares da base por inteiro, adiciona estrutura própria — um rótulo, um mecanismo de autoinjeção, um socket de topologia com um slot de anexação — e restringe o timeout herdado por meio de uma asserção. Ele não repete a regra audit-window-is-observable da linha de base: essa regra é herdada e avaliada primeiro, de modo que uma instância deste gateway precisa satisfazer os dois limites — no mínimo 100 e no máximo 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Para a Recipe que implementa esta interface core/gateway/kong sobre um chart Helm físico, veja entities/recipe, Exemplo C (kong-gateway).

O bloco assertions:

Component.spec.assertions: é um mapa opcional de regras nomeadas que expressam invariantes arquiteturais do contrato do Component — regras entre campos que a autoria do desenvolvedor precisa satisfazer independentemente de qual Recipe se vincule ao Component. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é o corpo de um template Go. O compilador as avalia por instância após a validação do schema e antes da vinculação da Recipe, na ordem em que estão escritas, e a primeira regra que falha interrompe o build com a mensagem de erro própria dessa regra, conforme o contrato Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

A regra acima é uma propriedade do contrato do Component — qualquer que seja a Recipe vinculada (chart Bitnami, alternativa feita à mão, implementação futura), o modo de replicação exige pelo menos duas réplicas secundárias.

assertions: é onde um Component que estende se restringe. Um Component que usa extends: sobre uma base herda literalmente o bloco de pilares da base e não declara conteúdo de pilares próprio, então uma especialização que precisa admitir menos do que o schema herdado expressa aqui a restrição como um predicado em vez de uma folha de schema estreitada — uma regra que rejeita um valor que os pilares herdados aceitam. O par de exemplos e o comportamento completo da herança estão em “Autoria de catálogo: estendendo Components base” acima: as regras se acumulam ao longo da cadeia a partir da raiz, e reutilizar o nome de uma regra herdada para uma regra diferente é rejeitado em vez de permitir que a substitua.

O compilador não verifica se duas regras podem ser satisfeitas ao mesmo tempo. Uma regra é um predicado de template, não uma restrição sobre a qual o compilador raciocina, então um par de regras que nenhum valor consegue satisfazer ao mesmo tempo — uma base exigindo no mínimo 100 e uma especialização exigindo no máximo 50 — não produz nenhum aviso quando o catálogo é carregado. Isso aparece da forma comum: uma instância é escrita, o build é interrompido na primeira das duas que disparar, e a mensagem dessa regra é o que o autor lê. Não espere que uma contradição seja relatada de antemão; verifique a restrição de uma especialização em relação ao que sua base já exige.

Use assertions: para regras genuinamente entre campos. Restrições por campo (intervalo, padrão, enum) pertencem às palavras-chave de schema:; predicados personalizados por campo pertencem a validate: da forma compacta; a forma condicional (se as restrições de uma subárvore se aplicam) pertence a when:. Para a gramática de autoria completa — campos do contexto do template, a convenção de mensagem {{ fail }}, a fase de avaliação e exemplos completos que abrangem os papéis de Component e Recipe —, veja templates/assertions-block.md.