@ultimat3/core 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -101,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

package/README.md

@@ -343,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "3.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-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}`);
     }
@@ -99,7 +113,7 @@ export function resetErrorRetry(): void {
  * 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);
+  return CORE_ERROR_RETRY.get(code) ?? REGISTERED.get(code);
 }
 
 export function retryFor(code: string): ErrorRetry {

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,
@@ -425,8 +425,7 @@ 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 {
@@ -471,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,
@@ -488,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,

package/src/logger.ts

@@ -10,6 +10,9 @@ import { isSecret, REDACTED } from './secret';
 // it without importing the logger, and two constants spelled the same is one rename from a leak.
 export { REDACTED } from './secret';
 
+/** What a `Date` this file cannot render says instead — the line survives, the value is named. */
+const INVALID_DATE = 'an invalid Date';
+
 export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'] as const;
 
 export type LogLevel = (typeof LOG_LEVELS)[number];
@@ -133,7 +136,7 @@ function serialise(value: unknown, depth: number): unknown {
   // `toISOString()` THROWS on an invalid Date, and an invalid Date is exactly the value worth
   // logging when a schedule went wrong.
   if (value instanceof Date) {
-    return Number.isNaN(value.getTime()) ? 'an invalid Date' : value.toISOString();
+    return Number.isNaN(value.getTime()) ? INVALID_DATE : value.toISOString();
   }
   if (isUltimateError(value)) return value.toJSON();
   if (value instanceof Error) return { name: value.name, message: value.message };
@@ -198,6 +201,22 @@ function renderLine(
   }
 }
 
+/**
+ * The one value in a line that is not the caller's, and it was the one read left unguarded:
+ * `toISOString()` raises `RangeError` on an invalid `Date`, and a `Clock` is injected — a frozen
+ * clock set from a bad string, or a clock whose `now()` throws, took the whole line with it. The
+ * same marker `serialise` gives an invalid `Date` in a FIELD, so one vocabulary covers both.
+ */
+function timestamp(clock: Clock): string {
+  try {
+    const at = clock.now();
+    if (at instanceof Date && !Number.isNaN(at.getTime())) return at.toISOString();
+  } catch {
+    // A clock that fights being read is exactly the moment a line is worth keeping.
+  }
+  return INVALID_DATE;
+}
+
 function envLevel(): LogLevel {
   const raw = process.env['LOG_LEVEL'];
   return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
@@ -215,7 +234,7 @@ export function createLogger(options?: LoggerOptions): Logger {
   function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
     if (LEVEL_WEIGHT[lineLevel] < threshold) return;
     const line = {
-      ts: clock.now().toISOString(),
+      ts: timestamp(clock),
       level: lineLevel,
       msg: message,
       ...redactFields(bound),

package/src/metrics-types.ts

@@ -0,0 +1,102 @@
+// Single responsibility: the OpenTelemetry-shaped metric DATA MODEL — what a point, a
+// descriptor, a collection and an instrument's options are. No registry and no state: `metrics.ts`
+// owns those, and a reader (`metrics-text.ts`, an exporter) needs the shapes without them.
+
+import type { SpanResource } from './telemetry';
+
+export type MetricKind = 'counter' | 'gauge' | 'histogram';
+
+/**
+ * Narrower than a span attribute on purpose: metric attributes become time-series labels, every
+ * distinct combination is a stored series, and an array label has no meaning in any exposition
+ * format. Keep the cardinality low — a user id here is an outage, and `maxSeries` is the ceiling
+ * that makes "keep it low" a mechanism instead of this sentence.
+ */
+export type MetricAttributeValue = string | number | boolean;
+
+export interface MetricAttributes {
+  readonly [key: string]: MetricAttributeValue;
+}
+
+export interface MetricDescriptor {
+  readonly name: string;
+  readonly kind: MetricKind;
+  /** UCUM, as OTel spells it: `1`, `s`, `By`, `{request}`. */
+  readonly unit: string;
+  readonly description: string;
+}
+
+export interface MetricPoint {
+  readonly attributes: MetricAttributes;
+  /** Counter: cumulative sum since process start. Gauge: last value. Histogram: sum. */
+  readonly value: number;
+}
+
+export interface HistogramPoint extends MetricPoint {
+  readonly count: number;
+  readonly min: number;
+  readonly max: number;
+  /** Explicit upper bounds; `buckets` is one longer, the last being the `+Inf` overflow. */
+  readonly bounds: readonly number[];
+  readonly buckets: readonly number[];
+}
+
+export interface ReadableMetric {
+  readonly descriptor: MetricDescriptor;
+  readonly points: readonly MetricPoint[];
+}
+
+export interface MetricCollection {
+  /** Epoch milliseconds, from the configured clock. */
+  readonly at: number;
+  readonly resource: SpanResource;
+  readonly metrics: readonly ReadableMetric[];
+}
+
+/** The driver seam. OTLP, Prometheus remote-write or a vendor SDK all arrive as one of these. */
+export interface MetricExporter {
+  export(collection: MetricCollection): void;
+}
+
+export interface Counter {
+  add(value?: number, attributes?: MetricAttributes): void;
+}
+
+export interface Gauge {
+  /** Set the current value. */
+  record(value: number, attributes?: MetricAttributes): void;
+  /** Move the current value — `+1` on connect, `-1` on disconnect. */
+  add(delta: number, attributes?: MetricAttributes): void;
+}
+
+export interface Histogram {
+  record(value: number, attributes?: MetricAttributes): void;
+}
+
+export interface InstrumentOptions {
+  readonly unit?: string | undefined;
+  readonly description?: string | undefined;
+  /**
+   * Distinct label sets this instrument may store. Past it every new set folds into one overflow
+   * series. Defaults to `DEFAULT_MAX_SERIES`; the first declaration of a name wins.
+   */
+  readonly maxSeries?: number | undefined;
+}
+
+export interface GaugeOptions extends InstrumentOptions {
+  /**
+   * 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.
+   * 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;
+}

package/src/metrics.ts

@@ -3,9 +3,44 @@
 // always on, a no-op exporter by default, and the wire format supplied by a driver, never here.
 
 import { type Clock, systemClock } from './clock';
+import { renderThrowable } from './error-render';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { logger } from './logger';
-import { type SpanResource, serviceResource } from './telemetry';
+import type {
+  Counter,
+  Gauge,
+  GaugeOptions,
+  Histogram,
+  HistogramOptions,
+  InstrumentOptions,
+  MetricAttributes,
+  MetricCollection,
+  MetricDescriptor,
+  MetricExporter,
+  MetricKind,
+  MetricPoint,
+} from './metrics-types';
+import { serviceResource } from './telemetry';
+
+// The data model is a module of its own; the public surface is unchanged, so nothing that imports
+// a metric type from here has to learn a second path.
+export type {
+  Counter,
+  Gauge,
+  GaugeOptions,
+  Histogram,
+  HistogramOptions,
+  HistogramPoint,
+  InstrumentOptions,
+  MetricAttributes,
+  MetricAttributeValue,
+  MetricCollection,
+  MetricDescriptor,
+  MetricExporter,
+  MetricKind,
+  MetricPoint,
+  ReadableMetric,
+} from './metrics-types';
 
 export class MetricNameInvalidError extends UltimateError {
   static readonly code = 'X_METRIC_NAME_INVALID';
@@ -31,103 +66,6 @@ export class MetricCardinalityError extends UltimateError {
   }
 }
 
-export type MetricKind = 'counter' | 'gauge' | 'histogram';
-
-/**
- * Narrower than a span attribute on purpose: metric attributes become time-series labels, every
- * distinct combination is a stored series, and an array label has no meaning in any exposition
- * format. Keep the cardinality low — a user id here is an outage, and `maxSeries` is the ceiling
- * that makes "keep it low" a mechanism instead of this sentence.
- */
-export type MetricAttributeValue = string | number | boolean;
-
-export interface MetricAttributes {
-  readonly [key: string]: MetricAttributeValue;
-}
-
-export interface MetricDescriptor {
-  readonly name: string;
-  readonly kind: MetricKind;
-  /** UCUM, as OTel spells it: `1`, `s`, `By`, `{request}`. */
-  readonly unit: string;
-  readonly description: string;
-}
-
-export interface MetricPoint {
-  readonly attributes: MetricAttributes;
-  /** Counter: cumulative sum since process start. Gauge: last value. Histogram: sum. */
-  readonly value: number;
-}
-
-export interface HistogramPoint extends MetricPoint {
-  readonly count: number;
-  readonly min: number;
-  readonly max: number;
-  /** Explicit upper bounds; `buckets` is one longer, the last being the `+Inf` overflow. */
-  readonly bounds: readonly number[];
-  readonly buckets: readonly number[];
-}
-
-export interface ReadableMetric {
-  readonly descriptor: MetricDescriptor;
-  readonly points: readonly MetricPoint[];
-}
-
-export interface MetricCollection {
-  /** Epoch milliseconds, from the configured clock. */
-  readonly at: number;
-  readonly resource: SpanResource;
-  readonly metrics: readonly ReadableMetric[];
-}
-
-/** The driver seam. OTLP, Prometheus remote-write or a vendor SDK all arrive as one of these. */
-export interface MetricExporter {
-  export(collection: MetricCollection): void;
-}
-
-export interface Counter {
-  add(value?: number, attributes?: MetricAttributes): void;
-}
-
-export interface Gauge {
-  /** Set the current value. */
-  record(value: number, attributes?: MetricAttributes): void;
-  /** Move the current value — `+1` on connect, `-1` on disconnect. */
-  add(delta: number, attributes?: MetricAttributes): void;
-}
-
-export interface Histogram {
-  record(value: number, attributes?: MetricAttributes): void;
-}
-
-export interface InstrumentOptions {
-  readonly unit?: string | undefined;
-  readonly description?: string | undefined;
-  /**
-   * Distinct label sets this instrument may store. Past it every new set folds into one overflow
-   * series. Defaults to `DEFAULT_MAX_SERIES`; the first declaration of a name wins.
-   */
-  readonly maxSeries?: number | undefined;
-}
-
-export interface GaugeOptions extends InstrumentOptions {
-  /**
-   * 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.
-   * 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;
-}
-
 /**
  * The per-instrument series ceiling. 2000 is roomy for a bounded label set — every route pattern
  * times every status class times every method — and small enough that the process notices an
@@ -204,6 +142,8 @@ interface Instrument {
   readonly maxSeries: number;
   /** Reported once. A cardinality blow-up is one bug, not one log line per call. */
   overflowed: boolean;
+  /** Reported once, for the same reason: a scrape every 15s must not become a log every 15s. */
+  observeFailed: boolean;
 }
 
 const instruments = new Map<string, Instrument>();
@@ -230,6 +170,7 @@ export function resetMetrics(): void {
   for (const instrument of instruments.values()) {
     instrument.series.clear();
     instrument.overflowed = false;
+    instrument.observeFailed = false;
   }
 }
 
@@ -294,6 +235,7 @@ function declare(name: string, kind: MetricKind, options: GaugeOptions & Histogr
     observe: options.observe,
     maxSeries,
     overflowed: false,
+    observeFailed: false,
   };
   instruments.set(name, instrument);
   return instrument;
@@ -350,6 +292,26 @@ function reportOverflow(instrument: Instrument): void {
   logger.error(error.format(), { code: error.code, metric: name });
 }
 
+/**
+ * Reported through the logger for `reportOverflow`'s reason and once for the same one — a scrape
+ * runs on a timer, so a permanently broken observer would otherwise write a log line every
+ * interval forever. A recurrence after the first is therefore silent by design; the missing series
+ * is the signal that outlives the line.
+ */
+function reportObserveFailure(instrument: Instrument, thrown: unknown): void {
+  if (instrument.observeFailed) return;
+  instrument.observeFailed = true;
+  const { name, kind } = instrument.descriptor;
+  const error = new MetricValueInvalidError({
+    // `renderThrowable`, never `${thrown}`: the value is whatever the app's callback threw, and a
+    // `.message` read on it is the one that throws where there is nothing left to answer with.
+    cause: `the observe() callback of ${name} did not produce a value: ${renderThrowable(thrown)}; this instrument contributes no point until it does`,
+    fix: `make the observe() callback of ${name} total — return a finite number when the resource it reads is gone, e.g. ${kind}('${name}', { observe: () => pool?.size ?? 0 })`,
+    meta: { metric: name },
+  });
+  logger.error(error.format(), { code: error.code, metric: name });
+}
+
 function createSeries(instrument: Instrument, key: string, attributes: MetricAttributes): Series {
   const created: Series = {
     attributes,
@@ -433,8 +395,19 @@ export function histogram(name: string, options?: HistogramOptions): Histogram {
 }
 
 function pointsOf(instrument: Instrument): readonly MetricPoint[] {
-  if (instrument.observe !== undefined) {
-    return [{ attributes: {}, value: instrument.observe() }];
+  const observe = instrument.observe;
+  if (observe !== undefined) {
+    try {
+      return [{ attributes: {}, value: finite(instrument.descriptor.name, observe()) }];
+    } catch (thrown) {
+      // The callback is the app's, run at SCRAPE time with no call site to blame: `() => pool.size`
+      // after a drain throws, and an unguarded read here took every other instrument down with it
+      // — /metrics 500s, `http_requests_total` goes invisible, and `startMetricExport`'s timer
+      // callback raises where nothing can catch it. One hostile observer costs its own point only,
+      // the same degradation `readinessChecks()` and the logger's per-key walk already make.
+      reportObserveFailure(instrument, thrown);
+      return [];
+    }
   }
   return [...instrument.series.values()].map((series) =>
     instrument.descriptor.kind === 'histogram'

package/src/otlp-metric-exporter.ts

@@ -1,6 +1,8 @@
 // Single responsibility: a `MetricExporter` that POSTs OTLP/HTTP JSON to a collector. No batching
 // — `collectMetrics()` already produces one whole snapshot per tick, so a tick is a request.
 
+import { renderThrowable } from './error-render';
+import { logger } from './logger';
 import type {
   HistogramPoint,
   MetricCollection,
@@ -124,10 +126,31 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
   return {
     export(collection: MetricCollection): void {
       startedAtMs ??= collection.at;
-      const body = JSON.stringify(otlpMetricsRequest(collection, startedAtMs));
+      let body: string;
+      try {
+        // `export` is called from a timer, not awaited by anyone, so this throw had nowhere to go
+        // but into the metric loop that called it: `MetricAttributeValue` is a compile-time claim,
+        // and an attribute the app spelled as an object or a bigint reaches `otlpAttributes` as a
+        // TypeError. Dropped with a line, the same degradation `postOtlp` already applies to a
+        // collector that is down — telemetry is best-effort and must never end the process.
+        body = JSON.stringify(otlpMetricsRequest(collection, startedAtMs));
+      } catch (failure) {
+        logger.warn('otlp metric snapshot dropped', {
+          url,
+          metrics: collection.metrics.length,
+          error: renderThrowable(failure),
+        });
+        return;
+      }
       // Chained, so a slow collector cannot make two snapshots arrive out of order and turn a
-      // cumulative counter into an apparent reset.
-      inflight = inflight.then(() => postOtlp({ url, headers, body, timeoutMs, fetch: send }));
+      // cumulative counter into an apparent reset. Chained on a SETTLED shadow, for the reason
+      // `otlp-span-exporter.ts` spells out: a chain that carries a rejection forward stops calling
+      // `postOtlp` for the life of the process, in silence.
+      const settled = inflight.then(
+        () => undefined,
+        () => undefined,
+      );
+      inflight = settled.then(() => postOtlp({ url, headers, body, timeoutMs, fetch: send }));
     },
     flush(): Promise<void> {
       return inflight;

package/src/otlp-span-exporter.ts

@@ -1,6 +1,8 @@
 // Single responsibility: a `SpanExporter` that POSTs OTLP/HTTP JSON to a collector. Batched,
 // because `SpanExporter.export` is one span and a request per span is a second load generator.
 
+import { renderThrowable } from './error-render';
+import { logger } from './logger';
 import {
   OTLP_SCOPE,
   type OtlpKeyValue,
@@ -134,15 +136,38 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
   const post = (batch: readonly ReadableSpan[]): Promise<void> => {
     const first = batch[0];
     if (first === undefined) return Promise.resolve();
-    const body = JSON.stringify(otlpTraceRequest(batch, first.resource));
+    let body: string;
+    try {
+      // The one synchronous throw on this path, and the only way `inflight` can reject at all:
+      // `AttributeValue` is a compile-time claim, so an attribute the app spelled as an object, a
+      // bigint or a cycle reaches `anyValue`'s `value.map(...)` as a TypeError. Dropped with a
+      // line, the same degradation `postOtlp` already applies to a collector that is down —
+      // telemetry is best-effort and must never become the process's exit code.
+      body = JSON.stringify(otlpTraceRequest(batch, first.resource));
+    } catch (failure) {
+      logger.warn('otlp span batch dropped', {
+        url,
+        spans: batch.length,
+        error: renderThrowable(failure),
+      });
+      return Promise.resolve();
+    }
     return postOtlp({ url, headers, body, timeoutMs, fetch: send });
   };
 
   const drainQueue = (): Promise<void> => {
     const batch = queue.splice(0, queue.length);
     // Chained, not concurrent: a collector reordering batches from one process turns a parent's
-    // span arriving after its child into a broken trace on the read side.
-    inflight = inflight.then(() => post(batch));
+    // span arriving after its child into a broken trace on the read side. Chained on a SETTLED
+    // shadow, because a chain that carries a rejection forward is poisoned for the life of the
+    // process: `post` is never called again while the queue keeps emptying, so every later span is
+    // dropped in silence and every timer tick mints a fresh unhandled rejection — which Bun ends
+    // the process on. Same shape as `offline-queue.ts`'s drain chain.
+    const settled = inflight.then(
+      () => undefined,
+      () => undefined,
+    );
+    inflight = settled.then(() => post(batch));
     return inflight;
   };
 

package/src/type-pins.ts

@@ -52,9 +52,15 @@ type _ActorFactMapAcceptsNothing = Assert<
 >;
 
 /**
- * The seam is additive: an actor literal written before it existed still is one. `facts` is
- * optional for that reason and not only for the denial rule — a required member would have been
- * a breaking change to a tier-0 type every package depends on.
+ * The seam is additive: an actor literal carrying the required members but no `facts` still is an
+ * `Actor`. `facts` is optional for that reason and not only for the denial rule — making it
+ * required would be a breaking change to a tier-0 type every package depends on.
+ *
+ * `permissions` joined the required set in 4.0.0 and is spelled here deliberately. That WAS such a
+ * breaking change, made knowingly and with a migration: policy's `PolicyActorFields` held it, so
+ * `userActor({ permissions })` silently dropped it and no builder could spell a direct grant. This
+ * pin is what makes the next one impossible to add by accident — a new required member fails here
+ * before it fails in an app.
  */
 type _ActorWithoutFactsIsStillAnActor = Assert<
   [
@@ -63,6 +69,7 @@ type _ActorWithoutFactsIsStillAnActor = Assert<
       readonly id: string;
       readonly roles: readonly string[];
       readonly scopes: readonly string[];
+      readonly permissions: readonly string[];
     },
   ] extends [Actor]
     ? true