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

Manifest

Il ruolo concettuale dell’entità Manifest (Dominio 4 — la tabella di mappatura che associa interfacce astratte a Recipes concrete) è descritto in architecture/04-entity-taxonomy.md. Questa pagina tratta la superficie di authoring del Manifest: come si affianca alla Release, la forma della mappatura a URI piatti, la composizione tramite extends, le regole di abbreviazione degli URI, i binding di Feature guidati dalle annotazioni e il prefisso aggrega.ai/ riservato dalla piattaforma.

Manifest e Release: separazione delle responsabilità

Il Manifest e la Release hanno responsabilità che non si sovrappongono:

  • Il Manifest stabilisce quale Recipe realizza ciascun tipo del catalogo e, tramite lo spec.capability di quella Recipe, il provider (ad es. Helm, Helm-chart, Compose) che lo renderizza. È la tabella di mappatura — una registrazione per progetto, sottoposta a commit in Git, di quale Recipe concreta implementa ciascuna interfaccia astratta; le versioni e i digest a cui una build vincola quelle Recipes sono fissati separatamente, nel lockfile di ciascuna Release.
  • La Release stabilisce la destinazione (ad es. la cartella di output fisica per la generazione di artefatti GitOps). È il router del deployment — una descrizione per ambiente di dove finiscono gli artefatti compilati.

Lo schema della Release non contiene alcun campo provider a nessun livello di annidamento; il dispatch del provider appartiene esclusivamente al Manifest.

Il percorso di compilazione. Quando un utente esegue aggrega build --release release.yaml, il compilatore risolve gli artefatti fisici unendo entrambe le fonti:

  1. Lettura della destinazione. Il compilatore esamina i confini della Release — ad esempio, il confine ovh-cluster-3 contiene il componente user-db (tipo: core/postgres:1.0.0).
  2. Scansione del Manifest. Apre il Manifest a cui la Release punta tramite il suo campo manifest:.
  3. Ricerca a due livelli. Controlla prima il livello name per "user-db". Se non lo trova, controlla il livello type per "core/postgres:1.0.0" (con versione), poi "core/postgres" (senza versione).
  4. Risoluzione della Recipe. Il valore della voce corrispondente è un URI di Recipe; la Recipe che nomina dichiara in spec.capability quale provider la renderizza.
  5. Generazione dell’output. Il compilatore ora conosce la cartella di destinazione (dist/boundaries/ovh-cluster-3/), il provider (rendering Helm tramite Wasm) e l’artefatto (il codice sorgente della Recipe). I confini GitOps ahead-of-time sono rispettati da un capo all’altro.

Mappatura URI piatta

Il blocco mappings: del Manifest è una mappa piatta da URI di tipo di componente a URI di Recipe (e da URI di tipo di funzionalità a URI di FeatureRecipe). La mappatura è agnostica rispetto alla capacità a livello di Manifest; la determinazione della capacità deriva dal campo spec.capability di ciascuna Recipe risolta al momento del rendering, non dalla forma strutturale del Manifest. Il blocco organizza le mappature sotto due chiavi di primo livello:

  • components.type mappa un URI di tipo di componente a un URI di Recipe. Ogni istanza di componente del tipo dichiarato si risolve nella Recipe specificata. La mappatura è uno-a-uno per tipo di componente. Una chiave che non nomina il tipo esatto di un’istanza la raggiunge comunque tramite la base del tipo, quando nessuna chiave nomina quel tipo esatto e nessun’altra chiave è scritta per la stessa base — quindi una chiave scritta senza versione (core/postgres), o una che nomina un’altra versione (core/postgres:1.0.0), può raggiungere un’istanza di core/postgres:2.0.0 — ma la Recipe che nomina deve implementare la versione propria di ciascuna di queste istanze: un’istanza di core/postgres:2.0.0 raggiunta in questo modo e mappata a una Recipe che dichiara implements: core/postgres:1.0.0 interrompe la build. Mappa un’istanza del genere, con una chiave che nomina la sua versione (core/postgres:2.0.0), a una Recipe che la implementa.
  • features.type mappa un URI di tipo di funzionalità a un URI di FeatureRecipe. Ogni collegamento di Feature del tipo dichiarato si risolve nella FeatureRecipe specificata. Le Features di credenziali (etichettate feature.aggrega.ai/kind: secret) risiedono nella stessa mappa features.type delle Features operative — il modello unificato dell’entità Feature.

Ogni blocco accetta anche un livello name accanto a type, che mappa uno specifico nome di istanza a un URI di Recipe (o di FeatureRecipe). Il livello del nome ha la precedenza sul livello del tipo: un’istanza nominata in components.name si risolve in quella Recipe, mentre ogni altra istanza dello stesso tipo si risolve tramite components.type. Questo esprime una sostituzione per istanza — due istanze di uno stesso tipo di componente possono essere distribuite tramite due Recipes diverse (ad esempio, la maggior parte delle istanze di database usa la Recipe mappata in blocco mentre un’istanza è fissata a un’implementazione fisica diversa), senza fare il fork del tipo di componente né duplicare il Manifest. La sostituzione si applica in modo uniforme: l’istanza nominata esegue il rendering tramite la Recipe di sostituzione e fissa da essa anche la propria sorgente. features.name è il livello simmetrico per i collegamenti di Feature, indicizzato dal nome proprio del collegamento — la chiave sotto cui è scritto nel features: di un componente — mai dal nome del componente a cui è collegato. L’esempio di sostituzione della ricetta per istanza illustra da cima a fondo un caso minimo con due istanze.

Un collegamento portato da una connessione è indicizzato dal nome che assume sul componente consumatore: <alias>.<slot>, l’alias sotto cui è scritta la connessione, un punto e lo slot che il collegamento occupa (vedi la voce di connessione dell’Aggregate). Così la credenziale di una connessione può essere realizzata in modo diverso da ogni altro collegamento del suo tipo:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

La voce è fissata e verificata come qualsiasi altra voce del livello del nome, come descrive il paragrafo successivo. Anche la Feature che il collegamento nomina è fissata e verificata, esattamente come la Feature di un collegamento scritto sul componente stesso, sotto la voce di connessione scritta dal suo autore — vedi Il lockfile.

Una chiave name deve nominare qualcosa che la build contiene. Il livello viene confrontato per nome esatto, quindi una chiave components.name che non è un’istanza di componente nella build, o una chiave features.name che non vi è un collegamento — molto spesso il nome del componente su cui si trova un collegamento, scritto dove va il nome proprio del collegamento — non verrebbe consultata da nulla, e le istanze a cui era destinata si risolverebbero silenziosamente tramite il livello type. La build si interrompe invece su una chiave del genere, prima che venga eseguito qualsiasi rendering, nominando il Manifest, la chiave, i nomi di quel genere che la build contiene e il nome che probabilmente intendevi — vedi A Manifest name mapping names nothing in the build (Una mappatura per nome del Manifest non nomina nulla nella build).

Una realizzazione vincolata per nome è fissata e verificata come una vincolata per tipo. aggrega pull acquisisce ogni Recipe e FeatureRecipe che uno dei due livelli vincola — da una directory di catalogo, dalla cache o da un registry — e registra ciascuna nel lockfile della Release con la sua versione risolta e il suo digest di contenuto, sotto la voce di mappatura che la vincola: manifest.spec.mappings.components.name.<instance> per una voce del livello del nome, accanto a manifest.spec.mappings.components.type.<type> per una del livello del tipo. aggrega build vincola ciascuna di esse al proprio pin. Un lockfile che non registra alcuna riga per una realizzazione che il Manifest vincola interrompe la build come non aggiornato, nominando la realizzazione e la voce che la vincola; una realizzazione il cui contenuto è cambiato dal pull la interrompe allo stesso modo, nominando entrambi i digest. In entrambi i casi aggrega pull --release <release> registra la realizzazione così com’è ora. Come una voce type, una voce name è fissata indipendentemente dal fatto che la Release dichiari un’istanza con quel nome, quindi una voce name che nomina una Recipe che nessun catalogo o registry contiene interrompe il pull; anche una voce name che non nomina alcuna istanza contenuta nella build è fissata, e interrompe la build come descritto nel paragrafo precedente.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Determinazione della capacità al momento del rendering. La voce del Manifest vincola un tipo di componente a un URI di Recipe. Un URI di Recipe ha al massimo due segmenti — una capacità iniziale facoltativa, poi il nome della ricetta — più un :version facoltativo; il resolver divide solo sulla prima /, quindi un riferimento con un terzo segmento non nomina alcuna ricetta e interrompe la risoluzione. Al momento del rendering, il resolver carica la Recipe tramite ricerca diretta per URI nel lockfile e nel catalogo, e il campo spec.capability di ciascuna Recipe determina il raggruppamento del dispatch per (percorso, capacità). La forma strutturale del Manifest resta piatta indipendentemente da quanti provider supporti il catalogo più ampio.

Ricerca diretta per URI

Il valore di mappatura del Manifest è un URI di Recipe. Il compilatore risolve l’URI direttamente rispetto al lockfile e al catalogo, restituendo la Recipe corrispondente. Non itera sulle dichiarazioni spec.implements per trovare una Recipe che «implementi» un tipo di componente. Ogni voce del Manifest vincola il tipo di componente scritto dallo sviluppatore a uno specifico URI di Recipe; la scelta è esplicita e non ambigua nel contenuto del Manifest.

spec.implements è un controllo di coerenza sulla tabella di mappatura. Il valore spec.implements della Recipe risolta DEVE corrispondere alla chiave di tipo di componente del Manifest per quella voce di mappatura — o a una base che quella chiave extends, a qualsiasi profondità della catena, poiché una Recipe scritta per una base implementa tutto ciò che la estende. Un valore che non corrisponde a nessuna delle due produce un OPS_ERROR con un diagnostico chiaro che nomina la voce del Manifest, la Recipe risolta e il valore spec.implements in conflitto. Il controllo scatta una volta per voce di mappatura del Manifest, sul Manifest composto e prima che qualsiasi Recipe venga risolta — statico, deterministico e senza percorrere nulla oltre la catena extends del tipo mappato stesso. Una chiave components.type che raggiunge un’istanza di componente a una versione che non nomina viene giudicata ancora una volta per quell’istanza, allo stesso modo, con il tipo proprio dell’istanza, alla versione con cui la build la compila, al posto della chiave, come descrive Mappatura URI piatta. Vedi ../vocabulary/inheritance-and-interface.md per ciò che la Recipe di una base risparmia e non risparmia a una specializzazione.

Ogni comando che legge le dipendenze di una Release lo esegue, e ciascuno decide da sé cosa significa un rilievo: aggrega build e aggrega pull si interrompono, poiché entrambi producono qualcosa che useresti in seguito, mentre aggrega validate e aggrega lint lo segnalano insieme al resto dei loro rilievi e terminano con un codice diverso da zero, e l’editor lo pubblica come un diagnostico tra gli altri. aggrega lint è l’eccezione per il giudizio di un’istanza: giudica le voci di mappatura e non le istanze che queste raggiungono, quindi non lo segnala, mentre aggrega build, aggrega pull e aggrega validate --release lo fanno. Vedi ../errors/fatal-halts.md per il diagnostico e come correggerlo.

Il controllo di coerenza è l’unica superficie di mappatura che legge la catena extends. La selezione della Recipe resta esatta sulla chiave di mappatura: un tipo di componente che estende una base mappata ha comunque bisogno di una propria voce qui, e non ne ottiene alcuna per ereditarietà.

spec.implements suggerisce anche dei candidati. Un’istanza il cui tipo non ha alcuna mappatura nel Manifest interrompe la build con un OPS_ERROR che elenca come candidate da fissare le ricette il cui spec.implements è in grado di implementare quel tipo; il completamento dell’editor su un valore di mappatura mette per prime quelle stesse ricette corrispondenti. Entrambe le superfici leggono spec.implements rispetto al tipo richiesto stesso, quindi una ricetta che implementa una delle basi di quel tipo non viene proposta come candidata anche se la mappatura sarebbe giudicata coerente. spec.implements dichiara quindi cosa una ricetta può implementare e orienta la scelta della persona — nel controllo di coerenza, nel diagnostico di mappatura mancante e nel completamento — ma non risolve mai una build. La mappatura del Manifest è la scelta di distribuzione esplicita dell’utente, fissata nel lockfile per la riproducibilità; il catalogo non sceglie mai una distribuzione al posto dell’utente.

Tre forme per il segmento di versione dell’URI

Un URI di Recipe nel Manifest può riportare la versione in una qualsiasi di tre forme:

  • Esatta — helm/postgres:1.2.0. Il lockfile deve fissare esattamente questa versione; alla prima risoluzione del lockfile, il resolver fissa questa versione; se il catalogo o il registry non contiene questa versione al momento della risoluzione, il caricamento del workspace si interrompe con un errore.
  • Intervallo — helm/postgres:^1.2.0. Intervallo semver con la regola MVS standard; alla prima risoluzione del lockfile, il resolver fissa la versione disponibile più alta che soddisfa l’intervallo.
  • Senza versione — helm/postgres. Nessun suffisso :version; alla prima risoluzione del lockfile, il resolver fissa l’ultima versione disponibile.

Le build successive usano la versione fissata nel lockfile indipendentemente dalla forma digitata dall’utente. Risolvere di nuovo verso una versione più recente richiede un’azione esplicita dell’utente — aggrega pull --upgrade --release <release> <uri> risolve di nuovo una singola dipendenza mantenendo ogni altro pin, oppure aggrega pull --upgrade --release <release> le risolve di nuovo tutte — il lockfile è la fonte di verità per le build; la forma digitata dall’utente è il modo in cui l’utente esprime il vincolo di versione al momento della scrittura.

Riferimenti qualificati per capacità

L’identità di una Recipe nel catalogo ha ambito di capacità: due ricette possono condividere un metadata.name e una versione dichiarando valori spec.capability diversi. L’identità nel registry è recipe/{capability}/{name}:{version}, derivata dal tipo della ricetta, dal suo spec.capability senza alcun pin di versione che esso riporti, e dal suo nome; l’albero del catalogo della libreria standard rispecchia quella coordinata in recipe/{capability}/{name}/ per convenzione. Un valore di mappatura del Manifest nomina la ricetta con l’una o l’altra precisione:

  • Semplice — mariadb:1.0.0. Si risolve quando esattamente una ricetta nel catalogo porta quel nome; la forma prevalente nella pratica.
  • Qualificata per capacità — compose/mariadb:1.0.0. Il segmento prima della prima / nomina il spec.capability della ricetta, senza il suo pin di versione — un pin scritto nel riferimento viene rifiutato (E0095). Obbligatoria quando più di una ricetta distribuisce lo stesso nome: un riferimento semplice che corrisponde a due ricette è ambiguo e si interrompe in modo esplicito durante la risoluzione invece di sceglierne una silenziosamente.

Un URI di Recipe non ha altre posizioni. Il resolver divide solo sulla prima /, quindi compose/mariadb nomina la capacità compose e la ricetta mariadb, e un riferimento a tre segmenti non corrisponde ad alcuna ricetta con nessuna delle due precisioni.

Le forme del segmento di versione descritte sopra si applicano a entrambe le varianti.

Entità pubblicate in un registry nelle mappature

Un’entità consumata da un registry anziché da un catalogo locale viene referenziata esattamente con la stessa identità usata da una locale: il riferimento non riporta alcun host di registry né alcun segmento di tipo di entità. Il resolver fornisce entrambi — l’host dal registry predefinito configurato nel workspace, il segmento di tipo dalla posizione del riferimento nello schema — secondo le regole degli URI abbreviati sensibili al contesto più sotto. Quando né una directory di catalogo locale né la cache ne contengono una copia, aggrega pull — o una build eseguita con --auto-pull — recupera l’entità dalla posizione derivata, la mette in cache e fissa la versione risolta e il digest di contenuto nel lockfile; le build successive consumano la cache senza accesso alla rete.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Poiché l’host e il segmento di tipo di entità sono derivati anziché scritti, scriverli nel riferimento non indirizza l’entità pubblicata — produce un’identità che nessuna voce del catalogo porta. Un riferimento a un Component o a una Feature è il suo metadata.name testuale più un :version facoltativo, che l’entità si risolva dal catalogo locale, dalla cache o da un registry. Un workspace che consuma un registry privato nomina quell’host nella propria configurazione anziché in ogni riferimento.

Controllo di completezza

Dopo che tutte le mappature sono state risolte, il compilatore verifica che ogni istanza di componente e di collegamento (una Feature di credenziali è un collegamento come qualsiasi altro) nell’Aggregate dello sviluppatore abbia una Recipe o una FeatureRecipe risolta. Le entità non mappate causano un arresto fatale con un diagnostico esplicito che elenca ogni entità mancante e suggerisce quale chiave components.type o features.type aggiungere per colmare la lacuna.

Ancore YAML per manifest DRY

Per evitare il gonfiamento dello YAML in grandi insiemi di mappature, il Manifest supporta un blocco defs: facoltativo per le ancore YAML standard (& e *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Negoziazione delle Feature

L’handshake di capacità usa la stessa mappatura URI piatta:

  1. Lo sviluppatore collega core/data-masking a un componente nell’Aggregate, sotto un nome proprio nella mappa features: di quel componente.
  2. Il compilatore cerca core/data-masking nella mappa features.type del Manifest.
  3. Se la ricerca si risolve in un URI di FeatureRecipe (ad es. helm/data-masking-litellm:1.0.0), la capacità esiste e la pipeline della FeatureRecipe viene eseguita nell’ordine definito.
  4. Se features.type non contiene alcuna voce corrispondente, il compilatore interrompe la build ed elenca la Feature non mappata.

Il Manifest accetta anche un blocco features.annotations — una superficie di authoring parallela che consente a un sottosistema di una Release o di un Aggregate di collegare Features tramite chiave di annotazione anziché tramite dichiarazione per componente. La forma del binding, la partizione side-vs-pillar che stabilisce quale superficie di authoring usa quali percorsi di instradamento, la disciplina per cui vince il collegamento esplicito e la regola dei default dello schema si trovano nella sezione dedicata Binding di Feature guidati da annotazioni più avanti.

Composizione tramite extends

Un Manifest può dichiarare un unico riferimento extends: che nomina un Manifest di base di cui eredita i mappings. Il riferimento non è un URI e non viene mai risolto tramite il catalogo: un Manifest appartiene al lato del deployment, scritto accanto alla Release anziché pubblicato, quindi il valore è un percorso relativo a un file di Manifest — ./base-manifest.yaml — oppure il semplice metadata.name di un Manifest che si trova nella directory stessa della Release. Un percorso relativo deve portare a un Manifest all’interno del workspace — oppure, quando la Release è stata indicata fuori dal workspace (sulla riga di comando o dalla configurazione del workspace), all’interno della directory che contiene quella Release, e per un Manifest che indichi da solo sulla riga di comando fuori dal workspace, all’interno della directory che contiene il Manifest: un percorso che ne esce risalendo, o che un collegamento simbolico porta fuori, viene rifiutato prima che il file che nomina venga letto (vedi errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Un riferimento a un altro file esce dalla directory in cui deve restare)”). I mapping del figlio sovrascrivono quelli di base in caso di collisione di chiavi, supportando pattern di overlay per ambiente (parità staging/prod con differenze chirurgiche per ambiente) e pattern di sviluppo locale senza dover copiare tutto.

Semantica di merge. Quando un Manifest locale estende un Manifest di base, il compilatore esegue una sostituzione superficiale delle chiavi per livello — i dizionari type e name vengono uniti indipendentemente, non con un merge profondo — il che garantisce ricerche nei dizionari O(1) e mantiene prevedibile il comportamento dell’ereditarietà. All’interno di ciascun livello, le chiavi del figlio sovrascrivono quelle del genitore.

Il pattern ponte per lo sviluppo locale. Un uso comune di extends è sostituire una FeatureRecipe di credenziali per la prototipazione locale senza toccare l’Aggregate. In produzione, il Manifest di base mappa la Feature di credenziali core/aws-secrets-manager a una FeatureRecipe di produzione nel livello features.type. Per la prototipazione locale, il team di piattaforma fornisce un local-manifest che estende quello di base e sovrascrive chirurgicamente il mapping della Feature di credenziali per usare host-env-injector — una FeatureRecipe locale che consegna la credenziale nel file Compose come riferimento a una variabile, ad esempio ${SECRET_NAME}, che Docker Compose sostituisce dall’ambiente della shell o da un file .env all’avvio dello stack. Lo sviluppatore ottiene un flusso di lavoro locale standard, e l’Aggregate resta agnostico rispetto alle capability per la produzione.

URI abbreviati sensibili al contesto

Il compilatore di Aggrega utilizza l’inferenza sensibile al contesto quando risolve gli URI OCI nei Manifests. Se un ingegnere omette il Fully Qualified Domain Name (FQDN) e il tipo di entità architetturale, il compilatore ripiega automaticamente sul registry predefinito (configurato in .aggrega-config.yaml) e deduce il tipo di entità in base alla posizione della stringa nello schema.

Le regole di inferenza:

  1. Dominio predefinito: a qualsiasi URI privo di dominio (ad es. python-worker-helm:1.0) viene anteposto il default_registry configurato (predefinito: hub.aggrega.ai/).
  2. Espansione contestuale dell’entità: il compilatore aggiunge il percorso di entità corretto in base al dizionario rigoroso dello schema:
    • Le stringhe sotto Aggregate.spec.components[].type si espandono in /component/.
    • Le stringhe sotto Aggregate.spec.aggregates[].type si espandono in /aggregate/.
    • Le stringhe sotto Manifest.spec.mappings.components.type o Manifest.spec.mappings.components.name si espandono in /recipe/.
    • Le stringhe sotto Manifest.spec.mappings.features.type o Manifest.spec.mappings.features.name si espandono in /featurerecipe/. Ciò include le Features di credenziali (etichettate feature.aggrega.ai/kind: secret) — usano lo stesso percorso della FeatureRecipe.
    • Le stringhe assegnate a pipeline[].plugin si espandono in /plugin/.
  3. Precedenza a tre livelli: prima di applicare l’inferenza OCI, il compilatore cerca nelle directory di catalogo del workspace e nella cache degli artefatti (il livello workspace e cache), come definito nel modello di risoluzione delle entità a tre livelli. L’inferenza OCI si applica solo quando l’entità raggiunge il livello del registry. Una chiave o un valore di mapping non viene mai letto come percorso di file: una Recipe o una FeatureRecipe scritta localmente si trova in una directory di catalogo — catalog/ nella radice del workspace, o una di quelle elencate da workspace.catalog_dirs — ed è indicata dal suo riferimento.

L’abbreviazione in azione:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

Nessun prefisso ops/. I nomi delle Recipe non hanno alcun prefisso ops/ — la directory del tipo di entità recipe/ nella tassonomia OCI identifica già il dominio, e le Recipes vengono distribuite sotto recipe/{capability}/{name} senza prefissi aggiuntivi. I Manifests fanno riferimento alle Recipes tramite {capability}/{name}, o tramite il nome semplice per l’inferenza sensibile al contesto. Vedi architecture/13-catalog-and-registry.md §6 per la tassonomia OCI completa.

Binding di Feature guidati dalle annotazioni

Il blocco features.annotations del Manifest dichiara i binding tra chiavi di annotazione e tipi di Feature, oltre ai percorsi di instradamento attraverso cui ciascun binding invia il valore dell’annotazione. Il binding è la superficie di authoring per comprimere i collegamenti di Feature ripetitivi per singolo component — il pattern in cui decine di component all’interno di un confine portano ciascuno un blocco features: identico — in singole dichiarazioni di annotazione sui confini della Release o sui sottosistemi dell’Aggregate.

Forma dello schema:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Un binding porta un campo feature che nomina il tipo di Feature di destinazione e un blocco maps che raggruppa le rotte delle sottochiavi in percorsi puntati per pilastro di destinazione. Il campo feature fa riferimento a un tipo di Feature che deve comparire anche nella sezione sorella features.type (dove risiede il binding di versione della FeatureRecipe). Il blocco maps dichiara due liste indicizzate per pilastro — maps.infra e maps.values — ciascuna con stringhe di percorsi puntati che rimandano alle proprietà spec.schema.<pillar>.<path> della Feature di destinazione. Un binding deve dichiarare almeno un percorso tra le due liste (il JSON Schema impone minProperties: 1 su maps).

Il polimorfismo del Provider per la stessa chiave di annotazione — ad es. feature.aggrega.ai/rewrite-host legata a core/k8s-dns-resolver in un deployment Kubernetes ma a core/compose-bridge in un deployment Compose locale — si esprime scegliendo tipi di Feature diversi in Manifests diversi; ciascun Manifest lega l’annotazione a una sola Feature, e la FeatureRecipe della Feature scelta contiene l’implementazione specifica del provider.

La partizione lato-pilastro. L’invariante dell’Aggregate come superficie di authoring limita ogni lato di authoring ai percorsi di instradamento di un solo pilastro. Le annotazioni lato Aggregate vengono instradate solo attraverso i percorsi maps.values; le annotazioni lato Release solo attraverso i percorsi maps.infra. Un binding che dichiara percorsi in entrambi i pilastri supporta la composizione tra lati: un’annotazione lato Aggregate attiva il sottoinsieme del pilastro values; un’annotazione lato Release sulla stessa chiave attiva il sottoinsieme del pilastro infra; entrambi i contributi si compongono in un unico collegamento di Feature per coppia (Component, Feature) con entrambi i pilastri popolati. Una mancata corrispondenza lato-pilastro — ad es. un’annotazione lato Aggregate su un binding che dichiara solo maps.infra — arresta la build con una diagnostica chiara che nomina la chiave di annotazione, il pilastro instradato, il lato di authoring e la posizione nel sorgente, classificata sotto il dominio del documento in cui è stato scritto il valore dell’annotazione.

Validazione delle destinazioni dei percorsi. Al caricamento del catalogo, il compilatore verifica che ogni percorso puntato dichiarato sotto maps.infra e maps.values corrisponda a una proprietà effettivamente dichiarata da spec.schema.<pillar> della Feature di destinazione. Un binding che instrada verso un percorso non elencato nello schema della Feature arresta il caricamento del catalogo con un OPS_ERROR chiaro, che nomina il binding, la Feature di destinazione, e il pilastro e il percorso attraverso cui ha instradato. Le forme di schema che sfuggono a una semplice visita delle proprietà ($ref, patternProperties, composizione oneOf / anyOf / allOf) terminano il controllo statico in quel ramo e lasciano che la validazione dello schema a valle intercetti qualsiasi mancata corrispondenza.

Forme dei valori di annotazione. Un binding consuma valori di annotazione in tre forme. Scalare — un singolo valore YAML (stringa, numero, booleano). Uno scalare abbinato a un binding che dichiara esattamente un percorso tra entrambi i pilastri instrada il valore verso quel singolo percorso; uno scalare abbinato a un binding che dichiara più di un percorso costituisce un instradamento ambiguo e arresta la build con una diagnostica chiara, classificata sotto il dominio del documento in cui è stato scritto il valore dell’annotazione. Strutturato — una mappa YAML le cui sottochiavi di primo livello corrispondono ciascuna a una voce di percorso puntato sotto maps.infra o maps.values; ogni sottochiave viene instradata indipendentemente verso il pilastro dichiarato, e la partizione lato-pilastro si applica per sottochiave. null YAML esplicito — esclude il binding ereditato nell’ambito della cascata (con un null per sottochiave all’interno di un valore strutturato che esclude singole sottochiavi mentre le sorelle restano). Per la guida di riferimento sull’authoring dei valori strutturati — merge a cascata per sottochiave, composizione tra lati, validazione del tipo per sottochiave, la disciplina del default rilassato per i campi di schema senza un type dichiarato — vedi providers/well-known-annotations.md §“Valori di annotazione strutturati”.

Il collegamento esplicito prevale in caso di collisione di chiavi. Quando un component di Release o un component di Aggregate porta sia una voce features: esplicita sia un’annotazione che si espande nella stessa chiave di Feature, la voce esplicita viene preservata e l’espansione dell’annotazione per quella chiave su quel component non ha effetto. Il collegamento sintetico non sovrascrive mai un’istanza di Feature dichiarata dall’autore. Gli autori possono quindi usare l’espansione delle annotazioni per la maggior parte dei component e sovrascrivere chirurgicamente singoli component scrivendo una voce features: esplicita con la stessa chiave — la voce esplicita porta la personalizzazione per component, l’annotazione si propaga in cascata invariata a ogni altro component.

L’esplicito prevale per foglia nella composizione tra lati. Quando un collegamento esplicito e un contributo di annotazione popolano entrambi la stessa istanza di Feature ma scrivono foglie diverse, entrambi i contributi restano e la Feature risultante porta entrambe le foglie, con una provenienza per foglia che registra l’origine di ciascuna. Quando un collegamento esplicito e un contributo di annotazione puntano alla stessa foglia all’interno dello stesso pilastro, prevale il contributo esplicito e l’IR registra la provenienza dell’annotazione soppressa come marcatore di override su quella foglia. Il caricamento del catalogo fa emergere questo override in fase di build tramite un avviso lint consultivo che nomina la chiave di annotazione soppressa + l’origine.

Default dello schema al momento dell’espansione. Il collegamento di Feature sintetico prodotto dall’espansione delle annotazioni porta solo le foglie che il valore dell’annotazione popola attraverso i percorsi dichiarati dal binding. I default dello schema dichiarati su spec.schema della Feature di destinazione non vengono uniti al collegamento sintetico al momento dell’espansione. La materializzazione dei valori predefiniti è responsabilità del livello di rendering della FeatureRecipe, applicata in modo uniforme ai collegamenti espliciti e sintetici, così che i due percorsi producano lo stesso output a valle per la stessa configurazione effettiva.

Separazione dei namespace delle annotazioni:

PrefissoProprietarioScopo
aggrega.ai/Solo la piattaforma AggregaAnnotazioni native della piattaforma lette direttamente dal provider (ad es. aggrega.ai/namespace).
feature.aggrega.ai/Libreria standard ufficialeScorciatoie di annotazione di Feature legate nel Manifest.
{any-other-domain}/Enterprise / communityScorciatoie personalizzate di annotazione di Feature.

Riserva del prefisso aggrega.ai/

I binding features.annotations del Manifest non possono usare il prefisso aggrega.ai/ semplice — è riservato alle annotazioni native della piattaforma emesse dal compilatore (etichette OTel/di provenienza, ecc.). I sotto-prefissi con ambito (component.aggrega.ai/*, compliance.aggrega.ai/*, acme.aggrega.ai/* aziendale) restano disponibili per l’authoring degli utenti. Vedi providers/well-known-annotations per l’insieme di annotazioni riservate alla piattaforma.