@ultimat3/action 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -1,6 +1,7 @@
 # @ultimat3/action
 
-Owns the `action` + `mutator` primitives and their six projections. Tier 3.
+Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP tool is
+`@ultimat3/mcp`'s one projection (O-tool, 25.0.0).
 
 ## Boundary
 
@@ -27,57 +28,59 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `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`) |
+| `errors-http.ts` | the three HTTP-declaration refusals |
+| `error-titles.ts` | every code's title, the one `registerErrorCodes` |
 | `client.ts` | typed RPC client (browser-safe: no server imports) — dispatches through core's `clientTransport` |
 | `record-wire.ts` | the record envelope on the HTTP projection: `carriesRecords` (from the output schema), the enveloped 200, and its OpenAPI shape. Server-only — `client.ts` never imports it |
 | `wire-issues.ts` | the ONE reader of a problem document's `issues` member — an untrusted array back into `@ultimat3/schema`'s `ValidationIssue` shape |
 | `transition.ts` | `transition()`: a MUTATOR factory over one entity column's state machine. Declares no error code — entity's three propagate |
-| — | opt-in flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported from `src/index.ts`. There is no local copy and must not be one |
-| `wire-headers.ts` | `BUILD_ID_HEADER` + `IDEMPOTENCY_HEADER`, and nothing else. Their own module so `client.ts` can name them without importing `http.ts` |
-| `mcp-tool.ts` | MCP descriptor, same `invoke` |
+| — | opt-in flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, imported from core — `src/index.ts` re-exports only the `ClientFlight`/`ClientRetry` types. There is no local copy and must not be one |
 | `job-handle.ts` | the `.job()` projection: an action as a queueable payload. **Not** consumed by `@ultimat3/jobs` — see Invariants |
 | `contract-test.ts` | assertions `x g action` emits |
 | `sample-input.ts` | a value `input:` accepts, from its own IR — what makes the policy assertion reach a policy |
 | `idempotency.ts` | the store SEAM: types, the installed-store slot, the scope declaration + `assertIdempotencyScope`, and `withIdempotency` — the replay-or-run gate |
 | `idempotency-key.ts` | the namespaced key — action + actor + the caller's key, as one JSON tuple — and the refusal of one that names no request |
 | `idempotency-memory.ts` | the process default: bounded, swept, `scope: 'process'` |
+| `idempotency-redact.ts` | `restingAnswer` — the copy of an answer a store may keep: core's `isRedactedKey` + `isSecret`, the SAME reference when nothing is redacted |
 | `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` |
 | `tx-scope.ts` | the open transaction — **the only** file that imports `@ultimat3/db` (`tx-scope.test.ts`): `openCommitScope` (the bust) and `liveTransaction` (the settle) |
+| `rate-limit-gate.ts` | **the one place** a declared `rateLimit:` is spent, and the installed-store slot |
 | `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.ts` | the audit seam's TYPES, re-exported from `@ultimat3/core` (shared with `query`); the slot (`setAuditSink`) is core's alone |
 | `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 |
 | `audit-input.ts` | what may be written DOWN: an `input` redacted through core's table and made JSON-representable on every path |
 | `audit-gate.ts` | **the only** file that calls a sink, and where the two failure policies live |
 | `type-pins.ts` | compile-time assertions `tsc` checks — what the erased view projects, and why `client()` is not part of it |
-| `naming.ts`, `validate.ts`, `json-schema.ts`, `stable.ts` | pure helpers. `stable.ts` is the DOCUMENT serializer plus a re-export of core's `isJsonObject` — the hash form is `@ultimat3/core`'s `canonicalJson`/`fingerprint` |
+| `naming.ts`, `validate.ts`, `json-schema.ts`, `stable.ts` | pure helpers. `stable.ts` is the DOCUMENT serializer (core's `isJsonObject` is imported from core, never re-exported) — the hash form is `@ultimat3/core`'s `canonicalJson`/`fingerprint` |
 
 ## Invariants — execution and authz
 
-- Every surface goes through `invoke`: the policy's actor half (`guardBeforeInput`, 403 before the
+- Every surface goes through `invoke`: the policy's actor half (`guardActionBeforeInput`, 403 before the
   parse), parse input, evaluate policy, handle, parse output. A second
   execution path is the one unforgivable change here.
 - **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
-  `@ultimat3/entity`'s tenant guard reads) must be the identity `guard()` decided about.
+  `@ultimat3/entity`'s tenant guard reads) must be the identity `guardAction()` decided about.
   `invoke-context.test.ts` asserts ambient, `options.actor` and `options.ctx` are one caller.
 - The declaration never leaves `invoke.ts`: `defOf`/`stashDef` are never re-exported from
   `src/index.ts` (`index.test.ts`). An action has no `.def`; outside, read `.input`/`.output`/
   `.policy`/`.mcp` or `describe()`. App code reaches a projection through the action
-  (`publishPost.tool()`); new methods are bound in `facade.ts`.
+  (`publishPost.openapi()`); new methods are bound in `facade.ts`. **No `.tool()`**: it was a second
+  MCP projection beside mcp's `toolFrom` (`index.test.ts`, `type-pins.ts`).
 - **`toRoute` sets `enforcedBy: 'handler'`** — `invoke` is the one evaluation and the only one holding
   the row `def.row` loaded; `meta.policy` stays set. `http.test.ts` counts exactly one evaluation.
-- **`meta.auth` comes from `@ultimat3/policy`'s `admitsAnonymous`** (a walk of the tree, via
-  `policy-gate.ts`), never the root combinator — never a copy here (`@ultimat3/query` needs the same
+- **`meta.auth` comes from `@ultimat3/policy`'s `admitsAnonymous`** (a walk of the tree, imported
+  from `@ultimat3/policy` by `http.ts`; 25.0.0 dropped this package's re-export, `index.test.ts`
+  pins the absence), never the root combinator — never a copy here (`@ultimat3/query` needs the same
   answer).
 - Authz goes through `enforce(surface, policy, { input, actor, ctx })`; a denial becomes
   `ActionDeniedError`, keeping the policy's code. `policy-gate.ts` is the only RUNTIME edge to
   `@ultimat3/policy` (`errors.ts`'s `import type { SurfaceDenial }` erases).
 - No policy at registration → `X_ACTION_POLICY_MISSING`. No exceptions, no flag.
 - **`registerAction` guards the derived PATH as well as the name** (`X_ACTION_PATH_DUPLICATE`; a
-  second index cleared by `resetRegistry`).
+  second index cleared by `resetActions`).
 - **A path is the app's `pathStyle` or the action's pin, never a third answer** (`http-path.ts`).
   `'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
@@ -117,7 +120,7 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 - **`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; `id` is the key `output.id` declares (`keySchemaOf`), never a fixed
-  `t.uuid`.
+  `t.uuid`; `row` goes to `mutator()` as declared, never loaded here (#687).
 - **A lookup table is read with `Object.hasOwn`** (`IRREGULAR` in `naming.ts`, `BY_FORMAT` in
   `sample-input.ts`) — caller- or provider-supplied keys.
 
@@ -152,11 +155,21 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   `json-schema.ts`). The HASH form is core's `canonicalJson`/`fingerprint` (injective: tags
   `NaN`/`±Infinity`/`-0`, `Date`, `Map`, `Set`); `stable.test.ts` pins byte-equality for ordinary
   payloads.
-- **`tagKeys` is `@ultimat3/cache`'s and `toBucket` is `@ultimat3/http`'s** (re-exported; raises
-  `X_RATE_LIMIT_INVALID`). Never restore a local copy; never use `@ultimat3/render`'s `tagKeys`.
-- **`rateLimit:` reaches the limiter**: `toRoute` sets `meta.rateLimit` AND `meta.rateLimitBucket`
-  (`toBucket`), which `@ultimat3/http`'s `withRouteBuckets` registers. The computed rate must be
-  finite and `limit` at least one token.
+- **`tagKeys` is `@ultimat3/cache`'s and `toBucket` is `@ultimat3/http`'s** (imported, never
+  re-exported; `toBucket` raises `X_RATE_LIMIT_INVALID`). Never restore a local copy.
+- **`rateLimit:` is spent ONCE, inside `invoke`** (`rate-limit-gate.ts`), so HTTP, MCP, the agent
+  tool and `.job()` share one bucket; `surface: 'server'` spends nothing. `toRoute` sets
+  `rateLimitedBy: 'handler'` and NO `meta.rateLimit`/`rateLimitBucket` — the stage spends neither
+  the action's bucket (the old HTTP-only point) nor `default`. Key `action:<name>|<subject>`.
+  HTTP gets `RateLimit-*` via `onRateLimit` → http's `publishRateLimit`. The store is
+  `@ultimat3/http`'s installed one, adopted by the boot on every role. Spent after
+  `guardActionBeforeInput`, BEFORE the parse and `def.row()` (an input/row-denied flood is refused). A key
+  the idempotency store holds spends nothing (replay); a reservation `withIdempotency` CREATES that
+  the peek did not pay for spends in `beforeRun`, released on refusal. A job run is charged to its
+  org, else `job:unattributed`. A surface's `clientAddress` is inherited by nested `invoke`s
+  (`withCallerAddress`); a `'job'` invoke opens a fresh frame (`withJobFrame`) so no visitor's
+  address follows work into the worker, and calls nested in it are the job's.
+  `rate-limit-surfaces.test.ts`. The computed rate must be finite and `limit` at least one token.
 - **`deprecated:` is a compat WINDOW** — headers on every response including failures, a
   `rel="successor-version"` link via `derivePath`, `deprecated: true` in OpenAPI,
   `deprecated_calls_total`. Rendered ONCE at projection (`X_ACTION_DEPRECATION_INVALID` at mount).
@@ -164,11 +177,11 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 - **The span wraps `execute` whole** (including `def.row()`), with bounded attributes plus the
   namespaced idempotency key (never a metric label). `telemetry.test.ts`.
 - **`policyCapability` is a display label; `policyPermissions` (`ActionDescriptor.permissions`) is
-  what a report matches on** (a `not()` clause contributes its permissions).
-- **MCP exposure reads core's `isMcpExposed`, in all three places** (`toMcpTools`, `describeAction`,
-  `x-ultimate.mcpTool`). **A tool's NAME is the export name verbatim everywhere** — `toToolName` is
-  deleted; `mcp-tool.test.ts` asserts one verbatim name across surfaces. `ActionFact.mcp` in the app
-  manifest carries only `{ expose, description? }`.
+  what a report matches on** (a `not()` clause contributes its permissions). Both are
+  `@ultimat3/policy`'s, imported from there.
+- **MCP exposure is core's `isMcpExposed`** (`describeAction`, `x-ultimate.mcpTool`); **a tool's
+  NAME is the export name verbatim** (`mcp-surface.test.ts`). `ActionFact.mcp` in the app manifest
+  carries only `{ expose, description? }`.
 - **`ActionJobHandle` is not consumed by `@ultimat3/jobs`** (`isJobHandle` needs `job()`'s private
   map). `.job()` gives `action:<name>` as a queue key, a payload-derived idempotency key and an
   `invoke` under `surface: 'job'`. The bridge is `agentJob()` in `@ultimat3/ai`, or an app's own
@@ -176,24 +189,25 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 
 ## Invariants — flight control
 
-- **Flight control is `@ultimat3/core`'s, re-exported** — the same objects `@ultimat3/query`
-  exports. Fix the pipeline in `packages/core/src/client-flight.ts`. No new code, curve, fence or
-  retry loop here (`bun run flight-copies`).
+- **Flight control is `@ultimat3/core`'s, and NOT re-exported** — its values are imported from
+  core (`X_HELPER_COPY` refuses a re-export); only the types `ClientFlight`/`ClientRetry`. Fix the
+  pipeline in `packages/core/src/client-flight.ts`. No new code, curve, fence or retry loop here (`bun run flight-copies`).
 - **`isTransientFailure` INVERTS `retryDecision`'s unclassified default** (a caller's `AbortError`
   is terminal). Must survive.
 - **`ClientFlight` is a TYPE inside `client.ts`, never a value.** Measured,
   `bun build --target=browser --minify`, one entry importing from `@ultimat3/action` — **the ONE
   table for these figures** (`packages/core/CLAUDE.md` points here):
 
-  | Entry | before (HEAD `98d16d84`) | onto `clientTransport` | trace headers moved to core's outbound slot | As of 2026-09-23 |
-  |---|---|---|---|---|
-  | `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 |
+  | Entry | `As of 2026-10-01` |
+  |---|---|
+  | `rpc` | 19,671 B (+181 B for the document's path-style stamp) |
+  | `rpc` + core's `clientFlight` | 25,954 B |
 
-  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`.
+  Earlier columns (pre-transport 18,097 B, +977 B net for the envelope decoder) are in git history.
+- **`sideEffects` is `["./src/error-titles.ts"]`**, never `false` (drops its bare imports): the
+  titles ride into every barrel chunk (`problemError` decodes by code), `errors.ts`'s classes do
+  not. An http refusal needs no http module: core's decoders take its title off the body and its
+  `retry-after` off the header (`rpc-refusal.test.ts`).
 
 ## Invariants — idempotency
 
@@ -208,8 +222,17 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   inside `withWriteOrigin(writeDigest(key))` so the page recognises its own `records` echo. A label,
   never a gate.
 - **Both stores FENCE a settlement on the reservation `id` AND `in-flight`**:
-  `settle(key, value, reservationId)` / `fail(key, failure, reservationId)`. A fenced no-op is logged,
-  never thrown.
+  `settle(key, value, reservationId, redacted)` / `fail(key, failure, reservationId)` /
+  `release(key, reservationId)`. A fenced no-op is never thrown.
+- **An answer rests REDACTED** (#591): `withIdempotency` passes the store `restingAnswer(value)`
+  (core's `isRedactedKey` + `isSecret` — never a second rule) and `redacted` as `settle`'s
+  REQUIRED 4th argument; both stores keep it (`x_idempotency.redacted`, memory's record field).
+  A flagged replay is `X_IDEMPOTENT_REPLAY_REDACTED`, decided by the FLAG, never by scanning for
+  `[redacted]`. Plain data is the same reference, replayed as before; anything else that
+  `JSON.stringify` would run app code on (`toJSON`, `Map`/`Set`, class instances, `Date`
+  subclasses) is redacted FAIL-CLOSED, and a getter is read once. `keepsRedaction: true` is a
+  required store declaration (`type-pins.ts`: a pre-25 store is a build error — a required
+  parameter alone is not). A reclaim and a `fail` reset the flag.
 - **A stored status is NARROWED** (`isIdempotencyStatus`; unknown is
   `X_IDEMPOTENCY_STATUS_UNKNOWN`), never cast.
 - **Where records live is DECLARED and refused at registration**: `IdempotencyStore.scope` vs
@@ -248,6 +271,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   DENIED attempt is recorded. No audit entity, retention, hash chain or "who" convention. The
   vocabulary matches `@ultimat3/admin`'s by name (tier 5, no edge); admin's `AuditSink` is a known
   duplicate that unifying would need core for.
+- **Records carry `name` + `primitive`, required** (`type-pins.ts`); no `action` alias since 25.0.0.
+  The `x_audit.action` column holds `name`.
 - **The memory sink DROPS** — a ring at `DEFAULT_MAX_AUDIT_RECORDS`, oldest first, counting `dropped`;
   no spelling of "unbounded".
 - **A durable sink writes what `audit-input.ts` allows**: input redacted through core's
@@ -257,7 +282,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   `locale`, `tz`, `buildId`, `role`, actor `id`/`kind`/`orgId`/`onBehalfOf`) and keeps
   `failure.code`, never the error.
 - **`x_audit` ships no purge**, deliberately. **`SQL_AUDIT_INSERT` is positional**, pinned by
-  `audit-parity.test.ts` with a distinct value per field.
+  `audit-parity.test.ts` with a distinct value per field. Only `*_TABLE` DDL is exported
+  (`X_SQL_EXPORT_UNREAD`).
 - **The two failure policies are opposites**: `X_AUDIT_SINK_MISSING` before the input parse (no
   logger-backed default sink); a sink refusing an ALLOWED record is `X_AUDIT_SINK_FAILED`, whose `fix:`
   branches on `record.idempotencyKey !== null` (`meta.replayable`); a sink refusing a denied or failed

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 |
@@ -308,8 +311,8 @@ no bypass flag. A look-alike that never came out of `action()` is `X_ACTION_FORE
 
 ## 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
@@ -407,6 +410,7 @@ await moveOrder({ id, from: 'pending', to: 'paid' }, { ctx });
 | `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` |
+| a row-level `policy` gets its row from **`row`** | the action's own loader, handed through: `row: ({ input, ctx }) => posts(ctx).find(input.id)`, then `can<TransitionValues<S>, Post>('post:move', ({ actor, row }) => row !== null && row.authorId === actor?.id)`. Loaded once, after the input parse, before the guard and the statement; the factory reads no row itself. Omitted, the rule sees `row: null` and must fail closed. **Check-then-act**, as every row-policy action's: the read is unlocked and outside any transaction, and the move's predicate is `id` + `from` only, so a concurrent change to a column the rule read (an `authorId` reassigned in between) is not seen. Where that matters, write an `action` whose handler opens `withTransaction`, reads the row `for update`, decides and calls `Table.transition` inside it |
 | `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 — a real `Table` satisfies the
@@ -427,17 +431,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
 
@@ -455,12 +485,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, reservationId) => inner.release(key, reservationId),
+    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
@@ -511,15 +576,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
@@ -536,6 +602,14 @@ 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.
 
+`release` takes it too (`As of 2026-10-07`): it is the pre-handler cleanup when `beforeRun` refuses,
+and keyed alone it DELETED whatever record the key held — a replacement's reservation, or its
+settled answer, so the next retry re-ran a handler that had already committed. A release that
+matches nothing does nothing (`idempotency-release.test.ts`, both stores). **A custom store's
+`release(key, reservationId)` must delete only the record whose id is `reservationId` and whose
+status is `in-flight`** — one that ignores the second argument reopens the double-run window, and
+type-checking cannot catch it: a one-parameter function still satisfies the signature.
+
 **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
@@ -561,7 +635,7 @@ 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 = {
@@ -578,6 +652,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
@@ -591,7 +668,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)); },
@@ -603,14 +680,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.
@@ -629,7 +711,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();
@@ -651,7 +734,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.
 
@@ -659,7 +742,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.
 
@@ -710,7 +793,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),

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ultimat3/action",
-  "version": "24.0.0",
+  "version": "25.1.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,19 +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": "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"
+    "@ultimat3/cache": "25.1.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/db": "25.1.0",
+    "@ultimat3/entity": "25.1.0",
+    "@ultimat3/http": "25.1.0",
+    "@ultimat3/policy": "25.1.0",
+    "@ultimat3/schema": "25.1.0"
   }
 }