Financial Integrity Operations

Admin-only operations surface for reconciliation findings, exceptions, and recovery operations. All endpoints require an admin-role JWT (x-dev-user dev identities are never accepted in production config). Implemented on the Cloudflare worker (be-cloudflare) — the Axum backend has no equivalent surface.

API surface

Summary and exceptions

GET  /api/v1/admin/financial-integrity/summary
GET  /api/v1/admin/financial-integrity/exceptions[?status=]
GET  /api/v1/admin/financial-integrity/exceptions/:id          # includes append-only event log
POST /api/v1/admin/financial-integrity/exceptions/:id/transition
     {to_status, reason, note?, operation_id?, correlation_id?}

Exception state machine (enforced by transition_allowed, migration 022):

OPEN → TRIAGED → INVESTIGATING → AWAITING_APPROVAL → REMEDIATING
     → REVERIFYING → RESOLVED | REOPENED
BLOCKED — enter/exit from any non-terminal state
CLOSED_AS_FALSE_POSITIVE — terminal (operator verdict)
REOPENED — engine re-detects fingerprint, or verify fails

• Every transition requires reason; transitions append to reconciliation_exception_events (append-only).
• RESOLVED is reached only via REVERIFYING + the producing check completing without re-observing the fingerprint (engine sync or a verified recovery op).
• Fingerprint dedup: sha256(check_name|entity_type|entity_id|finding_code) — re-observed findings bump occurrence_count instead of creating new rows.

Recovery operations

GET  /api/v1/admin/financial-integrity/operations[?status=]
POST /api/v1/admin/financial-integrity/operations
     {op_type, target_entity_type, target_entity_id,
      expected_state?, reason_code|reason, idempotency_key?}
GET  /api/v1/admin/financial-integrity/operations/:id
POST /api/v1/admin/financial-integrity/operations/:id/approve  {decision: approve|reject, reason}
POST /api/v1/admin/financial-integrity/operations/:id/execute
POST /api/v1/admin/financial-integrity/operations/:id/verify

op_type	target	approval	effect
RELEASE_STALE_SETTLEMENT_CLAIM	settlement_run / order	required	release run:* order claims
REDRIVE_OUTBOX	outbox	required	dead-letter → pending requeue
REPLAY_INBOX_PROCESSING	inbox_event	required	processing/failed → received (never terminal)
APPLY_CONFIRMED_REFUND_INTERNAL	refund_attempt	required	internal effects only — no PG call
RECHECK_PROVIDER_REFUND	refund_attempt	auto-approved	GET-only PG status recheck
RUN_RECON_VERIFY	reconciliation_exception	auto-approved	re-run recon, drive REVERIFYING

Rules:

• status: DRAFT → PENDING_APPROVAL → APPROVED → EXECUTING → VERIFIED | FAILED | CANCELLED
• Money-affecting ops require actor ≠ approver (403 SELF_APPROVAL_DENIED). Read-only recheck ops auto-approve with a system approval record.
• idempotency_key is UNIQUE — resubmission replays the stored operation.
• Execute/verify are CAS-guarded (no double execution); before/after target snapshots + receipt + verification are stored on the op.
• Internal recovery never performs new external PG capture/cancel calls — GET status reads only.

Settlements admin

POST /api/v1/admin/settlements/sweep              # release stale run claims
POST /api/v1/admin/settlements/:id/mark-paid     {payout_ref}   # payout confirmation

Evidence

Every op execute/verify emits a chain-sealed recovery.execute / recovery.verify evidence record (see audit-evidence).

Related runbooks

• reconciliation-runbook — findings → exceptions flow
• refund-recovery — refund attempt lifecycle
• settlement-recovery — settlement run recovery
• incident-response — incident ordering