Superfície de publicação
Todo YAML de catálogo do Aggrega carrega um conjunto uniforme de campos de metadados que descrevem a entidade para distribuição no catálogo: quem a mantém, sob qual licença ela é distribuída, onde fica seu código-fonte, quais palavras-chave a fazem aparecer nas buscas. Juntos, esses campos constituem a superfície de publicação — o vocabulário de metadados em que os publicadores de catálogos e as ferramentas que o consomem confiam, distinto do mecanismo do lado do conteúdo metadata.labels / metadata.annotations documentado em labels-and-annotations.md.
Esta página documenta os campos da superfície de publicação, o inventário dos campos de descrição no corpus (descrições do envelope, da instância e no nível do campo), o uso pretendido do campo maintainer e seu consumidor verificado, e as assimetrias de campos obrigatórios por entidade (quais campos cada entidade exige hoje e onde as assimetrias são deliberadas).
Os campos da superfície de publicação
Os campos a seguir aparecem em toda entidade do Domínio 2 (Component, Feature) e do Domínio 3 (Recipe, FeatureRecipe, Plugin), além do Aggregate como módulo reutilizável. Também aparecem no Manifest e na Release, com semântica reduzida (atribuição ao workspace em vez de publicação no catálogo).
| Campo | Tipo | Finalidade | Consumidor |
|---|---|---|---|
description | string | Resumo legível da entidade | Cartões flutuantes do editor (aggrega serve); a ferramenta describe que um assistente chama (aggrega mcp); uma anotação pesquisável no artefato publicado (aggrega push); aggrega inspect |
maintainers | array de objetos | Quem é dono da entidade (name, email, url) | catalog_metadata por nó na IR, nos nós Component |
license | string | Conformidade legal (normalmente um identificador SPDX) | catalog_metadata por nó na IR, nos nós Component |
repository | string (URL) | Repositório Git onde fica o código-fonte | catalog_metadata por nó na IR, nos nós Component — nada mais o lê |
home | string (URL) | URL da documentação / wiki | catalog_metadata por nó na IR, nos nós Component — nada mais o lê |
keywords | array de strings | Tags de descoberta | catalog_metadata por nó na IR, nos nós Component — nenhum índice de busca os consome |
Todos os seis campos são opcionais em toda entidade que os carrega. Um autor de catálogo que omite o conjunto inteiro produz um YAML válido — a superfície de publicação é para entidades destinadas à distribuição no catálogo; entidades de uso interno podem omiti-la sem consequências.
A coluna Consumidor é exaustiva para o que é distribuído hoje, e duas de suas consequências merecem ser ditas com clareza, porque mudam o que vale a pena escrever:
descriptioné o único campo com mais de um leitor.aggrega serveo renderiza no cartão flutuante de Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest e dos quatro tipos de biblioteca (SchemaLibrary,MappingLibrary,WorkloadLibrary,ArtifactLibrary) — não para Plugin nem Release. A ferramentadescribequeaggrega mcpexpõe o retorna para uma entidade de qualquer tipo.aggrega pusho carimba no artefato publicado como anotação pesquisável.aggrega inspecto imprime abaixo do cabeçalho da entidade para todo tipo, e não imprime nenhum outro campo da superfície de publicação.repository,homeekeywordssão validados e transportados, e nada os lê além da IR. Nenhuma superfície de listagem, site de catálogo ou índice de busca os consome. Escrevê-los registra uma procedência que viaja com a entidade e é legível na saída da IR e por uma política de governança; isso não torna a entidade encontrável em lugar nenhum.
A descontinuação não é um campo da superfície de publicação. Uma entidade é marcada como descontinuada registrando um marcador contra ela no registro após a publicação — um marcador assinado que carrega uma severidade (warning, error ou retracted), um motivo e um substituto, verificado no momento do pull. Toda superfície que lê o lockfile então o informa; build.halt_on_deprecated_severity decide apenas se ele também interrompe um build. O marcador nunca é escrito no próprio YAML da entidade, e o motivo é estrutural: um artefato publicado é imutável, então um sinalizador congelado nele no momento da publicação nunca poderia expressar uma decisão tomada depois. O aviso de descontinuação que aggrega inspect imprime para uma entidade do catálogo vem do marcador, para todo tipo que ele resolve pelo nome.
Consumo pela IR — catalog_metadata por nó
O compilador transporta os campos da superfície de publicação de cada Component para o bloco catalog_metadata do nó correspondente, visível no grafo IR que uma execução retorna (aggrega inspect <release> --ir-graph). O bloco contém maintainers, license, repository, home e keywords — os cinco campos que a IR transporta; description não está entre eles. Ferramentas construídas sobre o contrato do grafo IR leem os metadados dali em vez de reler o YAML do catálogo.
Somente nós Component. O bloco é preenchido procurando o tipo de componente do nó no catálogo como Component, então a superfície de publicação de uma Feature, de uma Recipe, de uma FeatureRecipe ou de um Plugin nunca chega à IR — essas entidades carregam os campos, e os campos são validados, mas nenhum nó IR resulta delas.
catalog_metadata desaparece totalmente do JSON da IR quando todo campo da superfície de publicação no Component de origem está vazio ou zerado: o bloco é omitido em vez de emitido com valores vazios. A mesma entrada, portanto, produz a mesma saída compacta, o que mantém o diff da IR estável entre execuções.
Uma política de governança pode ler o bloco. Um plugin vinculado em plugins.governance no papel ir-verdict recebe o grafo IR inteiro, nó por nó, incluindo o catalog_metadata de cada nó Component — então uma política pode aceitar ou rejeitar um build com base em license, repository, home, keywords ou maintainers de um nó. Esse alcance é específico do socket de governança: o plugin de renderização de um provedor recebe uma projeção por nó delimitada que não inclui catalog_metadata, então os plugins de renderização não podem ler esses campos.
Os três tipos de descrição
O campo description aparece uniformemente no envelope, mas o corpus também contém strings no estilo de descrição dentro de declarações de schema (descrições por campo) e dentro dos corpos dos pilares (descrições por instância). Três tipos distintos de descrição coexistem; a tabela abaixo os distingue.
| Tipo | Onde fica | Escrito por | Finalidade |
|---|---|---|---|
| Descrição do envelope | metadata.description em toda entidade | Publicador do catálogo | Resumo da entidade como um todo, mostrado nos cartões flutuantes do editor e carimbado no artefato publicado |
| Descrição da instância | Campo description ao lado de uma declaração por instância (por exemplo, featuresSchema.<slot>.description, usesSchema.<socket>.description) | Autor do schema | Descrição por slot / por socket / por porta, para autores de entidades consumidoras que leem a declaração |
| Descrição do campo | Anotação description: do JSON Schema 2020-12 dentro do conteúdo de schema: / featuresSchema: / usesSchema: (forma compacta ou JSON Schema completo em YAML) | Autor do schema | Documentação por campo que viaja com o schema |
Os três tipos compartilham a palavra “description”, mas ficam em níveis estruturalmente distintos. A descrição do envelope se aplica à entidade como um todo; a descrição da instância se aplica a uma declaração dentro de um slot de schema; a descrição do campo se aplica a um valor específico dentro de um schema tipado. Para quem escreve um Component:
- Defina
metadata.descriptionuma vez para a própria entidade Component. - Defina
featuresSchema.admin_password.descriptionuma vez por slot de credencial que o Component declara. - Defina anotações
description:por campo dentro do blocoschema:— em forma compacta (port: { type: integer, description: "..." }) ou em JSON Schema completo em YAML — para documentar cada campo para quem lê o schema do Component.
Os três tipos não se propagam em cascata nem colidem, e cada um chega a uma superfície diferente — ou a nenhuma:
- Descrição do envelope — cartões flutuantes do editor, as anotações pesquisáveis do artefato publicado e
aggrega inspect, conforme a coluna Consumidor acima. - Descrição do campo — aparece literalmente no trecho do schema que o cartão flutuante de um Component ou de uma Feature renderiza. O trecho cobre apenas
spec.schemae é truncado nas suas linhas iniciais, então uma descrição mais profunda no bloco — ou uma dentro defeaturesSchema:ouusesSchema:— não aparece ali. - Descrição da instância — declarada e transportada com a entidade; nenhuma superfície distribuída a renderiza sozinha.
aggrega inspectlista os sockets e os slots de funcionalidades de um Component sem suas descrições.
Intenção do campo maintainer
O campo maintainers carrega um array de objetos, cada um com name, email e url. A intenção e o consumidor verificado:
Intenção (informativa + procedência na IR). O campo é informativo para a publicação no catálogo: a intenção arquitetural é “quem é responsável por esta entidade do catálogo” — um sinal de propriedade que viaja com a entidade. Nenhuma superfície o apresenta como lista de contatos, e nenhuma verificação embutida o compara com nada.
Consumidor verificado (catalog_metadata por nó). O compilador transporta o metadata.maintainers de cada Component para o catalog_metadata.maintainers do nó correspondente na IR, visível no grafo que aggrega inspect <release> --ir-graph retorna quando o Component de origem declarou um. Esse é o único leitor do campo. Uma política de governança vinculada em plugins.governance no papel ir-verdict o vê ali, então uma regra de propriedade — toda entidade nomeia pelo menos um maintainer, o domínio de um maintainer corresponde a um conjunto aprovado — pode ser expressa sobre a IR em vez de sobre o YAML do catálogo. Nenhuma regra desse tipo é distribuída; o socket é onde uma delas entra.
O compilador não impõe nem valida o conteúdo de maintainer além da forma estrutural do JSON Schema (name obrigatório; email e url opcionais, ambos string). Se os maintainers listados de fato são donos da entidade, se o email deles é alcançável, se um commit do repositório é assinado por um deles — essas são questões de governança do catálogo, e nenhuma verificação distribuída avalia qualquer uma delas. Elas pertencem a uma política de governança que um operador vincula, não ao compilador.
Assimetrias de campos obrigatórios
Os tipos de entidade do Aggrega têm conjuntos de campos obrigatórios ligeiramente diferentes em seus JSON Schemas. A maioria das assimetrias é deliberada e reflete o papel da entidade.
Os campos obrigatórios por entidade (excluindo apiVersion / kind / metadata.name / metadata.version, que toda entidade exige uniformemente):
| Entidade | Campos obrigatórios adicionais | Justificativa |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | O requisito do rótulo é estrutural para a correspondência de seletores: as anotações x-aggrega-selector: de usesSchema filtram os Components de destino por este rótulo; sem ele, o Component é recusado ao ser carregado |
| Feature | — | Nenhum requisito de rótulo reservado; as Features se identificam por nome + publicador |
| Recipe | spec.capability, spec.implements | Capability condiciona o despacho ao provedor; implements condiciona a associação ao Component |
| FeatureRecipe | spec.capability, spec.implements | Igual a Recipe |
| Plugin | metadata.pluginType, spec.abiVersion | O tipo de socket que o plugin implementa (parte do bloco de endereçamento, que fornece o segmento <pluginType> da coordenada derivada plugin/<pluginType>/<name>) e a versão de ABI que ele tem como alvo; a localização do .wasm é derivada dessa identidade em vez de escrita; um plugin de renderização de provedor (pluginType: provider) carrega adicionalmente seu contrato de tradução em spec.provider |
| Aggregate | — | Um Aggregate que não declara nenhum de components, subsystems ou aggregates é carregado e compilado, e não renderiza nada |
| Manifest | spec.mappings | Os níveis de mapeamento são o único propósito do Manifest |
| Release | spec.aggregate, spec.manifest (uma Release que declara extends não escreve aggregate e pode omitir manifest); metadata.environment | Os dois primeiros ancoram o build a um Aggregate + Manifest específicos; o ambiente é carimbado na saída renderizada como o rótulo aggrega.ai/environment |
O requisito do rótulo Component é estrutural
O rótulo component.aggrega.ai/type é o único rótulo que o Aggrega exige em qualquer entidade. O requisito existe porque o mecanismo usesSchema da biblioteca padrão filtra os candidatos de destino por meio de anotações x-aggrega-selector: que carregam strings de seletor como "component.aggrega.ai/type=database" — o seletor consulta os rótulos do destino para determinar se o tipo corresponde aos tipos aceitos pelo socket. O schema do Component o impõe: um Component que omite o rótulo é recusado ao ser carregado (E0215), com a indicação da chave ausente.
O requisito, portanto, não é uma questão da superfície de publicação (o rótulo não serve à descoberta no catálogo), mas uma questão de topologia: todo Component o carrega, incluindo os Components de uso interno que não visam à distribuição no catálogo.
O metadata.environment da Release é obrigatório
O schema da Release exige metadata.environment, uma string que o build carimba na saída renderizada como o rótulo aggrega.ai/environment.
Outras assimetrias
As assimetrias restantes (campos obrigatórios da Recipe versus Component, o requisito mappings do Manifest) refletem o papel de cada entidade. Autores que querem um contrato uniforme de campos obrigatórios em todos os tipos de entidade não o encontrarão; as assimetrias são deliberadas conforme o design orientado por papéis.
Referências cruzadas
labels-and-annotations.md— mecanismo de metadados do lado do conteúdo que complementa a superfície de publicação.entities/component.md— o requisitometadata.labels.component.aggrega.ai/typedo Component e as declaraçõesschema/usesSchema/featuresSchema.entities/release.md— o campometadata.environmentda Release e seu requisito.10-status.md— o status do envelope de metadados.architecture/02-ecosystem-philosophy.md— o particionamento estrito de APIs e o enquadramento de design da Enterprise Metadata Suite.architecture/13-catalog-and-registry.md§“Lockfile pinning and artifact immutability (Fixação no lockfile e imutabilidade de artefatos)” + §“Catalog entity name-shape enforcement (Aplicação da forma dos nomes das entidades do catálogo)” — o que a regra de imutabilidade recusa no momento da publicação, e onde as formas de nome por tipo de entidade são verificadas: o plugin de disciplina de publicação as informa como aviso quando um autor executaaggrega lint, e nem o build nem a publicação as verificam.architecture/11-governance-and-compliance.md§“Inheritance and publishing discipline (Herança e disciplina de publicação)” — quais regras de governança pertencem ao plugin de disciplina de publicação, e quais a herança de um Component que estende outro resolve, em vez disso, por construção.