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

Superfície de publicação

Todo o YAML de catálogo do Aggrega contém um conjunto uniforme de campos de metadados que descrevem a entidade para distribuição no catálogo: quem a mantém, sob que licença é distribuída, onde está o seu código-fonte, que palavras-chave a fazem aparecer nas pesquisas. Em conjunto, estes campos constituem a superfície de publicação — o vocabulário de metadados em que os editores 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 ao nível do campo), a utilização prevista do campo maintainer e o seu consumidor verificado, e as assimetrias de campos obrigatórios por entidade (que campos cada entidade exige hoje e onde as assimetrias são deliberadas).

Os campos da superfície de publicação

Os campos seguintes aparecem em todas as entidades do Domínio 2 (Component, Feature) e do Domínio 3 (Recipe, FeatureRecipe, Plugin), bem como no Aggregate enquanto módulo reutilizável. Aparecem também no Manifest e na Release, com uma semântica reduzida (atribuição ao espaço de trabalho em vez de publicação no catálogo).

CampoTipoFinalidadeConsumidor
descriptionstringResumo legível da entidadeCartões flutuantes do editor (aggrega serve); a ferramenta describe que um assistente invoca (aggrega mcp); uma anotação pesquisável no artefacto publicado (aggrega push); aggrega inspect
maintainersarray de objetosQuem é o proprietário da entidade (name, email, url)catalog_metadata por nó na IR, nos nós Component
licensestringConformidade legal (normalmente um identificador SPDX)catalog_metadata por nó na IR, nos nós Component
repositorystring (URL)Repositório Git onde está o código-fontecatalog_metadata por nó na IR, nos nós Component — nada mais o lê
homestring (URL)URL da documentação / wikicatalog_metadata por nó na IR, nos nós Component — nada mais o lê
keywordsarray de stringsTags de descobertacatalog_metadata por nó na IR, nos nós Component — nenhum índice de pesquisa os consome

Todos os seis campos são opcionais em todas as entidades que os contêm. Um autor de catálogo que omita o conjunto inteiro produz um YAML válido — a superfície de publicação destina-se a entidades previstas para distribuição no catálogo; as entidades de uso interno podem omiti-la sem consequências.

A coluna Consumidor é exaustiva quanto ao que é distribuído hoje, e duas das suas consequências merecem ser ditas com clareza, porque mudam aquilo que vale a pena escrever:

  • description é o único campo com mais de um leitor. aggrega serve renderiza-o 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 ferramenta describe que aggrega mcp expõe devolve-o para uma entidade de qualquer tipo. aggrega push carimba-o no artefacto publicado como anotação pesquisável. aggrega inspect imprime-o por baixo do cabeçalho da entidade para todos os tipos, e não imprime nenhum outro campo da superfície de publicação.
  • repository, home e keywords são validados e transportados, e nada os lê para além da IR. Nenhuma superfície de listagem, sítio de catálogo ou índice de pesquisa os consome. Escrevê-los regista uma proveniência que viaja com a entidade e é legível a partir da saída da IR e por uma política de governança; não torna a entidade encontrável em lado nenhum.

A descontinuação não é um campo da superfície de publicação. Uma entidade é marcada como descontinuada registando um marcador contra ela no registo após a publicação — um marcador assinado que tem uma severidade (warning, error ou retracted), um motivo e um substituto, verificado no momento do pull. Todas as superfícies que leem o lockfile passam então a comunicá-lo; build.halt_on_deprecated_severity decide apenas se também interrompe uma compilação. O marcador nunca é escrito no próprio YAML da entidade, e a razão é estrutural: um artefacto publicado é imutável, pelo que um indicador congelado nele no momento da publicação nunca poderia exprimir uma decisão tomada mais tarde. O aviso de descontinuação que aggrega inspect imprime para uma entidade do catálogo provém do marcador, para todos os tipos que 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 devolve (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. As ferramentas construídas sobre o contrato do grafo IR leem os metadados daí em vez de voltarem a ler o YAML do catálogo.

Apenas nós Component. O bloco é preenchido procurando o tipo de componente do nó no catálogo como Component, pelo que a superfície de publicação de uma Feature, de uma Recipe, de uma FeatureRecipe ou de um Plugin nunca chega à IR — essas entidades contêm os campos, e os campos são validados, mas nenhum nó IR resulta delas.

catalog_metadata desaparece por completo do JSON da IR quando todos os campos da superfície de publicação no Component de origem estão vazios ou a zero: o bloco é omitido em vez de ser emitido com valores vazios. A mesma entrada produz, portanto, 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 anexado em plugins.governance no papel ir-verdict recebe o grafo IR inteiro, nó a nó, incluindo o catalog_metadata de cada nó Component — pelo que uma política pode aceitar ou rejeitar uma compilação 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 fornecedor recebe uma projeção por nó delimitada que não inclui catalog_metadata, pelo que os plugins de renderização não podem ler estes campos.

Os três tipos de descrição

O campo description aparece uniformemente no envelope, mas o corpus contém também strings do tipo descrição dentro de declarações de schema (descrições por campo) e dentro dos corpos dos pilares (descrições por instância). Coexistem três tipos distintos de descrição; a tabela abaixo distingue-os.

TipoOnde se encontraEscrito porFinalidade
Descrição do envelopemetadata.description em todas as entidadesEditor do catálogoResumo da entidade como um todo, mostrado nos cartões flutuantes do editor e carimbado no artefacto publicado
Descrição da instânciaCampo description junto a uma declaração por instância (por exemplo, featuresSchema.<slot>.description, usesSchema.<socket>.description)Autor do schemaDescrição por slot / por socket / por porta, para os autores de entidades consumidoras que leem a declaração
Descrição do campoAnotaçã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 schemaDocumentação por campo que viaja com o schema

Os três tipos partilham a palavra «description», mas situam-se em níveis estruturalmente distintos. A descrição do envelope aplica-se à entidade como um todo; a descrição da instância aplica-se a uma declaração dentro de um slot de schema; a descrição do campo aplica-se a um valor específico dentro de um schema tipado. Para quem escreve um Component:

  • Definir metadata.description uma vez para a própria entidade Component.
  • Definir featuresSchema.admin_password.description uma vez por cada slot de credencial que o Component declara.
  • Definir anotações description: por campo dentro do bloco schema: — 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 artefacto publicado e aggrega inspect, conforme a coluna Consumidor acima.
  • Descrição do campo — aparece literalmente no excerto do schema que o cartão flutuante de um Component ou de uma Feature renderiza. O excerto abrange apenas spec.schema e é truncado nas suas linhas iniciais, pelo que uma descrição mais profunda no bloco — ou uma dentro de featuresSchema: ou usesSchema: — não aparece aí.
  • Descrição da instância — declarada e transportada com a entidade; nenhuma superfície distribuída a renderiza por si só. aggrega inspect lista os sockets e os slots de funcionalidades de um Component sem as respetivas descrições.

Intenção do campo maintainer

O campo maintainers contém um array de objetos, cada um com name, email e url. A intenção e o consumidor verificado:

Intenção (informativa + proveniê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 contactos, e nenhuma verificação incorporada o compara com o que quer que seja.

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 devolve quando o Component de origem declarou um. Esse é o único leitor do campo. Uma política de governança anexada em plugins.governance no papel ir-verdict vê-o aí, pelo que uma regra de propriedade — todas as entidades nomeiam 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 deste tipo é distribuída; o socket é onde uma delas se coloca.

O compilador não impõe nem valida o conteúdo de maintainer para além da forma estrutural do JSON Schema (name obrigatório; email e url opcionais, ambos string). Se os maintainers listados são de facto proprietários da entidade, se o seu email é contactável, se um commit do repositório é assinado por um deles — estas são questões de governança do catálogo, e nenhuma verificação distribuída avalia qualquer uma delas. Pertencem a uma política de governança que um operador anexa, não ao compilador.

Assimetrias de campos obrigatórios

Os tipos de entidade do Aggrega têm conjuntos de campos obrigatórios ligeiramente diferentes nos 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 todas as entidades exigem uniformemente):

EntidadeCampos obrigatórios adicionaisFundamentação
Componentmetadata.labels.component.aggrega.ai/typeO requisito da etiqueta é estrutural para a correspondência de seletores: as anotações x-aggrega-selector: de usesSchema filtram os Components de destino por esta etiqueta; na sua ausência, o Component é recusado ao ser carregado
Feature—Nenhum requisito de etiqueta reservada; as Features identificam-se por nome + editor
Recipespec.capability, spec.implementsCapability condiciona o despacho para o fornecedor; implements condiciona a associação ao Component
FeatureRecipespec.capability, spec.implementsIgual a Recipe
Pluginmetadata.pluginType, spec.abiVersionO 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 tem como alvo; a localização do .wasm é derivada dessa identidade em vez de escrita; um plugin de renderização de fornecedor (pluginType: provider) contém adicionalmente o seu contrato de tradução em spec.provider
Aggregate—Um Aggregate que não declare nenhum de components, subsystems ou aggregates é carregado e compilado, e não renderiza nada
Manifestspec.mappingsOs níveis de mapeamento são o único propósito do Manifest
Releasespec.aggregate, spec.manifest (uma Release que declare extends não escreve aggregate e pode omitir manifest); metadata.environmentOs dois primeiros ancoram a compilação a um Aggregate + Manifest específicos; o ambiente é carimbado na saída renderizada como a etiqueta aggrega.ai/environment

O requisito da etiqueta Component é estrutural

A etiqueta component.aggrega.ai/type é a única etiqueta que o Aggrega exige em qualquer entidade. O requisito existe porque o mecanismo usesSchema da biblioteca padrão filtra os candidatos de destino através de anotações x-aggrega-selector: que contêm strings de seletor como "component.aggrega.ai/type=database" — o seletor consulta as etiquetas do destino para determinar se o tipo corresponde aos tipos aceites pelo socket. O schema do Component impõe-no: um Component que omita a etiqueta é recusado ao ser carregado (E0215), com a indicação da chave em falta.

O requisito não é, portanto, uma questão da superfície de publicação (a etiqueta não serve para a descoberta no catálogo), mas uma questão de topologia: cada Component contém-na, incluindo os Components de uso interno que não se destinam à distribuição no catálogo.

O metadata.environment da Release é obrigatório

O schema da Release exige metadata.environment, uma string que a compilação carimba na saída renderizada como a etiqueta aggrega.ai/environment.

Outras assimetrias

As restantes assimetrias (campos obrigatórios da Recipe face ao Component, o requisito mappings do Manifest) refletem o papel de cada entidade. Os autores que pretendam um contrato uniforme de campos obrigatórios em todos os tipos de entidade não o encontrarão; as assimetrias são deliberadas, de acordo com 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 requisito metadata.labels.component.aggrega.ai/type do Component e as declarações schema / usesSchema / featuresSchema.
  • entities/release.md — o campo metadata.environment da Release e o respetivo requisito.
  • 10-status.md — o estado 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 artefactos)» + §«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 são verificadas as formas de nome por tipo de entidade: o plugin de disciplina de publicação comunica-as a título de aviso quando um autor executa aggrega lint, e nem a compilação nem a publicação as verificam.
  • architecture/11-governance-and-compliance.md §«Inheritance and publishing discipline (Herança e disciplina de publicação)» — que 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.