@ultimat3/action 22.15.0 → 24.0.0

package/src/define-api.ts

@@ -50,16 +50,28 @@ type Registered<TModule, TKind extends string> = {
 };
 
 /**
- * Intersect a tuple of module namespaces. `{ createPost } & { inviteMember }` is the map the
+ * Intersect a list of module namespaces. `{ createPost } & { inviteMember }` is the map the
  * typed client indexes, so `rpc<Api['actions']>()` knows every action without a codegen step.
+ *
+ * Never by recursion over the tuple. `Registered<Head> & Merge<Rest>` is not a tail call, so the
+ * compiler spent one level of its instantiation depth per MODULE and answered TS2589 at the 48th
+ * entry of one list — whatever the number of actions inside them (measured: 30 modules of 10 pass,
+ * 48 modules of 1 fail). The list is read as a union and intersected in one step, so the depth is
+ * constant and `client-scale-pins.ts` holds it there.
  */
 type Merge<TModules, TKind extends string> = [TModules] extends [undefined]
   ? EmptyModule
-  : TModules extends readonly [infer THead, ...infer TRest]
-    ? Registered<THead, TKind> & Merge<TRest, TKind>
-    : TModules extends readonly []
-      ? EmptyModule
-      : Registered<TModules, TKind>;
+  : TModules extends readonly unknown[]
+    ? MergeAll<TModules[number], TKind>
+    : Registered<TModules, TKind>;
+
+/** An empty list has no members to intersect — and `unknown` is not a map `rpc` accepts. */
+type MergeAll<TModule, TKind extends string> = [TModule] extends [never]
+  ? EmptyModule
+  : Intersect<TModule extends unknown ? (map: Registered<TModule, TKind>) => void : never>;
+
+/** A union of one-parameter functions infers that parameter as the intersection of them all. */
+type Intersect<TFns> = [TFns] extends [(map: infer TMap) => void] ? TMap : never;
 
 type EmptyModule = Readonly<Record<never, never>>;
 

package/src/errors-idempotency.ts

@@ -1,5 +1,5 @@
 /**
- * The five idempotency failures, split out of `errors.ts` at its line ceiling. One subclass per
+ * The idempotency failures, split out of `errors.ts` at its line ceiling. One subclass per
  * stable code, exactly as there — the codes and their titles stay in `errors.ts`'s one
  * `registerErrorCodes` call, because a second registration is how two modules end up deciding a
  * title by load order.
@@ -77,7 +77,7 @@ export class IdempotencyNotSharedError extends UltimateError {
       // positional form is `unsafe`), so that line compiled and would have thrown on the first
       // reservation. The framework's own boot already installs this store; a host booting the
       // framework itself wraps the client it opened.
-      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) } })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
+      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) }, origin: () => client, reclaimAfterMs: requestDeadlineMs })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
       meta: { storeScope: storeScope ?? null },
     });
   }
@@ -138,3 +138,37 @@ export class IdempotencyStatusUnknownError extends UltimateError {
     });
   }
 }
+
+/**
+ * A mutator declared without `idempotent: true`. Refused at declaration: the client replays a
+ * mutator's write under one `Idempotency-Key` (a retry, an offline queue draining after a lost
+ * response), and `toRoute` reads that key only for an idempotent action — so the alternative is a
+ * toggle that flips back, with nothing in any log to say the handler ran twice.
+ */
+export class MutatorNotIdempotentError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_MUTATOR_NOT_IDEMPOTENT',
+      cause:
+        'a mutator is declared without idempotent: true, so a replay of its write under the same Idempotency-Key would run the server half a second time',
+      fix: 'add `idempotent: true` to the mutator definition',
+    });
+  }
+}
+
+/**
+ * A settlement inside the handler's transaction matched no record: the attempt ran past the
+ * request deadline, a retry reclaimed the key, and this one no longer owns it. THROWN, where the
+ * autocommit path only logs — nothing here has committed, so the throw rolls this attempt's
+ * writes back and the retry's are the only ones stored.
+ */
+export class IdempotencyReservationLostError extends UltimateError {
+  constructor(key: string) {
+    super({
+      code: 'X_IDEMPOTENCY_RESERVATION_LOST',
+      cause: `idempotency key "${key}" was reclaimed by a retry while this attempt was still in flight past the request deadline, so its transaction is rolled back rather than committed beside the retry's`,
+      fix: 'resend this request with the same Idempotency-Key — the attempt that took the key over answers it, and this one was rolled back',
+      meta: { key },
+    });
+  }
+}

package/src/errors.ts

@@ -1,7 +1,7 @@
 /**
  * Every failure @ultimat3/action can produce, one subclass per stable code so
  * callers `instanceof` a specific failure instead of string-matching a message.
- * The idempotency five live in `errors-idempotency.ts` — this file reached the line ceiling —
+ * The idempotency failures live in `errors-idempotency.ts` — this file reached the line ceiling —
  * and are re-exported here, so `./errors` stays the one import path for all of them.
  */
 import {
@@ -17,7 +17,7 @@ import {
 import type { SurfaceDenial } from '@ultimat3/policy';
 import type { ValidationIssue } from '@ultimat3/schema';
 
-// Re-exported, not re-declared: the five idempotency failures moved to their own file when this
+// 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`.
 export type { IdempotencyConflictReason, IdempotencyKeyProblem } from './errors-idempotency';
 export {
@@ -25,7 +25,9 @@ export {
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
   IdempotencyReplayedFailureError,
+  IdempotencyReservationLostError,
   IdempotencyStatusUnknownError,
+  MutatorNotIdempotentError,
 } from './errors-idempotency';
 
 /**
@@ -60,6 +62,9 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   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"

package/src/idempotency-memory.ts

@@ -4,6 +4,7 @@
  * Shaped after `@ultimat3/http`'s `memoryRateLimitStore`, including the deliberate eviction order.
  */
 import { finiteCount, uuid } 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,6 +37,24 @@ 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 {
@@ -43,6 +64,8 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
   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;
 
@@ -65,6 +88,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,7 +101,11 @@ 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 = {
@@ -89,10 +117,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
@@ -104,9 +150,29 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
    */
   settle(key: string, value: unknown, reservationId: string): Promise<void> {
     const existing = this.#owned(key, reservationId);
-    if (existing !== undefined) {
-      this.#records.set(key, { ...existing, status: 'settled', value });
+    const tx = liveTransaction();
+    if (tx === undefined) {
+      if (existing !== undefined) this.#records.set(key, { ...existing, status: 'settled', value });
+      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, { ...existing, status: 'settled', value });
+      }
+    });
     return Promise.resolve();
   }
 

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 type { PgExecutor } from '@ultimat3/core';
 import { finiteCount, logger, uuid } from '@ultimat3/core';
-import { IdempotencyStatusUnknownError } from './errors';
+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,25 +37,37 @@ 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;
 `;
 
 /**
- * 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,
+       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,
           (extract(epoch from created_at) * 1000)::bigint as created_at
 `;
@@ -125,7 +123,24 @@ interface IdempotencyRow {
 
 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 +163,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 +180,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 +198,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> => {
@@ -199,11 +227,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(),
           requestHash,
           windowSecs,
+          boundTx() !== undefined,
+          reclaimSecs(),
         ]);
         const row = claimed[0];
         if (row !== undefined) return { record: toRecord(row), created: true };
@@ -226,14 +259,22 @@ 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');
+      const params = [key, JSON.stringify(value ?? null), reservationId];
+      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 +301,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.

package/src/idempotency.ts

@@ -226,6 +226,10 @@ export async function withIdempotency<T>(
   //
   // `record.id` is THIS reservation's, so a straggler from an attempt whose window has since
   // lapsed cannot land on the replacement that reclaimed the key.
+  //
+  // Inside a transaction the shared store settles on that transaction's connection, so "settled"
+  // and "the write is durable" are one COMMIT — and a settle that lost its reservation THROWS
+  // (`X_IDEMPOTENCY_RESERVATION_LOST`), which is the rollback of an attempt a retry replaced.
   await store.settle(key, value, record.id);
   return { value, replayed: false };
 }

package/src/index.ts

@@ -19,12 +19,18 @@
  * before. `isSuperseded` is core's too: reading a fenced answer is the point of installing a
  * flight, and it should not cost a second import.
  */
+/**
+ * The SHARED store, and the only one an app running more than one replica may install. The
+ * statements are exported beside it because the table is applied the way `SQL_JOBS_TABLE` is —
+ * by `x db up` in development and by the release-phase `ROLE=migrate` in production.
+ */
 export type {
   ClientFlight,
   ClientFlightOptions,
   ClientRetry,
   FlightKeyOptions,
   FlightPlan,
+  PgExecutor,
   WireAnswer,
 } from '@ultimat3/core';
 export {
@@ -130,8 +136,10 @@ export {
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
   IdempotencyReplayedFailureError,
+  IdempotencyReservationLostError,
   IdempotencyStatusUnknownError,
   InputInvalidError,
+  MutatorNotIdempotentError,
   OutputInvalidError,
   RemoteActionError,
   RpcFailedError,
@@ -189,13 +197,7 @@ export {
   DEFAULT_MAX_IDEMPOTENCY_KEYS,
   MemoryIdempotencyStore,
 } from './idempotency-memory';
-/**
- * The SHARED store, and the only one an app running more than one replica may install. The
- * statements are exported beside it because the table is applied the way `SQL_JOBS_TABLE` is —
- * by `x db up` in development and by the release-phase `ROLE=migrate` in production.
- */
 export type {
-  PgExecutor,
   PostgresIdempotencyStore,
   PostgresIdempotencyStoreOptions,
 } from './idempotency-postgres';
@@ -214,7 +216,7 @@ export { actionName, invoke } from './invoke';
 export type { ActionJobHandle } from './job-handle';
 export { toJobHandle } from './job-handle';
 export type { JsonSchemaObject } from './json-schema';
-export { jsonSchemaOf, mcpSchemaOf } from './json-schema';
+export { jsonSchemaOf } from './json-schema';
 export type { McpInvokeOptions, McpToolDescriptor } from './mcp-tool';
 export { isExposed, toMcpTool, toMcpTools } from './mcp-tool';
 export type {
@@ -237,6 +239,11 @@ export {
   completeOpenApi,
   mountOpenApi,
 } from './openapi-complete';
+/**
+ * `@ultimat3/http`'s `hooks.explainMiss` for the action surface: a POST to an action's path under
+ * a `pathStyle` this app does not serve answers `X_CONTRACT_DRIFT` naming the style it does.
+ */
+export { explainActionPathMiss } from './path-style-miss';
 export type { ActionPolicy, PolicySubject, Surface } from './policy-gate';
 /**
  * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.
@@ -262,6 +269,7 @@ export {
   registerActions,
   resetRegistry,
 } from './registry';
+export { requestDeadlineMs } from './request-deadline';
 /**
  * A mutator FACTORY, never a ninth primitive: `transition()` returns a `mutator`, so a move through
  * a state machine inherits the route, the OpenAPI operation, the typed client, the MCP tool, the job

package/src/invoke.ts

@@ -268,8 +268,9 @@ async function perform(
   }
   // Only for a run that actually happened, and only through the gate. A replay ran no handler
   // and changed nothing the first call had not already busted — re-busting per retry re-purges
-  // the CDN and re-queues ISR for a write nobody made. And the bust is post-commit either way,
-  // so `bustAfterCommit` swallowing its own failure is what keeps a dead cache from turning a
+  // the CDN and re-queues ISR for a write nobody made. And the bust is post-COMMIT either way —
+  // invoked inside a transaction, it waits for the root commit and is dropped by a rollback — so
+  // `bustAfterCommit` swallowing its own failure is what keeps a dead cache from turning a
   // durable write into a failed action.
   if (wrote && def.cache !== undefined) await bustAfterCommit(name, def.cache.invalidates);
   return value;

package/src/json-schema.ts

@@ -1,10 +1,10 @@
 /**
- * Standard Schema -> JSON Schema, normalized to a plain record. OpenAPI, MCP
- * descriptors and the manifest all need the same object, produced the same way.
+ * Standard Schema -> JSON Schema, normalized to a plain record, for OpenAPI and the manifest. An
+ * MCP tool's schema is `@ultimat3/schema`'s `toWireSchema` — the one `tools/list` serves.
  */
 
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import { SchemaUnsupportedError, toJsonSchema, toMcpInputSchema } from '@ultimat3/schema';
+import { SchemaUnsupportedError, toJsonSchema } from '@ultimat3/schema';
 import { isJsonObject, stableStringify } from './stable';
 
 export type JsonSchemaObject = Record<string, unknown>;
@@ -23,13 +23,8 @@ export function jsonSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
   return normalizeJsonSchema(() => toJsonSchema(schema));
 }
 
-/** Draft-07, no `$schema` — the exact shape an MCP `tools/list` entry needs. */
-export function mcpSchemaOf(schema: StandardSchemaV1): JsonSchemaObject {
-  return normalizeJsonSchema(() => toMcpInputSchema(schema));
-}
-
 /**
- * The narrowing both projections share, and the refusal it earns: a converter that answered with
+ * The narrowing `jsonSchemaOf` applies, and the refusal it earns: a converter that answered with
  * something that is not a JSON object is the same failure by a quieter route, so it gets the same
  * shipped code rather than a permissive node. Exported for its own test and nothing else — it is
  * absent from `src/index.ts`, exactly as `sortSchema` is.

package/src/mcp-tool.ts

@@ -5,9 +5,10 @@
  */
 import type { Ctx } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
+import { toWireOutputSchema, toWireSchema } from '@ultimat3/schema';
 import type { AnyAction } from './action';
 import { actionName, defOf, invoke } from './invoke';
-import { type JsonSchemaObject, mcpSchemaOf, sortSchema } from './json-schema';
+import { type JsonSchemaObject, sortSchema } from './json-schema';
 import type { ActionPolicy } from './policy-gate';
 import { listActions } from './registry';
 
@@ -29,8 +30,14 @@ export interface McpToolDescriptor {
    * is what makes "an MCP call cannot reach a different authz path" checkable.
    */
   readonly policy: ActionPolicy;
+  /**
+   * What `@ultimat3/mcp`'s `tools/list` serves for this action — `@ultimat3/schema`'s wire subset,
+   * key-sorted — minus the reserved `idempotencyKey` argument an idempotent action's tool adds,
+   * which `invoke` here takes as an option instead.
+   */
   readonly inputSchema: JsonSchemaObject;
-  readonly outputSchema: JsonSchemaObject;
+  /** The served `outputSchema`: structure only, and absent when `output` has no object root. */
+  readonly outputSchema?: JsonSchemaObject;
   invoke(input: unknown, options?: McpInvokeOptions): Promise<unknown>;
 }
 
@@ -47,13 +54,14 @@ export interface McpInvokeOptions {
 export function toMcpTool(target: AnyAction): McpToolDescriptor {
   const name = actionName(target);
   const def = defOf(target);
+  const output = toWireOutputSchema(def.output);
   return {
     name,
     description: def.mcp?.description ?? name,
     action: name,
     policy: def.policy,
-    inputSchema: sortSchema(mcpSchemaOf(def.input)),
-    outputSchema: sortSchema(mcpSchemaOf(def.output)),
+    inputSchema: sortSchema({ ...toWireSchema(def.input) }),
+    ...(output === undefined ? {} : { outputSchema: sortSchema({ ...output }) }),
     invoke: (input, options = {}) =>
       invoke(target, input, {
         surface: 'mcp',