@ultimat3/action 24.0.0 → 25.0.0

package/src/errors.ts

@@ -9,13 +9,18 @@ import {
   deniedCallerFix,
   ERROR_DOCS_URL,
   hasErrorCode,
-  registerErrorCodes,
   renderFixShellArg,
   retryForStatus,
   UltimateError,
+  withStatedDelay,
 } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
 import type { ValidationIssue } from '@ultimat3/schema';
+// The titles are `error-titles.ts`, imported bare: this module is then side-effect-free and the
+// array does not list it, so a chunk keeps only the classes it constructs, and a chunk that
+// constructs one still registers every title first — anchored by use. The barrel imports it bare
+// too, for the browser that rebuilds a SERVER's refusal by code and constructs nothing from here.
+import './error-titles';
 
 // Re-exported, not re-declared: the idempotency failures moved to their own file when this
 // one reached the line ceiling, and every importer still reads them from `./errors`.
@@ -27,52 +32,10 @@ export {
   IdempotencyReplayedFailureError,
   IdempotencyReservationLostError,
   IdempotencyStatusUnknownError,
+  IdempotentReplayRedactedError,
   MutatorNotIdempotentError,
 } from './errors-idempotency';
 
-/**
- * Titles for the framework-wide code table — every one of them owned by this package.
- * `X_INPUT_INVALID` and `X_RPC_FAILED` are action's: an action is where an input schema is
- * enforced and where the typed client speaks, and `@ultimat3/query` only throws them.
- * Authz codes are absent on purpose — `ActionDeniedError` re-uses the policy decision's code.
- */
-const OWNED_TITLES: Readonly<Record<string, string>> = {
-  X_ACTION_DUPLICATE: 'two actions are registered under one name',
-  X_AUDIT_SINK_FAILED: 'an audited action ran and the audit sink refused its record',
-  X_AUDIT_SINK_MISSING: 'an action declares audit: true and no audit sink is installed',
-  X_ACTION_DEPRECATION_INVALID: 'an action declares a deprecation whose dates cannot be rendered',
-  X_ACTION_PATH_DUPLICATE: 'two actions derive one HTTP path',
-  X_ACTION_FOREIGN: 'a value that is not an action was projected as one',
-  X_ACTION_POLICY_MISSING: 'an action was registered without a policy',
-  X_ACTION_UNREGISTERED: 'an action was projected before it was registered',
-  X_CONTRACT_DRIFT: 'client and server disagree about the contract',
-  X_IDEMPOTENCY_CONFLICT: 'idempotency key reused with a different payload or still in flight',
-  X_IDEMPOTENCY_KEY_INVALID: 'an Idempotency-Key was sent that cannot identify one request',
-  X_IDEMPOTENCY_NOT_SHARED:
-    'idempotency is declared fleet-wide and the installed store is per-process',
-  X_IDEMPOTENCY_REPLAYED_FAILURE:
-    'a retried Idempotency-Key replays a first attempt that failed after it may have committed',
-  X_IDEMPOTENCY_STATUS_UNKNOWN: 'an idempotency record holds a status this build cannot read',
-  X_INPUT_INVALID: 'input failed schema validation',
-  X_MUTATOR_CLOCK_MISSING:
-    "a mutator declares conflict: 'last-write-wins' and its entity has no number clock column",
-  X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
-  X_RPC_FAILED: 'an RPC call failed without a problem+json body',
-  X_ACTION_HTTP_PATH_INVALID: "an action's pinned http.path is not a static lowercase path",
-  X_ACTION_PATH_STYLE_INVALID: "defineApi's http.pathStyle is not a known style",
-  X_OPENAPI_CONFIG_INVALID: "defineApi's openapi block cannot produce a valid document",
-  X_ACTION_PATH_DERIVED_EARLY: 'a path was derived before pathStyle changed',
-  X_MUTATOR_NOT_IDEMPOTENT: 'a mutator is declared without idempotent: true',
-  X_IDEMPOTENCY_RESERVATION_LOST:
-    "an idempotent action's reservation was taken over before its transaction could settle it",
-};
-
-// One unconditional call: a presence guard would turn "another package claims one of these codes"
-// from an X_ERROR_CODE_DUPLICATE at import into whichever module loaded first deciding the title.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(OWNED_TITLES).map(([code, title]) => [code, { title }])),
-);
-
 /** Thrown when a projection needs a name the action does not have yet. */
 export class ActionUnregisteredError extends UltimateError {
   constructor() {
@@ -129,7 +92,7 @@ export function denialReason(denial: SurfaceDenial): string {
 }
 
 /**
- * An authz denial, thrown by `guard()`. The code and reason come from the policy
+ * An authz denial, thrown by `guardAction()`. The code and reason come from the policy
  * decision — this package never invents an authz code — and the surface-shaped
  * denial rides along for projections that render it themselves.
  */
@@ -224,7 +187,7 @@ export class InputInvalidError extends UltimateError {
     super({
       code: 'X_INPUT_INVALID',
       cause: `input for ${subject} "${name}" failed validation: ${detail}`,
-      fix: `x actions describe ${name} --json  # prints the expected input schema`,
+      fix: `x actions describe ${renderFixShellArg(name, '<action-name>')} --json  # prints the expected input schema`,
       // A remote caller holds the published schema — the MCP `inputSchema`, the OpenAPI request
       // body — and cannot run `x actions describe`.
       callerFix:
@@ -245,7 +208,7 @@ export class OutputInvalidError extends UltimateError {
     super({
       code: 'X_OUTPUT_INVALID',
       cause: `action "${name}" returned a value its output schema rejects: ${detail}`,
-      fix: `x actions describe ${name} --json  # compare the handler's return against \`output:\``,
+      fix: `x actions describe ${renderFixShellArg(name, '<action-name>')} --json  # compare the handler's return against \`output:\``,
     });
   }
 }
@@ -294,6 +257,13 @@ export interface RemoteFailure {
    * so an island reads `error.meta.sessionId` where it used to run a regex over `cause`.
    */
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * The document's `title`, already read by core's `remoteTitleOf` — used only when this bundle
+   * registered no title for `code`, which is every http refusal in an island.
+   */
+  readonly title?: string | undefined;
+  /** The delay the answer's `Retry-After` named, in seconds (core's `retryAfterSecondsOf`). */
+  readonly retryAfterSeconds?: number | undefined;
 }
 
 /** A link, not a string the server happened to put in a field the overlay renders as an href. */
@@ -346,19 +316,27 @@ export class RemoteActionError extends UltimateError {
       // this build may never have heard of. `UltimateError` otherwise fills `retry` from
       // `retryFor(code)`, which fails closed — so a 503 out of a typed call announced itself as
       // `terminal` on the one field the framework promises a client never has to infer.
-      retry: retryForStatus(failure.code, failure.status),
-      meta: {
-        // The server's declared keys FIRST, so the four this class owns win a collision: a server
-        // meta naming `status` would otherwise overwrite the one a report reads the HTTP status
-        // from, and `origin: 'remote'` is what marks the code as one this bundle never declared.
-        ...failure.meta,
-        origin: 'remote',
-        action: failure.action,
-        status: failure.status,
-        // Absent rather than `undefined`: `meta` is rendered into `--json` and the error reporter,
-        // and a null member reads as "the server sent an empty list" rather than "it sent none".
-        ...(failure.issues === undefined ? {} : { issues: failure.issues }),
-      },
+      // A 429 or 503 that stated a delay is `retry-after` whoever registered the code, and the
+      // delay rides on `meta.retryAfterSeconds`, the one key core's `statedDelayMs` reads.
+      retry: retryForStatus(failure.code, failure.status, failure.retryAfterSeconds),
+      remoteTitle: failure.title,
+      // Core's `withStatedDelay`, the rule `problemError` applies too: a `retryAfterSeconds` off the
+      // body is dropped and only the header's is carried — the server never writes one there.
+      meta: withStatedDelay(
+        {
+          // The server's declared keys FIRST, so the four this class owns win a collision: a
+          // server meta naming `status` would otherwise overwrite the one a report reads the HTTP
+          // status from, and `origin: 'remote'` marks the code as one this bundle never declared.
+          ...failure.meta,
+          origin: 'remote',
+          action: failure.action,
+          status: failure.status,
+          // Absent rather than `undefined`: `meta` is rendered into `--json` and the error
+          // reporter, and a null member reads as "the server sent an empty list".
+          ...(failure.issues === undefined ? {} : { issues: failure.issues }),
+        },
+        failure.retryAfterSeconds,
+      ),
     });
     this.status = failure.status;
   }
@@ -375,7 +353,7 @@ export class RpcFailedError extends UltimateError {
     super({
       code: 'X_RPC_FAILED',
       cause: `${name} returned HTTP ${status} without a problem+json body`,
-      fix: `check the gateway in front of the app, then: x actions describe ${name} --json`,
+      fix: `check the gateway in front of the app, then: x actions describe ${renderFixShellArg(name, '<action-name>')} --json`,
       retry: retryForStatus('X_RPC_FAILED', status),
     });
   }
@@ -393,7 +371,7 @@ export class AuditSinkMissingError extends UltimateError {
     super({
       code: 'X_AUDIT_SINK_MISSING',
       cause: `action "${action}" declares \`audit: true\` and no audit sink is installed`,
-      fix: "call setAuditSink(yourSink) from '@ultimat3/action' at boot, before registerActions()",
+      fix: "call setAuditSink(yourSink) from '@ultimat3/core' at boot, before registerActions()",
     });
   }
 }

package/src/facade.ts

@@ -1,9 +1,10 @@
 /**
- * The fluent surface: every projection reachable as a method on the action itself,
- * `publishPost.tool()` rather than `toMcpTool(publishPost)`, and every declared
- * field lifted off `def` so app code never reaches through `.def`. The projection
- * functions stay exported for the framework's own call sites — this file only
- * binds them to the action, it never re-implements one.
+ * The fluent surface: every projection this package owns reachable as a method on the action
+ * itself, `publishPost.openapi()` rather than `toOpenApiOperation(publishPost)`, and every
+ * declared field lifted off `def` so app code never reaches through `.def`. The projection
+ * functions stay exported for the framework's own call sites — this file only binds them to the
+ * action, it never re-implements one. There is no `.tool()`: the MCP tool is `@ultimat3/mcp`'s
+ * one projection (`toolFrom(publishPost)`), a tier this package cannot import.
  */
 
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
@@ -13,7 +14,6 @@ import { contractTestsFor } from './contract-test';
 import { toOpenApiOperation } from './http';
 import { actionName, invoke } from './invoke';
 import { toJobHandle } from './job-handle';
-import { toMcpTool } from './mcp-tool';
 
 /**
  * `self` is a thunk on purpose: the façade is attached while the action is still
@@ -33,7 +33,6 @@ export function facadeFor<TInput extends StandardSchemaV1, TOutput extends Stand
     // the output type is this action's by construction.
     as: (actor, input, options) =>
       invoke(self(), input, { ...options, actor }) as Promise<InferOutput<TOutput>>,
-    tool: () => toMcpTool(self()),
     openapi: () => toOpenApiOperation(self()),
     client: (options) => clientMethodFor(actionName(self()), options, def.http?.path),
     job: () => toJobHandle(self()),

package/src/http-path.ts

@@ -69,7 +69,7 @@ export function setActionPathStyle(next: unknown): ActionPathStyle {
   return style;
 }
 
-/** Test seam, beside `resetRegistry`. */
+/** Test seam, beside `resetActions`. */
 /**
  * Forget which paths were handed out, keeping the style. `@ultimat3/testing` calls it between two
  * test files of one worker (22.7, no `--isolate`): a path an earlier FILE derived is not one this

package/src/http.ts

@@ -6,10 +6,15 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
+import type { Deprecation } from '@ultimat3/core';
 import {
+  IDEMPOTENCY_HEADER,
   isMcpExposed,
   RECORDS_OPENAPI_HEADER,
+  recordDeprecatedCall,
   recordEnvelopeSchema,
+  renderDeprecation,
+  useContext,
   withWriteOrigin,
   writeDigest,
 } from '@ultimat3/core';
@@ -17,10 +22,9 @@ import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
 // `toBucket` is `@ultimat3/http`'s, not this package's: http owns `Bucket` and the limiter maths,
 // and `@ultimat3/query` needs the identical conversion while being the same tier as this one — so
 // a copy here would be a second answer to "what does this limit mean" for the read half.
-import { json, redirect, takeRedirect, toBucket } from '@ultimat3/http';
+import { jsonResponse, publishRateLimit, redirect, takeRedirect, toBucket } from '@ultimat3/http';
+import { admitsAnonymous, policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { ActionRateLimit, AnyAction } from './action';
-import type { Deprecation } from './deprecation';
-import { recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { ActionDeprecationInvalidError } from './errors';
 import { actionPathStyle, servedActionRoute } from './http-path';
 import { actionName, defOf, invoke } from './invoke';
@@ -31,16 +35,7 @@ import {
   schemaRef,
   toOperationId,
 } from './naming';
-import { admitsAnonymous, policyCapability, policyPermissions } from './policy-gate';
 import { carriesRecords, recordResponse } from './record-wire';
-import { IDEMPOTENCY_HEADER } from './wire-headers';
-
-/**
- * Re-exported, never re-declared. The two strings moved to `wire-headers.ts` so `client.ts` can
- * name them without pulling this file's server graph into a browser bundle; every importer of
- * `./http` still reads them from here, which is what kept the move from touching a call site.
- */
-export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './wire-headers';
 
 export const REPLAYED_HEADER = 'x-ultimate-replayed';
 
@@ -90,6 +85,9 @@ function projectRoute(
   // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
   // not a surprise on the first request — the same rule `toBucket` follows for a rate limit.
   const sunsetting = deprecationHeadersFor(name, def.deprecated);
+  // Same rule, for a limit the limiter could not run on: refused at mount (`X_RATE_LIMIT_INVALID`),
+  // never on the first request that tries to spend it.
+  if (def.rateLimit !== undefined) toBucket(name, def.rateLimit);
   const enveloped = carriesRecords(target.output);
 
   const handler = async (req: UltimateRequest): Promise<Response> => {
@@ -121,6 +119,9 @@ function projectRoute(
         onReplay: () => {
           replayed = true;
         },
+        clientAddress: req.ctx.ip,
+        onRateLimit: (decision) =>
+          publishRateLimit(req.ctx, decision, useContext().now().getTime()),
       }),
     );
     // The one thing an action's return value cannot say. `setRedirect()` inside the handler
@@ -134,7 +135,7 @@ function projectRoute(
         ? redirect(to.location, to.status)
         : enveloped
           ? recordResponse(target.output, result)
-          : json(result);
+          : jsonResponse(result);
     if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0');
     return response;
   };
@@ -154,6 +155,9 @@ function projectRoute(
     // stage deciding first would decide from `row: null` — a denial for the row's own
     // author, from an authz system that never saw the row.
     enforcedBy: 'handler',
+    // Which primitive this is, for `@ultimat3/http`'s bucket check: a `rateLimit.buckets.<name>`
+    // named after an action limits nothing since 25.0.0, and is refused rather than ignored.
+    primitive: 'action',
     // `input` stays ABSENT, deliberately, exactly as `@ultimat3/query`'s `toQueryRoute` leaves it.
     // Setting it hands the action's schema to the pipeline's `body` stage, which throws
     // `bodyInvalid` — so this route answered `422 X_BODY_INVALID` for every malformed body while
@@ -167,12 +171,11 @@ function projectRoute(
     // failing a plain `route.ts`'s own schema, where no primitive owns the input.
     cache: { mode: 'no-store', tags: tagKeys(def.cache?.invalidates ?? []) },
     tags: [operationTagOf(target)],
-    // Name AND numbers. The name alone selected a bucket the limiter's table never held, so
-    // `bucketFor` fell through to `default` — 120 burst for an action that declared 5. The
-    // numbers ride along and `withRouteBuckets` registers them at construction.
-    ...(def.rateLimit === undefined
-      ? {}
-      : { rateLimit: name, rateLimitBucket: toBucket(name, def.rateLimit) }),
+    // `invoke` spends the declared bucket for every surface, so the stage spends no caller bucket
+    // for this route — not the action's (that was the second, HTTP-only enforcement point MCP,
+    // the agent tool and `.job()` never reached) and not `default` (a ceiling an action declaring
+    // more than it never had). The tenant allowance is still the stage's.
+    ...(def.rateLimit === undefined ? {} : { rateLimitedBy: 'handler' as const }),
     ...(def.mcp?.description === undefined ? {} : { description: def.mcp.description }),
   };
 
@@ -254,7 +257,7 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
       invalidates: tagKeys(def.cache?.invalidates ?? []),
       // The tool name an agent would call, or `null` when there is no tool. `!== false` here
       // advertised one for every action, so an agent reading the spec asked for a tool the MCP
-      // catalog never listed — `isMcpExposed` is the same answer `toMcpTool` gives. The NAME was
+      // catalog never listed — `isMcpExposed` is the same answer `@ultimat3/mcp` gives. The NAME was
       // the second half of the same defect: `toToolName` published `publish_post` while
       // `@ultimat3/mcp` served `publishPost`, so a spec-reading agent called a tool that does not
       // exist. Verbatim, and never derived — this is a published contract, not a label.

package/src/idempotency-memory.ts

@@ -3,7 +3,7 @@
  * 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,
@@ -60,6 +60,7 @@ interface Flight {
 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;
@@ -74,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,
@@ -109,7 +110,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
       return Promise.resolve({ record: existing, created: false });
     }
     const record: IdempotencyRecord = {
-      id: uuid(),
+      id: uuidV7(),
       key,
       requestHash,
       status: 'in-flight',
@@ -132,7 +133,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     if (record.status !== 'in-flight' || flight === undefined) return false;
     if (!flight.bound || flight.settling) return false;
     const reclaimAfterMs = finiteCount(
-      'MemoryIdempotencyStore',
+      'memoryIdempotencyStore',
       'reclaimAfterMs',
       this.#reclaimAfterMs(),
     );
@@ -148,11 +149,18 @@ 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);
+    // 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, { ...existing, status: 'settled', value });
+      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
@@ -170,7 +178,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
     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, { ...existing, status: 'settled', value });
+        this.#records.set(key, settled(existing));
       }
     });
     return Promise.resolve();
@@ -235,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

@@ -5,7 +5,7 @@
  * Statements are spelled out so an agent can run the exact one it saw in a log.
  */
 import type { PgExecutor } from '@ultimat3/core';
-import { finiteCount, logger, uuid } from '@ultimat3/core';
+import { finiteCount, logger, uuidV7 } from '@ultimat3/core';
 import { IdempotencyReservationLostError, IdempotencyStatusUnknownError } from './errors';
 import type {
   IdempotencyFailure,
@@ -39,6 +39,8 @@ 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;
 `;
 
 /**
@@ -62,18 +64,19 @@ on conflict (key) do update
        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)
     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,
+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
@@ -93,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
 `;
@@ -117,6 +122,8 @@ 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;
 }
@@ -220,6 +227,7 @@ export function postgresIdempotencyStore(
 
   return {
     scope: 'shared',
+    keepsRedaction: true,
     windowMs,
 
     async reserve(key, requestHash): Promise<IdempotencyReservation> {
@@ -232,7 +240,7 @@ export function postgresIdempotencyStore(
         // 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,
@@ -247,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',
@@ -258,8 +266,10 @@ export function postgresIdempotencyStore(
       };
     },
 
-    async settle(key, value, reservationId): Promise<void> {
-      const params = [key, JSON.stringify(value ?? null), reservationId];
+    // `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');
@@ -338,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),
   };
 }