suaveplan/openspec/archive/2026-05-02-datetime-spec-conformance/proposal.md

OpenSpec Change: datetime-spec-conformance

• Change ID: datetime-spec-conformance
• Package: @suaveplan/datetime
• Status: PROPOSED
• Date: 2026-04-26

Summary

Bring @suaveplan/datetime into spec conformance with openspec/specs/datetime/spec.md. Add **Verified by:** lines to every requirement, pin implicit scenarios with a single *.spec-conformance.test.ts, and rectify one piece of real OTel drift (DT-09) inline. Clear the retroactive-ticking marker so bun scripts/openspec-conformance.ts @suaveplan/datetime exits 0.

Current state

@suaveplan/datetime ships a complete enterprise-grade implementation: DatetimeError extending SuaveplanError with three DATETIME.* codes, Zod boundary schemas in types/datetime.schemas.ts, injectable Clock on formatRelative / timeAgo / timeUntil / expandRecurrence, BusinessDayOptions with custom holidays and weekendDays, AbortSignal cooperative cancellation, RRULE parser/formatter with FREQ/INTERVAL/COUNT/UNTIL/BYDAY/BYMONTHDAY, calendar arithmetic with month-clamp, fast-check property tests, and a mitata benchmark suite. The conformance gaps are:

• DT-09 spec mandates histograms for both expandRecurrence and businessDaysBetween tracking call duration and output size. Implementation only had a duration histogram for expandRecurrence and a counter for businessDaysBetween — missing the size histogram for both and the duration histogram for businessDaysBetween.
• 11/11 requirements lacked **Verified by:** lines.
• Implicit scenarios across DT-01..DT-10 were exercised indirectly only.
• tasks.md of 2026-04-19-enterprise-datetime/ carries the retroactive-ticking marker.

What changes

1. Wire four additional OTel histograms inline (DT-09) without breaking the pre-existing surface:
   • expandRecurrenceSize — number of occurrences emitted per call.
   • businessDaysBetweenDuration — wall-clock duration per call.
   • businessDaysBetweenSize — day-intervals walked per call.
   • recordExpandRecurrence(durationMs, size?) and recordBusinessDaysBetween(count, durationMs?) updated additively (extra params are optional, all old call sites still compile).
   • Both hot paths (expandRecurrence + businessDaysBetween) now feed both duration and size on every call.
2. Add **Verified by:** line under every requirement in openspec/specs/datetime/spec.md.
3. Add src/datetime.spec-conformance.test.ts (20 tests) pinning DT-01..DT-10:
   • DT-01 — DateInput accept Date / ISO / epoch + invalid throws PARSE.INVALID_INPUT.
   • DT-02 — formatRelative / timeAgo / timeUntil / expandRecurrence honour injected clock.
   • DT-03 — six business-day functions accept holidays + custom weekendDays + pre-aborted signal.
   • DT-04 — Jan 31 + 1 month clamp (Feb 28 / 29), subtractDuration mirrors addDuration, daysInMonth + isLeapYear.
   • DT-05 — RRULE field round-trip + INFINITE_EXPANSION throw.
   • DT-06 — codes namespaced under DATETIME.* and registry frozen.
   • DT-07 — every Zod schema parses a representative payload.
   • DT-08 — English pass-through label variants (just-now / past / future / plural).
   • DT-09 — duration + size histograms + counter exist for both hot paths.
   • DT-10 — package.json declares sideEffects: false.
4. Re-run bun scripts/openspec-conformance.ts @suaveplan/datetime and confirm exit 0.

Impact

• Public API gains four additional OTel histogram exports (additive only; all prior exports preserved).
• One new test file (~330 lines).
• openspec/specs/datetime/spec.md gains 11 **Verified by:** lines.
• recordExpandRecurrence and recordBusinessDaysBetween accept additional optional parameters (backwards compatible).