Add a settlement reconciliation discrepancy report endpoint backed by jobs/settlementReconciler.ts

[Baskarayelu]

📋 Description

The settlement reconciler in src/jobs/settlementReconciler.ts (tested in src/jobs/settlementReconciler.test.ts) compares the payouts table against the Horizon ledger and detects discrepancies, but there is no operator endpoint to retrieve the latest reconciliation result for triage.

This issue adds a read-only admin endpoint that returns the most recent reconciliation run's summary and the list of unmatched records, with cursor pagination.

Why this matters: reconciliation that runs in the dark forces operators to read logs during incidents. A queryable discrepancy report makes settlement drift actionable.

🎯 Requirements & Context

Functional requirements

• Add GET /api/admin/settlement/reconciliation under src/routes/admin, RBAC-gated.
• Persist reconciliation run summaries (matched count, unmatched count, run timestamp) and unmatched records.
• Return a paginated discrepancy list using the shared cursor envelope from src/lib/pagination.ts.
• Validate query params with zod; return the standard response envelope.
• Export a prom-client gauge for current unmatched count.

Context & constraints

• Endpoint is read-only; never mutates payout records.
• Reuse the reconciler's existing result types rather than re-deriving discrepancies in the route.

🛠️ Suggested Execution

1. Fork & branch

git checkout -b feat/settlement-reconciliation-report

2. Implement changes

• Persist run results; add the route, zod schema, pagination, and gauge.
• Add TSDoc + a zod-to-openapi annotation.
• Add supertest tests for empty, matched-only, and discrepancy-present runs plus RBAC.

3. Test & commit

npm run test -- settlementReconcil
npm run lint
npm run build

• Edge cases: no run yet, large unmatched set spanning multiple pages, non-admin caller.

Example commit message

feat(settlement): expose reconciliation discrepancy report endpoint

Persists settlementReconciler results and serves a paginated, RBAC-gated
report at GET /api/admin/settlement/reconciliation.

✅ Acceptance Criteria & Guidelines

Requirement	Target
Read-only paginated RBAC report	Required
Unmatched-count gauge	Required
Supertest coverage incl. discrepancy path	≥ 95% of route branches
npm run lint + npm run build clean	Required
Timeframe	96 hours from assignment

💬 Community & Support

Questions and design discussion — join the GrantFox contributor community on Discord: https://discord.gg/nmnPBkBge

Please comment on this issue to ask to be assigned before you start. 🚀

[DTech-Wiz1]

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

Please I would love to work on this issue.

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

[OkonkwoEmeka]

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

Hi maintainer, I’d like to work on this issue.

I understand the goal is to make settlement reconciliation results visible to operators instead of leaving them buried in logs. I’ll add a read-only, RBAC-gated "GET /api/admin/settlement/reconciliation" endpoint that returns the latest run summary and paginated unmatched records.

My approach would be to persist the reconciler output, reuse the existing result types, validate query params with zod, return the shared cursor pagination envelope, and export a prom-client gauge for the current unmatched count.

I’ll also add supertest coverage for no run yet, matched-only runs, discrepancy-present runs, pagination, and non-admin access before running the reconciliation tests, lint, and build.

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

[drips-wave]

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

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