Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-002 title: Las superficies de extensión de primera parte usan contratos de traits date: 2026-07-04 status: accepted 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: Las superficies de extensión de primera parte usan contratos de trait

Este es un registro retroactivo de una decisión tomada antes del proceso formal de ADR. La fecha original exacta de la decisión no está disponible en este registro; la fecha anterior es la fecha en que este ADR se añadió a la documentación de arquitectura.

Este registro fue redactado a partir de FND-002 §6.3, las superficies actuales del trait zeroclaw-api, y los documentos de límites de crate y herramientas. No fue recuperado de un archivo ADR anterior.

Contexto

ZeroClaw necesita muchas familias de extensiones: proveedores de modelos, canales de mensajería, herramientas, backends de memoria, destinos de observabilidad, adaptadores de ejecución y periféricos de hardware. Cada familia tiene distintas restricciones de E/S, errores, configuración, seguridad y ciclo de vida, pero todas deben seguir componiéndose en el mismo runtime del agente.

Sin contratos explícitos, cada integración presionaría al bucle de ejecución para acumular casos especiales. Eso haría que las nuevas integraciones fueran más rápidas al principio y más difíciles de mantener después: el enrutamiento de proveedores se filtraría en los canales, la política de herramientas se filtraría en los proveedores, la autenticación de canales se filtraría en el bucle del agente, y el comportamiento de memoria o registro se copiaría entre crates no relacionados.

El repositorio ya usa zeroclaw-api como la capa de contrato público. La documentación de arquitectura describe ese crate como la ABI del kernel y establece que el runtime depende de traits en lugar de implementaciones concretas.

Decisión

Las familias de extensiones de primera parte usan contratos explícitos de trait de Rust en zeroclaw-api y se conectan a través de la factory, registry, composition o boundary proporcionada por el host existentes para esa superficie.

Los contratos principales incluyen:

  • ModelProvider para clientes de model-provider;
  • Channel para superficies de mensajería entrante y saliente;
  • Tool para capacidades invocables por el agente;
  • Memory y MemoryStrategy para persistencia y recuperación;
  • Observer para telemetría en tiempo de ejecución;
  • RuntimeAdapter para las capacidades del host runtime;
  • Peripheral para hardware y superficies de placa.

El comportamiento compartido pertenece al límite del trait, la factory, el registry, la policy, la config, el logging o un helper de una capa inferior cuando varias implementaciones lo necesitan. Una integración individual no debería parchear el bucle de ejecución ni añadir estado paralelo solo para que funcione un proveedor, canal, tool o backend.

Este ADR cubre las superficies de extensión en proceso de primera parte. No reemplaza los límites de plugin, WIT, MCP o paquete de habilidades para capacidades fuera de proceso o distribuidas de forma independiente.

Consecuencias

Consecuencias positivas:

  • Las nuevas integraciones propias pueden revisarse en comparación con un contrato existente en lugar de como cambios de tiempo de ejecución a medida.
  • El código de ejecución puede centrarse en la orquestación, la política, el estado y el ciclo de vida en lugar del comportamiento específico del proveedor.
  • Las pruebas pueden enfocarse en el cableado de la fábrica, el registro o la frontera del host, en el comportamiento de los traits y en casos límite, sin necesidad de un tiempo de ejecución completo de extremo a extremo para cada integración.
  • La documentación y la guía de revisión pueden nombrar superficies de extensión concretas antes de que comience la implementación.

Consecuencias negativas:

  • Los cambios de trait tienen un amplio impacto y requieren una migración cuidadosa.
  • Un trait demasiado estrecho obliga a las integraciones a canalizar el comportamiento a través de la configuración, los logs o rutas auxiliares ad hoc.
  • Un trait demasiado amplio puede convertirse en una API de mínimo común denominador que oculta diferencias importantes de capacidad.
  • Los métodos de rasgo predeterminados pueden ocultar comportamiento no admitido, a menos que la documentación y las pruebas hagan explícitos los valores predeterminados.

Decisiones de seguimiento:

  • ADR-003 rige las capacidades de plugins WASM distribuidos de forma independiente, no solo las implementaciones Rust de primera parte.
  • ADR-005 registra el contrato de almacenamiento de memoria independiente del backend y el valor predeterminado de SQLite.
  • ADR-006 y ADR-007 siguen reservados para las decisiones sobre el complemento de canal y la extracción de la puerta de enlace condicionadas a la implementación.

Referencias