gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
67d8d4871bb788f351e191f60641debd205b6147
jarca-ledger-mcp/docs/batches/bat-002_20260627_operational-safety-backup-restore-validation-db/design.md
T
Jarca 67d8d4871b feat: add ledger backup safety workflow 
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
2026-06-27 10:40:06 +09:00

3.0 KiB
Raw Blame History

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.
View Git Blame Copy Permalink