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

Pipeline di compilazione (panoramica)

Questo capitolo descrive nel dettaglio la fisica interna del compilatore Go, definendo come lo YAML astratto viene tradotto in configurazioni fisiche lungo la pipeline di compilazione, il grafo della rappresentazione intermedia (IR) e i socket di esecuzione WebAssembly (Wasm).

La pipeline di compilazione e il flusso di esecuzione

Aggrega esegue una pipeline di compilazione Ahead-of-Time (AOT) rigorosa e a ordine fisso anziché una logica di orchestrazione codificata rigidamente. Avviato da aggrega build, il compilatore passa il grafo piatto tra socket WebAssembly (Wasm) isolati per valutare l’architettura prima di renderizzare gli artefatti fisici.

I socket Wasm girano su un host incorporato — il toolkit Extism sopra il motore Wazero — dietro un firewall di purezza AOT che nega a un plugin qualsiasi capacità di accesso a runtime (rete, file system, orologio di sistema, ambiente, I/O standard), così un plugin non può violare la garanzia deterministica e ahead-of-time. L’host esegue il publishing linter fuori banda, tramite aggrega lint. I gate in banda descritti di seguito — il ruolo label-transform del socket di governance alla costruzione della topologia e il suo ruolo IR-verdict all’analisi statica, più la pipeline di plugin che chiude il rendering — vengono eseguiti in ogni build: un ruolo di governance ovunque il workspace vi colleghi un plugin, e la pipeline di plugin per ogni Recipe che dichiara degli step. Stato del linguaggio indica lo stato di ciascuna fase della pipeline.

La pipeline viene eseguita interamente in memoria, in un ordine rigoroso e fisso:

Risoluzione — il resolver e il validatore di sintassi

  • Meccanismo: merge dell’ereditarietà, interpolazione dei template Go e validazione JSON Schema 2020-12.
  • Azione: La CLI recupera tutte le entità richieste (Components, Features, Releases). Per prima cosa controlla queste definizioni alla ricerca della parola chiave extends. Per le entità del catalogo, esegue un deep merge dei metadati YAML, e i due tipi si separano sui pilastri dei dati: lo schema: di una Feature si compone con quello della sua base secondo la composizione di JSON Schema 2020-12, mentre un Component che estende ne compone solo la struttura — i suoi slot di associazione, i socket di topologia, l’allowlist di self-inject e le asserzioni con nome — e riceve il blocco schema: della sua base esattamente come la base lo ha scritto. Una Release che estende si fonde secondo la stessa regola: il valore del figlio prevale chiave per chiave, fino al primo valore indivisibile — uno scalare, una lista, un template — che sostituisce per intero, e una chiave che il figlio scrive come null viene rimossa. Così viaggia tutta la sua superficie di authoring — l’albero dei boundary con gli infra per componente e le associazioni di Feature, il blocco parameters, le annotazioni e il puntatore al Manifest — mentre nessun campo metadata lo fa, poiché identità e provenienza sono proprie di ciascuna Release. Successivamente esegue un’interpolazione in memoria in tre sotto-passi: validazione del contratto dei parametri rispetto alle dichiarazioni tipizzate parameters: dell’Aggregate; interpolazione dei valori risolti nelle stringhe values: circostanti; ritiro della mappa .parameters da ogni contesto di template dei valori, lasciandola leggibile solo ai template di percorso scritti dall’operatore. Infine inietta i blocchi infra risolti nei payload dei componenti di destinazione. Una volta che il blueprint è completamente concreto, il compilatore usa la dichiarazione unificata schema: del catalogo (forma compatta o JSON Schema 2020-12 completo) per validare rigorosamente in locale le configurazioni values e infra dello sviluppatore.
    • Validazione dello schema delle Feature della Release: Le Features associate tramite la Release (sia a livello di boundary sia specifiche di un componente) vengono risolte rispetto alle loro entità di catalogo durante questo passo. Il compilatore valida i blocchi infra forniti dalla Release rispetto alla dichiarazione schema: di ciascuna Feature subito dopo la risoluzione del catalogo, garantendo la sicurezza dei tipi prima che la topologia venga costruita.
    • Sotto-fase di espansione delle Feature guidata dalle annotazioni: Dopo la risoluzione del Manifest, il binding di Recipe/Provider e la validazione dei target di binding del Manifest (i percorsi dichiarati sotto mappings.features.annotations.<key>.maps esistono nello spec.schema della Feature referenziata), il compilatore esegue una sotto-fase di espansione delle annotazioni prima del topology builder. La sotto-fase percorre i boundary della Release dall’esterno verso l’interno e i sottosistemi dell’Aggregate dall’esterno verso l’interno, calcolando l’insieme effettivo di annotazioni per componente tramite un merge a cascata + override + opt-out con null; analizza ogni valore di annotazione come YAML in uno scalare, un valore strutturato o null; instrada ogni valore (scalare o strutturato per sottochiave) attraverso la dichiarazione maps del binding del Manifest verso il pilastro dello schema della Feature di destinazione, imponendo la corrispondenza tra lato e pilastro (il lato Aggregate attiva maps.values; il lato Release attiva maps.infra); valida i tipi di ogni foglia rispetto allo spec.schema della Feature; e inietta associazioni di Feature sintetiche, che il grafo IR contrassegna con origin: annotation. Gli schemi vengono compilati una volta per build e riutilizzati tra i percorsi a cascata. L’espansione viene eseguita dopo la validazione dei target di binding e prima della costruzione della topologia, così le fasi a valle trattano le associazioni sintetiche in modo strutturalmente identico a quelle esplicite (salvo tramite l’ispezione della provenienza). Vedi 13-catalog-and-registry.md §«Espansione delle Feature guidata dalle annotazioni» e language-reference/providers/well-known-annotations.md per la forma del binding, la semantica della cascata e le regole di composizione tra i due lati.

Costruzione della topologia — il topology builder e il gate di mutazione

  • Meccanismo: espansione dell’AST + il ruolo label-transform del socket di governance.
  • Azione: Il compilatore legge nativamente i blocchi uses dichiarati esplicitamente dai componenti validati per tracciare in modo deterministico gli archi topologici tra i nodi del grafo, lasciando il blocco values completamente opaco. Valuta poi il gate di mutazione, passando una proiezione del grafo — le etichette di ogni nodo e i values che la sua istanza dichiara, che il compilatore consegna senza leggerli — insieme al nome e all’ambiente della Release, a un plugin di governance associato al ruolo label-transform. Il plugin valuta il contesto e restituisce JSONPatch per etichettare automaticamente e dinamicamente il grafo (ad es. iniettando l’etichetta compliance.aggrega.ai/data-class: restricted in base all’ambiente della Release, oppure datastore.aggrega.ai/engine: vector in base alle estensioni dichiarate di un database); le patch raggiungono solo le etichette.

Finalizzazione del grafo

  • Meccanismo: normalizzazione.
  • Azione: Il compilatore finalizza il grafo piatto della rappresentazione intermedia (IR), preservando gli archi topologici espliciti tracciati dal topology builder. Normalizza poi le Features associate e i loro payload values in un dizionario piatto indicizzato per ID di nodo, preparando per la validazione il grafo, agnostico rispetto alle capacità.
    • Normalizzazione del payload IR: La forma strutturale dell’IR impone un’unica fonte di verità per la configurazione: il livello di topologia porta solo la struttura del grafo (identità dei nodi, archi, etichette di metadati), e lo stato di configurazione normalizzato risiede in un dizionario in memoria separato che il compilatore passa ai plugin a valle. I mutatori che modificano la configurazione la modificano in un solo punto; il provider legge lo stato normalizzato senza rischio di divergenza dovuta a una memorizzazione ridondante.

Analisi statica — l’analizzatore statico e il gate di validazione

  • Meccanismo: controlli di purezza topologica + il ruolo ir-verdict del socket di governance.
  • Azione: Il compilatore esegue un’analisi statica astratta sul grafo IR. Per prima cosa estrae le stringhe selector dalle definizioni usesSchema e le valuta con un motore nativo Go di corrispondenza delle etichette (che supporta la semantica in stile Kubernetes di AND, OR tramite in() e NOT tramite !=) sugli archi del grafo definiti esplicitamente, per garantire la sicurezza dei tipi tra nodi sui socket dichiarati. Un arco su un socket ad hoc — uno che l’autore di un Aggregate ha nominato e che il catalogo non ha dichiarato — non ha una voce di catalogo e quindi nessun selettore, perciò per questo controllo non c’è nulla da valutare e nulla che manchi; ogni arco registra quale dei due casi è, e ciò che un arco ad hoc può trasportare è delimitato invece dai provides dichiarati dal target. Valuta inoltre i selettori appliesTo e appliesToAnyOf della Feature per verificare che le feature associate siano compatibili con le etichette del componente di destinazione, e il selector di ogni slot di associazione riempito rispetto alle etichette della Feature che lo riempie. In secondo luogo valuta ogni obbligo di presenza dichiarato dal Component di un nodo — ogni annotazione features.aggrega.ai/requiredType.<label> — rispetto all’insieme finale di associazioni di quel nodo. L’analizzatore è il posto giusto per questo controllo perché è la prima fase che dispone di entrambe le metà della regola: le annotazioni dell’entità Component risolta e l’insieme di associazioni prodotto dalla cascata a 5 livelli, contando allo stesso modo le associazioni fatte nell’Aggregate, nei sottosistemi, nella Release e quelle espanse dalle annotazioni. Un obbligo che nessuna associazione soddisfa arresta la build; un obbligo la cui dichiarazione è malformata la arresta con una diagnostica distinta, così una dichiarazione errata non viene mai letta come un requisito soddisfatto. In terzo luogo esegue il gate di validazione, passando la struttura completa del grafo (inclusi tutti i nodi, gli archi, le feature associate e i percorsi DFS precalcolati) a un plugin di governance associato al ruolo ir-verdict. La policy Wasm personalizzata dell’azienda valuta la topologia. Se il plugin Wasm restituisce un array di errori (ad es. rilevando un percorso continuo da un nodo public a un nodo restricted senza una specifica feature di proxy), la build si arresta.

Rendering

  • Meccanismo: intercettazione pre-render (injectMapping), late binding (valuesMapping) e socket di rendering Wasm (pipeline).
  • Azione: La fase finale di generazione degli artefatti è suddivisa in sotto-fasi temporali rigorose che vengono eseguite in un ordine fisso, il che mantiene l’esecuzione deterministica:
    • Inject mapping (intercettazione pre-render): Il compilatore Go risolve il contratto astratto .context.inject dello sviluppatore. Esegue poi i template Go injectMapping di tutte le FeatureRecipes associate seguendo il rigoroso ordine di esecuzione del modello a cipolla a 5 livelli (Sub-Aggregate — le associazioni proprie di un componente modulo, poi quelle dichiarate dai sottosistemi del suo modulo, dall’esterno verso l’interno → componente dell’Aggregate radice → sottosistema dell’Aggregate radice → boundary della Release dall’esterno verso l’interno → specifico del componente nella Release). Il compilatore esegue nativamente un deep merge dei dizionari risultanti sul canale di memoria .context.inject del chiamante. Questo riscrive in modo sicuro le variabili d’ambiente e le stringhe di connessione per il chiamante prima che la Recipe di base le veda. Un mapping può riscrivere ciò che il blocco inject: del chiamante o una delle sue connessioni ha fornito; una chiave che un’altra Feature associata ha già fornito — tramite il proprio mapping o il proprio blocco inject: — arresta la build indicando entrambe le associazioni, così l’ordine di esecuzione non decide mai tra i valori di due associazioni.
    • Preambolo dei locals: Prima che venga eseguito qualsiasi template provides, il compilatore valuta le voci .locals della Recipe nell’ordine in cui sono scritte, ciascuna rispetto a un contesto locale al nodo e autosufficiente — .context.instance_id, .values, .infra e le voci dello stesso blocco risolte fino a quel momento, ma non .context.inject né .context.uses. Una voce può quindi leggere una voce sorella definita sopra di essa e ne riceve il valore risolto; l’ordine scritto dall’autore fa parte del contratto ovunque una voce ne legga un’altra, e il blocco non viene mai riordinato per far risolvere un riferimento. Risolvere prima i locals è ciò che permette a un template provides di leggere .locals. Il template .source della Recipe viene valutato rispetto allo stesso contesto una volta risolti quei locals, il che mantiene .locals riutilizzabile come abbreviazione tra i template di una Recipe e permette agli autori di parametrizzare .source (versione del chart, percorso, registry) per ciascun boundary.
    • Rendering di base (valuesMapping della Recipe di base): Il compilatore valuta il template valuesMapping della Recipe di base. Il template legge le stringhe intercettate dal canale .context.inject (riscritte durante l’inject mapping), e il dizionario di valori risultante viene passato al provider indicato dalla capability della Recipe — i provider helm e helm-chart eseguono entrambi il rendering tramite Helm — per renderizzare gli artefatti dell’infrastruttura di base.
    • Parsing e validazione del Workload: Per una Recipe che dichiara workload: — contenuto di blocco inline, oppure workload: { $import: <path> } che indica un file — quel documento viene valutato come template rispetto al contesto di rendering del nodo, poi analizzato come YAML nella forma del Workload e controllato: i byte renderizzati sono validati rispetto allo schema del Workload, e anche il valore decodificato è validato rispetto a esso (i byte portano chiavi che la decodifica scarta, e la decodifica elide un campo fornito vuoto, quindi ciascuno rifiuta ciò che l’altro non vede), ogni voce di attachments è controllata rispetto agli slot che il featuresSchema del Component vincolato dichiara, e ogni riferimento a una risorsa è controllato rispetto ai provides risolti dello slot che nomina. Un errore in questo punto arresta la build. Il Workload analizzato viene posto nel contesto del template come .workload, così un template valutato successivamente sullo stesso nodo può leggerlo.
    • Valutazione degli artefatti: Ogni voce che una Recipe dichiara sotto artifacts: — contenuto inline, oppure un file indicato dal $import: della voce stessa — viene letta, analizzata come template, valutata rispetto al contesto completo del template e porta con sé la provenienza della build. La proiezione risultante viene passata al provider, che decide il formato di output, dove finisce la provenienza, il percorso di output e i byte finali. Ogni file emesso registra da quale forma scritta proviene, così una collisione di nomi di file può indicare ogni contributore.
    • Sintesi del Workload: Il Workload analizzato viene passato al provider indicato dalla capability della Recipe, che lo traduce nelle risorse native di quel provider. Una Recipe che non dichiara alcun workload: non ha nulla da sintetizzare qui; i suoi file provengono invece dal rendering del source.
    • Rendering delle Feature (generazione di risorse della FeatureRecipe): Ogni associazione sul nodo la cui FeatureRecipe vincolata porta i propri source, workload, artifacts e/o valuesMapping — il pattern di generazione di risorse, usato per manifest ausiliari come un ServiceMonitor, una NetworkPolicy, una ConfigMap sidecar o una risorsa di consegna delle credenziali — viene valutata in un unico passaggio, nello stesso ordine del modello a cipolla a 5 livelli seguito dall’inject mapping. C’è una sola sequenza su un solo insieme di associazioni: una Feature operativa e una Feature di credenziali percorrono la stessa strada, e ciò che le distingue è ciò che emette la loro FeatureRecipe. Per ogni associazione, .values e .infra vengono sostituiti con quelli del suo ambito; essa eredita i .locals valutati della Recipe di base; .attachment_name indica l’istanza in corso di rendering e .provides porta i provides risolti dell’associazione stessa, lo stesso insieme che legge il consumatore. Il dizionario di valori risultante viene passato al provider indicato dalla capability della FeatureRecipe stessa, e i file renderizzati vengono aggiunti all’output del boundary con due coordinate — il componente a cui la Feature è associata, poi il nome con cui è associata — così un nome di Feature associato a più componenti li mantiene separati. La forma che assumono queste coordinate deriva dal layout del provider ospite: una directory <component>--<instance>/ accanto a quella del componente, dove il target dà a ciascun contributore una posizione propria, e un prefisso del nome file <component>--<instance>-- dove legge solo i file che si trovano direttamente in una directory. Le FeatureRecipes di sola iniezione — quelle che portano solo injectMapping, già gestito durante l’inject mapping — vengono saltate qui. Come le sotto-fasi precedenti, il rendering delle Feature viene eseguito un componente alla volta, quindi un’associazione viene normalmente valutata subito dopo il componente a cui è associata. Un’associazione la cui FeatureRecipe dichiara readsCallerRenderFacts: true o readsTargetRenderFacts: true viene invece valutata una volta che ogni componente, e ogni associazione che non dichiara nessuno dei due, ha completato il rendering — così a quel punto ogni componente che si connette al suo host, e ogni componente a cui il suo host è collegato, ha completato il rendering — e il suo output finisce dove sarebbe finito altrimenti.
    • La pipeline di plugin (esecuzione dei passi Wasm): Il compilatore legge l’array pipeline della Recipe ed esegue i suoi passi nell’ordine dichiarato. Invoca il plugin Wasm indicato da ciascun passo sui documenti renderizzati del nodo, applica le operazioni JSON Patch RFC 6902 restituite dal passo ai documenti a cui tali operazioni si riferiscono ed emette accanto a essi gli effetti collaterali del passo — la superficie dietro mutazioni chirurgiche come l’iniezione di un sidecar Envoy o il montaggio di un VolumeMount di un secret. Un passo il cui gate when: viene renderizzato come falsy viene saltato come pass-through, lasciando invariato l’insieme di documenti per il passo successivo. L’URI plugin di ciascun passo viene risolto prima dell’esecuzione nei byte dell’artefatto verificato che il lockfile fissa tramite digest. I passi pipeline di una FeatureRecipe vengono eseguiti allo stesso modo, sui documenti renderizzati dell’associazione stessa e, per un’associazione con ambito di componente, anche su quelli del componente ospite.

Tutti e tre i tipi di input di una Recipe raggiungono il compilatore: source: + valuesMapping: tramite il rendering di base, workload: tramite il parsing e la sintesi del workload, e artifacts: tramite la valutazione degli artefatti. Quali di essi possano essere passati a un dato provider non viene deciso sotto-fase per sotto-fase — viene stabilito una volta per nodo, prima di qualsiasi dispatch di rendering, in base al contratto dichiarato dal provider stesso, così una Recipe il cui tipo di input non è accettato dal provider vincolato viene rifiutata in quel punto anziché a metà del rendering. Vedi 16-recipe-input-composition.md per il modello di composizione dei tre tipi di input, il tipo Workload e il meccanismo degli artefatti, e Stato del linguaggio per sapere quale provider accetta quale tipo.

Output nativo per GitOps

Per restare rigorosamente privi di opinioni su come viene applicato il loro output, i plugin di rendering scrivono gli artefatti generati in una struttura di directory pulita e isolata per boundary (ad es. dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Questo consente a controller GitOps esterni (come ArgoCD o Flux) di sincronizzare e applicare l’infrastruttura senza che il compilatore di Aggrega abbia mai bisogno delle credenziali API di un cluster attivo.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Mappa delle sorgenti dell’infrastruttura

Aggrega compila un Aggregate.yaml di circa 30 righe in migliaia di righe di configurazione fisica JSON o YAML. Senza un modo per risalire da una risorsa in esecuzione alla sua sorgente, il debug di un errore a «main.tf.json riga 4.032» costringe gli sviluppatori a ricostruire manualmente la corrispondenza. I plugin di rendering di Aggrega risolvono questo problema fondendo identificatori di traccia nella superficie di metadati nativa del provider — metadata.labels e metadata.annotations per Kubernetes, un commento di provenienza per Terraform e convenzioni equivalenti per ciascun provider — così ogni oggetto renderizzato porta un puntatore alla sorgente da cui proviene. L’etichetta aggrega.ai/compiler-version (documentata in governance-and-compliance §5) è una chiave di traccia di questa famiglia; accanto a essa il timbro porta aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri e aggrega.ai/environment, e i provider helm, helm-chart, compose, terraform e cloudformation lo emettono ciascuno — il provider helm-chart sui file di template che una Recipe aggiunge a un chart, poiché copia invariati i template propri del chart.

Il timbro non porta alcuna chiave che identifichi l’origine della feature o il tipo di catalogo.

Con il compilatore vengono distribuite altre due superfici di debug. aggrega build --trace scrive lo stato intermedio di ogni nodo, passaggio per passaggio, in .trace/ accanto a dist/, per l’autore di una Recipe che vuole ispezionare ciò che ogni fase ha ricevuto e prodotto; e una diagnostica che interrompe la build porta la categoria della superficie di authoring a cui appartiene — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR e le altre — ovunque l’errore ne abbia una, così da indicare l’autore giusto. Gli errori che riconducono un campo non valido di un manifest generato alla riga del template che lo ha prodotto non fanno parte del compilatore.

La pipeline dei validatori

La fase di convalida degli schemi della risoluzione poggia su una pipeline di validatori che converte il contenuto delle spec delle entità (forma compatta, JSON Schema in YAML o misto) in un unico documento JSON Schema 2020-12 con provenienza per foglia, quindi convalida rispetto a esso il contenuto delle istanze scritto dagli sviluppatori. Cinque stadi vengono eseguiti in ordine come trasformazioni pure; ciascuno è una funzione deterministica dei propri input dichiarati.

Stadio 1 — Compilazione della forma compatta. Il compilatore percorre l’albero YAML del contenuto di schema:, parameters: e SchemaLibrary; smista per nodo (foglia in forma compatta, JSON Schema in YAML, riferimento $ref: o composizione); emette JSON Schema 2020-12 risolto. La forma compatta e il JSON Schema in YAML possono mescolarsi a qualsiasi confine di nodo tramite l’escape $jsonschema:; il compilatore gestisce il caso misto percorrendo l’albero e smistando per nodo. La trasformazione è una funzione pura: lo stesso input in forma compatta produce sempre lo stesso output JSON Schema. Vedi language-reference/vocabulary/compact-form-authoring.md per il vocabolario delle parole chiave.

Stadio 2 — Risoluzione di spec.templates e $instantiate:. Per le voci di SchemaLibrary scritte come riferimenti a template, il compilatore percorre ogni voce della libreria che invoca $instantiate: con $args:, sostituisce i valori dei parametri come sostituzione di scalari letterali e produce voci di schema concrete. La sostituzione viene eseguita una volta per caricamento della libreria; le voci risolte vengono messe in cache. Vedi language-reference/entities/schemalibrary.md per la forma di authoring dell’entità libreria.

Stadio 3 — Espansione dei $ref: tra documenti. Per i riferimenti a SchemaLibrary tramite $ref: (la forma per identità <Library>#/schemas/<entry>), il compilatore percorre la catena di riferimenti in fase di compilazione propagando lo stack di risoluzione; il contenuto referenziato viene incorporato nello schema del consumatore. L’espansione preserva il rilevamento dei cicli (i cicli arrestano la build con un errore che nomina la catena), il vincolo identità-non-posizione (un riferimento che contiene un host di registry arresta la build indirizzando verso la forma per identità — i riferimenti indirizzano le librerie per identità, non per posizione fisica) e la composizione a sorgente singola (i blocchi $ref: accettano solo il riferimento nudo; le sovrascritture lato consumatore si compongono tramite allOf: di JSON Schema). Vedi language-reference/vocabulary/cross-document-ref.md per la semantica della risoluzione.

Stadio 4 — Sintesi del ponte per featuresSchema:. Il compilatore percorre il contenuto featuresSchema: di ogni entità nell’ordine dell’autore ed emette un frammento JSON Schema che descrive la forma di un riempimento che può legare ciascuno slot di attachment, con una parola chiave di estensione x-aggrega-inject: su uno slot che dichiara una allowlist inject. Quel frammento viene compilato e verificato a sé, rispetto al blocco di attachment scritto, invece di essere incorporato nel contenuto schema: rivolto allo sviluppatore; la parola chiave di estensione è un metadato che la convalida JSON Schema ignora, e nessuno stadio successivo la rilegge dal frammento — un controllo che vuole la allowlist di uno slot legge lo slot. La tabella dei socket usesSchema: non viene proiettata in alcun frammento: selector: e inject: di un socket vengono letti come lo YAML tipizzato scritto dall’architetto, e il valueSchema: / infraSchema: per arco di un socket viene compilato a sé. La sintesi è una funzione pura dei propri input.

Stadio 5 — Merger personalizzato con provenienza. Per le entità che dichiarano extends:, il compilatore percorre la catena dei genitori; il JSON Schema risolto del genitore diventa la base; le sovrascritture del figlio si applicano sopra. Ogni foglia dello schema risolto porta un tag di provenienza per foglia (percorso del file, numero di riga, origine genitore o figlio). L’output del merger è ciò che consuma il motore di convalida; il motore di convalida è un’implementazione di terze parti non modificata conforme a JSON Schema 2020-12, con attorno un walker deterministico per emettere i risultati in ordine.

I cinque stadi vengono eseguiti prima che il motore di convalida veda lo schema. Il motore riceve un unico documento JSON Schema 2020-12 risolto più il contenuto delle istanze dello sviluppatore; produce un report di convalida. Il formattatore degli errori consulta i tag di provenienza per emettere diagnostiche rivolte all’utente che nominano chiaramente le posizioni nel sorgente — compreso il file d’origine di un vincolo che una Feature ha ereditato dalla sua base invece di scriverlo essa stessa.

La pipeline del validatore viene eseguita nel punto in cui ciascun payload è completo per la prima volta — values e infra di un componente durante la risoluzione, i componenti di un sotto-aggregato man mano che la costruzione della topologia li introduce, e il payload di un collegamento alla finalizzazione del grafo — quindi un rilievo di schema interrompe la build prima che l’analisi statica valuti qualsiasi selettore, e prima della valutazione delle asserzioni, il che consente ai template delle asserzioni di fare affidamento su payload validati.

Preservazione del determinismo lungo la pipeline

Ogni stadio della pipeline di compilazione preserva l’invariante di output deterministico: a parità di file sorgente, di lockfile e di versione del compilatore, la build produce un output identico byte per byte. L’invariante è fondamentale — l’indirizzamento per contenuto nel lockfile richiede digest stabili degli artefatti; le build riproducibili richiedono che una release scritta sul portatile dello sviluppatore A compili nello stesso output sul portatile dello sviluppatore B e in CI; la revisionabilità dei diff richiede che le modifiche al sorgente compaiano come le uniche modifiche nell’output compilato.

Il determinismo è preservato da un piccolo numero di discipline che ogni trasformazione rispetta:

  • Ordine di iterazione fisso. Ogni visita di YAML a forma di mappa itera in un ordine fisso, perché l’iterazione nativa delle mappe in Go è randomizzata. Il compilatore ordina prima di iterare nella maggior parte degli stadi (compilatore della forma compatta, merger, resolver di spec.templates, formattatore degli errori, serializzatore YAML); la proiezione degli slot di attachment invece mantiene l’ordine dell’autore, così che l’ordine delle proprietà di una tabella di slot sia quello in cui è stata scritta.
  • Nessun timestamp incorporato. La compilazione non incorpora timestamp nell’output. Una build alle 14:00 produce lo stesso artefatto di una build alle 2:00. I metadati di provenienza del merger usano file:riga, non file:timestamp.
  • Percorsi relativi al workspace. Tutti i percorsi nell’output risolto sono relativi al workspace; il livello di risoluzione dei percorsi li normalizza prima che entrino in qualsiasi output.
  • Nessuna sorgente casuale, nessuno stato esterno. Le trasformazioni sono funzioni pure dei propri input dichiarati (contenuto dell’entità, catena dei genitori, lockfile). Lo stato esterno viene consultato solo durante la risoluzione (recupero degli artefatti OCI), e il contenuto risolto è indirizzato per contenuto tramite digest.
  • Serializzazione YAML canonica. L’output è scritto in un’unica forma fissa per un dato input: lo stesso ordine delle chiavi a ogni profondità a ogni esecuzione, con gli array e gli array enum: nell’ordine di input; indentazione di 2 spazi; terminatori di riga Unix LF; stringhe senza virgolette dove YAML lo consente; forma booleana true/false; null omesso per i campi assenti.
  • Ordine alfabetico di $defs:. Le voci $defs: di uno schema vengono emesse in ordine alfabetico di chiave nel JSON Schema risolto. $defs: è concettualmente un dizionario, non una lista ordinata; l’ordine alfabetico rende i diff prevedibili attraverso le riorganizzazioni del sorgente.
  • Il parallelismo non emerge nell’output. Il compilatore può parallelizzare unità indipendenti (entità diverse possono essere compilate in modo concorrente). I risultati paralleli vengono raccolti in una struttura deterministica (ad es. ordinata per nome dell’entità) prima di essere serializzati.

I test end-to-end del compilatore compilano ogni fixture più volte all’interno di un unico test e verificano che ogni esecuzione emetta gli stessi file con contenuti identici byte per byte. Ripetere la compilazione è ciò che individua una fuga dell’ordine di iterazione delle mappe o un’iterazione su un insieme non ordinato, che produce un output stabile nella maggior parte delle esecuzioni e diverge occasionalmente. I test vengono eseguiti insieme al resto della suite di test del compilatore.

L’invariante di output deterministico si applica al momento della build: a parità di file sorgente + lockfile + versione del compilatore, output identico byte per byte. La proprietà gemella al momento del lock (a parità di file sorgente + stato del registry, lo stesso lockfile) è più debole — i registry sono mutabili (si possono pubblicare nuove versioni; si possono aggiungere sidecar; i metadati per componente possono evolvere), quindi due invocazioni del lock sugli stessi file sorgente in momenti diversi possono produrre lockfile diversi. È proprio lo scopo del lockfile, in linea con le convenzioni di npm, Cargo e Go. A partire da un lockfile nuovo, la build produce un output deterministico. La separazione tra i due momenti è ciò che rende tollerabile la mutabilità lato registry: un sidecar pubblicato al tempo T2 cambia la successiva invocazione del lock; non cambia le build basate sul lockfile generato al tempo T1.