Cicle de Vida de l’Escenari de Porta de Decisió + Arquitectura de Magatzem d’Estat

Audience: Engineers implementing scenario execution, run lifecycle, and Audiència: Enginyers que implementen l’execució de scenarios, el cicle de vida d’execució i la persistència de l’estat d’execució.

Taula de continguts

Visió Executiva
Especificació de l’escenari
Cicle de Vida d’Execució de l’Escenari (MCP)
Model d’Estat d’Execució
Flux d’Execució del Pla de Control
Magatzems d’estat d’execució
File per Fitxer Referència Creuada

Executive Overview

Els escenaris defineixen fluxos de treball de divulgació escenificada en una especificació determinista. La capa MCP valida i registra escenaris, després instancia un temps d’execució del pla de control per a cada escenari. Les execucions es persisteixen mitjançant una implementació de RunStateStore (en memòria o SQLite). L’estat de l’execució és només d’append, registrant desencadenants, resultats de portes, decisions, paquets, presentacions i trucades d’eines. 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ó de l’escenari

ScenarioSpec és la definició canònica de l’escenari:

Identificadors (escenari, espai de noms, versió de l’especificació)
Definicions d’escenaris i lògica de portes
Definicions de condicions i consultes d’evidència
Referències d’esquema opcionals i id de llogater per defecte

Les especificacions es validen en carregar per assegurar la unicitat i la coherència interna. F:crates/decision-gate-core/src/core/spec.rs L51-L114

El comportament a nivell d’escenari es defineix mitjançant StageSpec (paquets d’entrada, portals, ramificació, temps d’espera opcional). F:crates/decision-gate-core/src/core/spec.rs L121-L140

Cicle de Vida d’Execució de l’Escenari (MCP)

Defineix Escenari

scenario_define registra un escenari i emmagatzema un temps d’execució al router de l’eina:

Aplicació de l’espai de noms
Validació del registre de capacitats
Validació estricta del comparador
Instanciació de ControlPlane amb la política de confiança actual + política d’ancoratge

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

Iniciar Execució

scenario_start crea un nou estat d’execució utilitzant el pla de control i el persisteix a través de l’emmagatzematge configurat. F:crates/decision-gate-mcp/src/tools/router.rs L760-L814

Estat / Següent / Enviar / Activar

Les eines posteriors operen sobre el runtime emmagatzemat i l’estat d’execució persistit:

scenario_status llegeix l’estat actual
scenario_next avança en funció de les proves disponibles
scenario_submit puja artefactes externs
scenario_trigger injecta un esdeveniment de desencadenament extern

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

Ordenació de Mutacions i Semàntica de Sobrecàrrega

Per als eines de mutació d’estat d’execució de les eines MCP, l’ordre s’aplica per cada clau d’execució (tenant_id, namespace_id, run_id) mitjançant un coordinador de mutació dins del router:

escenari_inici
estat_escenari
escenari_seguent
escenari_enviar
escenari_trigger

Això elimina intencionadament la serialització global entre execucions en la capa MCP mentre preserva l’ordenació determinista dins de la mateixa execució. F:crates/decision-gate-mcp/src/tools/router.rs L812-L991 F:crates/decision-gate-mcp/src/tools/router.rs L2161-L2360

Les sobrecàrregues del pla de control/store es tradueixen en errors de límit de taxa MCP recuperables (ToolError::RateLimited) en lloc de fallades internes genèriques. F:crates/decision-gate-mcp/src/tools/router.rs L3579-L3701 F:crates/decision-gate-core/src/interfaces/mod.rs L252-L329

Els diagnòstics del coordinador de mutacions per execució es poden exposar a través de GET /debug/mutation_stats per a la triatge operativa, però el punt final utilitza el mateix model d’autenticació que les trucades HTTP/SSE MCP i falla tancat (401/403) quan el sol·licitant no està autenticat o no està autoritzat. F:crates/decision-gate-mcp/src/server.rs L812-L851

scenario_submit.payload i scenario_trigger.payload es conserven en els registres d’estat d’execució i s’exporten en els artefactes de runpack per disseny. Les integracions han de tractar aquests canals de càrrega útil com a visibles per a l’auditoria i evitar enviar secrets en brut.

scenario_next pot incloure opcionalment comentaris (resum/traç/prova) en la resposta de l’eina quan ho permeti la política de comentaris del servidor. El comentari de traç reutilitza les avaluacions de portes emmagatzemades; el comentari de prova pot mostrar registres d’avaluació de portes amb la política de divulgació aplicada. F:crates/decision-gate-mcp/src/tools/router.rs L2144-L2257 F:crates/decision-gate-core/src/core/state.rs L357-L394

Model d’Estat d’Execució

L’estat d’execució és un registre estructurat, només d’apèndix, que conté:

Identificadors de llogater, espai de noms, execució, escenari
Estat actual i fase del cicle de vida
Objectius de despachament
Registre de desencadenament, registre d’avaluació de portes, registre de decisions
Paquets, presentacions i transcripcions de trucades d’eines

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

L’estat del cicle d’execució és un enum tancat: active, completed, failed. F:crates/decision-gate-core/src/core/state.rs L72-L85

Flux d’Execució del Pla de Control

El motor del pla de control executa transicions d’escenaris, avalua proves i registra decisions. Manté l’estat d’execució després de transicions clau i utilitza polítiques de confiança/ancoratge configurades en temps d’execució. F:crates/decision-gate-core/src/runtime/engine.rs L153-L178 F:crates/decision-gate-mcp/src/tools/router.rs L2029-L2066

Magatzems d’estat d’execució

Magatzem en Memòria

L’emmagatzematge en memòria està destinat a proves i demostracions. Implementa RunStateStore amb un mapa protegit per un mutex. F:crates/decision-gate-core/src/runtime/store.rs L53-L127

SQLite Store

L’emmagatzematge SQLite proporciona instantànies duradores:

Cada desament emmagatzema JSON canònic més un hash.
Les càrregues verifiquen la integritat del hash i la consistència de la clau.
Les versions es fan un seguiment per execució, amb una poda de retenció opcional.
Mutations (save + register) enqueue into a bounded deterministic writer runtime i es reconeixen només després de la confirmació de la transacció durable.
Writer runtime drains micro-batches (batch_max_ops, batch_max_bytes, batch_max_wait_ms) i executa una transacció durable per lot.
Read paths use a separate read-connection pool (read_pool_size) under WAL, reduint la interferència de lectura/escriptura mentre es preserven les semàntiques de tancament en fallida.

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

La configuració de l’emmagatzematge admet el mode WAL, el mode de sincronització, el temps d’espera ocupat, els límits de retenció, els controls de la cua d’escriptura, els límits de lot i la dimensionament del grup de lectura. F:crates/decision-gate-store-sqlite/src/store.rs L135-L156

Configuració MCP

La capa MCP selecciona el tipus de botiga mitjançant la configuració run_state_store. F:crates/decision-gate-config/src/config.rs L1523-L1582

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Especificació de l’escenari + validació	`crates/decision-gate-core/src/core/spec.rs`	Estructura canònica de l’escenari + invariants.
Model d’estat d’execució	`crates/decision-gate-core/src/core/state.rs`	Estat d’execució + registres només d’addició.
Motor del pla de control	`crates/decision-gate-core/src/runtime/engine.rs`	Execució i flux de decisió.
Cicle de vida de l’eina MCP	`crates/decision-gate-mcp/src/tools/router.rs`	scenario_define/start/next/submit/trigger/status.
Emmagatzematge en memòria	`crates/decision-gate-core/src/runtime/store.rs`	Implementació d’emmagatzematge de prova/determinista.
Emmagatzematge SQLite	`crates/decision-gate-store-sqlite/src/store.rs`	Emmagatzematge durable amb verificació de hash + retenció.
Configuració de l’emmagatzematge	`crates/decision-gate-config/src/config.rs`	selecció de run_state_store + validació.