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

Surface de publication

Chaque YAML de catalogue Aggrega porte un ensemble uniforme de champs de métadonnées qui décrivent l’entité pour la distribution en catalogue : qui la maintient, sous quelle licence elle est distribuée, où se trouve sa source, quels mots-clés la font ressortir dans la recherche. Ensemble, ces champs constituent la surface de publication — le vocabulaire de métadonnées sur lequel s’appuient les éditeurs de catalogues et les outils qui le consomment, distinct du mécanisme côté contenu metadata.labels / metadata.annotations documenté dans labels-and-annotations.md.

Cette page documente les champs de la surface de publication, l’inventaire des champs de description dans le corpus (descriptions de l’enveloppe, de l’instance et au niveau du champ), l’usage prévu du champ maintainer et son consommateur vérifié, ainsi que les asymétries des champs obligatoires par entité (quels champs chaque entité exige aujourd’hui et où les asymétries sont délibérées).

Les champs de la surface de publication

Les champs suivants apparaissent sur chaque entité du Domaine 2 (Component, Feature) et du Domaine 3 (Recipe, FeatureRecipe, Plugin), ainsi que sur l’Aggregate en tant que module réutilisable. Ils apparaissent aussi sur le Manifest et la Release, avec une sémantique réduite (attribution à l’espace de travail plutôt que publication en catalogue).

ChampTypeObjectifConsommateur
descriptionstringRésumé lisible de l’entitéCartes de survol de l’éditeur (aggrega serve) ; l’outil describe qu’un assistant appelle (aggrega mcp) ; une annotation consultable sur l’artefact publié (aggrega push) ; aggrega inspect
maintainerstableau d’objetsQui possède l’entité (name, email, url)catalog_metadata par nœud dans l’IR, sur les nœuds Component
licensestringConformité juridique (généralement un identifiant SPDX)catalog_metadata par nœud dans l’IR, sur les nœuds Component
repositorychaîne (URL)Dépôt Git où se trouve la sourcecatalog_metadata par nœud dans l’IR, sur les nœuds Component — rien d’autre ne le lit
homechaîne (URL)URL de documentation / de wikicatalog_metadata par nœud dans l’IR, sur les nœuds Component — rien d’autre ne le lit
keywordstableau de chaînesTags de découvertecatalog_metadata par nœud dans l’IR, sur les nœuds Component — aucun index de recherche ne les consomme

Les six champs sont tous facultatifs sur chaque entité qui les porte. Un auteur de catalogue qui omet l’ensemble complet produit un YAML valide — la surface de publication est destinée aux entités prévues pour la distribution en catalogue ; les entités à usage interne peuvent l’omettre sans conséquence.

La colonne Consommateur est exhaustive pour ce qui est livré aujourd’hui, et deux de ses conséquences méritent d’être énoncées clairement, parce qu’elles changent ce qui vaut la peine d’être rédigé :

  • description est le seul champ ayant plus d’un lecteur. aggrega serve l’affiche dans la carte de survol pour Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest et les quatre types de bibliothèque (SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) — pas pour Plugin ni Release. L’outil describe qu’expose aggrega mcp le renvoie pour une entité de n’importe quel type. aggrega push l’appose sur l’artefact publié comme annotation consultable. aggrega inspect l’affiche sous l’en-tête de l’entité pour chaque type, et n’affiche aucun autre champ de la surface de publication.
  • repository, home et keywords sont validés et transportés, et rien ne les lit au-delà de l’IR. Aucune surface de listage, aucun site de catalogue ni aucun index de recherche ne les consomme. Les rédiger enregistre une provenance qui voyage avec l’entité et qui est lisible depuis la sortie de l’IR et par une politique de gouvernance ; cela ne rend l’entité trouvable nulle part.

La dépréciation n’est pas un champ de la surface de publication. Une entité est dépréciée en enregistrant un marqueur à son encontre dans le registre après la publication — un marqueur signé portant une sévérité (warning, error ou retracted), une raison et un remplacement, vérifié au moment du pull. Toute surface qui lit le lockfile le signale alors ; build.halt_on_deprecated_severity décide seulement s’il arrête aussi un build. Le marqueur n’est jamais rédigé dans le YAML propre de l’entité, et la raison est structurelle : un artefact publié est immuable, de sorte qu’un indicateur figé dedans au moment de la publication ne pourrait jamais exprimer une décision prise plus tard. L’avis de dépréciation qu’affiche aggrega inspect pour une entité de catalogue provient du marqueur, pour chaque type qu’il résout par son nom.

Consommation par l’IR — catalog_metadata par nœud

Le compilateur reporte les champs de la surface de publication de chaque Component dans le bloc catalog_metadata du nœud correspondant, visible dans le graphe IR que renvoie une exécution (aggrega inspect <release> --ir-graph). Le bloc contient maintainers, license, repository, home et keywords — les cinq champs que porte l’IR ; description n’en fait pas partie. Les outils construits sur le contrat du graphe IR y lisent les métadonnées plutôt que de relire le YAML du catalogue.

Nœuds Component uniquement. Le bloc est rempli en recherchant le type de composant du nœud dans le catalogue en tant que Component, de sorte que la surface de publication d’une Feature, d’une Recipe, d’une FeatureRecipe ou d’un Plugin n’atteint jamais l’IR — ces entités portent les champs, et les champs sont validés, mais aucun nœud IR n’en résulte.

catalog_metadata disparaît entièrement du JSON de l’IR lorsque chaque champ de la surface de publication du Component source est vide ou nul : le bloc est omis plutôt qu’émis avec des valeurs vides. La même entrée produit donc la même sortie compacte, ce qui garde le diff de l’IR stable d’une exécution à l’autre.

Une politique de gouvernance peut lire le bloc. Un plugin rattaché sous plugins.governance dans le rôle ir-verdict reçoit l’intégralité du graphe IR, nœud par nœud, y compris le catalog_metadata de chaque nœud Component — de sorte qu’une politique peut accepter ou rejeter un build selon le license, le repository, le home, les keywords ou les maintainers d’un nœud. Cette portée est propre au socket de gouvernance : le plugin de rendu d’un fournisseur reçoit une projection par nœud bornée qui n’inclut pas catalog_metadata, de sorte que les plugins de rendu ne peuvent pas lire ces champs.

Les trois types de description

Le champ description apparaît uniformément sur l’enveloppe, mais le corpus contient aussi des chaînes de type description à l’intérieur des déclarations de schéma (descriptions par champ) et à l’intérieur des corps de piliers (descriptions par instance). Trois types de description distincts coexistent ; le tableau ci-dessous les distingue.

TypeOù elle se trouveRédigé parObjectif
Description de l’enveloppemetadata.description sur chaque entitéÉditeur du catalogueRésumé de l’entité dans son ensemble, affiché dans les cartes de survol de l’éditeur et apposé sur l’artefact publié
Description de l’instanceChamp description à côté d’une déclaration par instance (p. ex. featuresSchema.<slot>.description, usesSchema.<socket>.description)Auteur du schémaDescription par slot / par socket / par port, pour les auteurs des entités consommatrices qui lisent la déclaration
Description du champAnnotation description: de JSON Schema 2020-12 à l’intérieur du contenu de schema: / featuresSchema: / usesSchema: (forme compacte ou JSON Schema complet en YAML)Auteur du schémaDocumentation par champ qui voyage avec le schéma

Les trois types partagent le mot « description » mais se situent à des niveaux structurellement distincts. La description de l’enveloppe s’applique à l’entité dans son ensemble ; la description de l’instance s’applique à une déclaration à l’intérieur d’un slot de schéma ; la description du champ s’applique à une valeur précise à l’intérieur d’un schéma typé. Pour les auteurs qui rédigent un Component :

  • Définissez metadata.description une fois pour l’entité Component elle-même.
  • Définissez featuresSchema.admin_password.description une fois par slot d’identifiants que le Component déclare.
  • Définissez des annotations description: par champ à l’intérieur du bloc schema: — en forme compacte (port: { type: integer, description: "..." }) ou en JSON Schema complet en YAML — pour documenter chaque champ à l’intention de quiconque lit le schéma du Component.

Les trois types ne se propagent pas en cascade et n’entrent pas en collision, et chacun atteint une surface différente — ou aucune :

  • Description de l’enveloppe — les cartes de survol de l’éditeur, les annotations consultables de l’artefact publié et aggrega inspect, selon la colonne Consommateur ci-dessus.
  • Description du champ — apparaît telle quelle dans l’extrait de schéma qu’affiche la carte de survol d’un Component ou d’une Feature. L’extrait couvre uniquement spec.schema et est tronqué à ses premières lignes, de sorte qu’une description plus profonde dans le bloc — ou une description à l’intérieur de featuresSchema: ou usesSchema: — n’y apparaît pas.
  • Description de l’instance — déclarée et transportée avec l’entité ; aucune surface livrée ne l’affiche à elle seule. aggrega inspect liste les sockets et les slots de fonctionnalités d’un Component sans leurs descriptions.

Intention du champ maintainer

Le champ maintainers porte un tableau d’objets, chacun avec name, email et url. L’intention et le consommateur vérifié :

Intention (informative + provenance dans l’IR). Le champ est informatif pour la publication en catalogue : l’intention architecturale est « qui est responsable de cette entité du catalogue » — un signal de propriété qui voyage avec l’entité. Aucune surface ne le présente comme une liste de contacts, et aucune vérification intégrée ne le compare à quoi que ce soit.

Consommateur vérifié (catalog_metadata par nœud). Le compilateur reporte le metadata.maintainers de chaque Component dans le catalog_metadata.maintainers du nœud correspondant dans l’IR, visible dans le graphe que renvoie aggrega inspect <release> --ir-graph lorsque le Component source en a déclaré un. C’est le seul lecteur du champ. Une politique de gouvernance rattachée sous plugins.governance dans le rôle ir-verdict le voit là, de sorte qu’une règle de propriété — chaque entité nomme au moins un maintainer, le domaine d’un maintainer correspond à un ensemble approuvé — peut s’exprimer sur l’IR plutôt que sur le YAML du catalogue. Aucune règle de ce type n’est livrée ; le socket est l’endroit où elle se place.

Le compilateur n’impose ni ne valide le contenu de maintainer au-delà de la forme structurelle de JSON Schema (name obligatoire ; email et url facultatifs, tous deux de type chaîne). Que les maintainers listés possèdent réellement l’entité, que leur e-mail soit joignable, qu’un commit du dépôt soit signé par l’un d’eux — ce sont des préoccupations de gouvernance du catalogue, et aucune vérification livrée n’en évalue aucune. Elles relèvent d’une politique de gouvernance qu’un opérateur rattache, pas du compilateur.

Asymétries des champs obligatoires

Les types d’entités d’Aggrega portent des ensembles de champs obligatoires légèrement différents dans leurs JSON Schemas. La plupart des asymétries sont délibérées et reflètent le rôle de l’entité.

Les champs obligatoires par entité (à l’exclusion de apiVersion / kind / metadata.name / metadata.version, que chaque entité exige uniformément) :

EntitéChamps obligatoires supplémentairesJustification
Componentmetadata.labels.component.aggrega.ai/typeL’exigence de label est porteuse pour la correspondance des sélecteurs : les annotations x-aggrega-selector: de usesSchema filtrent les Components cibles par ce label ; en son absence, le Component est refusé à son chargement
Feature—Aucune exigence de label réservé ; les Features s’identifient par nom + éditeur
Recipespec.capability, spec.implementsCapability conditionne la répartition vers le fournisseur ; implements conditionne la liaison au Component
FeatureRecipespec.capability, spec.implementsComme pour Recipe
Pluginmetadata.pluginType, spec.abiVersionLe type de socket que le plugin implémente (partie du bloc d’adressage, qui fournit le segment <pluginType> de la coordonnée dérivée plugin/<pluginType>/<name>) et la version d’ABI qu’il cible ; l’emplacement du .wasm est dérivé de cette identité plutôt que rédigé ; un plugin de rendu de fournisseur (pluginType: provider) porte en outre son contrat de traduction sous spec.provider
Aggregate—Un Aggregate ne déclarant aucun de components, subsystems ou aggregates se charge et se construit, et ne rend rien
Manifestspec.mappingsLes niveaux de mapping sont la seule raison d’être du Manifest
Releasespec.aggregate, spec.manifest (une Release déclarant extends n’écrit pas d’aggregate et peut omettre manifest) ; metadata.environmentLes deux premiers ancrent le build à un Aggregate + Manifest précis ; l’environnement est apposé sur la sortie rendue en tant que label aggrega.ai/environment

L’exigence de label Component est porteuse

Le label component.aggrega.ai/type est le seul label qu’Aggrega exige sur une entité. L’exigence existe parce que le mécanisme usesSchema de la bibliothèque standard filtre les candidats cibles via des annotations x-aggrega-selector: portant des chaînes de sélecteur comme "component.aggrega.ai/type=database" — le sélecteur consulte les labels de la cible pour déterminer si le type correspond aux types acceptés par le socket. Le schéma du Component l’impose : un Component qui omet le label est refusé à son chargement (E0215), avec le nom de la clé manquante.

L’exigence n’est donc pas une préoccupation de surface de publication (le label ne sert pas à la découverte en catalogue) mais une préoccupation de topologie : chaque Component le porte, y compris les Components à usage interne qui ne visent pas la distribution en catalogue.

Le metadata.environment de la Release est obligatoire

Le schéma de la Release exige metadata.environment, une chaîne que le build appose sur la sortie rendue en tant que label aggrega.ai/environment.

Autres asymétries

Les asymétries restantes (champs obligatoires de la Recipe par rapport au Component, l’exigence mappings du Manifest) reflètent le rôle de chaque entité. Les auteurs qui veulent un contrat uniforme de champs obligatoires pour tous les types d’entités ne le trouveront pas ; les asymétries sont délibérées selon la conception guidée par les rôles.

Références croisées

  • labels-and-annotations.md — mécanisme de métadonnées côté contenu qui complète la surface de publication.
  • entities/component.md — l’exigence metadata.labels.component.aggrega.ai/type du Component et les déclarations schema / usesSchema / featuresSchema.
  • entities/release.md — le champ metadata.environment de la Release et son exigence.
  • 10-status.md — l’état de l’enveloppe de métadonnées.
  • architecture/02-ecosystem-philosophy.md — le partitionnement strict des API et le cadrage de conception de l’Enterprise Metadata Suite.
  • architecture/13-catalog-and-registry.md §« Lockfile pinning and artifact immutability (Épinglage dans le lockfile et immuabilité des artefacts) » + §« Catalog entity name-shape enforcement (Application de la forme des noms des entités du catalogue) » — ce que la règle d’immuabilité refuse au moment de la publication, et où les formes de noms par type d’entité sont vérifiées : le plugin de discipline de publication les signale à titre indicatif lorsqu’un auteur exécute aggrega lint, et ni la construction ni la publication ne les vérifient.
  • architecture/11-governance-and-compliance.md §« Inheritance and publishing discipline (Héritage et discipline de publication) » — quelles règles de gouvernance relèvent du plugin de discipline de publication, et lesquelles l’héritage d’un Component qui en étend un autre règle à la place par construction.