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

Manifest

Le rôle conceptuel de l’entité Manifest (Domaine 4 — la table de correspondance qui lie des interfaces abstraites à des Recipes concrètes) est décrit dans architecture/04-entity-taxonomy.md. Cette page couvre la surface de rédaction du Manifest : sa place à côté de la Release, la forme de la correspondance à URI plates, la composition via extends, les règles d’abréviation des URI, les liaisons de Feature pilotées par les annotations et le préfixe aggrega.ai/ réservé à la plateforme.

Manifest et Release : séparation des responsabilités

Le Manifest et la Release portent des responsabilités qui ne se recoupent pas :

  • Le Manifest dicte quelle Recipe réalise chaque type du catalogue et, via le spec.capability de cette Recipe, le provider (par ex. Helm, Helm-chart, Compose) qui le rend. C’est la table de correspondance — un enregistrement par projet, commité dans Git, de la Recipe concrète qui implémente chaque interface abstraite ; les versions et les digests auxquels un build astreint ces Recipes sont épinglés séparément, dans le lockfile de chaque Release.
  • La Release dicte la destination (par ex. le dossier de sortie physique pour la génération d’artefacts GitOps). C’est le routeur de déploiement — une description, par environnement, de l’endroit où arrivent les artefacts compilés.

Le schéma de la Release ne comporte aucun champ provider, à aucun niveau d’imbrication ; le dispatch vers le provider appartient exclusivement au Manifest.

Le chemin de compilation. Lorsqu’un utilisateur exécute aggrega build --release release.yaml, le compilateur résout les artefacts physiques en joignant les deux sources :

  1. Lecture de la destination. Le compilateur parcourt les frontières de la Release — par exemple, la frontière ovh-cluster-3 contient le composant user-db (type : core/postgres:1.0.0).
  2. Examen du Manifest. Il ouvre le Manifest vers lequel la Release pointe via son champ manifest:.
  3. Recherche à deux niveaux. Il vérifie d’abord le niveau name pour "user-db". S’il ne le trouve pas, il vérifie le niveau type pour "core/postgres:1.0.0" (versionné), puis "core/postgres" (non versionné).
  4. Résolution de la Recipe. La valeur de l’entrée correspondante est une URI de Recipe ; la Recipe qu’elle nomme déclare dans spec.capability quel provider la rend.
  5. Génération de la sortie. Le compilateur connaît désormais le dossier cible (dist/boundaries/ovh-cluster-3/), le provider (rendu Helm via Wasm) et l’artefact (le code source de la Recipe). Les frontières GitOps ahead-of-time sont respectées de bout en bout.

Mappage d’URI plat

Le bloc mappings: du Manifest est une table plate qui associe un URI de type de composant à un URI de Recipe (et un URI de type de fonctionnalité à un URI de FeatureRecipe). Le mappage est agnostique vis-à-vis de la capacité au niveau du Manifest ; la détermination de la capacité découle du champ spec.capability de chaque Recipe résolue au moment du rendu, et non de la forme structurelle du Manifest. Le bloc organise les mappages sous deux clés de premier niveau :

  • components.type associe un URI de type de composant à un URI de Recipe. Chaque instance de composant du type déclaré se résout vers la Recipe indiquée. Le mappage est biunivoque par type de composant. Une clé qui ne nomme pas le type exact d’une instance l’atteint tout de même par la base du type, lorsqu’aucune clé ne nomme ce type exact et qu’aucune autre clé n’est écrite pour la même base — ainsi une clé écrite sans version (core/postgres), ou une clé nommant une autre version (core/postgres:1.0.0), peut atteindre une instance de core/postgres:2.0.0 — mais la Recipe qu’elle nomme doit implémenter la version propre de chacune de ces instances : une instance de core/postgres:2.0.0 atteinte de cette façon et associée à une Recipe déclarant implements: core/postgres:1.0.0 arrête le build. Associez une telle instance, avec une clé nommant sa version (core/postgres:2.0.0), à une Recipe qui l’implémente.
  • features.type associe un URI de type de fonctionnalité à un URI de FeatureRecipe. Chaque rattachement de Feature du type déclaré se résout vers la FeatureRecipe indiquée. Les Features d’identifiants (étiquetées feature.aggrega.ai/kind: secret) se trouvent dans la même table features.type que les Features opérationnelles — le modèle d’entité Feature unifié.

Chaque bloc accepte aussi un niveau name à côté de type, qui associe un nom d’instance précis à un URI de Recipe (ou de FeatureRecipe). Le niveau des noms a priorité sur le niveau des types : une instance nommée dans components.name se résout vers cette Recipe, tandis que toutes les autres instances du même type se résolvent via components.type. Cela exprime une substitution par instance — deux instances d’un même type de composant peuvent être déployées via deux Recipes différentes (par exemple, la plupart des instances de base de données utilisent la Recipe associée en bloc tandis qu’une instance est épinglée à une implémentation physique différente), sans forker le type de composant ni dupliquer le Manifest. La substitution s’applique uniformément : l’instance nommée est à la fois rendue via la Recipe de substitution et épingle sa source depuis celle-ci. features.name est le niveau symétrique pour les rattachements de Feature, indexé par le nom propre du rattachement — la clé sous laquelle il est écrit dans les features: d’un composant — jamais par le nom du composant auquel il est rattaché. L’exemple de substitution de recette par instance parcourt de bout en bout un cas minimal à deux instances.

Un rattachement porté par une connexion est indexé par le nom qu’il prend sur le composant consommateur : <alias>.<slot>, l’alias sous lequel la connexion est écrite, un point, et l’emplacement que le rattachement occupe (voir l’entrée de connexion de l’Aggregate). Ainsi, l’identifiant d’une connexion peut être réalisé différemment de tout autre rattachement de son type :

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

L’entrée est épinglée et vérifiée comme toute autre entrée du niveau des noms, comme le décrit le paragraphe suivant. La Feature que nomme le rattachement est elle aussi épinglée et vérifiée, exactement comme l’est la Feature d’un rattachement écrit sur le composant lui-même, sous l’entrée de connexion qu’a écrite son auteur — voir Le lockfile.

Une clé name doit nommer quelque chose que le build contient. Le niveau est mis en correspondance par nom exact, de sorte qu’une clé components.name qui n’est pas une instance de composant du build, ou une clé features.name qui n’y est pas un rattachement — le plus souvent le nom du composant sur lequel se trouve un rattachement, écrit là où devrait figurer le nom propre du rattachement — ne serait consultée par rien, et les instances auxquelles elle était destinée se résoudraient silencieusement via le niveau type. Le build s’arrête plutôt sur une telle clé, avant tout rendu, en nommant le Manifest, la clé, les noms de cette sorte que le build contient, et le nom que vous vouliez probablement indiquer — voir A Manifest name mapping names nothing in the build (Un mappage par nom du Manifest ne nomme rien dans le build).

Une réalisation liée par nom est épinglée et vérifiée comme une réalisation liée par type. aggrega pull acquiert chaque Recipe et chaque FeatureRecipe que l’un ou l’autre niveau lie — depuis un répertoire de catalogue, le cache ou un registre — et enregistre chacune dans le lockfile de la Release avec sa version résolue et son condensat de contenu, sous l’entrée de mappage qui la lie : manifest.spec.mappings.components.name.<instance> pour une entrée du niveau des noms, à côté de manifest.spec.mappings.components.type.<type> pour une entrée du niveau des types. aggrega build tient chacune d’elles à son épinglage. Un lockfile qui n’enregistre aucune ligne pour une réalisation que le Manifest lie arrête le build comme obsolète, en nommant la réalisation et l’entrée qui la lie ; une réalisation dont le contenu a changé depuis le pull l’arrête de la même façon, en nommant les deux condensats. Dans les deux cas, aggrega pull --release <release> enregistre la réalisation telle qu’elle est à présent. Comme une entrée type, une entrée name est épinglée que la Release déclare ou non une instance de ce nom, de sorte qu’une entrée name nommant une Recipe qu’aucun catalogue ni registre ne contient arrête le pull ; une entrée name ne nommant aucune instance que le build contient est également épinglée, et arrête le build comme le décrit le paragraphe précédent.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Détermination de la capacité au moment du rendu. L’entrée du Manifest lie un type de composant à un URI de Recipe. Un URI de Recipe comporte au plus deux segments — une capacité initiale facultative, puis le nom de la recette — plus un :version facultatif ; le résolveur ne découpe que sur le premier /, de sorte qu’une référence comportant un troisième segment ne nomme aucune recette et arrête la résolution. Au moment du rendu, le résolveur charge la Recipe par une recherche directe d’URI dans le lockfile et le catalogue, et le champ spec.capability de chaque Recipe détermine le regroupement de répartition par (chemin, capacité). La forme structurelle du Manifest reste plate, quel que soit le nombre de fournisseurs que prend en charge le catalogue au sens large.

Recherche directe d’URI

La valeur de mappage du Manifest est un URI de Recipe. Le compilateur résout l’URI directement dans le lockfile et le catalogue, et renvoie la Recipe correspondante. Il ne parcourt pas les déclarations spec.implements pour trouver une Recipe qui « implémente » un type de composant. Chaque entrée du Manifest lie le type de composant écrit par le développeur à un URI de Recipe précis ; le choix est explicite et sans ambiguïté dans le contenu du Manifest.

spec.implements est une vérification de cohérence sur la table de mappage. La valeur spec.implements de la Recipe résolue DOIT correspondre à la clé de type de composant du Manifest pour cette entrée de mappage — ou à une base que cette clé étend par extends, à n’importe quelle profondeur de la chaîne, puisqu’une Recipe écrite pour une base implémente tout ce qui l’étend. Une valeur ne correspondant à aucune des deux produit un OPS_ERROR avec un diagnostic clair nommant l’entrée du Manifest, la Recipe résolue et la valeur spec.implements en conflit. La vérification s’exécute une fois par entrée de mappage du Manifest, sur le Manifest composé et avant toute résolution de Recipe — statique, déterministe, et sans rien parcourir au-delà de la propre chaîne extends du type mappé. Une clé components.type qui atteint une instance de composant à une version qu’elle ne nomme pas est jugée une fois de plus pour cette instance, de la même façon, le type propre de l’instance, à la version sous laquelle le build la compile, prenant la place de la clé, comme le décrit Mappage d’URI plat. Voir ../vocabulary/inheritance-and-interface.md pour ce que la Recipe d’une base épargne ou non à une spécialisation.

Chaque commande qui lit les dépendances d’une Release l’exécute, et chacune décide elle-même de ce que signifie un constat : aggrega build et aggrega pull s’arrêtent, puisque toutes deux produisent quelque chose que vous utiliseriez ensuite, tandis que aggrega validate et aggrega lint le signalent avec le reste de leurs constats et se terminent avec un code non nul, et l’éditeur le publie comme un diagnostic parmi les autres. aggrega lint est l’exception pour le jugement d’une instance : elle juge les entrées de mappage et non les instances qu’elles atteignent, et ne le signale donc pas, tandis que aggrega build, aggrega pull et aggrega validate --release le signalent. Voir ../errors/fatal-halts.md pour le diagnostic et la manière de le corriger.

La vérification de cohérence est la seule surface de mappage qui lit la chaîne extends. La sélection de la Recipe reste exacte sur la clé de mappage : un type de composant qui étend une base mappée a tout de même besoin de sa propre entrée ici, et n’en reçoit aucune par héritage.

spec.implements suggère aussi des candidates. Une instance dont le type n’a aucun mappage dans le Manifest arrête le build avec un OPS_ERROR qui liste comme candidates à l’épinglage les recettes dont le spec.implements peut implémenter ce type ; la complétion de l’éditeur sur une valeur de mappage classe ces mêmes recettes correspondantes en premier. Les deux surfaces lisent spec.implements par rapport au type demandé lui-même, de sorte qu’une recette implémentant l’une des bases de ce type n’est pas proposée comme candidate même si le mappage serait jugé cohérent. spec.implements déclare donc ce qu’une recette peut implémenter et éclaire le choix de la personne — dans la vérification de cohérence, le diagnostic d’absence de mappage et la complétion — mais il ne résout jamais un build. Le mappage du Manifest est le choix de déploiement explicite de l’utilisateur, épinglé dans le lockfile pour la reproductibilité ; le catalogue ne choisit jamais un déploiement à la place de l’utilisateur.

Trois formes pour le segment de version de l’URI

Un URI de Recipe dans le Manifest peut porter la version sous l’une de trois formes :

  • Exacte — helm/postgres:1.2.0. Le lockfile doit épingler exactement cette version ; à la première résolution du lockfile, le résolveur épingle cette version ; si le catalogue ou le registre ne contient pas cette version au moment de la résolution, le chargement de l’espace de travail s’arrête avec une erreur.
  • Plage — helm/postgres:^1.2.0. Plage semver avec la règle MVS standard ; à la première résolution du lockfile, le résolveur épingle la version disponible la plus élevée qui satisfait la plage.
  • Sans version — helm/postgres. Aucun suffixe :version ; à la première résolution du lockfile, le résolveur épingle la dernière version disponible.

Les builds suivants utilisent la version épinglée dans le lockfile, quelle que soit la forme saisie par l’utilisateur. Résoudre à nouveau 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, ou aggrega pull --upgrade --release <release> les résout toutes à nouveau — le lockfile est la source de vérité pour les builds ; la forme saisie par l’utilisateur est la manière dont celui-ci exprime la contrainte de version au moment de l’écriture.

Références qualifiées par capacité

L’identité d’une Recipe dans le catalogue est délimitée par la capacité : deux recettes peuvent partager un metadata.name et une version tout en déclarant des valeurs spec.capability différentes. L’identité dans le registre est recipe/{capability}/{name}:{version}, dérivée du type de la recette, de son spec.capability sans l’éventuel épinglage de version qu’il porte, et de son nom ; l’arborescence du catalogue de la bibliothèque standard reflète cette coordonnée sous recipe/{capability}/{name}/ par convention. Une valeur de mappage du Manifest nomme la recette selon l’une ou l’autre précision :

  • Simple — mariadb:1.0.0. Se résout lorsque exactement une recette du catalogue porte ce nom ; la forme dominante en pratique.
  • Qualifiée par capacité — compose/mariadb:1.0.0. Le segment avant le premier / nomme le spec.capability de la recette, sans son épinglage de version — un épinglage écrit dans la référence est refusé (E0095). Obligatoire lorsque plus d’une recette fournit le même nom : une référence simple correspondant à deux recettes est ambiguë et s’arrête explicitement à la résolution plutôt que d’en choisir une silencieusement.

Un URI de Recipe n’a pas d’autres positions. Le résolveur ne découpe que sur le premier /, de sorte que compose/mariadb nomme la capacité compose et la recette mariadb, et qu’une référence à trois segments ne correspond à aucune recette, quelle que soit la précision.

Les formes du segment de version ci-dessus s’appliquent aux deux variantes.

Entités publiées dans un registre dans les mappages

Une entité consommée depuis un registre plutôt que depuis un catalogue local est référencée par exactement la même identité qu’une entité locale : la référence ne porte aucun hôte de registre ni aucun segment de type d’entité. Le résolveur fournit les deux — l’hôte à partir du registre par défaut configuré dans l’espace de travail, le segment de type à partir de l’endroit où la référence se trouve dans le schéma — selon les règles des URI abrégés sensibles au contexte ci-dessous. Lorsque ni un répertoire de catalogue local ni le cache n’en contient une copie, aggrega pull — ou un build exécuté avec --auto-pull — récupère l’entité à l’emplacement dérivé, la met en cache, et épingle la version résolue et le condensat de contenu dans le lockfile ; les builds suivants consomment le cache sans accès réseau.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Comme l’hôte et le segment de type d’entité sont dérivés plutôt qu’écrits, écrire l’un ou l’autre dans la référence ne désigne pas l’entité publiée — cela produit une identité qu’aucune entrée de catalogue ne porte. Une référence à un Component ou à une Feature est son metadata.name tel quel, plus un :version facultatif, que l’entité se résolve depuis le catalogue local, depuis le cache ou depuis un registre. Un espace de travail qui consomme un registre privé nomme cet hôte dans sa propre configuration plutôt que dans chaque référence.

Vérification d’exhaustivité

Une fois tous les mappages résolus, le compilateur vérifie que chaque instance de composant et de rattachement (une Feature d’identifiants est un rattachement comme un autre) de l’Aggregate du développeur a une Recipe ou une FeatureRecipe résolue. Les entités non mappées provoquent un arrêt fatal avec un diagnostic explicite qui liste chaque entité manquante et suggère quelle clé components.type ou features.type ajouter pour combler le manque.

Ancres YAML pour des manifestes DRY

Pour éviter l’encombrement YAML dans les grands ensembles de mappages, le Manifest prend en charge un bloc defs: facultatif pour les ancres YAML standard (& et *) :

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Négociation de Feature

La poignée de main de capacité utilise le même mappage d’URI plat :

  1. Le développeur rattache core/data-masking à un composant dans l’Aggregate, sous un nom qui lui est propre dans la table features: de ce composant.
  2. Le compilateur recherche core/data-masking dans la table features.type du Manifest.
  3. Si la recherche se résout vers un URI de FeatureRecipe (par ex. helm/data-masking-litellm:1.0.0), la capacité existe et le pipeline de la FeatureRecipe s’exécute dans l’ordre défini.
  4. Si features.type ne contient aucune entrée correspondante, le compilateur arrête le build et liste la Feature non mappée.

Le Manifest accepte aussi un bloc features.annotations — une surface d’écriture parallèle qui permet à un sous-système d’une Release ou d’un Aggregate de rattacher des Features par clé d’annotation plutôt que par déclaration par composant. La forme de la liaison, la partition side-vs-pillar qui détermine quelle surface d’écriture utilise quels chemins de routage, la discipline selon laquelle le rattachement explicite l’emporte, et la règle des valeurs par défaut du schéma se trouvent dans la section dédiée Liaisons de Feature pilotées par annotation plus bas.

Composition via extends

Un Manifest peut déclarer une seule référence extends: nommant un Manifest de base dont il hérite les mappings. La référence n’est pas un URI et n’est jamais résolue via le catalogue : un Manifest relève du côté déploiement, rédigé à côté de la Release plutôt que publié ; la valeur est donc soit un chemin relatif vers un fichier de Manifest — ./base-manifest.yaml — soit le simple metadata.name d’un Manifest situé dans le répertoire même de la Release. Un chemin relatif doit mener à un Manifest à l’intérieur du workspace — ou, lorsque la Release a été désignée hors du workspace (sur la ligne de commande ou par la configuration du workspace), à l’intérieur du répertoire qui contient cette Release, et pour un Manifest que vous désignez seul sur la ligne de commande hors du workspace, à l’intérieur du répertoire qui contient le Manifest : un chemin qui en sort en remontant, ou qu’un lien symbolique fait sortir, est refusé avant que le fichier qu’il désigne soit lu (voir errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Une référence à un autre fichier sort du répertoire dans lequel elle doit rester)”). Les mappings enfants écrasent ceux de la base en cas de collision de clés, ce qui prend en charge les schémas de surcouche par environnement (parité staging/prod avec des différences chirurgicales par environnement) et les schémas de développement local sans copie intégrale.

Sémantique de fusion. Lorsqu’un Manifest local étend un Manifest de base, le compilateur effectue un remplacement superficiel des clés par niveau — les dictionnaires type et name sont fusionnés indépendamment, sans fusion profonde — ce qui garantit des recherches en O(1) dans les dictionnaires et rend le comportement de l’héritage prévisible. Au sein de chaque niveau, les clés enfants écrasent les clés parentes.

Le schéma de pont pour le développement local. Un usage courant de extends consiste à remplacer une FeatureRecipe d’identifiants pour le prototypage local sans toucher à l’Aggregate. En production, le Manifest de base associe la Feature d’identifiants core/aws-secrets-manager à une FeatureRecipe de production dans le niveau features.type. Pour le prototypage local, l’équipe plateforme fournit un local-manifest qui étend la base et remplace chirurgicalement l’association de la Feature d’identifiants pour utiliser host-env-injector — une FeatureRecipe locale qui livre l’identifiant dans le fichier Compose sous forme de référence de variable telle que ${SECRET_NAME}, que Docker Compose substitue à partir de l’environnement du shell ou d’un fichier .env au démarrage de la stack. Le développeur bénéficie d’un flux de travail local standard, et l’Aggregate reste agnostique vis-à-vis des capacités pour la production.

URI abrégés sensibles au contexte

Le compilateur Aggrega utilise l’inférence sensible au contexte lorsqu’il résout les URI OCI dans les Manifests. Si un ingénieur omet le nom de domaine complet (Fully Qualified Domain Name, FQDN) et le type d’entité architecturale, le compilateur se rabat automatiquement sur le registre par défaut (configuré dans .aggrega-config.yaml) et déduit le type d’entité d’après l’emplacement de la chaîne dans le schéma.

Les règles d’inférence :

  1. Domaine par défaut : tout URI dépourvu de domaine (par ex. python-worker-helm:1.0) est préfixé par le default_registry configuré (par défaut : hub.aggrega.ai/).
  2. Expansion contextuelle de l’entité : le compilateur ajoute le chemin d’entité correct d’après le dictionnaire strict du schéma :
    • Les chaînes sous Aggregate.spec.components[].type sont étendues en /component/.
    • Les chaînes sous Aggregate.spec.aggregates[].type sont étendues en /aggregate/.
    • Les chaînes sous Manifest.spec.mappings.components.type ou Manifest.spec.mappings.components.name sont étendues en /recipe/.
    • Les chaînes sous Manifest.spec.mappings.features.type ou Manifest.spec.mappings.features.name sont étendues en /featurerecipe/. Cela inclut les Features d’identifiants (étiquetées feature.aggrega.ai/kind: secret) — elles utilisent le même chemin de FeatureRecipe.
    • Les chaînes affectées à pipeline[].plugin sont étendues en /plugin/.
  3. Précédence à trois niveaux : avant d’appliquer l’inférence OCI, le compilateur parcourt les répertoires de catalogue du workspace et le cache d’artefacts (le niveau workspace et cache), comme défini dans le modèle de résolution des entités à trois niveaux. L’inférence OCI ne s’applique que lorsque l’entité atteint le niveau du registre. Une clé ou une valeur de mapping n’est jamais lue comme un chemin de fichier : une Recipe ou une FeatureRecipe rédigée localement se trouve dans un répertoire de catalogue — catalog/ à la racine du workspace, ou l’un de ceux que liste workspace.catalog_dirs — et est désignée par sa référence.

L’abréviation en action :

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

Pas de préfixe ops/. Les noms de Recipe ne portent pas de préfixe ops/ — le répertoire de type d’entité recipe/ de la taxonomie OCI identifie déjà le domaine, et les Recipes sont publiées sous recipe/{capability}/{name} sans préfixe supplémentaire. Les Manifests référencent les Recipes par {capability}/{name}, ou par le nom simple pour l’inférence sensible au contexte. Voir architecture/13-catalog-and-registry.md §6 pour la taxonomie OCI complète.

Liaisons de Feature pilotées par annotation

Le bloc features.annotations du Manifest déclare des liaisons entre des clés d’annotation et des types de Feature, ainsi que les chemins de routage par lesquels chaque liaison envoie la valeur de l’annotation. La liaison est la surface de rédaction permettant de condenser les rattachements de Feature répétitifs par composant — le schéma où des dizaines de composants d’un même périmètre portent chacun un bloc features: identique — en déclarations d’annotation uniques sur les périmètres de Release ou les sous-systèmes d’Aggregate.

Forme du schéma :

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

Une liaison porte un champ feature nommant le type de Feature cible et un bloc maps regroupant les routes de sous-clés en chemins pointés par pilier cible. Le champ feature référence un type de Feature qui doit aussi apparaître dans la section sœur features.type (où se trouve la liaison de version de la FeatureRecipe). Le bloc maps déclare deux listes indexées par pilier — maps.infra et maps.values — portant chacune des chaînes de chemins pointés qui désignent les propriétés spec.schema.<pillar>.<path> de la Feature cible. Une liaison doit déclarer au moins un chemin sur l’ensemble des deux listes (le JSON Schema impose minProperties: 1 sur maps).

Le polymorphisme de Provider pour une même clé d’annotation — par ex. feature.aggrega.ai/rewrite-host lié à core/k8s-dns-resolver dans un déploiement Kubernetes mais à core/compose-bridge dans un déploiement Compose local — s’exprime en choisissant des types de Feature différents dans des Manifests différents ; chaque Manifest lie l’annotation à une seule Feature, et la FeatureRecipe de la Feature choisie porte l’implémentation propre au provider.

La partition côté/pilier. L’invariant de l’Aggregate comme surface de rédaction restreint chaque côté de rédaction aux chemins de routage d’un seul pilier. Les annotations côté Aggregate ne passent que par les chemins maps.values ; les annotations côté Release ne passent que par les chemins maps.infra. Une liaison déclarant des chemins dans les deux piliers prend en charge la composition inter-côtés : une annotation côté Aggregate déclenche le sous-ensemble du pilier values ; une annotation côté Release sur la même clé déclenche le sous-ensemble du pilier infra ; les deux contributions se composent en un seul rattachement de Feature par paire (Component, Feature) avec les deux piliers renseignés. Une incohérence côté/pilier — par ex. une annotation côté Aggregate sur une liaison ne déclarant que maps.infra — arrête le build avec un diagnostic clair nommant la clé d’annotation, le pilier routé, le côté de rédaction et l’emplacement source, classé sous le domaine du document dans lequel la valeur de l’annotation a été rédigée.

Validation des cibles de chemin. Au chargement du catalogue, le compilateur vérifie que chaque chemin pointé déclaré sous maps.infra et maps.values correspond à une propriété que spec.schema.<pillar> de la Feature cible déclare réellement. Une liaison qui route vers un chemin que le schéma de la Feature ne liste pas arrête le chargement du catalogue avec une OPS_ERROR claire, nommant la liaison, la Feature cible, ainsi que le pilier et le chemin par lesquels elle a routé. Les formes de schéma qui échappent à un simple parcours des propriétés ($ref, patternProperties, composition oneOf / anyOf / allOf) terminent la vérification statique à cette branche et laissent la validation de schéma en aval détecter toute incohérence.

Formes des valeurs d’annotation. Une liaison consomme des valeurs d’annotation sous trois formes. Scalaire — une seule valeur YAML (chaîne, nombre, booléen). Un scalaire associé à une liaison déclarant exactement un chemin sur l’ensemble des deux piliers route la valeur vers ce chemin unique ; un scalaire associé à une liaison déclarant plus d’un chemin constitue un routage ambigu et arrête le build avec un diagnostic clair, classé sous le domaine du document dans lequel la valeur de l’annotation a été rédigée. Structurée — une map YAML dont chaque sous-clé de premier niveau correspond à une entrée de chemin pointé sous maps.infra ou maps.values ; chaque sous-clé est routée indépendamment vers son pilier déclaré, et la partition côté/pilier s’applique par sous-clé. null YAML explicite — désactive la liaison héritée à la portée de la cascade (un null par sous-clé à l’intérieur d’une valeur structurée désactivant des sous-clés individuelles tandis que leurs voisines restent en place). Pour la présentation de référence de la rédaction des valeurs structurées — fusion en cascade par sous-clé, composition inter-côtés, validation de type par sous-clé, la discipline du défaut assoupli pour les champs de schéma sans type déclaré — voir providers/well-known-annotations.md §“Valeurs d’annotation structurées”.

Le rattachement explicite l’emporte en cas de collision de clés. Lorsqu’un composant de Release ou un composant d’Aggregate porte à la fois une entrée features: explicite et une annotation qui s’étend vers la même clé de Feature, l’entrée explicite est conservée et l’expansion de l’annotation pour cette clé sur ce composant est sans effet. Le rattachement synthétique n’écrase jamais une instance de Feature déclarée par l’auteur. Les auteurs peuvent donc utiliser l’expansion d’annotation pour la majorité des composants et remplacer chirurgicalement des composants individuels en écrivant une entrée features: explicite avec la même clé — l’entrée explicite porte la personnalisation propre au composant, l’annotation se propage en cascade sans changement à tous les autres composants.

L’explicite l’emporte par feuille dans la composition inter-côtés. Lorsqu’un rattachement explicite et une contribution d’annotation renseignent tous deux la même instance de Feature mais écrivent des feuilles différentes, les deux contributions restent en place et la Feature résultante porte les deux feuilles, avec une provenance par feuille qui enregistre la source de chacune. Lorsqu’un rattachement explicite et une contribution d’annotation ciblent la même feuille au sein du même pilier, la contribution explicite l’emporte et l’IR enregistre la provenance de l’annotation supprimée comme marqueur de remplacement sur cette feuille. Le chargement du catalogue signale ce remplacement au moment du build par un avertissement de lint consultatif nommant la clé d’annotation supprimée + la source.

Valeurs par défaut du schéma au moment de l’expansion. Le rattachement de Feature synthétique produit par l’expansion d’annotation ne porte que les feuilles que la valeur de l’annotation renseigne via les chemins déclarés de la liaison. Les valeurs par défaut déclarées dans spec.schema de la Feature cible ne sont pas fusionnées dans le rattachement synthétique au moment de l’expansion. La matérialisation des valeurs par défaut relève de la couche de rendu de la FeatureRecipe, appliquée uniformément aux rattachements explicites et synthétiques afin que les deux chemins produisent la même sortie en aval pour la même configuration effective.

Séparation des espaces de noms d’annotation :

PréfixePropriétaireObjectif
aggrega.ai/Plateforme Aggrega uniquementAnnotations natives de la plateforme lues directement par le provider (par ex. aggrega.ai/namespace).
feature.aggrega.ai/Bibliothèque standard officielleRaccourcis d’annotation de Feature liés dans le Manifest.
{any-other-domain}/Entreprise / communautéRaccourcis d’annotation de Feature personnalisés.

Réservation du préfixe aggrega.ai/

Les liaisons features.annotations d’un Manifest ne peuvent pas utiliser le préfixe aggrega.ai/ seul — il est réservé aux annotations natives de la plateforme émises par le compilateur (labels OTel/de provenance, etc.). Les sous-préfixes délimités (component.aggrega.ai/*, compliance.aggrega.ai/*, acme.aggrega.ai/* d’entreprise) restent disponibles pour la rédaction par les utilisateurs. Voir providers/well-known-annotations pour l’ensemble des annotations réservées à la plateforme.