@ultimat3/core 2.0.0 → 4.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
@@ -90,6 +101,32 @@ the pin (`schema-error-codes-pin.test.ts`) lives in `@ultimat3/cli`, which may l
 `@ultimat3/storage` both need — core is the lowest tier both can reach, so the shared code lives
 here rather than in either package copying the other's file.
 
+`canonical-json.ts` is the same shape for the hash every SHARING key in the framework is taken
+over, `As of 2026-08`. `canonicalJson` is an INJECTIVE canonical form and `fingerprint` is
+SHA-256/16 of it, and three tier-3 packages needed exactly this while none may import another:
+`@ultimat3/action`'s `requestHash` and job dedupe key, `@ultimat3/query`'s `queryHash` (a
+read-cache entry, a cursor scope, a live query id) and `@ultimat3/realtime`'s `qid`. Each kept its
+own copy and the copies had **diverged in a way that leaked**: query's had no `Date` branch, so
+`Object.keys(date)` was `[]`, every date rendered `{}`, and one cache key, one cursor scope and one
+live window answered for every date window of a read — reachable straight off a query string, since
+`coerceQuery` turns a `t.date` member into a real `Date`. Injective is the whole requirement, not a
+formatting preference: every one of those keys decides which of two callers is served the other's
+answer. So `NaN`, `±Infinity` and `-0` are bare tokens the quoting `string` branch cannot spell,
+and a `Date`, a `Map` and a `Set` — the three values with no own enumerable key — are TAGGED. Never
+add a fourth copy, and never make it parseable: `@ultimat3/action`'s `stableStringify` is the
+DOCUMENT form for that (it publishes `openapi.json`), and it is a different function on purpose.
+
+`decimal-order.ts` is the third instance of the same rule, over a value rather than a shape.
+`compareDecimalText` is the exact ordering of two decimals however long the digits run — the order
+Postgres gives a `numeric` or an `int8` over the TEXT `@ultimat3/entity`'s `bigint()` and
+`decimal()` hand back, where `String(left) < String(right)` answers `["10","100","2","9"]` for
+`["2","9","10","100"]` and cuts a keyset page where the database does not. It answers **`undefined`**
+when either side is not a plain decimal, and that is the contract, not a convenience: a caller that
+knows the column's declared kind asks (`@ultimat3/entity`'s `compareByKind`), and a caller that does
+NOT — `@ultimat3/query`, whose `OrderKey` is a name and a direction — must never, because Postgres
+orders a `text` column of digits lexically and a comparator guessing would trade one disagreement
+with the SQL it printed for another.
+
 `mcp-exposure.ts` is the same shape for a declaration rather than an algorithm: `isMcpExposed` is
 the ONE answer to "did this primitive opt into being an MCP tool?", asked by `action`, `query`
 (t3), `mcp`, `ai`, `manifest` (t4) — five packages that cannot import each other, so core is the
@@ -214,6 +251,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` |
@@ -333,6 +343,7 @@ collectMetrics();       // the same numbers as data, for a MetricExporter
 | Names | lowercase `snake_case`, the intersection every exposition format accepts. Dotted OTel names survive OTLP and die at a Prometheus scrape |
 | Attributes | `string \| number \| boolean` only — each distinct set is a stored series, so a user id here is an outage |
 | Cardinality | enforced, not advised: `maxSeries` per instrument (default `DEFAULT_MAX_SERIES`), and past it every new label set folds into one `otel_metric_overflow="true"` series with `X_METRIC_CARDINALITY` logged once, naming the instrument |
+| Async gauges | an `observe()` that throws, or answers a non-finite number, costs that instrument its point and **nothing beside it** — `X_METRIC_VALUE_INVALID` logged once, naming the instrument. Unguarded it took the whole `/metrics` body down with it, and `startMetricExport`'s timer callback raised where nothing can catch it |
 | Driver seam | `MetricExporter`, defaulting to a no-op. `memoryMetricExporter()` for tests, `startMetricExport(ms)` for a periodic push, `otlpMetricExporter()` for a collector |
 
 `runtime-metrics.ts` holds the series every process emits, and `SCALING_METRICS` maps each
@@ -423,6 +434,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": "4.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/actor.ts

@@ -76,8 +76,27 @@ export interface Actor {
   readonly orgId?: string | undefined;
   /** Application roles (`admin`, `editor`). Unrelated to the runtime `Role`. */
   readonly roles: readonly string[];
-  /** Capability strings a policy can require (`post:publish`). */
+  /**
+   * FRAMEWORK capabilities, checked with `hasScope()`. One reader in the whole framework —
+   * `@ultimat3/entity`'s `crossTenant()`, gating `tenancy:cross` — and that narrowness is the
+   * point: a scope is an escape hatch the framework itself honours, never the app's authz
+   * vocabulary. That is `roles` and `permissions`, which `@ultimat3/policy` reads.
+   */
   readonly scopes: readonly string[];
+  /**
+   * DIRECT grants, bypassing roles: what a service token or a break-glass account holds
+   * (`post:publish`). `@ultimat3/policy` flattens these together with every grant `roles` expands
+   * to, so the two are one set by the time a predicate runs, and neither is `scopes`.
+   *
+   * Declared here rather than on policy's own `Actor` (`As of 2026-08-19`). It was policy's, which
+   * made it unreachable from the one place actors are built: core is tier 0 and cannot import
+   * policy, so `build()` below had no field to carry and `userActor({ permissions })` compiled and
+   * silently discarded the argument. Every caller worked around it with
+   * `{ ...userActor({ id }), permissions: [...] }` — a spread over a frozen actor, producing an
+   * UNFROZEN one — so the fixtures proving authz had a shape no request ever mints. `@ultimat3/auth`
+   * carried a second, hand-synced copy of the declaration for the same tier reason.
+   */
+  readonly permissions: readonly string[];
   /** App-declared facts. Read it through `actorFact()`; never logged — `actorLabel` is id-only. */
   readonly facts?: ActorFactMap | undefined;
   /**
@@ -93,6 +112,8 @@ export interface ActorInit {
   readonly orgId?: string | undefined;
   readonly roles?: readonly string[] | undefined;
   readonly scopes?: readonly string[] | undefined;
+  /** Direct grants. Absent means none — never "inherit some"; there is nothing to inherit from. */
+  readonly permissions?: readonly string[] | undefined;
   readonly facts?: ActorFactMap | undefined;
   /** For a session that already recorded an impersonation; `impersonate()` sets it otherwise. */
   readonly onBehalfOf?: ActorOrigin | undefined;
@@ -105,6 +126,7 @@ const ANONYMOUS: Actor = Object.freeze({
   id: 'anonymous',
   roles: Object.freeze([]),
   scopes: Object.freeze([]),
+  permissions: Object.freeze([]),
   facts: NO_FACTS,
 });
 
@@ -115,6 +137,10 @@ function build(kind: ActorKind, init: ActorInit): Actor {
     orgId: init.orgId,
     roles: Object.freeze([...(init.roles ?? [])]),
     scopes: Object.freeze([...(init.scopes ?? [])]),
+    // Copied and frozen like the two above, and for the sharper reason: this list IS the actor's
+    // authz. Handing back the caller's array would let whoever still holds it `push` a grant into
+    // a decision already made about a frozen actor.
+    permissions: Object.freeze([...(init.permissions ?? [])]),
     facts: Object.freeze({ ...init.facts }),
     onBehalfOf: init.onBehalfOf === undefined ? undefined : Object.freeze({ ...init.onBehalfOf }),
   });

package/src/canonical-json.ts

@@ -0,0 +1,102 @@
+/**
+ * The INJECTIVE canonical form of a value, and the sharing key taken over it.
+ *
+ * Tier 0 because three tier-3 packages need exactly this and none of them may import another:
+ * `@ultimat3/action`'s `requestHash` and job dedupe key, `@ultimat3/query`'s `queryHash` (the
+ * read-cache entry, the cursor scope, the live query id) and `@ultimat3/realtime`'s `qid`. Each
+ * kept its own copy, and the copies had already diverged — query's rendered every `Date` as `{}`,
+ * so one key answered for every date window a read ever served.
+ *
+ * Injective is the whole requirement: every one of those keys decides which of two callers is
+ * served the other's answer, so two distinct inputs sharing one string is a leak and not a
+ * collision. Nothing here is ever parsed back — `@ultimat3/action`'s `stableStringify` is the
+ * DOCUMENT form for that, and it is a different function on purpose.
+ */
+
+/**
+ * Bare tokens, never quoted and never `'null'`. This output is only ever hashed, so an unquoted
+ * word cannot collide with the `string` branch (which always quotes), while `'null'` collided with
+ * JSON `null` itself — `{ n: NaN }`, `{ n: Infinity }`, `{ n: -Infinity }` and `{ n: null }` were
+ * one key and therefore one idempotency record, one cache entry and one cursor scope. `-0` is
+ * spelled out for the same reason: `String(-0)` is `"0"`.
+ */
+function hashNumber(value: number): string {
+  if (Number.isNaN(value)) return 'NaN';
+  if (!Number.isFinite(value)) return value > 0 ? 'Infinity' : '-Infinity';
+  return Object.is(value, -0) ? '-0' : String(value);
+}
+
+/**
+ * The epoch, TAGGED — the same per-type tagging `hashNumber` uses for `NaN` and `-0`, for the same
+ * reason. Untagged, a `t.date` field and a `t.number` field holding that field's epoch would be one
+ * key, which is the collision this form exists to refuse; an Invalid Date would be the bare `NaN`
+ * token a `t.number` field already owns.
+ */
+function hashDate(value: Date): string {
+  return `Date(${hashNumber(value.getTime())})`;
+}
+
+/**
+ * Tagged for the reason a `Date` is: a `Map`, a `Set` and `{}` all have no own enumerable key, so
+ * the object branch rendered all three `{}` and one hash answered for three payloads sharing
+ * nothing. Entries are SORTED, as an object's keys are: insertion order is not part of what a Map
+ * or a Set holds, so two spellings of one payload stay one key.
+ */
+function hashCollection(value: Map<unknown, unknown> | Set<unknown>): string {
+  const entries =
+    value instanceof Map
+      ? [...value].map(([key, item]) => `${canonicalJson(key)}:${canonicalJson(item)}`)
+      : [...value].map((item) => canonicalJson(item));
+  return `${value instanceof Map ? 'Map' : 'Set'}(${entries.sort().join(',')})`;
+}
+
+/**
+ * JSON with object keys sorted at every depth, and every value a JSON document would fold onto
+ * `null` or `{}` given a token of its own. No timestamps, no insertion-order leaks.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'number':
+      return hashNumber(value);
+    case 'boolean':
+      return String(value);
+    case 'bigint':
+      return JSON.stringify(`${value}n`);
+    case 'undefined':
+    case 'function':
+    case 'symbol':
+      return 'null';
+    default:
+      break;
+  }
+  // Ahead of the object branch, because none of the three has an own enumerable key: `Object.keys`
+  // is empty for all of them and the branch below would answer `{}` for every date, every map and
+  // every set alike.
+  if (value instanceof Date) return hashDate(value);
+  if (value instanceof Map || value instanceof Set) return hashCollection(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record)
+    .filter((key) => record[key] !== undefined)
+    .sort();
+  const entries = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+  return `{${entries.join(',')}}`;
+}
+
+/**
+ * SHA-256, first 16 hex characters — the same primitive and width `@ultimat3/entity`'s `planScope`
+ * already chose, and for the same reason.
+ *
+ * This is a SHARING key over input a client chooses, not a checksum. It decides "same request,
+ * replay the stored response", which read-cache entry two callers are served from, which scope a
+ * cursor is bound to and which subscribers are served out of one live window — so a collision
+ * hands one caller another's rows. FNV-1a/32, which two of the three copies started as, is
+ * 4x10^9 values and brute-forceable offline in seconds: an input landing on another read's key was
+ * something an attacker could mint rather than something they had to wait for.
+ */
+export function fingerprint(value: unknown): string {
+  return new Bun.CryptoHasher('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);
+}

package/src/config.ts

@@ -28,13 +28,28 @@ export interface ThemeConfig {
  */
 export interface AuthConfig {
   readonly signInPath: string | null;
-  /** Where sign-in lands when there is nowhere to return to, or `?next=` is not same-origin. */
+  /**
+   * Where sign-in lands when there is nowhere to return to, or `?next=` is not same-origin.
+   *
+   * **Consulted by nothing, `As of 2026-08.`** Accepted, defaulted and merged here and read by no
+   * file in the repo — `dummy/social-media-clone/app.config.ts` sets `/dashboard` and gets
+   * whatever the sign-in route does on its own. Same shape `urlEnv`, `poolSize` and `schema` were
+   * deleted for below; this one is not deleted yet only because its writer is a tracked app's
+   * config, so removing the key and the line that sets it is one commit across two file sets.
+   */
   readonly afterSignInPath: string;
 }
 
 export interface PwaConfig {
   readonly enabled: boolean;
   readonly offline: OfflineStrategy;
+  /**
+   * **Consulted by nothing, `As of 2026-08.`** `wiki/Configuration.md` describes it as "render
+   * your own install affordance from the deferred event", both tracked apps set it, and
+   * `x new`'s scaffold writes it into every generated app — and no file reads it.
+   * `@ultimat3/pwa`'s `install.ts` is real and complete; nothing threads this flag into it.
+   * Delete the key or thread it; leaving it is a switch with no wire.
+   */
   readonly installPrompt: boolean;
   readonly backgroundSync: boolean;
   readonly push: boolean;
@@ -76,12 +91,18 @@ export interface JobsConfig {
   readonly visibilityTimeoutMs: number;
 }
 
+/**
+ * No `heartbeatMs`. It was declared here, defaulted to 15_000, and read by NOTHING — deleted
+ * 2026-08-19. The socket beat is `new LiveClient({ heartbeatMs })`, browser code that cannot read
+ * server config, and the presence beat is DERIVED (`PresenceRegistry.heartbeatMs` is
+ * `max(1000, floor(ttlMs / 3))`). A second knob is a second number that can disagree with the one
+ * it is a fraction of, and a knob nothing reads is a knob nothing enforces — axioms 1 and 3.
+ */
 export interface RealtimeConfig {
   readonly enabled: boolean;
   readonly tier: RealtimeTier;
   readonly transport: RealtimeTransport;
   readonly urlEnv: string | undefined;
-  readonly heartbeatMs: number;
 }
 
 export interface McpConfig {
@@ -91,7 +112,15 @@ export interface McpConfig {
 
 export interface AiConfig {
   readonly mcp: McpConfig;
-  /** Env key for the model id, so no model string is baked into the image. */
+  /**
+   * Env key for the model id, so no model string is baked into the image — **an intention, not a
+   * behaviour, `As of 2026-08`.** The only read of it in the repo is the merge two hundred lines
+   * below, which copies it from input to output; nothing consumes the merged value, so
+   * `examples/dummy`'s `modelEnv: 'ANTHROPIC_MODEL'` selects no model. `@ultimat3/ai` reads env
+   * for API KEYS only (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`); the model is
+   * `request.model ?? DEFAULT_MODEL`, a compile-time constant in `models.ts`. So the exact thing
+   * this key exists to prevent — a model string baked into the image — is what actually happens.
+   */
   readonly modelEnv: string | undefined;
 }
 
@@ -210,13 +239,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       backoff: 'exponential',
       visibilityTimeoutMs: 30_000,
     },
-    realtime: {
-      enabled: false,
-      tier: 'channels',
-      transport: 'memory',
-      urlEnv: undefined,
-      heartbeatMs: 15_000,
-    },
+    realtime: { enabled: false, tier: 'channels', transport: 'memory', urlEnv: undefined },
     ai: { mcp: { expose: true, path: '/mcp' }, modelEnv: undefined },
   };
 }

package/src/decimal-order.ts

@@ -0,0 +1,76 @@
+/**
+ * Two decimals compared EXACTLY, however long the digits run — the ordering Postgres gives a
+ * `numeric` or an `int8`, over the TEXT those columns' row values are.
+ *
+ * Tier 0 because the values are text and the fix has to be available wherever they arrive.
+ * `@ultimat3/entity`'s `bigint()` and `decimal()` both hand digits back as a string on purpose — a
+ * JS `bigint` is what `JSON.stringify` throws on and a `number` loses digits past 2^53, exactly
+ * where a legacy `int8` key lives — so no `typeof` branch catches them: `String(left) <
+ * String(right)` answered `["10","100","2","9"]` where the database answers `["2","9","10","100"]`,
+ * and a keyset page boundary was cut where the database never cuts one.
+ *
+ * It answers `undefined` rather than guessing, and that is the whole of its contract: a caller
+ * that knows the column's declared kind (`@ultimat3/entity`'s `compareByKind`) asks; a caller that
+ * does NOT know it — `@ultimat3/query`, whose `OrderKey` is a name and a direction — must not,
+ * because Postgres orders a `text` column holding `"10"` and `"9"` lexically and a comparator
+ * guessing "both sides look like decimals" would disagree with the SQL it printed.
+ */
+
+/** A decimal, split so two of them can be compared exactly however long the digits run. */
+interface Decimal {
+  readonly negative: boolean;
+  readonly whole: string;
+  readonly fraction: string;
+}
+
+const DECIMAL_SHAPE = /^([+-]?)(\d+)(?:\.(\d*))?$/;
+
+/**
+ * The digits, or `undefined` for anything that is not a plain decimal — an exponent
+ * (`String(1e21)` is `"1e+21"`), a `NaN`, an empty string. Those are not values a `numeric` column
+ * can hold, so they are not values Postgres would be ordering either.
+ */
+function decimalOf(value: unknown): Decimal | undefined {
+  const text =
+    typeof value === 'bigint' || typeof value === 'number'
+      ? String(value)
+      : typeof value === 'string'
+        ? value.trim()
+        : undefined;
+  const parts = text === undefined ? null : DECIMAL_SHAPE.exec(text);
+  const whole = parts?.[2];
+  if (parts === null || whole === undefined) return undefined;
+  return { negative: parts[1] === '-', whole, fraction: parts[3] ?? '' };
+}
+
+/**
+ * Exact at any width: the fractions are padded to one length and both sides become one integer, so
+ * a 38-digit `numeric` orders by its digits rather than by whatever a `Number` rounded it to.
+ */
+function compare(left: Decimal, right: Decimal): number {
+  if (left.negative !== right.negative) return left.negative ? -1 : 1;
+  const width = Math.max(left.fraction.length, right.fraction.length);
+  const scaled = (value: Decimal): bigint =>
+    BigInt(`${value.whole}${value.fraction.padEnd(width, '0')}`);
+  const first = scaled(left);
+  const second = scaled(right);
+  // Never a subtraction: the difference between two `bigint`s is exact and the return type is a
+  // `number`, which cannot hold it.
+  const order = first < second ? -1 : first > second ? 1 : 0;
+  // Guarded rather than negated: `-0` is a different value from `0` to `Object.is` and to a caller
+  // writing `=== 0`, and two equal negatives are a tie.
+  return left.negative && order !== 0 ? -order : order;
+}
+
+/**
+ * `-1`, `0` or `1` for two plain decimals; `undefined` when EITHER side is not one.
+ *
+ * Both, or neither: one decimal against a value that is not one is not a numeric comparison, and
+ * answering for that pair would order a mixed column by a rule the database does not use.
+ */
+export function compareDecimalText(left: unknown, right: unknown): number | undefined {
+  const first = decimalOf(left);
+  if (first === undefined) return undefined;
+  const second = decimalOf(right);
+  return second === undefined ? undefined : compare(first, second);
+}

package/src/env-example.ts

@@ -96,7 +96,15 @@ export interface EnvExampleReport {
   readonly ok: boolean;
   /** Declared in the schema, absent from the file. Always a defect. */
   readonly missing: readonly string[];
-  /** In the file, not in the schema. Reported, never fatal — apps set keys nothing declares. */
+  /**
+   * In the file, not in the schema — never fatal, because apps set keys nothing declares.
+   *
+   * NOT reported on its own, and the comment here said it was. `ok` is `missing.length === 0`, so
+   * an example carrying only extra keys returns `ok: true` and `assertEnvExample` never builds an
+   * error: the list reaches a surface only as `meta` on a drift some MISSING key already raised.
+   * A caller that wants it reads `checkEnvExample(...).extra` itself, which is why this stays
+   * public. `env-example.test.ts` pins both halves.
+   */
   readonly extra: readonly string[];
 }
 

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

@@ -27,15 +27,29 @@ export const DEFAULT_ERROR_RETRY: ErrorRetry = 'terminal';
  * app whose clients stop retrying a rolling restart, which is the one case retrying always wins.
  * Only the exceptions are listed — everything else is `terminal` by the default above.
  */
-const CORE_ERROR_RETRY: Readonly<Record<string, ErrorRetry>> = Object.freeze({
-  X_DRAINING: 'retryable',
-  // A deadline that expired is the canonical back-off-and-try-again case: nothing about the
-  // request was wrong, the budget ran out. Deliberately NOT `retry-after` — that spelling means
-  // the responder named a time, and a timeout by definition produced no such answer. Its twin
-  // `X_ABORTED` (the caller went away) is left to the `terminal` DEFAULT rather than listed here:
-  // the answer is the same, and listing it would close a door nobody has asked to open.
-  X_TIMEOUT: 'retryable',
-});
+// A `Map`, not a frozen object: `code` is a caller's string on every read below, and
+// `CORE_ERROR_RETRY['constructor']` on an object literal answers the `Object` FUNCTION — which
+// `retryFor` then returned as an `ErrorRetry`, into every `UltimateError.retry` and `toJSON()`.
+const CORE_ERROR_RETRY: ReadonlyMap<string, ErrorRetry> = new Map(
+  Object.entries({
+    X_DRAINING: 'retryable',
+    // A deadline that expired is the canonical back-off-and-try-again case: nothing about the
+    // request was wrong, the budget ran out. Deliberately NOT `retry-after` — that spelling means
+    // the responder named a time, and a timeout by definition produced no such answer. Its twin
+    // `X_ABORTED` (the caller went away) is left to the `terminal` DEFAULT rather than listed here:
+    // the answer is the same, and listing it would close a door nobody has asked to open.
+    X_TIMEOUT: 'retryable',
+    // Listed even though `terminal` is the default, and that is the whole point: `classifyThrown`
+    // reads an UNREGISTERED code carrying `terminal` as unclassified, because a per-instance
+    // `terminal` is indistinguishable from the default and honouring it would dead-letter the
+    // first attempt of every job in every app whose codes nobody has classified. So a stub that
+    // says "this build does not have the feature" fell through to the attempt count and burned a
+    // job's whole retry policy on a fact that cannot change between attempt 1 and attempt 5.
+    // It is core's code — every `notImplemented()` stub in the framework raises it — so it is
+    // classified once here rather than by each package that happens to throw it.
+    X_NOT_IMPLEMENTED: 'terminal',
+  } as const),
+);
 
 const REGISTERED = new Map<string, ErrorRetry>();
 
@@ -70,7 +84,7 @@ export function registerErrorRetry(retries: Readonly<Record<string, ErrorRetry>>
     if (!isErrorRetry(retry)) {
       throw retryInvalid(code, `"${String(retry)}" is not ${ERROR_RETRY_KINDS.join(' | ')}`);
     }
-    const core = CORE_ERROR_RETRY[code];
+    const core = CORE_ERROR_RETRY.get(code);
     if (core !== undefined) {
       throw retryInvalid(code, `the framework already classifies it as ${core}`);
     }
@@ -87,11 +101,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.get(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/image/errors.ts

@@ -42,7 +42,7 @@ export const imageDecodeFailed = (
 ): ImageDecodeFailedError =>
   new ImageDecodeFailedError(
     cause,
-    'check the file is a complete, uncorrupted image: `file <path>` then re-export it',
+    're-export the image from its source: `file <path>` reports what these bytes actually are',
     meta,
   );
 

package/src/index.ts

@@ -30,10 +30,9 @@ export {
   withFacts,
 } from './actor';
 export { APP_VERSION_KEY, appVersion, DEFAULT_APP_VERSION } from './app-version';
-export type { InvariantOptions } from './assert';
-export { assert, assertNever, invariant } from './assert';
-export type { Clock, FrozenClock } from './clock';
-export { frozenClock, systemClock } from './clock';
+export { assert, assertNever, type InvariantOptions, invariant } from './assert';
+export { canonicalJson, fingerprint } from './canonical-json';
+export { type Clock, type FrozenClock, frozenClock, systemClock } from './clock';
 export type {
   AiConfig,
   AiConfigInput,
@@ -78,6 +77,7 @@ export {
   resetCursorSigning,
   usesDevCursorSecret,
 } from './cursor';
+export { compareDecimalText } from './decimal-order';
 export type {
   Env,
   EnvBooleanVar,
@@ -130,6 +130,7 @@ export {
   CORE_ERROR_CODES,
   ConfigInvalidError,
   DEFAULT_ERROR_RETRY,
+  declaredErrorRetry,
   describeErrorCode,
   describeValue,
   EnvMissingError,
@@ -424,9 +425,9 @@ export {
   MAX_IMAGE_PIXELS,
   rasterFrom,
 } from './image/raster';
-export type { ImageFit, ResizeSpec } from './image/resize';
-export { fitBox, resizeRaster, scaledToFit } from './image/resize';
+export { fitBox, type ImageFit, type ResizeSpec, resizeRaster, scaledToFit } from './image/resize';
 export { impersonate, impersonationReason, isImpersonating } from './impersonate';
+export { cachedFormatter, canonicalLocale, MAX_CACHED_FORMATTERS } from './intl-cache';
 export type {
   HealthPayload,
   HealthReport,
@@ -469,10 +470,8 @@ export {
   markListening,
   resetListeners,
 } from './listeners';
-export type { McpExposureDeclaration } from './mcp-exposure';
-export { isMcpExposed } from './mcp-exposure';
-export type { CappedBody } from './read-capped';
-export { readWithinLimit } from './read-capped';
+export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
+export { type CappedBody, readWithinLimit } from './read-capped';
 export type { ModuleRegistrar, PrimitiveKind, RegisteredPrimitive } from './registrar';
 export {
   hasPrimitiveRegistrar,
@@ -486,8 +485,7 @@ export { err, isErr, isOk, map, mapErr, ok, tryCatch, unwrap, unwrapOr } from '.
 export type { ResolveRoleOptions, Role, RoleInfo, ScalingSignal } from './roles';
 export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
-export type { ServiceFactory } from './service';
-export { defineService, resetServices } from './service';
+export { defineService, resetServices, type ServiceFactory } from './service';
 export { timingSafeEqual } from './timing-safe-equal';
 export {
   frameworkVersion,