@ultimat3/time 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -21,12 +21,15 @@
 | `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 |
+| `plain-date-range.ts` | `plainDateRange` — the bounded, frozen list of dates between two `PlainDate`s |
+| `months.ts` | `addPlainMonths` / `addMonthsInZone` — month steps, the day clamped to the target month |
+| `holidays.ts` | `holidaySet` — the memoised `Set` `isHoliday` reads, one per holiday list |
 
 ## 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,
+  no field of its own: `ctxOf({ 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
@@ -143,6 +146,44 @@
   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.
+- **Months clamp, and the zoned step is Temporal's `'compatible'`, `As of 2026-10`.**
+  `addMonthsInZone` moves the LOCAL date by `addPlainMonths` and resolves the original wall time
+  once, `{ gap: 'next', overlap: 'first' }` — forward by the gap, the earlier offset in an overlap.
+  Not an option: a second rule is a second answer. `months === 0` returns a copy, because
+  re-resolving an overlap's second pass would answer the first. A recurring date is computed from
+  its anchor; a clamp does not compose (`months.test.ts` pins both). Its refusals carry the
+  corrected call as their fix (`monthsInvalid`) — an out-of-range count names the furthest one
+  that lands in 0000-9999.
+- **The holiday `Set` is keyed on the LIST, in a `WeakMap`, and the list is FROZEN when it is
+  built.** Keyed on the calendar, a replaced `holidays` would answer stale. An in-place edit would
+  too, and detecting one is a pass over the list per lookup — the cost the set removes — so it is
+  made impossible: after first use an edit throws `TypeError` at the line that tried it. The WeakMap
+  is the bound. `holidays.test.ts` counts builds through a Proxy, so a lost memo is a failing number.
+- **`plainDateRange` refuses a span over `MAX_PLAIN_DATE_RANGE_DAYS` (3660) before allocating**, and
+  a reversed range rather than answering it empty. Each refusal is `X_SCHEDULE_INVALID` with its
+  OWN fix, the corrected call (`rangeInvalid`), never `scheduleInvalid`'s generic field prose.
 - 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,
@@ -120,13 +126,54 @@ through `JSON.stringify` as itself, and is the literal Postgres accepts and retu
 
 `@ultimat3/entity`'s `date()` column is the one that stores it.
 
+## Months clamp
+
+A month has no fixed length, so month arithmetic clamps the day to the target month's last day —
+the same rule for a plain date and for a zoned instant.
+
+| Function | Answers |
+|---|---|
+| `addPlainMonths(date, months)` | `2026-01-31 + 1` → `2026-02-28`; `2024-01-31 + 1` → `2024-02-29`; `2026-03-31 − 1` → `2026-02-28`. Negative counts go back, the year rolls. A whole number of months, a result in `0000`-`9999`, or `X_SCHEDULE_INVALID` |
+| `addMonthsInZone(at, months, timeZone)` | the same LOCAL wall-clock time, `months` calendar months away; the local date clamps as above. `timeZone` is required |
+| `plainDateRange(start, end, { exclusive?, stepDays? })` | a frozen array of dates, `[start, end]` by default, `[start, end)` with `exclusive: true`. A reversed range, a step below 1 or a span over `MAX_PLAIN_DATE_RANGE_DAYS` (3660) is `X_SCHEDULE_INVALID` |
+
+`addMonthsInZone` resolves a target wall time that does not exist, or exists twice, by Temporal's
+`'compatible'` rule — fixed, not an option:
+
+| Target wall time | Resolves to |
+|---|---|
+| spring-forward **gap** | moved **forward** by the gap: 02:30 New York → 03:30 EDT; 02:15 Lord Howe (30-minute shift) → 02:45 |
+| fall-back **overlap** | the **earlier** instant: 01:30 New York → 01:30 EDT |
+
+**A recurring date is computed from its anchor, never chained.** A clamp does not compose:
+`2026-01-31 + 1 + 1` is `2026-03-28`, `2026-01-31 + 2` is `2026-03-31`.
+
+```ts
+import { addMonthsInZone, fromIso } from '@ultimat3/time';
+
+const anchor = fromIso('2026-01-31T00:00:00-05:00');
+const renewal = (n: number) => addMonthsInZone(anchor, n, 'America/Bogota');
+// renewal(1): Feb 28 00:00, renewal(2): Mar 31 00:00 — never stuck on the 28th
+```
+
 ## Cron
 
 `parseCron` handles 5 or 6 fields, `*/n`, ranges, lists, named months and days, `@daily`
 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 +186,29 @@ 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. A calendar with no business day in it — every weekday in `weekendDays`, or
+every remaining day a holiday for ten years — is refused with `X_SCHEDULE_INVALID`, never answered
+with a weekend day.
+
+**Closures are dates.** A multi-week closure is a range spread into the one holiday list — there is
+no second `closures` field. `isHoliday` builds a `Set` once per list and reuses it, so a long list
+costs one lookup per day walked. The list is **frozen** on first use, so the set can never go
+stale: an in-place edit afterwards throws `TypeError` — build a new list to change it.
+
+```ts
+import { type BusinessCalendar, plainDate, plainDateRange } from '@ultimat3/time';
+
+const calendar: BusinessCalendar = {
+  zone: 'Europe/Berlin',
+  holidays: [
+    '2026-10-03',
+    ...plainDateRange(plainDate('2026-12-20'), plainDate('2027-01-10')),
+  ],
+};
+```
+
 `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
@@ -156,7 +226,7 @@ negated; an empty one is `0` in either direction, never `-0`.
 | `X_INSTANT_INVALID` | unparseable timestamp |
 | `X_LOCALE_INVALID` | a tag `Intl` cannot parse (`en_US`, `''`) reached any entry point taking a `locale`. Declared by `@ultimat3/core` `As of 2026-08`, thrown here unchanged — `@ultimat3/time` owned it until then. It answers **400**, not 500: the `locale` stage negotiates `Accept-Language` and never throws, so a tag that reaches this code came from a path, query or action input the caller wrote |
 | `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` |
+| `X_SCHEDULE_INVALID` | a wall-clock field out of range: `slot.hour`, `slot.minute`, `slot.second`, `slot.weekday`; a fractional or non-finite `days`; a business calendar with no business day in it |
 
 ### Error classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "license": "MIT",
   "type": "module",
@@ -28,14 +28,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/schema": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/schema": "25.0.0"
   }
 }

package/src/business.ts

@@ -3,10 +3,11 @@
  * much of the Gulf, Sunday-only in parts of Asia, Saturday/Sunday in the West.
  */
 
-import { scheduleInvalid } from './errors';
+import { scheduleInvalid, type TimeError } from './errors';
+import { holidaySet } from './holidays';
 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;
@@ -15,6 +16,7 @@ export const WEEKEND_SAT_SUN: readonly IsoWeekday[] = [6, 7];
 /** Gulf states, and the default in Israel (Fri/Sat). */
 export const WEEKEND_FRI_SAT: readonly IsoWeekday[] = [5, 6];
 export const WEEKEND_SUN_ONLY: readonly IsoWeekday[] = [7];
+const EVERY_WEEKDAY: readonly IsoWeekday[] = [1, 2, 3, 4, 5, 6, 7];
 
 export interface BusinessCalendar {
   zone: TimeZone;
@@ -29,8 +31,8 @@ export function isWeekend(at: Instant, zone: TimeZone, weekendDays = WEEKEND_SAT
 }
 
 export function isHoliday(at: Instant, calendar: BusinessCalendar): boolean {
-  const holidays = calendar.holidays ?? [];
-  return holidays.includes(isoDateInZone(at, calendar.zone));
+  // A `Set` built once per list (`holidays.ts`): every business-day walk asks this per day.
+  return holidaySet(calendar.holidays).has(isoDateInZone(at, calendar.zone));
 }
 
 /** A business day is a non-weekend, non-holiday local day. */
@@ -56,19 +58,84 @@ export function addBusinessDays(at: Instant, days: number, calendar: BusinessCal
     throw scheduleInvalid('days', days, 'a whole number of business days');
   }
   if (days === 0) return at;
+  // The misconfiguration this refusal is usually about, answered before ten years of walking.
+  const weekend = calendar.weekendDays ?? WEEKEND_SAT_SUN;
+  if (EVERY_WEEKDAY.every((day) => weekend.includes(day))) {
+    throw noBusinessDay(calendar);
+  }
   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;
+    // 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);
   }
-  return cursor;
+  return landed;
+}
+
+/**
+ * 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.
+ */
+function noBusinessDay(calendar: BusinessCalendar): TimeError {
+  const weekend = calendar.weekendDays ?? WEEKEND_SAT_SUN;
+  if (EVERY_WEEKDAY.every((day) => weekend.includes(day))) {
+    return scheduleInvalid(
+      'calendar.weekendDays',
+      weekend,
+      'ISO weekdays (1-7) that leave at least one business day',
+    );
+  }
+  return scheduleInvalid(
+    'calendar.holidays',
+    (calendar.holidays ?? []).length,
+    'dates that leave at least one business day in any ten-year window (remove some of them)',
+  );
+}
+
+/**
+ * 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 +164,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;
@@ -100,7 +101,7 @@ export function resolveTimeZone(
  * 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,
+ * arrived. `withChildContext({ tz })` and `ctxOf({ 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 {

package/src/cron-occurrence.ts

@@ -3,11 +3,12 @@
  * converted once with `fromZoned` so DST gaps and overlaps resolve correctly.
  */
 
+import { finiteCount } from '@ultimat3/core';
 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 +39,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 +56,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 +169,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,22 +186,28 @@ 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`,
   );
 }
 
-/** The next `count` occurrences, each strictly after the previous one. */
+/**
+ * The next `count` occurrences, each strictly after the previous one.
+ *
+ * `count` is screened because it bounds the loop: `NaN` answered `[]` — "no occurrences" — `2.5`
+ * ran three times, and `Infinity` pushed until the process ran out of memory.
+ */
 export function nextCronOccurrences(
   expression: string | CronExpression,
   zone: TimeZone,
   after: Instant,
   count: number,
 ): Instant[] {
+  const total = finiteCount('nextCronOccurrences', 'count', count, 0);
   const cron = parseCronOnce(expression);
   const results: Instant[] = [];
   let cursor = after;
-  for (let index = 0; index < count; index += 1) {
+  for (let index = 0; index < total; index += 1) {
     cursor = nextCronOccurrence(cron, zone, cursor);
     results.push(cursor);
   }

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`);