@ultimat3/core 1.2.0 → 2.0.0

package/src/otlp-span-exporter.ts

@@ -0,0 +1,170 @@
+// Single responsibility: a `SpanExporter` that POSTs OTLP/HTTP JSON to a collector. Batched,
+// because `SpanExporter.export` is one span and a request per span is a second load generator.
+
+import {
+  OTLP_SCOPE,
+  type OtlpKeyValue,
+  otlpAttributes,
+  otlpEndpoint,
+  otlpHeaders,
+  otlpResource,
+  postOtlp,
+  unixNano,
+} from './otlp';
+import type {
+  ReadableSpan,
+  SpanContext,
+  SpanExporter,
+  SpanKind,
+  SpanResource,
+  SpanStatusCode,
+} from './telemetry';
+
+/** OTLP's `SpanKind` enum; `UNSPECIFIED` is 0 and Ultimate never emits it. */
+const SPAN_KIND: Readonly<Record<SpanKind, number>> = Object.freeze({
+  internal: 1,
+  server: 2,
+  client: 3,
+  producer: 4,
+  consumer: 5,
+});
+
+const STATUS_CODE: Readonly<Record<SpanStatusCode, number>> = Object.freeze({
+  unset: 0,
+  ok: 1,
+  error: 2,
+});
+
+interface OtlpSpanJson {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId?: string;
+  readonly name: string;
+  readonly kind: number;
+  readonly startTimeUnixNano: string;
+  readonly endTimeUnixNano: string;
+  readonly attributes: readonly OtlpKeyValue[];
+  readonly events: readonly unknown[];
+  readonly links: readonly unknown[];
+  readonly status: { readonly code: number; readonly message?: string };
+}
+
+function link(context: SpanContext): unknown {
+  return { traceId: context.traceId, spanId: context.spanId };
+}
+
+function spanJson(span: ReadableSpan): OtlpSpanJson {
+  return {
+    traceId: span.context.traceId,
+    spanId: span.context.spanId,
+    ...(span.parentSpanId === undefined ? {} : { parentSpanId: span.parentSpanId }),
+    name: span.name,
+    kind: SPAN_KIND[span.kind],
+    startTimeUnixNano: unixNano(span.startedAt),
+    endTimeUnixNano: unixNano(span.endedAt),
+    attributes: otlpAttributes(span.attributes),
+    events: span.events.map((event) => ({
+      timeUnixNano: unixNano(event.at),
+      name: event.name,
+      attributes: otlpAttributes(event.attributes),
+    })),
+    links: span.links.map(link),
+    status: {
+      code: STATUS_CODE[span.status.code],
+      ...(span.status.message === undefined ? {} : { message: span.status.message }),
+    },
+  };
+}
+
+/**
+ * Pure, so the wire format is a unit test rather than something discovered against a collector.
+ * Spans are grouped by resource identity — in one process there is exactly one, but grouping here
+ * keeps the shape correct if a future caller replays spans from elsewhere.
+ */
+export function otlpTraceRequest(spans: readonly ReadableSpan[], resource: SpanResource): unknown {
+  return {
+    resourceSpans: [
+      {
+        resource: otlpResource(resource),
+        scopeSpans: [{ scope: OTLP_SCOPE, spans: spans.map(spanJson) }],
+      },
+    ],
+  };
+}
+
+export interface OtlpSpanExporterOptions {
+  /** Overrides `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_ENDPOINT`. */
+  readonly endpoint?: string | undefined;
+  /** Merged over `OTEL_EXPORTER_OTLP_HEADERS`. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  /** Spans per POST. Default 512, the OTel batch processor's own default. */
+  readonly maxBatchSize?: number | undefined;
+  /** Default 5000ms. */
+  readonly flushIntervalMs?: number | undefined;
+  /** Spans held before the oldest are dropped. Default 2048 — a bound, not a promise. */
+  readonly maxQueueSize?: number | undefined;
+  /** Default 10000ms. */
+  readonly timeoutMs?: number | undefined;
+  /** Injected by tests; the preload seals the real one. */
+  readonly fetch?: typeof globalThis.fetch | undefined;
+}
+
+export interface OtlpSpanExporter extends SpanExporter {
+  /** Send whatever is queued now. Resolves once the POST settles. */
+  flush(): Promise<void>;
+  /** Stop the timer and flush. Wire this into `onShutdown('otlp', …, { phase: 'close' })`. */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Throws `X_OTLP_ENDPOINT_INVALID` at construction when nothing configured an endpoint — a
+ * telemetry exporter that silently sends nowhere is the failure this whole seam exists to end.
+ * Ask `tryOtlpEndpoint('traces')` first when the exporter is optional.
+ */
+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 send = options.fetch ?? globalThis.fetch;
+  const queue: ReadableSpan[] = [];
+  let inflight: Promise<void> = Promise.resolve();
+
+  const post = (batch: readonly ReadableSpan[]): Promise<void> => {
+    const first = batch[0];
+    if (first === undefined) return Promise.resolve();
+    const body = JSON.stringify(otlpTraceRequest(batch, first.resource));
+    return postOtlp({ url, headers, body, timeoutMs, fetch: send });
+  };
+
+  const drainQueue = (): Promise<void> => {
+    const batch = queue.splice(0, queue.length);
+    // Chained, not concurrent: a collector reordering batches from one process turns a parent's
+    // span arriving after its child into a broken trace on the read side.
+    inflight = inflight.then(() => post(batch));
+    return inflight;
+  };
+
+  // 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);
+  timer.unref();
+
+  return {
+    export(span: ReadableSpan): void {
+      // Drop the OLDEST: a bounded queue that drops the newest keeps a stale window forever, and
+      // the spans an operator wants during an incident are the ones happening now.
+      if (queue.length >= maxQueueSize) queue.shift();
+      queue.push(span);
+      if (queue.length >= maxBatchSize) void drainQueue();
+    },
+    flush(): Promise<void> {
+      return drainQueue();
+    },
+    async shutdown(): Promise<void> {
+      clearInterval(timer);
+      await drainQueue();
+    },
+  };
+}

package/src/otlp.ts

@@ -0,0 +1,217 @@
+// Single responsibility: the pieces both OTLP exporters share — endpoint resolution from the env
+// 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 { renderThrowable } from './error-render';
+import { type CodedErrorInit, UltimateError } from './errors';
+import { logger } from './logger';
+import type { AttributeValue, SpanResource } from './telemetry';
+
+export class OtlpEndpointInvalidError extends UltimateError {
+  static readonly code = 'X_OTLP_ENDPOINT_INVALID';
+  override readonly name = 'OtlpEndpointInvalidError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: OtlpEndpointInvalidError.code });
+  }
+}
+
+export class OtlpProtocolUnsupportedError extends UltimateError {
+  static readonly code = 'X_OTLP_PROTOCOL_UNSUPPORTED';
+  override readonly name = 'OtlpProtocolUnsupportedError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: OtlpProtocolUnsupportedError.code });
+  }
+}
+
+export type OtlpSignal = 'traces' | 'metrics';
+
+export const OTLP_ENDPOINT_KEY = 'OTEL_EXPORTER_OTLP_ENDPOINT';
+export const OTLP_HEADERS_KEY = 'OTEL_EXPORTER_OTLP_HEADERS';
+export const OTLP_PROTOCOL_KEY = 'OTEL_EXPORTER_OTLP_PROTOCOL';
+
+/** The gRPC receiver port. Named so the error can say which one the operator reached for. */
+const GRPC_PORT = '4317';
+
+export type OtlpEnv = Readonly<Record<string, string | undefined>>;
+
+const signalKey = (signal: OtlpSignal, suffix: string): string =>
+  `OTEL_EXPORTER_OTLP_${signal.toUpperCase()}_${suffix}`;
+
+/**
+ * OTLP/HTTP JSON only. gRPC needs HTTP/2 plus protobuf, which is a dependency and a second wire
+ * format for one signal — `docs/ops/03-observability.md` already points operators at `:4318`.
+ */
+function assertHttpJson(signal: OtlpSignal, url: URL, env: OtlpEnv): void {
+  const protocol = (env[signalKey(signal, 'PROTOCOL')] ?? env[OTLP_PROTOCOL_KEY] ?? '').trim();
+  if (protocol !== '' && protocol !== 'http/json') {
+    throw new OtlpProtocolUnsupportedError({
+      cause: `${OTLP_PROTOCOL_KEY}="${protocol}" — this exporter speaks OTLP/HTTP JSON and nothing else`,
+      fix: `unset ${OTLP_PROTOCOL_KEY} (or set it to http/json) and point ${OTLP_ENDPOINT_KEY} at the collector's HTTP receiver, e.g. http://otel-collector:4318`,
+      meta: { protocol, signal },
+    });
+  }
+  if (url.port === GRPC_PORT) {
+    throw new OtlpProtocolUnsupportedError({
+      cause: `${url.origin} is the collector's gRPC receiver (:${GRPC_PORT}); OTLP/HTTP JSON is served on :4318`,
+      fix: `set ${OTLP_ENDPOINT_KEY}=${url.protocol}//${url.hostname}:4318`,
+      meta: { endpoint: url.origin, signal },
+    });
+  }
+}
+
+function parseEndpoint(signal: OtlpSignal, raw: string, perSignal: boolean, env: OtlpEnv): string {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new OtlpEndpointInvalidError({
+      cause: `"${raw}" is not a URL`,
+      fix: `set ${OTLP_ENDPOINT_KEY}=http://otel-collector:4318`,
+      meta: { endpoint: raw, signal },
+    });
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new OtlpEndpointInvalidError({
+      cause: `"${raw}" is ${url.protocol}, and OTLP/HTTP needs http or https`,
+      fix: `set ${OTLP_ENDPOINT_KEY}=http://otel-collector:4318`,
+      meta: { endpoint: raw, signal },
+    });
+  }
+  assertHttpJson(signal, url, 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}`;
+}
+
+/** The endpoint an operator configured, or `undefined` when they configured none. */
+export function tryOtlpEndpoint(
+  signal: OtlpSignal,
+  env: OtlpEnv = process.env,
+): string | undefined {
+  const specific = env[signalKey(signal, 'ENDPOINT')]?.trim();
+  if (specific !== undefined && specific !== '') return parseEndpoint(signal, specific, true, env);
+  const generic = env[OTLP_ENDPOINT_KEY]?.trim();
+  if (generic === undefined || generic === '') return undefined;
+  return parseEndpoint(signal, generic, false, env);
+}
+
+/** The endpoint, or a coded error naming the variable to set. */
+export function otlpEndpoint(
+  signal: OtlpSignal,
+  explicit?: string | undefined,
+  env: OtlpEnv = process.env,
+): string {
+  if (explicit !== undefined && explicit !== '') return parseEndpoint(signal, explicit, true, env);
+  const resolved = tryOtlpEndpoint(signal, env);
+  if (resolved !== undefined) return resolved;
+  throw new OtlpEndpointInvalidError({
+    cause: `no OTLP endpoint: neither ${signalKey(signal, 'ENDPOINT')} nor ${OTLP_ENDPOINT_KEY} is set, and none was passed`,
+    fix: `set ${OTLP_ENDPOINT_KEY}=http://otel-collector:4318, or skip the exporter when tryOtlpEndpoint('${signal}') is undefined`,
+    meta: { signal },
+  });
+}
+
+/** `key=value,key2=value2`, percent-decoded — the spec's format for collector auth headers. */
+export function otlpHeaders(
+  explicit?: Readonly<Record<string, string>> | undefined,
+  env: OtlpEnv = process.env,
+): Record<string, string> {
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  const raw = env[OTLP_HEADERS_KEY];
+  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] = decodeURIComponent(pair.slice(index + 1).trim());
+    }
+  }
+  for (const [key, value] of Object.entries(explicit ?? {})) headers[key.toLowerCase()] = value;
+  return headers;
+}
+
+export interface OtlpAnyValue {
+  readonly stringValue?: string;
+  readonly boolValue?: boolean;
+  readonly intValue?: string;
+  readonly doubleValue?: number;
+  readonly arrayValue?: { readonly values: readonly OtlpAnyValue[] };
+}
+
+export interface OtlpKeyValue {
+  readonly key: string;
+  readonly value: OtlpAnyValue;
+}
+
+function anyValue(value: AttributeValue): OtlpAnyValue {
+  if (typeof value === 'string') return { stringValue: value };
+  if (typeof value === 'boolean') return { boolValue: value };
+  if (typeof value === 'number') {
+    // `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 };
+  }
+  return { arrayValue: { values: value.map((item) => anyValue(item)) } };
+}
+
+export function otlpAttributes(
+  attributes: Readonly<Record<string, AttributeValue>>,
+): readonly OtlpKeyValue[] {
+  return Object.entries(attributes).map(([key, value]) => ({ key, value: anyValue(value) }));
+}
+
+/** Epoch ms -> the string of nanoseconds OTLP/JSON wants, without losing precision to a float. */
+export function unixNano(epochMs: number): string {
+  return `${Math.round(epochMs)}000000`;
+}
+
+export function otlpResource(resource: SpanResource): {
+  readonly attributes: readonly OtlpKeyValue[];
+} {
+  return {
+    attributes: otlpAttributes({
+      'service.name': resource.serviceName,
+      'service.version': resource.serviceVersion,
+    }),
+  };
+}
+
+/** The instrumentation scope every signal this package emits belongs to. */
+export const OTLP_SCOPE = Object.freeze({ name: '@ultimat3/core' });
+
+export interface OtlpPostOptions {
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly timeoutMs: number;
+  readonly fetch: typeof globalThis.fetch;
+}
+
+/**
+ * Never throws and never rejects. Telemetry delivery is not the request: a collector that is down
+ * must not become the app's outage, and the alternative — an unhandled rejection from a `void`ed
+ * promise — takes the process with it on Bun.
+ */
+export async function postOtlp(options: OtlpPostOptions): Promise<void> {
+  try {
+    const response = await options.fetch(options.url, {
+      method: 'POST',
+      headers: { ...options.headers },
+      body: options.body,
+      signal: AbortSignal.timeout(options.timeoutMs),
+    });
+    if (!response.ok) {
+      logger.warn('otlp export rejected', { url: options.url, status: response.status });
+    }
+  } catch (failure) {
+    logger.warn('otlp export failed', {
+      url: options.url,
+      // `renderThrowable`: the read that renders a caught value must not itself throw, or the
+      // export failure this catch exists to swallow escapes as an unhandled rejection.
+      error: renderThrowable(failure),
+    });
+  }
+}

package/src/read-capped.ts

@@ -0,0 +1,47 @@
+// Single responsibility: reading a request body through a COUNTING reader, so a payload past the
+// cap is never held in full. It lives in core because two transports need the identical guarantee
+// and cannot share it any other way: `@ultimat3/http` (tier 2) owns `bodyLimitBytes`, and
+// `@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.
+
+/** 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 };
+
+/**
+ * The body, read through the stream and abandoned the instant the running total passes `limit`.
+ * `arrayBuffer()`/`json()` materialise first and check after, so a `transfer-encoding: chunked`
+ * request — one with no `content-length` for a pre-check to read — allocated its whole payload
+ * before the 413 it was going to get anyway. A declared length is a courtesy, not a guard.
+ */
+export const readWithinLimit = async (
+  body: ReadableStream<Uint8Array> | null,
+  limit: number,
+): Promise<CappedBody> => {
+  if (body === null) return { bytes: new Uint8Array(0) };
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      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 };
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { bytes };
+};

package/src/runtime-metrics.ts

@@ -48,6 +48,11 @@ export const jobs: Counter = counter('jobs_total', {
   description: 'Background jobs finished, by queue and outcome',
 });
 
+export const leasesLost: Counter = counter('job_leases_lost_total', {
+  unit: '{job}',
+  description: 'Job leases that lapsed while the job was still running, by queue',
+});
+
 export interface RequestSample {
   readonly method: string;
   /** The route PATTERN (`/posts/:id`), never the concrete path — one series per pattern. */
@@ -84,3 +89,13 @@ export function recordQueueDepth(queue: string, depth: number): void {
 export function recordJob(queue: string, outcome: 'ok' | 'failed' | 'dead'): void {
   jobs.add(1, { queue, outcome });
 }
+
+/**
+ * One per job whose lease the holding process could not renew inside the visibility timeout.
+ * Deliberately not an outcome on `jobs_total`: nothing failed and nothing finished — the queue
+ * simply handed the job to somebody else while this process was still running it. Every point on
+ * this series is one job that ran twice, which is the only reason it is worth a series at all.
+ */
+export function recordLeaseLost(queue: string): void {
+  leasesLost.add(1, { queue });
+}

package/src/safe-url.ts

@@ -0,0 +1,50 @@
+// Single responsibility: deciding whether a URL is safe to put in a URL-bearing HTML attribute.
+// It lives in core because the packages that need it — `@ultimat3/render` (the SSR attribute
+// writer) and `@ultimat3/ui` (an anchor whose href comes off a row) — are tiers 4 and 5 and one
+// cannot import the other; core is the lowest tier both reach. Same reason as `timing-safe-equal`.
+
+/** The attributes a browser will FOLLOW. A scheme in any of them is executable. */
+export const URL_ATTRIBUTES: readonly string[] = ['href', 'src', 'action', 'formaction'];
+
+/**
+ * `javascript:` and `vbscript:` are the two that execute; everything not on this list is refused
+ * rather than judged, because "which exotic scheme is harmless" is a question that gets a wrong
+ * answer once and then ships. The five here are the ones an anchor in an app actually carries —
+ * a refusal is SILENT (no attribute at all), so a scheme missing from this list is a dead link,
+ * which is why the list is the realistic set rather than the minimal one.
+ */
+const SAFE_SCHEMES: readonly string[] = ['http:', 'https:', 'mailto:', 'tel:', 'sms:'];
+
+const SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+
+/**
+ * The value to emit, or `null` when the attribute must not be emitted at all. An anchor with no
+ * `href` is inert and still renders its text, which is strictly better than a live one nobody
+ * checked.
+ *
+ * `attribute` is compared lowercased by the caller's own table, so pass the HTML spelling.
+ */
+export function safeUrl(value: string, attribute: string): string | null {
+  // A browser deletes TAB, CR and LF anywhere in a URL and trims leading C0 controls and spaces
+  // before parsing it, so `java\tscript:alert(1)` is `javascript:` by the time it is followed —
+  // the scheme has to be read off the stripped form, never off the raw one.
+  // Built by code point rather than a regex character class because Biome refuses a control
+  // character in a pattern - and it is right to: this is the one place that wants them named.
+  const stripped = [...value]
+    .filter((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      return code > 0x20 && code !== 0x7f;
+    })
+    .join('');
+  const matched = SCHEME.exec(stripped);
+  // No scheme at all: relative, absolute-path, protocol-relative, query or fragment. Nothing here
+  // can execute, and refusing them would refuse most of the links an app writes.
+  if (matched === null) return value;
+  const scheme = matched[0].toLowerCase();
+  if (SAFE_SCHEMES.includes(scheme)) return value;
+  // The one data URL kept, and only where the bytes are RENDERED rather than navigated to: the
+  // framework's own blur placeholder is a `data:image/webp`. In an `href` a data URL is a document
+  // that runs on nothing but is still a phishing surface, so it is refused there.
+  if (attribute === 'src' && stripped.slice(0, 11).toLowerCase() === 'data:image/') return value;
+  return null;
+}

package/src/sampler.ts

@@ -0,0 +1,126 @@
+// Single responsibility: the sampling decision — the one lever between "tracing is on" and "the
+// collector melts". Separate from `telemetry.ts` because the decision is a policy an app replaces,
+// while span construction is not.
+
+import { logger } from './logger';
+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.
+ */
+export interface Sampler {
+  shouldSample(name: string, parent: SpanContext | undefined, attributes: SpanAttributes): boolean;
+}
+
+export const OTEL_SAMPLER_KEY = 'OTEL_TRACES_SAMPLER';
+export const OTEL_SAMPLER_ARG_KEY = 'OTEL_TRACES_SAMPLER_ARG';
+
+/** Unset means on, exactly as OTel's own `parentbased_always_on` default does. */
+export const DEFAULT_SAMPLE_RATIO = 1;
+
+export const alwaysOnSampler: Sampler = Object.freeze({
+  shouldSample: (): boolean => true,
+});
+
+export const alwaysOffSampler: Sampler = Object.freeze({
+  shouldSample: (): boolean => false,
+});
+
+function parentSampled(parent: SpanContext | undefined): boolean | undefined {
+  return parent === undefined ? undefined : (parent.traceFlags & 1) === 1;
+}
+
+/**
+ * Honour the parent, else sample a `ratio` fraction of new traces.
+ *
+ * `random()` rather than a hash of the trace id: this sampler only ever decides for a ROOT span —
+ * a span with a parent takes the parent's bit verbatim — so there is no second service whose
+ * independent decision has to agree with ours, which is the only thing trace-id hashing buys.
+ * `random` is injectable so the ratio is a test and not a coin flip.
+ */
+export function parentBasedRatioSampler(
+  ratio: number,
+  random: () => number = Math.random,
+): Sampler {
+  return {
+    shouldSample(_name, parent): boolean {
+      const inherited = parentSampled(parent);
+      if (inherited !== undefined) return inherited;
+      if (ratio >= 1) return true;
+      if (ratio <= 0) return false;
+      return random() < ratio;
+    },
+  };
+}
+
+/** `always_off` / `always_on` without the parent-based prefix ignore the inbound decision. */
+export function ratioSampler(ratio: number, random: () => number = Math.random): Sampler {
+  return {
+    shouldSample(): boolean {
+      if (ratio >= 1) return true;
+      if (ratio <= 0) return false;
+      return random() < ratio;
+    },
+  };
+}
+
+function readRatio(raw: string | undefined, spelling: string): number {
+  if (raw === undefined || raw.trim() === '') return DEFAULT_SAMPLE_RATIO;
+  const parsed = Number.parseFloat(raw);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    // Warn rather than throw: this is read at the first span, not at boot, and a process that
+    // dies mid-request over a sampling typo has turned an observability misconfiguration into an
+    // outage. Falling back to 1 keeps the traces — losing them silently is the worse failure.
+    logger.warn('X_TELEMETRY_SAMPLER_ARG_INVALID', {
+      cause: `${spelling}="${raw}" is not a ratio between 0 and 1; sampling every trace instead`,
+      fix: `set ${spelling} to a value between 0 and 1, e.g. ${spelling}=0.05`,
+    });
+    return DEFAULT_SAMPLE_RATIO;
+  }
+  return parsed;
+}
+
+/**
+ * The sampler the env asks for. Recognises the OTel spellings an operator already knows; anything
+ * else falls through to parent-based ratio, which is the default behaviour either way.
+ */
+export function samplerFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Sampler {
+  const name = (env[OTEL_SAMPLER_KEY] ?? '').trim().toLowerCase();
+  const ratio = readRatio(env[OTEL_SAMPLER_ARG_KEY], OTEL_SAMPLER_ARG_KEY);
+  switch (name) {
+    case 'always_off':
+      return alwaysOffSampler;
+    case 'always_on':
+      return alwaysOnSampler;
+    case 'traceidratio':
+      return ratioSampler(ratio);
+    case 'parentbased_always_off':
+      return parentBasedRatioSampler(0);
+    default:
+      // `parentbased_always_on`, `parentbased_traceidratio` and the unset case are one sampler:
+      // honour the parent, else the ratio — which is 1 when nothing set an arg.
+      return parentBasedRatioSampler(ratio);
+  }
+}
+
+let cached: Sampler | undefined;
+
+/**
+ * Read at the first span, never at module scope: `installSecrets()` and `defineEnv()` both land
+ * values in `process.env` during boot, and a module-scope read would pin whatever was set before
+ * the app configured itself — the same defect `cursor.ts` fixed by moving its secret read into
+ * `sign()`.
+ */
+export function defaultSampler(): Sampler {
+  if (cached === undefined) cached = samplerFromEnv();
+  return cached;
+}
+
+/** Test-only: forget the env-derived sampler so the next read sees the current environment. */
+export function resetDefaultSampler(): void {
+  cached = undefined;
+}

package/src/schema-error-codes.ts

@@ -0,0 +1,28 @@
+// Single responsibility: register `@ultimat3/schema`'s error codes so their titles render for any
+// process that imports `@ultimat3/core` — not just the CLI. `@ultimat3/schema` is tier 0 alongside
+// this package, so it cannot call `registerErrorCodes()` itself (that would mean importing core,
+// a same-tier import) and this package cannot import schema to read its declarations back (same
+// reason, the other direction). The codes below are a deliberate, tested duplicate of
+// `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts` — `schema-error-codes-pin.test.ts`, in a
+// package that may legally import both (`@ultimat3/cli`), asserts them equal so a title edited in
+// one place and not the other fails the build instead of quietly disagreeing at runtime.
+
+import { registerErrorCodes } from './error-codes';
+
+/** Mirrors `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`. Keep the titles identical. */
+export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze({
+  X_VALIDATION_FAILED: 'value did not match its schema',
+  X_SCHEMA_UNSUPPORTED: 'the active schema provider cannot do this',
+  X_SCHEMA_DISCRIMINANT_INVALID: 'a discriminated union member can never be dispatched to',
+  X_SCHEMA_DEFAULT_UNSHAREABLE: 'a schema default cannot be copied per parse',
+});
+
+// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
+// these codes — `@ultimat3/schema` does — and `registerErrorCodes` is the one mechanism that
+// raises `X_ERROR_CODE_DUPLICATE` if a package that DOES own one of them ever tries to register it
+// too, which pins ownership even though the titles live in two files.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(SCHEMA_ERROR_CODE_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);