@ultimat3/action 23.0.0 → 25.0.0

package/src/idempotency-memory.ts

@@ -3,7 +3,8 @@
  * and for tests, and refused at registration under a `shared` declaration — its `scope` says so.
  * Shaped after `@ultimat3/http`'s `memoryRateLimitStore`, including the deliberate eviction order.
  */
-import { finiteCount, uuid } from '@ultimat3/core';
+import { finiteCount, uuidV7 } from '@ultimat3/core';
+import { IdempotencyReservationLostError } from './errors-idempotency';
 import type {
   IdempotencyFailure,
   IdempotencyRecord,
@@ -11,6 +12,8 @@ import type {
   IdempotencyScope,
   IdempotencyStore,
 } from './idempotency';
+import { requestDeadlineMs } from './request-deadline';
+import { liveTransaction } from './tx-scope';
 
 /**
  * How long a key is remembered. A day is the window every payment API this shape exists to serve
@@ -34,15 +37,36 @@ export interface MemoryIdempotencyStoreOptions {
   readonly maxKeys?: number | undefined;
   /** Injectable so a test can age a record without sleeping. */
   readonly now?: (() => number) | undefined;
+  /**
+   * The request deadline, read at every reservation — how long an in-flight record whose
+   * settlement rides a transaction is kept before a retry may take the key. Default: the app's
+   * own `requestTimeoutMs` (`requestDeadlineMs`). `0` is "no deadline".
+   */
+  readonly reclaimAfterMs?: (() => number) | undefined;
+}
+
+/**
+ * What an in-flight record's transaction has to do with it — the memory twin of the Postgres
+ * store's `tx_bound` column and of the row lock its settle holds until COMMIT. Keyed by the record
+ * object: a settled or failed record is a new object, so these never outlive the flight.
+ */
+interface Flight {
+  /** Reserved inside a transaction: its settle commits with the write or not at all. */
+  readonly bound: boolean;
+  /** The settle ran and its transaction has not ended yet — nobody may reclaim it now. */
+  settling: boolean;
 }
 
 export class MemoryIdempotencyStore implements IdempotencyStore {
   /** Declared, never inferred: this map is this process's and nothing else can reach it. */
   readonly scope: IdempotencyScope = 'process';
+  readonly keepsRedaction = true as const;
   readonly windowMs: number;
   readonly #maxKeys: number;
   readonly #evictTo: number;
   readonly #now: () => number;
+  readonly #reclaimAfterMs: () => number;
+  readonly #flights = new WeakMap<IdempotencyRecord, Flight>();
   readonly #records = new Map<string, IdempotencyRecord>();
   #lastSweepMs = Number.NEGATIVE_INFINITY;
 
@@ -51,13 +75,13 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     // size and `now - at > windowMs` is false for every record — a table with no cap, holding keys
     // that never expire, out of a `Math.max` that reads like a guard.
     this.windowMs = finiteCount(
-      'MemoryIdempotencyStore',
+      'memoryIdempotencyStore',
       'windowMs',
       options.windowMs ?? DEFAULT_IDEMPOTENCY_WINDOW_MS,
       1,
     );
     this.#maxKeys = finiteCount(
-      'MemoryIdempotencyStore',
+      'memoryIdempotencyStore',
       'maxKeys',
       options.maxKeys ?? DEFAULT_MAX_IDEMPOTENCY_KEYS,
       1,
@@ -65,6 +89,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     // Batched down to 90% so the eviction sort is paid once per 10% of the cap, not per write.
     this.#evictTo = Math.max(1, Math.floor(this.#maxKeys * 0.9));
     this.#now = options.now ?? ((): number => Date.now());
+    this.#reclaimAfterMs = options.reclaimAfterMs ?? requestDeadlineMs;
   }
 
   /** Records tracked right now — the bound, observable. */
@@ -77,11 +102,15 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     const existing = this.#records.get(key);
     // Expired is missing. A record past the window answers exactly as a first-ever key does, so
     // reclaiming it here is what makes the window mean something rather than being a comment.
-    if (existing !== undefined && !this.#expired(existing, nowMs)) {
+    if (
+      existing !== undefined &&
+      !this.#expired(existing, nowMs) &&
+      !this.#abandoned(existing, nowMs)
+    ) {
       return Promise.resolve({ record: existing, created: false });
     }
     const record: IdempotencyRecord = {
-      id: uuid(),
+      id: uuidV7(),
       key,
       requestHash,
       status: 'in-flight',
@@ -89,10 +118,28 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
       createdAt: nowMs,
     };
     this.#records.set(key, record);
+    this.#flights.set(record, { bound: liveTransaction() !== undefined, settling: false });
     this.#maintain(nowMs);
     return Promise.resolve({ record, created: true });
   }
 
+  /**
+   * An in-flight record past the request deadline whose settle was BOUND to a transaction: that
+   * settle lands with the commit or not at all, so the record being in flight proves nothing
+   * committed. An autocommit handler's record is never this — it may have written before it died.
+   */
+  #abandoned(record: IdempotencyRecord, nowMs: number): boolean {
+    const flight = this.#flights.get(record);
+    if (record.status !== 'in-flight' || flight === undefined) return false;
+    if (!flight.bound || flight.settling) return false;
+    const reclaimAfterMs = finiteCount(
+      'memoryIdempotencyStore',
+      'reclaimAfterMs',
+      this.#reclaimAfterMs(),
+    );
+    return reclaimAfterMs > 0 && nowMs - record.createdAt >= reclaimAfterMs;
+  }
+
   /**
    * Both settlements are FENCED on the reservation's own `id` AND on `in-flight`, as
    * `SQL_IDEMPOTENCY_SETTLE` is and as `@ultimat3/jobs`' `SQL_ACK` is. A record past the window is
@@ -102,11 +149,38 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
    * again — which is why the id is half the fence. Both stores fence, or the guarantee is
    * whichever store the deployment happens to install.
    */
-  settle(key: string, value: unknown, reservationId: string): Promise<void> {
+  settle(key: string, value: unknown, reservationId: string, redacted: boolean): Promise<void> {
     const existing = this.#owned(key, reservationId);
-    if (existing !== undefined) {
-      this.#records.set(key, { ...existing, status: 'settled', value });
+    // Spread only when set, so an unredacted record keeps the exact shape it always had.
+    const settled = (from: IdempotencyRecord): IdempotencyRecord => ({
+      ...from,
+      status: 'settled',
+      value,
+      ...(redacted ? { redacted: true } : {}),
+    });
+    const tx = liveTransaction();
+    if (tx === undefined) {
+      if (existing !== undefined) this.#records.set(key, settled(existing));
+      return Promise.resolve();
+    }
+    // Inside a transaction the record is settled BY the commit, as the Postgres store's is: a
+    // rollback leaves it in flight rather than replaying a success for rows nobody stored. And a
+    // settle that lost its reservation is thrown, because nothing has committed yet and the throw
+    // is what rolls this attempt back beside the retry that replaced it.
+    if (existing === undefined) {
+      return Promise.reject(new IdempotencyReservationLostError(key));
     }
+    const flight = this.#flights.get(existing);
+    if (flight !== undefined) flight.settling = true;
+    tx.onRollback(() => {
+      if (flight !== undefined) flight.settling = false;
+    });
+    tx.onCommit(() => {
+      // Still this reservation's: `settling` kept a reclaim away, and `release` may have dropped it.
+      if (this.#records.get(key) === existing) {
+        this.#records.set(key, settled(existing));
+      }
+    });
     return Promise.resolve();
   }
 
@@ -169,3 +243,13 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     // becomes sweepable the moment it ages past the window.
   }
 }
+
+/**
+ * The one way to build the memory store — the twin of `postgresIdempotencyStore()`. The class
+ * stays a type in the barrel (`X_FACTORY_NAME_SPELLING`), so `new` is never a second spelling.
+ */
+export function memoryIdempotencyStore(
+  options: MemoryIdempotencyStoreOptions = {},
+): MemoryIdempotencyStore {
+  return new MemoryIdempotencyStore(options);
+}

package/src/idempotency-postgres.ts

@@ -4,8 +4,9 @@
  * without it, `replicas: 3` means a retry that lands elsewhere re-runs a committed handler.
  * Statements are spelled out so an agent can run the exact one it saw in a log.
  */
-import { finiteCount, logger, uuid } from '@ultimat3/core';
-import { IdempotencyStatusUnknownError } from './errors';
+import type { PgExecutor } from '@ultimat3/core';
+import { finiteCount, logger, uuidV7 } from '@ultimat3/core';
+import { IdempotencyReservationLostError, IdempotencyStatusUnknownError } from './errors';
 import type {
   IdempotencyFailure,
   IdempotencyRecord,
@@ -15,22 +16,7 @@ import type {
 } from './idempotency';
 import { IDEMPOTENCY_STATUSES, isIdempotencyStatus } from './idempotency';
 import { DEFAULT_IDEMPOTENCY_WINDOW_MS } from './idempotency-memory';
-
-/**
- * The one thing this store needs from the DB layer, declared structurally rather than imported.
- * `@ultimat3/jobs` declares the same shape for the same reason: neither package owns the other's
- * connection, and neither depends on a database package.
- *
- * **`Bun.sql` does not satisfy it** — verified against Bun 1.3.14: `Bun.sql.query` is `undefined`.
- * `Bun.sql` is a tagged template whose positional form is `unsafe`, so `{ executor: Bun.sql }`
- * would `TypeError` on the first reservation, which is the one call path that must not fail open.
- * What satisfies it is a client that already speaks `(text, values)`, wrapped in one line —
- * `@ultimat3/cli`'s `pgExecutorFor(client)` over `@ultimat3/db`'s `DbClient.query({ text, values })`
- * is the framework's own — or a transaction handle, which is a client on its own connection.
- */
-export interface PgExecutor {
-  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
-}
+import { liveTransaction } from './tx-scope';
 
 /**
  * The store's ONE install point, applied the way `SQL_JOBS_TABLE` is — by the boot, not by an app
@@ -51,31 +37,46 @@ create table if not exists x_idempotency (
 );
 
 create index if not exists x_idempotency_created_at_idx on x_idempotency (created_at);
+
+alter table x_idempotency add column if not exists tx_bound boolean not null default false;
+
+alter table x_idempotency add column if not exists redacted boolean not null default false;
 `;
 
 /**
- * The reservation, atomic in one statement. The `do update` fires ONLY for a row already outside
- * the window — which answers as a missing one — so a returned row always means this caller owns
- * the reservation and must run the handler. No row back means a live record exists and belongs to
- * someone else.
+ * The reservation, atomic in one statement. The `do update` fires ONLY for a row that answers as a
+ * missing one, so a returned row always means this caller owns the reservation and must run the
+ * handler. No row back means a live record exists and belongs to someone else.
+ *
+ * Two rows answer as missing. One outside the window. And one still `in-flight` past the request
+ * deadline (`$6`) whose settlement was BOUND TO A TRANSACTION (`tx_bound`): that settle commits
+ * with the handler's writes or not at all, so the record being in flight proves nothing committed
+ * — the process died, or the unit of work rolled back. An autocommit handler's record is never
+ * reclaimed this way: "died before the write" and "wrote, then died before the settle" are one
+ * row, and re-running the second is the double charge.
  */
 export const SQL_IDEMPOTENCY_RESERVE = `
-insert into x_idempotency (key, id, request_hash, status)
-values ($1, $2, $3, 'in-flight')
+insert into x_idempotency (key, id, request_hash, status, tx_bound)
+values ($1, $2, $3, 'in-flight', $5)
 on conflict (key) do update
    set id           = excluded.id,
        request_hash = excluded.request_hash,
        status       = 'in-flight',
        value        = null,
        failure      = null,
+       redacted     = false,
+       tx_bound     = excluded.tx_bound,
        created_at   = now()
  where x_idempotency.created_at < now() - make_interval(secs => $4::double precision)
-returning key, id, request_hash, status, value, failure,
+    or (x_idempotency.status = 'in-flight'
+        and x_idempotency.tx_bound
+        and x_idempotency.created_at < now() - make_interval(secs => $6::double precision))
+returning key, id, request_hash, status, value, failure, redacted,
           (extract(epoch from created_at) * 1000)::bigint as created_at
 `;
 
 export const SQL_IDEMPOTENCY_GET = `
-select key, id, request_hash, status, value, failure,
+select key, id, request_hash, status, value, failure, redacted,
        (extract(epoch from created_at) * 1000)::bigint as created_at
   from x_idempotency
  where key = $1
@@ -95,13 +96,15 @@ select key, id, request_hash, status, value, failure,
  * the refusal observable: an update matching no row is indistinguishable from one that matched.
  */
 export const SQL_IDEMPOTENCY_SETTLE = `
-update x_idempotency set status = 'settled', value = $2::jsonb, failure = null
+update x_idempotency set status = 'settled', value = $2::jsonb, failure = null,
+       redacted = $4::boolean
  where key = $1 and id = $3::uuid and status = 'in-flight'
 returning key
 `;
 
 export const SQL_IDEMPOTENCY_FAIL = `
-update x_idempotency set status = 'failed', value = null, failure = $2::jsonb
+update x_idempotency set status = 'failed', value = null, failure = $2::jsonb,
+       redacted = false
  where key = $1 and id = $3::uuid and status = 'in-flight'
 returning key
 `;
@@ -119,13 +122,32 @@ interface IdempotencyRow {
   readonly status: string;
   readonly value: unknown;
   readonly failure: unknown;
+  /** Absent on a row read by a statement that predates the column — read as `false`. */
+  readonly redacted?: boolean | undefined;
   /** `bigint`, which every Postgres client hands back as a string. */
   readonly created_at: number | string;
 }
 
 export interface PostgresIdempotencyStoreOptions {
   readonly executor: PgExecutor;
+  /**
+   * The client transactions on THIS database are opened on — `baseClient` from `@ultimat3/db` for
+   * the store the boot installs. Compared by identity with an open transaction's `origin`: the
+   * settle rides a transaction on this database and no other. One opened elsewhere
+   * (`withTransaction(fn, { client: shard })`) has no `x_idempotency` to settle in, so the record
+   * is settled on the pool, exactly as an autocommit handler's is. REQUIRED: a store that could
+   * not tell would send the settle to whichever database the handler happened to be writing.
+   */
+  readonly origin: () => object;
   readonly windowMs?: number | undefined;
+  /**
+   * The request deadline in milliseconds, read at every reservation: how long an in-flight record
+   * whose settlement rides a transaction is kept before a retry may take the key. REQUIRED and a
+   * function — the deadline is the app's (`requestTimeoutMs`), declared after this store is built,
+   * and a number restated here would silently disagree with it. `0` is "no deadline": nothing is
+   * reclaimed before the window. Never applies to an autocommit handler's record.
+   */
+  readonly reclaimAfterMs: () => number;
   /**
    * Injectable, exactly as `MemoryIdempotencyStoreOptions.now` is. The two stores are one seam and
    * a caller must be able to drive either from the same clock; a hardcoded `Date.now()` here made
@@ -148,7 +170,7 @@ export interface PostgresIdempotencyStore extends IdempotencyStore {
 /**
  * **The boot installs this for you — an app declares the scope and nothing else.**
  * `@ultimat3/cli`'s `startServices` builds a `PgExecutor` from the client it already resolved and
- * calls `setIdempotencyStore(postgresIdempotencyStore({ executor }))` before `loadApp`, so the
+ * calls `setIdempotencyStore(postgresIdempotencyStore({ executor, origin, reclaimAfterMs }))` before `loadApp`, so the
  * store is in place by the time `registerAction` evaluates a declaration against it. All an app
  * owes is the one line `x new` scaffolds into `apps/web/server.ts`:
  *
@@ -165,6 +187,8 @@ export interface PostgresIdempotencyStore extends IdempotencyStore {
  * setIdempotencyStore(
  *   postgresIdempotencyStore({
  *     executor: { query: (text, values) => client.query({ text, values }) },
+ *     origin: () => client,
+ *     reclaimAfterMs: requestDeadlineMs, // the app's `requestTimeoutMs`, from '@ultimat3/action'
  *   }),
  * );
  * ```
@@ -181,7 +205,18 @@ export function postgresIdempotencyStore(
     1,
   );
   const windowSecs = windowMs / 1000;
+  // Screened on every read, like the window above: the value is the app's and arrives late. Never
+  // past the window, which already frees the record — and `0` means exactly that.
+  const reclaimSecs = (): number => {
+    const ms = finiteCount('postgresIdempotencyStore', 'reclaimAfterMs', options.reclaimAfterMs());
+    return (ms === 0 ? windowMs : Math.min(ms, windowMs)) / 1000;
+  };
   const exec = options.executor;
+  /** The executor of a transaction open on THIS database, or `undefined` — the pool settles. */
+  const boundTx = (): PgExecutor | undefined => {
+    const tx = liveTransaction();
+    return tx !== undefined && tx.origin === options.origin() ? tx.executor : undefined;
+  };
   const now = options.now ?? ((): number => Date.now());
 
   const fetch = async (key: string): Promise<IdempotencyRecord | undefined> => {
@@ -192,6 +227,7 @@ export function postgresIdempotencyStore(
 
   return {
     scope: 'shared',
+    keepsRedaction: true,
     windowMs,
 
     async reserve(key, requestHash): Promise<IdempotencyReservation> {
@@ -199,11 +235,16 @@ export function postgresIdempotencyStore(
       // back empty is a concurrent `release`/`purgeExpired` deleting the row between them, and a
       // caller losing that race twice is a store nobody should keep retrying against.
       for (let attempt = 0; attempt < 3; attempt += 1) {
+        // On the POOL, never the open transaction: a duplicate has to see the reservation now,
+        // and one that rolled back with the handler would let both attempts run. What rides the
+        // transaction is the SETTLE — and the row says so, which is what makes it reclaimable.
         const claimed = await exec.query<IdempotencyRow>(SQL_IDEMPOTENCY_RESERVE, [
           key,
-          uuid(),
+          uuidV7(),
           requestHash,
           windowSecs,
+          boundTx() !== undefined,
+          reclaimSecs(),
         ]);
         const row = claimed[0];
         if (row !== undefined) return { record: toRecord(row), created: true };
@@ -214,7 +255,7 @@ export function postgresIdempotencyStore(
       // that matters, so this is the honest answer: the caller sees the in-flight refusal.
       return {
         record: {
-          id: uuid(),
+          id: uuidV7(),
           key,
           requestHash,
           status: 'in-flight',
@@ -225,15 +266,25 @@ export function postgresIdempotencyStore(
       };
     },
 
-    async settle(key, value, reservationId): Promise<void> {
-      const rows = await exec.query(SQL_IDEMPOTENCY_SETTLE, [
-        key,
-        JSON.stringify(value ?? null),
-        reservationId,
-      ]);
-      fenced(rows, key, reservationId, 'settle');
+    // `value` is the resting copy `withIdempotency` redacted; `redacted` is kept beside it so the
+    // replay is refused by a column, never by searching the stored JSON for a marker string.
+    async settle(key, value, reservationId, redacted): Promise<void> {
+      const params = [key, JSON.stringify(value ?? null), reservationId, redacted];
+      const tx = boundTx();
+      if (tx === undefined) {
+        fenced(await exec.query(SQL_IDEMPOTENCY_SETTLE, params), key, reservationId, 'settle');
+        return;
+      }
+      // On the handler's OWN connection: the record is settled by the same COMMIT that makes the
+      // write durable, so a rollback leaves it in flight instead of replaying a success for rows
+      // that were never stored. And a settle that matches nothing here is THROWN, not logged —
+      // the key was taken over, nothing has committed yet, and the throw is what rolls it back.
+      const rows = await tx.query(SQL_IDEMPOTENCY_SETTLE, params);
+      if (rows.length === 0) throw new IdempotencyReservationLostError(key);
     },
 
+    // On the pool, whatever is open: the transaction this failure came out of is about to roll
+    // back, and the record of it has to outlive that.
     async fail(key, failure: IdempotencyFailure, reservationId): Promise<void> {
       const rows = await exec.query(SQL_IDEMPOTENCY_FAIL, [
         key,
@@ -260,7 +311,7 @@ export function postgresIdempotencyStore(
 }
 
 /**
- * Logged, never thrown. A settlement lands after the handler has committed, so raising here would
+ * Logged, never thrown — the AUTOCOMMIT path. A settlement lands after the handler has committed, so raising here would
  * turn a durable write into the caller's error — the rule `withIdempotency` already follows for a
  * store that refuses. An operator still has to see it: a fenced settle means this attempt's record
  * belongs to another reservation, and the value this attempt produced is stored nowhere.
@@ -297,6 +348,7 @@ function toRecord(row: IdempotencyRow): IdempotencyRecord {
     status: row.status,
     value: row.value,
     ...(failure === undefined ? {} : { failure }),
+    ...(row.redacted === true ? { redacted: true } : {}),
     createdAt: Number(row.created_at),
   };
 }

package/src/idempotency-redact.ts

@@ -0,0 +1,140 @@
+/**
+ * One job: the copy of an idempotent answer that may be kept AT REST — every value under a key
+ * core's `isRedactedKey` names, every `Secret` box, and everything the walk cannot vouch for
+ * replaced by `[redacted]`. The rule is core's table, the one `audit-input.ts` and the logger ask.
+ */
+import { isRedactedKey, isSecret, REDACTED } from '@ultimat3/core';
+
+/**
+ * How deep the walk inspects. Past it the subtree is REDACTED, never kept: what was not looked at
+ * cannot be shown to hold no credential, and the record of it outlives the request by a day. An
+ * output schema deep enough to reach this is a recursive one, and its replay is refused rather
+ * than served with a credential in it.
+ */
+export const IDEMPOTENCY_REDACT_MAX_DEPTH = 32;
+
+export interface RestingAnswer {
+  /** What the store may write down. The ORIGINAL reference when nothing was redacted. */
+  readonly value: unknown;
+  /** True when anything was replaced — the record's flag, so a replay never scans for a string. */
+  readonly redacted: boolean;
+}
+
+interface WalkState {
+  redacted: boolean;
+}
+
+/**
+ * The answer as it may rest. Plain data — objects whose prototype is `Object.prototype` or
+ * `null`, arrays, `Date`, primitives — with no redacted key comes back as the SAME reference, so
+ * the common case stores and replays exactly what it did before.
+ *
+ * **Fail closed on everything else.** The Postgres store writes `JSON.stringify(value)`, which
+ * runs app code this walk never saw: a `toJSON` (on a class, a plain object, an array, even a
+ * function) may return `{ apiKey }`, and a getter read a second time may return something else.
+ * So a value with a callable `toJSON`, a `Map`, a `Set`, a class instance or a `Date` subclass is
+ * `[redacted]` and the record flagged — its replay is refused, which is the honest answer for an
+ * answer this walk could not judge. An own getter is read ONCE and the subtree copied, so the
+ * serializer reads the value that was judged, not a fresh one. `toJSON` is never called. A CYCLE
+ * is cut the same way — its back-reference becomes `[redacted]` — so both stores keep one
+ * serializable copy; a value repeated as siblings is not a cycle and is kept.
+ */
+export function restingAnswer(value: unknown): RestingAnswer {
+  const state: WalkState = { redacted: false };
+  const out = walk(value, 0, new Set(), state);
+  return { value: out, redacted: state.redacted };
+}
+
+function redact(state: WalkState): string {
+  state.redacted = true;
+  return REDACTED;
+}
+
+/** `JSON.stringify` asks for `toJSON` on any object — a function included. */
+function hasToJson(value: object): boolean {
+  return typeof (value as { toJSON?: unknown }).toJSON === 'function';
+}
+
+/** A `Date` whose `toJSON` is the built-in one: its own prototype, no own override. */
+function isPlainDate(value: object): boolean {
+  return Object.getPrototypeOf(value) === Date.prototype && !Object.hasOwn(value, 'toJSON');
+}
+
+function isPlainObject(value: object): boolean {
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function walk(value: unknown, depth: number, ancestors: Set<object>, state: WalkState): unknown {
+  if (typeof value === 'function') return hasToJson(value) ? redact(state) : value;
+  if (typeof value !== 'object' || value === null) return value;
+  if (isSecret(value)) return redact(state);
+  if (isPlainDate(value)) return value;
+  // A back-reference fails closed: kept, `JSON.stringify` throws in the Postgres store after the
+  // handler committed, while the memory store would accept it — two answers for one record.
+  if (ancestors.has(value)) return redact(state);
+  const array = Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+  if (hasToJson(value) || !(array || isPlainObject(value))) return redact(state);
+  if (depth >= IDEMPOTENCY_REDACT_MAX_DEPTH) return redact(state);
+  ancestors.add(value);
+  try {
+    return array
+      ? walkArray(value as readonly unknown[], depth, ancestors, state)
+      : walkObject(value, depth, ancestors, state);
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+/**
+ * One read of an own property: a data property's value, or its getter called exactly once.
+ * `copy` says the subtree must be copied for the read to be the one the serializer sees.
+ */
+function readOnce(target: object, key: string | number): { value: unknown; copy: boolean } {
+  const descriptor = Object.getOwnPropertyDescriptor(target, key);
+  if (descriptor === undefined) return { value: undefined, copy: false };
+  if (descriptor.get !== undefined) return { value: descriptor.get.call(target), copy: true };
+  return { value: descriptor.value, copy: false };
+}
+
+function walkArray(
+  value: readonly unknown[],
+  depth: number,
+  ancestors: Set<object>,
+  state: WalkState,
+): unknown {
+  let copy: unknown[] | undefined;
+  // Indexed, not `forEach`: a hole is visited (as `undefined`) and kept in its place.
+  for (let index = 0; index < value.length; index += 1) {
+    const read = readOnce(value, index);
+    const next = walk(read.value, depth + 1, ancestors, state);
+    if (read.copy || next !== read.value) copy ??= value.slice(0, index);
+    copy?.push(next);
+  }
+  return copy ?? value;
+}
+
+function walkObject(
+  value: object,
+  depth: number,
+  ancestors: Set<object>,
+  state: WalkState,
+): unknown {
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  // OWN enumerable string keys: what `JSON.stringify` writes and what the Postgres store keeps.
+  for (const key of Object.keys(value)) {
+    const read = readOnce(value, key);
+    const item = read.value;
+    // The key decides before the value is walked, so a credential under a redacted name is never
+    // read further. `null` and `undefined` under one are KEPT: they hold no credential, and
+    // redacting them would refuse the replay of a `{ resetToken: null }` that never carried one.
+    const next =
+      item !== undefined && item !== null && isRedactedKey(key)
+        ? redact(state)
+        : walk(item, depth + 1, ancestors, state);
+    if (read.copy || next !== item) changed = true;
+    out[key] = next;
+  }
+  return changed ? out : value;
+}