@ultimat3/core 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -62,6 +62,7 @@ shape against a locally declared sample interface for exactly that reason.
 | `.env.example` | `env-example.ts` | a projection of the schema, never hand-maintained |
 | loading `.env` | **Bun**, not us | `envFileCandidates()` documents the measured order; there is no `.env.staging` |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one way out, on purpose greppable |
+| an `Intl` formatter cache | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `MAX_CACHED_FORMATTERS`) | a locale and a zone arrive from a request header, so the key must be canonical AND the cache bounded — never a second copy of either half |
 | the committed encrypted values | `secrets.ts` (envelope) + `secrets-store.ts` (files, `installSecrets`) | plaintext is a flat map of ENV NAMES; there is no `secrets.get()` |
 
 `installSecrets()` is the ONLY path from `secrets.enc.json` to an app value, and it lands in
@@ -70,6 +71,16 @@ shape against a locally declared sample interface for exactly that reason.
 implementations. The real environment always wins, which is what lets one image run in Compose and
 on K8s off one committed file.
 
+`intl-cache.ts` is tier 0 because two tier-1 packages need it and tier 1 may not import sideways.
+It was `@ultimat3/time`'s, internal, until 2.0.0, when `@ultimat3/money`'s `formatMoney` was found
+keyed raw on the caller's locale into an unbounded `Map` — 20,000 valid `en-US-x-*` tags from one
+`Accept-Language` header retained +55.1 MB of RSS (measured `As of 2026-08`). Copying the FIFO into
+`money` would have been a second answer to one question (axiom 1); `money → time` is a sideways
+import `bun run boundaries` refuses. The bound and the canonical key are **two halves of one rule**
+and live in one file for that reason: a canonical key bounds nothing (an unknown `-u-` extension
+value survives canonicalization as a distinct string) and the cap alone lets one locale evict
+itself under three spellings. Never build an `Intl` formatter on a caller string without both.
+
 `secrets-errors.ts` registers its seven codes through `registerErrorCodes()` rather than joining
 `CORE_CODE_TITLES` — the codes and the module that throws them ship together, and `registerErrorCodes`
 is the one mechanism that raises `X_ERROR_CODE_DUPLICATE` if anything else claims one. Consequence
@@ -214,6 +225,15 @@ Every `UltimateError` carries `retry` (`terminal | retryable | retry-after`), **
 registration path and it refuses to reclassify a core code, the same way `registerErrorStatus`
 refuses to remap one. A new code in any package should be classified beside its declaration.
 
+Two readers of that table, and picking the wrong one is a live defect. `retryFor(code)` answers
+*what to do* and fails closed; `declaredErrorRetry(code)` answers *what somebody declared* and is
+`undefined` when nobody did. `retry` on the instance is `init.retry ?? retryFor(code)`, so every
+unclassified error already reads `terminal` — a caller deciding whether to STOP work in flight
+(`@ultimat3/jobs`' executor) must read `declaredErrorRetry`, or it dead-letters attempt 1 of every
+job in every app whose codes nobody classified. An instance `retry: 'terminal'` on an **unregistered**
+code is indistinguishable from the default and is therefore read as unclassified; registering the
+code is the one way to have it honoured.
+
 Gotchas:
 - `exactOptionalPropertyTypes` is on — declare optional fields as `x?: T | undefined`.
 - `noPropertyAccessFromIndexSignature` is on — `ctx.services['mail']`, not `.mail`.

package/README.md

@@ -73,6 +73,16 @@ registerErrorRetry({ X_OAUTH_EXCHANGE_FAILED: 'retryable', X_RATE_LIMITED: 'retr
 Core's own classifications are closed, exactly as `registerErrorStatus`'s framework table is: a
 second, different registration for one code throws `X_ERROR_RETRY_INVALID`.
 
+**Two readers, and the difference is load-bearing.** `retryFor(code)` answers *what to do* and
+fails closed — `terminal` for a code nobody classified. `declaredErrorRetry(code)` answers *what
+somebody actually declared*, and is `undefined` when nobody did. `UltimateError.retry` is
+`init.retry ?? retryFor(code)`, so every unclassified error already carries `terminal`: a caller
+deciding whether to stop work already in flight reads `declaredErrorRetry`, and the job executor
+that read `retryFor` instead would dead-letter attempt 1 of every job in every app whose codes
+nobody has classified. An instance-level `retry: 'terminal'` on an **unregistered** code is
+indistinguishable from that default and is read as unclassified — register the code
+(`registerErrorRetry({ X_YOUR_CODE: 'terminal' })`), which is the one way.
+
 | Code | Subclass |
 |---|---|
 | `X_CONFIG_INVALID` | `ConfigInvalidError` |
@@ -423,6 +433,34 @@ never a silently wrong page.
 | `usesDevCursorSecret()` | true while the shipped dev key is in use |
 | `resetCursorSigning()` | test seam: forget `configureCursorSigning` and fall back to the environment |
 
+## One bounded cache for every `Intl` formatter
+
+```ts
+import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+
+const cache = new Map<string, Intl.NumberFormat>();
+
+export function euroFormatter(locale: string): Intl.NumberFormat {
+  // `EN-us` and `en-latn-us` collapse to one key, so one locale cannot evict itself.
+  const tag = canonicalLocale(locale) ?? locale;
+  return cachedFormatter(
+    cache,
+    `${tag}|EUR`,
+    () => new Intl.NumberFormat(tag, { style: 'currency', currency: 'EUR' }),
+  );
+}
+```
+
+A locale arrives from `Accept-Language` and a zone from `x-timezone`, so an unbounded `Map` keyed
+on that string is **memory the client chooses**. Measured `As of 2026-08`: 4,096 casings of one
+zone name retained 31 MB, and 20,000 valid `en-US-x-*` tags through `formatMoney` retained 55.1 MB.
+The bound
+(`MAX_CACHED_FORMATTERS`, 512, FIFO) and the canonical key are two halves of one rule and neither
+is sufficient alone — an unknown `-u-` extension value survives canonicalization as a distinct
+string, and the cap alone lets one locale evict itself under three spellings. A miss costs one
+`Intl` construction, never a wrong answer, which is what makes the bound safe. It lives here rather
+than in `@ultimat3/time` because `@ultimat3/money` needs it too and tier 1 may not import sideways.
+
 ## One image pipeline, everywhere
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/error-codes.ts

@@ -46,7 +46,8 @@ const CORE_CODE_TITLES = {
   X_INVARIANT: 'invariant violated',
   X_METRIC_CARDINALITY:
     'a metric exceeded its series ceiling and is folding into one overflow series',
-  X_METRIC_NAME_INVALID: 'metric name is malformed or already declared with another kind',
+  X_METRIC_NAME_INVALID:
+    'metric name is malformed, or redeclared with a different kind, bounds or observer',
   X_METRIC_VALUE_INVALID: 'metric value is not recordable',
   X_NO_CONTEXT: 'no request context is active',
   X_NOT_IMPLEMENTED: 'this driver does not implement the requested feature',

package/src/error-retry.ts

@@ -87,11 +87,23 @@ export function resetErrorRetry(): void {
   REGISTERED.clear();
 }
 
-// Core table first: `registerErrorRetry` already refuses those codes, so the order is
-// belt-and-braces — but it is the belt that keeps "core's classifications are fixed" true even if
-// a future caller reaches the map some other way.
+/**
+ * The classification somebody actually DECLARED for this code, `undefined` when nobody did.
+ *
+ * `retryFor` answers a client's question — "may I send this again?" — and fails closed, so it
+ * cannot tell a code declared `terminal` from a code nobody classified. A caller deciding whether
+ * to STOP work already in flight has to tell them apart: the job executor reads this, because
+ * treating every unclassified code as `terminal` would end the retry policy of every job in every
+ * shipped app, which is a far larger fault than the one that reading brings.
+ *
+ * Core table first, for the same belt-and-braces reason `retryFor` had it first.
+ */
+export function declaredErrorRetry(code: string): ErrorRetry | undefined {
+  return CORE_ERROR_RETRY[code] ?? REGISTERED.get(code);
+}
+
 export function retryFor(code: string): ErrorRetry {
-  return CORE_ERROR_RETRY[code] ?? REGISTERED.get(code) ?? DEFAULT_ERROR_RETRY;
+  return declaredErrorRetry(code) ?? DEFAULT_ERROR_RETRY;
 }
 
 /** Every classification a package or app declared, for `x errors list` and the manifest. */

package/src/exports/error-contract.ts

@@ -32,6 +32,7 @@ export {
 export type { ErrorRetry } from '../error-retry';
 export {
   DEFAULT_ERROR_RETRY,
+  declaredErrorRetry,
   ERROR_RETRY_KINDS,
   isErrorRetry,
   registerErrorRetry,

package/src/index.ts

@@ -130,6 +130,7 @@ export {
   CORE_ERROR_CODES,
   ConfigInvalidError,
   DEFAULT_ERROR_RETRY,
+  declaredErrorRetry,
   describeErrorCode,
   describeValue,
   EnvMissingError,
@@ -427,6 +428,7 @@ export {
 export type { ImageFit, ResizeSpec } from './image/resize';
 export { fitBox, resizeRaster, scaledToFit } from './image/resize';
 export { impersonate, impersonationReason, isImpersonating } from './impersonate';
+export { cachedFormatter, canonicalLocale, MAX_CACHED_FORMATTERS } from './intl-cache';
 export type {
   HealthPayload,
   HealthReport,

package/src/intl-cache.ts

@@ -0,0 +1,43 @@
+// One bounded cache, on one canonical key, for every `Intl` formatter the framework builds.
+// A locale and a zone both arrive from a request header, so an unbounded `Map` keyed on the
+// caller's spelling is memory the client chooses — 31 MB and 55.1 MB, measured `As of 2026-08` and
+// written up in the README. The bound and the canonical key are two halves of ONE rule.
+
+/**
+ * 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 {
+  // Membership decides, never truthiness: `T` is the caller's, so a stored `undefined` is a hit.
+  // The cast is sound because `has` just proved the key is present, which `get`'s signature cannot.
+  if (cache.has(key)) return cache.get(key) as T;
+  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;
+}
+
+/**
+ * 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 bound above 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;
+  }
+}

package/src/lifecycle.ts

@@ -6,7 +6,7 @@ import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
-import { type Logger, logger as rootLogger } from './logger';
+import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
 
@@ -165,6 +165,33 @@ export function readinessCheckCount(): number {
   return readiness.size;
 }
 
+/**
+ * Every line this file emits, and the only way it emits one. `log` is an injection seam
+ * (`configureLifecycle({ logger })`), so an app's `Logger` decides whether a log call can throw —
+ * and a throw here does not lose a line, it replaces the event. Inside `drain()` it rejected
+ * `drainPromise`: `state` never reached 'stopped', the memo re-rejected for every later caller,
+ * and on Bun the unhandled rejection ended the process the drain was trying to end cleanly.
+ * Inside `readinessChecks()` it replaced the probe's answer with a throw.
+ *
+ * A lifecycle that cannot report is still a lifecycle: the line falls back to core's own
+ * `rootLogger`, which is total by construction (`logger.ts`), and failing that is dropped.
+ */
+function report(level: 'info' | 'warn' | 'error', message: string, fields: LogFields): void {
+  try {
+    log[level](message, fields);
+    return;
+  } catch {
+    // Fall through — the injected sink is gone, and the fallback below is the last one there is.
+  }
+  if (log === rootLogger) return;
+  try {
+    rootLogger[level](message, fields);
+  } catch {
+    // Both sinks are gone. Dropping the line is the only remaining option that still ends the
+    // process, which is the outcome every caller of this file depends on.
+  }
+}
+
 /** Every check, run now, by name. A check that throws is `failing` — never an unhandled error. */
 export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
   const results: Record<string, ReadinessStatus> = {};
@@ -173,7 +200,7 @@ export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
       results[name] = check() ? 'ok' : 'failing';
     } catch (thrown) {
       results[name] = 'failing';
-      log.warn('readiness check threw', { check: name, error: thrown });
+      report('warn', 'readiness check threw', { check: name, error: thrown });
     }
   }
   return results;
@@ -278,7 +305,7 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
   for (const registration of registrations.filter((entry) => entry.phase === phase)) {
     const outcome = await settleWithin(() => registration.hook(reason), remainingBudget(reason));
     if (outcome.kind === 'failed') {
-      log.error('shutdown hook failed', {
+      report('error', 'shutdown hook failed', {
         hook: registration.name,
         phase,
         error: outcome.error,
@@ -290,7 +317,7 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
       // SIGKILL this process — the every-deploy duplicate that draining exists to prevent — so
       // the drain moves on and the hook is left running with nobody reading it. The cost of that
       // choice is real and named in the cause: a write it had in flight may be half done.
-      log.warn('X_SHUTDOWN_TIMEOUT', {
+      report('warn', 'X_SHUTDOWN_TIMEOUT', {
         code: 'X_SHUTDOWN_TIMEOUT',
         cause: `the "${registration.name}" shutdown hook (phase: ${phase}) was still running at the ${deadlineMs}ms drain deadline and has been ABANDONED — the process exits without it, so anything it had in flight may be incomplete`,
         fix: `raise the budget past the work this hook does — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute job — and set terminationGracePeriodSeconds to at least as many seconds, or make the "${registration.name}" hook return once it has stopped accepting work rather than once it has finished`,
@@ -308,25 +335,34 @@ export function drain(signal = 'manual'): Promise<void> {
   const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
 
   drainPromise = (async () => {
-    log.info('draining', { signal, deadlineMs, inflight });
-    await runPhase('accept', reason);
-
-    // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and a
-    // budget read off an injected clock is a number that timer will never honour.
-    const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
-    const idle = await waitForIdle(remaining);
-    if (!idle) {
-      log.warn('X_SHUTDOWN_TIMEOUT', {
-        code: 'X_SHUTDOWN_TIMEOUT',
-        cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
-        fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
-      });
+    try {
+      report('info', 'draining', { signal, deadlineMs, inflight });
+      await runPhase('accept', reason);
+
+      // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
+      // a budget read off an injected clock is a number that timer will never honour.
+      const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
+      const idle = await waitForIdle(remaining);
+      if (!idle) {
+        report('warn', 'X_SHUTDOWN_TIMEOUT', {
+          code: 'X_SHUTDOWN_TIMEOUT',
+          cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
+          fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
+        });
+      }
+
+      await runPhase('inflight', reason);
+      await runPhase('close', reason);
+    } catch (thrown) {
+      // Nothing above should reach here — every hook is caught by `settleWithin` and every line
+      // goes through `report`. If something does, the drain still ENDS: a rejected `drainPromise`
+      // is a memo that re-rejects for every later caller and an unhandled rejection that kills the
+      // process mid-drain, which is strictly worse than a drain that finished badly and said so.
+      report('error', 'drain failed', { signal, error: thrown });
+    } finally {
+      state = 'stopped';
     }
-
-    await runPhase('inflight', reason);
-    await runPhase('close', reason);
-    state = 'stopped';
-    log.info('stopped', { signal });
+    report('info', 'stopped', { signal });
   })();
 
   return drainPromise;
@@ -345,9 +381,14 @@ export function installSignalHandlers(options?: SignalHandlerOptions): () => voi
 
   for (const signal of signals) {
     const handler = (): void => {
-      void drain(signal).then(() => {
+      // Attached on BOTH settle paths, for the reason `settleWithin` gives: an unhandled rejection
+      // ends the process before the drain does, and the exit is what the kubelet is waiting for.
+      // `drain()` cannot reject today — that is the `try/finally` above, not luck — and this is
+      // the one line that keeps it true when someone changes the body.
+      const done = (): void => {
         if (options?.exit === true) process.exit(0);
-      });
+      };
+      void drain(signal).then(done, done);
     };
     handlers.set(signal, handler);
     process.on(signal, handler);

package/src/metrics.ts

@@ -111,12 +111,20 @@ export interface InstrumentOptions {
 }
 
 export interface GaugeOptions extends InstrumentOptions {
-  /** Async instrument: read at collection time instead of being pushed. Never stale. */
+  /**
+   * Async instrument: read at collection time instead of being pushed. Never stale.
+   * Stated twice for one name with two different callbacks is `X_METRIC_NAME_INVALID`, not a
+   * silent win for the first — see `assertSameDeclaration`.
+   */
   readonly observe?: (() => number) | undefined;
 }
 
 export interface HistogramOptions extends InstrumentOptions {
-  /** Explicit bucket boundaries, ascending. Defaults to the OTel latency-in-seconds set. */
+  /**
+   * Explicit bucket boundaries, ascending. Defaults to the OTel latency-in-seconds set.
+   * Stated twice for one name with two different sets is `X_METRIC_NAME_INVALID`, not a silent
+   * win for the first — see `assertSameDeclaration`.
+   */
   readonly bounds?: readonly number[] | undefined;
 }
 
@@ -263,6 +271,7 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
         meta: { name, declared: existing.descriptor.kind, requested: kind },
       });
     }
+    assertSameDeclaration(name, existing, options);
     return existing;
   }
   const maxSeries = options.maxSeries ?? DEFAULT_MAX_SERIES;
@@ -290,6 +299,39 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
   return instrument;
 }
 
+/**
+ * A second declaration that STATES a different shape is refused. The first declaration wins, so a
+ * second `histogram(name, { bounds })` recorded into buckets another module chose and a second
+ * `gauge(name, { observe })` was collected through the first module's observer — silently, in both
+ * cases, which is the whole failure. An OMITTED option is not a conflict: `gauge(name)` is how a
+ * module takes a handle on an instrument someone else declared, and `maxSeries` keeps its shipped
+ * first-declaration-wins rule because it decides a ceiling rather than what gets recorded.
+ */
+function assertSameDeclaration(
+  name: string,
+  existing: Instrument,
+  options: GaugeOptions & HistogramOptions,
+): void {
+  const { bounds, observe } = options;
+  if (bounds !== undefined && !sameBounds(existing.bounds, bounds)) {
+    throw new MetricNameInvalidError({
+      cause: `"${name}" is already declared with bounds [${existing.bounds.join(', ')}] and is redeclared with [${bounds.join(', ')}]; the first declaration wins, so the second set would never be used`,
+      fix: `declare "${name}" once and export the handle — import it where you record — or give the second instrument its own name`,
+      meta: { name, declared: existing.bounds.join(','), requested: bounds.join(',') },
+    });
+  }
+  if (observe !== undefined && observe !== existing.observe) {
+    throw new MetricNameInvalidError({
+      cause: `"${name}" is already declared with an observe() callback and is redeclared with a different one; the first declaration wins, so the second callback would never be read`,
+      fix: `declare "${name}" once and export the handle — import it where you read — or give the second gauge its own name`,
+      meta: { name },
+    });
+  }
+}
+
+const sameBounds = (left: readonly number[], right: readonly number[]): boolean =>
+  left.length === right.length && left.every((bound, index) => bound === right[index]);
+
 /**
  * Reported through the logger rather than thrown: the call site is `orderCounter.add(1, …)` deep
  * inside a request, and killing that request would turn a metrics bug into a user-visible outage