@ultimat3/action 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -1,11 +1,13 @@
 # @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
 
-- 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`.
 
@@ -26,55 +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` |
-| `audit.ts` | the audit seam: `AuditRecord`, `AuditSink`, the installed-sink store |
+| `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'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
@@ -98,6 +104,9 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   unchanged** — an upgrade must not make a committed contract stale by itself.
 - Registration names the action the app exported, in place. Naming an already-named action is the
   only case that twins.
+- **A mutator declares `idempotent: true` or does not exist**: required by `MutatorDef`, and
+  `X_MUTATOR_NOT_IDEMPOTENT` at `mutator()` for anything else. The client replays a mutator's write
+  under one key; `transition()` and `x g mutator` declare it. Never a default.
 - A mutator projects `.local`, `.server`, `.conflict` plus every action member — no aliases.
   `mutator.server()` calls the action's own callable (lands in `invoke`); `.local()` never leaves the
   client.
@@ -110,7 +119,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.
 
@@ -145,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).
@@ -157,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
@@ -169,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
 
@@ -201,22 +222,47 @@ 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,
+  `settle(key, value, reservationId, redacted)` / `fail(key, failure, reservationId)`. A fenced no-op is logged,
   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
   `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.
@@ -225,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
@@ -234,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