Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-006 title: Hacer que los plugins de tiempo de ejecución sean el objetivo para los canales opcionales date: 2026-07-18 status: proposed relates-to:

  • ADR-002
  • ADR-009
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8850
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8691#issuecomment-5009706612
  • wit/v0/channel.wit
  • crates/zeroclaw-plugins/src/wasm_channel.rs

ADR-006: Hacer que los plugins de tiempo de ejecución sean el destino de los canales opcionales

Contexto

ZeroClaw actualmente compila muchas integraciones de mensajería detrás de feature flags de Cargo. Esto mantiene el código de canales no utilizados fuera de las compilaciones seleccionadas, pero agregar o actualizar una integración opcional aún requiere recompilar la aplicación. También mantiene las dependencias específicas del proveedor y la cadencia de lanzamiento acopladas al binario principal.

El modelo de componentes WIT ahora define un mundo channel-plugin, y el adaptador del host implementa el trait Channel compartido para un componente WASM. El descubrimiento y el adaptador del lado del host existen, pero un demonio en ejecución todavía no construye los plugins de canal descubiertos ni proporciona todos los listeners por proveedor que necesitan. Por lo tanto, los plugins de tiempo de ejecución describen un destino real con una ruta operacional incompleta, no el modelo de empaquetado actual.

Las alternativas son mantener un híbrido permanente de compilación/ejecución, requerir una migración inmediata de todos los canales, o establecer los complementos en tiempo de ejecución como destino predeterminado mientras se permiten excepciones nativas explícitas para las capacidades que el límite del complemento aún no puede admitir.

Decisión

Haremos que los plugins instalables en tiempo de ejecución sean el modelo de empaquetado y ejecución objetivo para los canales opcionales.

Un canal opcional debería migrar de una funcionalidad compilada a un plugin en tiempo de ejecución cuando el límite del host WIT/WASI pueda proporcionar sus capacidades requeridas de red, entrada mediante webhook o sondeo, configuración, secretos, medios, interacción y ciclo de vida sin debilitar el modelo de seguridad en tiempo de ejecución.

Las implementaciones nativas pueden permanecer durante la transición únicamente como excepciones explícitas basadas en capacidades. Una excepción debe identificar la capacidad del host faltante o la restricción operativa, la ruta de código nativo que depende de ella y la condición que permite la migración. La identidad del proveedor, los indicadores de características existentes o la antigüedad de la implementación no son, por sí solos, motivos para una excepción permanente.

El runtime es el responsable del descubrimiento de plugins, la aplicación de permisos, la entrega de configuración, la supervisión de listeners, el reporte de salud y la adaptación al contrato compartido de Channel. Un plugin de canal es el responsable del comportamiento de protocolo específico de la plataforma y la traducción de mensajes. El ingreso alojado en el gateway puede enrutar tráfico HTTP genérico, pero no debe convertirse en el propietario permanente de la lógica de canal específica del proveedor.

La incidencia #8850 se encarga de la secuenciación de las migraciones, el seguimiento de las brechas de capacidades y el límite para retirar canales opcionales compilados. Este ADR no determina qué canal se migra primero ni exige eliminar una implementación nativa funcional antes de que su reemplazo en tiempo de ejecución tenga un soporte operativo equivalente.

Este ADR permanece propuesto hasta que se cumplan todas estas condiciones:

  • los plugins de canal descubiertos pueden configurarse y registrarse mediante un daemon en ejecución;
  • una distribución compatible puede instalar, configurar y ejecutar un plugin de canal sin una reconstrucción personalizada;
  • el tráfico entrante de escuchas o webhooks puede llegar al complemento bajo la propiedad del entorno de ejecución supervisado;
  • al menos un canal compilado opcional existente ha migrado de extremo a extremo; y
  • el proceso de excepción y compatibilidad está documentado para los canales que aún no pueden migrar.

Consecuencias

Consecuencias positivas:

  • Los usuarios pueden agregar y actualizar integraciones opcionales sin volver a compilar ZeroClaw.
  • Las dependencias de proveedores y la cadencia de lanzamiento pueden separarse del binario principal.
  • Las implementaciones de canales comparten un único límite de tiempo de ejecución con permisos y un único contrato de trait visible para el llamador.
  • Las excepciones nativas siguen siendo revisables porque están vinculadas a brechas de capacidad con nombre en lugar de convertirse en un segundo modelo permanente indefinido.

Consecuencias negativas:

  • El host debe supervisar los listeners de larga duración y preservar el estado del canal, la interacción, el comportamiento de los medios y de la configuración a través del límite del componente.
  • Algunas plataformas pueden permanecer nativas mientras las capacidades de WIT/WASI maduran, por lo que la transición aún conlleva dos rutas de empaquetado.
  • La distribución, compatibilidad, firma y revocación de plugins pasan a formar parte del ciclo de vida operativo del canal.
  • La migración requiere pruebas de paridad; limitarse a compilar un componente de canal no es suficiente para retirar su implementación nativa.

Referencias