@ultimat3/time 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -10,8 +10,6 @@
 | `instant.ts` | the UTC `Instant` brand, ISO/epoch conversion, `now(clock)`, `epoch()` |
 | `zones.ts` | IANA validation, `offsetAt` (minutes east), zone labels |
 | `zone-canonical.ts` | one zone, one key: `canonicalTimeZone` — the casing/alias collapse every cache keys on |
-| `locale-canonical.ts` | one locale, one key: `canonicalLocale` — the same collapse for the `Accept-Language` half |
-| `intl-cache.ts` | the one bounded FIFO every `Intl` formatter cache in this package uses |
 | `zoned.ts` | `toZoned` / `fromZoned` + gap and overlap policies. Everything depends on this. |
 | `format.ts` | `Intl` rendering. Every function takes `locale` **and** `zone`. |
 | `duration.ts` | `'2h30m'` ⇄ ms |
@@ -22,6 +20,7 @@
 | `schedule.ts` | `nextLocalSlot` — "09:00 local tomorrow" |
 | `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 |
 
 ## Rules
 
@@ -35,7 +34,10 @@
   possible version of the rule above. Never reintroduce either half.
 - **Never cache an `Intl` formatter on a raw caller string.** A zone and a locale both arrive from
   a request header, so the key must be canonical (`canonicalTimeZone` for a zone, `canonicalLocale`
-  for a locale) and the cache must be bounded (`cachedFormatter`, `intl-cache.ts`). An unbounded
+  for a locale) and the cache must be bounded (`cachedFormatter`). **`cachedFormatter`,
+  `MAX_CACHED_FORMATTERS` and `canonicalLocale` are `@ultimat3/core`'s as of 2.0.0**, not this
+  package's: `@ultimat3/money` hit the identical unbounded-`Map`-on-a-header bug and tier 1 may not
+  import sideways, so the mechanism moved down a tier rather than being copied. An unbounded
   `Map` keyed on `x-timezone` grew 31 MB for 4,096 casings of one zone name, and the casing space
   of a 13-letter zone is 2^12. **Both halves, always** — a canonical key does not bound anything
   (an unknown `-u-` extension value survives canonicalization as a distinct string) and the cap
@@ -50,6 +52,67 @@
   no seconds phrase, so a 6-field expression with a non-trivial seconds field is
   `X_CRON_NOT_DESCRIBABLE`. Adding a required field to `CronPhrases` would break every caller
   (`packages/cli/src/cmd-tasks.ts` builds one) to describe a schedule almost nobody writes.
+- **A `PlainDate` is a branded STRING, and the golden rule does not apply to it** — decided
+  2026-08 for `@ultimat3/entity`'s `date()` column. "Never format a date without a zone" is about
+  INSTANTS; a calendar date names no instant, so it needs no zone, and giving it one is the bug:
+  `effective_on` stored as a `timestamptz` is a different date on either side of midnight for half
+  the planet. Not a `Date` (that is an instant, and binding one to a Postgres `date` parameter
+  fails outright — `time zone "gmt-0500" not recognized`, measured on 17.10) and not
+  `{ year, month, day }` (an object sorts by nothing and JSON-stringifies as three fields). The ISO
+  string sorts lexicographically exactly as it sorts chronologically, which is why every cursor,
+  `orderBy` and `compare` in the framework handles it with no special case at all.
+- **`plainDateIn` takes a zone and `plainDateUtc` does not, and neither is a default for the
+  other.** An instant has a calendar date only in a zone; a `Date` a driver returns for a `date`
+  column is midnight UTC and reading its LOCAL fields loses a day west of Greenwich. `bun test`
+  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

@@ -23,8 +23,15 @@ return it. Anything reading a zone off a request header should canonicalize befo
 
 One **locale** is one key for the same reason — `Accept-Language` spells one locale `EN-us`,
 `en-US` and `en-latn-us`, and `formatDateTime` and `describeCron` collapse the three before they
-reach a formatter cache. The cap in `intl-cache.ts` stays either way: an unknown `-u-` extension
-value survives canonicalization as a distinct string, so the key bounds nothing on its own.
+reach a formatter cache. The cap stays either way: an unknown `-u-` extension value survives
+canonicalization as a distinct string, so the key bounds nothing on its own. Both halves —
+`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
@@ -78,6 +85,34 @@ one of these takes the zone explicitly, and none of them has a default.
 `daysBetween` counts boundaries, not milliseconds: 23 real hours across spring forward is `1`,
 and 24 real hours inside a 25-hour fall-back day is `0`.
 
+## A calendar date is not an instant
+
+`PlainDate` is `2026-03-14`: a year, a month and a day, with **no time and therefore no zone**,
+`As of 2026-08`. The golden rule at the top of this page is about instants — a `PlainDate` needs no
+zone because it names no moment, and that is the honest modelling of the values that have one.
+`effective_on` is the date a rate applies; a birthday is a date; an invoice period is two of them.
+Stored as a `timestamptz`, every one of those is a different date on either side of midnight for
+half the planet.
+
+| Function | Answers |
+|---|---|
+| `plainDate(value)` / `isPlainDate(value)` | the date, or a refusal — `2026-02-30` is not one, and a regex cannot say so |
+| `plainDateOf({ year, month, day })` | the same, from fields; an impossible day throws instead of rolling into the next month |
+| `plainDateParts(date)` | back to fields |
+| `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 |
+| `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,
+so `2026-03-14T00:00:00Z` is the 13th anywhere west of Greenwich, and binding one to a Postgres
+`date` parameter fails outright (`time zone "gmt-0500" not recognized`, measured on 17.10). A
+string: the ISO form sorts lexicographically exactly as it sorts chronologically, round-trips
+through `JSON.stringify` as itself, and is the literal Postgres accepts and returns.
+
+`@ultimat3/entity`'s `date()` column is the one that stores it.
+
 ## Cron
 
 `parseCron` handles 5 or 6 fields, `*/n`, ranges, lists, named months and days, `@daily`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "2.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": "2.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-describe.ts

@@ -4,10 +4,9 @@
  * ship English to every locale that forgot the argument — so injection is mandatory, not opt-in.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { type CronExpression, parseCronOnce } from './cron-parse';
 import { cronNotDescribable, localeInvalid } from './errors';
-import { cachedFormatter } from './intl-cache';
-import { canonicalLocale } from './locale-canonical';
 
 export interface CronPhrases {
   everyMinute: string;
@@ -134,8 +133,9 @@ function fill(template: string, vars: Readonly<Record<string, string | number>>)
  * header. `canonicalLocale` collapses the spellings of one locale — `EN-us`, `en-latn-us` — but it
  * still returns a distinct string for every unknown `-u-` extension value, so the key alone does
  * not bound anything and only the cap keeps the key space finite. Neither half is redundant. The
- * cap and its FIFO live in `intl-cache.ts`, because `zones.ts` and `format.ts` needed the same
- * rule and a hazard documented in one file is a hazard the other two repeat.
+ * cap and its FIFO live in `@ultimat3/core`'s `intl-cache.ts`, because `zones.ts`, `format.ts` and
+ * `@ultimat3/money`'s formatter all need the same rule, and a hazard documented in one file is a
+ * hazard every other one repeats.
  *
  * Both caches are fed the canonical `tag` by `describeCron` alone, never a caller string.
  */

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) {
@@ -65,12 +70,14 @@ export function parseCron(expression: string): CronExpression {
   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 rawDow = parseField(expression, dowField ?? '*', 0, 7, DAY_NAMES, 0);
+  // 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);
 
   // 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,
@@ -81,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 {
@@ -113,6 +166,13 @@ function parseField(
   max: number,
   names: readonly string[] = [],
   nameOffset = 0,
+  /**
+   * How many distinct values one full turn of this field has — `max - min + 1` for every field
+   * whose spelling is one-to-one. Day-of-week is the exception and the reason this is a parameter:
+   * it spells Sunday twice (0 and 7), so its 0-7 bounds describe 8 slots over a 7-day week, and a
+   * wrapping stride computed from the bounds walked a day that does not exist.
+   */
+  span = max - min + 1,
 ): number[] {
   const values = new Set<number>();
   for (const part of field.split(',')) {
@@ -144,7 +204,6 @@ function parseField(
       // Wrapping ranges (`fri-mon`, `22-2`) are a real cron idiom, and the stride CONTINUES across
       // the wrap: `23-3/2` is 23, 01, 03 — every second hour starting at 23. Restarting at `min`
       // answered 23, 00, 02, an hour off for every occurrence past midnight.
-      const span = max - min + 1;
       const length = to - from + span;
       for (let offset = 0; offset <= length; offset += step) {
         values.add(min + ((from - min + offset) % span));

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

@@ -4,9 +4,9 @@
  * because "the server's timezone" is never the answer to "what time is it for the user".
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
-import { cachedFormatter } from './intl-cache';
-import { canonicalLocale } from './locale-canonical';
+import { isoDateInZone } from './zoned';
 import { assertTimeZone, type TimeZone } from './zones';
 
 export type DateTimeStyle = 'short' | 'medium' | 'long' | 'full';
@@ -87,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'> {
@@ -156,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/index.ts

@@ -97,6 +97,21 @@ export {
   toIso,
   toIsoDateUtc,
 } from './instant';
+export {
+  addPlainDays,
+  comparePlainDates,
+  isPlainDate,
+  PLAIN_DATE_PATTERN,
+  type PlainDate,
+  type PlainDateParts,
+  plainDate,
+  plainDateIn,
+  plainDateOf,
+  plainDateParts,
+  plainDateToUtcInstant,
+  plainDateUtc,
+  plainDaysBetween,
+} from './plain-date';
 export {
   type LocalSlot,
   nextLocalSlot,

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();
 }

package/src/plain-date.ts

@@ -0,0 +1,133 @@
+// A calendar date: a year, a month and a day, with no time and therefore no zone. The framework's
+// "never format a date without an IANA zone" rule is about INSTANTS — a `PlainDate` needs no zone
+// because it names no instant, and that is the whole reason it exists: `effective_on` is the date
+// a rate applies, not a moment, and storing it as a `timestamptz` makes it a different date either
+// side of midnight for half the planet.
+
+import { scheduleInvalid } from './errors';
+import { type Instant, instant } from './instant';
+import { isoDateInZone } from './zoned';
+import type { TimeZone } from './zones';
+
+declare const plainDateBrand: unique symbol;
+
+/**
+ * `2026-03-14`. A branded STRING, not an object and not a `Date`, and each half of that is load-
+ * bearing:
+ *
+ * - not a `Date`, because a `Date` is an instant: read back through the local zone,
+ *   `2026-03-14T00:00:00Z` is the 13th anywhere west of Greenwich, and binding one to a Postgres
+ *   `date` parameter fails outright (`time zone "gmt-0500" not recognized`, measured on 17.10).
+ * - a string, because the ISO form sorts lexicographically exactly as it sorts chronologically,
+ *   round-trips through `JSON.stringify` as itself, and is the literal Postgres accepts and
+ *   returns for a `date` column.
+ */
+export type PlainDate = string & { readonly [plainDateBrand]: 'plain-date' };
+
+/** The shape a CHECK constraint and a JSON Schema both spell. ECMAScript and POSIX ERE agree. */
+export const PLAIN_DATE_PATTERN = '^\\d{4}-\\d{2}-\\d{2}$';
+
+const SHAPE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+export interface PlainDateParts {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+}
+
+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 =>
+  month === 2
+    ? (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0
+      ? 29
+      : 28
+    : [4, 6, 9, 11].includes(month)
+      ? 30
+      : 31;
+
+/**
+ * The parse every other function here goes through. `null` rather than a throw, so the guard and
+ * the thrower share one rule and only the failure policy differs — the same split
+ * `resolveEnvironment` / `tryResolveEnvironment` make in core.
+ */
+const read = (value: unknown): PlainDateParts | null => {
+  if (typeof value !== 'string') return null;
+  const match = SHAPE.exec(value);
+  if (match === null) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (month < 1 || month > 12) return null;
+  // A day the month does not have is the case a regex cannot see, and it is the one that matters:
+  // `2026-02-30` reaches Postgres as `date` input and is rejected there, three layers later.
+  if (day < 1 || day > daysInMonth(year, month)) return null;
+  return { year, month, day };
+};
+
+export const isPlainDate = (value: unknown): value is PlainDate => read(value) !== null;
+
+/** A calendar date from its ISO form. Throws on anything that is not one — including `2026-02-30`. */
+export function plainDate(value: string): PlainDate {
+  const parts = read(value);
+  if (parts === null) {
+    throw scheduleInvalid('date', value, 'a real YYYY-MM-DD calendar date');
+  }
+  return value as PlainDate;
+}
+
+/** A calendar date from its fields. Out-of-range fields throw rather than wrap into another month. */
+export function plainDateOf(parts: PlainDateParts): PlainDate {
+  return plainDate(`${pad(parts.year, 4)}-${pad(parts.month, 2)}-${pad(parts.day, 2)}`);
+}
+
+export function plainDateParts(date: PlainDate): PlainDateParts {
+  const parts = read(date);
+  if (parts === null) throw scheduleInvalid('date', date, 'a real YYYY-MM-DD calendar date');
+  return parts;
+}
+
+/**
+ * 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.
+ */
+export const plainDateIn = (at: Instant, zone: TimeZone): PlainDate =>
+  isoDateInZone(at, zone) as PlainDate;
+
+/**
+ * The calendar date a `Date` holds when read as UTC. For ONE caller: a Postgres driver hands a
+ * `date` column back as a `Date` at UTC midnight (measured: Bun's `sql` and PGlite both), so the
+ * date the column holds is its UTC date and reading it through the local zone loses a day west of
+ * Greenwich. Never use this on a timestamp — that is `plainDateIn`, which asks for the zone.
+ */
+export function plainDateUtc(at: Date): PlainDate {
+  const checked = instant(at);
+  return `${pad(checked.getUTCFullYear(), 4)}-${pad(checked.getUTCMonth() + 1, 2)}-${pad(
+    checked.getUTCDate(),
+    2,
+  )}` as PlainDate;
+}
+
+/** Midnight UTC of the date, as an instant — the inverse of `plainDateUtc`, and never of `plainDateIn`. */
+export const plainDateToUtcInstant = (date: PlainDate): Instant =>
+  instant(new Date(`${plainDate(date)}T00:00:00.000Z`));
+
+/** `-1`, `0`, `1`. Lexicographic order IS chronological order for this form; that is why it sorts. */
+export const comparePlainDates = (left: PlainDate, right: PlainDate): number =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const DAY_MS = 86_400_000;
+
+/** Whole days added, over UTC midnights, so no DST rule and no zone can shorten a day here. */
+export function addPlainDays(date: PlainDate, days: number): PlainDate {
+  if (!Number.isSafeInteger(days)) {
+    throw scheduleInvalid('days', days, 'a whole number of days');
+  }
+  return plainDateUtc(new Date(plainDateToUtcInstant(date).getTime() + days * DAY_MS));
+}
+
+/** Signed whole days from `from` to `to`. Always integral: both ends are UTC midnights. */
+export const plainDaysBetween = (from: PlainDate, to: PlainDate): number =>
+  (plainDateToUtcInstant(to).getTime() - plainDateToUtcInstant(from).getTime()) / DAY_MS;

package/src/zone-canonical.ts

@@ -4,7 +4,7 @@
  * A 13-letter name has 2^12 casings and a request header can name any of them.
  */
 
-import { cachedFormatter } from './intl-cache';
+import { cachedFormatter } from '@ultimat3/core';
 
 /** ES2024 `Intl` accepts `+01:00` as a zone; we do not — a fixed offset has no DST rules. */
 const NUMERIC_OFFSET = /^[+-]/;

package/src/zones.ts

@@ -4,9 +4,9 @@
  * is no offset table to keep in sync and no `date-fns-tz` dependency.
  */
 
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
 import { timezoneInvalid } from './errors';
 import type { Instant } from './instant';
-import { cachedFormatter } from './intl-cache';
 import { canonicalTimeZone } from './zone-canonical';
 
 /** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */
@@ -117,13 +117,22 @@ export function zoneAbbrev(
   locale = 'en-US',
   style: 'short' | 'long' | 'shortOffset' | 'longOffset' = 'short',
 ): string {
-  const formatter = new Intl.DateTimeFormat(locale, {
-    timeZone: zone,
-    timeZoneName: style,
-    hourCycle: 'h23',
+  const canonical = assertTimeZone(zone);
+  // A tag `Intl` cannot parse falls through unchanged, exactly as in `format.ts`: this decides a
+  // cache key, never whether a locale is acceptable.
+  const tag = canonicalLocale(locale) ?? locale;
+  // The one `Intl` construction in this package that escaped the shared cache: it built a formatter
+  // per call on the caller's raw zone and locale, so an `x-timezone` an app renders a label from
+  // paid for a fresh `Intl.DateTimeFormat` every time and an unknown one escaped as a `RangeError`.
+  const formatter = cachedFormatter(labelFormatters, `${canonical}|${tag}|${style}`, () => {
+    return new Intl.DateTimeFormat(tag, {
+      timeZone: canonical,
+      timeZoneName: style,
+      hourCycle: 'h23',
+    });
   });
   const label = formatter.formatToParts(at).find((part) => part.type === 'timeZoneName')?.value;
-  return label ?? offsetLabel(offsetAt(zone, at));
+  return label ?? offsetLabel(offsetAt(canonical, at));
 }
 
 /**
@@ -145,6 +154,7 @@ export function observesDst(zone: TimeZone, at: Instant): boolean {
 }
 
 const formatters = new Map<string, Intl.DateTimeFormat>();
+const labelFormatters = new Map<string, Intl.DateTimeFormat>();
 
 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.

package/src/intl-cache.ts

@@ -1,26 +0,0 @@
-/**
- * One bounded cache for every `Intl` formatter this package builds.
- * A locale and a zone both arrive from a request header, so an unbounded `Map` keyed on that
- * string is memory the client chooses: 4,096 case-variants of one zone name retained 31 MB,
- * ~7.7 KB per `Intl.DateTimeFormat`, and 600 zones times 2^12 casings has no ceiling at all.
- */
-
-/**
- * Above the full canonical IANA set (445 zones as of tzdata 2025) so a correct app never evicts,
- * and small enough that the worst case is a few megabytes rather than a leak. A miss costs one
- * `Intl` construction, never a wrong answer — which is what makes a bound safe here at all.
- */
-export const MAX_CACHED_FORMATTERS = 512;
-
-/** FIFO — a `Map` iterates in insertion order, so the first key inserted is the first evicted. */
-export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: () => T): T {
-  const hit = cache.get(key);
-  if (hit !== undefined) return hit;
-  const formatter = build();
-  if (cache.size >= MAX_CACHED_FORMATTERS) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  cache.set(key, formatter);
-  return formatter;
-}

package/src/locale-canonical.ts

@@ -1,23 +0,0 @@
-/**
- * One locale, one key. `Intl` accepts `EN-us`, `en-US` and `en-latn-us` as the same locale, so a
- * cache keyed on the caller's spelling holds three formatters where one would do — and the caller
- * is `Accept-Language`. The twin of `zone-canonical.ts`, for the other header-supplied string.
- */
-
-/**
- * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
- * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
- * falls back for it, and refusing here would be stricter than the formatters this feeds.
- *
- * Deliberately **not** memoised: this is string work, and a `Map` keyed on a header value is the
- * unbounded cache the whole `intl-cache.ts` bound exists to prevent.
- */
-export function canonicalLocale(locale: string): string | undefined {
-  try {
-    // `getCanonicalLocales` runs the same IsStructurallyValidLanguageTag check that
-    // `supportedLocalesOf` throws on, and unlike it, hands back the canonical spelling.
-    return Intl.getCanonicalLocales(locale)[0];
-  } catch {
-    return undefined;
-  }
-}