Make invoice funding reconciliation idempotent across retried batches

[mikewheeleer]

Summary

Reconciliation can be run more than once while a previous batch is still finishing, which can duplicate adjustments or reports.

Why this matters

This closes a correctness, security, or operability gap in the Liquifact backend and makes the behavior explicit, observable, and safe under failure.

Requirements

• Repository scope: Liquifact/Liquifact-backend only.
• Introduce a run identity and durable completion record; make retries resume or return the existing result; keep reconciliation scoped to one tenant and time window.
• Preserve tenant isolation, structured errors, and existing API compatibility unless the issue explicitly requires a contract change.
• Add focused unit and integration coverage for the new behavior.

Technical guidance

• Follow the repository's existing middleware, service, persistence, logging, and error-envelope conventions.
• Keep side effects bounded and make retries, authorization, and failure handling explicit.
• Document non-obvious tradeoffs and include security notes in the PR.

Edge cases — each must have a test

• first run completes once
• same run key is replayed
• two workers start the same run concurrently
• a partially completed batch resumes
• an empty window produces a stable result

Acceptance criteria

• Every requirement and edge case above is implemented and tested
• Unit and integration tests cover success, failure, retry, and authorization paths
• Existing tests pass with no regressions
• Errors are structured and do not leak secrets or internal stack details
• npm run lint, npm test, and npm run build passes locally
• Code follows existing conventions with no duplication or dead code
• Documentation or concise comments explain non-obvious decisions
• PR description explains the approach, includes test evidence and security notes, and references Closes #

Out of scope

• automatic financial remediation

[Outlaw1299]

@Outlaw1299 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I can work on this issue, kindly assign

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

[drips-wave]

Congratulations, @Outlaw1299! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Outlaw1299: 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 🌊

[drips-wave]

This issue has been marked as completed by a Drips Wave moderator for @Outlaw1299 as part of the Stellar Wave Program's 8th Wave 🥳

Moderator's reason: [Auto-assessed] The PR is open with no maintainer response across any of the four channels, and the diff cleanly implements idempotent invoice funding reconciliation with robust run keys, database migrations, concurrency handling, and associated tests.

😎 @Outlaw1299: You earned 100 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.

ℹ️ Note: This issue was marked complete via moderation. Points were issued even though the GitHub issue remains open.