@ultimat3/action 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -6,8 +6,7 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 ## Boundary
 
 - 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`).
+  `entity` through `record-wire.ts`; `db` through **`tx-scope.ts` only**. Full rule: `docs/history/action.md`.
 - Never import: `query`, `jobs`, `realtime` (sideways), or any tier 4-5 package.
 - Never re-implement authz, validation or caching — call `policy`, `schema`, `cache`.
 
@@ -20,12 +19,13 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 | `facade.ts` | the fluent surface — binds each projection to the action, re-implements none |
 | `mutator.ts` | action + optimistic `.local` twin + authoritative `.server` + `.conflict` |
 | `registry.ts` | export-name registration, collisions, `describeActions()` |
+| `tool-gate.ts` | a named tool's gate: `mcp` registers, `ai` reads, first wins |
 | `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call, and the `Api` type the typed clients are shaped from |
 | `client-scale-pins.ts` | compile-time pin: `rpc<Api['actions']>` over 300 actions in 100 modules, 100 reads in 50 |
 | `http.ts` | route projection (`enforcedBy: 'handler'`) + OpenAPI operation |
 | `openapi.ts` | deterministic OpenAPI 3.1 document |
-| `openapi-complete.ts` | the COMPLETE document (`defineApi({ openapi })`: info, servers, security schemes, 401/429 by the ROUTE's `meta.auth`) and a bearer mount's own cut |
-| `http-path.ts` | where an action is served: the app's `pathStyle` + a per-action `http.path` pin, read lazily by every projection |
+| `openapi-complete.ts` | the COMPLETE document (`defineApi({ openapi })`: info, servers, security schemes, 401/429 by the ROUTE's `meta.auth`, a declared `rateLimit` or `meter`) and a bearer mount's own cut |
+| `http-path.ts` | where an action is served: the app's `pathStyle` + a per-action `http.path` pin, read lazily by every projection; the pin's `:param` template + `method` (`ACTION_HTTP_METHODS`), `assertPinnedHttp`, `filledRoute`, `pathParametersOf`, `actionHttpPinOf` |
 | `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 |
@@ -33,11 +33,18 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 | `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 |
+| `action-stream.ts` | `streamingDef`: a `stream`-declaring `handle` (an async generator) DRAINED, each chunk parsed by `stream` (`X_ACTION_STREAM_INVALID`, `errors-stream.ts`); `chunksRead()` |
+| `http-stream.ts` | `accept: text/event-stream` → `event: chunk`… then ONE `done` or `error`; a refusal before the handler is the ordinary problem response |
+| `audit-subject-target.ts` | `auditSubjectTarget()`: `x_audit` as a subject-erase target — overwrites who acted and the input, never deletes the row |
 | `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`, 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 |
+| `exercise.ts` | the fourth contract assertion: run loop, verdict, `exerciseContract` |
+| `exercise-errors.ts` | the three `X_CONTRACT_*` classes, off-socket |
+| `declared-errors.ts` | the wrap `invoke` puts around `handle` and `row`, the ONLY judged throws. `errors:` is checked, sorted and frozen at `action()` |
+| `declared-errors-contract.ts` | `.contract()`'s source scan |
+| `openapi-errors.ts` | core's builder bound to http's status and `problemTypeFor` |
 | `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'` |
@@ -45,8 +52,9 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 | `idempotency-postgres.ts` | the SHARED store — one table, one `insert … on conflict` |
 | `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 |
+| `tx-scope.ts` | the open transaction — **the only** file that imports `@ultimat3/db` (`tx-scope.test.ts`): `openCommitScope` (the bust), `liveTransaction` (the settle), `completeTransaction`, and `inRolledBackScope`, the exercise's always-rolled-back scope and the memory transaction it opens always |
+| `rate-limit-gate.ts` | **the one place** a declared `rateLimit:` is spent (a `limit` resolved per call from `ctx`, through `toBucket`) |
+| `meter*.ts`, `errors-meter.ts` | `meter:` — declaration (`meter.ts`), UTC window, store seam + memory + Postgres (`x_meter`), and `meter-gate.ts`, **the one place** it is drawn |
 | `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 |
@@ -60,7 +68,8 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 
 - 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.
+  execution path is the one unforgivable change here. A 5xx keeps a bundle only under core's
+  `withFailureCapture` (`execute`); off, it runs bare.
 - **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
   `@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.
@@ -81,25 +90,11 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - 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 `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
-  under the default). `derivePath(name)` is pin-aware through `installPinLookup` — handed down by
-  `registry.ts`, never imported up (cycle through `action.ts`). `rpc()` cannot see a pin;
-  `action.client()` holds it.
-- **The style is stated ONCE, on the server.** A browser never restates it: the document carries
-  `<meta name="ultimate-path-style">` (render's `clientPathStyleTags`, written only for a
-  non-default style) and core's `actionPath(name)` reads it for every caller naming none — `rpc`,
-  realtime's `useMutation` and the outbox replay. `client.ts` passes `options.pathStyle` through
-  and adds NO default of its own. `ClientOptions.pathStyle` is for a caller with no document; a
-  wrong one is answered `X_CONTRACT_DRIFT` (404) by `explainActionPathMiss`, never
-  `X_ROUTE_NOT_FOUND`. A pinned action and a path under the SERVED style are never explained.
-- **`Merge` in `define-api.ts` never recurses over the module list.** `Head & Merge<Rest>` is not
-  a tail call: it cost one instantiation level per MODULE and answered TS2589 at the 48th entry of
-  one list, whatever each exported (#534). The list is read as a union and intersected in one
-  step. `client-scale-pins.ts` is the build error; `client-scale.contract.test.ts` compiles real
-  `action()`/`query()` modules through `defineApi`'s `const` inference; `@ultimat3/query` pins
-  `QueryClient` itself.
+- **A path is the app's `pathStyle` or the action's pin, never a third answer** (`http-path.ts`). A pin may be a template: `derivePath(name)` refuses one, `actionHttpPath(name, params)` fills it.
+  `'resource'` stays the default. Full rule: `docs/history/action.md`.
+- **The style is stated ONCE, on the server**; a browser reads `<meta name="ultimate-path-style">` through core's `actionPath(name)`. Full rule: `docs/history/action.md`.
+- **`Merge` in `define-api.ts` never recurses over the module list.** `client-scale-pins.ts` is the
+  build error. Full rule: `docs/history/action.md`.
 - **`defineApi({ openapi })` opts into the complete document; absent, `openapi.json`'s bytes are
   unchanged** — an upgrade must not make a committed contract stale by itself.
 - Registration names the action the app exported, in place. Naming an already-named action is the
@@ -118,15 +113,29 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   built from the registrars' results, never the modules' exports.
 - `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; `id` is the key `output.id` declares (`keySchemaOf`), never a fixed
-  `t.uuid`; `row` goes to `mutator()` as declared, never loaded here (#687); **the rule's reads
-  are pinned in the move** (#702, `transition-observe.ts`: `def.row`, `def.handle` share `input`).
-- **A lookup table is read with `Object.hasOwn`** (`IRREGULAR` in `naming.ts`, `BY_FORMAT` in
-  `sample-input.ts`) — caller- or provider-supplied keys.
+  codes propagate; `from` is REQUIRED (it is the UPDATE's predicate); **the rule's reads are pinned in
+  the move** (`transition-observe.ts`). Full rule: `docs/history/action.md`.
+- **A lookup table is read with `Object.hasOwn`** (`IRREGULAR` in `naming.ts`).
+- **`handlerReached(target)` in `invoke.ts` is a private per-declaration counter, never on the
+  barrel.** `exercise.ts` reads it to tell a run that reached `handle` from one stopped before it.
+- **The exercise has no bypass.** A coded 5xx, `X_OUTPUT_INVALID` or an uncoded
+  throw is `X_CONTRACT_DEFECT`. Full rule: `docs/history/action.md`.
 
 ## Invariants — the wire
 
+- **A streaming action is still ONE action through `invoke`** (`StreamAction`, `action({ stream })`):
+  `invoke` stores the declaration draining, so MCP, `.job()`, `.as()` and JSON get the RETURN value.
+  Only the first draining handler of THE declaration a stream was opened for gets the sink;
+  `chunksRead()` is `true` there alone, so a costly chunk is produced only when read.
+- **`.stream(input)` is on every typed-client method; the TYPE offers it only where the action
+  streams** (`StreamClientMethod`; the `rpc` proxy cannot see a declaration). `POST` through core's
+  `clientStream`, never `EventSource`; never retried (`retry` is not an option); a JSON answer is
+  the output.
+
+- **A `:param` pin's values come from the router's decoded params, merged into the input before
+  `invoke`** (`toRoute` → core's `mergePathParams`). A body naming the key differently is
+  `X_HTTP_PATH_INPUT_CONFLICT`, never overridden. `registerAction`'s duplicate index keys on method
+  + path. `http-path-params.test.ts`.
 - **Every browser call goes through core's `clientTransport`**: `client.ts` hands it the method, the
   URL (core's `actionPath`; `naming.ts` re-exports core's path helpers), body, headers, signal, key,
   flight and `retry`. Only action-specific hooks ride in: `onResponse` (build-id check,
@@ -141,14 +150,9 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - **`conflict` is core's `ConflictPolicy`, over ROWS**; `custom(merge)` builds
   `{ kind: 'custom', merge(localRow, serverRow) }`; core's `resolveConflict` is the one resolver.
 - **`X_INPUT_INVALID` carries the rejections twice**: the line in `cause`
-  (`formatIssues(issues).join('; ')`, pinned by `validate.test.ts`) and `meta.issues` structured.
-  The rendering stays out of `InputInvalidError` (browser-reachable). **`toValidationIssues`** keeps
-  four members, never a library's raw issue (it may carry the value). `issuesFromWire` rebuilds
-  member by member, all-or-nothing, bounded by `MAX_WIRE_ISSUES`. **`X_OUTPUT_INVALID` keeps the line alone.**
+  (`formatIssues(issues).join('; ')`, pinned by `validate.test.ts`) and `meta.issues` structured. Full rule: `docs/history/action.md`. **`X_OUTPUT_INVALID` keeps the line alone.**
 - **The client keeps the server's code and marks it remote** (`RemoteActionError`, `meta.origin:
-  'remote'`), only for an `X_SCREAMING_SNAKE` code. It never synthesizes a docs URL: the server's
-  `http(s)` `docs`/`type` (as an ordered pair), else this build's registered link, else
-  `ERROR_DOCS_URL`.
+  'remote'`), only for an `X_SCREAMING_SNAKE` code. It never synthesizes a docs URL. Full rule: `docs/history/action.md`.
 - **Both clients inject `traceparent`** before the caller's headers; an incomplete span sends nothing.
 - `serializeOpenApi` output is byte-stable: sorted keys, sorted registry, no clock. `client.ts` stays
   free of server imports.
@@ -158,28 +162,14 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   payloads.
 - **`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).
-  Twinned in `@ultimat3/query`.
+- **`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. Full rule: `docs/history/action.md`.
+- **`meter:` is drawn ONCE, inside `invoke`, on every surface (`server` too)**, after the policy, before `handle`; under a key only in `beforeRun`, so a replay draws nothing. One conditional increment, never read-then-write. Periods are UTC. `meter-surfaces.test.ts`. Subject: org, else actor, else `job:unattributed` inside a job frame (`inJobFrame()`, `rate-limit-gate.ts` — the limiter's split, one answer), else `anonymous`. `meter-memory.ts` evicts a counter whose period ENDED before a live one, then oldest start.
+- **`deprecated:` is a compat WINDOW**, rendered ONCE at projection
+  (`X_ACTION_DEPRECATION_INVALID`); twinned in `@ultimat3/query`. Full rule: `docs/history/action.md`.
 - **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). Both are
-  `@ultimat3/policy`'s, imported from there.
+  what a report matches on**; both `@ultimat3/policy`'s.
 - **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? }`.
@@ -199,10 +189,10 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   `bun build --target=browser --minify`, one entry importing from `@ultimat3/action` — **the ONE
   table for these figures** (`packages/core/CLAUDE.md` points here):
 
-  | Entry | `As of 2026-10-01` |
+  | Entry | `As of 2026-11-06`, Bun 1.4.4, one entry over the working tree |
   |---|---|
-  | `rpc` | 19,671 B (+181 B for the document's path-style stamp) |
-  | `rpc` + core's `clientFlight` | 25,954 B |
+  | `rpc` | 29,291 B: `.stream` (core's `clientStream`, through `dispatchStream`) +1,746 B over the 27,545 B before it; pinned paths (wave 5b) `fillWire` +758 B, `renderedActionPin` +619 B (each stubbed out) |
+  | `rpc` + core's `clientFlight` | 38,054 B |
 
 - **`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
@@ -214,6 +204,7 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - **Everything `withIdempotency`'s `run` throws is treated as possibly-committed**: the reservation
   is SETTLED as a failure and a retry replays it; `release()` is only for a pre-handler failure. A
   `settle` that refuses leaves the record in flight. `idempotency-failure.test.ts`.
+- **A keyed run is owed its end**: `completeTransaction()`, then `runToCompletion(run)` under `idempotencyCeilingMs()` (`X_IDEMPOTENCY_RUN_CEILING`); `invoke` reads the handler's `ctx` inside it. `idempotency-orphan.test.ts`.
 - **A record belongs to ONE CALLER**: the key is
   `JSON.stringify([action, actor.kind, actor.id, actor.orgId ?? null, key])` — a JSON tuple, never a
   joined string. A blank header is `X_IDEMPOTENCY_KEY_INVALID` (4xx, before the handler), never "no
@@ -225,14 +216,9 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
   `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.
+  (core's `isRedactedKey` + `isSecret`) and `redacted` as `settle`'s REQUIRED 4th argument. A
+  flagged replay is `X_IDEMPOTENT_REPLAY_REDACTED`, by the FLAG, never by scanning. Full rule: `docs/history/action.md`.
+- **A finished record skips the row half; a stale peek judges it in `beforeRun`** (`idempotency-row.test.ts`). **A `bigint` answer settles failed** (`X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE`).
 - **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
@@ -241,56 +227,37 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t
 - **The memory store is bounded; `in-flight` records are the last evicted.** Never an LRU.
 - **`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`.
+- **Inside a transaction the SETTLE commits with the write, on BOTH stores** (`liveTransaction()`). `idempotency-parity.test.ts`. Full rule: `docs/history/action.md`.
 - **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.
+  reservation (`requestDeadlineMs`, never a number here); `origin: () => object` is required too. Full rule: `docs/history/action.md`.
 
 ## 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.
+  skips the bust. **A started handler busts, thrown or not.**
 - **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).
+  dropped on rollback, never fired before the rows are durable. Full rule: `docs/history/action.md`.
 - **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`).
+  `code` pattern (`openapi-problem.test.ts`), checked both ways; `retry` is an enum of core's `ERROR_RETRY_KINDS`.
 - **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.
-  `contract-test.contract.test.ts`.
+  the input IR). Full rule: `docs/history/action.md`.
 - **The audit seam ships the mechanism and none of the row**: `audit: true` wraps `execute`, so a
-  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
-  `isRedactedKey` (the table `defineEnv({ secret: true })` extends) plus `isSecret` by value, and
-  always JSON-representable (named markers, cycle detection; `toJSON` never called).
+  DENIED attempt is recorded. No audit entity, retention, hash chain or "who" convention. Full rule: `docs/history/action.md`.
+- **`invoke` masks `trace.input` with `maskSensitive(def.input, …, REDACTED)` only when `audit: true`**;
+  `registerAction` calls `assertNoSensitiveOutput` on `output`. `wire-issues.ts` and
+  `PROBLEM_SCHEMA` carry `rule` and `params` (the four members stay `required`).
+- **A durable sink writes what `audit-input.ts` allows**. Full rule: `docs/history/action.md`.
 - **The `Ctx` is never walked**: `postgresAuditSink` reads an allow-list (`requestId`, `traceId`,
   `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. 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
-  record is logged (`audit.sink.failed`) and the original error still reaches the caller.
+- **The two failure policies are opposites**: `X_AUDIT_SINK_MISSING` before the input parse; a sink refusing an ALLOWED record is `X_AUDIT_SINK_FAILED`; refusing a denied or failed one is logged. Full rule: `docs/history/action.md`.
 - **`auditSettled` sits outside the `catch`**, and **`auditOutcomeFor` is TOTAL** (fails closed to
   `failed`); `audit.test.ts` asserts the caller's throwable by identity.
-- **`json-schema.ts`'s refusal names `introspect()`** (`normalizeJsonSchema`, test-only export).
 
 ## Commands
 

package/README.md

@@ -3,6 +3,8 @@
 One declaration → six artifacts. Five are projected here; the MCP tool is `@ultimat3/mcp`'s
 (tier 4), from the same declaration.
 
+`bun add @ultimat3/action` · guide: [Actions](https://github.com/developerz-ai/ultimate/wiki/Actions)
+
 | # | Artifact | Reach it with | Guarantees |
 |---|---|---|---|
 | 1 | HTTP route `POST /api/<resource>/<verb>` | `toRoute(publishPost)` — the server mounts it | policy + validation + idempotency + invalidation, non-optional |
@@ -10,7 +12,7 @@ One declaration → six artifacts. Five are projected here; the MCP tool is `@ul
 | 3 | Typed RPC client | `publishPost.client({ baseUrl })` / `rpc<Api['actions']>()` | server typo = compile error in Solid |
 | 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 |
+| 6 | Contract tests | `publishPost.contract({ exercise: { actor } })` | garbage rejected, anonymous denied, spec present, the handler survives generated legal input |
 
 ## The fluent surface
 
@@ -26,7 +28,7 @@ await publishPost.as(actor, { postId })        // run as someone, one execution
 publishPost.openapi()                          // OpenAPI operation
 publishPost.client({ baseUrl })                // typed RPC method
 publishPost.job()                              // durable-work handle
-publishPost.contract()                         // the three generated assertions
+publishPost.contract({ exercise: { actor } }) // the four generated assertions
 ```
 
 There is no `.tool()` (`As of 25.0.0`): it was a second MCP projection built a tier below the
@@ -167,6 +169,25 @@ Importing `rpc` alone from this package is **19,671 B** minified for the browser
 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.
 
+## Streaming — `stream:`
+
+An action may answer in pieces before it answers. `stream: <chunk schema>` beside an
+`async *handle` whose yields are chunks and whose **return** is the output. One route, chosen by
+`accept`; no channel, no `EventSource`, no second primitive.
+
+| Caller | Gets |
+|---|---|
+| `accept: text/event-stream` on its route | `event: chunk` per yield (each parsed by `stream` first), then one `done` (the output) or `error` (the problem document); `x-accel-buffering: no`, never compressed |
+| JSON, MCP, `.job()`, `.as()`, a direct call | the generator drained: the output alone, one contract |
+| the typed client | `api.sayWords.stream(input)` — an `AsyncGenerator` of chunks whose return is the output, through core's `clientStream` (POST, the page's credentials, the same problem decode). Typed on a stream-declaring method only (`StreamClientMethod`); never retried |
+| the handler itself | `chunksRead()` — `true` only while a caller reads the chunks; `llm()` streams its one-attempt turn then, and is the repairing call otherwise |
+
+A refusal before `handle` starts (policy, input, rate limit) is the ordinary problem response, not
+a stream. A chunk its schema refuses, or `stream:` beside a handle that is not a generator, is
+`X_ACTION_STREAM_INVALID`: one `error` frame, then close. A client that leaves cancels the body and
+aborts `ctx.signal`. Every typed-client method carries `.stream`, because the name-only `rpc` proxy
+cannot see a declaration: +2,064 B per island that uses `rpc` (measured 2026-11-06).
+
 ## Path derivation
 
 One rule per app, declared once — `defineApi({ http: { pathStyle } })` — plus a per-action pin.
@@ -183,9 +204,16 @@ One rule per app, declared once — `defineApi({ http: { pathStyle } })` — plu
   follows for reads. The OpenAPI tag becomes the resource the POLICY names (`can('cases:create')`
   → `cases`), never a noun parsed from `In`.
 - **`http: { path }` pins one action's URL** whatever the style — for a webhook a vendor holds:
-  `action({ …, http: { path: '/api/webhooks/wompi' } })`. Static, lowercase, no params, never
-  `/_x` (`X_ACTION_HTTP_PATH_INVALID`). A pin colliding with another path is
+  `action({ …, http: { path: '/api/webhooks/wompi' } })`. Lowercase, never `/_x`
+  (`X_ACTION_HTTP_PATH_INVALID`). A pin colliding with another path on the same method is
   `X_ACTION_PATH_DUPLICATE` at boot.
+- **A pin may carry `:param`s and a method** — `http: { path: '/orders/:id/refund', method:
+  'PATCH' }` (`ACTION_HTTP_METHODS`: `POST` default, `PUT`, `PATCH`, `DELETE`). Each `:param` is a
+  required `t.string` key of `input:`; the URL's value joins the body before `invoke`, and a body
+  naming it differently is 400 `X_HTTP_PATH_INPUT_CONFLICT` (core's). `actionHttpPath(name, { id })`
+  fills one, `derivePath(name)` refuses it, `action.client()` fills it from the input, and
+  `actionHttpPinOf(action)` is the manifest's `{ path, method }`. OpenAPI: `{id}` `in: path`, the
+  key out of the body component, the operation under its verb.
 - Every server-side reader agrees: `toRoute`, `toOpenApiOperation`, `describeAction`,
   `derivePath(name)` (pin-aware) and `actionHttpPath(action | name)`. A pinned action is called
   through `action.client()`, which holds the pin.
@@ -231,9 +259,9 @@ export const api = defineApi({
   // (cookie; bearer when a mount exists), 401 + 429 (Retry-After) on every authenticated
   // operation, RateLimit-* on rate-limited ones. Absent, the bytes are what they were.
   openapi: {
-    title: 'Notificado API',
+    title: 'Acme API',
     version: '1.0.0',
-    servers: [{ url: 'https://www.notificado.co' }],
+    servers: [{ url: 'https://www.example.com' }],
     sessionCookie: 'session',
   },
 });
@@ -297,7 +325,9 @@ path) and `.as()`/jobs. An audited action's denied attempt still records the par
 `cache: { invalidates }` fans out **after** the handler commits, so it never fails it: a
 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.
+call busts nothing; the first call already did. A handler that **threw** busts too: it may have
+committed, which is why `idempotent` records the same throw. A refused input or policy ran no handler
+and busts nothing.
 
 **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
@@ -446,6 +476,7 @@ call (`surface: 'server'` — a service, a seed, a test) is app code, not a call
 | 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` |
+| a per-call limit | `limit: ({ ctx }) => planOf(ctx).perMinute` — resolved before any bucket is touched, through `toBucket`'s screen (`NaN`/`0`/`Infinity` is `X_RATE_LIMIT_INVALID`); published as `rateLimitPerCall: { windowMs }` and `x-ultimate.rateLimit.limit: 'per-call'` |
 
 ```ts
 import type { PgExecutor } from '@ultimat3/core';
@@ -470,6 +501,25 @@ which would cap an action declaring more than it — and only the tenant allowan
 `http.rateLimit.buckets.<actionName>` entry is a different table: it neither conflicts with nor
 loosens what the action declared.
 
+## `meter:` — a durable per-period allowance
+
+```ts
+import type { ActionMeter } from '@ultimat3/action';
+
+const quotaWarning = { enqueue: async () => undefined }; // in an app: a job({ input: MeterWarning, … })
+
+// 500 calls per tenant per UTC day; one warning per tenant per day at 80%.
+const meter: ActionMeter = { name: 'calls', period: 'day', limit: 500, warnAt: 0.8, onWarn: quotaWarning };
+```
+
+Drawn once per call inside `invoke` (`meter-gate.ts`) on every surface, `server` included, after
+the policy and before `handle`; spent, `X_METER_EXCEEDED` (429, `meta: { meter, limit, resetsAt,
+retryAfterSeconds }`). Counter per `org:<id>` → `actor:<id>` → `anonymous`; periods are UTC and the
+stored key says so (`day@UTC`). An idempotent replay draws nothing. `limit` may be a function of
+`{ ctx }`. Store: `memoryMeterStore()` by default, `postgresMeterStore({ executor })` over `x_meter`
+installed by the CLI boot (one row per counter, rolled over in place, no purge). Full table:
+[Actions → Usage meters](https://github.com/developerz-ai/ultimate/wiki/Actions#usage-meters-meter).
+
 ## `idempotent:` — and where its records live
 
 `idempotent: true` + an `Idempotency-Key` header replays the first **outcome**
@@ -492,6 +542,17 @@ post-commit: a handler that took the money and then failed its own `output:` sch
 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 finished record answers its own retry before any row rule is asked.** A retried delete's row is
+gone, so a rule asked again judges `null` and refuses a write that committed. With a settled or
+failed record under this key, `row:` and the policy's input and row half are skipped; the actor's
+half (`can()` with a permission revoked since) is decided on every call, and the key is this
+actor's alone. Another payload is `X_IDEMPOTENCY_CONFLICT`. In flight or absent, the rule decides.
+
+**An answer no retry could replay is refused, on both stores.** A `bigint` has no JSON form:
+`X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE` (500), settled as a failure and replayed, the handler having
+run. Return `String(id)`. A cycle stays `X_IDEMPOTENT_REPLAY_REDACTED`. `undefined` rests as `null`:
+JSON has no `undefined`, and the action's `output` schema answers for the shape of a replay.
+
 **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
@@ -571,6 +632,8 @@ setIdempotencyStore(
 configureIdempotency({ scope: 'shared' });
 ```
 
+A keyed handler runs past the request deadline on a fresh signal, so its replay answers success, up to a hard ceiling: twice `requestTimeoutMs` by default (`idempotencyCeilingMs()`, 60 s), or `configureIdempotency({ scope, ceilingMs })`. Past it the handler is aborted and the key replays `X_IDEMPOTENCY_RUN_CEILING`.
+
 `configureIdempotency({ scope: 'shared' })` over a per-process store — or over a store that
 declares no scope at all — is `X_IDEMPOTENCY_NOT_SHARED` at `registerAction`, before the socket
 opens. The table is `SQL_IDEMPOTENCY_TABLE`, applied the way `SQL_JOBS_TABLE` is: `x db up` in
@@ -633,6 +696,53 @@ its `onCommit` (memory).
 
 A `query` has none and never will: a read has nothing to be idempotent about.
 
+## `registerToolGate` — what a named tool passes first
+
+`registerToolGate(names, gate)`, `toolGateFor(name)`, `gatedToolNames()`, `noteToolNames(names)`,
+`knownToolNames()`, `admitActionCaller(action, name)`, `asCallerContext(actor, fn)`, types `ToolGate`,
+`ToolGateCall`. A mechanism for the two tool surfaces, one tier above: `@ultimat3/mcp`'s
+`mcpConfirmations` registers and `@ultimat3/ai`'s adapter reads. Keyed by name because a tool is
+named across both. First registered keeps the name, a later one is a no-op. `resetActions` clears
+the table, so a test that calls it after each case must re-declare a module-level gate, or its later
+cases run ungated. Declared outside what a worker loads is `X_ROLE_LOAD_INCOMPLETE`.
+
+## `errors:` — the refusals a caller may branch on, closed
+
+```ts
+import { action } from '@ultimat3/action';
+import { defineError } from '@ultimat3/core';
+import { allow } from '@ultimat3/policy';
+import { t } from '@ultimat3/schema';
+
+const RefundTooLate = defineError({
+  code: 'X_REFUND_TOO_LATE',
+  title: 'the refund window has closed',
+  status: 409,
+  cause: 'the order is past its refund window',
+  fix: 'read the order first, and offer a refund only inside its window',
+});
+
+export const refundOrder = action({
+  input: t.object({ late: t.boolean }),
+  output: t.object({ refunded: t.boolean }),
+  policy: allow(),
+  errors: [RefundTooLate.code], // import the defineError class: the import registers its status
+  handle: ({ input }) => {
+    if (input.late) throw new RefundTooLate();
+    return { refunded: true };
+  },
+});
+```
+
+Each entry a registered 4xx code, listed once (`X_ACTION_ERRORS_INVALID` at `action()`). Judged
+around `handle` and `row` only (`declared-errors.ts`): a 4xx code outside the list is
+`X_ERROR_UNDECLARED` in a test or dev run and the original, warned and counted
+(`undeclared_errors_total`), in production. `.contract()` gains one assertion that scans the
+handler's own source (`declared-errors-contract.ts`); the OpenAPI operation names each code at its
+status (`openapi-errors.ts`); `describe().errors` publishes the sorted list, `null` when absent.
+The rule is `@ultimat3/core`'s, shared with `@ultimat3/query`. Wiki:
+[Declared refusals](../../wiki/Actions.md#declared-refusals-errors).
+
 ## `deprecated:` — a compat window, not a version
 
 ```ts
@@ -803,15 +913,25 @@ setAuditSink({
 });
 ```
 
+## The audit trail, for a subject export or erase
+
+`auditSubjectTarget({ executor, actor?, placeholder? })` is `x_audit` as a `defineSubject({ targets
+})` entry (`@ultimat3/jobs`). The export pages the rows the subject acted in, or was acted for, by
+id (`AUDIT_SUBJECT_COLUMNS`); the erase never deletes a trail row — it overwrites `actor_id` and
+`on_behalf_of_id` with `placeholder` (`'erased'`) and `input` with `null`, a bounded batch per
+statement. `actor` defaults to the subject's key. Keeping the person too is the app's call:
+`{ target, retain: '<why>' }`.
+
 ## Contract tests
 
-`publishPost.contract()` returns three assertions. Run them; they throw `X_CONTRACT_DRIFT`.
+`publishPost.contract()` returns four assertions. Run them; the first three throw `X_CONTRACT_DRIFT`.
 
 | Assertion | Holds when |
 |---|---|
 | 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 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 |
+| handler survives generated input | 16 runs (`exerciseAction`, `exercise.ts`) of input `arbitrary()` draws from `input:`, seeded by the name, each in a rolled-back transaction (`tx-scope.ts`): every answer is the output or a coded refusal under 500, and at least one run reached the handler |
 
 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
@@ -823,9 +943,15 @@ publishPost.contract({
   garbage: 42,                                 // what the input schema must reject
   input: { postId, orgId },                    // when the synthesized one cannot fit
   ctx: myCtx,                                  // default: an anonymous context
+  exercise: { actor, input: (drawn) => ({ ...drawn, postId }) }, // or { off: '<reason>' }
 })
 ```
 
+`exercise` is required unless the policy admits an anonymous caller
+(`X_CONTRACT_EXERCISE_UNDECLARED`). A defect is `X_CONTRACT_DEFECT` (`meta.run`, `meta.input`,
+`meta.failure`, and a `bun test <file> -t '<name>'` that replays it); no run reaching the handler
+is `X_CONTRACT_EXERCISE_UNREACHED`. Full rules: [Testing](https://github.com/developerz-ai/ultimate/wiki/Testing#the-exercise-assertion).
+
 Pass `input:` when the schema carries a constraint the IR cannot invert (a bare `pattern`) or
 when `row:` needs an id that resolves. Anything thrown *before* the policy decides is drift,
 never a pass — the assertion says which code got in the way and names `input:` as the fix.
@@ -838,6 +964,8 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_ACTION_PATH_DUPLICATE` | two actions derive one HTTP path (`archiveOrder` / `archiveOrders`) | rename one export |
 | `X_ACTION_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
 | `X_RATE_LIMIT_INVALID` | `rateLimit:` with a non-positive or non-finite half — `windowMs: 0` refills infinitely. Owned by `@ultimat3/http`, which owns the conversion | make both positive, or delete the block |
+| `X_METER_EXCEEDED` | a `meter:`'s allowance for the current UTC period is spent; `meta.resetsAt` and `Retry-After` say when it resets | wait, or raise what `meter.limit` resolves to for the tenant |
+| `X_METER_INVALID` | a `meter:` with a bad name, period or `warnAt`, half a `warnAt`/`onWarn` pair, or a limit resolving to anything but a whole number ≥ 0 | fix the declaration the cause names |
 | `X_ACTION_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `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 show <name> --json` |
 | `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
@@ -848,6 +976,9 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `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_CONTRACT_DEFECT` | a generated legal input made the handler throw uncoded, fail its output, or answer a coded 5xx | the replay command in `fix:` |
+| `X_CONTRACT_EXERCISE_UNREACHED` | no generated run reached the handler | `.contract({ exercise: { actor } })` with a permitted actor, or bind a row with `exercise.input` |
+| `X_CONTRACT_EXERCISE_UNDECLARED` | `.contract()` on a guarded action with no `exercise`, or a blank `off` | `.contract({ exercise: { actor } })` or `{ exercise: { off: '<reason>' } }` |
 | `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 |
 | `X_ACTION_UNREGISTERED` | projected before `registerActions()` ran | register at boot |
 | `X_AUDIT_SINK_MISSING` | `audit: true` and no sink installed — raised before the input parse | `setAuditSink(yourSink)` at boot |
@@ -861,7 +992,8 @@ The client does the same with the server's: a `problem+json` failure comes back
 the browser bundle may never have registered it, and linked only to a page that exists — the
 server's own `docs`/`type` when it sent an `http(s)` one, this build's registered link when it
 knows the code, otherwise the error index. A per-code URL is never synthesized for a code
-nothing here declares.
+nothing here declares. The document's root `requestId` lands on `meta.requestId` (core's
+`withRequestId`), so a report names the request support can find.
 
 A document carrying an `issues` member arrives parsed as well: `meta.issues`, read by
 `issuesFromWire` — a wire value, so the list is rebuilt member by member and a list this build
@@ -902,3 +1034,13 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 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*.
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `IdempotencyOutputUnserializableError` | the class behind `X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE` |
+| `IdempotencyRunCeilingError` | the class behind `X_IDEMPOTENCY_RUN_CEILING` |
+| `parseActionInput(schema, raw, name)` | `invoke`'s input parse, alone: the parsed value, or the same `X_INPUT_INVALID` (line and `issues`) `invoke` throws. `@ultimat3/ai` holds an agent eval's tool double to it |