Manifest
O papel conceptual da entidade Manifest (Domínio 4 — a tabela de mapeamento que associa interfaces abstratas a Recipes concretas) está descrito em architecture/04-entity-taxonomy.md. Esta página abrange a superfície de criação do Manifest: como se posiciona ao lado da Release, a forma de mapeamento de URIs planos, a composição através de extends, as regras de abreviatura de URIs, as associações de Features orientadas 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 que Recipe realiza cada tipo de catálogo e, através do
spec.capabilitydessa Recipe, o fornecedor (p. ex., Helm, Helm-chart, Compose) que o renderiza. É a tabela de mapeamento — um registo por projeto, com commit no Git, de que Recipe concreta implementa cada interface abstrata; as versões e os digests a que uma compilação vincula essas Recipes são fixados separadamente, no lockfile de cada Release. - A Release dita o destino (p. ex., a pasta de saída física para a geração de artefactos GitOps). É o encaminhador da implementação — uma descrição por ambiente de onde ficam os artefactos compilados.
O esquema da Release não tem nenhum campo provider em nenhum nível de aninhamento; o despacho de fornecedores pertence exclusivamente ao Manifest.
O caminho de compilação. Quando um utilizador executa aggrega build --release release.yaml, o compilador resolve os artefactos físicos juntando ambas as 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. Abre o Manifest para o qual a Release aponta através do seu campo
manifest:. - Pesquisa em dois níveis. Verifica primeiro o nível
namepara"user-db". Se não 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 indica declara em
spec.capabilityque fornecedor a renderiza. - Geração da saída. O compilador sabe agora a pasta de destino (
dist/boundaries/ovh-cluster-3/), o fornecedor (renderização Helm através de Wasm) e o artefacto (o código de origem da Recipe). As fronteiras GitOps ahead-of-time são respeitadas de ponta a ponta.
Mapeamento de URIs planos
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 ao 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. Cada instância de componente do tipo declarado resolve-se para a Recipe especificada. O mapeamento é de um para um por tipo de componente. Uma chave que não indique o tipo exato de uma instância alcança-a ainda assim pela base do tipo, quando nenhuma chave indica 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 indique outra versão (core/postgres:1.0.0), pode alcançar uma instância decore/postgres:2.0.0—, mas a Recipe que indica tem de 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. Uma instância dessas mapeia-se, com uma chave que indique a 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. Todas as anexações de Feature do tipo declarado se resolvem para a FeatureRecipe especificada. As Features de credenciais (etiquetadas comfeature.aggrega.ai/kind: secret) residem no mesmo mapafeatures.typeque as Features operacionais — o modelo unificado de entidade Feature.
Cada bloco aceita também um nível name a par 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 indicada em components.name resolve-se para essa Recipe, enquanto todas as outras instâncias do mesmo tipo se resolvem através de components.type. Isto exprime uma substituição por instância — duas instâncias de um mesmo tipo de componente podem ser implementadas através de duas Recipes diferentes (por exemplo, a maioria das instâncias de base de dados usa a Recipe mapeada em massa, enquanto uma instância é fixada numa implementação física diferente), sem fazer fork do tipo de componente nem duplicar o Manifest. A substituição aplica-se uniformemente: a instância indicada tanto renderiza através da Recipe de substituição como fixa a sua origem a partir dela. features.name é o nível simétrico para as anexações de Feature, indexado pelo nome próprio da anexação — a chave sob a qual está escrita no features: de um componente —, nunca pelo nome do componente ao qual está anexada. O exemplo de substituição de receita por instância percorre de ponta a ponta um caso mínimo com duas instâncias.
Uma anexação que uma ligação transporta é indexada pelo nome que assume no componente consumidor: <alias>.<slot>, o alias sob o qual a ligação está escrita, um ponto e o slot que a anexação preenche (consulte a entrada de ligação do Aggregate). Assim, a credencial de uma ligação pode ser realizada de forma diferente de todas as outras anexações 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 parágrafo seguinte. A Feature que a anexação indica também é fixada e verificada, exatamente como a Feature de uma anexação escrita no próprio componente, sob a entrada de ligação que o seu autor escreveu — consulte O lockfile.
Uma chave name tem de indicar algo que o build contém. O nível é comparado pelo nome exato, pelo que uma chave components.name que não seja uma instância de componente no build, ou uma chave features.name que não seja nele uma anexação — na maioria das vezes o nome do componente em que uma anexação se encontra, escrito onde deveria estar o nome próprio da anexação —, não seria consultada por nada, e as instâncias a que se destinava seriam resolvidas silenciosamente através do nível type. Em vez disso, o build é interrompido nessa chave, antes de qualquer renderização, indicando o Manifest, a chave, os nomes desse tipo que o build contém e o nome que provavelmente se pretendia — consulte A Manifest name mapping names nothing in the build (Um mapeamento por nome do Manifest não indica nada no build).
Uma realização associada por nome é fixada e verificada como uma associada por tipo. O aggrega pull obtém cada Recipe e FeatureRecipe que qualquer um dos níveis associa — a partir de um diretório de catálogo, da cache ou de um registo — e regista cada uma no lockfile da Release com a sua versão resolvida e o seu digest de conteúdo, sob a entrada de mapeamento que a associa: 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 vincula cada uma delas à sua fixação. Um lockfile que não regista nenhuma linha para uma realização que o Manifest associa interrompe o build por estar desatualizado, indicando a realização e a entrada que a associa; uma realização cujo conteúdo mudou desde o pull interrompe-o da mesma forma, indicando ambos os digests. Em ambos os casos, aggrega pull --release <release> regista a realização tal como está agora. Tal como uma entrada type, uma entrada name é fixada quer a Release declare ou não uma instância com esse nome, pelo que uma entrada name que indique uma Recipe que nenhum catálogo ou registo contém interrompe o pull; uma entrada name que não indique 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 associa 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 /, pelo que uma referência com um terceiro segmento não indica nenhuma receita e interrompe a resolução. No momento da renderização, o resolvedor carrega a Recipe através de uma pesquisa 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 mantém-se plana, independentemente de quantos fornecedores o catálogo mais amplo suporte.
Pesquisa direta por URI
O valor de mapeamento do Manifest é um URI de Recipe. O compilador resolve o URI diretamente contra o lockfile e o catálogo, devolvendo a Recipe correspondente. Não itera sobre as declarações spec.implements para encontrar uma Recipe que «implemente» um tipo de componente. Cada entrada do Manifest associa o tipo de componente criado pelo programador 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 TEM de corresponder à chave de tipo de componente do Manifest para essa entrada de mapeamento — ou a uma base que essa chave extends, a qualquer profundidade da cadeia, uma vez que uma Recipe escrita para uma base implementa tudo o que a estende. Um valor que não corresponda a nenhuma produz um OPS_ERROR com um diagnóstico claro que indica a entrada do Manifest, a Recipe resolvida e o valor spec.implements em conflito. A verificação dispara uma vez por entrada de mapeamento do Manifest, sobre o Manifest composto e antes de qualquer Recipe ser resolvida — estática, determinística e sem percorrer nada além da própria cadeia extends do tipo mapeado. Uma chave components.type que alcance uma instância de componente numa versão que não indica é avaliada 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. Consulte ../vocabulary/inheritance-and-interface.md para saber o que a Recipe de uma base poupa e não poupa a uma especialização.
Todos os comandos que leem as dependências de uma Release executam-na, e cada um decide por si o que significa uma constatação: aggrega build e aggrega pull interrompem-se, uma vez que ambos produzem algo que se vai usar a seguir, enquanto aggrega validate e aggrega lint a comunicam com as restantes constatações e terminam com código diferente de zero, e o editor publica-a como um diagnóstico entre os outros. aggrega lint é a exceção na avaliação de uma instância: avalia as entradas de mapeamento e não as instâncias que estas alcançam, pelo que não a comunica, enquanto aggrega build, aggrega pull e aggrega validate --release a comunicam. Consulte ../errors/fatal-halts.md para o diagnóstico e a forma de o corrigir.
A verificação de consistência é a única superfície de mapeamento que lê a cadeia extends. A seleção da Recipe continua a ser exata na chave de mapeamento: um tipo de componente que estende uma base mapeada continua a precisar da sua própria entrada aqui, e não obtém nenhuma entrada por herança.
spec.implements também sugere candidatas. Uma instância cujo tipo não tem nenhum mapeamento no Manifest interrompe o build com um OPS_ERROR que lista como candidatas a fixação as receitas cujo spec.implements consegue implementar esse tipo; o preenchimento automático do editor num valor de mapeamento coloca essas mesmas receitas correspondentes em primeiro lugar. Ambas as superfícies leem spec.implements face ao próprio tipo pedido, pelo que uma receita que implementa uma das bases desse tipo não é oferecida como candidata, embora o mapeamento fosse considerado consistente. spec.implements declara, assim, o que uma receita pode implementar e informa a escolha humana — na verificação de consistência, no diagnóstico de ausência de mapeamento e no preenchimento automático — mas nunca resolve um build. O mapeamento do Manifest é a escolha explícita de implementação do utilizador, fixada no lockfile para reprodutibilidade; o catálogo nunca escolhe uma implementação em nome do utilizador.
Três formas para o segmento de versão do URI
Um URI de Recipe no Manifest pode indicar a versão em qualquer uma de três formas:
- Exata —
helm/postgres:1.2.0. O lockfile tem de fixar exatamente esta versão; na primeira resolução do lockfile, o resolvedor fixa esta versão; se o catálogo ou o registo não contiver esta versão no momento da resolução, o carregamento do espaço de trabalho é 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 mais alta disponível 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 escrita pelo utilizador. Voltar a resolver para uma versão mais recente requer uma ação explícita do utilizador — aggrega pull --upgrade --release <release> <uri> volta a resolver uma única dependência, mantendo todas as outras fixações, ou aggrega pull --upgrade --release <release> volta a resolver todas — o lockfile é a fonte de verdade para os builds; a forma escrita pelo utilizador é a maneira como este exprime a restrição de versão no momento da criação.
Referências qualificadas pela capacidade
A identidade de uma Recipe no catálogo tem âmbito de capacidade: duas receitas podem partilhar um metadata.name e uma versão e declarar valores spec.capability diferentes. A identidade de registo é recipe/{capability}/{name}:{version}, derivada do tipo da receita, do seu spec.capability sem qualquer fixação de versão que este contenha, 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 indica a receita com qualquer uma das precisões:
- Simples —
mariadb:1.0.0. Resolve-se quando exatamente uma receita no catálogo tem o nome; a forma dominante na prática. - Qualificada pela capacidade —
compose/mariadb:1.0.0. O segmento antes da primeira/indica ospec.capabilityda receita, sem a sua fixação de versão — uma fixação escrita na referência é recusada (E0095). Obrigatória quando mais do que uma receita disponibiliza o mesmo nome: uma referência simples que corresponda a duas receitas é ambígua e interrompe ruidosamente a resolução, em vez de escolher uma silenciosamente.
Um URI de Recipe não tem mais posições. O resolvedor divide apenas na primeira /, pelo que compose/mariadb indica a capacidade compose e a receita mariadb, e uma referência com três segmentos não corresponde a nenhuma receita em nenhuma das precisões.
As formas de segmento de versão acima aplicam-se a ambas as formas.
Entidades publicadas em registos nos mapeamentos
Uma entidade consumida a partir de um registo e não de um catálogo local é referenciada exatamente pela mesma identidade que uma local usa: a referência não contém nenhum host de registo nem nenhum segmento de tipo de entidade. O resolvedor fornece ambos — o host a partir do registo predefinido configurado no espaço de trabalho, o segmento de tipo a partir do local onde a referência se encontra no esquema — segundo as regras de URIs abreviados sensíveis ao contexto abaixo. Quando nem um diretório de catálogo local nem a cache contêm uma cópia, o aggrega pull — ou um build executado com --auto-pull — obtém a entidade a partir da localização derivada, coloca-a em cache e fixa a versão resolvida e o digest de conteúdo no lockfile; os builds seguintes consomem a 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 criados, escrever qualquer um deles na referência não endereça a entidade publicada — produz uma identidade que nenhuma entrada do catálogo tem. Uma referência de Component ou Feature é o seu metadata.name literal mais um :version opcional, quer a entidade se resolva a partir do catálogo local, da cache ou de um registo. Um espaço de trabalho que consuma um registo privado indica esse host na sua própria configuração e não em cada referência.
Verificação de completude
Depois de todos os mapeamentos serem resolvidos, o compilador verifica que todas as instâncias de componente e de anexação (uma Feature de credencial é uma anexação como qualquer outra) no Aggregate do programador têm uma Recipe ou FeatureRecipe resolvida. As entidades não mapeadas provocam uma interrupção fatal com um diagnóstico explícito que lista todas as entidades em falta e sugere que chave components.type ou features.type acrescentar para colmatar 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 capacidades usa o mesmo mapeamento de URIs planos:
- O programador anexa
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 pesquisa se resolver para um URI de FeatureRecipe (p. ex.,
helm/data-masking-litellm:1.0.0), a capacidade existe e o pipeline da FeatureRecipe é executado pela ordem definida. - Se
features.typenão contiver nenhuma entrada correspondente, o compilador interrompe o build e lista a Feature não mapeada.
O Manifest aceita também um bloco features.annotations — uma superfície de criação paralela que permite a uma Release ou a um subsistema do Aggregate anexar Features por chave de anotação e não por declaração por componente. A forma da associação, a partição lado-versus-pilar que determina que superfície de criação usa que caminhos de encaminhamento, a disciplina de prevalência da anexação explícita e a regra dos valores predefinidos do esquema estão na secção dedicada Associações de Features orientadas por anotações mais abaixo.
Composição através de extends
Um Manifest pode declarar uma única referência extends: que indica um Manifest base cujos mappings herda. A referência não é um URI e nunca é resolvida através do catálogo: um Manifest é do lado da implementação, criado ao lado da Release e não publicado, pelo que o valor é ou um caminho relativo para um ficheiro de Manifest — ./base-manifest.yaml — ou o metadata.name simples de um Manifest que se encontra no próprio diretório da Release. Um caminho relativo tem de levar a um Manifest dentro do espaço de trabalho — ou, quando a Release foi indicada fora do espaço de trabalho (na linha de comandos ou pela configuração do espaço de trabalho), dentro do diretório que contém essa Release, e, para um Manifest indicado isoladamente na linha de comandos fora do espaço de trabalho, dentro do diretório que contém o Manifest: um que saia dele, ou que uma ligação simbólica leve para fora, é recusado antes de o ficheiro que indica ser lido (consulte errors/fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Uma referência a outro ficheiro sai do diretório dentro do qual tem de permanecer)»). Os mapeamentos do filho substituem os da base em caso de colisão de chaves, suportando padrões de sobreposição por ambiente (paridade staging/prod com diferenças cirúrgicas por ambiente) e padrões de desenvolvimento local sem criar cópias integrais.
Semântica de fusão. Quando um Manifest local estende um Manifest base, o compilador efetua uma substituição superficial de chaves por nível — os dicionários type e name são fundidos de forma independente, não em profundidade — o que garante pesquisas em dicionário O(1) e mantém o comportamento da herança previsível. Dentro de cada nível, as chaves do filho substituem as do pai.
O padrão de ponte para 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 credencial core/aws-secrets-manager para uma FeatureRecipe de produção no nível features.type. Para a prototipagem local, a equipa de plataforma fornece um local-manifest que estende a base e substitui cirurgicamente o mapeamento da Feature de credencial para usar host-env-injector — uma FeatureRecipe local que entrega a credencial no ficheiro Compose como uma referência de variável, como ${SECRET_NAME}, que o Docker Compose substitui a partir do ambiente da shell ou de um ficheiro .env quando a stack arranca. O programador obtém um fluxo de trabalho local padrão, e o Aggregate mantém-se agnóstico em relação à capacidade para produção.
URIs abreviados sensíveis ao contexto
O compilador do Aggrega utiliza inferência sensível ao contexto ao resolver URIs OCI em Manifests. Se um engenheiro omitir o nome de domínio totalmente qualificado (FQDN) e o tipo de entidade arquitetural, o compilador recorre automaticamente ao registo predefinido (configurado em .aggrega-config.yaml) e infere o tipo de entidade com base no local onde a string se encontra no esquema.
As regras de inferência:
- Domínio predefinido: qualquer URI sem domínio (p. ex.,
python-worker-helm:1.0) recebe como prefixo odefault_registryconfigurado (predefinição:hub.aggrega.ai/). - Expansão contextual de entidades: o compilador acrescenta o caminho de entidade correto com base no dicionário estrito do esquema:
- As strings sob
Aggregate.spec.components[].typeexpandem-se para/component/. - As strings sob
Aggregate.spec.aggregates[].typeexpandem-se para/aggregate/. - As strings sob
Manifest.spec.mappings.components.typeouManifest.spec.mappings.components.nameexpandem-se para/recipe/. - As strings sob
Manifest.spec.mappings.features.typeouManifest.spec.mappings.features.nameexpandem-se para/featurerecipe/. Isto inclui as Features de credenciais (etiquetadas comfeature.aggrega.ai/kind: secret) — usam o mesmo caminho de FeatureRecipe. - As strings atribuídas a
pipeline[].pluginexpandem-se para/plugin/.
- As 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 espaço de trabalho e a cache de artefactos (o nível de espaço de trabalho 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 registo. Uma chave ou um valor de mapeamento nunca é lido como caminho de ficheiro: uma Recipe ou FeatureRecipe criada localmente encontra-se num diretório de catálogo —
catalog/na raiz do espaço de trabalho, ou um dos queworkspace.catalog_dirsenumera — e é designada pela sua referência.
A abreviatura 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 das Recipes não têm prefixo ops/ — o diretório de tipo de entidade recipe/ na taxonomia OCI já identifica o domínio, e as Recipes são disponibilizadas em recipe/{capability}/{name} sem prefixo adicional. Os Manifests referenciam as Recipes por {capability}/{name}, ou pelo nome simples para a inferência sensível ao contexto. Consulte architecture/13-catalog-and-registry.md §6 para a taxonomia OCI completa.
Associações de Features orientadas por anotações
O bloco features.annotations do Manifest declara associações entre chaves de anotação e tipos de Feature, mais os caminhos de encaminhamento pelos quais cada associação envia o valor da anotação. A associação é a superfície de criação para comprimir anexações de Feature repetitivas por componente — o padrão em que dezenas de componentes de uma fronteira transportam cada um um bloco features: idêntico — em declarações únicas de anotações nas fronteiras da Release ou nos subsistemas do Aggregate.
Forma do esquema:
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.poolUma associação contém um campo feature que indica o tipo de Feature de destino e um bloco maps que agrupa as rotas de subchaves com caminhos com pontos por pilar de destino. O campo feature referencia um tipo de Feature que também tem de aparecer na secção irmã features.type (que é onde reside a associação da versão da FeatureRecipe). O bloco maps declara duas listas indexadas por pilar — maps.infra e maps.values — cada uma com strings de caminhos com pontos que apontam para as propriedades spec.schema.<pillar>.<path> da Feature de destino. Uma associação tem de declarar pelo menos um caminho nas 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 associada a core/k8s-dns-resolver numa implementação Kubernetes, mas a core/compose-bridge numa implementação Compose local — exprime-se escolhendo tipos de Feature diferentes em Manifests diferentes; cada Manifest associa a anotação a uma Feature, e a FeatureRecipe da Feature escolhida contém a implementação específica do provider.
A partição lado-versus-pilar. A invariante Aggregate-as-Authoring-Surface restringe cada lado de criação aos caminhos de encaminhamento de um pilar. As anotações do lado do Aggregate encaminham apenas através de caminhos maps.values; as anotações do lado da Release encaminham apenas através de caminhos maps.infra. Uma associação que declare caminhos em ambos os pilares suporta a composição entre lados: uma anotação do lado do Aggregate dispara o subconjunto do pilar values; uma anotação do lado da Release com a mesma chave dispara o subconjunto do pilar infra; ambos os contributos compõem-se numa única anexação de Feature por par (Component, Feature), com ambos os pilares preenchidos. Uma discrepância lado-versus-pilar — p. ex., uma anotação do lado do Aggregate contra uma associação que declara apenas maps.infra — interrompe o build com um diagnóstico claro que indica a chave da anotação, o pilar encaminhado, o lado de criação e a localização de origem, classificado no domínio do documento em que o valor da anotação foi criado.
Validação dos destinos dos caminhos. No carregamento do catálogo, o compilador verifica que cada caminho com pontos declarado em maps.infra e maps.values corresponde a uma propriedade que o spec.schema.<pillar> da Feature de destino declara efetivamente. Uma associação que encaminhe para um caminho que o esquema da Feature não lista interrompe o carregamento do catálogo com um OPS_ERROR claro, que indica a associação, a Feature de destino e o pilar e o caminho por onde encaminhou. As formas de esquema que escapam a um simples percurso de propriedades ($ref, patternProperties, composição oneOf / anyOf / allOf) terminam a verificação estática nesse ramo e deixam a validação de esquemas a jusante detetar qualquer discrepância.
Formas dos valores de anotação. Uma associação consome valores de anotação em três formas. Escalar — um único valor YAML (string, número, booleano). Um escalar combinado com uma associação que declare exatamente um caminho nos dois pilares encaminha o valor para esse único caminho; um escalar combinado com uma associação que declare mais do que um caminho é um encaminhamento ambíguo e interrompe o build com um diagnóstico claro, classificado no domínio do documento em que o valor da anotação foi criado. Estruturado — um mapa YAML cujas subchaves de nível superior correspondem cada uma a uma entrada de caminho com pontos em maps.infra ou maps.values; cada subchave é encaminhada para o seu pilar declarado de forma independente, e a partição lado-versus-pilar aplica-se por subchave. null YAML explícito — exclui a associação herdada no âmbito da cascata (com null por subchave dentro de um valor estruturado a excluir subchaves individuais enquanto as irmãs se mantêm). Para a explicação canónica de criação de valores estruturados — fusão em cascata por subchave, composição entre lados, validação de tipos por subchave, a disciplina de predefinição flexível para campos de esquema sem um type declarado — consulte providers/well-known-annotations.md §«Valores de anotação estruturados».
A anexação explícita prevalece em caso de colisão de chaves. Quando um componente da Release ou um componente do Aggregate transporta simultaneamente uma entrada features: explícita e 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 substitui uma instância de Feature declarada pelo autor. Os autores podem, portanto, usar a expansão de anotações para a maioria dos componentes e substituir cirurgicamente componentes individuais escrevendo uma entrada features: explícita com a mesma chave — a entrada explícita contém a personalização por componente, e a anotação passa em cascata para todos os outros componentes sem alterações.
Prevalência explícita por folha na composição entre lados. Quando uma anexação explícita e um contributo de anotação preenchem ambos a mesma instância de Feature mas escrevem em folhas diferentes, ambos os contributos se mantêm e a Feature resultante contém ambas as folhas, com uma proveniência por folha que regista a origem de cada uma. Quando uma anexação explícita e um contributo de anotação visam a mesma folha dentro do mesmo pilar, o contributo explícito prevalece e a IR regista a proveniência da anotação suprimida como um marcador de substituição nessa folha. O carregamento do catálogo revela esta substituição no momento do build através de um aviso de lint informativo que indica a chave + origem da anotação suprimida.
Valores predefinidos do esquema no momento da expansão. A anexação de Feature sintética produzida pela expansão de anotações contém apenas as folhas que o valor da anotação preenche através dos caminhos declarados da associação. Os valores predefinidos do esquema declarados no spec.schema da Feature de destino não são fundidos na anexação sintética no momento da expansão. A materialização dos valores predefinidos é responsabilidade da camada de renderização da FeatureRecipe, aplicada uniformemente às anexações explícitas e sintéticas, para que os dois caminhos produzam a mesma saída a jusante para a mesma configuração efetiva.
Separação de espaços de nomes de anotações:
| Prefixo | Proprietário | Finalidade |
|---|---|---|
aggrega.ai/ | Apenas a plataforma Aggrega | Anotações nativas da plataforma lidas diretamente pelo fornecedor (p. ex., aggrega.ai/namespace). |
feature.aggrega.ai/ | Biblioteca padrão oficial | Atalhos de anotações de Feature associados no Manifest. |
{any-other-domain}/ | Empresa / comunidade | Atalhos personalizados de anotações de Feature. |
Reserva do prefixo aggrega.ai/
As associações features.annotations do Manifest não podem usar o prefixo aggrega.ai/ simples — está reservado para anotações nativas da plataforma emitidas pelo compilador (etiquetas OTel/de proveniência, etc.). Os subprefixos com âmbito (component.aggrega.ai/*, compliance.aggrega.ai/*, o empresarial acme.aggrega.ai/*) continuam disponíveis para criação pelos utilizadores. Consulte providers/well-known-annotations para o conjunto de anotações reservadas pela plataforma.