@ultimat3/core 16.0.0 → 18.0.0

package/src/error-render.ts

@@ -252,57 +252,14 @@ export function renderMetaRecord(
  * There is no dev-only escape hatch on purpose — a flag is one misconfigured environment away
  * from being the same breach.
  *
- * A deliberate duplicate of `describeValue` in `packages/schema/src/describe-value.ts`, for the
- * reason `SCHEMA_ERROR_CODE_TITLES` is one: `@ultimat3/schema` is tier 0 alongside this package,
- * so neither may import the other. Keep the two answering IDENTICALLY — that is what
- * `packages/cli/src/describe-value-pin.test.ts` holds — and changing one alone is the bug.
- */
-export function describeValue(value: unknown): string {
-  if (value === undefined) return 'undefined';
-  if (value === null) return 'null';
-  switch (typeof value) {
-    case 'string':
-      return countOf(charCount(value), 'string', 'character');
-    case 'number':
-      return describeNumber(value);
-    case 'boolean':
-      return 'a boolean';
-    case 'bigint':
-      return 'a bigint';
-    case 'symbol':
-      return 'a symbol';
-    case 'function':
-      return 'a function';
-    default:
-      break;
-  }
-  if (Array.isArray(value)) return countOf(value.length, 'array', 'item');
-  // `getTime()` rather than a value: an invalid Date is the one Date fact a caller can act on.
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? 'an invalid Date' : 'a Date';
-  return 'an object';
-}
-
-function describeNumber(value: number): string {
-  if (Number.isNaN(value)) return 'NaN';
-  if (value === Number.POSITIVE_INFINITY) return 'Infinity';
-  if (value === Number.NEGATIVE_INFINITY) return '-Infinity';
-  return 'a number';
-}
-
-function countOf(size: number, noun: string, unit: string): string {
-  if (size === 0) return `an empty ${noun}`;
-  const article = noun === 'array' ? 'an' : 'a';
-  return `${article} ${noun} of ${size} ${unit}${size === 1 ? '' : 's'}`;
-}
-
-/**
- * The twin of `@ultimat3/schema`'s `char-count.ts`, duplicated for the same reason `describeValue`
- * is: both packages are tier 0 and neither may import the other. Code points, because the rules
- * that reject a string count in them and the message must quote the same unit — `'👍'.length` is 2.
- * Only a surrogate makes the two counts differ, so every ASCII value keeps the O(1) read.
+ * DECLARED IN `@ultimat3/schema` and re-exported here, `As of 2026-08-27`. It was a
+ * character-for-character copy of `packages/schema/src/describe-value.ts` — the two tier-0
+ * packages could not import each other — held equal by a 63-line behavioural pin in
+ * `@ultimat3/cli`, a TIER-5 package, that no rule required to exist. Whose function it is has not
+ * changed: schema's `expected()` is the other reader, and a widening that leaks a value is now one
+ * edit in one file rather than two files that can drift apart in silence.
+ *
+ * `charCount` went with it — the same duplication, one call deep — so the unit a message quotes
+ * and the unit a length rule counts in are the same code, not two files that agree today.
  */
-const HAS_SURROGATE = /[\uD800-\uDBFF]/;
-
-function charCount(value: string): number {
-  return HAS_SURROGATE.test(value) ? [...value].length : value.length;
-}
+export { describeValue } from '@ultimat3/schema';

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

@@ -65,13 +65,15 @@ export type {
   DatabaseConfig,
   JobsConfig,
   McpConfig,
-  PwaConfig,
+  NotifyConfig,
   RealtimeConfig,
   RealtimeTransport,
   ThemeConfig,
   ThemeMode,
 } from './config';
-export { defineConfig } from './config';
+export { defineConfig, INBOX_RETENTION_KEYS } from './config';
+export type { PwaColors, PwaConfig, PwaSchemeColors } from './config-pwa';
+export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
   createContext,
@@ -390,6 +392,7 @@ export {
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
+export { finiteCount, finiteOption } from './finite-option';
 export type {
   FlightGate,
   FlightGateLimits,
@@ -432,6 +435,7 @@ export type {
   ImageTransformSpec,
 } from './image/pipeline';
 export {
+  assertFiniteImageQuality,
   blurDataUrl,
   canDecode,
   canEncode,
@@ -453,7 +457,14 @@ 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,
+  MAX_LOCALE_EXCERPT,
+} 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
@@ -24,6 +27,16 @@ export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: ()
   return formatter;
 }
 
+/**
+ * The cap on the tag an `X_LOCALE_INVALID` cause quotes back, in code points.
+ *
+ * 35 is RFC 5646 §4.4.1's own number — Figure 7 derives it as the longest tag the registry can
+ * form (language 8 + script 5 + region 4 + two variants 9+9), and the same section says a protocol
+ * with a fixed buffer "MUST allow for language tags of at least 35 characters". So every tag a
+ * caller could legitimately have meant fits, and nothing longer is a tag being debugged.
+ */
+export const MAX_LOCALE_EXCERPT = 35;
+
 /**
  * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
  * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
@@ -41,3 +54,77 @@ 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: `${localeExcerpt(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 raw tag, under a NAME. A `cause` is copied into the 400 body and into the log line by
+    // `@ultimat3/http`'s `toProblem`, and a logger redacts by key — so a caller's value spliced
+    // into prose has no key left to redact, which is the whole argument `describeValue` rests on.
+    // `meta` is the key, and it is machine-read, so it carries the value WHOLE: an excerpt here
+    // would be a value a redactor or a bug report reads as complete when it is not.
+    meta: { locale },
+  });
+}
+
+/**
+ * The tag as a reader can act on it: the first `MAX_LOCALE_EXCERPT` code points, quoted, and SAID
+ * to be cut when there were more.
+ *
+ * `describeValue` is the usual answer for a caller-supplied value in a `cause` and it is the wrong
+ * one here — it renders `en_US` as "a 5-character string", deleting the only actionable content in
+ * a sentence whose entire job is to say WHICH tag was refused. Bounding it keeps the diagnostic and
+ * removes the part a stranger chooses: without a cap the whole of an `Accept-Language` value —
+ * megabytes, at the caller's option — became the error's `message`, its 400 body and its log line.
+ *
+ * Code points, never `slice`: cutting between a surrogate pair leaves a lone surrogate, which is
+ * not text and survives no encoder between here and the log index. The string iterator is lazy, so
+ * a megabyte tag costs 35 steps rather than a megabyte-long array.
+ *
+ * No escaping here: `UltimateError`'s constructor runs `singleLine` over every line-bearing field
+ * exactly once, which is what keeps a newline in a tag from writing a second line an operator reads
+ * as a genuine framework message. A second pass at this call site would be a second place that has
+ * to be right.
+ */
+function localeExcerpt(locale: string): string {
+  let head = '';
+  let taken = 0;
+  for (const char of locale) {
+    if (taken === MAX_LOCALE_EXCERPT) return `"${head}" (truncated at ${taken} characters)`;
+    head += char;
+    taken += 1;
+  }
+  return `"${head}"`;
+}
+
+/**
+ * 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 {