@ultimat3/core 29.4.0 → 30.1.0

package/src/error-reporter.ts

@@ -9,6 +9,7 @@ import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from './
 import { renderThrowable } from './error-render';
 import { failureStack } from './error-stack';
 import { toUltimateError } from './errors';
+import { releaseHeldFailure } from './failure-capture-flush';
 import { logger } from './logger';
 import type { Role } from './roles';
 import { currentSpanContext, type SpanResource, serviceResource } from './telemetry';
@@ -20,7 +21,7 @@ export type ErrorSeverity = 'warning' | 'error' | 'fatal';
  * 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 const ERROR_SOURCES = ['http', 'job', 'realtime', 'cli', 'process', 'browser'] as const;
 
 export type ErrorSource = (typeof ERROR_SOURCES)[number];
 
@@ -115,6 +116,15 @@ export function configureErrorReporting(options: ErrorReportingOptions): void {
   if (options.enabled !== undefined) enabled = options.enabled;
 }
 
+/**
+ * The reporter installed now. Read by a boot that adds its own (`@ultimat3/cli`'s `SENTRY_DSN`
+ * transport) so it composes with an app's sink through `chainErrorReporters` instead of
+ * replacing it — the app's modules import, and install, before that boot line runs.
+ */
+export function installedErrorReporter(): ErrorReporter {
+  return reporter;
+}
+
 export function resetErrorReporting(): void {
   reporter = noopErrorReporter;
   clock = systemClock;
@@ -198,6 +208,9 @@ export function errorReport(error: unknown, options: ReportErrorOptions): ErrorR
  * 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 {
+  // First, and whatever `enabled` says: a 5xx `invoke` held its bundle on this value, and this is
+  // where it learns its group (`failure-capture-flush.ts`). Nothing held costs one `WeakMap` read.
+  releaseHeldFailure(error, () => errorReport(error, options));
   if (!enabled) return;
   try {
     reporter.report(errorReport(error, options));

package/src/error-status-declared.ts

@@ -0,0 +1,82 @@
+// Single responsibility: the APP's half of the HTTP status table — codes an app owns, mapped to the
+// status a response answers. Here rather than in `@ultimat3/http` because `defineError` (core)
+// writes it and core may not import upward; `@ultimat3/http`'s `registerErrorStatus` writes the same
+// table, and its `declaredStatusFor` reads the framework's closed table FIRST, so no row here moves one.
+//
+// INTERNAL: reached through `@ultimat3/core/internal/error-status`, never the barrel — an app has one
+// writer of its own (`defineError`) and one for a re-raised library code (`registerErrorStatus`).
+
+import { renderCauseValue, renderFixShellArg } from './error-render';
+import { UltimateError } from './errors';
+
+/** A `Map`, never an object literal: the key is a caller's string, and `'toString'` is one. */
+const APP_ERROR_STATUS = new Map<string, number>();
+
+/**
+ * Every code `defineError` declared, with its status — `undefined` for an off-socket one. Beside the
+ * table, not in `define-error.ts`, so a reset and a snapshot cover both: a record that outlived its
+ * table refused a test's fresh declaration of the same code.
+ */
+const DEFINED = new Map<string, number | undefined>();
+
+/** Is `status` a value a `Response` can carry? */
+export const isHttpStatus = (status: unknown): status is number =>
+  typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599;
+
+/** The status this app declared for `code`, `undefined` when it declared none. */
+export const appErrorStatus = (code: string): number | undefined => APP_ERROR_STATUS.get(code);
+
+/**
+ * Write one row. The two writers — `defineError` and `registerErrorStatus` — each refuse first with
+ * their own code, so this is the last line, not the first: a status outside 100-599 or a second,
+ * different status for one code can never reach the table whoever forgot to check.
+ */
+export function declareAppErrorStatus(code: string, status: number): void {
+  const existing = APP_ERROR_STATUS.get(code);
+  if (!isHttpStatus(status) || (existing !== undefined && existing !== status)) {
+    throw new UltimateError({
+      code: 'X_ERROR_DECLARATION_INVALID',
+      cause: `${code} cannot answer ${renderCauseValue(status)}: ${
+        existing === undefined
+          ? 'that is not an HTTP status (100-599)'
+          : `this app already declared it as ${existing}`
+      }`,
+      fix: `grep -rn ${renderFixShellArg(code, '<CODE>')} apps packages   # keep one declaration, one status, then x verify --only errors`,
+      meta: { code },
+    });
+  }
+  APP_ERROR_STATUS.set(code, status);
+}
+
+/** Whether `defineError` declared `code`, and with which status (`undefined` = off-socket). */
+export const definedErrorStatus = (
+  code: string,
+): { readonly status: number | undefined } | undefined =>
+  DEFINED.has(code) ? { status: DEFINED.get(code) } : undefined;
+
+/** `defineError`'s record of a declaration it accepted. */
+export const recordDefinedError = (code: string, status: number | undefined): void => {
+  DEFINED.set(code, status);
+};
+
+/** Test seam. Production declares once at boot and never undeclares. */
+export const resetAppErrorStatus = (): void => {
+  APP_ERROR_STATUS.clear();
+  DEFINED.clear();
+};
+
+/**
+ * Test-only: capture the table and get the undo back — `errorCodeSnapshot`'s shape, for the same
+ * reason. Bun runs one process per suite, every app module declares at import, and a bare
+ * `resetAppErrorStatus()` strips rows the file never wrote.
+ */
+export function appErrorStatusSnapshot(): () => void {
+  const saved = new Map(APP_ERROR_STATUS);
+  const defined = new Map(DEFINED);
+  return () => {
+    APP_ERROR_STATUS.clear();
+    for (const [code, status] of saved) APP_ERROR_STATUS.set(code, status);
+    DEFINED.clear();
+    for (const [code, status] of defined) DEFINED.set(code, status);
+  };
+}

package/src/exercise-errors.ts

@@ -0,0 +1,41 @@
+// Single responsibility: the two refusals the shared exercise loop raises BEFORE a run, so an
+// action's and a query's exercise refuse the same way. Off the socket: each is raised in a test
+// process or a script, never served. The verdict codes (`X_CONTRACT_DEFECT`, …) stay action's.
+
+import { renderFixShellArg } from './error-render';
+import { UltimateError } from './errors';
+
+/**
+ * Not `development` or `test`: a deployed process. The exercise calls a handler with generated
+ * input, and mail, storage, outbound fetch and a non-outbox enqueue are not rolled back with the
+ * transaction — against a deploy those are real.
+ */
+export class ExerciseEnvironmentError extends UltimateError {
+  static readonly code = 'X_CONTRACT_EXERCISE_ENVIRONMENT';
+  override readonly name = 'ExerciseEnvironmentError';
+  constructor(subject: string, environment: string) {
+    super({
+      code: ExerciseEnvironmentError.code,
+      cause: `${subject} was exercised in the ${environment} environment: generated input would run against a deploy, and mail, storage, outbound fetch and non-outbox jobs are never rolled back`,
+      fix: `bun test <the file calling ${renderFixShellArg(subject, '<name>')}.contract()>   # under bun test (NODE_ENV=test) — never with ULTIMATE_ENV=${environment}`,
+      meta: { environment },
+    });
+  }
+}
+
+/**
+ * No transaction can be opened that the writes would join, outside `test`: the handler's writes
+ * would land on the process's lazy pool (`DATABASE_URL`) and be kept.
+ */
+export class ExerciseUnscopedError extends UltimateError {
+  static readonly code = 'X_CONTRACT_EXERCISE_UNSCOPED';
+  override readonly name = 'ExerciseUnscopedError';
+  constructor(subject: string, environment: string) {
+    super({
+      code: ExerciseUnscopedError.code,
+      cause: `${subject} was exercised in ${environment} with no database client installed and no transaction open, so its writes could not be rolled back`,
+      fix: `setDbClient(<a test database client>) from @ultimat3/db before ${renderFixShellArg(subject, '<name>')}.contract()   # or run it under bun test (NODE_ENV=test)`,
+      meta: { environment },
+    });
+  }
+}

package/src/exercise-run.ts

@@ -0,0 +1,176 @@
+/**
+ * The contract step's exercise loop, once for `@ultimat3/action` and `@ultimat3/query` (both tier
+ * 3, neither may import the other): seeded draws, the verdict on each run, the replay command and
+ * the refusals before a run. Each adapter supplies the draw, the schema check and one attempt.
+ */
+
+import { assert } from './assert';
+import type { ErrorStatusOf } from './declared-errors';
+import { type Environment, resolveEnvironment } from './environment';
+import { isFixShellSafe, renderThrowable } from './error-render';
+import { isUltimateError } from './errors';
+import { ExerciseEnvironmentError, ExerciseUnscopedError } from './exercise-errors';
+import { fnv1a } from './fnv1a';
+import { isJsonObject } from './json-object';
+
+/** Runs per exercise by default: sixteen invocations, four of them on the IR's bounds. */
+export const EXERCISE_RUNS = 16;
+/** The most a caller may raise `runs` to: every run is a real invocation. */
+export const EXERCISE_RUNS_MAX = 64;
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** One run's end. `reached` is the adapter's probe: did the handler (or `sql()`) start? */
+export type ExerciseAttempt =
+  | { readonly ok: true; readonly reached: boolean }
+  | { readonly ok: false; readonly reached: boolean; readonly error: unknown };
+
+/** What a passing exercise saw. */
+export interface ExerciseReport {
+  readonly runs: number;
+  readonly reached: number;
+  readonly refused: number;
+  readonly outcomes: readonly string[];
+}
+
+/** What the adapter hands the loop. `env` exists for a test; a caller leaves it out. */
+export interface ExerciseSubject {
+  readonly name: string;
+  readonly runs?: number | undefined;
+  /** How an outcome reads when the run stopped before the probe: `stopped before sql()`. */
+  readonly stoppedLabel: string;
+  draw(seed: number, run: number): unknown;
+  readonly bind?: ((drawn: unknown) => unknown) | undefined;
+  accepts(input: unknown): Promise<boolean>;
+  attempt(input: unknown): Promise<ExerciseAttempt>;
+  readonly statusOf: ErrorStatusOf;
+  readonly env?: Env | undefined;
+  /** A write: whether a transaction undoes each attempt. Omitted by a read, which writes nothing. */
+  readonly scoped?: boolean | undefined;
+}
+
+/** The loop's answer. Returned, never thrown: the codes are the adapter's to raise. */
+export type ExerciseVerdict =
+  | { readonly kind: 'pass'; readonly report: ExerciseReport }
+  | {
+      readonly kind: 'defect';
+      readonly run: number;
+      readonly input: unknown;
+      readonly defect: string;
+      readonly error: unknown;
+    }
+  | { readonly kind: 'unreached'; readonly outcomes: readonly string[] }
+  | { readonly kind: 'drift' };
+
+/** A thrown value's verdict: `null` is a pass (a coded refusal under 500), else what was wrong. */
+export function exerciseDefect(error: unknown, statusOf: ErrorStatusOf): string | null {
+  if (!isUltimateError(error)) return `threw an uncoded ${renderThrowable(error)}`;
+  if (error.code === 'X_OUTPUT_INVALID') return 'returned a value its output schema rejects';
+  // An unmapped code answers 500 on the wire, so it is a 500 here.
+  const status = statusOf(error.code) ?? 500;
+  return status >= 500 ? `answered ${error.code}, a ${status}` : null;
+}
+
+/** The host a sealed-network refusal names, read off its cause (`GET https://host/... was ...`). */
+export function sealedHost(cause: string): string {
+  const url = /^\S+ (\S+) was not mocked/.exec(cause)?.[1];
+  if (url === undefined || !URL.canParse(url)) return 'an unnamed host';
+  return new URL(url).host;
+}
+
+/**
+ * `bun test <this file> -t '<testName>'` when a test file is running — the seed is the name, so
+ * that replays the exact run — and the step otherwise. Single quotes are safe only around a name
+ * `isFixShellSafe` already carries verbatim; `testName` is that name plus fixed words.
+ */
+export function exerciseReplay(name: string, testName: string): string {
+  // POSIX separators on every platform: a Windows `Bun.main` is `C:\…\x.test.ts`, which neither
+  // strips against the cwd nor travels through a shell as written.
+  const posix = (path: string): string => path.replaceAll('\\', '/');
+  const main = posix(Bun.main);
+  const file = main.replace(`${posix(process.cwd())}/`, '');
+  if (!main.includes('.test.') || !isFixShellSafe(file) || !isFixShellSafe(name)) {
+    return 'x verify --only contract';
+  }
+  return `bun test ${file} -t '${testName}'`;
+}
+
+/**
+ * Which deploy the exercise is in. Fails CLOSED: a process naming neither `ULTIMATE_ENV` nor
+ * `NODE_ENV` is read as `production`, where the shared default is `development` — an unnamed
+ * deploy must not run generated input. `bun test` names `test`, so a test run is unaffected.
+ */
+const exerciseEnvironment = (env: Env | undefined): Environment =>
+  resolveEnvironment({ env, fallback: 'production' });
+
+/**
+ * Refuse when no transaction would undo the writes — no client installed, none open — anywhere
+ * but `test`, where the store is memory. Outside it the handler's writes reach `DATABASE_URL`.
+ */
+export function assertExerciseScoped(name: string, scoped: boolean, env?: Env): void {
+  const environment = exerciseEnvironment(env);
+  if (!scoped && environment !== 'test') throw new ExerciseUnscopedError(name, environment);
+}
+
+/** Exercise `subject`: refuse a deploy, then draw, check, attempt and judge each run. */
+export async function runExercise(subject: ExerciseSubject): Promise<ExerciseVerdict> {
+  const { name } = subject;
+  const environment = exerciseEnvironment(subject.env);
+  if (environment !== 'development' && environment !== 'test') {
+    throw new ExerciseEnvironmentError(name, environment);
+  }
+  if (subject.scoped !== undefined) assertExerciseScoped(name, subject.scoped, subject.env);
+  const runs = subject.runs ?? EXERCISE_RUNS;
+  assert(
+    Number.isInteger(runs) && runs >= 1 && runs <= EXERCISE_RUNS_MAX,
+    `${name}: exercise runs must be a whole number from 1 to ${EXERCISE_RUNS_MAX}`,
+    `${name}.contract({ exercise: { actor, runs: ${EXERCISE_RUNS} } })`,
+  );
+  const seed = fnv1a(name);
+  const outcomes: string[] = [];
+  let reached = 0;
+  let refused = 0;
+  for (let run = 0; run < runs; run += 1) {
+    const drawn = subject.draw(seed, run);
+    const input = subject.bind === undefined ? drawn : await subject.bind(drawn);
+    if (!(await subject.accepts(input))) {
+      refused += 1;
+      outcomes.push(`run ${run}: input refused by its own schema`);
+      continue;
+    }
+    const attempt = await subject.attempt(input);
+    if (attempt.ok) {
+      reached += attempt.reached ? 1 : 0;
+      outcomes.push(`run ${run}: answered`);
+      continue;
+    }
+    // Before the verdict: the sealed network is the test's wall, not the handler's failure, and
+    // its code maps to no status, so `exerciseDefect` would read it as a 500.
+    const { error } = attempt;
+    if (isUltimateError(error) && error.code === 'X_TEST_NETWORK_SEALED') {
+      outcomes.push(`run ${run}: network sealed (${sealedHost(error.cause)})`);
+      continue;
+    }
+    const defect = exerciseDefect(error, subject.statusOf);
+    if (defect !== null) return { kind: 'defect', run, input, defect, error };
+    const code = isUltimateError(error) ? error.code : 'uncoded';
+    reached += attempt.reached ? 1 : 0;
+    outcomes.push(`run ${run}: ${attempt.reached ? 'refused' : subject.stoppedLabel} with ${code}`);
+  }
+  if (refused === runs) return { kind: 'drift' };
+  if (reached === 0) return { kind: 'unreached', outcomes };
+  return { kind: 'pass', report: { runs, reached, refused, outcomes } };
+}
+
+/** A generated value an override binds into: an action's or a query's input is an object. */
+export type DrawnInput = Readonly<Record<string, unknown>>;
+
+/**
+ * An override's `input` as the loop's `bind`: typed over an object, so `(drawn) => ({ ...drawn,
+ * postId })` compiles as written. A value that drew no object is passed through, since nothing
+ * in it can be bound by name.
+ */
+export const bindDrawn = (
+  input: ((drawn: DrawnInput) => unknown) | undefined,
+): ((drawn: unknown) => unknown) | undefined =>
+  input === undefined ? undefined : (drawn) => (isJsonObject(drawn) ? input(drawn) : drawn);

package/src/exports/error-contract.ts

@@ -5,6 +5,13 @@
 
 export type { CoreErrorCode } from '../core-error-codes';
 export { CORE_ERROR_CODES } from '../core-error-codes';
+export type {
+  DefinedError,
+  DefinedErrorExtra,
+  DefineErrorSpec,
+  ErrorText,
+} from '../define-error';
+export { defineError } from '../define-error';
 export type {
   ErrorCodeDeclaration,
   ErrorCodeDescriptor,

package/src/exports/observability.ts

@@ -3,6 +3,7 @@
 // subject — a process's own account of what it did — and `index.ts` re-exports every name below
 // explicitly, so this file changes what a reader looks at and never what the package exports.
 
+export { errorFingerprint } from '../error-fingerprint';
 export type {
   ErrorReport,
   ErrorReporter,
@@ -17,11 +18,13 @@ export {
   configureErrorReporting,
   ERROR_SOURCES,
   errorReport,
+  installedErrorReporter,
   memoryErrorReporter,
   noopErrorReporter,
   reportError,
   resetErrorReporting,
 } from '../error-reporter';
+export { chainErrorReporters, errorReportersOf } from '../error-reporter-chain';
 export type {
   SentryDsn,
   SentryEnvelopeOptions,
@@ -33,6 +36,28 @@ export {
   sentryEnvelope,
   sentryErrorReporter,
 } from '../error-reporter-sentry';
+export type {
+  FailureActor,
+  FailureBundle,
+  FailureCaptureLimits,
+  FailureFact,
+  FailurePrimitive,
+  FailureRead,
+  FailureStore,
+  HeldFailure,
+} from '../failure-capture';
+export {
+  failureCaptureActive,
+  failureCaptureLimits,
+  installedFailureStore,
+  recordFailureFact,
+  recordFailureInput,
+  setFailureStore,
+  withFailureCapture,
+} from '../failure-capture';
+export { resetFailureCaptureWindows, settleFailureCaptures } from '../failure-capture-flush';
+export type { CapturedValue } from '../failure-capture-mask';
+export { captureValue } from '../failure-capture-mask';
 export type { LogFields, Logger, LoggerOptions, LogLevel } from '../logger';
 export {
   isRedactedKey,
@@ -87,6 +112,7 @@ export {
   OTLP_ENDPOINT_KEY,
   OTLP_HEADERS_KEY,
   OTLP_PROTOCOL_KEY,
+  OTLP_RETRY_STATUSES,
   OTLP_SCOPE,
   OtlpEndpointInvalidError,
   OtlpHeadersInvalidError,

package/src/failure-capture-flush.ts

@@ -0,0 +1,93 @@
+// Single responsibility: turning a held failure into a stored bundle, at `reportError` — the one
+// moment the failure has its group (`errorFingerprint` over the very report the monitor gets), so
+// `x_failures` and `x_error_groups` are keyed alike. Bounded per fingerprint per hour, capped in
+// bytes, and never awaited by the response: a store that refuses is a log line.
+
+import { errorFingerprint } from './error-fingerprint';
+import type { ErrorReport } from './error-reporter';
+import type { FailureBundle, HeldFailure } from './failure-capture';
+import {
+  failureCaptureLimits,
+  failureStoreRefused,
+  installedFailureStore,
+  takeHeldFailure,
+} from './failure-capture';
+import { uuidV7 } from './ids';
+
+const HOUR_MS = 60 * 60 * 1000;
+/** Fingerprints remembered for the hourly bound; past it the oldest window is forgotten. */
+const MAX_WINDOWS = 1000;
+
+const windows = new Map<string, { start: number; count: number }>();
+const pending = new Set<Promise<void>>();
+
+/** Whether one more bundle of this group fits this hour. Per process: a fleet stores N× the bound. */
+function admitted(fingerprint: string, at: number): boolean {
+  const window = windows.get(fingerprint);
+  if (window === undefined || at - window.start >= HOUR_MS) {
+    windows.delete(fingerprint);
+    if (windows.size >= MAX_WINDOWS) windows.delete(windows.keys().next().value ?? '');
+    windows.set(fingerprint, { start: at, count: 1 });
+    return true;
+  }
+  if (window.count >= failureCaptureLimits().perHour) return false;
+  window.count += 1;
+  return true;
+}
+
+const sizeOf = (bundle: FailureBundle): number =>
+  new TextEncoder().encode(JSON.stringify(bundle)).length;
+
+/** Rows dropped from the end, then the flags, until the bundle fits `maxBytes`. Never the input. */
+function capped(bundle: FailureBundle): FailureBundle {
+  const max = failureCaptureLimits().maxBytes;
+  if (sizeOf(bundle) <= max) return bundle;
+  const reads = [...bundle.reads];
+  let next: FailureBundle = bundle;
+  while (reads.length > 0 && sizeOf(next) > max) {
+    reads.pop();
+    next = { ...bundle, reads: [...reads], truncated: true };
+  }
+  return sizeOf(next) <= max ? next : { ...next, flags: {}, truncated: true };
+}
+
+function bundleOf(held: HeldFailure, report: ErrorReport): FailureBundle {
+  return capped({
+    ...held,
+    id: uuidV7(),
+    fingerprint: errorFingerprint(report),
+    code: report.code,
+    operation: report.scope.operation ?? null,
+    build: held.build ?? report.release,
+    at: held.at === 0 ? report.at : held.at,
+  });
+}
+
+/**
+ * Called by `reportError` with every report, before the reporter sees it. A value nothing held
+ * costs one `WeakMap` read. Total: it never throws, and the save is never awaited here.
+ */
+export function releaseHeldFailure(error: unknown, report: () => ErrorReport): void {
+  const store = installedFailureStore();
+  const held = takeHeldFailure(error);
+  if (store === null || held === undefined) return;
+  try {
+    const bundle = bundleOf(held, report());
+    if (!admitted(bundle.fingerprint, bundle.at)) return;
+    const saving = store.save(bundle).catch(failureStoreRefused);
+    pending.add(saving);
+    void saving.finally(() => pending.delete(saving));
+  } catch (failure) {
+    failureStoreRefused(failure);
+  }
+}
+
+/** Every save in flight, settled: a drain hook, and a test that reads the store next. */
+export async function settleFailureCaptures(): Promise<void> {
+  while (pending.size > 0) await Promise.all([...pending]);
+}
+
+/** Test-only: forget the hourly windows. */
+export function resetFailureCaptureWindows(): void {
+  windows.clear();
+}

package/src/failure-capture-mask.ts

@@ -0,0 +1,54 @@
+// Single responsibility: what a failure bundle may keep of a value — every key the app declared
+// secret (`redactKeys`), every `Secret` and every field a schema already masked, replaced by
+// `REDACTED` and LISTED by path, so `x repro` can say which fields it had to invent.
+
+import { isRedactedKey } from './logger';
+import { isSecret, REDACTED } from './secret';
+
+/** Deep enough for any input that is a request and not a document; past it the subtree is cut. */
+const MAX_DEPTH = 8;
+
+export interface CapturedValue {
+  readonly value: unknown;
+  /** Dotted paths (`card.pan`, `items[]`) whose value is `REDACTED` in `value`. */
+  readonly masked: readonly string[];
+}
+
+const join = (at: string, key: string): string => (at === '' ? key : `${at}.${key}`);
+
+function walk(value: unknown, at: string, depth: number, masked: string[]): unknown {
+  if (value === REDACTED || isSecret(value)) {
+    masked.push(at === '' ? '(the value)' : at);
+    return REDACTED;
+  }
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Date) return value.toISOString();
+  if (depth >= MAX_DEPTH) return '[depth-limit]';
+  if (Array.isArray(value)) return value.map((entry) => walk(entry, `${at}[]`, depth + 1, masked));
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const path = join(at, key);
+    const kept = isRedactedKey(key)
+      ? walk(REDACTED, path, depth + 1, masked)
+      : walk(entry, path, depth + 1, masked);
+    // `defineProperty`, never assignment: an input key named `__proto__` must stay a key.
+    Object.defineProperty(out, key, {
+      value: kept,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out;
+}
+
+/**
+ * A JSON-safe copy of `value` with every secret masked and listed. `value` may already carry
+ * `REDACTED` where a schema's `.sensitive()` masked it (`maskSensitive`); those are listed too.
+ * Paths are deduplicated: one masked field in every element of a list is one path, `items[].pan`.
+ */
+export function captureValue(value: unknown): CapturedValue {
+  const masked: string[] = [];
+  const kept = walk(value, '', 0, masked);
+  return { value: kept, masked: [...new Set(masked)] };
+}