La tassonomia delle entità
L’architettura di Aggrega è organizzata in quattro domini, ciascuno di proprietà di una persona diversa e contenente tipi di entità specifici, più un livello di librerie di Tier 3 — il terzo livello del modello a livelli delle entità del riferimento del linguaggio — che contiene contenuti riutilizzabili di schema, mapping, workload e artefatti. La panoramica seguente mostra come i quattro domini e le librerie di Tier 3 si relazionano tra loro; ogni sezione successiva si apre con un diagramma delle proprie entità, in cui un’entità di un altro dominio è disegnata con un contorno tratteggiato. Le superfici di authoring dettagliate (campi, schemi, esempi) di ciascuna entità si trovano nel catalogo delle entità del riferimento del linguaggio.
graph TD
Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
Libs["<b>Tier 3: Libraries</b>"]
Intent -->|"requests, attaches"| Catalog
Intent -->|"binds via"| Routing
Routing -->|"attaches"| Catalog
Catalog -->|"resolved to"| Infra
Routing -->|"resolves, renders via"| Infra
Catalog -.->|"$ref"| Libs
Infra -.->|"$import"| Libs
Il corpus si estende su quattro domini più il livello di librerie di Tier 3:
| # | Entità | Dominio | Ruolo |
|---|---|---|---|
| 1 | Aggregate | Dominio 1 — Intento dello sviluppatore | Progetto della topologia applicativa |
| 2 | Component | Dominio 2 — Platform Catalog | Interfaccia astratta di nodo di calcolo |
| 3 | Feature | Dominio 2 — Platform Catalog | Tratto operativo (incluse le Features di credenziali) |
| 4 | Recipe | Dominio 3 — Base dell’infrastruttura | Implementazione di un Component, per provider |
| 5 | FeatureRecipe | Dominio 3 — Base dell’infrastruttura | Implementazione di una Feature, per provider |
| 6 | Plugin | Dominio 3 — Base dell’infrastruttura | Plugin WebAssembly indirizzato per contenuto (rendering dei provider, passi di pipeline, linting) |
| 7 | Manifest | Dominio 4 — Instradamento e policy | Lockfile delle dipendenze che mappa le interfacce sulle Recipes |
| 8 | Release | Dominio 4 — Instradamento e policy | Router di deployment che lega l’Aggregate al Manifest |
| 9 | SchemaLibrary | Tier 3 — Librerie | Definizioni JSON Schema 2020-12 riutilizzabili |
| 10 | MappingLibrary | Tier 3 — Librerie | Frammenti di template Go riutilizzabili |
| 11 | WorkloadLibrary | Tier 3 — Librerie | Frammenti di template di Workload riutilizzabili |
| 12 | ArtifactLibrary | Tier 3 — Librerie | Bundle di artefatti con nome riutilizzabili |
Quella tabella è l’insieme completo dei tipi di entità di authoring, i tipi che un autore dichiara in un campo kind:. Il tipo Workload è un contenuto di proprietà della piattaforma incorporato nell’input sintetizzato di una Recipe anziché un’entità di catalogo autonoma (vedi il capitolo 16), per cui è deliberatamente assente dalla tabella precedente.
Il Plugin è un’entità di authoring di prima classe — con un proprio kind, un proprio JSON Schema e una propria directory di catalogo — di proprietà di Platform Ops nel Dominio 3. Un Plugin è un riferimento indirizzato per contenuto a un artefatto WebAssembly, che dichiara l’unico tipo di socket che implementa. La tassonomia ha sette membri: provider (rende i nodi IR in artefatti nativi del provider), linter (solleva diagnostiche sul contenuto scritto), pipeline-step (un passo di una feature-recipe-pipeline), governance (svolge un ruolo di governance — trasforma label o annotazioni, oppure restituisce un verdetto di accettazione/rifiuto sul grafo IR o sugli artefatti renderizzati), cli (aggiunge un sottocomando aggrega che un operatore invoca dalla riga di comando), parser (trasforma un testo sorgente esterno in un albero strutturato canonico) e importer (trasforma una sorgente esterna di infrastruttura o di definizione di agenti in bozze di file di authoring di Aggrega). Un Plugin di rendering del provider (pluginType: provider) è l’unità che serve il rendering del provider: dichiara il nome o i nomi di provider che renderizza in spec.provider.capabilities e porta il resto dei propri metadati di socket del provider nello stesso blocco spec.provider. Il compilatore fissa e instrada il riferimento; il runtime WebAssembly esegue i byte; il compilatore non interpreta ciò che il plugin fa — il plugin è il veicolo dell’intelligenza specifica di dominio che vive in WebAssembly. La sua superficie di authoring e di metadati è documentata in language-reference/entities/plugin.md.
Dominio 1: intento dello sviluppatore (il «cosa»)
graph LR
classDef ext stroke-dasharray:5 4;
A["Aggregate<br/>The 'What'"]
CC["Component"]:::ext
CapC["Feature"]:::ext
EB["Release"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
A -->|"Binds via"| EB
- Ruolo: lo sviluppatore. Si concentra esclusivamente sull’architettura AI, sui cicli cognitivi e sui requisiti di sopravvivenza dell’applicazione. Non ha bisogno di conoscere CEL, OPA o le porte fisiche.
- 1. Aggregate: il progetto dichiarativo basato su mappe della topologia applicativa. Che funga da Aggregate radice costruito da una Release o da modulo parametrizzato e riutilizzabile, definisce
componentslogici e collega, sottofeatures, le Features il cui comportamento è intento applicativo, con i relativivalues; una Feature i cui input sono tutti operativi viene invece collegata dall’operatore nella Release (vedi il dominio 4). Una credenziale si richiede su quella stessa superficie di collegamentofeatures, tramite una Feature di credenziali: non esiste un blocco separato per essa. Definisce requisiti di capacità astratti tramiteparameters(contratti tipizzati scritti nel vocabolario della forma compatta) e lo stato del payload tramitevalues. Le istanze di Component supportano un campodescriptionopzionale per la documentazione e il rendering nello Studio. Promuove la convenzione «Zero-Port» (astrarre le porte di rete a meno che non siano esplicitamente richieste da codice preesistente) senza alcuna piattaforma di destinazione o namespace codificati in modo fisso.
Dominio 2: Platform Catalog (le «interfacce e intelligenza»)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release"]:::ext
CC["Component<br/>The Compute Interface"]
CapC["Feature<br/>The Operational Trait"]
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
EB -.->|"Attaches"| CapC
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
- Ruolo: il Platform Architect. Il «programmatore» della piattaforma. Colloca ogni componente nell’ontologia operativa, scrive le policy programmabili (mutatori e validatori Wasm) e stabilisce le etichette semantiche di duck typing.
- 2. Component: l’interfaccia astratta di un nodo di calcolo. Dichiara la propria forma di base tramite l’ontologia cloud operativa (ad es.
component.aggrega.ai/type: server) e stratifica la propria identità cognitiva tramite etichette di duck typing (ad es.model.aggrega.ai/capability: generative). Dichiara gli slot delle credenziali tramitefeaturesSchema(obbligatori/opzionali, blackbox/trasparenti) e usaschema:(JSON Schema 2020-12, di norma scritto con la notazione abbreviata della forma compatta) per validare rigorosamente il bloccovaluesopaco dello sviluppatore. - 3. Feature: un tratto operativo modulare (ad es. mascheramento dei dati, instradamento DNS, gestione dei segreti). Usa selettori di etichette
appliesToper legarsi dinamicamente a specifiche etichette semantiche. Come i Components, dichiara gli slot delle credenziali tramitefeaturesSchemaper imporre il provisioning delle chiavi API. Soprattutto, usametadata.annotationsper etichettare esplicitamente gli elementi nel grafo IR piatto, il che indica ai validatori di policy Wasm e ai plugin di rendering a valle come gestire il payload di configurazione della Feature.- Features di credenziali: la piattaforma unifica la gestione delle credenziali nell’entità Feature: una Feature con l’etichetta
feature.aggrega.ai/kind: secretè una feature di credenziali, che definisce un’interfaccia di interrogazione verso un archivio di segreti (ad es. AWS Secrets Manager, HashiCorp Vault). Si collega sottofeatures:come qualsiasi altra Feature, sulla stessa superficie e con la stessa forma; l’etichetta è un metadato che il catalogo riporta per descrivere ciò che il collegamento produce, e nessun ramo del compilatore la legge. Non esiste un kind separato per l’archivio di segreti o per la recipe di segreti: una FeatureRecipe di credenziali ha la stessa forma di qualsiasi altra FeatureRecipe, la pipeline di recupero e consegna è la stessa per entrambe e il contratto di consegnainject(env,file,arg) è condiviso. Un’entità, una parola chiave di collegamento, un percorso di esecuzione dei modificatori attraverso il rendering; e le credenziali si mappano sottofeatures.typenel Manifest.
- Features di credenziali: la piattaforma unifica la gestione delle credenziali nell’entità Feature: una Feature con l’etichetta
L’ontologia come etichetta. L’ontologia cloud operativa è dichiarata in metadata.labels["component.aggrega.ai/type"] anziché come campo spec.type di primo livello. Questa scelta consente al motore dei selettori di etichette del compilatore di puntare direttamente ai valori dell’ontologia: una Feature dichiara appliesTo: "component.aggrega.ai/type in (server, worker)" per collegarsi dinamicamente a ogni componente server o worker senza alcuna nuova logica Go nel compilatore centrale. Lo stesso meccanismo dei selettori si applica a ogni etichetta di Aggrega, per cui una Feature, un selettore di socket o una mappatura dei confini di una Release legge la chiave di etichetta propria di un catalogo esattamente come legge questa.
component.aggrega.ai/type è la chiave di Aggrega, e il suo insieme di valori è chiuso: lo schema pubblicato del Component enumera le primitive, e un documento che riporti qualsiasi altro valore viene rifiutato al caricamento, con E0215 che nomina l’etichetta ed elenca ciò che accetta. Un catalogo che necessita di una classificazione che Aggrega non definisce aggiunge la propria chiave di etichetta accanto a essa (lo schema del Component accetta qualsiasi ulteriore chiave di etichetta con un valore stringa), per cui un nuovo asse costa una chiave tua e nessuna release del compilatore, mentre la chiave riservata mantiene un unico significato ovunque. È questo che fa funzionare una Feature scritta per component.aggrega.ai/type in (stateful-server) con Components di autori che non si sono mai incontrati.
Dominio 3: base dell’infrastruttura (le «implementazioni»)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
ENV["Manifest"]:::ext
EB["Release"]:::ext
CD["Recipe<br/>The Implementation"]
CapD["FeatureRecipe<br/>The Binding"]
T["Plugin<br/>The Wasm Plugin"]
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
EB -->|"Renders via"| T
- Ruolo: l’ingegnere dell’infrastruttura / Ops. Possiede la realtà fisica, l’assegnazione delle porte di rete e la logica di templating.
- 4. Recipe: il template di traduzione multi-provider (ad es. Helm o Docker Compose). Stabilisce un contratto API rigoroso 1:1 con il componente del catalogo tramite la parola chiave
implements. La Recipe mappa i.valuesdello sviluppatore nel formato fisico. Codifica in modo fisso le porte di rete fisiche (ad es.5432) e legge iprovidesdella destinazione attraverso la pipe.context.uses, soddisfacendo il contratto di iniezione senza codificare in modo fisso i nomi dei database. - 5. FeatureRecipe: mappa esplicitamente una
Featuresu un’implementazione di infrastruttura concreta tramite la parola chiaveimplements. Impone una capability del provider di destinazione incapability(ad es.helm,compose). Poiché la piattaforma unifica la gestione delle credenziali nell’entità Feature, le FeatureRecipes gestiscono sia le feature operative (mascheramento dei dati, instradamento DNS, iniezione di sidecar) sia le feature di credenziali (generazione di CRD per i vault, montaggio di volumi di segreti). Per coprire tutto questo spettro, supporta tre blocchi di esecuzione distinti:pipeline: un array sequenziale di plugin WebAssembly (Wasm) per la mutazione del Workload dopo il rendering (ad es. iniettare un sidecar Envoy tramite JSONPatch o montare un volume di segreti).sourceevaluesMapping,workload,artifacts: gli stessi tre tipi di input che porta una Recipe, usati per la generazione di risorse, consentono agli Ops di eseguire nativamente il rendering di template statici (ad es. generare una nuova CRDHTTPRouteo una CRDExternalSecret) accanto al componente di base.injectMapping(intercettazione prima del rendering): un blocco di template Go nativo eseguito prima del rendering della Recipe di base. Produce un dizionario JSON che il compilatore unisce nativamente in profondità sopra la pipe di memoria.context.injectdel chiamante, consentendo la mutazione delle variabili d’ambiente e delle stringhe di connessione lato chiamante, senza Wasm.
- Il pattern FeatureRecipe per le credenziali: quando una FeatureRecipe implementa una Feature di credenziali (etichettata
feature.aggrega.ai/kind: secret), si applica il principio standard del Plugin in due parti: lapipelineconcatena un plugin Fetcher (che genera la CRD specifica del vault) seguito da un plugin Injector (che monta il segreto nel container di destinazione). La separazione Fetcher/Injector massimizza la riusabilità: passare da AWS Secrets Manager a HashiCorp Vault richiede solo di sostituire il plugin Fetcher; l’Injector resta identico.
- 6. Plugin: il plugin WebAssembly indirizzato per contenuto. Un Plugin di rendering per provider (
pluginType: provider) è l’unità che trasforma i tipi di input di una Recipe nel formato di file finale serializzato come stringa: dichiara inspec.provider.capabilitiesil nome o i nomi dei provider che serve (ad es.helm), espone un exportrender_nodea cui il compilatore invia le richieste e porta il resto dei metadati del proprio socket provider (workloadSchema,wellKnownAnnotations) in quello stesso bloccospec.provider. Gli altri tipi di socket che un Plugin può dichiarare sonopipeline-step,linter,governance,cli,parsereimporter. Il compilatore instrada il riferimento fissato; il runtime WebAssembly esegue i byte.
Dominio 4: instradamento e policy (il «collante»)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release<br/>The Deployment Router"]
ENV["Manifest<br/>The Dependency Lockfile"]
CapC["Feature"]:::ext
T["Plugin"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -->|"Binds via"| EB
EB -.->|"Attaches"| CapC
EB -->|"Uses"| ENV
EB -->|"Renders via"| T
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
- Ruolo: il Platform Operator / DevOps.
- 7. Manifest: il lockfile delle dipendenze. Usa una mappatura URI piatta: un dizionario
components.typemappa i tipi di componenti del catalogo sugli URI delle Recipe, e un dizionariofeatures.typemappa i tipi di Feature sugli URI delle FeatureRecipe. La risoluzione è una ricerca diretta degli URI nel lockfile e nel catalogo; la determinazione della capability deriva dal campospec.capabilitydi ciascuna Recipe risolta, al momento della build. Dopo la risoluzione, ogni entità deve avere una mappatura, altrimenti il compilatore si arresta. Per mantenere un ecosistema DRY, i Manifests supportano un pattern di composizione in stile Kustomize tramite la parola chiaveextends, che consente ai manifest specifici di un ambiente (come locale o staging) di ereditare in modo pulito da un manifest di base globale e di dichiarare solo le proprie sostituzioni specifiche. - 8. Release: il router. Lega un
aggregatea unmanifeste mappa i componenti su confini fisici (ad es.aws-eks-production). Per mantenere un flusso di lavoro DRY, le Releases supportano l’ereditarietà tramite la parola chiaveextends, che consente alle release specifiche di un ambiente di ereditare in modo pulito da una release di base globale. Soddisfa il contratto astratto dell’aggregate iniettando le realtà fisiche rigorosamente nel bloccoparameters, e inietta il dimensionamento fisico (come CPU o porte) tramite il namespace paralleloinfra. Per proteggere l’Aggregate come unica fonte di verità, lo schema della Release vieta meccanicamente un bloccovalues:: gli Ops non possono dichiararevaluessu alcun Component o Feature da una Release. La variazione per ambiente dei valori rivolti allo sviluppatore passa attraverso il Parameter Hoisting: lo sviluppatore espone un campo tipizzatoparameters.*nell’Aggregate, il templatevaluesdel Component vi fa riferimento e la Release soddisfa il parametro per il proprio ambiente. I valori prodotti differiscono tra gli ambienti, mentre l’Aggregate, la superficie di authoring che stabilisce quali valori esistono e come fluiscono, resta l’unica fonte di verità. Vedi il vincolo 4, «La Release non può sovrascrivere i valori dello sviluppatore», in Vincoli architetturali e pattern consigliati per il divieto a livello di schema enunciato esplicitamente. Soprattutto, per impedire Releases non tracciabili che «mutano l’aggregate», quando una Release usaextends, la dichiarazione di unaggregateviene rifiutata dallo schema della Release (il vincolo dello schema non consente di dichiarareaggregatequando si usaextends). La release figlia deve corrispondere esattamente allo stesso intento dello sviluppatore della release padre. Ilmanifest, invece, diventa opzionale, abilitando il «late binding»: gli Ops possono ereditare l’intera topologia fisica ma sostituire chirurgicamente il lockfile delle dipendenze.- Collegamento delle Feature: anche la Release collega Features, sotto
featuressu un confine o su un singolo componente. Una Feature i cui input sono tutti operativi la collega direttamente, con il suotypee il suoinfra; una Feature collegata dall’Aggregate la dimensiona, scrivendo l’infradi quel collegamento sotto lo stesso nome.
- Collegamento delle Feature: anche la Release collega Features, sotto
Perché separare il Manifest dalla Release. Separare il lockfile del software (Manifest) dal router di deployment (Release) rende possibile una forma che le due entità non potrebbero produrre da sole: DevOps distribuisce una singola applicazione su più router di deployment regionali (diverse Releases che puntano a diverse regioni cloud, tutte con riferimento allo stesso Manifest) senza duplicare i binding delle Recipe tra gli ambienti. Ogni Release regionale porta la propria disposizione dei confini e i parametri specifici dell’ambiente, consumando lo stesso lockfile del software fornito dal Manifest. Lo scaling multi-regione deriva dalla separazione dei domini, non dalla duplicazione del Manifest.
Tier 3: librerie (riuso del catalogo)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
SL["SchemaLibrary<br/>JSON Schema definitions"]
ML["MappingLibrary<br/>Go template fragments"]
WL["WorkloadLibrary<br/>Workload template fragments"]
AL["ArtifactLibrary<br/>Named artifact bundles"]
CC -.->|"$ref"| SL
CapC -.->|"$ref"| SL
CD -.->|"valuesMapping $import"| ML
CapD -.->|"$import"| ML
CD -.->|"workload $import"| WL
CD -.->|"artifacts $import"| AL
CapD -.->|"$import"| AL
- Ruolo: il Platform Architect (la stessa persona del dominio 2), ma il ruolo entra in gioco solo quando il contenuto del catalogo cresce abbastanza da trarre vantaggio dal riuso degli schemi tra un Component e l’altro o dal riuso tra una Recipe e l’altra di template, forme di workload o bundle di artefatti. Gli autori singoli e i cataloghi piccoli si distribuiscono senza alcuna entità di Tier 3.
- 9. SchemaLibrary: definizioni JSON Schema 2020-12 riutilizzabili. Una libreria dichiara schemi con nome in
spec.schemas:e helper parametrizzati opzionali inspec.templates:(con dichiarazioni$params:e riferimenti$instantiate:per il riuso parametrico). Le entità del catalogo consumano le voci della libreria tramite la parola chiave JSON Schema standard$ref:che punta alla voce della libreria per identità, nella forma senza host<library>#/schemas/<name>(la versione proviene dal lockfile, non dal riferimento). Nomi in PascalCase, distribuzione tramite OCI, versione fissata nel lockfile. Facoltativa, per i cataloghi che necessitano del riuso degli schemi tra un Component e l’altro: forme comuni comePodResources,PersistenceSpec,NodePool,MetricsServiceMonitorricorrono in ogni Component di datastore e in ogni Component di workload, e le voci della SchemaLibrary eliminano questa ripetizione dalla definizione di ciascun Component. - 10. MappingLibrary: frammenti di template Go riutilizzabili. Una libreria dichiara template con nome in
spec.mappings:. Le Recipes e le FeatureRecipes consumano le voci della libreria per identità tramitevaluesMapping: { $import: <library>#/mappings/<name> }. Un’unica modalità di authoring (solo template Go); nessun percorso di authoring parallelo in Jsonnet. Facoltativa, per i cataloghi che necessitano del riuso dei mapping tra una Recipe e l’altra: pattern comuni come la logica degli helper dei chart Bitnami o i pattern condivisi dei template dei pod ricorrono in ogni Recipe di datastore che punta allo stesso provider, e le voci della MappingLibrary eliminano questa ripetizione dalla definizione di ciascuna Recipe. - 11. WorkloadLibrary: frammenti di template di Workload riutilizzabili. Una libreria dichiara voci di workload con nome in
spec.workloads:. Una Recipe consuma una voce per identità tramiteworkload: { $import: <library>#/workloads/<entry> }, e il corpo importato viene validato rispetto allo schema del Workload di proprietà della piattaforma esattamente come un bloccoworkload:inline, per cui un workload importato da una libreria produce lo stesso rendering dell’equivalente inline. Un’unica modalità di authoring (solo template Go). Facoltativa, per i cataloghi che necessitano del riuso dei workload tra una Recipe e l’altra, quando diverse Recipes condividono un’unica forma di deployment e differiscono solo per i valori. - 12. ArtifactLibrary: bundle di artefatti con nome riutilizzabili. Una libreria dichiara bundle con nome in
spec.artifacts:, ciascuno dei quali raggruppa i file di output che vanno insieme (ad esempio una CRD, il suo RBAC e una ConfigMap) e viene importato come un’unica unità. Le Recipes e le FeatureRecipes consumano un bundle per identità tramiteartifacts.<name>: { $import: <library>#/artifacts/<name> }. Un’unica modalità di authoring (solo template Go). Facoltativa, per i cataloghi che necessitano del riuso degli artefatti tra una Recipe e l’altra, quando lo stesso insieme di risorse ausiliarie accompagna molte Recipes.
Ogni libreria viene pubblicata tramite OCI, è fissata nel lockfile (le sezioni schema_libraries:, mapping_libraries:, workload_libraries: e artifact_libraries:) e compare nella UI dell’Hub con la consapevolezza dei consumatori (quali Components fanno riferimento a quali voci di libreria; quali Recipes consumano quali voci di libreria).