État du langage
Cette page est la référence canonique indiquant quelles surfaces d’Aggrega sont utilisables aujourd’hui, lesquelles sont documentées mais pas encore prises en compte par le compilateur, et lesquelles sont prévues pour une itération future. Elle complète les chapitres par domaine en présentant en un seul endroit l’état de maturité de l’ensemble du langage.
Deux populations de lecteurs consultent cette page. Les auteurs débutants vérifient la page avant de rédiger sur une surface qu’ils ne connaissent pas, pour confirmer que la surface produit aujourd’hui une sortie rendue. Les lecteurs en quête de référence vérifient la page lorsqu’une surface qu’ils utilisent se comporte de manière inattendue — par exemple, lorsque le YAML passe la validation mais qu’aucune sortie n’est produite, la page est le premier endroit où chercher l’état de la surface. Les lecteurs qui reviennent consultent aussi la page pour repérer les surfaces qui ont changé d’étiquette d’état depuis leur dernière lecture. Les chapitres par domaine et les références d’entités décrivent comment la surface est censée fonctionner ; cette page indique si elle fonctionne déjà.
Taxonomie des états
Chaque surface du langage sur cette page porte l’une des quatre étiquettes d’état suivantes :
-
disponible. Le schéma accepte la surface ; le compilateur la consomme ; le comportement correspond au contrat documenté. Les auteurs qui utilisent une surface
availableobtiennent le contrat documenté. -
acceptée mais inerte. Le schéma accepte la surface — la rédiger passe la validation — mais le compilateur n’en tient pas encore compte. Rédiger une surface
accepted but inertproduit un build syntaxiquement valide sans aucun effet rendu pour cette surface ; le compilateur peut émettre un avertissement nommant la surface inerte (le motif recommandé), ou certaines surfaces actuelles sont ignorées silencieusement sans avertissement. Les entrées par section ci-dessous indiquent le comportement précis. -
acceptée mais bloquée. Le schéma accepte la surface — la rédiger passe la validation — mais le compilateur arrête le build au lieu d’en effectuer le rendu. Rédiger sur une surface
accepted but blockedéchoue au rendu avec une erreur explicite indiquant quoi écrire à la place. Un blocage peut être permanent, lorsque ce qui a été rédigé est une ambiguïté que le compilateur ne résoudra pas à votre place, parce que choisir une lecture pour vous pourrait livrer quelque chose que vous n’avez pas demandé ; ou il peut ne durer que jusqu’à la livraison du comportement derrière la surface. Ce que promet l’étiquette est identique dans les deux cas : le schéma l’accepte, le build la refuse, et l’erreur vous indique comment corriger. -
prévue. La surface est documentée telle qu’elle est conçue, mais ni le schéma ni le compilateur ne l’acceptent encore. Rédiger sur une surface
plannedéchoue à la validation du schéma. La page présente les éléments prévus afin que les auteurs puissent s’organiser en tenant compte de leur absence plutôt que de découvrir le manque au moment du build.
Les étiquettes d’état sont évaluées par rapport au compilateur actuel. Les surfaces en cours de développement actif peuvent passer d’une étiquette à l’autre ; les entrées par section décrivent le plan de transition lorsqu’il est connu.
Types d’entrée de Recipe
Une Recipe compose sa sortie à partir de trois types d’entrée — sourcé, synthétisé et artefacts — décrits dans 16-recipe-input-composition.md. État par type d’entrée :
-
source:+valuesMapping:(sourcé) — disponible. Le compilateur résout l’URIsource:, évalue le templatevaluesMapping(en ligne,$import:de fichier ou$import:de bibliothèque) et transmet le résultat au provider cible pour le rendu. Consommé par les providers helm, helm-chart, compose, terraform et cloudformation. -
workload:(synthétisé) — disponible. La Recipe déclareworkload:soit en ligne (scalaire de bloc contenant le YAML du Workload), soit via$import:(chemin de fichier). Le compilateur analyse le Workload templatisé, le valide par rapport au schéma Workload intégré, et le transmet au synthétiseur de workload du provider cible. Consommé par les providers helm et compose. Le provider helm-chart redirige explicitement les auteurs vers le provider helm pour les manifests K8s synthétisés. Une Recipe déclarantworkload:pour un provider qui n’implémente pas la synthèse de workload s’arrête au rendu avec uneCATALOG_ERROR. -
artifacts:(artefacts) — disponible. Le champ est une map d’entrées nommées ; chaque entrée est rédigée en ligne ou chargée via un$import:propre à l’entrée. Les entrées sont évaluées après l’analyse du Workload et la résolution de la source, de sorte que le contexte de template complet — y compris.workloadet.source— leur est disponible ; elles reçoivent une provenance fusionnée dansmetadata.labelsetmetadata.annotationspour les documents qui portent des métadonnées (les clés non sûres pour le jeu de caractères — recipe-uri, boundary-path, sync-wave — en annotations, la même répartition que celle appliquée par les providers helm), et sont émises comme fichiers séparés à côté de la sortie de la Recipe rendue depuis la source ou synthétisée depuis le workload. Dispatch Provider — le provider helm plat émet des fichiers autonomes dans un répertoire nommé d’après le composant qui les a déclarés, à l’intérieur du répertoire de sortie du boundary, car la clé nomme le fichier et ne dit rien du composant qui l’a écrit ; le provider compose achemine ses émissions via le fusionneur de fin de Release ; le provider helm-chart évalue chaque entrée avec les délimiteurs Aggrega[[ ]]afin que la syntaxe{{ }}de Helm dans le même fichier survive jusqu’au rendu en aval, puis place chaque entrée selon sa forme rédigée — une entrée chargée par$import:dansboundaries/<bp>/charts/<nodeID>/templates/<authored-key>(les fichiers d’un bundle imbriqués sous cette clé), à côté des templates propres au chart sourcé, et une entrée à contenu en ligne dansboundaries/<bp>/charts/<nodeID>/<authored-key>, la racine du chart, où les templates propres du chart la lisent via.Files.Get/.Files.Glob; le provider terraform écrit chaque entrée telle quelle dans le répertoire propre du composant sous l’arborescencemodules/du boundary ; le provider cloudformation fusionne chaque entrée, un fragment de stack, dans l’unique stack assemblé pour ce répertoire de sortie. Les collisions de noms de fichiers entre origines de types d’entrée (sortie rendue depuis la source, synthétisée depuis le workload ou émise comme artefact) sont détectées au moment du rendu par le détecteur de collisions inter-origines et produisent une CATALOG_ERROR nommant chaque contributeur.
Voir entities/recipe.md pour la surface de rédaction de la Recipe et les règles de composition des types d’entrée ; errors/fatal-halts.md pour les règles de forme de la Recipe ; et la section Providers ci-dessous pour la matrice par provider.
Langages de mapping
Les Recipes (et les FeatureRecipes) se lient à un seul champ de mapping pour traduire le contexte Aggrega en dictionnaire de valeurs que consomme le provider sous-jacent. Le champ valuesMapping: prend en charge trois modes de rédaction, choisis selon la forme du contenu :
valuesMapping:— Modes 1 à 3 disponibles. Mode 1 : template Go en ligne (scalaire de bloc). Mode 2 :$import:de fichier (une map ne contenant que$import:avec un chemin de fichier local). Mode 3 :$import:de bibliothèque (une map ne contenant que$import:avec une référence d’identité par nom simple vers une entrée de MappingLibrary,<Library>#/mappings/<entry>, éventuellement avec un plancher:<version>). Le compilateur choisit selon la forme du contenu — scalaire de bloc pour le Mode 1,$import:avec un chemin de fichier pour le Mode 2,$import:avec une référence de bibliothèque par nom simple pour le Mode 3. Les trois évaluent le template Go résolu par rapport au contexte de template de la Recipe pendant le mapping des valeurs (la bibliothèque d’assistants Sprig est préenregistrée) ; le Mode 3 résout l’entrée par rapport au catalogue local et aux éventuelles bibliothèques épinglées dans le fichier de verrouillage, et une référence comportant un hôte est rejetée. Voirentities/recipe.md« Le champvaluesMapping— trois modes de rédaction » pour le mécanisme de dispatch et des exemples détaillés.
Voir entities/recipe.md pour la surface de rédaction de la Recipe et la conception du langage de mapping, et entities/mappinglibrary.md pour l’entité de bibliothèque sur laquelle repose le Mode 3.
Syntaxe d’inject
Le bloc inject: a une seule syntaxe quel que soit son emplacement — l’inject propre à un composant, celui d’une connexion uses et celui d’un attachement.
-
Une liste d’entrées par mécanisme (
[{in: ..., from: ...}],[{in: ..., value: ...}]) — disponible. Chaque mécanisme de livraison est une liste ; chaque entrée nomme son identifiant local (nom de variable d’environnement, chemin de fichier, flag d’argument) avecin:et porte exactement l’un defrom:(référence à une clé de provides) ouvalue:(chaîne littérale). Un mécanisme écrit comme une map plutôt que comme une liste, ou une entrée portant les deux mots-clés, arrête le build à l’enveloppe du document de l’Aggregate, en nommant le chemin. -
value:uniquement dans l’injectpropre à un composant. Un littéral a sa place dans l’injectpropre au composant, qui le délivre. Sur une connexionuses, unvalue:arrête le build, comme le décrit Aninject:entry on a connection carries a literal (Une entrée sur une connexion porte un littéral), et dans l’injectpropre à un attachement, il arrête aussi le build, comme le décrit Aninject:entry on an attached Feature carries a literal (Une entrée sur une Feature attachée porte un littéral) : tous deux ne délivrent que des clés qu’une autre entité publie, nommées avecfrom:.
Voir vocabulary/topology-triad.md pour la spécification complète de l’Injection Contract, y compris la sémantique du contexte à double état, les règles de collision de clés et des exemples détaillés.
Moteur de templates
Le moteur de templates Go d’Aggrega évalue les templates de Recipe et de FeatureRecipe par rapport au contexte de template à la phase par site que documente la Matrice d’expansion des templates. La bibliothèque d’assistants Sprig est préenregistrée aux côtés des assistants propres d’Aggrega sur chaque surface qu’évalue le moteur de rendu, à une exception près : la résolution d’une coordonnée source: structurée n’enregistre que les assistants d’Aggrega — optional et capitalizedWords y sont disponibles et les fonctions de Sprig ne le sont pas, de sorte qu’un appel Sprig dans un champ source:, ou dans une entrée locals: d’une entité qui porte un source: structuré, s’arrête à l’analyse. Voir errors/fatal-halts.md, qui consacre à cette surface sa propre section. L’évaluation, l’analyse et l’intégration de Sprig sont disponibles aujourd’hui.
Comportement en cas de clé manquante — toléré dans les templates de valeur ; missingkey=error strict dans les templates de chemin, dans les assertions et dans une coordonnée source:. Les templates de valeur sont évalués avec l’option missingkey=zero de Go, de sorte qu’un template qui référence une clé non liée (par ex. .values.unset_field) ne lève pas d’erreur et que la lecture ne rend rien. Les idiomes de catalogue comme {{ .values.optional_field | default "fallback" }} continuent de fonctionner avec cette politique, car une valeur non définie compte comme vide pour default. Les templates de chemin (directory: / subDirectory: sur les boundaries de Release) sont évalués avec missingkey=error par rapport à une liste d’autorisation fermée — les échecs silencieux de chemin produisent des arborescences de système de fichiers cassées que les opérateurs ne découvrent qu’après le build, et la rigueur détecte l’erreur plus tôt. Deux autres surfaces suivent la même politique stricte, pour la même raison : un rendu vide y produirait un verdict erroné ou un pin erroné plutôt qu’un champ que l’auteur peut relire. Il s’agit d’une entrée assertions: sur un Component, une Feature, une Recipe ou une FeatureRecipe, et des champs templatisés d’un bloc source: structuré sur une Recipe ou une FeatureRecipe. errors/fatal-halts.md détaille la politique de chaque surface une par une et donne les formes sensibles à la présence qui fonctionnent avec la politique stricte.
Repli sensible à la présence via optional. Lorsqu’un auteur de Recipe doit distinguer « clé absente » de « clé présente avec une valeur zéro / vide / false » — la distinction que le default de Sprig ne peut pas faire — le moteur de rendu expose l’assistant optional : {{ optional .infra "replicas" 1 }} renvoie le infra.replicas rédigé (y compris un 0 rédigé) lorsqu’il est présent, et ne se rabat sur 1 que lorsque la clé est absente. Voir templates/sprig-functions.md pour la sémantique complète.
Repliement de noms via capitalizedWords. Lorsqu’une cible n’accepte que des lettres et des chiffres dans les noms par lesquels elle adresse les ressources, {{ capitalizedWords .context.instance_id }} lit l’id comme des mots séparés par tout caractère hors de cet alphabet et met en majuscule la première lettre de chaque mot, de sorte que payments-db donne PaymentsDb. Le repliement supprime tous les séparateurs, si bien que deux id qui ne diffèrent que par la ponctuation aboutissent au même nom ; un build qui émettrait deux ressources sous un même nom s’arrête et nomme les deux id. Voir templates/sprig-functions.md pour la sémantique complète.
Application du contrat de paramètres au niveau de la déclaration. Les paramètres requis que la Release ne fournit pas produisent des erreurs explicites au niveau du contrat de paramètres, la première chose que vérifie la résolution, avec une provenance file:line nommant le paramètre et le contrat. Les violations de type / de contrainte apparaissent de la même façon. C’est là l’application substantielle des clés manquantes : le typage est vérifié là où réside l’intention du développeur (la déclaration parameters: de l’Aggregate), et non au moment de l’évaluation des templates en aval. Voir entities/aggregate.md § « Contrats de paramètres typés ».
Une seule grammaire de déclaration pour les parameters: de l’Aggregate. Chaque emplacement de paramètre est rédigé comme un objet de contrat typé (key: { type: <type>, default: <value>, ... }). La forme abrégée à scalaire simple (key: <value>) est rejetée à l’enveloppe du document de l’Aggregate, avec une erreur qui nomme le paramètre et indique qu’un objet était attendu. Le vocabulaire du contrat typé rend explicites la sémantique de type:, de required: et des contraintes au niveau de la déclaration ; le renseignement par la Release continue d’utiliser des valeurs scalaires selon le type déclaré par le contrat.
Voir templates/expansion-matrix.md pour la matrice d’évaluation par site de template et 05-templates.md pour la vue d’ensemble des templates.
Phases du pipeline de compilation
Le pipeline de compilation d’Aggrega est documenté dans ../architecture/10-compilation-pipeline.md. État par phase :
- Résolution, construction de la topologie, finalisation du graphe, analyse statique et rendu — disponibles.
- Inject mapping (interception avant rendu
injectMapping) et chaque sous-étape du rendu de base — publication des locals, mapping des valeurs, synthèse du workload, évaluation des artefacts, rendu du provider, rendu des features et génération de ressources par les FeatureRecipes d’identifiants — disponibles. - Le pipeline de plugins (exécution Wasm de
pipeline:) — disponible. Pour une Recipe ou une FeatureRecipe qui déclare des étapespipeline:non vides, chaque étape est exécutée dans l’ordre déclaré : le compilateur invoque le plugin Wasm nommé par l’étape sur la sortie rendue, applique les opérations JSON Patch renvoyées aux documents ciblés et émet les effets de bord de l’étape. Une étape dont la conditionwhen:est rendue comme fausse est ignorée et laisse passer l’ensemble de documents sans le modifier. Les auteurs qui visent des mutations de type JSONPatch (injection de sidecar Envoy, VolumeMount de secret, etc.) les obtiennent par cette surface.
Providers
La bibliothèque standard d’Aggrega fournit cinq providers de rendu — helm, helm-chart, compose, terraform et cloudformation. État par provider :
helm— disponible. Le mode sourcé (rendu de charts Helm via le SDK Helm) et le mode synthétisé (Workload → un objet contrôleur choisi selon laformdu Workload — Deployment, StatefulSet, DaemonSet, Job ou CronJob — plus des Services et des PVC) sont tous deux livrés.helm-chart— disponible. Le mode sourcé (composition par umbrella chart) est livré. Le type d’entrée synthétisé ne s’applique pas à ce provider ; les auteurs qui ont besoin de synthèse de manifests K8s utilisent le providerhelmavecworkload:.compose— disponible. Le mode sourcé (superposition de fragments compose) et le mode synthétisé (Workload → service compose + volumes + réseaux) sont tous deux livrés. La sortiedocker-compose.yamlpar boundary est assemblée par le compositeur au niveau de la Release.terraform— disponible. Le mode sourcé et les artefacts sont tous deux livrés ; chaque boundary reçoit une configuration racine,aggrega.modules.tf, qui déclare chaque composant comme un blocmoduledont les fichiers se trouvent dans son propre répertoire sousmodules/. Le type d’entrée synthétisé ne s’applique pas à ce provider.cloudformation— disponible. Le mode sourcé et les artefacts (fragments de stack) sont tous deux livrés ; tous les composants dont le rendu aboutit dans un même répertoire de sortie sont assemblés en un seul template de stack, émis en JSON pur. Le type d’entrée synthétisé ne s’applique pas à ce provider.
Le rendu Provider est assuré par un Plugin avec pluginType: provider ; voir entities/plugin.md pour la surface de rédaction du Plugin de rendu de provider et 06-providers.md pour les pages de référence par provider.
Expansion pilotée par les annotations
Les Manifests portent une section de liaison features.annotations: qui associe des clés d’annotation à des types de Feature, ainsi qu’une table de routage groupée par pilier (maps.infra / maps.values) indiquant quelles propriétés du schéma de la Feature chaque liaison peut renseigner. Documenté dans entities/manifest.md et providers/well-known-annotations.md ; place dans le pipeline dans ../architecture/10-compilation-pipeline.md ; mécanique au chargement du catalogue et à l’inspection dans ../architecture/13-catalog-and-registry.md § « Expansion de Feature pilotée par les annotations ».
- Liaisons
features.annotationsdu Manifest — disponibles. La sous-étape d’expansion des annotations de la résolution est livrée de bout en bout. Elle parcourt les boundaries 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), calcule l’ensemble effectif d’annotations par composant par cascade + surcharge avec désactivation par null sur la valeur entière et par sous-clé, analyse chaque valeur d’annotation comme un scalaire, une map structurée ou unnullexplicite, achemine par sous-clé à travers la déclarationmapsde la liaison en appliquant la contrainte côté-contre-pilier (le côté Aggregate déclenchemaps.values; le côté Release déclenchemaps.infra), valide les types de chaque feuille par rapport auspec.schemade la Feature cible, et injecte des attachements de Feature synthétiques, que le graphe IR marque avecorigin: annotation. La composition entre les deux côtés fusionne par pilier et par champ au moment de la construction de l’IR, la valeur explicite l’emportant champ par champ ;aggrega inspectaffiche la provenance entre crochets pour chaque feuille. La validation des cibles de liaison au chargement du catalogue, le lint de chevauchement des piliers du schéma et le lint de chevauchement des maps de liaison encadrent le parcours. Le préfixe nuaggrega.ai/est rejeté au chargement du Manifest lorsqu’il est utilisé comme clé de liaison — ce préfixe est réservé aux annotations natives de la plateforme ; les liaisons utilisentfeature.aggrega.ai/ou un domaine personnalisé.
Correspondance des versions
Les Recipes et les FeatureRecipes déclarent l’interface de Component ou de Feature qu’elles implémentent via le mot-clé implements:. implements: ne sélectionne jamais une Recipe : c’est le mapping du Manifest qui le fait, et une instance dont aucun mapping ne couvre le type s’arrête avec une erreur qui liste comme candidates les Recipes dont le implements: peut implémenter ce type. Ce que pilote implements:, c’est la vérification que la Recipe de chaque entrée de mapping du Manifest implémente le type mappé, ou une base que ce type étend par extends. Le type mappé est la clé de l’entrée et, pour une clé components.type, aussi le type de chaque instance de composant que la clé atteint à une version que la clé ne nomme pas — chaque instance qu’elle atteint, pour une clé écrite sans version — à la version sous laquelle le build compile cette instance : la version que nomme l’instance ou, pour une instance qui n’en nomme aucune, la version la plus élevée de ce Component que contient le catalogue. État par forme :
- Exacte (
core/api-server:1.0.0) — disponible. Le type mappé doit être exactement cette version. - Plage compatible avec la version majeure (
core/api-server:^1.0.0) — disponible. La forme à caret est une contrainte SemVer (>=1.0.0, <2.0.0dans l’exemple) ; la version du type mappé doit la satisfaire. - Non versionnée (
core/api-server) — disponible. N’importe quelle version du type la satisfait.
Une entrée de mapping dont le implements: de la Recipe ne correspond ni au type mappé ni à aucune de ses bases arrête le build avec une OPS_ERROR qui nomme l’entrée, la Recipe et sa valeur implements:. Une instance de composant qu’une clé atteint à une autre version, et dont la version ne satisfait pas le implements: de la Recipe, arrête le build avec la même OPS_ERROR, en nommant l’instance, son type — et, pour une instance qui ne nomme aucune version, la version sous laquelle elle a été compilée —, la clé, la Recipe et sa valeur implements:. La forme à caret est la surface de rédaction canonique pour la correspondance compatible avec la version majeure.
Voir vocabulary/inheritance-and-interface.md pour la surface de conception de implements: et entities/manifest.md pour la forme du niveau de mapping par Manifest.
Enveloppe de métadonnées
Les enveloppes des entités de catalogue portent metadata.labels, metadata.annotations et (sur la Release) metadata.environment. État par surface :
Disponibilité de metadata.labels et metadata.annotations — sur sept types. Les enveloppes d’entités qui portent ces champs sont Component (labels requis, avec la clé requise component.aggrega.ai/type, annotations facultatives), Feature (les deux facultatifs), les quatre types de bibliothèque SchemaLibrary, MappingLibrary, WorkloadLibrary et ArtifactLibrary (les deux facultatifs), et Aggregate (labels uniquement, facultatifs). Les entités restantes — Recipe, FeatureRecipe, Manifest, Release, Plugin — n’acceptent pas metadata.labels ni metadata.annotations au niveau de l’enveloppe.
metadata.environment sur la Release — requis. Le schéma de la Release liste environment comme champ metadata requis ; le build appose sa valeur sur la sortie rendue sous forme de label aggrega.ai/environment. Voir entities/release.md pour les cinq cas d’usage pratiques de la section Environment Metadata (attribution des coûts OTel/FinOps, filtrage des traces/logs OTel, ciblage des opérateurs Kubernetes, différenciation de la production multirégion, délimitation de la conformité).
Voir 02-naming-conventions.md pour la discipline de casse des champs qui s’applique aux clés metadata, et les pages de référence de chaque entité pour les formes d’enveloppe que chaque entité accepte aujourd’hui.
Commandes de la CLI
La CLI d’Aggrega enregistre le pipeline de build ainsi que l’introspection. État par commande :
aggrega build— disponible. Lit un fichier de Release, résout l’Aggregate + le Manifest, exécute le pipeline de compilation et écrit les artefacts rendus dans les répertoires de sortie des boundaries. Lorsqu’un fichier de verrouillage est présent, elle vérifie les dépendances par rapport à celui-ci ; lorsqu’il est absent, elle s’arrête en demandant un pull, ou le remplit d’abord lorsque--auto-pullouauto_pullle demande.aggrega inspect— disponible. Inspecte une entité de catalogue, un fichier d’entité, une entité publiée dans un registre ou une Release, et en rapporte la forme résolue. Voircli/aggrega-inspect.md.aggrega pull— disponible. Résout toutes les dépendances d’une Release et écrit un fichier de verrouillage par Release qui épingle chaque entité de catalogue et chaque artefact source à une version et à un digest de contenu, et chaque entrée externe demandée par le rendu de la Release à un digest de contenu ; met en cache le contenu récupéré sous.aggrega/cache.--verifyvérifie un fichier de verrouillage existant par rapport à l’état actuel. Voircli/aggrega-pull.md.aggrega push— disponible. Publie une entité de catalogue dans un registre OCI ;aggrega push --list-kindsindique quels types elle accepte. Voircli/aggrega-push.md.aggrega lint— disponible. Exécute les règles de discipline de publication avec la sévéritéwarnsur l’ensemble du catalogue, la fermeture des dépendances d’une Release ou une seule entité ; sur une seule entité,--pre-publishajoute une vérification de l’incrément de version par rapport à la version actuellement publiée de l’entité, et un écart provoque un arrêt. Les règles sont livrées sous forme de plugin Wasm optionnel. Voircli/aggrega-lint.md.aggrega serve— disponible. Un démon compilateur-en-service de longue durée parlant JSON-RPC 2.0 sur stdin/stdout, pour l’intégration avec les éditeurs et les IDE. Voircli/aggrega-serve.mdpour les méthodes qu’il sert.aggrega version— disponible. Affiche la version de la CLI ;-o jsonémet un objet de version lisible par une machine.aggrega validate— disponible. Vérifie la validité sur l’ensemble du catalogue, une Release ou une seule entité, en rapportant des diagnostics sans effectuer le rendu des artefacts.aggrega search— disponible. Recherche des entités publiées dans l’index local des registres configurés ; l’index est construit et actualisé paraggrega registry update.aggrega registry— disponible. Gère les registres et leur politique de confiance des signatures ;registry addenregistre un registre, etregistry updateconstruit l’index local qu’interrogeaggrega search.aggrega push-artifact— disponible. Publie un artefact de données autonome (comme un bundle de documentation) dans un registre OCI, à côté depush, qui publie les entités.aggrega sign— disponible. Signe un ou plusieurs artefacts déjà publiés et y attache leurs signatures.aggrega deprecate— disponible. Attache un marqueur de dépréciation signé à un artefact déjà publié.aggrega loginetaggrega logout— disponibles. S’authentifient auprès d’un registre OCI et stockent l’identifiant, ou suppriment un identifiant stocké.aggrega auth— disponible. Gère l’identité de signature locale utilisée pour signer les artefacts.aggrega config— disponible. Inspecte et gère la configuration du workspace ; les sous-commandes affichent la configuration effective fusionnée et l’origine de chaque paramètre, initialisent une configuration fonctionnelle avec un registre et sa politique de confiance des signatures, et figent dans le workspace la configuration effective critique pour le build afin qu’il se construise à l’identique sans dépendre de la configuration globale de la machine.aggrega get-schema— disponible. Affiche le JSON Schema d’un type d’entité ou de contrat.aggrega plugin— disponible. Inspecte les plugins Wasm que la CLI peut résoudre ; les sous-commandes les listent, ajoutent et suppriment des plugins configurés, synchronisent les enregistrements gérés par la machine d’un plugin et en génèrent une vue de catalogue.aggrega cache— disponible. Inspecte et entretient les caches sur disque ; les sous-commandes rapportent l’état, élaguent, évincent et vident.aggrega mcp— disponible. Exécute un serveur Model Context Protocol sur stdio, ou sur HTTPS pour un client sur une autre machine, exposant l’introspection du compilateur aux intégrations d’assistants d’IA.aggrega completion— disponible. Génère le script d’autocomplétion du shell pour la CLI.- Sous-commandes d’extension de la CLI — disponibles. Un plugin Wasm publié en tant qu’invité
pluginType: cliest résolu et enregistré comme sous-commande deaggrega, de sorte qu’une extension installée s’exécute en tant queaggrega <extension>aux côtés des commandes intégrées. aggrega import— disponible. Transforme une source déclarative externe de définition d’agents (Langflow, Flowise, n8n) en brouillons de fichiers de rédaction d’Aggregate et de Component, avec une décision déterministe de réutilisation du catalogue, notée par un score de confiance, enregistrée pour chaque nœud. Le mapping propre au format est fourni par un plugin importateur que le workspace résout pour le format de la source — un plugin que contient son catalogue, ou l’un des importateurs Langflow, Flowise et n8n du compilateur, qui sont construits et publiés avec chaque release du compilateur. Le binaire porte leurs entités Plugin mais pas leurs modules, de sorte qu’ils servent leurs formats dans chaque workspace : le premier import qui en a besoin d’un que la machine ne possède pas le récupère depuis le registre par défaut du workspace, le vérifie et le conserve dans le cache de contenu pour chaque import ultérieur. Une source est analysée par le parseur que le catalogue du workspace fournit pour sa syntaxe, ou, lorsque le catalogue n’en fournit aucun, par celui qu’embarque le compilateur, de sorte qu’un workspace dont le catalogue ne contient aucun parseur importe par l’un ou l’autre.aggrega scaffold— disponible. Rédige un document de départ pour n’importe quel type d’entité à partir du schéma de ce type — chaque champ qu’il exige, avec un espace réservé là où une valeur est nécessaire — et l’écrit sur la sortie standard ; avec--example, écrit dans un nouveau répertoire l’un des exemples exécutables de la documentation, lu depuis le bundle de documentation signé.aggrega explain— disponible. Explique la condition d’arrêt que nomme un code court (tel queE0007) ou un code descriptif.aggrega edit-document— disponible. Applique une modification structurée et délimitée à un document — ajouter un composant, attacher une Feature, câbler une connexion ou définir une valeur — en préservant chaque octet qu’elle ne touche pas.aggrega pin— disponible. Enregistre, dans l’entity.lockplacé à côté d’une Recipe ou d’une FeatureRecipe, l’épinglage de contenu de chaque entrée que l’entité lit en dehors de son propre document.aggrega skills— disponible. Installe la skill Aggrega dans un assistant IA.
Voir 07-cli.md pour la vue d’ensemble de la CLI et l’index de la référence du langage pour toutes les pages de référence par commande.
Éditeurs et autres frontends
Chaque frontend affiche ce que le binaire aggrega a compilé ; aucun n’embarque son propre compilateur. État par surface :
- Contrat du graphe IR — disponible. Le schéma du graphe IR, le contrat selon lequel chaque frontend lit le graphe, est livré avec la distribution des schémas d’Aggrega ; voir la référence du schéma IR.
- Lire le graphe depuis une commande — disponible.
aggrega buildaccepte--ir-graph, de même queaggrega inspectlorsqu’il reçoit une Release etaggrega validate --release; le flag écrit sur stdout, en JSON, le graphe résolu par cette exécution, en plus de ce que la commande produit déjà. Une session du démon lit le même graphe àaggrega/irGraph, et les outilscli-inspect,cli-buildetcli-validatedu serveur MCP le prennent comme argumentir_graph. - Graphe de topologie dans Visual Studio Code — disponible. L’extension Aggrega pour Visual Studio Code dessine le graphe IR de la Release sélectionnée sous forme de graphe interactif et y rattache des Features, en demandant les deux au démon
aggrega serve. - Mode de streaming headless de la CLI — prévu. Le mode headless émet le graphe IR en JSON délimité par des retours à la ligne sur stdout, pour qu’un frontend le consomme à mesure que la topologie change. Ce qui est livré aujourd’hui est un document par invocation plutôt qu’un flux : aucune commande n’émet une séquence de graphes sur un même stdout à mesure qu’une topologie change.
Voir ../architecture/15-editors-assistants-and-frontends.md pour la façon dont l’éditeur, l’assistant et le démon atteignent le compilateur.
Orientations de conception
La taxonomie des états ci-dessus classe l’état par surface dans tout le langage ; cette section consigne l’état d’orientations de conception plus larges documentées dans les chapitres d’architecture.
La conformité à l’échelle de tout le parc n’est pas une orientation prévue : énoncer une règle de gouvernance une seule fois de sorte qu’elle s’impose à chaque build du workspace est disponible aujourd’hui via le socket de gouvernance. Un plugin attaché à la clé plugins.governance de la configuration du workspace évalue chaque build de ce workspace — un rôle de verdict qui rejette un graphe ou un artefact rendu qui enfreint la règle, un rôle de transformation qui fournit des métadonnées dérivées qu’un développeur ne saisit jamais. Voir ../architecture/11-governance-and-compliance.md.
- Interface Parity & Auto-Implementation — disponible. Une Recipe écrite pour un Component de base sert chaque Component qui l’étend, à n’importe quelle profondeur de la chaîne, sans que l’Architect ait à rédiger une Recipe en double. Le Component qui étend écrit
schema: inherited; il n’ajoute donc àvalues/infra/providesaucune clé racine que la Recipe de la base ne pourrait pas consommer ; un Component qui déclareextendsavec un schéma propre est refusé à l’enveloppe de son document. Le Manifest mappe toujours le type qui étend avec une entrée propre, et la vérification du mapping l’accepte lorsque l’implementsde la Recipe mappée nomme ce type ou l’une des bases qu’il étend. Documenté dans../architecture/02-ecosystem-philosophy.md. - Ghost Infrastructure Tracker — disponible. Un garde-fou de la phase de rendu émet un avertissement lorsqu’une clé déclarée par un auteur atteint un nœud et qu’aucun template déclaré par la Recipe liée ne la lit, de sorte qu’une valeur déclarée par l’auteur et silencieusement ignorée par le template est nommée au lieu d’être perdue. C’est la moitié phase de rendu de la même conception de correspondance de formes. Voir
errors/warnings.md.
Les chapitres d’architecture décrivent les surfaces de conception ; cette page suit l’état de l’implémentation.