Catalogue et registre
Ce chapitre définit comment la plateforme passe à l’échelle de l’entreprise grâce au catalogue OCI (Open Container Initiative) : comment le catalogue est organisé, comment une référence se résout, comment une entité est publiée et épinglée, et les formes de noms que suivent les entités du catalogue.
Le catalogue Aggrega : taxonomie et résolution du registre
Le compilateur Aggrega s’appuie sur un registre strictement typé, inspiré d’OAM, pour résoudre l’intention abstraite du développeur (Domaine 1) en une réalité Ops concrète (Domaine 3). Pour prendre en charge un écosystème ouvert et distribué tout en préservant une expérience de développement fluide, l’ensemble des schémas, liaisons d’infrastructure, politiques programmables et plugins adaptateurs suit une taxonomie d’URI standardisée de l’Open Container Initiative (OCI). Comme chaque entité du catalogue est adressable par URI, aggrega pull récupère dans le cache celles dont une Release a besoin et les épingle dans son lockfile, et un build les lit à partir de là. Le workspace local du développeur ne contient que ses fichiers Aggregate et Release, et non une copie du catalogue.
1. Structure des répertoires principale (le catalogue)
Le dossier aggrega-catalog de la bibliothèque standard (et tout catalogue tiers conforme) est organisé de façon à imposer physiquement la séparation des responsabilités. La structure sépare explicitement les interfaces abstraites de leurs implémentations d’infrastructure concrètes.
Pour les Components et les Features, les segments d’URI correspondent 1:1 aux segments de chemin du système de fichiers. Les Components utilisent un URI à trois segments ({publisher}/{category}/{name}) dont le segment de catégorie porte l’une des catégories cognitives d’un ensemble fermé — le même mot que le label component.aggrega.ai/category du composant (le miroir 1:1 du répertoire, vérifié par la règle category-matches-directory du linter de publication). Les Features restent plates ({publisher}/{name}) — un petit ensemble, qui croît lentement. La classification ontologique opérationnelle (stateful-server, server, etc.) réside dans le label component.aggrega.ai/type, jamais dans la structure des répertoires ; les labels de capacité cognitive (datastore.aggrega.ai/engine, agent.aggrega.ai/autonomy, …) y superposent des sous-ensembles comportementaux. L’interface web du hub utilise les labels pour le filtrage et la recherche ; les catégories servent à la fois à la navigation dans le système de fichiers et à l’axe de parcours du catalogue.
L’arborescence ci-dessous est illustrative dans son contenu et exacte dans sa forme. Là où une entité est dessinée en entier, elle descend jusqu’à son fichier feuille, de sorte qu’un chemin réel complet peut être lu sur le diagramme : quel niveau de répertoire porte quel segment d’URI, où se trouve le segment de version obligatoire et quel nom de fichier chaque type d’entité utilise à la feuille. Elle montre une poignée d’entrées par niveau plutôt que le contenu complet du catalogue — ... marque une élision, et les noms écrits à côté sont d’autres entrées de ce même niveau.
aggrega-catalog/│├── schemalibrary/ # TIER 3: Reusable JSON Schema 2020-12 definitions│ │ # Shared shapes (BaseComponentParameter,│ │ # BaseDatastoreParameter) consumed from a Component or│ │ # Feature schema via $ref: <Library>#/schemas/<name>│ │ # Path: {name}/{version}/library.yaml│ ││ ├── ai-datastores/│ │ └── 1.0.0/│ │ └── library.yaml│ └── base-components/│ └── 1.0.0/│ └── library.yaml│├── workloadlibrary/ # TIER 3: Reusable Workload template fragments│ │ # Shared bodies (StatelessService) consumed from a│ │ # Recipe via workload: { $import: <Library>#/workloads/<name> }│ │ # Path: {name}/{version}/library.yaml│ ││ └── base-workloads/│ └── 1.0.0/│ └── library.yaml│├── component/ # DOMAIN 2: Abstract Interfaces│ │ # URI: {publisher}/{category}/{name}│ │ # Path: {publisher}/{category}/{name}/{version}/component.yaml│ │ # type: core/datastore/mariadb:1.0.0│ │ # → component/core/datastore/mariadb/1.0.0/component.yaml│ ││ ├── core/ # "core" = official Aggrega standard library│ │ ├── ai-agent/ # AI agent frameworks, platforms, patterns│ │ │ └── ... # anthropic, crewai, langflow, pydantic-ai, …│ │ ├── ai-model/ # model providers and inference runtimes│ │ │ └── ... # ai21, anthropic, azure-openai, openai, …│ │ ├── ai-tool/ # tools agents invoke│ │ │ └── ... # browser, mcp, search, …│ │ ├── ai-pipeline/ # AI data/processing pipelines│ │ │ └── ... # argo-workflows, temporal│ │ ├── datastore/ # persistent datastores│ │ │ ├── mariadb/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ ├── postgres/│ │ │ │ └── 1.0.0/│ │ │ │ └── component.yaml│ │ │ └── ... # etcd, ferretdb, qdrant, redis, valkey, …│ │ ├── gateway/ # API and AI gateways│ │ │ └── ... # apisix, contour, kong, nginx, …│ │ ├── compute/ # generic compute primitives│ │ │ └── ... # function, keda, server, task, worker, …│ │ ├── messaging/ # event buses, queues│ │ │ └── ... # kafka, nats, rabbitmq, …│ │ ├── observability/ # metrics, logs, traces│ │ │ └── ... # grafana, loki, otel-collector, prometheus, tempo, …│ │ ├── security/ # identity, secrets, certificates│ │ │ └── ... # cert-manager, external-secrets, keycloak, …│ │ ├── devtool/ # developer-facing tooling│ │ │ └── ... # adminer, promptlayer, …│ │ └── storage/ # object/file storage, and the backup controllers│ │ │ # that copy a cluster's resources, or its│ │ │ # volumes' files, into a bucket│ │ ├── s3-object-store/│ │ │ └── 1.0.0/│ │ │ └── component.yaml│ │ └── ... # barman-cloud-plugin, gcs, k8up, velero, …│ └── example/ # a second publisher, same three-segment shape│ └── compute/│ └── greeter/│ └── 1.0.0/│ └── component.yaml│├── feature/ # DOMAIN 2: Abstract Interfaces│ │ # Flat: {publisher}/{name} (no category segment)│ │ # Path: {publisher}/{name}/{version}/feature.yaml│ │ # type: core/data-masking:1.0.0│ │ # → feature/core/data-masking/1.0.0/feature.yaml│ ││ ├── core/│ │ ├── data-masking/│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ ├── secret-value/ # feature.aggrega.ai/kind: secret│ │ │ └── 1.0.0/│ │ │ └── feature.yaml│ │ └── ... # k8s-dns-resolver, public-ingress, retry-policy, …│ └── ... # other publishers, same flat shape│├── aggregate/ # DOMAIN 1: Reusable Aggregate Modules│ │ # Path: {publisher}/{name}/{version}/aggregate.yaml│ └── core/│ ├── keycloak/│ │ └── 1.0.0/│ │ └── aggregate.yaml│ └── ... # agenta, apisix, dify, harbor, kong, thanos, …│├── recipe/ # DOMAIN 3: Concrete Implementations│ │ # Organized by CAPABILITY (the one a Recipe declares│ │ # in spec.capability).│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ │ # The version directory may bundle the Recipe's own│ │ # source charts or modules beside recipe.yaml.│ │ # OCI: hub.aggrega.ai/recipe/helm/mariadb:1.0.0│ ││ ├── helm/│ │ ├── mariadb/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── postgres/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── compose/│ │ └── mariadb/│ │ └── 1.0.0/│ │ └── recipe.yaml│ ├── terraform/│ │ └── mariadb-rds-module/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── module/ # bundled Terraform source│ │ ├── main.tf│ │ └── variables.tf│ └── cloudformation/│ └── postgres-rds/│ └── 1.0.0/│ └── recipe.yaml│├── feature-recipe/ # DOMAIN 3: Concrete Implementations│ │ # Capability leads the path, same as recipes.│ │ # Path: {capability}/{name}/{version}/recipe.yaml│ ││ ├── helm/│ │ ├── k8s-secret-from-parameter/│ │ │ └── 1.0.0/│ │ │ └── recipe.yaml│ │ └── public-ingress/│ │ └── 1.0.0/│ │ ├── recipe.yaml│ │ └── chart/ # bundled Helm source│ │ ├── Chart.yaml│ │ └── templates/│ │ └── ingress.yaml│ ├── compose/│ │ └── dotenv-secret/│ │ └── 1.0.0/│ │ └── recipe.yaml│ └── ... # terraform, cloudformation│└── plugin/ # ARTIFACTS: Plugin entities, each a content-addressed │ # reference to a Wasm artifact. The compiled artifact │ # is published separately and is not stored here. │ # Path: {pluginType}/{name}/{version}/plugin.yaml │ ├── linter/ │ └── publishing/ │ └── 0.5.0/ │ └── plugin.yaml └── provider/ # the directory mirrors metadata.pluginType ├── helm/ │ └── 0.5.0/ │ └── plugin.yaml └── ... # cloudformation, compose, helm-chart, terraformLes catégories de composants forment un ensemble fermé, et c’est cet ensemble — et non le système de fichiers — qui fait autorité pour les catégories. Une valeur de catégorie qui n’a pas encore d’entité est du vocabulaire réservé : l’axe de parcours reste stable et un auteur sait où atterrira un futur composant ; une étagère vide est donc correcte, et non une vacance qui attend son occupant. Comme le catalogue ne contient aucun fichier de remplissage, le répertoire d’une telle valeur est créé lorsque sa première entité arrive.
La liste qui fait autorité — chaque catégorie, ce qu’elle contient, les valeurs opérationnelles de type que portent habituellement ses entités et les répertoires qui existent — est la section Catégories de Component du guide des conventions du catalogue, publié avec le catalogue de la bibliothèque standard qu’il régit.
L’axe type ne porte que les primitives opérationnelles — le vocabulaire cognitif n’y apparaît jamais, et le schéma Component publié énumère les valeurs que prend la clé réservée, de sorte qu’un mot cognitif écrit à cet endroit est refusé au chargement du document. La répartition en trois axes : type opérationnel (la façon dont l’infrastructure traite le composant), category cognitive (ce qu’il est, reflété par le répertoire) et labels de capacité par rôle (sous-ensembles comportementaux — une entité est category: datastore plus la valeur de datastore.aggrega.ai/engine que porte sa propre identité de produit, de sorte que core/datastore/qdrant porte vector et core/datastore/redis porte kv, et les deux axes sont interrogeables). Une capacité dont la véracité dépend de ce qu’un auteur configure n’est pas du tout portée dans le catalogue : elle est injectée à la compilation par le rôle label-transform du socket de gouvernance, qui lit les values déclarées par le développeur. Les catégories purement IA portent le préfixe ai- ; les catégories à double usage apparaissent sans préfixe, leur dimension IA étant exprimée par des labels de capacité. Les catégories sont choisies selon la façon dont les utilisateurs naviguent et parcourent, et non selon la façon dont le compilateur classe — le vocabulaire des catégories et les labels de capacité sont des termes auxquels le compilateur confronte les sélecteurs et auxquels il n’attribue aucun sens. Le nom d’un composant ne répète pas sa catégorie : le modèle OpenAI de la bibliothèque standard est core/ai-model/openai, et non core/ai-model/openai-model.
2. Le schéma scindé et le pipeline de synthèse du bridge
Pour éliminer le code passe-partout propre à chaque Component autour des déclarations de sockets de topologie, Aggrega scinde la validation en deux parties et contrôle chacune là où réside son objet :
usesSchema(YAML déclaratif). Déclare les sockets de topologie qu’une entité du catalogue propose et attribue à chacun un contrat. La CLI Go le lit nativement pour extraire les chaînesselector:servant à la correspondance de labels pendant l’analyse statique et pour valider les mécanismesinjectautorisés. Chaque entrée de socket prend en charge un champ facultatifrequired: true(par défautfalse) — lorsqu’il est défini, le compilateur émet une erreur de validation si aucune dépendance n’est déclarée dans ce socket. C’est la contrepartie, pour les sockets, de la sémantiquerequired: truesur les entrées defeaturesSchema: les deux arrêtent le build. Déclarer un socket ici est ce que fait le catalogue de la bibliothèque standard et reste la meilleure voie — mais ce n’est pas la seule manière dont un développeur peut tracer une arête. L’auteur d’un Aggregate peut nommer sur son propre composant un socket que ceusesSchemane déclare pas, y compris sur une entité qui ne déclare aucunusesSchema; un tel socket ad hoc ne porte ni sélecteur, ni liste d’autorisationinject, ni schéma par arête, précisément parce qu’il n’existe ici aucune entrée pour les porter. Lesusesd’un attachement de Feature et lesusespar arête d’une Release ne sont pas ouverts de cette façon — tous deux ne peuvent nommer qu’un socket déclaré. Consultez dependency-resolution §« Domaine 2 : le schéma scindé » pour le contrat complet et ce à quoi renonce un socket ad hoc.- Désucrage. Si les développeurs utilisent la forme abrégée en tableau YAML (
uses: databases: ["db1"]), la CLI la normalise en une map ({"db1": {"target": "db1"}}). - Synthèse du bridge. Le compilateur projette la table des slots
featuresSchema:en un fragment JSON Schema 2020-12 — une propriété par slot d’attachement, décrivant la forme d’un remplissage susceptible de le lier, avec un mot-clé d’extensionx-aggrega-inject:sur un slot qui déclare une liste d’autorisationinject. La validation JSON Schema ignore les mots-clés d’extension lors de la validation structurelle, et rien n’en relit un depuis le fragment : un contrôle qui a besoin de la liste d’autorisation d’un slot lit le slot lui-même. La table des socketsusesSchema:n’est projetée dans aucun fragment. Leselector:et l’inject:d’un socket restent dans le YAML typé écrit par l’architecte et sont lus à partir de là, et levalueSchema:/infraSchema:par arête d’un socket est encapsulé et compilé à part, sans qu’aucune contrainte ne soit inventée autour. - Composition. L’architecte de plateforme écrit une déclaration
schema:stricte (forme compacte ou JSON Schema 2020-12 complet) définissantvalues,infraetprovides. Cette déclaration est le contrat propre de l’entité et est compilée à part : ni le fragment des slots ni la table des sockets n’y sont intégrés. Chaque surface est vérifiée là où réside son objet, de sorte qu’un défaut de socket est signalé sur l’entrée de socket écrite par l’architecte plutôt qu’à un chemin à l’intérieur du blocschema:— et l’architecte n’écrit toujours aucun code passe-partoutuses.
Exemple — une déclaration de socket et ce que le compilateur en fait : Le YAML de l’architecte de plateforme
spec: usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: ["env", "file", "ssm_param"] # env and file are core mechanisms; ssm_param is a user-provided mechanism
schema: values: ha_mode: { type: boolean, default: false } infra: replicas: { type: integer, min: 1 } provides: host: { type: string, required: true }
assertions: # The Architect can write cross-pillar invariants against the unified instance content. ha-mode-needs-two-databases: | {{- if eq .values.ha_mode true -}} {{- if lt (len .uses.databases) 2 -}} {{- fail "ha_mode=true requires at least two database attachments" -}} {{- end -}} {{- end -}}Ce que le compilateur en fait La table des sockets est lue comme le YAML typé qu’elle est : la chaîne selector: est transmise au moteur natif de correspondance de labels, et la liste inject: restreint les mécanismes de livraison qu’une arête passant par ce socket peut nommer. Le bloc schema: est compilé séparément, comme contrat values / infra / provides propre à l’entité. L’analyseur statique lit la chaîne selector: dans l’entrée de socket écrite par l’architecte — avec appliesTo / appliesToAnyOf issus des entités Feature — et évalue la correspondance de labels par rapport aux metadata.labels de chaque cible afin de valider la sûreté de typage entre nœuds.
Sélecteurs de style Kubernetes dans usesSchema
Le moteur natif de correspondance de labels du compilateur Go évalue les chaînes de sélecteur selon la sémantique de sélection standard de style Kubernetes (AND par la virgule, OR par in(), NOT par !=/notin()). Ce même moteur — et la même grammaire de chaînes de sélecteur — évalue aussi les sélecteurs d’attachement des Feature (appliesTo, et chaque élément de appliesToAnyOf). La couche des sélecteurs est strictement la porte de la topologie — les déclarations schema: par pilier valident le contenu de values, infra et provides de façon indépendante. Une fois que le compilateur Go a tracé les arêtes topologiques lors de la construction de la topologie, l’analyseur statique lit les chaînes selector dans les entrées de socket rédigées par l’architecte et les évalue par rapport aux labels de catalogue du nœud cible afin de valider la sûreté de typage entre nœuds.
usesSchema: # 1. The AND Operator (Comma) databases: selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
# 2. The OR Operator (Set-based 'in') datastores: selector: "datastore.aggrega.ai/engine in (relational, vector)"
# 3. The NOT Operator internal_systems: selector: "compliance.aggrega.ai/data-class!=public"Un sélecteur que le moteur ne peut lire comme l’une de ses six formes d’exigence — une exigence vide, une clé contenant un espace ou l’un des caractères =, !, (, ) et la virgule, un ensemble non fermé — arrête le build sur chaque arête qu’il protège au lieu d’être lu comme un autre sélecteur. La grammaire des sélecteurs liste les formes et chaque refus.
3. Formats et composition des schémas
Pour fournir à la fois une validation stricte et les métadonnées standard du catalogue (auteur, version, description), les définitions du Domaine 2 (Interfaces) et du Domaine 3 (Implémentations) sont écrites sous forme d’enveloppes YAML. Le Domaine 2 utilise des déclarations schema: intégrées, exprimées en forme compacte (par défaut ; ~15 mots-clés, transformés mécaniquement en JSON Schema 2020-12) ou en YAML JSON Schema complet.
Pourquoi chaque YAML du catalogue répète l’enveloppe. L’enveloppe (bloc apiVersion, kind, metadata) figure en tête de chaque fichier du catalogue — Component, Feature, Recipe, FeatureRecipe, Aggregate, Manifest, Release, Plugin — quelle que soit la brièveté du corps. La répétition est délibérée : chaque fichier est conçu pour être analysé, validé, passé au linter et inspecté comme un artefact autonome. Un fichier isolé récupéré depuis le registre OCI, déposé dans un bac à sable de CI ou ouvert dans un éditeur tiers doit porter assez d’autodescription pour que l’outillage en aval puisse identifier quel type d’entité il représente et quelle version de schéma s’applique. L’emplacement du répertoire ne remplace jamais l’enveloppe : chaque analyseur, validateur et linter lit le type de l’entité et la version de schéma dans l’enveloppe. Le coût est un code passe-partout mécanique par fichier ; le bénéfice est que la garantie d’un outillage autonome vaut sur la surface de distribution OCI, le système de fichiers local et les surfaces IDE / CI / inspect. Les auteurs copient l’enveloppe depuis des fichiers existants lorsqu’ils rédigent un nouveau contenu de catalogue, ou partent de aggrega scaffold <kind>, qui affiche un document de départ pour le type avec ses apiVersion et kind déjà renseignés.
Pour respecter le principe DRY (Don’t Repeat Yourself, « ne vous répétez pas »), le catalogue emploie deux mécanismes de composition distincts :
- Entrées SchemaLibrary partagées (
$ref:inter-documents) : Les définitions JSON Schema réutilisables sont stockées dans des entités de catalogue SchemaLibrary (Tier 3). Elles sont référencées par identité via un$ref:inter-documents (<library>#/schemas/<entry>, sans hôte — la version provient du lockfile) depuis tout schéma de Component ou de Feature consommateur. La chaîne est parcourue à la compilation. Consultez entities/schemalibrary pour la forme de rédaction de l’entité bibliothèque et vocabulary/cross-document-ref pour la sémantique de résolution. - Héritage simple (
extends) : Pour des bases de composants complètes, les entités peuvent utiliser la propriétéextends: "URI". Le compilateur Go lit récursivement la chaîne des parents et fusionne en profondeur les métadonnées YAML (en écrasant les labels en cas de conflit et en ajoutant les tableaux à la suite). Les deux types de catalogue se séparent ensuite sur les piliers de données. Leschema:d’une Feature se compose avec celui de sa base selon la composition JSON Schema 2020-12. Un Component qui étend n’écrit aucun contenu de pilier : il écrit le marqueur littéralschema: inheritedet reçoit le blocschema:de sa base exactement tel que la base l’a écrit, à toute profondeur d’une chaîne. Ce qu’un tel Component compose à la place, c’est la structure — ses slots d’attachement (featuresSchema), ses sockets de topologie (usesSchema), sa liste d’autorisation d’auto-injection (inject) et sesassertionsnommées fusionnent tous le long de la chaîne. Consultez entities/component pour les exemples d’extension de composants de base et enfants + governance-and-compliance §« Héritage et discipline de publication » pour ce que l’héritage règle par construction et ce qui reste une règle de discipline de publication.
Consultez entities/component pour les exemples d’extension de composants de base et enfants, et entities/recipe pour la rédaction de Recipe à pointeurs et mappeurs, avec des exemples complets.
4. La configuration de l’espace de travail (.aggrega-config.yaml)
Le fichier .aggrega-config.yaml à la racine de l’espace de travail est la configuration d’espace de travail du projet — la déclaration propre de l’espace de travail, adaptée au contrôle de version comme l’est go.mod ou package.json. Par convention, le répertoire .aggrega/ est tenu hors du contrôle de version — listez-le dans .gitignore, comme vous le feriez pour node_modules/ ou .terraform/.
La section workspace est le marqueur de racine : sa présence marque la racine de l’espace de travail, et elle ne porte que les répertoires de catalogue qui définissent la racine — catalog_dirs, et la map releases qui donne à une Release ses propres répertoires de catalogue. Tout autre paramètre se trouve au niveau supérieur. Beaucoup sont des valeurs uniques ; d’autres sont des sections regroupant sous une seule clé les paramètres d’une même préoccupation. Chaque champ est facultatif, avec des valeurs par défaut documentées. L’ensemble complet et à jour des clés de premier niveau, chacune avec son type, sa valeur par défaut et sa signification, est généré à partir du schéma dans schema/other/aggrega-config ; l’exemple ci-dessous montre le marqueur de racine aux côtés de quelques paramètres à valeur unique :
workspace: # Root marker; presence marks the workspace root catalog_dirs: # Ordered list of local catalog directories (checked before cache) - ./aggrega-catalogdefault_registry: hub.aggrega.ai # Default registry for unqualified URIsoffline: false # Set true for air-gapped environmentsauto_pull: true # Opt in to the implicit pull; the default is false, keeping build read-onlyartifact_cache_dir: .aggrega/cache # On-disk artifact cache rootUn bloc signing: porte les valeurs par défaut de signature des artefacts utilisées par aggrega push --sign et aggrega sign, à la fois au niveau supérieur (global) et par registre :
signing: # Global signing defaults fulcio_url: https://fulcio.sigstore.dev # Keyless certificate authority (defaults to public-good) rekor_url: https://rekor.sigstore.dev # Keyless transparency log (defaults to public-good) timestamp_url: https://tsa.example.com/api/v1/timestamp # Optional RFC3161 timestamp authority (no default; opt-in) key_path: ./keys/signing.pem # Optional: path to a held keyed-key PEM (a pointer, never inline material)registries: - host: hub.example.com signing: # Per-registry override of the global signing block key_path: ./keys/hub.pemLa priorité par champ est : flag de la CLI > signing par registre > signing global > valeur par défaut d’intérêt public. Fulcio et Rekor utilisent par défaut les instances d’intérêt public de Sigstore ; ils sont donc facultatifs ; timestamp_url n’a pas de valeur par défaut — l’horodatage de confiance sans clé provient de l’inclusion dans le journal de transparence de Rekor, et une autorité d’horodatage RFC3161 est optionnelle (définissez timestamp_url, ou --timestamp-url, avec un point de terminaison complet pour en activer une). Sécurité : le bloc signing: ne contient aucun élément secret — le jeton d’identité OIDC n’est jamais un champ de configuration (c’est un secret de courte durée, fourni au moment de la signature : obtenu par un flux dans le navigateur sur un terminal interactif ou depuis le workflow sur GitHub Actions, et sinon passé avec --identity-token ou exporté sous la forme AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN), et la clé privée n’est jamais en ligne ; key_path est le chemin d’un fichier de clé. C’est l’asymétrie délibérée avec le côté vérification, qui épingle une clé publique en ligne, alors que le côté signature n’accepte jamais qu’un chemin de clé.
Marquez une racine sans catalogue vendorisé en écrivant workspace: {}. La liste catalog_dirs prend en charge les configurations monorepo où un catalogue partagé se trouve dans un répertoire voisin. Le compilateur vérifie chaque répertoire dans l’ordre. Le flag offline: true empêche tout accès au réseau — le compilateur n’utilise que les chemins locaux et le cache, et s’arrête si une entité est introuvable localement. Les paramètres en sections regroupent chacun une préoccupation. Parmi eux : les curseurs de rigueur au moment du build et les indications de rédaction ; les sockets d’attachement Wasm au niveau de l’espace de travail (governance, linter, importer, providers, cli), qui prennent chacun une liste de références de plugins ; la rigueur du lint par règle, y compris les commutateurs de politique de discipline de publication ; le réglage du cache d’analyse du démon et la taille de son pool de workers de répartition des requêtes ; et le plafond de taille du magasin de modules compilés partagé par toute la machine. D’autres encore portent les valeurs par défaut de signature et de confiance dans les signatures ainsi que le comportement propre du démon. Chaque clé de premier niveau est documentée intégralement dans schema/other/aggrega-config.
Trois caches distincts sont configurables, et il vaut la peine de prendre un moment pour les distinguer, car leurs noms se ressemblent alors que leurs portées diffèrent. artifact_cache_dir désigne le cache de contenu sur disque par espace de travail décrit ci-dessous. parse_cache plafonne le cache d’analyse en mémoire du démon, qui ne vit qu’aussi longtemps que le démon. compiled_module_cache plafonne le magasin sur disque du code machine des plugins compilés — l’un des caches partagés par tous les espaces de travail de la machine, car la forme compilée d’un plugin dépend du plugin et non du projet qui l’utilise :
# .aggrega-config.yaml — most at home in the global config file, since the store is machine-widecompiled_module_cache: max_bytes: 53687091200 # Default 50 GiB; 0 disables the capParmi les caches que partagent tous les projets de la machine, c’est celui qui peut finir par dominer l’usage du cache sur disque, puisque chaque plugin exécuté par la machine y est compilé une fois et conservé ; c’est donc le seul doté d’un plafond de taille permanent. Chaque invocation qui ouvre le magasin applique le plafond avant de compiler quoi que ce soit, en supprimant des entrées entières, les plus anciennement compilées d’abord, jusqu’à ce que le reste tienne. (Un build exécuté avec --disable-plugin-cache compile plutôt en mémoire ; il ne fait donc ni grossir ni réduire le magasin.) Supprimer une entrée coûte une recompilation ultérieure et rien d’autre, ce qui permet d’abaisser le plafond et de l’appliquer sans risque pendant que d’autres builds s’exécutent sur la même machine. Fixez-le au-dessus de ce que compile un seul build : comme le plafond est appliqué avant la compilation, un plafond inférieur à l’ensemble de travail d’un seul build oblige chaque build à jeter et recompiler les mêmes modules, et pour la même raison le magasin peut dépasser le plafond entre deux builds et être de nouveau réduit au début du suivant. aggrega cache status indique la taille du magasin, et aggrega cache evict --max-size le réduit à la demande à un plafond donné sur la ligne de commande.
La racine artifact_cache_dir porte trois sous-arborescences parallèles qu’une seule invocation de aggrega pull remplit de manière uniforme, une par classe de dépendance épinglée : <artifact_cache_dir>/entities/<encoded-kind>/<encoded-reference>/<encoded-version>/ pour les entités de catalogue (Components, Features, Recipes, FeatureRecipes, Aggregates, les bibliothèques, et les Plugins avec les exécutables qu’ils publient), où le type est celui sous lequel l’entité est publiée, de sorte que deux entités de types différents qui partagent une référence et une version — un Component et une Recipe de même nom — occupent deux slots ; <artifact_cache_dir>/source-artifacts/<kind>/<host>/<path>/<version>/<digest-prefix>/ pour les artefacts source récupérés depuis les champs spec.source des Recipe / FeatureRecipe (charts Helm, fragments compose) ; et <artifact_cache_dir>/inputs/sha256/<hex-digest> pour les entrées externes — les documents distants qu’un provider demande à l’hôte pendant son rendu, comme un $ref dans le values.schema.json d’un chart qui pointe vers une URL. Chaque slot de cache d’artefact source porte l’archive .tgz faisant autorité, un répertoire dérivé extracted/ régénéré à chaque lecture par un build, et un fichier metadata.yaml qui enregistre l’identité {kind, url, version, digest, mediatype, pulled_at} de l’artefact. Chaque slot de cache d’entité porte l’artefact publié tel qu’il a été récupéré et le manifeste OCI par rapport auquel il est vérifié. Le slot de chaque type dont le document peut nommer un fichier à côté de lui — une Recipe, une FeatureRecipe, un Component, une Feature — porte aussi un répertoire dérivé extracted/ contenant les fichiers que cet artefact transporte, dans un répertoire nommé d’après le digest de contenu de l’artefact : le document et les fichiers que l’entité a déclarés, lorsqu’elle a été publiée sous forme d’archive, et le document seul, lorsqu’elle a été publiée sous forme de document (§6). Le répertoire de l’entité y est disposé à partir de l’artefact vérifié à chaque lecture, de la même manière que les fichiers d’un artefact source : chaque fichier est vérifié par rapport à l’artefact, un fichier modifié ou ajouté à la main dans ce répertoire est écarté au lieu d’être lu, rien d’autre sous extracted/ n’est lu, et un artefact qui échoue à la vérification est refusé avant que quoi que ce soit ne soit disposé. Une lecture ne réécrit que ce qui diffère de l’artefact, de sorte que des builds lisant un même cache en même temps — des requêtes que aggrega serve traite côte à côte, ou deux commandes sur un même espace de travail — trouvent chacun intacts les fichiers qui leur ont été remis. Le segment <digest-prefix> de 12 caractères répartit dans des slots distincts un même {kind, url, version} re-étiqueté à des digests amont différents. Une entrée externe n’a pas besoin d’un tel slot : elle est stockée comme un fichier unique nommé d’après le digest de contenu auquel le lockfile l’épingle, de sorte que ce qu’un build ultérieur lit est adressé par l’épinglage plutôt que par l’URL d’où sont arrivés les octets — c’est ce qui permet à ce build de servir l’entrée avec le réseau refusé.
Trois autres répertoires peuvent apparaître à côté de ces trois-là, et aucun ne contient de contenu de dépendance épinglée : index/ porte les instantanés interrogeables par registre qu’écrit aggrega registry update (§8), signatures/ met en cache chaque bundle de signature vérifié sous son propre digest, de sorte qu’une lecture ultérieure revérifie le blob en cache par rapport au digest sous lequel il a été enregistré au lieu de récupérer à nouveau le bundle, et catalog-snapshots/ conserve chaque instantané publié du catalogue qu’un import a lu (§8) — l’archive et son manifeste dans un emplacement nommé d’après le digest du manifeste, l’arborescence du catalogue étant disposée à partir de l’archive à chaque lecture, ainsi qu’un fichier current qui nomme l’instantané que lit le workspace lorsque rien n’en nomme un autre.
Le bundle de documentation n’en fait pas partie. Ses octets ne dépendent que du registre dans lequel il est publié et de la version sous laquelle il est publié ; il est donc conservé une fois par machine, à côté du magasin de modules compilés sous la même racine de cache par utilisateur, dans docs-bundles/<encoded-reference>/<encoded-version>/ sous cette racine : le bundle, le manifeste par rapport auquel il est vérifié, et les signatures que ses récupérations ont vérifiées. artifact_cache_dir ne l’atteint pas. Avant qu’une page n’y soit lue, ces signatures sont vérifiées à nouveau selon le propre contrôle de signature de l’espace de travail lecteur pour le registre du bundle, de sorte qu’une copie admise par les paramètres plus permissifs d’un espace de travail n’est pas servie à un espace de travail dont le contrôle la refuse — consultez aggrega-explain et aggrega-cache.
artifact_cache_dir s’écrit relativement à la racine de l’espace de travail et désigne le même répertoire quel que soit le répertoire depuis lequel une commande est invoquée ou les répertoires de catalogue en cours d’analyse. Une valeur absolue est refusée au chargement de la configuration, avec un diagnostic nommant le champ : chaque lecteur du paramètre le résout par rapport à la racine de l’espace de travail, de sorte qu’un chemin absolu désignerait un emplacement qu’aucun d’eux n’atteint, et l’échec serait sinon silencieux — le cache qu’écrit un pull cesserait discrètement d’être le cache que lit un build. Le cache peut se trouver à l’intérieur d’un répertoire de catalogue, et c’est le cas dans la disposition par défaut, puisqu’un répertoire de catalogue est couramment la racine même de l’espace de travail. Ce qu’il ne doit pas faire, c’est être un répertoire de catalogue : une analyse du catalogue enjambe le cache, de sorte qu’un répertoire de cache qui est aussi un répertoire de catalogue retire tout le contenu de ce répertoire de chaque analyse. artifact_cache_dir: . désigne la racine de l’espace de travail, ce qui, dans la disposition par défaut, est exactement ce cas, et il est refusé au chargement de la configuration avec un diagnostic nommant le champ — comme toute autre graphie qui se ramène à la racine de l’espace de travail. Ces deux formes, avec le chemin absolu ci-dessus, sont celles que le contrôle de configuration peut reconnaître par lui-même. Une valeur désignant un autre répertoire de catalogue — sub, dans un espace de travail dont catalog_dirs liste sub — se charge sans protestation, et le seul symptôme est que les entités qu’il contient ne sont plus trouvées. Tenir le cache à l’écart de chaque répertoire listé dans workspace.catalog_dirs fait donc partie de l’écriture de la configuration, et n’est pas quelque chose qu’elle vérifie pour vous.
Enjamber le cache est ce qui empêche un artefact de résolution d’être lu comme si un auteur l’avait écrit. Un slot de cache contient des octets qu’une récupération depuis le registre y a placés, stockés sous la coordonnée à laquelle ils ont été récupérés et garantis par un digest du lockfile ; une analyse qui en ramasserait un comme contenu de catalogue rédigé prendrait des octets que rien n’a vérifiés, sur un chemin que l’auteur ne peut pas modifier. Une conséquence mérite d’être énoncée clairement : si le cache contient une entité qu’aucun lockfile n’épingle — laissée par un pull interrompu, copiée à la main ou délaissée lorsqu’une Release a cessé de la référencer —, cette entité n’est pas visible pour une analyse du catalogue, et un build ou une validation qui en dépend s’arrête en indiquant que l’entité est introuvable. Le remède consiste à refaire le pull de la Release, afin que l’entité soit résolue via le lockfile et que son digest soit enregistré ; l’arrêt nomme l’entité afin que l’épinglage manquant puisse être identifié. L’alternative — la résoudre quand même — est précisément la lecture non vérifiée que l’enjambement du cache existe pour empêcher.
Le lockfile est propre à chaque Release : la résolution de release.yaml écrit release.lock à côté de celui-ci (le nom de base du fichier de la Release suivi de .lock). aggrega pull résout les dépendances et écrit le lockfile ; aggrega build le lit et utilise les versions épinglées quel que soit l’état du registre au moment du build. Les workspaces versionnent le lockfile lorsque la reproductibilité du build d’une machine à l’autre compte ; après qu’une entité, une bibliothèque, un plugin ou la Release elle-même a changé dans le workspace, aggrega pull --release <release> le rafraîchit, en résolvant à nouveau ce qui a changé tout en conservant chaque autre épinglage, et aggrega pull --upgrade --release <release> est la manière d’adopter une version plus récente qu’un registre propose désormais. Le lockfile enregistre chaque entité résolue avec son type, son URI tel qu’il a été écrit, la version résolue, le digest du contenu et les emplacements qui la référencent. Le type et l’URI identifient ensemble une entrée, de sorte qu’une Release dont l’Aggregate et le Manifest partagent un nom enregistre une entrée pour chacun, et qu’une modification de l’un ou de l’autre arrête le build suivant jusqu’à ce qu’un pull l’enregistre :
# release.lockentities: - kind: component uri: core/datastore/mariadb:1.0.0 resolved_version: 1.0.0 digest: sha256:5deeedb9acc1be00d4e0f98e55e01d301a0bcc01d702c015a9d9628ff573650a referenced_from: - aggregate.spec.components.db.type - kind: recipe uri: mariadb-bitnami:1.0.0 resolved_version: 1.0.0 digest: sha256:215b54e2da1ce512fcdccff87f6f71daac707bc77e4214b60b946b27a24e483a referenced_from: - manifest.spec.mappings.components.type.core/datastore/mariadb:1.0.0generated_at: "2026-06-11T16:48:15Z"mapping_libraries: []plugins: []release: release.yamlschema_libraries: []source_artifacts: []version: 1Chaque entrée épinglée porte le type + l’URI + la version résolue + le digest adressable par contenu. Le digest est vérifié à chaque récupération ; des octets qui ne correspondent pas au digest épinglé arrêtent le build avec une erreur d’intégrité. Le digest d’une entité est calculé sur ce que porte une publication de celle-ci — son document et chaque fichier qu’elle déclare à côté, chacun par son chemin et ses octets — plutôt que sur les octets sous lesquels elle voyage, de sorte que la même entité enregistre le même digest, qu’elle soit lue depuis un répertoire de catalogue ou récupérée depuis un registre, quelle que soit la façon dont son archive a été compressée et quels que soient les bits de permission, bit d’exécution compris, qu’un checkout a donnés à ses fichiers. C’est d’abord par rapport au digest que le registre calcule lui-même sur les octets publiés qu’une récupération est vérifiée, via le manifest, dont une entrée résolue par le registre enregistre le digest à côté du sien.
5. Le modèle de résolution des entités à trois niveaux
Le compilateur résout chaque référence d’entité rencontrée pendant la compilation au moyen d’une recherche en cascade stricte. Les trois niveaux — chemin local, workspace et cache, et registre — correspondent à trois flux de travail de rédaction qui coexistent dans un projet Aggrega sain : une Release qui nomme les fichiers placés à côté d’elle, une équipe qui utilise un catalogue versionné ainsi qu’un cache récupéré précédemment, et un pull qui interroge le registre pour un artefact pas encore récupéré. Le niveau workspace et cache et le niveau registre de la même cascade évaluent les champs type dans les Aggregates, les valeurs d’URI dans les mappings du Manifest, les déclarations implements sur les Recipes et les FeatureRecipes, et les références plugin dans les pipelines de Recipe et de FeatureRecipe ; le niveau chemin local n’est atteint que par les fichiers que nomment une Release et son Manifest.
Chemin local. Une référence aggregate, manifest ou extends d’une Release, ou l’extends d’un Manifest, commençant par ./ ou ../ (un préfixe de chemin relatif POSIX) est lue directement sur le disque, relativement à la Release. Aucune recherche dans le catalogue, aucun appel au registre. Le préfixe explicite distingue au niveau syntaxique l’intention de chemin local de la recherche par nom : une Release qui écrit aggregate: ./aggregate.yaml nomme un fichier ; aggregate: checkout nomme un Aggregate par son metadata.name. Le résolveur n’inspecte jamais le contenu de la chaîne pour décider quel niveau s’applique — le préfixe est le discriminant. Toute autre référence, y compris un type de Component dans un Aggregate, se résout par le niveau workspace et cache et le niveau registre : une entité rédigée localement est placée sous catalog/ à la racine du workspace ou dans un répertoire que liste workspace.catalog_dirs, et un type écrit comme chemin de fichier relatif arrête le build comme une entité qu’aucun catalogue ne contient.
Workspace et cache. Une référence sans préfixe de chemin local explicite est d’abord recherchée dans les répertoires listés dans workspace.catalog_dirs (des arborescences de catalogue locales au projet, rédigées dans le dépôt ou copiées dans celui-ci — voir le §4 pour la forme de la configuration) — ou, pour une Release à laquelle la configuration attribue ses propres répertoires sous workspace.releases, dans ceux de cette Release — puis dans le répertoire catalog/ de la racine du workspace, puis dans artifact_cache_dir (l’emplacement .aggrega/cache/, ignoré par git, qui contient les artefacts récupérés lors de résolutions antérieures auprès du registre, et dont le §4 décrit les sous-arborescences). C’est l’accès au cache à partir du deuxième build qui permet à la boucle interne de se passer du réseau, même lorsque le projet dépend de contenu de catalogue distant.
Registre. Si le niveau workspace et cache ne renvoie aucune correspondance, aggrega pull — ou un build lancé avec --auto-pull ou avec le paramètre auto_pull du workspace — effectue un pull OCI basé sur ORAS auprès de default_registry (par défaut hub.aggrega.ai), décompresse l’artefact dans le cache pour les builds suivants et poursuit avec l’entité résolue. Un build sans l’un ni l’autre ne lit que ce que son lockfile épingle, et s’arrête en nommant aggrega pull lorsque le lockfile est absent. La forme d’URI OCI que construit l’appel au registre suit la taxonomie par type d’entité décrite au §6 (Empaquetage des artefacts & taxonomie OCI). Les URI abrégés dans les Aggregates et les Manifests sont développés en leur forme OCI complète avant l’appel au registre ; les règles d’inférence qui gouvernent ce développement se trouvent dans la référence URI abrégés sensibles au contexte du Manifest et au §8 ci-dessous.
Précédence et masquage. La précédence de résolution est strictement chemin local > workspace et cache > registre. Une entité d’un répertoire de catalogue local ayant la même identité qu’une entité du registre masque l’entité du registre — c’est intentionnel et cela permet aux auteurs de catalogues d’expérimenter des modifications avant de publier. Le même masquage s’applique entre catalog_dirs et le cache : une entité présente dans un répertoire de catalogue du workspace est préférée à une copie en cache, de sorte que les modifications locales d’un catalogue copié dans le dépôt prennent effet immédiatement.
Au sein du niveau workspace et cache, catalog_dirs est une pile de précédence ordonnée où le premier l’emporte. Lorsque la même identité d’entité apparaît dans plusieurs répertoires de catalogue listés, le répertoire listé en premier l’emporte et l’occurrence suivante est masquée — remplacée, non chargée, et ce n’est pas une erreur. Cela permet à un projet de placer son propre répertoire de catalogue devant un répertoire partagé ou copié dans le dépôt et de remplacer des entités choisies par leur identité, tandis que les autres retombent sur le répertoire partagé. Le remplacement est observable : le détail de la résolution indique quel répertoire l’a emporté et lequel a été masqué, de sorte qu’une superposition n’est jamais silencieuse. Le masquage ne s’applique qu’entre répertoires ; deux fichiers d’un même répertoire qui revendiquent la même identité sont une erreur de rédaction et arrêtent le chargement. Un répertoire nommé plus d’une fois — par un flag --catalog et dans catalog_dirs, ou deux fois dans la liste — est une seule entrée de la pile, parcourue une seule fois à l’endroit où il a été nommé en premier, de sorte qu’un masquage concerne toujours deux fichiers différents et jamais un répertoire lu contre lui-même. Comme la précédence suit l’ordre des répertoires contrôlé par l’auteur, l’ensemble résolu est déterministe.
Le répertoire catalog/ de la racine du workspace rejoint cette pile à sa fin, et non à sa tête, et seulement lorsque le répertoire existe — ainsi, tout ce qu’un projet liste l’emporte sur lui en cas de collision, et lister un répertoire sans rapport ne cesse jamais silencieusement de le faire lire. Il est ignoré lorsqu’une entrée listée l’atteint déjà, car le parcours d’un répertoire listé est récursif et une pile qui nomme la racine du workspace l’a déjà lu. Omettre catalog_dirs et l’écrire comme une liste vide sont deux déclarations différentes : omis, le workspace lit toujours catalog/ ; écrit [], il ne lit aucun catalogue local, et c’est ainsi qu’un workspace déclare qu’il n’en a pas.
Builds isolés du réseau. Définir offline: true (§4) ignore entièrement le niveau registre. Une référence qui ne se résout ni au niveau chemin local ni au niveau workspace et cache fait apparaître une erreur d’entité manquante au lieu de tenter silencieusement un appel réseau, ce qui offre aux pipelines CI qui ne peuvent légalement pas accéder au réseau un contrat déterministe d’échec rapide.
Où opère la cascade. La cascade charge l’entité en mémoire ; les mécanismes de résolution supplémentaires construits par-dessus — la recherche à deux niveaux type contre name du Manifest, la correspondance de version de implements sous trois formes (exacte / plage compatible avec la version majeure / sans version) décrite dans vocabulary/inheritance-and-interface, et la sélection de la Recipe par axe selon le provider et l’instance de composant — opèrent sur des entités que le résolveur a déjà récupérées par cette cascade.
6. Empaquetage des artefacts & taxonomie OCI (la capacité comme segment de tête)
Aggrega traite la logique d’infrastructure de la même manière que Docker traite les images de conteneurs, en utilisant les standards de l’Open Container Initiative (OCI) via ORAS (OCI Registry As Storage). Les utilisateurs peuvent héberger leur catalogue Aggrega sur n’importe quel registre standard (GHCR, AWS ECR, Aggrega Hub).
Comme les Recipes sont strictement en 1:1 avec une capacité de rendu — une Recipe nomme une seule capacité dans spec.capability et ne peut pas en cibler deux —, la manière la plus propre de les organiser dans un registre OCI est de placer la capacité dans le segment de tête du dépôt.
La taxonomie OCI couvre tous les types d’entités. Un nom de dépôt est le segment du kind — le kind de l’entité, en minuscules — suivi de l’identité de l’entité, le tout en minuscules :
hub.aggrega.ai/component/core/datastore/mariadb:1.0.0— Component, éditeurcore, catégoriedatastorehub.aggrega.ai/component/core/compute/api-server:1.0.0— Component, éditeurcore, catégoriecomputehub.aggrega.ai/feature/core/data-masking:1.0.0— Feature, éditeurcore(plat, sans catégories)hub.aggrega.ai/aggregate/core/db-module:1.0.0— Module Aggregate réutilisablehub.aggrega.ai/recipe/helm/mariadb:1.0.0— Recipe, capacitéhelmhub.aggrega.ai/recipe/helm-chart/mariadb:1.0.0— Recipe, capacitéhelm-charthub.aggrega.ai/recipe/compose/mariadb:1.0.0— Recipe, capacitécomposehub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0— FeatureRecipe, capacitéhelmhub.aggrega.ai/schemalibrary/aidatastores:1.0.0— SchemaLibrary, définitions de schéma partagées ; lemetadata.nameen PascalCaseAIDatastorespasse en minuscules dans le nom du dépôthub.aggrega.ai/mappinglibrary/bitnamihelpers:1.0.0— MappingLibrary, fragments de mapping Go-template partagéshub.aggrega.ai/plugin/provider/helm:0.5.0— Plugin, type de socketprovider(le segmentmetadata.pluginType)
Les kinds publiables couvrent les kinds de rédaction du catalogue, ainsi que l’Aggregate, un module réutilisable (publiable qu’il soit ensuite référencé comme spec.aggregate de premier niveau d’une Release ou imbriqué dans le bloc aggregates: d’un autre Aggregate), et le Plugin, une référence adressée par contenu à un artefact WebAssembly que le compilateur route et que le runtime exécute. Le Plugin est un artefact publiable structurel plutôt qu’un kind de rédaction du catalogue. Release et Manifest sont des entrées côté déploiement qui résident dans le contrôle de source et ne sont jamais poussées — aggrega push les rejette —, elles n’ont donc pas de mediatype de publication. aggrega push --list-kinds indique l’ensemble que publie le binaire installé, un kind par ligne. Chaque kind publiable a son propre mediatype OCI dans chacune des deux formes que prend une publication :
| Kind d’entité | Publiée sous forme de son document | Publiée avec les fichiers qu’elle déclare |
|---|---|---|
| Component | application/vnd.aggrega.component.v1beta1+yaml | application/vnd.aggrega.component.v1beta1+tar+gz |
| Feature | application/vnd.aggrega.feature.v1beta1+yaml | application/vnd.aggrega.feature.v1beta1+tar+gz |
| Recipe | application/vnd.aggrega.recipe.v1beta1+yaml | application/vnd.aggrega.recipe.v1beta1+tar+gz |
| FeatureRecipe | application/vnd.aggrega.featurerecipe.v1beta1+yaml | application/vnd.aggrega.featurerecipe.v1beta1+tar+gz |
| Aggregate | application/vnd.aggrega.aggregate.v1beta1+yaml | — ne déclare aucun fichier |
| SchemaLibrary | application/vnd.aggrega.schemalibrary.v1beta1+yaml | — ne déclare aucun fichier |
| MappingLibrary | application/vnd.aggrega.mappinglibrary.v1beta1+yaml | — ne déclare aucun fichier |
| WorkloadLibrary | application/vnd.aggrega.workloadlibrary.v1beta1+yaml | — ne déclare aucun fichier |
| ArtifactLibrary | application/vnd.aggrega.artifactlibrary.v1beta1+yaml | — ne déclare aucun fichier |
| Plugin | application/vnd.aggrega.wasmplugin.v1beta1+yaml | — publie via son propre manifest |
Ce que porte une publication, et donc sa forme, découle de ce que l’entité déclare — ni de son kind, ni de ce qui se trouve dans son répertoire. Une publication porte le document de l’entité et les fichiers que l’entité elle-même nomme à côté : la source: locale d’une Recipe ou d’une FeatureRecipe — un répertoire voyage avec chaque fichier qu’il contient que conservent les règles d’exclusion enregistrées dans son entity.lock —, chaque fichier que ses entrées valuesMapping:, workload: et artifacts: importent avec $import:, et l’entity.lock écrit par son étape d’épinglage ; ainsi que chaque fichier de schéma qu’un Component ou une Feature importe, y compris chaque fichier d’une chaîne d’imports. Rien d’autre dans le répertoire ne voyage : une note, un README ou la sortie d’un build à côté de l’entité ne fait pas partie de ce qu’elle publie, quel que soit son nom, et ne change pas la forme sous laquelle elle publie. Une entité qui ne nomme rien est publiée sous forme de son document tel qu’écrit, octet pour octet, sous le mediatype +yaml de son kind ; une entité qui nomme un fichier est publiée sous forme d’une archive tar compressée avec gzip contenant le document et ces fichiers, sous le mediatype +tar+gz de son kind. Un Aggregate, un Plugin et les kinds de bibliothèque ne déclarent aucun fichier à côté de leur document, ils sont donc toujours publiés sous forme du document — y compris un Aggregate à la racine d’un workspace, puisque chaque chemin qu’il déclare nomme une autre entité et non un fichier qu’il porte ; il en va de même d’une Recipe dont tout le contenu est en ligne. Une source distante est une référence et non un fichier, elle ne porte donc rien, bien que l’entity.lock qui enregistre son épinglage fasse d’une telle Recipe une archive. Le segment de version de chaque mediatype est commun à tous les kinds publiables, et le segment d’encodage indique laquelle des deux formes ont les octets. Les outils en aval aiguillent sur la chaîne complète du mediatype — kind, version et encodage ensemble.
Une forme rédigée ne nomme aucun répertoire qu’une publication puisse connaître : une source locale écrite comme template. Son répertoire n’est choisi qu’au moment où une Release remplit le template, donc l’entité porte chaque fichier de son propre répertoire que conservent ses règles d’exclusion enregistrées, afin que le répertoire qu’une Release choisira, quel qu’il soit, ait voyagé ; aggrega push le signale lorsque cela se produit. Ne porter que ce qui est nommé a un coût, et il retombe sur le consommateur : un fichier qu’une entité lit sans le nommer nulle part ne voyage pas, et c’est le build d’un consommateur — et non le push de l’éditeur — qui se heurte à son absence, en nommant le chemin manquant à l’intérieur de son emplacement de cache.
Les fichiers d’un répertoire source qui appartiennent à l’entité sont déterminés une seule fois, lorsque l’entité est épinglée, et enregistrés. Le plugin qui sert la capacité de l’entité dans le workspace de l’auteur déclare ce que son écosystème ne livre jamais — les répertoires de contrôle de version d’un plugin de chart et sa prise en compte du .helmignore d’un chart, le .terraform/ d’un plugin de module — et le .aggregaignore de l’auteur à côté de l’entité a le dernier mot. L’étape d’épinglage enregistre ce plugin et les règles composées dans l’entity.lock, et la publication, chaque comparaison des épinglages de la source, la ligne de l’entité dans le lockfile et le rendu appliquent tous les règles enregistrées au lieu d’interroger à nouveau un plugin, de sorte que ce qui est publié est ce que rend le build de l’auteur lui-même, et qu’un binding modifié ou un binaire plus récent ne change aucun digest tant que l’entité n’est pas épinglée à nouveau. Le compilateur n’a d’opinion sur aucun écosystème : les règles viennent du plugin et de l’auteur, et le compilateur se contente de les appliquer. Un lien symbolique parmi les fichiers d’une entité est refusé plutôt que suivi, puisque ce vers quoi il pointe voyagerait sous son nom. aggrega pin présente les règles en détail.
Le nom d’une Recipe ne porte ni préfixe de domaine ni la capacité : le répertoire du type d’entité et le segment de la capacité indiquent déjà l’un et l’autre.
Convention de nommage : les Components (domaine 2) utilisent {publisher}/{category}/{name}, et les Features (domaine 2) ainsi que les Aggregates réutilisables (domaine 1) utilisent {publisher}/{name}, où le segment publisher nomme le fournisseur ou l’auteur (core = bibliothèque standard officielle, acme = entreprise). Les entités du domaine 3 (Recipe, FeatureRecipe) utilisent {capability}/{name}, où la capacité est le provider que l’entité déclare dans spec.capability ; une référence peut aussi nommer l’entité sans préfixe, par la seule feuille. Les noms de Recipe n’incluent PAS non plus la capacité, puisqu’elle est déjà le segment de tête de l’URI canonique.
Les Recipes utilisent le mot-clé implements pour se lier à l’interface qu’elles réalisent. Le champ implements prend en charge la correspondance exacte, par plage compatible avec la version majeure, ou sans version (voir vocabulary/inheritance-and-interface pour la correspondance de version de implements). La Recipe d’une entrée de mapping du Manifest doit implémenter le type pour lequel elle est mappée, ou une base que ce type extends : la clé de l’entrée, ainsi que le type de chaque instance de composant que la clé atteint dans une version qu’elle ne nomme pas, dans la version sous laquelle le build compile cette instance — de sorte qu’une clé ne peut pas envoyer une instance vers une Recipe écrite pour une autre version de son type.
Lorsqu’un ingénieur Ops exécute aggrega push, la CLI publie l’entité sous cette forme, de manière immuable à sa version. Un consommateur la récupère via le modèle de résolution à trois niveaux, la met en cache localement dans .aggrega/cache/ et dispose ce qu’elle porte dans l’emplacement de cache de l’entité (§4) — les fichiers d’une archive, ou le document seul.
Une entité récupérée par pull lit les fichiers qu’elle transporte exactement comme elle les lit à côté d’elle dans un répertoire de catalogue. L’entité est lue depuis sa place dans cet arbre déployé, de sorte qu’un source: ou un $import: relatif qu’elle déclare — écrit en clair ou produit par un template — se résout à l’intérieur de ce qui a été publié, et qu’un chemin qui sort du répertoire propre de l’entité y est refusé exactement comme dans un répertoire de catalogue. Rien en dehors de l’arbre n’est lu à sa place : ni le répertoire depuis lequel un build s’exécute, ni un fichier déposé dans l’emplacement de cache. Un Component ou une Feature dont le schéma est importé depuis un fichier transporte ce fichier, de sorte qu’une copie récupérée charge le contrat qui a été publié et valide les valeurs rédigées par rapport à lui exactement comme le fait une copie lue depuis un répertoire de catalogue.
Relire l’entité depuis un paquet est l’étape inverse, et elle identifie l’entité par ce que le document est plutôt que par son nom : le document au niveau supérieur du paquet dont le kind: est un type d’entité publiable. Le nom du fichier de l’entité est une convention du catalogue et non un contrat, de sorte que recipe.yaml est ce qu’écrit le catalogue de la bibliothèque standard plutôt que ce qu’exige le format, et qu’un fichier transporté à côté de l’entité — un template de chart, un fragment compose — n’est pas confondu avec elle. La règle ne peut pas fonctionner dans l’autre sens, en se fondant sur le type que cherche le consommateur : un type est lu à partir de l’entité, qui se trouve à l’intérieur du paquet, de sorte qu’au moment où le paquet doit être ouvert, il n’y a aucun type sur lequel se fonder. Le côté lecture s’arrête plutôt que de choisir lorsque le niveau supérieur d’un paquet contient deux documents d’entité — le paquet qu’un autre client produit en empaquetant tout un répertoire contenant deux entités, et qui se trouverait alors sous chacune de leurs coordonnées publiées comme un seul artefact. La publication de ce produit ne peut pas le produire, car chaque entité ne transporte que ce qu’elle déclare, et le côté publication refuse en outre un tel répertoire : chaque type a un répertoire qui lui est propre, sauf Aggregate, Release et Manifest, et aggrega pin et aggrega push refusent une entité de tout autre type à côté de laquelle se trouve une autre entité, tandis qu’un chargement de catalogue, un lint et un build laissent le répertoire tel quel. Le nom d’un répertoire n’est jugé d’aucun côté : la disposition <name>/<version>/ est la convention du catalogue de la bibliothèque standard.
Une entité publiée est lue par la même étape. Une coordonnée transporte exactement une copie de son entité, dans la forme que ses déclarations lui ont donnée, et une personne l’examine avec aggrega inspect oci://<registry>/<repository>:<tag> plutôt qu’au moyen d’une copie lisible publiée à côté — il n’existe donc pas de seconde copie qui pourrait finir par diverger de celle qu’un build résout. La commande décompresse une archive selon la règle ci-dessus, lit l’entité d’un Plugin depuis son manifeste plutôt que depuis l’exécutable publié avec lui, et affiche le résultat comme s’affiche un fichier de ce type ; voir Lire une entité publiée.
Annotations de manifeste interrogeables. Chaque publication appose un petit ensemble d’annotations interrogeables sur le manifeste OCI de l’artefact, afin qu’un index de registre ou un navigateur de catalogue puisse filtrer les artefacts selon leurs métadonnées de catalogue sans récupérer ni analyser le corps de chaque entité. Chaque entité porte sa description lisible par un humain (l’annotation de description OCI standard) ainsi que sa catégorie de catalogue et son type. Un Plugin porte en outre son type de socket et les capabilities qu’il sert. Ces annotations sont ce que aggrega registry update relit dans l’index interrogeable local (§8).
Chaque fichier publié porte un nom. Chaque fichier qu’une publication transporte est nommé dans le manifeste avec l’annotation standard org.opencontainers.image.title, qui est le nom sous lequel un client OCI générique écrit ce fichier lorsqu’il récupère l’artefact dans un répertoire. Le nom dit ce qu’est le fichier, et son extension suit le media type du fichier :
| Ce qui est publié | Le fichier qu’écrit un client OCI générique |
|---|---|
| une entité publiée en tant que son document | entity.yaml |
| une entité publiée avec les fichiers qu’elle déclare | entity.tar.gz |
| un Plugin | entity.yaml, l’entité, à côté de entity.wasm, son exécutable |
| une signature attachée à un artefact | signature.json |
| un marqueur de dépréciation attaché à un artefact | deprecation.json |
un artefact de données publié avec aggrega push-artifact | le nom donné avec --name |
Ainsi, oras pull hub.aggrega.ai/component/core/compute/server:1.0.0 -o ./server laisse l’entité publiée dans ./server/entity.yaml, octet pour octet telle qu’elle a été publiée. oras ignore un descripteur qui ne porte aucun nom et signale tout de même une réussite, c’est pourquoi chaque descripteur qu’une publication empaquette en porte un. Le nom est dérivé du seul media type, jamais du nom du fichier qui a été publié, de sorte que les mêmes octets publiés depuis un fichier nommé différemment produisent le même manifeste. Une entité publiée avec ses fichiers arrive sous la forme de son paquet : entity.tar.gz nomme le paquet, et l’entité qu’il contient est trouvée selon la règle ci-dessus plutôt que par un nom de fichier. La résolution propre d’Aggrega ne lit jamais ces noms — elle sélectionne chaque fichier par son media type et lui fait confiance par son digest —, ils sont donc là pour tous les autres clients.
7. L’architecture de la Recipe : pointeurs et mappers
Voir entities/recipe pour la surface de rédaction complète de la Recipe — source: (pointeur), valuesMapping: (mapper, avec trois modes de rédaction : block scalar inline, $import: de fichier, $import: de bibliothèque vers une entrée d’une MappingLibrary), schémas de source pilotés par Wasm, prise en charge native de l’IaC et exemples commentés.
8. Le registre par défaut et les URI abrégées sensibles au contexte
Pour éliminer le gonflement du YAML, le compilateur résout les URI abrégées en fonction du contexte, d’après la position dans le schéma où elles apparaissent. Le registre par défaut est configuré dans .aggrega-config.yaml (par défaut hub.aggrega.ai).
Un hôte de registre n’a qu’une seule lecture. Chaque registries[].host est écrit comme l’hôte lui-même — un nom d’hôte en minuscules contenant un point, localhost, un nom unique suivi d’un port, une adresse IPv4 ou une adresse IPv6 entre crochets, chacun avec un :port facultatif, et sans schéma, chemin, identifiants ni majuscules —, car cette graphie est la clé sous laquelle se trouve chaque politique de confiance par registre, et l’exigence de signature intégrée du hub officiel est rattachée à hub.aggrega.ai. default_registry nomme un hôte de la même manière, et peut le faire suivre d’un chemin de dépôt, comme ghcr.io/acme : tout ce qui est publié par le registre par défaut aboutit alors sous ce chemin, et chaque référence courte se résout sous celui-ci, tandis que la confiance reste décidée par le seul hôte. default_registry peut aussi être écrit comme le name: d’une entrée de registries, et désigne alors l’hôte de cette entrée. Le nom est lu une seule fois, au moment où la configuration se résout, par rapport aux entrées en vigueur après chaque fichier de configuration et l’environnement, de sorte que chaque lecteur du registre par défaut — la publication, la liaison d’emplacement, la vérification des signatures et chaque recherche de confiance — lit l’hôte de cette seule entrée, et qu’aucun d’eux n’atteint un hôte écrit comme le nom ; un nom suivi d’un chemin est refusé, puisqu’un nom désigne une entrée et non un emplacement. Un nom est comparé avant une graphie d’hôte, et un nom porté par deux entrées est refusé comme ambigu. La même lecture décide de trois choses qu’un pull fait avec l’hôte : l’emplacement de registre auquel une identité de catalogue sans hôte est liée, si l’artefact récupéré nomme ou non un registre dont la signature est vérifiée, et la politique de confiance appliquée lors de cette vérification. Une graphie qui pourrait atteindre un registre tout en manquant sa politique — des majuscules, un port HTTPS par défaut explicite, un schéma, des identifiants, un chemin sur l’hôte d’une entrée de registries — est refusée là où elle est configurée, en indiquant la graphie à écrire, de même qu’un nom unique sans port qui ne nomme aucune entrée, ce qui est la forme du premier segment d’une identité de catalogue et non celle d’un hôte. Le refus s’applique à chaque niveau qui peut définir la valeur : le fichier de configuration, où le schéma énonce la même forme comme motif sur chaque registries[].host ; la variable d’environnement AGGREGA_DEFAULT_REGISTRY ; et la ligne de commande. Ainsi, chaque hôte qu’une configuration peut nommer est un hôte dont les artefacts sont vérifiés selon la politique écrite pour lui. L’hôte est jugé sur sa seule graphie ; que le nom se résolve, ou qu’un registre y réponde, relève de l’état d’exécution que le compilateur ne récupère jamais. configuration détaille les formes acceptées avec des exemples.
Les URI abrégées se résolvent en fonction du contexte par rapport au Manifest ; voir ../language-reference/entities/manifest.md §URI abrégées sensibles au contexte pour les règles d’inférence spécifiques.
Gérer les registres
aggrega registry gère les registres que connaît l’espace de travail et leur politique de confiance des signatures. L’identité d’un registre est son hôte ; les sous-commandes partagent un même modèle d’adressage :
aggrega registry add <host>enregistre un registre et épingle sa politique de confiance, en récupérant la politique annoncée par le registre au premier contact, sauf si des flags de confiance en fournissent une manuellement. Un--name <alias>facultatif attache un alias convivial à la même entrée indexée par hôte — l’hôte reste l’identité, et l’alias se résout en lui partout où un registre est nommé. Un alias est unique parmi les registres.aggrega registry listaffiche chaque registre configuré — hôte, alias, un bref résumé de la posture de confiance et un marqueur sur le registre par défaut — dans l’ordre croissant des hôtes. La commande lit la configuration résolue et ne contacte aucun réseau.aggrega registry remove <name|host>supprime l’entrée de politique de confiance d’un registre, désignée par son hôte ou son alias. Elle ne supprime que la politique de confiance : le pointeurdefault_registryreste intact et la possibilité de pousser vers cet hôte n’est pas affectée, de sorte que l’hôte revient à la confiance par défaut au lieu de devenir injoignable. Undefault_registryécrit comme le nom de l’entrée supprimée ne nomme plus rien par la suite, et il est refusé tant qu’il n’est pas réécrit.aggrega registry updateactualise l’index interrogeable local, décrit ci-dessous.
Partout où un registre est nommé — un argument d’une sous-commande registry ou le flag --registry de aggrega push et aggrega push-artifact —, le même résolveur interprète le jeton : un alias configuré se résout en son hôte, et tout autre jeton est lu comme l’hôte qu’il nomme, le schéma, le chemin et les identifiants d’une référence étant abandonnés. Là où cet hôte devient quelque chose par rapport à quoi une décision de signature est prise — la destination de aggrega push ou aggrega push-artifact, ou la clé sous laquelle aggrega registry add écrit une entrée —, il est tenu à l’unique lecture ci-dessus et refusé, en indiquant la graphie à écrire, lorsqu’il n’est pas écrit ainsi. Un hôte non enregistré écrit ainsi est une destination légitime et il est accepté.
L’index interrogeable local
aggrega registry update [<name|host>] construit un index interrogeable local des registres que connaît l’espace de travail. La commande parcourt les dépôts de chaque registre configuré, sélectionne la version publiée la plus élevée de chacun, lit les annotations de manifeste interrogeables de cette version (§6) et écrit un index par registre dans le cache des artefacts. Sans argument, elle indexe chaque registre configuré ; avec un seul argument de registre (un hôte ou un alias), elle n’indexe que celui-ci.
L’index suit le modèle d’actualisation explicite familier des gestionnaires de paquets : registry update est la commande qui contacte les registres, et un aggrega search ultérieur lit l’index écrit hors ligne. Le fichier d’enregistrements d’un registre est déterministe — deux actualisations sur le même état du registre produisent des octets identiques, et l’horodatage de fraîcheur se trouve dans un fichier voisin afin de ne jamais perturber les enregistrements. Un dépôt sans version publiée, ou qui ne peut pas être lu, est ignoré, de sorte qu’un seul dépôt illisible ne fait jamais abandonner l’index entier.
L’instantané publié du catalogue
Chaque publication du catalogue de la bibliothèque standard publie aussi le catalogue dans son ensemble : un seul artefact OCI, une archive tar compressée avec gzip de tous les fichiers que contient l’arborescence du catalogue au commit que cette publication a publié, à catalog/snapshot sous le registre où le catalogue est publié — hub.aggrega.ai/catalog/snapshot pour le hub officiel. Il n’est poussé qu’une fois que chaque entité de cette publication se trouve sur le registre, de sorte qu’il ne nomme aucune entité que le registre ne détienne. Il est étiqueté avec le commit à partir duquel il a été construit et avec latest, et il est signé sans clé par l’auteur de la publication, comme chaque entité de la publication, de sorte que l’identité de l’auteur de la publication permet de le vérifier selon la politique de confiance du registre ; latest ne passe à un instantané qu’une fois celui-ci signé. L’archive est écrite selon une disposition fixe unique — les entrées dans l’ordre croissant de leur nom, chacune avec le même mode, le même propriétaire et la même date de modification — de sorte qu’un même commit produit toujours la même archive tar.
Son unique lecteur est un import dont le workspace ne nomme aucun dossier de catalogue : ni workspace.catalog_dirs, ni AGGREGA_CATALOG_DIRS, ni répertoire catalog/ à la racine du workspace. aggrega import, l’import de la session de l’éditeur et l’outil d’import de l’assistant exécutent la même opération, de sorte que chacun obtient l’instantané de la même façon. L’import le récupère depuis le registre par défaut du workspace par le même contrôle du trafic sortant et la même connexion qu’un pull, vérifie sa signature selon la politique de confiance de ce registre avant de conserver quoi que ce soit, le conserve dans le cache d’artefacts du workspace et l’y lit comme un dossier de catalogue, lié à son digest — ainsi l’importateur se voit proposer les Components du catalogue, et --target ébauche un Manifest à partir de ses Recipes, exactement par le chemin que suit un dossier de catalogue. L’enregistrement que l’import écrit à côté de ses ébauches nomme l’instantané par le digest de son manifeste, de sorte qu’un import ultérieur des mêmes ébauches lit le même catalogue sans requête, et aggrega import --upgrade récupère l’instantané le plus récent et importe désormais par rapport à lui. En mode hors ligne, un import qui devrait récupérer un instantané s’arrête en nommant ce qu’il faut exécuter. Un workspace qui nomme un dossier de catalogue importe par rapport à celui-ci et ne récupère aucun instantané. Aucune autre commande ne lit l’instantané : un pull, un build et une validation résolvent chaque entité à travers les niveaux du §5 et l’épinglent dans le lockfile, et les ébauches d’un import référencent les entités du catalogue par leur nom, de sorte que les construire résout ces entités de la même façon.
9. Épinglage par lockfile et immuabilité des artefacts
La discipline d’épinglage par lockfile ancre chaque dépendance à un artefact précis adressable par son contenu. À la première résolution du lockfile (aggrega pull), le résolveur consulte le registre, choisit une version selon la contrainte à trois formes de l’URI (exacte / plage / sans version) et écrit la version épinglée + le digest dans le <release-stem>.lock de la Release. Les invocations suivantes de aggrega build utilisent les valeurs épinglées quelle que soit la mutabilité du registre ; de nouvelles versions peuvent être publiées sans affecter le lockfile existant.
Le modèle d’épinglage repose sur une règle porteuse : une fois qu’un name:version est publié dans un registre et se résout en digest D, cette correspondance est permanente. Republier le même name:version avec un contenu différent est rejeté au moment du push. aggrega push lui-même l’impose à chaque publication : il résout l’artefact existant à name:version dans le registre cible ; s’il est présent et que le digest correspond au contenu sur le point d’être poussé, le push ne téléverse rien et n’attache que ce qui manque encore à cette publication — sa date de publication, et sa signature lorsque le push signe ; s’il est présent et que le digest diffère, le push s’arrête avec une erreur de violation d’immuabilité qui cite les deux digests.
L’immuabilité importe pour deux conséquences :
- Les épinglages du lockfile sont fiables. Lorsque le lockfile enregistre
mariadb:1.0.0au digestD, un build qui récupère par digest reçoit les octets deD. Sans immuabilité, une modification côté registre pourrait remplacer les octets deDsous l’épinglage du lockfile, compromettant la stabilité entre le moment du verrouillage et celui du build. Les builds reproductibles reposent sur cette garantie. - Les modifications de métadonnées après publication ont une voie claire. Marquer une version publiée comme obsolète, faire tourner les clés de signature ou modifier des attestations ne peut pas se faire en modifiant l’artefact publié (la règle l’interdit). Il faut le faire en publiant une nouvelle version de correctif ou un artefact sidecar qui enregistre séparément la modification des métadonnées. Les deux voies sont auditables — une nouvelle version ou un sidecar apparaît comme une entrée distincte du registre — et aucune n’altère les octets de l’artefact d’origine.
La règle d’immuabilité s’applique uniformément à chaque artefact Aggrega publié via OCI (entités, SchemaLibrary, MappingLibrary, plugins Wasm référencés par le pipeline[].plugin: d’une Recipe / le pipeline[].plugin: d’une FeatureRecipe / le plugins.{governance,linter,importer}[]: de la configuration de l’espace de travail). Tout ce qui est épinglé par name:version plus un digest de contenu dans le lockfile est soumis à l’immuabilité.
L’immuabilité est inconditionnelle, et aucune configuration ne l’assouplit. Il n’existe aucun flag ni aucun paramètre de la configuration de l’espace de travail qui autorise un écrasement, car le registre n’expose aucune voie d’écrasement qu’un opérateur pourrait choisir d’activer. Un contenu modifié est publié sous une nouvelle version, et aggrega lint --pre-publish vérifie que l’incrément de version correspond à la classification de la modification.
Une nouvelle résolution vers une version plus récente exige une action explicite de l’utilisateur : aggrega pull --upgrade --release <release> <uri> résout à nouveau une seule dépendance en conservant tous les autres épinglages, et aggrega pull --upgrade --release <release> résout à nouveau toutes les dépendances par rapport à l’état actuel du registre. Les dépendances sous forme de plage et sans version se résolvent à nouveau vers la dernière version correspondante ; les épinglages sous forme exacte ne bougent pas, sauf si l’utilisateur passe explicitement à une autre version exacte. Le lockfile est la source de vérité pour les builds ; la forme saisie par l’utilisateur exprime la contrainte de version au moment de la rédaction.
10. Application de la forme des noms des entités de catalogue
Les noms des entités de catalogue suivent des motifs propres à chaque type d’entité — énumérés ci-dessous et détaillés par type dans la Vue d’ensemble de la référence des entités. Ils constituent une surface différente des noms d’instance qu’un développeur écrit dans un Aggregate ou une Release, qui partagent un seul motif quel que soit le type ; ce motif se trouve dans ../language-reference/02-naming-conventions.md « Noms d’instance ». Le champ metadata.name qu’un YAML de catalogue déclare n’est pas toujours identique à l’URI de référence canonique de l’entité : Component et Feature intègrent directement les segments d’éditeur et de regroupement dans metadata.name ; Recipe et FeatureRecipe déclarent un metadata.name réduit à la feuille, et leur URI canonique à deux segments associe cette feuille à la spec.capability que l’entité déclare ; chaque type de bibliothèque déclare un jeton PascalCase dans metadata.name.
Formes par type d’entité :
- Component — trois segments kebab-case
{publisher}/{category}/{name}déclarés dansmetadata.name. Exemple :core/datastore/postgres. - Feature — deux segments kebab-case
{publisher}/{name}déclarés dansmetadata.name. Exemple :core/data-masking. - Recipe — une seule feuille kebab-case dans
metadata.name(par ex.postgres). L’URI de référence canonique{capability}/{name}(selon le §6 ci-dessus) associe laspec.capabilitydéclarée par l’entité à cette feuille ; le segment de tête est comparé àspec.capability, et non à l’emplacement de l’entité sur le disque, de sorte que déplacer unrecipe.yamlne change pas la façon dont il est référencé. Le catalogue de la bibliothèque standard place l’entité dans<catalog-root>/recipe/<capability>/<name>/<version>/recipe.yamlafin que l’arbre reflète la coordonnée, mais ce reflet est une convention du catalogue et non la source de l’URI. Une référence peut aussi nommer la recette seule — la feuille uniquement, sans segment de capability —, ce qui est la forme dominante en pratique et se résout chaque fois qu’une seule recette du catalogue porte ce nom. Aucun segment d’éditeur n’apparaît dans une URI de Recipe, et une référence portant un troisième segment ne correspond à aucune recette. - FeatureRecipe — une seule feuille kebab-case dans
metadata.name(par ex.k8s-secret-from-parameter), symétrique de la Recipe : URI canonique{capability}/{name}à partir de laspec.capabilitydéclarée plus la feuille, la feuille seule acceptée de la même manière, et l’arbre<catalog-root>/feature-recipe/<capability>/<name>/<version>/recipe.yamlqui reflète la coordonnée par convention. - Les types de bibliothèque — SchemaLibrary, MappingLibrary, WorkloadLibrary et ArtifactLibrary — un seul jeton PascalCase dans
metadata.namecorrespondant à^[A-Z][A-Za-z0-9]*$(par ex.BaseComponents,AIDatastores,BaseWorkloads). La forme est la même pour chaque type de bibliothèque, de sorte que déplacer une entrée d’une bibliothèque à une autre ne signifie jamais la renommer selon une convention différente. L’enveloppe JSON Schema de chaque type de bibliothèque déclare elle aussi le motif, en plus de la vérification décrite ci-dessous.
Pour Component, Feature, Recipe et FeatureRecipe, le JSON Schema de metadata.name accepte toute chaîne non vide, de sorte que rien dans la forme n’est structurel pour ces types. Chaque forme documentée — y compris celles des types de bibliothèque, dont les enveloppes déclarent elles aussi leur motif — est vérifiée par le plugin de discipline de publication, qui porte les motifs comme source de vérité regex partagée avec la distribution du compilateur. Aucun type ne reçoit ici une forme que le plugin ignorerait ensuite.
La vérification est facultative : une seule commande l’effectue, et elle ne s’exécute que lorsqu’un auteur la demande. Les deux commandes que l’on suppose le plus souvent l’effectuer ne le font pas :
aggrega lintsignale les violations de forme des noms. Le plugin compare lemetadata.namede chaque entité au motif de son type. La vérification s’exécute lorsqu’un auteur invoqueaggrega lint— sur une seule entité, sur la fermeture des dépendances d’une Release avec--release, ou sur chaque entité du catalogue lorsqu’il est invoqué sans argument —, et le même ensemble de règles est accessible depuis la surface d’outils orientée éditeur que la CLI expose. Les constats sont consultatifs : ils sont signalés avec la gravitéwarn, et ils n’interrompent rien.
warn: E0278 name-shape: metadata.name "mariadbSynth" does not match the documented pattern for Recipe entities (^[a-z][a-z0-9-]*$)Le constat commence par sa gravité et le code court sous lequel sa règle est enregistrée, que aggrega explain E0278 développe. Le chemin du fichier en cause s’affiche au-dessus du constat, et une exécution sur l’ensemble du catalogue se termine par un décompte des entités vérifiées et des constats consultatifs émis.
aggrega buildne vérifie pas la forme des noms. La sortie rendue ne dépend pas des noms des entités Aggrega, de sorte qu’un build sur un catalogue contenant des noms non conformes n’émet aucun avertissement ni aucun diagnostic, et réussit exactement comme il le ferait autrement.aggrega pushne vérifie pas non plus la forme des noms. La publication refuse pour d’autres motifs — notamment la règle d’immuabilité ci-dessus, selon laquelle republier unname:versionexistant avec un contenu différent s’arrête. Lorsqu’un refus nommeaggrega lint --pre-publish, il indique à l’auteur quelle commande exécuter ; le push ne l’exécute pas.
Comme ni le build ni la publication ne vérifient la forme, un catalogue qui veut que la convention soit respectée exécute aggrega lint délibérément — dans un hook de pré-commit ou comme étape de pipeline. Notez qu’un constat de forme des noms est consultatif : aggrega lint le signale et se termine tout de même avec succès, de sorte qu’un pipeline qui veut conditionner son passage à la convention lit les constats signalés plutôt que de se fier au code de sortie.
Une politique par espace de travail désactive la règle :
# .aggrega-config.yaml — lint sectionlint: publishing_discipline: allow_nonstandard_names: true # default falseLorsque la politique est définie, la règle de forme des noms ne signale plus rien du tout. Elle peut aussi être définie pour une seule invocation avec aggrega lint --allow-nonstandard-names, ou désactivée de force à nouveau avec --no-allow-nonstandard-names. Les usages légitimes sont les catalogues qui ne seront jamais publiés, les expérimentations multi-éditeurs et les entités à usage spécial.
11. Expansion des Feature pilotée par les annotations
Le bloc mappings.features.annotations du Manifest déclare des liaisons entre des clés d’annotation et des types de Feature, ainsi qu’une table de routage regroupée par pilier (maps.infra, maps.values) qui nomme les propriétés du schéma de la Feature que chaque annotation peut renseigner. La sous-phase d’expansion des annotations de la résolution 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, calcule les ensembles effectifs d’annotations par composant par cascade et surcharge avec un opt-out null sur la valeur entière et par sous-clé, et injecte des rattachements synthétiques de Feature qui portent origin: annotation dans leur provenance IR. L’enseignement complet sur la forme des liaisons et la rédaction se trouve dans language-reference/entities/manifest.md et language-reference/providers/well-known-annotations.md ; cette section documente les mécanismes au chargement du catalogue et à l’inspection sur lesquels repose le chemin d’expansion.
Cache de compilation des schémas. Le spec.schema.{infra,values} de chaque Feature est compilé une fois par build et réutilisé d’un parcours en cascade à l’autre. La validation de type répétée par sous-clé par rapport au même schéma de Feature (une portée de cascade par composant, pour des centaines de composants) lit le schéma compilé au lieu de le compiler à nouveau. Rien n’est conservé entre les builds, de sorte qu’un schéma de Feature modifié est compilé à neuf par le build suivant.
Validation des cibles de liaison (chargement du catalogue). Au chargement du catalogue, le compilateur parcourt chaque liaison features.annotations du Manifest et vérifie que chaque chemin pointé déclaré sous maps.infra et maps.values correspond à une propriété que le spec.schema.<pillar> de la Feature référencée déclare effectivement. Une liaison qui route vers un chemin que le schéma de la Feature ne liste pas interrompt le chargement du catalogue avec un OPS_ERROR clair qui nomme la clé de liaison, le chemin manquant, l’URI de la Feature et l’emplacement dans la source.
Lint de chevauchement des piliers de schéma (chargement du catalogue). Un avertissement consultatif est émis lorsque le spec.schema d’une Feature déclare le même nom de propriété dans les deux piliers infra et values. Le chevauchement est rarement intentionnel — des propriétés de même nom dans des piliers différents brouillent l’intention de rédaction (quel pilier s’applique lorsqu’une annotation cible le nom partagé ?) et compliquent les messages de diagnostic. L’avertissement n’est pas bloquant et n’a pas d’opt-out : un auteur qui veut le chevauchement le conserve avec l’avertissement, et celui qui ne le veut pas renomme la propriété dans un pilier.
Lint de chevauchement des maps de liaison (résolution). Un avertissement consultatif est émis lorsqu’un chemin de sous-clé apparaît à la fois sous maps.infra et sous maps.values dans les liaisons du Manifest. Un chemin présent dans les deux listes de piliers est incohérent — une même sous-clé d’annotation ne peut pas router vers les deux piliers simultanément, et le départage déterministe qu’applique le compilateur (un chemin présent dans les deux listes route vers infra ; une annotation écrite dans l’Aggregate ne peut router que par values, de sorte qu’une annotation écrite là pour ce chemin est refusée) est un filet de sécurité, et non une forme de rédaction prévue. L’avertissement n’est pas bloquant ; les auteurs qui ignorent l’avertissement obtiennent tout de même un build propre, le départage restant visible dans la provenance IR.
Affichage de la provenance par aggrega inspect. La commande inspect affiche un crochet par rattachement de Feature, qui enregistre la source de chaque feuille renseignée :
[explicit]— la Feature a été rattachée explicitement via un blocfeatures:d’un Aggregate ou d’une Release.[annotation: <key> from <source>]— chaque feuille renseignée provient de la même clé d’annotation. Le crochet nomme la clé et l’endroit où l’annotation a été déclarée : le fichier, et le chemin de clé pointé à l’intérieur.- Crochets par feuille — composition inter-côtés où chaque feuille renseignée est affichée avec son propre crochet de source (certaines
[explicit], certaines[annotation: <key> from <source>]). Cette forme met en évidence la fusion où l’explicite l’emporte champ par champ : lorsqu’un rattachement explicite et une contribution d’annotation ciblent la même instance de Feature sur le même Component mais écrivent des feuilles différentes, les deux contributions restent sur leurs feuilles respectives et la sortie d’inspect nomme individuellement la source de chaque feuille.
L’affichage d’inspect lit les maps par pilier values_provenance et infra_provenance de l’IR — renseignées pendant l’expansion des annotations en même temps que l’injection des rattachements synthétiques — et émet la forme de crochet qui résume le mieux la source collective des feuilles. Le mécanisme d’inspect est la surface d’introspection canonique pour comprendre pourquoi un rattachement de Feature donné a abouti sur un Component donné et d’où proviennent ses valeurs.