feat: holiday-calendar blackouts for distribution scheduler (#664)

[Bug00Joe]

Overview

This PR adds jurisdiction-aware bank-holiday blackouts for the distribution scheduler. Distribution windows skip blackout days so investor bank rails receive funds on a settleable business day. The calendar is loaded from a signed static file (HMAC-SHA256, fail-closed) with per-jurisdiction overrides and a configurable previous/next shift policy.

Related Issue

Closes #664

Changes

📅 Holiday calendar service

• [MODIFY] src/services/holidayCalendarService.ts

  • Loads a signed { payload, signature } static file; validates HMAC-SHA256 with timingSafeEqual before applying the calendar.
  • Per-jurisdiction overrides augment the base holiday set.
  • getShiftedDate() shifts to the previous/next settleable business day.
  • Strictest shift: overlapping holidays across jurisdictions keep shifting until the candidate day is clear for every jurisdiction in the distribution (not just weekends).
  • Emits scheduler.blackout.shift and persists the calendar hash in a holiday_calendar.load audit event.

• [MODIFY] src/services/holidayCalendarService.test.ts — comprehensive unit coverage (36 tests).

• [MODIFY] src/services/distributionScheduler.test.ts — metric name + overlap fixture window-key fix.

• [MODIFY] docs/holiday-calendar-service.md — security model, shift semantics, env vars, abuse paths.

Verification Results

npx jest src/services/holidayCalendarService.test.ts --forceExit
✅ 36/36 passed

npx jest src/services/distributionScheduler.test.ts --testNamePattern="Holiday|holiday|blackout|Blackout|strictest" --forceExit
✅ holiday/blackout cases passed

Acceptance Criteria	Status
Calendar loaded from signed static file	✅ HMAC-SHA256 fail-closed
Signature validation before applying	✅ timingSafeEqual before decode
Per-jurisdiction overrides	✅ overrides augment base set
Fallback shift policy (previous vs next)	✅ configurable
Overlapping holidays apply strictest shift	✅ keeps shifting until settleable for all jurisdictions
Calendar hash in admin audit event	✅ holiday_calendar.load
Emit scheduler.blackout.shift per shift	✅ counter with direction + jurisdiction_count

Timeline

• Implemented HolidayCalendarService with signed-file loading and strictest multi-jurisdiction shift.
• Documented security model and abuse/failure paths.

[drips-wave]

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