jarca-ledger-mcp/docs/batches/bat-002_20260627_operational-safety-backup-restore-validation-db/implementation.md

BAT-002 Implementation

Plan Summary

Implemented REQ-002 as a staged additive operational-safety change. No transaction schema migration, operating DB restore, or broad data rewrite was performed.

Changed Files

• jarca_ledger_mcp/service.py
  • Added metadata-only DB status helpers.
  • Added SQLite online backup creation with retention enforcement.
  • Added backup list/status/hash functions.
  • Added explicit restore policy metadata (mcp_restore_exposed: false).
• jarca_ledger_mcp/server.py
  • Added MCP tools: get_ledger_db_status, create_ledger_backup, list_ledger_backups, get_ledger_backup_status.
  • Did not add any restore MCP tool.
• scripts/ledger_restore_smoke.py
  • Added script-only restore smoke helper with overwrite approval token.
• tests/test_backup_workflow.py
  • Added synthetic DB tests for metadata-only status, backup create/list/status/hash, retention pruning, and sensitive evidence exclusion.
• docs/runbooks/ledger-backup-restore.md
  • Added operator runbook and QC checklist.
• docs/runtime-flows.md
  • Added operational backup/validation/restore smoke runtime flow.
• docs/data-model.md
  • Added LedgerBackupArtifact and metadata-only persistence notes.
• docs/interface-contract.md
  • Added backup/status MCP contract and restore non-exposure rule.
• StagePilot docs
  • docs/srs/Non-Functional/req-002_operational-safety-backup-restore-validation-db.md
  • docs/srs/index.md
  • docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
  • docs/batches/index.md
  • docs/batches/bat-002_20260627_operational-safety-backup-restore-validation-db/*

Execution Log

• RED test first:
  • Command: source .venv/bin/activate && pytest tests/test_backup_workflow.py -q
  • Initial result: failed with missing service.get_ledger_db_status, create_ledger_backup, list_ledger_backups, get_ledger_backup_status attributes.
• Implemented service/server/script/docs changes.
• Targeted test:
  • Command: source .venv/bin/activate && pytest tests/test_backup_workflow.py -q
  • Result: 3 passed.
• Full syntax/test:
  • Command: source .venv/bin/activate && python -m py_compile jarca_ledger_mcp/*.py dashboard/app.py && pytest tests/test_backup_workflow.py -q && pytest -q
  • Result: backup tests passed, full suite passed with ...........ss.........ss [100%].
• Full pytest summary:
  • Command: source .venv/bin/activate && pytest -ra
  • Result: 20 passed, 4 skipped in 16.02s; skips are sample KB/Toss PDF tests without sample files/passwords.
• Restore smoke:
  • Command: created synthetic tmp DB, created backup via service.create_ledger_backup, then ran python scripts/ledger_restore_smoke.py --backup <tmp backup> --target <tmp restored.sqlite3>.
  • Result: success: true, backup and restored target integrity_check: ok, table counts {accounts: 1, transactions: 1, budgets: 0, import_batches: 0, category_rules: 0, ledger_categories: 0}, health check active_transactions: 1.
• MCP surface check:
  • Command: source .venv/bin/activate && hermes mcp test jarca-ledger
  • Result: connected, Tools discovered: 45, including backup/status tools and no restore tool.

Validation

• Synthetic DB tests confirmed no operating DB is needed for backup/status/list/hash verification.
• Restore smoke used /tmp/... source/target only, not /root/.local/share/jarca/ledger.sqlite3.
• Evidence captured only path, size, mtime, sha256, integrity, row counts, aggregate totals, and health/test results.

Remaining Risks

• Real operating DB restore remains intentionally untested and requires separate explicit user approval.
• Browser/UI copy is not changed in this batch; operator safety guidance is runbook/MCP/script level only.