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

Invariants architecturaux

Ces huit invariants sont les règles fondatrices d’Aggrega. Ils valent d’une release à l’autre, dans le cœur du compilateur, la couche des schémas, le catalogue et la surface des plugins Wasm. Chaque décision de conception, chaque fonctionnalité et chaque entité rédigée les respecte.

Les autres chapitres d’architecture font référence aux invariants par leur numéro. Quand un chapitre ultérieur dit « selon l’invariant 2 » ou « par la règle du String Pipe (invariant 3) », il renvoie ici.

1. Le compilateur est neutre vis-à-vis du contenu, sans parti pris et agnostique vis-à-vis de l’intention de l’utilisateur

Le compilateur Aggrega est un routeur de texte Ahead-Of-Time (AOT). Il analyse le YAML, parcourt des graphes, évalue des intersections d’étiquettes et achemine des chaînes des sources vers les destinations. Il ne contrôle pas ce que les auteurs placent dans values, parameters, infra, provides ou locals. Il n’impose ni conventions de nommage, ni conventions de ports, ni les étiquettes sémantiques qu’un Architect invente.

De nombreuses règles qui ressemblent à des règles du compilateur — le contrat Zero-Port, le style de catalogue Naked-Base / Flavored-Edges, le choix de la primitive opérationnelle adaptée à un composant donné — sont des contrats sociaux : des bonnes pratiques assorties de portes de sortie, maintenues par les architectes de plateforme qui rédigent le catalogue de la bibliothèque standard. Le compilateur ne les interprète pas.

Cet invariant porte sur ce que le compilateur déduit du contenu que vous rédigez, et cette portée constitue la totalité de son objet. Une poignée de clés appartiennent à Aggrega — réservées, avec les valeurs qu’elles acceptent inscrites dans le schéma publié — et le schéma les vérifie comme il vérifie tout autre champ déclaré. component.aggrega.ai/type en fait partie : son ensemble de valeurs est fermé, et un document portant une valeur hors de cet ensemble est refusé au chargement. C’est la plateforme qui énonce ce que signifie sa propre clé, et non le compilateur qui prête un sens à une chaîne que vous avez écrite ; cela laisse chacune de vos propres clés exactement aussi peu contrôlée que le dit cet invariant. Un catalogue qui classe les composants selon un axe qu’Aggrega ne définit pas rédige sa propre clé d’étiquette, que le schéma accepte avec n’importe quelle valeur de chaîne et que chaque surface de sélection lit de façon identique.

Ce que le compilateur impose est restreint : la validation des schémas, l’analyse YAML, la construction du graphe, l’évaluation des templates et le simple routage textuel du contrat d’injection. Tout le reste relève de la convention, appliquée au moment de la rédaction du catalogue ou dans le socket de gouvernance Wasm optionnel.

Les entreprises qui rédigent leurs propres catalogues internes sont explicitement libres d’enfreindre les conventions de la bibliothèque standard. Le compilateur accepte tout ce qu’elles écrivent, pourvu que cela passe la validation de schéma. L’architecture promeut les bonnes pratiques ; elle ne construit pas de prisons.

2. Pureté AOT : le compilateur n’a pas accès aux informations d’exécution

Aggrega est un compilateur Ahead-Of-Time. Au moment de la compilation :

  • Il ne s’authentifie pas auprès des API cloud.
  • Il ne récupère pas d’adresses IP actives, de noms DNS ni d’URL générées par le cloud.
  • Il ne résout pas les secrets en clair — les secrets restent des pointeurs de métadonnées dans toute la représentation intermédiaire (Intermediate Representation).
  • Il ne connaît pas l’état d’exécution des clusters ou des services cibles.
  • Il ne peut pas récupérer des données qui n’existent pas encore (points de terminaison postérieurs au provisionnement, ports attribués dynamiquement, noms de ressources générés automatiquement).

Tout ce qui dépend de l’état d’exécution est exprimé sous forme de chaîne pointeur déterministe — un nom DNS stable, une chaîne d’interpolation Terraform, une référence de ressource CloudFormation — fournie par la Ops Recipe. Le compilateur transmet le pointeur sans le résoudre. L’environnement d’exécution (le cluster, le gestionnaire d’état IaC) résout les données physiques finales.

C’est la véritable inversion de contrôle (True Control Inversion) : les développeurs dictent un Injection Contract dans l’Aggregate, le compilateur câble des pointeurs déterministes à l’avance, et l’environnement d’exécution résout les données physiques finales. Les exigences qui nécessitent réellement une résolution à l’exécution relèvent du pipeline Wasm d’une Ops Recipe, pas du cœur du compilateur.

3. Le String Pipe : le compilateur ne peut pas déduire le sens

Le compilateur n’interprète pas la signification des valeurs transmises. Lorsque le Component A utilise le Component B, le compilateur prend le scalaire que la Recipe du Component B produit via provides — une chaîne, un nombre ou un booléen — et le transmet dans le contexte de la Recipe du Component A, converti en chaîne de manière déterministe à la frontière d’injection. Que cette valeur soit un FQDN, un nom d’hôte local, une adresse IP littérale, un numéro de port ou un DSN formaté par Wasm ne fait aucune différence : le compilateur ne valide ni la routabilité, ni l’exactitude du protocole, ni la pertinence sémantique.

Il en découle deux conséquences :

  • Le compilateur ne devine pas la fonction d’un composant à partir de son nom. Un composant nommé database-production n’est pas reconnu comme une base de données. Les étiquettes de type sémantique telles que component.aggrega.ai/type (lorsqu’elles sont présentes) sont des métadonnées opaques utilisées pour la correspondance d’étiquettes, et non une logique de branchement du compilateur.
  • Le compilateur ne distingue pas un nom d’hôte d’un nom de base de données, d’un numéro de port ou d’une valeur opaque quelconque. Ce sont toutes des entrées scalaires du contexte d’injection, livrées sous forme de chaînes.

La triade de topologie — provides sur la Recipe productrice, uses sur l’Aggregate consommateur, inject sur l’arête — constitue l’Injection Contract. Le compilateur évalue des étiquettes et transmet des chaînes ; l’interprétation relève du contrat de rédaction entre Recipe et Component.

4. Pas d’infrastructure fantôme : le compilateur n’invente jamais de ressources de calcul ni de fonctionnalités

Le compilateur n’injecte jamais silencieusement de ressources de calcul, de Features, d’annotations, de proxys de routage ni aucune autre ressource que l’auteur n’a pas explicitement déclarée. Les violations de politique produisent des garde-fous bruyants (Loud Guardrails) — la build s’arrête sur une erreur précise qui indique à l’auteur ce qu’il doit corriger, dans le document qu’il a écrit — et non des mutations silencieuses qui créent des mystères d’infrastructure au moment du débogage.

Les ressources entrent dans le graphe par des déclarations explicites au moment de la rédaction :

  • L’Aggregate du développeur (composants, arêtes uses, rattachements de Feature).
  • Les rattachements de Feature de la Release (ajouts au niveau de l’opérateur).
  • L’expansion pilotée par les annotations (le Manifest déclare des liaisons annotation → Feature ; l’annotation sur un Component ou une frontière est une déclaration explicite).
  • La production de ressources au niveau de la Recipe : le rendu de source de la Recipe produit l’artefact principal ; la synthèse de workload émet la forme de déploiement propre au fournisseur (spécification de Pod, service Compose, etc.) ; les entrées de artifacts: (en ligne ou chargées par $import:) émettent des manifestes auxiliaires intrinsèques à la Recipe ; la génération de ressources des FeatureRecipe émet des ressources auxiliaires par Feature, déclenchées par un rattachement explicite de Feature.

Les chemins au niveau de la Recipe sont des déclarations au moment de la rédaction, à une étape de distance : l’auteur de la Recipe écrit source / workload / artifacts / valuesMapping par rapport à un contrat de Component, et l’Aggregate du développeur choisit quels Components participent. Une ressource qui apparaît dans la sortie rendue remonte soit à une déclaration dans l’Aggregate, la Release ou une liaison d’annotation, soit à la rédaction de la Recipe que les types de composants de l’Aggregate ont sélectionnée.

La synthèse transforme les formes déclarées par l’auteur en formats de sortie propres au fournisseur. Une spécification de Workload rédigée comme une table de conteneurs peut être rendue en spécification de Pod Kubernetes, en bloc de service Compose ou en module Terraform — la transformation est pilotée par le fournisseur, mais les ressources remontent à la déclaration de Workload de l’auteur.

Le socket de gouvernance porte un rôle par rattachement, et c’est le rôle — non le type du plugin — qui fixe ce qu’un rattachement peut faire à une build. Un plugin de gouvernance rattaché dans un rôle de verdict — qui examine le graphe IR (ir-verdict) ou les artefacts rendus (render-verdict) — peut rejeter une build mais ne peut pas la modifier. Si un tel verdict veut qu’une ressource soit ajoutée, il fait échouer la build avec une indication de remédiation, afin que l’auteur ajoute lui-même la ressource ; l’hôte ne lit la sortie d’un verdict que comme une acceptation ou un rejet et ne l’applique jamais comme une modification, de sorte qu’une réécriture non sollicitée du graphe pour le rendre conforme — exactement l’infrastructure fantôme que cet invariant interdit — ne peut pas provenir d’un rôle de verdict. Un plugin de gouvernance rattaché dans un rôle de transformation (label-transform ou annotation-transform) est l’exception étroite et explicite : un opérateur qui en rattache un — sur option, via la configuration plugins.governance de l’espace de travail — a déclaré cette transformation, de sorte que les modifications qu’elle apporte sont une déclaration explicite, avec le même statut que l’expansion pilotée par les annotations, et non une injection silencieuse. La distinction tient à l’invitation : un verdict non demandé ne peut pas réécrire la build, alors qu’une transformation rattachée explicitement le peut, parce que l’opérateur l’a demandée. Comme une transformation façonne la sortie rendue, elle est épinglée dans le fichier de verrouillage comme tout plugin qui façonne la sortie — la transformation appliquée est fixée au moment du pull, de sorte que la changer implique un nouveau pull plutôt qu’un glissement silencieux entre deux builds ; un verdict ne façonne aucune sortie et n’est pas épinglé.

5. L’Aggregate est la surface de rédaction ; la Release ne peut pas déclarer values:

Le schéma de la Release interdit mécaniquement un bloc values:. Les opérateurs ne peuvent pas écrire de values sur un Component ou une Feature depuis une Release. Il s’agit d’une contrainte du schéma au niveau de JSON Schema — ni un contrat social, ni une convention — et elle est bruyante : chaque document d’entité est validé par rapport au schéma de son type au chargement, de sorte qu’une Release portant values: arrête la build avec un diagnostic qui nomme le fichier et la clé fautive, au lieu d’être ignorée silencieusement.

Cela ne signifie pas que les valeurs sont identiques d’un environnement à l’autre. La voie prise en charge pour la variation par environnement est la remontée des paramètres (Parameter Hoisting) :

  1. Le développeur expose un champ typé parameters.* dans l’Aggregate.
  2. Le modèle values du Component y fait référence : storage_size: "{{ .parameters.db_size }}".
  3. La Release renseigne le paramètre : parameters: { db_size: "100Gi" }.
  4. La sortie rendue reflète la valeur propre à l’environnement.

L’Aggregate reste la source unique de vérité quant aux valeurs exposées à la variation par environnement (la déclaration parameters) et à la façon dont elles alimentent les valeurs du composant (la référence dans le modèle). La Release renseigne ; elle ne remplace pas.

Deux autres contraintes protègent le même invariant :

  • Quand une Release utilise extends, déclarer un pointeur aggregate: est interdit par le schéma. La Release enfant doit déployer la même intention du développeur (Developer Intent) que sa Release parente.
  • La Release ne peut pas introduire de ressources de calcul que l’Aggregate n’a pas déclarées, ni rediriger une arête que le développeur a déclarée. Dans les sockets que l’Architect a déclarés, la Release peut câbler et configurer des arêtes entre composants existants : elle définit l’infra par arête sur une arête que le développeur a câblée, ou câble vers un composant existant une arête aboutissant à un socket déclaré mais non lié. Elle ne peut pas déclarer de values par arête (elles restent dans l’Aggregate), lier un socket que le usesSchema du Component ne déclare pas, ni faire pointer une arête vers un composant qui n’existe pas — chacun de ces cas arrête la build. Notez quelle déclaration vise la proposition du milieu : le socket doit figurer dans le usesSchema du Component du catalogue. L’auteur d’un Aggregate peut nommer un socket que son type de composant ne déclare pas, et la surface de la Release n’est délibérément pas ouverte de la même manière — un opérateur câble et configure à l’intérieur d’une architecture au lieu d’en inventer une.

La configuration de connexion par arête est limitée au consommateur : les values et l’infra portés par une arête n’apparaissent que dans le contexte de rendu du nœud qui a rédigé l’arête, jamais dans le contexte de la cible. La sortie rendue d’un composant est donc invariante vis-à-vis des connexions que d’autres composants établissent vers lui — câbler ou configurer une arête vers une cible ne perturbe jamais ce que rend la Recipe de la cible. Le seul endroit où ces connexions sont visibles est une Feature rattachée à la cible : sa FeatureRecipe peut lire quels composants utilisent la cible, de sorte que les ressources qu’elle émet — par exemple une politique admettant exactement les appelants déclarés — suivent le câblage, alors que la sortie propre de la cible ne le fait pas. Même là, les values et l’infra par arête restent du côté du consommateur.

6. La frontière ABI WebAssembly : l’intelligence propre au domaine vit dans Wasm

Le binaire hôte en Go ne contient aucune logique propre au cloud ni à l’infrastructure. Toute l’intelligence propre au domaine, le rendu des modèles et la mise en forme vivent strictement dans des plugins WebAssembly exécutés par le runtime Wazero embarqué. L’hôte Go orchestre le pipeline et transmet les charges utiles à travers l’ABI aux invités Wasm sous forme de pointeurs mémoire, dans l’encodage que porte chaque socket.

Il en découle deux corollaires :

  • La logique propre au Provider (rendu propre à Helm, mise en forme propre à Terraform, fusion propre à Compose) ne vit jamais dans le cœur du compilateur Go. Le compilateur résout le nom de fournisseur qu’une Recipe déclare dans spec.capability en le Plugin de rendu de fournisseur qui le sert, et répartit le nœud vers ce plugin ; la traduction elle-même s’exécute entièrement dans l’invité Wasm. L’hôte ne contient pas de code Go par fournisseur pour un fournisseur standard, il n’y a donc rien dans le processus sur quoi se rabattre — un nom de fournisseur qui ne se résout en aucun Plugin le servant arrête la build au lieu de rendre une quelconque valeur par défaut intégrée.
  • La logique de politique (règles de sécurité, contrôles de conformité, calculs FinOps) ne vit jamais dans le cœur du compilateur Go. Les politiques relèvent du socket de gouvernance Wasm que les entreprises activent sur option — un plugin rattaché dans un rôle de verdict (ir-verdict / render-verdict) pour accepter ou rejeter une build, ou dans un rôle de transformation (label-transform / annotation-transform) pour façonner les étiquettes ou les annotations.

La frontière ABI garde le cœur Go compact, auditable et indépendant du cloud. Remplacer la logique de rendu d’un fournisseur revient à remplacer un artefact Wasm, et non à recompiler Aggrega lui-même.

7. Séparation des préoccupations (répartition en quatre domaines) — un guide, pas une prison

Les recommandations de conception d’Aggrega répartissent la rédaction en quatre domaines :

  • Developer Intent — Aggregate.
  • Platform Architect — entités de catalogue Component et Feature.
  • Platform Ops — Recipe, FeatureRecipe, Plugin (y compris le Plugin de rendu de fournisseur).
  • Platform Operator — Manifest, Release.

Le déploiement typique et qui fonctionne bien suit cette répartition : les développeurs écrivent l’intention applicative, pas l’infrastructure physique ; les Ops écrivent l’infrastructure physique, pas la logique applicative. Aggrega est conçu pour être utilisé ainsi, et la documentation officielle, les exemples et le catalogue de la bibliothèque standard sont rédigés en fonction de cette répartition.

La répartition en quatre domaines est un guide et un cadre de conception, et non une contrainte imposée par le compilateur. Le compilateur (selon l’invariant 1) est sans parti pris. Les utilisateurs sont libres de :

  • Fusionner les rôles (une seule personne qui écrit à la fois des Aggregates et des Recipes).
  • Mélanger les préoccupations (des Architects qui codent en dur des étiquettes de conformité directement sur des Components core/* quand les catalogues d’entreprise l’exigent).
  • Franchir les frontières entre domaines (des développeurs qui utilisent la remontée des paramètres pour injecter des préoccupations d’infrastructure dans l’Aggregate quand du code existant l’exige).

Le compilateur accepte tout modèle de rédaction qui passe la validation de schéma. L’architecture promeut les bonnes pratiques ; les contraintes au niveau du schéma (comme l’interdiction de values: dans la Release, invariant 5) sont les seuls franchissements de domaine que le compilateur rejette réellement. Toute autre séparation est un contrat social maintenu par les auteurs de catalogues et, là où les entreprises l’activent, par le socket de gouvernance Wasm.

8. Sortie déterministe

À entrée identique, le compilateur produit une sortie identique octet pour octet. Deux compilations du même Aggregate + Release + Manifest avec le même catalogue donnent des artefacts rendus égaux octet pour octet.

C’est le contrat sur lequel s’appuient les outils GitOps et les flux de revue fondés sur les diffs. Une pull request qui n’a pas modifié l’entrée ne devrait produire aucun diff dans la sortie rendue. Une pull request qui a modifié l’entrée ne devrait montrer que le diff qu’implique ce changement — aucun réordonnancement parasite, aucune fluctuation d’horodatage, aucun artefact d’itération de tables.

La sortie déterministe est assurée par trois disciplines :

  • Tables ordonnées par l’auteur : chaque table dont l’ordre d’itération pourrait affecter la sortie rendue utilise un conteneur de table ordonnée, afin que l’itération suive l’ordre de déclaration de l’auteur plutôt que l’ordre de hachage.
  • Aucun contenu dépendant de l’horloge ou aléatoire dans les artefacts rendus, sauf si l’auteur l’a explicitement injecté via l’entrée du modèle.
  • Le rendu est pur : la même invocation d’un invité Wasm avec la même entrée produit la même sortie.

L’option --trace du compilateur (voir language-reference/cli/aggrega-build.md) donne aux auteurs et aux opérateurs une surface de vérification pour cet invariant. Deux compilations de la même entrée avec --trace activé produisent des traces identiques octet pour octet ; tout diff dans une passe localise une régression. Le déterminisme n’est pas seulement une propriété au moment de la publication — il est observable à chaque état intermédiaire du compilateur grâce à la disposition des traces par nœud.

La sortie déterministe est le contrat qui permet d’utiliser Aggrega en toute sécurité comme source de vérité dans une boucle GitOps.

Portée de l’invariance selon les niveaux de résolution

La garantie de sortie identique octet pour octet s’applique aux artefacts épinglés dans le fichier de verrouillage — les entités résolues via des artefacts de registre dont le fichier de verrouillage enregistre les empreintes (le niveau registre du modèle de résolution des entités à trois niveaux). Quand une build lit les fichiers qu’une Release nomme par chemin (chemins locaux commençant par ./ ou ../) ou des entités dans des répertoires de catalogue de l’espace de travail (catalog_dirs:, au niveau espace de travail et cache), l’invariance dépend de ce que ces fichiers restent inchangés entre deux builds. Le fichier de verrouillage enregistre une entité d’un répertoire de catalogue de l’espace de travail par l’empreinte de son document et des fichiers qu’elle déclare, de sorte qu’une build s’arrête sur une entité modifiée depuis le pull au lieu de la rendre — à une exception près : une Recipe ou une FeatureRecipe que le Manifest nomme par une référence qui est aussi le nom d’un Component ou d’une Feature est enregistrée sous cette référence comme Component ou Feature, si bien que ses entrées ne sont retenues que par les épingles voisines dans le fichier de verrouillage, et qu’une modification de son propre document n’est pas détectée. Conserver les fichiers tels qu’ils étaient relève du système de gestion de versions (généralement Git).

Une référence à un chemin local dont le fichier sous-jacent change entre deux compilations produit un diff légitime dans la sortie rendue même si la forme de l’entrée du compilateur est inchangée — la garantie de sortie déterministe est préservée (même entrée en octets → même sortie en octets), mais les entrées diffèrent parce que le fichier local a changé. Les catalogues qui ont besoin d’une invariance entre builds pour chaque source récupèrent les artefacts d’un registre dans le cache épinglé par le fichier de verrouillage plutôt que de les lire depuis un chemin local ou un répertoire de l’espace de travail ; le fichier de verrouillage est l’ancre de l’identité octet pour octet.