feat: pin snapshot_at to period boundary for determinism

[chiemezie1]

Description

Make BalanceSnapshotService deterministic by pinning snapshot_at to the period boundary when the caller omits it. This ensures that re-running a snapshot for the same period produces identical snapshot_at timestamps, preserving downstream distribution determinism.

Closes #866

Changes

• BalanceSnapshotService: Pin snapshot_at to periodEnd when in idempotent mode and caller omits the parameter
• BalanceSnapshotRepository: Enforce snapshot_at requirement at the repository level via CreateSnapshotInput type
• Validation: Added mismatch guard that asserts stored snapshot_at matches when re-running with an existing snapshot
• Fallback: Support non-idempotent mode for testing with fallback to new Date()
• Tests: Comprehensive test coverage including:
  • Happy paths with determinism verification
  • Invalid input and authorization boundaries
  • Edge cases (DST boundaries, empty holders, duplicate runs)
  • Backward compatibility scenarios
  • Determinism contract validation across re-runs

Technical Details

Implementation Highlights

1. Determinism Contract: When snapshotAt is omitted in idempotent mode, derives default from periodEnd
2. Mismatch Protection: Rejects re-runs with mismatched snapshotAt values to prevent data corruption
3. Backward Compatibility: Preserves existing API contract, authorization, and production safeguards
4. Test Structure: Moved tests to Jest-compatible __tests__ directory

Security & Validation

• Authorization checks preserved at all levels
• Input validation enforced at repository layer
• Mismatch detection prevents silent data corruption
• Determinism validated across concurrent and sequential re-runs

Files Changed

• src/services/balanceSnapshotService.ts - Core determinism logic
• src/db/repositories/balanceSnapshotRepository.ts - Snapshot storage contract
• src/services/__tests__/balanceSnapshotService.test.ts - Service tests
• src/db/repositories/__tests__/balanceSnapshotRepository.test.ts - Repository tests

Test Coverage

• ✅ Happy paths with re-run determinism
• ✅ Invalid input and boundary conditions
• ✅ Mismatch detection and rejection
• ✅ Empty holders and DST edge cases
• ✅ Backward compatibility
• ✅ Concurrent snapshot handling

Validation

• All existing tests pass
• New tests provide >95% coverage of implementation
• No breaking changes to public API
• Production safeguards and authorization preserved

[drips-wave]

@chiemezie1 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