fix: Top 20 fund flow validation — GL entries, Kafka events, payment execution

[devin-ai-integration]

Summary

Systematic validation of the top 20 fund flow scenarios on the platform revealed 10 gaps where money moves without proper accounting trails, event publishing, or concurrency protection. This PR fixes all of them.

Gaps found and fixed (6 files, +536/-59 lines):

Router	Gap	Fix
agentLoanFacility.disburse	Credits agent float with no FOR UPDATE, no GL, no Kafka, no audit	Added SELECT...FOR UPDATE inside withTransaction, GL entry (2001→2004), Kafka loan_disbursement event, writeAuditLog
agentLoanFacility.recordRepayment	Updates loan with no FOR UPDATE, no GL, no Kafka	Added FOR UPDATE locking, GL entry (2004→2001), Kafka loan_repayment event, audit log
agentLoanFacility.approve	Status change with no audit trail	Added Kafka event + writeAuditLog
nfcTapToPay	No payment execution mutation at all	New processPayment mutation: CBN limits → FOR UPDATE → float debit → transaction record → GL (1001→2001) → fee GL (2001→4001) → Kafka → audit. New refundPayment mutation: GL reversal (2001→1001)
dynamicQrPayment.generateQr	Stub returning { success: true }	Real QR code generation with DB persistence, expiry, audit log
dynamicQrPayment	No payment execution mutation	New payQr mutation: QR validation → expiry check → CBN limits → FOR UPDATE → float debit → QR status update → GL (1001→2001) → Kafka → audit
stablecoinRails.create	Creates wallet with no GL, no Kafka	Added GL entry (1003→2001) + Kafka stablecoin_created event
loyalty.redeemReward	Deducts points with no GL, no Kafka	Added GL entry (5004→2005) + Kafka loyalty_redemption event
commissionPayouts	Payout request with no Kafka event	Added publishEvent for commission_payout_requested

All new payment mutations follow the established pattern: withIdempotency → withTransaction → checkDailyLimit → SELECT...FOR UPDATE → balance mutation → GL double-entry → Kafka publishEvent → writeAuditLog.

Link to Devin session: https://app.devin.ai/sessions/3ebd42bf0430422a9a2bd85ed9f9cd4c
Requested by: @munisp

[devin-ai-integration]

Original prompt from Patrick

https://drive.google.com/file/d/1ko3y7OBp1tJIXGTbe2QGFRHMQfxMTWHX/view?usp=sharing

1. Extract ALL everything in the archive
2. how do ensure and assess that features for example domain and business logic/rules/requirements are fully impemented and production ready and complete - can you thoroughly assess each files and features to determine there are ready for production

1. Database integration (replace in-memory with real Postgres)
2. Inter-service HTTP wiring with retries/circuit breakers
3. Security hardening (JWT everywhere, remove hardcoded creds, mTLS)
4. Integration tests for critical flows
5. Graceful shutdown, observability, alerting
   3)search for orphan, partially and generic scaffolded features across the platform - fully implement them end to end -generic CRUD-only patterns , modules with no domain logic, disconnected features, and incomplete implementations.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Test Results — Top 20 Fund Flow Validation

All 12 tests passed (50/50 structural assertions). Shell-based validation — no live server available.

Devin session

Structural Validation (Tests 3-12) — 50/50 passed

Test	Router	Assertions	Result
T3	agentLoanFacility.disburse	FOR UPDATE + GL(2001→2004) + Kafka(loan_disbursement) + Audit + withTransaction	6/6 passed
T4	agentLoanFacility.recordRepayment	FOR UPDATE + GL(2004→2001) + Kafka(loan_repayment) + Audit	5/5 passed
T5	nfcTapToPay.processPayment	exists + idempotency + CBN limits + FOR UPDATE + GL(1001→2001) + fee GL(→4001) + Kafka + Audit	9/9 passed
T6	nfcTapToPay.refundPayment	exists + GL reversal(2001→1001) + Kafka(nfc_refund) + tx marked reversed	5/5 passed
T7	dynamicQrPayment.generateQr	stub replaced with INSERT + amount validation + audit	3/3 passed
T8	dynamicQrPayment.payQr	exists + idempotency + FOR UPDATE(qr+agent) + CBN + GL(1001→2001) + status=used + Kafka	8/8 passed
T9	stablecoinRails.create	GL(1003→2001) + Kafka(stablecoin_created)	5/5 passed
T10	loyalty.redeemReward	GL(5004→2005) + Kafka(loyalty_redemption)	4/4 passed
T11	commissionPayouts	publishEvent import + Kafka(commission_payout_requested)	2/2 passed
T12	Cross-mutation consistency	Loan disburse/repay are GL reverses, NFC pay/refund are GL reverses, QR matches NFC accounts	3/3 passed

Compilation & Regression (Tests 1-2)

• T1: TypeScript compilation — passed (0 new errors; 6 pre-existing client errors)
• T2: Vitest regression — passed (4,241 pass, 5 pre-existing failures)

Escalations

• Not tested: Runtime execution against live DB — no DATABASE_URL/Redis/Kafka env vars in this session
• Pre-existing failures (not from this PR): db-performance fetch errors + sprint46 multi-currency activePairs count (42→48)

[devin-ai-integration]

Closing — all fund flow changes superseded by PRs #38, #39 (full middleware + hardening for all 18 fund flow routers).