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

Stato del linguaggio

Questa pagina è il riferimento canonico per sapere quali superfici di Aggrega sono utilizzabili oggi, quali sono documentate ma il compilatore non vi agisce ancora e quali sono pianificate per un’iterazione futura. Integra i capitoli per dominio mostrando in un unico posto lo stato di maturità di tutto il linguaggio.

Due tipi di lettori consultano questa pagina. Gli autori alle prime armi controllano la pagina prima di scrivere su una superficie che non conoscono, per confermare che la superficie produca oggi un output renderizzato. Chi cerca un riferimento controlla la pagina quando una superficie che sta usando si comporta in modo inatteso — ad esempio, quando lo YAML supera la validazione ma non viene prodotto alcun output, la pagina è il primo posto in cui cercare lo stato della superficie. Anche chi torna a leggerla consulta la pagina per individuare le superfici che hanno cambiato etichetta di stato dall’ultima lettura. I capitoli per dominio e i riferimenti delle entità descrivono come la superficie dovrebbe funzionare; questa pagina descrive se funziona già.

Tassonomia degli stati

Ogni superficie del linguaggio in questa pagina porta una di quattro etichette di stato:

  • disponibile. Lo schema accetta la superficie; il compilatore la consuma; il comportamento corrisponde al contratto documentato. Gli autori che usano una superficie available ricevono il contratto documentato.

  • accettata ma inerte. Lo schema accetta la superficie — scriverla supera la validazione — ma il compilatore non vi agisce ancora. Scrivere una superficie accepted but inert produce una build sintatticamente valida senza alcun effetto renderizzato per quella superficie; il compilatore può emettere un avviso che nomina la superficie inerte (il pattern consigliato), oppure alcune superfici attuali vengono saltate silenziosamente senza avviso. Le voci per sezione qui sotto indicano il comportamento specifico.

  • accettata ma bloccata. Lo schema accetta la superficie — scriverla supera la validazione — ma il compilatore interrompe la build invece di eseguirne il rendering. Scrivere su una superficie accepted but blocked fallisce al rendering con un errore esplicito che indica cosa scrivere al suo posto. Un blocco può essere permanente, quando ciò che è stato scritto è un’ambiguità che il compilatore non risolverà al posto tuo, perché scegliere una lettura per te potrebbe distribuire qualcosa che non hai chiesto; oppure può restare solo finché non viene rilasciato il comportamento dietro la superficie. Ciò che l’etichetta promette è lo stesso in entrambi i casi: lo schema la accetta, la build la rifiuta e l’errore ti dice come correggerla.

  • pianificata. La superficie è documentata come progettata, ma né lo schema né il compilatore la accettano ancora. Scrivere su una superficie planned fallisce alla validazione dello schema. La pagina mostra gli elementi pianificati così gli autori possono organizzarsi tenendo conto della loro assenza invece di scoprire la lacuna al momento della build.

Le etichette di stato sono valutate rispetto al compilatore attuale. Le superfici in sviluppo attivo possono passare da un’etichetta all’altra; le voci per sezione descrivono il piano di transizione quando è noto.

Tipi di input della Recipe

Una Recipe compone il proprio output da tre tipi di input — da sorgente, sintetizzato e artifact — descritti in 16-recipe-input-composition.md. Stato per tipo di input:

  • source: + valuesMapping: (da sorgente) — disponibile. Il compilatore risolve l’URI source:, valuta il template valuesMapping (inline, $import: da file o $import: da libreria) e passa il risultato al provider di destinazione per il rendering. Consumato dai provider helm, helm-chart, compose, terraform e cloudformation.

  • workload: (sintetizzato) — disponibile. La Recipe dichiara workload: inline (uno scalare a blocco che contiene lo YAML del Workload) oppure tramite $import: (percorso di file). Il compilatore analizza il Workload templatizzato, lo valida rispetto allo schema Workload incorporato e lo inoltra al sintetizzatore di workload del provider di destinazione. Consumato dai provider helm e compose. Il provider helm-chart reindirizza esplicitamente gli autori al provider helm per i manifest K8s sintetizzati. Una Recipe che dichiara workload: verso un provider che non implementa la sintesi dei workload si arresta al rendering con un CATALOG_ERROR.

  • artifacts: (artifact) — disponibile. Il campo è una mappa di voci con nome; ogni voce è scritta inline o caricata tramite un $import: per voce. Le voci vengono valutate dopo il parsing del Workload e la risoluzione della sorgente, quindi l’intero contesto dei template — inclusi .workload e .source — è a loro disposizione; ricevono la provenienza unita in metadata.labels e metadata.annotations per i documenti che portano metadati (le chiavi non sicure per il charset — recipe-uri, boundary-path, sync-wave — come annotazioni, la stessa suddivisione applicata dai provider helm) e vengono emesse come file separati accanto all’output della Recipe renderizzato dalla sorgente o sintetizzato dal workload. Dispatch del Provider — il provider helm flat emette file autonomi in una directory che porta il nome del componente che li ha dichiarati, all’interno della directory di output del boundary, perché la chiave dà il nome al file e non dice nulla su quale componente l’abbia scritto; il provider compose instrada le proprie emissioni attraverso il merger di fine Release; il provider helm-chart valuta ogni voce con i delimitatori Aggrega [[ ]], così la sintassi {{ }} di Helm nello stesso file sopravvive fino al rendering a valle, poi colloca ogni voce in base alla forma in cui è scritta — una voce caricata con $import: in boundaries/<bp>/charts/<nodeID>/templates/<authored-key> (i file di un bundle annidati sotto quella chiave), accanto ai template propri del chart da sorgente, e una voce con contenuto inline in boundaries/<bp>/charts/<nodeID>/<authored-key>, la radice del chart, dove i template del chart la leggono tramite .Files.Get / .Files.Glob; il provider terraform scrive ogni voce così com’è nella directory propria del componente sotto l’albero modules/ del boundary; il provider cloudformation unisce ogni voce, un frammento di stack, nell’unico stack assemblato per quella directory di output. Le collisioni di nomi di file tra origini di tipi di input diversi (output renderizzato dalla sorgente, sintetizzato dal workload o emesso come artifact) vengono rilevate al momento del rendering dal rilevatore di collisioni tra origini e producono un CATALOG_ERROR che nomina ogni contributore.

Consulta entities/recipe.md per la superficie di authoring della Recipe e le regole di composizione dei tipi di input; errors/fatal-halts.md per le regole di forma della Recipe; e la sezione Providers qui sotto per la matrice per provider.

Linguaggi di mapping

Le Recipes (e le FeatureRecipes) si legano a un unico campo di mapping per tradurre il contesto Aggrega nel dizionario dei valori che il provider sottostante consuma. Il campo valuesMapping: supporta tre modalità di authoring, scelte in base alla forma del contenuto:

  • valuesMapping: — Modalità 1-3 disponibili. Modalità 1: template Go inline (scalare a blocco). Modalità 2: $import: da file (una mappa che contiene solo $import: con un percorso di file locale). Modalità 3: $import: da libreria (una mappa che contiene solo $import: con un riferimento di identità per nome semplice a una voce di una MappingLibrary, <Library>#/mappings/<entry>, facoltativamente con una soglia minima :<version>). Il compilatore sceglie in base alla forma del contenuto — scalare a blocco per la Modalità 1, $import: con un percorso di file per la Modalità 2, $import: con un riferimento di libreria per nome semplice per la Modalità 3. Tutte e tre valutano il template Go risolto rispetto al contesto dei template della Recipe durante il mapping dei valori (la libreria di helper Sprig è preregistrata); la Modalità 3 risolve la voce rispetto al catalogo locale più le eventuali librerie fissate nel lockfile, e un riferimento che contiene un host viene rifiutato. Consulta entities/recipe.md «Il campo valuesMapping — tre modalità di authoring» per il meccanismo di dispatch ed esempi svolti.

Consulta entities/recipe.md per la superficie di authoring della Recipe e il design del linguaggio di mapping, e entities/mappinglibrary.md per l’entità di libreria su cui si basa la Modalità 3.

Sintassi di inject

Il blocco inject: ha un’unica sintassi in ogni posizione — l’inject proprio di un componente, quello di una connessione uses e quello di un allegato.

  • Un elenco di voci per meccanismo ([{in: ..., from: ...}], [{in: ..., value: ...}]) — disponibile. Ogni meccanismo di consegna è un elenco; ogni voce nomina il proprio identificatore locale (nome della variabile d’ambiente, percorso di file, flag di argomento) con in: e porta esattamente uno tra from: (riferimento a una chiave di provides) e value: (stringa letterale). Un meccanismo scritto come mappa anziché come elenco, o una voce che porta entrambe le parole chiave, arresta la build all’envelope del documento dell’Aggregate, nominando il percorso.

  • value: solo nell’inject proprio di un componente. Un letterale appartiene all’inject proprio del componente, che lo consegna. Su una connessione uses un value: arresta la build, come descrive An inject: entry on a connection carries a literal (Una voce su una connessione porta un letterale), e nell’inject proprio di un allegato arresta anch’esso la build, come descrive An inject: entry on an attached Feature carries a literal (Una voce su una Feature allegata porta un letterale): entrambi consegnano solo chiavi che un’altra entità pubblica, indicate con from:.

Consulta vocabulary/topology-triad.md per la specifica completa dell’Injection Contract, incluse la semantica del contesto a doppio stato, le regole di collisione delle chiavi ed esempi svolti.

Motore di template

Il motore di template Go di Aggrega valuta i template di Recipe e FeatureRecipe rispetto al contesto dei template nella fase per sito documentata dalla Matrice di espansione dei template. La libreria di helper Sprig è preregistrata insieme agli helper di Aggrega su ogni superficie valutata dal renderer, con un’eccezione: la risoluzione di una coordinata source: strutturata registra solo gli helper di Aggrega — lì sono disponibili optional e capitalizedWords, mentre le funzioni di Sprig non lo sono, quindi una chiamata Sprig in un campo source:, o in una voce locals: di un’entità che porta un source: strutturato, si arresta al momento del parsing. Consulta errors/fatal-halts.md, che dedica a quella superficie una sezione propria. Valutazione, parsing e integrazione con Sprig sono disponibili oggi.

Comportamento con chiavi mancanti — tollerato nei template di valore; missingkey=error rigoroso nei template di percorso, nelle asserzioni e in una coordinata source:. I template di valore vengono valutati con l’opzione missingkey=zero di Go, quindi un template che fa riferimento a una chiave non legata (ad es. .values.unset_field) non solleva un errore e la lettura non produce nulla. Gli idiomi di catalogo come {{ .values.optional_field | default "fallback" }} continuano a funzionare con questa policy, perché un valore non impostato conta come vuoto per default. I template di percorso (directory: / subDirectory: sui boundary della Release) vengono valutati con missingkey=error rispetto a un’allowlist chiusa — i fallimenti silenziosi dei percorsi producono layout di filesystem errati che gli operatori scoprono solo dopo la build, e il rigore intercetta l’errore prima. Altre due superfici adottano la stessa policy rigorosa, per lo stesso motivo: lì un rendering vuoto produrrebbe un verdetto sbagliato o un pin sbagliato invece di un campo che l’autore può rileggere. Si tratta di una voce assertions: su un Component, una Feature, una Recipe o una FeatureRecipe, e dei campi templatizzati di un blocco source: strutturato su una Recipe o una FeatureRecipe. errors/fatal-halts.md rende conto della policy di ogni superficie una per una e fornisce le forme sensibili alla presenza che funzionano con quella rigorosa.

Fallback sensibile alla presenza tramite optional. Quando l’autore di una Recipe deve distinguere «chiave assente» da «chiave presente con un valore zero / vuoto / false» — la distinzione che il default di Sprig non sa fare — il renderer espone l’helper optional: {{ optional .infra "replicas" 1 }} restituisce il valore scritto di infra.replicas (incluso uno 0 scritto) quando presente, e ricade su 1 solo quando la chiave è assente. Consulta templates/sprig-functions.md per la semantica completa.

Composizione dei nomi tramite capitalizedWords. Dove una destinazione accetta solo lettere e cifre nei nomi con cui indirizza le risorse, {{ capitalizedWords .context.instance_id }} legge l’id come parole separate da qualsiasi carattere esterno a quell’alfabeto e rende maiuscola la prima lettera di ogni parola, così payments-db diventa PaymentsDb. La trasformazione elimina ogni separatore, quindi due id che differiscono solo per la punteggiatura arrivano allo stesso nome; una build che emetterebbe due risorse con lo stesso nome si arresta e nomina entrambi gli id. Consulta templates/sprig-functions.md per la semantica completa.

Applicazione del contratto dei parametri al livello della dichiarazione. I parametri obbligatori che la Release non fornisce producono errori espliciti al livello del contratto dei parametri, la prima cosa che la risoluzione controlla, con una provenienza file:line che nomina il parametro e il contratto. Le violazioni di tipo / vincolo emergono allo stesso modo. Questa è l’applicazione sostanziale delle chiavi mancanti: la tipizzazione viene controllata dove risiede l’intento dello sviluppatore (la dichiarazione parameters: dell’Aggregate), non al momento della valutazione dei template a valle. Consulta entities/aggregate.md §«Contratti di parametri tipizzati».

Un’unica grammatica di dichiarazione per i parameters: dell’Aggregate. Ogni slot di parametro è scritto come oggetto a contratto tipizzato (key: { type: <type>, default: <value>, ... }). La forma abbreviata a scalare semplice (key: <value>) viene rifiutata all’envelope del documento dell’Aggregate, con un errore che nomina il parametro e dice che era atteso un oggetto. Il vocabolario del contratto tipizzato rende esplicita la semantica di type:, required: e dei vincoli al livello della dichiarazione; l’adempimento da parte della Release continua a usare valori scalari secondo il tipo dichiarato dal contratto.

Consulta templates/expansion-matrix.md per la matrice di valutazione per sito di template e 05-templates.md per la panoramica sui template.

Fasi della pipeline di compilazione

La pipeline di compilazione di Aggrega è documentata in ../architecture/10-compilation-pipeline.md. Stato per fase:

  • Risoluzione, costruzione della topologia, finalizzazione del grafo, analisi statica e rendering — disponibili.
  • Inject mapping (intercettazione pre-render injectMapping) e ogni sotto-fase del rendering di base — pubblicazione dei locals, mapping dei valori, sintesi del workload, valutazione degli artifact, render del provider, rendering delle feature e generazione delle risorse della FeatureRecipe di credenziale — disponibili.
  • La pipeline dei plugin (esecuzione Wasm di pipeline:) — disponibile. Per una Recipe o una FeatureRecipe che dichiara passi pipeline: non vuoti, ogni passo viene eseguito nell’ordine dichiarato: il compilatore invoca il plugin Wasm indicato dal passo sull’output renderizzato, applica le operazioni JSON Patch restituite ai documenti indirizzati ed emette gli effetti collaterali del passo. Un passo il cui gate when: viene renderizzato come falsy viene saltato come pass-through, lasciando invariato l’insieme dei documenti. Gli autori che vogliono mutazioni in stile JSONPatch (iniezione di sidecar Envoy, VolumeMount di secret, ecc.) le ottengono tramite questa superficie.

Providers

La libreria standard di Aggrega include cinque provider di rendering — helm, helm-chart, compose, terraform e cloudformation. Stato per provider:

  • helm — disponibile. Sono disponibili sia la modalità da sorgente (rendering di chart Helm tramite l’SDK di Helm) sia la modalità sintetizzata (Workload → un oggetto controller scelto in base al form del Workload — Deployment, StatefulSet, DaemonSet, Job o CronJob — più Services e PVC).
  • helm-chart — disponibile. È disponibile la modalità da sorgente (composizione con umbrella chart). Il tipo di input sintetizzato non si applica a questo provider; gli autori che hanno bisogno della sintesi di manifest K8s usano il provider helm con workload:.
  • compose — disponibile. Sono disponibili sia la modalità da sorgente (overlay di frammenti compose) sia la modalità sintetizzata (Workload → servizio compose + volumi + reti). L’output docker-compose.yaml per boundary viene assemblato dal composer a livello di Release.
  • terraform — disponibile. Sono disponibili sia la modalità da sorgente sia gli artifact; ogni boundary riceve una configurazione radice, aggrega.modules.tf, che dichiara ogni componente come blocco module i cui file si trovano in una directory propria sotto modules/. Il tipo di input sintetizzato non si applica a questo provider.
  • cloudformation — disponibile. Sono disponibili sia la modalità da sorgente sia gli artifact (frammenti di stack); tutti i componenti il cui rendering confluisce in una stessa directory di output vengono assemblati in un unico template di stack, emesso come JSON puro. Il tipo di input sintetizzato non si applica a questo provider.

Il rendering del Provider è servito da un Plugin con pluginType: provider; consulta entities/plugin.md per la superficie di authoring del Plugin di rendering dei provider e 06-providers.md per le pagine di riferimento dei singoli provider.

Espansione guidata dalle annotazioni

I Manifests portano una sezione di binding features.annotations: che mappa le chiavi di annotazione ai tipi di Feature, più una tabella di routing raggruppata per pilastro (maps.infra / maps.values) che indica quali proprietà dello schema della Feature ogni binding può popolare. Documentato in entities/manifest.md e providers/well-known-annotations.md; collocazione nella pipeline in ../architecture/10-compilation-pipeline.md; meccanica al caricamento del catalogo e al momento dell’inspect in ../architecture/13-catalog-and-registry.md §«Espansione delle Feature guidata dalle annotazioni».

  • Binding features.annotations del Manifest — disponibili. La sotto-fase di espansione delle annotazioni della risoluzione è disponibile end-to-end. Percorre i boundary della Release (dall’esterno all’interno) e i sottosistemi dell’Aggregate (dall’esterno all’interno), calcola l’insieme effettivo di annotazioni per componente tramite cascata + override con opt-out null sull’intero valore e per sottochiave, analizza ogni valore di annotazione come scalare, mappa strutturata o null esplicito, instrada per sottochiave attraverso la dichiarazione maps del binding applicando il vincolo lato-contro-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 di destinazione e inietta allegati Feature sintetici, che il grafo IR contrassegna con origin: annotation. La composizione tra i due lati unisce per pilastro e per campo al momento della costruzione dell’IR, con il valore esplicito che prevale campo per campo; aggrega inspect mostra la provenienza tra parentesi per ogni foglia. La validazione delle destinazioni di binding al caricamento del catalogo, il lint di sovrapposizione dei pilastri dello schema e il lint di sovrapposizione delle mappe di binding presidiano il percorso. Il prefisso semplice aggrega.ai/ viene rifiutato al caricamento del Manifest quando è usato come chiave di binding — quel prefisso è riservato alle annotazioni native della piattaforma; i binding usano feature.aggrega.ai/ o un dominio personalizzato.

Corrispondenza delle versioni

Le Recipes e le FeatureRecipes dichiarano l’interfaccia di Component o di Feature che implementano tramite la parola chiave implements:. implements: non seleziona mai una Recipe: lo fa il mapping del Manifest, e un’istanza il cui tipo non è coperto da alcun mapping si arresta con un errore che elenca come candidate le Recipes il cui implements: può implementare quel tipo. Ciò che implements: guida è il controllo che la Recipe di ogni voce di mapping del Manifest implementi il tipo mappato, o una base che quel tipo estende con extends. Il tipo mappato è la chiave della voce e, per una chiave components.type, anche il tipo di ciascuna istanza di componente che la chiave raggiunge a una versione che la chiave non nomina — ogni istanza che raggiunge, per una chiave scritta senza versione — alla versione con cui la build compila quell’istanza: la versione che l’istanza nomina oppure, per un’istanza che non ne nomina alcuna, la versione più alta di quel Component presente nel catalogo. Stato per forma:

  • Esatta (core/api-server:1.0.0) — disponibile. Il tipo mappato deve essere quella versione.
  • Intervallo compatibile con la major (core/api-server:^1.0.0) — disponibile. La forma con il caret è un vincolo SemVer (>=1.0.0, <2.0.0 nell’esempio); la versione del tipo mappato deve soddisfarlo.
  • Senza versione (core/api-server) — disponibile. Qualsiasi versione del tipo lo soddisfa.

Una voce di mapping il cui implements: della Recipe non corrisponde né al tipo mappato né ad alcuna delle sue basi arresta la build con un OPS_ERROR che nomina la voce, la Recipe e il suo valore implements:. Un’istanza di componente che una chiave raggiunge a un’altra versione, la cui versione non soddisfa l’implements: della Recipe, arresta la build con lo stesso OPS_ERROR, nominando l’istanza, il suo tipo — e, per un’istanza che non nomina alcuna versione, la versione con cui è stata compilata —, la chiave, la Recipe e il suo valore implements:. La forma con il caret è la superficie di authoring canonica per la corrispondenza compatibile con la major.

Consulta vocabulary/inheritance-and-interface.md per la superficie di design di implements: e entities/manifest.md per la forma del livello di mapping per Manifest.

Envelope dei metadati

Gli envelope delle entità di catalogo portano metadata.labels, metadata.annotations e (sulla Release) metadata.environment. Stato per superficie:

Disponibilità di metadata.labels e metadata.annotations — su sette tipi. Gli envelope delle entità che portano questi campi sono Component (label obbligatorie, con la chiave obbligatoria component.aggrega.ai/type, annotazioni facoltative), Feature (entrambi facoltativi), i quattro tipi di libreria SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary (entrambi facoltativi) e Aggregate (solo label, facoltative). Le entità restanti — Recipe, FeatureRecipe, Manifest, Release, Plugin — non accettano metadata.labels o metadata.annotations a livello di envelope.

metadata.environment sulla Release — obbligatorio. Lo schema della Release elenca environment come campo metadata obbligatorio; la build imprime il suo valore sull’output renderizzato come label aggrega.ai/environment. Consulta entities/release.md per i cinque casi d’uso pratici della sezione Environment Metadata (attribuzione dei costi OTel/FinOps, filtraggio di trace/log OTel, targeting degli operator Kubernetes, differenziazione della produzione multi-regione, definizione dell’ambito di compliance).

Consulta 02-naming-conventions.md per la disciplina sul casing dei campi che si applica alle chiavi metadata, e le pagine di riferimento delle singole entità per le forme di envelope che ciascuna entità accetta oggi.

Comandi della CLI

La CLI di Aggrega registra la pipeline di build più l’introspezione. Stato per comando:

  • aggrega build — disponibile. Legge un file di Release, risolve l’Aggregate + il Manifest, esegue la pipeline di compilazione e scrive gli artifact renderizzati nelle directory di output dei boundary. Quando è presente un lockfile, verifica le dipendenze rispetto a esso; quando è assente, si arresta chiedendo un pull, oppure lo compila prima, dove lo chiedono --auto-pull o auto_pull.
  • aggrega inspect — disponibile. Ispeziona un’entità di catalogo, un file di entità, un’entità pubblicata in un registry o una Release, e ne riporta la forma risolta. Consulta cli/aggrega-inspect.md.
  • aggrega pull — disponibile. Risolve tutte le dipendenze di una Release e scrive un lockfile per Release che fissa ogni entità di catalogo e artifact sorgente a una versione e a un digest del contenuto, e ogni input esterno richiesto dal render della Release a un digest del contenuto; mette in cache il contenuto scaricato in .aggrega/cache. --verify controlla un lockfile esistente rispetto allo stato attuale. Consulta cli/aggrega-pull.md.
  • aggrega push — disponibile. Pubblica un’entità di catalogo in un registry OCI; aggrega push --list-kinds indica quali tipi accetta. Consulta cli/aggrega-push.md.
  • aggrega lint — disponibile. Esegue le regole di disciplina di pubblicazione con severità warn sull’intero catalogo, sulla chiusura delle dipendenze di una Release o su una singola entità; su una singola entità, --pre-publish aggiunge un controllo dell’incremento di versione rispetto alla versione dell’entità attualmente pubblicata, e una discrepanza provoca un arresto. Le regole sono distribuite come plugin Wasm opzionale. Consulta cli/aggrega-lint.md.
  • aggrega serve — disponibile. Un daemon compiler-as-service di lunga durata che parla JSON-RPC 2.0 su stdin/stdout, per l’integrazione con editor e IDE. Consulta cli/aggrega-serve.md per i metodi che serve.
  • aggrega version — disponibile. Stampa la versione della CLI; -o json emette un oggetto di versione leggibile da una macchina.
  • aggrega validate — disponibile. Controlla la correttezza dell’intero catalogo, di una Release o di una singola entità, riportando le diagnostiche senza eseguire il rendering degli artifact.
  • aggrega search — disponibile. Cerca le entità pubblicate nell’indice locale dei registry configurati; l’indice viene costruito e aggiornato da aggrega registry update.
  • aggrega registry — disponibile. Gestisce i registry e la loro policy di fiducia delle firme; registry add registra un registry e registry update costruisce l’indice locale interrogato da aggrega search.
  • aggrega push-artifact — disponibile. Pubblica un artifact di dati autonomo (ad esempio un bundle di documentazione) in un registry OCI, accanto a push, che pubblica le entità.
  • aggrega sign — disponibile. Firma uno o più artifact già pubblicati e ne allega le firme.
  • aggrega deprecate — disponibile. Allega un marcatore di deprecazione firmato a un artifact già pubblicato.
  • aggrega login e aggrega logout — disponibili. Eseguono l’autenticazione a un registry OCI e memorizzano la credenziale, oppure rimuovono una credenziale memorizzata.
  • aggrega auth — disponibile. Gestisce l’identità di firma locale usata per firmare gli artifact.
  • aggrega config — disponibile. Ispeziona e gestisce la configurazione del workspace; i sottocomandi mostrano la configurazione effettiva unita e la provenienza di ogni impostazione, inizializzano una configurazione funzionante con un registry e la sua policy di fiducia delle firme, e congelano nel workspace la configurazione effettiva critica per la build, così che la build sia identica senza dipendere dalla configurazione globale della macchina.
  • aggrega get-schema — disponibile. Stampa il JSON Schema di un tipo di entità o di contratto.
  • aggrega plugin — disponibile. Ispeziona i plugin Wasm che la CLI può risolvere; i sottocomandi li elencano, aggiungono e rimuovono i plugin configurati, sincronizzano i record gestiti dalla macchina di un plugin e ne generano una vista di catalogo.
  • aggrega cache — disponibile. Ispeziona e mantiene le cache su disco; i sottocomandi ne riportano lo stato, le sfoltiscono, ne rimuovono voci e le svuotano.
  • aggrega mcp — disponibile. Esegue un server Model Context Protocol su stdio, oppure su HTTPS per un client su un’altra macchina, esponendo l’introspezione del compilatore alle integrazioni con assistenti AI.
  • aggrega completion — disponibile. Genera lo script di autocompletamento della shell per la CLI.
  • Sottocomandi di estensione della CLI — disponibili. Un plugin Wasm pubblicato come guest pluginType: cli viene risolto e registrato come sottocomando di aggrega, così un’estensione installata viene eseguita come aggrega <extension> accanto ai comandi integrati.
  • aggrega import — disponibile. Trasforma una sorgente dichiarativa esterna di definizione di agenti (Langflow, Flowise, n8n) in bozze di file di authoring di Aggregate e Component, con una decisione deterministica di riuso del catalogo, con punteggio di confidenza, registrata per ogni nodo. Il mapping specifico del formato è fornito da un plugin importer che il workspace risolve per il formato della sorgente — uno contenuto nel suo catalogo, oppure uno degli importer Langflow, Flowise e n8n del compilatore, che vengono compilati e pubblicati con ogni release del compilatore. Il binario porta le loro entità Plugin ma non i loro moduli, quindi servono i rispettivi formati in ogni workspace: il primo import che ne richiede uno non presente sulla macchina lo scarica dal registry predefinito del workspace, lo verifica e lo conserva nella cache dei contenuti per ogni import successivo. Una sorgente viene analizzata tramite il parser che il catalogo del workspace fornisce per la sua sintassi oppure, dove il catalogo non ne fornisce alcuno, tramite quello incluso nel compilatore, così un workspace il cui catalogo non contiene alcun parser importa tramite l’uno o l’altro.
  • aggrega scaffold — disponibile. Crea la bozza di un documento iniziale per qualsiasi tipo di entità a partire dallo schema di quel tipo — ogni campo che richiede, con un segnaposto dove serve un valore — e la scrive sullo standard output; con --example, scrive in una nuova directory uno degli esempi eseguibili della documentazione, letto dal bundle firmato della documentazione.
  • aggrega explain — disponibile. Spiega la condizione di arresto che un codice breve (come E0007) o un codice descrittivo nomina.
  • aggrega edit-document — disponibile. Applica a un documento una singola modifica strutturata e delimitata — aggiungere un componente, collegare una Feature, cablare una connessione o impostare un valore — preservando ogni byte che non tocca.
  • aggrega pin — disponibile. Registra, nell’entity.lock accanto a una Recipe o a una FeatureRecipe, il pin di contenuto per ogni input che l’entità legge al di fuori del proprio documento.
  • aggrega skills — disponibile. Installa la skill di Aggrega in un assistente AI.

Consulta 07-cli.md per la panoramica della CLI e l’indice del Riferimento del linguaggio per tutte le pagine di riferimento dei singoli comandi.

Editor e altri frontend

Ogni frontend mostra ciò che il binario aggrega ha compilato; nessuno contiene un proprio compilatore. Stato per superficie:

  • Contratto del grafo IR — disponibile. Lo schema del grafo IR, il contratto rispetto al quale ogni frontend legge il grafo, è incluso nella distribuzione degli schemi di Aggrega; vedi il riferimento dello schema IR.
  • Leggere il grafo da un comando — disponibile. aggrega build accetta --ir-graph, e così anche aggrega inspect quando riceve una Release e aggrega validate --release; il flag scrive su stdout come JSON il grafo risolto da quell’esecuzione, oltre a ciò che il comando produce già. Una sessione del daemon legge lo stesso grafo in aggrega/irGraph, e gli strumenti cli-inspect, cli-build e cli-validate del server MCP lo accettano come argomento ir_graph.
  • Grafo della topologia in Visual Studio Code — disponibile. L’estensione Aggrega per Visual Studio Code disegna il grafo IR della Release selezionata come grafo interattivo e da esso collega le Features, chiedendo entrambe le cose al daemon aggrega serve.
  • Modalità di streaming headless della CLI — pianificata. La modalità headless emette il grafo IR come JSON delimitato da newline su stdout perché un frontend lo consumi man mano che la topologia cambia. Ciò che è disponibile oggi è un documento per invocazione, non uno stream: nessun comando emette una sequenza di grafi su un unico stdout man mano che una topologia cambia.

Vedi ../architecture/15-editors-assistants-and-frontends.md per come l’editor, l’assistente e il daemon raggiungono il compilatore.

Direzioni di design

La tassonomia degli stati qui sopra classifica lo stato per superficie in tutto il linguaggio; questa sezione registra lo stato di direzioni di design più ampie documentate nei capitoli di architettura.

La compliance sull’intero patrimonio non è una direzione pianificata: enunciare una regola di governance una sola volta in modo che vincoli ogni build del workspace è disponibile oggi tramite il socket di governance. Un plugin collegato alla chiave plugins.governance della configurazione del workspace valuta ogni build in quel workspace — un ruolo di verdetto che rifiuta un grafo o un artifact renderizzato che viola la regola, un ruolo di trasformazione che fornisce metadati derivati che uno sviluppatore non digita mai. Consulta ../architecture/11-governance-and-compliance.md.

  • Interface Parity & Auto-Implementation — disponibile. Una Recipe scritta per un Component di base serve ogni Component che lo estende, a qualsiasi profondità della catena, senza che l’Architect debba scrivere una Recipe duplicata. Il Component che estende scrive schema: inherited, quindi non aggiunge a values / infra / provides alcuna chiave radice che la Recipe della base non potrebbe consumare; un Component che dichiara extends con uno schema proprio viene rifiutato all’envelope del suo documento. Il Manifest mappa comunque il tipo che estende con una voce propria, e il controllo del mapping la accetta quando l’implements della Recipe mappata nomina il tipo o una qualsiasi base che esso estende. Documentato in ../architecture/02-ecosystem-philosophy.md.
  • Ghost Infrastructure Tracker — disponibile. Un guardrail della fase di rendering emette un avviso quando una chiave dichiarata da un autore raggiunge un nodo e nessun template dichiarato dalla Recipe associata la legge, così un valore dichiarato dall’autore e scartato silenziosamente dal template viene nominato anziché perso. È la metà della fase di rendering dello stesso design di corrispondenza delle forme. Consulta errors/warnings.md.

I capitoli di architettura descrivono le superfici di design; questa pagina traccia lo stato di implementazione.