@ultimat3/action 22.15.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`.
 
@@ -18,11 +19,13 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `facade.ts` | the fluent surface — binds each projection to the action, re-implements none |
 | `mutator.ts` | action + optimistic `.local` twin + authoritative `.server` + `.conflict` |
 | `registry.ts` | export-name registration, collisions, `describeActions()` |
-| `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call |
+| `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call, and the `Api` type the typed clients are shaped from |
+| `client-scale-pins.ts` | compile-time pin: `rpc<Api['actions']>` over 300 actions in 100 modules, 100 reads in 50 |
 | `http.ts` | route projection (`enforcedBy: 'handler'`) + OpenAPI operation |
 | `openapi.ts` | deterministic OpenAPI 3.1 document |
 | `openapi-complete.ts` | the COMPLETE document (`defineApi({ openapi })`: info, servers, security schemes, 401/429 by the ROUTE's `meta.auth`) and a bearer mount's own cut |
 | `http-path.ts` | where an action is served: the app's `pathStyle` + a per-action `http.path` pin, read lazily by every projection |
+| `path-style-miss.ts` | `explainActionPathMiss` — `@ultimat3/http`'s `hooks.explainMiss`: a POST under the style this app does not serve is `X_CONTRACT_DRIFT` naming the one it does |
 | `api-declaration.ts` | `defineApi({ http, openapi })` held process-wide for the boot and `x manifest` |
 | `errors-http.ts` | the three HTTP-declaration refusals (codes registered in `errors.ts`) |
 | `client.ts` | typed RPC client (browser-safe: no server imports) — dispatches through core's `clientTransport` |
@@ -41,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 |
@@ -77,12 +82,28 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   `'resource'` stays the default (changing it moves every URL). `defineApi` sets the style FIRST and
   `configureActionPathStyle` re-derives every seated action (the module scan may have seated them
   under the default). `derivePath(name)` is pin-aware through `installPinLookup` — handed down by
-  `registry.ts`, never imported up (cycle through `action.ts`). `rpc()` cannot see a pin: it takes
-  `pathStyle`; `action.client()` holds the pin.
+  `registry.ts`, never imported up (cycle through `action.ts`). `rpc()` cannot see a pin;
+  `action.client()` holds it.
+- **The style is stated ONCE, on the server.** A browser never restates it: the document carries
+  `<meta name="ultimate-path-style">` (render's `clientPathStyleTags`, written only for a
+  non-default style) and core's `actionPath(name)` reads it for every caller naming none — `rpc`,
+  realtime's `useMutation` and the outbox replay. `client.ts` passes `options.pathStyle` through
+  and adds NO default of its own. `ClientOptions.pathStyle` is for a caller with no document; a
+  wrong one is answered `X_CONTRACT_DRIFT` (404) by `explainActionPathMiss`, never
+  `X_ROUTE_NOT_FOUND`. A pinned action and a path under the SERVED style are never explained.
+- **`Merge` in `define-api.ts` never recurses over the module list.** `Head & Merge<Rest>` is not
+  a tail call: it cost one instantiation level per MODULE and answered TS2589 at the 48th entry of
+  one list, whatever each exported (#534). The list is read as a union and intersected in one
+  step. `client-scale-pins.ts` is the build error; `client-scale.contract.test.ts` compiles real
+  `action()`/`query()` modules through `defineApi`'s `const` inference; `@ultimat3/query` pins
+  `QueryClient` itself.
 - **`defineApi({ openapi })` opts into the complete document; absent, `openapi.json`'s bytes are
   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.
@@ -95,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.
 
@@ -168,7 +190,9 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   | `rpc` | 18,097 B | 23,007 B | 18,119 B | 19,074 B |
   | `rpc` + `createClientFlight` | 23,903 B | 28,823 B | not measured | 25,197 B |
 
-  Net against the pre-transport figure: +977 B, about the envelope decoder's size.
+  Net against the pre-transport figure: +977 B, about the envelope decoder's size. `As of 2026-10-01`
+  `rpc` is 19,671 B (19,490 B before the document's path-style stamp was read: +181 B, +45 gzipped)
+  and `rpc` + `createClientFlight` 25,954 B.
 - **The `sideEffects` array is load-bearing**: `errors.ts` runs `registerErrorCodes` at import. Never `false`.
 
 ## Invariants — idempotency
@@ -192,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

@@ -113,8 +113,10 @@ export const client = rpc<Api['actions']>({ baseUrl: '/' });
 ```
 
 `Api['actions']` is the merged module type, so `client.publishPost` is typed from the
-declaration with no codegen step. `Api` is imported as a **type only**, which is what keeps
-a page's module graph free of any edge to a feature's implementation.
+declaration with no codegen step — at any app size: `client-scale-pins.ts` compiles the idiom over
+300 actions in 100 modules on every `typecheck` (the limit was 47 modules in one list, #534).
+`x new` writes this file as `apps/web/shared/browser-client.ts`. `Api` is imported as a **type
+only**, which is what keeps a page's module graph free of any edge to a feature's implementation.
 
 Every call dispatches through `@ultimat3/core`'s `clientTransport` — the one browser HTTP function.
 It owns credentials, the JSON body, the `Idempotency-Key` header, the principal fence and the
@@ -157,8 +159,8 @@ await api.charge({ orderId }, { idempotencyKey: `charge:${orderId}`, retry: { at
 It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
 this package exactly as before.
 
-Importing `rpc` alone from this package is **23,007 B** minified for the browser; adding
-`createClientFlight` is **28,823 B** (`As of 2026-09-22`; `CLAUDE.md` carries the before/after and
+Importing `rpc` alone from this package is **19,671 B** minified for the browser; adding
+`createClientFlight` is **25,954 B** (`As of 2026-10-01`; `CLAUDE.md` carries the before/after and
 what the delta is). `ClientFlight` is a TYPE inside `client.ts` and never a value, which is what
 keeps the second number off the first caller's bill.
 
@@ -182,9 +184,15 @@ One rule per app, declared once — `defineApi({ http: { pathStyle } })` — plu
   `/_x` (`X_ACTION_HTTP_PATH_INVALID`). A pin colliding with another path is
   `X_ACTION_PATH_DUPLICATE` at boot.
 - Every server-side reader agrees: `toRoute`, `toOpenApiOperation`, `describeAction`,
-  `derivePath(name)` (pin-aware) and `actionHttpPath(action | name)`. The browser's `rpc()` derives
-  from the name alone, so it is told the style: `rpc({ baseUrl, pathStyle: 'readable' })`; a pinned
-  action is called through `action.client()`, which holds the pin.
+  `derivePath(name)` (pin-aware) and `actionHttpPath(action | name)`. A pinned action is called
+  through `action.client()`, which holds the pin.
+- **A browser states no style.** The server stamps a non-default one into every document
+  (`<meta name="ultimate-path-style">`) and `rpc({ baseUrl: '' })` derives under it — as do
+  `useMutation` and the outbox replay. `'resource'` writes no tag.
+- **A caller with no document passes it**: `rpc({ baseUrl, pathStyle: 'readable' })` in a script or
+  another service. The wrong one is answered by the server — 404 `X_CONTRACT_DRIFT`, naming the
+  style it serves and the path the action lives at — never a bare `X_ROUTE_NOT_FOUND`
+  (`explainActionPathMiss`, wired as `@ultimat3/http`'s `hooks.explainMiss`).
 - **The style is read when the path is derived, so derive it late.** The scan evaluates
   `apps/web/api/index.ts` before any other module, so a page or admin view already sees the declared
   style. A module the index itself imports runs before its `defineApi` call: a module-level
@@ -288,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`.
 
@@ -302,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 }) {
@@ -333,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)`,
@@ -380,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
 
@@ -456,6 +481,7 @@ no record and runs the handler again:
 import {
   configureIdempotency,
   postgresIdempotencyStore,
+  requestDeadlineMs,
   setIdempotencyStore,
 } from '@ultimat3/action';
 import { db } from '@ultimat3/db';
@@ -470,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' });
@@ -506,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
@@ -677,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
@@ -708,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 |
@@ -754,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": "22.15.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",
@@ -22,6 +22,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -34,11 +35,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.15.0",
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/entity": "22.15.0",
-    "@ultimat3/http": "22.15.0",
-    "@ultimat3/policy": "22.15.0",
-    "@ultimat3/schema": "22.15.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/client-scale-pins.ts

@@ -0,0 +1,126 @@
+// Compile-time pin: the documented `rpc<Api['actions']>` idiom at 300 actions in 100 modules.
+// Source, not a `.test.ts`, for `type-pins.ts`'s reason — `tsc -b` never reads a test file. Types
+// only: nothing here is emitted, and a regression is TS2589 in the `typecheck` step.
+//
+// The shape is the OBSERVED one (issue #534): the limit was never the action count, it was the
+// number of MODULES in one `defineApi` list — 47 passed and 48 failed, whatever they exported.
+
+import type { NumberSchema, ObjectSchema, StringSchema } from '@ultimat3/schema';
+import type { Action } from './action';
+import type { rpc } from './client';
+import type { defineApi } from './define-api';
+
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+type Verb = 'create' | 'update' | 'archive';
+
+/** Distinct per module (`m7`), so no two modules collapse into one instantiation. */
+type ScaleInput<N extends number> = ObjectSchema<
+  {
+    readonly id: StringSchema;
+    readonly title: StringSchema;
+    readonly nested: ObjectSchema<{ readonly label: StringSchema; readonly rank: NumberSchema }>;
+  } & { readonly [K in `m${N}`]: NumberSchema }
+>;
+
+type ScaleOutput<N extends number> = ObjectSchema<
+  { readonly id: StringSchema } & { readonly [K in `out${N}`]: StringSchema }
+>;
+
+/** A feature module as `import * as` sees one: its actions, and a helper that is not one. */
+type ActionModule<N extends number> = {
+  readonly [K in `${Verb}Thing${N}`]: Action<ScaleInput<N>, ScaleOutput<N>>;
+} & { readonly [K in `helper${N}`]: (value: number) => number };
+
+/** `@ultimat3/query` is sideways, so a read is stood in for by the two members `Merge` reads. */
+type QueryModule<N extends number> = {
+  readonly [K in `listRows${N}` | `oneRow${N}`]: { readonly kind: 'query'; readonly name: string };
+};
+
+/** `[Module<0>, …, Module<TCount - 1>]`. A tail call, so the list length costs no depth here. */
+type ActionModules<
+  TCount extends number,
+  TAcc extends readonly unknown[] = [],
+> = TAcc['length'] extends TCount
+  ? TAcc
+  : ActionModules<TCount, [...TAcc, ActionModule<TAcc['length']>]>;
+
+type QueryModules<
+  TCount extends number,
+  TAcc extends readonly unknown[] = [],
+> = TAcc['length'] extends TCount
+  ? TAcc
+  : QueryModules<TCount, [...TAcc, QueryModule<TAcc['length']>]>;
+
+/** 100 modules of 3 actions, 50 modules of 2 reads — through `defineApi`'s own signature. */
+type ScaleApi = ReturnType<
+  typeof defineApi<{
+    readonly actions: ActionModules<100>;
+    readonly queries: QueryModules<50>;
+  }>
+>;
+
+/** The idiom itself: its `ActionMap` constraint is where TS2589 was raised. */
+type ScaleClient = ReturnType<typeof rpc<ScaleApi['actions']>>;
+
+export type _EveryModuleReachesTheClient = Assert<
+  'createThing0' | 'updateThing47' | 'archiveThing99' extends keyof ScaleClient ? true : false
+>;
+
+/** 300, counted: a `Merge` that dropped a module would still pass the three names above. */
+export type _TheClientHasExactlyTheRegisteredActions = Assert<
+  Equals<keyof ScaleClient, ActionName>
+>;
+
+type ActionName = {
+  [N in keyof ActionModules<100> & `${number}`]: `${Verb}Thing${N}`;
+}[keyof ActionModules<100> & `${number}`];
+
+/** A helper exported beside the actions is not a method — the server never registered it. */
+export type _AHelperIsNotAClientMethod = Assert<'helper0' extends keyof ScaleClient ? false : true>;
+
+/** One call, both sides inferred from the LAST module's own schemas. */
+export type _TheLastActionKeepsItsInput = Assert<
+  Equals<
+    Parameters<ScaleClient['archiveThing99']>[0],
+    {
+      readonly id: string;
+      readonly title: string;
+      readonly nested: { readonly label: string; readonly rank: number };
+      readonly m99: number;
+    }
+  >
+>;
+
+export type _TheLastActionKeepsItsOutput = Assert<
+  Equals<
+    Awaited<ReturnType<ScaleClient['archiveThing99']>>,
+    { readonly id: string; readonly out99: string }
+  >
+>;
+
+/** `Api['queries']` is the same `Merge`, and regresses with it. */
+export type _EveryQueryModuleIsMerged = Assert<
+  Equals<
+    keyof ScaleApi['queries'],
+    {
+      [N in keyof QueryModules<50> & `${number}`]: `listRows${N}` | `oneRow${N}`;
+    }[keyof QueryModules<50> & `${number}`]
+  >
+>;
+
+/** No list at all, and an empty one, are both the empty map — never `unknown`. */
+type EmptyApi = ReturnType<typeof defineApi<{ readonly actions: readonly [] }>>;
+
+export type _AnEmptyListIsAnEmptyMap = Assert<
+  Equals<keyof EmptyApi['actions'] | keyof EmptyApi['queries'], never>
+>;
+
+export type _AnEmptyMapStillSatisfiesRpc = ReturnType<typeof rpc<EmptyApi['actions']>>;
+
+/** One module handed over bare, not in a list — the other spelling `ApiModules` allows. */
+type BareApi = ReturnType<typeof defineApi<{ readonly actions: ActionModule<7> }>>;
+
+export type _ABareModuleIsRegisteredToo = Assert<Equals<keyof BareApi['actions'], `${Verb}Thing7`>>;

package/src/client.ts

@@ -84,10 +84,13 @@ export interface ClientOptions {
    */
   readonly flight?: ClientFlight;
   /**
-   * The server's `defineApi({ http: { pathStyle } })`, restated: the browser derives each URL from
-   * the name and cannot read the server's registry. Absent is `'resource'`, the server's default.
-   * A per-action `http.path` pin is honoured by `action.client()` (it holds the declaration); the
-   * name-only `rpc()` proxy cannot see one, so a pinned action is called through its own client.
+   * The style of a server that is NOT the one that rendered this page — a script, another
+   * service. A browser states nothing: the server stamps its `defineApi({ http: { pathStyle } })`
+   * into the document and every path is derived under that. With no document and no value here it
+   * is `'resource'`, the server's default; a server reached under the wrong one answers
+   * `X_CONTRACT_DRIFT` naming the style it serves. A per-action `http.path` pin is honoured by
+   * `action.client()` (it holds the declaration); the name-only `rpc()` proxy cannot see one, so a
+   * pinned action is called through its own client.
    */
   readonly pathStyle?: ActionPathStyle;
 }
@@ -123,7 +126,9 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
   options: ClientOptions,
   pinnedPath?: string,
 ): ClientMethod<TInput, TOutput> {
-  const path = pinnedPath ?? actionPath(name, options.pathStyle ?? 'resource');
+  // No default here: for a caller naming no style, `actionPath` asks the document the server
+  // rendered, and that answer must be the same one `useMutation` and the outbox replay get.
+  const path = pinnedPath ?? actionPath(name, options.pathStyle);
   const url = `${options.baseUrl.replace(/\/+$/, '')}${path}`;
   const onResponse = (response: Response): void =>
     assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);

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.