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

Contratti sociali

Aggrega è, per progettazione, un compilatore privo di opinioni. Secondo gli invarianti fondanti documentati in architecture/05-invariants.md, il compilatore analizza YAML, attraversa grafi, valuta intersezioni di etichette e convoglia stringhe tra componenti — ma non sorveglia ciò che gli sviluppatori mettono in values, parameters, infra, provides o locals; non impone convenzioni di denominazione, convenzioni sulle porte né le etichette semantiche che un Architetto inventa; non indovina lo scopo di un componente dai nomi. Molte discipline che sembrano regole del compilatore sono in realtà contratti sociali: best practice sostenute da una convenzione di authoring anziché da uno schema o da un’imposizione a runtime.

Dove si ferma questa neutralità merita di essere detto chiaramente, perché è una sola linea ed è facile sovrainterpretarla. Alcune chiavi sono proprie di Aggrega — riservate, con i valori che accettano scritti nello schema pubblicato — e quelle lo schema le controlla davvero, nello stesso modo in cui controlla qualsiasi altro campo dichiarato. Dichiarare l’insieme dei valori di una chiave che la piattaforma stessa definisce non significa che il compilatore legga un significato in ciò che hai scritto; è la piattaforma che dice che cosa significa la propria chiave. Tutto ciò che scrivi sotto una chiave tua resta esattamente non sorvegliato quanto descrive questa pagina.

Questa pagina è l’inventario canonico dei contratti sociali del linguaggio. Gli autori che imparano i contratti da questa pagina possono capire perché il compilatore accetta una build malformata secondo una convenzione (la accetta — il compilatore non interpreta la convenzione) e dove ricade la responsabilità di individuare la violazione (disciplina di authoring, attenzione dei revisori o un plugin linter eseguito da aggrega lint).

Tre classi di disciplina

Le discipline di Aggrega si dividono in tre classi in base a come la disciplina viene imposta. La classificazione è importante perché ogni classe ha una diversa modalità di errore quando la disciplina viene violata.

Imposta dallo schema

La disciplina è imposta dalla validazione JSON Schema 2020-12 al momento del caricamento (il JSON Schema dell’involucro dell’entità, più le dichiarazioni schema: a livello di pilastro sulle entità Component e Feature). Una violazione produce un arresto fatale prima che la build proceda; il compilatore si rifiuta di continuare. Gli autori che tentano di violare una disciplina imposta dallo schema vedono un errore di validazione esplicito che indica il campo e il vincolo.

Esempi: i campi obbligatori dell’involucro dell’entità (apiVersion / kind / metadata.name / metadata.version); la regex SemVer su metadata.version; l’insieme chiuso di valori dell’etichetta riservata component.aggrega.ai/type; il divieto meccanico dei blocchi values: nello schema della Release (secondo l’Invariante 5); il rifiuto di extends insieme ad aggregate sulla Release (l’invariante della fonte unica di verità); le regole di forma della Recipe che impongono il contratto di composizione dei tipi di input.

Le discipline imposte dallo schema sono le garanzie più forti che il linguaggio offre. Il compilatore si rifiuta di eseguire il rendering di qualunque cosa le violi.

Imposta da un plugin di policy

La disciplina è imposta da un plugin Wasm eseguito in uno dei punti socket documentati (il ruolo di governance label-transform durante la costruzione della topologia; il ruolo di governance ir-verdict durante l’analisi statica; il socket linter fuori banda). Una violazione produce un errore di policy che arresta la build (socket in banda) oppure un avviso consultivo (socket fuori banda), a seconda della semantica di gating del socket.

Una disciplina è imposta in questo modo solo dove viene eseguito un plugin che la verifica: il runtime Wasm invoca i plugin nei punti socket documentati, e una disciplina che nessun plugin verifica resta una convenzione. Il linter di pubblicazione, che aggrega lint esegue, verifica parte di una convenzione di questa pagina — vedi Convenzioni verificate da una regola del linter. Nessuna regola del linter di pubblicazione verifica l’ermeticità (la FuncMap di Sprig espone helper che rompono il determinismo dell’output, secondo l’avvertenza sul determinismo in templates/sprig-functions.md) né la denominazione delle risorse cloud (le Recipes i cui output di valuesMapping: fanno riferimento a campi di nomi di risorse cloud senza interpolazione di release_name / instance_id, secondo entities/recipe.md «Cloud-resource naming discipline (Disciplina di denominazione delle risorse cloud)»); un plugin linter tuo può verificare l’una o l’altra.

Per la superficie del contratto dei plugin Wasm e il criterio di collocazione (il socket linter rispetto ai ruoli di verdetto di governance), vedi plugins/plugin-contract.md.

Mantenuta per convenzione

La disciplina è mantenuta soltanto dalla disciplina di authoring più l’attenzione dei revisori. Il compilatore non la impone; nessuno schema rifiuta la violazione; nessun plugin Wasm la segnala. Gli autori imparano la disciplina dalla documentazione, la seguono perché la forma architetturale dipende da essa e si affidano alla revisione delle PR per individuare le sviste. Una violazione non produce alcun segnale in fase di compilazione — la build riesce, l’output renderizzato funziona per quanto ne sa il compilatore, e la violazione della disciplina emerge solo quando gli strumenti a valle o il comportamento a runtime dipendono dalla convenzione.

Le discipline mantenute per convenzione sono l’elenco portante che gli autori devono imparare dalla documentazione. Il compilatore non le interpreta; sbagliarle non rompe la build, ma rompe la forma architetturale da cui Aggrega dipende. La maggior parte di questa pagina le documenta.

Le convenzioni

I seguenti contratti sociali sono mantenuti per convenzione. Ogni voce indica la disciplina, la superficie in cui la convenzione è documentata e la modalità di errore in caso di violazione. Ognuno conserva il proprio numero ovunque si trovi: il contratto 3, la disciplina dei prefissi riservati, è verificato da una regola del linter per le chiavi delle annotazioni ed è descritto in Convenzioni verificate da una regola del linter.

1. Scegliere il tipo operativo adatto al componente

L’etichetta riservata component.aggrega.ai/type indica che tipo di cosa è un componente, attingendo a un insieme chiuso di primitive cloud universali: server, worker, task, function, stateful-server, resource. L’appartenenza a quell’insieme è imposta dallo schema, non mantenuta per convenzione. Aggrega definisce questa chiave e i valori che accetta, lo schema del Component li enumera, e un documento che riporta qualsiasi altro valore viene rifiutato al caricamento — E0215, la condizione entity-envelope-invalid, nomina l’etichetta ed elenca i valori che accetta. Quel rifiuto è ciò che questa voce non copre.

Ciò che resta convenzione è quale dei valori si adatta al componente che hai davanti. Nulla verifica che un database relazionale sia etichettato stateful-server anziché server, o che un consumatore di una coda sia worker anziché task; il selettore valuta qualunque valore trovi senza attribuirgli un significato. L’Architetto che scrive un Component sceglie il valore che descrive come l’infrastruttura deve trattarlo, e i selettori a valle, i plugin di policy e i plugin di rendering Wasm si affidano tutti all’onestà di quella scelta.

Classificare su un asse proprio. L’insieme chiuso governa questa sola chiave riservata e nient’altro. Un catalogo che ha bisogno di una classificazione che Aggrega non definisce — un livello, una zona dati, una classe di servizio o una suddivisione più fine delle primitive operative — aggiunge una propria chiave di etichetta accanto a quella riservata. Lo schema del Component accetta qualsiasi ulteriore chiave di etichetta con un valore stringa, e lo stesso meccanismo dei selettori la legge, quindi acme.aggrega.ai/storage-tier: oltp sta accanto a component.aggrega.ai/type: stateful-server e l’appliesTo di una Feature o il selector di un socket possono puntare all’una o all’altra. L’estensione avviene su una chiave tua, mai su un valore all’interno di quella di Aggrega.

Documentato in: architecture/02-ecosystem-philosophy.md (l’ontologia operativa) + labels-and-annotations.md (disciplina dei prefissi) + errors/sentinels.md (E0215).

Modalità di errore: Un valore dell’insieme che non si adatta al componente fuorvia tutto ciò che legge l’etichetta. Un datastore etichettato server viene rifiutato da una Feature o da un socket che seleziona stateful-server — un arresto che nomina il selettore, non l’etichetta errata — e un plugin di policy o un plugin di rendering che legge l’etichetta lo tratta come calcolo stateless. Dove solo tali lettori lo vedono, la build riesce; l’errore emerge solo quando gli artefatti renderizzati raggiungono il cluster.

2. Separazione di .context.annotations.* in tre contenitori

Le annotazioni propagate in cascata finiscono in tre contenitori con nome — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — ognuno con un intento diverso. L’obiettivo della disciplina: release è «dove viene eseguito questo componente, governato da Ops»; catalog è «che cos’è questo componente, scritto dall’Architetto»; aggregate è «che cosa fa questo componente, scritto dallo Sviluppatore».

Il compilatore non impone i confini tra i contenitori. I tre contenitori condividono una forma piatta string → string; il template di una Recipe può leggerli tutti e tre, e nulla impedisce che un’annotazione del confine della Release venga interpretata come metadati cognitivi o che un’annotazione del catalogo venga instradata in infra:. La separazione è mantenuta dagli autori che scrivono le annotazioni nel contenitore giusto e dai revisori che individuano le fughe tra contenitori.

Documentato in: labels-and-annotations.md (la separazione in tre contenitori è un contratto sociale).

Modalità di errore: La logica di instradamento che dipende dalla distinzione di intento tra i contenitori (ad es. una Recipe che instrada .context.annotations.release.aggrega.ai/region in un campo region di Terraform) consuma silenziosamente qualunque annotazione compaia nel contenitore, indipendentemente dall’intento di authoring. La build riesce; l’output renderizzato può contenere valori semanticamente errati.

4. Autocontenimento di provides: della Recipe

I template provides: della Recipe si chiudono solo sui dati del nodo stesso — .values, .infra, .context.instance_id, .context.rendered_name dove il provider del nodo ne riporta uno, i .locals risolti del nodo, più stringhe statiche. I riferimenti a .context.inject e .context.uses sono vietati perché la valutazione dei provides esegue quei template in qualsiasi ordine; leggere dati di altri nodi la vincolerebbe all’ordine di iterazione topologica, che il design evita deliberatamente. .locals fa parte della superficie anziché esserne escluso: i locals del nodo si risolvono nel preambolo della stessa fase, prima dei suoi provides, e sono locali al nodo, quindi leggerli non costa nulla in termini di ordinamento. Nominare una chiave che il blocco locals non dichiara provoca un arresto.

Questa è una regola in due metà, ognuna delle quali indica dove viene verificata. Il compilatore verifica la prima: la valutazione dei provides verifica ogni template rispetto a una allowlist positiva delle radici definite dal suo contesto prima che il template venga eseguito, quindi una lettura di .context.inject / .context.uses si arresta con un errore esplicito invece di produrre un rendering vuoto; la regola è documentata anche in templates/expansion-matrix.md, riga 6. La convenzione mantiene la seconda: il pattern più ampio (provides-is-public; locals-is-private) è ancorato alla convenzione.

Documentato in: templates/expansion-matrix.md riga 6 + vocabulary/data-pillars.md «provides: and locals: — public face vs private face (provides: e locals: — volto pubblico e volto privato)».

Modalità di errore: il compilatore rileva i riferimenti vietati e arresta la build al momento della valutazione dei template quando compaiono direttamente in provides:. La disciplina più ampia pubblico-contro-privato (non esporre lo stato interno attraverso le chiavi di provides:) è affidata solo alla convenzione — gli autori che trattano provides: come uno spazio dei nomi interno alla Recipe producono contratti da cui i chiamanti dipendono; il refactoring diventa una modifica incompatibile.

5. Determinismo — helper non ermetici nei template del percorso di rendering

L’invariante dell’output deterministico di Aggrega (Invariante 8 in architecture/05-invariants.md) richiede un output identico byte per byte per un input identico byte per byte. La FuncMap completa di Sprig espone helper che leggono lo stato dell’ambiente (lettori dell’orologio now / date; generatori casuali randAlpha / uuidv4; lettori delle variabili d’ambiente env / expandenv; resolver di rete getHostByName). Gli autori che invocano questi helper da un template che contribuisce all’output renderizzato rompono il contratto di determinismo.

Il compilatore non rileva né blocca l’uso di helper non ermetici. La FuncMap di Sprig li espone secondo templates/sprig-functions.md «Determinism caveat (Avvertenza sul determinismo)»; la disciplina è mantenuta dagli autori che evitano questi helper nei template del percorso di rendering e dai revisori che ne individuano l’uso nella revisione delle PR.

Documentato in: templates/sprig-functions.md «Determinism caveat (Avvertenza sul determinismo)».

Modalità di errore: L’output della build differisce tra esecuzioni dello stesso input. La discrepanza emerge al momento del diff GitOps, quando gli strumenti a valle (ArgoCD, Flux) rilevano una deriva inattesa tra il manifest committato e lo stato del cluster, oppure al momento dell’audit, quando due compilazioni dello stesso input producono artefatti diversi.

Nessuna regola del linter di pubblicazione verifica nei template le invocazioni di helper non ermetici. Il nome dell’helper è scritto nel template, quindi un plugin linter tuo può trovarlo (vedi Convenzioni verificate da una regola del linter).

6. Confini dei pilastri (segnali, non muri)

I confini dei pilastri sono disciplina di authoring, non un’imposizione del linguaggio. Il motore di template consente letture tra pilastri in ogni punto, salvo quando sono esplicitamente vietate dalle regole di autocontenimento (ad es. provides: e source: della Recipe che leggono .context.inject / .context.uses). Gli autori dovrebbero:

  • Leggere .values per il payload cognitivo (intento scritto dallo sviluppatore).
  • Leggere .infra per il dimensionamento fisico (dimensionamento scritto da Ops).
  • Leggere .context.uses.<alias>.provides.<key> per le stringhe puntatore tra componenti.
  • Leggere .context.inject per la pipe di consegna successiva all’idratazione.

Il motore di template non controlla la lettura. Un template di Recipe che legge .infra.replicas per determinare un campo values: funziona; nulla impedisce il percorso tra pilastri. L’obiettivo della disciplina sono i segnali — i confini descrivono l’intento di authoring (chi possiede i dati) anziché una restrizione a runtime.

Documentato in: vocabulary/data-pillars.md «Pillar boundaries and authoring discipline (Confini dei pilastri e disciplina di scrittura)».

Modalità di errore: Fuga tra pilastri — il payload cognitivo dello sviluppatore contiene dettagli di dimensionamento fisico, oppure il dimensionamento scritto da Ops contiene metadati cognitivi. La build riesce; la suddivisione dell’authoring in quattro domini si sfuma nel tempo man mano che gli autori aggirano i pilastri; la manutenzione a valle diventa più difficile man mano che la corrispondenza tra pilastri e flusso dei dati si indebolisce.

7. Semantica a doppia origine di containers.<name>.variables del Workload

La mappa variables: combina due origini di dati distinte tramite espressioni di template Go: letterali del pilastro dello sviluppatore (voci che leggono .values / .infra / .locals) e dati della pipe tra componenti (voci che leggono .context.inject.env.<KEY>). Gli autori scelgono un’origine per ogni voce a seconda che il valore sia locale al componente o derivato da altri componenti.

Il compilatore non distingue le due origini; entrambe confluiscono nella stessa lista env: di Kubernetes sul Deployment renderizzato. La semantica a doppia origine vale solo in fase di authoring — la disciplina consiste nel nominare l’intento (questa voce è locale al componente; quella voce è derivata da altri componenti) in modo che i futuri manutentori possano leggere quali voci dipendono da quali output dell’idratazione di inject.

Documentato in: entities/workload.md «Field-semantics essentials (Elementi essenziali della semantica dei campi)» (variables).

Modalità di errore: Gli autori che non distinguono le due origini perdono la traccia di «quali voci sono accoppiate ai provides: di quale target». Il refactoring delle chiavi di provides: di un target rompe silenziosamente ogni voce variables: del chiamante che leggeva attraverso la pipe di inject.

8. Disciplina di denominazione delle risorse cloud

Le Recipes che emettono nomi di risorse cloud (nomi di bucket S3, identificatori di database RDS, nomi di ruoli IAM, nomi di stack CloudFormation — qualsiasi campo il cui valore occupa uno spazio dei nomi globale presso il fornitore cloud) devono concatenare {{ .metadata.release_name }} e/o {{ .context.instance_id }} nel nome renderizzato per evitare collisioni quando la stessa Recipe viene eseguita su più Releases o istanze di componenti.

Il compilatore non ispeziona gli output di valuesMapping: alla ricerca di campi di nomi di risorse cloud privi di queste interpolazioni. La disciplina è mantenuta dagli autori delle Recipe (che sanno quali campi danno nome a risorse globalmente uniche per il provider di destinazione) e dai revisori (che individuano i pattern di risorse senza nome nella revisione delle PR).

Documentato in: entities/recipe.md «Cloud-resource naming discipline (Disciplina di denominazione delle risorse cloud)».

Modalità di errore: Due Releases dello stesso Aggregate (prod-billing e staging-billing) tentano entrambe di distribuire una risorsa con lo stesso nome globale; la seconda distribuzione fallisce a runtime con un rifiuto lato cloud. La build di Aggrega riesce; il fallimento della distribuzione emerge solo quando viene applicata la seconda Release.

Nessuna regola del linter di pubblicazione verifica che i campi di nomi di risorse cloud contengano le interpolazioni richieste; un plugin linter tuo può farlo (vedi Convenzioni verificate da una regola del linter).

9. Granularità del Component — un servizio coerente per Component

Un Component modella un servizio coerente — un singolo servizio esposto, oppure il workload (o i workload) di un servizio insieme ai suoi workload ausiliari solo interni. Quando un chart raggruppa servizi che un altro componente potrebbe sensatamente collegare con use singolarmente — in particolare infrastruttura esterna come un database, una cache o un message broker che Aggrega già modella come Component a sé — la libreria standard compone Components per servizio in un modulo sotto-aggregato (spec.aggregates + exportedComponents) invece di avvolgere l’intero prodotto come un unico Component opaco. La disciplina: più workload vanno bene all’interno di un Component; l’utilizzabilità indipendente è la linea che divide un Component in uno stack.

Il compilatore è agnostico rispetto a questa granularità. Esegue il rendering di qualunque cosa superi la validazione dello schema — non ispeziona quanti servizi raggruppa la Recipe di un Component, né se uno di essi sia utilizzabile in modo indipendente. Un autore che avvolge un prodotto a cinque servizi come un singolo Component produce un Component che il compilatore accetta e renderizza senza obiezioni; la convenzione è mantenuta dalla disciplina di authoring e dall’attenzione dei revisori.

Documentato in: ../../architecture/06-data-taxonomy-and-composition.md (un servizio coerente per Component — il confine del singolo workload).

Modalità di errore: Un avvolgimento monolitico multi-servizio viene compilato con successo, ma i servizi raggruppati sono invisibili alla topologia, al selettore e alle policy — non possono essere scalati, sostituiti né usati come dipendenza in modo indipendente. Il refactoring successivo del monolite in Components per servizio è una modifica incompatibile per ogni consumatore che faceva riferimento al singolo nodo avvolto.

Perché esistono le convenzioni

Ognuna di queste convenzioni è disciplina di authoring per scelta progettuale, anche se uno schema o una policy Wasm potrebbe imporre ciascuna di esse. Le motivazioni per tipo di contratto:

Estensibilità. La disciplina dei prefissi riservati (contratto 3) descrive il vocabolario della libreria standard, non l’universo del vocabolario valido. I cataloghi enterprise scrivono i propri prefissi e le proprie chiavi di etichetta per estendere la libreria standard; imporre tramite lo schema la convenzione dei prefissi trasformerebbe «la disciplina della libreria standard» in «l’unica forma consentita dal linguaggio» — è il muro che l’architettura evita deliberatamente. L’asse del tipo operativo (contratto 1) mantiene la stessa estensibilità su una superficie diversa: la chiave riservata che Aggrega definisce porta un insieme chiuso, imposto dallo schema, e un catalogo estende aggiungendo una propria chiave di etichetta accanto a essa anziché un valore all’interno di quella di Aggrega. Ciò che lo schema verifica è l’insieme di valori di una chiave che possiede; ciò che resta aperto è ogni altra chiave, ed è lì che vive il vocabolario proprio di un catalogo.

Purezza AOT. La disciplina di denominazione delle risorse cloud (contratto 8) e la disciplina del determinismo (contratto 5) richiedono di ispezionare il contenuto dei template per stabilire se un campo è un nome di risorsa cloud o l’invocazione di un helper non ermetico. La purezza AOT (Invariante 2) impedisce al compilatore di dipendere dallo stato a runtime; l’ispezione statica dei template è fattibile (un plugin linter legge i template dell’entità così come sono scritti), ma farla all’interno del compilatore principale accoppia la logica interna del compilatore a questioni di authoring specifiche di ciascun dominio. L’architettura sposta questi controlli fuori dal compilatore e dentro plugin Wasm secondo l’Invariante 6 (il confine dell’ABI Wasm).

Flessibilità di authoring. La disciplina dei confini dei pilastri (contratto 6) e la semantica a doppia origine di variables (contratto 7) descrivono pattern di authoring anziché vincoli a runtime. La stessa sintassi di template può esprimere un pattern che rispetta la disciplina o uno che la viola; fare della disciplina un controllo a runtime richiederebbe al compilatore di interpretare un intento di authoring a cui non ha accesso. L’architettura tratta la convenzione come documentazione da cui gli autori imparano, anziché come un invariante a runtime. Anche la granularità del Component (contratto 9) rientra qui: le aziende possono avvolgere un prodotto alla granularità che il loro catalogo preferisce, e il compilatore — neutrale rispetto ai contenuti e privo di opinioni secondo l’Invariante 1 — non ha modo di sapere se un workload raggruppato sia utilizzabile in modo indipendente, quindi il confine di un servizio coerente resta disciplina di authoring anziché un muro dello schema. La scelta del tipo operativo (contratto 1) ha la stessa forma: lo schema stabilisce quali valori esistono, ma quale di essi descrive un dato componente è un giudizio di modellazione su come l’infrastruttura deve trattarlo, e nulla in una Recipe o in un blocco values dice al compilatore se il giudizio era corretto.

Imposizione in due metà. L’autocontenimento di provides: della Recipe (contratto 4) è in parte imposto dal compilatore — il percorso di rendering rileva le letture di .context.inject / .context.uses nei template provides: e si arresta. La più ampia disciplina pubblico-contro-privato (non esporre lo stato interno) è ancorata alla convenzione perché il compilatore non può determinare quali stringhe debbano restare interne alla Recipe senza l’intento di authoring.

Le tre vie contano perché ciascuna indica dove risiede la responsabilità di individuare le violazioni. Imposta dallo schema: il compilatore. Imposta da un plugin di policy: il plugin che la verifica, dove ne viene eseguito uno. Mantenuta per convenzione: autori e revisori. Gli autori che interiorizzano le vie capiscono quali errori il compilatore intercetterà e quali passeranno silenziosamente agli strumenti a valle o al runtime.

Convenzioni verificate da una regola del linter

Il linter di pubblicazione, eseguito da aggrega lint, verifica in parte una convenzione di questa pagina: le chiavi delle annotazioni del contratto 3, più sotto. La sua segnalazione è consultiva, e la parte della convenzione che non raggiunge è mantenuta per convenzione, come le voci precedenti.

Nessuna regola del linter di pubblicazione verifica le altre convenzioni di questa pagina. Due di esse possono essere verificate da una regola del linter, perché la violazione è scritta nell’entità: il determinismo (contratto 5) — un template che chiama un helper non ermetico — e la denominazione delle risorse cloud (contratto 8) — un output di valuesMapping: che dà nome a una risorsa cloud senza interpolazione di release_name / instance_id. Lo stesso vale per le chiavi delle etichette sotto i prefissi riservati (contratto 3). Un workspace può collegare plugin linter propri sotto plugins.linter, accanto al linter di pubblicazione, per verificarne una qualsiasi; Le regole di disciplina elenca le regole che il linter di pubblicazione contiene.

Le altre convenzioni (1, 2, 4, 6, 7, 9) dipendono da ciò che l’autore intendeva, che nessuna regola ricava da ciò che è stato scritto. La separazione in contenitori è guidata dall’estensibilità (i cataloghi enterprise la ridefiniscono) — l’imposizione tramite lo schema entrerebbe in conflitto con quella flessibilità. Ciò che resta dell’asse del tipo operativo dopo che lo schema ha stabilito l’insieme di valori — scegliere la primitiva adatta al componente — è guidato dall’intento di authoring: il compilatore non sa distinguere un tipo operativo ben scelto da uno scelto male, perché entrambi sono valori che accetta. La disciplina dei confini dei pilastri e la semantica a doppia origine di variables sono guidate dall’intento di authoring — il compilatore non può determinare l’intento dalla sola sintassi dei template. L’autocontenimento di provides: della Recipe è imposto in parte; la più ampia disciplina pubblico-contro-privato dipende da quali chiavi l’autore intendeva mantenere interne, cosa che nulla nella Recipe dichiara. Anche la granularità del Component è guidata dall’intento di authoring — se un workload raggruppato sia utilizzabile in modo indipendente è un giudizio di modellazione che il compilatore non può ricavare dal contenuto della Recipe.

3. Disciplina dei prefissi riservati

Le chiavi delle annotazioni e delle etichette seguono una forma <namespace>/<name>. Cinque prefissi riservati comportano regole di authoring specifiche: aggrega.ai/ (solo piattaforma), feature.aggrega.ai/ (scorciatoie ufficiali di Feature), component.aggrega.ai/ (tratti intrinseci del Component), aggregate.aggrega.ai/ (identità del modulo Aggregate) e <any-other-domain>/ (enterprise / community).

Il compilatore non rifiuta un’annotazione scritta sotto un prefisso riservato su un’entità del catalogo o su una Release; solo un binding di annotazione di un Manifest o un’etichetta di output di una Recipe che rivendica una chiave sotto aggrega.ai/ arresta la build. Un’azienda che dichiara aggrega.ai/internal-billing-tag: "..." al di fuori del vocabolario della piattaforma produce un’annotazione che il compilatore accetta e propaga in cascata attraverso il sistema dei contenitori; gli aggiornamenti successivi della piattaforma che introducono un vero aggrega.ai/internal-billing-tag collidono silenziosamente.

Documentato in: labels-and-annotations.md (Disciplina dei prefissi) + providers/well-known-annotations.md.

Modalità di errore: Le annotazioni personalizzate sotto prefissi riservati collidono con future annotazioni della piattaforma con lo stesso nome; il comportamento atteso della piattaforma sovrascrive silenziosamente il valore scritto dall’azienda o coesiste con esso, a seconda dell’ordine.

Il linter di pubblicazione, eseguito da aggrega lint, segnala una chiave di annotazione di un’entità del catalogo sotto aggrega.ai/ che non è una delle annotazioni ben note della piattaforma, e una sotto feature.aggrega.ai/ su un’entità diversa da una Feature, come segnalazione consultiva (E0277). Le chiavi delle etichette, gli altri prefissi riservati e le annotazioni al di fuori dei metadata.annotations di un’entità — quelle che scrive una Release, per esempio — non vengono verificati, quindi per essi la disciplina resta una convenzione.

Riferimenti incrociati