jarca-ledger-mcp/docs/runbooks/ledger-backup-restore.md

Ledger Backup / Restore / Validation DB Runbook

Purpose

This runbook defines the approved operational safety workflow from dcy-002 / REQ-002. It is designed for Jarca Ledger local SQLite operation and for Hermes agents working under jarcaledgerdev/QC profiles.

Policy Summary

• Default backup directory: /root/.local/share/jarca/backups/ledger/
• Retention: keep backups from the most recent 30 days OR the newest 20 backup files.
• Backup creation/list/status/hash may be exposed as additive MCP tools or scripts.
• Restore execution must not be exposed as an MCP tool.
• Restore execution requires script/runbook use and explicit user approval before touching a real operating DB.
• Preferred validation DB: synthetic fixture DB. If an operating DB copy is needed, keep it outside the repository and report only metadata evidence.

Allowed Evidence

• DB path
• File size
• mtime
• sha256/checksum
• SQLite PRAGMA integrity_check result
• Major table row counts
• Category/report aggregate totals
• Test, health check, or smoke command result

Forbidden Evidence

• Full transaction row dumps
• Full merchant/counterparty dumps
• Full account identifiers/account numbers
• raw_payload
• Original financial file content
• Passwords or encrypted file secrets

Create Backup

From Python/service:

cd /root/projects/jarca-ledger-mcp
source .venv/bin/activate
python - <<'PY'
from jarca_ledger_mcp import service
print(service.create_ledger_backup())
PY

MCP tool equivalent is allowed:

• create_ledger_backup
• list_ledger_backups
• get_ledger_backup_status
• get_ledger_db_status

Validation DB Smoke

Prefer synthetic DB:

cd /root/projects/jarca-ledger-mcp
source .venv/bin/activate
pytest tests/test_backup_workflow.py

For a repo-external validation DB copy, set JARCA_LEDGER_DB_PATH to the copy path before running smoke tests or service checks. Do not commit that DB.

Restore Smoke Script

Restore is script-only and not an MCP operation.

cd /root/projects/jarca-ledger-mcp
source .venv/bin/activate
python scripts/ledger_restore_smoke.py \
  --backup /root/.local/share/jarca/backups/ledger/<backup>.sqlite3 \
  --target /tmp/jarca-ledger-restore-smoke.sqlite3

If the target already exists, overwriting requires explicit approval controls:

python scripts/ledger_restore_smoke.py \
  --backup /root/.local/share/jarca/backups/ledger/<backup>.sqlite3 \
  --target /tmp/jarca-ledger-restore-smoke.sqlite3 \
  --allow-overwrite \
  --approval-token RESTORE_APPROVED

Do not point --target at /root/.local/share/jarca/ledger.sqlite3 unless the user has explicitly approved a real operating DB restore in the current task.

High-Risk Work Checklist

Before import, rollback, categorization apply, reconciliation apply, migration, or any broad DB mutation:

1. Capture get_ledger_db_status for the selected DB.
2. Create a backup or confirm an acceptable recent backup.
3. Prefer running the risky operation against a synthetic fixture or repo-external validation copy first.
4. Capture post-operation status/report aggregates.
5. Record only allowed metadata evidence.
6. Ask QC to confirm no direct operating DB mutation occurred unless explicitly approved.

QC Gate Checklist

QC should verify:

• No source operating DB direct mutation without approval.
• Backup/status/list/hash tools exist and restore MCP tool does not exist.
• Restore path is script/runbook only and approval-gated for overwrite.
• Synthetic fixture or repo-external DB copy smoke evidence exists.
• Docs/tests/logs do not expose forbidden sensitive data.
• Tests and baseline docs are updated.