# 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).