Cómo se ejecutan los SOPs

Contrato de tiempo de ejecución

• Las definiciones de SOP se cargan desde <shared>/sops/<sop_name>/SOP.toml y el archivo opcional SOP.md.
• CLI zeroclaw sop gestiona las definiciones sin conexión: list, validate, show, graph, rename, delete.
• Las ejecuciones de SOP se inician mediante un agregador de eventos en vivo (webhook autenticado, MQTT, sistema de archivos o AMQP), mediante el ciclo periódico de mantenimiento de SOP del daemon para los desencadenadores cron, o mediante la herramienta del agente sop_execute. Los tipos de desencadenador restantes (periférico y calendario) están definidos y se pueden asociar, pero todavía no están conectados a una fuente de eventos en vivo (consulta Fan-in de SOP).
• La ejecución de la progresión utiliza las herramientas: sop_status, sop_approve, sop_advance.
• El estado de ejecución es local al proceso por defecto. Con sop.persist_runs = true, una inicialización exitosa del backend SQLite predeterminado lo almacena en <data_dir>/sop/runs.db y restaura las ejecuciones activas tras el reinicio. Un fallo en la inicialización registra una advertencia y recurre a la memoria local del proceso.
• Los registros de auditoría de SOP se almacenan en el backend de memoria configurado bajo la categoría sop.

El estado de ejecución y el historial de auditoría son superficies independientes. Consulta Background work lifecycle para conocer la propiedad del ciclo de vida, la cancelación y la semántica de reinicio.

Flujo de eventos

graph LR
    MQTT[MQTT listener] -->|topic match| Dispatch
    TOOL[sop_execute tool] -->|manual| Dispatch
    WH[Webhook request] -->|authenticated HTTP fan-in| Dispatch
    CRON[Cron trigger] -->|daemon maintenance tick| Dispatch
    GPIO[Peripheral trigger] -.->|defined, unwired| Dispatch

    Dispatch --> Engine[SOP Engine]
    Engine --> Run[SOP Run]
    Run --> Action{Action}
    Action -->|ExecuteStep| Agent[Agent Loop]
    Action -->|WaitApproval| Human[Operator]
    Human -->|sop_approve| Run

Primeros pasos

1. sops_dir no está establecido de forma predeterminada, por lo que la carga de SOP en tiempo de ejecución está desactivada de fábrica. Actívela estableciendo sops_dir a través de la puerta de enlace, zerocode o zeroclaw config set. Un valor relativo se resuelve respecto a la raíz de la instalación (el directorio que contiene config.toml), por lo que el valor documentado shared/sops da como resultado <install>/shared/sops, el mismo directorio en el que escribe el autor de la SOP. Un valor absoluto o con prefijo ~- se utiliza tal cual. Establecerlo de nuevo en "" (o eliminarlo) vuelve a desactivar la carga de SOP en tiempo de ejecución; la CLI sigue recurriendo a <install>/shared/sops para la inspección sin conexión.

   ¿Estás migrando desde una compilación anterior? Los valores relativos de sops_dir ahora se resuelven en relación con la raíz de instalación, de forma coherente con cómo se resuelven los directorios de skill-bundles. Las compilaciones anteriores tenían dos raíces diferentes para la misma configuración, así que comprueba ambas antes de actualizar:

   Mostrar en compilaciones anteriores	Root lo usó	Dónde terminó sops_dir = "shared/sops"
   Carga en tiempo de ejecución y CLI local de zeroclaw sop	data_dir	<data_dir>/shared/sops
   Redacción de SOP para web y RPC	<install>/shared	<install>/shared/shared/sops (doubled segment)

   Ambas ahora apuntan a la única ubicación canónica <install>/shared/sops. Inspecciona ambas ubicaciones antiguas y mueve las definiciones que encuentres allí a <install>/shared/sops; las definiciones que queden en cualquiera de los dos árboles dejarán de ser visibles después de la actualización. Las definiciones creadas a través de la antigua interfaz web o RPC son las más fáciles de pasar por alto, porque se encuentran en la ruta de escritura duplicada en lugar de la ubicación descrita en la documentación.

   Cualquier otro valor relativo se desplaza de la misma manera: sops_dir = "my-sops" pasa de <data_dir>/my-sops (tiempo de ejecución y CLI) o <install>/shared/my-sops (creación web y mediante RPC) a <install>/my-sops. Los valores absolutos y los valores con prefijo ~- no se ven afectados.

   El caso no establecido también cambia: la alternativa de la CLI sin conexión antes exploraba <data_dir>/sops y ahora explora <install>/shared/sops.

   zeroclaw sop list lee la nueva ubicación, por lo que un listado vacío después de la actualización significa que las definiciones todavía se encuentran en uno de los árboles antiguos.

2. Crea un directorio de SOP, por ejemplo:

   ~/.zeroclaw/shared/sops/deploy-prod/SOP.toml
   ~/.zeroclaw/shared/sops/deploy-prod/SOP.md
   

3. Validar e inspeccionar definiciones:

   sh

   zeroclaw sop list
   zeroclaw sop validate
   zeroclaw sop show deploy-prod
   

4. El desencadenante se ejecuta a través de las fuentes de eventos configuradas o manualmente desde un turno de agente con sop_execute.

Cambiar el nombre de un POE

El nombre de un SOP es su dirección: la definición reside en <sops>/<name>/, y cada superficie de edición guarda un SOP con el nombre que recibió. Guardar un SOP editado con un nombre distinto escribiría una segunda copia y dejaría el original, por lo que un guardado de edición rechaza por completo cualquier cambio de nombre. Cambiar el nombre es una operación independiente.

zeroclaw sop rename deploy-prod deploy-production

El daemon expone la misma operación como el método RPC sops/rename, que recibe {"from": "...", "to": "..."}, y como POST /api/sops/{name}/rename con un cuerpo {"to": "..."}. Un nombre de destino ya ocupado se devuelve como conflicto (409, código RPC -32020); un SOP de origen desconocido se devuelve como no encontrado (404, código RPC -32021).

Cambio de nombre:

• Rechaza un nombre de destino que ya está en uso, por lo que nunca puede fusionar dos SOP;
• rechaza un destino que no sea un único componente de ruta, la misma comprobación que aplican todas las demás operaciones de SOP que reciben un nombre;
• rechaza una fuente que no sea un directorio real ubicado en la raíz de SOP. Un enlace simbólico (symlink) en esa ubicación pasaría la comprobación de nombre y luego redirigiría todas las lecturas y escrituras hacia cualquier destino al que apunte, por lo que la comprobación de nombre se realiza sin seguir los enlaces y confirma que la fuente se resuelve dentro de la raíz antes de leer nada;
• vuelve a ejecutar la validación estricta al guardar, por lo que no puede volver a escribir en disco una definición que la superficie de autoría habría rechazado al escribirla;
• Cambia solo el valor de [sop] name en SOP.toml, manteniendo el comentario y el espaciado de esa línea. Los pasos, los disparadores, los demás comentarios y SOP.md se dejan exactamente como estaban; el único cambio cosmético es que un nombre entre comillas simples vuelve con comillas dobles.

La mudanza del directorio es un único renombrado del sistema de archivos y se realiza al final, de modo que el SOP existe en exactamente un lugar en todo momento: un renombrado interrumpido no puede dejar ni dos copias ni ninguna. Si un renombrado se interrumpe entre la reescritura del manifiesto y la mudanza, el SOP conserva su directorio anterior mientras el manifiesto ya contiene el nuevo nombre, por lo que zeroclaw sop list informa el nuevo nombre. Volver a ejecutar el mismo renombrado completa el proceso.

Renombrar reescribe la definición en disco, igual que guardar o eliminar una. Un daemon que ya cargó la definición anterior seguirá ejecutándola hasta que vuelva a cargar sus SOP, y el historial de ejecuciones, los registros de auditoría y cualquier otro elemento que haya capturado el nombre anterior conservarán el nombre antiguo.

Las escrituras de autoría se serializan. Crear, guardar, eliminar y renombrar obtienen todos un bloqueo consultivo sobre el archivo .sop-authoring.lock en la raíz de SOP antes de tocar nada, de modo que dos de ellas no pueden intercalarse, ni siquiera entre procesos: la CLI que escribe en una raíz donde un demonio en ejecución también realiza autoría espera su turno en lugar de competir con él. Una llamada de autoría que no pueda obtener el bloqueo en diez segundos falla en lugar de encolarse indefinidamente. Las lecturas no se serializan. Cada archivo que escribe una llamada de autoría se reemplaza mediante un renombrado atómico, de modo que un lector nunca ve un archivo truncado o a medio escribir. Un guardado escribe dos archivos, SOP.toml y SOP.md, uno después del otro, por lo que un lector que se ejecute durante un guardado puede ver brevemente el manifiesto de una revisión y los pasos de otra, y un lector que coincida con el primer guardado de un SOP nuevo puede ver su manifiesto antes de que existan sus pasos. La siguiente lectura tras el guardado devuelve ambos archivos en la nueva revisión.

Cada paso se confirma mediante un renombrado, de modo que ni un lector común ni un proceso terminado forzosamente llegan a ver un paso a medias. Después, se sincroniza al disco el directorio que contiene cada entrada renombrada, de modo que en Unix el orden también sobrevive a un fallo de la máquina. Si esa sincronización falla después de que el renombrado ya se haya producido, la operación termina igualmente y el fallo se registra en el log: el cambio está completo y es visible, y solo se pierde la garantía frente a fallos para esa entrada. macOS respeta la sincronización para el orden sin forzar el vaciado de la caché del dispositivo, y Windows no tiene una primitiva de sincronización de directorios; por lo tanto, en esas plataformas el último paso de la garantía depende del sistema de archivos y no es algo que ZeroClaw pueda forzar.

Para detalles de enrutamiento de disparadores y autenticación, consulta SOP Fan-In.