Component
O papel conceptual 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 Etiquetas Semânticas que os Arquitetos usam para sobrepor uma identidade cognitiva à ontologia base operacional, a declaração schema: para os pilares de dados, as tabelas declarativas usesSchema e featuresSchema para os sockets de topologia e os slots de anexo, os mandatos de presença, o mecanismo de herança extends: e o bloco de regras entre campos assertions:.
A taxonomia semântica de etiquetas (a convenção da biblioteca padrão)
Se os tipos base forem puramente cloud-native, a inteligência operacional e cognitiva da arquitetura é sobreposta inteiramente através de duck-typing semântico.
O compilador Go central não interpreta estas etiquetas. O compilador constrói o grafo plano da Representação Intermédia (IR) sem interpretar a semântica das etiquetas. Estas etiquetas representam a convenção da biblioteca padrão—«marcadores genéticos» imutáveis criados pelo Arquiteto de Plataforma no Domínio 2. Fornecem os ganchos 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 cloud genérica Estas etiquetas descrevem comportamentos universais, permitindo que os motores de políticas e os proxies L7 gerados governem arquiteturas empresariais padrão sem precisarem de compreender nativamente frameworks de IA.
| Prefixo da etiqueta | Valores permitidos (convenção) | Porque é que a equipa de Platform Ops precisa dela (o gancho de política) |
|---|---|---|
tool.aggrega.ai/impact | read-only, mutating | Permite que os motores de políticas avaliem a AuthZ de privilégio mínimo. As ferramentas que alteram estado podem acionar automaticamente políticas que exigem a anexação de sidecars de aprovação estritos. |
datastore.aggrega.ai/engine | relational, document, kv, vector, graph, semantic-memory, search (conjunto de valores em estabilização face ao catálogo preenchido) | Permite que os motores de políticas imponham segurança de tipos entre nós (por exemplo, impedindo que um agente tente enviar payloads SQL para uma Vector DB). |
gateway.aggrega.ai/intelligence | semantic, l4-mesh | Dita que funcionalidades um router consegue suportar fisicamente (por exemplo, impedindo que uma Feature que encaminha com base no modelo indicado num pedido, como uma cadeia de fallback, seja anexada a uma mesh TCP padrão). |
dataplane.aggrega.ai/request-mirroring | full-rate, sampled | Permite que uma Feature que copia tráfego em direto para um segundo destino selecione um proxy que consiga de todo copiar, e distinga um que copia todos os pedidos correspondentes de um cuja fração de pedidos copiados é configurável. |
dataplane.aggrega.ai/caller-identity | client-certificate, injected-header | Permite que uma Feature que precisa de identificar o chamador original perante o serviço por trás do proxy selecione um componente capaz de transmitir essa identidade, e leia qual o mecanismo que a transmite — os detalhes do certificado TLS do próprio cliente reencaminhados, ou um cabeçalho que o próprio proxy compõe depois de autenticar o chamador. |
dataplane.aggrega.ai/content-masking | entity-recognition, pattern-list | Permite que uma Feature que mascara texto sensível selecione um componente capaz de o substituir por um marcador de posição no payload de chat e de completion que encaminha, antes de o texto seguir mais adiante. O valor indica a fidelidade: com entity-recognition, o componente substitui as correspondências de padrões fornecidos na sua configuração e também os tipos de entidade que um serviço de reconhecimento que invoca deteta; com pattern-list, substitui apenas as correspondências de padrões fornecidos na sua configuração e não invoca nenhum serviço de reconhecimento. |
dataplane.aggrega.ai/prompt-guard | pattern-list, classifier | Permite que uma Feature que filtra prompts de modelos selecione um componente capaz de inspecionar o payload de chat e de completion que encaminha e de recusar um pedido com base no seu conteúdo. O valor indica a fidelidade: com pattern-list, a correspondência faz-se contra padrões fornecidos na sua configuração, sobre o payload do modelo e não sobre um corpo HTTP arbitrário; com classifier, o veredicto é o de um classificador de texto treinado, obtido através de um serviço de deteção que o componente invoca, face a um limiar fornecido na sua configuração. |
dataplane.aggrega.ai/upstream-tls | trust-anchor | Permite que uma Feature que exige que o proxy verifique com quem está a falar selecione um componente capaz de verificar o certificado de um upstream face a uma âncora de confiança que a Release fornece. |
dataplane.aggrega.ai/upstream-pinning | public-key | Permite que uma Feature que fixa a chave que um upstream pode apresentar selecione um componente capaz de recusar um upstream, a menos que um certificado que este apresente contenha uma das chaves públicas que a Release fornece. Uma asserção diferente de upstream-tls: uma fixação diz qual deve ser a chave de um certificado; uma âncora, o que este deve dizer. |
dataplane.aggrega.ai/period-budget | cost, tokens | Permite que uma Feature que limita o que o tráfego pode consumir ao longo de um período selecione um componente capaz de recusar pedidos a modelos assim que o que contabilizou ao longo do período exceda um limite definido na sua configuração. O valor indica o que contabiliza: cost, o custo do tráfego, calculado a partir de uma tabela de preços que o componente mantém por modelo; tokens, os tokens que a resposta de cada modelo indica ter lido, escrito ou ambos, que o componente contabiliza sem atribuir qualquer preço. |
dataplane.aggrega.ai/concurrency-cap | total, per-target | Permite que uma Feature que limita quantos pedidos um componente transporta em simultâneo selecione um componente capaz de reter ou recusar um pedido acima de um limite definido na sua configuração. O valor indica o que um limite contabiliza: total, todos os pedidos que o componente reencaminha, face a um único limite; per-target, os pedidos em curso para cada destino upstream para onde envia, com um limite para cada um e nenhum para o seu total. |
As chaves dataplane.aggrega.ai/ designam uma posição no caminho do tráfego e não um tipo de componente, pelo que um proxy, um gateway de entrada e uma service mesh se descrevem todos num único vocabulário, em vez de cada um precisar do seu. Vale a pena ler com atenção duas propriedades da família, porque ambas são fáceis de inverter:
- O valor transporta a fidelidade, não apenas a presença da capacidade. Dois componentes podem ambos espelhar pedidos e ainda assim diferir de uma forma que interessa a uma Feature, pelo que a distinção segue no valor e uma Feature seleciona a fidelidade de que precisa. Um componente que oferece uma fidelidade mais forte transporta o valor mais forte e nenhum outro.
- Um valor afirma o que o produto é capaz de fazer, nunca o que uma implementação ativou. Os dois leem-se de forma semelhante e só o primeiro é uma propriedade do componente. Um proxy capaz de verificar um certificado upstream transporta
upstream-tls: trust-anchor, quer uma dada implementação ative ou não a verificação, porque a etiqueta é aquilo com base no qual uma Feature seleciona antes de qualquer configuração.
Um componente sem nada a descrever num destes eixos não transporta nenhum valor nesse eixo, em vez de transportar o mais fraco, exatamente como no resto da taxonomia: a ausência significa que o eixo não tem objeto nesse componente, pelo que uma Feature que exija qualquer valor nesse eixo, corretamente, não é anexada.
(B) A camada de IA especializada (a identidade cognitiva) Estas etiquetas descrevem a identidade cognitiva da carga de trabalho, permitindo à arquitetura proteger frameworks de IA modernos.
| Prefixo da etiqueta | Valores permitidos (convenção) | Porque é que a equipa de Platform Ops precisa dela (o gancho de política) |
|---|---|---|
model.aggrega.ai/capability | generative, embedding, transcription | Usada pelas strings de seletor de usesSchema (avaliadas nativamente pelo compilador Go durante a análise estática) para garantir que um programador não encaminha por engano um payload de texto generativo para um endpoint de embeddings. |
model.aggrega.ai/api | openai, anthropic, gemini, native | Indica que 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 da Google, e native quando é a API própria do produto e nenhuma daquelas. Todos os componentes de modelo a transportam, tal como um gateway capaz de servir uma API de modelo, pelo 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 consiga servir 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 liga: um gateway cujos modelos estão ligados a um socket próprio também a transporta sem nada ligado. A etiqueta é uma string que o seletor compara; nada verifica o que de facto responde no endereço. |
agent.aggrega.ai/autonomy | autonomous, copilot | Identifica o risco de execução do ciclo cognitivo, permitindo que as políticas imponham funcionalidades de aprovação humana para agentes totalmente autónomos. |
(C) Os transversais (governação, estado & hardware) Estes representam as tags empresariais fundamentais que conduzem a validação Zero-Trust e o encaminhamento de hardware.
| Prefixo da etiqueta | Valores permitidos (convenção) | Porque é que a equipa de Platform Ops precisa dela (o gancho de política) |
|---|---|---|
component.aggrega.ai/hosting | self-hosted, managed, external, mixed | Regista quem opera o recurso subjacente de um componente — o eixo da fronteira de confiança. Os motores de políticas leem-na para calcular o risco de exfiltração de dados (por exemplo, dados internos encaminhados para uma API de terceiros managed saem da fronteira do operador). Transversal: os mesmos valores descrevem igualmente uma base de dados gerida, uma API de modelo gerida e um servidor de inferência autogerido. mixed assinala um componente cujas Recipes abrangem mais do que uma modalidade — um repositório de dados auto-alojado pelas suas Recipes de Helm e Compose e gerido pelas suas Recipes de RDS — pelo que a modalidade de uma Release segue a Recipe que o seu Manifest seleciona. |
compliance.aggrega.ai/data-class | public, internal, restricted | A classe dos dados que um componente contém. O compilador transporta-a para o 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 a sua ordem nas suas próprias definições e lê a etiqueta 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 a transporta: a classe é uma afirmação sobre a forma como um parque usa um componente, transportada pelo próprio Component desse parque — uma especialização através de extends, por exemplo. |
compliance.aggrega.ai/contains-pii | true, false | Assinala explicitamente cargas de trabalho no âmbito do GDPR/CCPA. Uma política que um operador anexa pode lê-la para exigir Features específicas nas rotas que o tráfego dessa carga de trabalho percorre — core/data-masking num gateway de IA através do qual 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 a transporta; tal como a classe de dados, é uma afirmação de um parque sobre os seus próprios componentes. |
hardware.aggrega.ai/accelerator | gpu, tpu, npu | Usadas pela equipa de DevOps no ficheiro Release. Encaminham explicitamente estes componentes para fronteiras físicas de pools de hardware (por exemplo, um cluster com GPU) através do mapa components: {}, enquanto um papel de veredicto de governação pode impor que componentes etiquetados com GPU nunca sejam colocados em fronteiras sem GPU. |
state.aggrega.ai/retention | retain, delete | Resolve a lacuna de eliminação AOT. Se um programador eliminar uma base de dados do seu Aggregate, um orquestrador GitOps apaga fisicamente o disco. Um passo pipeline: de uma Recipe pode ler a etiqueta retain e acrescentar proteção nativa do orquestrador aos artefactos renderizados (por exemplo, helm.sh/resource-policy: keep). |
state.aggrega.ai/backup-tier | mission-critical, standard, ephemeral | Gancho 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 ADN imutável do catálogo, os contextos de negócio dinâmicos (como o âmbito de auditoria SOC2 ou o acompanhamento de custos FinOps) mudam consoante quem implementa a aplicação e onde esta é executada. São governados por anotações injetadas dinamicamente pelos subsystems do Programador, pelas fronteiras da Release de Ops ou por um plugin de governação anexado no papel annotation-transform.
| Prefixo da anotação | Valores permitidos (convenção) | Porque é que a equipa de Platform Ops precisa dela (o gancho de política) |
|---|---|---|
business.aggrega.ai/cost-center | p. ex., finance, ai-research | Exigido pelos plugins de renderização Wasm para injetar etiquetagem física (por exemplo, tags da AWS ou labels do K8s) nos artefactos finais gerados para os painéis de faturação da cloud. |
business.aggrega.ai/owner | p. ex., team-alpha@corp.com | Encaminhamento da resposta a incidentes. Garante que a infraestrutura está associada a uma equipa humana. |
compliance.aggrega.ai/frameworks | p. ex., soc2, hipaa | Gatilho de âmbito SOC2. Injetado através da Release do ambiente. Os plugins Wasm leem esta string para gerar automaticamente sidecars rígidos de registo de auditoria e desativar portas de depuração quando uma aplicação entra numa 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, eliminá-la ou inventar o seu próprio vocabulário de etiquetas (mycompany.com/custom-trait). Os plugins Wasm avaliam quaisquer chaves de etiqueta que a empresa defina.
Criação de esquemas
O esquema do Component (e o seu equivalente Feature, incluindo as Features de credenciais etiquetadas com feature.aggrega.ai/kind: secret) declara o contrato de validação dos values criados pelo programador através de um bloco spec.schema:. O bloco aceita JSON Schema 2020-12 expresso quer na abreviatura YAML de forma compacta (a predefinição; cerca de 15 palavras-chave, transformadas mecanicamente em JSON Schema no momento da compilação) quer em JSON Schema YAML completo (a forma extensa), com referências entre documentos através de $ref: para entradas de SchemaLibrary partilhadas entre vários Components.
- Forma compacta inline (superfície de criação predefinida): um bloco YAML incorporado que contém folhas de forma compacta diretamente no YAML do Component. Abrange a grande maioria do conteúdo de esquemas do catálogo numa fração do número de linhas do JSON Schema completo. Consulte
vocabulary/compact-form-authoring.mdpara o vocabulário de palavras-chave e as convenções de criação. - JSON Schema YAML inline: a forma extensa, adequada quando o esquema precisa de palavras-chave do JSON Schema 2020-12 que a forma compacta não suporta diretamente (
$dynamicRef,unevaluatedPropertiesprofundo, composiçãonot:complexa). A forma compacta e o JSON Schema podem misturar-se em qualquer fronteira de nó dentro de um único blocoschema:através da via de escape$jsonschema:. - Referência entre documentos (
$ref:para uma entrada de SchemaLibrary): um$ref:nativo do JSON Schema que aponta para uma entrada de SchemaLibrary por identidade (Datastores#/schemas/MariaDBValuesou semelhante). Os esquemas empresariais com centenas de linhas e reutilizados em vários Components residem em entidades SchemaLibrary; o Component consumidor referencia a entrada sem incorporar o conteúdo. Consulteentities/schemalibrary.mdevocabulary/cross-document-ref.mdpara 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 qualquer conteúdo de pilares: 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: assume num Component desse tipo. Consulte «Criação no catálogo: estender Components base» abaixo.
O compilador resolve o bloco schema: — expandindo a forma compacta, desreferenciando os URLs $ref:, aplicando as cadeias de biblioteca para biblioteca da SchemaLibrary — e unifica o JSON Schema resultante com as bases geradas automaticamente a partir de usesSchema e featuresSchema (consulte a secção abaixo) durante a passagem de validação do Component. A validação é executada contra o esquema resolvido; o caminho de criação é opaco para as fases seguintes do pipeline.
As instâncias criadas são validadas contra este esquema resolvido no momento do build: os values criados pelo programador de uma instância de componente e o infra resolvido do Operador, mais os values/infra de qualquer anexação de Feature, têm de estar em conformidade com os pilares declarados — um valor de tipo errado, um número fora do intervalo, uma string que não tem o format declarado, um campo obrigatório em falta ou (para values, validado de forma fechada) uma propriedade não declarada interrompem o build na sua origem criada, em vez de produzirem um manifesto defeituoso no momento da implementaçã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, incluindo password — é recusado quando o catálogo é carregado, com a lista dos nomes suportados; consulte vocabulary/compact-form-authoring.md para o que cada nome verifica. Uma instância de um Component que extends: uma base é validada contra o bloco de pilares da base, que o Component que a estende herda sem alterações — pelo que 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 o infra criados não estão em conformidade com o esquema declarado)» para os diagnósticos e as regras por pilar (incluindo a forma como infra é validado contra a união de chaves do Component e do fornecedor).
Os valores predefinidos declarados materializam-se nos pilares renderizados. Além da validação, um default: declarado num campo de values (ou num campo de infra) é preenchido no pilar renderizado no momento do build para cada chave que o autor omite — pelo que um template de Recipe que lê {{ .values.charset }} recebe o utf8mb4 declarado no esquema em vez de um valor vazio. Os valores fornecidos pelo autor prevalecem sempre; os objetos aninhados são preenchidos por cada filho omitido. Como a materialização usa a mesma resolução de esquemas que a validação, os valores predefinidos alcançados através de um $ref: entre documentos para uma SchemaLibrary também se materializam — tanto uma referência a um pilar inteiro (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) como a forma base-mais-variante (um $ref: base a par de properties irmãs, cada uma com os seus próprios valores predefinidos). Os valores predefinidos declarados apenas dentro de uma referência local no documento #/$defs/, ou sob um ramo allOf / oneOf / anyOf, não são materializados; a biblioteca padrão compõe os pilares através de $ref: entre documentos, que é materializado.
O pilar values
O esquema do Component separa três pilares por propriedade: values é preenchido pelo Programador no Aggregate (intenção cognitiva — nome da base 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 Programador 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 seu fornecedor de destino espera. Esta secção abrange a superfície de criação do pilar values. Consulte vocabulary/data-pillars.md para a taxonomia mais ampla dos pilares e a disciplina de cascata entre pilares.
values transporta a intenção cognitiva do Programador — as escolhas que descrevem o que a aplicação é ou faz, não como é dimensionada ou executada. O nome da base de dados, o charset, a versão do motor, o nível de registo, as feature flags e os parâmetros da camada aplicacional que mudam entre versões da aplicação mas se mantêm estáveis entre ambientes são conteúdo típico de values. O Operador nunca substitui values: (o esquema da Release rejeita mecanicamente um bloco values: segundo architecture/06-data-taxonomy-and-composition.md §8 Restrição 4); a variação por ambiente flui através do Parameter Hoisting — o Aggregate expõe parameters.* tipados, o template de values do Component referencia-os e a Release preenche os parâmetros.
# Component schema declares the values shape:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: 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: infoConsumo do lado da Recipe. As Recipes leem os valores resolvidos através de .values.<field> em valuesMapping:, provides:, assertions: e nas outras 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 anexações de Feature no mesmo nó do Component, para que o contexto de template resolvido contenha todos os campos aplicáveis.
Disciplina entre pilares. values é o único pilar que o Programador cria no Aggregate. Os campos estritamente orientados para o programador pertencem aqui; os parâmetros operacionais (número de réplicas, limites de CPU/memória) pertencem ao pilar infra do Component, para que residam na Release; a saída pública (host, porta) pertence a provides da Recipe. Misturá-los quebra a invariante de propriedade; consulte vocabulary/data-pillars.md «Mecânica entre pilares» para os casos raros em que é justificado encaminhar deliberadamente valores entre pilares.
O pilar infra
O esquema do Component separa três pilares por propriedade: values é preenchido pelo Programador no Aggregate (intenção cognitiva — nome da base de dados, versão, charset), infra é preenchido pelo Operador na Release (dimensionamento operacional — computação, armazenamento, HA; a cópia de segurança de um armazenamento de dados não é dimensionada aqui, sendo antes 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 Programador 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 seu fornecedor de destino espera.
Três convenções de infra são relevantes em cada Component agnóstico em relação à capacidade da biblioteca padrão: uma via de escape de estrutura aberta para parâmetros específicos do fornecedor, uma substituição opcional da versão do artefacto upstream e um vocabulário baseado na 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 MariaDB ao controlador mariadb-operator, Recipes Terraform contra o AWS RDS, Recipes CloudFormation contra a mesma superfície do RDS e Recipes Compose contra um contentor local — e o seu bloco infra ilustra a primeira e a terceira.
infra.overrides
Os campos universais de infra — compute, storage, ha — abrangem a maior parte do dimensionamento operacional entre fornecedores. A parte restante é irredutivelmente específica do fornecedor: uma Recipe Kubernetes precisa de um nodeSelector, uma Recipe Terraform de RDS precisa de um instance_class, uma Recipe CloudFormation de RDS precisa de um DBInstanceClass, uma Recipe Compose precisa de uma substituição de image. O esquema do Component expõe um mapa verdadeiramente aberto como via de escape para que estes parâmetros passem sem sobrecarregar 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 permittedO type: object explícito com additionalProperties: true adere à semântica de mapa aberto. O compilador encaminha a estrutura sem a tocar; o corpo do template da Recipe lê as chaves que conhece e ignora as restantes. Cada Recipe documenta a ontologia de chaves de substituição no seu comentário de cabeçalho, para que um Operador que cria uma Release para uma combinação específica de Component × Recipe saiba que parâmetros a Recipe expõe.
Um fragmento de Release que usa 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-exporterO Programador nunca vê overrides — reside na Release, que é o domínio do Operador.
infra.source_version
O campo source de uma Recipe referencia um artefacto upstream numa versão específica (chart Helm 25.0.8, módulo Terraform 4.2.0, tag de imagem OCI). Fixar a versão dentro da Recipe obriga o responsável pelo catálogo a publicar uma nova Recipe a cada atualização compatível da 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ê-a através do helper optional no seu bloco source, pelo que uma fixação ausente recai na versão contra a qual a Recipe foi criada:
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 artefacto, contra .values, .infra e .locals, sem raiz .context; uma origem que indique um caminho no espaço de trabalho é avaliada quando a entidade é renderizada, contra o mesmo contexto autónomo que os locals da Recipe — .context.instance_id, .values, .infra e a totalidade dos .locals resolvidos do nó. .context.inject, .context.uses e .provides estão proibidos em ambos os casos. O facto de .infra estar nesse contexto é o que faz a substituição acima funcionar, e .locals permite a uma Recipe calcular um fragmento de origem uma vez e lê-lo de volta aqui. Um template de origem nunca lê os provides do seu próprio nó: esse pilar não faz parte do contexto, e um template que tente aceder-lhe 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 à predefinição da Recipe não garante que o valuesMapping da Recipe seja compatível a nível de transmissão com a nova versão upstream; a description da declaração source_version do esquema do Component contém esse aviso.
infra.ha.*
Os campos de alta disponibilidade usam vocabulário de intenção, não vocabulário de mecanismo:
infra: ha: enabled: { type: boolean, default: false } read_replicas: { type: integer, min: 0, default: 0 }infra.ha.enabled diz «torna este Component altamente disponível» e infra.ha.read_replicas diz «quero N cópias só de leitura». Cada Recipe decide em que se torna a intenção no seu fornecedor. As Recipes da biblioteca padrão para core/datastore/mariadb, com os nomes com que um Manifest as mapeia:
| Recipe | ha.enabled: true mapeia para | ha.read_replicas: N mapeia para |
|---|---|---|
helm/mariadb (um StatefulSet sobre a imagem oficial mariadb) | executa um único servidor, pelo que o build é interrompido indicando a chave | executa um único servidor, pelo que N acima de 0 interrompe o build |
helm/mariadb-cluster (um recurso personalizado MariaDB que o controlador mariadb-operator reconcilia) | ativa a comutação automática por falha (replication.primary.autoFailover: true); a comutação faz-se para uma réplica de leitura, pelo que N igual a 0 interrompe o build | define 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 no aws_db_instance primário | cria N recursos de réplica de leitura aws_db_instance separados |
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS através de um módulo) | passa multi_az = true ao módulo | aprovisiona uma única instância, pelo que N acima de 0 interrompe o build |
cloudformation/mariadb-rds (AWS RDS) | define MultiAZ: true no AWS::RDS::DBInstance | aprovisiona uma única instância, pelo que N acima de 0 interrompe o build |
compose/mariadb (contentor de desenvolvimento local) | executa um único servidor, pelo que o build é interrompido indicando a chave | executa um único servidor, pelo que N acima de 0 interrompe o build |
O vocabulário de mecanismo (infra.primary.replicas) lê-se naturalmente para um fornecedor (os pods Kubernetes são réplicas de um StatefulSet) e como erro de categoria nos restantes — o RDS não tem o conceito de «réplicas» no primário, o CloudFormation espelha o RDS, o Compose não tem qualquer abstração de réplicas horizontais. O vocabulário de intenção traduz-se: todos os fornecedores têm algum conceito de «tornar esta base de dados altamente disponível» e algum conceito de «quero N cópias só de leitura», e a Recipe transporta a tradução por fornecedor. Onde uma realização não tem esse mecanismo, a 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 as réplicas de leitura.
infra.ha.read_replicas: 0 é a predefinição; com ambas as chaves nas predefiniçõ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 anfitrião Docker local, pelo que infra.ha.enabled: true ou um infra.ha.read_replicas diferente de zero interrompe o build indicando a chave, e a mensagem remete para helm/mariadb-cluster, que proporciona comutação por falha e réplicas de leitura.
O pilar provides
provides é a API pública criada pela Recipe — os valores que a Recipe resolvida de um Component fornece aos chamadores a jusante através da sua superfície .context.uses.<alias>.provides.<provided-name> (ou, quando o chamador declara uma lista de permissões inject: na aresta, através do seu canal .context.inject). O esquema do Component declara a forma (nomes das chaves e tipos); o bloco provides: da Recipe associada fornece os valores. O Programador que cria um Aggregate vê a forma de provides na página do Component como o contrato em que os chamadores podem confiar; o autor da Recipe cumpre o contrato para a implementação específica que encapsula.
O cumprimento é imposto como uma Loud Guardrail: uma Recipe associada tem de produzir todas as chaves provides que o seu Component declara. Se a Recipe associada omitir uma chave declarada, o build é interrompido e indica a chave em falta, em vez de não entregar silenciosamente nada aos chamadores que a referenciam. É permitido produzir chaves adicionais além do conjunto declarado. Só é verificada a presença das chaves — os valores produzidos são strings opacas que o compilador encaminha, pelo que os seus tipos declarados continuam a ser um contrato que os chamadores leem, e não um valor que o compilador valida.
# Component schema declares the provides contract:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-serverspec: 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/v1beta1kind: Recipemetadata: name: mariadb-bitnami version: 1.0.0spec: 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 de avaliação provides-depois-inject. O compilador avalia os templates provides: na avaliação de provides contra o contexto de template autónomo (.context.instance_id, .context.rendered_name quando o fornecedor do nó indica um, .values, .infra e os locals: resolvidos da Recipe no mesmo nó) — nenhum estado do chamador é visível. Os locals do nó resolvem-se no preâmbulo dessa fase, antes dos seus provides, o que permite a um template provides: ler .locals. Na hidratação de inject, que é executada a seguir, o compilador percorre as arestas uses: e resolve o .context.uses.<alias>.provides.<provided-name> de cada chamador contra os valores de provides resolvidos. Separar as duas 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 fornecedor ainda não resolvido até à execução da hidratação de inject.
Evolução do contrato. Mudar o nome ou remover um campo de provides é uma alteração incompatível para todos os chamadores que dependem do nome antigo. A metadata.version do Component (e a declaração implements: da Recipe) transporta o sinal de evolução do contrato; os chamadores a jusante fixados numa versão major específica veem uma forma de provides estável.
Ensino do lado da Recipe. Para a gramática de criação de templates provides:, a matriz de disponibilidade por template e exemplos práticos de encaminhamento entre namespaces e entre regiões, consulte entities/recipe.md «O bloco provides:» e architecture/06-data-taxonomy-and-composition.md §3.
Mandatos de presença: features.aggrega.ai/requiredType.<label>
Um Component pode declarar que todas as suas instâncias têm de transportar uma anexação de um determinado tipo de Feature. Isto é um mandato de presença, e é criado como uma anotação repetível nos próprios metadados do Component:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: 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-compliancespec: schema: values: processor_endpoint: { type: string, required: true }A chave é o prefixo features.aggrega.ai/requiredType. seguido de uma etiqueta à sua escolha; o valor é o URI do tipo de Feature que pelo menos uma anexação tem de transportar. A etiqueta dá nome ao requisito no diagnóstico que um mandato não cumprido produz — audit e compliance acima — e essa é toda a sua função. As chaves com etiqueta são a forma como um Component declara mais do que um mandato de uma vez: as anotações são um mapa plano de strings e não podem conter uma chave duplicada.
O compilador avalia cada mandato contra o conjunto final de anexações da instância, depois de a cascata do 5-Tier Onion Model ter integrado todos os âmbitos: os blocos features: ao nível do componente e ao nível do subsistema do Aggregate, os blocos features: ao nível da fronteira e ao nível do componente da Release, e as anexações produzidas pela expansão orientada por anotações. Qualquer um deles satisfaz o mandato — a regra testa o que está presente, nunca como lá chegou. Assim, um Component cujo mandato só é cumprido porque um operador definiu uma anotação de monitorização na Release passa exatamente como um cujo programador anexou a Feature à mão.
Um mandato que nenhuma anexação satisfaz interrompe o build com um diagnóstico que indica a instância do componente, a etiqueta do requisito e o tipo exigido. Um valor de anotação é uma string opaca, pelo que nada valida a sua forma antes de o compilador a ler; um valor que não seja um URI de tipo de Feature, ou uma chave sem etiqueta após o prefixo, interrompe portanto o build com um diagnóstico separado a indicar que a declaração está malformada. Os dois são deliberadamente distintos: uma declaração defeituosa corrige-se na entidade do catálogo, enquanto um requisito não cumprido se resolve anexando a Feature — e um erro de escrita nunca deve ser lido como um requisito satisfeito.
Ambos os diagnósticos estão documentados em errors/fatal-halts.md «Required feature not attached (Funcionalidade exigida não anexada)».
Um mandato não é um slot. As duas superfícies respondem a perguntas diferentes e a diferença não é cosmética:
slot de featuresSchema | mandato de presença | |
|---|---|---|
| Declara | um ponto de ligação com nome | uma restrição sobre o que tem de estar presente |
| O nome é desreferenciável | sim — from: <slot> e .features.<slot>.provides.* | não — a etiqueta dá nome ao requisito, nada mais |
| Cardinalidade | exatamente um preenchimento por slot | pelo menos uma anexação do tipo |
| Restringe o preenchimento | selector, inject, sensitive | nada além do tipo |
| Satisfeito por uma anexação livre | não — um slot é preenchido pelo nome | sim — em qualquer âmbito, sob qualquer nome |
| Quando a exigência não é cumprida | interrompe quando required: true e nada associa o nome do slot | interrompe quando nenhuma anexação transporta o tipo |
Ambas as exigências são verificadas contra a mesma entrada — o conjunto final de anexações da instância — e ambas interrompem o build com o seu próprio diagnóstico, porque lhe fazem perguntas diferentes: se um ponto de ligação com nome está associado, versus se alguma anexação transporta um tipo com nome. Nenhuma responde pela outra.
Recorra a um slot quando a Recipe precisa de ler o que foi anexado. Recorra a um mandato quando o contrato do Component exige que uma capacidade esteja presente e não importa que instância a fornece. Um Component de processamento de pagamentos que exige core/audit-logging obtém registo de auditoria em todas as implementações, quer o programador se tenha lembrado ou não de o anexar; um Component em conformidade com PCI que exige core/pci-compliance não pode ser entregue sem a Feature de conformidade anexada algures na implementação.
Herança. Um mandato declarado num Component base é herdado por todo o Component que o extends:, porque as anotações de metadados se fundem ao longo da cadeia de extends, prevalecendo o filho por chave. Um filho pode portanto redirecionar um mandato herdado voltando a declarar a mesma etiqueta com um tipo diferente, ou acrescentar mandatos próprios sob novas etiquetas; não pode eliminar um que a base declarou.
Sockets de topologia: usesSchema
Um Component pode declarar sockets topológicos através de um bloco usesSchema: — um mapa YAML declarativo paralelo a featuresSchema. Cada entrada indica um socket através do qual o Component aceita dependências entre componentes e determina que formas de Component o programador pode ligar ao socket. O compilador gera automaticamente regras de validação JSON Schema 2020-12 a partir dos sockets declarados e unifica-as com o schema: do Component durante a resolução do Component; os programadores não criam à mão um pilar uses: dentro de schema:, porque a estrutura vem de usesSchema.
# Component declares the sockets it accepts:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/ai-agent/orchestrator version: 1.0.0 labels: component.aggrega.ai/type: serverspec: 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 ligação — um socket aceita um ou vários destinos. Os exemplos acima ligam cada socket a um único destino, mas um socket pode expandir-se para vários. Um valor de socket é criado numa 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 corresponde sempre a um objeto de entrada, nunca a um nome de destino simples: databases: { primary: orders-db } é rejeitado no carregamento, tal como um objeto de entrada que omita target:. Para ligar um único destino sem ter de inventar um alias, recorra à forma compacta — primary_datastore: [vector-db-instance] — que indica o destino uma vez e deriva dele o alias.
Cada entrada — elemento de lista ou alias de mapa — torna-se uma aresta, preservada pela ordem de criação. O selector: do socket aplica-se a todos os destinos ligados através dele (cada aresta é verificada quanto ao tipo de forma independente durante a análise estática), e required: true significa que tem de ser ligado pelo menos um destino.
Semântica dos campos:
| Campo | Tipo | Predefinição | Significado |
|---|---|---|---|
required | bool | false | Quando true, o programador tem de ligar pelo menos uma dependência a este socket. Quando false, o socket é opcional. |
selector | string | — | Um seletor de etiquetas, na gramática que a appliesTo da Feature usa, que o destino de todas as arestas ligadas através deste socket tem de satisfazer. É lido como a string aqui escrita e avaliado contra as etiquetas do destino durante a análise estática: um destino cujas etiquetas não o satisfaçam interrompe o build, tal como um seletor que a gramática recusa, indicando o requisito que não conseguiu ler. Um seletor vazio não impõe qualquer restrição ao destino. |
inject | string[] | — | Lista de permissões dos mecanismos de entrega de inject permitidos (paralela a featuresSchema[].inject). Ausente, ou [] (vazia), significa caixa negra — não é permitido nenhum bloco inject: na entrada uses: do programador; a Recipe controla a entrega. [env, file, arg] (não vazia) significa transparente — o programador pode ditar que mecanismo entrega os valores provides da dependência. Imposto: consulte «Onde é imposta a lista de permissões inject de um socket» abaixo. |
valueSchema | objeto | — | Contrato opcional por aresta para os values criados pelo programador numa aresta ligada através deste socket (criados no Aggregate). JSON Schema 2020-12 nas mesmas formas de criação que schema:. A omissão significa que o socket não declara nenhum contrato de values. |
infraSchema | objeto | — | Contrato opcional por aresta para o infra criado pelo operador numa aresta ligada através deste socket (criado na Release). As mesmas formas de criação que valueSchema. A omissão significa que o socket não declara nenhum contrato de infra. |
featuresSchema | mapa | — | Os slots de anexação que cada ligação feita através deste socket pode preencher, indexados pelo nome do slot, aceitando cada slot as chaves que um slot ao nível do Component aceita. A omissão significa que uma ligação através deste socket não transporta nenhuma anexação. Consulte «Slots que cada ligação preenche» abaixo. |
Onde é imposta a lista de permissões inject de um socket. A lista de permissões é a declaração do socket sobre se um consumidor pode de todo escolher a forma de entrega e, em caso afirmativo, quais as formas — por isso é verificada contra todas as arestas uses: ligadas através do socket, assim que a aresta e a declaração do socket estejam ambas disponíveis. Duas recusas decorrem de uma única regra, e ambas interrompem o build:
- Uma aresta que dita um mecanismo que a lista de permissões não inclui interrompe o build, indicando o socket, o mecanismo infrator e o que o socket permite. Todos os mecanismos infratores na aresta são comunicados em conjunto.
- Uma aresta que dita qualquer entrega através de um socket cuja lista de permissões está ausente ou vazia também interrompe o build. É a declaração de caixa negra a cumprir a sua função: diz «a Recipe entrega isto internamente; não dite a entrega», e uma lista de permissões vazia não permite nenhuma, em vez de permitir todas.
O socket é lido na entidade que o declarou, que nem sempre é o componente de que a aresta parte: uma aresta criada no uses: de uma anexação de Feature é resolvida contra o usesSchema da Feature anexada, e todas as outras arestas — criadas no Aggregate, ligadas a partir da Release ou alcançadas através de um subagregado — contra o do Component consumidor. Um socket herdado através de extends é lido exatamente como um que a entidade criou ela própria.
Uma aresta que não dita nada não é afetada por nenhuma das recusas, independentemente do que o socket declare: ler os valores de uma dependência a partir de .context.uses.<alias>.provides.<name> na Recipe consumidora não precisa de nenhum bloco inject: e está sempre disponível. Consulte errors/fatal-halts.md para ambos os diagnósticos.
Contratos de ligação por aresta — valueSchema e infraSchema. Além de determinar que Components podem ser ligados a um socket, um socket pode declarar que configuração cada ligação transporta. Dois esquemas opcionais por socket validam a configuração com âmbito de ligação em todas as arestas ligadas através do socket:
valueSchemaé o contrato para o blocovaluescriado pelo programador numa arestauses— ajustes por ligação que o programador exprime no Aggregate (por exemplo, o tamanho de um pool de ligações ou um modo de cliente).infraSchemaé o contrato para o blocoinfracriado pelo operador numa arestauses— dimensionamento operacional por ligação que o operador exprime 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 SchemaLibrary. São contratos por aresta, validados de forma independente contra a configuração de cada aresta; não são compostos no próprio esquema values do Component consumidor. Um socket que omite um esquema por aresta para um pilar não declara nenhum contrato nesse pilar, e qualquer configuração criada para esse pilar não é validada. A configuração por aresta é validada de forma fechada, e a validação tem em conta os valores predefinidos em ambos os pilares: uma chave a que o esquema atribui um default: conta como fornecida mesmo quando o autor a omite.
Um default: declarado também se materializa, em ambos os pilares. Uma chave que o autor omite chega ao contexto de renderização da Recipe consumidora com o seu valor predefinido declarado, exatamente como acontece com uma chave value ou infra de componente omitida — pelo que declarar o valor predefinido no socket é suficiente, e o template da Recipe não precisa de nenhuma expressão de recurso para ela. Um valor criado prevalece sempre sobre o valor predefinido declarado, e preenche apenas a chave que fornece: uma aresta que cria uma chave do contrato de um socket continua a receber os valores predefinidos declarados para as outras chaves desse contrato. Os valores predefinidos ligam-se às arestas, pelo que um socket não ligado 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. A criação prevalece por chave, dentro do seu próprio pilar: um Aggregate que define pool_size: 42 renderiza 42, enquanto tls_mode continua a ser preenchido com require, e uma Release que define storage_class: gp3 renderiza gp3 sem afetar nenhuma das chaves do programador.
Uma Recipe para o Component consumidor lê a configuração por aresta resolvida a partir do canal de topologia enriquecido em .context.uses.<alias>.values.<key> e .context.uses.<alias>.infra.<key> — consulte vocabulary/topology-triad.md.
Slots que cada ligação preenche — o featuresSchema de um socket. Um socket também pode declarar slots de anexação, e então cada ligação feita através dele pode transportar a sua própria anexação em cada um deles: um gateway que alcança vários modelos tem uma credencial diferente para cada um, porque a credencial está na ligaçã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 ligação preenche um slot transportando uma anexação sob o nome do slot nas suas próprias features: — na entrada de ligação do Aggregate (Aggregate) ou na da Release (Release) — e a anexação torna-se uma das anexações do componente consumidor, com o nome <alias>.<slot>.
O que a declaração faz, dito com exatidão:
- Os nomes dos slots são um conjunto fechado. Ao contrário do próprio
featuresSchemado Component, que admite uma anexação livre sob qualquer nome, os slots de um socket são os únicos nomes que uma ligação através dele pode transportar: qualquer outro nome interrompe o build quando este é carregado, e um socket que não declarafeaturesSchemanão admite nenhuma anexação nas suas ligações. Um socket ad hoc — um que esteusesSchemanão declara — não declara slots, pelo que as suas ligações também não transportam nenhuma. Cada ligação preenche ela própria os seus slots: uma anexação num âmbito mais amplo nunca passa em cascata para uma ligação, e uma chave de Release que escreva o nome composto da anexação de uma ligação interrompe o build. - As outras chaves vinculam cada ligação ao slot. Um slot aqui aceita as mesmas chaves que um slot ao nível do Component —
required,selector,inject,sensitive,description— e cada ligação é vinculada a elas individualmente.selectoré comparado com as etiquetas da Feature com que uma ligação preenche o slot, e um preenchimento que não admita interrompe o build, posicionado na entrada dessa ligação no documento que escreveu o preenchimento.required: trueé devido por todas as ligações feitas através do socket: uma ligação que deixe o slot vazio interrompe o build, indicando essa ligação, enquanto uma ligação ao lado que preencha o slot passa.sensitiveé lido exatamente como num slot ao nível do Component: a anexação que preenche o slot é marcada como sensível no grafo de build e emaggrega inspect. Numa ligação, tal como num componente, quais dos valores de uma anexação são retidos como sensíveis é decidido apenas pelo próprio esquema da Feature anexada.injectvincula a entrada de Workload que entrega o material do slot: a anexação de uma ligação não transporta nenhum blocoinject:próprio — nenhum dos documentos admite um numa entrada de ligação — pelo que um Workload o entrega indicando a ligação ao lado do slot, e essa entrada é vinculada à lista de permissões do slot do socket exatamente como uma entrada que indica um slot ao nível do Component é vinculada à desse slot.
O usesSchema de uma Feature não aceita featuresSchema: uma ligação que uma Feature estabelece não transporta anexações, e uma Feature que declare slots num socket é recusada quando é carregada. Uma credencial de que essa ligação precise é um slot no próprio featuresSchema da Feature.
Geração de esquemas a partir de usesSchema. O compilador gera um fragmento base de JSON Schema 2020-12 a partir dos sockets declarados e compõe-no com a declaração schema: do utilizador — o mesmo padrão que featuresSchema usa. O esquema gerado nunca toca o disco; existe apenas em memória durante a passagem de validação do Component. O mapa uses: do programador no Aggregate é validado contra o esquema fundido; o selector: por socket é avaliado contra as etiquetas do Component candidato durante a análise estática, como verificação de segurança de tipos entre nós.
Semântica do seletor — o mecanismo Split Schema. usesSchema[].selector: é o que faz com que a topologia do Aggrega seja mais do que passagem de strings sem tipo. Um socket que declara selector: "datastore.aggrega.ai/engine=vector" só aceita ligações a Components etiquetados com o par chave-valor correspondente; um agente que tente ligar o 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 etiquetas ao estilo do Kubernetes — requisitos combinados com E por vírgula sobre as formas =, !=, in (...), notin (...), chave simples e !key — a mesma gramática que a appliesTo da Feature usa; consulte vocabulary/modifier-system.md para a gramática e architecture/13-catalog-and-registry.md §2 «Seletores ao estilo do Kubernetes» para a semântica do motor. Um requisito fora dessas formas é recusado em vez de ser lido como outro seletor: um requisito vazio (uma vírgula no início, no fim ou duplicada), uma chave que contenha espaços em branco ou qualquer um de =, !, (, ) e a vírgula, ou um conjunto sem o parêntese de fecho interrompem todos os builds que liguem uma aresta através do socket, indicando o requisito. Assim, um socket destinado a excluir frontends escreve-se selector: "tier!=frontend"; "!tier=frontend" é recusado, porque ! indica uma chave de etiqueta e nada mais.
Sockets ad hoc — o que a declaração de um socket proporciona e o que um autor pode fazer sem ela. O autor de um Aggregate pode escrever uma entrada uses: no seu próprio componente sob um nome de socket que este usesSchema não declara, incluindo num Component que não declara nenhum usesSchema. A aresta é construída. O silêncio do catálogo sobre um socket significa que a ligação não foi prevista, não que é proibida, e o programador é dono da topologia da aplicação.
Aquilo de que um socket ad hoc abdica é precisamente o que um declarado oferece, porque tudo isso reside na entrada de usesSchema: nenhum selector, pelo que nada restringe o componente que a aresta pode alcançar e a verificação de segurança de tipos entre nós não tem nada para avaliar; nenhuma lista de permissões inject:; nenhum valueSchema por aresta, pelo que os values: por aresta não têm contrato contra o qual ser verificados nem valores predefinidos declarados para herdar. Abdica também de infraSchema, embora nada alcance esse contrato num socket desse tipo de qualquer forma: o infra por aresta é criado numa entrada de aresta da Release, e uma entrada da Release só pode indicar um socket que o Component consumidor declara. O que não muda é o que a aresta pode transportar: o from: de cada entrada inject tem ainda de indicar uma chave que o schema.provides do Component de destino declara, e o destino tem ainda de existir — ambos interrompem o build tal como num 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 negra, porque as duas parecem iguais e comportam-se de forma oposta. Uma aresta através de um socket ad hoc pode ditar a entrega livremente: não há lista de permissões fora da qual um mecanismo possa estar, e nenhuma entidade prometeu tratar os valores internamente. A recusa de caixa negra acima aplica-se a um socket que a entidade declarou e deixou sem uma lista de permissões inject: — essa omissão é uma afirmação sobre uma ligação que a entidade previu, e um socket ad hoc não faz tal afirmação.
A entrega segue o mesmo caminho, e o artefacto renderizado não regista qualquer 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 que o autor escolheu, alcançando a partir daí o artefacto renderizado. Há um único caminho de entrega e nada nele se ramifica consoante o socket tenha sido declarado. O que um socket declarado pode acrescentar é conteúdo — valores predefinidos por aresta que o seu valueSchema ou infraSchema preenche — pelo que, quando um socket declarado não transporta tal contrato, a mesma aresta é renderizada de forma idêntica sob qualquer dos tipos de socket. A declaração é um facto sobre a ligação, não uma entrada para o que é renderizado.
Os values: por aresta num socket ad hoc são aceites e chegam à Recipe consumidora em .context.uses.<alias>.values, sem validação: sem valueSchema contra o qual os medir, nenhuma chave é verificada e nenhuma é rejeitada. Isto não é exclusivo dos sockets ad hoc — um socket declarado que não cria nenhum contrato para o pilar trata a sua configuração por aresta da mesma forma. O que um socket ad hoc muda é que o contrato não pode ser acrescentado sem declarar o socket. .context.uses.<alias>.infra está vazio numa aresta desse tipo, porque a superfície que fornece infra por aresta não pode indicar um socket não declarado.
Cada aresta no grafo emitido regista qual dos dois tipos é, para que um consumidor nunca tenha de o inferir, e uma organização que queira que todas as ligações passem por um socket declarado pode exigi-lo como política de governação. Declarar o socket aqui continua a ser o melhor caminho e é o que o catálogo da biblioteca padrão faz: um socket declarado transporta um selector que restringe os componentes que a aresta pode alcançar, uma lista de permissões inject:, um contrato por aresta com os seus próprios valores predefinidos e uma descrição — uma afirmação revisível de uma ligação prevista, versionada com a entidade que a faz. A forma ad hoc é uma via de escape, não uma nova predefinição. Duas superfícies não estão deliberadamente abertas desta forma — o uses de uma anexação de Feature só pode indicar um socket que a Feature anexada declara, e o uses por aresta de uma Release só pode indicar um socket que o Component consumidor declara.
O exemplo prático examples/adhoc-uses-socket/ constrói ambos os tipos de aresta num único consumidor e mostra os dois valores entregues lado a lado na saída renderizada, juntamente com a interrupção que uma chave from: não declarada produz.
Os erros de escrita em nomes de sockets surgem como aviso, não como interrupção. Como um nome de socket não declarado é legal, um nome de socket mal escrito torna-se uma ligação ad hoc própria em vez de ligar o socket que o autor pretendia — e o build continua verde enquanto nada flui por ela. O compilador comunica um nome de socket que esteja a uma edição de distância de um nome que este usesSchema declara como um aviso que indica ambas as grafias — consulte errors/warnings.md «Uses-socket near-miss lint (lint de quase-correspondência de socket de uses)». O aviso nunca altera o veredicto do build; o compilador não controla o nome que um autor dá a um socket.
A relação entre usesSchema e featuresSchema. Ambas são tabelas declarativas e ambas transportam 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 governa as arestas entre componentes — o grafo de topologia — declarando que sockets transportam um contrato. featuresSchema governa os slots de anexação, e um slot é um ponto de ligação com nome, não uma enumeração: uma anexação sob um nome que nenhum slot declara é legal no próprio bloco do componente. (Os slots que um socket declara para as suas ligações são o único conjunto fechado, como indica «Slots que cada ligação preenche» acima.) As duas superfícies convergiram nesse ponto — a entrada uses: do próprio componente sob um nome de socket não declarado também é legal — mas continuam distintas: um slot não declarado é uma anexação livre num 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 compõem-se de forma independente.
Slots de anexação: featuresSchema
Um Component pode declarar slots de anexação através de um bloco featuresSchema. Cada slot indica um ponto de ligação no qual o Component espera que seja anexada uma Feature — uma palavra-passe de root, uma chave de API, um token de autenticação, uma associação de identidade — e restringe que Feature o pode associar e como pode ser entregue o material do preenchimento.
Esta secção trata dos próprios slots do Component. Os slots que um socket declara para cada ligação são, pelo contrário, um conjunto fechado — consulte «Slots que cada ligação preenche» em Sockets de topologia.
Declarar um slot não fecha a superfície de anexação. Um autor pode anexar uma Feature sob um nome que nenhum slot declara, e essa anexação é uma anexação livre: perfeitamente legal, simplesmente não associada a um slot declarado. Esta abertura é o que permite que uma única entidade do catálogo sirva duas formas de implementação diferentes sem um fork do catálogo:
- Por consumidor. Cada instância preenche o slot com a sua própria Feature, pelo que cada consumidor obtém a sua própria credencial renderizada.
- Partilhada. Nenhuma instância preenche o slot; em vez disso, uma credencial é anexada uma vez num âmbito mais amplo (um subsistema ou uma fronteira de Release) e passa em cascata para todos os componentes abaixo dele, pelo que todos os consumidores são preenchidos a partir dessa única declaração. O que é renderizado depende da realização: um Secret por consumidor, cada um com o mesmo material, numa realização que renderiza um Secret; nenhum numa que aponta todos os consumidores para um Secret que já existe.
O autor escolhe entre elas pelo que anexa. A entidade do catálogo é a mesma em ambos os casos.
Uma forma nessa superfície aberta interrompe o build: um preenchimento escrito no componente sob outro nome. Quando uma anexação escrita no próprio componente — no seu próprio bloco features: no Aggregate, ou na entrada da Release para esse componente — transporta um nome que nenhum slot declara, e a sua Feature satisfaz o selector de um slot que nada associa nesse componente depois de todos os âmbitos terem sido integrados, o build é interrompido. É essa a forma que um preenchimento destinado ao slot assume quando é escrito sob o nome errado: deixado como está, seria uma anexação livre enquanto o slot fica vazio, e um slot opcional deixado vazio produz um build verde e não entrega nada. A mensagem indica a anexação, o componente, a Feature e cada slot vazio em que essa Feature encaixa, e a solução é anexá-la sob o nome do slot. Aplica-se a qualquer Feature, não apenas a credenciais. Tudo o resto na superfície continua livre: uma anexação cuja Feature não encaixa em nenhum slot declarado, uma anexação extra depois de todos os slots em que encaixa estarem associados e uma anexação que o componente herda de um subsistema ou de uma fronteira de Release — pelo que a forma partilhada acima não é afetada. Um slot que não declara nenhum selector não diz nada sobre a Feature a que se destina, pelo que nenhuma anexação lhe fica vinculada desta forma. A interrupção está descrita em errors/fatal-halts.md em «An attachment written under another name fits a slot its component leaves empty (Uma anexação escrita sob outro nome encaixa num slot que o seu componente deixa vazio)».
As duas formas compõem-se, e a mais próxima prevalece. Um autor pode fazer ambas ao mesmo tempo: anexar uma Feature num âmbito mais amplo para que alcance todos os componentes nesse âmbito, e preencher o slot no único componente que precisa de algo diferente. O preenchimento com âmbito de componente prevalece — campo a campo, pelo que só precisa de voltar a indicar os campos que altera e os restantes continuam a vir da anexação mais ampla. Os componentes irmãos que não preencheram o slot mantêm a anexação mais ampla intacta. A regra de precedência completa, incluindo a forma como interage com anexações orientadas por anotações e com Aggregates compostos, está em vocabulary/labels-and-annotations.md «Precedência de anexações».
Definição do esquema 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:
| Campo | Tipo | Predefinição | Significado |
|---|---|---|---|
required | bool | false | Declara que o slot tem de acabar associado. O build é interrompido quando nada associa o nome do slot numa instância deste Component, o que é verificado contra o conjunto de anexações que a instância contém depois de toda a cascata de anexações — pelo que uma anexação declarada num âmbito do qual a instância herda satisfaz o slot exatamente como um preenchimento criado na própria instância. O diagnóstico indica o componente e o slot. |
inject | string[] | — | Lista de permissões dos mecanismos de entrega de inject permitidos. [] (vazia) significa caixa negra — a Recipe controla a entrega internamente e o material nunca é entregue à carga de trabalho. [env, file] significa transparente — o material do preenchimento pode ser entregue através dos mecanismos listados. A mesma semântica que usesSchema[].inject. |
description | string | — | Documentação para humanos, renderizada pelo IDE e pelo hub. |
selector | string | — | Seletor de etiquetas opcional ao estilo do Kubernetes que restringe que Feature pode preencher este slot — o análogo, para slots, do selector de um socket de usesSchema, com a mesma gramática e o mesmo motor nativo de correspondência de etiquetas. Avaliado contra as próprias etiquetas da Feature anexada durante a análise estática; um preenchimento cujas etiquetas não o satisfaçam interrompe o build, tal como um seletor que a gramática recusa, indicando o requisito que não conseguiu ler. Omita-o para não impor qualquer restrição ao preenchimento. |
sensitive | bool | false | Declara que aquilo que associa este slot trata material secreto. Uma afirmação sobre o ponto de ligação, não sobre um preenchimento em particular; consulte «Declarar um slot como sensível» abaixo. |
Um slot restringe que preenchimento o pode associar, não o que o preenchimento configura. Deliberadamente, não existe nenhum contrato values ou infra ao nível do slot: o próprio schema: da Feature anexada é dono desses pilares, pelo que cada contrato tem exatamente um lugar.
O selector do slot é a forma como um Component restringe que Feature pode preencher um slot — por exemplo, a uma Feature de credencial específica do fornecedor (feature.aggrega.ai/kind=secret, provider=helm) — sem indicar uma FeatureRecipe, exatamente como um seletor de socket de usesSchema restringe o destino de uma aresta de dependência. O compilador avalia o seletor contra as etiquetas da Feature anexada e nada mais: lê as etiquetas que o preenchimento transporta e indica se o seletor as admite. Que etiquetas faz sentido exigir é uma escolha de criação do catálogo, não uma regra que o compilador impõe.
Os erros de escrita em nomes de slots surgem como aviso, não como interrupção. Como um nome de anexação não declarado é legal, um nome de slot mal escrito torna-se uma anexação livre em vez de preencher o slot que o autor pretendia. O compilador comunica um nome de anexação que esteja a uma edição de distância de um nome de slot declarado como um aviso que indica ambas as grafias — consulte errors/warnings.md «Attachment-slot near-miss lint (lint de quase-correspondência de slot de anexação)». O aviso nunca altera o veredicto do build; o compilador não controla o nome que um autor dá a uma anexação. Um nome a uma edição de distância de um slot cujo selector a Feature da anexação satisfaz não gera nenhum aviso: quando esse slot acaba vazio, é a interrupção descrita acima que comunica a anexação, e quando outra coisa associa o slot, a anexação é uma anexação extra comum.
Declarar um slot como sensível
sensitive: true num slot exprime a exigência do próprio consumidor: aquilo que associa este ponto trata material secreto.
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env] description: "Optional database password credential."Esta é uma informação genuinamente diferente do sensitive: true de uma folha de esquema, não um duplicado por 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 deles é sensível: o nome de um Secret do Kubernetes é público, tal como a chave dentro dele. No entanto, o slot que essa credencial preenche trata indiscutivelmente material secreto. Uma folha diz este dado é material secreto; um slot diz este ponto de ligação trata material secreto; as duas afirmações dizem respeito a coisas diferentes e podem verificar-se de forma independente.
A consequência prática é que a exigência acompanha o ponto de ligação e não o preenchimento. Uma Feature que não declara nenhuma folha sensível — porque o motor de destino é dono da credencial e o autor não escreve nada — continua a associar um slot sensível como uma anexação sensível, porque o slot assim o disse. O inverso também se verifica: um preenchimento que declara uma folha sensível é uma anexação sensível mesmo quando associa um slot que não fez tal declaração, ou quando é uma anexação livre que não associa nenhum slot.
A declaração segue a cascata de anexações e não um bloco criado em particular. A exigência de um slot aplica-se ao preenchimento que acabar associado depois de todos os âmbitos terem sido integrados, pelo que um preenchimento ao nível do componente que substitui um mais amplo herda a exigência sem alterações.
sensitive num slot tem o mesmo limite que a palavra-chave ao nível da folha — anota, não cifra, não valida, não rejeita, não impõe um mecanismo de entrega nem altera um byte renderizado. A afirmaçã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 numa folha ou num slot: este dado, ou este ponto de ligação, trata material secreto. compliance.aggrega.ai/data-class é uma etiqueta graduada num nó inteiro — public, internal, restricted — que dá aos dados que um componente contém uma identidade de governação. Um é por dado e binário, o outro por nó e ordenado; nenhum substitui o outro, e uma entidade pode transportar ambos. A etiqueta é abordada em vocabulary/labels-and-annotations.md e architecture/08-credential-model.md «Governação de dados em torno das credenciais».
Projeção do esquema a partir de featuresSchema
Os slots declarados projetam-se num fragmento de JSON Schema 2020-12 que descreve a forma do bloco de anexações. Dois tipos de preenchimento são validados contra ele: o bloco de anexações de um componente fornecido por um módulo importado, assim que a composição que o importa é construída, e uma anexação declarada num âmbito mais amplo, contra o slot de cada componente que alcança. O bloco de anexações de um componente que o próprio Aggregate declara é medido, em vez disso, pelo esquema de documento do Aggregate e pela lista de permissões inject do slot (ver abaixo), e o fragmento tem uma forma tal que ambos chegam ao mesmo veredicto sobre qualquer preenchimento. A projeção nunca toca o disco; existe apenas em memória, e o schema: de um Component nunca precisa de criar à mão o pilar de anexaçõ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 allowlistAs duas profundidades são independentes. O objeto exterior é aberto, pelo que um slot declarado nunca proíbe as anexações que a entidade não enumerou. O próprio fragmento de cada slot declarado é fechado, pelo que um preenchimento que associe um slot declarado continua restringido à forma desse slot.
O fragmento descreve apenas a FORMA. Não contém nenhuma afirmação sobre que slots têm de estar associados, porque um slot marcado como required pode ser associado por uma anexação que chega em cascata de um âmbito mais amplo — o que deixa vazio o bloco que este fragmento descreve. O requisito é portanto verificado contra o conjunto de anexações com que um componente acaba e não contra o que um bloco declara, e as duas perguntas nunca se contradizem porque apenas uma delas é alguma vez feita ao bloco criado.
As chaves permitidas espelham as chaves que uma anexação pode transportar em qualquer lado, pelo que uma chave legal numa anexação livre continua legal num preenchimento de slot. Cada mecanismo de entrega da lista de permissões é uma lista de entradas de entrega — a mesma forma que inject: assume em todo o lado; o slot restringe que NOMES de mecanismos podem aparecer, não o aspeto de uma entrada.
Onde é imposta a lista de permissões inject
A lista de permissões vincula ambos os lados do slot, em duas etapas diferentes.
Contra o Workload da Recipe, na etapa de renderização: um Workload que referencia um slot através das entradas de anexação do seu contentor tem de indicar um slot que a entidade declara e tem de selecionar um mecanismo de entrega que a lista de permissões inject do slot permita; uma referência a um slot de caixa negra (inject: []), a um mecanismo fora da lista de permissões ou a um slot que a entidade nunca declarou interrompe o build. O diagnóstico indica a Recipe, o caminho do contentor e o slot infrator, e é classificado como falha do catálogo — foi a Recipe que errou.
Contra a própria anexação do Aggregate, quando as suas anexações são resolvidas e antes de qualquer renderização: um bloco inject: num preenchimento que associa um slot declarado só pode indicar mecanismos que a lista de permissões do slot permite, e um slot de caixa negra não permite nenhum — a sua lista de permissões vazia diz «a Recipe entrega isto internamente; não dite a entrega», e criar uma entrega para ele interrompe o build. O diagnóstico é posicionado na anexação e indica o slot e o mecanismo infrator, juntamente com os mecanismos que o slot permite, quando permite algum; é classificado como falha do programador, porque foi o Aggregate que errou. Um bloco inject: {} vazio não indica nenhum mecanismo, pelo que não dita nenhuma entrega e é aceite em todos os slots, incluindo um slot de caixa negra — seja num componente que o Aggregate declara, num fornecido por um módulo importado ou numa anexação declarada num âmbito mais amplo. Uma anexação livre — uma sob um nome que nenhum slot declara — não tem tal restrição, porque a lista de permissões pertence ao slot e não ao bloco.
O fluxo de ponta a ponta ao longo do pipeline de compilação — como uma anexação do Aggregate se liga a uma Feature de credencial (como core/secret-value) e depois a uma FeatureRecipe específica do fornecedor que entrega a credencial à carga de trabalho em execução — é trabalhado 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 extremidade guarda a chave do seu próprio lado, num slot que ela própria declara. Esta é uma convenção que o catálogo da biblioteca padrão segue; o compilador não impõe nada disto — verifica os slots de cada componente contra as próprias anexações desse componente, encaminha as suas strings e nunca compara o que um componente contém com o que outro contém.
- A chave que um chamador apresenta é do chamador. Fica num slot que o socket do chamador declara para cada ligação — consulte «Slots que cada ligação preenche» acima — pelo que um chamador que alcança vários destinos guarda uma chave para cada um. O socket
modeldecore/ai-agent/crewaideclara esse slot comocredential, e as suas Recipes entregam o que o preencher comoOPENAI_API_KEY. Os socketsmodelsdecore/gateway/litellm,core/gateway/kongecore/gateway/apisixtambém o declaram, e as suas Recipes entregam a chave de cada ligação numa variável própria, com o nome do alias da ligação, pelo que cada modelo que o gateway serve guarda uma chave própria. Uma chave que um Component declara, em vez disso, num slot próprio é uma única chave para todas as ligações que faz. - A chave que um servidor verifica é o próprio slot do servidor.
core/ai-model/vllm,core/ai-model/teiecore/ai-model/tgideclaram cada um umapi_keyopcional, e cada uma das suas Recipes entrega o que o preencher como a variável a partir da qual o servidor lê a sua chave. O modelo e o gateway LiteLLM declaramapi_keypara a chave a que o LiteLLM chama master key. - Nenhuma das extremidades vê as anexações da outra. Uma anexação numa ligação é uma das anexações do chamador e chega apenas à renderização do chamador, e a saída renderizada de um servidor é a mesma independentemente do que as ligações que o alcançam transportam. Um slot marcado como
requiredé devido pelo componente que o declara, nunca pelos componentes ligados a ele, e preencher o slot de uma extremidade não preenche nada na outra — pelo que declarar a chave em ambas as extremidades é o mínimo e não um duplicado. - Ambas as extremidades leem um único parâmetro, pelo 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 endsspec: 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-keyUm servidor que verifica uma única chave não consegue distinguir os seus chamadores: o vLLM, o TEI e o TGI verificam cada um uma única chave, pelo que todos os chamadores apresentam a mesma, por muitas ligações que alcancem o servidor. Se as duas extremidades referenciam um único segredo ou se cada uma guarda o seu depende de onde cada fornecedor resolve um segredo por referência, e o Manifest escolhe a realização de cada extremidade — o Modelo de credenciais trabalha ambos os casos.
Uma credencial que um componente guarda para si próprio — uma chave com que assina as suas próprias sessões, por exemplo — é um slot do seu próprio featuresSchema: como qualquer outro. Uma palavra-passe que apresenta a um armazenamento de dados que alcança através de um dos seus sockets é a chave do chamador acima, pelo que fica nessa ligação como credential: o socket backend de core/gateway/kong declara-a, e as suas Recipes de síntese de cargas de trabalho entregam-na como KONG_PG_PASSWORD, e o socket cache_store de core/gateway/litellm declara-a para a palavra-passe que a sua cache semântica apresenta ao armazenamento, entregue como REDIS_PASSWORD. Quando uma ligação apresenta um par — um identificador de chave de acesso e o 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 spec.inject: de nível superior que define uma lista de permissões de mecanismos de entrega de autoinjeção. Quando presente, os programadores podem usar um bloco inject: ao nível do componente no Aggregate para injetar as chaves values: ou provides: do próprio Component diretamente no seu próprio canal de entrega (as variáveis de ambiente, os ficheiros montados ou os argumentos de processo do seu contentor). Quando spec.inject: está ausente ou vazio, a autoinjeção ao nível do componente é proibida — a Recipe controla toda a ligação interna, de acordo com o padrão Black-Box que usesSchema[].inject: [] e featuresSchema[].inject: [] aplicam, respetivamente, à entrega entre componentes e à entrega de credenciais.
# Component declares its self-inject allowlist:apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/web-server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: 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_endpointCada 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 ser executada a resolução da autoinjeção, e .values não existe nesse momento; o escape repõe {{ para que a resolução da autoinjeção o avalie. Consulte Texto que contém as suas próprias chavetas duplas.
Semântica dos campos. spec.inject: é um array de nomes de mecanismos. Estão definidos três valores:
env— variáveis de ambiente no contentor.file— caminhos de ficheiros montados.arg— argumentos da linha de comandos do processo.
A semântica espelha exatamente usesSchema[].inject e featuresSchema[].inject — o mesmo vocabulário, o mesmo padrão Black-Box quando omitido, a mesma forma de criação do lado do Aggregate. A diferença é a origem: usesSchema[].inject determina como os provides de uma dependência entre componentes fluem para o canal de entrega do consumidor; featuresSchema[].inject determina como uma credencial chega a um contentor; spec.inject determina como os próprios values e provides do Component chegam ao próprio contentor do Component.
Disciplina de criação. Um Component core/web-server que declara spec.inject: [env, file] adere à entrega transparente — o autor do Aggregate dita que nomes de variáveis de ambiente transportam que valores. Um Component que declara spec.inject: [] (ou omite o campo) mantém a entrega opaca — o valuesMapping: da Recipe decide que campos fluem para que variáveis do contentor, e o programador não pode substituí-lo no Aggregate. O padrão Black-Box adequa-se a Components de contrato estável (um Component core/postgres-db cuja Recipe sabe como ligar a palavra-passe da base de dados a uma variável de ambiente POSTGRES_PASSWORD); o padrão transparente adequa-se a Components em que a intenção do programador indica legitimamente detalhes de entrega (um core/web-server cuja aplicação lê LOG_LEVEL a partir de um nome de variável não padrão que o programador pretende personalizar).
Modos de erro. O Aggregate de um programador que usa um bloco inject: num Component cujo spec.inject: está em falta ou vazio interrompe o build no carregamento do espaço de trabalho («Self-inject on a component without an allowlist» (Autoinjeção num componente sem lista de permissões)). Um bloco inject: que usa um mecanismo que não está na lista de permissões interrompe o build com a mesma condição, indicando o mecanismo e os que a lista de permissões admite («Self-inject mechanism not in the component’s allowlist» (Mecanismo de autoinjeção que não está na lista de permissões do componente)). Uma colisão de chaves de entrega entre a autoinjeção, a injeção entre componentes e a injeção de credenciais também interrompe o build («Duplicate delivery key across inject sources» (Chave de entrega duplicada entre origens de injeção)). Consulte errors/fatal-halts.md para a forma da mensagem de cada erro.
Criação no catálogo: estender Components base
Os Arquitetos de Plataforma usam a palavra-chave extends para sobrepor interfaces especializadas a bases empresariais ou da comunidade. Estender compõe a estrutura e herda os pilares de dados na íntegra. O compilador percorre a cadeia a partir da base; as duas metades comportam-se de forma diferente, e a diferença é todo o modelo de criação.
O que a extensão compõe. Estas superfícies fundem-se ao longo da cadeia, prevalecendo o Component que estende por chave e concatenando-se as listas a começar pela base, sem duplicados:
| Superfície | Como se compõe |
|---|---|
metadata.labels | fundidas por chave; o valor do Component que estende prevalece numa chave partilhada |
metadata.annotations | fundidas por chave, com a mesma precedência — e é por isso que o mandato de presença de uma base chega a todo o Component que a estende |
spec.featuresSchema | união dos slots de anexação; um slot que o Component que estende volta a declarar substitui a entrada da base com esse nome |
spec.usesSchema | união dos sockets de topologia, com a mesma regra de substituição por nome |
spec.inject | as duas listas de permissões de autoinjeção concatenam-se, primeiro as entradas da base, sem duplicados |
spec.assertions | as regras com nome acumulam-se, primeiro as regras da base — e esta é a única superfície que não admite substituição por nome; consulte «A herança de asserções é aditiva» abaixo |
Um socket que o Component que estende acrescenta pode transportar o seu próprio valueSchema e infraSchema por aresta; esses são contratos nas arestas desse socket, não acréscimos aos pilares do próprio Component.
O resto de metadata: fica com o documento que o declara. labels e annotations são os únicos metadados que descem ao longo da cadeia. name, version, description, maintainers, license, repository, home e keywords são do próprio Component que estende, lidos exatamente como este os criou — um Component que omite description: não tem nenhuma, em vez de usar a da sua base. A identidade e a proveniência pertencem ao documento que se está a ler, pelo que um invólucro nunca é confundido com aquilo que envolve.
O que a extensão herda na íntegra. Os três pilares de dados — values, infra, provides — não são compostos. Um Component que estende não cria conteúdo de pilares: escreve o marcador literal schema: inherited e recebe o bloco schema: da sua base exatamente como a base o criou. Ao longo de uma cadeia de qualquer profundidade, cada Component nela transporta o bloco da raiz da cadeia sem alterações, pelo que aggrega inspect --resolved numa folha mostra os mesmos pilares que a raiz.
O esquema publicado do Component determina qual dos três resultados possíveis é legal 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 sobschema:é rejeitado. O contrato do Component é o da sua base; um segundo contrato divergente não tem onde residir.extends:comschema:totalmente omitido é rejeitado. Uma omissão deixaria um leitor incapaz de distinguir um bloco de pilares herdado de um esquecido.schema: inheritedsemextends:é rejeitado. O marcador indica de onde vêm os pilares, e este Component não tem nenhuma base de onde os obter.
Um Component que estende não pode remodelar o conjunto de chaves. Não declara chaves de pilares, pelo que não pode ocultar, eliminar nem alterar o tipo de uma chave que a sua base declara, e não acrescenta nenhuma própria. Uma nova chave de pilar pertence ao Component cujo contrato é dono dela. O que quer que a base exponha, tudo o que a estende expõe de forma idêntica.
Uma especialização torna-se mais restritiva através de assertions:. Quando uma especialização tem de admitir menos do que os pilares da sua base — um intervalo numérico mais estreito, um subconjunto de um enum: herdado — di-lo no seu próprio bloco assertions:: uma regra aí rejeita um valor que o esquema herdado aceita. É essa a superfície onde reside o aumento de restrições; consulte «O bloco assertions:» abaixo.
Esses dois últimos parágrafos são uma única regra, e cada metade sozinha induz em erro: o estreitamento do conjunto de chaves é impossível, o aumento de restrições é possível. Considerando apenas o primeiro, conclui-se que uma especialização não pode restringir nada; considerando apenas o segundo, conclui-se que pode remodelar o contrato. Nenhuma das conclusões é verdadeira — o conjunto de chaves é fixado pela base, e os valores admitidos dentro dele podem ser estreitados por predicado.
A herança de asserções é aditiva, e a acumulação começa pela raiz. Uma instância de um Component que estende é verificada contra todas as regras que a sua cadeia declara, bem como contra as regras que o próprio Component declara, sendo as herdadas avaliadas primeiro. Ao longo de uma cadeia de qualquer profundidade, as regras acumulam-se a partir da raiz da cadeia para baixo, pelo que, quando uma instância falharia mais do que uma regra, a comunicada é a declarada mais acima na cadeia — o contrato mais fundamental responde primeiro.
Como a herança acrescenta 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 contra o catálogo, com um diagnóstico que indica ambos os Components e o nome partilhado. A verificação precisa do Component base disponível, pelo que é comunicada quando o catálogo é validado ou quando um build resolve a cadeia — validar o documento que estende isoladamente não a consegue detetar. O nome da regra é um identificador estável, pelo que nem eliminar a regra da base nem mudar-lhe o nome silenciosamente é uma opção, e a correção é uma mudança de nome no Component que estende. Repetir uma regra herdada byte a byte sob o seu próprio nome é aceite como a operação nula que é.
aggrega pull obtém a base. Uma base é uma dependência de cada Release que alcança um Component que a estende, quer algo mais a indique quer não. aggrega pull segue cada extends: até ao fim da cadeia, obtém do registry uma base que nenhum diretório de catálogo contém e regista cada base no lockfile da Release, referenciada a partir do spec.extends do Component que a indica; um build lê a base a partir daí. Assim, um Manifest mapeia o tipo próprio de um wrapper e nada mais — a base só precisa de uma linha de mapeamento própria onde um Aggregate também declara uma instância da base. Um aggrega validate do catálogo completo lê uma base da mesma forma, pelo que uma base publicada num registry é aí recusada, indicando aggrega pull, até que um pull a tenha obtido.
Consulte architecture/13-catalog-and-registry.md §3 para os formatos de conteúdo dos esquemas.
Exemplo A: o Component base (a base empresarial) O Arquiteto de Plataforma define um servidor empresarial fundamental. Esta base define a etiqueta obrigatória de primitiva operacional de cloud e estabelece as restrições de segurança no esquema. Como o bloco de pilares é herdado sem alterações, cada restrição aqui chega a cada Component que estende exatamente como foi criada.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: 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 (especializar a base) Um gateway é especializado a partir dessa base. Recebe os pilares da base na íntegra, acrescenta estrutura própria — uma etiqueta, um mecanismo de autoinjeção, um socket de topologia com um slot de anexação — e torna mais restritivo o timeout herdado através de uma asserção. Não repete a regra audit-window-is-observable da base: essa regra é herdada e é avaliada primeiro, pelo que uma instância deste gateway tem de satisfazer ambos os limites — pelo menos 100 e no máximo 2000.
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: 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 labelsspec: 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 contra um chart Helm físico, consulte o Exemplo C (kong-gateway) em entities/recipe.
O bloco assertions:
Component.spec.assertions: é um mapa opcional de regras com nome que exprimem invariantes arquiteturais do contrato do Component — regras entre campos que a criação do programador tem de satisfazer, independentemente da Recipe que se associa ao Component. Cada chave é um identificador de regra que aparece na mensagem de falha; cada valor é um corpo de template Go. O compilador avalia-as por instância depois da validação do esquema e antes da associação da Recipe, pela ordem em que estão escritas, e a primeira regra que falha interrompe o build com a mensagem de erro dessa regra, segundo o contrato das 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 que se associa (chart da 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 torna mais restritivo. Um Component que extends: uma base herda literalmente o bloco de pilares da base e não declara conteúdo de pilares próprio, pelo que uma especialização que tenha de admitir menos do que o esquema herdado indica aqui a restrição como um predicado e não como uma folha de esquema estreitada — uma regra que rejeita um valor que os pilares herdados aceitam. O par trabalhado e o comportamento completo de herança estão em «Criação no catálogo: estender Components base» acima: as regras acumulam-se ao longo da cadeia a começar pela raiz, e reutilizar o nome de uma regra herdada para uma regra diferente é rejeitado, em vez de lhe ser permitido substituí-la.
O compilador não verifica se duas regras podem ser ambas satisfeitas. Uma regra é um predicado de template, não uma restrição sobre a qual o compilador raciocine, pelo que um par de regras que nenhum valor consegue satisfazer em simultâneo — uma base que exige pelo menos 100 e uma especialização que exige no máximo 50 — não produz nenhum aviso quando o catálogo é carregado. Surge da forma habitual: é criada uma instância, 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 comunicada antecipadamente; verifique o aumento de restrições de uma especialização face ao que a sua base já exige.
Use assertions: para regras genuinamente entre campos. As restrições por campo (intervalo, padrão, enum) pertencem às palavras-chave de schema:; os predicados personalizados por campo pertencem ao 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 criação completa — campos do contexto de template, a convenção de mensagens {{ fail }}, a fase de avaliação e exemplos práticos que abrangem os papéis de Component e de Recipe — consulte templates/assertions-block.md.