@ultimat3/time 24.0.0 → 25.1.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
@@ -136,6 +139,8 @@
   canonical zero most emitters write — was refused along with `'PT0H0M0S'` and `'P0W'`, while
   `'P0D'` was let through by a special case. `ISO_8601` already requires a component group for any
   body past a bare `'P'`, which is the case the guard was written for.
+- **`parseDuration`'s rounded total must be `Number.isSafeInteger`** (`safeTotal`, both arms) —
+  finite components can still sum to `Infinity` or past 2^53. `X_DURATION_INVALID`.
 - **An impossible day/month pair is refused by `parseCron`, in constant time.**
   `isValidCron('0 0 30 2 *')` answered `true` and the refusal arrived ~150 ms later out of
   `nextCronOccurrence`, after 200,000 walk steps — a cost `firedSince` pays on every tick of the
@@ -165,6 +170,22 @@
   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

@@ -126,6 +126,36 @@ 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`
@@ -158,7 +188,26 @@ The weekend is configuration. `WEEKEND_SAT_SUN`, `WEEKEND_FRI_SAT` (much of the
 
 `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.
+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
@@ -171,13 +220,13 @@ negated; an empty one is `0` in either direction, never `-0`.
 |---|---|
 | `X_TIMEZONE_INVALID` | not `Area/Location` or `UTC`: an abbreviation (`CET`), a numeric offset (`+02:00`), or a single-label legacy name (`Japan`) |
 | `X_CRON_INVALID` | unparseable expression, or one that can never match |
-| `X_DURATION_INVALID` | `'3'` with no unit, trailing junk, unknown unit |
+| `X_DURATION_INVALID` | `'3'` with no unit, trailing junk, unknown unit, or a total past `Number.MAX_SAFE_INTEGER` ms (`'99999999999999999999d'`) |
 | `X_DST_AMBIGUOUS` | overlap hit with `overlap: 'throw'` |
 | `X_DST_NONEXISTENT` | gap hit with `gap: 'throw'` |
 | `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": "24.0.0",
+  "version": "25.1.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": "24.0.0",
-    "@ultimat3/schema": "24.0.0"
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/schema": "25.1.0"
   }
 }

package/src/business.ts

@@ -3,7 +3,8 @@
  * 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 { daysBetween, fromZoned, isoDateInZone, toZoned, type ZonedDateTime } from './zoned';
 import { type TimeZone, utcEpoch } from './zones';
@@ -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,6 +58,11 @@ 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);
@@ -71,12 +78,34 @@ export function addBusinessDays(at: Instant, days: number, calendar: BusinessCal
       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 localDay(origin, offset, calendar.zone) ?? landed;
+    // 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 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).

package/src/context.ts

@@ -101,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,6 +3,7 @@
  * 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';
@@ -190,17 +191,23 @@ function walk(
   );
 }
 
-/** 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/duration.ts

@@ -40,7 +40,7 @@ export function parseDuration(input: string): number {
   const negative = value.startsWith('-');
   const body = negative ? value.slice(1) : value;
 
-  if (/^p/i.test(body)) return (negative ? -1 : 1) * parseIso8601Duration(body, input);
+  if (/^p/i.test(body)) return safeTotal(parseIso8601Duration(body, input), negative, input);
 
   COMPONENT.lastIndex = 0;
   let total = 0;
@@ -58,7 +58,18 @@ export function parseDuration(input: string): number {
   // Sticky matching starts at 0, so anything short of the end is trailing junk, and a
   // zero-length match means there was no unit at all (`'3'` must not mean 3 of anything).
   if (matched === 0 || matched !== body.length) throw durationInvalid(input);
-  return (negative ? -1 : 1) * Math.round(total);
+  return safeTotal(Math.round(total), negative, input);
+}
+
+/**
+ * Each component is finite and their SUM still need not be: `'9'.repeat(305) + 'd'` is
+ * `Infinity`, and twenty nines of days is 8.64e27 — past 2^53, where no timer, `Date` or
+ * `wakeAt > now` reads what was written. Refused like any other unreadable duration, on the
+ * rounded total of both arms.
+ */
+function safeTotal(ms: number, negative: boolean, input: string): number {
+  if (!Number.isSafeInteger(ms)) throw durationInvalid(input);
+  return negative ? -ms : ms;
 }
 
 /**

package/src/errors.ts

@@ -53,13 +53,35 @@ export class TimeError extends UltimateError {
 /**
  * A wall-clock field outside its range. Separate from `X_DST_*`, which are about times that
  * are legitimately absent or doubled — this one is a spec the caller got wrong.
+ *
+ * A business calendar with no business day in it (`business.ts`) is the one refusal that is not
+ * about a number, and it has two causes with two different repairs, so the caller names which
+ * through `field`: `calendar.weekendDays` (the weekend covers the week — shorten it) or
+ * `calendar.holidays` (every remaining day is a holiday — remove some). A branch here rather than a
+ * second factory, so the code keeps one constructor. Each fix is a call that runs as written; the
+ * explanation is the cause's job.
  */
 export function scheduleInvalid(field: string, value: unknown, range: string): TimeError {
+  // `value` is whatever a caller put in a `LocalSlot` — this factory is exported, so it is a form
+  // field or a config value as often as it is the `number` the in-package caller passes.
+  const cause = `${field} must be ${range}, got ${renderCauseValue(value)}`;
+  if (field === 'calendar.weekendDays') {
+    return new TimeError({
+      code: 'X_SCHEDULE_INVALID',
+      cause,
+      fix: "addBusinessDays(new Date(), 1, { zone: 'UTC', weekendDays: [6, 7] })",
+    });
+  }
+  if (field === 'calendar.holidays') {
+    return new TimeError({
+      code: 'X_SCHEDULE_INVALID',
+      cause,
+      fix: "addBusinessDays(new Date(), 1, { zone: 'UTC', holidays: [] })",
+    });
+  }
   return new TimeError({
     code: 'X_SCHEDULE_INVALID',
-    // `value` is whatever a caller put in a `LocalSlot` — this factory is exported, so it is a form
-    // field or a config value as often as it is the `number` the in-package caller passes.
-    cause: `${field} must be ${range}, got ${renderCauseValue(value)}`,
+    cause,
     fix: `pass an integer in ${range} for ${field} — wall-clock fields are not wrapped or clamped, because a silently shifted schedule is worse than a failed one`,
   });
 }

package/src/holidays.ts

@@ -0,0 +1,32 @@
+/**
+ * The holiday lookup behind `isHoliday`: one `Set` per holiday LIST, built on first use. A business
+ * calendar is asked about every day it walks, and `includes` on a long closure list made each walk
+ * quadratic in the list.
+ */
+
+/**
+ * Keyed on the list itself, in a `WeakMap`: the cache is bounded by the lists still alive, with no
+ * cap to tune and no entry outliving its calendar, and a calendar whose `holidays` is REPLACED
+ * misses at once.
+ *
+ * The list is FROZEN when its set is built, so the two can never disagree. `readonly` is only a
+ * type, and an in-place edit (a push, or an element overwritten at the same length) would otherwise
+ * be answered from the stale set. Detecting one costs a pass over the list per lookup — the cost
+ * the set exists to remove — so the edit is made impossible instead: in strict code (every ES
+ * module) it throws a `TypeError` at the line that tried it. Freezing an already-frozen list, or one
+ * `plainDateRange` returned, changes nothing.
+ */
+const memo = new WeakMap<readonly string[], ReadonlySet<string>>();
+
+const EMPTY: ReadonlySet<string> = new Set<string>();
+
+/** The holiday dates of a calendar, as a set — the same set for the same list, always. */
+export function holidaySet(holidays: readonly string[] | undefined): ReadonlySet<string> {
+  if (holidays === undefined) return EMPTY;
+  const hit = memo.get(holidays);
+  if (hit !== undefined) return hit;
+  Object.freeze(holidays);
+  const set = new Set(holidays);
+  memo.set(holidays, set);
+  return set;
+}

package/src/index.ts

@@ -1,10 +1,8 @@
 /** Public surface of @ultimat3/time. Explicit exports only. */
 
 // `localeInvalid` and the `X_LOCALE_INVALID` it carries are `@ultimat3/core`'s since 16.x —
-// `@ultimat3/money` needs the same screen and `money -> time` is a sideways import. Re-exported
-// rather than dropped so this package's public surface is unchanged, the same way
-// `@ultimat3/action` and `@ultimat3/query` re-export core's client-flight names.
-export { localeInvalid } from '@ultimat3/core';
+// `@ultimat3/money` needs the same screen and `money -> time` is a sideways import. Imported from
+// core by every caller; 25.0.0 dropped this package's re-export (`X_HELPER_COPY`).
 export {
   addBusinessDays,
   type BusinessCalendar,
@@ -101,6 +99,7 @@ export {
   toIso,
   toIsoDateUtc,
 } from './instant';
+export { addMonthsInZone, addPlainMonths } from './months';
 export {
   addPlainDays,
   comparePlainDates,
@@ -116,6 +115,11 @@ export {
   plainDateUtc,
   plainDaysBetween,
 } from './plain-date';
+export {
+  MAX_PLAIN_DATE_RANGE_DAYS,
+  type PlainDateRangeOptions,
+  plainDateRange,
+} from './plain-date-range';
 export {
   type LocalSlot,
   nextLocalSlot,

package/src/months.ts

@@ -0,0 +1,118 @@
+/**
+ * Month arithmetic: the one calendar step with no fixed length. Both functions clamp the day to the
+ * target month's last day, and the zoned one does it on the LOCAL date — never UTC month math.
+ */
+
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { TimeError } from './errors';
+import { type Instant, instant } from './instant';
+import { daysInMonth, type PlainDate, plainDateOf, plainDateParts } from './plain-date';
+import { fromZoned, toZoned } from './zoned';
+import { assertTimeZone, type TimeZone } from './zones';
+
+/** The last month a `PlainDate` can name, counted from year 0's January: 9999-12. */
+const LAST_MONTH = 9999 * 12 + 11;
+
+/**
+ * `date` moved by `months` calendar months, the day clamped to the target month's last day:
+ * `2026-01-31 + 1` is `2026-02-28`, `2024-01-31 + 1` is `2024-02-29`, `2026-03-31 − 1` is
+ * `2026-02-28`. Negative counts go back; the year rolls either way.
+ *
+ * A clamp does not compose: `2026-01-31 + 1 + 1` is `2026-03-28`, while `2026-01-31 + 2` is
+ * `2026-03-31`. A recurring date (a renewal, a billing day) is computed from its ANCHOR —
+ * `addPlainMonths(anchor, n)` for the n-th — never chained from the previous result.
+ *
+ * A whole number of months, checked as `addPlainDays` checks its days; a result outside years
+ * 0000-9999 is refused rather than branded.
+ */
+export function addPlainMonths(date: PlainDate, months: number): PlainDate {
+  // Parsed first, so every refusal below can paste the caller's date back as a checked literal.
+  const { year, month, day } = plainDateParts(date);
+  if (!Number.isSafeInteger(months)) {
+    throw monthsInvalid(
+      `months must be a whole number of months, got ${renderCauseValue(months)}`,
+      `addPlainMonths(${dateLiteral(date)}, ${wholeMonths(months)})   # months is a whole number — round it before the call`,
+    );
+  }
+  // Months counted from year 0 so one floor-division carries the year in both directions.
+  const from = year * 12 + (month - 1);
+  const total = from + months;
+  if (total < 0 || total > LAST_MONTH) {
+    // The furthest count that still lands in 0000-9999, in the direction the caller asked.
+    const furthest = total < 0 ? -from : LAST_MONTH - from;
+    throw monthsInvalid(
+      `${date} ${months < 0 ? '-' : '+'} ${Math.abs(months)} months leaves years 0000-9999`,
+      `addPlainMonths(${dateLiteral(date)}, ${furthest})   # the furthest a PlainDate reaches from ${date}`,
+    );
+  }
+  const targetYear = Math.floor(total / 12);
+  const targetMonth = total - targetYear * 12 + 1;
+  return plainDateOf({
+    year: targetYear,
+    month: targetMonth,
+    day: Math.min(day, daysInMonth(targetYear, targetMonth)),
+  });
+}
+
+/**
+ * `at` moved by `months` calendar months in `zone`, keeping the LOCAL wall-clock time: 09:00 EST
+ * on Feb 15 + 1 is 09:00 EDT on Mar 15 — 743 hours later, not 744. The local DATE moves by
+ * `addPlainMonths` (so it clamps exactly as a plain date does), then the original wall time is
+ * resolved on it once. The zone is required: an instant has a month only in a zone.
+ *
+ * The target wall time can fail to exist, or exist twice. The rule is Temporal's `'compatible'`
+ * disambiguation, and it is not configurable:
+ *
+ * | Target wall time | Resolves to |
+ * |---|---|
+ * | in a spring-forward GAP | moved FORWARD by the gap's length — 02:30 New York → 03:30 EDT; 02:15 Lord Howe (a 30-minute shift) → 02:45 |
+ * | in a fall-back OVERLAP | the EARLIER instant, i.e. the pre-transition offset — 01:30 New York → 01:30 EDT |
+ *
+ * Those are `fromZoned`'s `{ gap: 'next', overlap: 'first' }`, the policies `addDaysInZone` uses.
+ * A caller needing another answer reads the local date from this result and calls `fromZoned` with
+ * its own policy. `months === 0` returns a copy of `at` untouched, even inside an overlap's second
+ * pass — re-resolving it would answer the first.
+ */
+export function addMonthsInZone(at: Instant, months: number, timeZone: TimeZone): Instant {
+  // The zone first: an omitted one is the mistake this signature exists to make loud.
+  const zone = assertTimeZone(timeZone);
+  if (!Number.isSafeInteger(months)) {
+    throw monthsInvalid(
+      `months must be a whole number of months, got ${renderCauseValue(months)}`,
+      `addMonthsInZone(at, ${wholeMonths(months)}, ${renderFixLiteral(zone, '<Area/Location>')})   # months is a whole number — round it before the call`,
+    );
+  }
+  if (months === 0) return instant(at);
+  const local = toZoned(at, zone);
+  const target = plainDateParts(
+    addPlainMonths(plainDateOf({ year: local.year, month: local.month, day: local.day }), months),
+  );
+  return fromZoned(
+    {
+      ...target,
+      hour: local.hour,
+      minute: local.minute,
+      second: local.second,
+      millisecond: local.millisecond,
+    },
+    zone,
+    { gap: 'next', overlap: 'first' },
+  );
+}
+
+/** A parsed `PlainDate` — digits and dashes only — as source that pastes as written. */
+const dateLiteral = (date: PlainDate): string =>
+  `plainDate(${renderFixLiteral(date, '<YYYY-MM-DD>')})`;
+
+/** The whole count nearest what the caller meant, or `1` when there is nothing to round (NaN). */
+const wholeMonths = (months: number): number => {
+  const rounded = Math.trunc(months);
+  return Number.isSafeInteger(rounded) ? rounded : 1;
+};
+
+/**
+ * `X_SCHEDULE_INVALID` with the corrected CALL as its fix — `scheduleInvalid`'s generic line names a
+ * field to repair, which is prose here. `TimeError` takes its fix per throw, so the code is shared.
+ */
+const monthsInvalid = (cause: string, fix: string): TimeError =>
+  new TimeError({ code: 'X_SCHEDULE_INVALID', cause, fix });

package/src/plain-date-range.ts

@@ -0,0 +1,75 @@
+/**
+ * `plainDateRange` — the calendar dates between two `PlainDate`s, as a bounded, frozen array. It is
+ * how a closure becomes holidays: `holidays: [...fixed, ...plainDateRange(from, to)]`, one list.
+ */
+
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { TimeError } from './errors';
+import { addPlainDays, type PlainDate, plainDate, plainDaysBetween } from './plain-date';
+
+/**
+ * The widest span accepted, in days: ten years and change. A range is materialised, so an absurd
+ * one (`0000-01-01 … 9999-12-31`, 3.65 M dates) is refused before it allocates — a holiday list or
+ * a report window longer than this is a bug in whatever computed its ends.
+ */
+export const MAX_PLAIN_DATE_RANGE_DAYS = 3660;
+
+export interface PlainDateRangeOptions {
+  /** Leave `end` out — `[start, end)`. Default `false`: `[start, end]`, the closure reading. */
+  readonly exclusive?: boolean;
+  /** Days between consecutive dates, a positive whole number. Default `1`. */
+  readonly stepDays?: number;
+}
+
+/**
+ * Every `stepDays`-th date from `start`, up to `end` — **inclusive by default** (`[start, end]`),
+ * `[start, end)` with `{ exclusive: true }`. `end` appears only when the step lands on it.
+ *
+ * An array, not a generator: every caller spreads it into a holiday list or iterates it twice, and
+ * the bound makes it small. Frozen: each call's list is its own, not a buffer to edit. A reversed
+ * range is refused rather than answered empty — `start > end` is a swapped argument far more often
+ * than a deliberate empty set — as is a span over `MAX_PLAIN_DATE_RANGE_DAYS`, whatever the step.
+ */
+export function plainDateRange(
+  start: PlainDate,
+  end: PlainDate,
+  options: PlainDateRangeOptions = {},
+): readonly PlainDate[] {
+  const from = plainDate(start);
+  const to = plainDate(end);
+  const step = options.stepDays ?? 1;
+  if (!Number.isSafeInteger(step) || step < 1) {
+    throw rangeInvalid(
+      `stepDays must be a whole number of days, at least 1, got ${renderCauseValue(step)}`,
+      `plainDateRange(${literal(from)}, ${literal(to)}, { stepDays: 1 })   # stepDays is a whole number of days, at least 1`,
+    );
+  }
+  const span = plainDaysBetween(from, to);
+  if (span < 0) {
+    throw rangeInvalid(
+      `end (${to}) precedes start (${from}) by ${-span} days`,
+      `plainDateRange(${literal(to)}, ${literal(from)})   # start first: end must not precede start`,
+    );
+  }
+  if (span > MAX_PLAIN_DATE_RANGE_DAYS) {
+    throw rangeInvalid(
+      `${from} … ${to} spans ${span} days, more than MAX_PLAIN_DATE_RANGE_DAYS (${MAX_PLAIN_DATE_RANGE_DAYS})`,
+      `plainDateRange(${literal(from)}, addPlainDays(${literal(from)}, ${MAX_PLAIN_DATE_RANGE_DAYS}))   # at most ${MAX_PLAIN_DATE_RANGE_DAYS} days per range — split a longer span into several`,
+    );
+  }
+  const last = options.exclusive === true ? span - 1 : span;
+  const dates: PlainDate[] = [];
+  for (let offset = 0; offset <= last; offset += step) dates.push(addPlainDays(from, offset));
+  return Object.freeze(dates);
+}
+
+/** A checked `PlainDate`'s literal — digits and dashes only, so it pastes into source as written. */
+const literal = (date: PlainDate): string => `plainDate(${renderFixLiteral(date, '<YYYY-MM-DD>')})`;
+
+/**
+ * `X_SCHEDULE_INVALID`, with a fix that is the corrected CALL. `scheduleInvalid`'s generic fix
+ * names an integer field to repair, which reads as prose here and names nothing this function
+ * takes; `TimeError` takes its fix per throw, so the code stays the package's one range refusal.
+ */
+const rangeInvalid = (cause: string, fix: string): TimeError =>
+  new TimeError({ code: 'X_SCHEDULE_INVALID', cause, fix });

package/src/plain-date.ts

@@ -37,8 +37,11 @@ export interface PlainDateParts {
 
 const pad = (value: number, width: number): string => String(value).padStart(width, '0');
 
-/** Days in a month, Gregorian. February is the only interesting one. */
-const daysInMonth = (year: number, month: number): number =>
+/**
+ * Days in a month, Gregorian. February is the only interesting one. Exported for `months.ts`'s
+ * clamp — one leap-year rule in the package — and deliberately not re-exported by `index.ts`.
+ */
+export const daysInMonth = (year: number, month: number): number =>
   month === 2
     ? (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0
       ? 29

package/src/zones.ts

@@ -70,8 +70,13 @@ export function zonePartsAt(zone: TimeZone, at: Instant): ZoneParts {
     if (value === undefined) throw timezoneInvalid(zone);
     return Number.parseInt(value, 10);
   };
+  // `Intl` writes the proleptic Gregorian ERA year: year 0 is "1 BC", year -5 is "6 BC". The era is
+  // read with it and mapped back to the astronomical year every caller computes with (`utcEpoch`,
+  // `getUTCFullYear`); without it year 0 read as 1, and every offset before AD 1 was a year off.
+  const eraYear = read('year');
+  const beforeCommonEra = parts.find((part) => part.type === 'era')?.value === BEFORE_COMMON_ERA;
   return {
-    year: read('year'),
+    year: beforeCommonEra ? 1 - eraYear : eraYear,
     month: read('month'),
     day: read('day'),
     hour: read('hour') % 24,
@@ -157,6 +162,9 @@ export function observesDst(zone: TimeZone, at: Instant): boolean {
 const formatters = new Map<string, Intl.DateTimeFormat>();
 const labelFormatters = new Map<string, Intl.DateTimeFormat>();
 
+/** What the `en-US` formatter below names the era before year 1, at `era: 'short'`. */
+const BEFORE_COMMON_ERA = 'BC';
+
 function partsFormatterFor(zone: TimeZone): Intl.DateTimeFormat {
   // Keyed on the canonical name, so 4,096 casings of one zone are one entry rather than 4,096.
   const canonical = canonicalTimeZone(zone);
@@ -168,6 +176,7 @@ function partsFormatterFor(zone: TimeZone): Intl.DateTimeFormat {
       new Intl.DateTimeFormat('en-US', {
         timeZone: canonical,
         hourCycle: 'h23',
+        era: 'short',
         year: 'numeric',
         month: '2-digit',
         day: '2-digit',