Raise reconciliation-mismatch alerts instead of only incrementing a counter

[mikewheeleer]

Alert on escrow reconciliation mismatches

Description

The nightly reconciliation job in src/jobs/reconcileEscrow.js compares DB fundedTotal against on-chain fundedAmount (via src/services/escrowRead.js), persists results to reconciliation_runs, and increments escrowReconciliationMismatches in src/metrics.js — but a mismatch raises no actionable alert, so funded-amount drift can sit undetected until someone queries the metric. This issue adds explicit alerting on mismatch beyond the counter.

Requirements and context

• Repository scope: Liquifact/Liquifact-backend only.
• On a detected mismatch, capture a structured alert (logged at error/warn with invoiceId, expected vs actual) and capture it to Sentry via src/observability/sentry.js when enabled, with sensitive fields scrubbed.
• Surface a mismatch summary through the reconciliation health check in src/services/health.js (checkReconciliationHealth) so /ready can degrade if drift exceeds a configurable threshold.
• Keep the existing keyset pagination, reconciliation_runs persistence, and counter increments unchanged.
• Make the alert threshold and channel configurable via env and documented.

Suggested execution

• Fork the repo and create a branch
• git checkout -b enhancement/reconciliation-14-mismatch-alerts
• Implement changes
  • Write code in: src/jobs/reconcileEscrow.js and src/services/health.js.
  • Write comprehensive tests in: tests/reconcileEscrow.test.js.
  • Add documentation: update docs/ops-reconcile.md.
  • Add JSDoc on the alerting helper.
  • Validate security: no PII/secrets in alerts; scrubbed Sentry capture.
• Test and commit

Test and commit

• Run npm test and npm run lint.
• Cover edge cases: no mismatch, single mismatch alert, threshold breach degrades readiness, Sentry disabled, read failure.
• Include the full npm test output and a short security-notes section in the PR description.

Example commit message

feat(reconciliation): raise structured alerts on funded-amount mismatches

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the Liquifact community on Discord for questions, reviews, and faster merges: https://discord.gg/JrGPH4V3
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[Achievers-sketch]

@Achievers-sketch has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I’d like to take this issue. I have experience building Node.js backend observability and alerting systems, including Sentry integrations, health checks, metrics pipelines, and automated incident notifications. My approach is to add structured mismatch alerts with configurable thresholds, Sentry reporting with sensitive-data scrubbing, readiness degradation when drift exceeds limits, comprehensive tests for edge cases, and clear operational documentation while preserving existing reconciliation behavior.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Achievers-sketch to this issue.

[drips-wave]

Congratulations, @Achievers-sketch! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Achievers-sketch: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊