@ultimat3/time 1.1.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,64 @@
+# @ultimat3/time — agent notes
+
+**Tier 1.** May import `@ultimat3/core`, `@ultimat3/schema`. No external deps — **never add
+`date-fns-tz`**; zone math is `Intl.DateTimeFormat` + `formatToParts`.
+
+## Boundary
+
+| File | Single responsibility |
+|---|---|
+| `instant.ts` | the UTC `Instant` brand, ISO/epoch conversion, `now(clock)`, `epoch()` |
+| `zones.ts` | IANA validation, `offsetAt` (minutes east), zone labels |
+| `zone-canonical.ts` | one zone, one key: `canonicalTimeZone` — the casing/alias collapse every cache keys on |
+| `locale-canonical.ts` | one locale, one key: `canonicalLocale` — the same collapse for the `Accept-Language` half |
+| `intl-cache.ts` | the one bounded FIFO every `Intl` formatter cache in this package uses |
+| `zoned.ts` | `toZoned` / `fromZoned` + gap and overlap policies. Everything depends on this. |
+| `format.ts` | `Intl` rendering. Every function takes `locale` **and** `zone`. |
+| `duration.ts` | `'2h30m'` ⇄ ms |
+| `cron.ts` | barrel over the three cron modules — the only one `index.ts` re-exports |
+| `cron-parse.ts` | field grammar → `CronExpression`. Non-integer, non-name tokens are rejected. |
+| `cron-occurrence.ts` | next occurrence, wall-clock driven |
+| `cron-describe.ts` | `describeCron` — `Intl` names, phrases injected. `CronPhrases` is required. |
+| `schedule.ts` | `nextLocalSlot` — "09:00 local tomorrow" |
+| `business.ts` | weekends as config, holidays as local dates |
+| `context.ts` | request timezone: which source wins, and reading core's `Ctx.tz` back off the ALS |
+
+## Rules
+
+- Never format without an explicit `timeZone`. No ambient default, no `toLocaleString()`.
+- **The ambient zone IS `Ctx.tz`**, core's own declared field. This package publishes no writer and
+  no field of its own: `createContext({ tz })` and `withChildContext({ tz })` are the way in,
+  `currentTimeZone()` the way out. It kept `attachTimeZone`/`timeZoneOf` over `ctx['timeZone']`
+  until 1.3.0 — a second ambient store, with **zero** writers, while `@ultimat3/http` wrote `tz` —
+  so `currentTimeZone()` answered `UTC` for every request and every `@ultimat3/ui` server render
+  formatted in UTC regardless of the zone the caller sent. Two ambient defaults is the worst
+  possible version of the rule above. Never reintroduce either half.
+- **Never cache an `Intl` formatter on a raw caller string.** A zone and a locale both arrive from
+  a request header, so the key must be canonical (`canonicalTimeZone` for a zone, `canonicalLocale`
+  for a locale) and the cache must be bounded (`cachedFormatter`, `intl-cache.ts`). An unbounded
+  `Map` keyed on `x-timezone` grew 31 MB for 4,096 casings of one zone name, and the casing space
+  of a 13-letter zone is 2^12. **Both halves, always** — a canonical key does not bound anything
+  (an unknown `-u-` extension value survives canonicalization as a distinct string) and the cap
+  alone lets one locale evict itself under three spellings.
+- **Never hand back the caller's own `Date`, and never export a shared one.** `Instant` is a
+  branded `Date` and a `Date` cannot be frozen — `Object.freeze` does not close `setTime`, the
+  value is in an internal slot. So `instant()` copies and `epoch()` is a function, not a constant.
+- **`businessDaysBetween` is `[from, to)` on local calendar dates** — the interval `daysBetween`
+  measures, so the two can never disagree. Comparing instants made the answer depend on the
+  endpoints' time of day. A new day-counting function states its interval in its header.
+- **`describeCron` declines what it cannot say.** `CronPhrases` is the caller's vocabulary and has
+  no seconds phrase, so a 6-field expression with a non-trivial seconds field is
+  `X_CRON_NOT_DESCRIBABLE`. Adding a required field to `CronPhrases` would break every caller
+  (`packages/cli/src/cmd-tasks.ts` builds one) to describe a schedule almost nobody writes.
+- Never add `86_400_000` to cross a day boundary — use `addDaysInZone` / `fromZoned`.
+- Never take the clock from `Date.now()`; accept a `Clock` (`now(clock)`).
+- Cron and schedules iterate the **local wall clock**, then convert once with `fromZoned`.
+- `m` is minutes, `ms` is milliseconds. A bare number is not a duration.
+- Tests must cover a spring-forward gap, a fall-back overlap and a non-hour offset zone.
+
+## Commands
+
+```
+bun test packages/time
+bun run --filter @ultimat3/time typecheck
+```

package/README.md

@@ -16,6 +16,20 @@ none ever will — "the server's timezone" is not an answer to "what time is it
 No `date-fns-tz`, no tzdata table. Zone math is derived from `Intl.DateTimeFormat` +
 `formatToParts`, which is exact in Bun and always current with the runtime's tzdata.
 
+**One zone is one key.** `Intl` accepts every casing of an IANA name, so `canonicalTimeZone(z)`
+answers the canonical spelling (or `undefined`), and `assertTimeZone` / `resolveTimeZone` both
+return it. Anything reading a zone off a request header should canonicalize before caching on it:
+4,096 casings of `Europe/Berlin` used to mint 4,096 permanent `Intl.DateTimeFormat`s, 31 MB.
+
+One **locale** is one key for the same reason — `Accept-Language` spells one locale `EN-us`,
+`en-US` and `en-latn-us`, and `formatDateTime` and `describeCron` collapse the three before they
+reach a formatter cache. The cap in `intl-cache.ts` stays either way: an unknown `-u-` extension
+value survives canonicalization as a distinct string, so the key bounds nothing on its own.
+
+Every value this package hands back is its own object: `instant(date)` copies rather than branding
+the caller's `Date`, and `epoch()` is a function — the `EPOCH` constant it replaces was one shared
+mutable `Date` that a single `setUTCFullYear` corrupted for the whole process.
+
 ## Use
 
 ```ts
@@ -73,13 +87,21 @@ change, and a job scheduled inside the gap runs at the first existing local time
 being skipped. `describeCron(expr, locale, phrases)` renders the dashboard summary — month and
 weekday names from `Intl`, every connective word **required** from the caller's `t('time.cron.*')`,
 because tier 1 cannot reach `t()` and a built-in default would ship English to every locale. A
-long clock-time list is capped and the remainder counted with `andMore`, never silently cut.
+long clock-time list is capped and the remainder counted with `andMore`, never silently cut. A
+6-field expression whose seconds field says something a 5-field one cannot is **declined** with
+`X_CRON_NOT_DESCRIBABLE` rather than summarised: `CronPhrases` has no seconds vocabulary, so a
+ten-second step used to render as "every minute".
 
 ## Business days
 
 The weekend is configuration. `WEEKEND_SAT_SUN`, `WEEKEND_FRI_SAT` (much of the Gulf),
 `WEEKEND_SUN_ONLY`, plus a holiday list of local `YYYY-MM-DD` dates.
 
+`businessDaysBetween(from, to, calendar)` counts `[from, to)` — half-open, on **local calendar
+days**, the same interval `daysBetween` measures. `from`'s own day counts, `to`'s does not, and
+neither endpoint's wall-clock time is part of the question. A reversed range is the same count
+negated; an empty one is `0` in either direction, never `-0`.
+
 ## Errors
 
 | Code | When |
@@ -91,6 +113,8 @@ The weekend is configuration. `WEEKEND_SAT_SUN`, `WEEKEND_FRI_SAT` (much of the
 | `X_DST_NONEXISTENT` | gap hit with `gap: 'throw'` |
 | `X_INSTANT_INVALID` | unparseable timestamp |
 | `X_LOCALE_INVALID` | a tag `Intl` cannot parse (`en_US`, `''`) reached `describeCron` |
+| `X_CRON_NOT_DESCRIBABLE` | a valid 6-field cron whose seconds field `CronPhrases` has no words for |
+| `X_SCHEDULE_INVALID` | a wall-clock field out of range: `slot.hour`, `slot.minute`, `slot.second`, `slot.weekday` |
 
 ## Why it exists
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.1.0"
+    "@ultimat3/core": "2.0.0"
   }
 }

package/src/business.ts

@@ -4,7 +4,7 @@
  */
 
 import type { Instant } from './instant';
-import { addDaysInZone, isoDateInZone, toZoned } from './zoned';
+import { addDaysInZone, daysBetween, isoDateInZone, toZoned } from './zoned';
 import type { TimeZone } from './zones';
 
 /** ISO weekday numbers: 1 = Monday … 7 = Sunday. */
@@ -68,8 +68,16 @@ export function nextBusinessDay(at: Instant, calendar: BusinessCalendar): Instan
 }
 
 /**
- * Business days in `[from, to)`, counted on local calendar days. Order-independent:
- * a reversed range returns a negative count.
+ * Business days in `[from, to)` — **half-open, and counted on local calendar days**: `from`'s own
+ * day counts, `to`'s does not, and the wall-clock time of either endpoint is not part of the
+ * question. It is exactly the interval `daysBetween` measures, minus the weekends and holidays
+ * in it, so the two functions can never disagree about how long a span is.
+ *
+ * The loop used to advance an *instant* one local day at a time and stop on
+ * `cursor.getTime() > end.getTime()`, which made the last day depend on whether `to`'s clock time
+ * had passed `from`'s: `Mon 09:00 → Fri 10:00` answered 4 and `Mon 09:00 → Fri 08:00` answered 3
+ * for the same calendar span. Order-independent: a reversed range returns a negative count, and an
+ * empty one returns `0` in either direction — never `-0`.
  */
 export function businessDaysBetween(
   from: Instant,
@@ -79,12 +87,16 @@ export function businessDaysBetween(
   const sign = to.getTime() < from.getTime() ? -1 : 1;
   const start = sign === 1 ? from : to;
   const end = sign === 1 ? to : from;
+  // `daysBetween` is the day count of the same half-open interval, so it is also the exact number
+  // of iterations — the loop cannot run away on a calendar `addDaysInZone` handles oddly.
+  const days = daysBetween(start, end, calendar.zone);
   let cursor = start;
   let count = 0;
-  while (isoDateInZone(cursor, calendar.zone) !== isoDateInZone(end, calendar.zone)) {
-    cursor = addDaysInZone(cursor, 1, calendar.zone);
-    if (cursor.getTime() > end.getTime()) break;
+  for (let index = 0; index < days; index += 1) {
     if (isBusinessDay(cursor, calendar)) count += 1;
+    cursor = addDaysInZone(cursor, 1, calendar.zone);
   }
-  return sign * count;
+  // Guarded rather than `sign * count`: an empty interval read backwards would otherwise answer
+  // `-0`, which `Object.is`, a `Map` key and every `toBe` treat as a value distinct from `0`.
+  return count === 0 ? 0 : sign * count;
 }

package/src/context.ts

@@ -1,24 +1,25 @@
 /**
  * Resolve the request timezone once, then read it from the ALS context.
- * User record → header → config default. Every formatter still takes the zone
- * explicitly; this is where call sites get the value from, not a hidden default.
+ * Explicit preference → chosen → browser guess → config default. Every formatter still takes the
+ * zone explicitly; this is where call sites get the value from, not a hidden default.
  */
 
-import { type Ctx, useContext } from '@ultimat3/core';
-import { isValidTimeZone, type TimeZone, UTC } from './zones';
+import { tryUseContext } from '@ultimat3/core';
+import { canonicalTimeZone } from './zone-canonical';
+import { type TimeZone, UTC } from './zones';
 
 /** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
 export const TIMEZONE_HEADER = 'x-timezone';
 
-const CTX_TIMEZONE = 'timeZone';
-
 export interface TimeZoneSources {
   /** `user.timeZone` — an explicit preference beats a browser guess. */
   user?: string | null;
-  /** `x-timezone` request header. */
-  header?: string | null;
+  /** The cookie a zone picker writes — chosen, so it beats what the browser was installed as. */
+  cookie?: string | null;
   /** `?tz=Europe/Berlin`, for share links and email previews. */
   query?: string | null;
+  /** `x-timezone` request header. */
+  header?: string | null;
 }
 
 export type TimeZoneSourceName = keyof TimeZoneSources;
@@ -34,7 +35,15 @@ export interface TimeConfig {
   order: readonly TimeZoneSourceName[];
 }
 
-let config: TimeConfig = { defaultZone: UTC, order: ['user', 'header', 'query'] };
+/**
+ * Explicit before inferred, the same rule `@ultimat3/i18n`'s locale order states: `Accept-Language`
+ * and `x-timezone` are what the browser was installed as, while the user row, the cookie and the
+ * query are what a person *chose*. A zone picker that wrote a cookie the header always outranked
+ * would appear to do nothing.
+ */
+const DEFAULT_ORDER: readonly TimeZoneSourceName[] = ['user', 'cookie', 'query', 'header'];
+
+let config: TimeConfig = { defaultZone: UTC, order: DEFAULT_ORDER };
 
 export function configureTime(partial: Partial<TimeConfig>): TimeConfig {
   config = { ...config, ...partial };
@@ -46,8 +55,12 @@ export function timeConfig(): TimeConfig {
 }
 
 /**
- * First valid IANA name wins. An invalid value is skipped, never thrown: a stale
- * `x-timezone` header from an old client must not fail the request.
+ * First valid IANA name wins, **canonicalized**. An invalid value is skipped, never thrown: a
+ * stale `x-timezone` header from an old client must not fail the request.
+ *
+ * The canonical spelling is what leaves this function, because `Intl` accepts every casing:
+ * `x-timezone: eUrOpE/bErLiN` used to travel the whole request as its own distinct zone string,
+ * and every formatter cache it reached kept a permanent entry for it.
  */
 export function resolveTimeZone(
   sources: TimeZoneSources,
@@ -57,38 +70,23 @@ export function resolveTimeZone(
   for (const name of order) {
     const candidate = sources[name];
     if (candidate === undefined || candidate === null || candidate === '') continue;
-    if (isValidTimeZone(candidate)) return { zone: candidate, source: name };
+    const zone = canonicalTimeZone(candidate);
+    if (zone !== undefined) return { zone, source: name };
   }
   return { zone: defaultZone, source: 'default' };
 }
 
-/** Called once per request by the HTTP layer. */
-export function attachTimeZone(ctx: Ctx, zone: TimeZone): TimeZone {
-  (ctx as unknown as Record<string, unknown>)[CTX_TIMEZONE] = zone;
-  return zone;
-}
-
-export function timeZoneOf(ctx: Ctx): TimeZone {
-  return readField(ctx, CTX_TIMEZONE) ?? config.defaultZone;
-}
-
-/** Ambient zone for the in-flight request; the configured default outside one. */
+/**
+ * Ambient zone for the in-flight request; the configured default outside one.
+ *
+ * The store is **`Ctx.tz`**, core's own declared field — never a second one this package writes.
+ * It used to be a `ctx['timeZone']` key nothing in the framework ever set, while the HTTP pipeline
+ * wrote `ctx.tz`: two ambient answers to one question, and the one every `@ultimat3/ui` component
+ * reads on a server render was the empty one, so every date rendered in UTC however the request
+ * arrived. `withChildContext({ tz })` and `createContext({ tz })` are therefore the only writers,
+ * which is what makes a subtree's zone a core concept rather than this package's.
+ */
 export function currentTimeZone(): TimeZone {
-  const ctx = tryContext();
-  return (ctx === undefined ? undefined : readField(ctx, CTX_TIMEZONE)) ?? config.defaultZone;
-}
-
-function tryContext(): Ctx | undefined {
-  try {
-    return useContext();
-  } catch {
-    // Outside a request scope (boot, worker tick, CLI) — fall back to the configured zone.
-    return undefined;
-  }
-}
-
-/** `Ctx` belongs to core (tier 0) and cannot import `TimeZone`; read the field structurally. */
-function readField(ctx: Ctx, field: string): string | undefined {
-  const value = (ctx as unknown as Record<string, unknown>)[field];
-  return typeof value === 'string' && value !== '' ? value : undefined;
+  const zone = tryUseContext()?.tz;
+  return zone === undefined || zone === '' ? config.defaultZone : zone;
 }

package/src/cron-describe.ts

@@ -5,7 +5,9 @@
  */
 
 import { type CronExpression, parseCronOnce } from './cron-parse';
-import { localeInvalid } from './errors';
+import { cronNotDescribable, localeInvalid } from './errors';
+import { cachedFormatter } from './intl-cache';
+import { canonicalLocale } from './locale-canonical';
 
 export interface CronPhrases {
   everyMinute: string;
@@ -27,15 +29,24 @@ const MAX_LISTED_TIMES = 6;
 /**
  * `describeCron('0 3 * * MON-FRI', 'en', phrases)` → `at 03:00 on Monday–Friday`.
  * Every phrase comes from the caller's `t('time.cron.*')`; only the names are `Intl`'s.
+ *
+ * A 6-field expression whose seconds field says something a 5-field one cannot is **declined**,
+ * not summarised: `CronPhrases` has no seconds vocabulary, so a ten-second step rendered as
+ * "every minute" and `30 0 3 * * *` rendered identically to `0 3 * * *`. A summary that is wrong
+ * is worse than one that says so, and the phrases are the caller's — adding a required field to
+ * `CronPhrases` breaks every existing caller to describe a schedule almost nobody writes.
  */
 export function describeCron(
   expression: string | CronExpression,
   locale: string,
   phrases: CronPhrases,
 ): string {
-  assertLocale(locale);
+  // Canonicalized once, at the entry point, and `tag` is what every line below uses — `EN-us` and
+  // `en-US` are one locale to `Intl`, and must be one key in the caches at the foot of this file.
+  const tag = assertLocale(locale);
   const cron = parseCronOnce(expression);
-  const list = new Intl.ListFormat(locale, { style: 'long', type: 'conjunction' });
+  if (cron.seconds.length !== 1 || cron.seconds[0] !== 0) throw cronNotDescribable(cron);
+  const list = new Intl.ListFormat(tag, { style: 'long', type: 'conjunction' });
   const segments: string[] = [];
 
   const minuteStep = uniformStep(cron.minutes, 60);
@@ -52,7 +63,7 @@ export function describeCron(
     segments.push(hourStep === 1 ? phrases.everyHour : fill(phrases.everyNHours, { n: hourStep }));
   } else {
     explicitTime = true;
-    segments.push(fill(phrases.at, { time: clockTimes(cron, phrases, locale, list) }));
+    segments.push(fill(phrases.at, { time: clockTimes(cron, phrases, tag, list) }));
   }
 
   if (cron.dayOfMonthRestricted) {
@@ -60,11 +71,11 @@ export function describeCron(
     segments.push(fill(phrases.onDaysOfMonth, { days }));
   }
   if (cron.dayOfWeekRestricted) {
-    const days = list.format(cron.daysOfWeek.map((day) => weekdayName(day, locale)));
+    const days = list.format(cron.daysOfWeek.map((day) => weekdayName(day, tag)));
     segments.push(fill(phrases.onWeekdays, { days }));
   }
   if (cron.months.length < 12) {
-    const months = list.format(cron.months.map((month) => monthName(month, locale)));
+    const months = list.format(cron.months.map((month) => monthName(month, tag)));
     segments.push(fill(phrases.inMonths, { months }));
   }
   if (explicitTime && segments.length === 1) segments.push(phrases.everyDay);
@@ -89,13 +100,14 @@ function clockTimes(
   return `${shown} ${fill(phrases.andMore, { n: times.length - MAX_LISTED_TIMES })}`;
 }
 
-/** `Intl` throws a bare `RangeError` on a malformed tag; convert it once, at the entry point. */
-function assertLocale(locale: string): void {
-  try {
-    Intl.DateTimeFormat.supportedLocalesOf([locale]);
-  } catch {
-    throw localeInvalid(locale);
-  }
+/**
+ * `Intl` throws a bare `RangeError` on a malformed tag; convert it once, at the entry point — and
+ * hand back the canonical spelling, so validating and keying are the same single step.
+ */
+function assertLocale(locale: string): string {
+  const tag = canonicalLocale(locale);
+  if (tag === undefined) throw localeInvalid(locale);
+  return tag;
 }
 
 /** Step fields: an evenly spaced set starting at 0 that covers the whole range. */
@@ -118,38 +130,33 @@ function fill(template: string, vars: Readonly<Record<string, string | number>>)
 }
 
 /**
- * Hard-capped rather than key-normalised, because `locale` can arrive from an Accept-Language
- * header: `supportedLocalesOf` collapses unknown *tags*, but still returns a distinct string for
- * every unknown `-u-` extension value, so only a bound keeps the key space finite. FIFO — a `Map`
- * iterates in insertion order — and a miss costs one `Intl` construction, not a wrong answer.
+ * Canonically keyed **and** hard-capped, because `locale` can arrive from an Accept-Language
+ * header. `canonicalLocale` collapses the spellings of one locale — `EN-us`, `en-latn-us` — but it
+ * still returns a distinct string for every unknown `-u-` extension value, so the key alone does
+ * not bound anything and only the cap keeps the key space finite. Neither half is redundant. The
+ * cap and its FIFO live in `intl-cache.ts`, because `zones.ts` and `format.ts` needed the same
+ * rule and a hazard documented in one file is a hazard the other two repeat.
+ *
+ * Both caches are fed the canonical `tag` by `describeCron` alone, never a caller string.
  */
-const MAX_CACHED_LOCALES = 32;
 const monthFormatters = new Map<string, Intl.DateTimeFormat>();
 const weekdayFormatters = new Map<string, Intl.DateTimeFormat>();
 
-function formatterFor(
-  cache: Map<string, Intl.DateTimeFormat>,
-  locale: string,
-  options: Intl.DateTimeFormatOptions,
-): Intl.DateTimeFormat {
-  const hit = cache.get(locale);
-  if (hit !== undefined) return hit;
-  const formatter = new Intl.DateTimeFormat(locale, options);
-  if (cache.size >= MAX_CACHED_LOCALES) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  cache.set(locale, formatter);
-  return formatter;
-}
-
 function monthName(month: number, locale: string): string {
-  const formatter = formatterFor(monthFormatters, locale, { month: 'long', timeZone: 'UTC' });
+  const formatter = cachedFormatter(
+    monthFormatters,
+    locale,
+    () => new Intl.DateTimeFormat(locale, { month: 'long', timeZone: 'UTC' }),
+  );
   return formatter.format(new Date(Date.UTC(2026, month - 1, 1)));
 }
 
 function weekdayName(isoDay: number, locale: string): string {
-  const formatter = formatterFor(weekdayFormatters, locale, { weekday: 'long', timeZone: 'UTC' });
+  const formatter = cachedFormatter(
+    weekdayFormatters,
+    locale,
+    () => new Intl.DateTimeFormat(locale, { weekday: 'long', timeZone: 'UTC' }),
+  );
   // 2026-06-01 is a Monday, so ISO day N is that date + (N - 1).
   return formatter.format(new Date(Date.UTC(2026, 5, isoDay)));
 }

package/src/cron-parse.ts

@@ -141,9 +141,14 @@ function parseField(
     }
 
     if (from > to) {
-      // Wrapping ranges (`fri-mon`, `22-2`) are a real cron idiom.
-      for (let value = from; value <= max; value += step) values.add(value);
-      for (let value = min; value <= to; value += step) values.add(value);
+      // Wrapping ranges (`fri-mon`, `22-2`) are a real cron idiom, and the stride CONTINUES across
+      // the wrap: `23-3/2` is 23, 01, 03 — every second hour starting at 23. Restarting at `min`
+      // answered 23, 00, 02, an hour off for every occurrence past midnight.
+      const span = max - min + 1;
+      const length = to - from + span;
+      for (let offset = 0; offset <= length; offset += step) {
+        values.add(min + ((from - min + offset) % span));
+      }
     } else {
       for (let value = from; value <= to; value += step) values.add(value);
     }

package/src/errors.ts

@@ -3,7 +3,7 @@
  * DST ambiguity is a real state of the world, so it gets a code instead of a guess.
  */
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, renderCauseValue, UltimateError } from '@ultimat3/core';
 
 export const TIME_ERROR_CODES = [
   'X_TIMEZONE_INVALID',
@@ -14,6 +14,7 @@ export const TIME_ERROR_CODES = [
   'X_INSTANT_INVALID',
   'X_SCHEDULE_INVALID',
   'X_LOCALE_INVALID',
+  'X_CRON_NOT_DESCRIBABLE',
 ] as const;
 
 export type TimeErrorCode = (typeof TIME_ERROR_CODES)[number];
@@ -27,6 +28,7 @@ export const TIME_ERROR_TITLES: Readonly<Record<TimeErrorCode, string>> = {
   X_INSTANT_INVALID: 'not a parseable instant',
   X_SCHEDULE_INVALID: 'a wall-clock field is out of range',
   X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
+  X_CRON_NOT_DESCRIBABLE: 'a valid cron expression describeCron has no vocabulary for',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -54,7 +56,9 @@ export class TimeError extends UltimateError {
 export function scheduleInvalid(field: string, value: unknown, range: string): TimeError {
   return new TimeError({
     code: 'X_SCHEDULE_INVALID',
-    cause: `${field} must be ${range}, got ${String(value)}`,
+    // `value` is whatever a caller put in a `LocalSlot` — this factory is exported, so it is a form
+    // field or a config value as often as it is the `number` the in-package caller passes.
+    cause: `${field} must be ${range}, got ${renderCauseValue(value)}`,
     fix: `pass an integer in ${range} for ${field} — wall-clock fields are not wrapped or clamped, because a silently shifted schedule is worse than a failed one`,
   });
 }
@@ -75,6 +79,22 @@ export function cronInvalid(expression: string, reason: string): TimeError {
   });
 }
 
+/**
+ * The expression parses and schedules correctly — `describeCron` just cannot put it into words.
+ * Separate from `X_CRON_INVALID`, which is a typo: this one is a valid schedule, and telling the
+ * caller to fix their cron would be telling them to break a working task.
+ */
+export function cronNotDescribable(cron: {
+  source: string;
+  seconds: readonly number[];
+}): TimeError {
+  return new TimeError({
+    code: 'X_CRON_NOT_DESCRIBABLE',
+    cause: `cron "${cron.source}" fires on second ${cron.seconds.join(',')}, and CronPhrases has no seconds vocabulary`,
+    fix: `render the real runs instead of a summary — nextCronOccurrences('${cron.source}', zone, from, 3) — or, if second-level precision is not wanted, describe the 5-field schedule describeCron('${cron.source.split(/\s+/).slice(1).join(' ')}', locale, phrases)`,
+  });
+}
+
 export function durationInvalid(input: string): TimeError {
   return new TimeError({
     code: 'X_DURATION_INVALID',

package/src/format.ts

@@ -5,6 +5,8 @@
  */
 
 import { differenceMs, type Instant } from './instant';
+import { cachedFormatter } from './intl-cache';
+import { canonicalLocale } from './locale-canonical';
 import { assertTimeZone, type TimeZone } from './zones';
 
 export type DateTimeStyle = 'short' | 'medium' | 'long' | 'full';
@@ -165,11 +167,17 @@ export function ordinal(value: number, locale = 'en'): string {
 
 const cache = new Map<string, Intl.DateTimeFormat>();
 
+/**
+ * Bounded, and keyed on a zone `assertTimeZone` and a locale `canonicalLocale` have both already
+ * canonicalized — `Accept-Language` sends `EN-us` and `en-US` for one locale, and each spelling
+ * used to mint its own permanent entry. The bound stays: an unknown `-u-` extension value survives
+ * canonicalization as a distinct string, so only the cap keeps this key space finite.
+ *
+ * A tag `Intl` cannot parse falls through unchanged, so the `Intl.DateTimeFormat` constructor
+ * still raises it — this seam decides a cache key, never whether a locale is acceptable.
+ */
 function formatterFor(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
-  const key = `${locale}|${JSON.stringify(options)}`;
-  const cached = cache.get(key);
-  if (cached !== undefined) return cached;
-  const formatter = new Intl.DateTimeFormat(locale, options);
-  cache.set(key, formatter);
-  return formatter;
+  const tag = canonicalLocale(locale) ?? locale;
+  const key = `${tag}|${JSON.stringify(options)}`;
+  return cachedFormatter(cache, key, () => new Intl.DateTimeFormat(tag, options));
 }

package/src/index.ts

@@ -14,7 +14,6 @@ export {
   WEEKEND_SUN_ONLY,
 } from './business';
 export {
-  attachTimeZone,
   configureTime,
   currentTimeZone,
   resolveTimeZone,
@@ -24,7 +23,6 @@ export {
   type TimeZoneSourceName,
   type TimeZoneSources,
   timeConfig,
-  timeZoneOf,
 } from './context';
 export {
   type CronExpression,
@@ -54,6 +52,7 @@ export {
 } from './duration';
 export {
   cronInvalid,
+  cronNotDescribable,
   dstAmbiguous,
   dstNonexistent,
   durationInvalid,
@@ -83,7 +82,7 @@ export {
   addMs,
   compareInstants,
   differenceMs,
-  EPOCH,
+  epoch,
   fromEpochMs,
   fromEpochSeconds,
   fromIso,
@@ -105,6 +104,11 @@ export {
   nextWeeklySlot,
   type WeeklySlot,
 } from './schedule';
+/**
+ * `canonicalTimeZone` is public because a zone arriving from a request header has to become one
+ * key before it reaches anything that caches on it — `@ultimat3/http` reads `x-timezone`.
+ */
+export { canonicalTimeZone } from './zone-canonical';
 export {
   addDaysInZone,
   daysBetween,

package/src/instant.ts

@@ -12,10 +12,16 @@ declare const instantBrand: unique symbol;
 /** A `Date` that has been proven valid and is documented as UTC. */
 export type Instant = Date & { readonly [instantBrand]: 'utc' };
 
-/** Wrap a `Date` from an untrusted source (a DB driver, a parsed payload). */
+/**
+ * Wrap a `Date` from an untrusted source (a DB driver, a parsed payload).
+ *
+ * A **copy**, never the caller's own object: `value as Instant` handed back a `Date` the caller
+ * still holds and can `setTime()` after the brand is applied, so a value this function certified
+ * as valid could stop being the value it certified.
+ */
 export function instant(value: Date): Instant {
   if (Number.isNaN(value.getTime())) throw instantInvalid(String(value));
-  return value as Instant;
+  return new Date(value.getTime()) as Instant;
 }
 
 /** ISO-8601 in, `Instant` out. An offset or `Z` is required — a bare local string is a bug. */
@@ -86,7 +92,18 @@ export function isInstant(value: unknown): value is Instant {
   return value instanceof Date && !Number.isNaN(value.getTime());
 }
 
-export const EPOCH: Instant = new Date(0) as Instant;
+/**
+ * A fresh instant at the Unix epoch, per call.
+ *
+ * Replaces the `EPOCH` constant, which was one shared mutable `Date` exported from a tier-1
+ * package: a single `EPOCH.setUTCFullYear(...)` anywhere in the process corrupted it for every
+ * other consumer, permanently and silently. A `Date` cannot be frozen — `Object.freeze` does not
+ * close `setTime`, because the value lives in an internal slot — so the only safe shape is a
+ * function. **Breaking: `EPOCH` is removed**; it had no callers in this repo.
+ */
+export function epoch(): Instant {
+  return new Date(0) as Instant;
+}
 
 /** Tolerates a `Clock` whose `now()` returns either a `Date` or epoch milliseconds. */
 function epochMsOf(value: Date | number): number {

package/src/intl-cache.ts

@@ -0,0 +1,26 @@
+/**
+ * One bounded cache for every `Intl` formatter this package builds.
+ * A locale and a zone both arrive from a request header, so an unbounded `Map` keyed on that
+ * string is memory the client chooses: 4,096 case-variants of one zone name retained 31 MB,
+ * ~7.7 KB per `Intl.DateTimeFormat`, and 600 zones times 2^12 casings has no ceiling at all.
+ */
+
+/**
+ * Above the full canonical IANA set (445 zones as of tzdata 2025) so a correct app never evicts,
+ * and small enough that the worst case is a few megabytes rather than a leak. A miss costs one
+ * `Intl` construction, never a wrong answer — which is what makes a bound safe here at all.
+ */
+export const MAX_CACHED_FORMATTERS = 512;
+
+/** FIFO — a `Map` iterates in insertion order, so the first key inserted is the first evicted. */
+export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: () => T): T {
+  const hit = cache.get(key);
+  if (hit !== undefined) return hit;
+  const formatter = build();
+  if (cache.size >= MAX_CACHED_FORMATTERS) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(key, formatter);
+  return formatter;
+}

package/src/locale-canonical.ts

@@ -0,0 +1,23 @@
+/**
+ * One locale, one key. `Intl` accepts `EN-us`, `en-US` and `en-latn-us` as the same locale, so a
+ * cache keyed on the caller's spelling holds three formatters where one would do — and the caller
+ * is `Accept-Language`. The twin of `zone-canonical.ts`, for the other header-supplied string.
+ */
+
+/**
+ * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
+ * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
+ * falls back for it, and refusing here would be stricter than the formatters this feeds.
+ *
+ * Deliberately **not** memoised: this is string work, and a `Map` keyed on a header value is the
+ * unbounded cache the whole `intl-cache.ts` bound exists to prevent.
+ */
+export function canonicalLocale(locale: string): string | undefined {
+  try {
+    // `getCanonicalLocales` runs the same IsStructurallyValidLanguageTag check that
+    // `supportedLocalesOf` throws on, and unlike it, hands back the canonical spelling.
+    return Intl.getCanonicalLocales(locale)[0];
+  } catch {
+    return undefined;
+  }
+}

package/src/schedule.ts

@@ -25,9 +25,9 @@ export interface LocalSlot {
  * gap, `{ gap: 'next' }` picks the first existing local time instead of skipping the day.
  */
 /** Wall-clock fields are never wrapped or clamped — a shifted schedule beats no schedule. */
-function assertWallField(field: string, value: number, max: number): void {
-  if (!Number.isInteger(value) || value < 0 || value > max) {
-    throw scheduleInvalid(field, value, `an integer 0-${String(max)}`);
+function assertWallField(field: string, value: number, max: number, min = 0): void {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw scheduleInvalid(field, value, `an integer ${String(min)}-${String(max)}`);
   }
 }
 
@@ -80,11 +80,16 @@ export interface WeeklySlot extends LocalSlot {
 
 /** Next `weekday` at the local time, strictly after `after`. */
 export function nextWeeklySlot(slot: WeeklySlot, after: Instant): Instant {
+  // Checked BEFORE the search, not after it. Falling out of the loop reported X_TIMEZONE_INVALID
+  // naming a zone that is perfectly valid, with a fix line about IANA identifiers that fixes
+  // nothing — the field the caller got wrong is `weekday`, and an error has to say so.
+  assertWallField('slot.weekday', slot.weekday, 7, 1);
   let cursor = after;
   for (let index = 0; index < 8; index += 1) {
     const candidate = nextLocalSlot(slot, cursor);
     if (toZoned(candidate, slot.zone).weekday === slot.weekday) return candidate;
     cursor = candidate;
   }
+  // Seven local days always contain every ISO weekday; reaching here means the zone data is broken.
   throw timezoneInvalid(slot.zone);
 }

package/src/zone-canonical.ts

@@ -0,0 +1,54 @@
+/**
+ * One IANA zone, one key. `Intl` accepts every casing of a zone name, so `Europe/Berlin` and
+ * `eUrOpE/bErLiN` reach a formatter cache — and every downstream comparison — as two zones.
+ * A 13-letter name has 2^12 casings and a request header can name any of them.
+ */
+
+import { cachedFormatter } from './intl-cache';
+
+/** ES2024 `Intl` accepts `+01:00` as a zone; we do not — a fixed offset has no DST rules. */
+const NUMERIC_OFFSET = /^[+-]/;
+
+/**
+ * Lowercase → canonical, for every zone the runtime lists. Built once, ~445 entries, and it is
+ * what makes the common case — a casing of a real zone — cost a string lookup instead of an
+ * `Intl.DateTimeFormat` construction the caller can mint at will.
+ */
+let listed: Map<string, string> | undefined;
+
+function listedZones(): Map<string, string> {
+  if (listed !== undefined) return listed;
+  const table = new Map<string, string>();
+  for (const zone of Intl.supportedValuesOf('timeZone')) table.set(zone.toLowerCase(), zone);
+  listed = table;
+  return table;
+}
+
+/**
+ * Deprecated aliases (`US/Eastern`, `Asia/Calcutta`) and the runtime's extras (`EST`, `GMT`) are
+ * not in the listed set, so they take the `Intl` probe once — bounded for the same reason every
+ * other cache here is.
+ */
+const probed = new Map<string, string | ''>();
+
+/**
+ * The canonical spelling of an IANA zone, or `undefined` for anything that is not one.
+ * `'CET'` and `'+01:00'` are not zones: an abbreviation is ambiguous and an offset has no rules.
+ */
+export function canonicalTimeZone(zone: string): string | undefined {
+  if (zone === '' || NUMERIC_OFFSET.test(zone)) return undefined;
+  const known = listedZones().get(zone.toLowerCase());
+  if (known !== undefined) return known;
+  // `''` is the cached "not a zone" answer — a `Map` miss and a cached refusal must not look the
+  // same, or every invalid header re-probes `Intl` forever.
+  const resolved = cachedFormatter(probed, zone, () => resolve(zone));
+  return resolved === '' ? undefined : resolved;
+}
+
+function resolve(zone: string): string | '' {
+  try {
+    return new Intl.DateTimeFormat('en-US', { timeZone: zone }).resolvedOptions().timeZone;
+  } catch {
+    return '';
+  }
+}

package/src/zones.ts

@@ -6,15 +6,14 @@
 
 import { timezoneInvalid } from './errors';
 import type { Instant } from './instant';
+import { cachedFormatter } from './intl-cache';
+import { canonicalTimeZone } from './zone-canonical';
 
 /** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */
 export type TimeZone = string;
 
 export const UTC: TimeZone = 'UTC';
 
-/** ES2024 `Intl` accepts `+01:00` as a zone; we do not — a fixed offset has no DST rules. */
-const NUMERIC_OFFSET = /^[+-]/;
-
 /**
  * The package's only builder of a UTC epoch from calendar fields, because `Date.UTC` remaps
  * years 0–99 onto 1900–1999 — silently, so a first-century wall clock resolves 1900 years off
@@ -36,18 +35,18 @@ export function utcEpoch(
 }
 
 export function isValidTimeZone(zone: string): boolean {
-  if (zone === '' || NUMERIC_OFFSET.test(zone)) return false;
-  try {
-    new Intl.DateTimeFormat('en-US', { timeZone: zone });
-    return true;
-  } catch {
-    return false;
-  }
+  return canonicalTimeZone(zone) !== undefined;
 }
 
+/**
+ * The **canonical** spelling, not the caller's. `Intl` answers for every casing of a zone name, so
+ * returning the input let one zone travel the process as many strings — each one its own key in
+ * every formatter cache downstream, and unbounded when the string came from a request header.
+ */
 export function assertTimeZone(zone: string): TimeZone {
-  if (!isValidTimeZone(zone)) throw timezoneInvalid(zone);
-  return zone;
+  const canonical = canonicalTimeZone(zone);
+  if (canonical === undefined) throw timezoneInvalid(zone);
+  return canonical;
 }
 
 /** Wall-clock fields of an instant in a zone, seconds precision. */
@@ -127,13 +126,20 @@ export function zoneAbbrev(
   return label ?? offsetLabel(offsetAt(zone, at));
 }
 
-/** True when the zone observes a different offset at some point in the surrounding year. */
+/**
+ * True when the zone observes a different offset at some point in the surrounding year.
+ *
+ * Twelve probes on the FIRST of twelve consecutive months. `setUTCMonth(+n)` rolls over at month
+ * end — from 31 January the twelve probes land in January, March, March, May, May, July, July,
+ * August, October, October, December, December, so February, April, June, September and November
+ * are never asked, and a zone whose only transition falls in one of them reads as DST-free.
+ */
 export function observesDst(zone: TimeZone, at: Instant): boolean {
+  const start = zonePartsAt(zone, at);
   const offsets = new Set<number>();
   for (let month = 0; month < 12; month += 1) {
-    const probe = new Date(at.getTime());
-    probe.setUTCMonth(probe.getUTCMonth() + month);
-    offsets.add(offsetAt(zone, probe as Instant));
+    const probe = new Date(utcEpoch(start.year, start.month + month, 1, 12)) as Instant;
+    offsets.add(offsetAt(zone, probe));
   }
   return offsets.size > 1;
 }
@@ -141,25 +147,24 @@ export function observesDst(zone: TimeZone, at: Instant): boolean {
 const formatters = new Map<string, Intl.DateTimeFormat>();
 
 function partsFormatterFor(zone: TimeZone): Intl.DateTimeFormat {
-  const cached = formatters.get(zone);
-  if (cached !== undefined) return cached;
-  let formatter: Intl.DateTimeFormat;
-  try {
-    formatter = new Intl.DateTimeFormat('en-US', {
-      timeZone: zone,
-      hourCycle: 'h23',
-      year: 'numeric',
-      month: '2-digit',
-      day: '2-digit',
-      hour: '2-digit',
-      minute: '2-digit',
-      second: '2-digit',
-    });
-  } catch {
-    throw timezoneInvalid(zone);
-  }
-  formatters.set(zone, formatter);
-  return formatter;
+  // Keyed on the canonical name, so 4,096 casings of one zone are one entry rather than 4,096.
+  const canonical = canonicalTimeZone(zone);
+  if (canonical === undefined) throw timezoneInvalid(zone);
+  return cachedFormatter(
+    formatters,
+    canonical,
+    () =>
+      new Intl.DateTimeFormat('en-US', {
+        timeZone: canonical,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+      }),
+  );
 }
 
 function pad2(value: number): string {