reconciliation job that detects and reports swap state drift

[mikewheeleer]

Summary

Nothing detects when swap records drift from their expected invariants (e.g. sums that must balance, statuses that must be consistent). Add a reconciliation routine that scans, detects drift, and reports it.

Why this matters

Silent drift in financial state compounds into real losses. A reconciliation pass turns invisible corruption into an actionable, tested signal.

Requirements

• Define the swap invariants that must always hold.
• Implement a bounded, idempotent scan that checks each invariant and collects violations.
• Emit a structured report (counts + offending ids + reason); never mutate silently.
• Expose it as a callable job with a summary result.

Technical guidance

• Keep the scan chunked and side-effect-free by default.
• Make invariants individually testable.

Edge cases — each must have a test

• consistent data -> zero violations
• an injected imbalance -> reported with the offending id
• an inconsistent status -> reported
• large dataset -> scan stays bounded
• the report is deterministic

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Auto-remediation of drift
• Scheduling/cron wiring

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.