Ciclo de Vida del Escenario de Puerta de Decisión + Arquitectura de Almacenamiento de Estado

Audience: Engineers implementing scenario execution, run lifecycle, and Audiencia: Ingenieros que implementan la ejecución de escenarios, el ciclo de vida de ejecución y la persistencia del estado de ejecución.

Tabla de Contenidos

Resumen Ejecutivo
Especificación del Escenario
Ciclo de Vida de Ejecución de Escenarios (MCP)
Modelo de Estado de Ejecución
Flujo de Ejecución del Plano de Control
Ejecutar Almacenes de Estado
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

Los escenarios definen flujos de trabajo de divulgación escalonados en una especificación determinista. La capa MCP valida y registra escenarios, luego instancia un tiempo de ejecución del plano de control para cada escenario. Las ejecuciones se persisten a través de una implementación de RunStateStore (en memoria o SQLite). El estado de la ejecución es solo de adición, registrando disparadores, resultados de puertas, decisiones, paquetes, presentaciones y llamadas a herramientas. F:crates/decision-gate-core/src/core/spec.rs L51-L114 F:crates/decision-gate-mcp/src/tools/router.rs L721-L895 F:crates/decision-gate-core/src/core/state.rs L357-L394

Especificación del Escenario

ScenarioSpec es la definición canónica del escenario:

Identificadores (escenario, espacio de nombres, versión de especificación)
Definiciones de etapas y lógica de puertas
Definiciones de condiciones y consultas de evidencia
Referencias de esquema opcionales e id de inquilino por defecto

Las especificaciones se validan al cargar para garantizar la unicidad y la consistencia interna. F:crates/decision-gate-core/src/core/spec.rs L51-L114

El comportamiento a nivel de etapa está definido por StageSpec (paquetes de entrada, puertas, ramificación, tiempo de espera opcional). F:crates/decision-gate-core/src/core/spec.rs L121-L140

Ciclo de Vida de Ejecución de Escenarios (MCP)

Definir Escenario

scenario_define registra un escenario y almacena un tiempo de ejecución en el enrutador de herramientas:

Aplicación de espacio de nombres
Validación del registro de capacidades
Validación estricta del comparador
Instanciación de ControlPlane con la política de confianza actual + política de anclaje

F:crates/decision-gate-mcp/src/tools/router.rs L721-L749 F:crates/decision-gate-mcp/src/tools/router.rs L2045-L2066

Iniciar Ejecución

scenario_start crea un nuevo estado de ejecución utilizando el plano de control y lo persiste a través del almacén configurado. F:crates/decision-gate-mcp/src/tools/router.rs L760-L814

Estado / Siguiente / Enviar / Activar

Las herramientas posteriores operan en el tiempo de ejecución en caché y el estado de ejecución persistido:

scenario_status lee el estado actual
scenario_next avanza en función de la evidencia disponible
scenario_submit carga artefactos externos
scenario_trigger inyecta un evento de activación externo

F:crates/decision-gate-mcp/src/tools/router.rs L816-L977

Orden de Mutación y Semántica de Sobrecarga

Para las herramientas MCP que mutan el estado de ejecución, el orden se aplica por clave de ejecución (tenant_id, namespace_id, run_id) mediante un coordinador de mutación en el enrutador:

scenario_start
estado_del_escenario
escenario_siguiente
scenario_submit
scenario_trigger

Esto elimina intencionadamente la serialización global entre ejecuciones en la capa MCP mientras preserva el orden determinista en la misma ejecución. F:crates/decision-gate-mcp/src/tools/router.rs L812-L991 F:crates/decision-gate-mcp/src/tools/router.rs L2161-L2360

Los desbordamientos del plano de control/store se traducen en errores de límite de tasa MCP reintentables (ToolError::RateLimited) en lugar de fallos internos genéricos. F:crates/decision-gate-mcp/src/tools/router.rs L3579-L3701 F:crates/decision-gate-core/src/interfaces/mod.rs L252-L329

Los diagnósticos del coordinador de mutaciones por ejecución se exponen a través de GET /debug/mutation_stats para el triaje operativo, pero el endpoint utiliza el mismo modelo de autenticación que las llamadas HTTP/SSE MCP y falla en modo cerrado (401/403) cuando el llamador no está autenticado o no está autorizado. F:crates/decision-gate-mcp/src/server.rs L812-L851

scenario_submit.payload y scenario_trigger.payload se persisten en los registros de estado de ejecución y se exportan a los artefactos de runpack por diseño. Las integraciones deben tratar estos canales de carga útil como visibles para auditoría y evitar enviar secretos en bruto.

scenario_next puede incluir opcionalmente comentarios (resumen/rastro/evidencia) en la respuesta de la herramienta cuando lo permita la política de comentarios del servidor. Los comentarios de rastro reutilizan las evaluaciones de puerta almacenadas; los comentarios de evidencia pueden mostrar registros de evaluación de puerta con la política de divulgación aplicada. F:crates/decision-gate-mcp/src/tools/router.rs L2144-L2257 F:crates/decision-gate-core/src/core/state.rs L357-L394

Modelo de Estado de Ejecución

El estado de ejecución es un registro estructurado y de solo anexado que contiene:

Identificadores de inquilino, espacio de nombres, ejecución y escenario
Estado actual y estado del ciclo de vida
Objetivos de despacho
Registro de activación, registro de evaluación de puerta, registro de decisiones
Paquetes, envíos y transcripciones de llamadas a herramientas

F:crates/decision-gate-core/src/core/state.rs L357-L394

El estado del ciclo de ejecución es un enum cerrado: activo, completado, fallido. F:crates/decision-gate-core/src/core/state.rs L72-L85

Flujo de Ejecución del Plano de Control

El motor del plano de control ejecuta transiciones de escenario, evalúa evidencia y registra decisiones. Persiste el estado de ejecución después de transiciones clave y utiliza políticas de confianza/anclaje configuradas en tiempo de ejecución. F:crates/decision-gate-core/src/runtime/engine.rs L153-L178 F:crates/decision-gate-mcp/src/tools/router.rs L2029-L2066

Ejecutar Almacenes de Estado

Almacenamiento en Memoria

El almacenamiento en memoria está destinado a pruebas y demostraciones. Implementa RunStateStore con un mapa protegido por mutex. F:crates/decision-gate-core/src/runtime/store.rs L53-L127

Almacén SQLite

El almacenamiento SQLite proporciona instantáneas duraderas:

Cada guardado almacena JSON canónico más un hash.
Las cargas verifican la integridad del hash y la consistencia de la clave.
Las versiones se rastrean por ejecución, con poda de retención opcional.
Mutations (save + register) enqueue into a bounded deterministic writer tiempo de ejecución y se reconocen solo después de la confirmación de la transacción duradera.
Writer runtime drains micro-batches (batch_max_ops, batch_max_bytes, batch_max_wait_ms) y ejecuta una transacción durable por lote.
Read paths use a separate read-connection pool (read_pool_size) under WAL, reduciendo la interferencia de lectura/escritura mientras se preservan las semánticas de cierre en fallo.

F:crates/decision-gate-store-sqlite/src/store.rs L540-L640

La configuración de la tienda admite el modo WAL, el modo de sincronización, el tiempo de espera ocupado, los límites de retención, los controles de cola de escritores, los límites de lotes y la dimensionamiento del grupo de lectura. F:crates/decision-gate-store-sqlite/src/store.rs L135-L156

Configuración de MCP

La capa MCP selecciona el tipo de tienda a través de la configuración run_state_store. F:crates/decision-gate-config/src/config.rs L1523-L1582

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Especificación de escenario + validación	`crates/decision-gate-core/src/core/spec.rs`	Estructura canónica del escenario + invariantes.
Modelo de estado de ejecución	`crates/decision-gate-core/src/core/state.rs`	Estado de ejecución + registros de solo anexado.
Motor de plano de control	`crates/decision-gate-core/src/runtime/engine.rs`	Ejecución y flujo de decisiones.
Ciclo de vida de la herramienta MCP	`crates/decision-gate-mcp/src/tools/router.rs`	scenario_define/start/next/submit/trigger/status.
Almacenamiento en memoria	`crates/decision-gate-core/src/runtime/store.rs`	Implementación de almacenamiento de prueba/determinista.
Almacenamiento SQLite	`crates/decision-gate-store-sqlite/src/store.rs`	Almacenamiento duradero con verificación de hash + retención.
Configuración de almacenamiento	`crates/decision-gate-config/src/config.rs`	Selección de run_state_store + validación.