@ultimat3/core 22.15.0 → 24.0.0

package/src/image/png-pixels.ts

@@ -3,6 +3,14 @@
 // safe zone `@ultimat3/pwa` promises is a composite. So this file exists for exactly that one hop:
 // Bun re-encodes to PNG, this reads the pixels back, `canvas.ts` blits, this writes them again.
 
+// why: `Bun.inflateSync` takes no output bound — measured, it ignores `maxOutputLength` and
+// returns the whole stream — and `DecompressionStream` is async where this seam is synchronous.
+// `node:zlib` is the one inflate here that can be told when to stop. A NAMESPACE import, never a
+// named one: the browser polyfill of this module has no `inflateRawSync`, and a named import of a
+// missing export fails the BUNDLE of every browser graph that reaches the barrel
+// (`async-context.test.ts` builds one) — for a function no browser ever calls.
+import * as zlib from 'node:zlib';
+import { stringField } from '../error-render';
 import { imageDecodeFailed, imageUnsupported } from './errors';
 import {
   adler32,
@@ -14,7 +22,7 @@ import {
   unshared,
   writeU32,
 } from './png-bytes';
-import { type Raster, rasterFrom } from './raster';
+import { assertPixelBudget, type Raster, rasterFrom } from './raster';
 
 /** Truecolour with alpha, 8 bits per channel — the ONE shape `Raster` is. */
 const RGBA_COLOR_TYPE = 8 << 4;
@@ -105,8 +113,13 @@ function readHeader(bytes: Uint8Array): PngHeader {
   return { width: readU32(bytes, 16), height: readU32(bytes, 20) };
 }
 
-/** Every IDAT concatenated: a PNG may split its stream across any number of them. */
-function idatStream(bytes: Uint8Array): Uint8Array {
+/**
+ * Every IDAT concatenated — a PNG may split its stream across any number of them — and inflated
+ * to AT MOST `limit` bytes, which is what the header says the pixels need. Inflating first and
+ * measuring after is the decompression bomb: deflate packs zeros ~1000:1, so a file of a few
+ * hundred kilobytes declaring 1x1 allocated hundreds of megabytes before anything compared it to 5.
+ */
+function idatStream(bytes: Uint8Array, limit: number): Uint8Array {
   const parts: Uint8Array[] = [];
   let at = 8;
   while (at + 12 <= bytes.length) {
@@ -123,8 +136,16 @@ function idatStream(bytes: Uint8Array): Uint8Array {
   try {
     // The 2-byte zlib header and the 4-byte Adler-32 trailer are PNG's envelope, stripped here
     // so the payload inflates as RAW deflate — see the encoder above for the mirror image.
-    return Bun.inflateSync(unshared(stream.subarray(2, stream.length - 4)), { windowBits: -15 });
-  } catch {
+    return zlib.inflateRawSync(unshared(stream.subarray(2, stream.length - 4)), {
+      maxOutputLength: limit,
+    });
+  } catch (error) {
+    if (stringField(error, 'code') === 'ERR_BUFFER_TOO_LARGE') {
+      throw imageDecodeFailed(
+        `the PNG IDAT stream inflates to more than the ${limit} bytes its header's size needs`,
+        { length: stream.length, limit },
+      );
+    }
     throw imageDecodeFailed(`the PNG IDAT stream (${stream.length} bytes) could not be inflated`, {
       length: stream.length,
     });
@@ -171,8 +192,10 @@ function unfilter(raw: Uint8Array, width: number, height: number): Uint8ClampedA
 /** PNG bytes to RGBA pixels. Refuses anything but 8-bit RGBA, naming the pipeline that reads it. */
 export function decodeImage(bytes: Uint8Array): Raster {
   const { width, height } = readHeader(bytes);
-  const raw = idatStream(bytes);
+  // From the HEADER, before the stream is touched: it bounds `expected`, which bounds the inflate.
+  assertPixelBudget(width, height, 'PNG');
   const expected = (width * BYTES_PER_PIXEL + 1) * height;
+  const raw = idatStream(bytes, expected);
   if (raw.length !== expected) {
     throw imageDecodeFailed(
       `the PNG inflates to ${raw.length} bytes but ${width}x${height} RGBA needs ${expected}`,

package/src/image/probe.ts

@@ -66,8 +66,13 @@ function requireBytes(bytes: Uint8Array, needed: number, format: string, missing
 
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const;
 
-/** `mif1` is the generic HEIF brand AVIF files carry; `avis` is an image sequence. */
-const AVIF_BRANDS: ReadonlySet<string> = new Set(['avif', 'avis', 'mif1']);
+/**
+ * `avif` is a still, `avis` an image sequence. NOT `mif1`: that is the generic HEIF brand, which
+ * an AVIF file lists as a COMPATIBLE brand and a HEIC file lists too — counting it sniffed every
+ * iPhone photo as AVIF, and the probe then read (or failed to read) it as one. An AVIF whose major
+ * brand is `mif1` still names `avif` among its compatible brands, which the scan below reads.
+ */
+const AVIF_BRANDS: ReadonlySet<string> = new Set(['avif', 'avis']);
 
 function isAvif(bytes: Uint8Array): boolean {
   if (!ascii(bytes, 4, 'ftyp')) return false;

package/src/image/raster.ts

@@ -25,7 +25,9 @@ export const MAX_IMAGE_PIXELS = 64_000_000;
 /** Checked from the header before a single byte is allocated. */
 export function assertPixelBudget(width: number, height: number, source: string): void {
   if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
-    throw imageTooLarge(`${source} declares a ${width}x${height} image, which is not a size`, {
+    // Decode-failed, not too-large: a header declaring zero, a fraction or `NaN` pixels is
+    // inconsistent bytes, and the too-large fix — downscale it — has nothing to act on.
+    throw imageDecodeFailed(`${source} declares a ${width}x${height} image, which is not a size`, {
       width,
       height,
       source,

package/src/index.ts

@@ -165,6 +165,8 @@ export {
   useService,
   withChildContext,
 } from './context';
+/** The one `Cookie:` reader — auth, http and i18n each parsed the header and could not share it. */
+export { readCookie } from './cookie';
 export type { CursorPayload } from './cursor';
 export {
   CursorInvalidError,
@@ -465,11 +467,15 @@ export type {
   FlightGateState,
 } from './flight-gate';
 export { createFlightGate, gateOverloaded } from './flight-gate';
+export { fnv1a } from './fnv1a';
 export { formatBytes } from './format-bytes';
 export type { GenerationFence } from './generation-fence';
 export { createFence, isSuperseded } from './generation-fence';
+export type { PublicHealthBody } from './health-disclosure';
+export { DEFAULT_HEALTH_DETAIL_PEERS, healthBody, healthPeerListed } from './health-disclosure';
 export type { HostDecision, HostRule } from './host-rules';
 export { ANY_HOST, hostDecision, hostMatches } from './host-rules';
+export { escapeHtml } from './html-escape';
 export type { Brand, Id } from './ids';
 export {
   isSpanId,
@@ -585,6 +591,9 @@ export type { Direction } from './locale-direction';
 export { directionOf, isRtl } from './locale-direction';
 export type { LocalePathSplit } from './locale-path';
 export { localeSegment, localizePath, splitLocalePath } from './locale-path';
+// The process logger's test seam, beside nothing it groups with: where a default-writer line goes.
+export type { LogSink } from './logger';
+export { setLogSink } from './logger';
 export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
 export type { MeasurementActorFactory } from './measurement-actor';
 export {
@@ -604,12 +613,18 @@ export {
   CLIENT_NAVIGATION_LOCATION_HEADER,
   CLIENT_NAVIGATION_SCOPE_HEADER,
   CLIENT_NAVIGATION_SURFACE_HEADER,
+  CLIENT_PATH_STYLE_META,
   CLIENT_PERSIST_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,
   CLIENT_SYNC_META,
   CLIENT_SYNC_WORKER_META,
 } from './page-meta';
+/** The structural Postgres seam http, auth, action and jobs share without a `@ultimat3/db` edge. */
+export type { PgExecutor } from './pg-executor';
+export type { ProcessMetricsOptions, ProcessReading } from './process-metrics';
+export { readProcess, resetProcessMetrics, startProcessMetrics } from './process-metrics';
+export { hasPublicCause, registerPublicCause, resetPublicCauses } from './public-cause';
 export { type CappedBody, readWithinLimit } from './read-capped';
 export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, encodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
@@ -640,6 +655,7 @@ export { retry, retryDecision } from './retry';
 export { isRetryableStatus, RETRYABLE_STATUSES } from './retryable-status';
 export type { ResolveRoleOptions, Role, RoleInfo, ScalingSignal } from './roles';
 export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
+export { routeRank } from './route-rank';
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
@@ -648,6 +664,20 @@ export {
   type OriginVerdict,
   proveSameOrigin,
 } from './same-origin';
+export type { SealOptions, SealPurposeOptions } from './seal';
+export { isSealed, open, openText, SEAL_VERSION, seal, sealAll, sealedKeyId } from './seal';
+export type { SealInvalidReason } from './seal-errors';
+export { SealInvalidError, SealKeyMissingError, SealKeyUnknownError } from './seal-errors';
+export type { SealKeyRing, SealKeySource } from './seal-keys';
+export {
+  resolveSealKeys,
+  SECRETS_RETIRED_KEYS_ENV,
+  sealKeyIds,
+  splitRetiredKeys,
+} from './seal-keys';
+// Beside the ring it is raised for, not in the `exports/secrets` group: same code as
+// `SecretsKeyInvalidError`, a different variable to repair.
+export { SecretsRingKeyInvalidError } from './secrets-errors';
 export {
   defineService,
   installedServices,
@@ -658,6 +688,8 @@ export {
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
 export { createSingleFlight } from './single-flight';
 export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
+export type { StoreMode } from './store-mode';
+export { STORE_MODES, storeMode } from './store-mode';
 export { timingSafeEqual } from './timing-safe-equal';
 export {
   frameworkVersion,

package/src/logger.ts

@@ -54,11 +54,10 @@ export interface LoggerOptions {
 }
 
 /**
- * LOWERCASE, always: `isRedactedKey` lowercases its lookup, so `apiKey`/`accessToken`/
- * `refreshToken` sat here for three releases matching nothing — and those are the exact field
- * names on `@ultimat3/auth`'s `OAuthTokens`. Matching is exact-key and never substring, so a
- * spelling that is not in this set is not redacted: both the camel and the snake wire spelling of
- * each credential is listed. Add through `redactKeys()` (which lowercases) rather than here.
+ * The exact-key FAST PATH. LOWERCASE, always: `isRedactedKey` lowercases its lookup, so
+ * `apiKey`/`accessToken`/`refreshToken` sat here for three releases matching nothing — and those
+ * are the exact field names on `@ultimat3/auth`'s `OAuthTokens`. Add through `redactKeys()` (which
+ * lowercases) rather than here. A name this set misses still meets `CREDENTIAL_NAME` below.
  */
 const redactedKeys = new Set<string>([
   'password',
@@ -81,15 +80,69 @@ const redactedKeys = new Set<string>([
   'client_secret',
   'privatekey',
   'private_key',
+  // The framework's own columns (`@ultimat3/auth`): a hash is what an offline guess runs against.
+  'passwordhash',
+  'tokenhash',
+  'keyhash',
 ]);
 
+/**
+ * The second half, for the names no list can enumerate. Exact-key matching alone let every
+ * COMPOUND credential through — `currentPassword`, `mfaSecret`, `resetToken`, `recoveryCode` — and
+ * `@ultimat3/action`'s audit walk asks this same predicate, so each was persisted in clear.
+ *
+ * Tested against the key lowercased with `_` and `-` removed, so one pattern covers the camel, the
+ * snake and the header spelling. It names what BEARS a credential and nothing wider, because a
+ * redacted field is one an operator cannot correlate on:
+ *
+ * - `password` / `passphrase` anywhere — no ordinary field carries the word.
+ * - `secret` as the LAST word (`mfaSecret`, `webhookSecret`, `appSecrets`, `secretAccessKey`), so
+ *   `clientSecretEnv` and `secretsPath` — a variable name and a path — stay readable.
+ * - a `token` is a bearer UNLESS its qualifier says it is not: fail closed, with the exceptions
+ *   named. `idempotencyToken`, `pageToken`, `continuationToken`, `cursorToken`, `syncToken` are
+ *   dedupe and paging keys an operator greps for; everything else ending in `token` — `resetToken`,
+ *   `githubToken`, `NPM_TOKEN` — is redacted without a provider list to keep current. The PLURAL
+ *   is the reverse: `maxTokens` / `inputTokens` are counts on every `@ultimat3/ai` usage line, so
+ *   `tokens` is redacted only behind a bearer qualifier (`accessTokens`).
+ * - key MATERIAL by its qualifier (`apiKey`, `privateKey`, `signingKey`, `encryptionKey`,
+ *   `masterKey`, `hmacKey`, `secretsKey`, `accessKey`, `retiredKeys`) and the id half of a key
+ *   pair (`accessKeyId`). A LOOKUP key — `cacheKey`, `primaryKey`, `idempotencyKey` — and a key's
+ *   own id (`signingKeyId`) carry no qualifier on this list and stay readable.
+ * - a value that EMBEDS a credential: `connectionString`, `dsn`, a registry `authConfig`, and the
+ *   service URLs that carry `user:password@` (`databaseUrl`, `REDIS_URL`). A bare `url` does not.
+ * - the one-time codes by name. Never a `code` suffix: that is the error contract's own field.
+ * - a stored hash of any of them: it is what an offline guess runs against.
+ *
+ * Built from constant alternatives with no nested quantifier, so there is no input it backtracks on.
+ */
+const CREDENTIAL_NAME = new RegExp(
+  [
+    'passw(?:or)?d|passphrase',
+    'secrets?$',
+    '(?:api|private|signing|encryption|master|hmac|secrets?|access|retired)keys?$|accesskeyid$',
+    '(?:token|key)hash(?:es)?$',
+    '(?<!idempotency|page|continuation|cursor|sync)token$',
+    '(?:access|refresh|id|session|reset|bearer|auth|api|csrf|xsrf|captcha|card|verification|invite|magic|magiclink|device|push|workload|oauth)tokens$',
+    'authconfig$|connectionstring$|dsn$',
+    '(?:database|db|redis|replication|nats|smtp|amqp|mongo)ur[li]s?$',
+    '^totp$|totpcode$|otp$|otpcode$',
+    '(?:recovery|backup|mfa)codes?(?:hash(?:es)?)?$',
+  ].join('|'),
+);
+
 /** Mark keys as secret everywhere. `defineEnv()` calls this for every `secret: true` var. */
 export function redactKeys(keys: Iterable<string>): void {
   for (const key of keys) redactedKeys.add(key.toLowerCase());
 }
 
+/**
+ * The framework's ONE answer to "is this field a credential?" — the log line, the error monitor's
+ * envelope and `@ultimat3/action`'s audit row all ask it, so a value that is `[redacted]` in one
+ * cannot be plaintext in another.
+ */
 export function isRedactedKey(key: string): boolean {
-  return redactedKeys.has(key.toLowerCase());
+  const lower = key.toLowerCase();
+  return redactedKeys.has(lower) || CREDENTIAL_NAME.test(lower.replace(/[_-]/g, ''));
 }
 
 /**
@@ -121,6 +174,28 @@ export function setLogStream(stream: 'stdout' | 'stderr'): void {
   logStream = stream;
 }
 
+/** What `setLogSink` installs: one complete JSON line, and the level it was written at. */
+export type LogSink = (line: string, level: LogLevel) => void;
+
+let logSink: LogSink | undefined;
+
+/**
+ * TEST SEAM. Every line with no explicit `writer` goes to `sink` INSTEAD of the process's streams,
+ * until it is cleared with `undefined`. Returns the sink that was installed, so a caller restores
+ * rather than clears — the shape `setRowObserver` has, for the same shared-process reason.
+ *
+ * It exists for two callers. A test preload installs a sink that drops every line, so a green run
+ * prints its reporter and nothing else; and a test that asserts on what the PROCESS logger wrote
+ * installs one that collects, instead of patching `process.stdout`. A logger given its own
+ * `writer` never reaches it, and the level is untouched: this decides where a line goes, never
+ * whether it is written.
+ */
+export function setLogSink(sink: LogSink | undefined): LogSink | undefined {
+  const previous = logSink;
+  logSink = sink;
+  return previous;
+}
+
 /**
  * The second half of the same defect, one call deeper than `envLevel`. A module init made safe
  * that still reached `process.stdout` here would only move the `ReferenceError` from load to the
@@ -135,6 +210,10 @@ export function setLogStream(stream: 'stdout' | 'stderr'): void {
  * its log stream, and where there is a `process` this writes to the fd as it always did.
  */
 function defaultWriter(line: string, level: LogLevel): void {
+  if (logSink !== undefined) {
+    logSink(line, level);
+    return;
+  }
   const toStderr = logStream === 'stderr' || LEVEL_WEIGHT[level] >= LEVEL_WEIGHT.error;
   if (typeof process === 'undefined') {
     if (toStderr) console.error(line);
@@ -198,7 +277,12 @@ function entryValue(source: Record<string, unknown>, key: string, depth: number)
   }
 }
 
-function redactFields(fields: LogFields): Record<string, unknown> {
+/**
+ * A caller's record made safe to SERIALISE and safe to SHIP: credentials replaced by key and by
+ * value, a bigint / cycle / hostile getter degraded per field. Exported for the one other sink
+ * that sends a caller's record off the box — `error-reporter-sentry.ts`.
+ */
+export function redactFields(fields: LogFields): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   const source = fields as Record<string, unknown>;
   // `Object.keys` before the values, so the read of each value is its own guarded step: a field
@@ -278,9 +362,18 @@ function timestamp(clock: Clock): string {
  */
 function envLevel(): LogLevel {
   const raw = typeof process === 'undefined' ? undefined : process.env['LOG_LEVEL'];
-  return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
-    ? (raw as LogLevel)
-    : 'info';
+  // Unset and EMPTY are the same answer — `LOG_LEVEL=` is how a compose file spells "not set".
+  if (raw === undefined || raw === '') return 'info';
+  // REFUSED, as `resolveLevel` refuses the same value from `createLogger({ level })`. It fell back
+  // to `info` in silence, so `LOG_LEVEL=verbose` — or `DEBUG`, the spelling half the ecosystem
+  // uses — gave an operator who asked for MORE lines fewer, and nothing said the variable was the
+  // reason. This runs at module init, so the refusal is the first thing the process prints.
+  assert(
+    (LOG_LEVELS as readonly string[]).includes(raw),
+    `LOG_LEVEL=${renderCauseValue(raw)} is not a log level`,
+    `set LOG_LEVEL=info (one of ${LOG_LEVELS.join(', ')}, lowercase), or unset LOG_LEVEL`,
+  );
+  return raw as LogLevel;
 }
 
 /**

package/src/nearest-name.ts

@@ -27,7 +27,16 @@ const distance = (a: string, b: string): number => {
 const MAX_EDITS = 3;
 
 /**
- * The nearest candidate within `MAX_EDITS`, or `undefined` when nothing is close enough. Ties keep
+ * The cutoff for one pair: `MAX_EDITS`, but never as many edits as the longer name has
+ * characters. A fixed 3 is a typo in `migrate` and a different word in `db` — replacing ALL of a
+ * one- or two-letter input costs at most its length, so `nearestName('a', ['db', 'gen'])`
+ * answered `db` with nothing typed in common.
+ */
+const cutoff = (input: string, candidate: string): number =>
+  Math.min(MAX_EDITS, Math.max(input.length, candidate.length) - 1);
+
+/**
+ * The nearest candidate within its cutoff, or `undefined` when nothing is close enough. Ties keep
  * the FIRST candidate, which is the order the caller declared them in — `definePermissions([...])`
  * and a `CommandSpec` list are both authored orders, and a stable answer is what lets a test pin one.
  */
@@ -36,7 +45,7 @@ export const nearestName = (input: string, candidates: readonly string[]): strin
   let bestScore = MAX_EDITS + 1;
   for (const candidate of candidates) {
     const score = distance(input, candidate);
-    if (score < bestScore) {
+    if (score < bestScore && score <= cutoff(input, candidate)) {
       best = candidate;
       bestScore = score;
     }

package/src/otlp-metric-exporter.ts

@@ -118,7 +118,7 @@ export interface OtlpMetricExporter extends MetricExporter {
  */
 export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): OtlpMetricExporter {
   const url = otlpEndpoint('metrics', options.endpoint);
-  const headers = otlpHeaders(options.headers);
+  const headers = otlpHeaders(options.headers, process.env, 'metrics');
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
   let startedAtMs = options.startedAtMs;

package/src/otlp-span-exporter.ts

@@ -126,7 +126,7 @@ export interface OtlpSpanExporter extends SpanExporter {
  */
 export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpanExporter {
   const url = otlpEndpoint('traces', options.endpoint);
-  const headers = otlpHeaders(options.headers);
+  const headers = otlpHeaders(options.headers, process.env, 'traces');
   const maxBatchSize = assertFiniteOtlpBound('maxBatchSize', options.maxBatchSize ?? 512);
   const maxQueueSize = assertFiniteOtlpBound('maxQueueSize', options.maxQueueSize ?? 2048);
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);

package/src/otlp.ts

@@ -96,7 +96,10 @@ function parseEndpoint(signal: OtlpSignal, raw: string, perSignal: boolean, env:
   // The spec's own asymmetry, not ours: a per-signal endpoint is the full URL an operator chose,
   // while the generic one is a base the signal path is appended to.
   if (perSignal) return url.toString();
-  return `${url.toString().replace(/\/+$/, '')}/v1/${signal}`;
+  // On the PATH, never on the string: `http://collector:4318?tenant=a` concatenated to
+  // `…/?tenant=a/v1/traces`, a request to `/` whose query merely ends in the receiver's path.
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/v1/${signal}`;
+  return url.toString();
 }
 
 /** The endpoint an operator configured, or `undefined` when they configured none. */
@@ -157,32 +160,43 @@ export function otlpEndpoint(
  * and no fix. Refused instead, naming the variable and the header KEY: the value is the
  * collector's credential and a `cause:` is folded into a log line.
  */
-function decodeHeaderValue(key: string, raw: string): string {
+function decodeHeaderValue(variable: string, key: string, raw: string): string {
   try {
     return decodeURIComponent(raw);
   } catch {
     throw new OtlpHeadersInvalidError({
-      cause: `${OTLP_HEADERS_KEY} carries a malformed percent-escape in the "${key}" value, so the header cannot be decoded`,
-      fix: `set ${OTLP_HEADERS_KEY}=${key}=<encoded>, where <encoded> is what bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints — or drop the stray % from the "${key}" value if it was meant literally`,
+      cause: `${variable} carries a malformed percent-escape in the "${key}" value, so the header cannot be decoded`,
+      fix: `set ${variable}=${key}=<encoded>, where <encoded> is what bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints — or drop the stray % from the "${key}" value if it was meant literally`,
       meta: { header: key },
     });
   }
 }
 
-/** `key=value,key2=value2`, percent-decoded — the spec's format for collector auth headers. */
+/**
+ * `key=value,key2=value2`, percent-decoded — the spec's format for collector auth headers.
+ *
+ * With a `signal`, `OTEL_EXPORTER_OTLP_<SIGNAL>_HEADERS` REPLACES the generic variable for that
+ * signal, which is the spec's rule and the one `ENDPOINT` and `PROTOCOL` already followed here:
+ * only the generic one was read, so a collector that authenticates traces and metrics with
+ * different keys got the same key on both and rejected one of them.
+ */
 export function otlpHeaders(
   explicit?: Readonly<Record<string, string>> | undefined,
   env: OtlpEnv = process.env,
+  signal?: OtlpSignal | undefined,
 ): Record<string, string> {
   const headers: Record<string, string> = { 'content-type': 'application/json' };
-  const raw = env[OTLP_HEADERS_KEY];
+  const specific = signal === undefined ? undefined : signalKey(signal, 'HEADERS');
+  const variable =
+    specific !== undefined && (env[specific] ?? '').trim() !== '' ? specific : OTLP_HEADERS_KEY;
+  const raw = env[variable];
   if (raw !== undefined) {
     for (const pair of raw.split(',')) {
       const index = pair.indexOf('=');
       if (index <= 0) continue;
       const key = pair.slice(0, index).trim().toLowerCase();
       if (key === '') continue;
-      headers[key] = decodeHeaderValue(key, pair.slice(index + 1).trim());
+      headers[key] = decodeHeaderValue(variable, key, pair.slice(index + 1).trim());
     }
   }
   for (const [key, value] of Object.entries(explicit ?? {})) headers[key.toLowerCase()] = value;
@@ -202,22 +216,39 @@ export interface OtlpKeyValue {
   readonly value: OtlpAnyValue;
 }
 
-function anyValue(value: AttributeValue): OtlpAnyValue {
+/**
+ * `undefined` for a number the wire cannot spell. `NaN` and `±Infinity` serialise as
+ * `{"doubleValue":null}`, and a validating collector rejects the WHOLE batch for it — `postOtlp`
+ * only warns, so one bad gauge silently cost every span beside it. Dropped, as a missing
+ * attribute is the honest reading of "not a number".
+ */
+function anyValue(value: AttributeValue): OtlpAnyValue | undefined {
   if (typeof value === 'string') return { stringValue: value };
   if (typeof value === 'boolean') return { boolValue: value };
   if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return undefined;
     // `intValue` is a 64-bit field, so the JSON encoding spells it as a string. A float that
-    // happens to be integral is still a double to whoever queries it; `Number.isInteger` is the
-    // only signal available and matches what every other OTLP/JSON encoder does.
-    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    // happens to be integral is still a double to whoever queries it; SAFE-integer is the signal,
+    // because past 2^53 `String(value)` is `"1e+21"` — exponent notation is not an int64.
+    return Number.isSafeInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  const values: OtlpAnyValue[] = [];
+  for (const item of value) {
+    const encoded = anyValue(item);
+    if (encoded !== undefined) values.push(encoded);
   }
-  return { arrayValue: { values: value.map((item) => anyValue(item)) } };
+  return { arrayValue: { values } };
 }
 
 export function otlpAttributes(
   attributes: Readonly<Record<string, AttributeValue>>,
 ): readonly OtlpKeyValue[] {
-  return Object.entries(attributes).map(([key, value]) => ({ key, value: anyValue(value) }));
+  const out: OtlpKeyValue[] = [];
+  for (const [key, raw] of Object.entries(attributes)) {
+    const value = anyValue(raw);
+    if (value !== undefined) out.push({ key, value });
+  }
+  return out;
 }
 
 /** Epoch ms -> the string of nanoseconds OTLP/JSON wants, without losing precision to a float. */

package/src/page-meta.ts

@@ -27,6 +27,13 @@ export const CLIENT_BUILD_META = 'x-ultimate-build';
  */
 export const APP_UPDATE_MESSAGE = 'AppUpdateAvailable';
 
+/**
+ * How this server turns an action's name into its URL (`defineApi({ http: { pathStyle } })`), for
+ * the browser's `actionPath`. Written only for a style other than the default: absent IS
+ * `'resource'`, so an app that declares nothing renders the bytes it always did.
+ */
+export const CLIENT_PATH_STYLE_META = 'ultimate-path-style';
+
 /** Where the page's one socket dials: `/_x/sync`, or the deployment's absolute `SYNC_URL`. */
 export const CLIENT_SYNC_META = 'ultimate-sync';
 

package/src/page.ts

@@ -43,6 +43,7 @@ export {
   CLIENT_NAVIGATION_LOCATION_HEADER,
   CLIENT_NAVIGATION_SCOPE_HEADER,
   CLIENT_NAVIGATION_SURFACE_HEADER,
+  CLIENT_PATH_STYLE_META,
   CLIENT_PERSIST_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,

package/src/pg-executor.ts

@@ -0,0 +1,15 @@
+// The one structural Postgres seam: `query(text, values)` answering rows. Declared at tier 0 so
+// `@ultimat3/http`, `auth`, `action` and `jobs` share it while staying free of `@ultimat3/db` —
+// four packages each declared it, and a copy is a fifth place for the contract to drift.
+
+/**
+ * One method, positional parameters. **`Bun.sql` does not satisfy it** — `Bun.sql.query` is
+ * `undefined`; it is a tagged template whose positional form is `unsafe`, so `{ executor: Bun.sql }`
+ * would `TypeError` on the first statement. What satisfies it is a client that already speaks
+ * `(text, values)`, wrapped in one line — `@ultimat3/cli`'s `pgExecutorFor(client)` over
+ * `@ultimat3/db`'s `DbClient.query({ text, values })` is the framework's own — or a transaction
+ * handle, which is a client on its own connection. It answers rows, never a command tag.
+ */
+export interface PgExecutor {
+  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
+}