Manifest
O papel conceitual da entidade Manifest (Domínio 4 — a tabela de mapeamento que vincula interfaces abstratas a Recipes concretas) está descrito em architecture/04-entity-taxonomy.md. Esta página cobre a superfície de autoria do Manifest: como ele se posiciona ao lado da Release, o formato de mapeamento de URIs planos, a composição via extends, as regras de abreviação de URIs, os vínculos de Feature orientados por anotações e o prefixo aggrega.ai/ reservado pela plataforma.
Manifest vs. Release: separação de responsabilidades
O Manifest e a Release têm responsabilidades que não se sobrepõem:
- O Manifest dita qual Recipe realiza cada tipo do catálogo e, por meio do
spec.capabilitydessa Recipe, o provider (por exemplo, Helm, Helm-chart, Compose) que o renderiza. É a tabela de mapeamento — um registro por projeto, versionado no Git, de qual Recipe concreta implementa cada interface abstrata; as versões e os digests aos quais um build vincula essas Recipes são fixados separadamente, no lockfile de cada Release. - A Release dita o destino (por exemplo, a pasta de saída física para a geração de artefatos GitOps). É o roteador do deployment — uma descrição por ambiente de onde os artefatos compilados vão parar.
O schema da Release não tem nenhum campo provider em nenhum nível de aninhamento; o despacho do provider pertence exclusivamente ao Manifest.
O caminho de compilação. Quando um usuário executa aggrega build --release release.yaml, o compilador resolve os artefatos físicos combinando as duas fontes:
- Ler o destino. O compilador percorre as fronteiras da Release — por exemplo, a fronteira
ovh-cluster-3contém o componenteuser-db(tipo:core/postgres:1.0.0). - Percorrer o Manifest. Ele abre o Manifest para o qual a Release aponta por meio de seu campo
manifest:. - Busca em dois níveis. Ele verifica primeiro o nível
namepara"user-db". Se não encontrar, verifica o níveltypepara"core/postgres:1.0.0"(com versão) e depois"core/postgres"(sem versão). - Resolver a Recipe. O valor da entrada correspondente é um URI de Recipe; a Recipe que ele nomeia declara em
spec.capabilityqual provider a renderiza. - Geração da saída. O compilador agora conhece a pasta de destino (
dist/boundaries/ovh-cluster-3/), o provider (renderização Helm via Wasm) e o artefato (o código-fonte da Recipe). As fronteiras GitOps ahead-of-time são respeitadas de ponta a ponta.
Mapeamento plano de URI
O bloco mappings: do Manifest é um mapa plano de URI de tipo de componente para URI de Recipe (e de URI de tipo de funcionalidade para URI de FeatureRecipe). O mapeamento é agnóstico em relação à capacidade no nível do Manifest; a determinação da capacidade decorre do campo spec.capability de cada Recipe resolvida no momento da renderização, não da forma estrutural do Manifest. O bloco organiza os mapeamentos sob duas chaves de nível superior:
components.typemapeia um URI de tipo de componente para um URI de Recipe. Toda instância de componente do tipo declarado é resolvida para a Recipe especificada. O mapeamento é um para um por tipo de componente. Uma chave que não nomeia o tipo exato de uma instância ainda a alcança pela base do tipo, quando nenhuma chave nomeia esse tipo exato e nenhuma outra chave está escrita para a mesma base — assim, uma chave escrita sem versão (core/postgres), ou uma que nomeia outra versão (core/postgres:1.0.0), pode alcançar uma instância decore/postgres:2.0.0—, mas a Recipe que ela nomeia deve implementar a versão própria de cada uma dessas instâncias: uma instância decore/postgres:2.0.0alcançada dessa forma e mapeada para uma Recipe que declaraimplements: core/postgres:1.0.0interrompe o build. Mapeie essa instância com uma chave que nomeie sua versão (core/postgres:2.0.0) para uma Recipe que a implemente.features.typemapeia um URI de tipo de funcionalidade para um URI de FeatureRecipe. Toda vinculação de Feature do tipo declarado é resolvida para a FeatureRecipe especificada. As Features de credenciais (rotuladas comfeature.aggrega.ai/kind: secret) ficam no mesmo mapafeatures.typeque as Features operacionais — o modelo unificado de entidade Feature.
Cada bloco também aceita um nível name ao lado de type, que mapeia um nome de instância específico para um URI de Recipe (ou de FeatureRecipe). O nível de nome tem precedência sobre o nível de tipo: uma instância nomeada em components.name é resolvida para essa Recipe, enquanto todas as outras instâncias do mesmo tipo são resolvidas por meio de components.type. Isso expressa uma substituição por instância — duas instâncias de um mesmo tipo de componente podem ser implantadas por meio de duas Recipes diferentes (por exemplo, a maioria das instâncias de banco de dados usa a Recipe mapeada em massa, enquanto uma instância é fixada em uma implementação física diferente), sem fazer fork do tipo de componente nem duplicar o Manifest. A substituição se aplica de maneira uniforme: a instância nomeada tanto é renderizada pela Recipe de substituição quanto fixa sua origem a partir dela. features.name é o nível simétrico para as vinculações de Feature, indexado pelo nome próprio da vinculação — a chave sob a qual ela está escrita no features: de um componente —, nunca pelo nome do componente ao qual está vinculada. O exemplo de substituição de receita por instância percorre de ponta a ponta um caso mínimo com duas instâncias.
Uma vinculação que uma conexão carrega é indexada pelo nome que assume no componente consumidor: <alias>.<slot>, o alias sob o qual a conexão está escrita, um ponto e o slot que a vinculação preenche (veja a entrada de conexão do Aggregate). Assim, a credencial de uma conexão pode ser realizada de forma diferente de qualquer outra vinculação do seu tipo:
spec: mappings: features: type: core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0 name: # The credential the "gpt" connection carries in its "credential" slot. gpt.credential: helm/k8s-external-secret:1.0.0A entrada é fixada e verificada como qualquer outra entrada do nível de nome, como descreve o próximo parágrafo. A Feature que a vinculação nomeia também é fixada e verificada, exatamente como a Feature de uma vinculação escrita no próprio componente, sob a entrada de conexão que seu autor escreveu — veja O lockfile.
Uma chave name precisa nomear algo que o build contém. O nível é comparado pelo nome exato, então uma chave components.name que não é uma instância de componente no build, ou uma chave features.name que não é uma vinculação nele — na maioria das vezes o nome do componente em que uma vinculação está, escrito onde deveria estar o nome próprio da vinculação —, não seria consultada por nada, e as instâncias às quais se destinava seriam resolvidas silenciosamente pelo nível type. Em vez disso, o build é interrompido nessa chave, antes que qualquer coisa seja renderizada, nomeando o Manifest, a chave, os nomes desse tipo que o build contém e o nome que você provavelmente quis dizer — veja A Manifest name mapping names nothing in the build (Um mapeamento por nome do Manifest não nomeia nada no build).
Uma realização vinculada por nome é fixada e verificada como uma vinculada por tipo. O aggrega pull obtém cada Recipe e FeatureRecipe que qualquer um dos níveis vincula — de um diretório de catálogo, do cache ou de um registro — e registra cada uma no lockfile da Release com sua versão resolvida e seu digest de conteúdo, sob a entrada de mapeamento que a vincula: manifest.spec.mappings.components.name.<instance> para uma entrada do nível de nome, ao lado de manifest.spec.mappings.components.type.<type> para uma do nível de tipo. O aggrega build mantém cada uma delas presa à sua fixação. Um lockfile que não registra nenhuma linha para uma realização que o Manifest vincula interrompe o build por estar desatualizado, nomeando a realização e a entrada que a vincula; uma realização cujo conteúdo mudou desde o pull o interrompe da mesma forma, nomeando ambos os digests. Em ambos os casos, aggrega pull --release <release> registra a realização como ela está agora. Assim como uma entrada type, uma entrada name é fixada quer a Release declare ou não uma instância com esse nome, então uma entrada name que nomeia uma Recipe que nenhum catálogo ou registro contém interrompe o pull; uma entrada name que não nomeia nenhuma instância contida no build também é fixada e interrompe o build, como descreve o parágrafo anterior.
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: production-manifest version: 1.0.0spec: mappings: components: type: # Component-type → Recipe URI. A Recipe URI is at most two segments: an # optional leading capability, then the recipe name. The bare one-segment # form (last line) is the common case. core/datastore/postgres: helm/postgres:1.2.0 core/api-server: helm/api-helm:0.5.0 core/python-worker: standard-python-worker:2.0.0
features: type: # Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones. core/data-masking: helm/data-masking-litellm:1.0.0 core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0Determinação da capacidade no momento da renderização. A entrada do Manifest vincula um tipo de componente a um URI de Recipe. Um URI de Recipe tem no máximo dois segmentos — uma capacidade inicial opcional e depois o nome da receita — mais um :version opcional; o resolvedor divide apenas na primeira /, então uma referência com um terceiro segmento não nomeia nenhuma receita e interrompe a resolução. No momento da renderização, o resolvedor carrega a Recipe por meio de uma busca direta por URI no lockfile e no catálogo, e o campo spec.capability de cada Recipe determina o agrupamento de despacho por (caminho, capacidade). A forma estrutural do Manifest permanece plana, independentemente de quantos provedores o catálogo mais amplo suporte.
Busca direta por URI
O valor de mapeamento do Manifest é um URI de Recipe. O compilador resolve o URI diretamente no lockfile e no catálogo, retornando a Recipe correspondente. Ele não itera sobre as declarações spec.implements para encontrar uma Recipe que “implemente” um tipo de componente. Cada entrada do Manifest vincula o tipo de componente escrito pelo desenvolvedor a um URI de Recipe específico; a escolha é explícita e inequívoca no conteúdo do Manifest.
spec.implements é uma verificação de consistência sobre a tabela de mapeamentos. O valor spec.implements da Recipe resolvida DEVE corresponder à chave de tipo de componente do Manifest para essa entrada de mapeamento — ou a uma base que essa chave estende por extends, em qualquer profundidade da cadeia, já que uma Recipe escrita para uma base implementa tudo o que a estende. Um valor que não corresponda a nenhuma das duas produz um OPS_ERROR com um diagnóstico claro que nomeia a entrada do Manifest, a Recipe resolvida e o valor spec.implements conflitante. A verificação é disparada uma vez por entrada de mapeamento do Manifest, sobre o Manifest composto e antes que qualquer Recipe seja resolvida — estática, determinística e sem percorrer nada além da própria cadeia extends do tipo mapeado. Uma chave components.type que alcança uma instância de componente em uma versão que ela não nomeia é julgada mais uma vez para essa instância, da mesma forma, com o tipo próprio da instância, na versão com que o build a compila, no lugar da chave, como descreve Mapeamento plano de URI. Veja ../vocabulary/inheritance-and-interface.md para saber o que a Recipe de uma base poupa e não poupa a uma especialização.
Todo comando que lê as dependências de uma Release a executa, e cada um decide por si o que uma constatação significa: aggrega build e aggrega pull são interrompidos, já que ambos produzem algo que você usaria em seguida, enquanto aggrega validate e aggrega lint a relatam com o restante de suas constatações e saem com código diferente de zero, e o editor a publica como um diagnóstico entre os outros. aggrega lint é a exceção para o julgamento de uma instância: ele julga as entradas de mapeamento e não as instâncias que elas alcançam, então não a relata, enquanto aggrega build, aggrega pull e aggrega validate --release relatam. Veja ../errors/fatal-halts.md para o diagnóstico e como corrigi-lo.
A verificação de consistência é a única superfície de mapeamento que lê a cadeia extends. A seleção da Recipe continua exata na chave de mapeamento: um tipo de componente que estende uma base mapeada ainda precisa de sua própria entrada aqui, e não recebe nenhuma por herança.
spec.implements também sugere candidatas. Uma instância cujo tipo não tem mapeamento no Manifest interrompe o build com um OPS_ERROR que lista como candidatas para fixação as receitas cujo spec.implements é capaz de implementar esse tipo; o preenchimento automático do editor em um valor de mapeamento classifica essas mesmas receitas correspondentes primeiro. Ambas as superfícies leem spec.implements em relação ao próprio tipo solicitado, então uma receita que implementa uma das bases desse tipo não é oferecida como candidata, mesmo que o mapeamento fosse julgado consistente. spec.implements declara, portanto, o que uma receita pode implementar e orienta a escolha da pessoa — na verificação de consistência, no diagnóstico de mapeamento ausente e no preenchimento automático —, mas nunca resolve um build. O mapeamento do Manifest é a escolha explícita de implantação do usuário, fixada no lockfile para reprodutibilidade; o catálogo nunca escolhe uma implantação em nome do usuário.
Três formas para o segmento de versão do URI
Um URI de Recipe no Manifest pode trazer a versão em qualquer uma de três formas:
- Exata —
helm/postgres:1.2.0. O lockfile deve fixar exatamente esta versão; na primeira resolução do lockfile, o resolvedor fixa esta versão; se o catálogo ou o registro não contiver esta versão no momento da resolução, o carregamento do workspace é interrompido com um erro. - Intervalo —
helm/postgres:^1.2.0. Intervalo semver com a regra MVS padrão; na primeira resolução do lockfile, o resolvedor fixa a versão disponível mais alta que satisfaz o intervalo. - Sem versão —
helm/postgres. Sem sufixo:version; na primeira resolução do lockfile, o resolvedor fixa a versão mais recente disponível.
Os builds seguintes usam a versão fixada no lockfile, independentemente da forma digitada pelo usuário. Resolver novamente para uma versão mais recente exige uma ação explícita do usuário — aggrega pull --upgrade --release <release> <uri> resolve novamente uma única dependência mantendo todas as outras fixações, ou aggrega pull --upgrade --release <release> resolve novamente todas —; o lockfile é a fonte da verdade para os builds; a forma digitada pelo usuário é como o usuário expressa a restrição de versão no momento da escrita.
Referências qualificadas por capacidade
A identidade de uma Recipe no catálogo tem escopo de capacidade: duas receitas podem compartilhar um metadata.name e uma versão e declarar valores de spec.capability diferentes. A identidade no registro é recipe/{capability}/{name}:{version}, derivada do tipo da receita, do seu spec.capability sem nenhuma fixação de versão que ele traga, e do seu nome; a árvore do catálogo da biblioteca padrão espelha essa coordenada em recipe/{capability}/{name}/ por convenção. Um valor de mapeamento do Manifest nomeia a receita com qualquer uma das duas precisões:
- Simples —
mariadb:1.0.0. É resolvida quando exatamente uma receita no catálogo tem esse nome; a forma predominante na prática. - Qualificada por capacidade —
compose/mariadb:1.0.0. O segmento antes da primeira/nomeia ospec.capabilityda receita, sem a fixação de versão dele — uma fixação escrita na referência é recusada (E0095). Obrigatória quando mais de uma receita fornece o mesmo nome: uma referência simples que corresponda a duas receitas é ambígua e é interrompida de forma explícita na resolução, em vez de escolher uma silenciosamente.
Um URI de Recipe não tem outras posições. O resolvedor divide apenas na primeira /, então compose/mariadb nomeia a capacidade compose e a receita mariadb, e uma referência com três segmentos não corresponde a nenhuma receita em nenhuma das duas precisões.
As formas do segmento de versão acima se aplicam às duas variantes.
Entidades publicadas em registro nos mapeamentos
Uma entidade consumida de um registro, e não de um catálogo local, é referenciada exatamente pela mesma identidade que uma local usa: a referência não traz nenhum host de registro nem nenhum segmento de tipo de entidade. O resolvedor fornece ambos — o host a partir do registro padrão configurado no workspace, o segmento de tipo a partir de onde a referência está no esquema — conforme as regras de URIs abreviados sensíveis ao contexto abaixo. Quando nem um diretório de catálogo local nem o cache contém uma cópia, o aggrega pull — ou um build executado com --auto-pull — busca a entidade no local derivado, armazena-a em cache e fixa a versão resolvida e o digest de conteúdo no lockfile; os builds seguintes consomem o cache sem acesso à rede.
# Aggregate fragment — a registry-published Component as the type:components: db: type: core/datastore/mariadb:1.0.0Como o host e o segmento de tipo de entidade são derivados, e não escritos, escrever qualquer um deles na referência não endereça a entidade publicada — isso produz uma identidade que nenhuma entrada de catálogo tem. Uma referência a um Component ou a uma Feature é o seu metadata.name literal mais um :version opcional, quer a entidade seja resolvida do catálogo local, do cache ou de um registro. Um workspace que consome um registro privado nomeia esse host na própria configuração, e não em cada referência.
Verificação de completude
Depois que todos os mapeamentos são resolvidos, o compilador verifica se toda instância de componente e de vinculação (uma Feature de credenciais é uma vinculação como qualquer outra) no Aggregate do desenvolvedor tem uma Recipe ou FeatureRecipe resolvida. Entidades não mapeadas causam uma interrupção fatal com um diagnóstico explícito que lista cada entidade ausente e sugere qual chave components.type ou features.type adicionar para fechar a lacuna.
Âncoras YAML para manifestos DRY
Para evitar o inchaço do YAML em grandes conjuntos de mapeamentos, o Manifest suporta um bloco defs: opcional para âncoras YAML padrão (& e *):
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: global-base-manifest version: 1.0.0defs: - &python_worker_recipe "helm/standard-python-worker:2.0.0"spec: mappings: components: type: core/python-worker: *python_worker_recipe core/postgres: helm/postgres:1.2.0Negociação de Feature
O handshake de capacidade usa o mesmo mapeamento plano de URI:
- O desenvolvedor vincula
core/data-maskinga um componente no Aggregate, sob um nome próprio no mapafeatures:desse componente. - O compilador procura
core/data-maskingno mapafeatures.typedo Manifest. - Se a busca for resolvida para um URI de FeatureRecipe (por exemplo,
helm/data-masking-litellm:1.0.0), a capacidade existe e o pipeline da FeatureRecipe é executado na ordem definida. - Se
features.typenão contiver nenhuma entrada correspondente, o compilador interrompe o build e lista a Feature não mapeada.
O Manifest também aceita um bloco features.annotations — uma superfície de autoria paralela que permite que um subsistema de uma Release ou de um Aggregate vincule Features por chave de anotação, em vez de por declaração por componente. A forma da vinculação, a partição side-vs-pillar que determina qual superfície de autoria usa quais caminhos de roteamento, a disciplina pela qual a vinculação explícita prevalece e a regra de padrões do esquema ficam na seção dedicada Vinculações de Feature orientadas por anotações mais adiante.
Composição via extends
Um Manifest pode declarar uma única referência extends: que nomeia um Manifest base cujos mappings ele herda. A referência não é um URI e nunca é resolvida pelo catálogo: um Manifest pertence ao lado da implantação, escrito ao lado da Release em vez de publicado, então o valor é um caminho relativo para um arquivo de Manifest — ./base-manifest.yaml — ou o simples metadata.name de um Manifest que está no próprio diretório da Release. Um caminho relativo deve levar a um Manifest dentro do workspace — ou, quando a Release foi indicada fora do workspace (na linha de comando ou pela configuração do workspace), dentro do diretório que contém essa Release, e, para um Manifest que você indica sozinho na linha de comando fora do workspace, dentro do diretório que contém o Manifest: um caminho que sai subindo, ou que um link simbólico leva para fora, é recusado antes que o arquivo que ele nomeia seja lido (veja errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Uma referência a outro arquivo sai do diretório em que deve permanecer)”). Os mappings filhos sobrescrevem os da base em caso de colisão de chaves, dando suporte a padrões de sobreposição por ambiente (paridade staging/prod com diferenças cirúrgicas por ambiente) e a padrões de desenvolvimento local sem precisar copiar tudo.
Semântica de mesclagem. Quando um Manifest local estende um Manifest base, o compilador realiza uma substituição rasa de chaves por nível — os dicionários type e name são mesclados de forma independente, não em profundidade —, o que garante buscas O(1) nos dicionários e mantém previsível o comportamento da herança. Dentro de cada nível, as chaves filhas sobrescrevem as chaves pai.
O padrão ponte para o desenvolvimento local. Um uso comum de extends é trocar uma FeatureRecipe de credenciais para prototipagem local sem tocar no Aggregate. Em produção, o Manifest base mapeia a Feature de credenciais core/aws-secrets-manager para uma FeatureRecipe de produção no nível features.type. Para prototipagem local, a equipe de plataforma fornece um local-manifest que estende a base e sobrescreve cirurgicamente o mapeamento da Feature de credenciais para usar host-env-injector — uma FeatureRecipe local que entrega a credencial no arquivo Compose como uma referência de variável como ${SECRET_NAME}, que o Docker Compose substitui a partir do ambiente do shell ou de um arquivo .env quando a stack é iniciada. O desenvolvedor obtém um fluxo de trabalho local padrão, e o Aggregate permanece agnóstico em relação às capacidades para produção.
URIs abreviados sensíveis ao contexto
O compilador do Aggrega utiliza a inferência sensível ao contexto ao resolver URIs OCI em Manifests. Se um engenheiro omitir o nome de domínio totalmente qualificado (Fully Qualified Domain Name, FQDN) e o tipo de entidade arquitetural, o compilador recorre automaticamente ao registry padrão (configurado em .aggrega-config.yaml) e infere o tipo de entidade com base em onde a string está localizada no schema.
As regras de inferência:
- Domínio padrão: qualquer URI sem domínio (por exemplo,
python-worker-helm:1.0) recebe como prefixo odefault_registryconfigurado (padrão:hub.aggrega.ai/). - Expansão contextual da entidade: o compilador acrescenta o caminho de entidade correto com base no dicionário estrito do schema:
- Strings sob
Aggregate.spec.components[].typese expandem para/component/. - Strings sob
Aggregate.spec.aggregates[].typese expandem para/aggregate/. - Strings sob
Manifest.spec.mappings.components.typeouManifest.spec.mappings.components.namese expandem para/recipe/. - Strings sob
Manifest.spec.mappings.features.typeouManifest.spec.mappings.features.namese expandem para/featurerecipe/. Isso inclui as Features de credenciais (rotuladas comfeature.aggrega.ai/kind: secret) — elas usam o mesmo caminho de FeatureRecipe. - Strings atribuídas a
pipeline[].pluginse expandem para/plugin/.
- Strings sob
- Precedência de três níveis: antes de aplicar a inferência OCI, o compilador pesquisa os diretórios de catálogo do workspace e o cache de artefatos (o nível de workspace e cache), conforme definido no modelo de resolução de entidades em três níveis. A inferência OCI só se aplica quando a entidade chega ao nível do registry. Uma chave ou um valor de mapping nunca é lido como caminho de arquivo: uma Recipe ou FeatureRecipe escrita localmente fica em um diretório de catálogo —
catalog/na raiz do workspace, ou um dos queworkspace.catalog_dirslista — e é nomeada pela sua referência.
A forma abreviada em ação:
# Capability-qualified — required when two recipes share the name "postgres":"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:"core/postgres": "postgres:2.0"# Found in a local catalog directory or the cache; failing both, `aggrega pull`# (or a build run with --auto-pull) fetches it from the registry location derived# from the configured default registry and the Recipe kind.# A private registry is named in workspace configuration, not in the reference.Sem prefixo ops/. Os nomes de Recipe não levam prefixo ops/ — o diretório de tipo de entidade recipe/ na taxonomia OCI já identifica o domínio, e as Recipes são publicadas sob recipe/{capability}/{name} sem prefixos adicionais. Os Manifests referenciam Recipes por {capability}/{name}, ou pelo nome simples para a inferência sensível ao contexto. Veja architecture/13-catalog-and-registry.md §6 para a taxonomia OCI completa.
Vínculos de Feature orientados por anotações
O bloco features.annotations do Manifest declara vínculos entre chaves de anotação e tipos de Feature, além dos caminhos de roteamento pelos quais cada vínculo envia o valor da anotação. O vínculo é a superfície de autoria para condensar anexações repetitivas de Feature por componente — o padrão em que dezenas de componentes dentro de uma fronteira carregam, cada um, um bloco features: idêntico — em declarações de anotação únicas nas fronteiras da Release ou nos subsistemas do Aggregate.
Formato do schema:
spec: mappings: features: type: core/rewrite-host: helm/rewrite-host-helm:1.0.0 core/db-pool: helm/db-pool-helm:1.0.0
annotations: feature.aggrega.ai/rewrite-host: feature: core/rewrite-host maps: infra: - upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool: feature: core/db-pool maps: values: - pool # Aggregate-side: routes annotation value into values.poolUm vínculo traz um campo feature que nomeia o tipo de Feature de destino e um bloco maps que agrupa rotas de subchaves em caminhos pontuados por pilar de destino. O campo feature referencia um tipo de Feature que também deve aparecer na seção irmã features.type (que é onde fica o vínculo de versão da FeatureRecipe). O bloco maps declara duas listas indexadas por pilar — maps.infra e maps.values —, cada uma com strings de caminhos pontuados que apontam para as propriedades spec.schema.<pillar>.<path> da Feature de destino. Um vínculo deve declarar pelo menos um caminho entre as duas listas (o JSON Schema impõe minProperties: 1 em maps).
O polimorfismo de Provider para a mesma chave de anotação — por exemplo, feature.aggrega.ai/rewrite-host vinculada a core/k8s-dns-resolver em uma implantação Kubernetes, mas a core/compose-bridge em uma implantação Compose local — é expresso escolhendo tipos de Feature diferentes em Manifests diferentes; cada Manifest vincula a anotação a uma única Feature, e a FeatureRecipe da Feature escolhida traz a implementação específica do provedor.
A partição lado/pilar. A invariante do Aggregate como superfície de autoria restringe cada lado de autoria aos caminhos de roteamento de um único pilar. Anotações do lado do Aggregate são roteadas apenas por caminhos maps.values; anotações do lado da Release, apenas por caminhos maps.infra. Um vínculo que declara caminhos nos dois pilares dá suporte à composição entre lados: uma anotação do lado do Aggregate aciona o subconjunto do pilar values; uma anotação do lado da Release na mesma chave aciona o subconjunto do pilar infra; ambas as contribuições se compõem em uma única anexação de Feature por par (Component, Feature) com os dois pilares preenchidos. Uma incompatibilidade lado/pilar — por exemplo, uma anotação do lado do Aggregate em um vínculo que declara apenas maps.infra — interrompe o build com um diagnóstico claro que nomeia a chave de anotação, o pilar roteado, o lado de autoria e a localização no código-fonte, registrado sob o domínio do documento em que o valor da anotação foi escrito.
Validação dos destinos de caminho. No carregamento do catálogo, o compilador verifica se cada caminho pontuado declarado sob maps.infra e maps.values corresponde a uma propriedade que spec.schema.<pillar> da Feature de destino de fato declara. Um vínculo que roteia para um caminho que o schema da Feature não lista interrompe o carregamento do catálogo com um OPS_ERROR claro, nomeando o vínculo, a Feature de destino e o pilar e o caminho pelos quais roteou. Formatos de schema que escapam a um simples percurso de propriedades ($ref, patternProperties, composição oneOf / anyOf / allOf) encerram a verificação estática nesse ramo e deixam que a validação de schema posterior detecte qualquer incompatibilidade.
Formatos dos valores de anotação. Um vínculo consome valores de anotação em três formatos. Escalar — um único valor YAML (string, número, booleano). Um escalar combinado com um vínculo que declara exatamente um caminho entre os dois pilares roteia o valor para esse único caminho; um escalar combinado com um vínculo que declara mais de um caminho é um roteamento ambíguo e interrompe o build com um diagnóstico claro, registrado sob o domínio do documento em que o valor da anotação foi escrito. Estruturado — um mapa YAML cujas subchaves de nível superior correspondem, cada uma, a uma entrada de caminho pontuado sob maps.infra ou maps.values; cada subchave é roteada de forma independente para o pilar declarado, e a partição lado/pilar se aplica por subchave. null YAML explícito — exclui o vínculo herdado no escopo da cascata (com um null por subchave dentro de um valor estruturado excluindo subchaves individuais enquanto as irmãs permanecem). Para a orientação de referência sobre a autoria de valores estruturados — mesclagem em cascata por subchave, composição entre lados, validação de tipo por subchave, a disciplina do padrão relaxado para campos de schema sem um type declarado — veja providers/well-known-annotations.md §“Valores de anotação estruturados”.
A anexação explícita vence em caso de colisão de chaves. Quando um componente de Release ou um componente de Aggregate traz tanto uma entrada features: explícita quanto uma anotação que se expande para a mesma chave de Feature, a entrada explícita é preservada e a expansão da anotação para essa chave nesse componente não tem efeito. A anexação sintética nunca sobrescreve uma instância de Feature declarada pelo autor. Os autores podem, portanto, usar a expansão de anotações para a maior parte dos componentes e sobrescrever cirurgicamente componentes individuais escrevendo uma entrada features: explícita com a mesma chave — a entrada explícita traz a personalização por componente, e a anotação se propaga em cascata, sem alterações, para todos os outros componentes.
O explícito vence por folha na composição entre lados. Quando uma anexação explícita e uma contribuição de anotação preenchem a mesma instância de Feature, mas escrevem folhas diferentes, ambas as contribuições permanecem e a Feature resultante traz as duas folhas, com uma proveniência por folha que registra a origem de cada uma. Quando uma anexação explícita e uma contribuição de anotação apontam para a mesma folha dentro do mesmo pilar, a contribuição explícita vence e a IR registra a proveniência da anotação suprimida como um marcador de override nessa folha. O carregamento do catálogo evidencia esse override em tempo de build por meio de um aviso de lint consultivo que nomeia a chave de anotação suprimida + a origem.
Padrões do schema no momento da expansão. A anexação de Feature sintética produzida pela expansão de anotações traz apenas as folhas que o valor da anotação preenche pelos caminhos declarados do vínculo. Os padrões de schema declarados em spec.schema da Feature de destino não são mesclados na anexação sintética no momento da expansão. A materialização dos valores padrão é responsabilidade da camada de renderização da FeatureRecipe, aplicada de maneira uniforme a anexações explícitas e sintéticas, para que os dois caminhos produzam a mesma saída posterior para a mesma configuração efetiva.
Separação dos namespaces de anotação:
| Prefixo | Responsável | Finalidade |
|---|---|---|
aggrega.ai/ | Somente a plataforma Aggrega | Anotações nativas da plataforma lidas diretamente pelo provedor (por exemplo, aggrega.ai/namespace). |
feature.aggrega.ai/ | Biblioteca padrão oficial | Atalhos de anotação de Feature vinculados no Manifest. |
{any-other-domain}/ | Empresa / comunidade | Atalhos personalizados de anotação de Feature. |
Reserva do prefixo aggrega.ai/
Os vínculos features.annotations de um Manifest não podem usar o prefixo aggrega.ai/ sozinho — ele é reservado para anotações nativas da plataforma emitidas pelo compilador (rótulos OTel/de proveniência etc.). Os subprefixos com escopo (component.aggrega.ai/*, compliance.aggrega.ai/*, acme.aggrega.ai/* corporativo) continuam disponíveis para autoria pelos usuários. Veja providers/well-known-annotations para o conjunto de anotações reservadas pela plataforma.