@ultimat3/action 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -4,8 +4,9 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 
 ## Boundary
 
-- May import: `core`, `schema` (t0), `cache`, `i18n`, `time` (t1), `entity`, `policy`, `http` (t2).
+- May import: `core`, `schema` (t0), `cache`, `db`, `i18n`, `time` (t1), `entity`, `policy`, `http` (t2).
   `entity` is a real edge since 21.0.0 (`record-wire.ts` → `hasEntityRows`/`rowsOf`), downward 3→2.
+  `db` is one since 2026-10-02, downward 3→1, through **`tx-scope.ts` only** (`currentTx`).
 - Never import: `query`, `jobs`, `realtime` (sideways), or any tier 4-5 package.
 - Never re-implement authz, validation or caching — call `policy`, `schema`, `cache`.
 
@@ -43,7 +44,9 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `idempotency-postgres.ts` | the SHARED store — one table, one `insert … on conflict` |
 | `deprecation.ts` | `Deprecation` + the RFC 9745/8594 render + the `deprecated_calls_total` counter |
 | `policy-gate.ts` | **the only** runtime edge to `@ultimat3/policy` (`errors.ts` takes `SurfaceDenial` as a type, which erases) |
-| `cache-gate.ts` | the post-commit bust — **the only** file that calls `invalidateTags` |
+| `cache-gate.ts` | the post-COMMIT bust — **the only** file that calls `invalidateTags` |
+| `tx-scope.ts` | the open transaction — **the only** file that imports `@ultimat3/db` (`tx-scope.test.ts`): `openCommitScope` (the bust) and `liveTransaction` (the settle) |
+| `request-deadline.ts` | `requestDeadlineMs` — the app's `requestTimeoutMs`, resolved by http's own `defineHttpConfig` |
 | `audit.ts` | the audit seam: `AuditRecord`, `AuditSink`, the installed-sink store |
 | `audit-memory.ts` | the process default: a bounded ring that DROPS, and counts what it dropped |
 | `audit-postgres.ts` | the DURABLE sink — one append-only `x_audit` table, one insert per record |
@@ -98,6 +101,9 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   unchanged** — an upgrade must not make a committed contract stale by itself.
 - Registration names the action the app exported, in place. Naming an already-named action is the
   only case that twins.
+- **A mutator declares `idempotent: true` or does not exist**: required by `MutatorDef`, and
+  `X_MUTATOR_NOT_IDEMPOTENT` at `mutator()` for anything else. The client replays a mutator's write
+  under one key; `transition()` and `x g mutator` declare it. Never a default.
 - A mutator projects `.local`, `.server`, `.conflict` plus every action member — no aliases.
   `mutator.server()` calls the action's own callable (lands in `invoke`); `.local()` never leaves the
   client.
@@ -110,7 +116,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim** (`index.test.ts` asserts identity).
 - **`transition()` is a mutator factory that decides nothing about the machine**: entity's three
   codes propagate; `from` is REQUIRED (it is the UPDATE's predicate); `conflict: 'server-wins'` fixed;
-  `audit` off unless declared.
+  `audit` off unless declared; `id` is the key `output.id` declares (`keySchemaOf`), never a fixed
+  `t.uuid`.
 - **A lookup table is read with `Object.hasOwn`** (`IRREGULAR` in `naming.ts`, `BY_FORMAT` in
   `sample-input.ts`) — caller- or provider-supplied keys.
 
@@ -209,14 +216,30 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   `configureIdempotency({ scope })`, compared by `assertIdempotencyScope` in `registerAction`
   (`X_IDEMPOTENCY_NOT_SHARED`). Default `'process'`.
 - **The memory store is bounded; `in-flight` records are the last evicted.** Never an LRU.
-- **`postgresIdempotencyStore` is the shared store** over a structural `PgExecutor` (no `action -> db`
-  edge); the reservation is ONE `insert … on conflict` statement. The CLI boot installs it.
+- **`postgresIdempotencyStore` is the shared store** over `@ultimat3/core`'s structural `PgExecutor`; the
+  reservation is ONE `insert … on conflict` statement. The CLI boot installs it.
+- **Inside a transaction the SETTLE commits with the write, on BOTH stores** (`liveTransaction()`):
+  Postgres on the handler's connection, memory at `onCommit`. The reservation and `fail` stay
+  immediate. A tx-bound settle that matches no record THROWS `X_IDEMPOTENCY_RESERVATION_LOST` (the
+  rollback of an attempt a retry replaced); the autocommit one only logs. Only a tx-bound
+  `in-flight` record is reclaimed past the deadline — never an autocommit one.
+  `idempotency-parity.test.ts` (memory + PGlite), `idempotency-postgres.live.test.ts`.
+- **The deadline is `reclaimAfterMs: () => number`, REQUIRED on the Postgres store** and read per
+  reservation — the app's `requestTimeoutMs` through `requestDeadlineMs` (`request-deadline.ts`,
+  http's own default, never a number here). **`origin: () => object` is required too**: a
+  transaction on another database settles on the pool. A FINISHED scope's handle binds nothing.
 
 ## Invariants — cache and audit
 
 - **The post-commit bust never fails the write** — `cache-gate.ts` (the only `invalidateTags` caller)
   absorbs a refusing fan-out and logs through core's `logger`, never rendering the tags. A replay
   skips the bust.
+- **The bust waits for the ROOT commit** when a transaction is open (`openCommitScope().onCommit`):
+  dropped on rollback, never fired before the rows are durable. A straggler past its scope gets
+  `DbTx.onCommit`'s own answer, as entity's row observer does. `cache-gate-tx.test.ts` (PGlite).
+- **The OpenAPI contract assertion reads the registry-wide document** and compares `operationId`
+  — one built from the action alone could not fail. **`Problem` is `toProblem`'s members**, no
+  `code` pattern (`openapi-problem.test.ts`).
 - **The policy contract test asserts `ActionDeniedError` and sends valid input** (`sampleInput` from
   the input IR). Only `X_INPUT_INVALID` (and `X_AUDIT_SINK_MISSING`, the one refusal before the parse)
   becomes `X_CONTRACT_DRIFT`; everything else keeps its own code; a non-`UltimateError` is rethrown.

package/README.md

@@ -296,6 +296,13 @@ fan-out that refuses — an undeclared tag, `X_CACHE_TAG_UNKNOWN` — is one
 `action.invalidate.failed` log line and the entries expire by TTL. A replayed idempotent
 call busts nothing; the first call already did.
 
+**After the COMMIT, not after the handler** (`As of 2026-10-02`). An action invoked inside a
+`withTransaction` — an app's own unit of work, or another action's — hands its bust to the ROOT
+transaction's `onCommit`: it fires once the commit is answered and never for a rollback or an
+aborted transaction (`X_DB_TRANSACTION_ABORTED`). Busting at the handler's return let a
+concurrent read refill the cache from the pre-commit rows, which then stayed for the TTL. With no
+transaction open the bust runs when the handler returns, as it always did.
+
 Registering an action without `policy:` throws `X_ACTION_POLICY_MISSING`; there is
 no bypass flag. A look-alike that never came out of `action()` is `X_ACTION_FOREIGN`.
 
@@ -310,6 +317,7 @@ export const likePost = mutator({
   input: t.object({ postId: t.uuid }),
   output: PostLikes,
   policy: can('post:like'),
+  idempotent: true, // REQUIRED — a replayed write answers the first result (below)
   // Convergent, not incremental: `local` replays on every rebase, so applying it N times has to
   // equal applying it once — `likedByMe` is what makes the second application a no-op.
   local(tx, { postId }) {
@@ -341,6 +349,14 @@ denies is denied there exactly as over HTTP. `.local()` is the only half that sk
 the core, because it never leaves the client; keep it a pure function of `(tx, input)`
 — no I/O, no clock, no randomness — since every rebase replays it.
 
+**`idempotent: true` is required on every mutator** — a compile error without it, and
+`X_MUTATOR_NOT_IDEMPOTENT` at declaration for a caller the compiler never saw. A mutator's write
+is replayed by construction: `useMutation` retries, and the offline queue drains after a dropped
+response, under ONE `Idempotency-Key`. The server reads that key only for an idempotent action, so
+without the declaration the replay ran `server` a second time — a toggle flipped back. It is
+declared, never defaulted, because the replay is answered from the idempotency store and which
+store that is (below) is the app's to decide. `transition()` declares it for you.
+
 `LocalTx` is the client write surface, implemented by `@ultimat3/realtime` over the page's
 record store — the SAME shape as that store's tx. Every table is addressed by **key**:
 `get(key)`, `all()`, `insert(key, row)`, `upsert(key, row)`, `update(key, patch | fn)`,
@@ -388,12 +404,13 @@ await moveOrder({ id, from: 'pending', to: 'paid' }, { ctx });
 | **`from` is required, and never defaulted or inferred** | it rides in the UPDATE's own predicate, so the state observed and the state written are one decision under the row's lock. Measured on the mechanism underneath: twenty concurrent moves at one row gave 14 winners with a read-then-check-then-write and **1 winner plus 19 refusals** with `from` in the predicate. Anything that supplies `from` for the caller is the lost update coming back |
 | the states are the **input schema**, not a `t.string` | the union survives into `InferOutput`, so the typed client refuses a typo at **compile** time, the MCP tool's `inputSchema` and the OpenAPI component both publish the legal set, and a bad state is `X_INPUT_INVALID` before a database is touched |
 | `conflict: 'server-wins'`, not overridable | the server is the half that REFUSED the move; a local twin winning the rebase would leave the client showing a state the database rejected |
+| `id` is the entity's **key**, read off `output.id` | a uuid key stays `t.uuid` (a malformed one is `X_INPUT_INVALID` before a database reads it); a `text()` key keeps its length and a `bigint()` key its digits pattern — never a fixed `t.uuid`, which refused every move on an entity keyed by anything else. An `output` that does not carry the key as `id` passes the key's schema as `id:`; with neither, the id is a uuid |
+| `idempotent: true`, always | a move replayed under its `Idempotency-Key` answers the first outcome, not an `X_STATE_CONFLICT` for a move that already happened |
 | `audit` is **off** unless the app says so | `audit: true` with no sink installed is `X_AUDIT_SINK_MISSING`, raised before the input parse — an on-by-default audit would make every `transition()` refuse until an unrelated decision was made. What the row is kept for, and for how long, is the same compliance question that kept a purge out of `postgresAuditSink` |
 | `X_STATE_TRANSITION_ILLEGAL`, `X_STATE_CONFLICT` and `X_STATE_UNDECLARED` propagate untouched | they are `@ultimat3/entity`'s. A second error class over one failure is a second path |
 
-`table` is typed structurally (`TransitionTarget`), not imported: `@ultimat3/action` holds no
-dependency edge on `@ultimat3/entity` — the tier table permits one, the manifest and the lockfile do
-not — and a real `Table` satisfies the seam as written.
+`table` is typed structurally (`TransitionTarget`), not imported — a real `Table` satisfies the
+seam as written.
 
 ## Determinism + idempotency
 
@@ -464,6 +481,7 @@ no record and runs the handler again:
 import {
   configureIdempotency,
   postgresIdempotencyStore,
+  requestDeadlineMs,
   setIdempotencyStore,
 } from '@ultimat3/action';
 import { db } from '@ultimat3/db';
@@ -478,6 +496,10 @@ const client = db();
 setIdempotencyStore(
   postgresIdempotencyStore({
     executor: { query: (text, values) => client.query({ text, values }) },
+    // The client transactions on THIS database open on: a settle rides one of those and no other.
+    origin: () => client,
+    // The app's `requestTimeoutMs` (`configureHttp`), read per reservation — never a number here.
+    reclaimAfterMs: requestDeadlineMs,
   }),
 );
 configureIdempotency({ scope: 'shared' });
@@ -514,6 +536,26 @@ Both stores fence on it AND on `in-flight` `As of 2026-08`, the way `@ultimat3/j
 so a straggler from the first attempt satisfied a status-only fence exactly and overwrote a live
 reservation.
 
+**Inside a transaction the settlement commits with the write** (`As of 2026-10-02`, BOTH stores —
+`idempotency-parity.test.ts` runs one set of cases over memory and Postgres). An action invoked
+inside `withTransaction` settles with that transaction: on its own connection (Postgres), or at
+its `onCommit` (memory).
+
+| The unit of work | The record | A retry |
+|---|---|---|
+| commits | `settled`, by the same `COMMIT` | replays the first result |
+| rolls back after the handler returned | still `in-flight` — never `settled` for rows nobody stored | `X_IDEMPOTENCY_CONFLICT` until the request deadline, then it runs |
+| dies mid-flight | still `in-flight` | the same |
+| outlives the deadline and a retry takes the key | the retry's | the slow attempt's settle is refused `X_IDEMPOTENCY_RESERVATION_LOST`, which rolls its transaction back — one write |
+
+| Rule | Why |
+|---|---|
+| the deadline is `reclaimAfterMs: () => number`, **required** on the Postgres store | it is the app's `requestTimeoutMs`, declared (`configureHttp`) after the boot built the store — so it is read per reservation, and `requestDeadlineMs` is the reader. `0` is "no deadline": nothing is reclaimed before the window. The memory store defaults to the same reader |
+| it frees only a record whose settle was BOUND to a transaction (`x_idempotency.tx_bound`) | a handler with no transaction around it keeps the old rule — reserve, run and settle are three commits, "died before the write" and "wrote, then died before the settle" are one row, and that row answers 409 for the whole window rather than risk the second charge |
+| the reservation and a recorded failure always go through the pool | a duplicate sees the first at once, and a failure outlives its rollback |
+| `origin: () => client` is **required** on the Postgres store | a transaction opened on ANOTHER database (`withTransaction(fn, { client: shard })`) has no `x_idempotency`; its record is settled on the pool, as an autocommit handler's is |
+| a finished transaction binds nothing | a promise chain the body forgot to await still finds the scope's handle; the settle then runs at once (`liveTxConnection`), never as a commit hook that a rollback already dropped |
+
 A `query` has none and never will: a read has nothing to be idempotent about.
 
 ## `deprecated:` — a compat window, not a version
@@ -685,7 +727,7 @@ setAuditSink({
 |---|---|
 | input schema rejects garbage | the invocation fails `X_INPUT_INVALID` — that code, not any failure |
 | policy denies an anonymous actor | the invocation fails with an `ActionDeniedError` |
-| OpenAPI document contains its operation | the derived path is in `buildOpenApi()` |
+| OpenAPI document contains its operation | the action's path, in the document built from the WHOLE registry (plus this action when a test drives an unregistered `.named()` twin), is this action's operation — a second registered action deriving the same route fails it |
 
 The denial assertion sends an input synthesized from `input:`'s own schema — required keys
 only, formats included — because a payload the schema rejects never reaches a policy. It
@@ -716,8 +758,10 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_INPUT_INVALID` | input failed the Standard Schema. Carries the rejections **twice**: the flattened line in `cause`, and the structured list in `meta.issues` — one value rendered two ways, `As of 2026-08-24` | `x actions describe <name> --json` |
 | `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
 | `X_IDEMPOTENCY_KEY_INVALID` | `Idempotency-Key:` sent blank (`Headers.get()` answers `''`, not `null`) or past 255 characters | send one unique value per request, or omit the header |
-| `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor })` at boot |
+| `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor, origin, reclaimAfterMs })` at boot |
 | `X_IDEMPOTENCY_REPLAYED_FAILURE` | a retried key replays a first attempt that failed and carried no framework code of its own | read the first attempt, then send a fresh key |
+| `X_IDEMPOTENCY_RESERVATION_LOST` | a settle inside the handler's transaction matched no record: the attempt outlived the request deadline and a retry took the key. This attempt's transaction rolls back | resend with the same `Idempotency-Key` |
+| `X_MUTATOR_NOT_IDEMPOTENT` | `mutator()` declared without `idempotent: true` | add `idempotent: true` to the definition |
 | `X_IDEMPOTENCY_STATUS_UNKNOWN` | `x_idempotency.status` holds a word this build has no branch for — written by a newer deploy | finish the rollout onto the build that writes it, then reconcile those requests — never DELETE the rows, which frees the key to run an already-committed action a second time |
 | `X_CONTRACT_DRIFT` | client/server build skew, missing spec entry | reload / `x verify --only contract` |
 | `X_RPC_FAILED` | registered, thrown by nothing since 21.0.0 — a non-`problem+json` failure is core's `X_CLIENT_TRANSPORT_FAILED` now, as for a query | match `X_CLIENT_TRANSPORT_FAILED` instead |
@@ -762,13 +806,15 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `IdempotencyKeyInvalidError` | `X_IDEMPOTENCY_KEY_INVALID` | `src/errors-idempotency.ts` |
 | `IdempotencyNotSharedError` | `X_IDEMPOTENCY_NOT_SHARED` | `src/errors-idempotency.ts` |
 | `IdempotencyReplayedFailureError` | `X_IDEMPOTENCY_REPLAYED_FAILURE` | `src/errors-idempotency.ts` |
+| `IdempotencyReservationLostError` | `X_IDEMPOTENCY_RESERVATION_LOST` | `src/errors-idempotency.ts` |
 | `IdempotencyStatusUnknownError` | `X_IDEMPOTENCY_STATUS_UNKNOWN` | `src/errors-idempotency.ts` |
 | `InputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |
+| `MutatorNotIdempotentError` | `X_MUTATOR_NOT_IDEMPOTENT` | `src/errors-idempotency.ts` |
 | `OutputInvalidError` | `X_OUTPUT_INVALID` | `src/errors.ts` |
 | `RemoteActionError` | the code the server sent, verbatim — `meta.origin: 'remote'` | `src/errors.ts` |
 | `RpcFailedError` | `X_RPC_FAILED` | `src/errors.ts` |
 
 ## Boundaries
 
-Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `entity`, `policy`, `http`. Never imports
+Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `db`, `entity`, `policy`, `http`. Never imports
 `query`, `jobs`, `realtime` (same tier) or anything above it — those import *this*.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "23.0.0",
+  "version": "24.0.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -35,11 +35,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "23.0.0",
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/http": "23.0.0",
-    "@ultimat3/policy": "23.0.0",
-    "@ultimat3/schema": "23.0.0"
+    "@ultimat3/cache": "24.0.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/db": "24.0.0",
+    "@ultimat3/entity": "24.0.0",
+    "@ultimat3/http": "24.0.0",
+    "@ultimat3/policy": "24.0.0",
+    "@ultimat3/schema": "24.0.0"
   }
 }

package/src/audit-memory.ts

@@ -34,6 +34,8 @@ export interface MemoryAuditSinkOptions {
  * here: a non-zero count on a real deployment is the sink saying it is the wrong one.
  */
 export interface MemoryAuditSink extends AuditSink {
+  /** Synchronous here: the window is an array, so nothing is left for a caller to await. */
+  write(record: AuditRecord): void;
   /** The retained window, oldest first. A copy — the log cannot be mutated through it. */
   records(): readonly AuditRecord[];
   /** Retained right now — the bound, observable. */

package/src/audit-postgres.ts

@@ -5,11 +5,10 @@
  * production. Statements are spelled out so an agent can run the exact one it saw in a log.
  */
 
-import type { Actor } from '@ultimat3/core';
+import type { Actor, PgExecutor } from '@ultimat3/core';
 import { uuid } from '@ultimat3/core';
 import type { AuditRecord, AuditSink } from './audit';
 import { auditableInput } from './audit-input';
-import type { PgExecutor } from './idempotency-postgres';
 
 /**
  * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, and

package/src/cache-gate.ts

@@ -1,22 +1,41 @@
 /**
  * The post-commit cache bust — the only file in this package that calls `invalidateTags`.
- * The handler has already committed by the time it runs, so a fan-out that refuses degrades to
- * one logged failure instead of a failed action: the stale entries expire by TTL, and the caller
- * keeps the write it already made.
+ * Post-COMMIT, not post-handler: inside a transaction it waits for the root commit. A fan-out that
+ * refuses degrades to one logged failure instead of a failed action — the stale entries expire by
+ * TTL, and the caller keeps the write it already made.
  */
 
 import type { CacheTag, InvalidationReport } from '@ultimat3/cache';
 import { invalidateTags } from '@ultimat3/cache';
 import { logger } from '@ultimat3/core';
+import { type CommitScope, openCommitScope } from './tx-scope';
 
 /**
- * Fan `tags` out and never throw. `undefined` back means the fan-out itself refused and nothing
- * was cleared — an undeclared tag (`X_CACHE_TAG_UNKNOWN`) is the one an app hits. One dead tier
- * is not that case: `invalidateTags` absorbs those into `report.errors` and still reports.
+ * Fan `tags` out and never throw. `undefined` back means nothing was cleared BY THIS CALL: the
+ * fan-out refused — an undeclared tag (`X_CACHE_TAG_UNKNOWN`) is the one an app hits — or it was
+ * deferred. One dead tier is not that case: `invalidateTags` absorbs those into `report.errors`.
+ *
+ * Inside a transaction (`scope`, the ambient one unless a caller passes its own) the handler's rows
+ * are not durable when it returns. Busting there let a concurrent read refill the cache with the
+ * pre-commit rows, which then stayed for the TTL — and a rollback busted for a write nobody made.
+ * So the bust is handed to the ROOT commit, as `@ultimat3/entity`'s row observer hands its report:
+ * `onCommit` never fires for a transaction that rolled back or whose COMMIT was lost.
  */
 export async function bustAfterCommit(
   action: string,
   tags: readonly CacheTag[],
+  scope: CommitScope | undefined = openCommitScope(),
+): Promise<InvalidationReport | undefined> {
+  if (scope === undefined) return bust(action, tags);
+  // Not awaited, and it cannot be: a commit effect is synchronous and runs after the transaction
+  // is durable. `bust` never rejects, so there is no rejection for the missing await to lose.
+  scope.onCommit(() => void bust(action, tags));
+  return undefined;
+}
+
+async function bust(
+  action: string,
+  tags: readonly CacheTag[],
 ): Promise<InvalidationReport | undefined> {
   try {
     return await invalidateTags(tags);

package/src/contract-test.ts

@@ -8,10 +8,13 @@ import type { Ctx } from '@ultimat3/core';
 import { createContext, isUltimateError, logger } from '@ultimat3/core';
 import type { AnyAction } from './action';
 import { ActionDeniedError, ContractDriftError } from './errors';
+import { toOpenApiOperation } from './http';
+import { servedActionRoute } from './http-path';
 import { actionName, invoke } from './invoke';
-import { derivePath } from './naming';
 import { buildOpenApi } from './openapi';
+import { listActions } from './registry';
 import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
+import { isJsonObject } from './stable';
 import { validateInput } from './validate';
 
 export interface ContractTest {
@@ -74,20 +77,41 @@ export function contractTestsFor(
     },
     {
       name: `${name}: OpenAPI document contains its operation`,
-      run: async () => {
-        const document = buildOpenApi({ actions: [target] });
-        const path = derivePath(name).path;
-        if (document.paths[path] === undefined) {
-          throw new ContractDriftError(
-            `OpenAPI document has no entry for ${path}`,
-            'x verify --json   # the contract suite is a step of it',
-          );
-        }
-      },
+      run: async () => assertDocumented(target, name),
     },
   ];
 }
 
+/**
+ * Against the document the APP publishes — the whole registry, plus this action when a test drives
+ * a `.named()` twin nothing seated — never one built from this action alone: that one holds its
+ * own path by construction, so the assertion could not fail. What can go wrong is in the rest of
+ * the registry: a second action deriving the same route, whose operation is the one published.
+ */
+function assertDocumented(target: AnyAction, name: string): void {
+  const seated = listActions();
+  const actions = seated.some((other) => other.name === name) ? seated : [...seated, target];
+  const { path } = servedActionRoute(name);
+  const published = buildOpenApi({ actions }).paths[path];
+  const owner = operationIdAt(published);
+  if (owner === toOpenApiOperation(target).operationId) return;
+  throw new ContractDriftError(
+    owner === undefined
+      ? `OpenAPI document has no entry for ${path}`
+      : `OpenAPI document serves ${path} as ${owner}, so ${name} is not in the published contract`,
+    owner === undefined
+      ? 'x verify --json   # the contract suite is a step of it'
+      : `x actions describe ${name} --json   # then rename it, or pin its own route with http: { path } in the ${name} definition`,
+  );
+}
+
+/** `paths[path].post.operationId`, read off a value typed `unknown` — narrowed, never cast. */
+function operationIdAt(entry: unknown): string | undefined {
+  if (!isJsonObject(entry) || !isJsonObject(entry['post'])) return undefined;
+  const id = entry['post']['operationId'];
+  return typeof id === 'string' ? id : undefined;
+}
+
 /**
  * A `pattern` cannot be inverted, so the framework cannot build a payload for
  * `t.string.pattern(...)` — but the pattern IS in the IR, so it knows that BEFORE it invokes.

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 {
@@ -267,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',

package/src/mutator.ts

@@ -18,6 +18,7 @@ import type {
 } from './action';
 import { action, isAction } from './action';
 import type { Deprecation } from './deprecation';
+import { MutatorNotIdempotentError } from './errors';
 import type { ActionHttp } from './http-path';
 import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
@@ -97,7 +98,14 @@ export interface MutatorDef<
   readonly deprecated?: Deprecation;
   /** Same key, same meaning as an action's: `http: { path }` pins the URL. */
   readonly http?: ActionHttp;
-  readonly idempotent?: boolean;
+  /**
+   * REQUIRED, and only `true`. A mutator's write is replayed under one `Idempotency-Key` —
+   * `useMutation`'s retry, the offline queue's drain after a dropped response — and the server
+   * reads that key only for an idempotent action. Declared rather than defaulted because the
+   * replay is answered from the idempotency store, and which store that is (`configureIdempotency`)
+   * is the app's decision to see. Omitted: a compile error, and `X_MUTATOR_NOT_IDEMPOTENT`.
+   */
+  readonly idempotent: true;
   /**
    * The row a row-level `policy` decides about — an action's `row`, and dropped on the way into
    * the action until 2026-09-23, so such a policy received `row === null` and denied every call.
@@ -158,6 +166,9 @@ export function mutator<
   TOutput extends StandardSchemaV1,
   TRow = unknown,
 >(def: MutatorDef<TInput, TOutput, TRow>): Mutator<TInput, TOutput> {
+  // First, and for a caller the compiler never saw: a replay that runs the server half twice is
+  // silent, so the declaration is refused where it is written rather than on the second POST.
+  if (def.idempotent !== true) throw new MutatorNotIdempotentError();
   const row = def.row;
   const actionDef: ActionDef<TInput, TOutput, TRow> = {
     input: def.input,
@@ -169,7 +180,7 @@ export function mutator<
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
     ...(def.http === undefined ? {} : { http: def.http }),
     ...(row === undefined ? {} : { row: (args: ActionRowArgs<TInput>) => row.call(def, args) }),
-    ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
+    idempotent: true,
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     handle: ({ input, ctx }) => def.server(ctx, input),
   };

package/src/openapi.ts

@@ -76,7 +76,12 @@ function compareByName(a: AnyAction, b: AnyAction): number {
   return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 }
 
-/** RFC 9457 + the Ultimate error contract (code / cause / fix / docs). */
+/**
+ * RFC 9457 + the Ultimate error contract, member for member what `@ultimat3/http`'s `toProblem`
+ * serves (`openapi-problem.test.ts` compares the two). `code` carries no `pattern`: `factsOf`
+ * serves whatever string an app's own throwable holds, and a published pattern the server breaks
+ * makes a generated client reject the very document it was written to read.
+ */
 const PROBLEM_SCHEMA: JsonSchemaObject = {
   type: 'object',
   required: ['type', 'title', 'status', 'code'],
@@ -85,9 +90,27 @@ const PROBLEM_SCHEMA: JsonSchemaObject = {
     title: { type: 'string' },
     status: { type: 'integer' },
     detail: { type: 'string' },
-    code: { type: 'string', pattern: '^X_[A-Z0-9_]+$' },
+    instance: { type: 'string' },
+    code: { type: 'string' },
     cause: { type: 'string' },
     fix: { type: 'string' },
     docs: { type: 'string', format: 'uri' },
+    requestId: { type: 'string' },
+    // Absent when the failure produced none — never `[]`, which would claim "validated clean".
+    issues: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['path', 'expected', 'received', 'message'],
+        properties: {
+          path: { type: 'string' },
+          expected: { type: 'string' },
+          received: { type: 'string' },
+          message: { type: 'string' },
+        },
+      },
+    },
+    // Only the keys the code declared through `registerProblemMeta`; its shape is per code.
+    meta: { type: 'object' },
   },
 };

package/src/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ActionPathStyle } from '@ultimat3/core';
-import { SchemaUnsupportedError } from '@ultimat3/schema';
+import { SchemaUnsupportedError, toWireSchema } from '@ultimat3/schema';
 import type { ActionDescriptor, AnyAction } from './action';
 import { isAction, nameAction } from './action';
 import { resetApiDeclaration } from './api-declaration';
@@ -19,7 +19,7 @@ import {
 } from './http-path';
 import { assertIdempotencyScope } from './idempotency';
 import { defOf } from './invoke';
-import { jsonSchemaOf, mcpSchemaOf } from './json-schema';
+import { jsonSchemaOf } from './json-schema';
 import type { ActionPath } from './naming';
 import { seatedActions } from './registry-store';
 
@@ -111,7 +111,8 @@ function assertProjectable(name: string, target: AnyAction): void {
   for (const field of ['input', 'output'] as const) {
     try {
       jsonSchemaOf(target[field]);
-      mcpSchemaOf(target[field]);
+      // The schema `.tool()` and `tools/list` publish — the one an MCP client reads.
+      toWireSchema(target[field]);
     } catch {
       // The thrown value is deliberately not rendered into the cause: it is the provider's, of
       // unknown shape, and this package's own two facts — which action, which field — are the

package/src/request-deadline.ts

@@ -0,0 +1,25 @@
+/**
+ * The app's request deadline — how long an idempotency record bound to a transaction may stay in
+ * flight before a retry takes the key. Read from `@ultimat3/http`'s own declaration and resolved
+ * by its own `defineHttpConfig`, so the default and its screen are never restated here.
+ */
+import { configuredHttp, defineHttpConfig } from '@ultimat3/http';
+
+let resolved: { readonly declared: number | undefined; readonly ms: number } | undefined;
+
+/**
+ * `configureHttp({ requestTimeoutMs })`, else http's default; `0` is "no deadline". Read on every
+ * call because the app declares it at module scope AFTER the boot has built its stores — resolved
+ * once per declared value, since `defineHttpConfig` screens a whole config to answer one field.
+ */
+export function requestDeadlineMs(): number {
+  const declared = configuredHttp()?.requestTimeoutMs;
+  if (resolved === undefined || resolved.declared !== declared) {
+    const config = defineHttpConfig({
+      ...(declared === undefined ? {} : { requestTimeoutMs: declared }),
+      rateLimit: { enabled: false, scope: 'process' },
+    });
+    resolved = { declared, ms: config.requestTimeoutMs };
+  }
+  return resolved.ms;
+}

package/src/transition.ts

@@ -17,15 +17,14 @@ import type {
   StandardSchemaV1,
   StringSchema,
 } from '@ultimat3/schema';
-import { t } from '@ultimat3/schema';
+import { nodeOf, t } from '@ultimat3/schema';
 import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
 
 /**
  * The one method this factory calls, declared structurally: `@ultimat3/entity`'s `Table.transition`
- * satisfies it as written. Structural and not an import because `@ultimat3/action` holds no
- * dependency edge on `@ultimat3/entity` — the tier table permits one (2 is below 3), the manifest
- * and the lockfile do not — the same trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down.
+ * satisfies it as written. Structural because it is all this file needs of a table — one method —
+ * and a fake that implements it is the whole test seam; the package does import entity elsewhere.
  *
  * `id` is a plain `string` rather than entity's `IdOf<Row>`: that alias "collapses to `string` for
  * every unbranded entity" by its own account, and a branded one still satisfies this because a
@@ -69,16 +68,22 @@ export interface TransitionDef<
    * tool's `inputSchema` carries it, the typed client refuses a typo at COMPILE time, and a
    * misspelled state is `X_INPUT_INVALID` before the request reaches a database.
    *
-   * It is the one thing restated from the column's own declaration, and the reason is a boundary:
-   * reading the machine off the entity needs `@ultimat3/entity` as a real dependency of this
-   * package. Listing a SUBSET refuses a legal move at the input schema — loud, and the fix is the
-   * enum in the refusal.
+   * It is the one thing restated from the column's own declaration: `table` is resolved per request
+   * (`(ctx) => …`), and the input schema is needed at declaration, before any table exists to read
+   * a machine off. Listing a SUBSET refuses a legal move at the input schema — loud, and the fix is
+   * the enum in the refusal.
    */
   readonly states: readonly [S, ...S[]];
   /** The local store's name for this entity — what the optimistic twin patches. */
   readonly localTable: string;
   /** The projection the caller gets back. Unknown keys are dropped by the parse, so a `$view` works. */
   readonly output: TOutput;
+  /**
+   * The key's schema, for an `output` that does not carry the key as `id`. Omitted — the usual
+   * case — it is read off `output.id` (`keySchemaOf`), which for an entity `$view` IS the key
+   * column's own shape.
+   */
+  readonly id?: StringSchema;
   readonly policy: ActionPolicy;
   /**
    * OFF unless the app says otherwise, and deliberately not `?? true`.
@@ -115,9 +120,12 @@ export function transition<
   // can reach these two callbacks.
   const valuesOf = (raw: unknown): TransitionValues<S> => raw as TransitionValues<S>;
   return mutator({
-    input: t.object({ id: t.uuid, from: state, to: state }),
+    input: t.object({ id: def.id ?? keySchemaOf(def.output), from: state, to: state }),
     output: def.output,
     policy: def.policy,
+    // A compare-and-set move replayed under its key answers the first outcome, never a second
+    // `X_STATE_CONFLICT` for a move that already happened.
+    idempotent: true,
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     // Never overridable: the server is the half that REFUSED the move, and a local twin that won
     // the rebase would leave the client showing a state the database rejected.
@@ -142,3 +150,21 @@ export function transition<
     },
   });
 }
+
+/**
+ * The `id` a move takes, from the key the OUTPUT declares — never a fixed `t.uuid`, which made
+ * every call on an entity keyed by `text()` or `bigint()` `X_INPUT_INVALID` while the mechanism
+ * underneath addresses any single-column key. An entity `$view` builds its `id` node from the key
+ * column, so the bounds copied here are that column's: a uuid stays a uuid (and a malformed one is
+ * still refused before a database reads it), a `bigint()` keeps its digits pattern, a `text()` its
+ * length. Never empty: an empty string names no row. An output with no string `id` keeps the
+ * framework's default key type, `uuid().primaryKey()`.
+ */
+function keySchemaOf(output: StandardSchemaV1): StringSchema {
+  const key = nodeOf(output)?.properties?.['id'];
+  if (key === undefined || key.kind !== 'string' || key.format === 'uuid') return t.uuid;
+  let schema = t.string.min(Math.max(1, key.minLength ?? 1));
+  if (key.maxLength !== undefined) schema = schema.max(key.maxLength);
+  if (key.pattern !== undefined) schema = schema.pattern(new RegExp(key.pattern, key.patternFlags));
+  return schema;
+}

package/src/tx-scope.ts

@@ -0,0 +1,57 @@
+/**
+ * The open database transaction, as this package needs it — **the only** file here that imports
+ * `@ultimat3/db` (`tx-scope.test.ts` holds that). When is a write durable (`openCommitScope`, the
+ * cache bust), and is a transaction really OPEN, on which client (`liveTransaction`, idempotency).
+ */
+
+// Type-only: `idempotency-postgres.ts` imports this module, and a runtime edge would be a cycle.
+import type { PgExecutor } from '@ultimat3/core';
+import { currentTx, liveTxConnection } from '@ultimat3/db';
+
+/** The half of a transaction a deferred effect needs. `@ultimat3/db`'s `DbTx` satisfies it. */
+export interface CommitScope {
+  /** Fired once the ROOT transaction has committed; dropped on rollback or a lost COMMIT. */
+  onCommit(effect: () => void): void;
+}
+
+/**
+ * The transaction this call runs inside, or `undefined`. `currentTx()` on purpose, FINISHED scopes
+ * included: a promise chain the body forgot to await still finds the handle after the scope
+ * closed, and `onCommit` on it runs the effect at once after a COMMIT and drops it after a
+ * ROLLBACK — the answer `@ultimat3/entity`'s row observer gets from the same call, so a late bust
+ * and a late change report never disagree about one write.
+ */
+export function openCommitScope(): CommitScope | undefined {
+  return currentTx();
+}
+
+/** A transaction that is still OPEN: statements sent now are inside it. */
+export interface LiveTransaction extends CommitScope {
+  /** The client it was opened on — which DATABASE this is, compared by identity. */
+  readonly origin: object;
+  /** Fired when the scope rolls back; never after a commit. */
+  onRollback(undo: () => void): void;
+  /** `(text, values)` on the transaction's OWN connection. */
+  readonly executor: PgExecutor;
+}
+
+/**
+ * The open transaction, or `undefined` — outside one, and ALSO for a finished scope's handle. A
+ * settlement bound to a transaction that already ended is bound to nothing: it would run as its
+ * own commit while the record claimed otherwise, and that record is the one a retry may reclaim.
+ *
+ * The fragment is assembled by hand, exactly as `@ultimat3/cli`'s `pgExecutorFor` does: the caller
+ * wrote the `$1..$n` text itself and hands over already-bound values.
+ */
+export function liveTransaction(): LiveTransaction | undefined {
+  const tx = currentTx();
+  if (tx === undefined || liveTxConnection() === undefined) return undefined;
+  return {
+    origin: tx.origin,
+    onCommit: (effect) => tx.onCommit(effect),
+    onRollback: (undo) => tx.onRollback(undo),
+    executor: {
+      query: <R>(text: string, values: readonly unknown[]) => tx.query<R>({ text, values }),
+    },
+  };
+}