@ultimat3/action 23.0.0 → 25.0.0

package/README.md

@@ -1,13 +1,14 @@
 # @ultimat3/action ⚡
 
-One declaration → six artifacts.
+One declaration → six artifacts. Five are projected here; the MCP tool is `@ultimat3/mcp`'s
+(tier 4), from the same declaration.
 
 | # | Artifact | Reach it with | Guarantees |
 |---|---|---|---|
 | 1 | HTTP route `POST /api/<resource>/<verb>` | `toRoute(publishPost)` — the server mounts it | policy + validation + idempotency + invalidation, non-optional |
 | 2 | OpenAPI 3.1 operation + document | `publishPost.openapi()` / `buildOpenApi()` | byte-stable output, diffed by `x verify` |
 | 3 | Typed RPC client | `publishPost.client({ baseUrl })` / `rpc<Api['actions']>()` | server typo = compile error in Solid |
-| 4 | MCP tool | `publishPost.tool()` | *identical* policy evaluation to the route |
+| 4 | MCP tool | `toolFrom(publishPost)` from `@ultimat3/mcp` — what `tools/list` serves | *identical* policy evaluation to the route: it calls this package's `invoke` with `surface: 'mcp'` |
 | 5 | Job handle | `publishPost.job()` | enqueue durable work, no rewrite |
 | 6 | Contract tests | `publishPost.contract()` | garbage rejected, anonymous denied, spec present |
 
@@ -22,16 +23,17 @@ publishPost.output                             // the declared output schema
 publishPost.policy                             // the one policy object
 publishPost.mcp                                // { expose, description }, as declared
 await publishPost.as(actor, { postId })        // run as someone, one execution path
-publishPost.tool()                             // MCP descriptor
 publishPost.openapi()                          // OpenAPI operation
 publishPost.client({ baseUrl })                // typed RPC method
 publishPost.job()                              // durable-work handle
 publishPost.contract()                         // the three generated assertions
 ```
 
-`publishPost.tool().policy === publishPost.policy` — the same object, so an MCP call
-cannot reach a different authz path. `.as()` keeps the surrounding context whole and
-swaps only the actor: impersonation, not a second context.
+There is no `.tool()` (`As of 25.0.0`): it was a second MCP projection built a tier below the
+one `@ultimat3/mcp` serves, and the two disagreed. The tool an agent is shown is
+`toolFrom(publishPost)`, and its every call lands in this package's `invoke` — the one
+policy object, so an MCP call cannot reach a different authz path. `.as()` keeps the
+surrounding context whole and swaps only the actor: impersonation, not a second context.
 
 ## Declare
 
@@ -133,7 +135,7 @@ returned none, so one operation has one wire shape. Every other action's body is
 what it was before the envelope existed, and its OpenAPI operation is unchanged; an enveloped one
 documents `data`, `records` and `removed`, and the header, generated from the declaration.
 
-### Flight control — `createClientFlight`, opt-in
+### Flight control — `clientFlight`, opt-in
 
 Same object as `@ultimat3/query`'s, installed the same way (`rpc({ baseUrl, flight })`), and the
 write half is the half made of refusals:
@@ -154,13 +156,14 @@ declare const orderId: string;
 await api.charge({ orderId }, { idempotencyKey: `charge:${orderId}`, retry: { attempts: 3 } });
 ```
 
-`createClientFlight` is **`@ultimat3/core`'s**, re-exported here: it is the same object
-`@ultimat3/query` re-exports, because both packages are tier 3 and neither may import the other.
-It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
-this package exactly as before.
+`clientFlight` is **`@ultimat3/core`'s**, and imported from there — `import {
+clientFlight } from '@ultimat3/core'`. It shipped as a byte-identical copy here and in
+`@ultimat3/query` (both tier 3, neither may import the other); the copies are gone, and since 25.0.0
+so are the re-exports: one value, one import path (`X_HELPER_COPY`, `bun run flight-copies`). The
+types `ClientFlight` and `ClientRetry` stay re-exported, because `rpc`'s options name them.
 
 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
+`clientFlight` (measured through this barrel, before 25.0.0 moved the import to core) 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.
 
@@ -252,14 +255,14 @@ Under the default style:
 | `likePost` | `POST /api/posts/like` | `likePost` |
 | `checkout` (single word) | `POST /api/checkouts/invoke` | `checkout` |
 
-**One name, four surfaces** — `.tool().name`, `openapi.json`'s `x-ultimate.mcpTool`,
+**One name, three surfaces** — `openapi.json`'s `x-ultimate.mcpTool`,
 `describeAction().mcp.tool` (what `x actions describe --json`, `x actions list --json`, the
 `actions.describe` dev MCP tool and the `/_x` Routes panel show) and the catalog `@ultimat3/mcp`
-serves. It was two until 2026-08: a `toToolName()` here snake_cased the first three to
+serves. It was two until 2026-08: a `toToolName()` here snake_cased the published ones to
 `publish_post` while the server answered only `publishPost`, so an agent that read the published
 contract called a tool that does not exist. `toToolName` is **deleted**, not deprecated — a second
-derivation is a second name. `mcp-tool.test.ts`'s "one name per action, on every surface" is what
-keeps it that way.
+derivation is a second name. `mcp-surface.test.ts` here and `@ultimat3/mcp`'s
+`cross-surface.test.ts` are what keep it that way.
 
 `x.manifest.json` is **not** one of the four: `ActionFact.mcp` is `{ expose, description? }`, so
 the manifest never carried a tool name and was never wrong about one.
@@ -277,7 +280,7 @@ no `.def`. A second authz path cannot be written without deleting that store.
 
 | Stage | Failure |
 |---|---|
-| policy, actor half (`guardBeforeInput`) | `X_UNAUTHENTICATED` / `X_FORBIDDEN` for a caller the policy refuses whatever the input — never a 400 describing the schema of an operation they may not call |
+| policy, actor half (`guardActionBeforeInput`) | `X_UNAUTHENTICATED` / `X_FORBIDDEN` for a caller the policy refuses whatever the input — never a 400 describing the schema of an operation they may not call |
 | parse input | `X_INPUT_INVALID` |
 | evaluate policy | the policy's own code — `X_UNAUTHENTICATED` (401), `X_FORBIDDEN` (403) |
 | handle | whatever the handler throws |
@@ -296,13 +299,20 @@ 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`.
 
 ## mutator = action + local twin
 
-`mutator()` is built **on top of** `action()`. A mutator IS an action, so it gets all
-six projections; it adds `local(tx, input)` for the optimistic write and a `conflict`
+`mutator()` is built **on top of** `action()`. A mutator IS an action, so it gets every
+projection an action has; it adds `local(tx, input)` for the optimistic write and a `conflict`
 strategy for the rebase.
 
 ```ts
@@ -310,6 +320,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 +352,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 +407,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
 
@@ -410,17 +430,43 @@ import type { ActionRateLimit } from '@ultimat3/action';
 const rateLimit: ActionRateLimit = { limit: 5, windowMs: 600_000 };
 ```
 
-One declaration, three places it lands: the bucket the limiter runs on (named after the action,
-registered by `@ultimat3/http`'s `withRouteBuckets` when the route is mounted), the
-`ratelimit-limit` header the caller reads, and `x-ultimate.rateLimit` in the OpenAPI operation.
+One declaration, one bucket, every surface. `invoke` spends it — so the HTTP route, the MCP tool,
+the in-app agent's tool call and `.job()` draw on the **same** bucket, and the third call to a
+`limit: 2` action is refused `X_RATE_LIMITED` whichever door it came through. A direct in-process
+call (`surface: 'server'` — a service, a seed, a test) is app code, not a caller, and spends nothing.
+
+| Fact | Answer |
+|---|---|
+| whose bucket | the caller's: actor → org → connection address (`@ultimat3/http`'s `rateLimitSpends`). An anonymous caller with no address (MCP, a job) shares one bucket |
+| where it is counted | `@ultimat3/http`'s installed store (`installRateLimitStore()`) — the slot `@ultimat3/query` spends from too; the boot fills it with the SAME instance it gives `httpServer({ rateLimitStore })`, on every role. Default: one process' memory |
+| what HTTP answers | `RateLimit-*` from the bucket closest to refusing, and on a refusal `429` + `Retry-After` — the pipeline's own shape |
+| a retry | an admitted attempt spends one token; a refused one spends nothing. A job refused `X_RATE_LIMITED` is rescheduled for its `Retry-After` WITHOUT counting an attempt, so a backlog is delayed, never dead-lettered |
+| an idempotent replay | spends nothing: the stored answer is served, never a 429 |
+| who a job run is | its actor, else its tenant (`org:<orgId>`); a run with neither shares one `job:unattributed` bucket, never the anonymous callers' |
+| OpenAPI | `x-ultimate.rateLimit`, and with `defineApi({ openapi })` the `RateLimit-*` headers and `429` |
+
+```ts
+import type { PgExecutor } from '@ultimat3/core';
+import { installRateLimitStore, postgresRateLimitStore } from '@ultimat3/http';
+
+declare const executor: PgExecutor; // the pool this boot already opened
+
+// Boot, before the first call — the one store every surface and every replica counts in.
+// `x dev` and a container boot do this themselves, and `httpServer({ rateLimitStore })` adopts
+// the store it is handed; a process with no server (a worker of your own) installs it here.
+const rateLimitStore = postgresRateLimitStore({ executor });
+installRateLimitStore(rateLimitStore);
+```
+
 `toBucket` is the only conversion — `capacity: limit`, `refillPerSecond: limit / (windowMs / 1000)`
 — so the published numbers and the enforced ones cannot differ. It lives in `@ultimat3/http`,
-beside `Bucket` and the limiter maths, and is re-exported here: `@ultimat3/query` needs the same
-conversion and is the same tier, so a copy in either package would be a second answer for the
-other. A pair the limiter cannot run on is `X_RATE_LIMIT_INVALID`, at projection. An action that declares nothing
-stays on the `default` bucket. An app that also configures `http.rateLimit.buckets.<actionName>`
-with **different** numbers is `X_RATE_LIMIT_BUCKET_CONFLICT` at boot: neither source wins, because
-the loser would go on being read as enforced.
+beside `Bucket` and the limiter maths, and is imported from there — never re-exported here (25.0.0
+dropped that second path): `@ultimat3/query` needs the same conversion and is the same tier, so a
+copy in either package would be a second answer for the other. A pair the limiter cannot run on is `X_RATE_LIMIT_INVALID`, at projection. The route says
+`rateLimitedBy: 'handler'`, so the pipeline's stage spends no caller bucket for it — not `default`,
+which would cap an action declaring more than it — and only the tenant allowance. An
+`http.rateLimit.buckets.<actionName>` entry is a different table: it neither conflicts with nor
+loosens what the action declared.
 
 ## `idempotent:` — and where its records live
 
@@ -438,12 +484,47 @@ interpolation broke. Omit the header to run un-keyed; the published `maxLength:
 by the same refusal. An anonymous caller has no identity to narrow to, so anonymous callers of a
 public idempotent action still share a key space: a UUID key is what keeps them apart.
 
-**A failed first attempt is replayed too, not re-run.** `guard()` and the input parse both happen
+**A failed first attempt is replayed too, not re-run.** `guardAction()` and the input parse both happen
 *before* the idempotency gate, so everything it can see throw is post-authorization and possibly
 post-commit: a handler that took the money and then failed its own `output:` schema is the case.
 The reservation is settled as a FAILURE and the retry re-throws it under the first attempt's own
 code. Releasing it there is what made idempotency the cause of a double charge.
 
+**A credential in the answer is never kept at rest.** The record lives a day, and a mutator is
+always idempotent — so a "create an API key" mutator would otherwise leave the plaintext key in
+`x_idempotency.value`. On settle, every value under a key `@ultimat3/core`'s `isRedactedKey` names
+(the table the logger and the audit row use, extended by `defineEnv({ secret: true })`) and every
+`Secret` box is stored as `[redacted]`, at any depth, and the record is flagged `redacted`. The
+first caller still gets the whole answer. A replay of a flagged record is
+`X_IDEMPOTENT_REPLAY_REDACTED` (409) rather than `[redacted]` served as the answer: the first call
+RAN, so read its effect with a query — a fresh key runs the mutation again. An answer with no such
+key is stored and replayed exactly as before — plain data (plain objects, arrays, `Date`,
+primitives) comes back as the same reference. **What the walk cannot vouch for is redacted too**:
+a value with a `toJSON` method, a `Map`, a `Set`, a class instance or a `Date` subclass, because
+`JSON.stringify` would run app code the walk never saw; an own getter is read once and the stored
+copy holds that read. A custom `IdempotencyStore` receives the redacted copy, must declare
+`keepsRedaction: true` (a store without it is a compile error), and must keep `settle`'s required
+fourth argument and hand it back as `IdempotencyRecord.redacted`:
+
+```ts
+import type { IdempotencyStore } from '@ultimat3/action';
+
+// A store that wraps another — a metrics or tracing decorator — passes the flag through.
+export function counted(inner: IdempotencyStore, onSettle: () => void): IdempotencyStore {
+  return {
+    scope: inner.scope,
+    keepsRedaction: true,
+    reserve: (key, requestHash) => inner.reserve(key, requestHash),
+    settle: (key, value, reservationId, redacted) => {
+      onSettle();
+      return inner.settle(key, value, reservationId, redacted);
+    },
+    release: (key) => inner.release(key),
+    get: (key) => inner.get(key),
+  };
+}
+```
+
 **The stored payload fingerprint is keyed.** `requestHash` is `keyedFingerprint(input, …)` from
 `@ultimat3/core`: `h1:<key id>:<HMAC-SHA-256/128>` under a key derived from the app's signing
 secret (`ULTIMATE_CURSOR_SECRET` / `configureCursorSigning`), never a bare hash — the row lives a
@@ -464,6 +545,7 @@ no record and runs the handler again:
 import {
   configureIdempotency,
   postgresIdempotencyStore,
+  requestDeadlineMs,
   setIdempotencyStore,
 } from '@ultimat3/action';
 import { db } from '@ultimat3/db';
@@ -478,6 +560,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' });
@@ -489,15 +575,16 @@ opens. The table is `SQL_IDEMPOTENCY_TABLE`, applied the way `SQL_JOBS_TABLE` is
 development, the release-phase `ROLE=migrate` in production. `postgresIdempotencyStore(...)
 .purgeExpired()` is the sweep — Postgres forgets nothing on its own, so run it from a `task`.
 
-**A plain mutating `route` can use the same gate.** `withIdempotency`, `IDEMPOTENCY_HEADER`,
-`idempotencyKeyFor` and `getIdempotencyStore` are all public, so a route that is not an action
-reserves and replays through the one implementation rather than growing a second:
+**A plain mutating `route` can use the same gate.** `withIdempotency`, `idempotencyKeyFor` and
+`getIdempotencyStore` are public here and `IDEMPOTENCY_HEADER` is `@ultimat3/core`'s (imported from
+core — 25.0.0 dropped this package's re-export, and `BUILD_ID_HEADER`'s with it), so a route that is
+not an action reserves and replays through the one implementation rather than growing a second:
 
 ```ts
 const key = req.header(IDEMPOTENCY_HEADER);
 // No header is the caller declining idempotency; a BLANK one is not, and
 // `idempotencyKeyFor` refuses it below rather than filing a record everyone shares.
-if (key === null) return json(await refund(input));
+if (key === null) return jsonResponse(await refund(input));
 const outcome = await withIdempotency(
   getIdempotencyStore(),
   // Namespaced by action AND actor: otherwise two routes share one caller's key, and two
@@ -514,12 +601,32 @@ 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
 
 ```ts
-import type { Deprecation } from '@ultimat3/action';
+import type { Deprecation } from '@ultimat3/core';
 
 // The `deprecated:` key of an `action()`.
 const deprecated: Deprecation = {
@@ -536,6 +643,9 @@ operation, and a `deprecated_calls_total{primitive,name}` counter — which is t
 answer "is anyone still calling it?" before deleting it. A date that cannot be rendered is
 `X_ACTION_DEPRECATION_INVALID` at projection, not on the first request.
 
+`Deprecation`, `renderDeprecation` and `recordDeprecatedCall` are `@ultimat3/core`'s and are
+imported from there — this package does not re-export them (`As of 25.0.0`).
+
 **Versioning itself is deliberately absent, and will stay absent.** Running `v1` and `v2` of one
 action side by side is two deployments behind one ingress — axiom 7's answer, costing this package
 no router feature, no path prefix and no second registry. What ships is the window: a date, a
@@ -549,7 +659,7 @@ price change are not the same event, and the framework is not the thing that kno
 them your business has to keep.
 
 ```ts
-import { setAuditSink } from '@ultimat3/action';
+import { setAuditSink } from '@ultimat3/core';
 
 setAuditSink({
   async write(record) { await record.ctx.db.auditRows.insert(myRow(record)); },
@@ -561,14 +671,19 @@ What the framework supplies is what it genuinely knows:
 | Field | |
 |---|---|
 | `at` | when the attempt began, from `ctx.now()` — an instant, never a rendering |
-| `action` / `mutator` | the registered name, and which primitive it was |
-| `surface` | `server` \| `http` \| `mcp` \| `job` — the same price change over MCP is not the same event |
+| `name` / `primitive` / `mutator` | the registered name; `'action'` (or `'query'` for an audited read); and whether `mutator()` built it. `name` and `primitive` are required, and the `action` alias of `name` is gone (`As of 25.0.0`) — `postgresAuditSink` still files `name` in the `x_audit.action` column |
+| `surface` | `server` \| `http` \| `mcp` \| `job` (and `live` on a read) — the same price change over MCP is not the same event |
 | `ctx` | the whole context: actor, `requestId`, `traceId`, locale, and the services a sink needs to write a row |
 | `input` | the **parsed** input, or `undefined` when the parse is what failed — never the raw payload |
 | `idempotencyKey` / `replayed` | the namespaced key, and whether this was a call rather than a write |
 | `outcome` | `allowed` \| `denied` \| `failed` |
 | `failure` | the `X_*` code and the thrown value, on every outcome but `allowed` |
 
+**One contract, one sink, shared with reads.** `AuditRecord`, `AuditSink` and the installed slot
+are `@ultimat3/core`'s, and so is the one way to install it: `setAuditSink` from `@ultimat3/core`
+(this package re-exports the two types, never the slot — `As of 25.0.0`) installs the sink `query({ audit: true })` writes to as well (`@ultimat3/query`'s README). A sink
+tells the two apart by `record.primitive`.
+
 What it does **not** supply: an audit entity, a retention policy, a hash chain, a subject index,
 or an opinion on what "who" means under impersonation. Four apps model those four ways; shipping
 one would make three of them wrong.
@@ -587,7 +702,8 @@ is `setAuditSink(memoryAuditSink())`, and nothing at that call site says the res
 
 ```ts
 // apps/web/server.ts — the app owns the connection, so the app installs the sink
-import { postgresAuditSink, setAuditSink } from '@ultimat3/action';
+import { postgresAuditSink } from '@ultimat3/action';
+import { setAuditSink } from '@ultimat3/core';
 import { db } from '@ultimat3/db';
 
 const client = db();
@@ -609,7 +725,7 @@ the actor, the correlation ids, the idempotency key — and the parsed `input` a
 through **core's own** `isRedactedKey` table, the one `defineEnv({ secret: true })` extends. So a
 value that renders `[redacted]` in a log line cannot be plaintext in the audit table, and a
 boxed `Secret` is redacted by value wherever its key sits. What never reaches a column: the `Ctx`
-itself (`createContext` spreads every installed service onto it, and an HTTP surface's is a
+itself (`ctxOf` spreads every installed service onto it, and an HTTP surface's is a
 `RequestContext` carrying the caller's `Authorization` and `Cookie`), and the thrown value behind
 a failure — the row keeps `failure.code`, never the throwable.
 
@@ -617,7 +733,7 @@ The table has **no purge**, deliberately, and it is the one framework table that
 stale idempotency row is meaningless while a stale audit row *is* the record, and "how long" is a
 legal answer that differs per app. Pruning or partitioning `x_audit` is yours.
 
-A denial is recorded because `invoke` wraps the whole path — `guard` throws **before** `handle`,
+A denial is recorded because `invoke` wraps the whole path — `guardAction` throws **before** `handle`,
 so nothing you could write around your own handler would ever see one. That is the reason this
 lives in the framework and the row does not.
 
@@ -668,7 +784,7 @@ setAuditSink({
     const prev = await chainHead(ctx);                  // hash-chained: the app's choice
     await ctx.db.auditRows.insert({
       orgId: orgOf(ctx.actor),                          // tenancy: derived from the actor
-      subjectId: subjectOf(record.action, record.input),// queryable by subject: the app's index
+      subjectId: subjectOf(record.name, record.input),  // queryable by subject: the app's index
       actorId: impersonatorOf(ctx.actor) ?? ctx.actor.id,
       at: record.at, outcome: record.outcome, code: record.failure?.code ?? null,
       prevHash: prev, hash: await sha256(prev, record),
@@ -685,7 +801,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 +832,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 +880,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,11 +1,11 @@
 {
   "name": "@ultimat3/action",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
-    "./src/errors.ts"
+    "./src/error-titles.ts"
   ],
   "repository": {
     "type": "git",
@@ -28,18 +28,19 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "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": "25.0.0",
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/db": "25.0.0",
+    "@ultimat3/entity": "25.0.0",
+    "@ultimat3/http": "25.0.0",
+    "@ultimat3/policy": "25.0.0",
+    "@ultimat3/schema": "25.0.0"
   }
 }