Initial Commit

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

@@ -0,0 +1,48 @@
+# 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).

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

@@ -0,0 +1,15 @@
+# Datetime Capability — Spec Delta (datetime-spec-conformance)
+
+## MODIFIED Requirements
+
+Each requirement in `openspec/specs/datetime/spec.md` gains a `**Verified by:**` line naming the test cases that pin it. No requirement text is changed; only verification metadata is added.
+
+DT-01..DT-11 are amended in-place. See the folded spec for the canonical Verified-by lines.
+
+## ADDED Requirements
+
+### DT-09a — Output-size histograms (clarifies DT-09)
+
+`expandRecurrence` MUST record an `expandRecurrenceSize` histogram (unit `{occurrences}`) in addition to its duration histogram. `businessDaysBetween` MUST record `businessDaysBetweenSize` (unit `{days}`) and `businessDaysBetweenDuration` (unit `ms`) histograms in addition to the cumulative `businessDaysBetweenTotal` counter. All four histograms are no-ops when no `MeterProvider` is registered.
+
+**Verified by:** `src/datetime.spec-conformance.test.ts::"expandRecurrence + businessDaysBetween expose duration + size histograms"` AND `src/otel/datetime-otel.test.ts::"recordExpandRecurrence with size does not throw"` AND `src/otel/datetime-otel.test.ts::"recordBusinessDaysBetween with duration does not throw"`.

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

@@ -0,0 +1,24 @@
+# Tasks: datetime-spec-conformance
+
+## 1. Source refactors (additive only)
+
+- [x] 1.1 Add `expandRecurrenceSize`, `businessDaysBetweenDuration`, `businessDaysBetweenSize` histograms in `src/otel/datetime-otel.ts`.
+- [x] 1.2 Extend `recordExpandRecurrence(durationMs, size?)` and `recordBusinessDaysBetween(count, durationMs?)` additively.
+- [x] 1.3 Wire size + duration recording in `src/recurrence/recurrence.ts::expandRecurrence` and `src/business-days/business-days.ts::businessDaysBetween`.
+- [x] 1.4 Re-export the new histograms from `src/index.ts`.
+- [x] 1.5 Update `src/otel/datetime-otel.md` to document the new instruments.
+
+## 2. Spec annotations
+
+- [x] 2.1 Add a `**Verified by:**` line under every requirement in `openspec/specs/datetime/spec.md`.
+- [x] 2.2 Clear the retroactive-ticking marker phrase in `openspec/archive/2026-04-19-enterprise-datetime/tasks.md`.
+
+## 3. Pinning tests
+
+- [x] 3.1 Add `src/datetime.spec-conformance.test.ts` covering DT-01..DT-10 (20 tests).
+
+## 4. Verify
+
+- [x] 4.1 `bunx turbo lint typecheck test --filter=@suaveplan/datetime` green.
+- [x] 4.2 `bunx turbo test:coverage --filter=@suaveplan/datetime` 100/100/100/100.
+- [x] 4.3 `bun scripts/openspec-conformance.ts @suaveplan/datetime` exits 0.