ADR 0019 — Founders Grace: business-day calendar library choice

Status: Proposed — open question; Kristerpher confirmation required before sub-card can be claimed Date: 2026-04-23 Deciders: software-architect (proposed) — needs Kristerpher confirmation Related: docs/architecture/founders-grace-transition.md §4 Parent card: #210

Context

The Founders grace window is 5 business days (one business week), computed from the UTC date when the trial expires. "Business day" means Monday–Friday, excluding US federal holidays. The computation must be:

• Reproducible (same input always yields the same output).
• Configurable (holiday list or calendar source must be swappable without redeploy).
• Lightweight (not pulling a 30 MB ML dependency to count 5 weekdays).
• Observable (failures must surface as errors, not silent miscounts).

Three candidates: pandas_market_calendars, workalendar (or its fork workalendar-core), and a custom hand-maintained holiday list via env var.

Decision (proposed — pending Kristerpher confirmation)

Use workalendar (or workalendar-core if the main package is unmaintained at implementation time) for UnitedStatesCalendar. This provides a maintained, tested US federal holiday schedule without pulling in the full pandas / numpy / pyexchange stack.

If workalendar is found to be unmaintained or unlicensed at implementation time, fall back to the custom env-var approach (see below).

The specific library is confirmed by feature-developer at implementation time, subject to: 1. License is MIT-compatible (MIT, Apache-2, BSD). 2. Package is receiving security updates. 3. Total dependency weight added to Raptor is < 5 MB.

If none of the above candidates pass, use the custom env-var approach without a third-party library.

Consequences

Positive (workalendar)

• Tested holiday list. US federal holidays (including observed-date rules for holidays falling on weekends) are handled by a maintained library, not a hand-maintained list.
• Lightweight. workalendar has no pandas/numpy/pyexchange dependency. It is a pure-Python calendar implementation.
• Swappable. FOUNDERS_HOLIDAY_CALENDAR=us_federal env var maps to the calendar class. Changing the calendar (e.g., for non-US expansion) does not require a code change.

Negative (workalendar)

• Third-party dependency. Library maintenance must be monitored. If the project is abandoned, observed-date rules for future holidays may drift.
• Holiday list is not auditable by ops without reading source. An ops team member cannot inspect the holiday list from the deployed environment without reading library source.

Custom env-var approach (fallback)

FOUNDERS_HOLIDAY_LIST is a JSON array of ISO-8601 date strings (e.g., ["2026-01-01", "2026-05-25"]). compute_grace_end iterates weekdays and skips dates in this list.

• Pro: fully auditable, no third-party dependency, updatable via env without redeploy.
• Con: requires annual ops update; human error possible if list is incomplete.

Alternatives considered

pandas_market_calendars

Has USFederalHolidayCalendar and NYSE/NASDAQ trading calendars. Rejected for v1 because it depends on pandas + numpy + pyexchange, adding significant weight to the Raptor container for a task that is a simple weekday-counting loop. The Founders grace window does not need market-hours granularity.

dateutil.rrule (python-dateutil)

Can generate business-day sequences via RRULE with BYDAY=MO,TU,WE,TH,FR. Does not include holiday awareness. Would require pairing with one of the above for holiday skipping. Rejected as incomplete on its own.

Python standard library only (no third-party)

calendar.weekday() + custom holiday list (as in the env-var fallback). Viable. If no acceptable third-party library exists at implementation time, this is the fallback.

Open question for Kristerpher

The library choice is proposed here but Kristerpher must confirm:

1. Is the custom env-var approach acceptable for v1, or is a maintained library required?
2. If a library: is workalendar acceptable, or is there a preference?
3. Who owns the annual holiday-list update? (Applies to both the library upgrade path and the env-var path.)

This decision blocks the compute_grace_end implementation sub-card.

Revisit when

• Raxx expands to non-US markets. Non-US business-day calendars will require either additional workalendar locales or separate calendar configuration per user region.
• The grace window computation is used for SLA enforcement in a regulated context. At that point, the calendar source should be auditor-visible (env-var approach becomes preferable over an opaque library).