id: ADR-002 title: Les surfaces d’extension first-party utilisent des contrats de traits date: 2026-07-04 status: accepté relates-to:

• crates/zeroclaw-api/src/model_provider.rs
• crates/zeroclaw-api/src/channel.rs
• crates/zeroclaw-api/src/tool.rs
• crates/zeroclaw-api/src/memory_traits.rs
• crates/zeroclaw-api/src/observability_traits.rs
• crates/zeroclaw-api/src/runtime_traits.rs
• crates/zeroclaw-api/src/peripherals_traits.rs
• docs/book/src/architecture/crates.md
• docs/book/src/developing/tool-inventory.md

ADR-002 : les surfaces d’extension de première partie utilisent des contrats de trait

Ceci est un enregistrement rétroactif d’une décision prise avant le processus ADR formel. La date exacte de la décision d’origine n’est pas disponible dans cet enregistrement ; la date ci-dessus est la date à laquelle cet ADR a été ajouté à la documentation d’architecture.

Cet enregistrement a été rédigé à partir de FND-002 §6.3, des surfaces de trait zeroclaw-api actuelles, et des docs de frontières de crate et d’outil. Il n’a pas été récupéré d’un ancien fichier ADR.

Contexte

ZeroClaw a besoin de nombreuses familles d’extensions : fournisseurs de modèles, canaux de messagerie, outils, backends de mémoire, sinks d’observabilité, adaptateurs de runtime et périphériques matériels. Chaque famille a des contraintes d’E/S, d’erreur, de configuration, de sécurité et de cycle de vie différentes, mais chacune doit toujours s’intégrer dans le même runtime d’agent.

Sans contrats explicites, chaque intégration exercerait une pression sur la boucle d’exécution pour qu’elle accumule des cas spéciaux. Cela rendrait les nouvelles intégrations plus rapides au début et plus difficiles à maintenir ensuite : le routage des providers fuiterait dans les canaux, la politique d’outils fuiterait dans les providers, l’authentification des canaux fuiterait dans la boucle de l’agent, et le comportement de mémoire ou de journalisation serait copié entre des crates sans rapport.

Le dépôt utilise déjà zeroclaw-api comme couche de contrat public. Les docs d’architecture décrivent ce crate comme l’ABI du noyau et indiquent que le runtime dépend de traits plutôt que d’implémentations concrètes.

Décision

Les familles d’extensions de première partie utilisent des contrats explicites de traits Rust dans zeroclaw-api et sont raccordées via la fabrique, le registre, la composition ou la limite fournie par l’hôte existants pour cette surface.

Les principaux contrats incluent :

• ModelProvider pour les clients de fournisseurs de modèles ;
• Channel pour les surfaces de messagerie entrantes et sortantes ;
• Tool pour les capacités appelables par l’agent ;
• Memory et MemoryStrategy pour la persistance et le rappel ;
• Observer pour la télémétrie d’exécution ;
• RuntimeAdapter pour les capacités du runtime hôte ;
• Peripheral pour le matériel et les surfaces de carte.

Le comportement partagé appartient à la frontière du trait, de la factory, du registry, de la policy, de la config, du logging ou d’un helper de couche inférieure lorsque plusieurs implémentations en ont besoin. Une intégration individuelle ne doit pas patcher la boucle d’exécution ni ajouter d’état parallèle uniquement pour faire fonctionner un provider, un channel, un tool ou un backend.

Cet ADR couvre les surfaces d’extension first-party in-process. Il ne remplace pas les frontières plugin, WIT, MCP ou skill-package pour les capacités out-of-process ou distribuées de manière indépendante.

Conséquences

Conséquences positives :

• Les nouvelles intégrations first-party peuvent être examinées par rapport à un contrat existant plutôt qu’en tant que modifications d’exécution sur mesure.
• Le code d’exécution peut rester concentré sur l’orchestration, la politique, l’état et le cycle de vie plutôt que sur le comportement spécifique au fournisseur.
• Les tests peuvent cibler le câblage factory, registry ou host-boundary, le comportement des traits et les cas limites sans nécessiter un runtime de bout en bout complet pour chaque intégration.
• La documentation et les guides de revue peuvent identifier des surfaces d’extension concrètes avant le début de l’implémentation.

Conséquences négatives :

• Les modifications de traits ont un large rayon d’impact et nécessitent une migration soigneuse.
• Un trait trop restrictif force les intégrations à acheminer le comportement via la configuration, les journaux ou des chemins auxiliaires ad hoc.
• Un trait trop générique peut devenir une API au plus petit dénominateur commun qui masque des différences importantes de capacités.
• Les méthodes par défaut des traits peuvent masquer un comportement non pris en charge, sauf si la documentation et les tests rendent explicites les valeurs par défaut.

Décisions de suivi :

• ADR-003 régit les capacités des plugins WASM distribués de manière indépendante, pas seulement les implémentations Rust de première partie.
• ADR-005 enregistre le contrat de stockage mémoire indépendant du backend et la valeur par défaut SQLite.
• ADR-006 et ADR-007 restent réservés aux décisions, conditionnées à leur implémentation, concernant le plugin de canal et l’extraction de la passerelle.

Références

• Architecture : Crates
• Inventaire des outils intégrés
• Protocole de plugin
• crates/zeroclaw-api/src/model_provider.rs
• crates/zeroclaw-api/src/channel.rs
• crates/zeroclaw-api/src/tool.rs
• crates/zeroclaw-api/src/memory_traits.rs
• crates/zeroclaw-api/src/observability_traits.rs
• crates/zeroclaw-api/src/runtime_traits.rs
• crates/zeroclaw-api/src/peripherals_traits.rs