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

Contratto dei plugin Wasm

La pipeline di compilazione di Aggrega include punti socket designati in cui i plugin WebAssembly (Wasm) estendono il comportamento del compilatore: i quattro ruoli del socket di governance, tra cui un Mutation Gate alla costruzione della topologia e un Validation Gate all’analisi statica; una pipeline di plugin post-rendering per i passi di FeatureRecipe e Recipe; un socket di rendering dei provider; un socket del parser; un socket dell’importatore; e un socket di linting fuori banda. Questa pagina documenta il contratto pubblico dei plugin Wasm: quali socket esistono, che cosa ciascun socket consuma e produce, dove si colloca ciascun socket nella pipeline di compilazione e la sandbox all’interno della quale ogni plugin viene eseguito.

Questa pagina tratta i socket — i punti della pipeline e le loro forme di input/output. Per il plugin — l’entità Plugin, le dichiarazioni di capacità per export, i limiti di runtime e il ciclo di vita publish→pull→build — vedi la guida per sviluppatori di plugin Wasm.

Aggrega incorpora un runtime host Wasm — Extism sopra il motore Wazero — che carica ed esegue i plugin dietro un firewall di purezza AOT: l’host non concede a un guest alcuna capacità ambientale — nessuna rete, nessun filesystem, nessun ambiente, stdio scartato, un orologio di sistema osservabile congelato su un istante invariante tra le build — così un plugin non può violare le garanzie ahead-of-time del compilatore. L’intera superficie delle capacità — la regola dei moduli di import al caricamento, i dinieghi al momento dell’istanziazione e le funzioni host selezionate — è il contratto della sandbox più avanti. Gli autori di Plugin si rivolgono all’host tramite il PDK in tre linguaggi (Go, Rust, TypeScript). aggrega lint invoca il socket del linter — il linter di pubblicazione standard — tramite l’host. aggrega build invoca i ruoli del socket di governance attivi in fase di build quando un workspace li configura: il ruolo annotation-transform durante la risoluzione e il ruolo label-transform alla costruzione della topologia (entrambi modellano l’output), più il verdetto IR all’analisi statica e il verdetto di rendering sugli artefatti renderizzati. Ciascuno è un no-op quando nessun plugin è associato a quel ruolo, quindi una build senza configurazione di governance resta invariata. aggrega build invoca anche la pipeline: della FeatureRecipe e della Recipe nella pipeline di plugin che chiude il rendering — ogni passo dichiarato viene eseguito tramite l’host sull’insieme dei documenti renderizzati, applicando le patch RFC 6902 del passo ed emettendo i suoi effetti collaterali. Vedi Stato del linguaggio → Fasi della pipeline di compilazione.

Il contratto della sandbox

Ogni socket invoca il proprio plugin attraverso la stessa sandbox dell’host. La sandbox ha due livelli indipendenti — un controllo strutturale al caricamento e il diniego delle capacità all’istanziazione — e insieme definiscono che cosa un plugin può raggiungere, che cosa non può raggiungere e di che cosa è responsabile.

La regola dei moduli di import (al caricamento). Il loader percorre la sezione di import del binario del plugin e ammette import di funzioni solo sotto tre namespace di modulo: wasi_snapshot_preview1 (il runtime WASI preview-1 a cui si collega il runtime di un linguaggio guest), extism:host/env (l’ABI del runtime Extism — gli intrinseci di memoria e I/O propri del PDK) e extism:host/user (le funzioni host selezionate di Aggrega). Un guest può importare qualsiasi nome di funzione sotto un modulo consentito; un import sotto qualsiasi altro modulo nomina una superficie che l’host non fornisce, e il plugin viene rifiutato al caricamento con una diagnostica che nomina il modulo e l’import. La regola deliberatamente non censura i singoli nomi di funzione WASI: il runtime di un linguaggio collegato staticamente importa funzioni di filesystem e di socket che i suoi percorsi di codice attivi non chiamano mai — incluse transitivamente dalle dipendenze — e nominare un import non concede nulla. È il diniego delle capacità all’istanziazione, non la censura degli import, a garantire l’assenza di I/O.

Nessuna capacità ambientale (istanziazione). L’host istanzia il guest con un comportamento WASI reale e nessuna autorità ambientale:

  • nessun filesystem — nessuna directory preaperta, quindi una chiamata al filesystem fallisce al confine della chiamata;
  • nessun socket di rete;
  • un ambiente vuoto;
  • stdio scartato — nulla di ciò che il guest scrive su stdout o stderr raggiunge i flussi dell’host;
  • un orologio di sistema osservabile congelato, fissato su un istante invariante tra le build, così un guest che legge l’ora non può far trapelare l’ora della build nel proprio output;
  • un orologio monotono reale che avanza — il runtime di un linguaggio guest ne ha bisogno per l’avvio, e il tempo monotono misura una durata trascorsa, non un istante dell’orologio di sistema;
  • entropia reale dell’host — un’entropia fissata stabilizzerebbe il seme di hash interno del runtime di un linguaggio e maschererebbe il non determinismo del guest invece di lasciarlo emergere come output diverso;
  • un unico nome di programma sintetico come argv.

Una chiamata di I/O che un guest effettua davvero — aprire un file, connettersi a un socket — fallisce al confine della chiamata. È il modello di sicurezza basato sulle capacità proprio di WASI: la sandbox nega la capacità anziché sorvegliare il codice.

Gli input arrivano solo attraverso il payload e le funzioni host selezionate. Un plugin riceve tutto ciò che renderizza o valuta nel payload trasportato dal suo socket — proiezioni del grafo e dei nodi, valori e contesto di rendering. La codifica in cui arriva un payload è fissata per socket e indicata nella sezione propria di quel socket più avanti; ogni tipo di payload pubblicato fornisce un punto di ingresso di codifica e uno di decodifica per la codifica del suo socket, così un guest chiama una funzione anziché scegliere un parser. Per un rendering di provider con sorgente, il payload trasporta un elenco della sorgente anziché i byte della sorgente: un insieme ordinato di voci {path, is_dir} sotto la radice della sorgente del nodo, senza alcuna interpretazione del layout del provider da parte dell’host. Il guest applica la propria logica di layout — selezionare l’unico file compose, scendere fino alla radice di un chart, richiedere un Chart.yaml, fare il vendoring ricorsivo di un modulo — e rilegge esattamente la porzione che seleziona tramite una callback dell’host. Oltre al payload, l’host espone un insieme selezionato di funzioni host a privilegio minimo, e concede a un plugin esattamente quelle che il suo binario importa:

  • aggrega_log — una riga di log sulla destinazione dei log dell’host.
  • aggrega_emit_warning — un avviso strutturato che l’host mostra dopo la chiamata.
  • aggrega_fetch_external_input — il canale di recupero degli input esterni (più avanti).
  • aggrega_pack_source — la callback di selezione della sorgente: il guest nomina una selezione {file | dir | tree, path} sotto la radice della sorgente e l’host legge e impacchetta esattamente quella, sotto una sandbox che risolve i percorsi sotto la radice e rifiuta ...
  • aggrega_read_source_file — una lettura del contenuto di un singolo file sotto la stessa sandbox, per una selezione della sorgente che dipende dal contenuto.
  • aggrega_parse_source — la callback di consumo dei produttori: il guest nomina un formato sintattico e consegna i byte della sorgente, e l’host risolve un parser per quel formato, lo esegue e restituisce l’albero canonico che ha prodotto. È il modo in cui un consumatore ottiene l’output di un produttore attraverso l’host invece di invocare esso stesso un guest produttore, e l’host la limita a un solo livello — un produttore raggiunto in questo modo che la chiama di nuovo viene respinto — così un consumatore la chiama una volta per sorgente e può consumare molte sorgenti in sequenza.

L’host ricava l’insieme che un plugin importa dal suo binario .wasm, lo convalida rispetto alla lista consentita selezionata e lo confronta con le funzioni host che il describe() del guest dichiara. aggrega plugin sync registra l’insieme nel spec.runtime.hostFunctions dell’entità, e una pubblicazione rifiuta un’entità il cui record differisce dal binario, così la superficie host di ogni plugin è visibile nel catalogo e non può divergere dal binario.

I fallimenti delle callback portano un codice confrontabile automaticamente, sotto hostfunc_error_code. Le callback dell’host che restituiscono una risposta — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file e la callback di consumo dei produttori aggrega_parse_source — segnalano il fallimento in banda: l’involucro della risposta porta un messaggio leggibile da una persona e, accanto a esso, un codice facoltativo confrontabile automaticamente sotto hostfunc_error_code, tratto da un vocabolario chiuso. Il messaggio è prosa libera per una persona; il codice è l’identità stabile in base alla quale un guest sceglie il ramo da seguire senza analizzare il messaggio. In caso di successo il codice è assente; in caso di fallimento l’host imposta entrambi. Il PDK espone la coppia come un errore tipizzato il cui testo è il messaggio e il cui campo codice un guest confronta con le costanti di codice riesportate dal linguaggio. Un guest tollera un codice assente e un codice che non riconosce ripiegando sul messaggio — quindi il confronto su un codice è un affinamento best-effort sovrapposto al messaggio sempre presente, mai un suo sostituto. L’insieme chiuso dei valori è lo schema dei codici di errore delle funzioni host.

🔴 Due vocabolari diversi nominano un fallimento su questo confine, e la chiave che leggi dice quale dei due hai in mano. Confonderli è l’unico errore che vale la pena segnalare qui, perché un valore dell’uno o dell’altro è una semplice stringa e né l’host né il guest verificano da quale insieme provenga.

  • hostfunc_error_code, su una risposta che l’host invia a un guest. Il suo valore è un membro del catalogo chiuso indicato sopra — un elenco fisso, che cambia lentamente, dei modi in cui una callback dell’host può fallire. Poiché l’insieme è chiuso, un guest può confrontare un valore con una costante con nome che il suo kit riesporta e scegliere il ramo in base al risultato.
  • condition_code accanto a condition_short_code, su un output di socket che un guest restituisce all’host. Sono i due identificatori di una condizione di arresto sollevata dal guest stesso, e provengono dall’insieme aperto e in crescita delle condizioni che il compilatore registra, anziché dal catalogo. condition_code è il codice descrittivo con cui la condizione è registrata; condition_short_code è la forma compatta — la lettera E e quattro cifre — che un lettore cita, cerca e incolla in una segnalazione. L’host stampa il codice breve nell’intestazione tra parentesi quadre della diagnostica che produce, così una condizione sollevata da un guest è citabile esattamente come una sollevata dal compilatore. Non ricava nessuno dei due valori, ma li verifica: un codice breve che non rimanda a nessuna condizione dichiarata da questo compilatore, o che rimanda a una il cui numero è stato ritirato, arresta la build invece di raggiungere un lettore come un identificatore che non rimanda a nulla.

I due identificatori lato guest vengono riportati insieme: un guest che ne imposta uno e non l’altro ha nominato una condizione che l’host non può risolvere, e l’host riporta allora invece la propria condizione generica di fallimento del plugin, con il messaggio che porta comunque l’intero fallimento. E un condition_code non è mai un membro del catalogo delle funzioni host, quindi confrontarne uno con una costante riesportata non trova mai corrispondenza — ed è per questo che ciascuna chiave nomina il proprio vocabolario anziché il fallimento in generale.

Gli slot di ogni callback hanno una codifica dichiarata, e ogni slot che contiene un documento di payload lo contiene in forma binaria. Ogni argomento che una callback dell’host accetta è un puntatore nella memoria del guest, a parte il livello numerico di aggrega_log; anche una callback che restituisce una risposta risponde con un puntatore. Che cosa contiene ciascuno di questi slot è fissato per callback:

CallbackSlot degli argomentiSlot della risposta
aggrega_log, aggrega_emit_warningTesto UTF-8 — nessun documento di payloadnessuna risposta
aggrega_fetch_external_inputun semplice URL UTF-8 — nessun documento di payloadCBOR canonico
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_sourceCBOR canonico (RFC 8949 §4.2.1)CBOR canonico

La tabella si divide in base a ciò che contiene ogni slot anziché in base all’identità della callback: uno slot che contiene un documento di payload trasporta CBOR canonico, e uno slot che contiene una semplice stringa — una riga di log, un campo di diagnostica, un URL — trasporta testo UTF-8. aggrega_fetch_external_input è quella i cui due slot differiscono: il suo argomento è un semplice URL, letto come testo UTF-8, e la sua risposta è un documento di payload in CBOR canonico.

Che cosa fa un guest in uno slot che trasporta un payload, e che cosa non deve fare. 🔴 Uno slot che contiene un documento di payload contiene una sequenza di byte opaca, non testo UTF-8 — quindi questa è la forma che un guest dichiara, non solo i byte che vi mette. Un guest che alloca una tale richiesta come stringa, o legge una tale risposta come stringa, non interopera: una conversione di testo in entrambe le direzioni corrompe i byte binari. Il fallimento è esplicito anziché parziale — una richiesta che l’host non riesce a decodificare torna come un involucro di risposta che porta il codice request_undecodable, nella stessa forma in banda di qualsiasi altro fallimento di callback, così il guest lo segnala invece di proseguire con un payload letto a metà. I tipi di payload sono SourcePackRequest e SourcePackResponse per aggrega_pack_source, SourceFileRequest e SourceFileResponse per aggrega_read_source_file, ParseInput e ParseSourceResponse per aggrega_parse_source, e il solo tipo di risposta FetchExternalInputResponse per aggrega_fetch_external_input, il cui URL è allocato come testo. In concreto, per kit:

  • Go — costruisci la richiesta con la funzione EncodeCBOR() del tipo di richiesta, allocala con pdk.AllocateBytes (non pdk.AllocateString) e leggi la risposta con ReadBytes() sulla memoria a cui si risolve il puntatore della risposta, nella funzione DecodeCBOR del tipo di risposta. L’URL di recupero è l’eccezione sul lato della richiesta, allocato con pdk.AllocateString; la sua risposta si legge come qualsiasi altra. La dichiarazione //go:wasmimport è comunque un puntatore, quindi nulla nella firma mostra la forma — è nell’allocazione e nella lettura che si trova.
  • Rust — la dichiarazione #[host_fn] indica la forma direttamente: ciascuna delle tre callback di payload si legge fn <callback>(request: Vec<u8>) -> Vec<u8>;, e la callback di recupero si legge fn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Costruisci la richiesta con la funzione encode_cbor() del tipo di richiesta e leggi la risposta con la funzione decode_cbor(&raw) del tipo di risposta.
  • TypeScript — costruisci la richiesta con la funzione encodeCBOR… del tipo di richiesta, allocala con Memory.fromBuffer (non Memory.fromString) e leggi la risposta con readBytes() nella funzione decodeCBOR… del tipo di risposta. L’URL di recupero è allocato con Memory.fromString; la sua risposta si legge con readBytes() come le altre. Come in Go, la voce declare module è comunque un puntatore.

Un guest che chiama un wrapper del PDK non ha bisogno di nulla di tutto ciò. I wrapper — FetchExternalInput, PackSource, ReadSourceFile e ParseSource, nella grafia propria di ciascun linguaggio — eseguono l’allocazione e la codifica, e nessuna delle loro firme nomina un tipo di dati trasmessi, quindi un guest che raggiunge queste callback tramite il proprio kit non alloca né decodifica nulla da sé; un guest che dichiara e chiama da sé le funzioni host alloca e legge la propria memoria come descritto sopra. Una richiesta allocata come testo viene rifiutata anziché servita a metà, e una risposta letta come testo non può essere decodificata, quindi una discrepanza tra i due lati è esplicita anziché silenziosa.

Due proprietà su cui fare affidamento. La risposta ha la stessa codifica sia in caso di successo sia in caso di fallimento: un guest legge un solo slot e non può sapere prima della decodifica quale dei due contiene, quindi un solo punto di ingresso di decodifica li legge entrambi, e il codice di errore e il messaggio descritti sopra arrivano attraverso di esso. E un guest compila un campo a valori in byte nel tipo di campo proprio del suo kit — una slice di byte in Go, una stringa base64 in Rust e TypeScript — perché la conversione nella sequenza di byte grezza che la codifica binaria trasporta è compito del codificatore generato, eseguita in uscita e invertita in entrata. Ciò riguarda i byte della sorgente di ParseInput, il contenuto del file che aggrega_read_source_file restituisce, il contenuto che aggrega_fetch_external_input ha recuperato e il contenuto di ciascun file impacchettato in una risposta pack-source: quei byte attraversano il confine una sola volta anziché essere codificati due volte, e nessun guest codifica in base64 qualcosa che il codificatore sta per decodificare dal base64. Il campo content delle risposte read-source-file e fetch viene omesso quando è vuoto, quindi la risposta per un file vuoto o per un payload recuperato di lunghezza zero non porta alcun contenuto; tale risposta è comunque un successo, perché un fallimento porta sempre il suo messaggio e il suo codice, e il wrapper di ogni kit restituisce byte vuoti per essa. L’albero che aggrega_parse_source restituisce viaggia come una sequenza di byte che contiene il proprio documento JSON alla lettera; l’host non lo legge né lo rimodella. Un parser legge lo stesso ParseInput, nella stessa codifica, sul proprio export parse — vedi il socket del parser.

Canonico significa che un input identico produce byte identici su ogni lato, ed è ciò che consente di confrontare un payload tra i tre kit di plugin anziché limitarsi a un round-trip, ed è il motivo per cui l’output di una build resta identico byte per byte. In un guest non serve alcuna libreria CBOR e nulla analizza i byte a mano: ogni tipo di payload pubblicato fornisce i punti di ingresso di codifica e decodifica di cui ha bisogno la codifica del suo slot.

Il determinismo è responsabilità dell’autore del plugin. L’host consuma i byte di output di un guest alla lettera e non vi applica alcun serializzatore, quindi il contratto che ogni plugin deve rispettare è: un input identico produce byte di output identici. La sandbox elimina le fonti ambientali di non determinismo — l’ora di sistema, l’ambiente, lo stato del filesystem — ma deliberatamente non maschera il resto: un guest che codifica entropia o tempo monotono trascorso nel proprio output produce byte visibilmente diversi tra un’esecuzione e l’altra anziché un difetto stabilmente nascosto.

Il canale di recupero degli input esterni. aggrega_fetch_external_input è l’unico canale sancito per il contenuto remoto, ed è mediato dall’host, non un accesso del guest alla rete: il guest nomina un URL e l’host serve i byte secondo la disciplina di fissaggio degli input esterni. Un URL fissato nel lockfile della Release viene servito dall’archivio locale indirizzato per contenuto e verificato rispetto al digest registrato; un URL non fissato viene rifiutato con una diagnostica che nomina l’URL e il passo che lo fissa, perché un rendering consuma la chiusura registrata dal suo lockfile e non la allarga mai. I fissaggi vengono scritti quando vengono risolte le dipendenze della Release, che è l’unico momento in cui qualcosa viene fissato. La guida per sviluppatori contiene le istruzioni di authoring e la disciplina di fissaggio per intero.

Mappe che mantengono il loro ordine

Alcune mappe che un payload trasporta sono marcate come mappe che preservano l’ordine nello schema del loro socket, perché l’ordine delle loro voci fa parte di ciò che trasportano: i nodi di una build, le etichette di un nodo, le associazioni su un nodo, gli input e gli output di un passo della pipeline, gli spazi di chiavi che un provider dichiara. I tipi di payload pubblicati conservano ciascuna di queste mappe in un contenitore che mantiene le voci nell’ordine in cui sono state impostate:

KitContenitore
Goaggrega.OrderedMap[V] — il nome che il kit dà a abi.OrderedMap[V] del pacchetto ABI
RustOrderedMap<V> dal crate aggrega-abi, riesportato dal kit
TypeScriptil Map<string, V> proprio del linguaggio

I contenitori Go e Rust offrono le operazioni di una mappa — cercare una chiave, impostarla, eliminarla, leggere le chiavi, percorrere le voci in ordine, contarle. Impostare una chiave che il contenitore contiene già ne sostituisce il valore e ne mantiene la posizione; una nuova chiave va dopo tutte quelle esistenti.

L’ordine sopravvive a entrambe le codifiche. Nella codifica binaria una mappa marcata viene scritta come un elenco ordinato di voci — ogni voce un elenco di due elementi, la chiave e poi il valore — nell’ordine del contenitore, laddove la codifica canonica scriverebbe altrimenti una mappa con le chiavi ordinate. Nella codifica testuale è un oggetto JSON i cui membri sono scritti nell’ordine del contenitore. Un decodificatore, in entrambe le codifiche, rifiuta una mappa che ripete una chiave, indicando la chiave. Una mappa che lo schema non marca mantiene la forma di mappa con chiavi ordinate nella codifica binaria e il tipo di mappa ordinario di un linguaggio nei tipi pubblicati.

Tre conseguenze per un guest:

  • L’ordine è output. Poiché una mappa marcata viene scritta nell’ordine in cui è stata riempita, un guest che ne riempie una a partire da una sorgente senza un ordine fisso — iterando una mappa integrata di Go, per esempio — scrive byte che differiscono tra esecuzioni con input identico. Riempila in un ordine fisso.
  • L’ordine vale solo finché la mappa resta nel suo contenitore. Un guest che converte un payload in un tipo di valore generico del proprio linguaggio ottiene invece l’ordine di quel tipo: un map[string]any di Go non ne ha alcuno, e il serde_json::Value di Rust mantiene ordinate le chiavi degli oggetti, a meno che il crate non sia compilato con la sua funzionalità preserve_order.
  • In TypeScript, leggi e scrivi tramite le funzioni generate. Un tipo che contiene una mappa marcata decodifica il proprio JSON membro per membro, così una chiave che si legge come un indice di array, come "8080", mantiene la sua posizione laddove JSON.parse la sposterebbe in testa all’oggetto; e il suo codificatore scrive ogni Map come un oggetto, laddove JSON.stringify scrive un Map come {}. Anche Object.keys di un Map è vuoto: leggi le chiavi di un Map con il suo keys().

Valori che un input marca come sensibili

Un plugin non cita mai, in un rifiuto o in un avviso che restituisce, un valore che il suo input marca come sensibile — tramite la sua chiave, o come parte di un payload marcato nel suo insieme. Un rifiuto è l’error che un output porta; un avviso è un Diagnostic che l’output porta, qualunque sia la sua severità, oppure uno sollevato tramite aggrega_emit_warning. L’host riporta quel testo invariato ovunque lo segnali — la riga di comando, il language server e l’elenco dei problemi dell’editor, gli strumenti dell’assistente — e non ne legge alcun valore, quindi il plugin è l’unica parte in grado di tenere fuori il valore. Indica invece la chiave, l’impostazione o la posizione: da lì un lettore trova il valore.

La regola copre il testo che una libreria scrive per il plugin tanto quanto il testo che il plugin scrive da sé. Un motore di template riporta i dati che stava valutando, un validatore di schema cita un valore che non soddisfa un pattern, un parser cita il token che non è riuscito a leggere. Dove un tale errore ha riguardato un valore che l’input marca, segnalalo senza il valore — per esempio, esegui di nuovo lo stesso passo con ogni valore marcato sostituito da un segnaposto, segnala l’errore di quell’esecuzione quando fallisce nello stesso punto, e altrimenti di’ che il testo dell’errore è trattenuto. Sotto un payload marcato nel suo insieme, ogni valore in quel payload è un valore marcato, mentre le sue chiavi — la forma del documento — restano leggibili.

Dove un input marca come sensibile una chiave o un payload, scritto come lo nominano i dati trasmessi:

Socket ed exportDove viene letta la marcatura
provider render_node e validate_node_input (RenderNodeInput)node.sensitive_rendered_keys: ogni chiave nomina una voce di node.values quando quei valori sono quelli propri del Component, indicizzati dalle foglie che esso dichiara — il valuesMapping di una Recipe scrive chiavi che nessuna dichiarazione nomina, quindi nessuna di esse è marcata qui — oppure una voce della mappa attachments del container di un carico di lavoro che legge uno slot dichiarato sensibile. node.sensitive_values marca node.values nel suo insieme: è true quando un valuesMapping — quello della Recipe, o quello della FeatureRecipe di un’associazione — ha prodotto quei valori e legge un valore che un autore ha dichiarato sensibile. workload_projection.sensitive_workload marca allo stesso modo ogni valore del carico di lavoro quando il template del carico di lavoro ne legge uno, e ogni voce di artifacts_projection.entries porta sensitive_content per il proprio contenuto, incluso un messaggio di un parser su quel contenuto. Ogni voce di omits porta sensitive quando il template che produce il suo kind, il suo nome o il suo namespace ne legge uno, e allora ogni campo di quella voce è un valore marcato. Ogni voce di node.features porta la marcatura della propria associazione: sensitive_payload_leaves (le foglie values.<path> e infra.<path> che la sua Feature dichiara sensibili), sensitive_inject (le chiavi di consegna inject che leggono una chiave provides che la sua Feature dichiara sensibile) e sensitive (se l’associazione gestisce o meno materiale dichiarato sensibile).
governance ir-verdict (PolicyInput)graph: le sensitive_payload_leaves di ogni nodo, e le sensitive_payload_leaves, sensitive_inject e sensitive di ogni associazione. Ogni valore che quelle marcature nominano arriva già come il marcatore di valore trattenuto {"aggrega_withheld": "declared"}, quindi il valore stesso non raggiunge mai il plugin.

Nessun altro input di socket, e nessun altro input di un export del provider, porta una marcatura. Una marcatura di chiave nomina solo ciò che collega esattamente a una dichiarazione, quindi una chiave assente non significa mai che un valore si possa citare senza rischi: significa che nessuna dichiarazione è stata collegata a quella chiave. Una marcatura di payload viene letta dai riferimenti del template che ha prodotto il payload — un riferimento che raggiunge un valore dichiarato, il template che trasmette l’intero insieme dei propri dati, o un template che non si riesce ad analizzare — e mai da un valore, quindi la sua assenza significa che quel template non ha letto alcun valore dichiarato, per quanto mostrano i suoi riferimenti, o che nessun template ha prodotto il payload; non è un’affermazione che il payload non porti nulla di sensibile.

Collocazione dei socket Wasm nella pipeline

La pipeline di compilazione riserva i seguenti punti socket. Le etichette di forma seguono la tassonomia a quattro etichette della pagina di stato.

SocketCollocazione nella pipelineStato attuale
Socket di governance, ruolo annotation-transformRisoluzione (prima dell’espansione delle annotazioni)disponibile — invocato quando un workspace associa un plugin annotation-transform; inietta annotazioni che l’espansione trasforma in associazioni di Feature
Socket di governance, ruolo label-transformCostruzione della topologia (il costruttore della topologia)disponibile — invocato quando un workspace associa un plugin label-transform; applica automaticamente etichette ai nodi tramite JSON Patch
Socket di governance, ruolo ir-verdictAnalisi statica (l’analizzatore statico, sul grafo IR)disponibile — invocato quando un workspace associa un plugin ir-verdict; un verdetto halt arresta la build
Socket di governance, ruolo render-verdictRendering (sugli artefatti renderizzati)disponibile — invocato quando un workspace associa un plugin render-verdict; un verdetto halt arresta la build
Plugin pipeline: di FeatureRecipe e RecipeLa pipeline dei plugin (mutazione post-rendering)disponibile — ogni passo dichiarato viene eseguito sull’insieme dei documenti renderizzati, applicando patch RFC 6902 ed emettendo effetti collaterali
Plugin di rendering dei Provider (helm, helm-chart, compose, terraform, cloudformation)Rendering di base (i provider)disponibile — ogni provider esegue il rendering tramite il proprio guest Wasm; il rendering è solo Wasm, senza alcun renderer di ripiego nell’host
Plugin parser (parse:<format>)Rendering, per una policy render-verdict; e fuori banda, per un’importazionedisponibile — chiamato per un artefatto in un formato che una policy render-verdict non legge nativamente, per un importatore tramite aggrega_parse_source, e per riconoscere il formato di un’importazione che non ne indica alcuno
Plugin importatori (import:<format>)Fuori banda (aggrega import)disponibile — invocato da aggrega import, dalla sessione dell’editor e dallo strumento rivolto all’assistente
Plugin linter (linter/publishing)Fuori banda (aggrega lint)disponibile — il linter di pubblicazione è incluso e viene eseguito tramite l’host con aggrega lint

La sotto-fase di espansione delle Feature guidata dalle annotazioni, parte della risoluzione, è un passaggio nativo Go della pipeline, non un socket Wasm. Convalida i valori delle annotazioni rispetto allo spec.schema della Feature di destinazione e inietta associazioni di Feature sintetiche al momento della build dell’IR. Vedi vocabulary/labels-and-annotations.md per le sei superfici che portano annotazioni ed etichette e providers/well-known-annotations.md per la forma dei binding e le indicazioni per scriverli.

Contratto della forma di output — che cosa esiste oggi

Il socket di governance offre una superficie di contratto tipizzata in ciascuno dei suoi quattro ruoli, ed è il ruolo a stabilire quale. Gli autori di Plugin implementano codice lato guest che produce le forme documentate; l’host le legge in fase di build, una volta per ogni plugin configurato, quando un workspace associa un plugin a quel ruolo. Le sottosezioni seguenti seguono l’ordine in cui la pipeline li invoca.

Il ruolo annotation-transform — output di iniezione di annotazioni

Collocazione nella pipeline. Risoluzione, dopo che i componenti sono stati risolti e prima che venga eseguita l’espansione delle Feature guidata dalle annotazioni.

Forma dell’input (host → guest). Un documento AnnotationTransformInput che contiene:

  • targets — le destinazioni dell’iniezione: i componenti risolti che il guest può annotare — quelli che un confine nomina direttamente, e ogni componente che una voce di instradamento sotto gli aggregates: di un confine fa entrare, che la voce lo nomini o meno — ciascuno con il suo boundary_path, il suo component_name (per un componente instradato, il suo id puntato nel grafo di build, come metrics.query) e le annotations che la Release scrive su di esso, così un guest può decidere che cosa aggiungere senza sostituire un valore scritto dall’autore. Ogni valore di annotazione arriva così come è scritto — una stringa, un oggetto di sottochiavi, oppure null dove il componente rinuncia a un’annotazione che erediterebbe — e ogni chiave che il componente porta è presente qualunque sia il suo valore. Ordinati in modo deterministico dall’host.
  • binding_keys — le chiavi di annotazione per cui il Manifest registra un binding, nell’ordine dell’autore. Un’iniezione sotto una chiave registrata prosegue espandendosi in un’associazione di Feature, quindi un guest legge questo elenco per iniettare chiavi che avranno effetto. L’host non richiede che un’iniezione nomini una chiave registrata: un’annotazione iniettata non registrata si comporta esattamente come un’annotazione scritta dall’autore senza binding.
  • sources — i file di definizione che l’associazione ha dichiarato sotto with.sources, ciascuno con il proprio percorso di nome base e il proprio contenuto, ordinati per percorso.
  • settings — l’oggetto di impostazioni in forma libera che l’associazione ha dichiarato sotto with.settings, consegnato al guest così com’è.

settings e sources sono lo stesso canale with agnostico rispetto al motore che legge ogni altro ruolo, ed entrambi sono assenti quando l’associazione non ne dichiara. Poiché l’output di questo ruolo modella la build, le impostazioni e il contenuto delle sorgenti dell’associazione vengono fissati nel lockfile della release al pull e ricostruiti da esso alla build.

Forma dell’output (guest → host). Un documento AnnotationTransformOutput che contiene:

  • injections — le annotazioni da aggiungere, in ordine. Ciascuna nomina una coordinata di destinazione esistente (boundary_path e component_name) più la annotation_key e il suo annotation_value: una stringa, oppure un oggetto di sottochiavi, che alimenta un binding che instrada più sottochiavi in una volta.

L’host applica soltanto aggiunte di annotazioni, a coordinate che ha fornito esso stesso, ciascuna con un valore che un autore potrebbe scrivere su quell’annotazione. Legge un valore iniettato esattamente come legge lo stesso valore scritto nella Release — le sottochiavi di un oggetto nell’ordine in cui il guest le ha scritte — così l’espansione lo incontra come incontra un valore scritto dall’autore. Un’iniezione che nomina una coordinata che il payload non porta, o che porta null, una lista, un numero, un booleano o un oggetto senza sottochiavi, arresta la build con un messaggio che nomina la coordinata e l’annotazione, anziché essere scartata o applicata silenziosamente; l’intero output viene controllato prima che una qualsiasi sua parte venga applicata. Questa restrizione è ciò che delimita il ruolo: un operatore che associa qui un plugin ha dichiarato l’iniezione di annotazioni e nient’altro. Dove la build rifiuta in seguito un’annotazione iniettata per il modo in cui instrada, per un valore di sottochiave che lo schema della Feature del binding non ammette, o per un pilastro che un’annotazione lato Release non può usare, il suo messaggio nomina il plugin che l’ha iniettata e il ruolo a cui è associato.

Codifica di trasmissione. Il payload e il risultato di questo ruolo viaggiano come CBOR canonico (RFC 8949 §4.2.1), in entrambe le direzioni. Un guest li legge e li scrive tramite i punti di ingresso che i tipi di payload portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, decodeCBORAnnotationTransformInput e encodeCBORAnnotationTransformOutput in TypeScript — così non serve alcuna libreria CBOR e nulla analizza i byte a mano. In Rust l’export accetta e restituisce Vec<u8>; in TypeScript legge Host.inputBytes() e scrive Host.outputBytes(...). Le annotations di ogni destinazione sono una mappa che lo schema marca come mappa che preserva l’ordine, quindi viaggiano come un elenco ordinato di voci nell’ordine in cui la destinazione le contiene, e un guest le legge tramite il contenitore che mantiene l’ordine del suo kit; ogni valore viaggia come i byte del suo JSON, come fa l’annotation_value di un’iniezione nell’altra direzione. settings viaggia come i byte del suo documento JSON, che un guest analizza come JSON per guardarvi dentro. Una risposta che non è un AnnotationTransformOutput in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — arresta la build, nominando il plugin e il suo export, anziché essere letta come un elenco vuoto di iniezioni. Chiamato direttamente con aggrega plugin run-local --export transform_annotations, un guest riceve il payload JSON scritto dall’autore convertito in questa codifica, e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Definizioni dei tipi. I tipi di dati trasmessi di annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — sono pubblicati in tutti e tre i pacchetti ABI, generati da un unico codec in modo che i tre restino allineati.

Il ruolo label-transform — output JSONPatch

Collocazione nella pipeline. Costruzione della topologia, dopo che il grafo è stato appiattito e prima che venga costruito il grafo IR, così i selettori di socket e di Feature che l’analizzatore valuta leggono le etichette che il ruolo lascia.

Forma dell’input (host → guest). Un documento MutatorInput che contiene:

  • compilation_context — l’identità della release (release_name, environment).
  • graph — una proiezione MutatorGraph dei nodi della topologia: per ogni nodo il suo Component, la versione risolta, le etichette e i values che la sua istanza dichiara.
  • settings — l’oggetto di impostazioni in forma libera che l’associazione ha dichiarato sotto with.settings, consegnato al guest così com’è.
  • sources — i file di definizione che l’associazione ha dichiarato sotto with.sources, ciascuno con il proprio percorso di nome base e il proprio contenuto, così un mutatore può essere guidato da un file di regole o di mappatura versionato anziché da impostazioni inline.

Il grafo è una proiezione e non il grafo IR: ogni nodo porta il proprio insieme di etichette risolto e i valori che la sua istanza dichiara nell’Aggregate, mentre gli archi e i payload delle funzionalità restano all’interno del compilatore. I valori sono quelli propri dell’Aggregate, con i suoi template già valutati rispetto ai suoi parametri, così un valore spostato in un parametro arriva come il valore fornito dalla Release; un valore predefinito che lo schema del Component dichiara, e qualunque cosa contribuiscano una Recipe o una Feature, non sono tra questi, e un nodo che non dichiara valori non porta alcuna chiave values. Un valore che il Component del nodo dichiara sensibile viene trattenuto esattamente come lo trattiene il verdetto sul grafo — si legge come {"aggrega_withheld": "declared"} — mentre ogni valore fratello che nessuna dichiarazione raggiunge arriva così come è scritto. È questo che permette a una configurazione dichiarata dallo sviluppatore di decidere un’etichetta — un database i cui valori abilitano un’estensione vettoriale promosso a datastore.aggrega.ai/engine: vector, per esempio. settings e sources sono lo stesso canale with agnostico rispetto al motore che leggono i ruoli di verdetto; l’host li trasmette senza mai interpretarne il contenuto. Poiché l’output di un mutatore modella la build, le impostazioni e il contenuto delle sorgenti dell’associazione vengono fissati nel lockfile della release al pull e ricostruiti da esso alla build, così l’input del mutatore è invariante rispetto a una modifica di uno dei due successiva al pull, fino al pull seguente.

Forma dell’output (guest → host). Un documento MutatorOutput che contiene:

  • patches — un array di documenti JSONPatch opachi (RFC 6902) che l’host applica soltanto alle etichette dei nodi; i valori che l’input portava sono di sola lettura.

Ogni patch indirizza le etichette di un nodo specifico tramite JSON Pointer (RFC 6901); l’host applica le patch nell’ordine dell’array e reinserisce l’insieme di etichette modificato nel grafo IR. Il compito del ruolo label-transform è l’etichettatura automatica aziendale — aggiungere etichette di conformità / osservabilità / attribuzione dei costi dichiarate dalla policy aziendale senza modificare il contenuto del catalogo. La superficie delle etichette è l’unico obiettivo consentito di questo ruolo: una patch che tocca un campo del nodo diverso dalle sue etichette, aggiunge o rimuove un nodo, o imposta un valore di etichetta che non è una stringa arresta la build anziché essere assorbita silenziosamente. RFC 6901 è la base di riferimento della grammatica dei percorsi per ogni superficie di percorso di documento in Aggrega — il contratto dei plugin Wasm qui, più gli export *_path di .locals, più i campi di schema *Path altrove nel corpus. Vedi 02-naming-conventions.md «Disciplina dei suffissi di denominazione dei percorsi di documento» per la dichiarazione canonica della base di riferimento e per la disciplina dei suffissi *Path / *_path che distingue i due lati della scrittura.

Codifica di trasmissione. Il payload e il risultato di questo ruolo viaggiano come CBOR canonico (RFC 8949 §4.2.1), in entrambe le direzioni. Canonico significa che un input identico produce byte identici da ogni lato, ed è ciò che permette di confrontare un payload tra i tre kit per plugin anziché soltanto codificarlo e ridecodificarlo, ed è il motivo per cui l’output di una build resta identico byte per byte. Un guest li legge e li scrive tramite i punti di ingresso che il tipo di payload del suo kit porta già — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, decodeCBORMutatorInput e encodeCBORMutatorOutput in TypeScript — così non serve alcuna libreria CBOR e nulla analizza i byte a mano. In Rust l’export accetta e restituisce Vec<u8>; in TypeScript legge Host.inputBytes() e scrive Host.outputBytes(...). I nodes del grafo, le labels di ogni nodo e i values di ogni nodo sono mappe che lo schema marca come mappe che preservano l’ordine, quindi viaggiano come elenchi ordinati di voci — i nodi nell’ordine in cui la build li contiene, che è l’ordine dell’autore, le etichette di ogni nodo nell’ordine in cui il nodo le porta, e i valori di ogni nodo nell’ordine in cui l’Aggregate li scrive — e un guest legge tutti e tre tramite il contenitore che mantiene l’ordine del suo kit. Ogni valore viaggia come i byte del suo documento JSON: i kit Go e Rust lo consegnano al guest come quel JSON, da analizzare quanto basta a una regola, e il kit TypeScript come il valore già analizzato.

Due cose che questo non cambia. L’array patches resta JSON: il socket porta ogni documento di patch così com’è come contenuto opaco e nessuno dei due lati vi legge dentro, quindi la forma propria di un documento di patch è indipendente dalla codifica che il suo socket porta. E settings e sources vengono ancora consegnati così come sono — settings arriva come i byte che l’associazione ha scritto, che un guest analizza come JSON se ha bisogno di guardarvi dentro.

Ogni altro ruolo di governance porta la stessa codifica — il ruolo annotation-transform e i due ruoli di verdetto lo dicono ciascuno nella propria sezione — così un guest che serve più di un ruolo parla CBOR canonico in ogni ruolo che serve, leggendo ogni payload tramite il punto di ingresso di decodifica del proprio tipo.

Definizioni dei tipi. I tipi di dati trasmessi del mutatore — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — sono pubblicati in tutti e tre i pacchetti ABI (github.com/aggrega-ai/aggrega-abi/go, il crate aggrega-abi e @aggrega-ai/aggrega-abi), generati da un unico codec in modo che i tre restino allineati. L’host assembla l’input e applica le patch che il guest restituisce.

I ruoli di verdetto — output di array di verdetti

Un guest di policy ispeziona una build e restituisce un elenco di verdetti; l’host agisce sulla severità di ciascun verdetto e non interpreta mai la policy stessa. La trattazione completa — i quattro ruoli, le severità, il canale di input fornito dall’operatore, la scrittura di una policy per l’uno o l’altro dei due motori inclusi nel compilatore, l’incapsulamento di un motore di policy esterno, i guest di riferimento e il modo in cui un operatore associa una policy — si trova nella pagina del socket di governance. Questa sezione registra la collocazione nella pipeline e le forme tipizzate dei dati trasmessi.

Collocazione nella pipeline. Una policy è associata esattamente a un ruolo di verdetto, che stabilisce dove viene valutata:

  • ir-verdict — valutato durante l’analisi statica, prima del rendering di base. L’analizzatore assembla il payload a ogni build.
  • render-verdict — valutato dopo il rendering, sugli artefatti emessi.

Quando un workspace associa un plugin di un ruolo di verdetto, la pipeline serializza il payload di quel ruolo verso il plugin e ne rilegge i verdetti.

Forma dell’input (host → guest). Il ruolo seleziona il payload:

  • Il PolicyInput di ir-verdict porta graph — l’intero grafo IR agnostico rispetto alle capacità (la stessa forma che emette il costruttore della topologia), con ogni dettaglio di nodi, archi e associazioni che il compilatore possiede, salvo che un valore che un autore ha dichiarato sensibile arriva trattenuto (vedi Valori che un input marca come sensibili) — e precalculated_paths, i percorsi di instradamento che l’analizzatore enumera accanto a esso, così una policy può ragionare sulla raggiungibilità senza ripercorrere il grafo. Il grafo è il grafo IR versionato, con un’unica fonte nello schema ir-v1beta1; la forma dell’IR non è segreta (è lo stesso grafo che aggrega inspect emette) e i segreti al suo interno sono puntatori, mai testo in chiaro.
  • Il RenderPolicyInput di render-verdict porta artifacts — i file di output renderizzati ordinati per percorso, così i dati trasmessi sono identici byte per byte tra esecuzioni con input identico. Ogni voce porta il path di output dell’artefatto e il suo content renderizzato; porta anche il format in cui è stato renderizzato, quando il provider che lo ha prodotto ne ha dichiarato uno, e un tree, la vista canonica analizzata di un formato che il guest non legge nativamente, che l’host analizza tramite il parser risolto e trasmette in modo opaco. Entrambi sono assenti quando non si applicano — un formato che il guest legge nativamente (JSON, YAML) resta non analizzato perché il guest lo legga da content.

Entrambi i ruoli portano inoltre le sources dell’associazione (file di definizione delle policy che l’host legge in fase di build e consegna al guest così come sono, con i percorsi come nomi base e il contenuto opaco) e le settings (un oggetto in forma libera consegnato senza modifiche). Entrambi sono assenti quando l’associazione non ne dichiara.

Forma dell’output (guest → host). Un documento PolicyOutput che contiene:

  • results — un array di voci Diagnostic, ciascuna con una severity (halt, warn o info) e una stringa message. Un verdetto può anche impostare code, rule_id, classification, source_ref, location e suggest sulla stessa voce; l’host aggiunge al verdetto mostrato quelli tra essi che il verdetto portava, su ogni percorso di severità.

Compaiono solo i verdetti scattati; una valutazione che consente restituisce un array vuoto. L’host percorre i verdetti e fa corrispondere a ciascuna severità un’azione: halt arresta la build (mostrando ogni messaggio halt), warn segnala il verdetto e lascia proseguire la build, info lo registra senza influire sull’esito. Un halt arresta la build attraverso lo stesso punto di controllo che usa una violazione di un selettore o di appliesTo.

Codifica di trasmissione. I payload di entrambi i ruoli, e il PolicyOutput che un guest restituisce in ciascuno dei due, viaggiano come CBOR canonico (RFC 8949 §4.2.1). Un guest li legge e li scrive tramite i punti di ingresso che i tipi di payload portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput e encodeCBORPolicyOutput in TypeScript — così non serve alcuna libreria CBOR e nulla analizza i byte a mano. In Rust ogni export accetta e restituisce Vec<u8>; in TypeScript legge Host.inputBytes() e scrive Host.outputBytes(...). Le mappe del grafo che preservano l’ordine, tra cui i suoi nodes e le labels di ogni nodo, viaggiano come elenchi ordinati di voci nell’ordine in cui la build le contiene, e un guest le legge tramite il contenitore che mantiene l’ordine del suo kit; l’ordine in cui una policy le incontra con ciascun motore di policy è descritto nella pagina del socket di governance. settings, e il tree analizzato di un artefatto, viaggiano come i byte dei loro documenti JSON, che un guest analizza come JSON per guardarvi dentro. Una risposta che non è un PolicyOutput in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — arresta la build, nominando il plugin e il suo export, anziché essere letta come un elenco vuoto di verdetti. Chiamato direttamente con aggrega plugin run-local --export verdict_ir o --export verdict_render, un guest riceve il payload JSON scritto dall’autore convertito in questa codifica, e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Definizioni dei tipi. I tipi di dati trasmessi delle policy sono pubblicati negli stessi tre pacchetti ABI: PolicyInput (ruolo ir-verdict), RenderPolicyInput (ruolo render-verdict), il PolicySource condiviso e PolicyOutput, le cui voci results sono valori Diagnostic. La severità di una diagnostica è uno di tre valori che ogni socket condivide — halt, warn o info — e i tre sono pubblicati come costanti accanto ai tipi di dati trasmessi in ciascuno dei tre pacchetti, così un guest segnala a partire dallo stesso insieme chiuso su cui l’host instrada. Un guest che restituisce qualsiasi altro valore arresta la build, con il messaggio che nomina il plugin e il valore restituito: una severità non instradabile è un difetto del plugin che l’host segnala, anziché una diagnostica che scarta.

Contratto della forma di output — la pipeline della FeatureRecipe e i socket dei provider

I socket seguenti offrono superfici di contratto tipizzate che il compilatore invoca in fase di build. I passi pipeline: di FeatureRecipe e Recipe vengono eseguiti nella pipeline dei plugin sull’insieme dei documenti renderizzati; il socket di rendering dei provider viene eseguito durante il rendering di base; il linter di pubblicazione viene eseguito fuori banda.

Patch RFC 6902 (la pipeline dei plugin)

I passi pipeline: di FeatureRecipe e Recipe eseguiti nella pipeline dei plugin emettono operazioni JSON Patch RFC 6902 sull’insieme dei documenti renderizzati. L’host consegna a ogni passo l’intero insieme dei documenti indicizzato per chiave; il passo seleziona per contenuto i documenti a cui è destinato e restituisce patch indirizzate per chiave, che il motore di applicazione applica ai documenti indirizzati — in genere aggiungendo un container sidecar, montando un volume di secret o riscrivendo una variabile d’ambiente. Un passo restituisce anche side_effects (più sotto), diagnostics — ogni voce nella stessa forma condivisa Diagnostic in cui ogni socket segnala i problemi — e outputs (più sotto). Descritto in examples/04-secrets.md.

Stato attuale: disponibile. Ogni passo dichiarato viene eseguito durante aggrega build.

Codifica di trasmissione. L’input di un passo (FRPStepInput) e la sua risposta (FRPStepOutput) viaggiano come CBOR canonico (RFC 8949 §4.2.1), in entrambe le direzioni. Un guest decodifica il proprio input e codifica la propria risposta tramite i punti di ingresso che i tipi di payload portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust (sui tipi che il crate aggrega-abi pubblica), decodeCBORFRPStepInput e encodeCBORFRPStepOutput in TypeScript — leggendo e scrivendo byte (Vec<u8> in Rust, Host.inputBytes() e Host.outputBytes(...) in TypeScript). Non serve alcuna libreria CBOR e nulla analizza i byte a mano. L’input with del passo (step_input), gli outputs che restituisce e gli insiemi di documenti own e host sono mappe che lo schema marca come mappe che preservano l’ordine, quindi viaggiano come elenchi ordinati di voci nell’ordine in cui la pipeline li contiene, e un guest li legge e li scrive tramite il contenitore che mantiene l’ordine del suo kit — ed è questo che permette agli output di un passo di raggiungere .steps.<id>.outputs nell’ordine in cui il passo li ha restituiti. Il tree di ogni unità, ogni valore di step_input e outputs, il value di una patch, il crd di un effetto collaterale e il context di rendering viaggiano come i byte dei loro documenti JSON, che un guest analizza come JSON per guardarvi dentro; i bytes di un’unità viaggiano come una sequenza di byte grezzi che il decodificatore generato inserisce nel tipo di campo proprio del kit — una slice di byte in Go, una stringa base64 in Rust e TypeScript. Ogni diagnostica viaggia nella forma condivisa Diagnostic. Una risposta che non è un FRPStepOutput in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — fa fallire il passo, nominando la funzione che esegue, il che arresta la build a meno che il passo non sia optional. Chiamato direttamente con aggrega plugin run-local --export step, un passo riceve il payload JSON scritto dall’autore convertito in questa codifica, e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Effetti collaterali — emissione di risorse (plugin di credenziali nella pipeline dei plugin)

Le pipeline di FeatureRecipe per le credenziali (principio del Plugin in due parti: Fetcher + Injector) emettono risorse complete accanto a una patch tramite i side_effects di un passo, ciascuna delle quali dichiara uno dei due tipi che il contratto definisce: emit_crd, un documento di risorsa personalizzata come una CRD ExternalSecret o VaultSecret che il cluster recupera a runtime, oppure emit_file, un file scritto. Un passo che restituisce qualsiasi altro tipo arresta la build, nominando il nodo, l’indice dell’effetto collaterale e il tipo che ha dichiarato. Il passo del Fetcher emette la risorsa completa; il passo dell’Injector restituisce una patch che monta il Secret Kubernetes risultante. Descritto in examples/04-secrets.md.

Stato attuale: disponibile.

Output di un passo (mappa outputs di un passo di pipeline:)

Un passo della pipeline dei plugin pubblica output con nome che i passi successivi consumano tramite {{ .steps.<id>.outputs.<key> }}. La forma dell’output è definita dal provider per ciascun plugin; gli output dei passi hanno come ambito la stessa pipeline e sono visibili solo ai passi successivi, nell’ordine di dichiarazione. Documentato in templates/expansion-matrix.md, riga 10.

Stato attuale: disponibile.

Rendering dei Provider — il socket guidato dal guest

Un provider è un guest Wasm. Il rendering è solo Wasm: il nome capability: di una Recipe si risolve nel Plugin di rendering dei provider (pluginType: provider) che elenca quel nome nelle proprie spec.provider.capabilities e annuncia un export render_node, e il guest di quel plugin esegue il rendering del nodo. Non esiste alcun renderer nell’host su cui ripiegare; un nome di provider che non si risolve in alcun Plugin che lo serva arresta la build al momento dell’instradamento. Aggiungere un provider standard significa distribuire un guest .wasm e un’entità Plugin del catalogo — l’host non contiene codice specifico per provider.

Una capacità servita da un provider non contiene due punti, e nemmeno una con cui un passo di pipeline si dichiara compatibile. Il capability: di una Recipe viene letto come la capacità fino all’ultimo segno di due punti, seguita da un fissaggio di versione — helm:1.0.0 chiede helm alla versione 1.0.0 — quindi un nome che contiene i due punti è un nome che nessuna Recipe può chiedere. L’host rifiuta un tale nome nelle capabilities di describe() per un guest provider o pipeline-step quando il guest viene caricato e quando la sua entità viene generata per la pubblicazione, nominando il guest e il nome. Il parse:<format> di un parser e l’import:<format> di un importatore mantengono i loro due punti: vengono cercati per formato, mai tramite il capability: di una Recipe.

L’host è un router generico. Legge l’autodescrizione describe() del guest — incluso il suo contratto di comportamento di rendering — e smista gli export del guest senza comprendere alcun formato di provider. Quel contratto guida lo smistamento come dati:

  • input_kinds (sourced, synthesized, artifacts_standalone) — quali tipi di input di Recipe il guest renderizza; l’host verifica il tipo di input di un nodo rispetto a questo insieme.
  • boundary_assembly (none | merge | nest) — come il guest combina l’output di un gruppo di smistamento: merge classifica l’output di ciascun nodo come frammenti che l’assemblatore unisce in un unico artefatto, nest annida i file di ciascun nodo sotto un involucro assemblato, none scrive direttamente l’output di ogni nodo.
  • nest_segment (opzionale) — per un assemblaggio nest, la directory sotto cui viene collocata la sottodirectory propria di ciascun contributore, scritta come un unico nome di directory; se assente, la sottodirectory di ciascun contributore si trova direttamente nella posizione di smistamento.
  • assembly_name_annotation (opzionale) — un’annotazione di confine il cui valore risolto dà il nome all’artefatto che il guest assembla da un gruppo di smistamento; se assente, il guest dà il nome al proprio assemblaggio a partire dal solo percorso di smistamento.
  • cross_boundary_linking (opzionale) — se il guest collega un arco uses tra confini diversi tramite i suoi export link_publish e link_resolve; un guest lo dichiara vero esattamente quando esporta entrambi, e il caricamento rifiuta un guest il cui flag e i cui export non concordano.
  • artifact_delimiters (opzionale) — la coppia di delimitatori dei template Go che il guest applica ai corpi degli artefatti.
  • reusable_instance (opzionale) — se un’unica istanza caricata può servire ogni attraversamento della build (vedi Determinismo e riutilizzo delle istanze più sotto).
  • omits (opzionale) — se il guest rispetta le voci di omissione che un rendering da sorgente porta (vedi Lasciare fuori le unità renderizzate più sotto).
  • boundary_artifacts (opzionale) — se la destinazione del guest accetta i file che una Recipe apporta all’output condiviso del proprio confine (vedi Accettare i file che una Recipe apporta al confine più sotto).
  • source_ignore (opzionale) — i file che l’ecosistema del guest non distribuisce mai accanto a una sorgente che esso renderizza (vedi Dichiarare ciò che l’ecosistema di una sorgente non distribuisce mai più sotto).

Il socket è un insieme fisso di export — uno obbligatorio, gli altri opzionali e annunciati in describe():

  • render_node (obbligatorio) — esegue il rendering di un nodo IR in file nativi del provider.
  • assemble_boundary (opzionale) — unisce l’output per nodo di un gruppo di smistamento in un unico artefatto per percorso (presente quando boundary_assembly è merge o nest).
  • validate_node_input (opzionale) — convalida strutturale dell’input di un nodo prima del rendering; una diagnostica halt arresta la build, una warn emerge nel risultato della build.
  • carve / reassemble (opzionali, in coppia) — il codec di patch proprio del guest, fedele ai byte, per i passi di pipeline successivi al rendering, usato solo quando entrambi sono annunciati.
  • name_bound (opzionale) — il guest valuta se un nome che l’host propone come identità di un componente produce nomi che la sua destinazione accetta, rispondendo con un vincolo anziché con un nome proprio.
  • rendered_name (opzionale) — il guest riporta il nome che la sua destinazione dà alle risorse che esso renderizza per un nodo.
  • link_publish / link_resolve (opzionali, in coppia) — il guest collega un arco uses tra confini diversi: l’estremità consumata pubblica un riferimento, e l’estremità consumatrice lo risolve nel proprio output assemblato.

Gli artifacts: di una Recipe confluiscono in render_node tramite una proiezione degli artefatti sull’input: l’host esegue la lettura di $import, la valutazione dei template Go e il calcolo delle chiavi/valori di provenienza, e consegna al guest ogni voce già letta e valutata; il guest è responsabile della collocazione e dell’emissione nel formato che solo esso conosce. Documentato in architecture/13-catalog-and-registry.md.

L’input di un rendering da sorgente porta i valori del nodo su node.values, e node.values_mapped dice da dove provengono: è true quando sono l’output del valuesMapping della Recipe — oppure, per il rendering proprio di un’associazione, di quello della sua FeatureRecipe — ed è assente quando sono i valori propri del componente trasmessi così come sono scritti. Se un guest lo legga o meno fa parte del contratto proprio di quel guest. Il provider cloudformation lega i Parameters di un template da sorgente solo a valori prodotti da una mappatura, perché i valori propri di un componente potrebbero essere stati scritti per gli altri input della Recipe; il provider terraform scrive gli argomenti di un modulo da sorgente a partire dai valori che il suo assemblaggio riceve, e non legge il flag. Quei valori viaggiano su ogni nodo renderizzato di un input di assemble_boundary per un nodo renderizzato da una sorgente — quelli di un componente, che una mappatura li abbia prodotti o meno, quelli di una Feature associata solo dove li ha prodotti il valuesMapping della sua FeatureRecipe — e lo stesso flag viaggia accanto a essi e solo dove essi viaggiano, così un assemblatore legge la stessa risposta che ha letto il rendering proprio del nodo; il provider cloudformation lo legge lì per sapere quali parametri il binding di un nodo ha valorizzato, e rifiuta un riferimento a uno di essi da qualsiasi altro punto dello stack, compreso il componente ospitante di una Feature associata. Il flag registra come sono stati prodotti i valori e non viene mai derivato da una chiave o da un valore.

Codifica di trasmissione. Ogni export di questo socket riceve il proprio input e restituisce il proprio output come CBOR canonico (RFC 8949 §4.2.1), in entrambe le direzioni. Un guest decodifica il proprio input e codifica il proprio output tramite i punti di ingresso che i tipi di payload già portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, e in TypeScript le funzioni decodeCBOR e encodeCBOR di ciascun tipo, come decodeCBORRenderNodeInput e encodeCBORRenderNodeOutput — leggendo e scrivendo byte (Vec<u8> in Rust, Host.inputBytes() e Host.outputBytes(...) in TypeScript). Non serve alcuna libreria CBOR e nulla analizza i byte a mano. Il content di un file renderizzato, e ogni altro campo di byte, viaggia come una sequenza di byte grezzi che il decodificatore generato inserisce nel tipo di campo proprio del kit: una slice di byte in Go, una stringa base64 in Rust e TypeScript. Le mappe che lo schema marca come mappe che preservano l’ordine — tra cui i values, le features e gli uses di un nodo, le derived_keys di una risposta e i values di un contributore di un assemblaggio — viaggiano come elenchi ordinati di voci nell’ordine in cui la build le contiene, e un guest le legge tramite il contenitore che mantiene l’ordine del suo kit. Ogni valore dei values di un nodo viaggia come i byte del proprio documento JSON, così le chiavi all’interno di un valore mantengono l’ordine in cui sono state scritte; lo stesso vale per ogni voce di associazione di features, il contesto di rendering, il carico di lavoro analizzato, ogni arco arricchito, ogni unità ritagliata e ogni operazione di patch, e un guest li analizza come JSON per guardarvi dentro. Ogni diagnostica viaggia nella forma condivisa Diagnostic. Una risposta che non ha la forma di output del suo export in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — arresta la build, nominando l’export che ha chiamato. Gli esempi di payload in questa pagina sono scritti come JSON per facilitarne la lettura. Chiamato direttamente con aggrega plugin run-local --export render_node, o con qualsiasi altro export del socket, un guest riceve il payload JSON scritto dall’autore convertito in questa codifica, e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Stato attuale: disponibile per tutti e cinque i provider. Il guest helm renderizza chart da sorgente (risolvendo la radice del chart), carichi di lavoro sintetizzati e artefatti autonomi come manifest Kubernetes piatti. Il guest helm-chart assembla un umbrella chart, annidando il chart da sorgente di ogni nodo come sotto-chart, e porta un codec di patch fedele ai byte e delimitatori di artefatto tra parentesi quadre ([[ ]]). Il guest compose renderizza file compose da sorgente e carichi di lavoro sintetizzati e unisce un gruppo di smistamento in un unico docker-compose.yaml, collegando un servizio alle reti dei componenti che il suo x-aggrega-networks-of nomina. Il guest terraform emette configurazione Terraform così com’è (HCL o JSON) oppure incorpora un modulo da sorgente e ne fornisce gli input come argomenti del blocco module di quel componente, convalida strutturalmente l’HCL di un modulo da sorgente prima del rendering, e compone un confine in un’unica configurazione radice che dichiara ogni componente come un blocco module che ha come sorgente la sottodirectory propria di quel componente. Il guest cloudformation renderizza template da sorgente e frammenti di stack autonomi, unisce un gruppo di smistamento in un unico template di stack, e collega un arco uses tra confini diversi tramite link_publish e link_resolve. Ognuno esegue il rendering offline e in modo deterministico.

Dichiarare i nomi che un guest deriva

Un guest di provider deriva di solito nomi di cui il suo output ha bisogno ma che nessuno ha scritto — l’identificatore con cui una destinazione indirizza una risorsa, il nome con cui un output viene pubblicato perché un altro vi faccia riferimento — dall’identità del nodo e dalla risorsa che sta emettendo. Due nodi possono arrivare allo stesso nome ogni volta che le parti da cui sono derivati coincidono, e poiché il nome vive all’interno dei byte del file che l’host scrive così come sono, l’host non può vedere il conflitto: dovrebbe analizzare il formato del provider per trovarlo, ed è esattamente la conoscenza che resta nel guest.

render_node restituisce quindi nel suo output delle derived_keys opzionali, e la direzione è invertita — anziché essere l’host a ispezionare l’output, il guest dichiara e l’host verifica:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"derived_keys": {
"logical-ids": ["paymentsapiQueue", "paymentsapiTopic"],
"export-names": ["aggrega--prod--api--orders-db--host"]
}
}

Ogni chiave di derived_keys è uno spazio di chiavi a cui il guest dà un nome, e ogni spazio porta i nomi che il guest vi ha derivato, nell’ordine di derivazione. Sia i nomi degli spazi sia i nomi al loro interno sono il tuo vocabolario: l’host li legge solo come stringhe da confrontare per uguaglianza all’interno di uno stesso spazio. Non analizza un nome, non apprende che cosa significhi uno spazio o un nome e non ne deriva mai uno da sé — così un unico controllo copre ogni tipo di nome che ogni provider deriva, e un nuovo provider non richiede nuovo codice nell’host. Nei tipi pubblicati derived_keys è una mappa che mantiene l’ordine, quindi gli spazi viaggiano nell’ordine in cui il tuo guest li imposta.

Ciò che l’host ne fa si riduce a una sola domanda: all’interno di uno spazio, ogni nome dichiarato è distinto tra i contributori il cui output confluisce in un unico assemblaggio? Due contributori che dichiarano lo stesso nome nello stesso spazio arrestano la build, e l’arresto nomina lo spazio, il nome ed entrambi i contributori, così un autore può intervenire senza leggere il provider. Nomi distinti, e nomi che coincidono per caso tra due spazi diversi, passano.

Tre proprietà sono utili da conoscere quando decidi che cosa dichiarare:

  • L’ambito è un unico output assemblato — l’insieme dei contributori i cui file vengono uniti. Un guest che vuole l’unicità in un ambito più ristretto o più ampio di questo esprime l’ambito nel nome dello spazio che dichiara, il che lascia la scelta a te anziché all’host.
  • Un contributore può ripetere liberamente un nome. Un nodo può essere renderizzato in diversi attraversamenti — un rendering da sorgente, una sintesi di carico di lavoro, una collocazione di artefatti — e le dichiarazioni si uniscono. Lo stesso nome dichiarato due volte da un contributore è quel contributore che descrive due volte una stessa risorsa, non un conflitto.
  • Dichiarare non cambia alcun byte. Il campo è un’asserzione su ciò che il guest ha derivato, mai una modifica a ciò che ha emesso, quindi l’output renderizzato di un guest è identico che dichiari o meno. Omettere derived_keys è valido e lascia il controllo inattivo per quel guest.

Riportare fatti su ciò che un guest ha emesso

Alcune cose del rendering di un nodo sono visibili solo al provider che lo ha prodotto — che cosa contengono i documenti che ha scritto, quali nomi definiscono, quanti elementi di un certo tipo ha emesso — perché ricavarle dai byte del file significa comprendere il formato del provider. render_node può riportare tali cose esso stesso, in un elenco opzionale render_facts accanto ai suoi file:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

Ogni fatto è un name e un value, ed entrambi appartengono al tuo provider: quali fatti riporta, che cosa significa ciascun nome e che cosa contiene ciascuna voce fanno parte del contratto documentato proprio del tuo provider, quindi documentali per gli autori che li leggeranno.

Riporta il valore di ogni fatto come un elenco — un array JSON — anche quando contiene una sola voce. Uno stesso nome può essere riportato da più di un rendering di un componente: il suo rendering proprio può richiedere diverse chiamate — un rendering di chart e una collocazione di artefatti, per esempio — e ogni Feature associata al componente viene renderizzata tramite una propria chiamata al provider. Nessun provider può sapere, mentre renderizza, se il suo resoconto sarà l’unico sotto un nome, quindi ogni resoconto è un elenco, e il compilatore unisce in un unico elenco gli elenchi che un nome riceve. Un fatto il cui valore è qualsiasi altra cosa — un oggetto, una stringa, un numero, un booleano, null — viene rifiutato quando il tuo guest lo restituisce: la build si arresta con il codice breve E0325, nominando il fatto, il nodo e il tuo guest, e dicendo qual era il valore. Le voci all’interno di un elenco sono valori JSON qualsiasi nella forma che documenti.

Che un valore sia un elenco è l’unica cosa che il compilatore ne apprende. Indicizza i fatti per nome e consegna ogni elenco ai template che lo leggono — i fatti del componente ospitante a ogni Feature a esso associata, i fatti di ciascun chiamante a una Feature che dichiara di leggere i fatti di rendering dei propri chiamanti, e i fatti di ciascuna destinazione a una Feature che dichiara di leggere i fatti di rendering dei componenti a cui il suo componente ospitante è collegato, come descrive il contesto dei template — decodificando ogni elenco in un valore su cui un template può iterare. Non apprende mai che cosa significhi un nome o una voce e non deriva mai un fatto da sé, quindi un nuovo provider può riportare nuovi fatti senza alcuna modifica dal lato del compilatore. I fatti che una Feature associata al nodo riporta dal proprio rendering sono tenuti separati da quelli che ha riportato il rendering proprio del nodo.

Quattro proprietà sono utili da conoscere quando decidi che cosa riportare:

  • L’ordine è tuo. I fatti mantengono l’ordine in cui il tuo guest li elenca, e ogni valore mantiene i propri byte — l’ordine delle voci di un elenco e delle chiavi di ogni oggetto è l’ordine che il tuo guest ha scritto. Elenca i fatti in un ordine fisso e scrivi ogni voce con un ordine fisso delle chiavi, così un input identico produce byte identici; un elenco di fatti anziché una mappa esiste proprio perché quell’ordine sopravviva nel tipo sequenza proprio di ogni kit senza nulla da marcare, mentre una mappa mantiene l’ordine scritto da un guest solo quando il suo schema la marca come mappa che preserva l’ordine e il guest riempie il contenitore che mantiene l’ordine del suo kit.
  • Riportare non cambia alcun byte. I file che il compilatore scrive sono i file che il tuo guest ha restituito, che siano accompagnati da fatti o meno.
  • Un nodo può riportare in diversi attraversamenti. Un nodo può essere renderizzato come rendering da sorgente, sintesi di carico di lavoro e collocazione di artefatti; i fatti che ciascuno riporta sono mantenuti nell’ordine in cui gli attraversamenti sono stati eseguiti, e un nome riportato da più di uno di essi si legge come un unico elenco che li unisce in quell’ordine.
  • Non riportare nulla è completo. Omettere render_facts è valido, e un provider che non riporta nulla renderizza esattamente come farebbe senza il campo.

Il tipo RenderFact è pubblicato nei tre pacchetti ABI e riesportato dal kit di sviluppo per plugin di ciascun linguaggio, e gli esempi di rendering dei kit riportano due fatti accanto ai loro file. In Go, un valore è il JSON che il tuo guest scrive; serializzare una slice di struct anziché di mappe è ciò che mantiene le chiavi di ogni voce nell’ordine in cui le hai dichiarate:

type stackFact struct {
Name string `json:"name"`
Resources int `json:"resources"`
}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})
if err != nil {
pdk.SetError(err)
return 1
}
out := aggrega.RenderNodeOutput{
Files: files,
RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},
}

Lasciare fuori le unità renderizzate

Un rendering da sorgente può nominare unità che il provider deve lasciare fuori da ciò che renderizza — un Secret che un chart scaricato genera di nuovo a ogni rendering, per esempio. Quale unità renderizzata nomini una voce è una conoscenza che ha solo il tuo provider, quindi le voci viaggiano fino al tuo guest ed è il tuo guest a lasciarle fuori. Arrivano sull’input di render_node come un elenco opzionale omits accanto al source_listing:

{
"node": { "id": "payments-api" },
"context": { },
"source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] },
"omits": [
{ "kind": "Secret", "name": "payments-api-token", "namespace": "payments" },
{ "kind": "ConfigMap", "name": "payments-api-dashboards" }
]
}

Ogni voce è un kind, un name e un namespace opzionale, già risolti in stringhe semplici ed elencati nell’ordine in cui l’autore li ha dichiarati; una voce che non si applica alla build non viene trasmessa. Ciò che i tre campi selezionano è il contratto proprio del tuo provider — il tipo, il nome e il namespace di una risorsa nel formato della tua destinazione — quindi documentalo per gli autori che scrivono le voci.

Un autore può costruire i campi di una voce a partire da un valore che ha dichiarato sensibile — una risorsa che prende il nome da un’impostazione sensibile, per esempio. Una voce del genere arriva con "sensitive": true, e il tuo guest la tratta come tratta ogni altro valore marcato che l’input di rendering porta (vedi Valori che un input marca come sensibili): continua a confrontare e contare la voce in base ai suoi campi, che è lo scopo della voce, e tiene ognuno dei suoi campi fuori da un rifiuto, da un avviso o da una riga di log. La marcatura copre l’intera voce, perché il compilatore non dice quale campo ha prodotto il valore. È assente quando nessun campo è stato costruito da un tale valore.

Un guest che rispetta le voci fa tre cose:

  • Confronta ogni voce con ciò che ha renderizzato, nei termini del tuo formato.
  • Lascia ogni unità corrispondente fuori da tutto ciò che restituisce — i suoi files, i nomi che dichiara in derived_keys e i fatti che riporta in render_facts — così nulla di ciò che il compilatore riceve la descrive ancora.
  • Riporta un conteggio per voce in un elenco opzionale omitted nel suo output, nell’ordine in cui le voci sono arrivate, ciascuno il numero di unità a cui quella voce ha corrisposto, contate indipendentemente dal fatto che anche un’altra voce vi corrispondesse:
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

Uno zero è una risposta completa: quella voce non ha corrisposto a nulla di ciò che il tuo guest ha renderizzato. I conteggi sono tutto ciò che torna indietro su ciò che è stato lasciato fuori; le unità stesse sono semplicemente assenti da ciò che il tuo guest ha restituito.

Un provider che fa tutte e tre le cose lo dichiara con omits: true nel suo contratto. L’entità Plugin registra la stessa dichiarazione come spec.provider.contract.omits; dove l’entità porta un contratto di comportamento di rendering, il caricamento rifiuta un guest il cui describe() riporta un valore diverso. Le voci accompagnano un elenco della sorgente e nient’altro: un rendering di un carico di lavoro sintetizzato o di un insieme di artefatti non le porta mai.

Un rendering che non porta voci non viene modificato dai campi. Entrambi i campi sono opzionali e assenti quando vuoti, quindi un rendering che non porta voci attraversa il socket byte per byte come farebbe se i campi non esistessero, e un guest che non li legge mai non ne è influenzato. Il tipo OmitEntry è pubblicato nei tre pacchetti ABI e riesportato dal kit di sviluppo per plugin di ciascun linguaggio.

Che cosa fa il compilatore con la tua risposta. Le voci provengono dalla chiave omits: che un autore scrive su una Recipe o una FeatureRecipe (Recipe → Il campo omits:); il compilatore valuta i template di ogni voce e consegna al tuo guest quelle che si applicano. Poi legge i tuoi conteggi, e solo i tuoi conteggi — non guarda mai all’interno di un file restituito per verificarli:

Stato attuale: disponibile. I guest helm, compose e cloudformation distribuiti con il compilatore fanno la dichiarazione e rispettano le voci. Il guest helm non scrive alcun campo di alcuna voce in un testo che restituisce. I guest compose e cloudformation nominano il tipo, il nome e il namespace di una voce quando rifiutano la voce, e le unità che una voce ha lasciato fuori quando rifiutano un file o un template che le nomina ancora, e lì mostrano ogni campo di una voce marcata come <redacted>. I guest helm-chart e terraform non fanno la dichiarazione, quindi un documento che dichiara omits: renderizzato da uno di essi viene rifiutato.

Accettare i file che una Recipe apporta al confine

Alcuni file appartengono a un confine nel suo insieme anziché a uno dei suoi componenti — una configurazione di provider che una destinazione legge una sola volta per tutto ciò che il confine rilascia, per esempio. Una Recipe li scrive sotto spec.boundary.artifacts, ed è il compilatore, non il tuo guest, a fare il lavoro: valuta ogni file nel contesto in cui viene valutata una voce artifacts:, unisce per nome i file che ogni contributore del gruppo di smistamento ha dichiarato, e scrive ciascuno una sola volta nella directory che contiene l’output assemblato del gruppo, accanto a ciò che restituisce il tuo assemble_boundary. Il tuo guest non riceve nessuno di questi file su alcun export e non viene mai interrogato su nessuno di essi, quindi non c’è nulla da implementare — solo un’affermazione da fare sulla tua destinazione:

"contract": {
"input_kinds": { "sourced": true, "artifacts_standalone": true },
"boundary_assembly": "nest",
"boundary_artifacts": true
}

Dichiara boundary_artifacts: true solo quando la tua destinazione legge un file collocato in quella directory come parte dell’output del confine. L’entità Plugin registra la stessa dichiarazione come spec.provider.contract.boundaryArtifacts; dove l’entità porta un contratto di comportamento di rendering, il caricamento rifiuta un guest il cui describe() riporta un valore diverso. Una Recipe che dichiara il blocco il cui provider non lo dichiara viene rifiutata prima che venga renderizzato qualsiasi cosa, nominando il provider e il componente; vedi The provider does not support boundary artifacts (Il provider non supporta gli artefatti del confine). Un file che una di queste unioni colloca sotto un nome che anche il tuo assemblaggio scrive arresta la build come due contributori che scrivono uno stesso percorso di output, quindi i nomi che il tuo assemblaggio scrive fanno parte di ciò che documenti per gli autori.

Stato attuale: disponibile. Il guest terraform distribuito con il compilatore fa la dichiarazione, e Terraform legge ogni file accanto alla configurazione radice del confine; i guest helm, compose, helm-chart e cloudformation non la fanno.

Dichiarare ciò che l’ecosistema di una sorgente non distribuisce mai

La directory sorgente locale di una Recipe — un chart co-locato, un modulo — viene pubblicata con la Recipe, e non tutti i file che contiene le appartengono. Un guest di provider dichiara ciò che il proprio ecosistema non distribuisce mai tramite source_ignore nel suo contratto, sotto forma di regole di esclusione nella sintassi che usa .gitignore:

"contract": {
"input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false },
"boundary_assembly": "none",
"source_ignore": {
"patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"],
"files": [".helmignore"]
}
}
  • patterns sono regole lette a partire dalla radice della directory sorgente, applicate in ordine, con una corrispondenza successiva che prevale su una precedente.
  • files nomina i file di esclusione che il tuo ecosistema rispetta all’interno di una sorgente. Ovunque la visita di una sorgente ne incontri uno, le sue righe vengono lette come ulteriori regole per la directory che lo contiene, dopo i tuoi pattern.

La dichiarazione viene letta quando un’entità viene fissata, non quando viene renderizzata. Il passo di fissaggio dell’autore risolve, nel suo workspace, il plugin che serve la capacità dell’entità, compone le tue regole con il suo .aggregaignore — le cui righe vengono per ultime e quindi prevalgono su ogni percorso che nominano — e registra il nome del tuo plugin, senza versione, insieme alle esatte regole composte, nell’entity.lock dell’entità. Ogni successiva pubblicazione, ogni confronto e ogni rendering di quell’entità applicano le regole registrate; l’host le confronta con i percorsi e non ha alcuna opinione propria su alcun ecosistema. Quindi i file che il tuo guest riceve al rendering — l’elenco e ogni file che chiede all’host di impacchettare o leggere — sono esattamente i file che una pubblicazione dell’entità porta con sé, e a un file che le regole escludono si risponde che non c’è, nominandolo. Un link simbolico all’interno di una sorgente viene rifiutato prima che il tuo guest venga invocato.

La compatibilità discende da ciò che è stato registrato. Un guest può renderizzare una Recipe pubblicata per la sua capacità quando parla la stessa versione dell’ABI, il suo contratto corrisponde alla dichiarazione della sua entità e non ha bisogno di alcun file al di fuori dell’insieme pubblicato. Un guest che ha bisogno di un file che l’insieme ha escluso deve far fallire la propria build in modo esplicito e nominare il file — il rifiuto da parte dell’host di un impacchettamento o di una lettura lo nomina, e un guest lo riporta nel proprio fallimento. Dove il plugin che il workspace di un consumatore lega a una capacità dichiara regole diverse da quelle che il lockfile di un’entità registra, il pull del consumatore stampa un avviso che nomina entrambi i plugin e la differenza; non si arresta mai per questo.

Omettere source_ignore non dichiara alcuna regola, e una sorgente che renderizzi conserva allora ogni file che le regole proprie dell’autore conservano. Il campo è opzionale e non richiede una versione dell’ABI propria: un guest che lo omette viene caricato come uno che non dichiara nulla. L’entità Plugin registra la stessa dichiarazione come spec.provider.contract.sourceIgnore; dove lo fa, il caricamento rifiuta un guest il cui describe() riporta qualcosa di diverso.

Determinismo e riutilizzo delle istanze

L’host consuma i byte di output di un guest alla lettera, quindi un guest deve produrre output identico da input identico. Per impostazione predefinita un guest viene caricato da zero per ogni nodo — nessuno stato trasportato da un nodo all’altro, per costruzione. Un guest che dichiara da sé reusable_instance viene invece caricato una sola volta per build e la sua unica istanza serve ogni attraversamento, il che recupera il costo dominante dell’istanziazione per nodo. Poiché il riutilizzo è sicuro solo per un guest privo di stato, aggrega build --verify-determinism renderizza ogni nodo due volte tramite la stessa istanza e arresta la build se i due rendering di un qualsiasi nodo differiscono; la build predefinita renderizza una sola volta e si fida della dichiarazione. La cache di compilazione Wasm risiede su disco ed è condivisa dall’intero processo, quindi un guest viene compilato una sola volta e le build a caldo saltano la ricompilazione.

Il socket del linter — il linter di pubblicazione

Il socket del linter viene distribuito come il publishing-linter standard, un punto di controllo fuori banda che viene eseguito tramite aggrega lint anziché in fase di compilazione. Consuma un’entità del catalogo (e, in modalità --pre-publish, la versione attualmente pubblicata dell’entità) e restituisce un elenco di rilievi, ciascuno con una severità e un messaggio; in modalità --pre-publish restituisce anche una classificazione dell’incremento di versione. L’host lo smista tramite il runtime Wasm integrato, dietro lo stesso firewall di purezza AOT di ogni altro socket. L’insieme completo delle regole, le severità e le esclusioni per singola regola sono documentati in cli/aggrega-lint.md.

Il linter è una disciplina di catalogo su adesione volontaria: il compilatore non lo esegue durante aggrega build (con l’unica eccezione dell’avviso che sconsiglia x-aggrega-*, che emerge con severità warn durante la build e con severità halt sotto aggrega lint --pre-publish). Poiché le regole risiedono in un plugin, un’azienda può indirizzare aggrega lint verso un plugin di linter diverso per applicare la propria disciplina.

Nessun valore di parametro raggiunge un plugin di linter, in qualunque ambito venga eseguito aggrega lint. Prima che qualsiasi documento venga consegnato, l’host trattiene i valori predefiniti dei parametri di un Aggregate, i valori che esso passa a ogni modulo che importa e i parametri di una Release, mantenendo il contratto di ogni dichiarazione di parametro — solo le chiavi con cui una dichiarazione è scritta, a ogni livello di annidamento — e qualsiasi testo di template che legge un parametro: il valore di un parametro può essere esso stesso una credenziale, e il plugin associato qui può essere codice che il workspace non ha scritto. Ciò che porta ogni documento è descritto in Cosa riceve un plugin di linter.

Codifica di trasmissione. L’input e l’output viaggiano entrambi come CBOR canonico (RFC 8949 §4.2.1). Un guest decodifica il proprio input e codifica il proprio output tramite i punti di ingresso che LinterInput e LinterOutput del suo kit già portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, decodeCBORLinterInput e encodeCBORLinterOutput in TypeScript — leggendo e scrivendo byte (Vec<u8> in Rust, Host.inputBytes() e Host.outputBytes(...) in TypeScript). Non serve alcuna libreria CBOR e nulla analizza i byte a mano. I documenti delle entità — proposed, previous, implemented_component e release — e ogni valore di components viaggiano come i byte dei loro documenti JSON, quindi un guest li analizza come JSON per guardarvi dentro. components è una mappa che lo schema marca come mappa che preserva l’ordine, quindi nell’input di una regola che legge un’intera Release viaggia come un elenco ordinato di voci nell’ordine in cui l’Aggregate dichiara le sue istanze di componente, e un guest lo legge tramite il contenitore che mantiene l’ordine del suo kit. policies viaggia come una mappa che contiene solo i flag impostati, quindi un flag che non contiene si legge come falso, e ogni rilievo viaggia nella forma condivisa Diagnostic. Una risposta che non è un LinterOutput in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — fa fallire il lint, nominando l’export chiamato, anziché essere letta come un’esecuzione che non ha trovato nulla. Chiamato direttamente con aggrega plugin run-local --export lint_rules, un linter riceve il payload JSON scritto dall’autore convertito in questa codifica, e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Stato attuale: disponibile. Il publishing-linter viene distribuito ed eseguito tramite l’host attraverso aggrega lint.

Il socket del parser — output di albero canonico

Un parser trasforma una sorgente scritta in un formato che il compilatore non legge nativamente in un albero strutturato canonico, così un consumatore legge l’albero invece di portare con sé un parser proprio. L’host risolve il parser che annuncia il formato richiesto come parse:<format> e chiama il suo export parse in tre punti: quando a una policy di render-verdict viene consegnato un artefatto renderizzato in un formato che non legge nativamente, quando un importatore chiede all’host un albero tramite aggrega_parse_source, e quando viene riconosciuta un’importazione che non nomina alcun formato (vedi il socket importatore più sotto). Un guest non chiama mai un parser direttamente.

Forma dell’input (host → guest). Un documento ParseInput che contiene:

  • format — il formato richiesto, una delle capacità parse:<format> del parser senza il suo prefisso.
  • bytes — i byte della sorgente.
  • options — un documento di opzioni che il consumatore fornisce per un comportamento specifico del parser, trasmesso così com’è. Assente quando il consumatore non ne fornisce.

Forma dell’output (guest → host). Un documento ParseOutput che contiene il tree — la sorgente analizzata come documento JSON, il cui livello superiore può essere un oggetto, un array o uno scalare — eventuali diagnostiche nella forma condivisa Diagnostic, intervalli di sorgente opzionali che localizzano i nodi dell’albero nei byte originali, e un error di fallimento quando il parsing non è riuscito a completarsi. Ogni campo e i suoi vincoli si trovano nel riferimento dello schema del socket del parser generato.

Codifica di trasmissione. L’input e l’output viaggiano entrambi come CBOR canonico (RFC 8949 §4.2.1), la codifica in cui viaggia lo stesso ParseInput quando un guest lo consegna ad aggrega_parse_source. Un guest decodifica il proprio input e codifica il proprio output tramite i punti di ingresso che ParseInput e ParseOutput del suo kit già portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, decodeCBORParseInput e encodeCBORParseOutput in TypeScript — leggendo e scrivendo byte (Vec<u8> in Rust, Host.inputBytes() e Host.outputBytes(...) in TypeScript). Non serve alcuna libreria CBOR e nulla analizza i byte a mano. I byte della sorgente viaggiano come una sequenza di byte grezzi, e il decodificatore generato li inserisce nel tipo di campo proprio del kit: una slice di byte in Go, una stringa base64 in Rust e TypeScript. options e tree viaggiano come i byte dei loro documenti JSON, così l’albero che un parser scrive raggiunge il suo consumatore alla lettera. Un parser che non riesce a completare dice perché nell’error dell’output, e il parsing fallisce nominando il parser e quel messaggio; una risposta che non è un ParseOutput in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — fa fallire anch’essa il parsing, nominando il parser e il suo export parse. Un parsing fallito arresta una build nel ruolo render-verdict, e raggiunge un importatore come il fallimento con cui risponde aggrega_parse_source. Lo stesso vale per una sorgente che il parser rifiuta — una a cui risponde con una diagnostica halt accanto al suo albero: la chiamata dell’importatore fallisce con il messaggio di ciascuna di tali diagnostiche, nell’ordine del parser, e non riceve mai l’albero. Chiamato direttamente con aggrega plugin run-local --export parse, un parser riceve il payload JSON scritto dall’autore convertito in questa codifica — la sorgente scritta in quel payload come base64, come JSON scrive qualsiasi campo di byte — e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Definizioni dei tipi. I tipi di dati trasmessi del parser — ParseInput, ParseOutput, NodeSpan e SourceSpan — sono pubblicati in tutti e tre i pacchetti ABI e riesportati dal kit di sviluppo di plugin di ciascun linguaggio, generati da un unico codec in modo che i tre restino allineati. L’esempio parse di ciascun kit legge il proprio input e scrive il proprio output in questo modo, e così fanno i parser per HCL, TOML, YAML, JSON e JSON con commenti distribuiti all’interno del binario.

Stato attuale: disponibile — smistato nel ruolo render-verdict per un artefatto in un formato che la policy non legge nativamente, tramite aggrega_parse_source per un importatore, e per riconoscere il formato di un’importazione che non ne nomina alcuno.

Il socket dell’importatore — output di authoring in bozza

Un importatore trasforma una sorgente scritta per un altro strumento — ad esempio un flusso esportato da un costruttore di agenti — in file di authoring Aggrega in bozza. Viene eseguito fuori banda: aggrega import, il metodo aggrega/import della sessione dell’editor e lo strumento import rivolto all’assistente risolvono l’importatore che annuncia il formato richiesto come import:<format> e chiamano il suo export import una volta per importazione. Una build non lo smista mai. Quale importatore viene eseguito, e che cosa gli consegna un operatore, è descritto in Quale importer trasforma una sorgente in bozze. Gli importatori propri del compilatore, uno per ciascun formato che legge, sono descritti in Importatori core: quali sono quei formati, che cosa legge ciascuno, che cosa genera in bozza, le impostazioni che accetta, la loro pubblicazione a ogni release del compilatore, e come un’importazione ne scarica e verifica uno che la macchina non contiene ancora.

Forma dell’input (host → guest). Un documento ImportInput che contiene:

  • format — il formato richiesto dall’importazione, una delle capacità import:<format> dell’importatore senza il suo prefisso.
  • bytes — i byte della sorgente: l’intero file per un’importazione di un file, e vuoto per un’importazione di una directory, i cui file arrivano sotto sources.
  • name — il nome della sorgente, senza alcuna directory davanti, così l’importatore può nominare la sorgente in ciò che riporta e in ciò che genera in bozza: per un’importazione di un file, il nome base del file da cui è stato letto bytes; per un’importazione di una directory, il nome base della directory stessa, letto dal suo percorso completo, così aggrega import . consegna il nome della directory in cui viene eseguito, mentre i file della directory arrivano comunque ciascuno sotto il proprio nome. Assente dove la sorgente non ha alcun nome da dare.
  • sources — le sorgenti nominate, ciascuna con il proprio nome e i propri byte, in un’unica lista ordinata per nome: per un’importazione di una directory, ogni suo file selezionato dai pattern di file dichiarati dall’importatore, esclusa la cartella di output della build del workspace, nominato con il suo percorso separato da barre all’interno della directory; e i file che la voce plugins.importer che associa questo importatore dichiara sotto with.sources, ciascuno sotto il proprio nome base. Un file della directory e un file di with.sources con lo stesso nome fanno rifiutare l’importazione, anziché lasciare che l’uno nasconda l’altro. Assente dove non ce ne sono.
  • settings — l’oggetto di impostazioni che quella voce dichiara sotto with.settings, come documento JSON con le chiavi ordinate, trasmesso così com’è. Assente quando nessuna voce associa l’importatore o la voce non ne dichiara.
  • catalog — una vista dei Components che il catalogo proprio del workspace contiene: il catalogo da cui l’importatore stesso è stato selezionato — le cartelle del catalogo del workspace o, dove non ne nomina alcuna, lo snapshot del catalogo che il suo registry predefinito pubblica, conservato su questa macchina — senza che nulla venga scaricato per la vista stessa. La sua lista components contiene una voce per ogni nome di Component, ordinata per nome; dove il catalogo contiene più versioni di un Component, la voce descrive la versione a cui si risolve un riferimento che lo nomina senza versione. Ogni voce porta il name e la version del Component, le sue labels, i nomi delle chiavi di primo livello che i suoi values e provides dichiarano (values e provides, ciascuno ordinato), e i suoi sockets — ciascuno con il name del socket e il selector di etichette che una dipendenza collegata tramite esso deve soddisfare — nell’ordine in cui il Component li dichiara. Un Component che ne estende un altro porta ciò che eredita oltre a ciò che dichiara, e i socket che eredita vengono per primi. La vista contiene solo nomi, versioni, etichette e selettori — mai un valore, un valore predefinito o un segreto — e il suo ordine è fisso, quindi un catalogo produce una sola sequenza di byte. Assente quando il catalogo non contiene alcun Component.

Forma dell’output (guest → host). Un documento ImportOutput che contiene le entità prodotte dall’importazione — ciascuna un riferimento a un’entità di catalogo esistente o un corpo generato in bozza — le decisioni di mappatura che le sottendono, eventuali diagnostiche nella forma condivisa Diagnostic, i file di scaffold da scrivere, e un error di fallimento quando l’importazione non è riuscita a completarsi. Ogni campo e i suoi vincoli si trovano nel riferimento dello schema del socket dell’importatore generato.

Codifica di trasmissione. L’input e l’output viaggiano entrambi come CBOR canonico (RFC 8949 §4.2.1). Un guest decodifica il proprio input e codifica il proprio output tramite i punti di ingresso che ImportInput e ImportOutput del suo kit già portano — DecodeCBOR e EncodeCBOR in Go, decode_cbor e encode_cbor in Rust, decodeCBORImportInput e encodeCBORImportOutput in TypeScript — leggendo e scrivendo byte (Vec<u8> in Rust, Host.inputBytes() e Host.outputBytes(...) in TypeScript). Non serve alcuna libreria CBOR e nulla analizza i byte a mano. settings viaggia all’interno del documento binario come i byte del suo documento JSON, quindi un guest lo analizza come JSON per guardarvi dentro, come su ogni altro socket. Un importatore che non riesce a completare dice perché nell’error dell’output, e l’importazione si arresta nominando l’importatore e quel messaggio; una risposta che non è un ImportOutput in questa codifica — una scritta come JSON, o una che porta un campo di primo livello che la forma non dichiara — arresta anch’essa l’importazione, nominando l’importatore e il suo export import. Chiamato direttamente con aggrega plugin run-local --export import, un importatore riceve il payload JSON scritto dall’autore convertito in questa codifica, e la sua risposta viene letta come la forma di output dell’export e stampata come JSON — una risposta che non ha quella forma viene rifiutata, nominando l’export, come la rifiuta una build.

Come viene riconosciuta una sorgente del tuo formato. Un’importazione può non nominare alcun formato, e l’host allora ne riconosce uno da ciò che dichiarano gli importatori, senza conoscere di per sé alcun formato. Un importatore dichiara nella sua autodescrizione describe(), sotto importer (un ImporterContract), una lista detect delle firme da cui viene riconosciuta una sorgente dei suoi formati. Ogni DetectSignature nomina:

  • syntax — il formato sintattico in cui viene analizzata la sorgente, un formato che un plugin di parser annuncia come parse:<syntax>, ad esempio json o yaml;
  • files — pattern opzionali di nomi di file confrontati con la parte finale del nome della sorgente: un segmento con il nome proprio del file, più segmenti separati da barre con altrettanti segmenti finali del suo percorso, con *, ? e [...] che trovano corrispondenza all’interno di un segmento. Una firma che non ne dichiara si applica a una sorgente che è un solo file, comunque si chiami, e a nessun file di una directory;
  • match — i predicati che l’albero analizzato deve soddisfare tutti, ciascuno un PathMatch con un path di chiavi unite da punti a partire dalla cima dell’albero (un segmento numerico intero seleziona una posizione di array), un is tra present, absent, object, array, string, number o boolean, e facoltativamente una stringa equals o una stringa prefix — al massimo una delle due.

Quando un’importazione non nomina alcun formato, l’host confronta le firme di ogni importatore tra cui l’importazione sceglie — quelli nel catalogo del workspace e gli importatori core del compilatore — in ordine di identità e versione: analizza la sorgente tramite il parser che il catalogo serve per una sintassi — oppure, per una sintassi per cui il catalogo non serve alcun parser, quello che il compilatore stesso porta con sé — al massimo una volta per sintassi, valuta i predicati sull’albero, e legge la sorgente come il formato dell’unico importatore la cui firma corrisponde. È anche il parser tramite cui riceve risposta la chiamata aggrega_parse_source di un importatore, quindi un importatore legge la propria sorgente tramite il parser con cui è stata riconosciuta. Una sorgente che non si analizza in una sintassi non corrisponde ad alcuna firma che la nomina; una sintassi per cui né il catalogo né il compilatore servono un parser arresta il riconoscimento, nominando l’assenza del parser. Una sorgente a cui non corrisponde alcuna firma viene rifiutata chiedendo il formato, e una riconosciuta come più di un formato viene rifiutata nominandoli. Una firma riconosce una sorgente come ogni formato che il suo importatore annuncia, quindi un importatore le cui sorgenti devono essere riconosciute serve un solo formato, e uno che non dichiara alcuna firma è raggiungibile solo nominandone il formato.

L’entità Plugin dell’importatore registra la stessa lista come spec.importer.detect, derivata da describe() quando l’entità viene generata dal guest; il riconoscimento legge quella registrazione, quindi il guest non viene caricato finché il suo formato non è stabilito. Il caricamento e la pubblicazione del guest rifiutano uno la cui autodescrizione differisce dalla registrazione della sua entità, nominando importer.detect, e un’entità che non ne registra alcuna non dichiara nulla. Il descrittore viene rifiutato al caricamento dove il contratto è dichiarato su un plugin che non è un importatore, dove una firma non nomina alcuna sintassi o nomina un pattern di file malformato, e dove un predicato non nomina alcun percorso, nomina un is al di fuori dei sette, oppure nomina sia equals sia prefix.

Gli importatori core del compilatore e l’esempio import del kit Go dichiarano le proprie in questo modo. L’importatore Langflow legge una sorgente come JSON e chiede un array in data.nodes; l’importatore Flowise chiede array in nodes e edges e nulla in data.nodes; l’importatore n8n chiede un array in nodes, un oggetto in connections e nulla in edges né in data.nodes; l’importatore MCP dichiara una firma per ogni configurazione di client, che ne nomina il file — .mcp.json, claude_desktop_config.json e .cursor/mcp.json, letti come JSON con un oggetto in mcpServers, e .vscode/mcp.json, letto come JSON con commenti, come lo legge Visual Studio Code, con un oggetto in servers — e una che non nomina alcun file e chiede una stringa $schema che inizia con https://static.modelcontextprotocol.io/schemas/; l’importatore Compose legge una sorgente come YAML, nomina i file che Compose legge per impostazione predefinita — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml e i loro quattro file di sovrascrittura — e chiede un oggetto in services; l’importatore Dify legge una sorgente come YAML, non nomina alcun file, e chiede la stringa app in kind e qualcosa in app.mode e in version; l’importatore CrewAI nomina config/agents.yaml e config/tasks.yaml, letti come YAML senza chiedere nulla all’albero, crew.jsonc e crew.json, letti come JSON con commenti con una lista in agents, e agents/*.jsonc e agents/*.json, letti come JSON con commenti con qualcosa in role, così che nessuna coppia di essi corrisponda a una stessa sorgente, e un file importato da solo senza nominare alcun formato viene letto come YAML oltre che come JSON; l’importatore LangGraph nomina langgraph.json, letto come JSON con un oggetto in graphs, dichiara una firma che non nomina alcun file e chiede un oggetto in graphs e la stringa https://langgra.ph/schema.json in $schema, e non nomina alcun file di ambiente, poiché il riconoscimento legge ogni file selezionato dai pattern di qualsiasi importatore, quindi un pattern che ne nominasse uno aprirebbe i file di ambiente di ogni directory importata senza nominare alcun formato; l’importatore Google ADK nomina root_agent.yaml, letto come YAML con qualcosa in name e in instruction, oppure una stringa in agent_class e qualcosa in name, e non nomina altri file, poiché la configurazione di un sotto-agente può chiamarsi in qualsiasi modo e un pattern che nominasse ogni file YAML aprirebbe ciascuno di essi in ogni directory importata senza nominare alcun formato; l’importatore Agent Framework legge una sorgente come YAML, non nomina alcun file, e chiede la stringa Prompt in kind e un oggetto in model; l’esempio import del kit Go legge una sorgente come YAML e chiede la stringa DemoSource in kind. In Go:

Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{
Syntax: "json",
Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},
}}},

Che cosa legge un’importazione di una directory. Una sorgente può essere una directory, e i pattern di file dichiarati dall’importatore decidono che cosa legge: l’host legge esattamente i file della directory, a qualsiasi profondità, selezionati da uno dei pattern files delle firme dell’importatore — ciascuno confrontato con la parte finale del percorso del file separato da barre all’interno della directory — e li consegna come sources in ordine di nome, con bytes vuoto e il nome della directory stessa come name. Nessun altro file della directory viene aperto. La cartella in cui una build del workspace scrive i suoi file renderizzati — dist/ sotto la radice del workspace — non viene letta come parte di una directory che la contiene: nessuno dei suoi file viene consegnato o riconosciuto, e un link che vi conduce viene saltato, quindi una directory già sottoposta a build viene letta come il progetto che contiene, mentre una directory che è quella cartella, o si trova al suo interno, viene letta così come indicata. Una firma che non dichiara alcun pattern files non seleziona alcun file di una directory, quindi un importatore che non ne dichiara legge un solo file e rifiuta una directory, e anche una directory che non contiene alcun file selezionato dai suoi pattern viene rifiutata. La directory resta confinata a sé stessa: un link tra i file che leggerebbe, o verso una directory, che porta fuori dalla directory viene rifiutato prima che venga letto qualsiasi cosa, un link a una directory non viene mai attraversato, e un link a un file che nessun pattern seleziona viene saltato senza essere letto. Il riconoscimento del formato di una directory segue la stessa regola — ogni firma viene provata sui file selezionati dai suoi pattern, in ordine di nome, ogni file letto e analizzato al massimo una volta per sintassi, e una firma che non dichiara alcun pattern non si applica ad alcuno di essi. L’host non pone alcun limite: una directory troppo grande per l’importatore viene rifiutata dai limiti di runtime propri dell’importatore. Nessuno degli importatori Langflow, Flowise, n8n, Dify e Agent Framework del compilatore dichiara pattern files, quindi ciascuno legge un solo file; il suo importatore MCP dichiara i nomi delle quattro configurazioni di client, quindi legge ciascuna di esse che una directory contiene; il suo importatore Compose dichiara gli otto nomi di file Compose, quindi riceve ogni file Compose che una directory contiene e unisce quelli che Compose leggerebbe; e il suo importatore CrewAI dichiara i sei nomi con cui sono scritte le dichiarazioni di un progetto CrewAI, quindi riceve le dichiarazioni di un progetto e nulla del suo programma; e il suo importatore LangGraph dichiara langgraph.json, quindi riceve la configurazione di un’applicazione e nulla del suo codice né dei suoi file di ambiente, e un file di ambiente lo raggiunge solo sotto il with.sources della sua associazione; e il suo importatore Google ADK dichiara root_agent.yaml, quindi riceve la configurazione dell’agente radice di un’applicazione e nulla del suo codice né del suo file di ambiente, e le configurazioni nominate dai suoi sotto-agenti lo raggiungono solo sotto il with.sources della sua associazione.

Definizioni dei tipi. I tipi di dati trasmessi dell’importatore — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput e le forme di entità, decisione e scaffold che porta — sono pubblicati in tutti e tre i pacchetti ABI e riesportati dal kit di sviluppo di plugin di ciascun linguaggio, generati da un unico codec in modo che i tre restino allineati, e così anche i tipi di riconoscimento ImporterContract, DetectSignature e PathMatch che l’autodescrizione describe porta. Il package importer del kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, porta tutto ciò che un importatore fa qualunque sia il suo formato, e gli importatori core del compilatore, tutti costruiti su di esso, leggono il proprio input e scrivono il proprio output in questo modo.

Rispetto a che cosa valuta un importatore costruito sul kit Go. Il valutatore del kit pesa ogni nodo della sorgente rispetto ai Components della vista catalog e a nient’altro: i candidati sono il catalogo proprio del workspace — i Components di un catalogo aziendale esattamente come quelli della libreria standard — e il kit non porta alcun candidato proprio. Di ogni Component legge il nome, la categoria che porta la sua etichetta component.aggrega.ai/category, le sue etichette e i nomi delle chiavi che i suoi values dichiarano; le sue chiavi provides e i suoi socket non vengono pesati. Un Component aggiunto al catalogo è un candidato alla successiva importazione, senza ricompilare alcun importatore. Dove la vista è assente, perché il catalogo non contiene alcun Component, nessun nodo ha un candidato: nessuno viene referenziato o suggerito, e ogni nodo a cui la bozza dà un Component proprio viene generato in bozza. Ogni importatore che valuta tramite il kit valuta in questo modo — tra cui gli importatori Langflow, Flowise, n8n e Compose del compilatore, mentre il suo importatore MCP non pesa alcun candidato; un importatore che non usa il kit legge la vista come preferisce.

Per che cosa un importatore costruito sul kit Go legge i socket di una piattaforma. I socket non hanno alcun peso in un punteggio, ma il kit li legge per disporre una bozza. Un formato i cui flussi una piattaforma esegue così come sono scritti — come fanno quelli di Langflow, Flowise e n8n — viene generato in bozza per impostazione predefinita come un’unica istanza del Component di quella piattaforma che porta il flusso, e ogni parte del flusso viene collegata al primo socket, nell’ordine in cui la voce catalog della piattaforma elenca i suoi sockets, il cui selector è soddisfatto dalle etichette del Component della parte, così come la vista porta quelle etichette. Vengono letti solo il selettore e le etichette, e il selettore viene confrontato da una funzione che l’importatore fornisce, poiché il kit non porta alcuna grammatica di selettori propria; dove la vista non contiene alcun Component con il nome della piattaforma, nessuna parte viene collegata. Importatori core descrive la bozza che gli importatori Langflow, Flowise e n8n del compilatore costruiscono in questo modo, e l’impostazione layout che invece genera in bozza ogni nodo come un Component proprio.

Stato attuale: disponibile — smistato da aggrega import e dalla stessa operazione sulla sessione dell’editor e sullo strumento rivolto all’assistente.

Criterio di collocazione: il socket del linter rispetto ai ruoli di verdetto della governance

Due dei socket documentati condividono una superficie simile — entrambi emettono risultati per regola — ma differiscono per collocazione nella pipeline e per semantica di blocco. Il criterio per decidere quale socket ospita un determinato controllo:

  • I ruoli di verdetto della governance (in banda, che arrestano la build). Riservati alle policy che arrestano la build: un verdetto halt ferma la pipeline di compilazione e la build non produce artefatti. I casi d’uso sono le policy la cui violazione rende l’output non sicuro da applicare: punti di controllo di conformità (collocazione dei confini PCI / SOC2), invarianti di topologia (ingress zero-trust, autenticazione tra confini diversi), forma del flusso delle credenziali (nessun secret in chiaro nell’IR), ecc. Una policy ragiona sul grafo IR (ir-verdict, prima del rendering) o sugli artefatti renderizzati (render-verdict, dopo il rendering).
  • Il socket del linter (fuori banda, CI / IDE, consultivo). Riservato ai controlli di best practice e di rilevabilità: regole la cui violazione è sospetta ma non pericolosa — secret orfani, parametri inutilizzati, vocabolario di etichette deprecato, completezza dei tag per l’attribuzione dei costi, deriva dalle convenzioni di denominazione. Un fallimento produce un output consultivo; la build produce comunque gli artefatti.

Il criterio di collocazione formulato come un’unica regola: se il controllo deve arrestare la build, appartiene a un ruolo di verdetto della governance; se il controllo deve avvisare un autore o un revisore senza bloccare la pipeline, appartiene al socket del linter.

Entrambi sono utilizzabili oggi. Il socket del linter esegue il publishing-linter tramite aggrega lint; i ruoli di verdetto della governance vengono invocati in banda durante aggrega build quando un workspace associa un plugin con ruolo di verdetto. Nota che un ruolo di verdetto ha le proprie severità — una policy può essa stessa emettere verdetti warn e info che avvisano senza arrestare — quindi la linea tra arresto e avviso tracciata sopra è l’indicazione di collocazione per controlli interi, non l’affermazione che una policy possa soltanto arrestare. Vedi la pagina del socket di governance per il modello di severità.

Riferimenti incrociati

  • policy-socket.md — la trattazione completa del socket di governance: i quattro ruoli, le severità dei verdetti, il canale di input dell’operatore, la scrittura di una policy per uno dei due motori inclusi nel compilatore, l’incapsulamento di un motore di policy esterno e i guest di riferimento.
  • core-importers.md — gli importatori propri del compilatore, uno per ogni formato che legge: che cosa legge ciascuno, le loro impostazioni e la loro pubblicazione a ogni release del compilatore.
  • 10-status.md#compilation-pipeline-phases — classificazione della pipeline dei plugin nella pagina di stato (prontezza a runtime della pipeline dei plugin Wasm).
  • architecture/04-entity-taxonomy.md §«Domain 3: Infrastructure Base (Dominio 3: base dell’infrastruttura)» — principio del Plugin in due parti per le FeatureRecipes delle credenziali (pattern Fetcher + Injector).
  • architecture/13-catalog-and-registry.md — la tassonomia OCI che inizia con il segmento del provider.
  • entities/featurerecipe.md — la superficie di authoring pipeline: della FeatureRecipe.
  • when-to-use-a-pipeline-step.md — guida alla decisione: un passo di pipeline o una FeatureRecipe basata su template.
  • templates/expansion-matrix.md — le regole di valutazione dei template del blocco pipeline: with: della pipeline dei plugin e la semantica di accesso a .steps.
  • examples/04-secrets.md — la forma di pipeline Fetcher + Injector che una FeatureRecipe per le credenziali può assumere.
  • errors/error-translation.md — la disciplina di traduzione degli errori a cui partecipano i guest dei plugin.