# 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:

```bash
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:

```bash
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.

```bash
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:

```bash
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.