Contrat des plugins Wasm
Le pipeline de compilation d’Aggrega comprend des points de socket désignés où des plugins WebAssembly (Wasm) étendent le comportement du compilateur : les quatre rôles du socket de gouvernance, parmi lesquels un Mutation Gate à la construction de la topologie et un Validation Gate à l’analyse statique ; un pipeline de plugins post-rendu pour les étapes de FeatureRecipe et de Recipe ; un socket de rendu des fournisseurs ; un socket de parseur ; un socket d’importateur ; et un socket de linting hors bande. Cette page documente le contrat public des plugins Wasm : quels sockets existent, ce que chaque socket consomme et produit, où chaque socket se situe dans le pipeline de compilation, et la sandbox dans laquelle s’exécute chaque plugin.
Cette page couvre les sockets — les points du pipeline et leurs formes d’entrée/sortie. Pour le plugin — l’entité Plugin, les déclarations de capacités par export, les limites d’exécution et le cycle de vie publish→pull→build — voir le guide du développeur de plugins Wasm.
Aggrega embarque un runtime hôte Wasm — Extism au-dessus du moteur Wazero — qui charge et exécute les plugins derrière un pare-feu de pureté AOT : l’hôte n’accorde à un guest aucune capacité ambiante — pas de réseau, pas de système de fichiers, pas d’environnement, stdio ignoré, une horloge murale observable figée sur un instant invariant d’un build à l’autre — si bien qu’un plugin ne peut pas rompre les garanties ahead-of-time du compilateur. La surface complète des capacités — la règle des modules d’import au chargement, les refus au moment de l’instanciation et les fonctions hôtes sélectionnées — est le contrat de la sandbox ci-dessous. Les auteurs de Plugin ciblent l’hôte au moyen du PDK en trois langages (Go, Rust, TypeScript). aggrega lint invoque le socket de linter — le linter de publication standard — par l’intermédiaire de l’hôte. aggrega build invoque les rôles du socket de gouvernance actifs au moment du build lorsqu’un espace de travail les configure : le rôle annotation-transform pendant la résolution et le rôle label-transform à la construction de la topologie (tous deux façonnent la sortie), plus le verdict IR à l’analyse statique et le verdict de rendu sur les artefacts rendus. Chacun est sans effet lorsqu’aucun plugin n’est rattaché à ce rôle, si bien qu’un build sans configuration de gouvernance est inchangé. aggrega build invoque aussi le pipeline: de la FeatureRecipe et de la Recipe dans le pipeline de plugins qui clôt le rendu — chaque étape déclarée s’exécute par l’intermédiaire de l’hôte sur l’ensemble des documents rendus, en appliquant les correctifs RFC 6902 de l’étape et en émettant ses effets de bord. Voir État du langage → Phases du pipeline de compilation.
Le contrat de la sandbox
Chaque socket invoque son plugin à travers la même sandbox de l’hôte. La sandbox comporte deux couches indépendantes — une vérification structurelle au chargement et un refus des capacités à l’instanciation — qui, ensemble, définissent ce qu’un plugin peut atteindre, ce qu’il ne peut pas atteindre et ce dont il est responsable.
La règle des modules d’import (au chargement). Le chargeur parcourt la section d’import du binaire du plugin et n’admet des imports de fonctions que sous trois espaces de noms de module : wasi_snapshot_preview1 (le runtime WASI preview-1 auquel se lie le runtime d’un langage guest), extism:host/env (l’ABI du runtime Extism — les intrinsèques de mémoire et d’E/S propres au PDK) et extism:host/user (les fonctions hôtes sélectionnées d’Aggrega). Un guest peut importer n’importe quel nom de fonction sous un module autorisé ; un import sous tout autre module désigne une surface que l’hôte ne fournit pas, et le plugin est rejeté au chargement avec un diagnostic qui nomme le module et l’import. La règle ne censure délibérément pas les noms de fonctions WASI individuels : le runtime d’un langage lié statiquement importe des fonctions de système de fichiers et de socket que ses chemins de code actifs n’appellent jamais — tirées transitivement par des dépendances — et nommer un import n’accorde rien. C’est le refus des capacités à l’instanciation, et non la censure des imports, qui garantit l’absence d’E/S.
Aucune capacité ambiante (instanciation). L’hôte instancie le guest avec un comportement WASI réel et aucune autorité ambiante :
- pas de système de fichiers — aucun répertoire pré-ouvert, si bien qu’un appel au système de fichiers échoue à la frontière de l’appel ;
- pas de sockets réseau ;
- un environnement vide ;
- stdio ignoré — rien de ce que le guest écrit sur stdout ou stderr n’atteint les flux de l’hôte ;
- une horloge murale observable figée, fixée sur un instant invariant d’un build à l’autre, si bien qu’un guest qui lit l’heure ne peut pas faire fuiter l’heure du build dans sa sortie ;
- une horloge monotone réelle qui avance — le runtime d’un langage guest en a besoin pour démarrer, et le temps monotone mesure une durée écoulée, pas un instant de l’horloge murale ;
- une entropie réelle de l’hôte — une entropie épinglée stabiliserait la graine de hachage interne du runtime d’un langage et masquerait le non-déterminisme du guest au lieu de le laisser apparaître sous forme de sorties différentes ;
- un unique nom de programme synthétique comme argv.
Un appel d’E/S qu’un guest effectue réellement — ouvrir un fichier, se connecter à un socket — échoue à la frontière de l’appel. C’est le modèle de sécurité propre à WASI, fondé sur les capacités : la sandbox refuse la capacité au lieu de surveiller le code.
Les entrées n’arrivent que par la charge utile et les fonctions hôtes sélectionnées. Un plugin reçoit tout ce qu’il rend ou évalue dans la charge utile que transporte son socket — des projections du graphe et des nœuds, des valeurs et un contexte de rendu. L’encodage dans lequel arrive une charge utile est fixé par socket et indiqué dans la section propre à ce socket ci-dessous ; chaque type de charge utile publié fournit un point d’entrée d’encodage et un point d’entrée de décodage pour l’encodage de son socket, si bien qu’un guest appelle une fonction au lieu de choisir un parseur. Pour un rendu de fournisseur avec source, la charge utile transporte une liste de la source plutôt que les octets de la source : un ensemble trié d’entrées {path, is_dir} sous la racine de la source du nœud, sans aucune interprétation de la disposition du fournisseur par l’hôte. Le guest applique sa propre logique de disposition — sélectionner l’unique fichier compose, descendre jusqu’à la racine d’un chart, exiger un Chart.yaml, vendoriser un module récursivement — et relit exactement la portion qu’il sélectionne au moyen d’un callback de l’hôte. Au-delà de la charge utile, l’hôte expose un ensemble sélectionné de fonctions hôtes à moindre privilège, et accorde à un plugin exactement celles que son binaire importe :
aggrega_log— une ligne de journal vers la destination de journalisation de l’hôte.aggrega_emit_warning— un avertissement structuré que l’hôte présente après l’appel.aggrega_fetch_external_input— le canal de récupération des entrées externes (ci-dessous).aggrega_pack_source— le callback de sélection de la source : le guest nomme une sélection{file | dir | tree, path}sous la racine de la source et l’hôte lit et empaquette exactement celle-ci dans une sandbox qui résout les chemins sous la racine et rejette...aggrega_read_source_file— une lecture du contenu d’un seul fichier dans la même sandbox, pour une sélection de la source qui dépend du contenu.aggrega_parse_source— le callback de consommation des producteurs : le guest nomme un format syntaxique et transmet les octets de la source, et l’hôte résout un parseur pour ce format, l’exécute et renvoie l’arbre canonique qu’il a produit. C’est ainsi qu’un consommateur obtient la sortie d’un producteur par l’intermédiaire de l’hôte au lieu d’invoquer lui-même un guest producteur, et l’hôte le limite à un seul niveau — un producteur atteint de cette façon qui l’appelle à nouveau se voit refuser l’appel — si bien qu’un consommateur l’appelle une fois par source et peut consommer de nombreuses sources en séquence.
L’hôte déduit l’ensemble qu’un plugin importe de son binaire .wasm, le valide par rapport à la liste d’autorisation sélectionnée et le recoupe avec les fonctions hôtes que déclare le describe() du guest. aggrega plugin sync enregistre l’ensemble dans le spec.runtime.hostFunctions de l’entité, et une publication refuse une entité dont l’enregistrement diffère du binaire, si bien que la surface hôte de chaque plugin est visible dans le catalogue et ne peut pas diverger du binaire.
Les échecs de callback portent un code comparable par machine, sous hostfunc_error_code. Les callbacks de l’hôte qui renvoient une réponse — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file et le callback de consommation des producteurs aggrega_parse_source — signalent l’échec dans la bande : l’enveloppe de réponse porte un message lisible par un humain et, à côté, un code facultatif comparable par machine sous hostfunc_error_code, tiré d’un vocabulaire fermé. Le message est une prose libre destinée à une personne ; le code est l’identité stable sur laquelle un guest effectue un branchement sans analyser le message. En cas de succès, le code est absent ; en cas d’échec, l’hôte définit les deux. Le PDK présente la paire comme une erreur typée dont le texte est le message et dont un guest compare le champ de code aux constantes de code réexportées par le langage. Un guest tolère un code absent et un code qu’il ne reconnaît pas en se rabattant sur le message — la comparaison sur un code est donc un raffinement au mieux superposé au message toujours présent, jamais un substitut de celui-ci. L’ensemble fermé des valeurs est le schéma des codes d’erreur des fonctions hôtes.
🔴 Deux vocabulaires différents nomment un échec sur cette frontière, et la clé que vous lisez indique lequel vous avez entre les mains. Les confondre est la seule erreur qui mérite d’être signalée ici, car une valeur de l’un ou de l’autre est une simple chaîne et ni l’hôte ni le guest ne vérifient de quel ensemble elle provient.
hostfunc_error_code, sur une réponse que l’hôte envoie à un guest. Sa valeur est un membre du catalogue fermé lié ci-dessus — une liste fixe, qui évolue lentement, des façons dont un callback de l’hôte peut échouer. Comme l’ensemble est fermé, un guest peut comparer une valeur à une constante nommée que son kit réexporte et effectuer un branchement sur le résultat.condition_codeà côté decondition_short_code, sur une sortie de socket qu’un guest renvoie à l’hôte. Ce sont les deux identifiants d’une condition d’arrêt que le guest a lui-même levée, et ils proviennent de l’ensemble ouvert et croissant des conditions que le compilateur enregistre plutôt que du catalogue.condition_codeest le code descriptif sous lequel la condition est enregistrée ;condition_short_codeest la forme compacte — la lettreEet quatre chiffres — qu’un lecteur cite, recherche et colle dans un rapport. L’hôte imprime le code court dans l’en-tête entre crochets du diagnostic qu’il rend, si bien qu’une condition levée par un guest se cite exactement comme une condition levée par le compilateur. Il ne dérive aucune des deux valeurs, mais il les vérifie : un code court qui ne correspond à aucune condition que ce compilateur déclare, ou qui correspond à une condition dont le numéro a été retiré, arrête le build au lieu d’atteindre un lecteur sous la forme d’un identifiant qui ne renvoie à rien.
Les deux identifiants côté guest sont signalés ensemble : un guest qui définit l’un et pas l’autre a nommé une condition que l’hôte ne peut pas résoudre, et l’hôte signale alors à la place sa propre condition générique d’échec de plugin, le message portant toujours l’échec entier. Et un condition_code n’est jamais un membre du catalogue des fonctions hôtes, si bien que le comparer à une constante réexportée ne donne jamais de correspondance — c’est pourquoi chaque clé nomme son propre vocabulaire plutôt que l’échec en général.
Les emplacements de chaque callback portent un encodage déclaré, et tout emplacement qui contient un document de charge utile le contient sous forme binaire. Chaque argument que prend un callback de l’hôte est un pointeur dans la mémoire du guest, à part le niveau numérique de aggrega_log ; un callback qui renvoie une réponse répond lui aussi par un pointeur. Ce que contient chacun de ces emplacements est fixé par callback :
| Callback | Emplacements d’argument | Emplacement de réponse |
|---|---|---|
aggrega_log, aggrega_emit_warning | Texte UTF-8 — aucun document de charge utile | aucune réponse |
aggrega_fetch_external_input | une URL UTF-8 nue — aucun document de charge utile | CBOR canonique |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | CBOR canonique (RFC 8949 §4.2.1) | CBOR canonique |
Le tableau se répartit selon ce que contient chaque emplacement plutôt que selon l’identité du callback : un emplacement qui contient un document de charge utile transporte du CBOR canonique, et un emplacement qui contient une simple chaîne — une ligne de journal, un champ de diagnostic, une URL — transporte du texte UTF-8. aggrega_fetch_external_input est le seul dont les deux emplacements diffèrent : son argument est une URL nue, lue comme du texte UTF-8, et sa réponse est un document de charge utile en CBOR canonique.
Ce que fait un guest à un emplacement qui porte une charge utile, et ce qu’il ne doit pas faire. 🔴 Un emplacement qui contient un document de charge utile contient une suite d’octets opaque, et non du texte UTF-8 — c’est donc la forme que déclare un guest, et pas seulement les octets qu’il y place. Un guest qui alloue une telle requête comme une chaîne, ou lit une telle réponse comme une chaîne, n’interopère pas : une conversion de texte dans l’un ou l’autre sens corrompt les octets binaires. L’échec est manifeste plutôt que partiel — une requête que l’hôte ne peut pas décoder revient sous la forme d’une enveloppe de réponse portant le code request_undecodable, dans la même forme dans la bande que tout autre échec de callback, si bien que le guest le signale au lieu de poursuivre avec une charge utile à moitié lue. Les types de charge utile sont SourcePackRequest et SourcePackResponse pour aggrega_pack_source, SourceFileRequest et SourceFileResponse pour aggrega_read_source_file, ParseInput et ParseSourceResponse pour aggrega_parse_source, et le seul type de réponse FetchExternalInputResponse pour aggrega_fetch_external_input, dont l’URL est allouée comme du texte. Concrètement, par kit :
- Go — construisez la requête avec
EncodeCBOR()du type de requête, allouez-la avecpdk.AllocateBytes(et nonpdk.AllocateString), et lisez la réponse avecReadBytes()sur la mémoire vers laquelle se résout le pointeur de réponse, dansDecodeCBORdu type de réponse. L’URL de récupération est l’exception côté requête, allouée avecpdk.AllocateString; sa réponse se lit comme n’importe quelle autre. La déclaration//go:wasmimportest un pointeur dans les deux cas, si bien que rien dans la signature ne montre la forme — c’est dans l’allocation et la lecture qu’elle se trouve. - Rust — la déclaration
#[host_fn]indique directement la forme : chacun des trois callbacks de charge utile se litfn <callback>(request: Vec<u8>) -> Vec<u8>;, et le callback de récupération se litfn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Construisez la requête avecencode_cbor()du type de requête et lisez la réponse avecdecode_cbor(&raw)du type de réponse. - TypeScript — construisez la requête avec la fonction
encodeCBOR…du type de requête, allouez-la avecMemory.fromBuffer(et nonMemory.fromString), et lisez la réponse avecreadBytes()dans la fonctiondecodeCBOR…du type de réponse. L’URL de récupération est allouée avecMemory.fromString; sa réponse se lit avecreadBytes()comme les autres. Comme en Go, l’entréedeclare moduleest un pointeur dans les deux cas.
Un guest qui appelle un wrapper du PDK n’a besoin de rien de tout cela. Les wrappers — FetchExternalInput, PackSource, ReadSourceFile et ParseSource, dans la graphie propre à chaque langage — effectuent l’allocation et l’encodage, et aucune de leurs signatures ne nomme un type de transmission, si bien qu’un guest qui atteint ces callbacks par son kit n’alloue et ne décode rien lui-même ; un guest qui déclare et appelle lui-même les fonctions hôtes alloue et lit sa mémoire comme décrit ci-dessus. Une requête allouée comme du texte est refusée plutôt qu’à moitié servie, et une réponse lue comme du texte ne peut pas être décodée, si bien qu’un décalage entre les deux côtés est manifeste plutôt que silencieux.
Deux propriétés sur lesquelles s’appuyer. La réponse porte le même encodage qu’elle réussisse ou qu’elle échoue : un guest lit un seul emplacement et ne peut pas savoir avant le décodage lequel des deux il contient, si bien qu’un seul point d’entrée de décodage lit les deux, et le code d’erreur et le message décrits ci-dessus arrivent par lui. Et un guest remplit un champ à valeur d’octets dans le type de champ propre à son kit — une slice d’octets en Go, une chaîne base64 en Rust et en TypeScript — car la conversion vers la suite d’octets brute que transporte l’encodage binaire est le travail de l’encodeur généré, effectuée à l’aller et inversée au retour. Cela couvre les octets de source de ParseInput, le contenu de fichier que renvoie aggrega_read_source_file, le contenu que aggrega_fetch_external_input a récupéré et le contenu de chaque fichier empaqueté dans une réponse pack-source : ces octets traversent la frontière une seule fois plutôt que doublement encodés, et aucun guest n’encode en base64 ce que l’encodeur s’apprête à décoder du base64. Le champ content des réponses read-source-file et fetch est omis lorsqu’il est vide, si bien que la réponse pour un fichier vide ou une charge utile récupérée de longueur nulle ne porte aucun contenu ; une telle réponse reste un succès, car un échec porte toujours son message et son code, et le wrapper de chaque kit renvoie des octets vides pour elle. L’arbre que renvoie aggrega_parse_source voyage comme une suite d’octets contenant son propre document JSON tel quel ; l’hôte ne le lit ni ne le remanie. Un parseur lit le même ParseInput, dans le même encodage, sur son propre export parse — voir le socket de parseur.
Canonique signifie qu’une entrée identique produit des octets identiques de chaque côté, ce qui permet de comparer une charge utile entre les trois kits de plugins plutôt que de seulement lui faire faire un aller-retour, et c’est pourquoi la sortie d’un build reste identique à l’octet près. Aucune bibliothèque CBOR n’est nécessaire dans un guest et rien n’analyse des octets à la main : chaque type de charge utile publié fournit les points d’entrée d’encodage et de décodage dont l’encodage de son emplacement a besoin.
Le déterminisme relève de la responsabilité de l’auteur du plugin. L’hôte consomme les octets de sortie d’un guest tels quels et ne leur applique aucun sérialiseur, si bien que le contrat que tout plugin doit respecter est le suivant : une entrée identique produit des octets de sortie identiques. La sandbox supprime les sources ambiantes de non-déterminisme — l’heure murale, l’environnement, l’état du système de fichiers — mais ne masque délibérément pas le reste : un guest qui encode de l’entropie ou un temps monotone écoulé dans sa sortie produit des octets visiblement différents d’une exécution à l’autre plutôt qu’un défaut caché de façon stable.
Le canal de récupération des entrées externes. aggrega_fetch_external_input est le seul canal sanctionné pour le contenu distant, et il passe par l’hôte, ce n’est pas un accès du guest au réseau : le guest nomme une URL, et l’hôte sert les octets selon la discipline d’épinglage des entrées externes. Une URL épinglée dans le fichier de verrouillage de la Release est servie depuis le magasin local adressé par contenu et vérifiée par rapport à son digest enregistré ; une URL non épinglée est refusée avec un diagnostic qui nomme l’URL et l’étape qui l’épingle, car un rendu consomme la fermeture que son fichier de verrouillage enregistre et ne l’élargit jamais. Les épinglages sont écrits lorsque les dépendances de la Release sont résolues, ce qui est le seul moment où quoi que ce soit est épinglé. Le guide du développeur présente le mode d’emploi de la création et la discipline d’épinglage dans leur intégralité.
Tables qui conservent leur ordre
Certaines tables qu’une charge utile transporte sont marquées comme préservant l’ordre dans le schéma de leur socket, parce que l’ordre de leurs entrées fait partie de ce qu’elles transportent : les nœuds d’un build, les labels d’un nœud, les rattachements d’un nœud, les entrées et les sorties d’une étape du pipeline, les espaces de clés qu’un fournisseur déclare. Les types de charge utile publiés conservent chacune de ces tables dans un conteneur qui garde ses entrées dans l’ordre où elles ont été définies :
| Kit | Conteneur |
|---|---|
| Go | aggrega.OrderedMap[V] — le nom que le kit donne à abi.OrderedMap[V] du paquet ABI |
| Rust | OrderedMap<V> du crate aggrega-abi, réexporté par le kit |
| TypeScript | le Map<string, V> propre au langage |
Les conteneurs Go et Rust offrent les opérations d’une table — rechercher une clé, la définir, la supprimer, lire les clés, parcourir les entrées dans l’ordre, les compter. Définir une clé que le conteneur contient déjà remplace sa valeur et conserve sa place ; une nouvelle clé se place après toutes les clés existantes.
L’ordre survit aux deux encodages. Dans l’encodage binaire, une table marquée est écrite comme une liste ordonnée d’entrées — chaque entrée étant une liste de deux éléments, la clé puis la valeur — dans l’ordre du conteneur, là où l’encodage canonique écrirait sinon une table aux clés triées. Dans l’encodage textuel, c’est un objet JSON dont les membres sont écrits dans l’ordre du conteneur. Un décodeur, dans l’un ou l’autre encodage, refuse une table qui répète une clé, en nommant la clé. Une table que le schéma ne marque pas garde la forme de table triée dans l’encodage binaire et le type de table ordinaire d’un langage dans les types publiés.
Trois conséquences pour un guest :
- L’ordre fait partie de la sortie. Comme une table marquée est écrite dans l’ordre où elle a été remplie, un guest qui en remplit une à partir d’une source sans ordre fixe — en itérant sur une table native de Go, par exemple — écrit des octets qui diffèrent d’une exécution à l’autre pour une entrée identique. Remplissez-la dans un ordre fixe.
- L’ordre ne tient que tant que la table reste dans son conteneur. Un guest qui convertit une charge utile en un type de valeur générique de son propre langage obtient à la place l’ordre de ce type : un
map[string]anyde Go n’en a aucun, et leserde_json::Valuede Rust garde les clés des objets triées, sauf si le crate est compilé avec sa fonctionnalitépreserve_order. - En TypeScript, lisez et écrivez au moyen des fonctions générées. Un type contenant une table marquée décode son JSON membre par membre, si bien qu’une clé qui se lit comme un indice de tableau, comme
"8080", garde sa place là oùJSON.parsela déplacerait en tête de l’objet ; et son encodeur écrit chaqueMapcomme un objet, là oùJSON.stringifyécrit unMapcomme{}.Object.keysd’unMapest vide lui aussi : lisez les clés d’unMapavec son proprekeys().
Valeurs qu’une entrée marque comme sensibles
Un plugin ne cite jamais, dans un refus ou un avertissement qu’il renvoie, une valeur que son entrée marque comme sensible — par sa clé, ou comme partie d’une charge utile marquée dans son ensemble. Un refus est l’error que porte une sortie ; un avertissement est un Diagnostic que porte la sortie, quel que soit son niveau de gravité, ou un avertissement émis au moyen de aggrega_emit_warning. L’hôte reproduit ce texte sans modification partout où il le signale — la ligne de commande, le serveur de langage et la liste des problèmes de l’éditeur, les outils de l’assistant — et n’en lit aucune valeur, si bien que le plugin est la seule partie capable de tenir la valeur à l’écart. Nommez plutôt la clé, le paramètre ou la position : un lecteur retrouve la valeur à partir de là.
La règle couvre le texte qu’une bibliothèque écrit pour le plugin autant que le texte que le plugin écrit lui-même. Un moteur de modèles signale les données qu’il évaluait, un validateur de schéma cite une valeur qui échoue à un pattern, un parseur cite le jeton qu’il n’a pas pu lire. Lorsqu’un tel échec a porté sur une valeur que l’entrée marque, signalez-le sans la valeur — par exemple, exécutez à nouveau la même étape en remplaçant chaque valeur marquée par un espace réservé, signalez l’échec de cette exécution lorsqu’elle échoue au même endroit, et sinon indiquez que le texte de l’échec est retenu. Sous une charge utile marquée dans son ensemble, chaque valeur de cette charge utile est une valeur marquée, tandis que ses clés — la forme du document — restent lisibles.
Où une entrée marque une clé ou une charge utile comme sensible, écrit comme les données transmises le nomment :
| Socket et export | Où le marquage est lu |
|---|---|
fournisseur render_node et validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys : chaque clé nomme une entrée de node.values lorsque ces valeurs sont celles du Component lui-même, indexées par les feuilles qu’il déclare — le valuesMapping d’une Recipe écrit des clés qu’aucune déclaration ne nomme, si bien qu’aucune d’elles n’est marquée ici — ou une entrée de la table attachments du conteneur d’une charge de travail qui lit un emplacement déclaré sensible. node.sensitive_values marque node.values dans son ensemble : il vaut true lorsqu’un valuesMapping — celui de la Recipe, ou celui de la FeatureRecipe d’un rattachement — a produit ces valeurs et lit une valeur qu’un auteur a déclarée sensible. workload_projection.sensitive_workload marque de la même façon chaque valeur de la charge de travail lorsque le modèle de la charge de travail en lit une, et chaque entrée de artifacts_projection.entries porte sensitive_content pour son propre contenu, y compris le message d’un parseur sur ce contenu. Chaque entrée de omits porte sensitive lorsque le modèle qui produit son kind, son nom ou son namespace en lit une, et alors chaque champ de cette entrée est une valeur marquée. Chaque entrée de node.features porte le marquage de son propre rattachement : sensitive_payload_leaves (les feuilles values.<path> et infra.<path> que sa Feature déclare sensibles), sensitive_inject (les clés de livraison inject qui lisent une clé provides que sa Feature déclare sensible) et sensitive (si le rattachement manipule ou non du contenu déclaré sensible). |
gouvernance ir-verdict (PolicyInput) | graph : les sensitive_payload_leaves de chaque nœud, et les sensitive_payload_leaves, sensitive_inject et sensitive de chaque rattachement. Chaque valeur que ces marquages nomment arrive déjà sous la forme du marqueur de retenue {"aggrega_withheld": "declared"}, si bien que la valeur elle-même n’atteint jamais le plugin. |
Aucune autre entrée de socket, ni aucune entrée d’un autre export de fournisseur, ne porte de marquage. Un marquage de clé ne nomme que ce qu’il relie exactement à une déclaration, si bien qu’une clé absente ne signifie jamais qu’une valeur peut être citée sans risque : elle signifie qu’aucune déclaration n’a pu être reliée à cette clé. Un marquage de charge utile est lu à partir des références du modèle qui a produit la charge utile — une référence qui atteint une valeur déclarée, le modèle qui transmet l’ensemble de ses données, ou un modèle qui ne s’analyse pas — et jamais à partir d’une valeur, si bien que son absence signifie que ce modèle n’a lu aucune valeur déclarée, pour autant que ses références le montrent, ou qu’aucun modèle n’a produit la charge utile ; ce n’est pas une affirmation que la charge utile ne porte rien de sensible.
Position des sockets Wasm dans le pipeline
Le pipeline de compilation réserve les points de socket suivants. Les labels de forme suivent la taxonomie à quatre labels de la page d’état.
| Socket | Position dans le pipeline | État actuel |
|---|---|---|
Socket de gouvernance, rôle annotation-transform | Résolution (avant l’expansion des annotations) | disponible — invoqué lorsqu’un espace de travail rattache un plugin annotation-transform ; injecte des annotations que l’expansion transforme en rattachements de Feature |
Socket de gouvernance, rôle label-transform | Construction de la topologie (le constructeur de topologie) | disponible — invoqué lorsqu’un espace de travail rattache un plugin label-transform ; ajoute automatiquement des labels aux nœuds au moyen de JSON Patch |
Socket de gouvernance, rôle ir-verdict | Analyse statique (l’analyseur statique, sur le graphe IR) | disponible — invoqué lorsqu’un espace de travail rattache un plugin ir-verdict ; un verdict halt arrête le build |
Socket de gouvernance, rôle render-verdict | Rendu (sur les artefacts rendus) | disponible — invoqué lorsqu’un espace de travail rattache un plugin render-verdict ; un verdict halt arrête le build |
Plugins pipeline: de FeatureRecipe et de Recipe | Le pipeline des plugins (mutation post-rendu) | disponible — chaque étape déclarée s’exécute sur l’ensemble des documents rendus, en appliquant des correctifs RFC 6902 et en émettant des effets de bord |
| Plugins de rendu de Provider (helm, helm-chart, compose, terraform, cloudformation) | Rendu de base (les fournisseurs) | disponible — chaque fournisseur effectue le rendu au moyen de son guest Wasm ; le rendu est exclusivement Wasm, sans repli sur un moteur de rendu dans l’hôte |
Plugins de parseur (parse:<format>) | Rendu, pour une politique render-verdict ; et hors bande, pour un import | disponible — appelé pour un artefact dans un format qu’une politique render-verdict ne lit pas nativement, pour un importateur au moyen de aggrega_parse_source, et pour reconnaître le format d’un import qui n’en indique aucun |
Plugins d’importateur (import:<format>) | Hors bande (aggrega import) | disponible — invoqué par aggrega import, la session de l’éditeur et l’outil destiné à l’assistant |
Plugins de linter (linter/publishing) | Hors bande (aggrega lint) | disponible — le linter de publication est livré et s’exécute par l’intermédiaire de l’hôte au moyen de aggrega lint |
La sous-phase d’expansion des Feature pilotée par les annotations, qui fait partie de la résolution, est une passe native Go du pipeline, et non un socket Wasm. Elle valide les valeurs d’annotation par rapport au spec.schema de la Feature cible et injecte des rattachements de Feature synthétiques au moment du build de l’IR. Voir vocabulary/labels-and-annotations.md pour les six surfaces portant des annotations et des labels et providers/well-known-annotations.md pour la forme des liaisons et les explications sur leur rédaction.
Contrat de forme de sortie — ce qui existe aujourd’hui
Le socket de gouvernance porte une surface de contrat typée à chacun de ses quatre rôles, et c’est le rôle qui détermine laquelle. Les auteurs de Plugin implémentent du code côté guest qui produit les formes documentées ; l’hôte les lit au moment du build, une fois par plugin configuré, lorsqu’un espace de travail rattache un plugin à ce rôle. Les sous-sections ci-dessous suivent l’ordre dans lequel le pipeline les invoque.
Le rôle annotation-transform — sortie d’injection d’annotations
Position dans le pipeline. Résolution, après la résolution des composants et avant l’exécution de l’expansion des Feature pilotée par les annotations.
Forme d’entrée (hôte → guest). Un document AnnotationTransformInput contenant :
targets— les cibles de l’injection : les composants résolus que le guest peut annoter — ceux qu’une frontière nomme directement, et chaque composant qu’une entrée de routage sous lesaggregates:d’une frontière fait entrer par routage, que l’entrée le nomme ou non — chacun portant sonboundary_path, soncomponent_name(pour un composant routé, son identifiant pointé dans le graphe de build, commemetrics.query) et lesannotationsque la Release écrit sur lui, afin qu’un guest puisse décider quoi ajouter sans écarter une valeur écrite par l’auteur. Chaque valeur d’annotation arrive telle qu’elle est écrite — une chaîne, un objet de sous-clés, ounulllà où le composant renonce à une annotation dont il hériterait — et chaque clé que porte le composant est présente, quelle que soit sa valeur. Ordonnées de façon déterministe par l’hôte.binding_keys— les clés d’annotation pour lesquelles le Manifest enregistre une liaison, dans l’ordre de l’auteur. Une injection sous une clé enregistrée est ensuite développée en un rattachement de Feature, si bien qu’un guest lit cette liste pour injecter des clés qui prendront effet. L’hôte n’exige pas qu’une injection nomme une clé enregistrée : une annotation injectée non enregistrée se comporte exactement comme une annotation écrite par l’auteur sans liaison.sources— les fichiers de définition que le rattachement a déclarés souswith.sources, chacun portant son chemin de nom de base et son contenu, triés par chemin.settings— l’objet de paramètres de forme libre que le rattachement a déclaré souswith.settings, transmis tel quel au guest.
settings et sources sont le même canal with, agnostique vis-à-vis du moteur, que lit chaque autre rôle, et tous deux sont absents lorsque le rattachement n’en déclare aucun. Comme la sortie de ce rôle façonne le build, les paramètres et le contenu des sources du rattachement sont épinglés dans le fichier de verrouillage de la release au pull et reconstruits à partir de lui au build.
Forme de sortie (guest → hôte). Un document AnnotationTransformOutput contenant :
injections— les annotations à ajouter, dans l’ordre. Chacune nomme une coordonnée cible existante (boundary_pathetcomponent_name) ainsi que laannotation_keyet saannotation_value: une chaîne, ou un objet de sous-clés, qui alimente une liaison routant plusieurs sous-clés à la fois.
L’hôte n’applique que des ajouts d’annotations, à des coordonnées qu’il a lui-même fournies, chacun avec une valeur qu’un auteur pourrait écrire sur cette annotation. Il lit une valeur injectée exactement comme il lit la même valeur écrite dans la Release — les sous-clés d’un objet dans l’ordre où le guest les a écrites — si bien que l’expansion la rencontre comme elle rencontre une valeur écrite par l’auteur. Une injection qui nomme une coordonnée que la charge utile ne porte pas, ou qui porte null, une liste, un nombre, un booléen ou un objet sans sous-clés, arrête le build avec un message nommant la coordonnée et l’annotation, au lieu d’être silencieusement écartée ou appliquée ; l’ensemble de la sortie est vérifié avant qu’une partie quelconque en soit appliquée. C’est ce confinement qui borne le rôle : un opérateur qui rattache ici un plugin a déclaré l’injection d’annotations et rien de plus. Lorsque le build refuse ensuite une annotation injectée pour la façon dont elle route, pour une valeur de sous-clé que le schéma de la Feature liée n’admet pas, ou pour un pilier qu’une annotation côté Release ne peut pas utiliser, son message nomme le plugin qui l’a injectée et le rôle auquel il est rattaché.
Encodage de transmission. La charge utile et le résultat de ce rôle circulent en CBOR canonique (RFC 8949 §4.2.1), dans les deux sens. Un guest les lit et les écrit au moyen des points d’entrée que portent les types de charge utile — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, decodeCBORAnnotationTransformInput et encodeCBORAnnotationTransformOutput en TypeScript — si bien qu’aucune bibliothèque CBOR n’est nécessaire et que rien n’analyse les octets à la main. En Rust, l’export prend et renvoie Vec<u8> ; en TypeScript, il lit Host.inputBytes() et écrit Host.outputBytes(...). Les annotations de chaque cible sont une table que le schéma marque comme préservant l’ordre, si bien qu’elles circulent sous la forme d’une liste ordonnée d’entrées dans l’ordre où la cible les contient, et qu’un guest les lit au moyen du conteneur de son kit qui conserve l’ordre ; chaque valeur circule sous la forme des octets de son JSON, comme le fait la annotation_value d’une injection dans l’autre sens. settings circule sous la forme des octets de son document JSON, qu’un guest analyse comme du JSON pour en examiner le contenu. Une réponse qui n’est pas un AnnotationTransformOutput dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — arrête le build, en nommant le plugin et son export, au lieu d’être lue comme une liste vide d’injections. Appelé directement avec aggrega plugin run-local --export transform_annotations, un guest reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage, et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
Définitions de types. Les types de transmission d’annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — sont publiés dans les trois paquets ABI, générés à partir d’un même codec afin que les trois restent synchronisés.
Le rôle label-transform — sortie JSONPatch
Position dans le pipeline. Construction de la topologie, après l’aplatissement du graphe et avant la construction du graphe IR, si bien que les sélecteurs de socket et de Feature que l’analyseur évalue lisent les labels que le rôle laisse.
Forme d’entrée (hôte → guest). Un document MutatorInput contenant :
compilation_context— l’identité de la release (release_name,environment).graph— une projectionMutatorGraphdes nœuds de la topologie : pour chaque nœud, son Component, sa version résolue, ses labels et lesvaluesque son instance déclare.settings— l’objet de paramètres de forme libre que le rattachement a déclaré souswith.settings, transmis tel quel au guest.sources— les fichiers de définition que le rattachement a déclarés souswith.sources, chacun portant son chemin de nom de base et son contenu, afin qu’un mutateur puisse être piloté par un fichier de règles ou de correspondance versionné plutôt que par des paramètres en ligne.
Le graphe est une projection et non le graphe IR : chaque nœud porte son ensemble de labels résolu et les valeurs que son instance déclare dans l’Aggregate, tandis que les arêtes et les charges utiles des fonctionnalités restent à l’intérieur du compilateur. Les valeurs sont celles de l’Aggregate lui-même, avec ses modèles déjà évalués par rapport à ses paramètres, si bien qu’une valeur remontée dans un paramètre arrive comme la valeur fournie par la Release ; une valeur par défaut que déclare le schéma du Component, et tout ce qu’apporte une Recipe ou une Feature, n’en font pas partie, et un nœud qui ne déclare aucune valeur ne porte aucune clé values. Une valeur que le Component du nœud déclare sensible est retenue exactement comme le verdict sur le graphe la retient — elle se lit comme {"aggrega_withheld": "declared"} — tandis que chaque valeur sœur qu’aucune déclaration n’atteint arrive telle qu’elle est écrite. C’est ce qui permet à une configuration déclarée par le développeur de décider d’un label — une base de données dont les valeurs activent une extension vectorielle promue en datastore.aggrega.ai/engine: vector, par exemple. settings et sources sont le même canal with, agnostique vis-à-vis du moteur, que lisent les rôles de verdict ; l’hôte les transmet sans jamais interpréter leur contenu. Comme la sortie d’un mutateur façonne le build, les paramètres et le contenu des sources du rattachement sont épinglés dans le fichier de verrouillage de la release au pull et reconstruits à partir de lui au build, si bien que l’entrée du mutateur reste invariante face à une modification de l’un ou l’autre après le pull, jusqu’au pull suivant.
Forme de sortie (guest → hôte). Un document MutatorOutput contenant :
patches— un tableau de documents JSONPatch opaques (RFC 6902) que l’hôte applique aux seuls labels des nœuds ; les valeurs que portait l’entrée sont en lecture seule.
Chaque correctif adresse les labels d’un nœud précis au moyen de JSON Pointer (RFC 6901) ; l’hôte applique les correctifs dans l’ordre du tableau et réintègre l’ensemble de labels modifié dans le graphe IR. La tâche du rôle label-transform est l’ajout automatique de labels à l’échelle de l’entreprise — ajouter des labels de conformité / d’observabilité / d’attribution des coûts déclarés par la politique de l’entreprise sans modifier le contenu du catalogue. La surface des labels est la seule cible autorisée de ce rôle : un correctif qui touche un champ du nœud autre que ses labels, ajoute ou supprime un nœud, ou définit une valeur de label qui n’est pas une chaîne arrête le build au lieu d’être silencieusement absorbé. La RFC 6901 est la référence de base de la grammaire des chemins pour chaque surface de chemin de document dans Aggrega — le contrat des plugins Wasm ici, plus les exports *_path de .locals, plus les champs de schéma *Path ailleurs dans le corpus. Voir 02-naming-conventions.md « Discipline des suffixes de nommage des chemins de document » pour la déclaration canonique de cette référence de base et pour la discipline des suffixes *Path / *_path qui distingue les deux côtés de la rédaction.
Encodage de transmission. La charge utile et le résultat de ce rôle circulent en CBOR canonique (RFC 8949 §4.2.1), dans les deux sens. Canonique signifie qu’une entrée identique produit des octets identiques de chaque côté, ce qui permet de comparer une charge utile entre les trois kits de plugin au lieu de seulement l’encoder puis la décoder à nouveau, et c’est pourquoi la sortie d’un build reste identique à l’octet près. Un guest les lit et les écrit au moyen des points d’entrée que porte déjà le type de charge utile de son kit — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, decodeCBORMutatorInput et encodeCBORMutatorOutput en TypeScript — si bien qu’aucune bibliothèque CBOR n’est nécessaire et que rien n’analyse les octets à la main. En Rust, l’export prend et renvoie Vec<u8> ; en TypeScript, il lit Host.inputBytes() et écrit Host.outputBytes(...). Les nodes du graphe, les labels de chaque nœud et les values de chaque nœud sont des tables que le schéma marque comme préservant l’ordre, si bien qu’elles circulent sous la forme de listes ordonnées d’entrées — les nœuds dans l’ordre où le build les contient, qui est l’ordre de l’auteur, les labels de chaque nœud dans l’ordre où le nœud les porte, et les valeurs de chaque nœud dans l’ordre où l’Aggregate les écrit — et qu’un guest lit les trois au moyen du conteneur de son kit qui conserve l’ordre. Chaque valeur circule sous la forme des octets de son document JSON : les kits Go et Rust la remettent au guest sous la forme de ce JSON, à analyser autant qu’une règle en a besoin, et le kit TypeScript sous la forme de la valeur analysée.
Deux choses que cela ne change pas. Le tableau patches reste du JSON : le socket transporte chaque document de correctif tel quel comme contenu opaque et aucun des deux côtés n’en lit le contenu, si bien que la forme propre d’un document de correctif est indépendante de l’encodage que porte son socket. Et settings et sources sont toujours transmis tels quels — settings arrive sous la forme des octets que le rattachement a écrits, qu’un guest analyse comme du JSON s’il a besoin d’en examiner le contenu.
Tous les autres rôles de gouvernance portent le même encodage — le rôle annotation-transform et les deux rôles de verdict le disent chacun dans leur propre section — si bien qu’un guest qui sert plus d’un rôle parle le CBOR canonique à chaque rôle qu’il sert, en lisant chaque charge utile au moyen du point d’entrée de décodage de son propre type.
Définitions de types. Les types de transmission du mutateur — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — sont publiés dans les trois paquets ABI (github.com/aggrega-ai/aggrega-abi/go, le crate aggrega-abi et @aggrega-ai/aggrega-abi), générés à partir d’un même codec afin que les trois restent synchronisés. L’hôte assemble l’entrée et applique les correctifs que le guest renvoie.
Les rôles de verdict — sortie de tableau de verdicts
Un guest de politique inspecte un build et renvoie une liste de verdicts ; l’hôte agit selon le niveau de gravité de chaque verdict et n’interprète jamais la politique elle-même. Le traitement complet — les quatre rôles, les niveaux de gravité, le canal d’entrée fourni par l’opérateur, l’écriture d’une politique pour l’un ou l’autre des deux moteurs livrés dans le compilateur, l’encapsulation d’un moteur de politiques externe, les guests de référence et la façon dont un opérateur rattache une politique — se trouve sur la page du socket de gouvernance. Cette section consigne la position dans le pipeline et les formes typées de transmission.
Position dans le pipeline. Une politique est rattachée à exactement un rôle de verdict, qui détermine où elle est évaluée :
ir-verdict— évalué lors de l’analyse statique, avant le rendu de base. L’analyseur assemble la charge utile à chaque build.render-verdict— évalué après le rendu, sur les artefacts émis.
Lorsqu’un espace de travail rattache un plugin d’un rôle de verdict, le pipeline sérialise la charge utile de ce rôle vers le plugin et en relit les verdicts.
Forme d’entrée (hôte → guest). Le rôle sélectionne la charge utile :
- Le
PolicyInputdeir-verdictportegraph— le graphe IR complet, agnostique vis-à-vis des capacités (la même forme que celle qu’émet le constructeur de topologie), avec chaque détail de nœud, d’arête et de rattachement que détient le compilateur, à ceci près qu’une valeur qu’un auteur a déclarée sensible arrive retenue (voir Valeurs qu’une entrée marque comme sensibles) — etprecalculated_paths, les chemins de routage que l’analyseur énumère à côté, afin qu’une politique puisse raisonner sur l’atteignabilité sans parcourir à nouveau le graphe. Le graphe est le graphe IR versionné, dont la source unique est le schémair-v1beta1; la forme de l’IR n’est pas secrète (c’est le même graphe qu’émetaggrega inspect) et les secrets qu’il contient sont des pointeurs, jamais du texte en clair. - Le
RenderPolicyInputderender-verdictporteartifacts— les fichiers de sortie rendus, triés par chemin, si bien que les données transmises sont identiques à l’octet près d’une exécution à l’autre pour une entrée identique. Chaque entrée porte lepathde sortie de l’artefact et soncontentrendu ; elle porte aussi leformatdans lequel il a été rendu, lorsque le fournisseur qui l’a produit en a déclaré un, et untree, la vue canonique analysée d’un format que le guest ne lit pas nativement, que l’hôte analyse au moyen du parseur résolu et transmet de façon opaque. Les deux sont absents lorsqu’ils ne s’appliquent pas — un format que le guest lit nativement (JSON, YAML) reste non analysé pour que le guest le lise depuiscontent.
Les deux rôles portent en outre les sources du rattachement (des fichiers de définition de politique que l’hôte lit au moment du build et remet tels quels au guest, avec les chemins sous forme de noms de base et le contenu opaque) et les settings (un objet de forme libre transmis sans modification). Les deux sont absents lorsque le rattachement n’en déclare aucun.
Forme de sortie (guest → hôte). Un document PolicyOutput contenant :
results— un tableau d’entréesDiagnostic, chacune avec uneseverity(halt,warnouinfo) et une chaînemessage. Un verdict peut aussi définircode,rule_id,classification,source_ref,locationetsuggestsur la même entrée ; l’hôte ajoute au verdict affiché ceux d’entre eux que portait le verdict, sur chaque voie d’acheminement par niveau de gravité.
Seuls les verdicts déclenchés apparaissent ; une évaluation qui autorise renvoie un tableau vide. L’hôte parcourt les verdicts et fait correspondre chaque niveau de gravité à une action : halt arrête le build (en faisant apparaître chaque message halt), warn signale le verdict et laisse le build se poursuivre, info l’enregistre sans affecter le résultat. Un halt arrête le build par le même point de contrôle qu’utilise une violation d’un sélecteur ou de appliesTo.
Encodage de transmission. Les charges utiles des deux rôles, et le PolicyOutput qu’un guest renvoie à l’un ou l’autre, circulent en CBOR canonique (RFC 8949 §4.2.1). Un guest les lit et les écrit au moyen des points d’entrée que portent les types de charge utile — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput et encodeCBORPolicyOutput en TypeScript — si bien qu’aucune bibliothèque CBOR n’est nécessaire et que rien n’analyse les octets à la main. En Rust, chaque export prend et renvoie Vec<u8> ; en TypeScript, il lit Host.inputBytes() et écrit Host.outputBytes(...). Les tables du graphe qui préservent l’ordre, dont ses nodes et les labels de chaque nœud, circulent sous la forme de listes ordonnées d’entrées dans l’ordre où le build les contient, et un guest les lit au moyen du conteneur de son kit qui conserve l’ordre ; l’ordre dans lequel une politique les rencontre avec chaque moteur de politiques est décrit sur la page du socket de gouvernance. settings, et le tree analysé d’un artefact, circulent sous la forme des octets de leurs documents JSON, qu’un guest analyse comme du JSON pour en examiner le contenu. Une réponse qui n’est pas un PolicyOutput dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — arrête le build, en nommant le plugin et son export, au lieu d’être lue comme une liste vide de verdicts. Appelé directement avec aggrega plugin run-local --export verdict_ir ou --export verdict_render, un guest reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage, et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
Définitions de types. Les types de transmission des politiques sont publiés dans les trois mêmes paquets ABI : PolicyInput (rôle ir-verdict), RenderPolicyInput (rôle render-verdict), le PolicySource partagé et PolicyOutput, dont les entrées results sont des valeurs Diagnostic. Le niveau de gravité d’un diagnostic est l’une de trois valeurs que partagent tous les sockets — halt, warn ou info — et les trois sont publiées sous forme de constantes à côté des types de transmission dans chacun des trois paquets, si bien qu’un guest signale à partir du même ensemble fermé que celui sur lequel l’hôte achemine. Un guest qui renvoie toute autre valeur arrête le build, avec un message nommant le plugin et la valeur renvoyée : un niveau de gravité impossible à acheminer est un défaut du plugin que l’hôte signale, et non un diagnostic qu’il écarte.
Contrat de forme de sortie — le pipeline de FeatureRecipe et les sockets de fournisseur
Les sockets ci-dessous portent des surfaces de contrat typées que le compilateur invoque au moment du build. Les étapes pipeline: de FeatureRecipe et de Recipe s’exécutent dans le pipeline des plugins sur l’ensemble des documents rendus ; le socket de rendu des fournisseurs s’exécute lors du rendu de base ; le linter de publication s’exécute hors bande.
Correctifs RFC 6902 (le pipeline des plugins)
Les étapes pipeline: de FeatureRecipe et de Recipe qui s’exécutent dans le pipeline des plugins émettent des opérations JSON Patch RFC 6902 sur l’ensemble des documents rendus. L’hôte remet à chaque étape l’ensemble de documents indexé par clé en entier ; l’étape sélectionne par leur contenu les documents qu’elle cible et renvoie des correctifs adressés par clé, que le moteur d’application applique aux documents adressés — typiquement en ajoutant un conteneur sidecar, en montant un volume de secret ou en réécrivant une variable d’environnement. Une étape renvoie aussi side_effects (ci-dessous), diagnostics — chaque entrée ayant la même forme partagée Diagnostic dans laquelle chaque socket signale les problèmes — et outputs (ci-dessous). Décrit dans examples/04-secrets.md.
État actuel : disponible. Chaque étape déclarée s’exécute pendant aggrega build.
Encodage de transmission. L’entrée d’une étape (FRPStepInput) et sa réponse (FRPStepOutput) circulent en CBOR canonique (RFC 8949 §4.2.1), dans les deux sens. Un guest décode son entrée et encode sa réponse au moyen des points d’entrée que portent les types de charge utile — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust (sur les types que publie le crate aggrega-abi), decodeCBORFRPStepInput et encodeCBORFRPStepOutput en TypeScript — en lisant et en écrivant des octets (Vec<u8> en Rust, Host.inputBytes() et Host.outputBytes(...) en TypeScript). Aucune bibliothèque CBOR n’est nécessaire et rien n’analyse les octets à la main. L’entrée with de l’étape (step_input), les outputs qu’elle renvoie et les ensembles de documents own et host sont des tables que le schéma marque comme préservant l’ordre, si bien qu’ils circulent sous la forme de listes ordonnées d’entrées dans l’ordre où le pipeline les contient, et qu’un guest les lit et les écrit au moyen du conteneur de son kit qui conserve l’ordre — c’est ce qui permet aux sorties d’une étape d’atteindre .steps.<id>.outputs dans l’ordre où l’étape les a renvoyées. Le tree de chaque unité, chaque valeur de step_input et de outputs, la value d’un correctif, le crd d’un effet de bord et le context de rendu circulent sous la forme des octets de leurs documents JSON, qu’un guest analyse comme du JSON pour en examiner le contenu ; les bytes d’une unité circulent sous la forme d’une suite d’octets bruts que le décodeur généré place dans le type de champ propre au kit — une tranche d’octets en Go, une chaîne base64 en Rust et en TypeScript. Chaque diagnostic circule dans la forme partagée Diagnostic. Une réponse qui n’est pas un FRPStepOutput dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — fait échouer l’étape, en nommant la fonction qu’elle exécute, ce qui arrête le build à moins que l’étape ne soit optional. Appelée directement avec aggrega plugin run-local --export step, une étape reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage, et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
Effets de bord — émission de ressources (plugins d’identifiants dans le pipeline des plugins)
Les pipelines de FeatureRecipe d’identifiants (principe du Plugin en deux parties : Fetcher + Injector) émettent des ressources complètes à côté d’un correctif au moyen des side_effects d’une étape, chacune déclarant l’un des deux types que le contrat définit : emit_crd, un document de ressource personnalisée tel qu’une CRD ExternalSecret ou VaultSecret que le cluster récupère à l’exécution, ou emit_file, un fichier écrit. Une étape qui renvoie tout autre type arrête le build, en nommant le nœud, l’index de l’effet de bord et le type qu’elle a déclaré. L’étape du Fetcher émet la ressource complète ; l’étape de l’Injector renvoie un correctif qui monte le Secret Kubernetes résultant. Décrit dans examples/04-secrets.md.
État actuel : disponible.
Sortie d’étape (table outputs d’une étape de pipeline:)
Une étape du pipeline des plugins publie des sorties nommées que les étapes suivantes consomment au moyen de {{ .steps.<id>.outputs.<key> }}. La forme de sortie est définie par le fournisseur pour chaque plugin ; les sorties d’étape ont pour portée le même pipeline et ne sont visibles que par les étapes suivantes, dans l’ordre de déclaration. Documenté dans templates/expansion-matrix.md, ligne 10.
État actuel : disponible.
Rendu de Provider — le socket piloté par le guest
Un fournisseur est un guest Wasm. Le rendu est exclusivement Wasm : le nom capability: d’une Recipe se résout vers le Plugin de rendu de fournisseur (pluginType: provider) qui liste ce nom dans ses spec.provider.capabilities et annonce un export render_node, et le guest de ce plugin effectue le rendu du nœud. Il n’existe aucun moteur de rendu dans l’hôte sur lequel se replier ; un nom de fournisseur qui ne se résout vers aucun Plugin qui le sert arrête le build au moment du routage. Ajouter un fournisseur standard revient à livrer un guest .wasm et une entité Plugin du catalogue — l’hôte ne contient aucun code propre à un fournisseur.
Une capacité qu’un fournisseur sert ne contient pas de deux-points, pas plus qu’une capacité avec laquelle une étape de pipeline se déclare compatible. Le capability: d’une Recipe se lit comme la capacité jusqu’à son dernier deux-points, suivie d’un épinglage de version — helm:1.0.0 demande helm en version 1.0.0 — si bien qu’un nom contenant un deux-points est un nom qu’aucune Recipe ne peut demander. L’hôte refuse un tel nom dans les capabilities de describe() pour un guest provider ou pipeline-step lorsque le guest se charge et lorsque son entité est générée pour la publication, en nommant le guest et le nom. Le parse:<format> d’un parseur et l’import:<format> d’un importateur conservent leur deux-points : ceux-ci sont recherchés par format, jamais au moyen du capability: d’une Recipe.
L’hôte est un routeur générique. Il lit l’auto-description describe() du guest — y compris son contrat de comportement de rendu — et distribue les exports du guest sans comprendre aucun format de fournisseur. Ce contrat pilote la distribution sous forme de données :
input_kinds(sourced,synthesized,artifacts_standalone) — les types d’entrée de Recipe dont le guest effectue le rendu ; l’hôte contrôle le type d’entrée d’un nœud par rapport à cet ensemble.boundary_assembly(none|merge|nest) — la façon dont le guest combine la sortie d’un groupe de distribution :mergeclasse la sortie de chaque nœud comme des fragments que l’assembleur fusionne en un seul artefact,nestimbrique les fichiers de chaque nœud sous une enveloppe assemblée,noneécrit directement la sortie de chaque nœud.nest_segment(facultatif) — pour un assemblagenest, le répertoire sous lequel est placé le sous-répertoire propre à chaque contributeur, écrit comme un seul nom de répertoire ; en son absence, le sous-répertoire de chaque contributeur se trouve directement à la position de distribution.assembly_name_annotation(facultatif) — une annotation de frontière dont la valeur résolue nomme l’artefact que le guest assemble à partir d’un groupe de distribution ; en son absence, le guest nomme son assemblage à partir du seul chemin de distribution.cross_boundary_linking(facultatif) — indique si le guest relie une arêteusesentre frontières au moyen de ses exportslink_publishetlink_resolve; un guest le déclare vrai exactement lorsqu’il exporte les deux, et le chargement refuse un guest dont l’indicateur et les exports ne concordent pas.artifact_delimiters(facultatif) — la paire de délimiteurs de template Go que le guest applique aux corps des artefacts.reusable_instance(facultatif) — indique si une seule instance chargée peut servir chaque passage du build (voir Déterminisme et réutilisation des instances ci-dessous).omits(facultatif) — indique si le guest respecte les entrées d’omission que porte un rendu de source (voir Laisser de côté des unités rendues ci-dessous).boundary_artifacts(facultatif) — indique si la cible du guest accepte les fichiers qu’une Recipe apporte à la sortie partagée de sa frontière (voir Accepter les fichiers qu’une Recipe apporte à la frontière ci-dessous).source_ignore(facultatif) — les fichiers que l’écosystème du guest ne livre jamais à côté d’une source dont il effectue le rendu (voir Déclarer ce que l’écosystème d’une source ne livre jamais ci-dessous).
Le socket est un ensemble fixe d’exports — un obligatoire, les autres facultatifs et annoncés dans describe() :
render_node(obligatoire) — effectue le rendu d’un nœud IR en fichiers natifs du fournisseur.assemble_boundary(facultatif) — fusionne la sortie par nœud d’un groupe de distribution en un seul artefact par chemin (présent lorsqueboundary_assemblyvautmergeounest).validate_node_input(facultatif) — validation structurelle de l’entrée d’un nœud avant le rendu ; un diagnostichaltarrête le build, unwarnremonte dans le résultat du build.carve/reassemble(facultatifs, appariés) — le codec de correctifs propre au guest, fidèle à l’octet près, pour les étapes de pipeline postérieures au rendu, utilisé seulement lorsque les deux sont annoncés.name_bound(facultatif) — le guest juge si un nom que l’hôte propose comme identité de composant produit des noms que sa cible accepte, en répondant par une contrainte plutôt que par un nom de son choix.rendered_name(facultatif) — le guest indique le nom que sa cible donne aux ressources dont il effectue le rendu pour un nœud.link_publish/link_resolve(facultatifs, appariés) — le guest relie une arêteusesentre frontières : l’extrémité consommée publie un identifiant, et l’extrémité consommatrice le résout dans sa propre sortie assemblée.
Les artifacts: d’une Recipe sont intégrés à render_node au moyen d’une projection des artefacts dans l’entrée : l’hôte effectue la lecture de $import, l’évaluation des templates Go et le calcul des clés/valeurs de provenance, et remet au guest chaque entrée déjà lue et évaluée ; le guest est responsable du placement et de l’émission dans le format que lui seul connaît. Documenté dans architecture/13-catalog-and-registry.md.
L’entrée d’un rendu de source porte les valeurs du nœud dans node.values, et node.values_mapped indique d’où elles viennent : il vaut true lorsqu’elles sont la sortie du valuesMapping de la Recipe — ou, pour le rendu propre d’un rattachement, de celui de sa FeatureRecipe — et il est absent lorsqu’elles sont les valeurs propres du composant transmises telles qu’elles sont écrites. Qu’un guest le lise ou non relève du contrat propre à ce guest. Le fournisseur cloudformation ne lie les Parameters d’un template issu d’une source qu’à des valeurs produites par un mappage, car les valeurs propres d’un composant peuvent avoir été écrites pour les autres entrées de la Recipe ; le fournisseur terraform écrit les arguments d’un module issu d’une source à partir des valeurs que reçoit son assemblage, et ne lit pas l’indicateur. Ces valeurs circulent sur chaque nœud rendu d’une entrée de assemble_boundary pour un nœud rendu à partir d’une source — celles d’un composant, qu’un mappage les ait produites ou non, celles d’une Feature rattachée seulement là où le valuesMapping de sa FeatureRecipe les a produites — et le même indicateur circule à côté d’elles et seulement là où elles circulent, si bien qu’un assembleur lit la même réponse que le rendu propre du nœud ; le fournisseur cloudformation l’y lit pour savoir quels paramètres la liaison d’un nœud a renseignés, et refuse une référence à l’un d’eux depuis tout autre endroit de la stack, y compris le composant hôte d’une Feature rattachée. L’indicateur enregistre la façon dont les valeurs ont été produites et n’est jamais dérivé d’une clé ni d’une valeur.
Encodage de transmission. Chaque export de ce socket prend son entrée et renvoie sa sortie en CBOR canonique (RFC 8949 §4.2.1), dans les deux sens. Un guest décode son entrée et encode sa sortie au moyen des points d’entrée que portent déjà les types de charge utile — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, et en TypeScript les fonctions decodeCBOR et encodeCBOR de chaque type, comme decodeCBORRenderNodeInput et encodeCBORRenderNodeOutput — en lisant et en écrivant des octets (Vec<u8> en Rust, Host.inputBytes() et Host.outputBytes(...) en TypeScript). Aucune bibliothèque CBOR n’est nécessaire et rien n’analyse les octets à la main. Le content d’un fichier rendu, et tout autre champ d’octets, circule sous la forme d’une suite d’octets bruts que le décodeur généré place dans le type de champ propre au kit : une tranche d’octets en Go, une chaîne base64 en Rust et en TypeScript. Les tables que le schéma marque comme préservant l’ordre — parmi lesquelles les values, features et uses d’un nœud, les derived_keys d’une réponse et les values d’un contributeur d’assemblage — circulent sous la forme de listes ordonnées d’entrées dans l’ordre où le build les contient, et un guest les lit au moyen du conteneur de son kit qui conserve l’ordre. Chaque valeur des values d’un nœud circule sous la forme des octets de son propre document JSON, si bien que les clés à l’intérieur d’une valeur conservent l’ordre dans lequel elles ont été écrites ; il en va de même pour chaque entrée de rattachement de features, le contexte de rendu, la charge de travail analysée, chaque arête enrichie, chaque unité découpée et chaque opération de correctif, et un guest les analyse comme du JSON pour en examiner le contenu. Chaque diagnostic circule dans la forme partagée Diagnostic. Une réponse qui n’a pas la forme de sortie de son export dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — arrête le build, en nommant l’export qu’il a appelé. Les exemples de charges utiles de cette page sont écrits en JSON pour faciliter la lecture. Appelé directement avec aggrega plugin run-local --export render_node, ou avec tout autre export du socket, un guest reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage, et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
État actuel : disponible pour les cinq fournisseurs. Le guest helm effectue le rendu des charts issus d’une source (en résolvant la racine du chart), des charges de travail synthétisées et des artefacts autonomes sous forme de manifestes Kubernetes à plat. Le guest helm-chart assemble un chart parapluie, en imbriquant le chart issu d’une source de chaque nœud comme sous-chart, et porte un codec de correctifs fidèle à l’octet près ainsi que des délimiteurs d’artefact entre crochets ([[ ]]). Le guest compose effectue le rendu des fichiers compose issus d’une source et des charges de travail synthétisées et fusionne un groupe de distribution en un seul docker-compose.yaml, en reliant un service aux réseaux des composants que nomme son x-aggrega-networks-of. Le guest terraform émet la configuration Terraform telle quelle (HCL ou JSON) ou intègre un module issu d’une source et fournit ses entrées comme arguments du bloc module de ce composant, valide structurellement le HCL d’un module issu d’une source avant le rendu, et compose une frontière en une seule configuration racine qui déclare chaque composant comme un bloc module ayant pour source le sous-répertoire propre à ce composant. Le guest cloudformation effectue le rendu des templates issus d’une source et des fragments de stack autonomes, fusionne un groupe de distribution en un seul template de stack, et relie une arête uses entre frontières au moyen de link_publish et link_resolve. Chacun effectue le rendu hors ligne et de façon déterministe.
Déclarer les noms qu’un guest dérive
Un guest de fournisseur dérive généralement des noms dont sa sortie a besoin mais que personne n’a écrits — l’identifiant par lequel une cible adresse une ressource, le nom sous lequel une sortie est publiée pour qu’une autre y fasse référence — à partir de l’identité du nœud et de la ressource qu’il émet. Deux nœuds peuvent aboutir au même nom chaque fois que les éléments dont ils sont dérivés concordent, et comme le nom se trouve dans les octets du fichier que l’hôte écrit tels quels, l’hôte ne peut pas voir le conflit : il lui faudrait analyser le format du fournisseur pour le trouver, ce qui est exactement la connaissance qui reste dans le guest.
render_node renvoie donc des derived_keys facultatives dans sa sortie, et le sens est inversé — au lieu que l’hôte inspecte la sortie, le guest déclare et l’hôte vérifie :
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Chaque clé de derived_keys est un espace de clés que le guest nomme, et chaque espace porte les noms que le guest y a dérivés, dans l’ordre de dérivation. Les noms des espaces comme les noms qu’ils contiennent relèvent de votre vocabulaire : l’hôte ne les lit que comme des chaînes à comparer pour l’égalité au sein d’un même espace. Il n’analyse aucun nom, n’apprend pas ce que signifie un espace ou un nom, et n’en dérive jamais un lui-même — ainsi un seul contrôle couvre toute sorte de nom que dérive n’importe quel fournisseur, et un nouveau fournisseur ne nécessite aucun nouveau code dans l’hôte. Dans les types publiés, derived_keys est une table qui conserve l’ordre, si bien que les espaces circulent dans l’ordre où votre guest les définit.
Ce que l’hôte en fait tient en une seule question : au sein d’un espace, chaque nom déclaré est-il distinct parmi les contributeurs dont la sortie fusionne en un seul assemblage ? Deux contributeurs déclarant un même nom dans un même espace arrêtent le build, et l’arrêt nomme l’espace, le nom et les deux contributeurs, si bien qu’un auteur peut agir sans lire le fournisseur. Des noms distincts, et des noms qui se trouvent coïncider entre deux espaces différents, passent.
Trois propriétés sont utiles à connaître lorsque vous décidez de ce que vous déclarez :
- La portée est une sortie assemblée — l’ensemble des contributeurs dont les fichiers fusionnent. Un guest qui veut l’unicité sur une portée plus étroite ou plus large que celle-ci exprime cette portée dans le nom d’espace qu’il déclare, ce qui laisse le choix entre vos mains plutôt qu’entre celles de l’hôte.
- Un contributeur peut répéter librement un nom. Un nœud peut être rendu au cours de plusieurs passages — un rendu de source, une synthèse de charge de travail, un placement d’artefacts — et les déclarations fusionnent. Le même nom déclaré deux fois par un contributeur, c’est ce contributeur qui décrit deux fois une même ressource, et non un conflit.
- Déclarer ne change aucun octet. Le champ est une assertion sur ce que le guest a dérivé, jamais une modification de ce qu’il a émis, si bien que la sortie rendue d’un guest est identique qu’il déclare ou non. Omettre
derived_keysest valide et laisse le contrôle inactif pour ce guest.
Signaler des faits sur ce qu’un guest a émis
Certaines choses concernant le rendu d’un nœud ne sont visibles que du fournisseur qui l’a produit — ce que contiennent les documents qu’il a écrits, quels noms ils définissent, combien d’éléments d’un certain type il a émis — parce que les extraire des octets du fichier suppose de comprendre le format du fournisseur. render_node peut signaler ces choses lui-même, dans une liste facultative render_facts à côté de ses fichiers :
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Chaque fait est un name et une value, et tous deux appartiennent à votre fournisseur : les faits qu’il signale, ce que signifie chaque nom et ce que contient chaque entrée font partie du contrat documenté propre à votre fournisseur ; documentez-les donc pour les auteurs qui les liront.
Signalez la valeur de chaque fait sous forme de liste — un tableau JSON — même lorsqu’elle ne contient qu’une entrée. Un même nom peut être signalé par plus d’un rendu d’un composant : son propre rendu peut nécessiter plusieurs appels — un rendu de chart et un placement d’artefacts, par exemple — et chaque Feature rattachée au composant est rendue par un appel au fournisseur qui lui est propre. Aucun fournisseur ne peut savoir, au moment du rendu, si son signalement sera le seul sous un nom ; chaque signalement est donc une liste, et le compilateur réunit en une seule liste les listes qu’un nom reçoit. Un fait dont la valeur est autre chose — un objet, une chaîne, un nombre, un booléen, null — est refusé lorsque votre guest le renvoie : le build s’arrête avec le code court E0325, en nommant le fait, le nœud et votre guest, et en indiquant quelle était la valeur. Les entrées d’une liste sont des valeurs JSON quelconques, dans la forme que vous documentez.
Qu’une valeur soit une liste est la seule chose que le compilateur en apprend. Il indexe les faits par nom et remet chaque liste aux templates qui la lisent — les faits du composant hôte à chaque Feature qui lui est rattachée, les faits de chaque appelant à une Feature qui déclare lire les faits de rendu de ses appelants, et les faits de chaque cible à une Feature qui déclare lire les faits de rendu des composants auxquels son composant hôte est relié, comme le décrit le contexte de template — en décodant chaque liste en une valeur qu’un template peut parcourir. Il n’apprend jamais ce que signifie un nom ou une entrée et ne dérive jamais un fait lui-même, si bien qu’un nouveau fournisseur peut signaler de nouveaux faits sans aucune modification du côté du compilateur. Les faits qu’une Feature rattachée au nœud signale à partir de son propre rendu sont tenus à l’écart de ceux que le rendu propre du nœud a signalés.
Quatre propriétés sont utiles à connaître lorsque vous décidez de ce que vous signalez :
- L’ordre vous appartient. Les faits conservent l’ordre dans lequel votre guest les liste, et chaque valeur conserve ses propres octets — l’ordre des entrées d’une liste et des clés de chaque objet est l’ordre que votre guest a écrit. Listez les faits dans un ordre fixe, et écrivez chaque entrée avec un ordre de clés fixe, afin que des données d’entrée identiques produisent des octets identiques ; une liste de faits plutôt qu’une table existe précisément pour que cet ordre survive dans le type séquence propre à chaque kit sans rien à marquer, alors qu’une table ne conserve l’ordre écrit par un guest que lorsque son schéma la marque comme préservant l’ordre et que le guest remplit le conteneur qui conserve l’ordre de son kit.
- Signaler ne change aucun octet. Les fichiers que le compilateur écrit sont les fichiers que votre guest a renvoyés, que des faits les accompagnent ou non.
- Un nœud peut signaler au cours de plusieurs passages. Un nœud peut être rendu sous forme de rendu de source, de synthèse de charge de travail et de placement d’artefacts ; les faits que chacun signale sont conservés dans l’ordre où les passages se sont exécutés, et un nom signalé par plus d’un d’entre eux se lit comme une seule liste qui les réunit dans cet ordre.
- Ne rien signaler est complet. Omettre
render_factsest valide, et un fournisseur qui ne signale rien effectue le rendu exactement comme il le ferait sans le champ.
Le type RenderFact est publié dans les trois paquets ABI et réexporté par le kit de développement de plugins de chaque langage, et les exemples de rendu des kits signalent deux faits à côté de leurs fichiers. En Go, une valeur est le JSON que votre guest écrit ; sérialiser une tranche de structs plutôt que de tables est ce qui conserve les clés de chaque entrée dans l’ordre où vous les avez déclarées :
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}Laisser de côté des unités rendues
Un rendu de source peut nommer des unités que le fournisseur doit laisser de côté dans ce qu’il rend — un Secret qu’un chart récupéré génère à nouveau à chaque rendu, par exemple. Quelle unité rendue une entrée désigne est une connaissance que seul votre fournisseur possède ; les entrées parviennent donc à votre guest, et c’est votre guest qui les laisse de côté. Elles arrivent dans l’entrée de render_node sous la forme d’une liste facultative omits à côté du source_listing :
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}Chaque entrée est un kind, un name et un namespace facultatif, déjà résolus en chaînes simples et listés dans l’ordre où l’auteur les a déclarés ; une entrée qui ne s’applique pas au build n’est pas transmise. Ce que sélectionnent les trois champs relève du contrat propre à votre fournisseur — le type, le nom et le namespace d’une ressource dans le format de votre cible — documentez-le donc pour les auteurs qui écrivent les entrées.
Un auteur peut construire les champs d’une entrée à partir d’une valeur qu’il a déclarée sensible — une ressource nommée d’après un paramètre sensible, par exemple. Une telle entrée arrive avec "sensitive": true, et votre guest la traite comme il traite toute autre valeur marquée que porte l’entrée de rendu (voir Valeurs qu’une entrée marque comme sensibles) : il continue de faire correspondre et de compter l’entrée d’après ses champs, ce qui est la raison d’être de l’entrée, et tient chacun de ses champs à l’écart d’un refus, d’un avertissement ou d’une ligne de journal. Le marquage couvre l’entrée entière, car le compilateur n’indique pas quel champ la valeur a produit. Il est absent lorsqu’aucun champ n’a été construit à partir d’une telle valeur.
Un guest qui respecte les entrées fait trois choses :
- Il fait correspondre chaque entrée à ce qu’il a rendu, dans les termes de votre format.
- Il laisse chaque unité correspondante en dehors de tout ce qu’il renvoie — ses
files, les noms qu’il déclare dansderived_keyset les faits qu’il signale dansrender_facts— si bien que rien de ce que reçoit le compilateur ne la décrit encore. - Il signale un décompte par entrée dans une liste facultative
omittedde sa sortie, dans l’ordre d’arrivée des entrées, chacun étant le nombre d’unités auxquelles cette entrée a correspondu, comptées qu’une autre entrée leur ait aussi correspondu ou non :
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}Un zéro est une réponse complète : cette entrée n’a correspondu à rien de ce que votre guest a rendu. Les décomptes sont tout ce qui revient sur ce qui a été laissé de côté ; les unités elles-mêmes sont simplement absentes de ce que votre guest a renvoyé.
Un fournisseur qui fait ces trois choses le déclare avec omits: true dans son contrat. L’entité Plugin enregistre la même revendication sous spec.provider.contract.omits ; lorsque l’entité porte un contrat de comportement de rendu, le chargement refuse un guest dont le describe() indique une valeur différente. Les entrées accompagnent une liste de la source et rien d’autre : un rendu d’une charge de travail synthétisée ou d’un ensemble d’artefacts ne les porte jamais.
Un rendu qui ne porte aucune entrée n’est pas modifié par les champs. Les deux champs sont facultatifs et absents lorsqu’ils sont vides, si bien qu’un rendu qui ne porte aucune entrée traverse le socket octet pour octet comme si les champs n’existaient pas, et qu’un guest qui ne les lit jamais n’en est pas affecté. Le type OmitEntry est publié dans les trois paquets ABI et réexporté par le kit de développement de plugins de chaque langage.
Ce que fait le compilateur de votre réponse. Les entrées proviennent de la clé omits: qu’un auteur écrit sur une Recipe ou une FeatureRecipe (Recipe → Le champ omits:) ; le compilateur évalue les templates de chaque entrée et remet à votre guest celles qui s’appliquent. Il lit ensuite vos décomptes, et seulement vos décomptes — il ne regarde jamais dans un fichier renvoyé pour les vérifier :
- Une liste de décomptes qui ne comporte pas un décompte non négatif par entrée transmise arrête le build — absente, trop courte, trop longue, ou contenant un décompte inférieur à zéro — en nommant le nœud, votre fournisseur, le nombre d’entrées transmises et le nombre de décomptes revenus. Un signalement qui ne concorde pas ne laisse aucun moyen de savoir quelle entrée a laissé quoi de côté. Voir A provider’s omitted counts do not match the omits entries it was handed (Les décomptes d’omissions d’un fournisseur ne correspondent pas aux entrées omits qui lui ont été transmises).
- Un zéro arrête le build, en nommant la première entrée, dans l’ordre de l’auteur, dont le décompte est zéro : le nœud, votre fournisseur, la position de l’entrée dans la liste que déclare son document, ainsi que le type, le nom et le namespace auxquels elle s’est résolue. Votre guest signale le zéro ; l’arrêt revient au compilateur. Voir An omits entry left out nothing the source rendered (Une entrée omits n’a rien laissé de côté de ce que la source a rendu).
- Un document déclarant
omits:dont le fournisseur ne revendique pasomits: trueest refusé avant tout rendu, si bien qu’un auteur apprend tout de suite que la clé n’aurait aucun effet, au lieu de trouver le document dans la sortie. Le compilateur lit votre revendication dans votredescribe()une fois que chaque Recipe et FeatureRecipe du build est liée, et refuse avant que le premier composant ne soit rendu — si bien qu’un guest qui ne revendique pas la clé ne reçoit jamais d’entrée. Le refus nomme le fournisseur et le composant pour lequel le document effectue le rendu, ou, pour une FeatureRecipe qui génère une seule fois pour une frontière, la frontière et le rattachement. Voir The provider does not support omits (Le fournisseur ne prend pas en charge omits).
État actuel : disponible. Les guests helm, compose et cloudformation distribués avec le compilateur déclarent la revendication et respectent les entrées. Le guest helm n’écrit aucun champ d’aucune entrée dans un texte qu’il renvoie. Les guests compose et cloudformation nomment le type, le nom et le namespace d’une entrée lorsqu’ils refusent l’entrée, ainsi que les unités qu’une entrée a laissées de côté lorsqu’ils refusent un fichier ou un template qui les nomme encore, et y affichent chaque champ d’une entrée marquée sous la forme <redacted>. Les guests helm-chart et terraform ne déclarent pas la revendication ; un document déclarant omits: que l’un d’eux rend est donc refusé.
Accepter les fichiers qu’une Recipe apporte à la frontière
Certains fichiers appartiennent à une frontière dans son ensemble plutôt qu’à l’un de ses composants — une configuration de fournisseur qu’une cible lit une seule fois pour tout ce que la frontière déploie, par exemple. Une Recipe les écrit sous spec.boundary.artifacts, et c’est le compilateur, et non votre guest, qui fait le travail : il évalue chaque fichier dans le contexte dans lequel une entrée artifacts: est évaluée, fusionne par nom les fichiers que chaque contributeur du groupe de distribution a déclarés, et écrit chacun une seule fois dans le répertoire qui contient la sortie assemblée du groupe, à côté de ce que renvoie votre assemble_boundary. Votre guest ne reçoit aucun de ces fichiers sur aucun export et n’est jamais interrogé à leur sujet ; il n’y a donc rien à implémenter — seulement une affirmation à faire sur votre cible :
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Déclarez boundary_artifacts: true uniquement lorsque votre cible lit un fichier placé dans ce répertoire comme faisant partie de la sortie de la frontière. L’entité Plugin enregistre la même revendication sous spec.provider.contract.boundaryArtifacts ; lorsque l’entité porte un contrat de comportement de rendu, le chargement refuse un guest dont le describe() indique une valeur différente. Une Recipe déclarant le bloc dont le fournisseur ne le revendique pas est refusée avant tout rendu, en nommant le fournisseur et le composant ; voir The provider does not support boundary artifacts (Le fournisseur ne prend pas en charge les artefacts de frontière). Un fichier que l’une de ces fusions place sous un nom que votre assemblage écrit aussi arrête le build comme deux contributeurs écrivant un même chemin de sortie, si bien que les noms qu’écrit votre assemblage font partie de ce que vous documentez pour les auteurs.
État actuel : disponible. Le guest terraform distribué avec le compilateur déclare la revendication, et Terraform lit chaque fichier à côté de la configuration racine de la frontière ; les guests helm, compose, helm-chart et cloudformation ne la déclarent pas.
Déclarer ce que l’écosystème d’une source ne livre jamais
Le répertoire source local d’une Recipe — un chart co-localisé, un module — est publié avec la Recipe, et tous les fichiers qu’il contient ne lui appartiennent pas. Un guest de fournisseur indique ce que son propre écosystème ne livre jamais au moyen de source_ignore dans son contrat, sous forme de règles d’exclusion dans la syntaxe qu’utilise .gitignore :
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patternssont des règles lues à partir de la racine du répertoire source, appliquées dans l’ordre, une correspondance ultérieure l’emportant sur une précédente.filesnomme les fichiers d’exclusion que votre écosystème respecte à l’intérieur d’une source. Partout où le parcours d’une source en rencontre un, ses lignes sont lues comme des règles supplémentaires pour le répertoire qui le contient, après vos motifs.
La déclaration est lue lorsqu’une entité est épinglée, et non lorsqu’elle est rendue. L’étape d’épinglage de l’auteur résout, dans son espace de travail, le plugin qui sert la capacité de l’entité, compose vos règles avec son propre .aggregaignore — dont les lignes viennent en dernier et l’emportent donc sur tout chemin qu’elles nomment — et enregistre le nom de votre plugin, sans version, avec les règles composées exactes, dans le entity.lock de l’entité. Chaque publication, chaque comparaison et chaque rendu ultérieurs de cette entité appliquent les règles enregistrées ; l’hôte effectue la correspondance et n’a aucune opinion propre sur un quelconque écosystème. Ainsi, les fichiers que reçoit votre guest au rendu — la liste, et chaque fichier qu’il demande à l’hôte d’empaqueter ou de lire — sont exactement les fichiers que porte une publication de l’entité, et un fichier que les règles laissent de côté reçoit pour réponse qu’il n’existe pas, avec son nom. Un lien symbolique sous une source est refusé avant que votre guest ne soit invoqué.
La compatibilité découle de ce qui a été enregistré. Un guest peut effectuer le rendu d’une Recipe publiée pour sa capacité lorsqu’il parle la même version de l’ABI, que son contrat correspond à la déclaration de son entité et qu’il n’a besoin d’aucun fichier hors de l’ensemble publié. Un guest qui a besoin d’un fichier que l’ensemble a laissé de côté doit faire échouer son build de façon manifeste et nommer le fichier — le refus par l’hôte d’un empaquetage ou d’une lecture le nomme, et un guest reporte cela dans son propre échec. Lorsque le plugin que l’espace de travail d’un consommateur lie à une capacité déclare des règles autres que celles qu’enregistre le fichier de verrouillage d’une entité, le pull du consommateur affiche un avertissement qui nomme les deux plugins et la différence ; il ne s’arrête jamais pour cela.
Omettre source_ignore ne déclare aucune règle, et une source dont vous effectuez le rendu conserve alors chaque fichier que conservent les règles propres de l’auteur. Le champ est facultatif et ne nécessite aucune version de l’ABI qui lui soit propre : un guest qui l’omet se charge comme un guest qui ne déclare rien. L’entité Plugin enregistre la même déclaration sous spec.provider.contract.sourceIgnore ; lorsqu’elle le fait, le chargement refuse un guest dont le describe() indique autre chose.
Déterminisme et réutilisation des instances
L’hôte consomme les octets de sortie d’un guest tels quels, si bien qu’un guest doit produire une sortie identique à partir d’une entrée identique. Par défaut, un guest est chargé à neuf pour chaque nœud — aucun état n’est transporté d’un nœud à l’autre, par construction. Un guest qui déclare de lui-même reusable_instance est en revanche chargé une seule fois par build et son instance unique sert chaque passage, ce qui récupère le coût d’instanciation par nœud, qui est le coût dominant. Comme la réutilisation n’est sûre que pour un guest sans état, aggrega build --verify-determinism effectue le rendu de chaque nœud deux fois au moyen de la même instance et arrête le build si les deux rendus d’un nœud quelconque diffèrent ; le build par défaut effectue le rendu une seule fois et fait confiance à la déclaration. Le cache de compilation Wasm est stocké sur disque et partagé à l’échelle du processus, si bien qu’un guest est compilé une seule fois et que les builds à chaud sautent la recompilation.
Le socket de linter — le linter de publication
Le socket de linter est livré sous la forme du publishing-linter standard, un point de contrôle hors bande qui s’exécute par aggrega lint plutôt qu’au moment de la compilation. Il consomme une entité du catalogue (et, en mode --pre-publish, la version actuellement publiée de l’entité) et renvoie une liste de constats, chacun avec un niveau de gravité et un message ; en mode --pre-publish, il renvoie aussi une classification de l’incrément de version. L’hôte le distribue au moyen du runtime Wasm embarqué, derrière le même pare-feu de pureté AOT que tout autre socket. L’ensemble complet des règles, les niveaux de gravité et les désactivations par règle sont documentés dans cli/aggrega-lint.md.
Le linter est une discipline de catalogue à activer volontairement : le compilateur ne l’exécute pas pendant aggrega build (à la seule exception de l’avertissement qui déconseille x-aggrega-*, qui apparaît au niveau de gravité warn pendant le build et au niveau de gravité halt sous aggrega lint --pre-publish). Comme les règles résident dans un plugin, une entreprise peut diriger aggrega lint vers un autre plugin de linter pour faire respecter sa propre discipline.
Aucune valeur de paramètre n’atteint un plugin de linter, quelle que soit la portée dans laquelle aggrega lint s’exécute. Avant qu’un document soit remis, l’hôte retient les valeurs par défaut des paramètres d’un Aggregate, les valeurs qu’il transmet à chaque module qu’il importe et les paramètres d’une Release, en conservant le contrat de chaque déclaration de paramètre — seulement les clés avec lesquelles une déclaration est écrite, à chaque niveau d’imbrication — et tout texte de template qui lit un paramètre : la valeur d’un paramètre peut être elle-même un identifiant secret, et le plugin rattaché ici peut être du code que l’espace de travail n’a pas écrit. Ce que contient chaque document est exposé sous Ce que reçoit un plugin de linter.
Encodage de transmission. L’entrée et la sortie circulent toutes deux en CBOR canonique (RFC 8949 §4.2.1). Un guest décode son entrée et encode sa sortie au moyen des points d’entrée que portent déjà les LinterInput et LinterOutput de son kit — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, decodeCBORLinterInput et encodeCBORLinterOutput en TypeScript — en lisant et en écrivant des octets (Vec<u8> en Rust, Host.inputBytes() et Host.outputBytes(...) en TypeScript). Aucune bibliothèque CBOR n’est nécessaire et rien n’analyse les octets à la main. Les documents d’entité — proposed, previous, implemented_component et release — et chaque valeur de components circulent sous la forme des octets de leurs documents JSON, si bien qu’un guest les analyse comme du JSON pour en examiner le contenu. components est une table que le schéma marque comme préservant l’ordre, si bien que, dans l’entrée d’une règle qui lit une Release entière, elle circule sous la forme d’une liste ordonnée d’entrées dans l’ordre où l’Aggregate déclare ses instances de composant, et qu’un guest la lit au moyen du conteneur de son kit qui conserve l’ordre. policies circule sous la forme d’une table ne contenant que les indicateurs définis, si bien qu’un indicateur qu’elle ne contient pas se lit comme faux, et chaque constat circule dans la forme partagée Diagnostic. Une réponse qui n’est pas un LinterOutput dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — fait échouer le lint, en nommant l’export appelé, au lieu d’être lue comme une exécution qui n’a rien trouvé. Appelé directement avec aggrega plugin run-local --export lint_rules, un linter reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage, et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
État actuel : disponible. Le publishing-linter est livré et s’exécute par l’intermédiaire de l’hôte via aggrega lint.
Le socket de parseur — sortie d’arbre canonique
Un parseur transforme une source écrite dans un format que le compilateur ne lit pas nativement en un arbre structuré canonique, si bien qu’un consommateur lit l’arbre au lieu d’embarquer son propre parseur. L’hôte résout le parseur qui annonce le format demandé sous la forme parse:<format> et appelle son export parse à trois endroits : lorsqu’une politique du rôle render-verdict reçoit un artefact rendu dans un format qu’elle ne lit pas nativement, lorsqu’un importateur demande un arbre à l’hôte au moyen de aggrega_parse_source, et lorsqu’une importation qui ne nomme aucun format est reconnue (voir le socket importateur ci-dessous). Un guest n’appelle jamais lui-même un parseur.
Forme d’entrée (hôte → guest). Un document ParseInput contenant :
format— le format demandé, l’une des capacitésparse:<format>du parseur sans son préfixe.bytes— les octets de la source.options— un document d’options que le consommateur fournit pour un comportement propre au parseur, transmis tel quel. Absent lorsque le consommateur n’en fournit aucun.
Forme de sortie (guest → hôte). Un document ParseOutput contenant le tree — la source analysée sous forme de document JSON, dont le premier niveau peut être un objet, un tableau ou un scalaire — les éventuels diagnostics dans la forme partagée Diagnostic, des plages de source facultatives qui situent les nœuds de l’arbre dans les octets d’origine, et un échec signalé dans error lorsque l’analyse n’a pas pu aboutir. Chaque champ et ses contraintes figurent dans la référence du schéma du socket de parseur générée.
Encodage de transmission. L’entrée et la sortie circulent toutes deux en CBOR canonique (RFC 8949 §4.2.1), l’encodage dans lequel circule le même ParseInput lorsqu’un guest le remet à aggrega_parse_source. Un guest décode son entrée et encode sa sortie au moyen des points d’entrée que portent déjà les ParseInput et ParseOutput de son kit — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, decodeCBORParseInput et encodeCBORParseOutput en TypeScript — en lisant et en écrivant des octets (Vec<u8> en Rust, Host.inputBytes() et Host.outputBytes(...) en TypeScript). Aucune bibliothèque CBOR n’est nécessaire et rien n’analyse les octets à la main. Les octets de la source circulent sous la forme d’une suite d’octets bruts, et le décodeur généré les place dans le type de champ propre au kit : une tranche d’octets en Go, une chaîne base64 en Rust et en TypeScript. options et tree circulent sous la forme des octets de leurs documents JSON, si bien que l’arbre qu’écrit un parseur atteint son consommateur tel quel. Un parseur qui ne peut pas aboutir en indique la raison dans le error de la sortie, et l’analyse échoue en nommant le parseur et ce message ; une réponse qui n’est pas un ParseOutput dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — fait elle aussi échouer l’analyse, en nommant le parseur et son export parse. Une analyse échouée arrête un build au rôle render-verdict, et atteint un importateur sous la forme de l’échec par lequel répond aggrega_parse_source. Il en va de même d’une source que le parseur refuse — une source à laquelle il répond par un diagnostic halt à côté de son arbre : l’appel de l’importateur échoue avec le message de chacun de ces diagnostics, dans l’ordre du parseur, et ne reçoit jamais l’arbre. Appelé directement avec aggrega plugin run-local --export parse, un parseur reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage — la source écrite dans cette charge utile en base64, comme JSON écrit tout champ d’octets — et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
Définitions de types. Les types de transmission du parseur — ParseInput, ParseOutput, NodeSpan et SourceSpan — sont publiés dans les trois paquets ABI et réexportés par le kit de développement de plugins de chaque langage, générés à partir d’un même codec afin que les trois restent synchronisés. L’exemple parse de chaque kit lit son entrée et écrit sa sortie de cette façon, tout comme les parseurs pour HCL, TOML, YAML, JSON et JSON avec commentaires livrés dans le binaire.
État actuel : disponible — distribué au rôle render-verdict pour un artefact dans un format que la politique ne lit pas nativement, au moyen de aggrega_parse_source pour un importateur, et pour reconnaître le format d’une importation qui n’en nomme aucun.
Le socket d’importateur — sortie de brouillons de création
Un importateur transforme une source écrite pour un autre outil — un flux exporté depuis un constructeur d’agents, par exemple — en fichiers de création Aggrega en brouillon. Il s’exécute hors bande : aggrega import, la méthode aggrega/import de la session de l’éditeur et l’outil import destiné à l’assistant résolvent l’importateur qui annonce le format demandé sous la forme import:<format> et appellent son export import une fois par importation. Un build ne le distribue jamais. L’importateur qui s’exécute, et ce que lui transmet un opérateur, sont décrits sous Quel importeur transforme une source en brouillons. Les importateurs propres au compilateur, un pour chaque format qu’il lit, sont décrits sur Importateurs core : quels sont ces formats, ce que lit chacun, ce qu’il produit en brouillon, les paramètres qu’il accepte, leur publication avec chaque version du compilateur, et la façon dont une importation en récupère et en vérifie un que la machine ne contient pas encore.
Forme d’entrée (hôte → guest). Un document ImportInput contenant :
format— le format que l’importation a demandé, l’une des capacitésimport:<format>de l’importateur sans son préfixe.bytes— les octets de la source : le fichier entier pour l’importation d’un fichier, et vide pour l’importation d’un répertoire, dont les fichiers arrivent soussources.name— le nom de la source, sans répertoire devant lui, afin que l’importateur puisse nommer la source dans ce qu’il rapporte et dans ce qu’il produit en brouillon : pour l’importation d’un fichier, le nom de base du fichier depuis lequelbytesa été lu ; pour l’importation d’un répertoire, le nom de base du répertoire lui-même, lu depuis son chemin complet, si bien queaggrega import .transmet le nom du répertoire dans lequel la commande s’exécute, tandis que les fichiers du répertoire arrivent toujours chacun sous leur propre nom. Absent lorsque la source n’a aucun nom à donner.sources— les sources nommées, chacune portant son nom et ses octets, dans une seule liste triée par nom : pour l’importation d’un répertoire, chacun de ses fichiers que sélectionnent les motifs de fichier déclarés par l’importateur, hormis le dossier de sortie de build de l’espace de travail, nommé par son chemin séparé par des barres obliques à l’intérieur du répertoire ; et les fichiers que l’entréeplugins.importerrattachant cet importateur déclare souswith.sources, chacun sous son nom de base. Un fichier du répertoire et un fichier dewith.sourcesportant le même nom font refuser l’importation plutôt que l’un ne masque l’autre. Absent lorsqu’il n’y en a aucune.settings— l’objet de paramètres que cette entrée déclare souswith.settings, sous forme de document JSON aux clés triées, transmis tel quel. Absent lorsqu’aucune entrée ne rattache l’importateur ou que l’entrée n’en déclare aucun.catalog— une vue des Components que contient le catalogue propre de l’espace de travail : le catalogue dans lequel l’importateur lui-même a été sélectionné — les dossiers de catalogue de l’espace de travail ou, lorsqu’il n’en nomme aucun, l’instantané du catalogue que publie son registre par défaut, conservé sur cette machine — sans rien récupérer pour la vue elle-même. Sa listecomponentscontient une entrée par nom de Component, triée par nom ; lorsque le catalogue contient plusieurs versions d’un Component, l’entrée décrit la version vers laquelle se résout une référence qui le nomme sans version. Chaque entrée porte lenameet laversiondu Component, seslabels, les noms de clés de premier niveau que déclarent ses values et ses provides (valuesetprovides, chacun trié), et sessockets— chacun avec lenamedu socket et leselectorde labels que doit satisfaire une dépendance reliée par son intermédiaire — dans l’ordre où le Component les déclare. Un Component qui en étend un autre porte ce dont il hérite aussi bien que ce qu’il déclare, et les sockets dont il hérite viennent en premier. La vue ne contient que des noms, des versions, des labels et des sélecteurs — jamais une valeur, une valeur par défaut ni un secret — et son ordre est fixe, si bien qu’un catalogue donne une seule suite d’octets. Absent lorsque le catalogue ne contient aucun Component.
Forme de sortie (guest → hôte). Un document ImportOutput contenant les entités produites par l’importation — chacune une référence à une entité de catalogue existante ou un corps produit en brouillon — les décisions de correspondance qui les sous-tendent, les éventuels diagnostics dans la forme partagée Diagnostic, les fichiers d’échafaudage à écrire, et un échec signalé dans error lorsque l’importation n’a pas pu aboutir. Chaque champ et ses contraintes figurent dans la référence du schéma du socket d’importateur générée.
Encodage de transmission. L’entrée et la sortie circulent toutes deux en CBOR canonique (RFC 8949 §4.2.1). Un guest décode son entrée et encode sa sortie au moyen des points d’entrée que portent déjà les ImportInput et ImportOutput de son kit — DecodeCBOR et EncodeCBOR en Go, decode_cbor et encode_cbor en Rust, decodeCBORImportInput et encodeCBORImportOutput en TypeScript — en lisant et en écrivant des octets (Vec<u8> en Rust, Host.inputBytes() et Host.outputBytes(...) en TypeScript). Aucune bibliothèque CBOR n’est nécessaire et rien n’analyse les octets à la main. settings circule à l’intérieur du document binaire sous la forme des octets de son document JSON, si bien qu’un guest l’analyse comme du JSON pour en examiner le contenu, comme sur tout autre socket. Un importateur qui ne peut pas aboutir en indique la raison dans le error de la sortie, et l’importation s’arrête en nommant l’importateur et ce message ; une réponse qui n’est pas un ImportOutput dans cet encodage — une réponse écrite en JSON, ou une réponse portant un champ de premier niveau que la forme ne déclare pas — arrête elle aussi l’importation, en nommant l’importateur et son export import. Appelé directement avec aggrega plugin run-local --export import, un importateur reçoit la charge utile JSON écrite par l’auteur convertie dans cet encodage, et sa réponse est lue comme la forme de sortie de l’export et affichée en JSON — une réponse qui n’a pas cette forme est refusée, en nommant l’export, comme un build la refuse.
Comment une source de votre format est reconnue. Une importation peut ne nommer aucun format, et l’hôte en reconnaît alors un d’après ce que déclarent les importateurs, sans connaître lui-même aucun format. Un importateur déclare dans son auto-description describe(), sous importer (un ImporterContract), une liste detect des signatures par lesquelles une source de ses formats est reconnue. Chaque DetectSignature nomme :
syntax— le format syntaxique selon lequel la source est analysée, un format qu’un plugin de parseur annonce sous la formeparse:<syntax>, commejsonouyaml;files— des motifs de nom de fichier facultatifs comparés à la fin du nom de la source : un segment au nom propre du fichier, plusieurs segments séparés par des barres obliques à autant de segments finaux de son chemin,*,?et[...]correspondant à l’intérieur d’un segment. Une signature qui n’en déclare aucun s’applique à une source qui est un seul fichier, quel que soit son nom, et à aucun fichier d’un répertoire ;match— les prédicats que l’arbre analysé doit tous satisfaire, chacun unPathMatchavec unpathde clés jointes par des points depuis le sommet de l’arbre (un segment entier sélectionne une position de tableau), unisparmipresent,absent,object,array,string,numberouboolean, et éventuellement une chaîneequalsou une chaîneprefix— au plus l’une des deux.
Lorsqu’une importation ne nomme aucun format, l’hôte confronte les signatures de chaque importateur parmi lesquels l’importation choisit — ceux du catalogue de l’espace de travail et les importateurs core du compilateur — dans l’ordre de leur identité et de leur version : il analyse la source au moyen du parseur que sert le catalogue pour une syntaxe — ou, pour une syntaxe pour laquelle le catalogue ne sert aucun parseur, celui que le compilateur embarque lui-même — au plus une fois par syntaxe, évalue les prédicats sur l’arbre, et lit la source comme le format de l’unique importateur dont la signature correspond. C’est aussi par ce parseur qu’il est répondu à l’appel aggrega_parse_source d’un importateur, si bien qu’un importateur lit sa source au moyen du parseur par lequel elle a été reconnue. Une source qui ne s’analyse pas dans une syntaxe ne correspond à aucune signature nommant celle-ci ; une syntaxe pour laquelle ni le catalogue ni le compilateur ne servent de parseur arrête la reconnaissance, en nommant l’absence du parseur. Une source à laquelle ne correspond aucune signature est refusée en demandant le format, et une source reconnue comme plus d’un format est refusée en les nommant. Une signature reconnaît une source comme chacun des formats qu’annonce son importateur, si bien qu’un importateur dont les sources doivent être reconnues sert un seul format, et qu’un importateur qui ne déclare aucune signature n’est atteint qu’en nommant son format.
L’entité Plugin de l’importateur enregistre la même liste sous spec.importer.detect, dérivée de describe() lorsque l’entité est générée à partir du guest ; la reconnaissance lit cet enregistrement, si bien que le guest n’est pas chargé tant que son format n’est pas établi. Le chargement et la publication du guest refusent un guest dont l’auto-description diffère de l’enregistrement de son entité, en nommant importer.detect, et une entité qui n’en enregistre aucune ne revendique rien. Le descripteur est refusé au chargement lorsque le contrat est déclaré sur un plugin qui n’est pas un importateur, lorsqu’une signature ne nomme aucune syntaxe ou nomme un motif de fichier mal formé, et lorsqu’un prédicat ne nomme aucun chemin, nomme un is en dehors des sept, ou nomme à la fois equals et prefix.
Les importateurs core du compilateur et l’exemple import du kit Go déclarent les leurs de cette façon. L’importateur Langflow lit une source comme du JSON et demande un tableau à data.nodes ; l’importateur Flowise demande des tableaux à nodes et edges et rien à data.nodes ; l’importateur n8n demande un tableau à nodes, un objet à connections et rien à edges ni à data.nodes ; l’importateur MCP déclare une signature par configuration de client, nommant son fichier — .mcp.json, claude_desktop_config.json et .cursor/mcp.json, lus comme du JSON avec un objet à mcpServers, et .vscode/mcp.json, lu comme du JSON avec commentaires, tel que Visual Studio Code le lit, avec un objet à servers — et une signature ne nommant aucun fichier qui demande une chaîne $schema commençant par https://static.modelcontextprotocol.io/schemas/ ; l’importateur Compose lit une source comme du YAML, nomme les fichiers que Compose lit par défaut — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml et leurs quatre fichiers de remplacement — et demande un objet à services ; l’importateur Dify lit une source comme du YAML, ne nomme aucun fichier, et demande la chaîne app à kind et quelque chose à app.mode et à version ; l’importateur CrewAI nomme config/agents.yaml et config/tasks.yaml, lus comme du YAML sans rien demander à l’arbre, crew.jsonc et crew.json, lus comme du JSON avec commentaires avec une liste à agents, et agents/*.jsonc et agents/*.json, lus comme du JSON avec commentaires avec quelque chose à role, de sorte que deux d’entre eux ne correspondent jamais à une même source, et qu’un fichier importé seul sans nommer de format est lu comme du YAML aussi bien que comme du JSON ; l’importateur LangGraph nomme langgraph.json, lu comme du JSON avec un objet à graphs, déclare une signature ne nommant aucun fichier qui demande un objet à graphs et la chaîne https://langgra.ph/schema.json à $schema, et ne nomme aucun fichier d’environnement, puisque la reconnaissance lit tout fichier que sélectionnent les motifs de n’importe quel importateur, si bien qu’un motif en nommant un ouvrirait les fichiers d’environnement de chaque répertoire importé sans nommer de format ; l’importateur Google ADK nomme root_agent.yaml, lu comme du YAML avec quelque chose à name et à instruction, ou une chaîne à agent_class et quelque chose à name, et ne nomme aucun autre fichier, puisque la configuration d’un sous-agent peut s’appeler n’importe comment et qu’un motif nommant tout fichier YAML ouvrirait chacun d’eux dans chaque répertoire importé sans nommer de format ; l’importateur Agent Framework lit une source comme du YAML, ne nomme aucun fichier, et demande la chaîne Prompt à kind et un objet à model ; l’exemple import du kit Go lit une source comme du YAML et demande la chaîne DemoSource à kind. En Go :
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},Ce que lit l’importation d’un répertoire. Une source peut être un répertoire, et les motifs de fichier déclarés par l’importateur décident de ce qu’il lit : l’hôte lit exactement les fichiers du répertoire, à toute profondeur, que sélectionne l’un des motifs files des signatures de l’importateur — chacun comparé à la fin du chemin du fichier séparé par des barres obliques à l’intérieur du répertoire — et les transmet sous sources dans l’ordre des noms, avec bytes vide et le nom propre du répertoire comme name. Aucun autre fichier du répertoire n’est ouvert. Le dossier dans lequel un build de l’espace de travail écrit ses fichiers rendus — dist/ sous la racine de l’espace de travail — n’est pas lu comme faisant partie d’un répertoire qui le contient : aucun de ses fichiers n’est transmis ni reconnu, et un lien qui y mène est ignoré, si bien qu’un répertoire qui a été construit est lu comme le projet qu’il contient, tandis qu’un répertoire qui est ce dossier, ou qui se trouve à l’intérieur, est lu tel qu’il est nommé. Une signature qui ne déclare aucun motif files ne sélectionne aucun fichier d’un répertoire, si bien qu’un importateur qui n’en déclare aucun lit un seul fichier et refuse un répertoire, et un répertoire ne contenant aucun fichier que sélectionnent ses motifs est refusé aussi. Le répertoire est tenu à lui-même : un lien parmi les fichiers que l’hôte lirait, ou vers un répertoire, qui mène hors du répertoire est refusé avant que quoi que ce soit ne soit lu, un lien vers un répertoire n’est jamais parcouru, et un lien vers un fichier qu’aucun motif ne sélectionne est ignoré sans être lu. La reconnaissance du format d’un répertoire suit la même règle — chaque signature est essayée sur les fichiers que sélectionnent ses motifs, dans l’ordre des noms, chaque fichier lu et analysé au plus une fois par syntaxe, et une signature qui ne déclare aucun motif ne s’applique à aucun d’eux. L’hôte ne plafonne rien : un répertoire trop volumineux pour l’importateur est refusé par les limites d’exécution propres à l’importateur. Aucun des importateurs Langflow, Flowise, n8n, Dify et Agent Framework du compilateur ne déclare de motifs files, si bien que chacun lit un seul fichier ; son importateur MCP déclare les noms des quatre configurations de clients, si bien qu’il lit chacune d’elles que contient un répertoire ; son importateur Compose déclare les huit noms de fichiers Compose, si bien qu’il reçoit chaque fichier Compose que contient un répertoire et fusionne ceux que Compose lirait ; et son importateur CrewAI déclare les six noms sous lesquels sont écrites les déclarations d’un projet CrewAI, si bien qu’il reçoit les déclarations d’un projet et rien de son programme ; et son importateur LangGraph déclare langgraph.json, si bien qu’il reçoit la configuration d’une application et rien de son code ni de ses fichiers d’environnement, un fichier d’environnement ne lui parvenant que sous le with.sources de son rattachement ; et son importateur Google ADK déclare root_agent.yaml, si bien qu’il reçoit la configuration de l’agent racine d’une application et rien de son code ni de son fichier d’environnement, les configurations que nomment ses sous-agents ne lui parvenant que sous le with.sources de son rattachement.
Définitions de types. Les types de transmission de l’importateur — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput et les formes d’entité, de décision et d’échafaudage qu’il porte — sont publiés dans les trois paquets ABI et réexportés par le kit de développement de plugins de chaque langage, générés à partir d’un même codec afin que les trois restent synchronisés, de même que les types de reconnaissance ImporterContract, DetectSignature et PathMatch que porte l’auto-description describe. Le paquet importer du kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, porte tout ce que fait un importateur quel que soit son format, et les importateurs core du compilateur, tous construits sur lui, lisent leur entrée et écrivent leur sortie de cette façon.
Par rapport à quoi évalue un importateur construit sur le kit Go. L’évaluateur du kit pèse chaque nœud de la source par rapport aux Components de la vue catalog et à rien d’autre : les candidats sont le catalogue propre de l’espace de travail — les Components d’un catalogue d’entreprise exactement comme ceux de la bibliothèque standard — et le kit n’embarque aucun candidat propre. De chaque Component, il lit le nom, la catégorie que porte son label component.aggrega.ai/category, ses labels et les noms de clés que déclarent ses values ; ses clés provides et ses sockets ne sont pas pesés. Un Component ajouté au catalogue est candidat dès l’importation suivante, sans qu’aucun importateur soit reconstruit. Lorsque la vue est absente, parce que le catalogue ne contient aucun Component, aucun nœud n’a de candidat : aucun n’est référencé ni suggéré, et chaque nœud auquel le brouillon donne un Component propre est produit en brouillon. Tout importateur qui évalue au moyen du kit évalue de cette façon — parmi eux les importateurs Langflow, Flowise, n8n et Compose du compilateur, tandis que son importateur MCP ne pèse aucun candidat ; un importateur qui n’utilise pas le kit lit la vue comme il l’entend.
Pour quoi un importateur construit sur le kit Go lit les sockets d’une plateforme. Les sockets ne pèsent rien dans un score, mais le kit les lit pour disposer un brouillon. Un format dont une plateforme exécute les flux tels qu’ils sont écrits — comme c’est le cas de ceux de Langflow, Flowise et n8n — est produit en brouillon par défaut comme une instance du Component de cette plateforme qui porte le flux, et chaque partie du flux est reliée au premier socket, dans l’ordre où l’entrée catalog de la plateforme liste ses sockets, dont le selector est satisfait par les labels du Component de la partie, tels que la vue porte ces labels. Seuls le sélecteur et les labels sont lus, et le sélecteur est mis en correspondance par une fonction que fournit l’importateur, puisque le kit n’embarque aucune grammaire de sélecteur propre ; lorsque la vue ne contient aucun Component portant le nom de la plateforme, aucune partie n’est reliée. Importateurs core décrit le brouillon que les importateurs Langflow, Flowise et n8n du compilateur produisent de cette façon, et le paramètre layout qui produit au contraire chaque nœud en brouillon comme un Component propre.
État actuel : disponible — distribué par aggrega import et par la même opération dans la session de l’éditeur et l’outil destiné à l’assistant.
Critère de placement : le socket de linter face aux rôles de verdict de la gouvernance
Deux des sockets documentés partagent une surface semblable — tous deux émettent des résultats par règle — mais diffèrent par leur placement dans le pipeline et par leur sémantique de blocage. Le critère pour décider quel socket porte une vérification donnée :
- Les rôles de verdict de la gouvernance (dans la bande, qui arrêtent le build). Réservés aux politiques qui arrêtent le build : un verdict
haltstoppe le pipeline de compilation et le build ne produit aucun artefact. Les cas d’usage sont les politiques dont la violation rend la sortie dangereuse à appliquer : points de contrôle de conformité (placement des frontières PCI / SOC2), invariants de topologie (ingress zero-trust, authentification entre frontières), forme du flux d’identifiants (aucun secret en clair dans l’IR), etc. Une politique raisonne sur le graphe IR (ir-verdict, avant le rendu) ou sur les artefacts rendus (render-verdict, après le rendu). - Le socket de linter (hors bande, CI / IDE, consultatif). Réservé aux vérifications de bonnes pratiques et de découvrabilité : des règles dont la violation est suspecte mais pas dangereuse — secrets orphelins, paramètres inutilisés, vocabulaire de labels obsolète, complétude des tags pour l’attribution des coûts, dérive par rapport aux conventions de nommage. Un échec produit une sortie consultative ; le build produit tout de même des artefacts.
Le critère de placement formulé comme une règle unique : si la vérification doit arrêter le build, elle relève d’un rôle de verdict de la gouvernance ; si la vérification doit avertir un auteur ou un relecteur sans bloquer le pipeline, elle relève du socket de linter.
Les deux sont utilisables aujourd’hui. Le socket de linter exécute le publishing-linter via aggrega lint ; les rôles de verdict de la gouvernance sont invoqués dans la bande pendant aggrega build lorsqu’un espace de travail rattache un plugin à rôle de verdict. Notez qu’un rôle de verdict porte ses propres niveaux de gravité — une politique peut elle-même émettre des verdicts warn et info qui avertissent sans arrêter — si bien que la ligne entre arrêt et avertissement tracée ci-dessus est l’indication de placement pour des vérifications entières, et non l’affirmation qu’une politique ne peut qu’arrêter. Voir la page du socket de gouvernance pour le modèle des niveaux de gravité.
Références croisées
policy-socket.md— le traitement complet du socket de gouvernance : les quatre rôles, les niveaux de gravité des verdicts, le canal d’entrée de l’opérateur, l’écriture d’une politique pour l’un ou l’autre des deux moteurs livrés dans le compilateur, l’encapsulation d’un moteur de politiques externe et les guests de référence.core-importers.md— les importateurs propres au compilateur, un pour chaque format qu’il lit : ce que lit chacun, leurs paramètres et leur publication avec chaque version du compilateur.10-status.md#compilation-pipeline-phases— classification du pipeline des plugins sur la page d’état (maturité d’exécution du pipeline des plugins Wasm).architecture/04-entity-taxonomy.md§« Domain 3: Infrastructure Base (Domaine 3 : base d’infrastructure) » — principe du Plugin en deux parties pour les FeatureRecipes d’identifiants (modèle Fetcher + Injector).architecture/13-catalog-and-registry.md— la taxonomie OCI qui commence par le segment du fournisseur.entities/featurerecipe.md— la surface de créationpipeline:de la FeatureRecipe.when-to-use-a-pipeline-step.md— guide de décision : une étape de pipeline ou une FeatureRecipe à base de templates.templates/expansion-matrix.md— les règles d’évaluation des templates du blocpipeline:with:du pipeline des plugins et la sémantique d’accès à.steps.examples/04-secrets.md— la forme de pipeline Fetcher + Injector que peut prendre une FeatureRecipe d’identifiants.errors/error-translation.md— la discipline de traduction des erreurs à laquelle participent les guests des plugins.