@ultimat3/core 29.3.2 → 30.0.0

package/src/declared-errors.ts

@@ -0,0 +1,185 @@
+// Single responsibility: an action's or a query's `errors:` list — what may be listed, which throw
+// out of a handler the list judges, and what a test run and a production run do with a miss. Here
+// and not in `@ultimat3/action` because `@ultimat3/query` needs the same rule and tiers never go
+// sideways; the HTTP status is passed in because `@ultimat3/http` sits above this package.
+
+import { FRAMEWORK_CODE } from './client-wire';
+import { tryResolveEnvironment } from './environment';
+import { renderCauseValue } from './error-render';
+import { isUltimateError, UltimateError } from './errors';
+import { logger } from './logger';
+import { counter } from './metrics';
+
+/** The status a code answers, `undefined` when nothing declared one: `@ultimat3/http`'s reader. */
+export type ErrorStatusOf = (code: string) => number | undefined;
+
+/** Which declaration a verdict is about — the two primitives that carry `errors:`. */
+export interface DeclaredErrorsOwner {
+  readonly primitive: 'action' | 'query';
+  readonly name: string;
+}
+
+/**
+ * The process's lifetime, never a refusal a handler chose: a drain or an abort reaches every
+ * handler alike, so listing them on each would be a list nobody could keep true.
+ */
+export const LIFETIME_ERROR_CODES: readonly string[] = ['X_ABORTED', 'X_DRAINING'];
+
+/** `open` — no list declared; `exempt` — not a contract member; else the list's answer. */
+export type DeclaredErrorVerdict = 'open' | 'exempt' | 'declared' | 'undeclared';
+
+/** Is `status` a refusal the caller can branch on? A 5xx or no status is an outage. */
+const isRefusal = (status: number | undefined): boolean =>
+  status !== undefined && status >= 400 && status <= 499;
+
+/** The one judgement both halves make: the dynamic wrap and the contract's source scan. */
+export function judgeThrown(
+  declared: readonly string[] | undefined,
+  code: string,
+  status: number | undefined,
+): DeclaredErrorVerdict {
+  if (declared === undefined) return 'open';
+  if (LIFETIME_ERROR_CODES.includes(code) || !isRefusal(status)) return 'exempt';
+  return declared.includes(code) ? 'declared' : 'undeclared';
+}
+
+export class ErrorUndeclaredError extends UltimateError {
+  static readonly code = 'X_ERROR_UNDECLARED';
+  override readonly name = 'ErrorUndeclaredError';
+  constructor(owner: DeclaredErrorsOwner, code: string, sourceError?: unknown) {
+    super({
+      code: ErrorUndeclaredError.code,
+      cause: `${owner.primitive} ${owner.name} threw ${code}, which its errors: list does not declare`,
+      fix: `errors: [ …, '${code}' ]   # add it in the ${owner.name} definition, or stop throwing it there; then: x verify --only contract`,
+      meta: { primitive: owner.primitive, name: owner.name, undeclared: code },
+      sourceError,
+    });
+  }
+}
+
+export class ActionErrorsInvalidError extends UltimateError {
+  static readonly code = 'X_ACTION_ERRORS_INVALID';
+  override readonly name = 'ActionErrorsInvalidError';
+  constructor(owner: string, listed: unknown, why: string) {
+    const shown = renderCauseValue(listed);
+    const code = typeof listed === 'string' && FRAMEWORK_CODE.test(listed) ? listed : '<CODE>';
+    super({
+      code: ActionErrorsInvalidError.code,
+      cause: `errors: in ${owner} lists ${shown}, which ${why}`,
+      fix: `defineError({ code: '${code}', title, status: 4xx, cause, fix })   # import it where ${owner} is declared, list its .code once; x errors explain ${code} --json`,
+      meta: { owner, listed: shown },
+    });
+  }
+}
+
+/**
+ * The list as written, refused where it is written: malformed, unregistered, not a 4xx, or
+ * repeated. Answers a frozen, sorted copy — what the descriptor, the manifest and the OpenAPI
+ * document publish — so a caller mutating the literal it passed changes nothing that was checked.
+ */
+export function checkDeclaredErrors(
+  errors: readonly string[],
+  statusOf: ErrorStatusOf,
+  owner: string,
+): readonly string[];
+export function checkDeclaredErrors(
+  errors: readonly string[] | undefined,
+  statusOf: ErrorStatusOf,
+  owner: string,
+): readonly string[] | undefined;
+export function checkDeclaredErrors(
+  errors: readonly string[] | undefined,
+  statusOf: ErrorStatusOf,
+  owner: string,
+): readonly string[] | undefined {
+  if (errors === undefined) return undefined;
+  if (!Array.isArray(errors)) throw new ActionErrorsInvalidError(owner, errors, 'is not an array');
+  const seen = new Set<string>();
+  for (const code of errors as readonly unknown[]) {
+    if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
+      throw new ActionErrorsInvalidError(owner, code, 'is not an X_SCREAMING_SNAKE code');
+    }
+    if (seen.has(code)) throw new ActionErrorsInvalidError(owner, code, 'is listed twice');
+    const status = statusOf(code);
+    if (!isRefusal(status)) {
+      throw new ActionErrorsInvalidError(
+        owner,
+        code,
+        status === undefined ? 'has no registered HTTP status' : `answers ${status}, not a 4xx`,
+      );
+    }
+    seen.add(code);
+  }
+  return Object.freeze([...seen].sort());
+}
+
+const undeclaredErrors = counter('undeclared_errors_total', {
+  unit: '{error}',
+  description: 'Refusals a handler threw outside its declared errors: list, by primitive and name',
+});
+
+/**
+ * Where a test or a dev run goes red. Anything that is not literally `test` or `development` —
+ * an unset environment included — takes the production branch: a bookkeeping miss must never turn
+ * a refusal into a 500 in front of a user.
+ */
+const raisesUndeclared = (): boolean => {
+  const environment = tryResolveEnvironment({ fallback: 'production' });
+  return environment === 'test' || environment === 'development';
+};
+
+/** The (primitive, name, code) triples already warned about in this process. */
+const WARNED = new Set<string>();
+
+/**
+ * What to throw in place of `error`, a throw out of a handler. The original, unless it is a 4xx
+ * code the list does not name: then `X_ERROR_UNDECLARED` in test and development (the
+ * original as its `sourceError`), and the original with a warning and a count in production.
+ */
+export function enforceDeclared(
+  error: unknown,
+  declared: readonly string[] | undefined,
+  statusOf: ErrorStatusOf,
+  owner: DeclaredErrorsOwner,
+): unknown {
+  if (declared === undefined || !isUltimateError(error)) return error;
+  const { code } = error;
+  if (judgeThrown(declared, code, statusOf(code)) !== 'undeclared') return error;
+  if (raisesUndeclared()) return new ErrorUndeclaredError(owner, code, error);
+  undeclaredErrors.add(1, { primitive: owner.primitive, name: owner.name, code });
+  // One line per (primitive, name, code) per process: a hot endpoint is counted on every hit and
+  // logged once, never a line per request. The key space is bounded by the codebase.
+  const key = `${owner.primitive}\u0000${owner.name}\u0000${code}`;
+  if (!WARNED.has(key)) {
+    WARNED.add(key);
+    logger.warn('declared-errors.undeclared', { ...owner, code });
+  }
+  return error;
+}
+
+/** Run a handler under its list: the wrap `invoke` and the read path put around `handle`/`sql`. */
+export async function withDeclaredErrors<T>(
+  declared: readonly string[] | undefined,
+  statusOf: ErrorStatusOf,
+  owner: DeclaredErrorsOwner,
+  run: () => T | Promise<T>,
+): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    throw enforceDeclared(error, declared, statusOf, owner);
+  }
+}
+
+/**
+ * A tool's description, ending with the refusals its declaration lists — so an agent plans around
+ * a refusal before it calls. One sentence for `@ultimat3/mcp`'s tool and `@ultimat3/ai`'s, which
+ * the tier table keeps apart (`scripts/ai-mcp-tool-parity.test.ts`). Unchanged without a list.
+ */
+export function describeDeclaredErrors(
+  description: string,
+  errors: readonly string[] | undefined,
+): string {
+  if (errors === undefined || errors.length === 0) return description;
+  return `${description} Declared refusals: ${errors.join(', ')}.`;
+}

package/src/define-error.ts

@@ -0,0 +1,200 @@
+// Single responsibility: `defineError` — an APP code's one declaration: its title, its HTTP status
+// (or `offSocket`), its retry, and the `UltimateError` subclass that throws it. Its own module so a
+// chunk importing only `UltimateError` never retains it (`define-error-bytes.test.ts`). A framework
+// code goes through `bun run new-error-code` instead; the split is in this package's CLAUDE.md.
+
+import { describeErrorCode, hasErrorCode, registerErrorCodes } from './error-codes';
+import { renderCauseValue } from './error-render';
+import { type ErrorRetry, registerErrorRetry } from './error-retry';
+import {
+  appErrorStatus,
+  declareAppErrorStatus,
+  definedErrorStatus,
+  isHttpStatus,
+  recordDefinedError,
+} from './error-status-declared';
+import { isUltimateError, UltimateError } from './errors';
+
+/** A line written once, or computed from the throw's params. */
+export type ErrorText<P> = string | ((params: P) => string);
+
+interface ErrorSpecFields<P> {
+  /** `X_SCREAMING_SNAKE`, written as a literal here: the `errors` step and the manifest read it. */
+  readonly code: string;
+  readonly title: string;
+  readonly cause: ErrorText<P>;
+  /** A command to run, a call to paste, or an edit naming a file — `x verify --only errors` checks. */
+  readonly fix: ErrorText<P>;
+  readonly callerFix?: ErrorText<P> | undefined;
+  readonly docs?: string | undefined;
+  readonly retry?: ErrorRetry | undefined;
+  readonly meta?: ((params: P) => Readonly<Record<string, unknown>>) | undefined;
+}
+
+/**
+ * Exactly one of `status` (what a response answers) or `offSocket: true` (a boot, CLI or job fault
+ * no response ever carries). Neither was the 500-by-omission a reference app shipped for "post not
+ * found"; the type makes the choice, and `X_ERROR_DECLARATION_INVALID` holds it at runtime.
+ */
+export type DefineErrorSpec<P = undefined> = ErrorSpecFields<P> &
+  (
+    | { readonly status: number; readonly offSocket?: undefined }
+    | { readonly offSocket: true; readonly status?: undefined }
+  );
+
+/** What a throw site may add beyond the params: the value it wraps, and a one-site retry. */
+export interface DefinedErrorExtra {
+  readonly sourceError?: unknown;
+  readonly retry?: ErrorRetry | undefined;
+}
+
+type DefinedErrorArgs<P> = [P] extends [undefined]
+  ? [params?: undefined, extra?: DefinedErrorExtra]
+  : [params: P, extra?: DefinedErrorExtra];
+
+export interface DefinedError<P = undefined> {
+  new (...args: DefinedErrorArgs<P>): UltimateError;
+  readonly prototype: UltimateError;
+  readonly code: string;
+  /** `undefined` when declared `offSocket`. */
+  readonly status: number | undefined;
+  /**
+   * The brand plus the code — never `instanceof`, which a browser's `RemoteActionError` and a
+   * duplicated module instance both fail.
+   */
+  is(value: unknown): value is UltimateError;
+}
+
+const SCREAMING_SNAKE = /^X(?:_[A-Z0-9]+)+$/;
+
+const invalid = (code: unknown, cause: string): UltimateError =>
+  new UltimateError({
+    code: 'X_ERROR_DECLARATION_INVALID',
+    cause: `defineError({ code: ${renderCauseValue(code)} }) ${cause}`,
+    fix: 'x verify --only errors   # after editing the defineError call the cause names',
+    meta: { code: renderCauseValue(code) },
+  });
+
+const duplicate = (code: string, cause: string): UltimateError =>
+  new UltimateError({
+    code: 'X_ERROR_CODE_DUPLICATE',
+    cause: `${code} is already declared ${cause}`,
+    fix: `grep -rn "${code}" apps packages   # keep one declaration of the code, then x verify --only errors`,
+    meta: { code },
+  });
+
+/**
+ * Where each code was declared: the caller's stack frame, as text, never parsed here. The class a
+ * declaration returns is named `Defined` whatever the app binds it to, so `errors:`'s source scan
+ * (`declared-errors-scan.ts`) reads the binding off this line — test-time, on demand.
+ */
+const DECLARED_AT = new Map<string, string>();
+
+/** Code → the stack frame that declared it. Read by `definedErrorClassCodes` alone. */
+export const definedErrorSites = (): ReadonlyMap<string, string> => DECLARED_AT;
+
+function recordSite(code: string): void {
+  if (DECLARED_AT.has(code)) return;
+  const holder: { stack?: string } = {};
+  Error.captureStackTrace(holder, defineError);
+  const frame = holder.stack?.split('\n')[1];
+  if (frame !== undefined) DECLARED_AT.set(code, frame);
+}
+
+const text = <P>(value: ErrorText<P>, params: P): string =>
+  typeof value === 'function' ? value(params) : value;
+
+/** Every refusal, before any table is written: a refused declaration leaves no half behind. */
+function refusalOf<P>(spec: DefineErrorSpec<P>): UltimateError | undefined {
+  const { code } = spec;
+  if (typeof code !== 'string' || !SCREAMING_SNAKE.test(code)) {
+    return invalid(code, 'is not X_SCREAMING_SNAKE (X_ then upper-case words and digits)');
+  }
+  const hasStatus = spec.status !== undefined;
+  const offSocket = spec.offSocket === true;
+  if (hasStatus === offSocket) {
+    return invalid(
+      code,
+      hasStatus ? 'gives both status and offSocket' : 'gives neither status nor offSocket',
+    );
+  }
+  if (hasStatus && !isHttpStatus(spec.status)) {
+    return invalid(
+      code,
+      `gives status ${renderCauseValue(spec.status)}, which is not an HTTP status (100-599)`,
+    );
+  }
+  const defined = definedErrorStatus(code);
+  if (hasErrorCode(code)) {
+    // Registered and not by this function: a framework package's code (or an app table's). Its
+    // status is not this declaration's to give — X_FORBIDDEN's class would claim 200 while http
+    // answers 403 — so a matching title is no licence.
+    if (defined === undefined) return duplicate(code, 'by the framework');
+    const title = describeErrorCode(code).title;
+    if (title !== spec.title) {
+      return duplicate(code, `with the title ${renderCauseValue(title)}`);
+    }
+  }
+  // Off-socket is a declaration too, so a later `status: 404` for it is a disagreement — which only
+  // the record can see: the status table holds no row for an off-socket code.
+  const status = defined === undefined ? appErrorStatus(code) : defined.status;
+  if ((defined !== undefined || status !== undefined) && status !== spec.status) {
+    return duplicate(code, status === undefined ? 'off-socket' : `with the status ${status}`);
+  }
+  return undefined;
+}
+
+/**
+ * Declare an app error code and get its class back. Importing the module that calls it IS the
+ * registration — `registerErrorCodes`' convention. The same declaration twice is a no-op (a module
+ * re-evaluated under `x dev`); a different title or status is `X_ERROR_CODE_DUPLICATE`.
+ *
+ * ```ts
+ * export const PostNotFound = defineError<{ readonly ref: string }>({
+ *   code: 'X_POST_NOT_FOUND',
+ *   title: 'no such post in this organisation',
+ *   status: 404,
+ *   cause: (p) => `no post ${p.ref} in the actor's organisation`,
+ *   fix: 'x queries show postById --json, then pass an id it returns',
+ * });
+ * throw new PostNotFound({ ref });
+ * ```
+ */
+export function defineError<P = undefined>(spec: DefineErrorSpec<P>): DefinedError<P> {
+  const refused = refusalOf(spec);
+  if (refused !== undefined) throw refused;
+  const { code } = spec;
+  // `registerErrorRetry` refuses an unknown kind or a conflicting one BEFORE it writes, and the
+  // two writes after it cannot fail: `refusalOf` already answered for both.
+  if (spec.retry !== undefined) registerErrorRetry({ [code]: spec.retry });
+  if (!hasErrorCode(code)) {
+    registerErrorCodes({ [code]: { title: spec.title, docs: spec.docs } });
+  }
+  if (spec.status !== undefined) declareAppErrorStatus(code, spec.status);
+  recordDefinedError(code, spec.status);
+  recordSite(code);
+
+  class Defined extends UltimateError {
+    static readonly code = code;
+    static readonly status = spec.status;
+
+    static is(value: unknown): value is UltimateError {
+      return isUltimateError(value) && value.code === code;
+    }
+
+    constructor(...[params, extra]: DefinedErrorArgs<P>) {
+      const input = params as P;
+      super({
+        code,
+        cause: text(spec.cause, input),
+        fix: text(spec.fix, input),
+        callerFix: spec.callerFix === undefined ? undefined : text(spec.callerFix, input),
+        docs: spec.docs,
+        meta: spec.meta?.(input),
+        retry: extra?.retry,
+        sourceError: extra?.sourceError,
+      });
+    }
+  }
+  return Defined;
+}

package/src/deprecation.ts

@@ -44,6 +44,19 @@ export function recordDeprecatedCall(primitive: 'action' | 'query', name: string
   deprecatedCalls.add(1, { primitive, name });
 }
 
+/** The RFC 8288 link naming a retired declaration's replacement. One spelling, written and read. */
+export function successorLink(path: string): string {
+  return `<${path}>; rel="successor-version"`;
+}
+
+/**
+ * The path `successorLink` wrote, or `undefined` for a link that is not exactly one: another
+ * relation is an app's own header, and whoever re-serves a route has no claim on it.
+ */
+export function successorPathOf(link: string): string | undefined {
+  return /^<([^<>]*)>; rel="successor-version"$/.exec(link)?.[1];
+}
+
 /**
  * `Deprecation` is a structured-field Date (`@` + unix seconds, RFC 9745); `Sunset` is an
  * HTTP-date (IMF-fixdate, RFC 8594). Two spellings of one instant because two RFCs chose
@@ -64,9 +77,7 @@ export function renderDeprecation(
   };
   // The successor's URL, derived by the caller from its own route naming — the one the typed
   // client uses. A link built here from the export name would be a second URL derivation.
-  if (successorPath !== undefined) {
-    headers['link'] = `<${successorPath}>; rel="successor-version"`;
-  }
+  if (successorPath !== undefined) headers['link'] = successorLink(successorPath);
 
   const meta: Record<string, string> = {
     since: new Date(since).toISOString(),

package/src/drain-deadline.ts

@@ -26,8 +26,16 @@ export const DRAIN_DEADLINE_MAX_MS = 3_600_000;
  */
 export const WORKER_DRAIN_DEADLINE_MAX_MS = 86_400_000;
 
+/**
+ * An hour: how long a retiring worker (`SIGUSR2`, the chart's `preStop`) may finish what it holds,
+ * aborting nothing, before the SIGTERM. Not a second drain budget: this one cancels nothing. On by
+ * default because an idle worker exits at once, so it costs only while a job really holds a pod.
+ */
+export const WORKER_RETIRE_DEFAULT_MS = 3_600_000;
+
 const DEADLINE_KEY = 'drain.deadlineMs';
 const WORKER_DEADLINE_KEY = 'drain.workerDeadlineMs';
+const WORKER_RETIRE_KEY = 'drain.workerRetireMs';
 
 /**
  * Why a value is not a drain budget, or `undefined` when it is one. A whole number of milliseconds
@@ -55,15 +63,29 @@ export function workerDrainDeadlineIssue(value: unknown): string | undefined {
     : undefined;
 }
 
+/**
+ * Why a value is not the worker's retire, or `undefined` when it is one. A whole number in
+ * `0 ≤ v ≤ 86400000`; unlike a drain budget 0 is a real answer here: no retire, the plain SIGTERM.
+ */
+export function workerRetireIssue(value: unknown): string | undefined {
+  const count = countIssue(WORKER_RETIRE_KEY, value, 0);
+  if (count !== undefined) return count;
+  return (value as number) > WORKER_DRAIN_DEADLINE_MAX_MS
+    ? `${WORKER_RETIRE_KEY} must be at most ${WORKER_DRAIN_DEADLINE_MAX_MS} milliseconds (a day) — a job longer than that belongs in steps, which replay instead of re-running`
+    : undefined;
+}
+
 /** The `drain` section's issues, one per key, for `defineConfig`'s validator. */
 export function drainIssues(drain: {
   readonly readinessGraceMs: unknown;
   readonly deadlineMs: unknown;
   readonly workerDeadlineMs?: unknown;
+  readonly workerRetireMs?: unknown;
 }): readonly (string | undefined)[] {
   return [
     readinessGraceIssue(drain.readinessGraceMs),
     drainDeadlineIssue(drain.deadlineMs),
     workerDrainDeadlineIssue(drain.workerDeadlineMs),
+    workerRetireIssue(drain.workerRetireMs),
   ];
 }

package/src/env.ts

@@ -2,6 +2,7 @@
 // is reported in ONE error — an agent should never have to restart the process six times to
 // discover six missing variables.
 
+import { numeric } from '@ultimat3/schema';
 import { describeValue } from './error-render';
 import { EnvMissingError } from './errors';
 import { REDACTED, redactKeys } from './logger';
@@ -135,8 +136,9 @@ function parseValue(decl: EnvVarDecl, raw: string): { ok: true; value: unknown }
     case 'number':
     case 'integer':
     case 'port': {
-      const value = Number(raw);
-      if (!Number.isFinite(value)) return { ok: false };
+      // Schema's one decimal reader: `Number()` reads `' '` as 0 and `0x1F90` as 8080.
+      const value = numeric(raw);
+      if (value === undefined) return { ok: false };
       if (decl.type !== 'number' && !Number.isInteger(value)) return { ok: false };
       if (decl.type === 'port' && (value < 1 || value > 65535)) return { ok: false };
       if (decl.min !== undefined && value < decl.min) return { ok: false };
@@ -150,7 +152,10 @@ function parseValue(decl: EnvVarDecl, raw: string): { ok: true; value: unknown }
     case 'url':
       return URL.canParse(raw) ? { ok: true, value: raw } : { ok: false };
     default:
-      if (decl.pattern !== undefined && !decl.pattern.test(raw)) return { ok: false };
+      if (decl.pattern === undefined) return { ok: true, value: raw };
+      // A `g`/`y` pattern resumes at its `lastIndex`: a second check would refuse a valid value.
+      decl.pattern.lastIndex = 0;
+      if (!decl.pattern.test(raw)) return { ok: false };
       return { ok: true, value: raw };
   }
 }

package/src/error-fingerprint.ts

@@ -0,0 +1,95 @@
+// Single responsibility: which error reports are the same fault. A pure function over a report,
+// never a field on it: `ErrorReport` is public, and a member every hand-built report must now
+// carry, or every reader must now tolerate missing, is a break for a key a monitor can derive.
+
+import { fingerprint } from './canonical-json';
+import { stringField } from './error-render';
+import type { ErrorReport } from './error-reporter';
+
+/** `errorReport()`'s code for a throw nobody classified: the one code too wide to group on. */
+const UNCLASSIFIED = 'X_INTERNAL';
+
+/** `    at fn (path:1:2)`, `    at async fn (path:1:2)`, `    at path:1:2`. */
+const FRAME = /^\s*at\s+(?:async\s+)?(?:(.*?)\s+\((.*)\)|(.*))$/;
+
+/** A line and a column, or a line alone: an edit above the throw moves both. */
+const POSITION = /(?::\d+){1,2}$/;
+
+/** Library frames: the first frame that is the APP's names the fault, not the library under it. */
+const LIBRARY = /(?:^|\/)(?:node_modules|@ultimat3)\//;
+
+/** Reads that cannot throw: this runs on the path that reports a failure, and adds none. */
+function read<T>(get: () => T): T | undefined {
+  try {
+    return get();
+  } catch {
+    return undefined;
+  }
+}
+
+function workingDirectory(): string | undefined {
+  const cwd = read(() => process.cwd());
+  return cwd === undefined ? undefined : `${cwd.replaceAll('\\', '/').replace(/\/$/, '')}/`;
+}
+
+/** `file://`, the working directory and the position dropped; `/` separators on every OS. */
+function relativePath(location: string, root: string | undefined): string {
+  let path = location.trim().replace(POSITION, '').replaceAll('\\', '/');
+  if (path.startsWith('file://')) path = path.slice('file://'.length);
+  if (root !== undefined && path.startsWith(root)) path = path.slice(root.length);
+  return path.replace(/^\.\//, '');
+}
+
+/**
+ * The stack's FRAMES: the trailing run of `at …` lines. Read from the end, because the header
+ * above them is the error's message, and a message may itself hold `\n    at x (y:1:1)` — which
+ * read top-down would set the group to whatever the message's author typed.
+ */
+function framesOf(stack: string): readonly RegExpExecArray[] {
+  const frames: RegExpExecArray[] = [];
+  const lines = stack.trimEnd().split('\n');
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const match = FRAME.exec(lines[index] ?? '');
+    if (match === null) break;
+    frames.unshift(match);
+  }
+  return frames;
+}
+
+/**
+ * The top application frame as `fn path`, or `undefined`. A frame with no file location (`native`,
+ * `<anonymous>`, `processTicksAndRejections (native:7:39)`) is skipped as well: it is the
+ * runtime's, and two faults share it. A file location has a `/`; a runtime's never does.
+ */
+function applicationFrame(stack: string | undefined): string | undefined {
+  if (stack === undefined) return undefined;
+  const root = workingDirectory();
+  for (const match of framesOf(stack)) {
+    const location = match[2] ?? match[3] ?? '';
+    if (!POSITION.test(location.trim())) continue;
+    if (!location.replaceAll('\\', '/').includes('/')) continue;
+    const path = relativePath(location, root);
+    if (path === '' || LIBRARY.test(path)) continue;
+    const name = (match[1] ?? '').replace(/^new\s+/, '').trim();
+    return name === '' ? path : `${name} ${path}`;
+  }
+  return undefined;
+}
+
+/**
+ * A stable, 16-hex grouping key for a report. A coded fault groups on `code`, `source` and
+ * `scope.operation`; `X_INTERNAL` adds the top application frame (function and root-relative path,
+ * no line or column), because on its code alone every unclassified throw in an app is one group.
+ * Never `cause`, `meta`, an id or `release`: a row id splits one fault into a group per row, and a
+ * deploy is not a new fault. Total: a report it cannot read degrades to the frameless key.
+ */
+export function errorFingerprint(report: ErrorReport): string {
+  const code = stringField(report, 'code');
+  const source = stringField(report, 'source');
+  const operation = stringField(
+    read(() => report.scope),
+    'operation',
+  );
+  const frame = code === UNCLASSIFIED ? applicationFrame(stringField(report, 'stack')) : undefined;
+  return fingerprint({ code, source, operation, frame });
+}

package/src/error-reporter-chain.ts

@@ -0,0 +1,45 @@
+// Single responsibility: several `ErrorReporter`s behind the ONE seam — a vendor transport beside
+// an app's own sink (`@ultimat3/admin`'s `errorGroupsSink`). Not a second seam: the chain IS a
+// reporter, installed through `configureErrorReporting` like any other.
+
+import { renderThrowable } from './error-render';
+import { type ErrorReport, type ErrorReporter, noopErrorReporter } from './error-reporter';
+import { logger } from './logger';
+
+/** Which reporters a chain was built from — read back by `errorReportersOf`, never mutated. */
+const members = new WeakMap<ErrorReporter, readonly ErrorReporter[]>();
+
+/** The flat member list a reporter stands for: a chain's members, the no-op's none, else itself. */
+export function errorReportersOf(reporter: ErrorReporter): readonly ErrorReporter[] {
+  if (reporter === noopErrorReporter) return [];
+  return members.get(reporter) ?? [reporter];
+}
+
+/**
+ * One reporter that hands every report to each member, in order. A member that throws is logged
+ * and costs ONLY itself — `reportError`'s own catch guards the whole reporter, so without this one
+ * a vendor that is down would silence every member after it. Chains flatten and a member listed
+ * twice reports once, so a boot that composes with what is installed cannot double a sink.
+ */
+export function chainErrorReporters(...reporters: readonly ErrorReporter[]): ErrorReporter {
+  const flat = [...new Set(reporters.flatMap(errorReportersOf))];
+  if (flat.length === 0) return noopErrorReporter;
+  if (flat.length === 1) return flat[0] ?? noopErrorReporter;
+  const chain: ErrorReporter = {
+    report(event: ErrorReport): void {
+      flat.forEach((member, index) => {
+        try {
+          member.report(event);
+        } catch (failure) {
+          logger.warn('error reporter failed', {
+            source: event.source,
+            member: index,
+            error: renderThrowable(failure),
+          });
+        }
+      });
+    },
+  };
+  members.set(chain, Object.freeze(flat));
+  return chain;
+}

package/src/error-reporter-sentry.ts

@@ -3,6 +3,7 @@
 // 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 { errorFingerprint } from './error-fingerprint';
 import { renderThrowable } from './error-render';
 import type { ErrorReport, ErrorReporter, ErrorSeverity } from './error-reporter';
 import { type CodedErrorInit, UltimateError } from './errors';
@@ -89,6 +90,9 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
     server_name: report.resource.serviceName,
     ...(report.release === null ? {} : { release: report.release }),
     ...(report.scope.operation === undefined ? {} : { transaction: report.scope.operation }),
+    // The group. Without it the monitor groups on its own reading of the exception, which is the
+    // code, so every unclassified throw in the app was one issue (`errorFingerprint`).
+    fingerprint: [errorFingerprint(report)],
     // 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: {