@ultimat3/time 1.2.0 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# @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 |
+| `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 |
+| `plain-date.ts` | `PlainDate` — a calendar date with no time and no zone, and the two conversions to an instant |
+
+## 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`). **`cachedFormatter`,
+  `MAX_CACHED_FORMATTERS` and `canonicalLocale` are `@ultimat3/core`'s as of 2.0.0**, not this
+  package's: `@ultimat3/money` hit the identical unbounded-`Map`-on-a-header bug and tier 1 may not
+  import sideways, so the mechanism moved down a tier rather than being copied. 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.
+- **A `PlainDate` is a branded STRING, and the golden rule does not apply to it** — decided
+  2026-08 for `@ultimat3/entity`'s `date()` column. "Never format a date without a zone" is about
+  INSTANTS; a calendar date names no instant, so it needs no zone, and giving it one is the bug:
+  `effective_on` stored as a `timestamptz` is a different date on either side of midnight for half
+  the planet. Not a `Date` (that is an instant, and binding one to a Postgres `date` parameter
+  fails outright — `time zone "gmt-0500" not recognized`, measured on 17.10) and not
+  `{ year, month, day }` (an object sorts by nothing and JSON-stringifies as three fields). The ISO
+  string sorts lexicographically exactly as it sorts chronologically, which is why every cursor,
+  `orderBy` and `compare` in the framework handles it with no special case at all.
+- **`plainDateIn` takes a zone and `plainDateUtc` does not, and neither is a default for the
+  other.** An instant has a calendar date only in a zone; a `Date` a driver returns for a `date`
+  column is midnight UTC and reading its LOCAL fields loses a day west of Greenwich. `bun test`
+  pins the process to UTC, so that bug is invisible to every in-process test — `plain-date.test.ts`
+  spawns a subprocess with `TZ=America/Los_Angeles` for exactly one assertion, and that is the only
+  reason it can fail.
+- 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,22 @@ 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 stays either way: an unknown `-u-` extension value survives
+canonicalization as a distinct string, so the key bounds nothing on its own. Both halves —
+`canonicalLocale` and `cachedFormatter` — are `@ultimat3/core`'s as of 2.0.0, so `@ultimat3/money`
+reads the same bound rather than a copy of it.
+
+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
@@ -64,6 +80,34 @@ one of these takes the zone explicitly, and none of them has a default.
 `daysBetween` counts boundaries, not milliseconds: 23 real hours across spring forward is `1`,
 and 24 real hours inside a 25-hour fall-back day is `0`.
 
+## A calendar date is not an instant
+
+`PlainDate` is `2026-03-14`: a year, a month and a day, with **no time and therefore no zone**,
+`As of 2026-08`. The golden rule at the top of this page is about instants — a `PlainDate` needs no
+zone because it names no moment, and that is the honest modelling of the values that have one.
+`effective_on` is the date a rate applies; a birthday is a date; an invoice period is two of them.
+Stored as a `timestamptz`, every one of those is a different date on either side of midnight for
+half the planet.
+
+| Function | Answers |
+|---|---|
+| `plainDate(value)` / `isPlainDate(value)` | the date, or a refusal — `2026-02-30` is not one, and a regex cannot say so |
+| `plainDateOf({ year, month, day })` | the same, from fields; an impossible day throws instead of rolling into the next month |
+| `plainDateParts(date)` | back to fields |
+| `plainDateIn(at, zone)` | the calendar date an **instant** falls on, in a named zone. It takes the zone because there is no other honest way to make this conversion |
+| `plainDateUtc(at)` | the date a `Date` holds read as UTC — for the one caller that needs it: a Postgres driver returns a `date` column as midnight UTC |
+| `plainDateToUtcInstant(date)` | midnight UTC of the date. The inverse of `plainDateUtc`, and never of `plainDateIn` |
+| `addPlainDays(date, days)` / `plainDaysBetween(from, to)` | calendar arithmetic with no zone in it: a DST day is one day, because there is no zone to shorten |
+| `comparePlainDates(a, b)` | `-1` / `0` / `1` |
+
+It is a branded **string**, and both halves are load-bearing. Not a `Date`: a `Date` is an instant,
+so `2026-03-14T00:00:00Z` is the 13th anywhere west of Greenwich, and binding one to a Postgres
+`date` parameter fails outright (`time zone "gmt-0500" not recognized`, measured on 17.10). A
+string: the ISO form sorts lexicographically exactly as it sorts chronologically, round-trips
+through `JSON.stringify` as itself, and is the literal Postgres accepts and returns.
+
+`@ultimat3/entity`'s `date()` column is the one that stores it.
+
 ## Cron
 
 `parseCron` handles 5 or 6 fields, `*/n`, ranges, lists, named months and days, `@daily`
@@ -73,13 +117,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 +143,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.2.0",
+  "version": "3.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.2.0"
+    "@ultimat3/core": "3.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

@@ -4,8 +4,9 @@
  * ship English to every locale that forgot the argument — so injection is mandatory, not opt-in.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { type CronExpression, parseCronOnce } from './cron-parse';
-import { localeInvalid } from './errors';
+import { cronNotDescribable, localeInvalid } from './errors';
 
 export interface CronPhrases {
   everyMinute: string;
@@ -27,15 +28,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 +62,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 +70,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 +99,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 +129,34 @@ 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 `@ultimat3/core`'s `intl-cache.ts`, because `zones.ts`, `format.ts` and
+ * `@ultimat3/money`'s formatter all need the same rule, and a hazard documented in one file is a
+ * hazard every other one repeats.
+ *
+ * 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

@@ -65,7 +65,9 @@ export function parseCron(expression: string): CronExpression {
   const hours = parseField(expression, hourField ?? '*', 0, 23);
   const daysOfMonth = parseField(expression, domField ?? '*', 1, 31);
   const months = parseField(expression, monthField ?? '*', 1, 12, MONTH_NAMES, 1);
-  const rawDow = parseField(expression, dowField ?? '*', 0, 7, DAY_NAMES, 0);
+  // Span 7, not `max - min + 1` = 8: the dow field accepts 0-7 because Sunday has two spellings,
+  // so the modulus a wrap strides over is a week with a phantom day in it unless it is stated.
+  const rawDow = parseField(expression, dowField ?? '*', 0, 7, DAY_NAMES, 0, 7);
 
   // 0 and 7 are both Sunday in cron; ISO calls Sunday 7.
   const daysOfWeek = [...new Set(rawDow.map((day) => (day === 0 ? 7 : day)))].sort((a, b) => a - b);
@@ -113,6 +115,13 @@ function parseField(
   max: number,
   names: readonly string[] = [],
   nameOffset = 0,
+  /**
+   * How many distinct values one full turn of this field has — `max - min + 1` for every field
+   * whose spelling is one-to-one. Day-of-week is the exception and the reason this is a parameter:
+   * it spells Sunday twice (0 and 7), so its 0-7 bounds describe 8 slots over a 7-day week, and a
+   * wrapping stride computed from the bounds walked a day that does not exist.
+   */
+  span = max - min + 1,
 ): number[] {
   const values = new Set<number>();
   for (const part of field.split(',')) {
@@ -141,9 +150,13 @@ 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 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

@@ -4,6 +4,7 @@
  * because "the server's timezone" is never the answer to "what time is it for the user".
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
 import { assertTimeZone, type TimeZone } from './zones';
 
@@ -165,11 +166,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,
@@ -98,6 +97,21 @@ export {
   toIso,
   toIsoDateUtc,
 } from './instant';
+export {
+  addPlainDays,
+  comparePlainDates,
+  isPlainDate,
+  PLAIN_DATE_PATTERN,
+  type PlainDate,
+  type PlainDateParts,
+  plainDate,
+  plainDateIn,
+  plainDateOf,
+  plainDateParts,
+  plainDateToUtcInstant,
+  plainDateUtc,
+  plainDaysBetween,
+} from './plain-date';
 export {
   type LocalSlot,
   nextLocalSlot,
@@ -105,6 +119,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/plain-date.ts

@@ -0,0 +1,133 @@
+// A calendar date: a year, a month and a day, with no time and therefore no zone. The framework's
+// "never format a date without an IANA zone" rule is about INSTANTS — a `PlainDate` needs no zone
+// because it names no instant, and that is the whole reason it exists: `effective_on` is the date
+// a rate applies, not a moment, and storing it as a `timestamptz` makes it a different date either
+// side of midnight for half the planet.
+
+import { scheduleInvalid } from './errors';
+import { type Instant, instant } from './instant';
+import { isoDateInZone } from './zoned';
+import type { TimeZone } from './zones';
+
+declare const plainDateBrand: unique symbol;
+
+/**
+ * `2026-03-14`. A branded STRING, not an object and not a `Date`, and each half of that is load-
+ * bearing:
+ *
+ * - not a `Date`, because a `Date` is an instant: read back through the local zone,
+ *   `2026-03-14T00:00:00Z` is the 13th anywhere west of Greenwich, and binding one to a Postgres
+ *   `date` parameter fails outright (`time zone "gmt-0500" not recognized`, measured on 17.10).
+ * - a string, because the ISO form sorts lexicographically exactly as it sorts chronologically,
+ *   round-trips through `JSON.stringify` as itself, and is the literal Postgres accepts and
+ *   returns for a `date` column.
+ */
+export type PlainDate = string & { readonly [plainDateBrand]: 'plain-date' };
+
+/** The shape a CHECK constraint and a JSON Schema both spell. ECMAScript and POSIX ERE agree. */
+export const PLAIN_DATE_PATTERN = '^\\d{4}-\\d{2}-\\d{2}$';
+
+const SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+export interface PlainDateParts {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+}
+
+const pad = (value: number, width: number): string => String(value).padStart(width, '0');
+
+/** Days in a month, Gregorian. February is the only interesting one. */
+const daysInMonth = (year: number, month: number): number =>
+  month === 2
+    ? (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0
+      ? 29
+      : 28
+    : [4, 6, 9, 11].includes(month)
+      ? 30
+      : 31;
+
+/**
+ * The parse every other function here goes through. `null` rather than a throw, so the guard and
+ * the thrower share one rule and only the failure policy differs — the same split
+ * `resolveEnvironment` / `tryResolveEnvironment` make in core.
+ */
+const read = (value: unknown): PlainDateParts | null => {
+  if (typeof value !== 'string') return null;
+  const match = SHAPE.exec(value);
+  if (match === null) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (month < 1 || month > 12) return null;
+  // A day the month does not have is the case a regex cannot see, and it is the one that matters:
+  // `2026-02-30` reaches Postgres as `date` input and is rejected there, three layers later.
+  if (day < 1 || day > daysInMonth(year, month)) return null;
+  return { year, month, day };
+};
+
+export const isPlainDate = (value: unknown): value is PlainDate => read(value) !== null;
+
+/** A calendar date from its ISO form. Throws on anything that is not one — including `2026-02-30`. */
+export function plainDate(value: string): PlainDate {
+  const parts = read(value);
+  if (parts === null) {
+    throw scheduleInvalid('date', value, 'a real YYYY-MM-DD calendar date');
+  }
+  return value as PlainDate;
+}
+
+/** A calendar date from its fields. Out-of-range fields throw rather than wrap into another month. */
+export function plainDateOf(parts: PlainDateParts): PlainDate {
+  return plainDate(`${pad(parts.year, 4)}-${pad(parts.month, 2)}-${pad(parts.day, 2)}`);
+}
+
+export function plainDateParts(date: PlainDate): PlainDateParts {
+  const parts = read(date);
+  if (parts === null) throw scheduleInvalid('date', date, 'a real YYYY-MM-DD calendar date');
+  return parts;
+}
+
+/**
+ * The calendar date an instant falls on **in a named zone** — the one conversion between the two,
+ * and it takes a zone because there is no other honest way to make it. 09:00 UTC on the 14th is
+ * still the 13th in Los Angeles.
+ */
+export const plainDateIn = (at: Instant, zone: TimeZone): PlainDate =>
+  isoDateInZone(at, zone) as PlainDate;
+
+/**
+ * The calendar date a `Date` holds when read as UTC. For ONE caller: a Postgres driver hands a
+ * `date` column back as a `Date` at UTC midnight (measured: Bun's `sql` and PGlite both), so the
+ * date the column holds is its UTC date and reading it through the local zone loses a day west of
+ * Greenwich. Never use this on a timestamp — that is `plainDateIn`, which asks for the zone.
+ */
+export function plainDateUtc(at: Date): PlainDate {
+  const checked = instant(at);
+  return `${pad(checked.getUTCFullYear(), 4)}-${pad(checked.getUTCMonth() + 1, 2)}-${pad(
+    checked.getUTCDate(),
+    2,
+  )}` as PlainDate;
+}
+
+/** Midnight UTC of the date, as an instant — the inverse of `plainDateUtc`, and never of `plainDateIn`. */
+export const plainDateToUtcInstant = (date: PlainDate): Instant =>
+  instant(new Date(`${plainDate(date)}T00:00:00.000Z`));
+
+/** `-1`, `0`, `1`. Lexicographic order IS chronological order for this form; that is why it sorts. */
+export const comparePlainDates = (left: PlainDate, right: PlainDate): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const DAY_MS = 86_400_000;
+
+/** Whole days added, over UTC midnights, so no DST rule and no zone can shorten a day here. */
+export function addPlainDays(date: PlainDate, days: number): PlainDate {
+  if (!Number.isSafeInteger(days)) {
+    throw scheduleInvalid('days', days, 'a whole number of days');
+  }
+  return plainDateUtc(new Date(plainDateToUtcInstant(date).getTime() + days * DAY_MS));
+}
+
+/** Signed whole days from `from` to `to`. Always integral: both ends are UTC midnights. */
+export const plainDaysBetween = (from: PlainDate, to: PlainDate): number =>
+  (plainDateToUtcInstant(to).getTime() - plainDateToUtcInstant(from).getTime()) / DAY_MS;

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 '@ultimat3/core';
+
+/** 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

@@ -4,17 +4,16 @@
  * is no offset table to keep in sync and no `date-fns-tz` dependency.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { timezoneInvalid } from './errors';
 import type { Instant } from './instant';
+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. */
@@ -118,48 +117,64 @@ export function zoneAbbrev(
   locale = 'en-US',
   style: 'short' | 'long' | 'shortOffset' | 'longOffset' = 'short',
 ): string {
-  const formatter = new Intl.DateTimeFormat(locale, {
-    timeZone: zone,
-    timeZoneName: style,
-    hourCycle: 'h23',
+  const canonical = assertTimeZone(zone);
+  // A tag `Intl` cannot parse falls through unchanged, exactly as in `format.ts`: this decides a
+  // cache key, never whether a locale is acceptable.
+  const tag = canonicalLocale(locale) ?? locale;
+  // The one `Intl` construction in this package that escaped the shared cache: it built a formatter
+  // per call on the caller's raw zone and locale, so an `x-timezone` an app renders a label from
+  // paid for a fresh `Intl.DateTimeFormat` every time and an unknown one escaped as a `RangeError`.
+  const formatter = cachedFormatter(labelFormatters, `${canonical}|${tag}|${style}`, () => {
+    return new Intl.DateTimeFormat(tag, {
+      timeZone: canonical,
+      timeZoneName: style,
+      hourCycle: 'h23',
+    });
   });
   const label = formatter.formatToParts(at).find((part) => part.type === 'timeZoneName')?.value;
-  return label ?? offsetLabel(offsetAt(zone, at));
+  return label ?? offsetLabel(offsetAt(canonical, 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;
 }
 
 const formatters = new Map<string, Intl.DateTimeFormat>();
+const labelFormatters = 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 {