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

Component

Il ruolo concettuale dell’entità Component (l’interfaccia astratta del nodo di calcolo nel Dominio 2) si trova in architecture/04-entity-taxonomy.md. Questa pagina tratta la superficie di authoring del Component: la tassonomia delle etichette semantiche che gli architetti usano per stratificare l’identità cognitiva sopra l’ontologia operativa di base, la dichiarazione schema: per i pilastri dei dati, le tabelle dichiarative usesSchema e featuresSchema per i socket di topologia e gli slot di attachment, i mandati di presenza, il meccanismo di ereditarietà extends: e il blocco di regole tra campi assertions:.

La tassonomia delle etichette semantiche (la convenzione della libreria standard)

Se i tipi di base sono puramente cloud-native, l’intelligenza operativa e cognitiva dell’architettura viene stratificata interamente tramite il duck typing semantico.

Il compilatore Go principale non interpreta queste etichette. Il compilatore costruisce il grafo piatto della rappresentazione intermedia (IR) senza interpretare la semantica delle etichette. Queste etichette rappresentano la convenzione della libreria standard—«marcatori genetici» immutabili creati dall’architetto di piattaforma nel Dominio 2. Forniscono gli hook semantici espliciti che i validatori di policy Wasm e le Recipes fisiche di Ops usano per governare l’architettura.

(A) Il livello cloud generico Queste etichette descrivono comportamenti universali, consentendo ai motori di policy e ai proxy L7 generati di governare architetture enterprise standard senza dover comprendere nativamente i framework di IA.

Prefisso dell’etichettaValori ammessi (convenzione)Perché serve a Platform Ops (l’hook di policy)
tool.aggrega.ai/impactread-only, mutatingConsente ai motori di policy di valutare l’autorizzazione a privilegio minimo (Least-Privilege AuthZ). Gli strumenti che modificano dati possono attivare automaticamente policy che richiedono il collegamento di sidecar con gate di approvazione rigorosi.
datastore.aggrega.ai/enginerelational, document, kv, vector, graph, semantic-memory, search (insieme di valori in via di stabilizzazione rispetto al catalogo popolato)Consente ai motori di policy di imporre la sicurezza dei tipi tra nodi (ad esempio, impedendo a un agente di tentare di inviare payload SQL a un Vector DB).
gateway.aggrega.ai/intelligencesemantic, l4-meshDetermina quali funzionalità un router può supportare fisicamente (ad esempio, impedendo che una Feature che instrada in base al modello indicato da una richiesta, come una catena di fallback, venga collegata a una mesh TCP standard).
dataplane.aggrega.ai/request-mirroringfull-rate, sampledConsente a una Feature che copia il traffico live verso una seconda destinazione di selezionare un proxy effettivamente in grado di copiare, e di distinguere uno che copia ogni richiesta corrispondente da uno la cui quota di richieste copiate è configurabile.
dataplane.aggrega.ai/caller-identityclient-certificate, injected-headerConsente a una Feature che ha bisogno che il chiamante originale sia identificato presso il servizio dietro il proxy di selezionare un componente in grado di trasmettere tale identità, e di leggere quale meccanismo la trasmette — i dettagli del certificato TLS del client stesso inoltrati, oppure un header che il proxy compone da sé dopo aver autenticato il chiamante.
dataplane.aggrega.ai/content-maskingentity-recognition, pattern-listConsente a una Feature che maschera testo sensibile di selezionare un componente in grado di sostituirlo con un segnaposto nel payload di chat e completion che instrada, prima che il testo prosegua. Il valore indica la fedeltà: con entity-recognition il componente sostituisce le corrispondenze dei pattern forniti nella sua configurazione, e anche i tipi di entità rilevati da un servizio di riconoscimento che chiama; con pattern-list sostituisce solo le corrispondenze dei pattern forniti nella sua configurazione, e non chiama alcun servizio di riconoscimento.
dataplane.aggrega.ai/prompt-guardpattern-list, classifierConsente a una Feature che filtra i prompt del modello di selezionare un componente in grado di ispezionare il payload di chat e completion che instrada e di rifiutare una richiesta in base al suo contenuto. Il valore indica la fedeltà: con pattern-list la corrispondenza avviene con pattern forniti nella sua configurazione, sul payload del modello e non su un corpo HTTP arbitrario; con classifier il verdetto è quello di un classificatore di testo addestrato, raggiunto tramite un servizio di rilevamento che il componente chiama, rispetto a una soglia fornita nella sua configurazione.
dataplane.aggrega.ai/upstream-tlstrust-anchorConsente a una Feature che richiede al proxy di verificare con chi sta comunicando di selezionare un componente in grado di verificare il certificato di un upstream rispetto a un trust anchor fornito dalla Release.
dataplane.aggrega.ai/upstream-pinningpublic-keyConsente a una Feature che fissa quale chiave può presentare un upstream di selezionare un componente in grado di rifiutare un upstream a meno che un certificato da esso presentato non contenga una delle chiavi pubbliche fornite dalla Release. Un’asserzione diversa da upstream-tls: un pin dice quale chiave deve essere un certificato, un anchor che cosa deve dire.
dataplane.aggrega.ai/period-budgetcost, tokensConsente a una Feature che limita ciò che il traffico può consumare in un periodo di selezionare un componente in grado di rifiutare le richieste al modello una volta che quanto ha conteggiato nel periodo supera un limite impostato nella sua configurazione. Il valore indica cosa conteggia: cost, quanto è costato il traffico, calcolato in base a una tabella di prezzi che il componente mantiene per ogni modello; tokens, i token che la risposta di ciascun modello dichiara di aver letto, scritto o entrambi, che il componente conteggia senza attribuire alcun prezzo.
dataplane.aggrega.ai/concurrency-captotal, per-targetConsente a una Feature che limita quante richieste un componente gestisce contemporaneamente di selezionare un componente in grado di trattenere o rifiutare una richiesta oltre un limite impostato nella sua configurazione. Il valore indica cosa conteggia un limite: total, ogni richiesta che il componente inoltra, rispetto a un unico limite; per-target, le richieste in corso verso ciascun target upstream a cui invia, con un limite per ciascuno e nessuno sul loro totale.

Le chiavi dataplane.aggrega.ai/ indicano una posizione sul percorso del traffico anziché un tipo di componente, così un proxy, un gateway di ingress e una service mesh si descrivono tutti con un unico vocabolario invece di averne ciascuno uno proprio. Due proprietà della famiglia meritano una lettura attenta, perché entrambe sono facili da invertire:

  • Il valore porta la fedeltà, non solo la presenza della capacità. Due componenti possono entrambi duplicare le richieste e differire comunque in un modo che interessa a una Feature, quindi la distinzione viaggia nel valore e una Feature seleziona la fedeltà di cui ha bisogno. Un componente che offre una fedeltà più forte porta il valore più forte e nessun altro.
  • Un valore afferma ciò che il prodotto è in grado di fare, mai ciò che un deployment ha attivato. I due si leggono allo stesso modo e solo il primo è una proprietà del componente. Un proxy in grado di verificare il certificato di un upstream porta upstream-tls: trust-anchor indipendentemente dal fatto che un dato deployment abiliti il controllo, perché l’etichetta è ciò su cui una Feature effettua la selezione prima che qualsiasi cosa venga configurata.

Un componente che non ha nulla da descrivere su uno di questi assi non vi porta alcun valore anziché uno più debole, esattamente come altrove nella tassonomia: l’assenza significa che l’asse non ha alcun oggetto su quel componente, quindi una Feature che richiede un valore qualsiasi su di esso correttamente non si collega.

(B) Il livello di IA specializzato (l’identità cognitiva) Queste etichette descrivono l’identità cognitiva del carico di lavoro, consentendo all’architettura di proteggere i moderni framework di IA.

Prefisso dell’etichettaValori ammessi (convenzione)Perché serve a Platform Ops (l’hook di policy)
model.aggrega.ai/capabilitygenerative, embedding, transcriptionUsato dalle stringhe di selettore di usesSchema (valutate nativamente dal compilatore Go durante l’analisi statica) per garantire che uno sviluppatore non instradi per errore un payload di testo generativo verso un endpoint di embedding.
model.aggrega.ai/apiopenai, anthropic, gemini, nativeIndica quale API di modello risponde all’indirizzo pubblicato da un componente: openai quando si tratta dell’API OpenAI, quella del fornitore stesso o l’implementazione di un server, anthropic quando si tratta della Messages API di Anthropic, quella del fornitore stesso o l’implementazione di un server, gemini quando si tratta della Gemini API di Google, e native quando si tratta dell’API propria del prodotto e di nessuna di queste. Ogni componente modello la porta, e così anche un gateway in grado di servire un’API di modello, quindi un socket che seleziona component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api accetta un modello o un gateway di questo tipo e rifiuta un gateway che non ne serve nessuna, mentre un socket che indica un solo valore, come model.aggrega.ai/api=anthropic, accetta solo ciò che serve quell’API. Indica ciò che il prodotto serve, non ciò che una singola Release collega: un gateway i cui modelli sono collegati a un proprio socket la porta anche senza nulla di collegato. L’etichetta è una stringa su cui il selettore effettua la corrispondenza; nulla verifica che cosa risponda effettivamente all’indirizzo.
agent.aggrega.ai/autonomyautonomous, copilotIdentifica il rischio di esecuzione del ciclo cognitivo, consentendo alle policy di imporre funzionalità di approvazione umana per gli agenti completamente autonomi.

(C) Gli elementi trasversali (governance, stato e hardware) Rappresentano i tag enterprise fondamentali che guidano la validazione Zero-Trust e l’instradamento verso l’hardware.

Prefisso dell’etichettaValori ammessi (convenzione)Perché serve a Platform Ops (l’hook di policy)
component.aggrega.ai/hostingself-hosted, managed, external, mixedRegistra chi gestisce la risorsa sottostante di un componente — l’asse del confine di fiducia. I motori di policy la leggono per calcolare il rischio di esfiltrazione dei dati (ad esempio, i dati interni instradati verso un’API di terze parti managed escono dal confine dell’operatore). Trasversale: gli stessi valori descrivono allo stesso modo un database gestito, un’API di modello gestita e un server di inferenza autogestito. mixed contrassegna un componente le cui Recipes coprono più di una postura — un datastore eseguito in self-hosting dalle sue Recipes Helm e Compose e gestito dalle sue Recipes RDS — così la postura di una Release segue la Recipe selezionata dal suo Manifest.
compliance.aggrega.ai/data-classpublic, internal, restrictedLa classe dei dati che un componente contiene. Il compilatore la porta nel grafo di build come stringa e non stabilisce alcun ordinamento; una policy che un operatore collega al ruolo ir-verdict assegna alle classi il loro ordine nelle proprie impostazioni e legge l’etichetta lungo le rotte che il compilatore enumera — interrompendo, ad esempio, una build in cui un componente restricted raggiunge un componente di un’altra classe senza alcuna Feature di declassificazione collegata sulla rotta (policy-data-class-route). Nessun Component della libreria standard la porta: la classe è un’affermazione su come un parco infrastrutturale usa un componente, portata dal Component proprio di quel parco — una specializzazione tramite extends, ad esempio.
compliance.aggrega.ai/contains-piitrue, falseContrassegna esplicitamente i carichi di lavoro che rientrano nell’ambito GDPR/CCPA. Una policy collegata da un operatore può leggerla per richiedere Features specifiche sulle rotte seguite dal traffico di tale carico di lavoro — core/data-masking su un gateway di IA attraverso cui invia traffico verso i modelli, ad esempio, la forma che policy-data-class-route verifica per una classe di dati. Nessun Component della libreria standard la porta; come la classe di dati, è un’affermazione di un parco infrastrutturale sui propri componenti.
hardware.aggrega.ai/acceleratorgpu, tpu, npuUsato da DevOps nel file Release. Instradano esplicitamente questi componenti entro i confini fisici dei pool hardware (ad esempio, un cluster dotato di GPU) tramite la mappa components: {}, mentre un ruolo verdict di governance può imporre che i componenti etichettati come GPU non vengano mai collocati in confini privi di GPU.
state.aggrega.ai/retentionretain, deleteRisolve il divario di eliminazione AOT. Se uno sviluppatore elimina un database dal proprio Aggregate, un orchestratore GitOps rimuoverà fisicamente il disco. Uno step pipeline: di una Recipe può leggere l’etichetta retain e aggiungere una protezione nativa dell’orchestratore agli artefatti renderizzati (ad esempio, helm.sh/resource-policy: keep).
state.aggrega.ai/backup-tiermission-critical, standard, ephemeralHook di disponibilità SOC2. Indica alla FeatureRecipe di Ops se generare fisicamente configurazioni automatiche di Snapshot/Volume Backup per la risorsa.

(D) Il contesto di business dinamico (annotazioni a cascata) Mentre le labels definiscono il DNA immutabile del catalogo, i contesti di business dinamici (come la definizione dell’ambito di audit SOC2 o il monitoraggio dei costi FinOps) cambiano a seconda di chi distribuisce l’applicazione e di dove viene eseguita. Sono governati da annotazioni iniettate dinamicamente dai subsystems dello sviluppatore, dai confini della Release di Ops o da un plugin di governance collegato nel ruolo annotation-transform.

Prefisso dell’annotazioneValori ammessi (convenzione)Perché serve a Platform Ops (l’hook di policy)
business.aggrega.ai/cost-centerad es. finance, ai-researchRichiesto dai plugin di rendering Wasm per iniettare tag fisici (ad esempio, tag AWS o label K8s) negli artefatti finali generati per le dashboard di fatturazione cloud.
business.aggrega.ai/ownerad es. team-alpha@corp.comInstradamento della risposta agli incidenti. Garantisce che l’infrastruttura sia associata a un team umano.
compliance.aggrega.ai/frameworksad es. soc2, hipaaTrigger dell’ambito SOC2. Iniettato tramite la Release dell’ambiente. I plugin Wasm leggono questa stringa per generare automaticamente sidecar rigidi di audit logging e disabilitare le porte di debug quando un’applicazione entra in un confine di conformità di produzione.

La tassonomia è una convenzione del catalogo, non una regola del compilatore. Le aziende possono ignorarla, eliminarla o inventare un proprio vocabolario di etichette (mycompany.com/custom-trait). I plugin Wasm valutano qualsiasi chiave di etichetta definita dall’azienda.

Creazione dello schema

Lo schema Component (e la sua controparte Feature, incluse le Features di credenziali etichettate feature.aggrega.ai/kind: secret) dichiara il contratto di validazione per i values creati dallo sviluppatore tramite un blocco spec.schema:. Il blocco accetta JSON Schema 2020-12 espresso nella forma abbreviata YAML compatta (il default; circa 15 parole chiave, trasformate meccanicamente in JSON Schema in fase di compilazione) oppure in YAML JSON Schema completo (la forma estesa), con riferimenti tra documenti tramite $ref: per voci di SchemaLibrary condivise tra più Components.

  • Forma compatta inline (superficie di authoring predefinita): un blocco YAML incorporato che porta foglie in forma compatta direttamente nello YAML del Component. Copre la grande maggioranza del contenuto degli schemi del catalogo con una frazione delle righe di un JSON Schema completo. Vedi vocabulary/compact-form-authoring.md per il vocabolario delle parole chiave e le convenzioni di authoring.
  • YAML JSON Schema inline: la forma estesa, adatta quando lo schema necessita di parole chiave di JSON Schema 2020-12 che la forma compatta non porta direttamente ($dynamicRef, unevaluatedProperties profondi, composizioni not: complesse). Forma compatta e JSON Schema possono essere combinati a qualsiasi confine di nodo all’interno di un unico blocco schema: tramite la via d’uscita $jsonschema:.
  • Riferimento tra documenti ($ref: a una voce di SchemaLibrary): un $ref: nativo di JSON Schema che punta a una voce di SchemaLibrary per identità (Datastores#/schemas/MariaDBValues o simile). Gli schemi enterprise che si estendono per centinaia di righe e sono riutilizzati in più Components risiedono in entità SchemaLibrary; il Component che li consuma referenzia la voce senza incorporarne il contenuto. Vedi entities/schemalibrary.md e vocabulary/cross-document-ref.md per l’entità libreria e la semantica di risoluzione.

Le tre forme precedenti creano il contenuto dei pilastri, e sono disponibili per un Component che non estende nulla. Un Component che dichiara extends: non crea alcun contenuto dei pilastri: scrive il marcatore letterale schema: inherited e riceve il blocco dei pilastri della sua base esattamente come la base lo ha creato. Quel marcatore è l’unico valore che schema: accetta su un Component di questo tipo. Vedi «Creazione del catalogo: estendere i Components di base» più avanti.

Il compilatore risolve il blocco schema: — espandendo la forma compatta, dereferenziando gli URL $ref:, applicando le catene da libreria a libreria di SchemaLibrary — e unifica il JSON Schema risultante con le basi generate automaticamente derivate da usesSchema e featuresSchema (vedi la sezione più avanti) durante la fase di validazione del Component. La validazione viene eseguita sullo schema risolto; il percorso di authoring è opaco per le fasi successive della pipeline.

Le istanze create vengono validate rispetto a questo schema risolto in fase di build: i values creati dallo sviluppatore di un’istanza di componente e l’infra risolto dell’Operatore, più i values/infra su qualsiasi collegamento di Feature, devono essere conformi ai pilastri dichiarati — un valore di tipo errato, un numero fuori intervallo, una stringa che non ha il format dichiarato, un campo obbligatorio mancante o (per values, validato in forma chiusa) una proprietà non dichiarata interrompono la build alla sua sorgente creata, invece di produrre un manifest rotto in fase di deploy. Un pilastro il cui schema indica un format che il compilatore non controlla — qualsiasi cosa al di fuori di email, uri, hostname, ipv4, ipv6, uuid, date-time e date, password incluso — viene rifiutato al caricamento del catalogo, con l’elenco dei nomi supportati; vedi vocabulary/compact-form-authoring.md per ciò che ciascun nome controlla. Un’istanza di un Component che extends: una base viene validata rispetto al blocco dei pilastri della base, che il Component che estende eredita invariato — così un’istanza della base e un’istanza di qualunque cosa la estenda affrontano lo stesso contratto dei pilastri. Vedi errors/fatal-halts.md §«Authored values or infra do not conform to the declared schema (I values o l’infra creati non sono conformi allo schema dichiarato)» per la diagnostica e le regole per pilastro (incluso come infra viene validato rispetto all’unione delle chiavi del Component e del provider).

I default dichiarati si materializzano nei pilastri renderizzati. Oltre alla validazione, un default: dichiarato su un campo di values (o su un campo di infra) viene inserito nel pilastro renderizzato in fase di build per ogni chiave che l’autore omette — così un template di Recipe che legge {{ .values.charset }} riceve l’utf8mb4 dichiarato dallo schema anziché un valore vuoto. I valori forniti dall’autore prevalgono sempre; gli oggetti annidati vengono completati per ogni figlio omesso. Poiché la materializzazione usa la stessa risoluzione dello schema della validazione, si materializzano anche i default raggiunti tramite un $ref: tra documenti verso una SchemaLibrary — sia un riferimento all’intero pilastro (values: {$ref: "BaseComponents#/schemas/BaseModelParameter"}) sia la forma base-più-variante (un $ref: di base accanto a properties sorelle, ciascuna con i propri default). I default dichiarati solo all’interno di un riferimento locale nello stesso documento #/$defs/, o sotto un ramo allOf / oneOf / anyOf, non vengono materializzati; la libreria standard compone i pilastri tramite $ref: tra documenti, che invece viene materializzato.

Il pilastro values

Lo schema del Component separa tre pilastri in base alla proprietà: values è compilato dallo sviluppatore nell’Aggregate (intento cognitivo — nome del database, versione, charset), infra è compilato dall’operatore nella Release (dimensionamento operativo — calcolo, storage, HA) e provides è impostato dalla Recipe (il contratto dell’API pubblica — host, porta, protocollo). Lo sviluppatore non vede mai infra; l’operatore non vede mai values. Le Recipes consumano entrambi i pilastri durante il rendering di base, mappando i pilastri astratti nella forma concreta che il loro provider di destinazione si aspetta. Questa sezione tratta la superficie di authoring del pilastro values. Consulta vocabulary/data-pillars.md per la tassonomia più ampia dei pilastri e la disciplina della cascata tra pilastri.

values porta l’intento cognitivo dello sviluppatore — le scelte che descrivono che cosa l’applicazione è o fa, non come viene dimensionata o eseguita. Nome del database, charset, versione del motore, livello di log, flag di funzionalità e parametri del livello applicativo che cambiano tra le versioni dell’applicazione ma restano stabili tra gli ambienti sono il contenuto tipico di values. L’operatore non sovrascrive mai values: (lo schema della Release rifiuta meccanicamente un blocco values: secondo architecture/06-data-taxonomy-and-composition.md §8 Vincolo 4); la variazione per ambiente passa attraverso il Parameter Hoisting — l’Aggregate espone parameters.* tipizzati, il template values del Component li referenzia e la Release soddisfa i parametri.

# Component schema declares the values shape:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
charset: { type: string, default: utf8mb4, enum: [utf8mb4, latin1, ascii] }
engine_version: { type: string, default: "10.11" }
log_level: { type: string, default: info, enum: [debug, info, warn, error] }
# Aggregate fragment — the developer fills values:
components:
customer-db:
type: core/datastore/mariadb
values:
database_name: customers
charset: utf8mb4
engine_version: "{{ .parameters.mariadb_version }}" # Parameter Hoisting
log_level: info

Consumo lato Recipe. Le Recipes leggono i valori risolti tramite .values.<field> in valuesMapping:, provides:, assertions: e nelle altre superfici di template — consulta entities/recipe.md per la matrice di disponibilità per template. Il compilatore unifica lo schema values del Component con gli eventuali schemi values: degli attachment di Feature sullo stesso nodo del Component, in modo che il contesto di template risolto contenga ogni campo applicabile.

Disciplina tra pilastri. values è l’unico pilastro che lo sviluppatore scrive nell’Aggregate. Qui vanno i campi strettamente rivolti allo sviluppatore; i parametri operativi (numero di repliche, limiti di CPU/memoria) vanno nel pilastro infra del Component, così da risiedere nella Release; l’output pubblico (host, porta) va nel provides della Recipe. Mescolarli rompe l’invariante di proprietà; consulta vocabulary/data-pillars.md «Meccaniche tra pilastri» per i rari casi in cui un passaggio deliberato tra pilastri è giustificato.

Il pilastro infra

Lo schema del Component separa tre pilastri in base alla proprietà: values è compilato dallo sviluppatore nell’Aggregate (intento cognitivo — nome del database, versione, charset), infra è compilato dall’operatore nella Release (dimensionamento operativo — calcolo, storage, HA; il backup di un datastore non si dimensiona qui, ma è la Feature core/backup che l’operatore collega nella Release) e provides è impostato dalla Recipe (il contratto dell’API pubblica — host, porta, protocollo). Lo sviluppatore non vede mai infra; l’operatore non vede mai values. Le Recipes consumano entrambi durante il rendering di base, mappando i pilastri astratti nella forma concreta che il loro provider di destinazione si aspetta.

Tre convenzioni di infra contano in ogni Component agnostico rispetto alla capacità della libreria standard: una via d’uscita a struttura aperta per i parametri specifici del provider, un override opzionale della versione dell’artefatto upstream e un vocabolario basato sull’intento per i campi di alta disponibilità. Il Component di riferimento canonico è core/datastore/mariadb nel catalogo della libreria standard — implementabile da Recipes Helm che eseguono l’immagine ufficiale mariadb o consegnano una risorsa personalizzata MariaDB al controller mariadb-operator, da Recipes Terraform su AWS RDS, da Recipes CloudFormation sulla stessa superficie RDS e da Recipes Compose su un container locale — e il suo blocco infra illustra la prima e la terza.

infra.overrides

I campi universali di infra — compute, storage, ha — coprono la maggior parte del dimensionamento operativo tra i provider. La parte restante è irriducibilmente specifica del provider: una Recipe Kubernetes ha bisogno di un nodeSelector, una Recipe Terraform per RDS ha bisogno di un instance_class, una Recipe CloudFormation per RDS ha bisogno di un DBInstanceClass, una Recipe Compose ha bisogno di un override di image. Lo schema del Component espone una mappa davvero aperta come via d’uscita, così che questi parametri passino senza appesantire lo schema:

infra:
# ... universal fields ...
# Provider-specific overrides. Accepts any nested structure.
# Each Recipe documents which keys it reads.
overrides:
type: object
additionalProperties: true # genuinely open map: arbitrary nested structure permitted

Il type: object esplicito con additionalProperties: true attiva la semantica di mappa aperta. Il compilatore fa passare la struttura senza modificarla; il corpo del template della Recipe legge le chiavi che conosce e ignora le altre. Ogni Recipe documenta l’ontologia delle chiavi di override nel suo commento di intestazione, così che un operatore che scrive una Release per una specifica combinazione Component × Recipe sappia quali parametri la Recipe espone.

Un frammento di Release che usa gli override:

components:
main-db:
infra:
compute: { cpu: "2", memory: 8Gi }
storage: { size: 40Gi, type: balanced-csi }
overrides:
nodeSelector:
kubernetes.io/hostname: cluster1-worker1
service_type: LoadBalancer
metrics:
enabled: true
image:
repository: bitnamilegacy/mysqld-exporter

Lo sviluppatore non vede mai overrides: risiede nella Release, che è il dominio dell’operatore.

infra.source_version

Il campo source di una Recipe fa riferimento a un artefatto upstream a una versione specifica (chart Helm 25.0.8, modulo Terraform 4.2.0, tag di immagine OCI). Fissare la versione nel codice della Recipe costringe chi mantiene il catalogo a pubblicare una nuova Recipe a ogni aggiornamento compatibile della versione upstream. Lo schema del Component espone un override opzionale:

infra:
source_version:
type: string
description: |
Source artifact version. A Recipe versions its artifact from this key
where its source resolution reads it, and is unaffected where it does not.
Changing from the version a Recipe was authored against does not
guarantee value mapping compatibility.

La Recipe lo legge tramite l’helper optional nel suo blocco source, così che un pin assente ricada sulla versione per cui la Recipe è stata scritta:

source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "{{ optional .infra `source_version` `25.0.8` }}"

Le stringhe source di una Recipe (e i sottocampi con valore stringa di una mappa source: strutturata) sono valutate come template Go. Una coordinata remota — come la version qui sopra — viene valutata quando aggrega pull fissa l’artefatto, rispetto a .values, .infra e .locals senza radice .context; una source che indica un percorso nel workspace viene valutata durante il rendering dell’entità, rispetto allo stesso contesto autosufficiente dei locals della Recipe — .context.instance_id, .values, .infra e l’intero .locals risolto del nodo. .context.inject, .context.uses e .provides sono vietati in entrambi i casi. È la presenza di .infra in quel contesto a far funzionare l’override qui sopra, e .locals consente a una Recipe di calcolare una volta un frammento di source e di rileggerlo qui. Un template di source non legge mai i provides del proprio nodo: quel pilastro non fa parte del contesto, e un template che tenta di accedervi interrompe la build — una proprietà fissa della superficie e non una lacuna in attesa di lavoro futuro. Consulta la riga n. 5 della matrice di espansione dei template per le regole di disponibilità complete. Cambiare infra.source_version rispetto al default della Recipe non garantisce che il valuesMapping della Recipe sia compatibile a livello di wire con la nuova versione upstream; la description della dichiarazione source_version nello schema del Component riporta questo avviso.

infra.ha.*

I campi di alta disponibilità usano un vocabolario di intento, non di meccanismo:

infra:
ha:
enabled: { type: boolean, default: false }
read_replicas: { type: integer, min: 0, default: 0 }

infra.ha.enabled dice «rendi questo Component altamente disponibile» e infra.ha.read_replicas dice «voglio N copie di sola lettura». Ogni Recipe decide che cosa diventa l’intento sul proprio provider. Le Recipes della libreria standard per core/datastore/mariadb, con i nomi con cui un Manifest le mappa:

Recipeha.enabled: true corrisponde aha.read_replicas: N corrisponde a
helm/mariadb (uno StatefulSet sull’immagine ufficiale mariadb)esegue un solo server, quindi la build si interrompe indicando la chiaveesegue un solo server, quindi N maggiore di 0 interrompe la build
helm/mariadb-cluster (una risorsa personalizzata MariaDB che il controller mariadb-operator riconcilia)attiva il failover automatico (replication.primary.autoFailover: true); il failover avviene su una replica di lettura, quindi N pari a 0 interrompe la buildimposta spec.replicas a N + 1 e attiva la replica; provides.host diventa il Service <name>-primary
terraform/mariadb-rds (AWS RDS)imposta multi_az = true sulla risorsa aws_db_instance primariacrea N risorse di replica di lettura aws_db_instance separate
terraform/mariadb-rds-module, terraform/mariadb-rds-terraform-aws-modules (AWS RDS tramite un modulo)passa multi_az = true al moduloesegue il provisioning di una sola istanza, quindi N maggiore di 0 interrompe la build
cloudformation/mariadb-rds (AWS RDS)imposta MultiAZ: true sulla risorsa AWS::RDS::DBInstanceesegue il provisioning di una sola istanza, quindi N maggiore di 0 interrompe la build
compose/mariadb (container di sviluppo locale)esegue un solo server, quindi la build si interrompe indicando la chiaveesegue un solo server, quindi N maggiore di 0 interrompe la build

Il vocabolario di meccanismo (infra.primary.replicas) suona naturale per un provider (i pod Kubernetes sono repliche di uno StatefulSet) e come un errore di categoria altrove — RDS non ha un concetto di «repliche» sul primario, CloudFormation rispecchia RDS, Compose non ha alcuna astrazione di repliche orizzontali. Il vocabolario di intento si traduce: ogni provider ha un qualche concetto di «rendi questo database altamente disponibile» e un qualche concetto di «voglio N copie di sola lettura», e la Recipe porta la traduzione per provider. Dove una realizzazione non ha un meccanismo del genere, la sua Recipe può interrompere la build indicando la chiave, come fanno helm/mariadb e compose/mariadb per entrambe le chiavi e le Recipes RDS a istanza singola per le repliche di lettura.

infra.ha.read_replicas: 0 è il default; con entrambe le chiavi ai loro default, helm/mariadb-cluster produce un MariaDB a istanza singola senza blocco replication, anziché una replica su una sola istanza. compose/mariadb esegue un solo server sull’host Docker locale, quindi infra.ha.enabled: true o un infra.ha.read_replicas diverso da zero interrompe la build indicando la chiave, e il messaggio rimanda a helm/mariadb-cluster, che fornisce failover e repliche di lettura.

Il pilastro provides

provides è l’API pubblica scritta dalla Recipe — i valori che la Recipe risolta di un Component fornisce ai chiamanti a valle tramite la loro superficie .context.uses.<alias>.provides.<provided-name> (oppure, quando il chiamante dichiara una allowlist inject: sull’edge, tramite la sua pipe .context.inject). Lo schema del Component dichiara la forma (nomi delle chiavi più tipi); il blocco provides: della Recipe associata fornisce i valori. Lo sviluppatore che scrive un Aggregate vede la forma di provides nella pagina del Component come il contratto su cui i chiamanti possono contare; l’autore della Recipe soddisfa il contratto per la specifica implementazione che incapsula.

Il rispetto del contratto è imposto come Loud Guardrail: una Recipe associata deve produrre ogni chiave di provides che il suo Component dichiara. Se la Recipe associata omette una chiave dichiarata, la build si interrompe e indica la chiave mancante, anziché non consegnare silenziosamente nulla ai chiamanti che vi fanno riferimento. Produrre chiavi aggiuntive oltre all’insieme dichiarato è consentito. Viene verificata solo la presenza delle chiavi — i valori prodotti sono stringhe opache che il compilatore fa passare, quindi i loro tipi dichiarati restano un contratto che i chiamanti leggono, non un valore che il compilatore convalida.

# Component schema declares the provides contract:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
database_name: { type: string, required: true }
provides:
host: { type: string }
port: { type: integer }
database: { type: string }
# Recipe fulfills the contract:
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: mariadb-bitnami
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:1.0.0
source:
kind: helm-oci-chart
url: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "25.0.8"
provides:
# The chart's primary Service, named by the fullnameOverride pinned below
host: "{{ .context.rendered_name }}"
port: "3306"
database: "{{ .values.database_name }}"
valuesMapping: |
fullnameOverride: "{{ .context.rendered_name }}"

La separazione della valutazione tra provides e inject. Il compilatore valuta i template provides: nella fase di valutazione dei provides, rispetto al contesto di template autosufficiente (.context.instance_id, .context.rendered_name dove il provider del nodo ne riporta uno, .values, .infra e i locals: risolti della Recipe sullo stesso nodo) — nessuno stato dei chiamanti è visibile. I locals del nodo vengono risolti nel preambolo di quella fase, prima dei suoi provides, ed è questo che consente a un template provides: di leggere .locals. Nell’idratazione degli inject, che viene eseguita subito dopo, il compilatore percorre gli edge uses: e risolve il .context.uses.<alias>.provides.<provided-name> di ogni chiamante rispetto ai valori di provides risolti. Separare le due fasi garantisce una risoluzione aciclica: provides: non può fare riferimento a un chiamante, e l’inject: di un chiamante non può fare riferimento all’output di un provider non ancora risolto finché non viene eseguita l’idratazione degli inject.

Evoluzione del contratto. Rinominare o rimuovere un campo di provides è una modifica incompatibile per ogni chiamante che si basa sul vecchio nome. La metadata.version del Component (e la dichiarazione implements: della Recipe) porta il segnale di evoluzione del contratto; i chiamanti a valle vincolati a una specifica versione major vedono una forma di provides stabile.

Approfondimento lato Recipe. Per la grammatica di authoring dei template provides:, la matrice di disponibilità per template ed esempi completi di routing tra namespace e tra regioni, consulta entities/recipe.md «Il blocco provides:» e architecture/06-data-taxonomy-and-composition.md §3.

Obblighi di presenza: features.aggrega.ai/requiredType.<label>

Un Component può dichiarare che ogni sua istanza deve avere un attachment di un dato tipo di Feature. Si tratta di un obbligo di presenza, e si scrive come annotazione ripetibile nei metadata del Component stesso:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/payment-processor
version: 1.0.0
labels:
component.aggrega.ai/type: server
annotations:
features.aggrega.ai/requiredType.audit: core/audit-logging
features.aggrega.ai/requiredType.compliance: core/pci-compliance
spec:
schema:
values:
processor_endpoint: { type: string, required: true }

La chiave è il prefisso features.aggrega.ai/requiredType. seguito da un’etichetta a tua scelta; il valore è l’URI del tipo di Feature che almeno un attachment deve avere. L’etichetta dà il nome al requisito nel messaggio diagnostico prodotto da un obbligo non soddisfatto — audit e compliance qui sopra — ed è tutto il suo compito. Le chiavi con etichetta sono il modo in cui un Component dichiara più obblighi contemporaneamente: le annotazioni sono una mappa piatta di stringhe e non possono contenere una chiave duplicata.

Il compilatore valuta ogni obbligo rispetto all’insieme finale di attachment dell’istanza, dopo che la cascata del 5-Tier Onion Model ha ripiegato ogni ambito: i blocchi features: a livello di componente e di sottosistema dell’Aggregate, i blocchi features: a livello di confine e di componente della Release e gli attachment prodotti dall’espansione guidata da annotazioni. Ognuno di essi soddisfa l’obbligo — la regola verifica ciò che è presente, mai come ci è arrivato. Così un Component il cui obbligo è soddisfatto solo perché un operatore ha impostato un’annotazione di monitoraggio nella Release passa esattamente come uno a cui lo sviluppatore ha collegato la Feature a mano.

Un obbligo che nessun attachment soddisfa interrompe la build con un messaggio diagnostico che indica l’istanza del componente, l’etichetta del requisito e il tipo richiesto. Il valore di un’annotazione è una stringa opaca, quindi nulla ne convalida la forma prima che il compilatore la legga; un valore che non è un URI di tipo di Feature, o una chiave senza etichetta dopo il prefisso, interrompe quindi la build con un messaggio diagnostico separato che indica che la dichiarazione è malformata. I due sono volutamente distinti: una dichiarazione errata si corregge nell’entità di catalogo, mentre un requisito non soddisfatto si risolve collegando la Feature — e un refuso non deve mai apparire come un requisito soddisfatto.

Entrambi i messaggi diagnostici sono documentati in errors/fatal-halts.md «Required feature not attached (funzionalità richiesta non collegata)».

Un obbligo non è uno slot. Le due superfici rispondono a domande diverse e la differenza non è cosmetica:

slot featuresSchemaobbligo di presenza
Dichiaraun punto di binding con nomeun vincolo su ciò che deve essere presente
Il nome è dereferenziabilesì — from: <slot> e .features.<slot>.provides.*no — l’etichetta dà il nome al requisito, nient’altro
Cardinalitàesattamente un riempimento per slotalmeno un attachment del tipo
Vincola il riempimentoselector, inject, sensitivenulla oltre al tipo
Soddisfatto da un attachment liberono — uno slot si riempie per nomesì — a qualsiasi ambito, con qualsiasi nome
Quando la richiesta non è soddisfattainterrompe la build quando required: true e nulla associa il nome dello slotinterrompe la build quando nessun attachment ha il tipo

Entrambe le richieste sono verificate rispetto allo stesso input — l’insieme finale di attachment dell’istanza — ed entrambe interrompono la build con un proprio messaggio diagnostico, perché gli pongono domande diverse: se un punto di binding con nome è associato, oppure se un qualche attachment ha un tipo con nome. Nessuna delle due risponde per l’altra.

Ricorri a uno slot quando la Recipe deve leggere ciò che è stato collegato. Ricorri a un obbligo quando il contratto del Component richiede che una capacità sia presente e non importa quale istanza la fornisca. Un Component di elaborazione dei pagamenti che impone core/audit-logging ottiene l’audit logging in ogni deployment, che lo sviluppatore si sia ricordato di collegarlo o meno; un Component conforme a PCI che impone core/pci-compliance non può essere distribuito senza che la Feature di conformità sia collegata da qualche parte nel deployment.

Ereditarietà. Un obbligo dichiarato su un Component di base è ereditato da ogni Component che lo estende con extends:, perché le annotazioni dei metadata si uniscono lungo la catena di extends e, per ogni chiave, prevale il figlio. Un figlio può quindi reindirizzare un obbligo ereditato dichiarando di nuovo la stessa etichetta con un tipo diverso, o aggiungere obblighi propri con nuove etichette; non può eliminarne uno dichiarato dalla base.

Socket di topologia: usesSchema

Un Component può dichiarare socket topologici tramite un blocco usesSchema: — una mappa YAML dichiarativa parallela a featuresSchema. Ogni voce nomina un socket attraverso cui il Component accetta dipendenze tra componenti e stabilisce quali forme di Component lo sviluppatore può collegare al socket. Il compilatore genera automaticamente regole di validazione JSON Schema 2020-12 dai socket dichiarati e le unifica con lo schema: del Component durante la risoluzione del Component; gli sviluppatori non scrivono a mano un pilastro uses: dentro schema:, perché la struttura deriva da usesSchema.

# Component declares the sockets it accepts:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/ai-agent/orchestrator
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
primary_datastore:
required: true
selector: "datastore.aggrega.ai/engine=vector"
inject: [env]
cache:
required: false
selector: "datastore.aggrega.ai/engine=kv"
inject: [env, file]
log_destination:
required: false
selector: "component.aggrega.ai/category=messaging"
inject: []
# Aggregate fragment — developer wires the sockets:
components:
agent:
type: core/ai-agent/orchestrator
uses:
primary_datastore:
main: { target: vector-db-instance }
log_destination:
audit: { target: audit-sink }

Forme di collegamento — un socket accetta uno o più target. Gli esempi precedenti collegano ciascun socket a un singolo target, ma un socket può diramarsi verso diversi target. Il valore di un socket si scrive in una delle due forme:

uses:
# Compact form — a list of target names. Each entry produces an edge
# whose alias equals its target. Use it for the single-target case, and
# when one socket connects to several peers of the same shape.
shards: [orders-db, customers-db, inventory-db]
# Verbose form — an alias-keyed map. Each alias maps to an entry object
# carrying its own `target:`, and may carry its own inject directives.
# Use when the connections need distinct names or per-edge inject.
databases:
primary: { target: orders-db, inject: { env: [{ in: DB_URL, from: url }] } }
replica: { target: orders-db-ro, inject: { env: [{ in: DB_REPLICA_URL, from: url }] } }

Un alias corrisponde sempre a un oggetto voce, mai a un semplice nome di target: databases: { primary: orders-db } viene rifiutato al caricamento, così come un oggetto voce che omette target:. Per collegare un singolo target senza dover inventare un alias, usa la forma compatta — primary_datastore: [vector-db-instance] — che nomina il target una sola volta e ne deriva l’alias.

Ogni voce — elemento di lista o alias di mappa — diventa un arco, conservato nell’ordine di scrittura. Il selector: del socket si applica a ogni target collegato tramite esso (ogni arco viene verificato nei tipi in modo indipendente durante l’analisi statica), e required: true significa che deve essere collegato almeno un target.

Semantica dei campi:

CampoTipoPredefinitoSignificato
requiredboolfalseSe true, lo sviluppatore deve collegare almeno una dipendenza a questo socket. Se false, il socket è facoltativo.
selectorstring—Un selettore di label, nella grammatica usata da appliesTo della Feature, che il target di ogni arco collegato tramite questo socket deve soddisfare. Viene letto come la stringa scritta qui e valutato rispetto alle label del target durante l’analisi statica: un target le cui label non lo soddisfano interrompe la build, così come un selettore che la grammatica rifiuta, indicando il requisito che non è riuscita a leggere. Un selettore vuoto non pone alcun vincolo sul target.
injectstring[]—Allowlist dei meccanismi di consegna inject consentiti (parallela a featuresSchema[].inject). Assente, o [] (vuota), significa blackbox — nessun blocco inject: consentito sulla voce uses: dello sviluppatore; la Recipe controlla la consegna. [env, file, arg] (non vuota) significa trasparente — lo sviluppatore può stabilire quale meccanismo consegna i valori provides della dipendenza. Applicato: vedi «Dove viene applicata l’allowlist inject di un socket» più avanti.
valueSchemaobject—Contratto opzionale per arco per i values scritti dallo sviluppatore su un arco collegato tramite questo socket (scritti nell’Aggregate). JSON Schema 2020-12 nelle stesse forme di scrittura di schema:. Se omesso, il socket non dichiara alcun contratto values.
infraSchemaobject—Contratto opzionale per arco per l’infra scritto dall’operatore su un arco collegato tramite questo socket (scritto nella Release). Stesse forme di scrittura di valueSchema. Se omesso, il socket non dichiara alcun contratto infra.
featuresSchemamap—Gli slot di attachment che ogni connessione collegata tramite questo socket può riempire, indicizzati per nome di slot, ciascuno con le chiavi accettate da uno slot a livello di Component. Se omesso, una connessione tramite questo socket non porta alcun attachment. Vedi «Slot riempiti da ogni connessione» più avanti.

Dove viene applicata l’allowlist inject di un socket. L’allowlist è la dichiarazione del socket su se un consumatore possa scegliere la forma di consegna e, in caso affermativo, quali forme — quindi viene verificata rispetto a ogni arco uses: collegato tramite il socket, una volta disponibili sia l’arco sia la dichiarazione del socket. Da un’unica regola derivano due rifiuti, ed entrambi interrompono la build:

  • Un arco che impone un meccanismo non elencato nell’allowlist interrompe la build, indicando il socket, il meccanismo in violazione e ciò che il socket consente. Tutti i meccanismi in violazione sull’arco vengono segnalati insieme.
  • Anche un arco che impone qualsiasi consegna tramite un socket la cui allowlist è assente o vuota interrompe la build. È la dichiarazione blackbox che fa il suo lavoro: dice «la Recipe consegna questo internamente; non imporre la consegna», e un’allowlist vuota non consente nulla invece di consentire tutto.

Il socket si legge sull’entità che lo ha dichiarato, che non è sempre il componente da cui parte l’arco: un arco scritto nel uses: di un attachment di una Feature si risolve rispetto all’usesSchema della Feature collegata, e ogni altro arco — scritto nell’Aggregate, collegato dalla Release o raggiunto tramite un sub-aggregate — rispetto a quello del Component consumatore. Un socket ereditato tramite extends si legge esattamente come uno scritto dall’entità stessa.

Un arco che non impone nulla non è interessato da nessuno dei due rifiuti, qualunque cosa dichiari il socket: leggere i valori di una dipendenza da .context.uses.<alias>.provides.<name> nella Recipe consumatrice non richiede alcun blocco inject: ed è sempre possibile. Vedi errors/fatal-halts.md per entrambe le diagnostiche.

Contratti di connessione per arco — valueSchema e infraSchema. Oltre a stabilire quali Components possono collegarsi a un socket, un socket può dichiarare quale configurazione porta ciascuna connessione. Due schemi opzionali per socket validano la configurazione con ambito di connessione su ogni arco collegato tramite il socket:

  • valueSchema è il contratto per il blocco values scritto dallo sviluppatore su un arco uses — la messa a punto per connessione che lo sviluppatore esprime nell’Aggregate (ad esempio, la dimensione di un pool di connessioni o una modalità client).
  • infraSchema è il contratto per il blocco infra scritto dall’operatore su un arco uses — il dimensionamento operativo per connessione che l’operatore esprime nella Release.

Entrambi accettano JSON Schema 2020-12 nelle stesse forme di contenuto del campo schema: — forma compatta inline, JSON Schema YAML inline o un $ref: tra documenti verso una voce di una SchemaLibrary. Sono contratti per arco, validati in modo indipendente rispetto alla configurazione di ciascun arco; non vengono composti nello schema values proprio del Component consumatore. Un socket che omette uno schema per arco per un pilastro non vi dichiara alcun contratto, e qualsiasi configurazione scritta per quel pilastro non viene validata. La configurazione per arco viene validata in forma chiusa, e la validazione tiene conto dei default in entrambi i pilastri: una chiave a cui lo schema assegna un default: conta come fornita anche quando l’autore la omette.

Un default: dichiarato inoltre si materializza, in entrambi i pilastri. Una chiave che l’autore omette raggiunge il contesto di rendering della Recipe consumatrice con il suo default dichiarato, esattamente come una chiave value o infra di un componente omessa — quindi dichiarare il default sul socket è sufficiente, e il template della Recipe non ha bisogno di alcuna espressione di fallback per essa. Un valore scritto prevale sempre sul default dichiarato, e riempie solo la chiave che fornisce: un arco che scrive una chiave del contratto di un socket riceve comunque i default dichiarati per le altre chiavi di quel contratto. I default si legano agli archi, quindi un socket lasciato non collegato non contribuisce nulla.

spec:
usesSchema:
databases:
required: true
selector: "datastore.aggrega.ai/engine=relational"
inject: [env]
valueSchema: # developer per-edge values, authored in the Aggregate
pool_size: { type: integer, minimum: 1, maximum: 100, default: 10 }
tls_mode: { type: string, enum: [disable, require, verify-full], default: require }
infraSchema: # operator per-edge infra, authored in the Release
storage_class: { type: string, default: standard }

Con quel socket dichiarato, un arco il cui Aggregate omette pool_size produce 10, e un arco la cui Release omette storage_class produce standard. Ciò che è scritto prevale chiave per chiave, all’interno del proprio pilastro: un Aggregate che imposta pool_size: 42 produce 42 mentre tls_mode viene comunque riempito con require, e una Release che imposta storage_class: gp3 produce gp3 senza toccare nessuna delle due chiavi dello sviluppatore.

Una Recipe per il Component consumatore legge la configurazione per arco risolta dalla pipe di topologia arricchita in .context.uses.<alias>.values.<key> e .context.uses.<alias>.infra.<key> — vedi vocabulary/topology-triad.md.

Slot riempiti da ogni connessione — il featuresSchema di un socket. Un socket può anche dichiarare slot di attachment, e allora ogni connessione collegata tramite esso può portare un proprio attachment in ciascuno di essi: un gateway che raggiunge diversi modelli detiene una credenziale diversa per ciascuno, perché la credenziale sta sulla connessione e non sul gateway.

spec:
usesSchema:
models:
selector: "component.aggrega.ai/category=ai-model"
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: The credential the consumer presents to the component this connection reaches.

Una connessione riempie uno slot portando un attachment con il nome dello slot nel proprio features: — sulla voce di connessione dell’Aggregate (Aggregate) o su quella della Release (Release) — e l’attachment diventa uno degli attachment del componente consumatore, con nome <alias>.<slot>.

Che cosa fa la dichiarazione, detto con esattezza:

  • I nomi degli slot sono un insieme chiuso. A differenza del featuresSchema proprio del Component, che ammette un attachment libero con qualsiasi nome, gli slot di un socket sono gli unici nomi che una connessione tramite esso può portare: qualsiasi altro nome interrompe la build al caricamento, e un socket che non dichiara alcun featuresSchema non ammette alcun attachment sulle sue connessioni. Un socket ad hoc — uno che questo usesSchema non dichiara — non dichiara slot, quindi nemmeno le sue connessioni ne portano. Ogni connessione riempie da sé i propri slot: un attachment a un ambito più ampio non si propaga mai a cascata su una connessione, e una chiave della Release che riporta il nome composto dell’attachment di una connessione interrompe la build.
  • Le altre chiavi vincolano ogni connessione allo slot. Uno slot qui accetta le stesse chiavi di uno slot a livello di Component — required, selector, inject, sensitive, description — e ogni connessione vi è vincolata singolarmente. selector viene confrontato con le label della Feature con cui una connessione riempie lo slot, e un riempimento che esso non ammette interrompe la build, con la posizione sulla voce di quella connessione nel documento che ha scritto il riempimento. required: true vale per ogni connessione collegata tramite il socket: una connessione che lascia vuoto lo slot interrompe la build, indicando quella connessione, mentre una connessione accanto che riempie lo slot passa. sensitive si legge esattamente come su uno slot a livello di Component: l’attachment che riempie lo slot è contrassegnato come sensibile nel grafo di build e in aggrega inspect. Su una connessione, come su un componente, quali valori di un attachment vengano trattenuti come sensibili lo decide solo lo schema proprio della Feature collegata. inject vincola la voce del Workload che consegna il materiale dello slot: l’attachment di una connessione non porta un proprio blocco inject: — nessuno dei due documenti ne ammette uno su una voce di connessione — quindi un Workload lo consegna nominando la connessione accanto allo slot, e quella voce è vincolata all’allowlist dello slot del socket esattamente come una voce che nomina uno slot a livello di Component è vincolata all’allowlist di quello slot.

L’usesSchema di una Feature non accetta featuresSchema: una connessione tracciata da una Feature non porta attachment, e una Feature che dichiara slot su un socket viene rifiutata al caricamento. Una credenziale di cui ha bisogno una connessione di questo tipo è uno slot nel featuresSchema proprio della Feature.

Generazione dello schema da usesSchema. Il compilatore genera un frammento base di JSON Schema 2020-12 dai socket dichiarati e lo compone con la dichiarazione schema: dell’utente — lo stesso meccanismo usato da featuresSchema. Lo schema generato non tocca mai il disco; esiste solo in memoria durante il passaggio di validazione del Component. La mappa uses: dello sviluppatore nell’Aggregate viene validata rispetto allo schema unito; il selector: di ciascun socket viene valutato rispetto alle label di ogni Component candidato durante l’analisi statica, come verifica di type-safety tra nodi.

Semantica dei selettori — il meccanismo dello schema diviso. usesSchema[].selector: è ciò che rende la topologia di Aggrega più di un semplice passaggio di stringhe non tipizzate. Un socket che dichiara selector: "datastore.aggrega.ai/engine=vector" accetta solo collegamenti a Components etichettati con la coppia chiave-valore corrispondente; un agente che tenta di collegare il proprio socket primary_datastore a un Component relational non supera lo Static Analyzer, con una diagnostica chiara di violazione del selettore. Il selettore è una stringa di selettore di label in stile Kubernetes — requisiti in AND separati da virgole nelle forme =, !=, in (...), notin (...), chiave semplice e !key — la stessa grammatica usata da appliesTo della Feature; vedi vocabulary/modifier-system.md per la grammatica e architecture/13-catalog-and-registry.md §2 «Selettori in stile Kubernetes» per la semantica del motore. Un requisito al di fuori di queste forme viene rifiutato invece di essere letto come un altro selettore: un requisito vuoto (una virgola iniziale, finale o doppia), una chiave che contiene spazi o uno qualsiasi tra =, !, (, ) e la virgola, oppure un insieme privo della parentesi di chiusura interrompe ogni build che collega un arco tramite il socket, indicando il requisito. Quindi un socket pensato per escludere i frontend si scrive selector: "tier!=frontend"; "!tier=frontend" viene rifiutato, perché ! nomina una chiave di label e nient’altro.

Socket ad hoc — che cosa si ottiene dichiarando un socket e che cosa può fare un autore senza farlo. L’autore di un Aggregate può scrivere una voce uses: sul proprio componente con un nome di socket che questo usesSchema non dichiara, anche su un Component che non dichiara alcun usesSchema. L’arco viene costruito. Il silenzio del catalogo su un socket significa che la connessione non era prevista, non che sia vietata, e la topologia dell’applicazione appartiene allo sviluppatore.

Ciò a cui rinuncia un socket ad hoc è esattamente ciò che fornisce un socket dichiarato, perché tutto risiede nella voce di usesSchema: nessun selector, quindi nulla vincola quale componente l’arco può raggiungere e la verifica di type-safety tra nodi non ha nulla da valutare; nessuna allowlist inject:; nessun valueSchema per arco, quindi i values: per arco non hanno un contratto rispetto a cui essere verificati né default dichiarati da ereditare. Rinuncia anche a infraSchema, anche se su un socket del genere quel contratto non viene comunque raggiunto: l’infra per arco si scrive su una voce di arco della Release, e una voce della Release può nominare solo un socket che il Component consumatore dichiara. Ciò che non cambia è ciò che l’arco può portare: il from: di ogni voce inject deve comunque nominare una chiave che lo schema.provides del Component target dichiara, e il target deve comunque esistere — entrambi interrompono la build come su un socket dichiarato.

Leggi «nessuna allowlist inject:» come assenza di un vincolo e non come una dichiarazione blackbox, perché le due cose si somigliano e si comportano in modo opposto. Un arco tramite un socket ad hoc può imporre liberamente la consegna: non c’è alcuna allowlist al di fuori della quale un meccanismo possa trovarsi, e nessuna entità ha promesso di gestire i valori internamente. Il rifiuto blackbox descritto sopra si applica a un socket che l’entità ha dichiarato e ha lasciato senza un’allowlist inject: — quell’omissione è una dichiarazione su una connessione che l’entità aveva previsto, e un socket ad hoc non fa alcuna dichiarazione del genere.

La consegna segue lo stesso percorso, e l’artefatto renderizzato non registra alcuna differenza. Il blocco inject di un arco ad hoc viene risolto e consegnato esattamente come quello di un socket dichiarato: ogni chiave from: viene letta dai provides valutati del target e arriva nel contesto di iniezione del nodo consumatore sotto la chiave di consegna scelta dall’autore, raggiungendo da lì l’artefatto renderizzato. C’è un solo percorso di consegna e nulla lungo di esso si dirama in base al fatto che il socket sia stato dichiarato. Ciò che un socket dichiarato può aggiungere è contenuto — i default per arco che il suo valueSchema o infraSchema inserisce — quindi, dove un socket dichiarato non porta alcun contratto del genere, lo stesso arco produce un rendering identico con entrambi i tipi di socket. La dichiarazione è un fatto relativo alla connessione, non un input di ciò che viene renderizzato.

I values: per arco su un socket ad hoc vengono accettati e raggiungono la Recipe consumatrice in .context.uses.<alias>.values, senza validazione: senza un valueSchema con cui confrontarli, nessuna chiave viene verificata e nessuna viene rifiutata. Questo non è peculiare dei socket ad hoc — un socket dichiarato che non scrive alcun contratto per il pilastro tratta la propria configurazione per arco allo stesso modo. Ciò che cambia con un socket ad hoc è che il contratto non può essere aggiunto senza dichiarare il socket. .context.uses.<alias>.infra è vuoto su un arco del genere, perché la superficie che fornisce l’infra per arco non può nominare un socket non dichiarato.

Ogni arco nel grafo emesso registra quale dei due tipi sia, così un consumatore non deve mai dedurlo, e un’organizzazione che vuole che ogni connessione passi attraverso un socket dichiarato può richiederlo come policy di governance. Dichiarare il socket qui resta la strada migliore ed è ciò che fa il catalogo della libreria standard: un socket dichiarato porta un selector che vincola quali componenti l’arco può raggiungere, un’allowlist inject:, un contratto per arco con i propri default e una descrizione — una dichiarazione verificabile di una connessione prevista, versionata insieme all’entità che la fa. La forma ad hoc è una via d’uscita, non un nuovo default. Due superfici deliberatamente non sono aperte in questo modo — gli uses di un attachment di una Feature possono nominare solo un socket che la Feature collegata dichiara, e gli uses per arco di una Release possono nominare solo un socket che il Component consumatore dichiara.

L’esempio pratico examples/adhoc-uses-socket/ costruisce entrambi i tipi di arco su un unico consumatore e mostra i due valori consegnati affiancati nell’output renderizzato, insieme all’interruzione prodotta da una chiave from: non dichiarata.

Gli errori di battitura nei nomi dei socket emergono come avviso, non come interruzione. Poiché un nome di socket non dichiarato è lecito, un nome di socket scritto male diventa una connessione ad hoc a sé stante invece di collegare il socket che l’autore intendeva — e la build resta verde mentre nulla vi transita. Il compilatore segnala come avviso un nome di socket che dista una sola modifica da un nome dichiarato da questo usesSchema, indicando entrambe le grafie — vedi errors/warnings.md «Uses-socket near-miss lint (Lint dei nomi di socket uses quasi corrispondenti)». L’avviso non cambia mai il verdetto della build; il compilatore non sorveglia il nome che un autore dà a un socket.

Il rapporto tra usesSchema e featuresSchema. Entrambi sono tabelle dichiarative ed entrambi portano un’allowlist inject: con semantica identica, ma un socket e uno slot sono cose diverse e non sono intercambiabili. usesSchema governa gli archi tra componenti — il grafo di topologia — dichiarando quali socket portano un contratto. featuresSchema governa gli slot di attachment, e uno slot è un punto di binding con nome, non un’enumerazione: un attachment con un nome che nessuno slot dichiara è lecito nel blocco proprio del componente. (Gli slot che un socket dichiara per le proprie connessioni sono l’unico insieme chiuso, come indicato sopra in «Slot riempiti da ogni connessione».) Le due superfici sono convergite su quel punto — anche la voce uses: propria di un componente con un nome di socket non dichiarato è lecita — ma restano distinte: uno slot non dichiarato è un attachment libero su un Component i cui slot dichiarati non ne sono influenzati, mentre un socket non dichiarato è un arco senza selettore e senza contratto per arco. Molti Components dichiarano entrambi; le due tabelle si compongono in modo indipendente.

Slot di associazione: featuresSchema

Un Component può dichiarare slot di associazione tramite un blocco featuresSchema. Ogni slot denomina un punto di aggancio al quale il Component si aspetta che venga associata una Feature — una password di root, una chiave API, un token di autenticazione, un binding di identità — e vincola quale Feature può occuparlo e come può essere consegnato il materiale del riempimento.

Questa sezione riguarda gli slot propri del Component. Gli slot che un socket dichiara per ciascuna connessione sono invece un insieme chiuso — vedi «Slot riempiti da ogni connessione» sotto Socket di topologia.

Dichiarare uno slot non chiude la superficie di associazione. Un autore può associare una Feature con un nome che nessuno slot dichiara, e quell’associazione è un’associazione libera: perfettamente legittima, semplicemente non legata a uno slot dichiarato. Questa apertura è ciò che consente a un’unica entità del catalogo di servire due diverse forme di deployment senza un fork del catalogo:

  • Per consumatore. Ogni istanza riempie lo slot con la propria Feature, quindi ogni consumatore ottiene la propria credenziale renderizzata.
  • Condivisa. Nessuna istanza riempie lo slot; invece una credenziale viene associata una sola volta in un ambito più ampio (un sottosistema, o un confine di Release) e si propaga a cascata a ogni componente al suo interno, così ogni consumatore viene riempito da quell’unica dichiarazione. Ciò che viene renderizzato dipende dalla realizzazione: un Secret per consumatore, ciascuno con lo stesso materiale, con una realizzazione che renderizza un Secret; nessuno con una che indirizza ogni consumatore a un Secret già esistente.

L’autore sceglie tra le due in base a ciò che associa. L’entità del catalogo è la stessa in entrambi i casi.

Su quella superficie aperta una sola forma causa un arresto: un riempimento scritto sul componente con un altro nome. Quando un’associazione scritta sul componente stesso — nel suo blocco features: nell’Aggregate, o nella voce della Release per quel singolo componente — porta un nome che nessuno slot dichiara, e la sua Feature soddisfa il selector di uno slot che nulla occupa su quel componente una volta ripiegati tutti gli ambiti, la build si arresta. È la forma che assume un riempimento destinato allo slot quando viene scritto con il nome sbagliato: lasciato così sarebbe un’associazione libera mentre lo slot resta vuoto, e uno slot opzionale lasciato vuoto produce una build verde e non consegna nulla. Il messaggio indica l’associazione, il componente, la Feature e ogni slot vuoto a cui quella Feature corrisponde, e il rimedio è associarla con il nome dello slot. Vale per ogni Feature, non solo per le credenziali. Tutto il resto sulla superficie rimane libero: un’associazione la cui Feature non corrisponde ad alcuno slot dichiarato, un’associazione aggiuntiva una volta occupato ogni slot a cui corrisponde, e un’associazione che il componente eredita da un sottosistema o da un confine di Release — quindi la forma condivisa descritta sopra non è toccata. Uno slot che non dichiara alcun selector non dice nulla su quale Feature sia destinata a esso, quindi nessuna associazione viene vincolata a esso in questo modo. L’arresto è descritto in errors/fatal-halts.md sotto «An attachment written under another name fits a slot its component leaves empty (Un’associazione scritta con un altro nome corrisponde a uno slot che il suo componente lascia vuoto)».

Le due forme si compongono, e prevale la più vicina. Un autore può fare entrambe le cose insieme: associare una Feature in un ambito più ampio perché raggiunga ogni componente in quell’ambito, e riempire lo slot sull’unico componente che ha bisogno di qualcosa di diverso. Prevale il riempimento con ambito di componente — campo per campo, quindi deve ridichiarare solo i campi che cambia e il resto continua a provenire dall’associazione più ampia. I componenti fratelli che non hanno riempito lo slot mantengono intatta l’associazione più ampia. La regola di precedenza completa, compreso il modo in cui interagisce con le associazioni guidate da annotazioni e con gli Aggregates composti, si trova in vocabulary/labels-and-annotations.md «Precedenza delle associazioni».

Definizione dello schema sul Component:

spec:
featuresSchema:
root_password:
inject: []
description: Root database password. Recipe controls delivery (Black-Box).
user_password:
inject: [env, file]
description: Application user password, auto-generated if omitted.
replication_password:
inject: []
description: Replication password for HA setups.

Semantica dei campi:

CampoTipoPredefinitoSignificato
requiredboolfalseDichiara che lo slot deve risultare occupato. La build si arresta quando nulla occupa il nome dello slot su un’istanza di questo Component, verificato rispetto all’insieme di associazioni che l’istanza possiede dopo l’intera cascata di associazioni — così un’associazione dichiarata in un ambito da cui l’istanza eredita soddisfa lo slot esattamente come un riempimento scritto sull’istanza stessa. La diagnostica indica il componente e lo slot.
injectstring[]—Allowlist dei meccanismi di consegna inject consentiti. [] (vuota) significa blackbox — la Recipe controlla la consegna internamente e il materiale non viene mai consegnato al workload. [env, file] significa trasparente — il materiale del riempimento può essere consegnato tramite i meccanismi elencati. Stessa semantica di usesSchema[].inject.
descriptionstring—Documentazione per le persone, renderizzata dall’IDE e dall’hub.
selectorstring—Selettore di label opzionale in stile Kubernetes che vincola quale Feature può riempire questo slot — l’analogo per lo slot del selector di un socket di usesSchema, con la stessa grammatica e lo stesso motore nativo di corrispondenza delle label. Viene valutato rispetto alle label proprie della Feature associata durante l’analisi statica; un riempimento le cui label non lo soddisfano causa un arresto, e lo stesso vale per un selettore che la grammatica rifiuta, indicando il requisito che non è riuscita a leggere. Omettilo per non porre alcun vincolo sul riempimento.
sensitiveboolfalseDichiara che qualunque cosa occupi questo slot gestisce materiale segreto. È un’affermazione sul punto di aggancio, non su un particolare riempimento; vedi «Dichiarare uno slot sensibile» più avanti.

Uno slot vincola quale riempimento può occuparlo, non ciò che il riempimento configura. Deliberatamente non esiste un contratto values o infra a livello di slot: lo schema: proprio della Feature associata possiede quei pilastri, così ogni contratto ha esattamente una sede.

Il selector dello slot è il modo in cui un Component restringe quale Feature può riempire uno slot — ad esempio a una Feature di credenziale specifica di un provider (feature.aggrega.ai/kind=secret, provider=helm) — senza nominare una FeatureRecipe, esattamente come un selettore di socket di usesSchema restringe la destinazione di un arco di dipendenza. Il compilatore valuta il selettore rispetto alle label della Feature associata e a nient’altro: legge le label che il riempimento porta e riporta se il selettore le ammette. Quali label abbia senso richiedere è una scelta di authoring del catalogo, non una regola che il compilatore impone.

I refusi nei nomi degli slot emergono come avviso, non come arresto. Poiché un nome di associazione non dichiarato è legittimo, un nome di slot scritto male diventa un’associazione libera anziché riempire lo slot che l’autore intendeva. Il compilatore segnala un nome di associazione che dista una sola modifica da un nome di slot dichiarato con un avviso che indica entrambe le grafie — vedi errors/warnings.md «Attachment-slot near-miss lint (Lint dei quasi-errori negli slot di associazione)». L’avviso non cambia mai il verdetto della build; il compilatore non controlla come un autore chiama un’associazione. Un nome a una modifica di distanza da uno slot il cui selector è soddisfatto dalla Feature dell’associazione non genera alcun avviso: dove quello slot resta vuoto, è invece l’arresto descritto sopra a segnalare l’associazione, e dove qualcos’altro occupa lo slot, l’associazione è una normale associazione aggiuntiva.

Dichiarare uno slot sensibile

sensitive: true su uno slot esprime la richiesta propria del consumatore: qualunque cosa occupi questo punto gestisce materiale segreto.

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]
description: "Optional database password credential."

Si tratta di un’informazione realmente diversa dal sensitive: true di una foglia dello schema, non di un suo duplicato di comodo, e il catalogo della libreria standard ha bisogno di entrambi. Una credenziale referenziabile pubblica provides.name e provides.key — il localizzatore della risorsa e la chiave dei dati al suo interno — e nessuno dei due è sensibile: il nome di un Secret Kubernetes è pubblico, e lo è anche la chiave al suo interno. Eppure lo slot che quella credenziale riempie gestisce senza dubbio materiale segreto. Una foglia dice questo dato è materiale segreto; uno slot dice questo punto di aggancio gestisce materiale segreto; le due affermazioni riguardano cose diverse e possono valere indipendentemente.

La conseguenza pratica è che la richiesta viaggia con il punto di aggancio anziché con il riempimento. Una Feature che non dichiara alcuna foglia sensibile — perché il motore di destinazione possiede la credenziale e l’autore non scrive nulla — occupa comunque uno slot sensibile come associazione sensibile, perché lo slot lo ha dichiarato. Vale anche il contrario: un riempimento che dichiara una foglia sensibile è un’associazione sensibile anche quando occupa uno slot che non ha fatto tale dichiarazione, o quando è un’associazione libera che non occupa alcuno slot.

La dichiarazione segue la cascata delle associazioni anziché un singolo blocco scritto. La richiesta di uno slot si applica a qualunque riempimento risulti occuparlo dopo il ripiegamento di tutti gli ambiti, quindi un riempimento a livello di componente che sostituisce uno più ampio eredita la richiesta invariata.

sensitive su uno slot ha lo stesso limite della parola chiave a livello di foglia — annota, non cifra, non valida, non rifiuta, non impone un meccanismo di consegna né cambia un byte renderizzato. La formulazione completa è in vocabulary/compact-form-authoring.md «Cosa la parola chiave non fa».

sensitive e compliance.aggrega.ai/data-class sono due assi diversi, documentati l’uno accanto all’altro e mai confusi. sensitive è un booleano su una foglia o su uno slot: questo dato, o questo punto di aggancio, gestisce materiale segreto. compliance.aggrega.ai/data-class è una label graduata su un intero nodo — public, internal, restricted — che dà ai dati custoditi da un componente un’identità di governance. Uno è per dato e binario, l’altra per nodo e ordinata; nessuno dei due sostituisce l’altro, e un’entità può portarli entrambi. La label è trattata in vocabulary/labels-and-annotations.md e in architecture/08-credential-model.md «Governance dei dati attorno alle credenziali».

Proiezione dello schema da featuresSchema

Gli slot dichiarati vengono proiettati in un frammento JSON Schema 2020-12 che descrive la forma del blocco di associazioni. Rispetto a esso vengono validati due tipi di riempimento: il blocco di associazioni di un componente fornito da un modulo importato, una volta costruita la composizione che lo importa, e un’associazione dichiarata a un ambito più ampio, rispetto allo slot di ciascun componente che raggiunge. Il blocco di associazioni di un componente dichiarato dall’Aggregate stesso viene invece misurato dallo schema del documento dell’Aggregate e dall’allowlist inject dello slot (vedi sotto), e il frammento è modellato in modo che entrambi arrivino allo stesso verdetto su qualsiasi riempimento. La proiezione non tocca mai il disco; esiste solo in memoria, e lo schema: di un Component non deve mai scrivere a mano il pilastro delle associazioni.

featuresSchema in ingresso:

featuresSchema:
root_password:
inject: []
user_password:
inject: [env, file]

Frammento proiettato (in memoria; rappresentazione in forma compatta):

# The OUTER object is open: an attachment under a name no slot declares is
# admitted, because a free attachment is legal authoring.
root_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
# inject admits only an empty block — inject: [] means the Recipe controls
# delivery, so a fill may name no mechanism
inject: {}
user_password:
type: { type: string }
description: { type: string }
values:
type: object
additionalProperties: true
inject:
env: { type: array }
file: { type: array }
# arg is absent — not in the inject allowlist

Le due profondità sono indipendenti. L’oggetto esterno è aperto, quindi uno slot dichiarato non vieta mai le associazioni che l’entità non ha enumerato. Il frammento proprio di ciascuno slot dichiarato è chiuso, quindi un riempimento che occupa uno slot dichiarato resta comunque vincolato alla forma di quello slot.

Il frammento descrive solo la FORMA. Non contiene alcuna affermazione su quali slot debbano essere occupati, perché uno slot marcato required può essere occupato da un’associazione che arriva a cascata da un ambito più ampio — il che lascia vuoto il blocco descritto da questo frammento. Il requisito viene quindi verificato rispetto all’insieme di associazioni che un componente ottiene alla fine anziché rispetto a ciò che dichiara un singolo blocco, e le due domande non si contraddicono mai perché solo una delle due viene posta al blocco scritto.

Le chiavi consentite rispecchiano le chiavi che un’associazione può portare ovunque, quindi una chiave legittima su un’associazione libera resta legittima sul riempimento di uno slot. Ogni meccanismo di consegna in allowlist è una lista di voci di consegna — la stessa forma che inject: assume ovunque; lo slot restringe quali NOMI di meccanismo possono comparire, non l’aspetto di una voce.

Dove viene applicata l’allowlist inject

L’allowlist vincola entrambi i lati dello slot, in due passaggi diversi.

Rispetto al Workload della Recipe, nel passaggio di rendering: un Workload che fa riferimento a uno slot tramite le voci di associazione del proprio container deve nominare uno slot che l’entità dichiara, e deve selezionare un meccanismo di consegna consentito dall’allowlist inject dello slot; un riferimento a uno slot blackbox (inject: []), a un meccanismo esterno all’allowlist, o a uno slot che l’entità non ha mai dichiarato arresta la build. La diagnostica indica la Recipe, il percorso del container e lo slot incriminato, ed è classificata come errore del catalogo — è la Recipe ad aver sbagliato.

Rispetto all’associazione propria dell’Aggregate, quando le sue associazioni vengono risolte e prima di qualsiasi rendering: un blocco inject: su un riempimento che occupa uno slot dichiarato può nominare solo meccanismi consentiti dall’allowlist dello slot, e uno slot blackbox non ne consente nessuno — la sua allowlist vuota dice «la Recipe consegna questo internamente; non imporre la consegna», e scrivere una consegna per esso arresta la build. La diagnostica è posizionata sull’associazione e indica lo slot e il meccanismo incriminato, insieme ai meccanismi che lo slot consente, se ne consente; è classificata come errore dello sviluppatore, perché è l’Aggregate ad aver sbagliato. Un blocco inject: {} vuoto non nomina alcun meccanismo, quindi non impone alcuna consegna ed è accettato su ogni slot, compreso uno slot blackbox — allo stesso modo su un componente dichiarato dall’Aggregate, su uno fornito da un modulo importato e su un’associazione dichiarata a un ambito più ampio. Un’associazione libera — con un nome che nessuno slot dichiara — non ha alcun vincolo di questo tipo, perché l’allowlist appartiene allo slot e non al blocco.

Il flusso end-to-end attraverso la pipeline di compilazione — come un’associazione dell’Aggregate si collega a una Feature di credenziale (come core/secret-value) e poi a una FeatureRecipe specifica del provider che consegna la credenziale al workload in esecuzione — è sviluppato in examples/05-credential-features.

Una chiave che il chiamante presenta e una chiave che il server verifica

Quando un componente ne chiama un altro che verifica una chiave, ciascuna estremità tiene la chiave dal proprio lato, in uno slot che dichiara essa stessa. Questa è una convenzione che il catalogo della libreria standard segue; il compilatore non ne applica nulla — verifica gli slot di ciascun componente rispetto alle associazioni proprie di quel componente, ne fa passare le stringhe e non confronta mai ciò che un componente possiede con ciò che ne possiede un altro.

  • La chiave che un chiamante presenta è del chiamante. Si trova in uno slot che il socket del chiamante dichiara per ciascuna connessione — vedi «Slot riempiti da ogni connessione» sopra — quindi un chiamante che raggiunge più destinazioni tiene una chiave per ciascuna. Il socket model di core/ai-agent/crewai dichiara quello slot come credential, e le sue Recipes consegnano qualunque cosa lo riempia come OPENAI_API_KEY. Anche i socket models di core/gateway/litellm, core/gateway/kong e core/gateway/apisix lo dichiarano, e le loro Recipes consegnano la chiave di ciascuna connessione in una variabile propria, chiamata secondo l’alias della connessione, così ogni modello servito dal gateway ha una chiave propria. Una chiave che un Component dichiara invece in uno slot proprio è un’unica chiave per ogni connessione che stabilisce.
  • La chiave che un server verifica è uno slot proprio del server. core/ai-model/vllm, core/ai-model/tei e core/ai-model/tgi dichiarano ciascuno un api_key opzionale, e ciascuna delle loro Recipes consegna qualunque cosa lo riempia come la variabile da cui il server legge la propria chiave. Il modello e il gateway LiteLLM dichiarano api_key per la chiave che LiteLLM chiama master key.
  • Nessuna delle due estremità vede le associazioni dell’altra. Un’associazione su una connessione è una delle associazioni del chiamante e raggiunge solo il rendering del chiamante, e l’output renderizzato di un server è lo stesso qualunque cosa portino le connessioni che lo raggiungono. Uno slot marcato required è dovuto dal componente che lo dichiara, mai dai componenti collegati a esso, e riempire lo slot di un’estremità non riempie nulla sull’altra — quindi dichiarare la chiave su entrambe le estremità è il minimo e non un duplicato.
  • Entrambe le estremità leggono un unico parametro, quindi la chiave che il chiamante presenta e la chiave che il server verifica non possono essere scritte in modo divergente.
# Aggregate fragment — one parameter feeds both ends
spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
agent:
type: core/ai-agent/crewai
# values (role, goal, backstory, …) elided
uses:
model:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

Un server che verifica una sola chiave non può distinguere i propri chiamanti: vLLM, TEI e TGI verificano ciascuno una singola chiave, quindi ogni chiamante presenta la stessa, per quante connessioni raggiungano il server. Se le due estremità fanno riferimento a un unico secret o ne tengono ciascuna uno proprio dipende da dove ciascun provider risolve un secret per riferimento, e il Manifest sceglie la realizzazione di ciascuna estremità — Modello delle credenziali sviluppa entrambi i casi.

Una credenziale che un componente tiene per sé — una chiave con cui firma le proprie sessioni, ad esempio — è uno slot del proprio featuresSchema: come qualsiasi altro. Una password che presenta a un datastore raggiunto tramite uno dei suoi socket è la chiave del chiamante descritta sopra, quindi si trova su quella connessione come credential: il socket backend di core/gateway/kong la dichiara, e le sue Recipes di sintesi del workload la consegnano come KONG_PG_PASSWORD, e il socket cache_store di core/gateway/litellm la dichiara per la password che la sua cache semantica presenta allo store, consegnata come REDIS_PASSWORD. Quando una connessione presenta una coppia — un identificatore di chiave di accesso e il relativo segreto — la metà segreta è credential e la metà identificatore credential_id, come sul socket store di core/ai-agent/agenta-api.

Auto-iniezione: spec.inject

Un Component può dichiarare un array di primo livello spec.inject: che elenca i meccanismi di consegna consentiti per l’auto-iniezione. Quando è presente, gli sviluppatori possono usare un blocco inject: a livello di component nell’Aggregate per iniettare le chiavi values: o provides: del Component direttamente nella sua pipe di consegna (le variabili d’ambiente del suo container, i file montati o gli argomenti del processo). Quando spec.inject: è assente o vuoto, l’auto-iniezione a livello di component è vietata: la Recipe controlla tutto il cablaggio interno, secondo il pattern Black-Box che usesSchema[].inject: [] e featuresSchema[].inject: [] applicano rispettivamente alla consegna tra component e alla consegna delle credenziali.

# Component declares its self-inject allowlist:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/web-server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
inject: [env, file]
schema:
values:
log_level: { type: string, default: info }
tls_enabled: { type: boolean, default: false }
provides:
health_endpoint: { type: string }
# Aggregate fragment — developer dictates self-inject delivery:
components:
api:
type: core/web-server
values:
log_level: debug
tls_enabled: true
inject:
env:
- in: LOG_LEVEL
value: '{{"{{"}} .values.log_level }}'
- in: TLS_ENABLED
value: '{{"{{"}} .values.tls_enabled }}'
file:
- in: /etc/web/health-probe
from: health_endpoint

Ogni template value: si apre con {{"{{"}} anziché con {{. L’intero testo dell’Aggregate viene letto una volta come template, per l’interpolazione dei parametri, prima che venga eseguita la risoluzione dell’auto-iniezione, e a quel punto .values non esiste; l’escape rimette {{ al suo posto perché la risoluzione dell’auto-iniezione lo valuti. Vedi Testo che contiene le proprie doppie graffe.

Semantica del campo. spec.inject: è un array di nomi di meccanismi. Sono definiti tre valori:

  • env — variabili d’ambiente nel container.
  • file — percorsi di file montati.
  • arg — argomenti della riga di comando del processo.

La semantica rispecchia esattamente usesSchema[].inject e featuresSchema[].inject: stesso vocabolario, stesso pattern Black-Box quando il campo è omesso, stessa forma di authoring sul lato dell’Aggregate. La differenza è la sorgente: usesSchema[].inject regola come i provides di una dipendenza tra component confluiscono nella pipe di consegna del consumatore; featuresSchema[].inject regola come una credenziale raggiunge un container; spec.inject regola come i values e i provides del Component stesso raggiungono il container del Component stesso.

Disciplina di authoring. Un Component core/web-server che dichiara spec.inject: [env, file] sceglie la consegna trasparente: l’autore dell’Aggregate stabilisce quali nomi di variabili d’ambiente trasportano quali valori. Un Component che dichiara spec.inject: [] (o che omette il campo) mantiene la consegna opaca: il valuesMapping: della Recipe decide quali campi confluiscono in quali variabili del container, e lo sviluppatore non può sovrascriverlo nell’Aggregate. Il pattern Black-Box si addice ai Components con un contratto stabile (un Component core/postgres-db la cui Recipe sa come collegare la password del DB a una variabile d’ambiente POSTGRES_PASSWORD); il pattern trasparente si addice ai Components in cui l’intento dello sviluppatore nomina legittimamente dettagli di consegna (un core/web-server la cui applicazione legge LOG_LEVEL da un nome di variabile non standard che lo sviluppatore vuole personalizzare).

Modalità di errore. Un Aggregate di uno sviluppatore che usa un blocco inject: su un Component il cui spec.inject: manca o è vuoto interrompe la build al caricamento del workspace («Self-inject on a component without an allowlist» (Auto-iniezione su un component senza lista di consentiti)). Un blocco inject: che usa un meccanismo non presente nella lista di consentiti interrompe la build con la stessa condizione, indicando il meccanismo e quelli consentiti dalla lista («Self-inject mechanism not in the component’s allowlist» (Meccanismo di auto-iniezione non presente nella lista di consentiti del component)). Anche una collisione di chiavi di consegna tra auto-iniezione, iniezione tra component e iniezione di credenziali interrompe la build («Duplicate delivery key across inject sources» (Chiave di consegna duplicata tra sorgenti di iniezione)). Vedi errors/fatal-halts.md per la forma del messaggio di ciascun errore.

Authoring del catalogo: estendere i Components di base

I Platform Architects usano la parola chiave extends per stratificare interfacce specializzate sopra baseline aziendali o della community. L’estensione compone la struttura ed eredita i pilastri dei dati per intero. Il compilatore percorre la catena dalla base verso il basso; le due metà si comportano in modo diverso, e la differenza è l’intero modello di authoring.

Cosa compone l’estensione. Queste superfici si fondono lungo la catena: il Component che estende prevale chiave per chiave e le liste si concatenano a partire dalla base, senza duplicati:

SuperficieCome si compone
metadata.labelsfusione chiave per chiave; il valore del Component che estende prevale su una chiave condivisa
metadata.annotationsfusione chiave per chiave, con la stessa precedenza: ecco perché il mandato di presenza di una base raggiunge ogni Component che la estende
spec.featuresSchemaunione degli slot di collegamento; uno slot che il Component che estende ridichiara sostituisce la voce della base con quel nome
spec.usesSchemaunione dei socket di topologia, con la stessa regola di sostituzione per nome
spec.injectle due liste di consentiti per l’auto-iniezione si concatenano, prima le voci della base, con i duplicati scartati
spec.assertionsle regole con nome si accumulano, prima quelle della base, e questa sola superficie non ammette alcuna sostituzione per nome; vedi «L’ereditarietà delle asserzioni è additiva» più sotto

Un socket aggiunto dal Component che estende può avere valueSchema e infraSchema propri per ciascun arco; sono contratti sugli archi di quel socket, non aggiunte ai pilastri del Component stesso.

Il resto di metadata: resta al documento che lo dichiara. labels e annotations sono gli unici metadati che scendono lungo la catena. name, version, description, maintainers, license, repository, home e keywords appartengono al Component che estende e si leggono esattamente come li ha scritti: un Component che omette description: non ne ha alcuna, anziché prendere in prestito quella della base. Identità e provenienza appartengono al documento che stai leggendo, così un wrapper non viene mai scambiato per ciò che avvolge.

Cosa l’estensione eredita per intero. I tre pilastri dei dati — values, infra, provides — non vengono composti. Un Component che estende non scrive alcun contenuto dei pilastri: scrive il marcatore letterale schema: inherited e riceve il blocco schema: della base esattamente come la base lo ha scritto. Lungo una catena di qualsiasi profondità, ogni Component della catena porta invariato il blocco della radice, quindi aggrega inspect --resolved su una foglia mostra gli stessi pilastri della radice.

Lo schema Component pubblicato stabilisce quale dei tre esiti possibili è legale e rifiuta gli altri due al caricamento del documento, con una diagnostica diversa per ciascuno, perché sono errori diversi:

  • extends: con contenuto dei pilastri sotto schema: viene rifiutato. Il contratto del Component è quello della sua base; un secondo contratto divergente non ha dove stare.
  • extends: con schema: omesso del tutto viene rifiutato. Un’omissione impedirebbe a chi legge di distinguere un blocco di pilastri ereditato da uno dimenticato.
  • schema: inherited senza extends: viene rifiutato. Il marcatore indica da dove provengono i pilastri, e questo Component non ha una base da cui prenderli.

Un Component che estende non può rimodellare l’insieme delle chiavi. Non dichiara chiavi dei pilastri, quindi non può nascondere, eliminare o ritipizzare una chiave dichiarata dalla sua base, e non ne aggiunge di proprie. Una nuova chiave dei pilastri appartiene al Component il cui contratto la possiede. Qualunque cosa esponga la base, tutto ciò che la estende la espone in modo identico.

Una specializzazione restringe tramite assertions:. Quando una specializzazione deve ammettere meno di quanto ammettano i pilastri della sua base — un intervallo numerico più stretto, un sottoinsieme di un enum: ereditato — lo dichiara nel proprio blocco assertions:: una regola lì rifiuta un valore che lo schema ereditato accetta. È questa la superficie in cui vive il restringimento; vedi «Il blocco assertions:» più sotto.

Questi ultimi due paragrafi sono un’unica regola, e ciascuna metà da sola trae in inganno: restringere l’insieme delle chiavi è impossibile, restringere i vincoli è possibile. Se si prende solo la prima, si conclude che una specializzazione non può vincolare nulla; se si prende solo la seconda, si conclude che può rimodellare il contratto. Nessuna delle due cose è vera: l’insieme delle chiavi è fissato dalla base, e i valori ammessi al suo interno possono essere ristretti tramite un predicato.

L’ereditarietà delle asserzioni è additiva, e l’accumulo parte dalla radice. Un’istanza di un Component che estende viene verificata rispetto a ogni regola dichiarata dalla sua catena oltre che alle regole dichiarate dal Component stesso, valutando per prime quelle ereditate. Lungo una catena di qualsiasi profondità le regole si accumulano dalla radice della catena verso il basso, quindi quando un’istanza violerebbe più di una regola, viene segnalata quella dichiarata più in alto nella catena: risponde per primo il contratto più fondamentale.

Poiché l’ereditarietà aggiunge anziché sostituire, un Component che estende non può riutilizzare il nome di una regola ereditata per dichiarare una regola diversa: ciò viene rifiutato quando la catena di extends viene risolta rispetto al catalogo, con una diagnostica che nomina entrambi i Components e il nome condiviso. Il controllo richiede di avere a disposizione il Component di base, quindi viene segnalato quando il catalogo viene validato o quando una build risolve la catena: validare da solo il documento che estende non può rilevarlo. Il nome della regola è un identificatore stabile, quindi né eliminare la regola della base né rinominarla silenziosamente è un’opzione, e la correzione consiste in una rinomina nel Component che estende. Ripetere una regola ereditata byte per byte con il suo stesso nome è accettato come l’operazione nulla che è.

aggrega pull recupera la base. Una base è una dipendenza di ogni Release che raggiunge un Component che la estende, indipendentemente dal fatto che qualcos’altro la nomini. aggrega pull segue ogni extends: fino alla fine della catena, recupera dal registry una base che nessuna directory di catalogo contiene e registra ogni base nel lockfile della Release, referenziata dallo spec.extends del Component che la nomina; una build legge la base da lì. Così un Manifest mappa il tipo proprio di un wrapper e nulla di più — la base ha bisogno di una propria riga di mappatura solo dove un Aggregate dichiara anche un’istanza della base. Un aggrega validate sull’intero catalogo legge una base allo stesso modo, quindi lì una base pubblicata in un registry viene rifiutata, indicando aggrega pull, finché un pull non l’ha recuperata.

Vedi architecture/13-catalog-and-registry.md §3 per i formati del contenuto degli schemi.

Esempio A: il Component di base (la baseline aziendale) Il Platform Architect definisce un server aziendale di base. Questa base imposta l’etichetta obbligatoria della primitiva cloud operativa e stabilisce i vincoli di sicurezza nello schema. Poiché il blocco dei pilastri viene ereditato invariato, ogni vincolo qui definito raggiunge ciascun Component che estende esattamente come è stato scritto.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/base-enterprise-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
inject: [env]
schema:
values:
# The corporate baseline constraint. Every Component extending this base
# receives this leaf verbatim; none of them can restate or loosen it.
tls_enabled: { type: boolean, enum: [true], default: true }
# An open range at the baseline. A specialization that needs a tighter
# bound expresses it as an assertion, not as a redeclared schema leaf.
timeout_ms: { type: integer, default: 5000 }
assertions:
# A baseline invariant. It is evaluated for instances of this Component AND
# for instances of every Component extending it, under this same name.
audit-window-is-observable: |
{{- if lt (int .values.timeout_ms) 100 -}}
{{- fail "the corporate baseline needs timeout_ms of at least 100 so requests are observable" -}}
{{- end -}}

Esempio B: il Component che estende (specializzare la baseline) Un gateway viene specializzato a partire da quella baseline. Prende per intero i pilastri della base, aggiunge una struttura propria — un’etichetta, un meccanismo di auto-iniezione, un socket di topologia con uno slot di collegamento — e restringe il timeout ereditato tramite un’asserzione. Non ripete la regola audit-window-is-observable della baseline: quella regola è ereditata e viene valutata per prima, quindi un’istanza di questo gateway deve soddisfare entrambi i limiti, almeno 100 e al massimo 2000.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/gateway/kong
version: 1.0.0
labels:
# Every Component declares the reserved base-ontology key, including one
# that extends: the envelope requires it on the document itself.
component.aggrega.ai/type: "server"
api.aggrega.ai/protocol: "http" # merged with the base's labels
spec:
extends: core/base-enterprise-server
schema: inherited # values, infra and provides are the base's, verbatim
inject: [file] # concatenates with the base's [env] -> [env, file]
usesSchema: # a socket of its own; the base declared none
backend:
required: true
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]
featuresSchema: # a slot each connection through it fills
credential:
sensitive: true
inject: [env]
description: Password the gateway presents to the configuration backend this connection reaches.
assertions:
# The tightening. The inherited schema admits any integer for timeout_ms;
# this gateway admits only 2000 or less, so the rule rejects a value the
# inherited pillar block would accept.
timeout-within-gateway-budget: |
{{- if gt (int .values.timeout_ms) 2000 -}}
{{- fail "the gateway must answer within 2000ms: set timeout_ms to 2000 or less" -}}
{{- end -}}

Per la Recipe che implementa questa interfaccia core/gateway/kong su un chart Helm fisico, vedi entities/recipe, Esempio C (kong-gateway).

Il blocco assertions:

Component.spec.assertions: è una mappa opzionale di regole con nome che esprimono invarianti architetturali del contratto del Component: regole tra più campi che l’authoring dello sviluppatore deve soddisfare indipendentemente da quale Recipe si leghi al Component. Ogni chiave è un identificatore di regola che compare nel messaggio di errore; ogni valore è il corpo di un template Go. Il compilatore le valuta per ogni istanza dopo la validazione dello schema e prima del binding della Recipe, nell’ordine in cui sono scritte, e la prima regola che fallisce interrompe la build con il messaggio di errore proprio di quella regola, secondo il contratto Loud Guardrails.

spec:
assertions:
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt (int .values.secondary.replicaCount) 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}

La regola qui sopra è una proprietà del contratto del Component: qualunque Recipe si leghi (chart Bitnami, alternativa scritta a mano, implementazione futura), la modalità di replica richiede almeno due repliche secondarie.

assertions: è il punto in cui un Component che estende restringe. Un Component che usa extends: su una base eredita alla lettera il blocco dei pilastri della base e non dichiara alcun contenuto dei pilastri proprio, quindi una specializzazione che deve ammettere meno di quanto ammetta lo schema ereditato esprime qui la restrizione come predicato anziché come foglia di schema ristretta: una regola che rifiuta un valore che i pilastri ereditati accettano. La coppia di esempi e il comportamento completo dell’ereditarietà si trovano in «Authoring del catalogo: estendere i Components di base» più sopra: le regole si accumulano lungo la catena a partire dalla radice, e riutilizzare il nome di una regola ereditata per una regola diversa viene rifiutato anziché consentire che la sostituisca.

Il compilatore non verifica se due regole possono essere soddisfatte entrambe. Una regola è un predicato di template, non un vincolo su cui il compilatore ragiona, quindi una coppia di regole che nessun valore può soddisfare contemporaneamente — una base che richiede almeno 100 e una specializzazione che richiede al massimo 50 — non produce alcun avviso al caricamento del catalogo. Emerge nel modo ordinario: viene scritta un’istanza, la build si interrompe sulla prima delle due che scatta, e il messaggio di quella regola è ciò che l’autore legge. Non aspettarti che una contraddizione venga segnalata in anticipo; verifica il restringimento di una specializzazione rispetto a ciò che la sua base già richiede.

Usa assertions: per regole autenticamente tra più campi. I vincoli su un singolo campo (intervallo, pattern, enum) appartengono alle parole chiave di schema:; i predicati personalizzati su un singolo campo appartengono al validate: della forma compatta; la forma condizionale (se si applicano i vincoli di un sottoalbero) appartiene a when:. Per la grammatica di authoring completa — i campi del contesto del template, la convenzione del messaggio {{ fail }}, la fase di valutazione ed esempi svolti che coprono i ruoli di Component e Recipe — vedi templates/assertions-block.md.