@ultimat3/core 16.0.0 → 17.0.0

package/CLAUDE.md

@@ -125,7 +125,7 @@ shape against a locally declared sample interface for exactly that reason.
 | the five above, composed into one typed-client call | `client-flight.ts` + `client-wire.ts` | `@ultimat3/action` and `@ultimat3/query` both project a typed client and are both tier 3, so neither could import the other: it shipped as a byte-identical 288-line + 85-line copy in each, policed by a `client-twin.test.ts` in both. Both packages re-export these names, so their public surface is unchanged. Declares NO code of its own — `X_SUPERSEDED`, `X_TIMEOUT` and `X_FLIGHT_GATE_OVERLOADED` are already here |
 | is this `unknown` a keyed record? | `json-object.ts` | `isJsonObject`, which was the same three terms in both those packages' `stable.ts`. A `Date` and a class instance PASS: it narrows a shape, it does not certify provenance |
 | 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 |
+| an `Intl` formatter cache, and the screen in front of it | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `assertLocale`, `MAX_CACHED_FORMATTERS`) | a locale and a zone arrive from a request header, so the tag must be REFUSED when it is not a tag (`X_LOCALE_INVALID`), the key must be canonical AND the cache bounded — never a second copy of any of the three |
 | 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
@@ -144,6 +144,15 @@ and live in one file for that reason: a canonical key bounds nothing (an unknown
 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.
 
+`assertLocale` and `X_LOCALE_INVALID` moved here from `@ultimat3/time` in 16.x, for the third
+time the same argument was made: `@ultimat3/money` handed a malformed `Accept-Language` tag
+straight to `Intl.NumberFormat` at four entry points and let a bare `RangeError` out, and copying
+time's screen down would have been a second answer to one question. Validating and keying are ONE
+step — `getCanonicalLocales` runs exactly the check `supportedLocalesOf` throws on and hands back
+the spelling the cache keys on — which is why the screen lives in this file and not beside it. A
+code has one declaration: `X_LOCALE_INVALID` left `TIME_ERROR_CODES` in the same change, or
+`registerErrorCodes` would raise `X_ERROR_CODE_DUPLICATE` the moment both packages loaded.
+
 `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
@@ -218,6 +227,28 @@ the layer imports anything but this package, nothing runs at import time, and ev
 non-determinism — the roll, the sleep, the clock, the timer — is injected, because a schedule
 provable only by waiting is a schedule no test pins.
 
+**`backoffDelay` REFUSES a non-finite bound, `As of 2026-08-26`, and that is a behaviour change.**
+It used to answer `0`, on the argument that 0 is "wrong loudly". It is not: measured,
+`retry({ attempts: 5, max: NaN })` slept `[0, 0, 0, 0]` and `factor: NaN` slept `[1000, 0, 0, 0]` —
+a retry loop with no wait at all, which is the failure backoff exists to prevent, on the tree's ONE
+curve (`bun run flight-copies`), reaching every retry in the framework. `attempt`, `base`, `max`
+and `factor` each go through `finiteOption` before the clamps, because `Math.max`, `Math.min` and
+`Math.trunc` propagate rather than validate and `Math.min(raw, Infinity)` is `Infinity`. The
+`return 0` below them stays and is still reachable, by exactly one route: `factor ** (step - 1)`
+overflows around attempt 1030 and `0 * Infinity` is `NaN` — a zero base is a caller asking for no
+wait, which is the answer it gets.
+
+**`finiteOption` / `finiteCount` (`finite-option.ts`) are the framework's ONE screen for a numeric
+option, `As of 2026-08-26`.** They landed here because `@ultimat3/jobs`, `@ultimat3/realtime` and
+`@ultimat3/query` each held a byte-identical copy; all three were deleted and now import these.
+`finiteCount(subject, option, value, min)` takes `min: 0 | 1` as a DEFAULT PARAMETER rather than
+shipping a third `finitePositive`, because only the caller knows what zero means —
+`requestTimeoutMs: 0` is "no deadline", a pool `max: 0` is a pool nothing can run on.
+`bun run finite-bounds` is the ratchet, and it recognises a repair by the SHAPE OF THE CALL: a
+package screen that does not carry `Finite` in its name is invisible to it, which is why
+`assertFiniteImageQuality`, `assertFiniteOtlpBound` and their siblings in five other packages are
+spelled that way.
+
 Two rules that are not preferences. `backoffDelay` clamps to `max` **before** jitter: capping after
 turns `full` into a distribution whose upper half is a single value at `max`, which is the
 correlation jitter exists to remove. `createFlightGate` **hands** its slot to a waiter rather than

package/README.md

@@ -316,7 +316,9 @@ nothing and still reports healthy.
 - **Sampling is honoured, not just propagated.** `startSpan` takes the parent's bit when there is
   one, else asks the `Sampler`; `span.end()` exports nothing when the bit is 0. The default reads
   `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` at the first span, and
-  `configureTelemetry({ sampler })` replaces it.
+  `configureTelemetry({ sampler })` replaces it. `shouldSample` is handed the TRACE ID of the span
+  being created, so `traceidratio` decides once per trace by hashing it — a roll per span left one
+  trace half exported, which is orphan children under a root the collector never saw.
 - **The OTLP exporters ship**, speaking OTLP/HTTP JSON, no dependency:
   `otlpSpanExporter({ endpoint })` (batched, with `flush()` / `shutdown()`) and
   `otlpMetricExporter({ endpoint })`. Both default to `OTEL_EXPORTER_OTLP_ENDPOINT`;
@@ -457,13 +459,16 @@ never a silently wrong page.
 ## One bounded cache for every `Intl` formatter
 
 ```ts
-import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+import { assertLocale, cachedFormatter } 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;
+  // Validates AND canonicalizes: `EN-us` and `en-latn-us` collapse to one key, and a tag `Intl`
+  // cannot parse is `X_LOCALE_INVALID` here rather than a bare `RangeError` out of the constructor
+  // below. `canonicalLocale(locale) ?? locale` is the same call with the refusal deleted — it is
+  // what `@ultimat3/money` did, and an `Accept-Language` value of `en_US` took the request down.
+  const tag = assertLocale(locale);
   return cachedFormatter(
     cache,
     `${tag}|EUR`,

package/package.json

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

package/src/backoff.ts

@@ -3,6 +3,8 @@
 // (equal jitter), `@ultimat3/ai` (full jitter, `Math.random` inline and so untestable),
 // `@ultimat3/realtime` (full jitter, 0-based attempt) and `@ultimat3/db` (no backoff at all).
 
+import { finiteOption } from './finite-option';
+
 export type BackoffCurve = 'exponential' | 'linear' | 'fixed';
 
 /**
@@ -12,6 +14,9 @@ export type BackoffCurve = 'exponential' | 'linear' | 'fixed';
  */
 export type JitterMode = 'full' | 'equal' | 'none';
 
+/** Named in every refusal below, so a reader knows which call built the schedule. */
+const SUBJECT = 'backoffDelay';
+
 /** Injected everywhere. A delay only provable by observing a range is a delay no test pins. */
 export type Random = () => number;
 
@@ -38,19 +43,26 @@ export interface BackoffOptions {
  * jitter exists to remove.
  */
 export function backoffDelay(options: BackoffOptions): number {
-  const step = Math.max(1, Math.trunc(options.attempt));
-  const base = Math.max(0, options.base);
-  const factor = options.factor ?? 2;
+  // Every bound is REFUSED before it is clamped, because the clamps are not validators: measured,
+  // `retry({ attempts: 5, max: NaN })` slept `[0, 0, 0, 0]` and `factor: NaN` slept
+  // `[1000, 0, 0, 0]` — `Math.max`, `Math.min` and `Math.trunc` each propagate it,
+  // `Math.min(raw, Infinity)` is `Infinity`, and the `return 0` below then turns the whole
+  // schedule into a spin.
+  const step = Math.max(1, Math.trunc(finiteOption(SUBJECT, 'attempt', options.attempt)));
+  const base = Math.max(0, finiteOption(SUBJECT, 'base', options.base));
+  const max = finiteOption(SUBJECT, 'max', options.max);
+  const factor = finiteOption(SUBJECT, 'factor', options.factor ?? 2);
 
   let raw: number;
   if (options.curve === 'fixed') raw = base;
   else if (options.curve === 'linear') raw = base * step;
   else raw = base * factor ** (step - 1);
 
-  const capped = Math.max(0, Math.min(raw, options.max));
-  // A NaN reaches here from an unvalidated config value, and `setTimeout(NaN)` fires IMMEDIATELY —
-  // a retry loop with no wait at all, which is the failure mode backoff exists to prevent. 0 is
-  // wrong too, but it is wrong loudly: the next attempt still happens once, not in a tight spin.
+  const capped = Math.max(0, Math.min(raw, max));
+  // Still reachable with four finite inputs, and only one way: `factor ** (step - 1)` overflows to
+  // `Infinity` around attempt 1030, and `0 * Infinity` is `NaN`. A zero base is a caller asking
+  // for no wait, so 0 is the answer it asked for — it is no longer the answer an unvalidated
+  // config value gets, which is what this line used to be.
   if (!Number.isFinite(capped)) return 0;
 
   const roll = options.random ?? Math.random;

package/src/context.ts

@@ -34,6 +34,7 @@ import { type Actor, anonymousActor } from './actor';
 import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
+import { finiteOption } from './finite-option';
 import { traceId as newTraceId, uuid } from './ids';
 import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
 import { type Role, resolveRole } from './roles';
@@ -173,7 +174,7 @@ export function createContext(init: CtxInit = {}): Ctx {
     now: () => clock.now(),
     logger: base.child({ requestId, traceId: trace }),
     signal: init.signal ?? neverAborted,
-    deadlineAt: init.deadlineAt ?? null,
+    deadlineAt: screenDeadline(init.deadlineAt),
   };
   // A registered service (`defineService`) closes over the ctx it is built for — actor, clock,
   // tz — so it has to run HERE, against this exact call's fields, rather than once at boot and
@@ -231,6 +232,35 @@ export function hasContext(): boolean {
   return tryUseContext() !== undefined;
 }
 
+/**
+ * The tighter of two instants, where absent means "no bound" — the bounded form
+ * `lifecycle.ts`'s drain budget uses, over two optional values instead of one. Returns
+ * `undefined` rather than `null` because that is what `CtxInit.deadlineAt` spells.
+ */
+function earliest(left: number | undefined, right: number | null | undefined): number | undefined {
+  if (left === undefined) return right ?? undefined;
+  if (right === undefined || right === null) return left;
+  return Math.min(left, right);
+}
+
+/**
+ * The one screen over `deadlineAt`, at both boundaries that can set it. A deadline is an instant,
+ * not a count, so `finiteOption` rather than `finiteCount` — a clock epoch is legitimately large
+ * and a test clock's is legitimately small.
+ *
+ * WHY IT IS REFUSED AND NOT CLAMPED, in this file specifically: `Math.min` PROPAGATES `NaN`, so one
+ * non-finite side poisons the child's deadline as well as its own. `remainingBudgetMs` then asks
+ * `left >= 1` of a `NaN`, gets `false`, and answers `undefined` — the same answer it gives for "no
+ * deadline at all". So the `x-request-timeout-ms` header is silently omitted and the next hop falls
+ * back to its OWN configured budget, which `request-budget.ts`'s own header calls "the exact
+ * failure this header exists to prevent". A deadline that quietly stops bounding anything is the
+ * dangerous direction, and it is the direction `??` cannot see, because `NaN` is not nullish.
+ */
+function screenDeadline(value: number | null | undefined): number | null {
+  if (value === undefined || value === null) return null;
+  return finiteOption('the request context', 'deadlineAt', value);
+}
+
 /**
  * Derive a narrowed context — impersonation, a locale switch, a per-step abort signal.
  * `requestId` is deliberately not patchable: one request, one id.
@@ -256,8 +286,10 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     logger: patch.logger ?? parent.logger,
     // One request, one budget: a child scope inherits the deadline for the same reason it
     // inherits `requestId`. A patch may SHORTEN it (a step with its own budget); nothing here
-    // lengthens it, because the socket the parent is answering does not move.
-    deadlineAt: patch.deadlineAt ?? parent.deadlineAt ?? undefined,
+    // lengthens it, because the socket the parent is answering does not move. `??` alone said
+    // that and did not do it — a patched hour replaced a parent's second outright, and
+    // `remainingBudgetMs` then put the hour on `x-request-timeout-ms` for the next hop.
+    deadlineAt: earliest(screenDeadline(patch.deadlineAt) ?? undefined, parent.deadlineAt),
     signal: patch.signal ?? parent.signal,
     services: { ...carried, ...(patch.services ?? {}) },
   });

package/src/error-codes.ts

@@ -52,6 +52,9 @@ const CORE_CODE_TITLES = {
   X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
   X_INTERNAL: 'unexpected internal framework error',
   X_INVARIANT: 'invariant violated',
+  // Owned here rather than by `@ultimat3/time`, which declared it until 16.x: `@ultimat3/money`
+  // needs the same screen and tier 1 may not import sideways. One code, one declaration.
+  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
   X_METRIC_CARDINALITY:
     'a metric exceeded its series ceiling and is folding into one overflow series',
   X_METRIC_NAME_INVALID:

package/src/error-retry.ts

@@ -106,9 +106,21 @@ export function registerErrorRetry(retries: Readonly<Record<string, ErrorRetry>>
   }
 }
 
-/** Test seam. Production registers once at boot and never unregisters. */
-export function resetErrorRetry(): void {
+/**
+ * Test seam. Production registers once at boot and never unregisters.
+ *
+ * `restore` is not a nicety: this map is PROCESS-WIDE and every package fills it at module
+ * evaluation, so a bare `clear()` in one file's `afterEach` deletes registrations that file never
+ * made. Bun runs one process for the whole suite and `scripts/test-setup.ts` imports packages
+ * before any test runs, so their module bodies never run again to repair it — measured,
+ * `@ultimat3/policy`'s codes read as unclassified in every file loaded after core's tests, and
+ * `@ultimat3/db`, `@ultimat3/ai` and `@ultimat3/jobs` each carry a `beforeEach` that re-registers
+ * their own table for exactly this reason. Pass `registeredErrorRetry()` captured at module scope
+ * and the wipe is scoped to what the test added.
+ */
+export function resetErrorRetry(restore: Readonly<Record<string, ErrorRetry>> = {}): void {
   REGISTERED.clear();
+  for (const [code, retry] of Object.entries(restore)) REGISTERED.set(code, retry);
 }
 
 /**

package/src/finite-option.ts

@@ -0,0 +1,54 @@
+// Single responsibility: the one refusal the framework makes for a numeric option that is not a
+// number. Tier 0 because twenty-one packages need it — `jobs`, `realtime` and `query` each carried
+// a byte-identical copy, the shape three backoff curves and three SQL escapes already took.
+// `bun run finite-bounds` is the ratchet; this is the repair it recognises.
+
+import { assert } from './assert';
+
+/**
+ * The option, when it is a real number. Returns it so a call site stays one expression:
+ * `this.#capacity = finiteOption('ChangeBuffer', 'capacity', options.capacity ?? 1024)`.
+ *
+ * WHY IT TAKES A FUNCTION AT ALL, since every part of the job looks already done by an operator:
+ * `??` guards NULLISH and `NaN` is not nullish, so `Number(process.env.X)` on an unset variable, a
+ * `parseInt` of a typo and a JSON `null`-turned-`NaN` all walk straight past the default. And
+ * `Math.max` / `Math.min` / `Math.floor` PROPAGATE it rather than validating, so none of the three
+ * is a screen either — `Math.min(raw, Infinity)` is `Infinity`. What the value then bounds decides
+ * WHICH failure you get, and all four have shipped: a comparison that reads false forever, an
+ * `Array.from({ length: NaN })` that is `[]`, a `setTimeout(fn, NaN)` that is `setTimeout(fn, 0)`,
+ * and a loop that never terminates. Several packages' comments point here for this argument.
+ */
+export function finiteOption(subject: string, option: string, value: number): number {
+  assert(
+    Number.isFinite(value),
+    `${subject} ${option} is ${String(value)}, so every comparison against it is false and the bound it sets does not exist`,
+    `pass a finite ${option} to ${subject}, or omit it and take the default — Math.max/Math.min/Math.floor do not validate it, they propagate it`,
+  );
+  return value;
+}
+
+/**
+ * The same rule where the option counts THINGS — rows, bytes, entries, milliseconds, slots — and a
+ * fraction is as wrong as a `NaN`: `Array.from({ length: 2.5 })` throws, a `slice` truncates, and
+ * above 2^53 a double cannot name its own successor, so a "count" up there is already rounded.
+ * `Number.isSafeInteger`, which is what `@ultimat3/schema` demands of an integer at the wire.
+ *
+ * `min` is the caller's because only the caller knows what zero MEANS: `requestTimeoutMs: 0` is
+ * "no deadline" and `maxInflight: 0` is "never shed", both decisions the code reads, while
+ * `max: 0` connections is a pool nothing can run on. A helper that picked one would be wrong at
+ * half the call sites, and this is deliberately the only knob it takes — a third function for
+ * "positive" would be the copy this file exists to prevent.
+ */
+export function finiteCount(
+  subject: string,
+  option: string,
+  value: number,
+  min: 0 | 1 = 0,
+): number {
+  assert(
+    Number.isSafeInteger(value) && value >= min,
+    `${subject} ${option} is ${String(value)}, and it counts things: it must be a whole number of ${min === 1 ? 'at least 1' : '0 or more'}, or the bound it sets is not one`,
+    `pass a whole ${option} to ${subject} — and parse an environment value before you pass it, because Number(process.env.…) is NaN when the variable is unset and Math.floor does not repair that`,
+  );
+  return value;
+}

package/src/ids.ts

@@ -4,6 +4,7 @@
 import { type Clock, systemClock } from './clock';
 import { describeValue } from './error-render';
 import { UltimateError } from './errors';
+import { finiteCount } from './finite-option';
 
 /** Nominal typing without a runtime cost. `Brand<string, 'post'>` never mixes with `'user'`. */
 export type Brand<T, K extends string> = T & { readonly __brand: K };
@@ -39,8 +40,13 @@ function seedCounter(): number {
   return (((bytes[0] ?? 0) << 8) | (bytes[1] ?? 0)) & COUNTER_SEED_MASK;
 }
 
+/**
+ * `new Uint8Array(NaN)` is a zero-length array, not a throw, so an unscreened length made this
+ * answer `''` — an id that is no id, minted silently. `min: 1`: zero bytes of randomness is the
+ * same empty string, and every caller here (`uuid`, `traceId`, `spanId`) wants a width.
+ */
 export function randomHex(byteLength: number): string {
-  const bytes = randomBytes(byteLength);
+  const bytes = randomBytes(finiteCount('randomHex', 'byteLength', byteLength, 1));
   let out = '';
   for (const byte of bytes) {
     out += HEX[byte >> 4];
@@ -109,9 +115,15 @@ export function uuidTimestamp(id: string): Date {
   return new Date(Number.parseInt(id.slice(0, 8) + id.slice(9, 13), 16));
 }
 
-/** URL-safe random id. Not sortable — use it for tokens and slugs, never primary keys. */
+/**
+ * URL-safe random id. Not sortable — use it for tokens and slugs, never primary keys.
+ *
+ * The default is not a screen: `??` guards nullish and `NaN` is not nullish, so
+ * `nanoid(Number(process.env.ID_LENGTH))` on an unset variable walked past `21` and answered the
+ * empty string. `min: 1` for the reason `randomHex` gives.
+ */
 export function nanoid(length = 21): string {
-  const bytes = randomBytes(length);
+  const bytes = randomBytes(finiteCount('nanoid', 'length', length, 1));
   let out = '';
   for (const byte of bytes) out += NANO_ALPHABET[byte & 63] as string;
   return out;

package/src/image/pipeline.ts

@@ -3,6 +3,7 @@
 // copy: responsive variants, blur placeholders and PWA icons are the same three steps with
 // different numbers, and a framework that generated them twice would drift twice.
 
+import { assert } from '../assert';
 import { composeOnto, layOut, type ResizeSpec } from './canvas';
 import { imageFromBunError, imageUnsupported } from './errors';
 import { unshared } from './png-bytes';
@@ -34,6 +35,27 @@ export const canEncode = (format: string): format is EncodableFormat =>
 /** 1-100, lossy formats only. Bun's own default, pinned here so output cannot drift with it. */
 export const DEFAULT_IMAGE_QUALITY = 80;
 
+/**
+ * The encoder CLAMPS and never refuses, which is why this is a screen and not a comment. Exported
+ * because `@ultimat3/storage` mints a variant KEY from the same number without ever reaching this
+ * pipeline — two screens that refuse different qualities would mint `q150` keys for bytes this
+ * encoder goes on to refuse, which is the dead-on-arrival shape `buildSignedUrl`'s own
+ * `finiteCount` screen already exists for — that package held a private `assertFiniteSignedUrlBound`
+ * until this sweep collapsed it onto the tier-0 check. Measured
+ * on a 3x2 PNG re-encoded as JPEG: quality 80 wrote 663 bytes, and `NaN`, `-5` and `0` each wrote
+ * 635 — the worst encoding the codec can make — while `Infinity` and `1e9` each wrote 719. Every
+ * one of them silently. `Number(url.searchParams.get('q'))` is `NaN` when the parameter is absent,
+ * so the degraded image is the one an unparameterised URL gets.
+ */
+export const assertFiniteImageQuality = (quality: number): number => {
+  assert(
+    Number.isInteger(quality) && quality >= 1 && quality <= 100,
+    `image quality is ${String(quality)}, and the encoder clamps rather than refusing: it must be a whole number from 1 to 100`,
+    `pass a whole quality from 1 to 100 — transformImageBytes(bytes, { quality: ${String(DEFAULT_IMAGE_QUALITY)} }) — and parse a query value before you pass it`,
+  );
+  return quality;
+};
+
 const encodeFix =
   "request 'png', 'jpeg' or 'webp', or route the transform through an ImageTransformDriver (a " +
   'CDN or an external encoder) that can produce it';
@@ -86,7 +108,7 @@ export async function transformImageBytes(
   if (format !== undefined && !canEncode(format)) {
     throw imageUnsupported(`encoding ${format} is not built in`, encodeFix, { format });
   }
-  const quality = spec.quality ?? DEFAULT_IMAGE_QUALITY;
+  const quality = assertFiniteImageQuality(spec.quality ?? DEFAULT_IMAGE_QUALITY);
   const source = await run('reading the image header', () => bunImage(bytes).metadata());
   const output: EncodableFormat = format ?? (canEncode(source.format) ? source.format : 'png');
   const layout = layOut(source, spec);

package/src/index.ts

@@ -390,6 +390,7 @@ export {
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
+export { finiteCount, finiteOption } from './finite-option';
 export type {
   FlightGate,
   FlightGateLimits,
@@ -432,6 +433,7 @@ export type {
   ImageTransformSpec,
 } from './image/pipeline';
 export {
+  assertFiniteImageQuality,
   blurDataUrl,
   canDecode,
   canEncode,
@@ -453,7 +455,13 @@ export {
   rasterFrom,
 } from './image/raster';
 export { impersonate, impersonationReason, isImpersonating } from './impersonate';
-export { cachedFormatter, canonicalLocale, MAX_CACHED_FORMATTERS } from './intl-cache';
+export {
+  assertLocale,
+  cachedFormatter,
+  canonicalLocale,
+  localeInvalid,
+  MAX_CACHED_FORMATTERS,
+} from './intl-cache';
 export { isJsonObject } from './json-object';
 export type {
   HealthPayload,

package/src/intl-cache.ts

@@ -1,8 +1,11 @@
-// One bounded cache, on one canonical key, for every `Intl` formatter the framework builds.
+// One bounded cache, on one canonical key, and one screen, 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.
 
+import { UltimateError } from './errors';
+
 /**
  * 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
@@ -41,3 +44,41 @@ export function canonicalLocale(locale: string): string | undefined {
     return undefined;
   }
 }
+
+/**
+ * A tag `Intl` cannot parse. Distinct from `@ultimat3/i18n`'s `X_LOCALE_UNSUPPORTED`, which is a
+ * well-formed tag outside the app's supported set — this one is not a tag at all, and a raw
+ * `RangeError` out of a formatter says nothing about which caller supplied it.
+ */
+export function localeInvalid(locale: string): UltimateError {
+  return new UltimateError({
+    code: 'X_LOCALE_INVALID',
+    cause: `"${locale}" is not a well-formed BCP 47 language tag`,
+    fix: "pass a tag like 'en', 'en-GB' or 'de-DE' — screen a header-supplied value with Intl.DateTimeFormat.supportedLocalesOf([tag]) before it reaches a formatter",
+  });
+}
+
+/**
+ * The canonical spelling of a well-formed tag, or `X_LOCALE_INVALID`. The ONE screen a
+ * caller-supplied BCP 47 tag passes before it reaches an `Intl` constructor.
+ *
+ * Validating and keying are one step, which is why this lives beside the cache rather than in
+ * either caller: `getCanonicalLocales` runs exactly the structural check
+ * `Intl.DateTimeFormat.supportedLocalesOf` throws on — what the `fix:` above tells the caller to
+ * run — and unlike it hands back the spelling every formatter cache keys on, so `EN-us` and
+ * `en-US` cannot mint two entries for one locale.
+ *
+ * It is tier 0 for the reason `cachedFormatter` is: `@ultimat3/time` and `@ultimat3/money` both
+ * need it and `money -> time` is a sideways import `bun run boundaries` refuses. Money was the
+ * last package still letting the tag through — a `RangeError` off an `Accept-Language` header —
+ * on the argument that this seam "decides a cache key, never whether a locale is acceptable",
+ * which is true of the cache and was never an argument for passing the tag on.
+ *
+ * Well-formed but unknown to this runtime's ICU (`zz`) is NOT refused: `Intl` falls back for
+ * those, and a user carrying a locale the runtime has no data for must still get a rendered page.
+ */
+export function assertLocale(locale: string): string {
+  const tag = canonicalLocale(locale);
+  if (tag === undefined) throw localeInvalid(locale);
+  return tag;
+}

package/src/lifecycle.ts

@@ -4,6 +4,7 @@
 
 import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
+import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
@@ -49,6 +50,8 @@ export interface LifecycleOptions {
    * lapses and another worker re-claims it, which is what at-least-once already promises. The
    * alternative is not "the job finishes": it is the same duplicate, delivered by SIGKILL at the
    * kubelet's grace period, with no log line naming what overran.
+   *
+   * Screened where it is assigned: a whole number of milliseconds, 0 or more. `0` is "drain now".
    */
   readonly deadlineMs?: number | undefined;
   readonly clock?: Clock | undefined;
@@ -119,7 +122,15 @@ let idleWaiters: (() => void)[] = [];
 const readiness = new Map<string, ReadinessCheck>();
 
 export function configureLifecycle(options: LifecycleOptions): void {
-  if (options.deadlineMs !== undefined) deadlineMs = options.deadlineMs;
+  // Screened above the write, never beside the arithmetic: `Math.max(0, deadlineAt - monotonic())`
+  // PROPAGATES a NaN into `setTimeout(fn, NaN)`, i.e. 0 — measured, one in-flight operation dropped
+  // and a 300ms close hook ABANDONED 111ms into a 25s budget, while `X_SHUTDOWN_TIMEOUT` rendered
+  // `NaNms` and told the operator to RAISE a budget that was never a number. `min: 0` because 0 is
+  // a real budget — drain now, no grace — and `@ultimat3/http`'s `drainTimeoutMs` accepts 0 and
+  // hands it straight here, so a floor of 1 would refuse at boot what that package declares.
+  if (options.deadlineMs !== undefined) {
+    deadlineMs = finiteCount('configureLifecycle', 'deadlineMs', options.deadlineMs, 0);
+  }
   if (options.clock !== undefined) {
     clock = options.clock;
     startedAtMono = clock.monotonic();

package/src/metric-names.ts

@@ -0,0 +1,68 @@
+// Single responsibility: the identifier grammar every metric name and every LABEL name obeys, and
+// the one code that refuses a value outside it. Split out of `metrics.ts` because that file is at
+// the 500-line ceiling `x verify`'s `filesize` step enforces, and because the two refusals are one
+// rule asked of two things — the exposition format spells them identically.
+
+import { type CodedErrorInit, UltimateError } from './errors';
+import type { MetricAttributes } from './metrics-types';
+
+export class MetricNameInvalidError extends UltimateError {
+  static readonly code = 'X_METRIC_NAME_INVALID';
+  override readonly name = 'MetricNameInvalidError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: MetricNameInvalidError.code });
+  }
+}
+
+/**
+ * Lowercase snake, the intersection of what every exposition format accepts. OTel's dotted names
+ * survive an OTLP hop but not a Prometheus scrape, and the autoscaler reads the scrape.
+ */
+export const METRIC_NAME_RE = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * The suggestion both `fix:` lines below hand back, and it has to SATISFY `METRIC_NAME_RE`, not
+ * merely resemble it: the grammar's first character is `[a-z_]`, so lowercasing `2digits` left
+ * `2digits` and the refusal told the caller to rename the label to the same name it had just
+ * refused. An underscore prefix is the one repair that keeps the rest of the identifier — which is
+ * also what makes the empty string a nameable `_` rather than a second refusal.
+ */
+const snake = (value: string): string => {
+  const lowered = value.toLowerCase().replaceAll(/[^a-z0-9_]/g, '_');
+  return /^[a-z_]/.test(lowered) ? lowered : `_${lowered}`;
+};
+
+/** Refused at DECLARATION, where the instrument is still nameable. */
+export function assertMetricName(name: string): void {
+  if (METRIC_NAME_RE.test(name)) return;
+  throw new MetricNameInvalidError({
+    cause: `"${name}" is not lowercase snake_case matching ${METRIC_NAME_RE.source}`,
+    fix: `rename the instrument to lowercase snake_case, e.g. ${snake(name)}`,
+    meta: { name },
+  });
+}
+
+/**
+ * A LABEL name obeys that same grammar, and it was guarded nowhere: `metrics-text.ts` escapes the
+ * label VALUE and interpolates the KEY raw, so `bad"key` rendered `orders_total{bad"key="x"} 1`
+ * and a `\n` in one split the body into a line the scraper reads as a different series. A scraper
+ * rejects the WHOLE response over one unparseable line, so `http_requests_total`, `connections`
+ * and `queue_depth` — the three the chart's HPA reads — disappear together, and the autoscaler
+ * sees no signal rather than a bad one.
+ *
+ * Refused on the way in, never sanitised at render: a silently renamed label is a different
+ * series, and the point would land somewhere the dashboard querying the declared name cannot see.
+ * Once per label set the instrument has not seen — `seriesFor` calls this on its MISS, ahead of
+ * the cardinality ceiling, because the overflow branch answers without allocating a series and a
+ * check hung off the allocation would have made the refusal a function of how busy the process is.
+ */
+export function assertLabelNames(metric: string, attributes: MetricAttributes): void {
+  for (const label of Object.keys(attributes)) {
+    if (METRIC_NAME_RE.test(label)) continue;
+    throw new MetricNameInvalidError({
+      cause: `${metric} was given the label "${label}", which is not lowercase snake_case matching ${METRIC_NAME_RE.source} — the exposition line it renders is one no scraper can parse, and one bad line drops the whole scrape`,
+      fix: `rename the label at the call site to lowercase snake_case, e.g. { ${snake(label)}: … }`,
+      meta: { metric, label },
+    });
+  }
+}

package/src/metrics-text.ts

@@ -14,6 +14,12 @@ function escapeLabel(value: string): string {
   return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n');
 }
 
+/**
+ * The KEY is interpolated bare and the VALUE is escaped, which is the whole grammar: a label name
+ * is an identifier `metrics.ts` refuses at series creation (`X_METRIC_NAME_INVALID`), a label
+ * value is arbitrary text. Never sanitise a key here — a renamed label is a different series, and
+ * this function has no way to tell the dashboard that.
+ */
 function labels(attributes: MetricAttributes, extra?: readonly [string, string]): string {
   const pairs = Object.entries(attributes)
     .sort(([a], [b]) => (a < b ? -1 : 1))

package/src/metrics.ts

@@ -2,10 +2,12 @@
 // aggregated in process, read through one `collectMetrics()`. Shaped exactly like `telemetry.ts`:
 // always on, a no-op exporter by default, and the wire format supplied by a driver, never here.
 
+import { assert } from './assert';
 import { type Clock, systemClock } from './clock';
 import { renderThrowable } from './error-render';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { logger } from './logger';
+import { assertLabelNames, assertMetricName, MetricNameInvalidError } from './metric-names';
 import type {
   Counter,
   Gauge,
@@ -22,8 +24,10 @@ import type {
 } 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.
+// The data model and the identifier grammar are modules of their own; the public surface is
+// unchanged, so nothing that imports a metric type or the name error from here learns a second
+// path.
+export { MetricNameInvalidError } from './metric-names';
 export type {
   Counter,
   Gauge,
@@ -42,14 +46,6 @@ export type {
   ReadableMetric,
 } from './metrics-types';
 
-export class MetricNameInvalidError extends UltimateError {
-  static readonly code = 'X_METRIC_NAME_INVALID';
-  override readonly name = 'MetricNameInvalidError';
-  constructor(init: CodedErrorInit) {
-    super({ ...init, code: MetricNameInvalidError.code });
-  }
-}
-
 export class MetricValueInvalidError extends UltimateError {
   static readonly code = 'X_METRIC_VALUE_INVALID';
   override readonly name = 'MetricValueInvalidError';
@@ -88,12 +84,6 @@ export const DEFAULT_HISTOGRAM_BOUNDS: readonly number[] = Object.freeze([
   0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
 ]);
 
-/**
- * Lowercase snake, the intersection of what every exposition format accepts. OTel's dotted names
- * survive an OTLP hop but not a Prometheus scrape, and the autoscaler reads the scrape.
- */
-const METRIC_NAME_RE = /^[a-z_][a-z0-9_]*$/;
-
 export const noopMetricExporter: MetricExporter = Object.freeze({
   export(): void {
     // Intentionally empty: instruments are always live, and free until an exporter is configured.
@@ -231,13 +221,7 @@ function assertBounds(name: string, bounds: readonly number[] | undefined): void
 }
 
 function declare(name: string, kind: MetricKind, options: GaugeOptions & HistogramOptions) {
-  if (!METRIC_NAME_RE.test(name)) {
-    throw new MetricNameInvalidError({
-      cause: `"${name}" is not lowercase snake_case matching ${METRIC_NAME_RE.source}`,
-      fix: `rename the instrument to lowercase snake_case, e.g. ${name.toLowerCase().replaceAll(/[^a-z0-9_]/g, '_')}`,
-      meta: { name },
-    });
-  }
+  assertMetricName(name);
   assertBounds(name, options.bounds);
   const existing = instruments.get(name);
   if (existing !== undefined) {
@@ -367,6 +351,12 @@ function seriesFor(instrument: Instrument, attributes: MetricAttributes): Series
   const key = seriesKey(attributes);
   const found = instrument.series.get(key);
   if (found !== undefined) return found;
+  // On the MISS, ahead of the ceiling — never inside `createSeries`, which the overflow branch
+  // below returns without reaching. A screen that ran only where a series is BORN was a screen
+  // that depended on load: `bad"key` threw on a fresh process and was swallowed on a busy one,
+  // once the instrument had filled up, which is exactly when an unparseable label is likeliest to
+  // arrive. A hit needs no check — a key in the map passed this on the way in.
+  assertLabelNames(instrument.descriptor.name, attributes);
   if (instrument.series.size >= instrument.maxSeries) {
     reportOverflow(instrument);
     // Created directly rather than through this function again: the overflow series is the ONE
@@ -485,6 +475,14 @@ export function exportMetrics(): void {
  * — the drain hook, not this timer, decides when the process may leave.
  */
 export function startMetricExport(intervalMs = 60_000): () => void {
+  // A timer given a non-finite delay does not export less often — `setInterval(fn, NaN)` runs at
+  // 1ms in this Bun, measured, so a `Number(process.env.METRICS_INTERVAL_MS)` on an unset variable
+  // pushes a thousand collections a second for the life of the process.
+  assert(
+    Number.isSafeInteger(intervalMs) && intervalMs >= 1,
+    `startMetricExport was given ${String(intervalMs)}ms; an export interval is a whole number of at least 1ms, and a timer given anything else runs at 1ms`,
+    "pass a whole number of milliseconds — startMetricExport(60_000) — and parse an environment value first: Number(process.env.METRICS_INTERVAL_MS ?? '') is NaN when the variable is unset",
+  );
   const timer = setInterval(exportMetrics, intervalMs);
   timer.unref();
   return () => clearInterval(timer);

package/src/otlp-metric-exporter.ts

@@ -11,6 +11,7 @@ import type {
   ReadableMetric,
 } from './metrics';
 import {
+  assertFiniteOtlpBound,
   OTLP_SCOPE,
   otlpAttributes,
   otlpEndpoint,
@@ -118,7 +119,7 @@ export interface OtlpMetricExporter extends MetricExporter {
 export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): OtlpMetricExporter {
   const url = otlpEndpoint('metrics', options.endpoint);
   const headers = otlpHeaders(options.headers);
-  const timeoutMs = options.timeoutMs ?? 10_000;
+  const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
   let startedAtMs = options.startedAtMs;
   let inflight: Promise<void> = Promise.resolve();

package/src/otlp-span-exporter.ts

@@ -4,6 +4,7 @@
 import { renderThrowable } from './error-render';
 import { logger } from './logger';
 import {
+  assertFiniteOtlpBound,
   OTLP_SCOPE,
   type OtlpKeyValue,
   otlpAttributes,
@@ -126,9 +127,13 @@ export interface OtlpSpanExporter extends SpanExporter {
 export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpanExporter {
   const url = otlpEndpoint('traces', options.endpoint);
   const headers = otlpHeaders(options.headers);
-  const maxBatchSize = options.maxBatchSize ?? 512;
-  const maxQueueSize = options.maxQueueSize ?? 2048;
-  const timeoutMs = options.timeoutMs ?? 10_000;
+  const maxBatchSize = assertFiniteOtlpBound('maxBatchSize', options.maxBatchSize ?? 512);
+  const maxQueueSize = assertFiniteOtlpBound('maxQueueSize', options.maxQueueSize ?? 2048);
+  const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
+  const flushIntervalMs = assertFiniteOtlpBound(
+    'flushIntervalMs',
+    options.flushIntervalMs ?? 5_000,
+  );
   const send = options.fetch ?? globalThis.fetch;
   const queue: ReadableSpan[] = [];
   let inflight: Promise<void> = Promise.resolve();
@@ -173,7 +178,7 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
 
   // Unref'd, so a pending flush never holds a draining process open — `shutdown()` is what
   // decides the last batch leaves, exactly as `startMetricExport` defers to the drain hook.
-  const timer = setInterval(() => void drainQueue(), options.flushIntervalMs ?? 5_000);
+  const timer = setInterval(() => void drainQueue(), flushIntervalMs);
   timer.unref();
 
   return {

package/src/otlp.ts

@@ -2,6 +2,7 @@
 // an operator already sets, header parsing, the OTLP/JSON value encoding, and one POST that never
 // throws. A serialisation, not a vendor (axiom 7), exactly as `metrics-text.ts` is to Prometheus.
 
+import { assert } from './assert';
 import { renderThrowable } from './error-render';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { logger } from './logger';
@@ -111,6 +112,29 @@ export function tryOtlpEndpoint(
 }
 
 /** The endpoint, or a coded error naming the variable to set. */
+/**
+ * A batch size, a queue bound or a millisecond budget, screened where the exporter is CONSTRUCTED.
+ *
+ * These arrive as `Number(process.env.OTEL_…)` as often as literals, and `NaN` is not nullish so
+ * `??` keeps it. What follows is never a wrong number: `setInterval(fn, NaN)` runs at 1ms in this
+ * Bun (measured, with a `TimeoutNaNWarning`), so the collector is POSTed a thousand times a
+ * second; `AbortSignal.timeout(NaN)` throws, and `postOtlp` swallows it, so every export fails
+ * with one warn line and the traces simply stop; and `queue.length >= NaN` is false, so a bound
+ * that exists to be a bound stops being one. `X_INVARIANT` rather than a fourth `X_OTLP_*` code:
+ * the three here name the endpoint, the headers and the protocol, and this is none of those.
+ *
+ * The `Finite` in the name is load-bearing: `bun run finite-bounds` recognises a repair by the
+ * shape of the CALL, so a screen named for its subject alone is invisible to the ratchet.
+ */
+export function assertFiniteOtlpBound(option: string, value: number): number {
+  assert(
+    Number.isSafeInteger(value) && value >= 1,
+    `otlp exporter option ${option} is ${String(value)}; it must be a whole number of at least 1 — a comparison against a non-finite bound is false for every value, and a timer given one runs at 1ms`,
+    `pass a whole number for ${option}, and parse an environment value before you pass it: Number(process.env.OTEL_BSP_SCHEDULE_DELAY ?? '') is NaN when the variable is unset`,
+  );
+  return value;
+}
+
 export function otlpEndpoint(
   signal: OtlpSignal,
   explicit?: string | undefined,

package/src/read-capped.ts

@@ -4,6 +4,8 @@
 // `@ultimat3/mcp` (tier 4) serves a bare `Request` that never passes through http's pipeline —
 // `await request.json()` there was governed only by Bun's 128 MiB default.
 
+import { assert } from './assert';
+
 /** What a body read produced: the bytes, or the running total at the moment it went over. */
 export type CappedBody = { readonly bytes: Uint8Array } | { readonly over: number };
 
@@ -17,6 +19,18 @@ export const readWithinLimit = async (
   body: ReadableStream<Uint8Array> | null,
   limit: number,
 ): Promise<CappedBody> => {
+  // The cap is this function's whole contract, so it is screened here and not by each caller in
+  // turn. `total > NaN` is false for every chunk, so a non-finite limit does not RAISE the ceiling
+  // — it removes it, and the payload the caller was promised would never be held in full is held
+  // in full. Both callers reach it from configuration (`@ultimat3/http`'s `bodyLimitBytes`,
+  // `@ultimat3/mcp`'s own), and `Number(process.env.…)` on an unset variable is `NaN`. Before the
+  // body is touched: a cap this wrong is the caller's bug, not the peer's, and cancelling their
+  // stream over it would be answering the wrong party.
+  assert(
+    Number.isSafeInteger(limit) && limit >= 0,
+    `readWithinLimit was given a limit of ${String(limit)}; a byte cap is a whole number of zero or more, and every comparison against a non-finite one is false, so the read is unbounded rather than capped`,
+    "pass a whole number of bytes — readWithinLimit(request.body, 1_048_576) — and parse an environment value before you pass it: Number(process.env.BODY_LIMIT_BYTES ?? '') is NaN when the variable is unset",
+  );
   if (body === null) return { bytes: new Uint8Array(0) };
   const reader = body.getReader();
   const chunks: Uint8Array[] = [];
@@ -26,15 +40,19 @@ export const readWithinLimit = async (
       const { done, value } = await reader.read();
       if (done) break;
       total += value.byteLength;
-      if (total > limit) {
-        // Cancelled rather than drained: the peer is told to stop sending, and nothing past the
-        // cap is ever held. Draining is how a rejected request still costs its full transfer.
-        await reader.cancel();
-        return { over: total };
-      }
+      // Cancelled rather than drained, in the `finally` below: the peer is told to stop sending,
+      // and nothing past the cap is ever held. Draining is how a rejected request still costs its
+      // full transfer.
+      if (total > limit) return { over: total };
       chunks.push(value);
     }
   } finally {
+    // Cancel rather than merely release — `@ultimat3/storage`'s `readWithin` is the same bounded
+    // read and states the same rule: a refused body must stop arriving, not keep filling a socket
+    // buffer nobody will read. Swallowed, because a cancellation that fails on the way out must
+    // not replace the answer this function computed: an unguarded `cancel()` turned the 413 into
+    // whatever the stream threw. A completed stream answers it as a no-op.
+    await reader.cancel().catch(() => undefined);
     reader.releaseLock();
   }
   const bytes = new Uint8Array(total);

package/src/sampler.ts

@@ -9,9 +9,20 @@ import type { SpanAttributes, SpanContext } from './telemetry';
  * The seam. `parent` is the inbound span context when there is one — an upstream that decided
  * "not sampled" has said so in `parent.traceFlags`, and a sampler that ignores it splits one
  * distributed trace into a sampled half and an unsampled half, which is worse than either.
+ *
+ * `traceId` is the id of the span being CREATED — the parent's carried forward, or the one this
+ * process just minted for a root. It is an argument of its own for the same reason OTel makes it
+ * one: a trace-id-hashing sampler has to answer for a ROOT too, where there is no parent to read
+ * the id off, and every span of one trace has to reach the same answer or the collector is handed
+ * orphans. An implementation that ignores it (`always_on`, `parentbased_*`) simply omits it.
  */
 export interface Sampler {
-  shouldSample(name: string, parent: SpanContext | undefined, attributes: SpanAttributes): boolean;
+  shouldSample(
+    name: string,
+    parent: SpanContext | undefined,
+    attributes: SpanAttributes,
+    traceId: string,
+  ): boolean;
 }
 
 export const OTEL_SAMPLER_KEY = 'OTEL_TRACES_SAMPLER';
@@ -55,13 +66,38 @@ export function parentBasedRatioSampler(
   };
 }
 
-/** `always_off` / `always_on` without the parent-based prefix ignore the inbound decision. */
+/** The 64-bit space OTel's `TraceIdRatioBased` compares the low 8 bytes of a trace id against. */
+const TRACE_ID_SPACE = 2 ** 64;
+
+const TRACE_ID_HEX = /^[0-9a-f]{32}$/;
+
+/**
+ * OTel's `TraceIdRatioBased`: the LOW 8 bytes of the trace id as a big-endian unsigned integer,
+ * against `ratio` of the 2^64 space. Answers `undefined` for anything that is not a 32-hex trace
+ * id, so the caller decides what to do with an id no hash can read rather than this silently
+ * sampling or silently dropping it.
+ */
+function traceIdSampled(traceId: string, ratio: number): boolean | undefined {
+  if (!TRACE_ID_HEX.test(traceId)) return undefined;
+  return BigInt(`0x${traceId.slice(16)}`) < BigInt(Math.floor(ratio * TRACE_ID_SPACE));
+}
+
+/**
+ * `traceidratio` — the OTel spelling that ignores the inbound decision and hashes the TRACE ID.
+ *
+ * The hash is the whole of it, and a roll is not a substitute: `startSpan` asks the sampler for
+ * every span, root and child alike, so a `random()` here re-decided per span and one trace left
+ * as a sampled half and an unsampled half — measured at 0.5, an unexported root with eight of its
+ * twenty children at the collector. Hashing the id makes the answer a function of the trace, which
+ * is what the name of this sampler means and what lets a second SERVICE agree with us unprompted.
+ * `random` survives only for an id no hash can read, and stays injectable so that path is a test.
+ */
 export function ratioSampler(ratio: number, random: () => number = Math.random): Sampler {
   return {
-    shouldSample(): boolean {
+    shouldSample(_name, _parent, _attributes, traceId): boolean {
       if (ratio >= 1) return true;
       if (ratio <= 0) return false;
-      return random() < ratio;
+      return traceIdSampled(traceId, ratio) ?? random() < ratio;
     },
   };
 }

package/src/telemetry.ts

@@ -201,10 +201,13 @@ export function startSpan(name: string, options?: StartSpanOptions): Span {
   // so one trace is sampled or not sampled as a whole. Before this, `traceFlags` was hardcoded to
   // 1 for a root and `end()` exported regardless, which made the bit a value the framework
   // forwarded and nobody obeyed.
+  // The id is resolved BEFORE the decision, because the decision may be a function of it: a
+  // `traceidratio` sampler hashes the trace id, and a root's id exists nowhere else to hash.
+  const traceId = parent?.traceId ?? newTraceId();
   const context: SpanContext = {
-    traceId: parent?.traceId ?? newTraceId(),
+    traceId,
     spanId: newSpanId(),
-    traceFlags: currentSampler().shouldSample(name, inbound, attributes) ? 1 : 0,
+    traceFlags: currentSampler().shouldSample(name, inbound, attributes, traceId) ? 1 : 0,
   };
   const events: SpanEvent[] = [];
   const startedAt = clock.now().getTime();