@ultimat3/time 30.8.0 → 31.0.0

package/CLAUDE.md

@@ -19,6 +19,8 @@
 | `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 |
+| `business-span.ts` | business-day arithmetic on epoch days: weekday by `mod 7`, whole weeks multiplied, holidays binary-searched — no zone, no `Intl` |
+| `zone-skipped-days.ts` | `localDayAt` and `skippedDays` — the dates a zone never had at a wall time, found by sampling offsets |
 | `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 |
 | `plain-date-range.ts` | `plainDateRange` — the bounded, frozen list of dates between two `PlainDate`s |
@@ -160,9 +162,20 @@
   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
+  stayed 03:30 on Monday. `businessDaysBetween` reads the same dates (`localDayAt`): 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.
+- **Business days are counted arithmetically, never walked, `As of 2026-11`.** The walk asked
+  `Intl` 2–3 times per DAY: 30 years of `businessDaysBetween` was ~830 ms, `addBusinessDays(…, 5000)`
+  ~500 ms. Now whole weeks multiply (`business-span.ts`), holidays are a sorted binary search, and
+  `Intl` is asked only for offset samples (`zone-skipped-days.ts`, one per 28 days) plus the dates
+  near a transition that could remove one. The 28-day stride rests on a MEASUREMENT (every zone,
+  1900–2050): transitions under 28 days apart are all 1-hour shifts, which move a date only for a
+  wall time from 23:00 — where the stride drops to 6 days (closest pair: 7.0). After a tzdata
+  change that adds a short-lived rule, re-measure: sample every zone's offset twice a day and list
+  consecutive transitions under 28 days apart.
+  `business-linear.test.ts` keeps the old walk as the ORACLE over random zones, walls, weekends and
+  holidays; never delete it to make a change pass.
 - **`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.**
@@ -217,6 +230,6 @@
 ## Commands
 
 ```
-bun test packages/time
+bun test ./packages/time/
 bun run --filter @ultimat3/time typecheck
 ```

package/README.md

@@ -30,7 +30,7 @@ answers the canonical spelling (or `undefined`), and `assertTimeZone` / `resolve
 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.
 
-**The request's zone, in order:** `user`, `cookie` (a picker's `x_timezone`), `query` (`?tz=`),
+**The request's zone, in order:** `user`, `cookie` (`TIMEZONE_COOKIE`, a picker's `x_timezone`), `query` (`?tz=`),
 `header` (`x-timezone`), `detected` (`TIMEZONE_DETECTED_COOKIE`, `x_timezone_detected`), then the
 `configureTime` default. `detected` is what `@ultimat3/render`'s `zoneScript` writes on `app/`
 documents under `time: { detect: true }`: a guess, below everything chosen, never written over it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "30.8.0",
+  "version": "31.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "keywords": [
     "ultimate",
@@ -46,7 +46,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.8.0",
-    "@ultimat3/schema": "30.8.0"
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/schema": "31.0.0"
   }
 }

package/src/business-span.ts

@@ -0,0 +1,115 @@
+// Single responsibility: business-day arithmetic on CALENDAR DAYS — epoch day numbers, no zone and
+// no `Intl`. A weekday is `day mod 7`, a run of whole weeks is multiplication, and a holiday is a
+// sorted number searched in O(log n): what lets a 30-year span cost what a week did.
+
+import { holidaySet } from './holidays';
+
+export const DAY_MS = 86_400_000;
+
+/** 1970-01-01, epoch day 0, was a Thursday: ISO weekday 4. */
+const EPOCH_WEEKDAY = 4;
+
+/** ISO weekday (1 = Monday … 7 = Sunday) of an epoch day, for any sign. */
+export function weekdayOfDay(day: number): number {
+  return ((((day + EPOCH_WEEKDAY - 1) % 7) + 7) % 7) + 1;
+}
+
+/** The epoch day a UTC midnight epoch names. */
+export function dayOfEpoch(epochMs: number): number {
+  return Math.round(epochMs / DAY_MS);
+}
+
+/**
+ * `isWorkday[weekday]` for ISO weekdays 1–7, from the weekend list exactly as `includes` reads it:
+ * a stray entry (`0`, `8`) matches no weekday, as it never did.
+ */
+export function workdayTable(weekend: readonly number[]): readonly boolean[] {
+  const table = [false];
+  for (let weekday = 1; weekday <= 7; weekday += 1) table.push(!weekend.includes(weekday));
+  return table;
+}
+
+/** Workdays among the epoch days `[from, to)`: whole weeks multiplied, the remainder walked. */
+export function workdaysIn(from: number, to: number, isWorkday: readonly boolean[]): number {
+  if (to <= from) return 0;
+  const perWeek = isWorkday.filter(Boolean).length;
+  const weeks = Math.floor((to - from) / 7);
+  let count = weeks * perWeek;
+  for (let day = from + weeks * 7; day < to; day += 1) {
+    if (isWorkday[weekdayOfDay(day)]) count += 1;
+  }
+  return count;
+}
+
+/**
+ * The distance `t >= 1` from `origin` (in `step`'s direction) of its `k`th workday, `k >= 1`.
+ * The table holds at least one workday — the caller refused an all-weekend calendar first.
+ */
+export function nthWorkday(
+  origin: number,
+  k: number,
+  step: 1 | -1,
+  isWorkday: readonly boolean[],
+): number {
+  const perWeek = isWorkday.filter(Boolean).length;
+  const weeks = Math.floor((k - 1) / perWeek);
+  let remaining = k - weeks * perWeek;
+  let distance = weeks * 7;
+  while (remaining > 0) {
+    distance += 1;
+    if (isWorkday[weekdayOfDay(origin + step * distance)]) remaining -= 1;
+  }
+  return distance;
+}
+
+/** `isoDateInZone`'s spelling of an epoch day: the form a calendar's holidays are written in. */
+export function isoOfDay(day: number): string {
+  const at = new Date(day * DAY_MS);
+  const pad2 = (value: number): string => String(value).padStart(2, '0');
+  return `${String(at.getUTCFullYear()).padStart(4, '0')}-${pad2(at.getUTCMonth() + 1)}-${pad2(at.getUTCDate())}`;
+}
+
+const ISO_DAY = /^(\d{4,})-(\d{2})-(\d{2})$/;
+
+/** Holiday epoch days, sorted, per holiday SET — `holidaySet` returns one set per list. */
+const holidayDayMemo = new WeakMap<ReadonlySet<string>, readonly number[]>();
+
+/**
+ * A calendar's holidays as sorted epoch days. A string is kept only when it round-trips through
+ * `isoOfDay` — exactly the strings the per-day walk could ever have matched, so `2026-02-30` and
+ * `2026-3-1` stay the no-ops they always were rather than rolling onto a real day.
+ */
+export function holidayDays(holidays: readonly string[] | undefined): readonly number[] {
+  const set = holidaySet(holidays);
+  const hit = holidayDayMemo.get(set);
+  if (hit !== undefined) return hit;
+  const days: number[] = [];
+  for (const iso of set) {
+    const match = typeof iso === 'string' ? ISO_DAY.exec(iso) : null;
+    if (match === null) continue;
+    const at = new Date(0);
+    at.setUTCFullYear(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+    const day = dayOfEpoch(at.getTime());
+    if (isoOfDay(day) === iso) days.push(day);
+  }
+  days.sort((left, right) => left - right);
+  holidayDayMemo.set(set, days);
+  return days;
+}
+
+/** The first index in a sorted list whose value is `>= value`. */
+function lowerBound(sorted: readonly number[], value: number): number {
+  let low = 0;
+  let high = sorted.length;
+  while (low < high) {
+    const mid = (low + high) >>> 1;
+    if ((sorted[mid] ?? 0) < value) low = mid + 1;
+    else high = mid;
+  }
+  return low;
+}
+
+/** How many values of a sorted list lie in `[from, to)`. */
+export function countIn(sorted: readonly number[], from: number, to: number): number {
+  return to <= from ? 0 : lowerBound(sorted, to) - lowerBound(sorted, from);
+}

package/src/business.ts

@@ -3,10 +3,20 @@
  * much of the Gulf, Sunday-only in parts of Asia, Saturday/Sunday in the West.
  */
 
+import {
+  countIn,
+  dayOfEpoch,
+  holidayDays,
+  nthWorkday,
+  weekdayOfDay,
+  workdaysIn,
+  workdayTable,
+} from './business-span';
 import { scheduleInvalid, type TimeError } from './errors';
 import { holidaySet } from './holidays';
 import type { Instant } from './instant';
-import { daysBetween, fromZoned, isoDateInZone, toZoned, type ZonedDateTime } from './zoned';
+import { localDayAt, skippedDays } from './zone-skipped-days';
+import { daysBetween, isoDateInZone, toZoned, type ZonedDateTime } from './zoned';
 import { type TimeZone, utcEpoch } from './zones';
 
 /** ISO weekday numbers: 1 = Monday … 7 = Sunday. */
@@ -64,28 +74,55 @@ export function addBusinessDays(at: Instant, days: number, calendar: BusinessCal
     throw noBusinessDay(calendar);
   }
   const step = days > 0 ? 1 : -1;
-  const origin = toZoned(at, calendar.zone);
-  let remaining = Math.abs(days);
-  let offset = 0;
-  let guard = 0;
-  let landed = at;
-
-  while (remaining > 0) {
-    offset += step;
-    const candidate = localDay(origin, offset, calendar.zone);
-    if (candidate !== null && isBusinessDay(candidate, calendar)) {
-      remaining -= 1;
-      landed = candidate;
+  const wanted = Math.abs(days);
+  const zoned = toZoned(at, calendar.zone);
+  const origin = epochDayOf(zoned);
+  const isWorkday = workdayTable(weekend);
+  const holidays = holidayDays(calendar.holidays).filter((day) => isWorkday[weekdayOfDay(day)]);
+  // Ten years past the last day a full week could need without one business day: the calendar has
+  // none to give. The guard used to RETURN the day it stopped on, a weekend or a holiday — which a
+  // caller schedules against as if it were the business day it asked for.
+  const guard = wanted * 7 + 3650;
+  // Workdays the zone never had at this wall time, gathered as the span grows: `[1, scanned]` days out.
+  const skipped: number[] = [];
+  let scanned = 0;
+  // The smallest distance with `wanted` business days in `(origin, origin + distance]`: start at
+  // the `wanted`th workday and move to the `(wanted + excluded)`th until the excluded count stops
+  // growing — each step stays at or below the answer, so the fixed point IS the answer.
+  let distance = nthWorkday(origin, wanted, step, isWorkday);
+  for (;;) {
+    if (distance > guard) throw noBusinessDay(calendar);
+    if (distance > scanned) {
+      const [low, high] = span(origin, scanned + 1, distance + 1, step);
+      for (const day of skippedDays(calendar.zone, zoned, low, high)) {
+        if (isWorkday[weekdayOfDay(day)] && countIn(holidays, day, day + 1) === 0)
+          skipped.push(day);
+      }
+      skipped.sort((left, right) => left - right);
+      scanned = distance;
     }
-    guard += 1;
-    // Ten years past the last day a full week could need without one business day: the calendar has
-    // none to give. It used to RETURN here — the day the guard stopped on, a weekend or a holiday —
-    // which a caller schedules against as if it were the business day it asked for.
-    if (guard > Math.abs(days) * 7 + 3650) throw noBusinessDay(calendar);
+    const [low, high] = span(origin, 1, distance + 1, step);
+    const excluded = countIn(holidays, low, high) + countIn(skipped, low, high);
+    const next = nthWorkday(origin, wanted + excluded, step, isWorkday);
+    if (next === distance) break;
+    distance = next;
   }
+  const landed = localDayAt(origin + step * distance, zoned, calendar.zone);
+  // `skippedDays` found every date this zone lacks; a `null` here is a tzdata it was not measured on.
+  if (landed === null) throw noBusinessDay(calendar);
   return landed;
 }
 
+/** The epoch days `[low, high)` that distances `[near, far)` from `origin` cover, in `step`'s direction. */
+function span(origin: number, near: number, far: number, step: 1 | -1): [number, number] {
+  return step === 1 ? [origin + near, origin + far] : [origin - far + 1, origin - near + 1];
+}
+
+/** The local calendar date of a zoned value, as an epoch day. */
+function epochDayOf(zoned: ZonedDateTime): number {
+  return dayOfEpoch(utcEpoch(zoned.year, zoned.month, zoned.day));
+}
+
 /**
  * The refusal for a calendar the loop above can never land in. Which list is at fault decides the
  * repair: a weekend covering all seven days, or — the weekend leaving days — holidays covering them.
@@ -106,38 +143,6 @@ function noBusinessDay(calendar: BusinessCalendar): TimeError {
   );
 }
 
-/**
- * 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. */
 export function nextBusinessDay(at: Instant, calendar: BusinessCalendar): Instant {
   return isBusinessDay(at, calendar) ? at : addBusinessDays(at, 1, calendar);
@@ -167,11 +172,17 @@ export function businessDaysBetween(
   // 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);
-  const origin = toZoned(start, calendar.zone);
-  let count = 0;
-  for (let index = 0; index < days; index += 1) {
-    const day = localDay(origin, index, calendar.zone);
-    if (day !== null && isBusinessDay(day, calendar)) count += 1;
+  const zoned = toZoned(start, calendar.zone);
+  const first = epochDayOf(zoned);
+  const last = first + days;
+  const weekend = calendar.weekendDays ?? WEEKEND_SAT_SUN;
+  const isWorkday = workdayTable(weekend);
+  // Whole weeks multiplied, holidays subtracted by binary search, and only the dates the zone
+  // never had at this wall time asked of `Intl` — it was every date, two to three calls each.
+  const holidays = holidayDays(calendar.holidays).filter((day) => isWorkday[weekdayOfDay(day)]);
+  let count = workdaysIn(first, last, isWorkday) - countIn(holidays, first, last);
+  for (const day of skippedDays(calendar.zone, zoned, first, last)) {
+    if (isWorkday[weekdayOfDay(day)] && countIn(holidays, day, day + 1) === 0) 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

@@ -11,6 +11,12 @@ import { assertTimeZone, type TimeZone, UTC } from './zones';
 /** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
 export const TIMEZONE_HEADER = 'x-timezone';
 
+/**
+ * Cookie a zone picker writes: the visitor's CHOICE, ranked above the header. Published so the
+ * picker and `@ultimat3/http`'s default reader name one constant — each spelled its own literal.
+ */
+export const TIMEZONE_COOKIE = 'x_timezone';
+
 /**
  * Cookie `@ultimat3/render`'s zone script writes from the same `Intl` call, on `app/` documents: a
  * document navigation sends no header, so without it a new visitor's first pages render in UTC.

package/src/format.ts

@@ -140,10 +140,11 @@ const CALENDAR_UNITS: readonly [Intl.RelativeTimeFormatUnit, number][] = [
 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 formatter = relativeFormatterFor(
+    options.locale,
+    options.numeric ?? 'auto',
+    options.style ?? 'long',
+  );
   const magnitude = Math.abs(delta);
   // `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
@@ -158,6 +159,25 @@ export function formatRelative(at: Instant, options: FormatRelativeOptions): str
   return formatter.format(0, 'second');
 }
 
+const relativeCache = new Map<string, Intl.RelativeTimeFormat>();
+
+/**
+ * `formatterFor`'s rule for the relative formatter: one per canonical locale and options, through
+ * core's bounded cache. Built per call it was most of what a 10k-row activity feed cost to render.
+ */
+function relativeFormatterFor(
+  locale: string,
+  numeric: 'always' | 'auto',
+  style: 'long' | 'short' | 'narrow',
+): Intl.RelativeTimeFormat {
+  const tag = assertLocale(locale);
+  return cachedFormatter(
+    relativeCache,
+    `${tag}|${numeric}|${style}`,
+    () => new Intl.RelativeTimeFormat(tag, { numeric, style }),
+  );
+}
+
 /** `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);
@@ -174,6 +194,9 @@ export function formatRange(from: Instant, to: Instant, options: FormatDateTimeO
   return `${formatter.format(from)} – ${formatter.format(to)}`;
 }
 
+/** One English ordinal rule set for the process: it takes no locale, so it has no key. */
+let ordinalRules: Intl.PluralRules | undefined;
+
 const ORDINAL_SUFFIX: Record<Intl.LDMLPluralRule, string> = {
   one: 'st',
   two: 'nd',
@@ -195,7 +218,8 @@ const ORDINAL_SUFFIX: Record<Intl.LDMLPluralRule, string> = {
  * rendered page. **Breaking: the `locale` parameter is gone.**
  */
 export function ordinal(value: number): string {
-  const category = new Intl.PluralRules('en', { type: 'ordinal' }).select(value);
+  ordinalRules ??= new Intl.PluralRules('en', { type: 'ordinal' });
+  const category = ordinalRules.select(value);
   return `${value}${ORDINAL_SUFFIX[category]}`;
 }
 

package/src/index.ts

@@ -10,7 +10,6 @@ export {
   type IsoWeekday,
   isBusinessDay,
   isHoliday,
-  isWeekend,
   nextBusinessDay,
   WEEKEND_FRI_SAT,
   WEEKEND_SAT_SUN,
@@ -20,6 +19,7 @@ export {
   configureTime,
   currentTimeZone,
   resolveTimeZone,
+  TIMEZONE_COOKIE,
   TIMEZONE_DETECTED_COOKIE,
   TIMEZONE_HEADER,
   type TimeConfig,
@@ -32,7 +32,6 @@ export {
   type CronExpression,
   type CronPhrases,
   describeCron,
-  firedSince,
   isValidCron,
   matchesCron,
   nextCronOccurrence,
@@ -52,20 +51,11 @@ export {
   SECOND,
   toMs,
   toSeconds,
-  WEEK,
 } from './duration';
 export {
-  cronInvalid,
-  cronNotDescribable,
-  dstAmbiguous,
-  dstNonexistent,
-  durationInvalid,
-  instantInvalid,
   TIME_ERROR_CODES,
-  TIME_ERROR_TITLES,
   TimeError,
   type TimeErrorCode,
-  timezoneInvalid,
 } from './errors';
 export {
   type DateTimeStyle,
@@ -74,7 +64,6 @@ export {
   type FormatRelativeOptions,
   formatDate,
   formatDateTime,
-  formatIsoDate,
   formatRange,
   formatRelative,
   formatTime,
@@ -83,22 +72,15 @@ export {
 } from './format';
 export {
   addMs,
-  compareInstants,
   differenceMs,
   epoch,
   fromEpochMs,
-  fromEpochSeconds,
   fromIso,
   type Instant,
   instant,
-  isAfter,
-  isBefore,
-  isInstant,
   now,
-  subtractMs,
   toEpochMs,
   toIso,
-  toIsoDateUtc,
 } from './instant';
 export { addMonthsInZone, addPlainMonths } from './months';
 export {
@@ -124,9 +106,6 @@ export {
 export {
   type LocalSlot,
   nextLocalSlot,
-  nextLocalSlots,
-  nextWeeklySlot,
-  type WeeklySlot,
 } from './schedule';
 /**
  * `canonicalTimeZone` is public because a zone arriving from a request header has to become one
@@ -157,7 +136,6 @@ export {
   isValidTimeZone,
   observesDst,
   offsetAt,
-  offsetLabel,
   type TimeZone,
   UTC,
   type ZoneParts,

package/src/zone-skipped-days.ts

@@ -0,0 +1,113 @@
+// Single responsibility: which local calendar dates a zone never had at a given wall time — Samoa's
+// 2011-12-30, or a late-evening gap that pushes the clock past midnight — found by sampling the
+// zone's offset, not by asking `Intl` about every day. Each candidate is still settled by `localDayAt`.
+
+import type { Instant } from './instant';
+import { fromZoned, toZoned } from './zoned';
+import { offsetSecondsAt, type TimeZone } from './zones';
+
+const DAY_MS = 86_400_000;
+const HOUR_MS = 3_600_000;
+
+/** A wall time of day: the part of the origin every candidate date keeps. */
+export interface WallTime {
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+  readonly millisecond: number;
+}
+
+/**
+ * The instant `day` (an epoch day) names at `wall` in `zone`, or `null` when the zone never had
+ * that date at that time. Built from the calendar date and the ORIGINAL wall time, never from the
+ * day before it: chaining a day at a time carried a DST repair (02:30 → 03:30) onto every later day.
+ * `{ gap: 'next' }` moves a skipped wall time forward; when that lands on another date, this date
+ * did not happen at this time.
+ */
+export function localDayAt(day: number, wall: WallTime, zone: TimeZone): Instant | null {
+  const date = new Date(day * DAY_MS);
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth() + 1;
+  const dayOfMonth = date.getUTCDate();
+  const { hour, minute, second, millisecond } = wall;
+  const candidate = fromZoned(
+    { year, month, day: dayOfMonth, hour, minute, second, millisecond },
+    zone,
+    { gap: 'next' },
+  );
+  const got = toZoned(candidate, zone);
+  return got.year === year && got.month === month && got.day === dayOfMonth ? candidate : null;
+}
+
+/**
+ * The sampling stride. A transition is found as a change of offset between two samples, so two
+ * transitions inside one stride that cancel are invisible. Measured over every zone `Intl` lists,
+ * 1900–2050 (2026-11): the closest such pairs are 7.0 days apart (Brazil 2000, Gaza 2040), and
+ * every pair under 28 days is a ONE-hour shift. A 1-hour gap moves a date only for a wall time from
+ * 23:00 (see `skippedDays`), so 28 days is exact below 23:00 and 6 days above it.
+ */
+const STRIDE_DAYS = 28;
+const LATE_STRIDE_DAYS = 6;
+const LATE_WALL_MS = 23 * HOUR_MS;
+
+const offsetMs = (zone: TimeZone, epochMs: number): number =>
+  offsetSecondsAt(zone, new Date(epochMs) as Instant) * 1000;
+
+/**
+ * The epoch days in `[from, to)` that `localDayAt` answers `null` for, ascending.
+ *
+ * A gap of `Δ` makes `{ gap: 'next' }` land `Δ` later on the wall clock, so it changes the DATE only
+ * when `wall + Δ` reaches midnight: a 1-hour spring-forward never removes a 09:00, and Samoa's
+ * 24-hour jump removes every time of day. Only a transition that can do that is located (to the
+ * day) and its neighbouring dates checked exactly; everything else is a date that exists.
+ */
+export function skippedDays(zone: TimeZone, wall: WallTime, from: number, to: number): number[] {
+  if (to <= from) return [];
+  const wallMs = wall.hour * HOUR_MS + wall.minute * 60_000 + wall.second * 1000 + wall.millisecond;
+  const stride = (wallMs >= LATE_WALL_MS ? LATE_STRIDE_DAYS : STRIDE_DAYS) * DAY_MS;
+  // Two days of margin each side: a historic offset reaches ±15:56 (Manila's LMT).
+  const start = from * DAY_MS - 2 * DAY_MS;
+  const end = to * DAY_MS + 2 * DAY_MS;
+  const found = new Set<number>();
+  let left = start;
+  let leftOffset = offsetMs(zone, left);
+  while (left < end) {
+    const right = Math.min(left + stride, end);
+    const rightOffset = offsetMs(zone, right);
+    if (rightOffset !== leftOffset) {
+      locate(zone, left, leftOffset, right, rightOffset, (low, lowOffset, high, highOffset) => {
+        const jump = highOffset - lowOffset;
+        if (jump <= 0 || wallMs + jump < DAY_MS - 1000) return;
+        const first = Math.floor((low + lowOffset - wallMs) / DAY_MS) - 1;
+        const last = Math.floor((high + highOffset - wallMs) / DAY_MS) + 1;
+        for (let day = Math.max(first, from); day <= Math.min(last, to - 1); day += 1) {
+          if (localDayAt(day, wall, zone) === null) found.add(day);
+        }
+      });
+    }
+    left = right;
+    leftOffset = rightOffset;
+  }
+  return [...found].sort((a, b) => a - b);
+}
+
+type Leaf = (low: number, lowOffset: number, high: number, highOffset: number) => void;
+
+/** Halve `[low, high]` down to a day around each change of offset; `visit` each such day. */
+function locate(
+  zone: TimeZone,
+  low: number,
+  lowOffset: number,
+  high: number,
+  highOffset: number,
+  visit: Leaf,
+): void {
+  if (high - low <= DAY_MS) {
+    visit(low, lowOffset, high, highOffset);
+    return;
+  }
+  const mid = low + Math.floor((high - low) / 2);
+  const midOffset = offsetMs(zone, mid);
+  if (midOffset !== lowOffset) locate(zone, low, lowOffset, mid, midOffset, visit);
+  if (highOffset !== midOffset) locate(zone, mid, midOffset, high, highOffset, visit);
+}