Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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).

CampoTipoScopoConsumatore
descriptionstringRiepilogo 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
maintainersarray di oggettiChi possiede l’entità (name, email, url)catalog_metadata per nodo nell’IR, sui nodi Component
licensestringConformità legale (tipicamente un identificatore SPDX)catalog_metadata per nodo nell’IR, sui nodi Component
repositorystringa (URL)Repository Git in cui si trova il sorgentecatalog_metadata per nodo nell’IR, sui nodi Component — nient’altro lo legge
homestringa (URL)URL della documentazione / del wikicatalog_metadata per nodo nell’IR, sui nodi Component — nient’altro lo legge
keywordsarray di stringheTag per la ricercacatalog_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 serve lo 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 strumento describe esposto da aggrega mcp lo restituisce per un’entità di qualsiasi tipo. aggrega push lo imprime sull’artefatto pubblicato come annotazione ricercabile. aggrega inspect lo stampa sotto l’intestazione dell’entità per ogni tipo, e non stampa nessun altro campo della superficie di pubblicazione.
  • repository, home e keywords vengono 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.

TipoDove si trovaScritto daScopo
Descrizione dell’involucrometadata.description su ogni entitàEditore del catalogoRiepilogo dell’entità nel suo insieme, mostrato nelle schede hover dell’editor e impresso sull’artefatto pubblicato
Descrizione dell’istanzaCampo description accanto a una dichiarazione per istanza (per es. featuresSchema.<slot>.description, usesSchema.<socket>.description)Autore dello schemaDescrizione per slot / per socket / per porta, per gli autori delle entità consumatrici che leggono la dichiarazione
Descrizione del campoAnnotazione description: di JSON Schema 2020-12 all’interno del contenuto di schema: / featuresSchema: / usesSchema: (forma compatta o JSON Schema completo in YAML)Autore dello schemaDocumentazione 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.description una volta per l’entità Component stessa.
  • Imposta featuresSchema.admin_password.description una volta per ogni slot di credenziale che il Component dichiara.
  • Imposta annotazioni description: per campo all’interno del blocco schema: — 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.schema ed è troncato alle sue righe iniziali, quindi una descrizione più in profondità nel blocco — o una all’interno di featuresSchema: o usesSchema: — non vi compare.
  • Descrizione dell’istanza — dichiarata e trasportata con l’entità; nessuna superficie distribuita la mostra da sola. aggrega inspect elenca 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 aggiuntiviMotivazione
Componentmetadata.labels.component.aggrega.ai/typeIl 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
Recipespec.capability, spec.implementsCapability determina il dispatch al provider; implements determina il binding al Component
FeatureRecipespec.capability, spec.implementsCome per Recipe
Pluginmetadata.pluginType, spec.abiVersionIl 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
Manifestspec.mappingsI livelli di mappatura sono l’unico scopo del Manifest
Releasespec.aggregate, spec.manifest (una Release che dichiara extends non scrive aggregate e può omettere manifest); metadata.environmentI 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 requisito metadata.labels.component.aggrega.ai/type del Component e le dichiarazioni schema / usesSchema / featuresSchema.
  • entities/release.md — il campo metadata.environment della 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 esegue aggrega 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.