@ultimat3/time 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -143,6 +143,28 @@
   applies ONLY when day-of-month is restricted and day-of-week is not: Vixie's OR means
   `0 0 30 2 5` fires every Friday in February, so refusing it would break a working schedule.
   `MAX_STEPS` stays as the backstop for what the check cannot see.
+- **The repeated hour of a fall-back night is run through by an INTERVAL and fired once by a FIXED
+  time, `As of 2026-10`.** `CronExpression.wildcardTime` — the minute or hour field spelled `*` or
+  `*/n`, Vixie's test — is the whole decision. The wall-clock walk alone cannot see the hour come
+  round again (from 02:55 it reaches 03:00), so `*/5 * * * *` went dark 01:00Z–02:00Z in Berlin
+  once a year while `matchesCron` answered `true` inside it. `nextCronOccurrence` walks a second
+  time from the wall clock the transition lands on. A fixed time never returns its second pass,
+  from ANY `after` — `@ultimat3/jobs`' `latestOccurrence` bisects over `after`, so the answer must
+  be monotone in it; `cron-occurrence.test.ts` pins that. `matchesCron` stays the pure wall-clock
+  predicate and is `true` for a fixed time's second pass: it answers "does this instant's clock
+  match", not "is this an occurrence".
+- **`addBusinessDays` builds every candidate from the calendar date + the ORIGINAL wall time.**
+  Chained through `addDaysInZone`, a 02:30 that crossed a spring-forward Sunday became 03:30 and
+  stayed 03:30 on Monday. `businessDaysBetween` walks the same dates (`localDay`): a chain steps
+  OVER a date the zone never had (Samoa, 2011-12-30) and so counted the day `to` excludes. A date
+  that does not exist is not a day of either kind.
+- **`formatRelative` takes `zone`, and from a day apart counts CALENDAR days** (`daysBetween`).
+  `trunc(47h / 24h)` called two midnights away "tomorrow". Under a day it is elapsed time; a full
+  day apart with no midnight crossed (a 25-hour day) is hours, not "today". **Breaking.**
+- **A cron name matches EXACTLY** — its three letters or its whole word. First-three-letters
+  matching read `marzipan` as March. Extra `-` and `/` parts are refused, not dropped.
+- **A `PlainDate` has four year digits.** `plainDateUtc` (and so `addPlainDays`) and `plainDateIn`
+  refuse a year outside 0000-9999 rather than brand `10000-01-01`, which `isPlainDate` rejects.
 - 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`.

package/README.md

@@ -58,6 +58,11 @@ formatWithOffset(at, { locale: 'en-GB', zone: 'America/New_York' });
 nextLocalSlot({ zone: 'Asia/Kathmandu', hour: 9 }, now(clock)); // 09:00 local, +05:45 handled
 ```
 
+`formatRelative(at, { locale, zone, now })` — `in 3 days`, `2 hours ago`. `zone` is required: from
+a day apart the number is **calendar days in that zone** (`daysBetween`), so 47 hours ahead across
+two midnights is `in 2 days`, never `tomorrow`. Under a day apart it is elapsed hours, minutes or
+seconds.
+
 ## DST is a policy, not a guess
 
 `fromZoned(wall, zone, { gap, overlap })` is the function everything else is built on.
@@ -84,9 +89,10 @@ one of these takes the zone explicitly, and none of them has a default.
 | Function | Answers |
 |---|---|
 | `startOfDay(at, zone)` / `endOfDay(at, zone)` | local midnight; the last millisecond of the day |
-| `addDaysInZone(at, days, zone)` | the same wall-clock time, `days` calendar days away |
+| `addDaysInZone(at, days, zone)` | the same wall-clock time, `days` calendar days away. `days` is a whole number — `NaN` and `0.5` are `X_SCHEDULE_INVALID` |
 | `daysBetween(from, to, zone)` | local day boundaries crossed — signed, always integral |
 | `isoDateInZone(at, zone)` | `2026-03-14` |
+| `isoInZone(at, zone)` | `2026-03-08T03:00:00-04:00` — ISO-8601 with the zone's own offset, never `Z` for a non-UTC zone. `toIso` is the UTC form |
 | `isSameLocalDay(left, right, zone)` | whether two instants share a local date |
 
 `daysBetween` counts boundaries, not milliseconds: 23 real hours across spring forward is `1`,
@@ -109,7 +115,7 @@ half the planet.
 | `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 |
+| `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. A result outside years `0000`-`9999` is `X_SCHEDULE_INVALID` |
 | `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,
@@ -126,7 +132,18 @@ through `JSON.stringify` as itself, and is the literal Postgres accepts and retu
 macros, and Vixie's dom/dow OR rule. `nextCronOccurrence(expr, zone, after)` iterates the
 zone's **wall clock**, so `0 3 * * *` in `Europe/Berlin` stays at 03:00 local across a DST
 change, and a job scheduled inside the gap runs at the first existing local time instead of
-being skipped. `describeCron(expr, locale, phrases)` renders the dashboard summary — month and
+being skipped. A name is its three letters or its whole word (`mon`, `monday`) — never a prefix
+match — and a range has two ends, a step one: `marzipan`, `1-5-7` and `1/2/3` are `X_CRON_INVALID`.
+
+On a fall-back night the repeated hour is decided by what the expression names
+(`CronExpression.wildcardTime`, Vixie's rule):
+
+| Expression | In the repeated hour |
+|---|---|
+| a fixed time — `30 2 * * *` | fires **once**, on the first pass, whichever instant it is asked from |
+| an interval — minute or hour field `*` or `*/n`: `*/5 * * * *`, `0 * * * *` | runs through **both** passes; no hour of the night is 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. A
@@ -139,6 +156,10 @@ ten-second step used to render as "every minute".
 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.
 
+`addBusinessDays(at, days, calendar)` keeps the **original** wall-clock time: every candidate is the
+calendar date plus the time the caller started with, so a spring-forward day on the way does not
+shift the days after it.
+
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -34,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/schema": "22.15.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/schema": "24.0.0"
   }
 }

package/src/business.ts

@@ -5,8 +5,8 @@
 
 import { scheduleInvalid } from './errors';
 import type { Instant } from './instant';
-import { addDaysInZone, daysBetween, isoDateInZone, toZoned } from './zoned';
-import type { TimeZone } from './zones';
+import { daysBetween, fromZoned, isoDateInZone, toZoned, type ZonedDateTime } from './zoned';
+import { type TimeZone, utcEpoch } from './zones';
 
 /** ISO weekday numbers: 1 = Monday … 7 = Sunday. */
 export type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
@@ -57,18 +57,56 @@ export function addBusinessDays(at: Instant, days: number, calendar: BusinessCal
   }
   if (days === 0) return at;
   const step = days > 0 ? 1 : -1;
+  const origin = toZoned(at, calendar.zone);
   let remaining = Math.abs(days);
-  let cursor = at;
+  let offset = 0;
   let guard = 0;
+  let landed = at;
 
   while (remaining > 0) {
-    cursor = addDaysInZone(cursor, step, calendar.zone);
-    if (isBusinessDay(cursor, calendar)) remaining -= 1;
+    offset += step;
+    const candidate = localDay(origin, offset, calendar.zone);
+    if (candidate !== null && isBusinessDay(candidate, calendar)) {
+      remaining -= 1;
+      landed = candidate;
+    }
     guard += 1;
     // A calendar with every day marked as a holiday would otherwise loop forever.
-    if (guard > Math.abs(days) * 7 + 3650) return cursor;
+    if (guard > Math.abs(days) * 7 + 3650) return localDay(origin, offset, calendar.zone) ?? landed;
   }
-  return cursor;
+  return landed;
+}
+
+/**
+ * The calendar date `offset` days from `origin`'s, at `origin`'s wall time — or `null` when the
+ * zone never had that date (Samoa's 2011-12-30).
+ *
+ * Built from the calendar date and the ORIGINAL wall time, never from the day before it. Chaining
+ * `addDaysInZone` a day at a time carried a DST repair forward: 02:30 through a spring-forward
+ * Sunday became 03:30 there and stayed 03:30 on Monday, where 02:30 exists. `fromZoned` normalizes
+ * the day overflow, so `day + offset` is the whole walk.
+ */
+function localDay(origin: ZonedDateTime, offset: number, zone: TimeZone): Instant | null {
+  const candidate = fromZoned(
+    {
+      year: origin.year,
+      month: origin.month,
+      day: origin.day + offset,
+      hour: origin.hour,
+      minute: origin.minute,
+      second: origin.second,
+      millisecond: origin.millisecond,
+    },
+    zone,
+    { gap: 'next' },
+  );
+  const wanted = new Date(utcEpoch(origin.year, origin.month, origin.day + offset));
+  const got = toZoned(candidate, zone);
+  const exists =
+    got.year === wanted.getUTCFullYear() &&
+    got.month === wanted.getUTCMonth() + 1 &&
+    got.day === wanted.getUTCDate();
+  return exists ? candidate : null;
 }
 
 /** The next business day at the same local time; today if it already qualifies. */
@@ -97,13 +135,14 @@ export function businessDaysBetween(
   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.
+  // of iterations. Each one is a calendar DATE counted from `start`'s — not the instant a day after
+  // the previous one, which steps over a date the zone skipped and so reaches past `to`.
   const days = daysBetween(start, end, calendar.zone);
-  let cursor = start;
+  const origin = toZoned(start, calendar.zone);
   let count = 0;
   for (let index = 0; index < days; index += 1) {
-    if (isBusinessDay(cursor, calendar)) count += 1;
-    cursor = addDaysInZone(cursor, 1, calendar.zone);
+    const day = localDay(origin, index, calendar.zone);
+    if (day !== null && isBusinessDay(day, calendar)) count += 1;
   }
   // 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`.

package/src/context.ts

@@ -57,11 +57,12 @@ let config: TimeConfig = { defaultZone: UTC, order: DEFAULT_ORDER };
  * request, but a default nothing can fall back to is a boot-time mistake with no second answer.
  */
 export function configureTime(partial: Partial<TimeConfig>): TimeConfig {
-  const defaultZone =
-    partial.defaultZone === undefined ? undefined : assertTimeZone(partial.defaultZone);
+  // `defaultZone: undefined` means "not given" and must not be spread over the zone in force.
+  const { defaultZone: given, ...rest } = partial;
+  const defaultZone = given === undefined ? undefined : assertTimeZone(given);
   config = {
     ...config,
-    ...partial,
+    ...rest,
     ...(defaultZone === undefined ? {} : { defaultZone }),
   };
   return config;

package/src/cron-occurrence.ts

@@ -7,7 +7,7 @@ import { type CronExpression, matchesDay, parseCronOnce } from './cron-parse';
 import { cronInvalid } from './errors';
 import { fromEpochMs, type Instant } from './instant';
 import { fromZoned, toZoned } from './zoned';
-import { assertTimeZone, type TimeZone, utcEpoch } from './zones';
+import { assertTimeZone, offsetAt, type TimeZone, utcEpoch } from './zones';
 
 /** True when `at` matches the expression in `zone`, to the second. */
 export function matchesCron(
@@ -38,7 +38,15 @@ const MAX_STEPS = 200_000;
  * and converted with `fromZoned({ gap: 'next', overlap: 'first' })`:
  *  - spring forward: a 02:30 daily job runs once, at the first existing local time after
  *    the gap, instead of being silently skipped;
- *  - fall back: a repeated local time runs once, on its first occurrence.
+ *  - fall back, a FIXED time (`30 2 * * *`): the repeated local time runs once, on its first
+ *    occurrence — asked from anywhere, including from inside the repeated hour;
+ *  - fall back, an INTERVAL (every five minutes, `0 * * * *` — `CronExpression.wildcardTime`):
+ *    the repeated hour is real elapsed time and the schedule runs through both passes of it.
+ *
+ * The last two are Vixie cron's rule, and they are one rule about what the author named: a fixed
+ * time names a moment of the day, an interval names a rhythm. The wall clock alone could not say
+ * it — walking it forward from 02:55 reaches 03:00 and never sees 02:00 come round again, so
+ * every interval schedule went dark for one hour a year.
  */
 export function nextCronOccurrence(
   expression: string | CronExpression,
@@ -47,16 +55,77 @@ export function nextCronOccurrence(
 ): Instant {
   const cron = parseCronOnce(expression);
   assertTimeZone(zone);
+  const source = typeof expression === 'string' ? expression : cron.source;
 
   const start = toZoned(after, zone);
-  const cursor: Cursor = {
+  const first = walk(cron, zone, source, after, {
     year: start.year,
     month: start.month,
     day: start.day,
     hour: start.hour,
     minute: start.minute,
     second: start.second + 1,
-  };
+  });
+  if (!cron.wildcardTime) return first;
+
+  // The second pass of an overlap that begins AFTER `after`. Its wall times are behind the cursor
+  // the first walk started from, so that walk cannot have met them; they are met here, by walking
+  // again from the wall clock the transition lands on. Only a transition inside the overlap's own
+  // reach matters — past it, every repeated wall time has a first-pass instant that is itself
+  // after `after`, and the first walk already answered with something at or before it.
+  const horizon = Math.min(first.getTime(), after.getTime() + OVERLAP_REACH_MS);
+  const offsetBefore = offsetAt(zone, after);
+  if (offsetAt(zone, fromEpochMs(horizon)) >= offsetBefore) return first;
+  const landed = toZoned(fromEpochMs(fallBackAt(zone, after.getTime(), horizon)), zone);
+  const repeated = walk(
+    cron,
+    zone,
+    source,
+    after,
+    {
+      year: landed.year,
+      month: landed.month,
+      day: landed.day,
+      hour: landed.hour,
+      minute: landed.minute,
+      second: landed.second,
+    },
+    'second',
+  );
+  return repeated.getTime() < first.getTime() ? repeated : first;
+}
+
+/**
+ * How far ahead of `after` a fall-back can begin and still repeat a wall time `after` has already
+ * passed. A day and a bit: no zone's clock has ever been set back by more than a day.
+ */
+const OVERLAP_REACH_MS = 26 * 3_600_000;
+
+/** The first epoch ms in `(from, to]` whose offset is below `from`'s — found by bisection. */
+function fallBackAt(zone: TimeZone, from: number, to: number): number {
+  const before = offsetAt(zone, fromEpochMs(from));
+  let lo = from;
+  let hi = to;
+  while (hi - lo > 1) {
+    const mid = lo + Math.floor((hi - lo) / 2);
+    if (offsetAt(zone, fromEpochMs(mid)) < before) hi = mid;
+    else lo = mid;
+  }
+  return hi;
+}
+
+/**
+ * Walk the wall clock forward from `cursor` (inclusive) to the first matching wall time whose
+ * instant is after `after`. `overlap` is which pass a repeated wall time resolves to FIRST.
+ */
+function walk(
+  cron: CronExpression,
+  zone: TimeZone,
+  source: string,
+  after: Instant,
+  cursor: Cursor,
+  overlap: 'first' | 'second' = 'first',
+): Instant {
   carry(cursor);
 
   for (let step = 0; step < MAX_STEPS; step += 1) {
@@ -99,8 +168,14 @@ export function nextCronOccurrence(
       continue;
     }
 
-    const candidate = fromZoned({ ...cursor }, zone, { gap: 'next', overlap: 'first' });
+    const candidate = fromZoned({ ...cursor }, zone, { gap: 'next', overlap });
     if (candidate.getTime() > after.getTime()) return candidate;
+    // `after` is INSIDE the second pass of a repeated hour, so the first pass of this wall time is
+    // behind it. An interval schedule's next run is the second pass; a fixed time already ran.
+    if (cron.wildcardTime && overlap === 'first') {
+      const later = fromZoned({ ...cursor }, zone, { gap: 'next', overlap: 'second' });
+      if (later.getTime() > after.getTime()) return later;
+    }
     // The DST gap can push a candidate onto an instant we have already passed; step on.
     cursor.second += 1;
     carry(cursor);
@@ -110,7 +185,7 @@ export function nextCronOccurrence(
   // February — is refused by `parseCron` in constant time, because reaching it here cost ~150ms of
   // blocking CPU per call and `firedSince` pays that per tick of the scheduler's leader loop.
   throw cronInvalid(
-    typeof expression === 'string' ? expression : cron.source,
+    source,
     `no occurrence after ${MAX_STEPS} search steps — the date fields can never all match`,
   );
 }

package/src/cron-parse.ts

@@ -18,6 +18,11 @@ export interface CronExpression {
   /** Vixie semantics: when both day fields are restricted, either one matching is a hit. */
   dayOfMonthRestricted: boolean;
   dayOfWeekRestricted: boolean;
+  // The minute or the hour field is `*` or a stepped `*` — an INTERVAL, not a time of day. Vixie's
+  // test, and it decides one thing: whether the repeated hour of a fall-back night is run through
+  // (every five minutes) or fired once (02:30 daily). A fact about how the field was spelled,
+  // which the value lists cannot carry — `0-59` and `*` hold the same sixty numbers.
+  wildcardTime: boolean;
 }
 
 // A `Map`, not an object literal: the key is a caller's string, and `MACROS['constructor']` on a
@@ -50,6 +55,7 @@ const MONTH_NAMES = [
   'dec',
 ];
 const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const DAY_LABELS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
 
 /** Parse 5 fields (`m h dom mon dow`) or 6 with a leading seconds field. */
 export function parseCron(expression: string): CronExpression {
@@ -69,10 +75,10 @@ export function parseCron(expression: string): CronExpression {
   const minutes = parseField(expression, minuteField ?? '*', 0, 59);
   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 months = parseField(expression, monthField ?? '*', 1, 12, [MONTH_NAMES, MONTH_LABELS], 1);
   // 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);
+  const rawDow = parseField(expression, dowField ?? '*', 0, 7, [DAY_NAMES, DAY_LABELS], 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);
@@ -87,6 +93,7 @@ export function parseCron(expression: string): CronExpression {
     daysOfWeek,
     dayOfMonthRestricted: isRestricted(domField ?? '*'),
     dayOfWeekRestricted: isRestricted(dowField ?? '*'),
+    wildcardTime: isWildcard(minuteField ?? '*') || isWildcard(hourField ?? '*'),
   };
   assertReachableDate(expression, parsed);
   return parsed;
@@ -164,7 +171,7 @@ function parseField(
   field: string,
   min: number,
   max: number,
-  names: readonly string[] = [],
+  names: readonly (readonly string[])[] = [],
   nameOffset = 0,
   /**
    * How many distinct values one full turn of this field has — `max - min + 1` for every field
@@ -177,8 +184,11 @@ function parseField(
   const values = new Set<number>();
   for (const part of field.split(',')) {
     if (part === '') throw cronInvalid(expression, `empty list item in "${field}"`);
-    const [rangePart, stepPart] = part.split('/');
-    if (rangePart === undefined || (part.includes('/') && stepPart === undefined)) {
+    // Destructuring the split read the first two pieces and dropped the rest, so `1/2/3` was
+    // `1/2` and `1-5-7` was `1-5`: a typo that validated and scheduled something else.
+    const stepParts = part.split('/');
+    const [rangePart, stepPart] = stepParts;
+    if (rangePart === undefined || stepParts.length > 2) {
       throw cronInvalid(expression, `malformed step in "${part}"`);
     }
     const step = stepPart === undefined ? 1 : parseInteger(stepPart);
@@ -192,7 +202,11 @@ function parseField(
       from = min;
       to = max;
     } else if (rangePart.includes('-')) {
-      const [left, right] = rangePart.split('-');
+      const ends = rangePart.split('-');
+      if (ends.length !== 2) {
+        throw cronInvalid(expression, `a range has two ends, got ${ends.length} in "${part}"`);
+      }
+      const [left, right] = ends;
       from = toNumber(expression, left, min, max, names, nameOffset);
       to = toNumber(expression, right, min, max, names, nameOffset);
     } else {
@@ -221,13 +235,13 @@ function toNumber(
   token: string | undefined,
   min: number,
   max: number,
-  names: readonly string[],
+  names: readonly (readonly string[])[],
   nameOffset: number,
 ): number {
   if (token === undefined || token === '') throw cronInvalid(expression, 'missing value');
-  // Names match on their first three letters, so `mon` and `monday` both work — but a token
-  // carrying anything that is not a letter is a typo, not a name, and falls through to digits.
-  const named = /^[a-z]+$/.test(token) ? names.indexOf(token.slice(0, 3)) : -1;
+  // A name is its three-letter form or its whole word — `mon` and `monday` — matched EXACTLY.
+  // Matching on the first three letters read `marzipan` as March and `monkey` as Monday.
+  const named = names.reduce((found, list) => (found === -1 ? list.indexOf(token) : found), -1);
   const value = named === -1 ? parseInteger(token) : named + nameOffset;
   if (value === undefined) {
     throw cronInvalid(expression, `"${token}" is not a number or a name`);

package/src/duration.ts

@@ -152,7 +152,9 @@ export function formatDuration(
   // Screened once, here, rather than at each of the three `Intl` constructions below — and before
   // any of them, so a malformed tag is one refusal and never a partially built string.
   const tag = assertLocale(locale);
-  let remaining = Math.abs(Math.round(ms));
+  // `NaN` rendered as "NaN days, NaN hr" — every `Math.floor` below propagates it and `Intl`
+  // formats it. `finiteOption`, as `toMs`: a duration is legitimately negative and fractional.
+  let remaining = Math.abs(Math.round(finiteOption('formatDuration', 'ms', ms)));
   const pieces: string[] = [];
 
   for (const [unit, scale] of FORMAT_UNITS) {
@@ -179,7 +181,9 @@ export function formatDuration(
 
 /** `PT2H30M` — for OpenAPI schemas and cron metadata. */
 export function formatDurationIso(ms: number): string {
-  const total = Math.abs(Math.round(ms));
+  // Screened for the reason `formatDuration` is: `NaN` fails every `> 0` below and came out as
+  // `P0D`, a well-formed zero for a duration nobody computed.
+  const total = Math.abs(Math.round(finiteOption('formatDurationIso', 'ms', ms)));
   const days = Math.floor(total / DAY);
   const hours = Math.floor((total % DAY) / HOUR);
   const minutes = Math.floor((total % HOUR) / MINUTE);

package/src/errors.ts

@@ -69,10 +69,12 @@ export function scheduleInvalid(field: string, value: unknown, range: string): T
  * abbreviations left an operator holding `"Japan"` reading advice about `CET`. A legacy single-label
  * link has a mechanical replacement; an abbreviation has none, and saying so IS the instruction.
  */
-export function timezoneInvalid(zone: string): TimeError {
+export function timezoneInvalid(zone: unknown): TimeError {
   return new TimeError({
     code: 'X_TIMEZONE_INVALID',
-    cause: `"${zone}" is not an IANA Area/Location zone name`,
+    // `unknown`, because the refusal is reached by exactly the callers the `string` type did not
+    // stop — an omitted `zone` is `undefined` here. A string keeps its quoted spelling.
+    cause: `${typeof zone === 'string' ? `"${zone}"` : renderCauseValue(zone)} is not an IANA Area/Location zone name`,
     fix: "use Area/Location, or UTC. A single-label legacy name swaps mechanically — Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC. An abbreviation or a numeric offset does not: CET and EST5EDT name no jurisdiction and carry no DST rule, so name the city whose clock you mean (Europe/Paris, America/New_York). Every accepted name: Intl.supportedValuesOf('timeZone')",
   });
 }

package/src/format.ts

@@ -6,7 +6,7 @@
 
 import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
-import { isoDateInZone } from './zoned';
+import { daysBetween, isoDateInZone } from './zoned';
 import { assertTimeZone, type TimeZone } from './zones';
 
 export type DateTimeStyle = 'short' | 'medium' | 'long' | 'full';
@@ -27,9 +27,10 @@ export interface FormatDateTimeOptions extends FormatContext {
 
 /** `14 Mar 2026, 09:00` in `en-GB` / `Europe/Berlin`. */
 export function formatDateTime(at: Instant, options: FormatDateTimeOptions): string {
+  const zone = zoneOf(options);
   const style = options.style ?? 'medium';
   return formatterFor(options.locale, {
-    timeZone: assertTimeZone(options.zone),
+    timeZone: zone,
     dateStyle: options.dateStyle ?? style,
     timeStyle: options.timeStyle ?? (style === 'full' || style === 'long' ? 'medium' : style),
     ...(options.hour12 === undefined ? {} : { hour12: options.hour12 }),
@@ -40,8 +41,9 @@ export function formatDate(
   at: Instant,
   options: FormatContext & { style?: DateTimeStyle },
 ): string {
+  const zone = zoneOf(options);
   return formatterFor(options.locale, {
-    timeZone: assertTimeZone(options.zone),
+    timeZone: zone,
     dateStyle: options.style ?? 'medium',
   }).format(at);
 }
@@ -50,8 +52,9 @@ export function formatTime(
   at: Instant,
   options: FormatContext & { style?: DateTimeStyle; hour12?: boolean },
 ): string {
+  const zone = zoneOf(options);
   return formatterFor(options.locale, {
-    timeZone: assertTimeZone(options.zone),
+    timeZone: zone,
     timeStyle: options.style ?? 'short',
     ...(options.hour12 === undefined ? {} : { hour12: options.hour12 }),
   }).format(at);
@@ -63,11 +66,12 @@ export function formatTime(
  * in a fixed position instead of wherever the locale pattern happens to put it.
  */
 export function formatWithOffset(at: Instant, options: FormatDateTimeOptions): string {
+  const zone = zoneOf(options);
   const style = options.style ?? 'medium';
   // `timeZoneName` is a component option, and Intl forbids mixing those with dateStyle /
   // timeStyle — so the components are spelled out here instead.
   const parts = formatterFor(options.locale, {
-    timeZone: assertTimeZone(options.zone),
+    timeZone: zone,
     year: 'numeric',
     month: style === 'short' ? 'numeric' : style === 'medium' ? 'short' : 'long',
     day: 'numeric',
@@ -100,44 +104,66 @@ export function formatIsoDate(at: Instant, zone: TimeZone): string {
   return isoDateInZone(at, assertTimeZone(zone));
 }
 
-export interface FormatRelativeOptions extends Omit<FormatContext, 'zone'> {
+export interface FormatRelativeOptions extends FormatContext {
   /** The reference point. Pass `now(clock)` — never let this default to a live clock. */
   now: Instant;
   numeric?: 'always' | 'auto';
   style?: 'long' | 'short' | 'narrow';
 }
 
-const RELATIVE_UNITS: readonly [Intl.RelativeTimeFormatUnit, number][] = [
-  ['year', 31_536_000_000],
-  ['month', 2_592_000_000],
-  ['week', 604_800_000],
-  ['day', 86_400_000],
+const DAY_MS = 86_400_000;
+
+/** Under a day apart: elapsed time, largest unit first. */
+const CLOCK_UNITS: readonly [Intl.RelativeTimeFormatUnit, number][] = [
   ['hour', 3_600_000],
   ['minute', 60_000],
   ['second', 1000],
 ];
 
-/** `in 3 days` / `2 hours ago`, picking the largest unit that fits. */
+/** A day or more apart: calendar days in the zone, largest unit first. */
+const CALENDAR_UNITS: readonly [Intl.RelativeTimeFormatUnit, number][] = [
+  ['year', 365],
+  ['month', 30],
+  ['week', 7],
+  ['day', 1],
+];
+
+/**
+ * `in 3 days` / `2 hours ago`, picking the largest unit that fits.
+ *
+ * From a day apart, the number is CALENDAR days in `zone` — local midnights crossed, the count
+ * `daysBetween` gives — never elapsed milliseconds truncated. "Tomorrow" is a statement about the
+ * calendar: 47 hours ahead is two midnights away, and `trunc(47 / 24)` called it tomorrow. That is
+ * why this takes a zone like every other formatter here; which day an instant falls on has no
+ * answer without one.
+ */
 export function formatRelative(at: Instant, options: FormatRelativeOptions): string {
+  const zone = zoneOf(options);
   const delta = differenceMs(options.now, at);
   const formatter = new Intl.RelativeTimeFormat(assertLocale(options.locale), {
     numeric: options.numeric ?? 'auto',
     style: options.style ?? 'long',
   });
   const magnitude = Math.abs(delta);
-  for (const [unit, ms] of RELATIVE_UNITS) {
-    if (magnitude >= ms) {
-      return formatter.format(Math.trunc(delta / ms), unit);
-    }
+  // `days === 0` a full day apart is 24 real hours inside one 25-hour local day: no midnight was
+  // crossed, so it is hours — "today" would be the calendar's answer to a question about elapsed
+  // time.
+  const days = magnitude >= DAY_MS ? daysBetween(options.now, at, zone) : 0;
+  for (const [unit, size] of CALENDAR_UNITS) {
+    if (Math.abs(days) >= size) return formatter.format(Math.trunc(days / size), unit);
+  }
+  for (const [unit, ms] of CLOCK_UNITS) {
+    if (magnitude >= ms) return formatter.format(Math.trunc(delta / ms), unit);
   }
   return formatter.format(0, 'second');
 }
 
 /** `14–16 Mar 2026` — one call, so the locale decides how to collapse the range. */
 export function formatRange(from: Instant, to: Instant, options: FormatDateTimeOptions): string {
+  const zone = zoneOf(options);
   const style = options.style ?? 'medium';
   const formatter = formatterFor(options.locale, {
-    timeZone: assertTimeZone(options.zone),
+    timeZone: zone,
     dateStyle: options.dateStyle ?? style,
     ...(options.timeStyle === undefined ? {} : { timeStyle: options.timeStyle }),
   }) as Intl.DateTimeFormat & {
@@ -173,6 +199,16 @@ export function ordinal(value: number): string {
   return `${value}${ORDINAL_SUFFIX[category]}`;
 }
 
+/**
+ * The options' zone, canonical — read FIRST in every formatter, and through `?.`: a call from
+ * untyped code with the options object missing is the same mistake as one with `zone` missing, and
+ * both are `X_TIMEZONE_INVALID` rather than a bare `TypeError` on the first property read.
+ */
+function zoneOf(options: { readonly zone: TimeZone }): TimeZone {
+  const loose: { readonly zone?: unknown } | null | undefined = options;
+  return assertTimeZone(loose?.zone as TimeZone);
+}
+
 const cache = new Map<string, Intl.DateTimeFormat>();
 
 /**

package/src/index.ts

@@ -138,6 +138,7 @@ export {
   fromZonedDetailed,
   type GapPolicy,
   isoDateInZone,
+  isoInZone,
   isSameLocalDay,
   type OverlapPolicy,
   startOfDay,

package/src/plain-date.ts

@@ -91,10 +91,20 @@ export function plainDateParts(date: PlainDate): PlainDateParts {
 /**
  * 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.
+ * still the 13th in Los Angeles. A local date outside years 0000-9999 is refused, as `plainDateUtc`
+ * refuses one.
  */
-export const plainDateIn = (at: Instant, zone: TimeZone): PlainDate =>
-  isoDateInZone(at, zone) as PlainDate;
+export function plainDateIn(at: Instant, zone: TimeZone): PlainDate {
+  const local = isoDateInZone(at, zone);
+  // Checked, not cast: an instant late on 9999-12-31 is already year 10000 east of Greenwich, and
+  // `isoDateInZone` spells that with five digits — a string `isPlainDate` rejects. `isoDateInZone`
+  // itself stays total: it returns a plain string, and `isSameLocalDay` compares two of them for
+  // instants in any year a `Date` can hold.
+  if (!isPlainDate(local)) {
+    throw scheduleInvalid('date', local, 'a calendar date in years 0000-9999');
+  }
+  return local;
+}
 
 /**
  * The calendar date a `Date` holds when read as UTC. For ONE caller: a Postgres driver hands a
@@ -104,7 +114,14 @@ export const plainDateIn = (at: Instant, zone: TimeZone): PlainDate =>
  */
 export function plainDateUtc(at: Date): PlainDate {
   const checked = instant(at);
-  return `${pad(checked.getUTCFullYear(), 4)}-${pad(checked.getUTCMonth() + 1, 2)}-${pad(
+  const year = checked.getUTCFullYear();
+  // The form has four year digits and no sign. A `Date` reaches 275760 and -271821, and padding
+  // those gave `10000-01-01` branded `PlainDate` — a value `isPlainDate` rejects and a Postgres
+  // `date` parameter reads as something else. Refused, so the brand is never a lie.
+  if (year < 0 || year > 9999) {
+    throw scheduleInvalid('date', checked.toISOString(), 'a calendar date in years 0000-9999');
+  }
+  return `${pad(year, 4)}-${pad(checked.getUTCMonth() + 1, 2)}-${pad(
     checked.getUTCDate(),
     2,
   )}` as PlainDate;
@@ -120,7 +137,10 @@ export const comparePlainDates = (left: PlainDate, right: PlainDate): number =>
 
 const DAY_MS = 86_400_000;
 
-/** Whole days added, over UTC midnights, so no DST rule and no zone can shorten a day here. */
+/**
+ * Whole days added, over UTC midnights, so no DST rule and no zone can shorten a day here. A
+ * result outside years 0000-9999 is refused by `plainDateUtc` rather than branded.
+ */
 export function addPlainDays(date: PlainDate, days: number): PlainDate {
   if (!Number.isSafeInteger(days)) {
     throw scheduleInvalid('days', days, 'a whole number of days');

package/src/zone-canonical.ts

@@ -37,6 +37,11 @@ const probed = new Map<string, string | ''>();
  * `'CET'` and `'+01:00'` are not zones: an abbreviation is ambiguous and an offset has no rules.
  */
 export function canonicalTimeZone(zone: string): string | undefined {
+  // The type says `string`; a plain-JS caller, a JSON-driven call and an `as never` do not. Every
+  // zoned function in the package funnels through here, so this is the one place a non-string
+  // becomes "not a zone" — and so `X_TIMEZONE_INVALID` — rather than a bare `TypeError` out of
+  // `zone.toLowerCase()` several frames from the call that omitted it.
+  if (typeof zone !== 'string') return undefined;
   if (zone === '' || NUMERIC_OFFSET.test(zone)) return undefined;
   const known = listedZones().get(zone.toLowerCase());
   if (known !== undefined) return known;

package/src/zoned.ts

@@ -3,9 +3,16 @@
  * instant. `fromZoned` is the DST-correct one, and it is the reason this package exists.
  */
 
-import { dstAmbiguous, dstNonexistent } from './errors';
+import { dstAmbiguous, dstNonexistent, scheduleInvalid } from './errors';
 import { addMs, type Instant } from './instant';
-import { assertTimeZone, offsetAt, type TimeZone, utcEpoch, zonePartsAt } from './zones';
+import {
+  assertTimeZone,
+  offsetAt,
+  offsetLabel,
+  type TimeZone,
+  utcEpoch,
+  zonePartsAt,
+} from './zones';
 
 /** A local date and time with no zone attached — meaningless until paired with one. */
 export interface WallClock {
@@ -168,8 +175,15 @@ export function endOfDay(at: Instant, zone: TimeZone): Instant {
 /**
  * Add calendar days in a zone, keeping the wall-clock time. Adding one day is 23, 24 or
  * 25 hours depending on the transition — which is why this is not `+ 86_400_000`.
+ *
+ * A WHOLE number of days, checked as `addPlainDays` and `addBusinessDays` check theirs: `NaN`
+ * reached `Date.UTC` and came back out of `Intl` as a bare `RangeError`, and `0.5` was truncated
+ * there and moved nothing — a silent no-op that reads as an answer.
  */
 export function addDaysInZone(at: Instant, days: number, zone: TimeZone): Instant {
+  if (!Number.isSafeInteger(days)) {
+    throw scheduleInvalid('days', days, 'a whole number of days');
+  }
   const zoned = toZoned(at, zone);
   return fromZoned(
     {
@@ -192,6 +206,19 @@ export function isoDateInZone(at: Instant, zone: TimeZone): string {
   return `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
 }
 
+/**
+ * `2026-03-08T03:00:00-04:00` — ISO-8601 with the ZONE's OWN offset, never collapsed to UTC `Z`
+ * (which is what `toIso` is for). The form a schedule is read in: the two passes of a fall-back
+ * hour are one wall time and two instants, and the offset is the only thing that tells them
+ * apart. Seconds precision; `fromIso` reads it back to the same second.
+ */
+export function isoInZone(at: Instant, zone: TimeZone): string {
+  const zoned = toZoned(at, zone);
+  const date = `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
+  const time = `${pad2(zoned.hour)}:${pad2(zoned.minute)}:${pad2(zoned.second)}`;
+  return `${date}T${time}${offsetLabel(zoned.offsetMinutes)}`;
+}
+
 /** True when both instants fall on the same local calendar day. */
 export function isSameLocalDay(left: Instant, right: Instant, zone: TimeZone): boolean {
   return isoDateInZone(left, zone) === isoDateInZone(right, zone);