@ultimat3/time 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -67,6 +67,52 @@
   pins the process to UTC, so that bug is invisible to every in-process test — `plain-date.test.ts`
   spawns a subprocess with `TZ=America/Los_Angeles` for exactly one assertion, and that is the only
   reason it can fail.
+- **`fromIso` refuses a clock time with no offset.** `new Date('2026-03-14T09:00')` is the
+  PROCESS's 09:00, so one CSV row imported on two pods becomes two instants — the ambient default
+  this package exists to abolish, inside its own entry point. `Z` or an offset, or `X_INSTANT_INVALID`;
+  wall-clock input is `fromZoned(wall, zone)`, which names its zone. A date-only form carries no
+  clock time and is UTC by specification, so it still parses.
+- **`fromEpochMs` checks the `Date` RANGE, not `Number.isFinite`.** ±8.64e15 ms is the limit, so a
+  finite `1e16` used to hand back an Invalid Date branded as an `Instant` — a value `isInstant`
+  answers `false` for (the type's own predicate rejecting what its constructor certified) and
+  `toIso` throws a bare `RangeError` out of. `fromEpochSeconds`, `addMs`, `subtractMs` and
+  `now(clock)` all reach it and none re-checks, so the one test is `new Date(ms).getTime()` being
+  NaN — exactly what `instant()` already does.
+- **`configureTime({ defaultZone })` goes through `assertTimeZone`**, which validates AND
+  canonicalizes. It did neither: `'Mars/Olympus'` was accepted at boot and first refused inside a
+  formatter at render time, from a stack naming no configuration, and `'eUrOpE/bErLiN'` travelled
+  the process as its own zone string minting a permanent entry in every formatter cache. It throws
+  where `resolveTimeZone` skips — a stale header must not fail a request, a default nothing can
+  fall back to is a boot-time mistake with no second answer.
+- **`formatIsoDate` is built from `isoDateInZone`, never from `Intl` directly.** `year: 'numeric'`
+  neither zero-pads a year below 1000 nor carries the era, so it answered `'50-01-01'` where
+  `isoDateInZone` answered `'0050-01-01'` — two functions in one package answering one question
+  differently, and the short form matches no ISO pattern and is rejected by the `<input type="date">`
+  it exists for. One padding rule, in one place.
+- **`ordinal(value)` takes no locale.** It used to accept one, select the plural CATEGORY with it,
+  and append the ENGLISH suffix for that category regardless: `ordinal(1, 'de')` was `'1th'`. A
+  parameter that cannot change the answer correctly is removed, so a caller wanting a localized
+  ordinal hears it from `tsc`. **Breaking.**
+- **A day count is a whole number, and `formatDuration`'s `maxUnits` is at least 1.**
+  `addBusinessDays(at, 0.5)` moved a whole day and `NaN` returned the input unchanged, which reads
+  as "no movement was needed"; `maxUnits: 0` made the ceiling test true before the first unit, so
+  every duration rendered as "0 sec". Both refuse through `scheduleInvalid`, the in-package generic
+  range refusal `addPlainDays` already uses — not clamped, for the reason that error's own fix line
+  gives.
+- **`toSeconds` carries the sign out and rounds the MAGNITUDE.** `Math.round` breaks ties toward
+  `+Infinity`, so `'1500ms'` was 2 and `'-1500ms'` was -1. `@ultimat3/money`'s `rounding.ts` is the
+  framework's statement of this, and its `signed()` is why zero never comes back as `-0`.
+- **`parseDuration` rejects an ISO body by its GROUPS, never by its total.** `'PT0S'` — the
+  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.
+- **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
+  scheduler's leader loop. February is 29 in the table because leap years happen, and the check
+  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.
 - 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

@@ -28,6 +28,11 @@ canonicalization as a distinct string, so the key bounds nothing on its own. Bot
 `canonicalLocale` and `cachedFormatter` — are `@ultimat3/core`'s as of 2.0.0, so `@ultimat3/money`
 reads the same bound rather than a copy of it.
 
+`fromIso` refuses a bare local timestamp. `2026-03-14T09:00` names a different instant on every
+pod, because `new Date` resolves it through the process's zone — so a clock time reaches an
+`Instant` only with `Z` or an offset beside it (`X_INSTANT_INVALID`), and wall-clock input goes
+through `fromZoned(wall, zone)`, which names the zone it is stated in.
+
 Every value this package hands back is its own object: `instant(date)` copies rather than branding
 the caller's `Date`, and `epoch()` is a function — the `EPOCH` constant it replaces was one shared
 mutable `Date` that a single `setUTCFullYear` corrupted for the whole process.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "3.0.0"
+    "@ultimat3/core": "4.0.0"
   }
 }

package/src/business.ts

@@ -3,6 +3,7 @@
  * much of the Gulf, Sunday-only in parts of Asia, Saturday/Sunday in the West.
  */
 
+import { scheduleInvalid } from './errors';
 import type { Instant } from './instant';
 import { addDaysInZone, daysBetween, isoDateInZone, toZoned } from './zoned';
 import type { TimeZone } from './zones';
@@ -44,8 +45,16 @@ export function isBusinessDay(at: Instant, calendar: BusinessCalendar): boolean
  * Move `days` business days forward (or back, if negative), keeping the local wall-clock
  * time. `days === 0` returns the input untouched, even on a weekend — callers that want
  * "the next business day" should ask for 1.
+ *
+ * The count is a WHOLE number of days, checked the way `plain-date.ts`'s `addPlainDays` checks its
+ * own: `0.5` used to reach `Math.abs(days)` as a loop bound and move a whole day, and a `NaN` —
+ * the shape a corrupted config or a failed parse takes — failed `remaining > 0` on the first test
+ * and returned the input, which reads as "no movement was needed" rather than as a failure.
  */
 export function addBusinessDays(at: Instant, days: number, calendar: BusinessCalendar): Instant {
+  if (!Number.isSafeInteger(days)) {
+    throw scheduleInvalid('days', days, 'a whole number of business days');
+  }
   if (days === 0) return at;
   const step = days > 0 ? 1 : -1;
   let remaining = Math.abs(days);

package/src/context.ts

@@ -6,7 +6,7 @@
 
 import { tryUseContext } from '@ultimat3/core';
 import { canonicalTimeZone } from './zone-canonical';
-import { type TimeZone, UTC } from './zones';
+import { assertTimeZone, type TimeZone, UTC } from './zones';
 
 /** Header a client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
 export const TIMEZONE_HEADER = 'x-timezone';
@@ -45,8 +45,25 @@ const DEFAULT_ORDER: readonly TimeZoneSourceName[] = ['user', 'cookie', 'query',
 
 let config: TimeConfig = { defaultZone: UTC, order: DEFAULT_ORDER };
 
+/**
+ * The default zone goes through `assertTimeZone`, which both VALIDATES and CANONICALIZES — the two
+ * halves `resolveTimeZone` already promises for every other source, on the one source that skipped
+ * them. Unchecked, `configureTime({ defaultZone: 'Mars/Olympus' })` was accepted at boot and first
+ * refused inside a formatter at render time, from a stack that names no configuration; and
+ * `'eUrOpE/bErLiN'` travelled the process as its own zone string, minting a permanent entry in
+ * every formatter cache it reached.
+ *
+ * It throws, where `resolveTimeZone` skips: a stale header from an old client must not fail a
+ * 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 {
-  config = { ...config, ...partial };
+  const defaultZone =
+    partial.defaultZone === undefined ? undefined : assertTimeZone(partial.defaultZone);
+  config = {
+    ...config,
+    ...partial,
+    ...(defaultZone === undefined ? {} : { defaultZone }),
+  };
   return config;
 }
 

package/src/cron-occurrence.ts

@@ -106,9 +106,12 @@ export function nextCronOccurrence(
     carry(cursor);
   }
 
+  // The backstop, not the primary check. An impossible day/month pair — `0 0 30 2 *`, a 30th of
+  // 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,
-    `no occurrence after ${MAX_STEPS} search steps — the date fields can never all match (e.g. "0 0 30 2 *", a 30th of February)`,
+    `no occurrence after ${MAX_STEPS} search steps — the date fields can never all match`,
   );
 }
 

package/src/cron-parse.ts

@@ -20,15 +20,20 @@ export interface CronExpression {
   dayOfWeekRestricted: boolean;
 }
 
-const MACROS: Readonly<Record<string, string>> = {
-  '@yearly': '0 0 1 1 *',
-  '@annually': '0 0 1 1 *',
-  '@monthly': '0 0 1 * *',
-  '@weekly': '0 0 * * 0',
-  '@daily': '0 0 * * *',
-  '@midnight': '0 0 * * *',
-  '@hourly': '0 * * * *',
-};
+// A `Map`, not an object literal: the key is a caller's string, and `MACROS['constructor']` on a
+// plain object answers `Object` — a function that reached `.split()` as a bare `TypeError` out of
+// the one function whose entire contract is a coded refusal.
+const MACROS: ReadonlyMap<string, string> = new Map(
+  Object.entries({
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *',
+  }),
+);
 
 const MONTH_NAMES = [
   'jan',
@@ -49,7 +54,7 @@ const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
 /** Parse 5 fields (`m h dom mon dow`) or 6 with a leading seconds field. */
 export function parseCron(expression: string): CronExpression {
   const trimmed = expression.trim().toLowerCase();
-  const expanded = MACROS[trimmed] ?? trimmed;
+  const expanded = MACROS.get(trimmed) ?? trimmed;
   const fields = expanded.split(/\s+/).filter((field) => field !== '');
 
   if (fields.length !== 5 && fields.length !== 6) {
@@ -72,7 +77,7 @@ export function parseCron(expression: string): CronExpression {
   // 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);
 
-  return {
+  const parsed: CronExpression = {
     source: expanded,
     seconds,
     minutes,
@@ -83,6 +88,52 @@ export function parseCron(expression: string): CronExpression {
     dayOfMonthRestricted: isRestricted(domField ?? '*'),
     dayOfWeekRestricted: isRestricted(dowField ?? '*'),
   };
+  assertReachableDate(expression, parsed);
+  return parsed;
+}
+
+/** Longest each month can be. February is 29 because leap years happen — 29 CAN fire, 30 cannot. */
+const LONGEST_MONTH: readonly number[] = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+const MONTH_LABELS = [
+  'january',
+  'february',
+  'march',
+  'april',
+  'may',
+  'june',
+  'july',
+  'august',
+  'september',
+  'october',
+  'november',
+  'december',
+];
+
+/**
+ * A grammatically valid expression whose day and month fields can never both match — `0 0 30 2 *`,
+ * a 30th of February. Decidable from the parsed fields in a bounded 12 x 31 scan, and decided
+ * HERE, because the alternative was `nextCronOccurrence` exhausting its 200,000-step walk: ~150 ms
+ * of blocking CPU, paid by `firedSince` on every tick of the scheduler's leader loop, to reach a
+ * refusal that `isValidCron` had already answered `true` for.
+ *
+ * Only when day-of-month is restricted and day-of-week is NOT. Vixie's OR rule is why: with both
+ * restricted, `0 0 30 2 5` means "the 30th of February OR any Friday in February", which fires
+ * every Friday in February — refusing it would break a working schedule.
+ */
+function assertReachableDate(expression: string, cron: CronExpression): void {
+  if (!cron.dayOfMonthRestricted || cron.dayOfWeekRestricted) return;
+  for (const month of cron.months) {
+    const longest = LONGEST_MONTH[month - 1] ?? 31;
+    for (const day of cron.daysOfMonth) {
+      if (day <= longest) return;
+    }
+  }
+  const months = cron.months.map((month) => MONTH_LABELS[month - 1] ?? String(month)).join(', ');
+  throw cronInvalid(
+    expression,
+    `day ${cron.daysOfMonth.join(',')} never occurs in ${months}, so this expression can never fire`,
+  );
 }
 
 export function isValidCron(expression: string): boolean {

package/src/duration.ts

@@ -3,7 +3,7 @@
  * `step.sleep('3d')` in @ultimat3/jobs and every `retry.backoff` value comes through here.
  */
 
-import { durationInvalid } from './errors';
+import { durationInvalid, scheduleInvalid } from './errors';
 
 export const MS = 1;
 export const SECOND = 1000;
@@ -65,8 +65,17 @@ export function toMs(duration: string | number): number {
   return typeof duration === 'number' ? duration : parseDuration(duration);
 }
 
+/**
+ * `Math.round` breaks ties toward `+Infinity`, which is asymmetric across zero: `'1500ms'` was 2
+ * and `'-1500ms'` was -1, so a signed duration and its mirror did not answer mirrored seconds.
+ * The sign is carried out and the MAGNITUDE rounded — `packages/money/src/rounding.ts` is the
+ * framework's one statement of this, and `signed()` there is why zero never comes back as `-0`.
+ */
 export function toSeconds(duration: string | number): number {
-  return Math.round(toMs(duration) / SECOND);
+  const ms = toMs(duration);
+  const seconds = Math.round(Math.abs(ms) / SECOND);
+  if (seconds === 0) return 0;
+  return ms < 0 ? -seconds : seconds;
 }
 
 export interface FormatDurationOptions {
@@ -95,6 +104,14 @@ export function formatDuration(
 ): string {
   const style = options.style ?? 'short';
   const maxUnits = options.maxUnits ?? 2;
+  // Refused, not clamped, for the reason `scheduleInvalid`'s own fix line gives: `maxUnits: 0`
+  // made `pieces.length >= maxUnits` true before the first unit was measured, so EVERY duration
+  // fell through to the zero fallback and 9,000,000 ms rendered as "0 sec". A caller that asked
+  // for no units wanted something this function cannot express, and a silently wrong number on a
+  // screen is worse than a failed render.
+  if (!Number.isInteger(maxUnits) || maxUnits < 1) {
+    throw scheduleInvalid('maxUnits', maxUnits, 'at least 1');
+  }
   let remaining = Math.abs(Math.round(ms));
   const pieces: string[] = [];
 
@@ -141,13 +158,25 @@ function parseIso8601Duration(body: string, original: string): number {
   const match = ISO_8601.exec(body);
   if (match === null) throw durationInvalid(original);
   const [, weeks, days, hours, minutes, seconds] = match;
+  // The guard is on the GROUPS, not on the total. `'P'` and `'PT'` name no duration and must be
+  // refused; `'PT0S'` — the canonical zero most emitters write — names one, and testing
+  // `total === 0` rejected it 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 bare `P`.
+  if (
+    weeks === undefined &&
+    days === undefined &&
+    hours === undefined &&
+    minutes === undefined &&
+    seconds === undefined
+  ) {
+    throw durationInvalid(original);
+  }
   const total =
     number(weeks) * WEEK +
     number(days) * DAY +
     number(hours) * HOUR +
     number(minutes) * MINUTE +
     number(seconds) * SECOND;
-  if (total === 0 && body.toUpperCase() !== 'P0D') throw durationInvalid(original);
   return Math.round(total);
 }
 

package/src/format.ts

@@ -6,6 +6,7 @@
 
 import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
+import { isoDateInZone } from './zoned';
 import { assertTimeZone, type TimeZone } from './zones';
 
 export type DateTimeStyle = 'short' | 'medium' | 'long' | 'full';
@@ -86,15 +87,17 @@ export function formatWithOffset(at: Instant, options: FormatDateTimeOptions): s
   return offset === '' ? text : `${text} (${offset})`;
 }
 
-/** ISO-8601 date parts in a zone, for `<input type="date">` and CSV columns. */
+/**
+ * ISO-8601 date parts in a zone, for `<input type="date">` and CSV columns.
+ *
+ * Built from `isoDateInZone`, not from `Intl`: `year: 'numeric'` neither zero-pads a year below
+ * 1000 nor carries the era, so this answered `'50-01-01'` where `isoDateInZone` answered
+ * `'0050-01-01'` — two functions in one package answering one question differently, and the short
+ * form matches no ISO pattern and is rejected by the very input this exists for. One padding rule,
+ * in one place.
+ */
 export function formatIsoDate(at: Instant, zone: TimeZone): string {
-  const parts = formatterFor('en-CA', {
-    timeZone: assertTimeZone(zone),
-    year: 'numeric',
-    month: '2-digit',
-    day: '2-digit',
-  }).format(at);
-  return parts.replace(/\//g, '-');
+  return isoDateInZone(at, assertTimeZone(zone));
 }
 
 export interface FormatRelativeOptions extends Omit<FormatContext, 'zone'> {
@@ -155,12 +158,18 @@ const ORDINAL_SUFFIX: Record<Intl.LDMLPluralRule, string> = {
 };
 
 /**
- * `Intl` renders `November 5, 2011`, never `5th of November`. When a design asks for the
- * ordinal, build it from `Intl.PluralRules` with `type: 'ordinal'` — English-only by
- * nature, which is why it is a helper and not the default date format.
+ * `Intl` renders `November 5, 2011`, never `5th of November`. When a design asks for the ordinal,
+ * build it from `Intl.PluralRules` with `type: 'ordinal'` — **English only**, which is why it is a
+ * helper and not the default date format.
+ *
+ * It takes NO locale, and that is the enforcement rather than a note. It used to accept one, pick
+ * the plural category with it, and then append the ENGLISH suffix for that category: `ordinal(1,
+ * 'de')` was `'1th'`, a word in no language. A parameter that cannot change the answer correctly
+ * is removed, so a caller who wants a localized ordinal finds out from `tsc` instead of from a
+ * rendered page. **Breaking: the `locale` parameter is gone.**
  */
-export function ordinal(value: number, locale = 'en'): string {
-  const category = new Intl.PluralRules(locale, { type: 'ordinal' }).select(value);
+export function ordinal(value: number): string {
+  const category = new Intl.PluralRules('en', { type: 'ordinal' }).select(value);
   return `${value}${ORDINAL_SUFFIX[category]}`;
 }
 

package/src/instant.ts

@@ -24,8 +24,20 @@ export function instant(value: Date): Instant {
   return new Date(value.getTime()) as Instant;
 }
 
-/** ISO-8601 in, `Instant` out. An offset or `Z` is required — a bare local string is a bug. */
+/**
+ * A time of day, and the zone it is stated in. `2026-03-14T09:00` without one is resolved by
+ * `new Date` through the PROCESS's zone, so the guard has to see both halves: a string carrying
+ * a clock time is refused unless it also carries `Z` or an offset. A date-only form carries no
+ * clock time and is UTC by specification, so it passes.
+ */
+const CLOCK_TIME = /[t ]\d{1,2}:\d{2}/i;
+const UTC_OFFSET = /(?:z|[+-]\d{2}:?\d{2})$/i;
+
+/** ISO-8601 in, `Instant` out. An offset or `Z` is required — a bare local string is refused. */
 export function fromIso(iso: string): Instant {
+  // Enforced, not documented: this header asked for an offset for three releases while the body
+  // accepted a bare local string and answered a different instant per deployment timezone.
+  if (CLOCK_TIME.test(iso) && !UTC_OFFSET.test(iso)) throw instantInvalid(iso);
   const parsed = new Date(iso);
   if (Number.isNaN(parsed.getTime())) throw instantInvalid(iso);
   return parsed as Instant;
@@ -41,9 +53,17 @@ export function toIsoDateUtc(at: Instant): string {
   return at.toISOString().slice(0, 10);
 }
 
+/**
+ * The SAME test `instant()` performs, and for the same reason. `Number.isFinite` is not the `Date`
+ * range: `+/-8.64e15` ms is the limit, so a finite `1e16` produced an Invalid Date branded as an
+ * `Instant` — a value `isInstant` answers `false` for (the type's own predicate rejecting what its
+ * constructor certified) and `toIso` throws a bare `RangeError` out of. Reached through
+ * `fromEpochSeconds`, `addMs`, `subtractMs` and `now(clock)`, none of which re-check.
+ */
 export function fromEpochMs(ms: number): Instant {
-  if (!Number.isFinite(ms)) throw instantInvalid(String(ms));
-  return new Date(ms) as Instant;
+  const at = new Date(ms);
+  if (Number.isNaN(at.getTime())) throw instantInvalid(String(ms));
+  return at as Instant;
 }
 
 export function toEpochMs(at: Instant): number {
@@ -105,7 +125,11 @@ export function epoch(): Instant {
   return new Date(0) as Instant;
 }
 
-/** Tolerates a `Clock` whose `now()` returns either a `Date` or epoch milliseconds. */
+/**
+ * `Clock.now()` returns a `Date`, so the number branch is unreachable through the typed API. It is
+ * kept for the untyped caller: a JS `Clock` answering epoch milliseconds would otherwise reach
+ * `.getTime()` on a number and throw a bare `TypeError` instead of `X_INSTANT_INVALID`.
+ */
 function epochMsOf(value: Date | number): number {
   return typeof value === 'number' ? value : value.getTime();
 }