id: ADR-015 title: El catálogo unificado de capacidades es una proyección de solo lectura sobre los propietarios canónicos date: 2026-08-22 status: propuesto relates-to:

https://github.com/zeroclaw-labs/zeroclaw/issues/9346
https://github.com/zeroclaw-labs/zeroclaw/issues/6489
https://github.com/zeroclaw-labs/zeroclaw/issues/8908
https://github.com/zeroclaw-labs/zeroclaw/issues/8850
https://github.com/zeroclaw-labs/zeroclaw/issues/8367
docs/book/src/plugins/index.md
crates/zeroclaw-plugins/src/config.rs

ADR-015: El catálogo unificado de capacidades es una proyección de solo lectura sobre los propietarios canónicos

Contexto

ZeroClaw tiene varias interfaces que describen sus capacidades: canales y herramientas integrados, paquetes de plugins instalados, paquetes disponibles en el registro, alias de proveedores y canales configurados, entradas de integración del gateway, comandos de plugins de la CLI, vistas del panel web, ZeroCode y guía de configuración orientada a agentes. Estas interfaces actualmente responden a preguntas diferentes y utilizan términos que se solapan, como “instalado”, “configurado”, “habilitado”, “activo” y “saludable”.

La dirección del producto en #6489 es contar con un único catálogo fidedigno que abarque integraciones, componentes integrados, paquetes instalables, instancias configuradas y observaciones del tiempo de ejecución. En ocasiones, esa dirección se resume como “todo es un plugin”, pero la arquitectura estable es más específica: un catálogo, no un único mecanismo de implementación. Las implementaciones integradas y respaldadas por paquetes pueden coexistir indefinidamente.

El RFC aceptado #9346 define el contrato faltante. El catálogo debe mantener separados los datos de paquetes, los datos de capacidades, los datos de implementación, los datos de instancias configuradas y las observaciones del tiempo de ejecución. Debe derivar cada dato de su propietario canónico en lugar de crear otro registro persistido del ciclo de vida. También debe preservar la compatibilidad con las proyecciones existentes de paquetes y de Integration antes de retirar cualquier ruta, realizar migraciones o comprometerse con una API pública estable.

Este registro describe esa arquitectura objetivo. No afirma que se hayan lanzado la proyección del catálogo unificado, el puente de compatibilidad ni el modelo de observación en tiempo de ejecución.

Decisión

Mantén separadas cinco identidades

El catálogo unificado utiliza identidades independientes para hechos distintos:

Artefacto de paquete: un artefacto integrado, instalado o disponible en un registro, identificado por el origen del paquete, el espacio de nombres/nombre, la versión y el contenido inmutable o la revisión de admisión cuando existe un artefacto.
Capacidad: comportamiento tipado como channel:discord, provider:ollama, tool:web_search, un backend de memoria, una skill, un observador o una integración de plataforma.
Implementación: la implementación integrada o proporcionada por el paquete que ofrece una capacidad.
Instancia configurada: un alias definido por el operador a partir de la configuración canónica del subsistema propietario.
Observación del entorno de ejecución: evidencia transitoria de activación, estado o fallo comunicada por el propietario del entorno de ejecución para una generación del entorno de ejecución.

Ninguna de estas identidades sustituye a otra. Un paquete puede exponer varias capacidades. Una capacidad puede tener implementaciones integradas, instaladas y disponibles en el registro. Una instancia configurada puede existir sin una instancia activa en tiempo de ejecución. Una observación en tiempo de ejecución puede quedar obsoleta sin cambiar la instalación, la configuración ni la habilitación.

Los identificadores no deben contener secretos, valores de configuración sin procesar, tokens de acceso, nombres de host, nombres de usuario, rutas absolutas ni etiquetas de visualización mutables. Las capacidades proporcionadas por los paquetes y las observaciones del tiempo de ejecución permanecen vinculadas a la procedencia exacta del artefacto, por lo que las versiones instaladas y las del registro no se combinan, y las actualizaciones no pueden dejar ambiguas las evidencias de activación o del estado de salud.

Declara la identidad de la capacidad mediante los propietarios

Las identidades de las capacidades las declara el propietario de la familia de capacidades mediante campos de inventario integrados con tipos o mediante un esquema admitido del manifiesto del paquete. El catálogo vincula los artefactos y las implementaciones con esas declaraciones. No debe inferir una identidad lógica a partir de nombres de herramientas invocables, tipos generales PluginCapability, nombres para mostrar o una tabla de agrupación paralela.

Una familia sin una declaración tipada proporcionada por el propietario no tiene una identidad de capacidad del catálogo hasta que dicho propietario añade una. Esto mantiene la autoridad sobre la agrupación en el subsistema que entiende la capacidad, en lugar de trasladarla a la proyección del catálogo.

Evidencia de la fuente de verdad del proyecto, no escrituras del ciclo de vida

El catálogo está orientado a la lectura. Materializa una vista a partir de los propietarios canónicos en el momento de la solicitud o desde una caché derivada que contiene suficientes generaciones de origen para invalidarse por sí misma. No acepta escrituras del ciclo de vida ni persiste otra tabla de habilitación, admisión, configuración, activación, disponibilidad o estado de salud.

Cada eje de estado tiene un responsable:

Hecho	Propietario
Disponibilidad del registro	el cliente configurado del registro o índice
Disponibilidad integrada	el inventario integrado compilado
Paquete instalado y estado de admisión	el inventario de instalación y admisión de paquetes
Identidad de la capacidad, exportaciones y origen de la implementación	el propietario de la familia de capacidades mediante un inventario tipado o declaraciones de manifiesto admitidas
Instancia configurada	la sección `Config` canónica del subsistema propietario
Estado habilitado	configuración canónica y la política de activación del subsistema propietario
Estado activo	el registro de tiempo de ejecución que instanció o registró la instancia
Estado de salud o fallo	el responsable del entorno de ejecución específico de la capacidad o la sonda
Preparación para agentes	una proyección bajo demanda como #8367, utilizando identidades del catálogo y evidencias sin convertirse en otro responsable del ciclo de vida

La evidencia faltante es unknown, no false. Los resultados de estado distinguen entre verdadero conocido, falso conocido, desconocido y no aplicable. La salud es un resultado de observación definido por el propietario, no valores booleanos independientes que puedan afirmar simultáneamente healthy y failed. Las observaciones del tiempo de ejecución incluyen la hora de observación, la generación del tiempo de ejecución, la implementación seleccionada, la procedencia del artefacto cuando proviene de un paquete y una regla de vigencia. Una vez obsoleta, la salud vuelve a unknown hasta que se actualiza.

Una proyección no es una transacción atómica entre propietarios independientes. Las cargas útiles públicas incluyen generated_at y, cuando resulta útil, las generaciones de los propietarios participantes o la procedencia, de modo que los consumidores no puedan inferir que la información del paquete, la configuración y el entorno de ejecución se observaron simultáneamente.

Mantener la autoridad del resolvedor específica de la familia

La colisión y la precedencia entre elementos nativos y complementos no constituyen una política global del catálogo. RFC #8850 proporciona el comportamiento de colisión entre elementos nativos y complementos para canales y herramientas. El catálogo proyecta ese resultado para channel:* y tool:*.

Para proveedores, backends de memoria, observadores, habilidades e integraciones de plataforma sin un resolutor definido por el propietario, el catálogo informa de cada implementación coincidente con evidencia explícita de conflictos sin resolver o desconocidos y no aplica ningún orden implícito. Un resolutor definido posteriormente por el propietario puede convertirse en la fuente de esa familia sin convertir el catálogo en el resolutor.

Mantén la visibilidad separada de la autoridad

La visibilidad del catálogo puede restringir lo que puede ver un usuario, la UI, la API o un agente. No puede conceder autoridad para invocar.

Los registros de herramientas de agentes, los perfiles de riesgo, el acotamiento por ejecución, la política de destino, las concesiones, las aprobaciones y la autorización con ámbito de sujeto permanecen fuera del catálogo. Un consumidor como #8367 puede derivar orientación puntual a partir de la evidencia del catálogo y de la política específica del sujeto, pero esa orientación es una proyección. No autoriza una acción, no escribe el estado del ciclo de vida ni se convierte en un hecho de una instancia configurada.

Las proyecciones públicas excluyen credenciales, referencias a secretos, valores de configuración sin procesar, autenticación del registro, identidad del host, rutas de sistema de archivos sin restricciones, errores de ejecución sin procesar y campos privados del manifiesto. El texto del registro y del manifiesto son metadatos no confiables y deben representarse como datos, no como instrucciones.

Preservar la compatibilidad antes de la convergencia

GET /api/plugins sigue siendo una proyección centrada en paquetes mientras se estabiliza el trabajo con paquetes. /api/integrations sigue siendo una proyección de compatibilidad sobre el catálogo compartido hasta que una decisión de compatibilidad independiente autorice su retirada, redirección o una ruptura de la API estable.

CLI, web, ZeroCode, la pasarela y la preparación orientada a agentes consumen proyecciones versionadas del mismo contrato. Los campos aditivos pueden introducirse de forma compatible. Los cambios de identificadores, la retirada de rutas, la migración de la configuración, los compromisos de estabilidad de la API pública y la política de confianza del marketplace requieren una revisión independiente con planes de reversión y compatibilidad.

La identidad de los paquetes debe corresponderse con las líneas existentes del registro, en lugar de crear otro sistema de coordenadas no relacionado. El trabajo de implementación debe conciliar las coordenadas de los paquetes con la identidad de paquetes al estilo MCP y con la línea del registro OCI propuesta por separado antes de que un segundo consumidor dependa de ellas.

El vocabulario de evidencias sigue intencionadamente las prácticas consolidadas de estado distribuido: la semántica de condiciones al estilo de Kubernetes para los hechos conocidos, desconocidos y observados, y la distinción de systemd entre la intención de habilitación y el estado de ejecución activo. ZeroClaw no necesita importar esos sistemas en su totalidad, pero el catálogo debería conservar esa separación.

Controles de aceptación

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

los artefactos de paquetes, las capacidades, las implementaciones, las instancias configuradas, las observaciones en tiempo de ejecución y las evidencias de estado se documentan con ejemplos representativos de canales, proveedores, herramientas, plataformas y paquetes con múltiples capacidades;
cada identidad de capacidad lógica proviene de una declaración tipada proporcionada por el propietario, y el catálogo no puede inferir una a partir de nombres de invocables o categorías amplias de capacidades;
cada campo de estado proyectado indica su fuente de verdad y utiliza correctamente las semánticas de conocido, desconocido y no aplicable;
la disponibilidad del paquete, la instalación, la admisión, la configuración, la habilitación, la activación, el estado de salud y la preparación orientada al agente siguen pudiéndose representar de forma independiente y no son modificables a través del catálogo;
el comportamiento de las colisiones entre canales y herramientas integrados y de complementos coincide con el de #8850, mientras que las demás familias de capacidades permanecen explícitamente sin resolver a menos que su responsable defina un resolutor;
las capacidades proporcionadas por el paquete y las observaciones del tiempo de ejecución permanecen vinculadas a la procedencia exacta del artefacto a través de las diferencias entre las versiones instaladas y disponibles, las actualizaciones, las recargas y las generaciones del tiempo de ejecución;
las proyecciones públicas exponen metadatos de generación o procedencia y no implican coherencia atómica entre propietarios independientes;
la visibilidad del catálogo no puede otorgar autoridad de invocación ni omitir las comprobaciones de agente, turno, destino, concesión, aprobación o política;
/api/plugins y /api/integrations cuentan con un puente de compatibilidad aditivo antes de cualquier convergencia de rutas, retirada o compromiso con una API estable; y
La identidad de las coordenadas del paquete se coteja con las directrices existentes de los registros MCP y OCI antes de que más de un consumidor de paquetes dependa de ella.

Consecuencias

Consecuencias positivas:

Los colaboradores pueden indicar si un hecho se refiere a la disponibilidad de un paquete, su instalación, configuración, habilitación, activación, estado de salud o preparación.
La CLI, la pasarela, la web, ZeroCode y las instrucciones dirigidas a los agentes pueden usar un mismo vocabulario sin copiar el estado del ciclo de vida.
Las implementaciones integradas y de complementos pueden coexistir sin pretender que todas las integradas hayan migrado a WASM.
Las afirmaciones sobre el estado y la activación en tiempo de ejecución pasan a estar respaldadas por evidencias, en lugar de inferirse a partir de la configuración o de la presencia del paquete.
El trabajo de compatibilidad puede realizarse de forma aditiva antes de cambiar las rutas públicas o la terminología.

Consecuencias negativas:

El contrato del catálogo es más complejo que una única enumeración status.
Los responsables de las familias de capacidades deben añadir declaraciones tipadas antes de que sus capacidades puedan integrarse correctamente.
Los responsables del runtime deben publicar observaciones asociadas a una generación antes de que el catálogo pueda informar de evidencias de actividad o de estado de salud.
La convergencia de la API es más lenta porque /api/plugins y /api/integrations deben pasar por capas de compatibilidad.
La conciliación de las coordenadas de los paquetes debe realizarse con suficiente antelación para evitar otro sistema de identidad del registro.

ZeroClaw Docs