Jarca
67d8d4871b
confirm dcy-002 and add REQ/BAT evidence add ledger backup/status metadata workflow document restore as runbook/script-only guarded operation add synthetic DB backup/restore smoke tests
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# 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.
|