suaveplan/openspec/archive/2026-04-19-enterprise-datetime/tasks.md

Archived 2026-04-19: all tasks retroactively ticked; package shipped under universal/primitives/datetime.

Tasks: enterprise-datetime

1. Scaffold

• 1.1 Create packages/universal/datetime/ with package.json, tsconfig.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md skeleton
• 1.2 Register coverage thresholds at 100/100/100/100 in vitest.config.ts; provider = istanbul
• 1.3 Add cross-cutting guard tests in tests/: dep-graph (no banned deps), no-disallowed (no any/TODO/skip), tree-shake (sideEffects: false)
• 1.4 Add package to root CLAUDE.md, README.md, and STRUCTURE.yml
• 1.5 Add packages/universal/datetime to Turborepo pipeline (turbo.json if needed)

2. Types + error codes

• 2.1 Implement src/types/datetime.types.ts — DateInput, Duration, DurationUnit, Weekday, DayAbbreviation, Timezone, CalendarDay, CalendarMonth, BusinessDayOptions, RelativeTimeOptions, Frequency, RecurrenceOptions, RecurrenceRule
• 2.2 Add Zod schemas in src/types/datetime.schemas.ts for every exported type
• 2.3 Implement src/errors/datetime-error.ts — DatetimeError extends SuaveplanError; defineCodes for DATETIME.PARSE.INVALID_INPUT, DATETIME.RECURRENCE.INFINITE_EXPANSION, DATETIME.TIMEZONE.UNKNOWN
• 2.4 Tests for error construction, code narrowing, walkCauses

3. Calendar module

• 3.1 Implement src/calendar/calendar.ts — addDuration, subtractDuration, daysInMonth, endOf, startOf, getCalendarMonth, isLeapYear, isSameDay, isSameMonth, toDate
• 3.2 All functions accept { clock?: Clock } where they read current time
• 3.3 Unit tests covering leap years, DST boundaries, month rollover, all DurationUnit variants
• 3.4 Property-based tests: addDuration + subtractDuration inverse, startOf ≤ date ≤ endOf
• 3.5 Co-located src/calendar/calendar.md (≥200 words, examples, API reference)

4. Business days module

• 4.1 Implement src/business-days/business-days.ts — addBusinessDays, subtractBusinessDays, businessDaysBetween, isBusinessDay, nextBusinessDay, previousBusinessDay
• 4.2 Support custom holidays list and weekendDays in BusinessDayOptions
• 4.3 Honour AbortSignal in businessDaysBetween for large ranges (check every 256 iterations)
• 4.4 Unit tests: standard week, custom weekends, holiday lists, edge dates (year boundaries)
• 4.5 Property-based tests: addBusinessDays(d, n) always a business day; businessDaysBetween ≥ 0
• 4.6 Co-located src/business-days/business-days.md

5. Recurrence module

• 5.1 Implement src/recurrence/recurrence.ts — parseRRule, formatRRule, nextOccurrence, expandRecurrence
• 5.2 Support DAILY, WEEKLY, MONTHLY, YEARLY frequencies; COUNT, UNTIL, BYDAY, BYMONTHDAY, INTERVAL
• 5.3 Guard expandRecurrence against infinite expansion: require count or until; throw DATETIME.RECURRENCE.INFINITE_EXPANSION otherwise
• 5.4 Honour AbortSignal in expandRecurrence (check every 64 occurrences)
• 5.5 Unit tests: all frequencies, BYDAY, BYMONTHDAY, COUNT vs UNTIL, edge months
• 5.6 Property-based tests: parseRRule → formatRRule → parseRRule identity
• 5.7 Co-located src/recurrence/recurrence.md

6. Relative time module

• 6.1 Implement src/relative/relative.ts — formatRelative, timeAgo, timeUntil, diffInUnits
• 6.2 Accept { clock?: Clock; precision?: DurationUnit } options
• 6.3 i18n-ready: all user-visible strings are keyed (default: English pass-through)
• 6.4 Unit tests: seconds/minutes/hours/days/weeks/months/years ranges, past/future, precision options
• 6.5 Co-located src/relative/relative.md

7. OTel instrumentation

• 7.1 Add @opentelemetry/api histogram for expandRecurrence duration (occurrence count attribute)
• 7.2 Add counter for businessDaysBetween calls
• 7.3 All instrumentation no-ops when no OTel exporter registered (verify in tests)

8. Benchmarks

• 8.1 src/__benchmarks__/calendar.bench.ts — getCalendarMonth 12-month batch (mitata)
• 8.2 src/__benchmarks__/recurrence.bench.ts — expandRecurrence 1 000-occurrence daily rule
• 8.3 src/__benchmarks__/business-days.bench.ts — businessDaysBetween 10-year span
• 8.4 Publish baseline numbers in README

9. Docs

• 9.1 Co-located .md for every implementation file (≥200 words, simple + advanced example, full API reference)
• 9.2 Rewrite README.md with full public API overview, design rationale, consumer guide
• 9.3 bun run docs:check --filter=@suaveplan/datetime ≥ 90%

10. Verify and publish

• 10.1 bunx turbo lint typecheck test --filter=@suaveplan/datetime green
• 10.2 bunx turbo test:coverage --filter=@suaveplan/datetime at 100/100/100/100
• 10.3 bunx turbo build --filter=@suaveplan/datetime green
• 10.4 bun scripts/publish.ts --package @suaveplan/datetime to Verdaccio at 0.0.0
• 10.5 Archive OpenSpec change to openspec/archive/2026-04-18-enterprise-datetime/