Superficie di pubblicazione
Ogni YAML di catalogo di Aggrega porta un insieme uniforme di campi di metadati che descrivono l’entità per la distribuzione nel catalogo: chi la mantiene, con quale licenza viene distribuita, dove si trova il suo sorgente, quali parole chiave la fanno emergere nella ricerca. Insieme, questi campi costituiscono la superficie di pubblicazione — il vocabolario di metadati su cui fanno affidamento gli editori di cataloghi e gli strumenti che lo consumano, distinto dal meccanismo lato contenuto metadata.labels / metadata.annotations documentato in labels-and-annotations.md.
Questa pagina documenta i campi della superficie di pubblicazione, l’inventario dei campi di descrizione nel corpus (descrizioni dell’involucro, dell’istanza e a livello di campo), l’uso previsto del campo maintainer e il suo consumatore verificato, e le asimmetrie dei campi obbligatori per entità (quali campi richiede oggi ciascuna entità e dove le asimmetrie sono deliberate).
I campi della superficie di pubblicazione
I campi seguenti compaiono su ogni entità del Dominio 2 (Component, Feature) e del Dominio 3 (Recipe, FeatureRecipe, Plugin), oltre che sull’Aggregate come modulo riutilizzabile. Compaiono anche su Manifest e Release, con una semantica ridotta (attribuzione al workspace anziché pubblicazione nel catalogo).
| Campo | Tipo | Scopo | Consumatore |
|---|---|---|---|
description | string | Riepilogo leggibile dell’entità | Schede hover dell’editor (aggrega serve); lo strumento describe che un assistente invoca (aggrega mcp); un’annotazione ricercabile sull’artefatto pubblicato (aggrega push); aggrega inspect |
maintainers | array di oggetti | Chi possiede l’entità (name, email, url) | catalog_metadata per nodo nell’IR, sui nodi Component |
license | string | Conformità legale (tipicamente un identificatore SPDX) | catalog_metadata per nodo nell’IR, sui nodi Component |
repository | stringa (URL) | Repository Git in cui si trova il sorgente | catalog_metadata per nodo nell’IR, sui nodi Component — nient’altro lo legge |
home | stringa (URL) | URL della documentazione / del wiki | catalog_metadata per nodo nell’IR, sui nodi Component — nient’altro lo legge |
keywords | array di stringhe | Tag per la ricerca | catalog_metadata per nodo nell’IR, sui nodi Component — nessun indice di ricerca li consuma |
Tutti e sei i campi sono facoltativi su ogni entità che li porta. Un autore di catalogo che omette l’intera serie produce uno YAML valido — la superficie di pubblicazione è pensata per le entità destinate alla distribuzione nel catalogo; le entità a uso interno possono ometterla senza conseguenze.
La colonna Consumatore è esaustiva per ciò che viene distribuito oggi, e due delle sue conseguenze meritano di essere dette chiaramente, perché cambiano ciò che vale la pena scrivere:
descriptionè l’unico campo con più di un lettore.aggrega servelo mostra nella scheda hover per Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest e i quattro tipi di libreria (SchemaLibrary,MappingLibrary,WorkloadLibrary,ArtifactLibrary) — non per Plugin o Release. Lo strumentodescribeesposto daaggrega mcplo restituisce per un’entità di qualsiasi tipo.aggrega pushlo imprime sull’artefatto pubblicato come annotazione ricercabile.aggrega inspectlo stampa sotto l’intestazione dell’entità per ogni tipo, e non stampa nessun altro campo della superficie di pubblicazione.repository,homeekeywordsvengono validati e trasportati, e nulla li legge oltre l’IR. Nessuna superficie di elenco, nessun sito di catalogo e nessun indice di ricerca li consuma. Scriverli registra una provenienza che viaggia con l’entità ed è leggibile dall’output dell’IR e da una policy di governance; non rende l’entità reperibile da nessuna parte.
La deprecazione non è un campo della superficie di pubblicazione. Un’entità viene deprecata registrando un marcatore a suo carico nel registry dopo la pubblicazione — un marcatore firmato che porta una gravità (warning, error o retracted), un motivo e un sostituto, verificato al momento del pull. Ogni superficie che legge il lockfile lo segnala quindi; build.halt_on_deprecated_severity decide solo se interrompe anche una build. Il marcatore non viene mai scritto nello YAML dell’entità stessa, e la ragione è strutturale: un artefatto pubblicato è immutabile, quindi un flag congelato al suo interno al momento della pubblicazione non potrebbe mai esprimere una decisione presa più tardi. L’avviso di deprecazione che aggrega inspect stampa per un’entità del catalogo proviene dal marcatore, per ogni tipo che risolve per nome.
Consumo nell’IR — catalog_metadata per nodo
Il compilatore trasporta i campi della superficie di pubblicazione da ogni Component nel blocco catalog_metadata del nodo corrispondente, visibile nel grafo IR che un’esecuzione restituisce (aggrega inspect <release> --ir-graph). Il blocco contiene maintainers, license, repository, home e keywords — i cinque campi che l’IR trasporta; description non è tra questi. Gli strumenti costruiti sul contratto del grafo IR leggono i metadati da lì anziché rileggere lo YAML del catalogo.
Solo nodi Component. Il blocco viene popolato cercando il tipo di componente del nodo nel catalogo come Component, quindi la superficie di pubblicazione di una Feature, di una Recipe, di una FeatureRecipe o di un Plugin non raggiunge mai l’IR — quelle entità portano i campi, e i campi vengono validati, ma da esse non risulta alcun nodo IR.
catalog_metadata scompare del tutto dal JSON dell’IR quando ogni campo della superficie di pubblicazione del Component di origine è vuoto o zero: il blocco viene omesso anziché emesso con valori vuoti. Lo stesso input produce quindi lo stesso output compatto, il che mantiene stabile il diff dell’IR tra un’esecuzione e l’altra.
Una policy di governance può leggere il blocco. Un plugin associato sotto plugins.governance nel ruolo ir-verdict riceve l’intero grafo IR, nodo per nodo, incluso il catalog_metadata di ciascun nodo Component — quindi una policy può accettare o rifiutare una build in base a license, repository, home, keywords o maintainers di un nodo. Questa portata è specifica del socket di governance: il plugin di rendering di un provider riceve una proiezione per nodo limitata che non include catalog_metadata, quindi i plugin di rendering non possono leggere questi campi.
I tre tipi di descrizione
Il campo description compare in modo uniforme sull’involucro, ma il corpus contiene anche stringhe in stile descrizione all’interno delle dichiarazioni di schema (descrizioni per campo) e all’interno dei corpi dei pilastri (descrizioni per istanza). Coesistono tre tipi distinti di descrizione; la tabella seguente li distingue.
| Tipo | Dove si trova | Scritto da | Scopo |
|---|---|---|---|
| Descrizione dell’involucro | metadata.description su ogni entità | Editore del catalogo | Riepilogo dell’entità nel suo insieme, mostrato nelle schede hover dell’editor e impresso sull’artefatto pubblicato |
| Descrizione dell’istanza | Campo description accanto a una dichiarazione per istanza (per es. featuresSchema.<slot>.description, usesSchema.<socket>.description) | Autore dello schema | Descrizione per slot / per socket / per porta, per gli autori delle entità consumatrici che leggono la dichiarazione |
| Descrizione del campo | Annotazione description: di JSON Schema 2020-12 all’interno del contenuto di schema: / featuresSchema: / usesSchema: (forma compatta o JSON Schema completo in YAML) | Autore dello schema | Documentazione per campo che viaggia con lo schema |
I tre tipi condividono la parola «description» ma risiedono a livelli strutturalmente distinti. La descrizione dell’involucro si applica all’entità nel suo insieme; la descrizione dell’istanza si applica a una dichiarazione all’interno di uno slot di schema; la descrizione del campo si applica a un valore specifico all’interno di uno schema tipizzato. Per chi scrive un Component:
- Imposta
metadata.descriptionuna volta per l’entità Component stessa. - Imposta
featuresSchema.admin_password.descriptionuna volta per ogni slot di credenziale che il Component dichiara. - Imposta annotazioni
description:per campo all’interno del bloccoschema:— in forma compatta (port: { type: integer, description: "..." }) o in JSON Schema completo in YAML — per documentare ogni campo per chi legge lo schema del Component.
I tre tipi non si propagano a cascata e non collidono, e ciascuno raggiunge una superficie diversa — o nessuna:
- Descrizione dell’involucro — schede hover dell’editor, annotazioni ricercabili dell’artefatto pubblicato e
aggrega inspect, secondo la colonna Consumatore qui sopra. - Descrizione del campo — compare testualmente nell’estratto dello schema che la scheda hover di un Component o di una Feature mostra. L’estratto copre solo
spec.schemaed è troncato alle sue righe iniziali, quindi una descrizione più in profondità nel blocco — o una all’interno difeaturesSchema:ousesSchema:— non vi compare. - Descrizione dell’istanza — dichiarata e trasportata con l’entità; nessuna superficie distribuita la mostra da sola.
aggrega inspectelenca i socket e gli slot di funzionalità di un Component senza le loro descrizioni.
Intento del campo maintainer
Il campo maintainers porta un array di oggetti, ciascuno con name, email e url. L’intento e il consumatore verificato:
Intento (informativo + provenienza nell’IR). Il campo è informativo per la pubblicazione nel catalogo: l’intento architetturale è «chi è responsabile di questa entità del catalogo» — un segnale di proprietà che viaggia con l’entità. Nessuna superficie lo presenta come elenco di contatti, e nessun controllo integrato lo confronta con alcunché.
Consumatore verificato (catalog_metadata per nodo). Il compilatore trasporta il metadata.maintainers di ogni Component nel catalog_metadata.maintainers del nodo corrispondente nell’IR, visibile nel grafo che aggrega inspect <release> --ir-graph restituisce quando il Component di origine ne ha dichiarato uno. Quello è l’unico lettore del campo. Una policy di governance associata sotto plugins.governance nel ruolo ir-verdict lo vede lì, quindi una regola di proprietà — ogni entità nomina almeno un maintainer, il dominio di un maintainer corrisponde a un insieme approvato — è esprimibile sull’IR anziché sullo YAML del catalogo. Nessuna regola del genere viene distribuita; il socket è il posto in cui ne va una.
Il compilatore non applica né valida il contenuto del maintainer oltre la forma strutturale di JSON Schema (name obbligatorio; email e url facoltativi, entrambi stringhe). Se i maintainer elencati possiedano effettivamente l’entità, se la loro email sia raggiungibile, se un commit del repository sia firmato da uno di loro — queste sono questioni di governance del catalogo, e nessun controllo distribuito ne valuta alcuna. Appartengono a una policy di governance che un operatore associa, non al compilatore.
Asimmetrie dei campi obbligatori
I tipi di entità di Aggrega hanno insiemi di campi obbligatori leggermente diversi nei loro JSON Schema. La maggior parte delle asimmetrie è deliberata e riflette il ruolo dell’entità.
I campi obbligatori per entità (esclusi apiVersion / kind / metadata.name / metadata.version, che ogni entità richiede in modo uniforme):
| Entità | Campi obbligatori aggiuntivi | Motivazione |
|---|---|---|
| Component | metadata.labels.component.aggrega.ai/type | Il requisito dell’etichetta è portante per la corrispondenza dei selettori: le annotazioni x-aggrega-selector: di usesSchema filtrano i Components di destinazione in base a questa etichetta; in sua assenza, il Component viene rifiutato al caricamento |
| Feature | — | Nessun requisito di etichetta riservata; le Features si identificano per nome + editore |
| Recipe | spec.capability, spec.implements | Capability determina il dispatch al provider; implements determina il binding al Component |
| FeatureRecipe | spec.capability, spec.implements | Come per Recipe |
| Plugin | metadata.pluginType, spec.abiVersion | Il tipo di socket che il plugin implementa (parte del blocco di indirizzamento, che fornisce il segmento <pluginType> della coordinata derivata plugin/<pluginType>/<name>) e la versione ABI a cui è destinato; la posizione del .wasm è derivata da quell’identità anziché scritta; un plugin di rendering del provider (pluginType: provider) porta inoltre il proprio contratto di traduzione sotto spec.provider |
| Aggregate | — | Un Aggregate che non dichiara nessuno tra components, subsystems o aggregates viene caricato e compilato, e non renderizza nulla |
| Manifest | spec.mappings | I livelli di mappatura sono l’unico scopo del Manifest |
| Release | spec.aggregate, spec.manifest (una Release che dichiara extends non scrive aggregate e può omettere manifest); metadata.environment | I primi due ancorano la build a uno specifico Aggregate + Manifest; l’ambiente viene impresso sull’output renderizzato come etichetta aggrega.ai/environment |
Il requisito dell’etichetta Component è portante
L’etichetta component.aggrega.ai/type è l’unica etichetta che Aggrega richiede su qualsiasi entità. Il requisito esiste perché il meccanismo usesSchema della libreria standard filtra i candidati di destinazione tramite annotazioni x-aggrega-selector: che portano stringhe di selettore come "component.aggrega.ai/type=database" — il selettore consulta le etichette della destinazione per determinare se il tipo corrisponde ai tipi accettati dal socket. Lo schema del Component lo impone: un Component che omette l’etichetta viene rifiutato al caricamento (E0215), con l’indicazione della chiave mancante.
Il requisito non è quindi una questione di superficie di pubblicazione (l’etichetta non serve alla scoperta nel catalogo) ma una questione di topologia: ogni Component la porta, compresi i Components a uso interno che non mirano alla distribuzione nel catalogo.
Il metadata.environment della Release è obbligatorio
Lo schema della Release richiede metadata.environment, una stringa che la build imprime sull’output renderizzato come etichetta aggrega.ai/environment.
Altre asimmetrie
Le restanti asimmetrie (campi obbligatori della Recipe rispetto al Component, il requisito mappings del Manifest) riflettono il ruolo di ciascuna entità. Gli autori che desiderano un contratto uniforme dei campi obbligatori per ogni tipo di entità non lo troveranno; le asimmetrie sono deliberate secondo il design guidato dai ruoli.
Riferimenti incrociati
labels-and-annotations.md— meccanismo dei metadati lato contenuto che complementa la superficie di pubblicazione.entities/component.md— il requisitometadata.labels.component.aggrega.ai/typedel Component e le dichiarazionischema/usesSchema/featuresSchema.entities/release.md— il campometadata.environmentdella Release e il suo requisito.10-status.md— lo stato dell’involucro dei metadati.architecture/02-ecosystem-philosophy.md— il partizionamento rigoroso delle API e l’inquadramento progettuale dell’Enterprise Metadata Suite.architecture/13-catalog-and-registry.md§«Lockfile pinning and artifact immutability (Blocco delle versioni nel lockfile e immutabilità degli artefatti)» + §«Catalog entity name-shape enforcement (Applicazione della forma dei nomi delle entità del catalogo)» — ciò che la regola di immutabilità rifiuta al momento della pubblicazione, e dove vengono controllate le forme dei nomi per tipo di entità: il plugin di disciplina di pubblicazione le segnala come avviso quando un autore esegueaggrega lint, e né la compilazione né la pubblicazione le controllano.architecture/11-governance-and-compliance.md§«Inheritance and publishing discipline (Ereditarietà e disciplina di pubblicazione)» — quali regole di governance appartengono al plugin di disciplina di pubblicazione, e quali invece l’ereditarietà di un Component che ne estende un altro risolve per costruzione.