[Simultech369]

Summary

Addresses Issue #556 by implementing a bounded, chunked, idempotent, and side-effect-free reconciliation subsystem that scans swap records, detects drift against core financial and lifecycle invariants, and generates deterministic structured violation reports.

Invariants Implemented

1. Balance Conservation (BALANCE_CONSERVATION):
   • $\text{amountIn} = \text{netAmount} + \text{feeAmount}$ verified using exact scaled BigInt arithmetic across arbitrary decimal precisions.
   • Non-negativity guard (IMBALANCE_NEGATIVE_AMOUNT).
   • Numeric validation guard (AMOUNT_INVALID_NUMERIC).
2. Status & Lifecycle Integrity (STATUS_CONSISTENCY):
   • Validates terminal completion requirements (completedAt, positive amountOut, no refundedAt).
   • Validates refund requirements (refundedAt).
   • Validates failure requirements (failureReason, no completedAt).
   • Validates pending states (no terminal timestamps).
   • Enforces timestamp monotonicity (updatedAt >= createdAt, completedAt >= createdAt).
3. Rate & Numeric Integrity (RATE_INTEGRITY):
   • Ensures exchange rates are finite, positive numbers (RATE_NON_POSITIVE).
4. Route Leg Continuity (ROUTE_CONTINUITY):
   • Enforces multi-hop asset chaining ($\text{destAsset}i = \text{sourceAsset}{i+1}$) and intermediate amount continuity ($\text{amountOut}i = \text{amountIn}{i+1}$).

Edge Cases Covered & Verified

• Consistent data -> zero violations: Verified clean runs produce zero violations and 0 drift rate.
• Injected imbalance -> reported with offending id: Detects mismatched balances, flags offending swapId, and computes drift rate.
• Inconsistent status -> reported: Detects corrupt statuses, missing timestamps, and lifecycle anomalies.
• Large dataset -> scan stays bounded: Enforces maxRecords ceiling and marks isBoundedLimitReached: true.
• Deterministic report: Alphabetically sorts violations by swapId, invariant, and code, guaranteeing identical outputs for identical inputs.

Acceptance Criteria & Quality

• Added comprehensive unit test suite: src/__tests__/reconciliation.unit.test.ts (22 tests).
• Added comprehensive integration test suite: src/__tests__/reconciliation.integration.test.ts (6 tests).
• All 37 test suites and 1,013 tests pass with 0 failures.
• npm run lint and npm run build pass with 0 errors.
• Documented in docs/swap-drift-reconciliation.md and registered in OpenAPI spec (src/openapi.ts).
• Exposed via reconcileSwapsSync, runReconciliationJob, and administrative endpoint POST /api/v1/admin/reconciliation/swaps.

Closes #556

[mikewheeleer]

Closing as part of a repository reset; new issues will be opened shortly. Thanks for contributing!