Merge pull request #30 from PromptExecution/codex-issue-20-persist-mcp-state

feat: persist MCP operational state across restart

Author: elasticdotventures

AGENTS.md

@@ -249,6 +249,10 @@ Treat this as a standing operational gate, not a one-time migration task.
   - Treat `ledger_core::workbook::REQUIRED_SHEETS` as the canonical base workbook contract for export paths.
   - `export_cpa_workbook` should rebuild the full workbook from canonical service state on each export, including `META.config`, `ACCT.registry`, schedule sheets, flag sheets, transaction sheets, and `AUDIT.log`.
   - Tests should assert representative workbook contents, not just that a file was written.
+- 2026-04-17: restart-visible MCP operational state now persists as a deterministic sidecar next to the manifest workbook path.
+  - Persist ingest idempotency state, transaction row cache, audit log, lifecycle event history, and HSM checkpoint together as one snapshot.
+  - Keep the workbook as the human/accountant artifact; do not overload it as the only machine recovery mechanism for agent queues and replay state.
+  - If the sidecar exists but cannot be parsed or its version is unsupported, fail closed instead of silently resetting state.
 
 
 

crates/ledger-core/src/classify.rs

@@ -2,6 +2,7 @@ use std::path::Path;
 
 use crate::ingest::{deterministic_tx_id, TransactionInput};
 use rhai::{Dynamic, Engine, EvalAltResult, Map, Scope, AST};
+use serde::{Deserialize, Serialize};
 
 #[derive(Debug, thiserror::Error)]
 pub enum ClassificationError {
@@ -46,13 +47,13 @@ pub struct ClassificationBatch {
     pub classifications: Vec<ClassifiedTransaction>,
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 pub enum FlagStatus {
     Open,
     Resolved,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct ReviewFlag {
     pub tx_id: String,
     pub year: i32,
@@ -62,7 +63,7 @@ pub struct ReviewFlag {
     pub confidence: f64,
 }
 
-#[derive(Debug, Default)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct ClassificationEngine {
     flags: Vec<ReviewFlag>,
 }
@@ -200,10 +201,16 @@ fn run_classify_fn(
 fn sample_to_map(sample: &SampleTransaction) -> Map {
     let mut tx = Map::new();
     tx.insert("tx_id".into(), Dynamic::from(sample.tx_id.clone()));
-    tx.insert("account_id".into(), Dynamic::from(sample.account_id.clone()));
+    tx.insert(
+        "account_id".into(),
+        Dynamic::from(sample.account_id.clone()),
+    );
     tx.insert("date".into(), Dynamic::from(sample.date.clone()));
     tx.insert("amount".into(), Dynamic::from(sample.amount.clone()));
-    tx.insert("description".into(), Dynamic::from(sample.description.clone()));
+    tx.insert(
+        "description".into(),
+        Dynamic::from(sample.description.clone()),
+    );
     tx
 }
 

crates/ledger-core/src/ingest.rs

@@ -3,8 +3,9 @@ use std::path::Path;
 
 use crate::journal::{append_entries, JournalTransaction};
 use crate::workbook::{materialize_tx_projection, TxProjectionRow};
+use serde::{Deserialize, Serialize};
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct TransactionInput {
     pub account_id: String,
     pub date: String,
@@ -13,13 +14,13 @@ pub struct TransactionInput {
     pub source_ref: String,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct IngestedTransaction {
     pub tx_id: String,
     pub source_ref: String,
 }
 
-#[derive(Debug, Default)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct IngestedLedger {
     seen: BTreeSet<String>,
     projection_rows: Vec<TxProjectionRow>,

crates/ledger-core/src/journal.rs

@@ -75,4 +75,3 @@ fn invert_amount(amount: &str) -> String {
         format!("-{}", trimmed)
     }
 }
-

crates/ledger-core/src/workbook.rs

@@ -1,6 +1,7 @@
 use std::path::Path;
 
 use rust_xlsxwriter::Workbook;
+use serde::{Deserialize, Serialize};
 
 pub const REQUIRED_SHEETS: &[&str] = &[
     "META.config",
@@ -23,7 +24,7 @@ pub fn initialize_workbook(path: &Path) -> Result<(), rust_xlsxwriter::XlsxError
     workbook.save(path)
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct TxProjectionRow {
     pub tx_id: String,
     pub account_id: String,

crates/ledgerr-mcp/Cargo.toml

@@ -7,7 +7,7 @@ license.workspace = true
 [dependencies]
 blake3 = "1.8.3"
 ledger-core = { version = "=1.3.7", path = "../ledger-core" }
-rust_decimal = "1.41.0"
+rust_decimal = { version = "1.41.0", features = ["serde"] }
 rust_xlsxwriter = { workspace = true }
 schemars = { version = "0.8", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }

crates/ledgerr-mcp/src/bin/ledgerr-mcp-server.rs

@@ -219,7 +219,12 @@ fn handle_request(request: Value) -> Option<Value> {
 fn global_service() -> &'static TurboLedgerService {
     static SERVICE: OnceLock<TurboLedgerService> = OnceLock::new();
     SERVICE.get_or_init(|| {
-        let manifest = "[session]\nworkbook_path=\"tax-ledger.xlsx\"\nactive_year=2023\n\n[accounts]\nWF-BH-CHK = { institution = \"Wells Fargo\", type = \"checking\", currency = \"USD\" }\n";
-        TurboLedgerService::from_manifest_str(manifest).expect("default manifest must parse")
+        // Allow test/process callers to inject an explicit manifest so the stdio
+        // transport can exercise restart persistence without sharing one global
+        // relative workbook path across unrelated test processes.
+        let manifest = std::env::var("LEDGERR_MCP_MANIFEST").unwrap_or_else(|_| {
+            "[session]\nworkbook_path=\"tax-ledger.xlsx\"\nactive_year=2023\n\n[accounts]\nWF-BH-CHK = { institution = \"Wells Fargo\", type = \"checking\", currency = \"USD\" }\n".to_string()
+        });
+        TurboLedgerService::from_manifest_str(&manifest).expect("default manifest must parse")
     })
 }

crates/ledgerr-mcp/src/contract.rs

@@ -599,23 +599,23 @@ Expected blocked outcomes:\n\n\
 
 pub fn generated_mcp_cli_demo_script() -> String {
     "#!/usr/bin/env bash\nset -euo pipefail\n\n\
-JOURNAL_PATH=\"${{JOURNAL_PATH:-/tmp/demo.beancount}}\"\n\
-WORKBOOK_PATH=\"${{WORKBOOK_PATH:-/tmp/demo.xlsx}}\"\n\
-SOURCE_REF=\"${{SOURCE_REF:-wf-2023-01.rkyv}}\"\n\n\
+JOURNAL_PATH=\"${JOURNAL_PATH:-/tmp/demo.beancount}\"\n\
+WORKBOOK_PATH=\"${WORKBOOK_PATH:-/tmp/demo.xlsx}\"\n\
+SOURCE_REF=\"${SOURCE_REF:-wf-2023-01.rkyv}\"\n\n\
 cargo run -q -p ledgerr-mcp --bin ledgerr-mcp-server <<EOF\n\
-{{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{{\"clientInfo\":{{\"name\":\"demo\",\"version\":\"0.1.0\"}}}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\",\"params\":{{}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{{}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_documents\",\"arguments\":{{\"action\":\"pipeline_status\"}}}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_documents\",\"arguments\":{{\"action\":\"list_accounts\"}}}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_documents\",\"arguments\":{{\"action\":\"ingest_pdf\",\"pdf_path\":\"WF--BH-CHK--2023-01--statement.pdf\",\"journal_path\":\"$JOURNAL_PATH\",\"workbook_path\":\"$WORKBOOK_PATH\",\"raw_context_bytes\":[99,116,120],\"extracted_rows\":[{{\"account_id\":\"WF-BH-CHK\",\"date\":\"2023-01-15\",\"amount\":\"-42.11\",\"description\":\"Coffee Shop\",\"source_ref\":\"$SOURCE_REF\"}}]}}}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_documents\",\"arguments\":{{\"action\":\"get_raw_context\",\"rkyv_ref\":\"$SOURCE_REF\"}}}}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"clientInfo\":{\"name\":\"demo\",\"version\":\"0.1.0\"}}}\n\
+{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\",\"params\":{}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_documents\",\"arguments\":{\"action\":\"pipeline_status\"}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_documents\",\"arguments\":{\"action\":\"list_accounts\"}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_documents\",\"arguments\":{\"action\":\"ingest_pdf\",\"pdf_path\":\"WF--BH-CHK--2023-01--statement.pdf\",\"journal_path\":\"$JOURNAL_PATH\",\"workbook_path\":\"$WORKBOOK_PATH\",\"raw_context_bytes\":[99,116,120],\"extracted_rows\":[{\"account_id\":\"WF-BH-CHK\",\"date\":\"2023-01-15\",\"amount\":\"-42.11\",\"description\":\"Coffee Shop\",\"source_ref\":\"$SOURCE_REF\"}]}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_documents\",\"arguments\":{\"action\":\"get_raw_context\",\"rkyv_ref\":\"$SOURCE_REF\"}}}\n\
 EOF\n\n\
 # Troubleshooting path\n\
 cat <<'EOF'\n\
-{{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_workflow\",\"arguments\":{{\"action\":\"resume\",\"state_marker\":\"invalid-checkpoint\"}}}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_reconciliation\",\"arguments\":{{\"action\":\"commit\",\"source_total\":\"100.00\",\"extracted_total\":\"95.00\",\"posting_amounts\":[\"-95.00\",\"95.00\"]}}}}}}\n\
-{{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{{\"name\":\"ledgerr_audit\",\"arguments\":{{\"action\":\"event_history\",\"time_start\":\"2026-12-31\",\"time_end\":\"2026-01-01\"}}}}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_workflow\",\"arguments\":{\"action\":\"resume\",\"state_marker\":\"invalid-checkpoint\"}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_reconciliation\",\"arguments\":{\"action\":\"commit\",\"source_total\":\"100.00\",\"extracted_total\":\"95.00\",\"posting_amounts\":[\"-95.00\",\"95.00\"]}}}\n\
+{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"ledgerr_audit\",\"arguments\":{\"action\":\"event_history\",\"time_start\":\"2026-12-31\",\"time_end\":\"2026-01-01\"}}}\n\
 EOF\n"
         .to_string()
 }

crates/ledgerr-mcp/src/events.rs

@@ -1,10 +1,11 @@
 use std::collections::BTreeMap;
 
 use crate::ToolError;
+use serde::{Deserialize, Serialize};
 
 const EVENT_TYPES: &[&str] = &["ingest", "classification", "reconciliation", "adjustment"];
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct LifecycleEvent {
     pub event_id: String,
     pub sequence: u64,
@@ -22,7 +23,7 @@ pub struct AppendEventResult {
     pub sequence: u64,
 }
 
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 pub struct EventHistoryFilter {
     pub tx_id: Option<String>,
     pub document_ref: Option<String>,
@@ -54,7 +55,7 @@ pub trait LifecycleEventStore {
     fn list_events(&self, filter: EventHistoryFilter) -> Result<EventHistoryResponse, ToolError>;
 }
 
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct InMemoryLifecycleEventStore {
     events: Vec<LifecycleEvent>,
     next_sequence: u64,
@@ -233,10 +234,7 @@ pub fn reconstruct_lifecycle(events: &[LifecycleEvent]) -> ReplayProjection {
             expected_sequence = expected_sequence.saturating_add(1);
         }
 
-        let tx_id = event
-            .tx_id
-            .clone()
-            .unwrap_or_else(|| "_stream".to_string());
+        let tx_id = event.tx_id.clone().unwrap_or_else(|| "_stream".to_string());
         let current_stage = stage_by_tx.get(&tx_id).cloned();
         if current_stage.is_none() && event.event_type != "ingest" {
             diagnostics.push(format!(

crates/ledgerr-mcp/src/hsm.rs

@@ -1,4 +1,6 @@
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
 pub enum LifecycleState {
     Ingest,
     Normalize,
@@ -33,7 +35,7 @@ impl LifecycleState {
     }
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
 pub enum LifecycleSubstate {
     Pending,
     Ready,
@@ -56,7 +58,7 @@ impl LifecycleSubstate {
     }
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
 pub struct LifecycleNode {
     pub state: LifecycleState,
     pub substate: LifecycleSubstate,
@@ -110,7 +112,7 @@ pub struct HsmResumeResponse {
     pub blockers: Vec<String>,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct HsmMachine {
     pub current: LifecycleNode,
     pub last_valid_checkpoint: String,
@@ -130,7 +132,11 @@ impl Default for HsmMachine {
 }
 
 pub fn checkpoint_marker(node: LifecycleNode) -> String {
-    format!("{}:{}:advanced", node.state.as_str(), node.substate.as_str())
+    format!(
+        "{}:{}:advanced",
+        node.state.as_str(),
+        node.substate.as_str()
+    )
 }
 
 pub fn parse_checkpoint_marker(marker: &str) -> Option<LifecycleNode> {
@@ -144,7 +150,11 @@ pub fn parse_checkpoint_marker(marker: &str) -> Option<LifecycleNode> {
     parse_node(state, substate)
 }
 
-pub fn resume_response(node: LifecycleNode, resumed: bool, mut blockers: Vec<String>) -> HsmResumeResponse {
+pub fn resume_response(
+    node: LifecycleNode,
+    resumed: bool,
+    mut blockers: Vec<String>,
+) -> HsmResumeResponse {
     blockers.sort();
     blockers.dedup();
     HsmResumeResponse {
@@ -195,7 +205,10 @@ pub fn next_hint_for(node: LifecycleNode) -> String {
     .to_string()
 }
 
-pub fn transition_blocked_response(current: LifecycleNode, requested: LifecycleNode) -> HsmTransitionResponse {
+pub fn transition_blocked_response(
+    current: LifecycleNode,
+    requested: LifecycleNode,
+) -> HsmTransitionResponse {
     let mut transition_evidence = vec![
         format!("from={}", current.token()),
         format!("to={}", requested.token()),
@@ -212,7 +225,11 @@ pub fn transition_blocked_response(current: LifecycleNode, requested: LifecycleN
         status: "blocked".to_string(),
         guard_reason: Some("invalid_transition".to_string()),
         transition_evidence,
-        state_marker: format!("{}:{}:blocked", current.state.as_str(), current.substate.as_str()),
+        state_marker: format!(
+            "{}:{}:blocked",
+            current.state.as_str(),
+            current.substate.as_str()
+        ),
     }
 }