Skip to content

reconciliation job that detects and reports charge state drift #548

Description

@mikewheeleer

Summary

Nothing detects when charge 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 charge 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.

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions