Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Superficie de publicación

Todo YAML de catálogo de Aggrega lleva un conjunto uniforme de campos de metadatos que describen la entidad para su distribución en el catálogo: quién la mantiene, bajo qué licencia se distribuye, dónde reside su código fuente, qué palabras clave la hacen aparecer en las búsquedas. En conjunto, estos campos constituyen la superficie de publicación — el vocabulario de metadatos en el que confían los editores de catálogos y las herramientas que lo consumen, distinto del mecanismo del lado del contenido metadata.labels / metadata.annotations documentado en labels-and-annotations.md.

Esta página documenta los campos de la superficie de publicación, el inventario de campos de descripción en el corpus (descripciones de la envoltura, de la instancia y a nivel de campo), el uso previsto del campo maintainer y su consumidor verificado, y las asimetrías de campos obligatorios por entidad (qué campos exige hoy cada entidad y dónde las asimetrías son deliberadas).

Los campos de la superficie de publicación

Los siguientes campos aparecen en toda entidad del Dominio 2 (Component, Feature) y del Dominio 3 (Recipe, FeatureRecipe, Plugin), además de en el Aggregate como módulo reutilizable. También aparecen en el Manifest y la Release, con una semántica reducida (atribución al espacio de trabajo en lugar de publicación en el catálogo).

CampoTipoPropósitoConsumidor
descriptionstringResumen legible de la entidadTarjetas flotantes del editor (aggrega serve); la herramienta describe a la que llama un asistente (aggrega mcp); una anotación buscable en el artefacto publicado (aggrega push); aggrega inspect
maintainersarray de objetosQuién es el propietario de la entidad (name, email, url)catalog_metadata por nodo en la IR, en los nodos Component
licensestringCumplimiento legal (normalmente un identificador SPDX)catalog_metadata por nodo en la IR, en los nodos Component
repositorycadena (URL)Repositorio Git donde reside el código fuentecatalog_metadata por nodo en la IR, en los nodos Component — nada más lo lee
homecadena (URL)URL de documentación / wikicatalog_metadata por nodo en la IR, en los nodos Component — nada más lo lee
keywordsarray de cadenasTags de descubrimientocatalog_metadata por nodo en la IR, en los nodos Component — ningún índice de búsqueda los consume

Los seis campos son opcionales en toda entidad que los lleva. Un autor de catálogo que omite el conjunto completo produce un YAML válido — la superficie de publicación es para entidades destinadas a la distribución en el catálogo; las entidades de uso interno pueden omitirla sin consecuencias.

La columna Consumidor es exhaustiva para lo que se distribuye hoy, y dos de sus consecuencias merecen decirse con claridad, porque cambian lo que vale la pena escribir:

  • description es el único campo con más de un lector. aggrega serve lo muestra en la tarjeta flotante de Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest y los cuatro tipos de biblioteca (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) — no para Plugin ni Release. La herramienta describe que expone aggrega mcp lo devuelve para una entidad de cualquier tipo. aggrega push lo estampa en el artefacto publicado como anotación buscable. aggrega inspect lo imprime bajo el encabezado de la entidad para todos los tipos, y no imprime ningún otro campo de la superficie de publicación.
  • repository, home y keywords se validan y se transportan, y nada los lee más allá de la IR. Ninguna superficie de listado, sitio de catálogo ni índice de búsqueda los consume. Escribirlos registra una procedencia que viaja con la entidad y que es legible desde la salida de la IR y por una política de gobernanza; no hace que la entidad se pueda encontrar en ninguna parte.

La obsolescencia no es un campo de la superficie de publicación. Una entidad se marca como obsoleta registrando un marcador contra ella en el registro después de la publicación — un marcador firmado que lleva una gravedad (warning, error o retracted), un motivo y un reemplazo, verificado en el momento del pull. Toda superficie que lee el lockfile lo informa entonces; build.halt_on_deprecated_severity decide solo si además detiene una compilación. El marcador nunca se escribe en el YAML propio de la entidad, y la razón es estructural: un artefacto publicado es inmutable, así que un indicador congelado en él en el momento de publicar nunca podría expresar una decisión tomada después. El aviso de obsolescencia que aggrega inspect imprime para una entidad del catálogo procede del marcador, para cada tipo que resuelve por nombre.

Consumo en la IR — catalog_metadata por nodo

El compilador traslada los campos de la superficie de publicación de cada Component al bloque catalog_metadata del nodo correspondiente, visible en el grafo IR que devuelve una ejecución (aggrega inspect <release> --ir-graph). El bloque contiene maintainers, license, repository, home y keywords — los cinco campos que lleva la IR; description no está entre ellos. Las herramientas construidas sobre el contrato del grafo IR leen los metadatos de ahí en lugar de volver a leer el YAML del catálogo.

Solo nodos Component. El bloque se rellena buscando el tipo de componente del nodo en el catálogo como Component, así que la superficie de publicación de una Feature, una Recipe, una FeatureRecipe o un Plugin nunca llega a la IR — esas entidades llevan los campos, y los campos se validan, pero de ellas no resulta ningún nodo IR.

catalog_metadata desaparece por completo del JSON de la IR cuando todos los campos de la superficie de publicación del Component de origen están vacíos o a cero: el bloque se omite en lugar de emitirse con valores vacíos. Por tanto, la misma entrada produce la misma salida compacta, lo que mantiene estable el diff de la IR entre ejecuciones.

Una política de gobernanza puede leer el bloque. Un plugin vinculado bajo plugins.governance en el rol ir-verdict recibe el grafo IR completo, nodo por nodo, incluido el catalog_metadata de cada nodo Component — así que una política puede aceptar o rechazar una compilación según el license, repository, home, keywords o maintainers de un nodo. Ese alcance es específico del socket de gobernanza: el plugin de renderizado de un proveedor recibe una proyección por nodo acotada que no incluye catalog_metadata, así que los plugins de renderizado no pueden leer estos campos.

Los tres tipos de descripción

El campo description aparece de manera uniforme en la envoltura, pero el corpus también contiene cadenas de tipo descripción dentro de las declaraciones de esquema (descripciones por campo) y dentro de los cuerpos de los pilares (descripciones por instancia). Coexisten tres tipos distintos de descripción; la tabla siguiente los distingue.

TipoDónde resideEscrito porPropósito
Descripción de la envolturametadata.description en toda entidadEditor del catálogoResumen de la entidad en su conjunto, mostrado en las tarjetas flotantes del editor y estampado en el artefacto publicado
Descripción de la instanciaCampo description junto a una declaración por instancia (p. ej., featuresSchema.<slot>.description, usesSchema.<socket>.description)Autor del esquemaDescripción por slot / por socket / por puerto, para los autores de entidades consumidoras que leen la declaración
Descripción del campoAnotación description: de JSON Schema 2020-12 dentro del contenido de schema: / featuresSchema: / usesSchema: (forma compacta o JSON Schema completo en YAML)Autor del esquemaDocumentación por campo que viaja con el esquema

Los tres tipos comparten la palabra «description» pero residen en niveles estructuralmente distintos. La descripción de la envoltura se aplica a la entidad en su conjunto; la descripción de la instancia se aplica a una declaración dentro de un slot de esquema; la descripción del campo se aplica a un valor concreto dentro de un esquema tipado. Para quien escribe un Component:

  • Establece metadata.description una vez para la propia entidad Component.
  • Establece featuresSchema.admin_password.description una vez por cada slot de credenciales que declara el Component.
  • Establece anotaciones description: por campo dentro del bloque schema: — en forma compacta (port: { type: integer, description: "..." }) o en JSON Schema completo en YAML — para documentar cada campo para quien lea el esquema del Component.

Los tres tipos no se propagan en cascada ni colisionan, y cada uno llega a una superficie diferente — o a ninguna:

  • Descripción de la envoltura — tarjetas flotantes del editor, las anotaciones buscables del artefacto publicado y aggrega inspect, según la columna Consumidor anterior.
  • Descripción del campo — aparece literalmente en el extracto del esquema que muestra la tarjeta flotante de un Component o de una Feature. El extracto cubre solo spec.schema y se trunca a sus primeras líneas, así que una descripción más profunda en el bloque — o una dentro de featuresSchema: o usesSchema: — no aparece ahí.
  • Descripción de la instancia — declarada y transportada con la entidad; ninguna superficie distribuida la muestra por sí sola. aggrega inspect lista los sockets y los slots de funcionalidades de un Component sin sus descripciones.

Intención del campo maintainer

El campo maintainers lleva un array de objetos, cada uno con name, email y url. La intención y el consumidor verificado:

Intención (informativa + procedencia en la IR). El campo es informativo para la publicación en el catálogo: la intención arquitectónica es «quién es responsable de esta entidad del catálogo» — una señal de propiedad que viaja con la entidad. Ninguna superficie lo presenta como lista de contactos, y ninguna comprobación integrada lo compara con nada.

Consumidor verificado (catalog_metadata por nodo). El compilador traslada el metadata.maintainers de cada Component al catalog_metadata.maintainers del nodo correspondiente en la IR, visible en el grafo que devuelve aggrega inspect <release> --ir-graph cuando el Component de origen declaró uno. Ese es el único lector del campo. Una política de gobernanza vinculada bajo plugins.governance en el rol ir-verdict lo ve ahí, así que una regla de propiedad — toda entidad nombra al menos un maintainer, el dominio de un maintainer coincide con un conjunto aprobado — se puede expresar sobre la IR en lugar de sobre el YAML del catálogo. No se distribuye ninguna regla así; el socket es donde va una.

El compilador no impone ni valida el contenido de maintainer más allá de la forma estructural de JSON Schema (name obligatorio; email y url opcionales, ambos de tipo cadena). Si los maintainers listados son realmente propietarios de la entidad, si su email es alcanzable, si un commit del repositorio está firmado por uno de ellos — son cuestiones de gobernanza del catálogo, y ninguna comprobación distribuida evalúa ninguna de ellas. Corresponden a una política de gobernanza que vincula un operador, no al compilador.

Asimetrías de campos obligatorios

Los tipos de entidad de Aggrega tienen conjuntos de campos obligatorios ligeramente distintos en sus JSON Schemas. La mayoría de las asimetrías son deliberadas y reflejan el rol de la entidad.

Los campos obligatorios por entidad (excluidos apiVersion / kind / metadata.name / metadata.version, que toda entidad exige de manera uniforme):

EntidadCampos obligatorios adicionalesJustificación
Componentmetadata.labels.component.aggrega.ai/typeEl requisito de la etiqueta es fundamental para la coincidencia de selectores: las anotaciones x-aggrega-selector: de usesSchema filtran los Components de destino por esta etiqueta; sin ella, el Component se rechaza al cargarse
Feature—Sin requisito de etiqueta reservada; las Features se identifican por nombre + editor
Recipespec.capability, spec.implementsCapability condiciona el despacho al proveedor; implements condiciona el enlace al Component
FeatureRecipespec.capability, spec.implementsIgual que Recipe
Pluginmetadata.pluginType, spec.abiVersionEl tipo de socket que implementa el plugin (parte del bloque de direccionamiento, que aporta el segmento <pluginType> de la coordenada derivada plugin/<pluginType>/<name>) y la versión de ABI a la que apunta; la ubicación del .wasm se deriva de esa identidad en lugar de escribirse; un plugin de renderizado de proveedor (pluginType: provider) lleva además su contrato de traducción bajo spec.provider
Aggregate—Un Aggregate que no declara ninguno de components, subsystems o aggregates se carga y se compila, y no renderiza nada
Manifestspec.mappingsLos niveles de mapeo son el único propósito del Manifest
Releasespec.aggregate, spec.manifest (una Release que declara extends no escribe aggregate y puede omitir manifest); metadata.environmentLos dos primeros anclan la compilación a un Aggregate + Manifest concretos; el entorno se estampa en la salida renderizada como la etiqueta aggrega.ai/environment

El requisito de la etiqueta Component es fundamental

La etiqueta component.aggrega.ai/type es la única etiqueta que Aggrega exige en cualquier entidad. El requisito existe porque el mecanismo usesSchema de la biblioteca estándar filtra los candidatos de destino mediante anotaciones x-aggrega-selector: que llevan cadenas de selector como "component.aggrega.ai/type=database" — el selector consulta las etiquetas del destino para determinar si el tipo coincide con los tipos aceptados por el socket. El esquema del Component lo impone: un Component que omite la etiqueta se rechaza al cargarse (E0215), indicando la clave que falta.

Por tanto, el requisito no es una cuestión de la superficie de publicación (la etiqueta no es para el descubrimiento en el catálogo) sino una cuestión de topología: todo Component la lleva, incluidos los Components de uso interno que no se destinan a la distribución en el catálogo.

El metadata.environment de la Release es obligatorio

El esquema de la Release exige metadata.environment, una cadena que la compilación estampa en la salida renderizada como la etiqueta aggrega.ai/environment.

Otras asimetrías

Las asimetrías restantes (campos obligatorios de la Recipe frente al Component, el requisito mappings del Manifest) reflejan el rol de cada entidad. Los autores que quieran un contrato uniforme de campos obligatorios para todos los tipos de entidad no lo encontrarán; las asimetrías son deliberadas según el diseño guiado por roles.

Referencias cruzadas

  • labels-and-annotations.md — mecanismo de metadatos del lado del contenido que complementa la superficie de publicación.
  • entities/component.md — el requisito metadata.labels.component.aggrega.ai/type del Component y las declaraciones schema / usesSchema / featuresSchema.
  • entities/release.md — el campo metadata.environment de la Release y su requisito.
  • 10-status.md — el estado de la envoltura de metadatos.
  • architecture/02-ecosystem-philosophy.md — la partición estricta de las API y el encuadre de diseño de la Enterprise Metadata Suite.
  • architecture/13-catalog-and-registry.md §«Lockfile pinning and artifact immutability (Fijación en el lockfile e inmutabilidad de los artefactos)» + §«Catalog entity name-shape enforcement (Aplicación de la forma de los nombres de las entidades del catálogo)» — lo que la regla de inmutabilidad rechaza al publicar, y dónde se comprueban las formas de nombre por tipo de entidad: el plugin de disciplina de publicación las informa como advertencia cuando un autor ejecuta aggrega lint, y ni la compilación ni la publicación las comprueban.
  • architecture/11-governance-and-compliance.md §«Inheritance and publishing discipline (Herencia y disciplina de publicación)» — qué reglas de gobernanza corresponden al plugin de disciplina de publicación, y cuáles resuelve en cambio por construcción la herencia de un Component que extiende otro.