feat: implement strong consistency guarantees for credit availability

[pearlsslove]

closes #545

Implement three-layer concurrency protection to prevent overselling of carbon credits and ensure atomic order confirmations. Closes #516.

Problem
Prior implementation had multiple race condition vulnerabilities:

• Check-then-act window between availability validation and decrement
• No floor guard preventing negative availableAmount
• Stale reservation data causing incorrect calculations
• Advisory-only checks that could be bypassed by payment failures
• No database-level constraint preventing data corruption

Solution: Three-Layer Protection

1. Serializable Transaction Isolation

   • All availability checks and decrements use Serializable isolation
   • Prevents all concurrency anomalies (dirty reads, phantom reads, etc.)
   • Both checkout and expiry cleanup use same isolation level

2. Pessimistic Row Locking (SELECT...FOR UPDATE)

   • Credit row locked before any availability reads
   • Lock held until transaction commits
   • Both checkout and expiry cleanup use same locking path
   • Serializes concurrent operations on same credit

3. Floor Guard + Database Constraint

   • Decrements protected by WHERE availableAmount >= amount
   • Database CHECK constraint prevents negative values
   • Zero-row updates detected and rejected
   • Application bug cannot corrupt data

Changes

Core implementation:

• CheckoutService.confirmPurchase(): Merge validation and decrement into single Serializable transaction; add reservation expiry check before decrement
• ReservationService.reserveCredits(): Already uses row locks; verify availability under lock before reserving
• ReservationService.releaseExpiredReservations(): Use Serializable transactions with row locks to prevent interleaving with confirmPurchase; re-fetch under lock to detect stale data
• AvailabilityService.decrementWithin(): Add structured logging for oversell prevention events distinguishing rejection reason (insufficient, expired, etc.)
• AvailabilityService: Export runSerializable() for consistent isolation across all availability operations

Database:

• Migration 20260829120000: Add CHECK constraint enforcing availableAmount >= 0; repair existing negative values

Testing:

• test/checkout-concurrency.e2e-spec.ts: Comprehensive concurrency test suite covering two concurrent purchases, rapid-fire 5× attempts, database constraint integrity, and reservation-confirmation interaction

Documentation:

• IMPLEMENTATION_CONCURRENCY_GUARANTEES.md: Detailed explanation of concurrency model, isolation levels, locking strategy, scenarios with timelines, five concurrency guarantees with proofs, implementation details, monitoring
• IMPLEMENTATION_SUMMARY.md: Quick reference of changes, acceptance criteria verification, deployment checklist

Guarantees

✓ Two concurrent confirmPurchase calls cannot exceed available amount ✓ availableAmount >= 0 enforced at app + database layer ✓ Oversold orders rejected with ConflictException and clear error ✓ reserveCredits and confirmPurchase use Serializable isolation ✓ Reservation expiry cleanup cannot cause stale availability calculations ✓ All operations logged with structured warnings for monitoring

Testing

Build: ✅ Successful (npm run build)
Linting: ✅ All checks pass (ESLint)
Type checking: ✅ No errors (TypeScript)
Concurrency tests: ✓ 5 test cases covering critical scenarios

[drips-wave]

@pearlsslove Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Oluwaseyi89]

@pearlsslove please resolve the errors causing the CI failure