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
43 lines
3.0 KiB
Markdown
43 lines
3.0 KiB
Markdown
# BAT-002 Design
|
|
|
|
## Architecture Summary
|
|
BAT-002 adds a small operational-safety layer around the existing SQLite ledger without changing transaction schemas. The service layer produces metadata-only DB evidence, creates backups with SQLite's online backup API, lists backup files, and validates one backup file. MCP exposes only non-destructive backup/status operations. Restore remains a repo script/runbook workflow requiring explicit user approval before overwriting a target DB.
|
|
|
|
## Changed Areas
|
|
- `jarca_ledger_mcp/service.py`
|
|
- New constants: default backup directory and restore policy.
|
|
- New helpers: sha256, file metadata, read-only SQLite status, safe table counts, aggregate totals.
|
|
- New public functions: `get_ledger_db_status`, `create_ledger_backup`, `list_ledger_backups`, `get_ledger_backup_status`.
|
|
- `jarca_ledger_mcp/server.py`
|
|
- New additive MCP tools for backup/status/list/hash only.
|
|
- No restore MCP tool.
|
|
- `scripts/ledger_restore_smoke.py`
|
|
- Script-only restore smoke helper with explicit overwrite approval token.
|
|
- Docs/tests
|
|
- Synthetic tests and operational runbook/baseline docs.
|
|
|
|
## Key Decisions
|
|
1. Backup creation uses SQLite online backup API rather than raw copy so WAL-mode DBs are copied consistently.
|
|
2. Backup evidence returns metadata only: path, size, mtime, sha256, integrity result, table row counts, and aggregate totals by cashflow kind.
|
|
3. Retention policy implements "recent 30 days OR recent 20 files" by pruning only files that are both older than the retention window and outside the newest count.
|
|
4. Restore is deliberately excluded from MCP. The script exists for fixture/validation DB restore smoke and requires `RESTORE_APPROVED` for overwriting any existing target.
|
|
5. Existing success response shapes are preserved; all new response fields are additive under new tools/functions.
|
|
|
|
## Edge Cases
|
|
- Missing source DB: backup/status returns `not_found` rather than initializing or mutating a new DB.
|
|
- Empty backup directory: list returns success with zero backups.
|
|
- Invalid/corrupt backup: backup status includes integrity error metadata and restore smoke fails before copying.
|
|
- Existing target restore path: restore smoke fails unless `--allow-overwrite --approval-token RESTORE_APPROVED` are supplied.
|
|
- Sensitive row data: metadata collection never selects merchant, counterparty, account number, raw_payload, or raw financial file content.
|
|
|
|
## Architecture Impact
|
|
- runtime-flows: updated with backup/status and restore-restricted operational flow.
|
|
- data-model: updated with backup artifact and evidence policy notes.
|
|
- interface-contract: updated with new MCP tools and explicit no-restore-MCP rule.
|
|
|
|
## Reference Doc Update Plan
|
|
- Update `docs/runtime-flows.md` with operational backup/validation/restore-smoke flow and high-risk flow constraints.
|
|
- Update `docs/data-model.md` with backup artifact/evidence persistence boundary.
|
|
- Update `docs/interface-contract.md` with additive backup/status tools and restore non-exposure.
|
|
- Add `docs/runbooks/ledger-backup-restore.md`.
|