Recorder Asset Core Decision Gate
Docs
Decision Gate Docs

Deterministic, replayable gate evaluation with auditable decisions.

Asset Core docs

Decision Gate Scenario Lifecycle + State Store Architecture

Audience: Engineers implementing scenario execution, run lifecycle, and run state persistence.

Table of Contents

  1. Executive Overview
  2. Scenario Specification
  3. Scenario Runtime Lifecycle (MCP)
  4. Run State Model
  5. Control Plane Execution Flow
  6. Run State Stores
  7. File-by-File Cross Reference

Executive Overview

Scenarios define staged disclosure workflows in a deterministic spec. The MCP layer validates and registers scenarios, then instantiates a control plane runtime for each scenario. Runs are persisted via a RunStateStore implementation (in-memory or SQLite). The run state is append-only, logging triggers, gate outcomes, decisions, packets, submissions, and tool calls. 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

Scenario Specification

ScenarioSpec is the canonical scenario definition:

  • Identifiers (scenario, namespace, spec version)
  • Stage definitions and gate logic
  • Condition definitions and evidence queries
  • Optional schema references and default tenant id

Specs are validated on load to ensure uniqueness and internal consistency. F:crates/decision-gate-core/src/core/spec.rs L51-L114

Stage-level behavior is defined by StageSpec (entry packets, gates, branching, optional timeout). F:crates/decision-gate-core/src/core/spec.rs L121-L140

Scenario Runtime Lifecycle (MCP)

Define Scenario

scenario_define registers a scenario and caches a runtime in the tool router:

  • Namespace enforcement
  • Capability registry validation
  • Strict comparator validation
  • ControlPlane instantiation with current trust + anchor policy

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

Start Run

scenario_start creates a new run state using the control plane and persists it via the configured store. F:crates/decision-gate-mcp/src/tools/router.rs L760-L814

Status / Next / Submit / Trigger

Subsequent tools operate on the cached runtime and persisted run state:

  • scenario_status reads the current status
  • scenario_next advances based on available evidence
  • scenario_submit uploads external artifacts
  • scenario_trigger injects an external trigger event

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

Mutation Ordering and Overload Semantics

For run-state mutating MCP tools, ordering is enforced per run key (tenant_id, namespace_id, run_id) by an in-router mutation coordinator:

  • scenario_start
  • scenario_status
  • scenario_next
  • scenario_submit
  • scenario_trigger

This intentionally removes global cross-run serialization in the MCP layer while preserving deterministic same-run ordering. F:crates/decision-gate-mcp/src/tools/router.rs L812-L991 F:crates/decision-gate-mcp/src/tools/router.rs L2161-L2360

Control-plane/store overloads map to retryable MCP rate-limit errors (ToolError::RateLimited) rather than generic internal failures. F:crates/decision-gate-mcp/src/tools/router.rs L3579-L3701 F:crates/decision-gate-core/src/interfaces/mod.rs L252-L329

Per-run mutation coordinator diagnostics are exposed via GET /debug/mutation_stats for operational triage, but the endpoint uses the same auth model as HTTP/SSE MCP calls and fails closed (401/403) when the caller is unauthenticated or unauthorized. F:crates/decision-gate-mcp/src/server.rs L812-L851

scenario_submit.payload and scenario_trigger.payload are persisted in run state logs and exported into runpack artifacts by design. Integrations must treat these payload channels as audit-visible and avoid sending raw secrets.

scenario_next can optionally include feedback (summary/trace/evidence) in the tool response when permitted by server feedback policy. Trace feedback reuses stored gate evaluations; evidence feedback can surface gate evaluation records with disclosure policy applied. F:crates/decision-gate-mcp/src/tools/router.rs L2144-L2257 F:crates/decision-gate-core/src/core/state.rs L357-L394

Run State Model

Run state is a structured, append-only log containing:

  • Tenant, namespace, run, scenario identifiers
  • Current stage and lifecycle status
  • Dispatch targets
  • Trigger log, gate evaluation log, decision log
  • Packets, submissions, and tool call transcripts

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

Run lifecycle status is a closed enum: active, completed, failed. F:crates/decision-gate-core/src/core/state.rs L72-L85

Control Plane Execution Flow

The control plane engine executes scenario transitions, evaluates evidence, and records decisions. It persists run state after key transitions and uses trust/anchor policies configured at runtime. F:crates/decision-gate-core/src/runtime/engine.rs L153-L178 F:crates/decision-gate-mcp/src/tools/router.rs L2029-L2066

Run State Stores

In-Memory Store

The in-memory store is intended for tests and demos. It implements RunStateStore with a mutex-protected map. F:crates/decision-gate-core/src/runtime/store.rs L53-L127

SQLite Store

The SQLite store provides durable snapshots:

  • Each save stores canonical JSON plus a hash.
  • Loads verify hash integrity and key consistency.
  • Versions are tracked per run, with optional retention pruning.
  • Mutations (save + register) enqueue into a bounded deterministic writer runtime and are acknowledged only after durable transaction commit.
  • Writer runtime drains micro-batches (batch_max_ops, batch_max_bytes, batch_max_wait_ms) and executes one durable transaction per batch.
  • Read paths use a separate read-connection pool (read_pool_size) under WAL, reducing read/write interference while preserving fail-closed semantics.

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

Store configuration supports WAL mode, sync mode, busy timeout, retention limits, writer queue controls, batch limits, and read-pool sizing. F:crates/decision-gate-store-sqlite/src/store.rs L135-L156

MCP Configuration

The MCP layer selects store type via run_state_store configuration. F:crates/decision-gate-config/src/config.rs L1523-L1582

File-by-File Cross Reference

AreaFileNotes
Scenario spec + validationcrates/decision-gate-core/src/core/spec.rsCanonical scenario structure + invariants.
Run state modelcrates/decision-gate-core/src/core/state.rsRun status + append-only logs.
Control plane enginecrates/decision-gate-core/src/runtime/engine.rsExecution and decision flow.
MCP tool lifecyclecrates/decision-gate-mcp/src/tools/router.rsscenario_define/start/next/submit/trigger/status.
In-memory storecrates/decision-gate-core/src/runtime/store.rsTest/deterministic store implementation.
SQLite storecrates/decision-gate-store-sqlite/src/store.rsDurable store with hash verification + retention.
Store configcrates/decision-gate-config/src/config.rsrun_state_store selection + validation.