@ultimat3/core 1.1.0 → 2.0.0

package/src/error-render.ts

@@ -0,0 +1,249 @@
+// Single responsibility: turn a value the framework does not control into text for an error's
+// `cause` or `fix`, without ever throwing while doing it. An error factory that dies formatting
+// its own message replaces the refusal with a `TypeError`, and `error.code === 'X_…'` then
+// matches nothing — the last message that may be lost to its own rendering.
+
+/**
+ * The cap on a rendered cause, in characters. A cause is READ — one log line, one `--json` field,
+ * one terminal paragraph — and the value it describes is the app's, so it can be a megabyte of
+ * request body. `JSON.stringify` has neither an output limit nor a streaming mode, so without a
+ * bound the whole of that value became the error's `message`, its log line and its `--json` field,
+ * and stayed there for the life of the error. Past every real cause in this repo, short of
+ * anything that costs.
+ */
+export const MAX_RENDERED_LENGTH = 512;
+
+/** The last guard: whatever survived the bounded walk still ends at the cap, ellipsis included. */
+const truncate = (text: string): string =>
+  text.length <= MAX_RENDERED_LENGTH ? text : `${text.slice(0, MAX_RENDERED_LENGTH - 1)}…`;
+
+/**
+ * `JSON.stringify` with a budget. The replacer runs before each value is serialised, so a long
+ * string is cut and the entries past the budget are dropped BEFORE they are written — the point
+ * being that the bound is on what gets allocated, not on a full serialisation trimmed afterwards.
+ * Dropping degrades exactly as the language already does: an object key disappears, an array slot
+ * becomes `null`.
+ */
+const boundedJson = (value: unknown): string | undefined => {
+  let spent = 0;
+  return JSON.stringify(value, (_key, entry: unknown) => {
+    if (spent > MAX_RENDERED_LENGTH) return undefined;
+    if (typeof entry !== 'string') {
+      spent += 1;
+      return entry;
+    }
+    spent += entry.length;
+    return entry.length > MAX_RENDERED_LENGTH ? `${entry.slice(0, MAX_RENDERED_LENGTH)}…` : entry;
+  });
+};
+
+/**
+ * A value from an app, rendered for a `cause`. `JSON.stringify` raises a `TypeError` on a bigint
+ * and on a cyclic structure, RUNS any `toJSON` the value carries and reads every enumerable
+ * getter — so building the message can raise INSTEAD of the refusal. The caller then catches a
+ * `TypeError` where a validation denial belongs, catching by code finds nothing, and an HTTP
+ * surface answers 500 rather than the mapped status.
+ *
+ * A cause DESCRIBES, so degrading to a type name — or to a bounded prefix — costs a reader nothing
+ * they needed. Template interpolation is avoided for the same reason: `` `${symbol}` `` throws
+ * where `String(symbol)` does not. Lifted from `@ultimat3/entity`'s `renderValue` — the spelling
+ * two independent fixes converged on — including its `a ${typeof value}` fallback for the values
+ * `JSON.stringify` answers `undefined` for: a function's source is neither bounded nor a thing a
+ * reader wants.
+ *
+ * Text for a `fix:` goes through `renderFixLiteral` instead, because a fix has to parse.
+ */
+export function renderCauseValue(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'bigint') return `${value}n`;
+  if (typeof value === 'symbol') return String(value);
+  try {
+    return truncate(boundedJson(value) ?? `a ${typeof value}`);
+  } catch {
+    return `a ${typeof value} that cannot be rendered`;
+  }
+}
+
+/**
+ * `value instanceof Error`, made total. The test itself can throw: a `Proxy`'s `getPrototypeOf`
+ * trap runs during `instanceof`, and the one place this question is asked is a `catch` block that
+ * has nothing left to answer with if it does.
+ */
+export function isThrownError(value: unknown): value is Error {
+  try {
+    return value instanceof Error;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A caught value as text: an `Error`'s own words where it has them, `renderCauseValue` everywhere
+ * else. `.name` and `.message` are ordinary property reads, so a subclass with a getter — or a
+ * `Proxy` — makes the read throw exactly where the catch block cannot afford it.
+ *
+ * One helper because the framework spelled `error instanceof Error ? error.message : …` in seven
+ * places, each carrying the same hole: `toUltimateError`, `@ultimat3/http`'s `finalizeFailed`,
+ * `@ultimat3/auth`'s OAuth callback, three CLI reporters and `@ultimat3/realtime`'s wire error.
+ */
+export function renderThrowable(value: unknown): string {
+  try {
+    if (value instanceof Error) {
+      const name = typeof value.name === 'string' ? value.name : 'Error';
+      const message = value.message;
+      return truncate(
+        `${name}: ${typeof message === 'string' ? message : renderCauseValue(message)}`,
+      );
+    }
+  } catch {
+    // The value fought being read, which is the case this function exists for: render it whole.
+  }
+  return renderCauseValue(value);
+}
+
+/**
+ * One string field off a value that may fight being read. An `UltimateError` crossing a worker,
+ * a subprocess or a WebSocket arrives as a plain object, so every surface that re-renders one asks
+ * structurally — `typeof value.code === 'string'` — and that read is a getter call, or a `Proxy`'s
+ * `get` trap, on a value the framework did not build. It throws in the one place with nothing left
+ * to answer with: the catch block deciding what the caller sees. The renderers above are total and
+ * were still reached past three of these reads.
+ *
+ * `undefined` covers absent, wrong type and threw, because each one means the same thing to every
+ * caller: this value did not supply the field, so use the default.
+ */
+export function stringField(value: unknown, key: string): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held = (value as Record<string, unknown>)[key];
+    return typeof held === 'string' ? held : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The same value where the text has to PARSE — a `fix:` is pasted and run, so a degraded type
+ * name in it produces a command that does not work. A string becomes its quoted literal; anything
+ * else becomes the placeholder, which is a parameter because what is missing differs by call
+ * site: an org id in one fix line, a flag key in the next, and a fix that names the wrong thing
+ * is not a fix. `JSON.stringify` cannot throw on a string primitive.
+ *
+ * Lifted from `@ultimat3/entity`'s `asLiteral`.
+ */
+export function renderFixLiteral(value: unknown, placeholder: string): string {
+  return typeof value === 'string' ? JSON.stringify(value) : placeholder;
+}
+
+/** `JSON.stringify` with its throw removed: did the value survive being serialised at all? */
+const canRender = (value: unknown): boolean => {
+  try {
+    JSON.stringify(value);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** A record's own keys, or none — a `Proxy` may refuse to be enumerated, and `ownKeys` throws. */
+const metaKeys = (meta: Readonly<Record<string, unknown>>): readonly string[] => {
+  try {
+    return Object.keys(meta);
+  } catch {
+    return [];
+  }
+};
+
+/** One entry, kept as it is when it renders — reading it is its own throw, past a getter. */
+const metaEntry = (meta: Readonly<Record<string, unknown>>, key: string): unknown => {
+  try {
+    const value = meta[key];
+    // A function passes `canRender` — `JSON.stringify(fn)` answers `undefined` rather than
+    // throwing — but copying one into the record moves the throw one layer out instead of removing
+    // it: a `meta` carrying an enumerable `toJSON` is INVOKED when `--json` serialises the error
+    // around it, which is the render this whole file exists to keep alive. Rendered, never copied.
+    return canRender(value) && typeof value !== 'function' ? value : renderCauseValue(value);
+  } catch {
+    return 'a value that cannot be read';
+  }
+};
+
+/**
+ * The third surface, one layer past the two above: `UltimateError.toJSON()` hands `meta` straight
+ * to `JSON.stringify`, so a bigint, a cycle or a hostile `toJSON` in it throws at `--json` RENDER
+ * time — after a constructor the renderers already made safe. `parseId` puts the rejected value in
+ * `meta` itself, so core feeds it uncontrolled values on its own.
+ *
+ * `meta` is MACHINE-READ, which decides the shape: a record that serialises is returned unchanged,
+ * value identity included, because describing a value a caller parses today would be a worse bug
+ * than the throw. Only what cannot be rendered degrades, and it degrades one key at a time — a
+ * single broken value must not cost the reader the keys beside it. The cost of that pass-through
+ * is one extra `JSON.stringify` of a small record on an error path, and any `toJSON` in it running
+ * twice; a `toJSON` with side effects is already outside what an error's `meta` may carry.
+ */
+export function renderMetaRecord(
+  meta: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> | undefined {
+  if (meta === undefined || canRender(meta)) return meta;
+  const out: Record<string, unknown> = {};
+  for (const key of metaKeys(meta)) out[key] = metaEntry(meta, key);
+  return out;
+}
+
+/**
+ * The shape of a rejected value — **never its content**.
+ *
+ * WHY: `renderCauseValue` above is safe against THROWING, not against LEAKING. It is the right
+ * renderer for a value the framework itself built; it is the wrong one for a value a caller
+ * supplied, because a `cause` is not a private diagnostic — it is folded into an HTTP problem
+ * document AND written into the log line, and the logger redacts `fields` by key, so a value
+ * baked into a message string has no key left to redact. That is not hypothetical: it was
+ * reproduced this cycle that a validator echoing a rejected value wrote mistyped passwords to
+ * both the log index and the user's own network tab.
+ *
+ * So: type and length, which is what a format or type violation actually needs, and nothing else.
+ * There is no dev-only escape hatch on purpose — a flag is one misconfigured environment away
+ * from being the same breach.
+ *
+ * A deliberate, character-for-character 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 identical; 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(value.length, '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'}`;
+}

package/src/error-reporter-sentry.ts

@@ -0,0 +1,175 @@
+// Single responsibility: one `ErrorReporter` that speaks the Sentry ENVELOPE wire format. A
+// serialisation, not a vendor (axiom 7, exactly as `metrics-text.ts` is to Prometheus): the format
+// is documented and several self-hostable monitors ingest it. Nothing here names a host, a project
+// or an organisation — the DSN is the app's own typed env, passed in at wiring time.
+
+import { renderThrowable } from './error-render';
+import type { ErrorReport, ErrorReporter, ErrorSeverity } from './error-reporter';
+import { type CodedErrorInit, UltimateError } from './errors';
+import { traceId } from './ids';
+import { logger } from './logger';
+
+export class ErrorReporterDsnInvalidError extends UltimateError {
+  static readonly code = 'X_ERROR_REPORTER_DSN_INVALID';
+  override readonly name = 'ErrorReporterDsnInvalidError';
+  constructor(init: CodedErrorInit) {
+    super({ ...init, code: ErrorReporterDsnInvalidError.code });
+  }
+}
+
+export interface SentryDsn {
+  readonly publicKey: string;
+  readonly projectId: string;
+  /** Where an envelope is POSTed. Derived from the DSN, never configured separately. */
+  readonly envelopeUrl: string;
+}
+
+const DSN_FIX =
+  'set the monitor DSN in .env to https://<publicKey>@<host>/<projectId>, then run: x env check';
+
+/**
+ * `https://<publicKey>@<host>[:<port>][/<path>]/<projectId>`. Parsed at wiring time rather than at
+ * the first error: a typo discovered by the first outage is a monitor that was never connected.
+ */
+export function parseSentryDsn(dsn: string): SentryDsn {
+  let url: URL;
+  try {
+    url = new URL(dsn);
+  } catch {
+    throw new ErrorReporterDsnInvalidError({
+      cause: `"${dsn}" is not a URL`,
+      fix: DSN_FIX,
+      meta: { dsn },
+    });
+  }
+  const segments = url.pathname.split('/').filter((part) => part.length > 0);
+  const projectId = segments.pop();
+  if (
+    (url.protocol !== 'https:' && url.protocol !== 'http:') ||
+    url.username === '' ||
+    projectId === undefined
+  ) {
+    throw new ErrorReporterDsnInvalidError({
+      cause: `"${url.protocol}//${url.host}${url.pathname}" has no publicKey, no projectId or a non-HTTP scheme`,
+      fix: DSN_FIX,
+      meta: { dsn },
+    });
+  }
+  const prefix = segments.length === 0 ? '' : `/${segments.join('/')}`;
+  return {
+    publicKey: url.username,
+    projectId,
+    envelopeUrl: `${url.protocol}//${url.host}${prefix}/api/${projectId}/envelope/`,
+  };
+}
+
+/** The protocol's own level names. `warning`/`error`/`fatal` happen to be the same three words. */
+const LEVELS: Readonly<Record<ErrorSeverity, string>> = Object.freeze({
+  warning: 'warning',
+  error: 'error',
+  fatal: 'fatal',
+});
+
+export interface SentryEnvelopeOptions {
+  readonly dsn: string;
+  /** 32 lowercase hex, no dashes. `traceId()` already produces exactly that shape. */
+  readonly eventId: string;
+}
+
+function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown> {
+  return {
+    event_id: eventId,
+    // Seconds, as the protocol spells a timestamp. `new Date` here converts a number the caller
+    // supplied; it never reads a clock, which stays `clock.ts`'s job.
+    timestamp: report.at / 1000,
+    platform: 'javascript',
+    level: LEVELS[report.severity],
+    logger: report.source,
+    environment: report.environment,
+    server_name: report.resource.serviceName,
+    ...(report.release === null ? {} : { release: report.release }),
+    ...(report.scope.operation === undefined ? {} : { transaction: report.scope.operation }),
+    // Tags are the monitor's facets, so only bounded values go here — the same rule metric labels
+    // follow. `requestId` and `actorId` are unbounded and live in `extra`.
+    tags: {
+      code: report.code,
+      source: report.source,
+      service_version: report.resource.serviceVersion,
+      ...(report.scope.role === undefined ? {} : { role: report.scope.role }),
+    },
+    ...(report.scope.traceId === undefined
+      ? {}
+      : {
+          contexts: {
+            trace: {
+              trace_id: report.scope.traceId,
+              ...(report.scope.spanId === undefined ? {} : { span_id: report.scope.spanId }),
+            },
+          },
+        }),
+    extra: {
+      // The whole point of reporting the framework's contract instead of a message: whoever is
+      // paged reads the runnable fix next to the failure.
+      fix: report.fix,
+      docs: report.docs,
+      ...(report.scope.requestId === undefined ? {} : { requestId: report.scope.requestId }),
+      ...(report.scope.actorId === undefined ? {} : { actorId: report.scope.actorId }),
+      ...(report.stack === undefined ? {} : { stack: report.stack }),
+      ...(report.meta ?? {}),
+      ...(report.scope.extra ?? {}),
+    },
+    exception: { values: [{ type: report.code, value: `${report.title} — ${report.cause}` }] },
+  };
+}
+
+/** Pure, so the wire format is a unit test rather than a thing discovered in production. */
+export function sentryEnvelope(report: ErrorReport, options: SentryEnvelopeOptions): string {
+  const payload = JSON.stringify(payloadOf(report, options.eventId));
+  const header = JSON.stringify({
+    event_id: options.eventId,
+    sent_at: new Date(report.at).toISOString(),
+    dsn: options.dsn,
+  });
+  const item = JSON.stringify({
+    type: 'event',
+    content_type: 'application/json',
+    length: new TextEncoder().encode(payload).length,
+  });
+  return `${header}\n${item}\n${payload}\n`;
+}
+
+export interface SentryReporterOptions {
+  /** From the app's typed env. The framework declares no default and ships no constant. */
+  readonly dsn: string;
+  /** Injected by tests; the preload seals the real one. */
+  readonly fetch?: typeof globalThis.fetch | undefined;
+  readonly clientName?: string | undefined;
+}
+
+/**
+ * Fire-and-forget on purpose. A report is not the request, and awaiting the monitor would add its
+ * latency — and its outages — to every failure the app already knows how to answer.
+ */
+export function sentryErrorReporter(options: SentryReporterOptions): ErrorReporter {
+  const dsn = parseSentryDsn(options.dsn);
+  const send = options.fetch ?? globalThis.fetch;
+  const client = options.clientName ?? 'ultimate';
+  const auth = `Sentry sentry_version=7, sentry_client=${client}, sentry_key=${dsn.publicKey}`;
+  return {
+    report(report: ErrorReport): void {
+      const body = sentryEnvelope(report, { dsn: options.dsn, eventId: traceId() });
+      void send(dsn.envelopeUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-sentry-envelope', 'x-sentry-auth': auth },
+        body,
+      }).catch((failure: unknown) => {
+        logger.warn('error reporter delivery failed', {
+          url: dsn.envelopeUrl,
+          // `renderThrowable`: this is the `.catch` that keeps a monitor outage from becoming a
+          // second failure, so rendering the rejection may not raise one of its own.
+          error: renderThrowable(failure),
+        });
+      });
+    },
+  };
+}

package/src/error-reporter.ts

@@ -0,0 +1,212 @@
+// Single responsibility: the error-monitoring seam — every surface reports a caught error through
+// ONE `ErrorReporter`. Shaped exactly like `telemetry.ts` and `metrics.ts`: always on, a no-op
+// driver by default, and the wire format supplied by a transport, never here. The framework names
+// no vendor (axiom 7); a transport takes its endpoint from the app's typed env.
+
+import { type Clock, systemClock } from './clock';
+import { tryUseContext } from './context';
+import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from './environment';
+import { renderThrowable, stringField } from './error-render';
+import { toUltimateError } from './errors';
+import { logger } from './logger';
+import type { Role } from './roles';
+import { currentSpanContext, type SpanResource, serviceResource } from './telemetry';
+
+export type ErrorSeverity = 'warning' | 'error' | 'fatal';
+
+/**
+ * Which surface caught it. A closed list on purpose: this becomes a facet in the monitor, and a
+ * free-form string here is the same unbounded-cardinality mistake that a user id in a metric
+ * label is. A new surface adds a member; it never passes a string of its own.
+ */
+export const ERROR_SOURCES = ['http', 'job', 'realtime', 'cli', 'process'] as const;
+
+export type ErrorSource = (typeof ERROR_SOURCES)[number];
+
+export interface ErrorScope {
+  readonly requestId?: string | undefined;
+  readonly traceId?: string | undefined;
+  readonly spanId?: string | undefined;
+  readonly role?: Role | undefined;
+  /** The route PATTERN, the job name, the frame type — never a concrete path or a row id. */
+  readonly operation?: string | undefined;
+  readonly actorId?: string | undefined;
+  /** Anything else worth reading during triage. Not a facet: never indexed, never grouped on. */
+  readonly extra?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/**
+ * What a reporter receives. The framework's error contract verbatim — a monitor groups on `code`
+ * and shows `fix` to whoever is paged, which is the whole reason a report carries more than a
+ * message string.
+ */
+export interface ErrorReport {
+  /** Epoch milliseconds, from the configured clock. */
+  readonly at: number;
+  readonly severity: ErrorSeverity;
+  readonly source: ErrorSource;
+  readonly code: string;
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly meta: Readonly<Record<string, unknown>> | undefined;
+  readonly stack: string | undefined;
+  readonly resource: SpanResource;
+  readonly environment: Environment;
+  /** The deploy's own id — `BUILD_ID`, the same value `x-ultimate-build` carries. */
+  readonly release: string | null;
+  readonly scope: ErrorScope;
+  /** The value that was actually thrown. A transport may read it; nothing else should. */
+  readonly error: unknown;
+}
+
+/** The driver seam. A self-hosted monitor, an OTLP logs exporter or a file all arrive as one. */
+export interface ErrorReporter {
+  report(event: ErrorReport): void;
+}
+
+export const noopErrorReporter: ErrorReporter = Object.freeze({
+  report(): void {
+    // Intentionally empty: reporting is always on, and free until a transport is configured.
+  },
+});
+
+export interface MemoryErrorReporter extends ErrorReporter {
+  readonly events: readonly ErrorReport[];
+  reset(): void;
+}
+
+/** For tests, and for a `x dev` process that shows its own failures without leaving the box. */
+export function memoryErrorReporter(): MemoryErrorReporter {
+  const events: ErrorReport[] = [];
+  return {
+    events,
+    report(event: ErrorReport): void {
+      events.push(event);
+    },
+    reset(): void {
+      events.length = 0;
+    },
+  };
+}
+
+export interface ErrorReportingOptions {
+  readonly reporter?: ErrorReporter | undefined;
+  readonly clock?: Clock | undefined;
+  /** The deploy's build id. `serve.ts` passes the one it already computed; never a second one. */
+  readonly release?: string | null | undefined;
+  readonly environment?: Environment | undefined;
+  readonly enabled?: boolean | undefined;
+}
+
+let reporter: ErrorReporter = noopErrorReporter;
+let clock: Clock = systemClock;
+let release: string | null = null;
+let environment: Environment | undefined;
+let enabled = true;
+
+export function configureErrorReporting(options: ErrorReportingOptions): void {
+  if (options.reporter !== undefined) reporter = options.reporter;
+  if (options.clock !== undefined) clock = options.clock;
+  if (options.release !== undefined) release = options.release;
+  if (options.environment !== undefined) environment = options.environment;
+  if (options.enabled !== undefined) enabled = options.enabled;
+}
+
+export function resetErrorReporting(): void {
+  reporter = noopErrorReporter;
+  clock = systemClock;
+  release = null;
+  environment = undefined;
+  enabled = true;
+}
+
+function environmentNow(): Environment {
+  // A malformed `ULTIMATE_ENV` is its own error with its own code and its own fix. Failing to tag
+  // a report with an environment must never replace the error being reported — which is why the
+  // non-throwing resolver is core's, not a `try` around the throwing one here: two call sites
+  // catching the same throw is two places the policy can drift.
+  return environment ?? tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
+}
+
+export interface ReportErrorOptions {
+  readonly source: ErrorSource;
+  /** Default `error`. `warning` is for a failure the framework already recovered from. */
+  readonly severity?: ErrorSeverity | undefined;
+  readonly scope?: ErrorScope | undefined;
+}
+
+/**
+ * Normalise a throwable into an `ErrorReport`. Exported so a transport can be tested against a
+ * report built the same way the runtime builds one, and so a surface can enrich before sending.
+ * The ambient context and the active span fill in whatever the caller did not name.
+ */
+export function errorReport(error: unknown, options: ReportErrorOptions): ErrorReport {
+  const normalized = toUltimateError(error);
+  const ctx = tryUseContext();
+  const span = currentSpanContext();
+  /**
+   * Trace and span resolve as a PAIR, from one source, and never field by field. Falling back
+   * per-field let a caller-supplied `traceId` pick up the *ambient* `spanId`, so a report claimed
+   * a span that belongs to a different trace — whoever is paged then opens the wrong span inside
+   * the right trace, which is worse than no span at all because it looks authoritative. A caller
+   * naming a trace is making a statement; the ambient span only fills a silence.
+   */
+  const trace: { traceId: string | undefined; spanId: string | undefined } =
+    options.scope?.traceId === undefined
+      ? {
+          traceId: span?.traceId ?? ctx?.traceId,
+          spanId: span?.spanId === '' ? undefined : span?.spanId,
+        }
+      : { traceId: options.scope.traceId, spanId: options.scope.spanId };
+  const scope: ErrorScope = {
+    requestId: options.scope?.requestId ?? ctx?.requestId,
+    traceId: trace.traceId,
+    spanId: trace.spanId,
+    role: options.scope?.role ?? ctx?.role,
+    operation: options.scope?.operation,
+    actorId: options.scope?.actorId ?? ctx?.actor.id,
+    extra: options.scope?.extra,
+  };
+  return {
+    at: clock.now().getTime(),
+    severity: options.severity ?? 'error',
+    source: options.source,
+    code: normalized.code,
+    title: normalized.title,
+    cause: normalized.cause,
+    fix: normalized.fix,
+    docs: normalized.docs,
+    meta: normalized.meta,
+    // The thrown value's own stack, not the wrapper's: `toUltimateError` builds its `InternalError`
+    // at this line, so the wrapper's stack points here rather than at the throw. Read through
+    // `stringField`, because `error instanceof Error` and `.stack` are both property operations
+    // on a caught value — and this function's own contract is that reporting never throws.
+    stack: stringField(error, 'stack') ?? normalized.stack,
+    resource: serviceResource(),
+    environment: environmentNow(),
+    release: release ?? ctx?.buildId ?? null,
+    scope,
+    error,
+  };
+}
+
+/**
+ * The one call every surface makes. It never throws and never rejects: a monitor that is down
+ * must not turn one failure into two, and the surface that caught this has already logged it.
+ */
+export function reportError(error: unknown, options: ReportErrorOptions): void {
+  if (!enabled) return;
+  try {
+    reporter.report(errorReport(error, options));
+  } catch (failure) {
+    logger.warn('error reporter failed', {
+      source: options.source,
+      // `renderThrowable`: `failure instanceof Error ? failure.message : String(failure)` is
+      // itself a throw on a hostile value, and it sat inside the catch that makes this function's
+      // documented "never throws" true.
+      error: renderThrowable(failure),
+    });
+  }
+}