@ultimat3/time 16.0.0 → 17.0.0

package/CLAUDE.md

@@ -12,7 +12,6 @@
 | `zone-canonical.ts` | one zone, one key: `canonicalTimeZone` — the casing/alias collapse every cache keys on |
 | `zoned.ts` | `toZoned` / `fromZoned` + gap and overlap policies. Everything depends on this. |
 | `format.ts` | `Intl` rendering. Every function takes `locale` **and** `zone`. |
-| `locale.ts` | `assertLocale` — the ONE screen a caller-supplied BCP 47 tag passes before `Intl` |
 | `duration.ts` | `'2h30m'` ⇄ ms |
 | `cron.ts` | barrel over the three cron modules — the only one `index.ts` re-exports |
 | `cron-parse.ts` | field grammar → `CronExpression`. Non-integer, non-name tokens are rejected. |
@@ -52,14 +51,17 @@
   a code that has shipped since 1.0, with a runnable `fix:`, thrown by exactly one of nine callers.
   `format.ts` argued the pass-through decided "a cache key, never whether a locale is acceptable",
   which is true of the cache and was not an argument for letting the tag through. **Breaking at
-  9.x.** `assertLocale` (`locale.ts`) is the one screen and it VALIDATES AND CANONICALIZES in one
+  9.x.** `assertLocale` (**`@ultimat3/core`'s**, since 16.x — `locale.ts` is gone, because
+  `@ultimat3/money` needs the identical screen and tier 1 may not import sideways) is the one
+  screen and it VALIDATES AND CANONICALIZES in one
   step — `Intl.getCanonicalLocales` runs the same structural check `supportedLocalesOf` throws on
   and hands back the spelling the cache keys on, so there is no second question to ask. Well-formed
   but unknown to ICU (`zz`) is **not** refused: `Intl` falls back, and so must a rendered page.
 - **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, `assertLocale`
   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
+  `MAX_CACHED_FORMATTERS`, `canonicalLocale` and `assertLocale` are `@ultimat3/core`'s** — the
+  first three as of 2.0.0 and the screen as of 16.x, with `X_LOCALE_INVALID` moving with it — 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
@@ -141,6 +143,19 @@
 - 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`.
 - `m` is minutes, `ms` is milliseconds. A bare number is not a duration.
+- **`toMs`'s NUMBER arm is screened, `As of 2026-08-26`** — `finiteOption('toMs', 'duration', …)`.
+  The string arm has always been total, because `parseDuration` refuses everything it cannot read;
+  the number arm passed straight through, so `toMs(Number(process.env.TTL_MS))` on an unset
+  variable answered `NaN` and every `wakeAt > now` built from it read false forever — a sleep that
+  never ends and a timeout that never fires, with no error anywhere. `??` does not guard it: `NaN`
+  is not nullish. `@ultimat3/notify`'s `toDurationMs` had screened its own copy of the body and
+  this one had not, so one duration vocabulary gave two answers to one input (#372);
+  `packages/notify/src/plan-bounds.test.ts` calls BOTH on the same inputs and is what keeps them
+  from drifting apart again.
+  **`finiteOption`, never `finiteCount`**: a duration here is legitimately NEGATIVE —
+  `parseDuration` accepts a leading `-`, and `toSeconds(-3000)` is a tested `-3` — and legitimately
+  fractional. A caller that needs whole non-negative milliseconds narrows on top; narrowing here
+  breaks the signed-duration contract `toSeconds` is built on.
 - Tests must cover a spring-forward gap, a fall-back overlap and a non-hour offset zone.
 
 ## Commands

package/README.md

@@ -154,7 +154,7 @@ negated; an empty one is `0` in either direction, never `-0`.
 | `X_DST_AMBIGUOUS` | overlap hit with `overlap: 'throw'` |
 | `X_DST_NONEXISTENT` | gap hit with `gap: 'throw'` |
 | `X_INSTANT_INVALID` | unparseable timestamp |
-| `X_LOCALE_INVALID` | a tag `Intl` cannot parse (`en_US`, `''`) reached `describeCron` |
+| `X_LOCALE_INVALID` | a tag `Intl` cannot parse (`en_US`, `''`) reached any entry point taking a `locale`. Declared by `@ultimat3/core` `As of 2026-08`, thrown here unchanged — `@ultimat3/time` owned it until then. It answers **400**, not 500: the `locale` stage negotiates `Accept-Language` and never throws, so a tag that reaches this code came from a path, query or action input the caller wrote |
 | `X_CRON_NOT_DESCRIBABLE` | a valid 6-field cron whose seconds field `CronPhrases` has no words for |
 | `X_SCHEDULE_INVALID` | a wall-clock field out of range: `slot.hour`, `slot.minute`, `slot.second`, `slot.weekday` |
 

package/package.json

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

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 } from '@ultimat3/core';
+import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { type CronExpression, parseCronOnce } from './cron-parse';
 import { cronNotDescribable } from './errors';
-import { assertLocale } from './locale';
 
 export interface CronPhrases {
   everyMinute: string;

package/src/duration.ts

@@ -3,8 +3,8 @@
  * `step.sleep('3d')` in @ultimat3/jobs and every `retry.backoff` value comes through here.
  */
 
+import { assertLocale, finiteOption } from '@ultimat3/core';
 import { durationInvalid, scheduleInvalid } from './errors';
-import { assertLocale } from './locale';
 
 export const MS = 1;
 export const SECOND = 1000;
@@ -61,9 +61,25 @@ export function parseDuration(input: string): number {
   return (negative ? -1 : 1) * Math.round(total);
 }
 
-/** Parse-or-passthrough for APIs that accept either form. */
+/**
+ * Parse-or-passthrough for APIs that accept either form.
+ *
+ * The STRING arm has always been total — `parseDuration` refuses everything it cannot read. The
+ * NUMBER arm was the hole: it passed straight through, so `toMs(Number(process.env.TTL_MS))` on an
+ * unset variable answered `NaN`, and every `wakeAt > now` built from it reads false forever — a
+ * sleep that never ends, a timeout that never fires, no error anywhere. `??` does not guard it,
+ * because `NaN` is not nullish. `@ultimat3/notify` screened its own copy of this body and this one
+ * did not, so one duration vocabulary gave two answers to one input.
+ *
+ * `finiteOption`, not `finiteCount`: a duration here is legitimately NEGATIVE — `parseDuration`
+ * accepts a leading `-` and `toSeconds(-3000)` is a tested `-3` — and legitimately fractional.
+ * A caller that needs whole non-negative milliseconds narrows on top of this, which is what
+ * `@ultimat3/notify`'s `toDurationMs` does; narrowing here would break both.
+ */
 export function toMs(duration: string | number): number {
-  return typeof duration === 'number' ? duration : parseDuration(duration);
+  return typeof duration === 'number'
+    ? finiteOption('toMs', 'duration', duration)
+    : parseDuration(duration);
 }
 
 /**

package/src/errors.ts

@@ -1,6 +1,10 @@
 /**
  * The X_* error codes owned by @ultimat3/time.
  * DST ambiguity is a real state of the world, so it gets a code instead of a guess.
+ *
+ * `X_LOCALE_INVALID` is NOT here: it moved to `@ultimat3/core` beside `assertLocale`, because
+ * `@ultimat3/money` needs the same screen and tier 1 may not import sideways. A code has exactly
+ * one declaration — a second `registerErrorCodes` claim is `X_ERROR_CODE_DUPLICATE`.
  */
 
 import { registerErrorCodes, renderCauseValue, UltimateError } from '@ultimat3/core';
@@ -13,7 +17,6 @@ export const TIME_ERROR_CODES = [
   'X_DST_NONEXISTENT',
   'X_INSTANT_INVALID',
   'X_SCHEDULE_INVALID',
-  'X_LOCALE_INVALID',
   'X_CRON_NOT_DESCRIBABLE',
 ] as const;
 
@@ -27,7 +30,6 @@ export const TIME_ERROR_TITLES: Readonly<Record<TimeErrorCode, string>> = {
   X_DST_NONEXISTENT: 'the local time does not exist',
   X_INSTANT_INVALID: 'not a parseable instant',
   X_SCHEDULE_INVALID: 'a wall-clock field is out of range',
-  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
   X_CRON_NOT_DESCRIBABLE: 'a valid cron expression describeCron has no vocabulary for',
 };
 
@@ -123,19 +125,6 @@ export function dstNonexistent(wall: string, zone: string): TimeError {
   });
 }
 
-/**
- * A tag `Intl` cannot parse. Distinct from i18n's `X_LOCALE_UNSUPPORTED`, which is a
- * well-formed tag outside the app's supported set — this one is not a tag at all, and a raw
- * `RangeError` from a formatter says nothing about which caller supplied it.
- */
-export function localeInvalid(locale: string): TimeError {
-  return new TimeError({
-    code: 'X_LOCALE_INVALID',
-    cause: `"${locale}" is not a well-formed BCP 47 language tag`,
-    fix: "pass a tag like 'en', 'en-GB' or 'de-DE' — screen a header-supplied value with Intl.DateTimeFormat.supportedLocalesOf([tag]) before it reaches a formatter",
-  });
-}
-
 export function instantInvalid(input: string): TimeError {
   return new TimeError({
     code: 'X_INSTANT_INVALID',

package/src/format.ts

@@ -4,9 +4,8 @@
  * because "the server's timezone" is never the answer to "what time is it for the user".
  */
 
-import { cachedFormatter } from '@ultimat3/core';
+import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
-import { assertLocale } from './locale';
 import { isoDateInZone } from './zoned';
 import { assertTimeZone, type TimeZone } from './zones';
 

package/src/index.ts

@@ -1,5 +1,10 @@
 /** 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';
 export {
   addBusinessDays,
   type BusinessCalendar,
@@ -57,7 +62,6 @@ export {
   dstNonexistent,
   durationInvalid,
   instantInvalid,
-  localeInvalid,
   TIME_ERROR_CODES,
   TIME_ERROR_TITLES,
   TimeError,

package/src/zones.ts

@@ -4,10 +4,9 @@
  * is no offset table to keep in sync and no `date-fns-tz` dependency.
  */
 
-import { cachedFormatter } from '@ultimat3/core';
+import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { timezoneInvalid } from './errors';
 import type { Instant } from './instant';
-import { assertLocale } from './locale';
 import { canonicalTimeZone } from './zone-canonical';
 
 /** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */

package/src/locale.ts

@@ -1,24 +0,0 @@
-// Single responsibility: the one place a caller-supplied BCP 47 tag is screened before it reaches
-// an `Intl` constructor. One question, one answer (axiom 1) — `cron-describe.ts` refused a
-// malformed tag from the start while seven sibling formatters handed the raw string to `Intl` and
-// let a bare, uncoded `RangeError` escape several frames from the header it came out of.
-
-import { canonicalLocale } from '@ultimat3/core';
-import { localeInvalid } from './errors';
-
-/**
- * The canonical spelling of a well-formed tag, or `X_LOCALE_INVALID`.
- *
- * Validating and keying are one step: `Intl.getCanonicalLocales` runs exactly the structural check
- * `Intl.DateTimeFormat.supportedLocalesOf` throws on — which is what `localeInvalid`'s `fix:` tells
- * the caller to run — and unlike it hands back the spelling every formatter cache keys on, so
- * `EN-us` and `en-US` cannot mint two entries for one locale.
- *
- * Well-formed but unknown to this runtime's ICU (`zz`) is NOT refused: `Intl` falls back for those,
- * and a user carrying a locale the runtime has no data for must still get a rendered page.
- */
-export function assertLocale(locale: string): string {
-  const tag = canonicalLocale(locale);
-  if (tag === undefined) throw localeInvalid(locale);
-  return tag;
-}