Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Pipeline de compilation (vue d’ensemble)

Ce chapitre détaille la physique interne du compilateur Go, en définissant comment du YAML abstrait est traduit en configurations physiques à travers le pipeline de compilation, le graphe de représentation intermédiaire (IR) et les sockets d’exécution WebAssembly (Wasm).

Le pipeline de compilation et le flux d’exécution

Aggrega exécute un pipeline de compilation anticipée (AOT) strict, à ordre fixe, plutôt qu’une logique d’orchestration codée en dur. Déclenché par aggrega build, le compilateur fait passer le graphe plat entre des sockets WebAssembly (Wasm) isolés pour évaluer l’architecture avant de produire les artefacts physiques.

Les sockets Wasm s’exécutent sur un hôte embarqué — la boîte à outils Extism au-dessus du moteur Wazero — derrière un pare-feu de pureté AOT qui refuse à un plugin toute capacité d’accès à l’exécution (réseau, système de fichiers, horloge murale, environnement, E/S standard), de sorte qu’un plugin ne peut pas rompre la garantie déterministe de compilation anticipée. L’hôte exécute le linter de publication hors bande, via aggrega lint. Les barrières intra-bande décrites ci-dessous — le rôle label-transform du socket de gouvernance lors de la construction de la topologie et son rôle de verdict IR lors de l’analyse statique, ainsi que le pipeline de plugins qui clôt le rendu — s’exécutent à chaque build : un rôle de gouvernance partout où l’espace de travail lui attache un plugin, et le pipeline de plugins pour chaque Recipe qui déclare des étapes. État du langage suit l’état de chaque phase du pipeline.

Le pipeline s’exécute entièrement en mémoire, dans un ordre strict et fixe :

Résolution — le résolveur et le validateur de syntaxe

  • Mécanisme : fusion par héritage, interpolation de templates Go et validation JSON Schema 2020-12.
  • Action : la CLI récupère toutes les entités demandées (Components, Features, Releases). Elle vérifie d’abord si ces définitions contiennent le mot-clé extends. Pour les entités du catalogue, elle fusionne en profondeur les métadonnées YAML, et les deux types d’entité se séparent sur les piliers de données : le schema: d’une Feature se compose avec celui de sa base selon la composition JSON Schema 2020-12, tandis qu’un Component qui en étend un autre n’en compose que la structure — ses emplacements d’attachement, ses sockets de topologie, sa liste d’autorisation d’auto-injection et ses assertions nommées — et reçoit le bloc schema: de sa base exactement tel que la base l’a écrit. Une Release qui en étend une autre se replie selon la même règle : la valeur de l’enfant l’emporte clé par clé, jusqu’à la première valeur indivisible — un scalaire, une liste, un template — qui est remplacée en entier, et une clé que l’enfant écrit à null est supprimée. Ainsi, toute sa surface de rédaction est transmise — l’arbre des frontières avec l’infra et les attachements de Feature de chaque composant, le bloc parameters, les annotations et le pointeur de Manifest — alors qu’aucun champ metadata ne l’est, puisque l’identité et la provenance sont propres à chaque Release. Ensuite, elle effectue une interpolation en mémoire en trois sous-étapes : la validation du contrat de paramètres par rapport aux déclarations typées parameters: de l’Aggregate ; l’interpolation des valeurs résolues dans les chaînes values: environnantes ; le retrait de la map .parameters de chaque contexte de template de valeur, qui ne reste lisible que par les templates de chemin écrits par l’opérateur. Enfin, elle injecte les blocs infra résolus dans les charges utiles des composants cibles. Une fois le plan entièrement concret, le compilateur utilise la déclaration unifiée schema: du catalogue (forme compacte ou JSON Schema 2020-12 complet) pour valider strictement, en local, les configurations values et infra du développeur.
    • Validation du schéma des Features de la Release : les Features attachées via la Release (à l’échelle d’une frontière comme spécifiques à un composant) sont résolues par rapport à leurs entités de catalogue au cours de cette étape. Le compilateur valide les blocs infra fournis par la Release par rapport à la déclaration schema: de chaque Feature immédiatement après la résolution du catalogue, garantissant la sûreté de typage avant la construction de la topologie.
    • Sous-phase d’expansion de Feature pilotée par annotations : après la résolution du Manifest, la liaison Recipe/Provider et la validation des cibles de liaison du Manifest (les chemins déclarés sous mappings.features.annotations.<key>.maps existent dans le spec.schema de la Feature référencée), le compilateur exécute une sous-phase d’expansion des annotations avant le constructeur de topologie. La sous-phase parcourt les frontières de la Release de l’extérieur vers l’intérieur et les sous-systèmes de l’Aggregate de l’extérieur vers l’intérieur, en calculant l’ensemble effectif d’annotations de chaque composant par une fusion cascade + surcharge + désactivation par null ; analyse chaque valeur d’annotation en YAML en un scalaire, une valeur structurée ou null ; achemine chaque valeur (scalaire ou structurée par sous-clé) via la déclaration maps de la liaison du Manifest vers le pilier de schéma de la Feature cible, en contrôlant la correspondance entre côté et pilier (le côté Aggregate déclenche maps.values ; le côté Release déclenche maps.infra) ; valide les types de chaque feuille par rapport au spec.schema de la Feature ; et injecte des attachements de Feature synthétiques, que le graphe IR marque avec origin: annotation. Les schémas sont compilés une fois par build et réutilisés d’un parcours de cascade à l’autre. L’expansion s’exécute après la validation des cibles de liaison et avant la construction de la topologie, de sorte que les étapes en aval traitent les attachements synthétiques de manière structurellement identique aux attachements explicites (sauf par inspection de la provenance). Voir 13-catalog-and-registry.md §« Expansion de Feature pilotée par annotations » et language-reference/providers/well-known-annotations.md pour la forme de la liaison, la sémantique de la cascade et les règles de composition entre les deux côtés.

Construction de la topologie — le constructeur de topologie et la barrière de mutation

  • Mécanisme : expansion de l’AST + le rôle label-transform du socket de gouvernance.
  • Action : le compilateur lit nativement les blocs uses explicitement déclarés des composants validés pour tracer de manière déterministe les arêtes topologiques entre les nœuds du graphe, en laissant le bloc values entièrement opaque. Il évalue ensuite la barrière de mutation, en transmettant une projection du graphe — les labels de chaque nœud et les values que déclare son instance, que le compilateur transmet sans les lire — avec le nom et l’environnement de la Release, à un plugin de gouvernance attaché au rôle label-transform. Le plugin évalue le contexte et renvoie des JSONPatches pour étiqueter automatiquement et dynamiquement le graphe (par exemple, en injectant le label compliance.aggrega.ai/data-class: restricted en fonction de l’environnement de la Release, ou datastore.aggrega.ai/engine: vector en fonction des extensions déclarées d’une base de données) ; les patches n’atteignent que les labels.

Finalisation du graphe

  • Mécanisme : normalisation.
  • Action : le compilateur finalise le graphe plat de représentation intermédiaire (IR), en préservant les arêtes topologiques explicites tracées par le constructeur de topologie. Il normalise ensuite les Features attachées et leurs charges utiles values dans un dictionnaire plat indexé par ID de nœud, préparant pour la validation le graphe agnostique vis-à-vis des capacités.
    • Normalisation des charges utiles de l’IR : la forme structurelle de l’IR impose une source unique de vérité pour la configuration : la couche de topologie ne porte que la structure du graphe (identité des nœuds, arêtes, labels de métadonnées), et l’état normalisé de la configuration réside dans un dictionnaire en mémoire distinct que le compilateur transmet aux plugins en aval. Les mutateurs qui modifient la configuration la modifient en un seul endroit ; le fournisseur lit l’état normalisé sans risque de divergence due à un stockage redondant.

Analyse statique — l’analyseur statique et la barrière de validation

  • Mécanisme : vérifications de pureté topologique + le rôle ir-verdict du socket de gouvernance.
  • Action : le compilateur exécute une analyse statique abstraite sur le graphe IR. Premièrement, il extrait les chaînes selector des définitions usesSchema et les évalue à l’aide d’un moteur natif Go de correspondance de labels (prenant en charge une sémantique à la Kubernetes : AND, OR via in() et NOT via !=) sur les arêtes du graphe explicitement définies, afin de garantir la sûreté de typage entre nœuds sur les sockets déclarés. Une arête sur un socket ad hoc — un socket qu’un auteur d’Aggregate a nommé et que le catalogue n’a pas déclaré — n’a pas d’entrée de catalogue et donc pas de sélecteur, si bien que cette vérification n’a rien à évaluer et que rien ne manque ; chaque arête enregistre lequel des deux cas elle représente, et ce qu’une arête ad hoc peut porter est borné à la place par les provides déclarés de la cible. Il évalue aussi les sélecteurs appliesTo et appliesToAnyOf des Features pour vérifier que les fonctionnalités attachées sont compatibles avec les labels de leur composant cible, ainsi que le selector propre à chaque emplacement d’attachement rempli par rapport aux labels de la Feature qui le remplit. Deuxièmement, il évalue chaque obligation de présence que déclare le Component d’un nœud — chaque annotation features.aggrega.ai/requiredType.<label> — par rapport à l’ensemble final des attachements de ce nœud. L’analyseur est l’endroit où cette vérification a sa place, car c’est la première étape qui détient les deux moitiés de la règle : les annotations de l’entité Component résolue et l’ensemble des attachements qu’a produit la cascade à 5 niveaux, en comptant indistinctement les attachements faits sur l’Aggregate, sur un sous-système, sur la Release et ceux issus de l’expansion des annotations. Une obligation qu’aucun attachement ne satisfait arrête le build ; une obligation dont la déclaration est mal formée l’arrête avec un diagnostic distinct, de sorte qu’une déclaration défectueuse ne se lit jamais comme une exigence satisfaite. Troisièmement, il exécute la barrière de validation, en transmettant la structure complète du graphe (y compris tous les nœuds, arêtes, fonctionnalités attachées et chemins DFS précalculés) à un plugin de gouvernance attaché au rôle ir-verdict. La politique Wasm personnalisée de l’entreprise évalue la topologie. Si le plugin Wasm renvoie un tableau d’échecs (par exemple, en détectant un chemin continu d’un nœud public vers un nœud restricted sans fonctionnalité de proxy spécifique), le build s’arrête.

Rendu

  • Mécanisme : interception avant rendu (injectMapping), liaison tardive (valuesMapping) et sockets de rendu Wasm (pipeline).
  • Action : la phase finale de génération des artefacts est divisée en sous-phases temporelles strictes qui s’exécutent dans un ordre fixe, ce qui maintient l’exécution déterministe :
    • Mapping d’injection (interception avant rendu) : le compilateur Go résout le contrat abstrait .context.inject du développeur. Il exécute ensuite les templates Go injectMapping de toutes les FeatureRecipes attachées, en suivant l’ordre d’exécution strict du modèle en oignon à 5 niveaux (sous-Aggregate — les attachements propres d’un composant module, puis ceux que déclarent les sous-systèmes de son module, de l’extérieur vers l’intérieur → composant de l’Aggregate racine → sous-système de l’Aggregate racine → frontière de la Release, de l’extérieur vers l’intérieur → spécifique au composant de la Release). Le compilateur fusionne nativement en profondeur les dictionnaires obtenus par-dessus le canal mémoire .context.inject de l’appelant. Cela réécrit en toute sécurité les variables d’environnement et les chaînes de connexion de l’appelant avant même que la Recipe de base ne les voie. Un mapping peut réécrire ce que le bloc inject: de l’appelant ou l’une de ses connexions a fourni ; une clé qu’une autre Feature attachée a déjà fournie — par son propre mapping ou son propre bloc inject: — arrête le build en nommant les deux attachements, de sorte que l’ordre d’exécution ne tranche jamais entre les valeurs de deux attachements.
    • Préambule des locals : avant l’exécution de tout template provides, le compilateur évalue les entrées .locals de la Recipe dans l’ordre où elles sont écrites, chacune par rapport à un contexte autonome local au nœud — .context.instance_id, .values, .infra et les entrées du même bloc résolues jusque-là, mais pas .context.inject ni .context.uses. Une entrée peut donc lire une entrée sœur définie au-dessus d’elle et reçoit la valeur résolue de celle-ci ; l’ordre d’écriture fait partie du contrat dès qu’une entrée en lit une autre, et le bloc n’est jamais réordonné pour qu’une référence se résolve. C’est la résolution préalable des locals qui permet à un template provides de lire .locals. Le template .source de la Recipe est évalué par rapport au même contexte une fois ces locals résolus, ce qui garde .locals réutilisable comme raccourci dans tous les templates d’une Recipe et permet aux auteurs de paramétrer .source (version du chart, chemin, registre) par frontière.
    • Rendu de base (valuesMapping de la Recipe de base) : le compilateur évalue le template valuesMapping de la Recipe de base. Le template lit les chaînes interceptées dans le canal .context.inject (réécrites pendant le mapping d’injection), et le dictionnaire de valeurs obtenu est transmis au fournisseur que nomme la capability de la Recipe — les fournisseurs helm et helm-chart effectuent tous deux leur rendu via Helm — pour produire les artefacts d’infrastructure de base.
    • Analyse et validation du Workload : pour une Recipe qui déclare workload: — un contenu de bloc en ligne, ou workload: { $import: <path> } qui nomme un fichier —, ce document est évalué comme un template par rapport au contexte de rendu du nœud, puis analysé en YAML selon la forme Workload et vérifié : les octets rendus sont validés par rapport au schéma Workload, la valeur décodée est également validée par rapport à celui-ci (les octets portent des clés que le décodage écarte, et le décodage élide un champ fourni vide, si bien que chacun rejette ce que l’autre ne peut pas voir), chaque entrée attachments est vérifiée par rapport aux emplacements que déclare le featuresSchema du Component lié, et chaque référence de ressource est vérifiée par rapport aux provides résolus de l’emplacement qu’elle nomme. Un échec à ce stade arrête le build. Le Workload analysé est placé dans le contexte de template sous .workload, de sorte qu’un template évalué plus tard sur le même nœud peut le lire.
    • Évaluation des artefacts : chaque entrée qu’une Recipe déclare sous artifacts: — un contenu en ligne, ou un fichier nommé par le propre $import: de cette entrée — est lue, analysée comme template, évaluée par rapport au contexte de template complet, et porte la provenance du build. La projection obtenue est remise au fournisseur, qui décide du format de sortie, de l’endroit où atterrit la provenance, du chemin de sortie et des octets finaux. Chaque fichier émis enregistre de quelle forme rédigée il provient, de sorte qu’une collision de noms de fichiers peut nommer chaque contributeur.
    • Synthèse du Workload : le Workload analysé est remis au fournisseur que nomme la capability de la Recipe, qui le traduit en ressources natives de ce fournisseur. Une Recipe qui ne déclare pas de workload: n’a rien à synthétiser ici ; ses fichiers proviennent à la place du rendu de la source.
    • Rendu des Features (génération de ressources par FeatureRecipe) : chaque attachement du nœud dont la FeatureRecipe liée porte ses propres source, workload, artifacts et/ou valuesMapping — le modèle de génération de ressources, utilisé pour des manifestes auxiliaires comme un ServiceMonitor, une NetworkPolicy, une ConfigMap de sidecar ou une ressource de livraison d’identifiants — est évalué en une seule passe, dans le même ordre du modèle en oignon à 5 niveaux que suit le mapping d’injection. Il y a une seule séquence sur un seul ensemble d’attachements : une Feature opérationnelle et une Feature d’identifiants suivent le même chemin, et ce qui les distingue est ce qu’émet leur FeatureRecipe. Les .values et .infra de chaque attachement sont remplacés par ceux de sa propre portée ; il hérite des .locals évalués de la Recipe de base ; .attachment_name nomme l’instance en cours de rendu et .provides porte les provides résolus propres à l’attachement, le même ensemble que lit le consommateur. Le dictionnaire de valeurs obtenu est transmis au fournisseur nommé par la propre capacité de la FeatureRecipe, et les fichiers rendus sont ajoutés à la sortie de la frontière avec deux coordonnées — le composant auquel la Feature est attachée, puis le nom sous lequel elle est attachée — de sorte qu’un même nom de Feature attaché à plusieurs composants les garde séparés. La forme que prennent ces coordonnées découle de la disposition propre au fournisseur hôte : un répertoire <component>--<instance>/ à côté de celui du composant, là où la cible donne à chaque contributeur une position propre, et un préfixe de nom de fichier <component>--<instance>-- là où elle ne lit que les fichiers situés directement dans un répertoire. Les FeatureRecipes d’injection seule — celles qui ne portent que injectMapping, déjà traitées pendant le mapping d’injection — sont ignorées ici. Comme les sous-phases qui la précèdent, le rendu des fonctionnalités s’exécute un composant à la fois, si bien qu’un attachement est normalement évalué juste après le composant auquel il est attaché. Un attachement dont la FeatureRecipe déclare readsCallerRenderFacts: true ou readsTargetRenderFacts: true est en revanche évalué une fois que chaque composant, et chaque attachement qui ne déclare ni l’un ni l’autre, a été rendu — de sorte que chaque composant qui se connecte à son hôte, et chacun de ceux auxquels son hôte est relié, a été rendu à ce moment-là — et sa sortie atterrit là où elle aurait atterri sinon.
    • Le pipeline de plugins (exécution des étapes Wasm) : le compilateur lit le tableau pipeline de la Recipe et exécute ses étapes dans l’ordre déclaré. Il distribue le plugin Wasm nommé de chaque étape sur les documents rendus du nœud, applique les opérations JSON Patch RFC 6902 que renvoie l’étape aux documents que ces opérations visent, et émet les effets de bord de l’étape à côté d’eux — la surface derrière des mutations chirurgicales comme l’injection d’un sidecar Envoy ou le montage d’un VolumeMount de secret. Une étape dont la barrière when: produit une valeur fausse est ignorée et laisse tout passer, l’ensemble de documents restant inchangé pour l’étape suivante. L’URI plugin de chaque étape se résout avant l’exécution vers les octets d’artefact vérifiés que le fichier de verrouillage épingle par digest. Les étapes pipeline d’une FeatureRecipe s’exécutent de la même manière, sur les documents rendus propres à l’attachement et, pour un attachement de portée composant, sur ceux du composant hôte en plus.

Les trois types d’entrée de Recipe atteignent le compilateur : source: + valuesMapping: par le rendu de base, workload: par l’analyse du workload et la synthèse du workload, et artifacts: par l’évaluation des artefacts. Lequel d’entre eux peut être remis à un fournisseur donné ne se décide pas sous-étape par sous-étape — cela est réglé une fois par nœud, avant tout envoi de rendu, à partir du contrat déclaré du fournisseur lui-même, de sorte qu’une Recipe dont le fournisseur lié n’accepte pas le type d’entrée est refusée à ce stade plutôt qu’en cours de rendu. Voir 16-recipe-input-composition.md pour le modèle de composition des trois types d’entrée, le kind Workload et le mécanisme des artefacts, et État du langage pour savoir quel fournisseur accepte quel type.

Sortie native GitOps

Pour rester strictement sans parti pris quant à la manière dont leur sortie est appliquée, les plugins de rendu écrivent les artefacts générés dans une arborescence de répertoires propre, isolée par frontière (par exemple, dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Cela permet à des contrôleurs GitOps externes (comme ArgoCD ou Flux) de synchroniser et d’appliquer l’infrastructure sans que le compilateur Aggrega ait jamais besoin d’identifiants d’API de cluster en direct.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Carte des sources de l’infrastructure

Aggrega compile un Aggregate.yaml d’environ 30 lignes en milliers de lignes de configuration JSON ou YAML physique. Sans moyen de remonter d’une ressource en cours d’exécution à sa source, déboguer une défaillance à « main.tf.json, ligne 4 032 » oblige les développeurs à reconstruire la correspondance à la main. Les plugins de rendu d’Aggrega y remédient en fusionnant des identifiants de traçage dans la surface de métadonnées native du fournisseur — metadata.labels et metadata.annotations pour Kubernetes, un commentaire de provenance pour Terraform et des conventions équivalentes propres à chaque fournisseur — de sorte que chaque objet rendu porte un pointeur vers la source dont il provient. Le label aggrega.ai/compiler-version (documenté dans governance-and-compliance §5) est une clé de traçage de cette famille ; à côté de lui, le tampon porte aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri et aggrega.ai/environment, et les fournisseurs helm, helm-chart, compose, terraform et cloudformation l’émettent chacun — le fournisseur helm-chart sur les fichiers de template qu’une Recipe ajoute à un chart, puisqu’il copie sans modification les templates propres au chart.

Le tampon ne porte aucune clé identifiant l’origine de la fonctionnalité ou le type de catalogue.

Deux autres surfaces de débogage sont livrées avec le compilateur. aggrega build --trace écrit l’état intermédiaire de chaque nœud, passe par passe, dans .trace/ à côté de dist/, pour l’auteur d’une Recipe qui inspecte ce que chaque étape a reçu et produit ; et un diagnostic bloquant porte la catégorie de la surface d’écriture à laquelle il appartient — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR et les autres — partout où l’échec en a une, de sorte qu’il désigne le bon auteur. Les erreurs qui ramènent un champ défaillant d’un manifeste généré à la ligne de template qui l’a produit ne font pas partie du compilateur.

Le pipeline des validateurs

La phase de validation des schémas de la résolution repose sur un pipeline de validateurs qui convertit le contenu des spécifications d’entités (forme compacte, JSON Schema en YAML, ou mixte) en un document JSON Schema 2020-12 unifié avec une provenance par feuille, puis valide par rapport à lui le contenu d’instance écrit par les développeurs. Cinq étapes s’exécutent dans l’ordre comme des transformations pures ; chacune est une fonction déterministe de ses entrées déclarées.

Étape 1 — Compilation de la forme compacte. Le compilateur parcourt l’arbre YAML du contenu de schema:, de parameters: et de SchemaLibrary ; il aiguille par nœud (feuille en forme compacte, JSON Schema en YAML, référence $ref: ou composition) ; il émet du JSON Schema 2020-12 résolu. La forme compacte et le JSON Schema en YAML peuvent se mélanger à n’importe quelle frontière de nœud grâce à l’échappement $jsonschema: ; le compilateur gère le cas mixte en parcourant l’arbre et en aiguillant par nœud. La transformation est une fonction pure : la même entrée en forme compacte produit toujours la même sortie JSON Schema. Voir language-reference/vocabulary/compact-form-authoring.md pour le vocabulaire des mots-clés.

Étape 2 — Résolution de spec.templates et $instantiate:. Pour les entrées de SchemaLibrary écrites comme des références de modèles, le compilateur parcourt chaque entrée de bibliothèque qui invoque $instantiate: avec $args:, substitue les valeurs des paramètres par remplacement de scalaires littéraux et produit des entrées de schéma concrètes. La substitution s’exécute une fois par chargement de bibliothèque ; les entrées résolues sont mises en cache. Voir language-reference/entities/schemalibrary.md pour la forme d’écriture de l’entité bibliothèque.

Étape 3 — Expansion des $ref: inter-documents. Pour les références à une SchemaLibrary via $ref: (la forme d’identité <Library>#/schemas/<entry>), le compilateur parcourt la chaîne de références à la compilation en propageant une pile de résolution ; le contenu référencé est intégré dans le schéma du consommateur. L’expansion préserve la détection des cycles (les cycles arrêtent le build avec une erreur qui nomme la chaîne), le garde-fou identité-et-non-emplacement (une référence portant un hôte de registre arrête le build en orientant vers la forme d’identité — les références désignent les bibliothèques par leur identité, non par leur emplacement physique) et la composition à source unique (les blocs $ref: n’acceptent que la référence nue ; les surcharges côté consommateur se composent via allOf: de JSON Schema). Voir language-reference/vocabulary/cross-document-ref.md pour la sémantique de résolution.

Étape 4 — Synthèse du pont pour featuresSchema:. Le compilateur parcourt le contenu featuresSchema: de chaque entité dans l’ordre de l’auteur et émet un fragment JSON Schema décrivant la forme d’un remplissage susceptible de lier chaque slot d’attachement, avec un mot-clé d’extension x-aggrega-inject: sur un slot qui déclare une allowlist inject. Ce fragment est compilé et vérifié à part, par rapport au bloc d’attachement écrit, au lieu d’être intégré au contenu schema: destiné au développeur ; le mot-clé d’extension est une métadonnée que la validation JSON Schema ignore, et aucune étape ultérieure ne le relit dans le fragment — une vérification qui a besoin de l’allowlist d’un slot lit le slot. La table de sockets usesSchema: n’est projetée dans aucun fragment : le selector: et l’inject: d’un socket sont lus comme le YAML typé que l’architecte a écrit, et le valueSchema: / infraSchema: par arête d’un socket est compilé à part. La synthèse est une fonction pure de ses entrées.

Étape 5 — Fusion personnalisée avec provenance. Pour les entités qui déclarent extends:, le compilateur parcourt la chaîne des parents ; le JSON Schema résolu du parent devient la base ; les surcharges de l’enfant s’appliquent par-dessus. Chaque feuille du schéma résolu porte une étiquette de provenance par feuille (chemin du fichier, numéro de ligne, origine parent ou enfant). La sortie de la fusion est ce que consomme le moteur de validation ; le moteur de validation est une implémentation tierce non modifiée conforme à JSON Schema 2020-12, entourée d’un parcoureur déterministe pour émettre les constats dans l’ordre.

Les cinq étapes s’exécutent avant que le moteur de validation ne voie le schéma. Le moteur reçoit un unique document JSON Schema 2020-12 résolu plus le contenu d’instance du développeur ; il produit un rapport de validation. Le formateur d’erreurs consulte les étiquettes de provenance pour émettre des diagnostics destinés à l’utilisateur qui nomment clairement les positions dans la source — y compris le fichier d’origine d’une contrainte qu’une Feature a héritée de sa base au lieu de l’écrire elle-même.

Le pipeline de validation s’exécute là où chaque charge utile est complète pour la première fois — les values et l’infra d’un composant pendant la résolution, les composants d’un sous-agrégat à mesure que la construction de la topologie les intègre, et la charge utile d’un attachement lors de la finalisation du graphe — de sorte qu’un constat de schéma arrête le build avant que l’analyse statique n’évalue le moindre sélecteur, et avant l’évaluation des assertions, ce qui permet aux templates d’assertion de s’appuyer sur des charges utiles validées.

Préservation du déterminisme tout au long du pipeline

Chaque étape du pipeline de compilation préserve l’invariant de sortie déterministe : avec les mêmes fichiers source, le même lockfile et la même version du compilateur, le build produit une sortie identique octet pour octet. L’invariant est fondamental — l’adressage par contenu dans le lockfile exige des empreintes d’artefacts stables ; les builds reproductibles exigent qu’une release écrite sur l’ordinateur portable du développeur A se compile en la même sortie sur celui du développeur B et en CI ; la relecture des diffs exige que les modifications de la source apparaissent comme les seules modifications de la sortie compilée.

Le déterminisme est préservé par un petit nombre de disciplines que chaque transformation respecte :

  • Ordre d’itération fixe. Tout parcours de YAML en forme de map itère dans un ordre fixe, car l’itération native des maps en Go est aléatoire. Le compilateur trie avant d’itérer dans la plupart des étapes (compilateur de la forme compacte, fusion, résolveur de spec.templates, formateur d’erreurs, sérialiseur YAML) ; la projection des slots d’attachement conserve au contraire l’ordre de l’auteur, de sorte que l’ordre des propriétés d’une table de slots est celui dans lequel elle a été écrite.
  • Aucun horodatage incorporé. La compilation n’incorpore pas d’horodatages dans la sortie. Un build à 14 h 00 produit le même artefact qu’un build à 2 h 00. Les métadonnées de provenance de la fusion utilisent fichier:ligne, et non fichier:horodatage.
  • Chemins relatifs à l’espace de travail. Tous les chemins de la sortie résolue sont relatifs à l’espace de travail ; la couche de résolution des chemins les normalise avant qu’ils n’entrent dans une sortie.
  • Aucune source aléatoire, aucun état externe. Les transformations sont des fonctions pures de leurs entrées déclarées (contenu de l’entité, chaîne des parents, lockfile). L’état externe n’est consulté que pendant la résolution (récupération des artefacts OCI), et le contenu résolu est adressé par contenu via son empreinte.
  • Sérialisation YAML canonique. La sortie est écrite sous une seule forme fixe pour une entrée donnée : le même ordre des clés à toutes les profondeurs à chaque exécution, les tableaux et les tableaux enum: restant dans l’ordre d’entrée ; une indentation de 2 espaces ; des fins de ligne Unix LF ; des chaînes sans guillemets là où YAML le permet ; la forme booléenne true/false ; null omis pour les champs absents.
  • Ordre alphabétique de $defs:. Les entrées $defs: d’un schéma sont émises par ordre alphabétique des clés dans le JSON Schema résolu. $defs: est conceptuellement un dictionnaire, et non une liste ordonnée ; l’ordre alphabétique rend les diffs prévisibles d’une réorganisation de la source à l’autre.
  • Le parallélisme ne remonte pas jusqu’à la sortie. Le compilateur peut paralléliser des unités indépendantes (des entités différentes peuvent se compiler simultanément). Les résultats parallèles sont rassemblés dans une structure déterministe (par ex. triée par nom d’entité) avant d’être sérialisés.

Les tests de bout en bout du compilateur compilent chaque fixture plusieurs fois au sein d’un même test et vérifient que chaque exécution émet les mêmes fichiers avec un contenu identique octet pour octet. C’est la répétition de la compilation qui détecte une fuite de l’ordre d’itération des maps ou une itération sur un ensemble non trié, qui produit une sortie stable dans la plupart des exécutions et diverge occasionnellement. Les tests s’exécutent avec le reste de la suite de tests du compilateur.

L’invariant de sortie déterministe s’applique au moment du build : mêmes fichiers source + même lockfile + même version du compilateur, sortie identique octet pour octet. La propriété complémentaire au moment du verrouillage (mêmes fichiers source + même état du registre, même lockfile) est plus faible — les registres sont modifiables (de nouvelles versions peuvent être publiées ; des sidecars peuvent être ajoutés ; les métadonnées par composant peuvent évoluer), si bien que deux invocations du verrouillage sur les mêmes fichiers source à des moments différents peuvent produire des lockfiles différents. C’est précisément le rôle du lockfile, à l’image des conventions de npm, Cargo et Go. À partir d’un lockfile neuf, le build produit une sortie déterministe. La séparation entre ces deux moments est ce qui rend tolérable la mutabilité côté registre : un sidecar publié au temps T2 modifie la prochaine invocation du verrouillage ; il ne modifie pas les builds effectués avec le lockfile généré au temps T1.