@ultimat3/time 23.0.0 → 25.0.0

package/src/duration.ts

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

package/src/errors.ts

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

package/src/format.ts

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

package/src/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,
@@ -138,6 +142,7 @@ export {
   fromZonedDetailed,
   type GapPolicy,
   isoDateInZone,
+  isoInZone,
   isSameLocalDay,
   type OverlapPolicy,
   startOfDay,

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

package/src/zone-canonical.ts

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

package/src/zoned.ts

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

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',