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