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

Catalogo e registro

Questo capitolo definisce come la piattaforma scala a livello aziendale tramite il Catalogo OCI (Open Container Initiative): come è organizzato il catalogo, come si risolve un riferimento, come un’entità viene pubblicata e fissata, e le forme dei nomi che le entità del catalogo seguono.

Il catalogo Aggrega: tassonomia e risoluzione del registro

Il compilatore Aggrega si basa su un registro rigorosamente tipizzato e ispirato a OAM per risolvere l’intento astratto dello sviluppatore (Dominio 1) nella realtà concreta delle Ops (Dominio 3). Per supportare un ecosistema aperto e distribuito mantenendo un’esperienza di sviluppo fluida, tutti gli schemi, i binding dell’infrastruttura, le policy programmabili e i plugin adattatori seguono una tassonomia di URI standardizzata Open Container Initiative (OCI). Poiché ogni entità del catalogo è indirizzabile tramite URI, aggrega pull recupera nella cache quelle di cui una Release ha bisogno e le fissa nel suo lockfile, e una build le legge da lì. Il workspace locale dello sviluppatore contiene solo i suoi file Aggregate e Release, non una copia del catalogo.

1. Struttura delle directory principale (il catalogo)

La cartella aggrega-catalog della libreria standard (e qualsiasi catalogo di terze parti conforme) è organizzata in modo da imporre fisicamente la separazione delle responsabilità. La struttura separa esplicitamente le interfacce astratte dalle loro implementazioni concrete dell’infrastruttura.

Per i Components e le Features, i segmenti dell’URI corrispondono 1:1 ai segmenti del percorso nel filesystem. I Components usano un URI a tre segmenti ({publisher}/{category}/{name}) in cui il segmento della categoria contiene una tra un insieme chiuso di categorie cognitive — la stessa parola dell’etichetta component.aggrega.ai/category del componente (lo specchio 1:1 della directory, verificato dalla regola category-matches-directory del linter di pubblicazione). Le Features restano piatte ({publisher}/{name}) — un insieme piccolo, che cresce lentamente. La classificazione ontologica operativa (stateful-server, server, ecc.) risiede nell’etichetta component.aggrega.ai/type, mai nella struttura delle directory; le etichette di capacità cognitive (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) vi sovrappongono sottoinsiemi comportamentali. L’interfaccia web dell’hub usa le etichette per il filtraggio e la ricerca; le categorie servono sia alla navigazione nel filesystem sia all’asse di consultazione del catalogo.

L’albero seguente è illustrativo nei contenuti ed esatto nella forma. Dove un’entità è disegnata per intero, scende fino al suo file foglia, così che dal diagramma si possa leggere un intero percorso reale: quale livello di directory contiene quale segmento dell’URI, dove si trova il segmento di versione obbligatorio e quale nome di file usa ogni tipo di entità nella foglia. Mostra una manciata di voci per livello anziché l’intero contenuto del catalogo — ... indica un’omissione, e i nomi scritti accanto sono ulteriori voci allo stesso livello.

aggrega-catalog/
│
├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions
│ │ # Shared shapes (BaseComponentParameter,
│ │ # BaseDatastoreParameter) consumed from a Component or
│ │ # Feature schema via $ref: <Library>#/schemas/<name>
│ │ # Path: {name}/{version}/library.yaml
│ │
│ ├── ai-datastores/
│ │ └── 1.0.0/
│ │ └── library.yaml
│ └── base-components/
│ └── 1.0.0/
│ └── library.yaml
│
├── workloadlibrary/ # TIER 3: Reusable Workload template fragments
│ │ # Shared bodies (StatelessService) consumed from a
│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }
│ │ # Path: {name}/{version}/library.yaml
│ │
│ └── base-workloads/
│ └── 1.0.0/
│ └── library.yaml
│
├── component/ # DOMAIN 2: Abstract Interfaces
│ │ # URI: {publisher}/{category}/{name}
│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml
│ │ # type: core/datastore/mariadb:1.0.0
│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml
│ │
│ ├── core/ # "core" = official Aggrega standard library
│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns
│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …
│ │ ├── ai-model/ # model providers and inference runtimes
│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …
│ │ ├── ai-tool/ # tools agents invoke
│ │ │ └── ... # browser, mcp, search, …
│ │ ├── ai-pipeline/ # AI data/processing pipelines
│ │ │ └── ... # argo-workflows, temporal
│ │ ├── datastore/ # persistent datastores
│ │ │ ├── mariadb/
│ │ │ │ └── 1.0.0/
│ │ │ │ └── component.yaml
│ │ │ ├── postgres/
│ │ │ │ └── 1.0.0/
│ │ │ │ └── component.yaml
│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …
│ │ ├── gateway/ # API and AI gateways
│ │ │ └── ... # apisix, contour, kong, nginx, …
│ │ ├── compute/ # generic compute primitives
│ │ │ └── ... # function, keda, server, task, worker, …
│ │ ├── messaging/ # event buses, queues
│ │ │ └── ... # kafka, nats, rabbitmq, …
│ │ ├── observability/ # metrics, logs, traces
│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …
│ │ ├── security/ # identity, secrets, certificates
│ │ │ └── ... # cert-manager, external-secrets, keycloak, …
│ │ ├── devtool/ # developer-facing tooling
│ │ │ └── ... # adminer, promptlayer, …
│ │ └── storage/ # object/file storage, and the backup controllers
│ │ │ # that copy a cluster's resources, or its
│ │ │ # volumes' files, into a bucket
│ │ ├── s3-object-store/
│ │ │ └── 1.0.0/
│ │ │ └── component.yaml
│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …
│ └── example/ # a second publisher, same three-segment shape
│ └── compute/
│ └── greeter/
│ └── 1.0.0/
│ └── component.yaml
│
├── feature/ # DOMAIN 2: Abstract Interfaces
│ │ # Flat: {publisher}/{name} (no category segment)
│ │ # Path: {publisher}/{name}/{version}/feature.yaml
│ │ # type: core/data-masking:1.0.0
│ │ # → feature/core/data-masking/1.0.0/feature.yaml
│ │
│ ├── core/
│ │ ├── data-masking/
│ │ │ └── 1.0.0/
│ │ │ └── feature.yaml
│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret
│ │ │ └── 1.0.0/
│ │ │ └── feature.yaml
│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …
│ └── ... # other publishers, same flat shape
│
├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules
│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml
│ └── core/
│ ├── keycloak/
│ │ └── 1.0.0/
│ │ └── aggregate.yaml
│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …
│
├── recipe/ # DOMAIN 3: Concrete Implementations
│ │ # Organized by CAPABILITY (the one a Recipe declares
│ │ # in spec.capability).
│ │ # Path: {capability}/{name}/{version}/recipe.yaml
│ │ # The version directory may bundle the Recipe's own
│ │ # source charts or modules beside recipe.yaml.
│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0
│ │
│ ├── helm/
│ │ ├── mariadb/
│ │ │ └── 1.0.0/
│ │ │ └── recipe.yaml
│ │ └── postgres/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ ├── compose/
│ │ └── mariadb/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ ├── terraform/
│ │ └── mariadb-rds-module/
│ │ └── 1.0.0/
│ │ ├── recipe.yaml
│ │ └── module/ # bundled Terraform source
│ │ ├── main.tf
│ │ └── variables.tf
│ └── cloudformation/
│ └── postgres-rds/
│ └── 1.0.0/
│ └── recipe.yaml
│
├── feature-recipe/ # DOMAIN 3: Concrete Implementations
│ │ # Capability leads the path, same as recipes.
│ │ # Path: {capability}/{name}/{version}/recipe.yaml
│ │
│ ├── helm/
│ │ ├── k8s-secret-from-parameter/
│ │ │ └── 1.0.0/
│ │ │ └── recipe.yaml
│ │ └── public-ingress/
│ │ └── 1.0.0/
│ │ ├── recipe.yaml
│ │ └── chart/ # bundled Helm source
│ │ ├── Chart.yaml
│ │ └── templates/
│ │ └── ingress.yaml
│ ├── compose/
│ │ └── dotenv-secret/
│ │ └── 1.0.0/
│ │ └── recipe.yaml
│ └── ... # terraform, cloudformation
│
└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed
│ # reference to a Wasm artifact. The compiled artifact
│ # is published separately and is not stored here.
│ # Path: {pluginType}/{name}/{version}/plugin.yaml
│
├── linter/
│ └── publishing/
│ └── 0.5.0/
│ └── plugin.yaml
└── provider/ # the directory mirrors metadata.pluginType
├── helm/
│ └── 0.5.0/
│ └── plugin.yaml
└── ... # cloudformation, compose, helm-chart, terraform

Le categorie dei componenti sono un insieme chiuso, ed è quell’insieme — non il filesystem — l’autorità sulle categorie. Un valore di categoria che non ha ancora alcuna entità è vocabolario riservato: l’asse di consultazione resta stabile e un autore sa dove finirà un componente futuro, quindi uno scaffale vuoto è corretto, non un posto vacante in attesa di un occupante. Poiché il catalogo non contiene file segnaposto, la directory per un valore simile viene creata quando arriva la sua prima entità.

L’elenco autorevole — ogni categoria, che cosa contiene, i valori operativi di type che le sue entità portano tipicamente e quali directory esistono — è la sezione Categorie dei Component della guida alle convenzioni del catalogo, pubblicata insieme al catalogo della libreria standard che governa.

L’asse type contiene solo le primitive operative — il vocabolario cognitivo non vi compare mai, e lo schema pubblicato del Component enumera i valori che la chiave riservata accetta, quindi una parola cognitiva scritta lì viene rifiutata al caricamento del documento. La suddivisione in tre assi: type operativo (come l’infrastruttura tratta il componente), category cognitiva (che cosa è, rispecchiata dalla directory) ed etichette di capacità per ruolo (sottoinsiemi comportamentali — un’entità è category: datastore più qualunque valore di datastore.aggrega.ai/engine porti la sua identità di prodotto, quindi core/datastore/qdrant porta vector e core/datastore/redis porta kv, ed entrambi gli assi sono interrogabili). Una capacità la cui verità dipende da ciò che un autore configura non è affatto contenuta nel catalogo: viene iniettata in fase di compilazione dal ruolo label-transform del socket di governance, che legge i values dichiarati dallo sviluppatore. Le categorie puramente AI portano il prefisso ai-; le categorie a duplice uso compaiono senza prefisso, con la connotazione AI espressa dalle etichette di capacità. Le categorie sono scelte in base a come gli utenti navigano e consultano, non a come il compilatore classifica — il vocabolario delle categorie e le etichette di capacità sono termini rispetto ai quali il compilatore confronta i selettori e a cui non attribuisce alcun significato. Il nome di un componente non ripete la sua categoria: il modello OpenAI della libreria standard è core/ai-model/openai, non core/ai-model/openai-model.

2. Lo schema diviso e la pipeline di sintesi del bridge

Per eliminare il boilerplate per singolo Component attorno alle dichiarazioni dei socket di topologia, Aggrega divide la validazione in due parti e controlla ciascuna dove risiede il suo oggetto:

  1. usesSchema (YAML dichiarativo). Dichiara i socket di topologia che un’entità del catalogo offre e assegna a ciascuno un contratto. La CLI Go lo legge nativamente per estrarre le stringhe selector: per il matching delle label durante l’analisi statica e per validare i meccanismi inject consentiti. Ogni voce di socket supporta un campo opzionale required: true (predefinito false) — quando è impostato, il compilatore emette un errore di validazione se in quel socket non è dichiarata alcuna dipendenza. È la controparte per i socket della semantica required: true sulle voci di featuresSchema: entrambe interrompono la build. Dichiarare un socket qui è ciò che fa il catalogo della libreria standard e resta la strada migliore — ma non è l’unico modo in cui uno sviluppatore può tracciare un arco. L’autore di un Aggregate può nominare sul proprio componente un socket che questo usesSchema non dichiara, anche su un’entità che non dichiara alcun usesSchema; un socket ad hoc di questo tipo non porta alcun selettore, alcuna allowlist inject né alcuno schema per arco, proprio perché qui non c’è alcuna voce che li porti. Gli uses di un attachment di una Feature e gli uses per arco di una Release non sono aperti in questo modo — entrambi possono nominare solo un socket dichiarato. Vedi dependency-resolution §«Dominio 2: lo schema diviso» per il contratto completo e per ciò a cui rinuncia un socket ad hoc.
  2. Desugaring. Se gli sviluppatori usano la forma abbreviata ad array YAML (uses: databases: ["db1"]), la CLI la normalizza in una mappa ({"db1": {"target": "db1"}}).
  3. Sintesi del bridge. Il compilatore proietta la tabella degli slot featuresSchema: in un frammento JSON Schema 2020-12 — una proprietà per ogni slot di attachment, che descrive la forma di un riempimento che può vincolarlo, con una keyword di estensione x-aggrega-inject: su uno slot che dichiara una allowlist inject. La validazione JSON Schema ignora le keyword di estensione durante la validazione strutturale, e nulla ne rilegge una dal frammento: un controllo che vuole la allowlist di uno slot legge lo slot stesso. La tabella dei socket usesSchema: non viene proiettata in alcun frammento. Il selector: e l’inject: di un socket restano nel YAML tipizzato scritto dall’architetto e vengono letti da lì, e il valueSchema: / infraSchema: per arco di un socket viene incapsulato e compilato a sé, senza alcun vincolo inventato attorno.
  4. Composizione. L’architetto di piattaforma scrive una dichiarazione schema: rigorosa (forma compatta o JSON Schema 2020-12 completo) che definisce values, infra e provides. Quella dichiarazione è il contratto proprio dell’entità e viene compilata a sé: né il frammento degli slot né la tabella dei socket vi vengono incorporati. Ogni superficie viene verificata dove risiede il suo oggetto, quindi un errore di socket viene segnalato sulla voce di socket scritta dall’architetto anziché su un percorso all’interno del blocco schema: — e l’architetto continua a non scrivere alcun boilerplate uses.

Esempio — una dichiarazione di socket e cosa ne fa il compilatore: Il YAML dell’architetto di piattaforma

spec:
usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema:
values:
ha_mode: { type: boolean, default: false }
infra:
replicas: { type: integer, min: 1 }
provides:
host: { type: string, required: true }
assertions:
# The Architect can write cross-pillar invariants against the unified instance content.
ha-mode-needs-two-databases: |
{{- if eq .values.ha_mode true -}}
{{- if lt (len .uses.databases) 2 -}}
{{- fail "ha_mode=true requires at least two database attachments" -}}
{{- end -}}
{{- end -}}

Cosa ne fa il compilatore La tabella dei socket viene letta come il YAML tipizzato che è: la stringa selector: va al motore nativo di matching delle label, e la lista inject: vincola quali meccanismi di consegna può nominare un arco che passa per quel socket. Il blocco schema: viene compilato separatamente, come contratto values / infra / provides proprio dell’entità. L’analizzatore statico legge la stringa selector: dalla voce di socket scritta dall’architetto — insieme ad appliesTo / appliesToAnyOf dalle entità Feature — e valuta il matching delle label rispetto ai metadata.labels di ciascun target per validare la type safety tra nodi.

Selettori in stile Kubernetes in usesSchema

Il motore nativo di matching delle label del compilatore Go valuta le stringhe di selettore usando la semantica di selezione standard in stile Kubernetes (AND tramite virgola, OR tramite in(), NOT tramite !=/notin()). Questo stesso motore — e la stessa grammatica delle stringhe di selettore — valuta anche i selettori di attachment delle Feature (appliesTo e ciascun elemento di appliesToAnyOf). Il livello dei selettori è strettamente il gate della topologia — le dichiarazioni schema: per pilastro validano il contenuto di values, infra e provides in modo indipendente. Dopo che il compilatore Go ha tracciato gli archi topologici durante la costruzione della topologia, l’analizzatore statico legge le stringhe selector dalle voci di socket scritte dall’architetto e le valuta rispetto alle labels di catalogo del nodo target per validare la type safety tra nodi.

usesSchema:
# 1. The AND Operator (Comma)
databases:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in')
datastores:
selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator
internal_systems:
selector: "compliance.aggrega.ai/data-class!=public"

Un selettore che il motore non riesce a leggere come una delle sue sei forme di requisito — un requisito vuoto, una chiave che contiene spazi o uno tra =, !, (, ) e la virgola, un insieme non chiuso — arresta la build su ogni arco che protegge anziché essere letto come un altro selettore. La grammatica dei selettori elenca le forme e ogni rifiuto.

3. Formati e composizione degli schemi

Per fornire sia una validazione rigorosa sia i metadati standard del catalogo (autore, versione, descrizione), le definizioni del Dominio 2 (Interfacce) e del Dominio 3 (Implementazioni) sono scritte come envelope YAML. Il Dominio 2 utilizza dichiarazioni schema: incorporate espresse in forma compatta (il default; ~15 keyword, trasformate meccanicamente in JSON Schema 2020-12) o in JSON Schema YAML completo.

Perché ogni YAML del catalogo ripete l’envelope. L’envelope (blocco apiVersion, kind, metadata) compare in cima a ogni file del catalogo — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — per quanto breve sia il corpo. La ripetizione è voluta: ogni file è progettato per essere analizzato, validato, sottoposto a lint e ispezionato come artefatto autonomo. Un singolo file scaricato dal registry OCI, inserito in una sandbox di CI o aperto in un editor di terze parti deve contenere abbastanza autodescrizione perché gli strumenti a valle possano identificare quale tipo di entità rappresenta e quale versione dello schema si applica. La posizione della directory non sostituisce mai l’envelope: ogni parser, validatore e linter legge il tipo dell’entità e la versione dello schema dall’envelope. Il costo è un boilerplate meccanico per file; il vantaggio è che la garanzia degli strumenti autonomi vale sulla superficie di distribuzione OCI, sul filesystem locale e sulle superfici IDE / CI / inspect. Gli autori copiano l’envelope dai file esistenti quando scrivono nuovo contenuto del catalogo, oppure partono da aggrega scaffold <kind>, che stampa un documento iniziale per il tipo con apiVersion e kind già compilati.

Per rispettare il principio DRY (Don’t Repeat Yourself, «non ripeterti»), il catalogo impiega due meccanismi di composizione distinti:

  • Voci condivise di SchemaLibrary ($ref: tra documenti): Le definizioni JSON Schema riutilizzabili sono memorizzate in entità di catalogo SchemaLibrary (Tier 3). Vengono referenziate per identità tramite $ref: tra documenti (<library>#/schemas/<entry>, senza host — la versione proviene dal lockfile) da qualsiasi schema di Component o Feature che le consuma. La catena viene percorsa in fase di compilazione. Vedi entities/schemalibrary per la forma di authoring dell’entità libreria e vocabulary/cross-document-ref per la semantica di risoluzione.
  • Ereditarietà singola (extends): Per baseline complete di componenti, le entità possono usare la proprietà extends: "URI". Il compilatore Go legge ricorsivamente la catena dei genitori ed esegue il deep merge dei metadati YAML (sovrascrivendo le label in caso di conflitto e accodando gli array). I due tipi di catalogo si separano poi sui pilastri dei dati. Lo schema: di una Feature si compone con quello della sua base secondo la composizione di JSON Schema 2020-12. Un Component che estende non scrive alcun contenuto di pilastro: scrive il marcatore letterale schema: inherited e riceve il blocco schema: della sua base esattamente come la base lo ha scritto, a ogni profondità di una catena. Ciò che un tale Component compone invece è la struttura — i suoi slot di attachment (featuresSchema), i socket di topologia (usesSchema), la allowlist di self-inject (inject) e le assertions con nome si uniscono tutti lungo la catena. Vedi entities/component per gli esempi di estensione di componenti base e figlio + governance-and-compliance §«Ereditarietà e disciplina di pubblicazione» per ciò che l’ereditarietà risolve per costruzione e ciò che resta una regola di disciplina di pubblicazione.

Vedi entities/component per gli esempi di estensione di componenti base e figlio, e entities/recipe per l’authoring delle Recipe con puntatori e mapper, con esempi completi.

4. La configurazione del workspace (.aggrega-config.yaml)

Il file .aggrega-config.yaml nella radice del workspace è la configurazione del workspace del progetto — la dichiarazione propria del workspace, adatta al controllo di versione come lo sono go.mod o package.json. Per convenzione, la directory .aggrega/ resta fuori dal controllo di versione — elencala in .gitignore, come faresti con node_modules/ o .terraform/.

La sezione workspace è il marcatore della radice: la sua presenza segna la radice del workspace, e contiene solo le directory di catalogo che definiscono la radice — catalog_dirs, e la mappa releases che dà a una Release directory di catalogo proprie. Ogni altra impostazione sta al livello superiore. Molte sono valori singoli; altre sono sezioni che raccolgono sotto un’unica chiave le impostazioni di un singolo aspetto. Ogni campo è opzionale, con valori predefiniti documentati. L’insieme completo e aggiornato delle chiavi di primo livello, ciascuna con tipo, valore predefinito e significato, è generato dallo schema in schema/other/aggrega-config; l’esempio seguente mostra il marcatore della radice insieme ad alcune delle impostazioni a valore singolo:

.aggrega-config.yaml
workspace: # Root marker; presence marks the workspace root
catalog_dirs: # Ordered list of local catalog directories (checked before cache)
- ./aggrega-catalog
default_registry: hub.aggrega.ai # Default registry for unqualified URIs
offline: false # Set true for air-gapped environments
auto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-only
artifact_cache_dir: .aggrega/cache # On-disk artifact cache root

Un blocco signing: contiene i valori predefiniti per la firma degli artefatti usati da aggrega push --sign e aggrega sign, sia al livello superiore (globale) sia per registry:

.aggrega-config.yaml
signing: # Global signing defaults
fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good)
rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good)
timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in)
key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)
registries:
- host: hub.example.com
signing: # Per-registry override of the global signing block
key_path: ./keys/hub.pem

La precedenza per campo è flag della CLI > signing per registry > signing globale > default public-good. Fulcio e Rekor usano per default le istanze public-good di Sigstore, quindi sono opzionali; timestamp_url non ha default — il timestamp attendibile keyless proviene dall’inclusione nel transparency log di Rekor, e un’autorità di timestamp RFC3161 è opt-in (imposta timestamp_url, o --timestamp-url, con un endpoint completo per abilitarne una). Sicurezza: il blocco signing: non contiene materiale segreto — il token di identità OIDC non è mai un campo di configurazione (è un segreto di breve durata, fornito al momento della firma: ottenuto tramite un flusso nel browser in un terminale interattivo o dal workflow su GitHub Actions, e altrimenti passato con --identity-token o esportato come AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN), e la chiave privata non è mai inline; key_path è il percorso di un file di chiave. È l’asimmetria voluta rispetto al lato della verifica, che fissa una chiave pubblica inline, mentre sul lato della firma c’è sempre e solo il percorso di una chiave.

Segna una radice senza cataloghi vendorizzati scrivendo workspace: {}. La lista catalog_dirs supporta configurazioni monorepo in cui un catalogo condiviso risiede in una directory sorella. Il compilatore controlla ogni directory in sequenza. Il flag offline: true impedisce qualsiasi accesso alla rete — il compilatore usa solo percorsi locali e la cache, e si arresta se un’entità non viene trovata localmente. Le impostazioni a sezioni raccolgono ciascuna un aspetto. Tra queste: le manopole di rigore in fase di build e i suggerimenti di authoring; i socket di attachment Wasm a livello di workspace (governance, linter, importer, providers, cli), ciascuno dei quali accetta una lista di riferimenti a plugin; il rigore del lint per regola, compresi gli interruttori delle policy di disciplina di pubblicazione; la messa a punto della cache di parsing del daemon e la dimensione del suo pool di worker per lo smistamento delle richieste; e il limite di dimensione dello store dei moduli compilati condiviso dall’intera macchina. Altre ancora contengono i valori predefiniti per la firma e per la fiducia nelle firme e il comportamento del daemon stesso. Ogni chiave di primo livello è documentata per intero in schema/other/aggrega-config.

Sono configurabili tre cache distinte, e vale la pena distinguerle perché i loro nomi sono simili mentre i loro ambiti non lo sono. artifact_cache_dir indica la cache dei contenuti su disco per workspace descritta più avanti. parse_cache limita la cache di parsing in memoria del daemon, che vive solo quanto il daemon. compiled_module_cache limita lo store su disco del codice macchina dei plugin compilati — una delle cache condivise da tutti i workspace della macchina, perché la forma compilata di un plugin dipende dal plugin e non dal progetto che lo usa:

# .aggrega-config.yaml — most at home in the global config file, since the store is machine-wide
compiled_module_cache:
max_bytes: 53687091200 # Default 50 GiB; 0 disables the cap

Tra le cache che tutti i progetti della macchina condividono, è quella che può arrivare a dominare l’uso della cache su disco, poiché ogni plugin eseguito dalla macchina vi viene compilato una volta e conservato, ed è quindi l’unica con un limite di dimensione permanente. Ogni invocazione che apre lo store applica il limite prima di compilare qualsiasi cosa, rimuovendo voci intere a partire da quelle compilate per prime finché il resto non rientra. (Una build eseguita con --disable-plugin-cache compila invece in memoria, quindi non fa crescere lo store né lo riduce.) Rimuovere una voce costa una ricompilazione successiva e nient’altro, ed è questo che rende sicuro abbassare il limite e applicarlo mentre altre build sono in esecuzione sulla stessa macchina. Impostalo al di sopra di ciò che compila una singola build: poiché il limite viene applicato prima della compilazione, un limite inferiore al working set di una singola build fa sì che ogni build scarti e ricompili gli stessi moduli, e per lo stesso motivo lo store può restare sopra il limite tra una build e l’altra e viene ridotto di nuovo all’inizio della successiva. aggrega cache status riporta la dimensione dello store, e aggrega cache evict --max-size lo riduce su richiesta a un limite indicato sulla riga di comando.

La radice artifact_cache_dir contiene tre sottoalberi paralleli che una singola invocazione di aggrega pull popola in modo uniforme, uno per ogni classe di dipendenza fissata: <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ per le entità di catalogo (Components, Features, Recipes, FeatureRecipes, Aggregates, le librerie e i Plugins con gli eseguibili che pubblicano), dove il tipo è quello con cui l’entità viene pubblicata, così due entità di tipi diversi che condividono un riferimento e una versione — un Component e una Recipe con lo stesso nome — occupano due slot; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ per gli artefatti sorgente scaricati dai campi spec.source di Recipe / FeatureRecipe (chart Helm, frammenti compose); e <artifact_cache_dir>/inputs/sha256/<hex-digest> per gli input esterni — i documenti remoti che un provider chiede all’host durante il rendering, come un $ref nel values.schema.json di un chart che punta a un URL. Ogni slot di cache di un artefatto sorgente contiene l’archivio .tgz autorevole, una directory derivata extracted/ rigenerata a ogni lettura della build e un file metadata.yaml che registra l’identità {kind, url, version, digest, mediatype, pulled_at} dell’artefatto. Ogni slot di cache di un’entità contiene l’artefatto pubblicato così come è stato recuperato e il manifesto OCI rispetto al quale viene verificato. Lo slot di ogni tipo il cui documento può nominare un file accanto a sé — una Recipe, una FeatureRecipe, un Component, una Feature — contiene anche una directory derivata extracted/ con i file che quell’artefatto porta, in una directory denominata dal digest del contenuto dell’artefatto: il documento e i file che l’entità ha dichiarato, dove è stata pubblicata come archivio, e il solo documento, dove è stata pubblicata come documento (§6). La directory dell’entità viene disposta lì a partire dall’artefatto verificato a ogni lettura, così come lo sono i file di un artefatto sorgente: ogni file viene confrontato con l’artefatto, un file modificato o aggiunto a mano in quella directory viene scartato anziché letto, nient’altro sotto extracted/ viene letto, e un artefatto che non supera la verifica viene rifiutato prima che venga disposto qualsiasi cosa. Una lettura riscrive solo ciò che differisce dall’artefatto, quindi le build che leggono una stessa cache contemporaneamente — richieste che aggrega serve gestisce in parallelo, o due comandi sullo stesso workspace — trovano ciascuna integri i file che hanno ricevuto. Il segmento <digest-prefix> di 12 caratteri separa in slot distinti lo stesso {kind, url, version} ritaggato con digest upstream diversi. Un input esterno non ha bisogno di uno slot del genere: viene memorizzato come singolo file denominato dal digest del contenuto a cui il lockfile lo fissa, quindi ciò che una build successiva legge è indirizzato dal pin anziché dall’URL da cui sono arrivati i byte — ed è questo che permette a quella build di servire l’input con la rete negata.

Accanto a queste tre possono comparire altre tre directory, e nessuna di esse contiene contenuto di dipendenze fissate: index/ contiene gli snapshot ricercabili per registry che scrive aggrega registry update (§8), signatures/ memorizza in cache ogni bundle di firma verificato sotto il proprio digest, così che una lettura successiva ricontrolli il blob in cache rispetto al digest con cui è stato registrato anziché recuperare di nuovo il bundle, e catalog-snapshots/ conserva ogni snapshot pubblicato del catalogo letto da un’importazione (§8) — l’archivio e il suo manifest in uno slot denominato dal digest del manifest, con l’albero del catalogo disposto a partire dall’archivio a ogni lettura, e un file current che indica lo snapshot che il workspace legge laddove nient’altro ne indichi un altro.

Il bundle della documentazione non è tra queste. I suoi byte dipendono solo dal registry in cui è pubblicato e dalla versione con cui è pubblicato, quindi viene conservato una volta per macchina, accanto allo store dei moduli compilati sotto la stessa radice di cache per utente, in docs-bundles/<encoded-reference>/<encoded-version>/ sotto quella radice: il bundle, il manifesto rispetto al quale viene verificato e le firme verificate dai suoi recuperi. artifact_cache_dir non lo raggiunge. Prima che una pagina venga letta da esso, quelle firme vengono verificate di nuovo secondo il controllo delle firme proprio del workspace che legge, per il registry del bundle, così che una copia fatta entrare dalle impostazioni più permissive di un workspace non venga servita a un workspace il cui controllo la rifiuta — vedi aggrega-explain e aggrega-cache.

artifact_cache_dir si scrive relativo alla radice del workspace e indica la stessa directory indipendentemente dalla directory da cui viene invocato un comando o da quali directory di catalogo vengono scansionate. Un valore assoluto viene rifiutato al caricamento della configurazione, con una diagnostica che nomina il campo: ogni lettore dell’impostazione la risolve rispetto alla radice del workspace, quindi un percorso assoluto nominerebbe una posizione che nessuno di essi raggiunge, e il fallimento sarebbe altrimenti silenzioso — la cache scritta da un pull smetterebbe silenziosamente di essere la cache letta da una build. La cache può trovarsi all’interno di una directory di catalogo, e nel layout predefinito è così, poiché una directory di catalogo è comunemente la radice stessa del workspace. Ciò che non deve fare è essere una directory di catalogo: una scansione del catalogo salta la cache, quindi una directory di cache che è anche una directory di catalogo esclude da ogni scansione l’intero contenuto di quella directory. artifact_cache_dir: . nomina la radice del workspace, che nel layout predefinito è esattamente questo caso, e viene rifiutato al caricamento della configurazione con una diagnostica che nomina il campo — come qualsiasi altra grafia che si riduce alla radice del workspace. Queste due forme, insieme al percorso assoluto visto sopra, sono quelle che il controllo della configurazione è in grado di riconoscere da solo. Un valore che nomina un’altra directory di catalogo — sub, in un workspace il cui catalog_dirs elenca sub — viene caricato senza obiezioni, e l’unico sintomo è che le entità al suo interno smettono di essere trovate. Tenere la cache fuori da ogni directory elencata in workspace.catalog_dirs fa quindi parte della scrittura della configurazione, e non è qualcosa che essa verifica per te.

Saltare la cache è ciò che impedisce che un artefatto di risoluzione venga letto come se lo avesse scritto un autore. Uno slot di cache contiene byte che vi ha collocato un recupero dal registry, memorizzati sotto la coordinata da cui sono stati recuperati e garantiti da un digest del lockfile; una scansione che ne raccogliesse uno come contenuto di catalogo scritto da un autore prenderebbe byte che nulla ha verificato, su un percorso che l’autore non può modificare. Vale la pena dichiarare apertamente una conseguenza: se la cache contiene un’entità che nessun lockfile fissa — lasciata da un pull interrotto, copiata a mano o rimasta orfana quando una Release ha smesso di referenziarla — quell’entità non è visibile a una scansione del catalogo, e una build o una validazione che ne dipende si arresta dicendo che l’entità non è stata trovata. Il rimedio è eseguire di nuovo il pull della Release, così che l’entità venga risolta tramite il lockfile e il suo digest venga registrato; l’arresto nomina l’entità, così che il pin mancante possa essere identificato. L’alternativa — risolverla comunque — è proprio la lettura non verificata che il salto della cache esiste per impedire.

Il lockfile è per Release: la risoluzione di release.yaml scrive release.lock accanto a esso (il nome base del file della Release più .lock). aggrega pull risolve le dipendenze e scrive il lockfile; aggrega build lo legge e usa le versioni fissate indipendentemente dallo stato del registry al momento della build. I workspace eseguono il commit del lockfile quando conta la riproducibilità della build tra macchine diverse; dopo che un’entità, una libreria, un plugin o la Release stessa cambiano nel workspace, aggrega pull --release <release> lo aggiorna, risolvendo di nuovo ciò che è cambiato e mantenendo ogni altro pin, e aggrega pull --upgrade --release <release> è il modo in cui si adotta una versione più recente che un registry ora offre. Il lockfile registra ogni entità risolta con il suo tipo, il suo URI così come è stato scritto, la versione risolta, il digest del contenuto e i punti che la referenziano. Il tipo e l’URI insieme identificano una voce, quindi una Release il cui Aggregate e il cui Manifest condividono un nome registra una voce per ciascuno, e una modifica a uno dei due arresta la build successiva finché un pull non la registra:

# release.lock
entities:
- kind: component
uri: core/datastore/mariadb:1.0.0
resolved_version: 1.0.0
digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a
referenced_from:
- aggregate.spec.components.db.type
- kind: recipe
uri: mariadb-bitnami:1.0.0
resolved_version: 1.0.0
digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a
referenced_from:
- manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0
generated_at: "2026-06-11T16:48:15Z"
mapping_libraries: []
plugins: []
release: release.yaml
schema_libraries: []
source_artifacts: []
version: 1

Ogni voce fissata riporta il tipo + l’URI + la versione risolta + il digest indirizzabile per contenuto. Il digest viene verificato a ogni fetch; byte che non corrispondono al digest fissato arrestano la build con un errore di integrità. Il digest di un’entità è calcolato su ciò che una sua pubblicazione trasporta — il suo documento e ogni file che dichiara accanto a esso, ciascuno per percorso e per byte — anziché sui byte con cui viaggia, così la stessa entità registra lo stesso digest sia che venga letta da una directory di catalogo sia che venga scaricata da un registry, comunque sia stato compresso il suo archivio e qualunque bit di permesso, bit di esecuzione incluso, un checkout abbia dato ai suoi file. Il digest che il registry stesso calcola sui byte pubblicati è ciò rispetto a cui un fetch viene verificato per primo, tramite il manifest, il cui digest una voce risolta dal registry registra accanto al proprio.

5. Il modello di risoluzione delle entità a tre livelli

Il compilatore risolve ogni riferimento a un’entità incontrato durante la compilazione tramite una ricerca a cascata rigorosa. I tre livelli — percorso locale, workspace e cache, e registry — corrispondono a tre flussi di lavoro di authoring che coesistono in un progetto Aggrega sano: una Release che nomina i file accanto a sé, un team che usa un catalogo sottoposto a commit più la cache scaricata in precedenza, e un pull che raggiunge il registry per un artefatto non ancora scaricato. Il livello workspace e cache e il livello registry della stessa cascata valutano i campi type negli Aggregates, i valori URI nelle mappature del Manifest, le dichiarazioni implements su Recipes e FeatureRecipes e i riferimenti plugin all’interno delle pipeline di Recipe e FeatureRecipe; il livello del percorso locale è raggiunto solo dai file che una Release e il suo Manifest nominano.

Percorso locale. Un riferimento aggregate, manifest o extends di una Release, o l’extends di un Manifest, che inizia con ./ o ../ (un prefisso di percorso relativo POSIX) viene letto direttamente dal disco, relativamente alla Release. Nessuna ricerca nel catalogo, nessuna chiamata al registry. Il prefisso esplicito distingue a livello sintattico l’intento di percorso locale dalla ricerca per nome: una Release che scrive aggregate: ./aggregate.yaml nomina un file; aggregate: checkout nomina un Aggregate tramite il suo metadata.name. Il resolver non analizza mai il contenuto della stringa per decidere quale livello si applica — il discriminante è il prefisso. Ogni altro riferimento, compreso un type di Component in un Aggregate, si risolve tramite il livello workspace e cache e il livello registry: un’entità scritta in locale si colloca sotto catalog/ nella radice del workspace o in una directory elencata da workspace.catalog_dirs, e un type scritto come percorso di file relativo arresta la build come un’entità che nessun catalogo contiene.

Workspace e cache. Un riferimento senza un prefisso esplicito di percorso locale viene cercato prima nelle directory elencate in workspace.catalog_dirs (alberi di catalogo locali al progetto, scritti o copiati nel repository — vedi §4 per la forma della configurazione) — oppure, per una Release a cui la configurazione assegna directory proprie sotto workspace.releases, in quelle di quella Release — poi nella directory catalog/ della radice del workspace, e infine in artifact_cache_dir (la posizione .aggrega/cache/, ignorata da git, che contiene gli artefatti scaricati da precedenti risoluzioni dal registry, i cui sottoalberi sono descritti al §4). Il riscontro nella cache dalla seconda build in poi è ciò che mantiene il ciclo interno privo di accessi alla rete anche quando il progetto dipende da contenuti di catalogo remoti.

Registry. Se il livello workspace e cache non restituisce alcuna corrispondenza, aggrega pull — o una build eseguita con --auto-pull o con l’impostazione auto_pull del workspace — esegue un pull OCI basato su ORAS verso default_registry (predefinito hub.aggrega.ai), decomprime l’artefatto nella cache per le build successive e prosegue con l’entità risolta. Una build senza nessuno dei due legge solo ciò che il suo lockfile fissa, e quando il lockfile manca si arresta indicando aggrega pull. La forma di URI OCI costruita dalla chiamata al registry segue la tassonomia per tipo di entità descritta al §6 (Packaging degli artefatti & tassonomia OCI). Gli URI abbreviati negli Aggregates e nei Manifests vengono espansi nella loro forma OCI completa prima della chiamata al registry; le regole di inferenza che guidano tale espansione si trovano nel riferimento URI abbreviati sensibili al contesto del Manifest e al §8 più avanti.

Precedenza e shadowing. La precedenza di risoluzione è rigorosamente percorso locale > workspace e cache > registry. Un’entità in una directory di catalogo locale con la stessa identità di un’entità del registry oscura l’entità del registry — è intenzionale e consente agli autori di cataloghi di sperimentare modifiche prima della pubblicazione. Lo stesso oscuramento vale tra catalog_dirs e la cache: un’entità presente in una directory di catalogo del workspace è preferita a una copia in cache, così le modifiche locali a un catalogo copiato nel repository hanno effetto immediato.

All’interno del livello workspace e cache, catalog_dirs è uno stack di precedenza ordinato in cui vince il primo. Quando la stessa identità di entità compare in più di una directory di catalogo elencata, vince la directory elencata prima e l’occorrenza successiva viene oscurata — sovrascritta, non caricata, e non è un errore. Questo consente a un progetto di anteporre la propria directory di catalogo a una condivisa o copiata nel repository e di sovrascrivere entità selezionate per identità, mentre le restanti ricadono sulla directory condivisa. La sovrascrittura è osservabile: il dettaglio della risoluzione riporta quale directory ha vinto e quale è stata oscurata, quindi una stratificazione non è mai silenziosa. L’oscuramento si applica solo tra directory diverse; due file in una singola directory che rivendicano la stessa identità sono un errore di authoring e arrestano il caricamento. Una directory indicata più di una volta — da un flag --catalog e in catalog_dirs, oppure due volte nell’elenco — è una sola voce dello stack, cercata una sola volta nella posizione in cui è stata indicata per prima, così un oscuramento riguarda sempre due file diversi e mai una directory letta contro sé stessa. Poiché la precedenza segue l’ordine delle directory controllato dall’autore, l’insieme risolto è deterministico.

La directory catalog/ della radice del workspace entra in quello stack alla sua fine, non in testa, e solo quando la directory esiste — così qualsiasi cosa un progetto elenchi vince su di essa in caso di collisione, ed elencare una directory non correlata non fa mai smettere silenziosamente di leggerla. Viene saltata quando una voce elencata la raggiunge già, poiché la visita di una directory elencata è ricorsiva e uno stack che indica la radice del workspace l’ha già letta. Omettere catalog_dirs e scriverlo come elenco vuoto sono affermazioni diverse: se omesso, il workspace legge comunque catalog/; se scritto come [], non legge alcun catalogo locale, ed è così che un workspace dichiara di non averne.

Build air-gapped. Impostare offline: true (§4) salta completamente il livello registry. Un riferimento che non si risolve nel livello del percorso locale o nel livello workspace e cache produce un errore di entità mancante invece di tentare silenziosamente una chiamata di rete, il che offre alle pipeline CI che per legge non possono raggiungere la rete un contratto deterministico di fallimento rapido.

Dove opera la cascata. La cascata carica l’entità in memoria; gli ulteriori meccanismi di risoluzione costruiti sopra di essa — la ricerca a due livelli type vs name del Manifest, la corrispondenza di versione in tre forme di implements (esatta / intervallo compatibile con la major / senza versione) descritta in vocabulary/inheritance-and-interface, e la selezione della Recipe per asse in base al provider e all’istanza del componente — operano su entità che il resolver ha già recuperato tramite questa cascata.

6. Packaging degli artefatti & tassonomia OCI (la capacità come segmento iniziale)

Aggrega tratta la logica dell’infrastruttura nello stesso modo in cui Docker tratta le immagini dei container, utilizzando gli standard della Open Container Initiative (OCI) tramite ORAS (OCI Registry As Storage). Gli utenti possono ospitare il proprio catalogo Aggrega su qualsiasi registry standard (GHCR, AWS ECR, Aggrega Hub).

Poiché le Recipes sono rigorosamente 1:1 con una capacità di rendering — una Recipe indica una sola capacità in spec.capability e non può puntare a due — il modo più pulito per organizzarle in un registry OCI è mettere la capacità nel segmento iniziale del repository.

La tassonomia OCI copre tutti i tipi di entità. Il nome di un repository è il segmento del kind — il kind dell’entità, in minuscolo — seguito dall’identità dell’entità, tutto in minuscolo:

  • hub.aggrega.ai/component/core/datastore/mariadb:1.0.0 — Component, publisher core, categoria datastore
  • hub.aggrega.ai/component/core/compute/api-server:1.0.0 — Component, publisher core, categoria compute
  • hub.aggrega.ai/feature/core/data-masking:1.0.0 — Feature, publisher core (piatta, senza categorie)
  • hub.aggrega.ai/aggregate/core/db-module:1.0.0 — Modulo Aggregate riutilizzabile
  • hub.aggrega.ai/recipe/helm/mariadb:1.0.0 — Recipe, capacità helm
  • hub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0 — Recipe, capacità helm-chart
  • hub.aggrega.ai/recipe/compose/mariadb:1.0.0 — Recipe, capacità compose
  • hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0 — FeatureRecipe, capacità helm
  • hub.aggrega.ai/schemalibrary/aidatastores:1.0.0 — SchemaLibrary, definizioni di schema condivise; il metadata.name in PascalCase AIDatastores diventa minuscolo nel nome del repository
  • hub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0 — MappingLibrary, frammenti di mappatura Go-template condivisi
  • hub.aggrega.ai/plugin/provider/helm:0.5.0 — Plugin, tipo di socket provider (il segmento metadata.pluginType)

I kind pubblicabili comprendono i kind di authoring del catalogo insieme all’Aggregate, un modulo riutilizzabile (pubblicabile sia che venga poi referenziato come spec.aggregate di primo livello di una Release sia che venga annidato nel blocco aggregates: di un altro Aggregate), e al Plugin, un riferimento indirizzato per contenuto a un artefatto WebAssembly che il compilatore instrada e il runtime esegue. Il Plugin è un artefatto pubblicabile strutturale anziché un kind di authoring del catalogo. Release e Manifest sono input lato deployment che risiedono nel controllo di versione e non vengono mai inviati con push — aggrega push li rifiuta — quindi non hanno un mediatype di pubblicazione. aggrega push --list-kinds riporta l’insieme che il binario installato pubblica, un kind per riga. Ogni kind pubblicabile ha il proprio mediatype OCI in ciascuna delle due forme che una pubblicazione assume:

Tipo di entitàPubblicata come il suo documentoPubblicata con i file che dichiara
Componentapplication/vnd.aggrega.component.v1beta1+yamlapplication/vnd.aggrega.component.v1beta1+tar+gz
Featureapplication/vnd.aggrega.feature.v1beta1+yamlapplication/vnd.aggrega.feature.v1beta1+tar+gz
Recipeapplication/vnd.aggrega.recipe.v1beta1+yamlapplication/vnd.aggrega.recipe.v1beta1+tar+gz
FeatureRecipeapplication/vnd.aggrega.featurerecipe.v1beta1+yamlapplication/vnd.aggrega.featurerecipe.v1beta1+tar+gz
Aggregateapplication/vnd.aggrega.aggregate.v1beta1+yaml— non dichiara alcun file
SchemaLibraryapplication/vnd.aggrega.schemalibrary.v1beta1+yaml— non dichiara alcun file
MappingLibraryapplication/vnd.aggrega.mappinglibrary.v1beta1+yaml— non dichiara alcun file
WorkloadLibraryapplication/vnd.aggrega.workloadlibrary.v1beta1+yaml— non dichiara alcun file
ArtifactLibraryapplication/vnd.aggrega.artifactlibrary.v1beta1+yaml— non dichiara alcun file
Pluginapplication/vnd.aggrega.wasmplugin.v1beta1+yaml— pubblica tramite il proprio manifest

Ciò che una pubblicazione trasporta, e quindi la sua forma, deriva da ciò che l’entità dichiara — non dal suo kind, né da ciò che si trova nella sua directory. Una pubblicazione trasporta il documento dell’entità e i file che l’entità stessa indica accanto a esso: il source: locale di una Recipe o di una FeatureRecipe — una directory viaggia con ogni file al suo interno che le regole di esclusione registrate nel suo entity.lock mantengono — ogni file che le sue voci valuesMapping:, workload: e artifacts: importano con $import:, e l’entity.lock scritto dal suo passo di pin; e ogni file di schema che un Component o una Feature importa, compreso ogni file di una catena di import. Nient’altro nella directory viaggia: una nota, un README o l’output di una build accanto all’entità non fa parte di ciò che essa pubblica, comunque si chiami, e non cambia la forma in cui pubblica. Un’entità che non indica nulla viene pubblicata come il documento scritto, byte per byte, sotto il mediatype +yaml del suo kind; una che indica un file viene pubblicata come tar compresso con gzip del documento e di quei file, sotto il mediatype +tar+gz del suo kind. Un Aggregate, un Plugin e i kind di libreria non dichiarano alcun file accanto al loro documento, quindi vengono sempre pubblicati come documento — compreso un Aggregate alla radice di un workspace, poiché ogni percorso che dichiara indica un’altra entità e non un file che trasporta; lo stesso vale per una Recipe il cui contenuto è interamente inline. Un source remoto è un riferimento e non un file, quindi non trasporta nulla, anche se l’entity.lock che registra il suo pin rende tale Recipe un archivio. Il segmento di versione di ogni mediatype è comune a tutti i kind pubblicabili, e il segmento di codifica indica quale delle due forme hanno i byte. Gli strumenti a valle effettuano il dispatch sull’intera stringa del mediatype — kind, versione e codifica insieme.

Una forma scritta non indica alcuna directory che una pubblicazione possa conoscere: un source locale scritto come template. La sua directory viene scelta solo quando una Release compila il template, quindi l’entità trasporta ogni file della propria directory che le sue regole di esclusione registrate mantengono, così che qualunque directory una Release scelga abbia viaggiato; aggrega push lo segnala quando accade. Trasportare solo ciò che è indicato ha un costo, e ricade sul consumatore: un file che un’entità legge e non indica da nessuna parte non viaggia, ed è la build di un consumatore — non il push del publisher — a scontrarsi con la sua assenza, indicando il percorso mancante all’interno del suo slot della cache.

Quali file di una directory sorgente appartengono all’entità viene deciso una sola volta, quando l’entità viene fissata, e registrato. Il plugin che serve la capacità dell’entità nel workspace dell’autore dichiara ciò che il suo ecosistema non distribuisce mai — le directory di controllo di versione di un plugin per chart e il suo rispetto del .helmignore di un chart, la .terraform/ di un plugin per moduli — e il .aggregaignore dell’autore accanto all’entità ha l’ultima parola. Il passo di pin registra quel plugin e le regole composte nell’entity.lock, e la pubblicazione, ogni confronto dei pin del source, la riga dell’entità nel lockfile e il rendering applicano tutti le regole registrate anziché interrogare di nuovo un plugin, così ciò che viene pubblicato è ciò che la build dell’autore stesso renderizza, e un binding cambiato o un binario più recente non sposta alcun digest finché l’entità non viene fissata di nuovo. Il compilatore non ha alcuna opinione su nessun ecosistema: le regole provengono dal plugin e dall’autore, e il compilatore si limita a confrontarle. Un collegamento simbolico tra i file di un’entità viene rifiutato anziché seguito, poiché ciò a cui punta viaggerebbe sotto il suo nome. aggrega pin illustra le regole per intero.

Il nome di una Recipe non contiene né un prefisso di dominio né la capacità: la directory del tipo di entità e il segmento della capacità indicano già entrambi.

Convenzione di denominazione: i Components (Dominio 2) usano {publisher}/{category}/{name}, mentre le Features (Dominio 2) e gli Aggregates riutilizzabili (Dominio 1) usano {publisher}/{name}, dove il segmento publisher indica il vendor/autore (core = libreria standard ufficiale, acme = enterprise). Le entità del Dominio 3 (Recipe, FeatureRecipe) usano {capability}/{name}, dove la capacità è il provider che l’entità dichiara in spec.capability; un riferimento può anche indicare l’entità senza prefisso, con la sola foglia. Anche i nomi delle Recipe NON includono la capacità, poiché è già il segmento iniziale dell’URI canonico.

Le Recipes utilizzano la parola chiave implements per legarsi all’interfaccia che soddisfano. Il campo implements supporta la corrispondenza esatta, per intervallo compatibile con la major o senza versione (vedi vocabulary/inheritance-and-interface per la corrispondenza di versione di implements). La Recipe di una voce di mappatura del Manifest deve implementare il tipo per cui è mappata, o una base che quel tipo extends: la chiave della voce, e il tipo di ogni istanza di componente che la chiave raggiunge a una versione che non nomina, alla versione con cui la build compila quell’istanza — così una chiave non può inviare un’istanza a una Recipe scritta per un’altra versione del suo tipo.

Quando un ingegnere Ops esegue aggrega push, la CLI pubblica l’entità in quella forma, in modo immutabile alla sua versione. Un consumatore la recupera tramite il modello di risoluzione a tre livelli, la mette in cache localmente in .aggrega/cache/ e dispone ciò che trasporta nello slot di cache dell’entità (§4) — i file di un archivio, oppure il solo documento.

Un’entità scaricata legge i file che porta con sé esattamente come li legge accanto a sé in una directory di catalogo. L’entità viene letta dalla sua posizione in quell’albero disposto, quindi un source: o un $import: relativo che dichiara — scritto per esteso o prodotto da un template — si risolve all’interno di ciò che è stato pubblicato, e un percorso che esce dalla directory propria dell’entità viene rifiutato lì esattamente come in una directory di catalogo. Nulla al di fuori dell’albero viene letto al suo posto: né la directory da cui viene eseguita una build, né un file collocato nello slot della cache. Un Component o una Feature il cui schema è importato da un file porta con sé quel file, quindi una copia scaricata carica il contratto che è stato pubblicato e convalida i valori scritti rispetto a esso esattamente come fa una copia letta da una directory di catalogo.

Rileggere l’entità da un pacchetto è il passo inverso, e identifica l’entità in base a ciò che il documento è anziché a come si chiama: il documento al livello superiore del pacchetto il cui kind: è un tipo di entità pubblicabile. Il nome del file dell’entità è una convenzione del catalogo e non un contratto, quindi recipe.yaml è ciò che scrive il catalogo della libreria standard anziché ciò che il formato richiede, e un file portato accanto all’entità — un template di chart, un frammento compose — non viene scambiato per essa. La regola non può funzionare al contrario, basandosi sul tipo che cerca il consumatore: un tipo si legge dall’entità, che si trova all’interno del pacchetto, quindi nel momento in cui il pacchetto deve essere aperto non c’è alcun tipo su cui basarsi. Il lato di lettura si arresta anziché scegliere quando il livello superiore di un pacchetto contiene due documenti di entità — il pacchetto che un altro client produce impacchettando un’intera directory che contiene due entità, che si troverebbe quindi sotto ciascuna delle loro coordinate pubblicate come un unico artefatto. La pubblicazione di questo prodotto non può produrlo, perché ogni entità porta con sé solo ciò che dichiara, e il lato di pubblicazione rifiuta inoltre una directory del genere: ogni tipo ha una directory propria tranne Aggregate, Release e Manifest, e aggrega pin e aggrega push rifiutano un’entità di qualsiasi altro tipo che abbia un’altra entità accanto, mentre il caricamento di un catalogo, un lint e una build lasciano stare la directory. Il nome di una directory non viene giudicato da nessuno dei due lati: il layout <name>/<version>/ è la convenzione del catalogo della libreria standard.

Un’entità pubblicata viene letta attraverso lo stesso passo. Una coordinata porta esattamente una copia della sua entità, nella forma che le sue dichiarazioni le hanno dato, e una persona la esamina con aggrega inspect oci://<registry>/<repository>:<tag> anziché attraverso una copia leggibile pubblicata accanto a essa — quindi non esiste una seconda copia che possa finire per divergere da quella che una build risolve. Il comando estrae un archivio secondo la regola precedente, legge l’entità di un Plugin dal suo manifest anziché dall’eseguibile pubblicato con esso, e visualizza il risultato come viene visualizzato un file di quel tipo; vedi Leggere un’entità pubblicata.

Annotazioni del manifest ricercabili. Ogni pubblicazione imprime un piccolo insieme di annotazioni ricercabili nel manifest OCI dell’artefatto, così che un indice di registry o un browser di catalogo possa filtrare gli artefatti in base ai loro metadati di catalogo senza scaricare e analizzare il corpo di ogni entità. Ogni entità porta la sua descrizione leggibile (l’annotazione di descrizione OCI standard) più la sua categoria di catalogo e il suo tipo. Un Plugin porta inoltre il suo tipo di socket e le capability che serve. Queste annotazioni sono ciò che aggrega registry update rilegge nell’indice ricercabile locale (§8).

Ogni file pubblicato ha un nome. Ogni file che una pubblicazione porta con sé è nominato nel manifest con l’annotazione standard org.opencontainers.image.title, che è il nome con cui un client OCI generico scrive quel file quando scarica l’artefatto in una directory. Il nome dice che cos’è il file, e la sua estensione segue il media type del file:

Che cosa viene pubblicatoIl file che scrive un client OCI generico
un’entità pubblicata come suo documentoentity.yaml
un’entità pubblicata con i file che dichiaraentity.tar.gz
un Pluginentity.yaml, l’entità, accanto a entity.wasm, il suo eseguibile
una firma allegata a un artefattosignature.json
un marcatore di deprecazione allegato a un artefattodeprecation.json
un artefatto di dati pubblicato con aggrega push-artifactil nome dato con --name

Così oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server lascia l’entità pubblicata in ./server/entity.yaml, byte per byte come è stata pubblicata. oras salta un descrittore che non porta alcun nome e riporta comunque un esito positivo, ed è per questo che ogni descrittore che una pubblicazione impacchetta ne porta uno. Il nome è derivato soltanto dal media type, mai dal nome del file che è stato pubblicato, quindi gli stessi byte pubblicati da un file con un nome diverso producono lo stesso manifest. Un’entità pubblicata con i suoi file arriva come il suo pacchetto: entity.tar.gz dà il nome al pacchetto, e l’entità al suo interno viene trovata secondo la regola precedente anziché in base a un nome di file. La risoluzione di Aggrega stessa non legge mai questi nomi — seleziona ogni file in base al suo media type e se ne fida in base al suo digest — quindi esistono per ogni altro client.

7. L’architettura della Recipe: puntatori e mapper

Vedi entities/recipe per l’intera superficie di authoring della Recipe — source: (puntatore), valuesMapping: (mapper, con tre modalità di authoring: block scalar inline, $import: da file, $import: di libreria verso una voce di una MappingLibrary), schemi di sorgente guidati da Wasm, supporto IaC nativo ed esempi svolti.

8. Il registry predefinito e gli URI abbreviati sensibili al contesto

Per eliminare il sovraccarico di YAML, il compilatore risolve gli URI abbreviati in modo sensibile al contesto rispetto alla posizione dello schema in cui compaiono. Il registry predefinito è configurato in .aggrega-config.yaml (con hub.aggrega.ai come valore predefinito).

Un host di registry ha una sola lettura. Ogni registries[].host è scritto come l’host stesso — un nome host in minuscolo che contiene un punto, localhost, un singolo nome seguito da una porta, un indirizzo IPv4 o un indirizzo IPv6 tra parentesi quadre, ciascuno con un :port facoltativo, e senza schema, percorso, credenziali o lettere maiuscole — perché quella grafia è la chiave sotto cui si trova ogni policy di fiducia per registry, e il requisito di firma integrato dell’hub ufficiale è associato a hub.aggrega.ai. default_registry nomina un host allo stesso modo, e può farlo seguire da un percorso di repository, come ghcr.io/acme: tutto ciò che viene pubblicato attraverso il predefinito finisce allora sotto quel percorso, e ogni riferimento breve si risolve sotto di esso, mentre la fiducia è ancora decisa dal solo host. default_registry può invece essere scritto come il name: di una voce di registries, e in quel caso sta per l’host di quella voce. Il nome viene letto una sola volta, mentre la configurazione si risolve, rispetto alle voci in vigore dopo ogni file di configurazione e l’ambiente, quindi ogni lettore del predefinito — la pubblicazione, il binding della posizione, la verifica delle firme e ogni ricerca di fiducia — legge l’host di quell’unica voce, e nessuno di essi raggiunge un host scritto come il nome; un nome seguito da un percorso viene rifiutato, poiché un nome sta per una voce anziché per una posizione. Un nome viene confrontato prima di una grafia di host, e un nome portato da due voci viene rifiutato come ambiguo. La stessa lettura decide tre cose che un pull fa con l’host: la posizione di registry a cui è legata un’identità di catalogo senza host, se l’artefatto scaricato nomini un registry di cui si verifica la firma, e quale policy di fiducia viene applicata in quella verifica. Una grafia che potrebbe raggiungere un registry mancando però la sua policy — maiuscole, una porta HTTPS predefinita esplicita, uno schema, credenziali, un percorso sull’host di una voce di registries — viene rifiutata nel punto in cui è configurata, indicando la grafia da scrivere, e così pure un singolo nome senza porta che non nomina alcuna voce, che è la forma del primo segmento di un’identità di catalogo anziché di un host. Il rifiuto si applica a ogni livello che può impostare il valore: il file di configurazione, dove lo schema dichiara la stessa forma come pattern su ogni registries[].host; la variabile d’ambiente AGGREGA_DEFAULT_REGISTRY; e la riga di comando. Quindi ogni host che una configurazione può nominare è uno i cui artefatti vengono verificati secondo la policy scritta per esso. L’host viene giudicato solo in base alla sua grafia; se il nome si risolve, o se lì risponde un registry, è stato di runtime che il compilatore non recupera mai. configurazione illustra le forme accettate con esempi.

Gli URI abbreviati si risolvono in modo sensibile al contesto rispetto al Manifest; vedi ../language-reference/entities/manifest.md §URI abbreviati sensibili al contesto per le regole di inferenza specifiche.

Gestione dei registry

aggrega registry gestisce i registry che il workspace conosce e la loro policy di fiducia delle firme. L’identità di un registry è il suo host; i sottocomandi condividono un unico modello di indirizzamento:

  • aggrega registry add <host> registra un registry e fissa la sua policy di fiducia, recuperando la policy pubblicizzata dal registry al primo contatto, a meno che dei flag di fiducia non ne forniscano una manualmente. Un --name <alias> facoltativo associa un alias descrittivo alla stessa voce indicizzata per host — l’host resta l’identità, e l’alias si risolve in esso ovunque venga nominato un registry. Un alias è univoco tra i registry.
  • aggrega registry list stampa ogni registry configurato — host, alias, un breve riepilogo della postura di fiducia e un indicatore sul predefinito — in ordine crescente di host. Legge la configurazione risolta e non contatta alcuna rete.
  • aggrega registry remove <name|host> elimina la voce della policy di fiducia di un registry, indirizzata tramite il suo host o il suo alias. Rimuove solo la policy di fiducia: il puntatore default_registry resta invariato e la possibilità di eseguire il push verso quell’host non viene toccata, quindi l’host torna alla fiducia predefinita anziché diventare irraggiungibile. Un default_registry scritto come il nome della voce rimossa non nomina più nulla in seguito, e viene rifiutato finché non viene riscritto.
  • aggrega registry update aggiorna l’indice ricercabile locale, descritto di seguito.

Ovunque venga nominato un registry — un argomento di un sottocomando registry o il flag --registry su aggrega push e aggrega push-artifact — lo stesso resolver interpreta il token: un alias configurato si risolve nel suo host, e qualsiasi altro token viene letto come l’host che nomina, scartando lo schema, il percorso e le credenziali di un riferimento. Dove quell’host diventa qualcosa rispetto a cui si prende una decisione di firma — la destinazione di aggrega push o aggrega push-artifact, o la chiave sotto cui aggrega registry add scrive una voce — viene vincolato all’unica lettura descritta sopra e rifiutato, indicando la grafia da scrivere, quando non è scritto in quel modo. Un host non registrato scritto in quel modo è una destinazione legittima e viene accettato.

L’indice ricercabile locale

aggrega registry update [<name|host>] costruisce un indice ricercabile locale dei registry che il workspace conosce. Percorre i repository di ogni registry configurato, seleziona la versione rilasciata più alta di ciascuno, legge le annotazioni ricercabili del manifest di quella versione (§6) e scrive un indice per registry nella cache degli artefatti. Senza argomenti indicizza ogni registry configurato; con un singolo argomento di registry (un host o un alias) indicizza solo quello.

L’indice segue il modello di aggiornamento esplicito familiare dai package manager: registry update è il comando che contatta i registry, e un successivo aggrega search legge offline l’indice scritto. Il file dei record di un registry è deterministico — due aggiornamenti sullo stesso stato del registry producono byte identici, e il timestamp di aggiornamento si trova in un file adiacente, così da non perturbare mai i record. Un repository senza alcuna versione rilasciata, o che non può essere letto, viene saltato, così un singolo repository illeggibile non fa mai abbandonare l’intero indice.

Lo snapshot pubblicato del catalogo

Ogni pubblicazione del catalogo della libreria standard pubblica anche il catalogo nel suo insieme: un unico artefatto OCI, un tar compresso con gzip di ogni file che l’albero del catalogo contiene al commit pubblicato da quella pubblicazione, in catalog/snapshot sotto il registry in cui il catalogo è pubblicato — hub.aggrega.ai/catalog/snapshot per l’hub ufficiale. Viene inviato solo dopo che ogni entità di quella pubblicazione si trova nel registry, così da non nominare alcuna entità che il registry non contenga. Viene taggato con il commit da cui è stato costruito e con latest, ed è firmato in modalità keyless da chi lo pubblica, come ogni entità della pubblicazione, così che l’identità di chi pubblica ne permetta la verifica secondo la trust policy del registry; latest passa a uno snapshot solo dopo che questo è stato firmato. L’archivio è scritto secondo un unico layout fisso — voci in ordine crescente di nome, ciascuna con la stessa modalità dei permessi, lo stesso proprietario e lo stesso orario di modifica — così che uno stesso commit produca sempre lo stesso tar.

Il suo unico lettore è un’importazione il cui workspace non indica alcuna cartella di catalogo: nessun workspace.catalog_dirs, nessun AGGREGA_CATALOG_DIRS e nessuna directory catalog/ nella root del workspace. aggrega import, l’importazione della sessione dell’editor e lo strumento di importazione dell’assistente eseguono la stessa operazione, quindi ciascuno acquisisce lo snapshot allo stesso modo. L’importazione lo recupera dal registry predefinito del workspace attraverso lo stesso controllo del traffico in uscita e la stessa autenticazione di un pull, ne verifica la firma secondo la trust policy di quel registry prima di conservare qualsiasi cosa, lo conserva nella cache degli artefatti del workspace e lo legge lì come una cartella di catalogo, vincolato al suo digest — così all’importatore vengono offerti i Components del catalogo, e --target mette in bozza un Manifest a partire dalle sue Recipes, esattamente attraverso il percorso che segue una cartella di catalogo. Il record che l’importazione scrive accanto alle sue bozze indica lo snapshot tramite il digest del suo manifest, così che un’importazione successiva delle stesse bozze legga lo stesso catalogo senza alcuna richiesta, e aggrega import --upgrade recupera lo snapshot più recente e da quel momento importa rispetto a esso. In modalità offline, un’importazione che dovrebbe recuperare uno snapshot si arresta, indicando cosa eseguire. Un workspace che indica una cartella di catalogo importa rispetto a essa e non recupera alcuno snapshot. Nessun altro comando legge lo snapshot: un pull, una build e una validazione risolvono ciascuna entità attraverso i livelli del §5 e la fissano nel lockfile, e le bozze di un’importazione fanno riferimento alle entità del catalogo per nome, quindi costruirle risolve quelle entità nello stesso modo.

9. Pinning del lockfile e immutabilità degli artefatti

La disciplina del pinning tramite lockfile ancora ogni dipendenza a uno specifico artefatto indirizzabile per contenuto. Alla prima risoluzione del lockfile (aggrega pull), il resolver consulta il registry, sceglie una versione secondo il vincolo in tre forme dell’URI (esatta / intervallo / senza versione) e scrive la versione fissata + il digest nel <release-stem>.lock della Release. Le successive invocazioni di aggrega build usano i valori fissati indipendentemente dalla mutabilità del registry; nuove versioni possono essere pubblicate senza influire sul lockfile esistente.

Il modello di pinning porta con sé una regola portante: una volta che un name:version è pubblicato in un registry e si risolve nel digest D, quella corrispondenza è permanente. Ripubblicare lo stesso name:version con contenuto diverso viene rifiutato al momento del push. aggrega push stesso lo impone a ogni pubblicazione: risolve l’artefatto esistente in name:version nel registry di destinazione; se è presente e il digest corrisponde al contenuto che sta per essere inviato, il push non carica nulla e allega solo ciò che manca ancora a quella pubblicazione — la sua data di pubblicazione, e la sua firma dove il push firma; se è presente e il digest differisce, il push si arresta con un errore di violazione dell’immutabilità che cita entrambi i digest.

L’immutabilità conta per due conseguenze:

  1. I pin del lockfile sono affidabili. Quando il lockfile registra mariadb:1.0.0 al digest D, una build che scarica per digest riceve i byte di D. Senza immutabilità, una modifica lato registry potrebbe sostituire i byte di D sotto il pin del lockfile, compromettendo la stabilità dal momento del lock al momento della build. Le build riproducibili si basano su questa garanzia.
  2. Le modifiche ai metadati dopo la pubblicazione hanno un percorso chiaro. Contrassegnare una versione pubblicata come deprecata, ruotare le chiavi di firma o correggere le attestazioni non si può fare modificando l’artefatto pubblicato (la regola lo vieta). Va fatto pubblicando una nuova versione patch o un artefatto sidecar che registri separatamente la modifica dei metadati. Entrambi i percorsi sono verificabili — una nuova versione o un sidecar compare come voce distinta del registry — e nessuno dei due altera i byte dell’artefatto originale.

La regola di immutabilità si applica in modo uniforme a ogni artefatto Aggrega pubblicato su OCI (entità, SchemaLibrary, MappingLibrary, plugin Wasm referenziati da pipeline[].plugin: di una Recipe / pipeline[].plugin: di una FeatureRecipe / plugins.{governance,linter,importer}[]: della configurazione del workspace). Tutto ciò che è fissato tramite name:version più un digest di contenuto nel lockfile è soggetto all’immutabilità.

L’immutabilità è incondizionata, e nessuna configurazione la attenua. Non esiste alcun flag né alcuna impostazione della configurazione del workspace che consenta una sovrascrittura, perché il registry non espone alcun percorso di sovrascrittura che un operatore possa scegliere di attivare. Il contenuto modificato viene pubblicato con una nuova versione, e aggrega lint --pre-publish verifica che l’incremento di versione corrisponda alla classificazione della modifica.

La nuova risoluzione 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, e aggrega pull --upgrade --release <release> risolve di nuovo tutte le dipendenze rispetto allo stato attuale del registry. Le dipendenze in forma di intervallo e senza versione si risolvono di nuovo nell’ultima versione corrispondente; i pin in forma esatta non si spostano a meno che l’utente non esegua esplicitamente l’upgrade a una diversa versione esatta. Il lockfile è la fonte di verità per le build; la forma digitata dall’utente esprime il vincolo di versione al momento dell’authoring.

10. Applicazione della forma dei nomi delle entità di catalogo

I nomi delle entità di catalogo seguono pattern specifici per tipo di entità — elencati di seguito e descritti in dettaglio per tipo nella Panoramica del riferimento alle entità. Sono una superficie diversa dai nomi di istanza che uno sviluppatore scrive in un Aggregate o in una Release, che condividono un unico pattern indipendentemente dal tipo; quel pattern si trova in ../language-reference/02-naming-conventions.md «Nomi di istanza». Il campo metadata.name che uno YAML di catalogo dichiara non è sempre identico all’URI di riferimento canonico dell’entità: Component e Feature incorporano i segmenti di publisher e di raggruppamento direttamente in metadata.name; Recipe e FeatureRecipe dichiarano un metadata.name costituito dalla sola foglia, e il loro URI canonico a due segmenti associa quella foglia alla spec.capability che l’entità dichiara; ogni tipo di libreria dichiara un token PascalCase in metadata.name.

Forme per tipo di entità:

  • Component — tre segmenti kebab-case {publisher}/{category}/{name} dichiarati in metadata.name. Esempio: core/datastore/postgres.
  • Feature — due segmenti kebab-case {publisher}/{name} dichiarati in metadata.name. Esempio: core/data-masking.
  • Recipe — una singola foglia kebab-case in metadata.name (ad es. postgres). L’URI di riferimento canonico {capability}/{name} (secondo il §6 sopra) associa la spec.capability dichiarata dall’entità a quella foglia; il segmento iniziale viene confrontato con spec.capability, non con la posizione dell’entità sul disco, quindi spostare un recipe.yaml non cambia il modo in cui viene referenziato. Il catalogo della libreria standard colloca l’entità in <catalog-root>/recipe/<capability>/<name>/<version>/recipe.yaml così che l’albero rispecchi la coordinata, ma questo rispecchiamento è una convenzione del catalogo anziché l’origine dell’URI. Un riferimento può anche nominare la ricetta senza qualificatori — la sola foglia, senza segmento di capability — che è la forma dominante nella pratica e si risolve ogni volta che una sola ricetta nel catalogo porta quel nome. Nessun segmento di publisher compare in un URI di Recipe, e un riferimento che porta un terzo segmento non corrisponde ad alcuna ricetta.
  • FeatureRecipe — singola foglia kebab-case in metadata.name (ad es. k8s-secret-from-parameter), simmetrica rispetto alla Recipe: URI canonico {capability}/{name} dalla spec.capability dichiarata più la foglia, la foglia senza qualificatori accettata allo stesso modo, e l’albero <catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yaml che rispecchia la coordinata per convenzione.
  • I tipi di libreria — SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary — un singolo token PascalCase in metadata.name che corrisponde a ^[A-Z][A-Za-z0-9]*$ (ad es. BaseComponents, AIDatastores, BaseWorkloads). La forma è la stessa per ogni tipo di libreria, quindi spostare una voce tra librerie non significa mai rinominarla secondo una convenzione diversa. L’envelope JSON Schema di ogni tipo di libreria dichiara anch’esso il pattern, in aggiunta al controllo descritto di seguito.

Per Component, Feature, Recipe e FeatureRecipe, il JSON Schema di metadata.name accetta qualsiasi stringa non vuota, quindi nulla della forma è strutturale per quei tipi. Ogni forma documentata — compresi i tipi di libreria, i cui envelope dichiarano anch’essi il proprio pattern — viene controllata dal plugin di disciplina della pubblicazione, che porta i pattern come fonte di verità regex condivisa con la distribuzione del compilatore. A nessun tipo viene assegnata qui una forma che il plugin poi ignori.

Il controllo è opzionale: un solo comando lo esegue, e viene eseguito solo quando un autore lo richiede. I due comandi che più spesso si presume lo eseguano non lo fanno:

  • aggrega lint segnala le violazioni della forma dei nomi. Il plugin confronta il metadata.name di ogni entità con il pattern del suo tipo. Il controllo viene eseguito quando un autore invoca aggrega lint — su una singola entità, sulla chiusura delle dipendenze di una Release con --release, o su ogni entità del catalogo quando viene invocato senza argomenti — e lo stesso insieme di regole è raggiungibile dalla superficie di strumenti rivolta all’editor che la CLI espone. I rilievi sono consultivi: vengono segnalati con gravità warn e non arrestano nulla.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)

Il rilievo si apre con la sua gravità e il codice breve con cui è registrata la sua regola, che aggrega explain E0278 espande. Il percorso del file incriminato viene stampato sopra il rilievo, e un’esecuzione sull’intero catalogo si chiude con un conteggio delle entità controllate e dei rilievi consultivi sollevati.

  • aggrega build non controlla la forma dei nomi. L’output renderizzato non dipende dai nomi delle entità Aggrega, quindi una build su un catalogo che contiene nomi non conformi non emette alcun avviso né alcuna diagnostica, e riesce esattamente come riuscirebbe altrimenti.
  • Nemmeno aggrega push controlla la forma dei nomi. La pubblicazione rifiuta per altri motivi — in particolare la regola di immutabilità descritta sopra, per cui ripubblicare un name:version esistente con contenuto diverso si arresta. Dove un rifiuto nomina aggrega lint --pre-publish, sta indicando all’autore quale comando eseguire; il push non lo esegue.

Poiché né la build né la pubblicazione controllano la forma, un catalogo che vuole che la convenzione sia rispettata esegue aggrega lint deliberatamente — in un hook pre-commit o come passo di una pipeline. Nota che un rilievo sulla forma dei nomi è consultivo: aggrega lint lo segnala e termina comunque con successo, quindi una pipeline che vuole porre un vincolo sulla convenzione legge i rilievi segnalati anziché affidarsi allo stato di uscita.

Una policy per workspace disattiva la regola:

# .aggrega-config.yaml — lint section
lint:
publishing_discipline:
allow_nonstandard_names: true # default false

Con la policy impostata, la regola sulla forma dei nomi non segnala nulla. Può anche essere impostata per una singola invocazione con aggrega lint --allow-nonstandard-names, o disattivata di nuovo forzatamente con --no-allow-nonstandard-names. Gli usi legittimi sono i cataloghi che non verranno mai pubblicati, gli esperimenti con più publisher e le entità per scopi speciali.

11. Espansione delle Feature guidata dalle annotazioni

Il blocco mappings.features.annotations del Manifest dichiara i binding tra chiavi di annotazione e tipi di Feature, più una tabella di instradamento raggruppata per pilastro (maps.infra, maps.values) che nomina le proprietà dello schema della Feature che ogni annotazione può popolare. La sotto-fase di espansione delle annotazioni della risoluzione percorre i confini della Release dall’esterno verso l’interno e i sottosistemi dell’Aggregate dall’esterno verso l’interno, calcola gli insiemi effettivi di annotazioni per componente tramite cascata e override con opt-out null sull’intero valore e per sottochiave, e inietta collegamenti sintetici di Feature che portano origin: annotation nella loro provenienza IR. La trattazione completa sulla forma dei binding e sull’authoring si trova in language-reference/entities/manifest.md e language-reference/providers/well-known-annotations.md; questa sezione documenta i meccanismi al momento del caricamento del catalogo e al momento dell’inspect su cui si basa il percorso di espansione.

Cache di compilazione degli schemi. Lo spec.schema.{infra,values} di ogni Feature viene compilato una volta per build e riutilizzato tra i percorsi a cascata. La ripetuta convalida dei tipi per sottochiave rispetto allo stesso schema di Feature (un ambito di cascata per componente, per centinaia di componenti) legge lo schema compilato anziché compilarlo di nuovo. Nulla viene conservato tra una build e l’altra, quindi uno schema di Feature modificato viene compilato da capo dalla build successiva.

Convalida delle destinazioni dei binding (caricamento del catalogo). Al caricamento del catalogo, il compilatore percorre ogni binding features.annotations del Manifest e verifica che ogni percorso puntato dichiarato sotto maps.infra e maps.values corrisponda a una proprietà che lo spec.schema.<pillar> della Feature referenziata dichiara effettivamente. Un binding che instrada verso un percorso che lo schema della Feature non elenca arresta il caricamento del catalogo con un OPS_ERROR chiaro che nomina la chiave del binding, il percorso mancante, l’URI della Feature e la posizione nel sorgente.

Lint di sovrapposizione dei pilastri dello schema (caricamento del catalogo). Viene emesso un avviso consultivo quando lo spec.schema di una Feature dichiara lo stesso nome di proprietà in entrambi i pilastri infra e values. La sovrapposizione è raramente intenzionale — proprietà con lo stesso nome in pilastri diversi confondono l’intento dell’authoring (quale pilastro si attiva quando un’annotazione punta al nome condiviso?) e complicano i messaggi diagnostici. L’avviso non è bloccante e non prevede opt-out: un autore che vuole la sovrapposizione la mantiene insieme all’avviso, e uno che non la vuole rinomina la proprietà in un pilastro.

Lint di sovrapposizione delle mappe dei binding (risoluzione). Viene emesso un avviso consultivo quando un percorso di sottochiave compare sia sotto maps.infra sia sotto maps.values nei binding del Manifest. Un percorso che compare in entrambi gli elenchi di pilastri è incoerente — una singola sottochiave di annotazione non può instradare verso entrambi i pilastri contemporaneamente, e lo spareggio deterministico che il compilatore applica (un percorso presente in entrambi gli elenchi instrada verso infra; un’annotazione scritta nell’Aggregate può instradare solo tramite values, quindi una scritta lì per quel percorso viene rifiutata) è una rete di sicurezza, non una forma di authoring prevista. L’avviso non è bloccante; gli autori che eseguono ignorando l’avviso ottengono comunque una build pulita, con lo spareggio visibile nella provenienza IR.

Visualizzazione della provenienza in aggrega inspect. Il comando inspect visualizza una parentesi per ogni collegamento di Feature, che registra l’origine di ogni foglia popolata:

  • [explicit] — la Feature è stata collegata esplicitamente tramite un blocco features: di un Aggregate o di una Release.
  • [annotation: <key> from <source>] — ogni foglia popolata proviene dalla stessa chiave di annotazione. La parentesi nomina la chiave e il punto in cui l’annotazione è stata dichiarata: il file e il percorso puntato della chiave al suo interno.
  • Parentesi per foglia — composizione tra lati in cui ogni foglia popolata viene visualizzata con la propria parentesi di origine (alcune [explicit], alcune [annotation: <key> from <source>]). Questa forma fa emergere il merge in cui l’esplicito prevale campo per campo: quando un collegamento esplicito e un contributo di annotazione puntano alla stessa istanza di Feature sullo stesso Component ma scrivono foglie diverse, entrambi i contributi restano sulle rispettive foglie e l’output di inspect nomina individualmente l’origine di ogni foglia.

La visualizzazione di inspect legge le mappe per pilastro values_provenance e infra_provenance dell’IR — popolate durante l’espansione delle annotazioni insieme all’iniezione dei collegamenti sintetici — ed emette la forma di parentesi che meglio riassume l’origine collettiva delle foglie. Il meccanismo di inspect è la superficie di introspezione canonica per capire perché un determinato collegamento di Feature è finito su un determinato Component e da dove provengono i suoi valori.