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

Invarianti architetturali

Questi otto invarianti sono le regole fondanti di Aggrega. Valgono in tutte le release, nel core del compilatore, nel livello degli schemi, nel catalogo e nella superficie dei plugin Wasm. Ogni decisione di progettazione, ogni funzionalità e ogni entità scritta li rispetta.

Gli altri capitoli dell’architettura fanno riferimento alle invarianti per numero. Quando un capitolo successivo dice «secondo l’Invariante 2» o «per la regola della String Pipe (Invariante 3)», rimanda a questa pagina.

1. Il compilatore è neutrale rispetto ai contenuti, privo di opinioni e agnostico rispetto all’intento dell’utente

Il compilatore di Aggrega è un instradatore di testo Ahead-Of-Time (AOT). Analizza YAML, attraversa grafi, valuta intersezioni di etichette e convoglia stringhe dalle sorgenti alle destinazioni. Non controlla ciò che gli autori inseriscono in values, parameters, infra, provides o locals. Non impone convenzioni di denominazione, convenzioni sulle porte o le etichette semantiche che un Architect inventa.

Molte regole che sembrano regole del compilatore — il contratto Zero-Port, lo stile di catalogo Naked-Base / Flavored-Edges, la scelta della primitiva operativa adatta a un dato componente — sono contratti sociali: best practice con vie d’uscita, sostenute dagli architetti di piattaforma che scrivono il catalogo della libreria standard. Il compilatore non le interpreta.

Questa invariante riguarda ciò che il compilatore deduce dal contenuto che scrivi, e quell’ambito è tutto ciò che copre. Una manciata di chiavi appartiene ad Aggrega — riservate, con i valori che accettano scritti nello schema pubblicato — e lo schema le verifica come verifica qualsiasi altro campo dichiarato. component.aggrega.ai/type è una di queste: il suo insieme di valori è chiuso, e un documento che porta un valore al di fuori di esso viene rifiutato al caricamento. Questa è la piattaforma che dichiara che cosa significa la propria chiave, non il compilatore che attribuisce un significato a una stringa che hai scritto, e lascia ogni tua chiave esattamente tanto non controllata quanto dice questa invariante. Un catalogo che classifica i componenti su un asse che Aggrega non definisce scrive una propria chiave di etichetta, che lo schema accetta con qualsiasi valore stringa e che ogni superficie di selezione legge allo stesso modo.

Ciò che il compilatore impone è circoscritto: la validazione degli schemi, il parsing YAML, la costruzione del grafo, la valutazione dei template e il semplice instradamento testuale del contratto di iniezione. Tutto il resto è convenzione, imposta al momento della scrittura del catalogo o all’interno del socket di governance Wasm opzionale.

Le aziende che scrivono i propri cataloghi interni sono esplicitamente libere di infrangere le convenzioni della libreria standard. Il compilatore accetta qualsiasi cosa scrivano, a condizione che superi la validazione dello schema. L’architettura promuove le best practice; non costruisce prigioni.

2. Purezza AOT: il compilatore non ha accesso alle informazioni di runtime

Aggrega è un compilatore Ahead-Of-Time. In fase di compilazione:

  • Non si autentica presso le API cloud.
  • Non recupera indirizzi IP attivi, nomi DNS o URL generati dal cloud.
  • Non risolve i segreti in chiaro: i segreti restano puntatori di metadati in tutta la rappresentazione intermedia (Intermediate Representation).
  • Non conosce lo stato di runtime dei cluster o dei servizi di destinazione.
  • Non può recuperare dati che non esistono ancora (endpoint successivi al provisioning, porte assegnate dinamicamente, nomi di risorse generati automaticamente).

Tutto ciò che dipende dallo stato di runtime è espresso come stringa puntatore deterministica — un nome DNS stabile, una stringa di interpolazione Terraform, un riferimento a una risorsa CloudFormation — fornita dalla Ops Recipe. Il compilatore fa passare il puntatore senza risolverlo. È l’ambiente di runtime (il cluster, il gestore dello stato IaC) a risolvere i dati fisici finali.

Questa è la vera inversione del controllo (True Control Inversion): gli sviluppatori dettano un Injection Contract nell’Aggregate, il compilatore collega puntatori deterministici in anticipo e l’ambiente di runtime risolve i dati fisici finali. I requisiti che richiedono davvero una risoluzione a runtime appartengono alla pipeline Wasm di una Ops Recipe, non al nucleo del compilatore.

3. La String Pipe: il compilatore non può dedurre il significato

Il compilatore non interpreta il significato dei valori convogliati. Quando il Component A usa il Component B, il compilatore prende lo scalare che la Recipe del Component B produce tramite provides — una stringa, un numero o un booleano — e lo convoglia nel contesto della Recipe del Component A, convertito in stringa in modo deterministico al confine di iniezione. Che quel valore sia un FQDN, un hostname locale, un IP letterale, un numero di porta o un DSN formattato da Wasm non fa alcuna differenza: il compilatore non valida l’instradabilità, la correttezza del protocollo né l’appropriatezza semantica.

Ne seguono due conseguenze:

  • Il compilatore non indovina lo scopo di un componente dal nome. Un componente chiamato database-production non viene riconosciuto come database. Le etichette di tipo semantico come component.aggrega.ai/type (quando presenti) sono metadati opachi usati per la corrispondenza delle etichette, non logica di diramazione del compilatore.
  • Il compilatore non distingue un hostname da un nome di database, da un numero di porta o da un valore opaco arbitrario. Sono tutte voci scalari nel contesto di iniezione, consegnate come stringhe.

La triade della topologia — provides sulla Recipe che produce, uses sull’Aggregate che consuma, inject sull’arco — è l’Injection Contract. Il compilatore valuta etichette e passa stringhe; l’interpretazione è il contratto di scrittura tra Recipe e Component.

4. Nessuna infrastruttura fantasma: il compilatore non inventa mai risorse di calcolo o funzionalità

Il compilatore non inietta mai in modo silenzioso risorse di calcolo, Features, annotazioni, proxy di instradamento o qualsiasi altra risorsa che l’autore non abbia dichiarato esplicitamente. Le violazioni delle policy producono guardrail espliciti (Loud Guardrails) — la build si interrompe con un errore specifico che dice all’autore che cosa correggere, nel documento che ha scritto — e non mutazioni silenziose che generano misteri infrastrutturali al momento del debug.

Le risorse entrano nel grafo attraverso dichiarazioni esplicite in fase di scrittura:

  • L’Aggregate dello sviluppatore (componenti, archi uses, collegamenti di Feature).
  • I collegamenti di Feature della Release (aggiunte a livello di operatore).
  • L’espansione guidata dalle annotazioni (il Manifest dichiara i binding annotazione → Feature; l’annotazione su un Component o su un confine è una dichiarazione esplicita).
  • La produzione di risorse a livello di Recipe: il rendering di source della Recipe produce l’artefatto principale; la sintesi del workload emette la forma di deployment specifica del provider (spec di Pod, servizio Compose, ecc.); le voci di artifacts: (inline o caricate con $import:) emettono manifest ausiliari intrinseci alla Recipe; la generazione di risorse delle FeatureRecipe emette risorse ausiliarie per ogni Feature, attivate da un collegamento esplicito di Feature.

I percorsi a livello di Recipe sono dichiarazioni in fase di scrittura a un passo di distanza: l’autore della Recipe scrive source / workload / artifacts / valuesMapping rispetto a un contratto di Component, e l’Aggregate dello sviluppatore seleziona quali Components partecipano. Una risorsa che compare nell’output renderizzato risale a una dichiarazione nell’Aggregate, nella Release, in un binding di annotazione, oppure alla scrittura della Recipe selezionata dai tipi di componente dell’Aggregate.

La sintesi trasforma le forme dichiarate dall’autore nei formati di output specifici del provider. Una spec di Workload scritta come mappa di container può essere renderizzata come spec di Pod Kubernetes, come blocco di servizio Compose o come modulo Terraform: la trasformazione è guidata dal provider, ma le risorse risalgono alla dichiarazione di Workload dell’autore.

Il socket di governance porta un ruolo per ciascun collegamento, ed è il ruolo — non il tipo del plugin — a stabilire che cosa un collegamento può fare a una build. Un plugin di governance collegato in un ruolo di verdetto — che esamina il grafo IR (ir-verdict) o gli artefatti renderizzati (render-verdict) — può rifiutare una build ma non può modificarla. Se un verdetto di questo tipo vuole che venga aggiunta una risorsa, fa fallire la build con un’indicazione di rimedio, così che sia l’autore stesso ad aggiungere la risorsa; l’host legge l’output di un verdetto solo come accettazione o rifiuto e non lo applica mai come modifica, quindi una riscrittura non richiesta del grafo per renderlo conforme — esattamente l’infrastruttura fantasma che questa invariante vieta — non può provenire da un ruolo di verdetto. Un plugin di governance collegato in un ruolo di trasformazione (label-transform o annotation-transform) è l’eccezione circoscritta ed esplicita: un operatore che ne collega uno — su richiesta, tramite la configurazione plugins.governance del workspace — ha dichiarato quella trasformazione, quindi le modifiche che apporta sono una dichiarazione esplicita, con lo stesso status dell’espansione guidata dalle annotazioni, non un’iniezione silenziosa. La distinzione è l’invito: un verdetto non richiesto non può riscrivere la build, mentre una trasformazione collegata esplicitamente può farlo, perché l’operatore l’ha chiesta. Poiché una trasformazione dà forma all’output renderizzato, viene fissata nel lockfile come ogni plugin che dà forma all’output: la trasformazione che si applica è stabilita al momento del pull, quindi cambiarla significa rieseguire il pull anziché uno spostamento silenzioso tra una build e l’altra; un verdetto non dà forma ad alcun output e non viene fissato.

5. L’Aggregate è la superficie di scrittura; la Release non può dichiarare values:

Lo schema della Release vieta meccanicamente un blocco values:. Gli operatori non possono scrivere values su un Component o su una Feature a partire da una Release. Si tratta di un’imposizione dello schema a livello di JSON Schema — non un contratto sociale, non una convenzione — ed è esplicita: ogni documento di entità viene validato rispetto allo schema del suo tipo al caricamento, quindi una Release che contiene values: interrompe la build con una diagnostica che indica il file e la chiave incriminata, invece di essere ignorata in silenzio.

Questo non significa che i valori siano identici in tutti gli ambienti. Il percorso supportato per la variazione per ambiente è il sollevamento dei parametri (Parameter Hoisting):

  1. Lo sviluppatore espone un campo tipizzato parameters.* nell’Aggregate.
  2. Il template values del Component vi fa riferimento: storage_size: "{{ .parameters.db_size }}".
  3. La Release valorizza il parametro: parameters: { db_size: "100Gi" }.
  4. L’output renderizzato riflette il valore specifico dell’ambiente.

L’Aggregate resta l’unica fonte di verità su quali valori sono esposti alla variazione per ambiente (la dichiarazione parameters) e su come confluiscono nei valori del componente (il riferimento nel template). La Release valorizza; non sovrascrive.

Altri due vincoli proteggono la stessa invariante:

  • Quando una Release usa extends, dichiarare un puntatore aggregate: è vietato dallo schema. La Release figlia deve distribuire lo stesso intento dello sviluppatore (Developer Intent) della sua Release padre.
  • La Release non può introdurre risorse di calcolo che l’Aggregate non ha dichiarato, né può reindirizzare un arco dichiarato dallo sviluppatore. All’interno dei socket che l’Architect ha dichiarato, la Release può collegare e configurare archi tra componenti esistenti: imposta l’infra per arco su un arco collegato dallo sviluppatore, oppure collega a un componente esistente un arco verso un socket dichiarato ma non associato. Non può dichiarare values per arco (quelli restano nell’Aggregate), associare un socket che lo usesSchema del Component non dichiara, né puntare un arco verso un componente che non esiste: ciascuno di questi casi interrompe la build. Nota quale dichiarazione intende la clausola centrale: il socket deve comparire nello usesSchema del Component di catalogo. L’autore di un Aggregate può nominare un socket che il suo tipo di componente non dichiara, e la superficie della Release volutamente non viene aperta allo stesso modo: un operatore collega e configura all’interno di un’architettura invece di inventarne una.

La configurazione di connessione per arco ha come ambito il consumatore: i values e l’infra portati da un arco compaiono solo nel contesto di rendering del nodo che ha scritto l’arco, mai nel contesto della destinazione. L’output renderizzato di un componente è quindi invariante rispetto alle connessioni che altri componenti stabiliscono verso di esso: collegare o configurare un arco verso una destinazione non altera mai ciò che la Recipe della destinazione renderizza. L’unico punto in cui quelle connessioni sono visibili è una Feature collegata alla destinazione: la sua FeatureRecipe può leggere quali componenti usano la destinazione, quindi le risorse che emette — per esempio una policy che ammette esattamente i chiamanti dichiarati — seguono il collegamento, mentre l’output della destinazione no. Anche lì, i values e l’infra per arco restano al consumatore.

6. Il confine ABI di WebAssembly: l’intelligenza specifica del dominio vive in Wasm

Il binario host in Go non contiene alcuna logica specifica del cloud o dell’infrastruttura. Tutta l’intelligenza specifica del dominio, il rendering dei template e la formattazione vivono rigorosamente all’interno di plugin WebAssembly eseguiti dal runtime Wazero incorporato. L’host Go orchestra la pipeline e passa i payload attraverso l’ABI ai guest Wasm come puntatori di memoria, nella codifica che ciascun socket porta.

Ne seguono due corollari:

  • La logica specifica del Provider (rendering specifico di Helm, formattazione specifica di Terraform, unione specifica di Compose) non vive mai nel nucleo del compilatore Go. Il compilatore risolve il nome del provider che una Recipe dichiara in spec.capability nel Plugin di rendering del provider che lo serve e invia il nodo a quel plugin; la traduzione stessa avviene interamente nel guest Wasm. L’host non contiene codice Go per singolo provider per un provider standard, quindi non c’è nulla nel processo a cui ripiegare: un nome di provider che non si risolve in alcun Plugin che lo serva interrompe la build invece di renderizzare un qualche default integrato.
  • La logica delle policy (regole di sicurezza, controlli di conformità, calcoli FinOps) non vive mai nel nucleo del compilatore Go. Le policy appartengono al socket di governance Wasm che le aziende scelgono di attivare: un plugin collegato in un ruolo di verdetto (ir-verdict / render-verdict) per accettare o rifiutare una build, oppure in un ruolo di trasformazione (label-transform / annotation-transform) per dare forma alle etichette o alle annotazioni.

Il confine ABI mantiene il nucleo Go compatto, verificabile e indipendente dal cloud. Sostituire la logica di rendering di un provider significa sostituire un artefatto Wasm, non ricompilare Aggrega stesso.

7. Separazione delle responsabilità (suddivisione in quattro domini): una guida, non una prigione

Le linee guida di progettazione di Aggrega separano la scrittura in quattro domini:

  • Developer Intent — Aggregate.
  • Platform Architect — entità di catalogo Component e Feature.
  • Platform Ops — Recipe, FeatureRecipe, Plugin (incluso il Plugin di rendering del provider).
  • Platform Operator — Manifest, Release.

Il deployment tipico e ben funzionante segue questa suddivisione: gli sviluppatori scrivono l’intento applicativo, non l’infrastruttura fisica; gli Ops scrivono l’infrastruttura fisica, non la logica applicativa. Aggrega è progettato per essere usato così, e la documentazione ufficiale, gli esempi e il catalogo della libreria standard sono scritti in funzione di questa suddivisione.

La suddivisione in quattro domini è una guida e un’impostazione progettuale, non un’imposizione del compilatore. Il compilatore (secondo l’Invariante 1) è privo di opinioni. Gli utenti sono liberi di:

  • Accorpare i ruoli (una sola persona che scrive sia gli Aggregates sia le Recipes).
  • Mescolare le responsabilità (gli Architect che codificano etichette di conformità direttamente sui Components core/* quando i cataloghi aziendali lo richiedono).
  • Attraversare i confini tra domini (gli sviluppatori che usano il sollevamento dei parametri per iniettare aspetti infrastrutturali nell’Aggregate quando il codice legacy lo richiede).

Il compilatore accetta qualsiasi schema di scrittura che superi la validazione dello schema. L’architettura promuove le best practice; i vincoli a livello di schema (come il divieto di values: nella Release dell’Invariante 5) sono gli unici attraversamenti di dominio che il compilatore rifiuta davvero. Ogni altra separazione è un contratto sociale sostenuto dagli autori dei cataloghi e, dove le aziende scelgono di attivarlo, dal socket di governance Wasm.

8. Output deterministico

A parità di input, il compilatore produce un output identico byte per byte. Due compilazioni dello stesso Aggregate + Release + Manifest rispetto allo stesso catalogo producono artefatti renderizzati che risultano uguali byte per byte.

È il contratto su cui si basano gli strumenti GitOps e i flussi di revisione basati sui diff. Una pull request che non ha cambiato l’input non dovrebbe produrre alcun diff nell’output renderizzato. Una pull request che ha cambiato l’input dovrebbe mostrare solo il diff implicato da quella modifica: nessun riordinamento spurio, nessun rimescolamento di timestamp, nessun artefatto dovuto all’iterazione delle mappe.

L’output deterministico è garantito da tre discipline:

  • Mappe ordinate dall’autore: ogni mappa il cui ordine di iterazione potrebbe influire sull’output renderizzato usa un contenitore di mappa ordinata, così che l’iterazione segua l’ordine di dichiarazione dell’autore anziché l’ordine degli hash.
  • Nessun contenuto basato sull’orologio di sistema o casuale negli artefatti renderizzati, a meno che l’autore non l’abbia iniettato esplicitamente tramite l’input del template.
  • Il rendering è puro: la stessa invocazione del guest Wasm con lo stesso input produce lo stesso output.

Il flag --trace del compilatore (vedi language-reference/cli/aggrega-build.md) offre ad autori e operatori una superficie di verifica per questa invariante. Due compilazioni dello stesso input con --trace abilitato producono dump di traccia identici byte per byte; qualsiasi diff in una singola passata localizza una regressione. Il determinismo non è solo una proprietà al momento del rilascio: è osservabile in ogni stato intermedio del compilatore attraverso il layout di traccia per nodo.

L’output deterministico è il contratto che rende Aggrega sicuro da usare come fonte di verità in un ciclo GitOps.

Ambito dell’invarianza tra i livelli di risoluzione

La garanzia di output identico byte per byte riguarda gli artefatti fissati nel lockfile: le entità risolte tramite artefatti di registry i cui digest sono registrati nel lockfile (il livello del registry del modello di risoluzione delle entità a tre livelli). Quando una build legge i file che una Release nomina tramite percorso (percorsi locali che iniziano con ./ o ../) o entità nelle directory di catalogo del workspace (catalog_dirs:, nel livello del workspace e della cache), l’invarianza dipende dal fatto che quei file restino invariati tra una build e l’altra. Il lockfile registra un’entità in una directory di catalogo del workspace tramite il digest del suo documento e dei file che dichiara, quindi una build si interrompe su un’entità cambiata dopo il pull invece di renderizzarla, con un’eccezione: una Recipe o una FeatureRecipe che il Manifest nomina con un riferimento che è anche il nome di un Component o di una Feature viene registrata sotto quel riferimento come Component o Feature, quindi i suoi input sono vincolati solo dai pin presenti accanto a essa nel lock, e una modifica al suo stesso documento non viene rilevata. Mantenere i file come erano è responsabilità del sistema di controllo del codice sorgente (tipicamente Git).

Un riferimento a un percorso locale il cui file sottostante cambia tra due compilazioni produce un diff legittimo nell’output renderizzato anche se la forma dell’input del compilatore è invariata: la garanzia di output deterministico è preservata (stesso input in byte → stesso output in byte), ma gli input differiscono perché il file locale è cambiato. I cataloghi che hanno bisogno di invarianza tra build per ogni sorgente scaricano gli artefatti da un registry nella cache fissata dal lockfile invece di leggerli da un percorso locale o da una directory del workspace; il lockfile è l’ancora dell’identità byte per byte.