Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-009 title: Les composants WIT et wasmtime en direct remplacent le pont de plugins Extism date: 2026-07-04 status: accepté relates-to:

  • ADR-003
  • crates/zeroclaw-plugins
  • wit/v0
  • docs/book/src/foundations/fnd-001-intentional-architecture.md

ADR-009 : WIT Components et Wasmtime direct remplacent le pont de plugin Extism

Cet ADR remplace ADR-003. L’ADR-003 a documenté le pont Extism initial. L’architecture actuellement acceptée est une surface du modèle de composants WASM définie par WIT, hébergée directement par wasmtime.

Contexte

Extism a servi de bootstrap utile pour démontrer que des plugins WASM externes pouvaient apparaître en tant qu’outils ZeroClaw. Il a également fourni au projet un protocole JSON simple et un modèle de fonctions hôtes contrôlé par des permissions.

À mesure que l’architecture à micro-noyau a mûri, la surface des plugins a nécessité une limite de compatibilité plus stricte :

  • les contrats de plugins devaient être explicites, versionnés et révisables ;
  • outils, canaux et backends de mémoire nécessitaient des mondes typés séparés ;
  • l’hôte avait besoin de backends d’exécution spécifiques à la cible de release ;
  • imports de l’hôte nécessaires pour s’attacher aux permissions à l’édition de liens ;
  • les auteurs de plugins avaient besoin d’une ABI durable au lieu d’exports JSON ad hoc ;
  • les limites du store et les surfaces d’hôte WASI devaient appartenir à ZeroClaw.

Le modèle de composants WASM et WIT fournissent cette frontière. L’intégration directe de wasmtime donne à l’hôte un contrôle suffisant pour sélectionner les backends, attacher les surfaces WASI Preview 2, imposer des limites de ressources et relier les mondes invités aux traits Rust de ZeroClaw.

Décision

L’ABI des plugins de ZeroClaw est basée sur des composants WASM décrits par des interfaces WIT sous wit/v0. L’hôte utilise le câblage direct du modèle de composants wasmtime dans crates/zeroclaw-plugins, avec des ponts par world pour les outils, les canaux et les backends de mémoire.

Le modèle d’exécution est :

  • wit/v0/tool.wit, channel.wit et memory.wit définissent les contrats guest.
  • crates/zeroclaw-plugins/src/component.rs possède l’infrastructure partagée de l’hôte de composants, l’état du store, les limites de ressources, les liaisons WIT et le câblage WASI.
  • wasm_tool.rs, wasm_channel.rs et wasm_memory.rs relient ces mondes aux traits Rust Tool, Channel et Memory.
  • Un manifest.toml de plugin déclare le nom du plugin, la version, le type de capacité, les autorisations, la configuration et les données de signature.
  • La vérification du manifeste Ed25519 reste une partie de l’hôte de plugin.

La sélection du backend d’exécution est explicite :

  • plugins-wasm active la surface hôte des plugins dans l’espace de travail principal.
  • plugins-wasm-runtime-only active le plus petit hôte runtime-only.
  • plugins-wasm-cranelift active la compilation Cranelift là où c’est pris en charge.
  • plugins-wasm-pulley active l’interpréteur Pulley pour les cibles où Cranelift est indisponible ou indésirable.

Les surfaces hôtes sont restreintes par les permissions :

  • HttpClient est la permission qui attache l’état HTTP sortant et lie WASI HTTP.
  • ConfigRead est requis avant que l’hôte n’injecte les valeurs résolues sous l’outil __config ou ne serve le canal config.get. Un outil ou un consommateur de canal peut marquer les propriétés de type chaîne de niveau supérieur avec x-secret = true ; ces valeurs n’entrent jamais dans l’objet public et sont lues via l’import secrets limité à l’instance. Les outils reçoivent l’accès aux secrets pendant execute. Les canaux reçoivent config.get et secrets.get pendant configure et les appels opérationnels ; les deux lectures partagent une résolution canonique unique de la configuration par appel. L’instanciation et la découverte des métadonnées statiques restent indisponibles. L’hôte supprime la vue matérialisée de chaque appel ; les invités de canal conformes doivent effectuer la résolution au point d’utilisation et ne pas conserver la configuration renvoyée ni les données en clair, ce que l’hôte ne peut pas faire respecter après la livraison. L’identité statique et les exportations de capacités sont lues au chargement ; la modification de ces valeurs nécessite donc de reconstruire le cycle de vie du canal.
  • L’hôte n’expose pas de fonction de lecture brute des variables d’environnement.
  • Les limites du store, le fuel, les limites de table, les limites d’instance et les plafonds de mémoire sont résolus avant que le store ne soit construit.

Conséquences

Positif :

  • Les plugins partagent une surface de contrat typée unique avec l’hôte Rust au lieu de conventions JSON ad hoc par type de plugin.
  • Les fichiers WIT deviennent la frontière de compatibilité qui peut être figée et revue.
  • Les plugins d’outil, de canal et de mémoire peuvent apparaître au runtime comme des implémentations de traits natives.
  • Les backends d’exécution sont sélectionnés en fonction de la cible de publication, au lieu d’être masqués dans un seul indicateur de fonctionnalité polyvalent.
  • Les vérifications de permissions sont attachées aux imports de l’hôte, et non seulement documentées dans les manifestes.

Négatif :

  • L’intégration directe des composants wasmtime est plus complexe que le bridge Extism d’origine.
  • Les builds de release doivent choisir le bon backend d’exécution pour chaque cible.
  • Les auteurs de plugins doivent construire des composants WASI Preview 2 et suivre les interfaces WIT plutôt que d’exporter des fonctions JSON.
  • La surface WIT nécessite désormais une discipline de compatibilité. La modifier est une décision d’architecture inter-plugins, pas une modification locale de crate.

Suite :

  • Les règles de versionnement et de compatibilité WIT se trouvent avec les docs WIT. Si la politique de compatibilité change, rédigez un nouvel ADR plutôt que de modifier silencieusement celui-ci.
  • Les nouveaux mondes invités doivent être ajoutés en tant que surfaces WIT versionnées avec le code de pont hôte correspondant et une revue des permissions.

Références