Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-009 title: Los componentes WIT y la sustitución directa de wasmtime reemplazan el puente de complementos de Extism date: 2026-07-04 status: accepted relates-to:

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

ADR-009: Componentes WIT y reemplazo directo de Wasmtime del puente de plugins de Extism

Este ADR sustituye a ADR-003. ADR-003 registró el puente inicial de Extism. La arquitectura aceptada actual es una superficie del modelo de componentes WASM definida por WIT, alojada directamente por wasmtime.

Contexto

Extism fue un arranque útil para demostrar que los plugins WASM externos podían aparecer como herramientas de ZeroClaw. También le dio al proyecto un protocolo JSON sencillo y un modelo de funciones del host con permisos restringidos.

A medida que la arquitectura de microkernel maduró, la superficie de plugins necesitó un límite de compatibilidad más sólido:

  • los contratos de los complementos debían ser explícitos, versionados y revisables;
  • las herramientas, los canales y los backends de memoria necesitaban mundos tipados separados;
  • el host necesitaba backends de ejecución específicos del target de lanzamiento;
  • Se necesitan importaciones del host para adjuntarse a los permisos en tiempo de enlace;
  • los autores de complementos necesitaban un ABI duradero en lugar de exportaciones JSON ad hoc;
  • los límites de almacenamiento y las superficies de host WASI debían ser propiedad de ZeroClaw.

El Modelo de Componentes de WASM y WIT proporcionan ese límite. La integración directa de wasmtime le da al host suficiente control para seleccionar backends, adjuntar superficies de WASI Preview 2, imponer límites de recursos y conectar los mundos invitados con los traits de Rust de ZeroClaw.

Decisión

La ABI de complementos de ZeroClaw se basa en componentes WASM descritos por interfaces WIT bajo wit/v0. El host usa la instrumentación directa del modelo de componentes de wasmtime en crates/zeroclaw-plugins, con puentes por mundo para herramientas, canales y backends de memoria.

El modelo de ejecución es:

  • wit/v0/tool.wit, channel.wit y memory.wit definen los contratos del invitado.
  • crates/zeroclaw-plugins/src/component.rs contiene la infraestructura compartida del host de componentes, el estado del almacén, los límites de recursos, los enlaces WIT y el cableado WASI.
  • wasm_tool.rs, wasm_channel.rs, y wasm_memory.rs puentean esos mundos de vuelta a los traits Tool, Channel y Memory de Rust.
  • Un plugin manifest.toml declara el nombre del plugin, la versión, el tipo de capacidad, los permisos, la configuración y el material de firma.
  • La verificación del manifiesto Ed25519 sigue siendo parte del host del complemento.

La selección del backend de ejecución es explícita:

  • plugins-wasm habilita la superficie del host de complementos en el espacio de trabajo principal.
  • plugins-wasm-runtime-only habilita el host de solo runtime más pequeño.
  • plugins-wasm-cranelift habilita la compilación de Cranelift donde está soportada.
  • plugins-wasm-pulley habilita el intérprete Pulley para objetivos donde Cranelift no está disponible o no es deseable.

Las superficies del host están restringidas por permisos:

  • HttpClient es el permiso que adjunta el estado HTTP de salida y vincula WASI HTTP.
  • ConfigRead es obligatorio antes de que el host inyecte valores resueltos en __config de la herramienta o proporcione config.get del canal. Un consumidor de herramienta o canal puede marcar las propiedades de cadena de nivel superior con x-secret = true; esos valores nunca entran en el objeto público y se leen mediante la importación secrets con ámbito de instancia. Las herramientas reciben acceso a los secretos durante execute. Los canales reciben config.get y secrets.get durante configure y las llamadas operativas; ambas lecturas comparten una única resolución canónica de la configuración por llamada. La instanciación y la detección de metadatos estáticos siguen sin estar disponibles. El host descarta la vista materializada de cada llamada; los invitados de canal conformes deben resolverla en el punto de uso y no conservar la configuración devuelta ni el texto plano, algo que el host no puede hacer cumplir después de la entrega. Las exportaciones estáticas de identidad y capacidades se leen durante la carga, por lo que cambiar esos valores requiere reconstruir el ciclo de vida del canal.
  • El host no expone una función de lectura directa de variables de entorno.
  • Los límites del almacén, el combustible, los límites de tabla, los límites de instancia y los techos de memoria se resuelven antes de que se construya el almacén.

Consecuencias

Positivo:

  • Los plugins comparten una única superficie de contrato tipada con el host de Rust en lugar de convenciones JSON ad hoc por tipo de plugin.
  • Los archivos WIT se convierten en el límite de compatibilidad que se puede congelar y revisar.
  • Los plugins de tool, channel y memory pueden aparecer en tiempo de ejecución como implementaciones nativas de traits.
  • Los backends de ejecución se seleccionan según el objetivo de lanzamiento en lugar de estar ocultos en un único indicador de funciones de propósito general.
  • Las comprobaciones de permisos se adjuntan a las importaciones del host, no solo se documentan en los manifiestos.

Negativo:

  • La integración directa de componentes de wasmtime es más compleja que el puente original de Extism.
  • Las compilaciones de release deben elegir el backend de ejecución adecuado para cada objetivo.
  • Los autores de complementos deben compilar componentes de WASI Preview 2 y seguir las interfaces WIT en lugar de exportar funciones JSON.
  • La superficie WIT ahora necesita disciplina de compatibilidad. Cambiarla es una decisión de arquitectura entre plugins, no una edición local del crate.

Seguimiento:

  • Las reglas de versionado y compatibilidad de WIT están en la documentación de WIT. Si la política de compatibilidad cambia, escribe un nuevo ADR en lugar de editar este en silencio.
  • Los nuevos mundos de invitado deben agregarse como superficies WIT versionadas con el código de puente del host correspondiente y revisión de permisos.

Referencias