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

Contrats sociaux

Aggrega est, par conception, un compilateur sans parti pris. Selon les invariants fondateurs documentés dans architecture/05-invariants.md, le compilateur analyse le YAML, parcourt des graphes, évalue des intersections de labels et achemine des chaînes entre composants — mais il ne contrôle pas ce que les développeurs mettent dans values, parameters, infra, provides ou locals ; il n’impose ni conventions de nommage, ni conventions de ports, ni les labels sémantiques qu’un Architecte invente ; il ne devine pas la finalité d’un composant à partir des noms. Beaucoup de disciplines qui ressemblent à des règles du compilateur sont en réalité des contrats sociaux : des bonnes pratiques maintenues par une convention de rédaction plutôt que par le schéma ou par une application à l’exécution.

Il vaut la peine de dire clairement où s’arrête cette neutralité, parce qu’il s’agit d’une seule ligne et qu’il est facile de la surinterpréter. Quelques clés sont propres à Aggrega — réservées, avec les valeurs qu’elles acceptent écrites dans le schéma publié — et celles-là, le schéma les vérifie bien, de la même manière qu’il vérifie tout autre champ déclaré. Déclarer l’ensemble des valeurs d’une clé que la plateforme définit elle-même, ce n’est pas le compilateur qui lit un sens dans ce que vous avez écrit ; c’est la plateforme qui dit ce que signifie sa propre clé. Tout ce que vous rédigez sous une clé à vous reste exactement aussi peu contrôlé que le décrit cette page.

Cette page est l’inventaire canonique des contrats sociaux du langage. Les auteurs qui apprennent ces contrats sur cette page peuvent comprendre pourquoi le compilateur accepte un build mal formé au regard d’une convention (il l’accepte — le compilateur n’interprète pas la convention) et à qui revient la responsabilité de détecter la violation (discipline de rédaction, attention des relecteurs ou un plugin linter exécuté par aggrega lint).

Trois classes de discipline

Les disciplines d’Aggrega se répartissent en trois classes selon la manière dont la discipline est imposée. Cette classification compte, car chaque classe a un mode de défaillance différent lorsque la discipline est violée.

Imposée par le schéma

La discipline est imposée par la validation JSON Schema 2020-12 au chargement (le JSON Schema de l’enveloppe de l’entité, plus les déclarations schema: au niveau des piliers sur les entités Component et Feature). Une violation produit un arrêt fatal avant que le build ne progresse ; le compilateur refuse de continuer. Les auteurs qui tentent de violer une discipline imposée par le schéma voient une erreur de validation explicite qui désigne le champ et la contrainte.

Exemples : les champs obligatoires de l’enveloppe de l’entité (apiVersion / kind / metadata.name / metadata.version) ; la regex SemVer sur metadata.version ; l’ensemble fermé de valeurs du label réservé component.aggrega.ai/type ; l’interdiction mécanique des blocs values: par le schéma de la Release (selon l’invariant 5) ; le rejet de extends combiné à aggregate sur la Release (l’invariant de la source unique de vérité) ; les règles de forme de la Recipe qui imposent le contrat de composition des types d’entrée.

Les disciplines imposées par le schéma sont les garanties les plus fortes que porte le langage. Le compilateur refuse de produire le rendu de tout ce qui les viole.

Imposée par un plugin de politique

La discipline est imposée par un plugin Wasm exécuté à l’un des points de socket documentés (le rôle de gouvernance label-transform lors de la construction de la topologie ; le rôle de gouvernance ir-verdict lors de l’analyse statique ; le socket du linter hors bande). Une violation produit soit un échec de politique qui arrête le build (sockets en bande), soit un avertissement consultatif (sockets hors bande), selon la sémantique de blocage du socket.

Une discipline n’est imposée de cette manière que là où s’exécute un plugin qui la vérifie : le runtime Wasm invoque les plugins aux points de socket documentés, et une discipline qu’aucun plugin ne vérifie reste une convention. Le linter de publication, qu’exécute aggrega lint, vérifie une partie d’une convention de cette page — voir Conventions qu’une règle du linter vérifie. Aucune règle du linter de publication ne vérifie l’herméticité (la FuncMap de Sprig expose des helpers qui cassent le déterminisme de la sortie, selon la mise en garde sur le déterminisme de templates/sprig-functions.md) ni le nommage des ressources cloud (les Recipes dont les sorties de valuesMapping: référencent des champs de nom de ressource cloud sans interpolation de release_name / instance_id, selon entities/recipe.md « Cloud-resource naming discipline (Discipline de nommage des ressources cloud) ») ; votre propre plugin linter peut vérifier l’un ou l’autre.

Pour la surface du contrat des plugins Wasm et le critère de placement (le socket du linter face aux rôles de verdict de gouvernance), voir plugins/plugin-contract.md.

Maintenue par convention

La discipline n’est maintenue que par la discipline de rédaction et l’attention des relecteurs. Le compilateur ne l’impose pas ; aucun schéma ne rejette la violation ; aucun plugin Wasm ne la signale. Les auteurs apprennent la discipline dans la documentation, la suivent parce que la forme architecturale en dépend, et comptent sur la revue de PR pour repérer les écarts. Une violation ne produit aucun signal à la compilation — le build réussit, la sortie rendue fonctionne pour autant que le compilateur le sache, et la violation de la discipline n’apparaît que lorsque l’outillage en aval ou le comportement à l’exécution dépend de la convention.

Les disciplines maintenues par convention forment la liste porteuse que les auteurs doivent apprendre dans la documentation. Le compilateur ne les interprète pas ; se tromper ne casse pas le build, mais casse la forme architecturale dont Aggrega dépend. L’essentiel de cette page les documente.

Les conventions

Les contrats sociaux suivants sont maintenus par convention. Chaque entrée nomme la discipline, la surface où la convention est documentée et le mode de défaillance en cas de violation. Chacun conserve son numéro où qu’il se trouve : le contrat 3, la discipline des préfixes réservés, est vérifié par une règle du linter pour les clés d’annotation et est décrit sous Conventions qu’une règle du linter vérifie.

1. Choisir le type opérationnel adapté au composant

Le label réservé component.aggrega.ai/type indique quel genre de chose est un composant, à partir d’un ensemble fermé de primitives cloud universelles : server, worker, task, function, stateful-server, resource. L’appartenance à cet ensemble est imposée par le schéma, et non maintenue par convention. Aggrega définit cette clé et les valeurs qu’elle accepte, le schéma du Component les énumère, et un document portant toute autre valeur est refusé au chargement — E0215, la condition entity-envelope-invalid, nomme le label et liste les valeurs qu’il accepte. Ce refus est ce que cette entrée ne couvre pas.

Ce qui reste une convention, c’est laquelle des valeurs convient au composant que vous avez devant vous. Rien ne vérifie qu’une base de données relationnelle est labellisée stateful-server plutôt que server, ni qu’un consommateur de file d’attente est worker plutôt que task ; le sélecteur évalue toute valeur qu’il trouve sans lui prêter de sens. L’Architecte qui rédige un Component choisit la valeur qui décrit comment l’infrastructure doit le traiter, et les sélecteurs en aval, les plugins de politique et les plugins de rendu Wasm comptent tous sur l’honnêteté de ce choix.

Classer selon un axe qui vous est propre. L’ensemble fermé régit cette seule clé réservée et rien d’autre. Un catalogue qui a besoin d’une classification qu’Aggrega ne définit pas — un niveau, une zone de données, une classe de service ou une subdivision plus fine des primitives opérationnelles — ajoute sa propre clé de label à côté de la clé réservée. Le schéma du Component accepte toute autre clé de label avec une valeur de type chaîne, et la même mécanique de sélecteurs la lit, de sorte que acme.aggrega.ai/storage-tier: oltp côtoie component.aggrega.ai/type: stateful-server et que l’appliesTo d’une Feature ou le selector d’un socket peut cibler l’une ou l’autre. L’extension se fait sur une clé qui vous est propre, jamais sur une valeur à l’intérieur de celle d’Aggrega.

Documenté dans : architecture/02-ecosystem-philosophy.md (l’ontologie opérationnelle) + labels-and-annotations.md (discipline des préfixes) + errors/sentinels.md (E0215).

Mode de défaillance : Une valeur de l’ensemble qui ne convient pas au composant induit en erreur tout ce qui lit le label. Un magasin de données labellisé server est refusé par une Feature ou un socket qui sélectionne stateful-server — un arrêt qui nomme le sélecteur, pas l’erreur de label — et un plugin de politique ou un plugin de rendu qui lit le label le traite comme du calcul sans état. Là où seuls ces lecteurs le voient, le build réussit ; l’erreur n’apparaît qu’une fois que les artefacts rendus atteignent le cluster.

2. Séparation de .context.annotations.* en trois compartiments

Les annotations en cascade arrivent dans trois compartiments nommés — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — chacun porteur d’une intention différente. L’objectif de la discipline : release est « où ce composant s’exécute, régi par Ops » ; catalog est « ce qu’est ce composant, rédigé par l’Architecte » ; aggregate est « ce que fait ce composant, rédigé par le Développeur ».

Le compilateur n’impose pas les frontières entre les compartiments. Les trois compartiments partagent une forme plate string → string ; le template d’une Recipe peut lire les trois, et rien n’empêche qu’une annotation de frontière de Release soit interprétée comme des métadonnées cognitives ou qu’une annotation de catalogue soit acheminée dans infra:. La séparation est maintenue par les auteurs qui écrivent les annotations dans le bon compartiment et par les relecteurs qui repèrent les fuites entre compartiments.

Documenté dans : labels-and-annotations.md (la séparation en trois compartiments est un contrat social).

Mode de défaillance : Une logique de routage qui dépend de la distinction d’intention entre compartiments (par ex. une Recipe qui achemine .context.annotations.release.aggrega.ai/region dans un champ region de Terraform) consomme silencieusement toute annotation qui apparaît dans le compartiment, quelle que soit l’intention de rédaction. Le build réussit ; la sortie rendue peut porter des valeurs sémantiquement erronées.

4. Autonomie de provides: dans la Recipe

Les templates provides: d’une Recipe ne se referment que sur les données propres du nœud — .values, .infra, .context.instance_id, .context.rendered_name là où le fournisseur du nœud en signale un, les .locals résolus du nœud, plus des chaînes statiques. Les références à .context.inject et .context.uses sont interdites, car l’évaluation des provides exécute ces templates dans n’importe quel ordre ; lire des données d’autres nœuds la couplerait à l’ordre d’itération topologique, ce que la conception évite délibérément. .locals fait partie de la surface au lieu d’en être exclu : les locals du nœud se résolvent dans le préambule de la même étape, avant ses provides, et ils sont locaux au nœud, si bien que les lire ne coûte rien en matière d’ordre. Nommer une clé que le bloc locals ne déclare pas provoque un arrêt.

C’est une règle en deux moitiés, chacune indiquant où elle est vérifiée. Le compilateur vérifie la première : l’évaluation des provides vérifie chaque template par rapport à une liste d’autorisation positive des racines que son contexte définit avant que le template ne s’exécute, de sorte qu’une lecture de .context.inject / .context.uses s’arrête avec une erreur explicite au lieu de produire un rendu vide ; la règle est aussi documentée dans templates/expansion-matrix.md, ligne 6. La convention maintient la seconde : le modèle plus large (provides-is-public; locals-is-private) est ancré dans la convention.

Documenté dans : templates/expansion-matrix.md ligne 6 + vocabulary/data-pillars.md « provides: and locals: — public face vs private face (provides: et locals: — face publique et face privée) ».

Mode de défaillance : le compilateur détecte les références interdites et arrête le build au moment de l’évaluation des templates lorsqu’elles apparaissent directement dans provides:. La discipline plus large public contre privé (ne pas exposer d’état interne via les clés de provides:) relève uniquement de la convention — les auteurs qui traitent provides: comme un espace de noms interne à la Recipe produisent des contrats dont les appelants dépendent ; le refactoring devient un changement cassant.

5. Déterminisme — helpers non hermétiques dans les templates du chemin de rendu

L’invariant de sortie déterministe d’Aggrega (invariant 8 dans architecture/05-invariants.md) exige une sortie identique octet pour octet pour une entrée identique octet pour octet. La FuncMap complète de Sprig expose des helpers qui lisent l’état ambiant (lecteurs d’horloge now / date ; générateurs aléatoires randAlpha / uuidv4 ; lecteurs d’environnement env / expandenv ; résolveurs réseau getHostByName). Les auteurs qui invoquent ces helpers depuis un template qui contribue à la sortie rendue cassent le contrat de déterminisme.

Le compilateur ne détecte ni ne bloque l’utilisation de helpers non hermétiques. La FuncMap de Sprig les expose selon templates/sprig-functions.md « Determinism caveat (Mise en garde sur le déterminisme) » ; la discipline est maintenue par les auteurs qui évitent ces helpers dans les templates du chemin de rendu et par les relecteurs qui repèrent leur usage lors de la revue de PR.

Documenté dans : templates/sprig-functions.md « Determinism caveat (Mise en garde sur le déterminisme) ».

Mode de défaillance : La sortie du build diffère d’une exécution à l’autre pour la même entrée. L’écart apparaît au moment du diff GitOps, lorsque l’outillage en aval (ArgoCD, Flux) constate une dérive inattendue entre le manifeste commité et l’état du cluster, ou au moment d’un audit, lorsque deux compilations de la même entrée produisent des artefacts différents.

Aucune règle du linter de publication ne vérifie les templates à la recherche d’invocations de helpers non hermétiques. Le nom du helper est écrit dans le template, si bien que votre propre plugin linter peut le trouver (voir Conventions qu’une règle du linter vérifie).

6. Frontières des piliers (des panneaux, pas des murs)

Les frontières des piliers relèvent de la discipline de rédaction, non d’une contrainte du langage. Le moteur de templates permet des lectures entre piliers à chaque endroit, sauf interdiction explicite par des règles d’autonomie (par ex. provides: et source: d’une Recipe qui lisent .context.inject / .context.uses). Les auteurs devraient :

  • Lire .values pour la charge utile cognitive (intention rédigée par le développeur).
  • Lire .infra pour le dimensionnement physique (dimensionnement rédigé par Ops).
  • Lire .context.uses.<alias>.provides.<key> pour les chaînes de pointeur entre composants.
  • Lire .context.inject pour le pipe de livraison post-hydratation.

Le moteur de templates ne contrôle pas la lecture. Un template de Recipe qui lit .infra.replicas pour piloter un champ values: fonctionne ; rien n’empêche le chemin entre piliers. L’objectif de la discipline, ce sont des panneaux — les frontières décrivent l’intention de rédaction (à qui appartiennent les données) plutôt qu’une restriction à l’exécution.

Documenté dans : vocabulary/data-pillars.md « Pillar boundaries and authoring discipline (Frontières des piliers et discipline de rédaction) ».

Mode de défaillance : Fuite entre piliers — la charge utile cognitive du développeur contient des détails de dimensionnement physique, ou le dimensionnement rédigé par Ops contient des métadonnées cognitives. Le build réussit ; la répartition de la rédaction en quatre domaines s’estompe avec le temps à mesure que les auteurs contournent les piliers ; la maintenance en aval devient plus difficile à mesure que la correspondance entre piliers et flux de données s’affaiblit.

7. Sémantique à double source de containers.<name>.variables du Workload

La map variables: mêle deux sources de données distinctes au moyen d’expressions de template Go : des littéraux du pilier développeur (entrées qui lisent .values / .infra / .locals) et des données du pipe entre composants (entrées qui lisent .context.inject.env.<KEY>). Les auteurs choisissent une source par entrée selon que la valeur est locale au composant ou dérivée d’autres composants.

Le compilateur ne distingue pas les deux sources ; toutes deux aboutissent dans la même liste env: de Kubernetes sur le Deployment rendu. La sémantique à double source n’existe qu’au moment de la rédaction — la discipline consiste à nommer l’intention (cette entrée est locale au composant ; celle-là est dérivée d’autres composants) afin que les futurs mainteneurs puissent lire quelles entrées dépendent de quelles sorties de l’hydratation d’inject.

Documenté dans : entities/workload.md « Field-semantics essentials (Notions essentielles sur la sémantique des champs) » (variables).

Mode de défaillance : Les auteurs qui ne distinguent pas les deux sources perdent la trace « quelles entrées sont couplées aux provides: de quelle cible ». Refactoriser les clés de provides: d’une cible casse silencieusement chaque entrée variables: appelante qui lisait via le pipe d’inject.

8. Discipline de nommage des ressources cloud

Les Recipes qui émettent des noms de ressources cloud (noms de buckets S3, identifiants de bases de données RDS, noms de rôles IAM, noms de stacks CloudFormation — tout champ dont la valeur occupe un espace de noms global chez le fournisseur cloud) doivent concaténer {{ .metadata.release_name }} et/ou {{ .context.instance_id }} dans le nom rendu pour éviter les collisions lorsque la même Recipe s’exécute sur plusieurs Releases ou instances de composant.

Le compilateur n’inspecte pas les sorties de valuesMapping: à la recherche de champs de nom de ressource cloud dépourvus de ces interpolations. La discipline est maintenue par les auteurs de Recipe (qui savent quels champs nomment des ressources globalement uniques pour le fournisseur cible) et par les relecteurs (qui repèrent les motifs de ressources non nommées lors de la revue de PR).

Documenté dans : entities/recipe.md « Cloud-resource naming discipline (Discipline de nommage des ressources cloud) ».

Mode de défaillance : Deux Releases du même Aggregate (prod-billing et staging-billing) tentent toutes deux de déployer une ressource portant le même nom global ; le second déploiement échoue à l’exécution avec un rejet côté cloud. Le build d’Aggrega réussit ; l’échec du déploiement n’apparaît que lorsque la seconde Release est appliquée.

Aucune règle du linter de publication ne vérifie que les champs de nom de ressource cloud contiennent les interpolations requises ; votre propre plugin linter le peut (voir Conventions qu’une règle du linter vérifie).

9. Granularité du Component — un service cohérent par Component

Un Component modélise un service cohérent — un seul service exposé, ou la ou les charges de travail d’un service avec ses charges de travail auxiliaires purement internes. Lorsqu’un chart regroupe des services qu’un autre composant pourrait utilement référencer seuls avec use — en particulier une infrastructure externe telle qu’une base de données, un cache ou un broker de messages qu’Aggrega modélise déjà comme son propre Component — la bibliothèque standard compose des Components par service en un module sous-agrégat (spec.aggregates + exportedComponents) au lieu d’envelopper le produit entier dans un seul Component opaque. La discipline : plusieurs charges de travail conviennent au sein d’un Component ; l’utilisabilité indépendante est la ligne qui scinde un Component en un stack.

Le compilateur est agnostique vis-à-vis de cette granularité. Il produit le rendu de tout ce qui passe la validation du schéma — il n’inspecte ni le nombre de services que regroupe la Recipe d’un Component, ni si l’un d’eux est utilisable de façon indépendante. Un auteur qui enveloppe un produit à cinq services dans un seul Component produit un Component que le compilateur accepte et rend sans protester ; la convention est maintenue par la discipline de rédaction et l’attention des relecteurs.

Documenté dans : ../../architecture/06-data-taxonomy-and-composition.md (un service cohérent par Component — la frontière de la charge de travail unique).

Mode de défaillance : Un enveloppement monolithique multi-services se compile avec succès, mais les services regroupés sont invisibles pour la topologie, le sélecteur et la politique — ils ne peuvent être ni mis à l’échelle, ni remplacés, ni servir de dépendance indépendamment. Refactoriser plus tard le monolithe en Components par service est un changement cassant pour chaque consommateur qui référençait le nœud enveloppé unique.

Pourquoi les conventions existent

Chacune de ces conventions relève de la discipline de rédaction par choix de conception, bien qu’un schéma ou une politique Wasm puisse imposer n’importe laquelle d’entre elles. Le raisonnement par type de contrat :

Extensibilité. La discipline des préfixes réservés (contrat 3) décrit le vocabulaire de la bibliothèque standard, pas l’univers du vocabulaire valide. Les catalogues d’entreprise rédigent leurs propres préfixes et clés de label pour étendre la bibliothèque standard ; imposer par le schéma la convention des préfixes transformerait « la discipline de la bibliothèque standard » en « la seule forme autorisée par le langage » — c’est le mur que l’architecture évite délibérément. L’axe du type opérationnel (contrat 1) conserve la même extensibilité sur une autre surface : la clé réservée qu’Aggrega définit porte un ensemble fermé, imposé par le schéma, et un catalogue étend en ajoutant sa propre clé de label à côté d’elle plutôt qu’une valeur à l’intérieur de celle d’Aggrega. Ce que le schéma vérifie, c’est l’ensemble de valeurs d’une clé qu’il possède ; ce qui reste ouvert, c’est toute autre clé, et c’est là que vit le vocabulaire propre d’un catalogue.

Pureté AOT. La discipline de nommage des ressources cloud (contrat 8) et la discipline du déterminisme (contrat 5) exigent d’inspecter le contenu des templates pour déterminer si un champ est un nom de ressource cloud ou l’invocation d’un helper non hermétique. La pureté AOT (invariant 2) empêche le compilateur de dépendre de l’état à l’exécution ; l’inspection statique des templates est réalisable (un plugin linter lit les templates de l’entité tels qu’ils sont écrits), mais la faire dans le compilateur central couple la logique interne du compilateur à des préoccupations de rédaction propres à chaque domaine. L’architecture sort ces vérifications du compilateur pour les placer dans des plugins Wasm, selon l’invariant 6 (la frontière de l’ABI Wasm).

Flexibilité de rédaction. La discipline des frontières des piliers (contrat 6) et la sémantique à double source de variables (contrat 7) décrivent des modèles de rédaction plutôt que des contraintes à l’exécution. La même syntaxe de template peut exprimer un modèle qui respecte la discipline ou un modèle qui la viole ; faire de la discipline une vérification à l’exécution exigerait que le compilateur interprète une intention de rédaction à laquelle il n’a pas accès. L’architecture traite la convention comme une documentation dont les auteurs apprennent plutôt que comme un invariant à l’exécution. La granularité du Component (contrat 9) se range ici aussi : les entreprises peuvent envelopper un produit à la granularité que leur catalogue privilégie, et le compilateur — neutre vis-à-vis du contenu et sans parti pris selon l’invariant 1 — n’a aucun moyen de savoir si une charge de travail regroupée est utilisable indépendamment, si bien que la frontière du service cohérent unique reste une discipline de rédaction plutôt qu’un mur de schéma. Le choix du type opérationnel (contrat 1) a la même forme : le schéma fixe quelles valeurs existent, mais celle qui décrit un composant donné relève d’un jugement de modélisation sur la manière dont l’infrastructure doit le traiter, et rien dans une Recipe ou dans un bloc values n’indique au compilateur si ce jugement était juste.

Imposition en deux moitiés. L’autonomie de provides: dans la Recipe (contrat 4) est en partie imposée par le compilateur — le chemin de rendu détecte les lectures de .context.inject / .context.uses dans les templates provides: et s’arrête. La discipline plus large public contre privé (ne pas exposer d’état interne) est ancrée dans la convention, car le compilateur ne peut pas déterminer quelles chaînes doivent rester internes à la Recipe sans l’intention de rédaction.

Les trois voies comptent, car chacune indique où se situe la responsabilité de repérer les violations. Imposée par le schéma : le compilateur. Imposée par un plugin de politique : le plugin qui la vérifie, là où il s’en exécute un. Maintenue par convention : les auteurs et les relecteurs. Les auteurs qui intériorisent ces voies comprennent quelles erreurs le compilateur interceptera et lesquelles passeront silencieusement jusqu’à l’outillage en aval ou à l’exécution.

Conventions qu’une règle du linter vérifie

Le linter de publication, exécuté par aggrega lint, vérifie en partie une convention de cette page : les clés d’annotation du contrat 3, ci-dessous. Son constat est consultatif, et la partie de la convention qu’il n’atteint pas est maintenue par convention, comme les entrées ci-dessus.

Aucune règle du linter de publication ne vérifie une autre convention de cette page. Deux d’entre elles peuvent être vérifiées par une règle du linter, car la violation est écrite dans l’entité : le déterminisme (contrat 5) — un template qui appelle un helper non hermétique — et le nommage des ressources cloud (contrat 8) — une sortie de valuesMapping: qui nomme une ressource cloud sans interpolation de release_name / instance_id. Il en va de même des clés de label sous les préfixes réservés (contrat 3). Un workspace peut attacher ses propres plugins linter sous plugins.linter, à côté du linter de publication, pour vérifier n’importe laquelle d’entre elles ; Les règles de discipline liste les règles que porte le linter de publication.

Les autres conventions (1, 2, 4, 6, 7, 9) dépendent de ce que l’auteur voulait dire, ce qu’aucune règle ne lit dans ce qui a été écrit. La séparation en compartiments est motivée par l’extensibilité (les catalogues d’entreprise la redéfinissent) — une imposition par le schéma entrerait en conflit avec cette flexibilité. Ce qui reste de l’axe du type opérationnel une fois que le schéma a fixé l’ensemble de valeurs — choisir la primitive adaptée au composant — relève de l’intention de rédaction : le compilateur ne peut pas distinguer un type opérationnel bien choisi d’un type mal choisi, car les deux sont des valeurs qu’il accepte. La discipline des frontières des piliers et la sémantique à double source de variables relèvent de l’intention de rédaction — le compilateur ne peut pas déterminer l’intention à partir de la seule syntaxe des templates. L’autonomie de provides: dans la Recipe est en partie imposée ; la discipline plus large public contre privé dépend des clés que l’auteur voulait garder internes, ce que rien dans la Recipe n’énonce. La granularité du Component relève elle aussi de l’intention de rédaction — savoir si une charge de travail regroupée est utilisable indépendamment est un jugement de modélisation que le compilateur ne peut pas lire dans le contenu de la Recipe.

3. Discipline des préfixes réservés

Les clés d’annotation et de label suivent une forme <namespace>/<name>. Cinq préfixes réservés portent des règles de rédaction spécifiques : aggrega.ai/ (réservé à la plateforme), feature.aggrega.ai/ (raccourcis officiels de Feature), component.aggrega.ai/ (traits intrinsèques au Component), aggregate.aggrega.ai/ (identité de module de l’Aggregate) et <any-other-domain>/ (entreprise / communauté).

Le compilateur ne rejette pas une annotation rédigée sous un préfixe réservé sur une entité de catalogue ou une Release ; seuls une liaison d’annotation d’un Manifest ou un label de sortie d’une Recipe qui revendique une clé sous aggrega.ai/ arrêtent le build. Une entreprise qui déclare aggrega.ai/internal-billing-tag: "..." en dehors du vocabulaire de la plateforme produit une annotation que le compilateur accepte et propage en cascade à travers le système de compartiments ; les mises à jour ultérieures de la plateforme qui introduisent un véritable aggrega.ai/internal-billing-tag entrent silencieusement en collision.

Documenté dans : labels-and-annotations.md (Discipline des préfixes) + providers/well-known-annotations.md.

Mode de défaillance : Les annotations personnalisées sous des préfixes réservés entrent en collision avec de futures annotations de la plateforme portant le même nom ; le comportement attendu de la plateforme écrase silencieusement la valeur rédigée par l’entreprise ou coexiste avec elle, selon l’ordre.

Le linter de publication, exécuté par aggrega lint, signale une clé d’annotation d’une entité de catalogue sous aggrega.ai/ qui ne fait pas partie des annotations connues de la plateforme, ainsi qu’une clé sous feature.aggrega.ai/ sur une entité autre qu’une Feature, comme constat consultatif (E0277). Les clés de label, les autres préfixes réservés et les annotations hors des metadata.annotations d’une entité — celles qu’écrit une Release, par exemple — ne sont pas vérifiés, si bien que pour eux la discipline reste une convention.

Références croisées