Reconciliation Runbook

The reconciliation engine (financial_integrity, migration 017/021/022) evaluates invariant checks over D1 and records findings + deduplicated exceptions. It never auto-repairs money — only state-surfacing fixes (stale lease release) are automatic; everything else stays needs_review/exception until an operator acts.

Running a scan

POST /api/v1/admin/reconciliation/run        # start/resume {run_id?}
GET  /api/v1/admin/reconciliation/reports
GET  /api/v1/admin/reconciliation/report/:id

• A run is running (resumable via cursor), completed, degraded (some check ERROR/INCOMPLETE — partial coverage, never reported as completed), or failed.
• The 5-minute cron also runs: outbox dispatch → settlement sweep → one recon run → audit assurance.
• yp integrity status|report|verify (devpay-cli) is a read-only wrapper over these endpoints.

Check findings → exceptions

Each check maps findings to reconciliation_findings rows; the engine then syncs them into reconciliation_exceptions by fingerprint:

1. New fingerprint → OPEN exception + event.
2. Re-observed → occurrence_count+1 (no new row); from REVERIFYING/terminal → REOPENED.
3. Absent + producing check completed while REVERIFYING → RESOLVED.

Triage workflow

GET /api/v1/admin/financial-integrity/summary                 # severity counts, stale items
GET /api/v1/admin/financial-integrity/exceptions?status=OPEN
POST .../exceptions/:id/transition {to_status:"TRIAGED", reason:"..."}

• auto_fixed findings (stale outbox/inbox lease, orphan settlement claim release) — verify follow-on delivery, then close via CLOSED_AS_FALSE_POSITIVE only if truly benign; otherwise continue the state machine.
• needs_review findings (money/entitlement drift) — pick a recovery op from financial-integrity or fix manually, then move REMEDIATING → REVERIFYING and re-run recon or RUN_RECON_VERIFY.
• Alert stub: ≥3 consecutive failed/degraded runs produce an alert:recon_failures audit evidence record (external notification is PLANNED — check audit_evidence via admin endpoints, not email/Slack).

Fail-closed guarantees

• A missing DB row or query error is never treated as clean — checks report ERROR, runs report degraded.
• INCOMPLETE checks report remaining>0 — never silently pass partial scans.