id: ADR-015 title: Le catalogue unifié des capacités est une projection en lecture seule des propriétaires canoniques date: 2026-08-22 status: proposé relates-to:

https://github.com/zeroclaw-labs/zeroclaw/issues/9346
https://github.com/zeroclaw-labs/zeroclaw/issues/6489
https://github.com/zeroclaw-labs/zeroclaw/issues/8908
https://github.com/zeroclaw-labs/zeroclaw/issues/8850
https://github.com/zeroclaw-labs/zeroclaw/issues/8367
docs/book/src/plugins/index.md
crates/zeroclaw-plugins/src/config.rs

ADR-015 : Le catalogue unifié des capacités est une projection en lecture seule des propriétaires canoniques

Contexte

ZeroClaw possède plusieurs interfaces qui décrivent ses fonctionnalités : les canaux et outils intégrés, les paquets de plugins installés, les paquets disponibles dans le registre, les alias de fournisseurs et de canaux configurés, les entrées d’intégration de la passerelle, les commandes de plugins CLI, les vues du tableau de bord web, ZeroCode et les instructions de configuration destinées à l’agent. Ces interfaces répondent actuellement à des questions différentes et utilisent des termes qui se chevauchent, tels que « installé », « configuré », « activé », « actif » et « sain ».

L’orientation du produit dans #6489 est de disposer d’un catalogue unique et fidèle couvrant les intégrations, les composants intégrés, les packages installables, les instances configurées et les observations à l’exécution. Cette orientation est parfois résumée par « tout est un plugin », mais l’architecture pérenne est plus restreinte : un catalogue, et non un mécanisme d’implémentation unique. Les implémentations intégrées et celles fournies par des packages peuvent coexister indéfiniment.

Le RFC accepté #9346 définit le contrat manquant. Le catalogue doit conserver séparément les informations relatives aux packages, aux capacités, aux implémentations, aux instances configurées et aux observations d’exécution. Il doit dériver chaque information de son propriétaire canonique au lieu de créer un autre registre persistant du cycle de vie. Il doit également préserver la compatibilité avec les projections existantes de package et d’Integration avant tout retrait de route, toute migration ou tout engagement concernant une API publique stable.

Ce document consigne cette architecture cible. Il n’affirme pas que la projection de catalogue unifiée, le pont de compatibilité ou le modèle d’observation de l’exécution ont été livrés.

Décision

Gardez les cinq identités séparées

Le catalogue unifié utilise des identités distinctes pour des faits distincts :

Artefact de paquet : un artefact intégré, installé ou disponible dans un registre, identifié par la source du paquet, l’espace de noms et le nom, la version, ainsi que le contenu immuable ou la révision d’admission lorsqu’un artefact existe.
Capacité : comportement typé tel que channel:discord, provider:ollama, tool:web_search, un backend de mémoire, une compétence, un observateur ou une intégration de plateforme.
Implémentation : l’implémentation intégrée ou fournie par un package qui fournit une fonctionnalité.
Instance configurée : alias défini par l’opérateur à partir de la configuration canonique du sous-système propriétaire.
Observation du runtime : informations transitoires sur l’activation, l’état de santé ou l’échec, signalées par le propriétaire du runtime pour une génération de runtime.

Aucune de ces identités ne se substitue à une autre. Un paquet peut exposer plusieurs capacités. Une capacité peut disposer d’implémentations intégrées, installées et disponibles dans le registre. Une instance configurée peut exister sans instance d’exécution active. Une observation de l’exécution peut devenir obsolète sans modifier l’installation, la configuration ou l’activation.

Les identifiants ne doivent pas contenir de secrets, de valeurs de configuration brutes, de jetons d’accès, de noms d’hôte, de noms d’utilisateur, de chemins absolus ou de libellés d’affichage modifiables. Les fonctionnalités fournies par les packages et les observations de l’exécution restent liées à la provenance exacte de l’artefact ; les versions installées et celles du registre ne sont donc pas fusionnées, et les mises à niveau ne peuvent pas rendre ambiguës les preuves d’activation ou d’état de santé.

Déclarer l’identité de la capacité via les propriétaires

Les identités de capacité sont déclarées par le propriétaire de la famille de capacités au moyen de champs d’inventaire intégrés typés ou d’un schéma de manifeste de package admis. Le catalogue associe les artefacts et les implémentations à ces déclarations. Il ne doit pas déduire une identité logique à partir des noms des outils appelables, des types généraux PluginCapability, des noms d’affichage ou d’une table de regroupement parallèle.

Une famille dépourvue de déclaration typée fournie par son propriétaire n’a aucune identité de capacité du catalogue tant que ce propriétaire n’en a pas ajouté une. Cela maintient l’autorité de regroupement au sein du sous-système qui comprend la capacité, au lieu de la transférer à la projection du catalogue.

Preuves provenant de la source de vérité du projet, et non des écritures du cycle de vie

Le catalogue est orienté lecture. Il matérialise une vue à partir des propriétaires canoniques au moment de la requête, ou à partir d’un cache dérivé qui contient suffisamment de générations des sources pour s’invalider lui-même. Il n’accepte pas les écritures du cycle de vie et ne conserve pas de table supplémentaire d’activation, d’admission, de configuration, de mise en service, de disponibilité ou d’état de santé.

Chaque axe d’état a un seul propriétaire :

Fait	Propriétaire
Disponibilité du registre	le client de registre ou d’index configuré
Disponibilité intégrée	l’inventaire intégré compilé
Paquet installé et état d’admission	l’inventaire des installations et des admissions de paquets
Identité de la capacité, exports et origine de l’implémentation	le propriétaire de la famille de capacités au moyen d’un inventaire typé ou de déclarations de manifeste admises
Instance configurée	la section `Config` canonique du sous-système propriétaire
État activé	configuration canonique ainsi que la politique d’activation du sous-système propriétaire
État actif	le registre d’exécution qui a instancié ou enregistré l’instance
État de santé ou échec	le responsable de l’environnement d’exécution spécifique à la fonctionnalité ou de la sonde
Préparation côté agent	une projection à la demande telle que #8367, s’appuyant sur les identités et les éléments de preuve du catalogue sans devenir un autre responsable du cycle de vie

Les éléments de preuve manquants sont unknown, et non false. Les résultats d’état distinguent la valeur vraie connue, la valeur fausse connue, la valeur inconnue et la valeur non applicable. L’état de santé est un résultat d’observation défini par le propriétaire, et non des booléens indépendants pouvant simultanément indiquer healthy et failed. Les observations de l’environnement d’exécution incluent l’heure d’observation, la génération de l’environnement d’exécution, l’implémentation sélectionnée, la provenance de l’artefact lorsqu’il provient d’un package, ainsi qu’une règle de fraîcheur. Une fois obsolète, l’état de santé redevient inconnu jusqu’à son actualisation.

Une projection n’est pas une transaction atomique entre des propriétaires indépendants. Les charges utiles publiques incluent generated_at ainsi que les générations ou la provenance des propriétaires participants lorsque cela est utile, afin que les consommateurs ne puissent pas déduire que les informations relatives au paquet, à la configuration et à l’environnement d’exécution ont été observées simultanément.

Conserver l’autorité du résolveur propre à chaque famille

Les règles de collision et de priorité entre composants natifs et plugins ne relèvent pas de la politique globale du catalogue. La RFC #8850 définit le comportement en cas de collision entre composants natifs et plugins pour les canaux et les outils. Le catalogue applique ce résultat à channel:* et tool:*.

Pour les fournisseurs, les backends mémoire, les observateurs, les compétences et les intégrations de plateforme sans résolveur défini par le propriétaire, le catalogue signale chaque implémentation correspondante avec des éléments explicites indiquant un conflit non résolu ou inconnu, et n’applique aucun ordre implicite. Un résolveur défini ultérieurement par le propriétaire peut devenir la source de cette famille sans transformer le catalogue en résolveur.

Séparez la visibilité de l’autorité

La visibilité du catalogue peut restreindre ce qu’un utilisateur, une interface utilisateur, une API ou un agent voit. Elle ne peut pas accorder de droits d’invocation.

Les registres des outils des agents, les profils de risque, la restriction par exécution, la politique de destination, les droits accordés, les approbations et l’autorisation limitée au sujet restent hors du catalogue. Un consommateur tel que #8367 peut déduire des indications ponctuelles à partir des éléments probants du catalogue et de la politique spécifique au sujet, mais ces indications sont une projection. Elles n’autorisent pas une action, n’écrivent pas l’état du cycle de vie et ne deviennent pas un fait de l’instance configurée.

Les projections publiques excluent les informations d’identification, les références aux secrets, les valeurs de configuration brutes, l’authentification auprès des registres, l’identité de l’hôte, les chemins de système de fichiers sans restriction, les erreurs d’exécution brutes et les champs privés des manifestes. Le texte des registres et des manifestes constitue des métadonnées non fiables et doit être rendu comme des données, et non comme des instructions.

Préserver la compatibilité avant la convergence

GET /api/plugins reste une projection centrée sur les packages pendant la stabilisation du travail sur les packages. /api/integrations reste une projection de compatibilité sur le catalogue partagé jusqu’à ce qu’une décision de compatibilité distincte autorise sa suppression, sa redirection ou une rupture de l’API stable.

La CLI, le web, ZeroCode, la passerelle et l’état de préparation destiné aux agents consomment des projections versionnées issues du même contrat. Des champs supplémentaires peuvent être introduits de manière compatible. Les changements d’identifiants, le retrait de routes, la migration de configuration, les engagements relatifs à la stabilité de l’API publique et la politique de confiance de la marketplace nécessitent une revue distincte, accompagnée de plans de retour arrière et de compatibilité.

L’identité des packages doit s’aligner sur les orientations existantes du registre, plutôt que de créer un autre système de coordonnées sans rapport. Le travail d’implémentation doit mettre en cohérence les coordonnées des packages avec l’identité de package de style MCP existante et l’orientation de registre OCI proposée séparément, avant qu’un deuxième consommateur ne s’appuie dessus.

Le vocabulaire des preuves suit intentionnellement les pratiques établies en matière d’état distribué : la sémantique des conditions à la Kubernetes pour les faits connus, inconnus et observés, ainsi que la distinction de systemd entre l’intention d’activation et l’état d’exécution actif. ZeroClaw n’a pas besoin d’importer ces systèmes dans leur intégralité, mais le catalogue doit préserver cette séparation.

Critères d’acceptation

Cet ADR reste proposé jusqu’à ce que toutes ces conditions soient remplies :

les artefacts de package, les capacités, les implémentations, les instances configurées, les observations à l’exécution et les preuves d’état sont documentés avec des exemples représentatifs de canaux, de fournisseurs, d’outils, de plateformes et de packages multicapacités ;
chaque identité de capacité logique provient d’une déclaration typée fournie par le propriétaire, et le catalogue ne peut pas en déduire une à partir de noms appelables ou de catégories générales de capacités ;
chaque champ d’état projeté indique sa source de vérité et utilise correctement les sémantiques « connu », « inconnu » et « non applicable » ;
la disponibilité des paquets, l’installation, l’admission, la configuration, l’autorisation, l’activation, l’état de santé et l’état de préparation côté agent restent représentables indépendamment et non modifiables via le catalogue ;
le comportement en cas de collision entre un canal et un outil intégré/plugin correspond à celui de #8850, tandis que les autres familles de capacités restent explicitement non résolues, sauf si leur responsable définit un résolveur ;
les capacités fournies par le paquet et les observations d’exécution restent liées à la provenance exacte de l’artefact malgré les écarts entre les versions installée et disponible, les mises à niveau, les rechargements et les générations d’exécution ;
les projections publiques exposent des métadonnées de génération ou de provenance et n’impliquent pas de cohérence atomique entre des propriétaires indépendants ;
la visibilité du catalogue ne peut pas accorder l’autorité d’invocation ni contourner les vérifications de l’agent, du tour, de la destination, de l’octroi, de l’approbation ou de la politique ;
/api/plugins et /api/integrations disposent d’un pont de compatibilité additif avant toute convergence des routes, tout retrait ou tout engagement envers une API stable ; et
L’identité des coordonnées de package est alignée sur les directives existantes des registres MCP et OCI avant que plusieurs consommateurs de packages n’en dépendent.

Conséquences

Conséquences positives :

Les contributeurs peuvent déterminer si un fait concerne la disponibilité d’un paquet, l’installation, la configuration, la mise en service, l’activation, l’état de santé ou l’état de préparation.
CLI, la passerelle, le web, ZeroCode et les conseils destinés aux agents peuvent utiliser un vocabulaire commun sans recopier l’état du cycle de vie.
Les implémentations intégrées et des plugins peuvent coexister sans prétendre que toutes les implémentations intégrées ont migré vers WASM.
Les affirmations concernant l’état de fonctionnement et l’activation sont désormais fondées sur des preuves plutôt que déduites de la configuration ou de la présence d’un paquet.
Les travaux de compatibilité peuvent être effectués de manière additive avant toute modification des routes publiques ou de la terminologie.

Conséquences négatives :

Le contrat du catalogue est plus complexe qu’une simple énumération status.
Les responsables des familles de capacités doivent ajouter des déclarations typées avant que leurs capacités puissent y participer correctement.
Les responsables de l’environnement d’exécution doivent publier des observations propres à la génération avant que le catalogue puisse signaler des éléments attestant l’activité ou l’état de santé.
La convergence de l’API est plus lente, car /api/plugins et /api/integrations doivent transiter par des couches de compatibilité.
La réconciliation des coordonnées de paquet doit intervenir suffisamment tôt pour éviter un autre système d’identification du registre.

ZeroClaw Docs