@ultimat3/action 11.3.0 → 13.0.0

package/CLAUDE.md

@@ -21,6 +21,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `http.ts` | route projection (`enforcedBy: 'handler'`) + OpenAPI operation |
 | `openapi.ts` | deterministic OpenAPI 3.1 document |
 | `client.ts` | typed RPC client (browser-safe: no server imports) |
+| `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` |
@@ -34,13 +36,44 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `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 memory sink, the installed-sink store |
+| `audit.ts` | the audit seam: `AuditRecord`, `AuditSink`, the installed-sink store |
+| `audit-memory.ts` | the process default: a bounded ring that DROPS, and counts what it dropped |
+| `audit-postgres.ts` | the DURABLE sink — one append-only `x_audit` table, one insert per record |
+| `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` |
 
 ## Invariants
 
+- **`X_INPUT_INVALID` carries the rejections TWICE, and they are one value.** The flattened line
+  stays in `cause` — it is what an operator reads in a log and what a non-form caller sees — and
+  `meta.issues` carries the same list structured, so a client rebuilding a form knows WHICH field
+  each rejection belongs to instead of splitting a string on `'; '` and guessing. `validate.ts` is
+  the one caller that passes both, and `validate.test.ts` pins `cause` to
+  `formatIssues(issues).join('; ')`; the rendering deliberately does NOT happen inside
+  `InputInvalidError`, because that module is reachable from browser-safe `client.ts` and
+  `@ultimat3/schema` declares no `sideEffects`, so a value import of `formatIssues` there would drag
+  that package's whole barrel into every bundle holding the typed client.
+- **`toValidationIssues`, never a library's raw issues.** A conforming schema library's issue object
+  may carry members Ultimate's shape does not — including the rejected VALUE — and this list is
+  handed to an HTTP surface that returns it to the caller. Four members travel. The same rule on the
+  way back in: `issuesFromWire` REBUILDS each entry member by member rather than copying it.
+- **`X_OUTPUT_INVALID` keeps the line alone.** An output rejection is a server defect whose remedy
+  is a code change; no client can act on a per-field list, and shipping the handler's internal
+  projection to a caller is new surface for nothing.
+- **An `issues` list off the wire is all-or-nothing.** A partly-parsed list would DROP the entries
+  it could not read, and a caller that finds `meta.issues` uses it INSTEAD of `cause` — so a dropped
+  entry is a rejection the user never hears about. `MAX_WIRE_ISSUES` bounds it, because whoever
+  displays the list renders it into a DOM.
+- **`transition()` is a factory, not a primitive, and it decides nothing about the machine.** It
+  returns a `mutator`, so every projection is inherited rather than re-declared, and it holds no
+  legality rule: `X_STATE_TRANSITION_ILLEGAL`, `X_STATE_CONFLICT` and `X_STATE_UNDECLARED` are
+  `@ultimat3/entity`'s and propagate untouched. `from` is REQUIRED — it is the UPDATE's predicate,
+  which is what makes the refusal free; defaulting or inferring it is the lost update coming back.
+  `conflict: 'server-wins'` is fixed (the server is the half that refused), and `audit` is OFF
+  unless declared (`audit: true` with no sink is `X_AUDIT_SINK_MISSING` before the input parse, so
+  defaulting it on would hold the factory hostage to an unrelated decision).
 - Every surface goes through `invoke`: parse input, evaluate policy, handle, parse
   output. Adding a second execution path is the one unforgivable change here.
 - **An explicit `ctx` is INSTALLED, never merely passed** (`As of 2026-08`). `invoke` entered
@@ -339,10 +372,19 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   around its own handler could ever see one. What reaches the sink is what `invoke` already holds
   (`at` from `ctx.now()`, the name, the mutator brand, the surface, the whole `ctx`, the parsed
   input, the namespaced idempotency key, `replayed`, the outcome, the failure code). What does
-  **not** ship, ever: an audit entity, a schema, a retention policy, a storage backend, a hash
-  chain, a subject index, or an opinion on what "who" means under impersonation — four apps model
-  those four ways, so by axiom 8's own test they are business convention and shipping one makes
-  three of them wrong. `result` is absent for the same reason and one more: a handler's return is
+  **not** ship, ever: 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, so by axiom
+  8's own test they are business convention and shipping one makes three of them wrong.
+  **"a storage backend" was on that list until 2026-08-24 and is off it**, because the list was
+  answering a different question than it appeared to. What four apps model four ways is the ROW —
+  which of their own facts it carries, how long they keep it, whether it chains. Where the record
+  the FRAMEWORK already defines is put is not one of those: `x_audit`'s columns are the fields of
+  `AuditRecord` and nothing else, which is the same relationship `idempotency-postgres.ts` has to
+  `IdempotencyRecord` and `@ultimat3/http`'s `postgresRateLimitStore` to its `Bucket`. Leaving it
+  off meant the only sink that shipped was a ring that drops, so the shortest edit clearing
+  `X_AUDIT_SINK_MISSING` was `setAuditSink(memoryAuditSink())` — compliant in dev, silently
+  amnesiac in production, which `docs/idea/20-large-app-readiness.md` scores as **Ship**. An app
+  that wants columns of its own still writes its own sink; the seam is one method. `result` is absent for the same reason and one more: a handler's return is
   reachable from the handler itself, so shipping it would be this package deciding a row carries
   an after-image, which is `@ultimat3/admin`'s `diff` convention arriving one tier down.
 - **The audit vocabulary is `@ultimat3/admin`'s, shared by name and not by import.** `AuditOutcome`
@@ -353,6 +395,47 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   Unifying them means lifting the vocabulary into `@ultimat3/core` — the only tier both reach —
   and rebuilding `admin/audit.ts` on this seam. Not done here: `admin` is a shipped public API
   and its `AuditEntry` is a different shape.
+- **The memory sink DROPS, and both halves of that sentence are enforced.** It was a plain array
+  with a `push` — the one memory implementation in the framework with no cap, beside five that
+  have one (`memoryRateLimitStore`, `MemoryIdempotencyStore`, `createLimiter`,
+  `createTotpReplayGuard`, `createMemoryEventBus`) — and a record pins a whole `Ctx`, so at 50
+  audited writes a second it is 4.3M immortal records a day and the pod OOMs holding the trail it
+  was retaining. It is now a ring at `DEFAULT_MAX_AUDIT_RECORDS`, evicting the OLDEST (the
+  direction `createMemoryEventBus` evicts in: refusing new writes would answer "nothing has
+  happened since" for a process that has been serving all day). `dropped` is what makes "it drops"
+  checkable in a running process instead of a sentence in a header — a non-zero count on a real
+  deployment is the sink saying it is the wrong one. A `maxRecords` of `0`, negative or `NaN`
+  falls back to the default: there is no spelling of "no bound", because that spelling was the bug.
+- **What a DURABLE sink may write down is decided in `audit-input.ts`, and it is two rules.**
+  A record's `input` is the PARSED input, which is exactly where a password, a bearer token or a
+  card number lives, so `postgresAuditSink` redacts it through `@ultimat3/core`'s `isRedactedKey`
+  — the SAME table `defineEnv({ secret: true })` extends, never a copy of the list, because a copy
+  is how a value that is `[redacted]` in a log line becomes plaintext in a table. `isSecret`
+  redacts by VALUE beside it, for a credential travelling under a harmless name. The second rule
+  is that the answer is always JSON-representable: a `bigint`, a `NaN`, a function and a cycle all
+  become a NAMED marker rather than a throw, because `auditSettled` turns a sink throw into a
+  failed invocation for a handler that has already committed — and because `JSON.stringify` over a
+  cycle takes ~4.6s in Bun 1.4 before it raises, so leaving the detection to the serializer stalls
+  the audited path either way. `toJSON` is never called: it is app code in the frame that owes the
+  caller a record.
+- **The `Ctx` is never walked, and never will be.** `createContext` spreads every installed
+  service ONTO the context object and an HTTP surface's value is a `RequestContext` carrying the
+  request's own `Authorization` and `Cookie`, so a projection that iterated it would write an
+  app's database clients and its caller's credentials into an audit table. `postgresAuditSink`
+  reads an allow-list of framework-owned fields (`requestId`, `traceId`, `locale`, `tz`,
+  `buildId`, `role`, and the actor's `id`/`kind`/`orgId`/`onBehalfOf`) and nothing else.
+  `failure.error` is not among them — the row keeps `failure.code`, because a throwable's stack is
+  worth reading and is not worth storing, and rendering one into a column is the trap
+  `renderThrowable` exists for.
+- **`x_audit` ships no purge, and it is the only framework table that does not.**
+  `x_idempotency` and `x_rate_limit` both ship one because a stale row there is meaningless; a
+  stale audit row IS the record, and "how long" is a legal answer that is seven years for one app
+  and thirty days for the next. Shipping a `delete` would be shipping one of those answers.
+- **`SQL_AUDIT_INSERT` is positional, so its parameter order is pinned by a test and not by a
+  type.** `audit-parity.test.ts` names every column once and compares both sinks' answer for every
+  string field with a DIFFERENT value per field — two columns holding the same word cannot catch a
+  slip, and a `locale` in the `tz` slot type-checks perfectly. Proven by mutation: the first draft
+  of that test did NOT catch a swapped `locale`/`tz` and was widened until it did.
 - **A sink may not silently swallow, and the two failure policies are deliberate opposites.**
   `X_AUDIT_SINK_MISSING` is raised *before* the input parse, so an audited action nothing can
   record refuses with no committed write behind it — there is deliberately no logger-backed

package/README.md

@@ -240,6 +240,53 @@ the core, because it never leaves the client; keep it a pure function of `(tx, i
 SQLite). Type your tables once: `declare module '@ultimat3/action' { interface
 LocalTables { posts: PostRow } }`.
 
+## `transition()` — a mutator factory over a state machine
+
+`As of 2026-08-24`. A move through an entity column's state machine is a server-authoritative write
+with an input schema, an output schema and a policy — which is what a `mutator` already is. So
+`transition()` **returns one**, and the move inherits the route, the OpenAPI operation, the typed
+client, the MCP tool, the job handle and its `PRIMITIVE_FACTORIES` row. It is not a ninth primitive
+and it declares no error code of its own.
+
+```ts
+import { t, transition, type TransitionTarget } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import { can } from '@ultimat3/policy';
+
+const ORDER_STATES = ['pending', 'paid', 'shipped'] as const;
+type OrderState = (typeof ORDER_STATES)[number];
+
+const OrderView = t.object({ id: t.uuid, status: t.enum(ORDER_STATES) });
+
+// `@ultimat3/entity`'s `orders(ctx)`: a real `Table` satisfies the seam as written.
+declare function orders(ctx: Ctx): TransitionTarget<{ id: string; status: OrderState }, OrderState>;
+declare const id: string;
+declare const ctx: Ctx;
+
+export const moveOrder = transition({
+  table: (ctx) => orders(ctx),      // the request's table — tenant-scoped like every write
+  column: 'status',                 // the column whose enumerated().transitions() IS the machine
+  states: ORDER_STATES,             // typed against the row: a state it cannot hold is a compile error
+  localTable: 'orders',             // what the optimistic twin patches
+  output: OrderView,
+  policy: can('order:move'),
+});
+
+await moveOrder({ id, from: 'pending', to: 'paid' }, { ctx });
+```
+
+| Rule | Why |
+|---|---|
+| **`from` is required, and never defaulted or inferred** | it rides in the UPDATE's own predicate, so the state observed and the state written are one decision under the row's lock. Measured on the mechanism underneath: twenty concurrent moves at one row gave 14 winners with a read-then-check-then-write and **1 winner plus 19 refusals** with `from` in the predicate. Anything that supplies `from` for the caller is the lost update coming back |
+| the states are the **input schema**, not a `t.string` | the union survives into `InferOutput`, so the typed client refuses a typo at **compile** time, the MCP tool's `inputSchema` and the OpenAPI component both publish the legal set, and a bad state is `X_INPUT_INVALID` before a database is touched |
+| `conflict: 'server-wins'`, not overridable | the server is the half that REFUSED the move; a local twin winning the rebase would leave the client showing a state the database rejected |
+| `audit` is **off** unless the app says so | `audit: true` with no sink installed is `X_AUDIT_SINK_MISSING`, raised before the input parse — an on-by-default audit would make every `transition()` refuse until an unrelated decision was made. What the row is kept for, and for how long, is the same compliance question that kept a purge out of `postgresAuditSink` |
+| `X_STATE_TRANSITION_ILLEGAL`, `X_STATE_CONFLICT` and `X_STATE_UNDECLARED` propagate untouched | they are `@ultimat3/entity`'s. A second error class over one failure is a second path |
+
+`table` is typed structurally (`TransitionTarget`), not imported: `@ultimat3/action` holds no
+dependency edge on `@ultimat3/entity` — the tier table permits one, the manifest and the lockfile do
+not — and a real `Table` satisfies the seam as written.
+
 ## Determinism + idempotency
 
 `serializeOpenApi(buildOpenApi())` sorts keys at every depth, iterates the registry
@@ -249,7 +296,10 @@ name-sorted, and reads no clock, env or random source — same registry ⇒ same
 ## `rateLimit:` is the enforced limit
 
 ```ts
-rateLimit: { limit: 5, windowMs: 600_000 },   // 5 held, one back every two minutes
+import type { ActionRateLimit } from '@ultimat3/action';
+
+// The `rateLimit:` key of an `action()`: 5 held, one back every two minutes.
+const rateLimit: ActionRateLimit = { limit: 5, windowMs: 600_000 };
 ```
 
 One declaration, three places it lands: the bucket the limiter runs on (named after the action,
@@ -298,6 +348,9 @@ import {
   postgresIdempotencyStore,
   setIdempotencyStore,
 } from '@ultimat3/action';
+import { db } from '@ultimat3/db';
+
+const client = db();
 
 // NOT `executor: Bun.sql` — `Bun.sql.query` is `undefined` `As of 2026-08` (it is a tagged
 // template whose positional form is `unsafe`), so that line compiles and throws on the first
@@ -348,7 +401,14 @@ A `query` has none and never will: a read has nothing to be idempotent about.
 ## `deprecated:` — a compat window, not a version
 
 ```ts
-deprecated: { since: '2026-08-01T00:00:00Z', sunset: '2026-12-31T23:59:59Z', replacedBy: 'searchOrders' },
+import type { Deprecation } from '@ultimat3/action';
+
+// The `deprecated:` key of an `action()`.
+const deprecated: Deprecation = {
+  since: '2026-08-01T00:00:00Z',
+  sunset: '2026-12-31T23:59:59Z',
+  replacedBy: 'searchOrders',
+};
 ```
 
 Four things at once: `Deprecation: @1754006400` (RFC 9745) and `Sunset: Wed, 31 Dec 2026 …`
@@ -391,9 +451,53 @@ What the framework supplies is what it genuinely knows:
 | `outcome` | `allowed` \| `denied` \| `failed` |
 | `failure` | the `X_*` code and the thrown value, on every outcome but `allowed` |
 
-What it does **not** supply: an audit entity, a schema, a retention policy, a storage backend, 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.
+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.
+
+### Two sinks ship, and only one of them keeps anything
+
+| Sink | Keeps | Use it for |
+|---|---|---|
+| `memoryAuditSink({ maxRecords })` | the newest `DEFAULT_MAX_AUDIT_RECORDS` (1,000) records, verbatim. **It DROPS** — `dropped` counts what it discarded | `x dev`, tests |
+| `postgresAuditSink({ executor })` | one append-only `x_audit` row per attempt. Drops nothing | anything that has to keep its trail |
+
+The memory sink is bounded because a record pins a whole `Ctx`: at 50 audited writes a second an
+unbounded array is 4.3M immortal records a day and the pod dies holding the trail it was
+retaining. The trap it names out loud is that the shortest edit clearing `X_AUDIT_SINK_MISSING`
+is `setAuditSink(memoryAuditSink())`, and nothing at that call site says the result is amnesiac.
+
+```ts
+// apps/web/server.ts — the app owns the connection, so the app installs the sink
+import { postgresAuditSink, setAuditSink } from '@ultimat3/action';
+import { db } from '@ultimat3/db';
+
+const client = db();
+setAuditSink(
+  postgresAuditSink({ executor: { query: (text, values) => client.query({ text, values }) } }),
+);
+```
+
+**The table is applied by the boot; the sink is not.** `startQueue` runs `SQL_AUDIT_TABLE` on
+every start — `x dev`, the container's `web`/`worker`, and the release-phase `ROLE=migrate` — the
+way `SQL_IDEMPOTENCY_TABLE` is applied, because a package holding no database dependency cannot
+apply its own schema. Installing a sink stays your one line, deliberately: there is no default, so
+`audit: true` with none installed keeps refusing with `X_AUDIT_SINK_MISSING` instead of recording
+into a ring. `executor` is a client that already speaks `(text, values)` — never `Bun.sql`, whose
+`.query` is `undefined`.
+
+`x_audit` carries the framework's own facts as columns — the action, the surface, the outcome,
+the actor, the correlation ids, the idempotency key — and the parsed `input` as `jsonb`, redacted
+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
+`RequestContext` carrying the caller's `Authorization` and `Cookie`), and the thrown value behind
+a failure — the row keeps `failure.code`, never the throwable.
+
+The table has **no purge**, deliberately, and it is the one framework table that does not: a
+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`,
 so nothing you could write around your own handler would ever see one. That is the reason this
@@ -491,7 +595,7 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `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_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 | `x actions describe <name> --json` |
+| `X_INPUT_INVALID` | input failed the Standard Schema. Carries the rejections **twice**: the flattened line in `cause`, and the structured list in `meta.issues` — one value rendered two ways, `As of 2026-08-24` | `x actions describe <name> --json` |
 | `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
 | `X_IDEMPOTENCY_KEY_INVALID` | `Idempotency-Key:` sent blank (`Headers.get()` answers `''`, not `null`) or past 255 characters | send one unique value per request, or omit the header |
 | `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor })` at boot |
@@ -513,6 +617,12 @@ server's own `docs`/`type` when it sent an `http(s)` one, this build's registere
 knows the code, otherwise the error index. A per-code URL is never synthesized for a code
 nothing here declares.
 
+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
+cannot read is dropped whole rather than half-kept, leaving `cause` (which still holds every
+rejection) as the answer. It is exported for the island that posts with a plain `fetch` and holds
+the body itself.
+
 ## Boundaries
 
 Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `policy`, `http`. Never imports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "11.3.0",
+  "version": "13.0.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,10 +34,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "11.3.0",
-    "@ultimat3/core": "11.3.0",
-    "@ultimat3/http": "11.3.0",
-    "@ultimat3/policy": "11.3.0",
-    "@ultimat3/schema": "11.3.0"
+    "@ultimat3/cache": "13.0.0",
+    "@ultimat3/core": "13.0.0",
+    "@ultimat3/http": "13.0.0",
+    "@ultimat3/policy": "13.0.0",
+    "@ultimat3/schema": "13.0.0"
   }
 }

package/src/audit-input.ts

@@ -0,0 +1,78 @@
+/**
+ * One job: turn an `AuditRecord.input` into something a durable sink may write down — redacted
+ * through core's own table, and representable as JSON on every path. Both halves are safety, not
+ * formatting: a stored credential is a leak, and a sink that throws on the caller's input fails an
+ * invocation whose handler has already committed.
+ */
+
+import { isRedactedKey, isSecret, REDACTED } from '@ultimat3/core';
+
+/**
+ * What a value this cannot represent becomes. A NAME and never `null`: `JSON.stringify` writes
+ * `null` for `NaN` and `±Infinity` and drops a function entirely, so an auditor reading the row
+ * could not tell "the field was absent" from "the field held something unwritable".
+ */
+export const UNREPRESENTABLE = '[unrepresentable]';
+
+/**
+ * How deep the walk goes. The input is schema-parsed, so its shape is the app's declaration — but
+ * `t.record` and a recursive schema have no depth of their own, and an overflow HERE lands in the
+ * sink, after the handler committed. Anything past this is `UNREPRESENTABLE`, which is the honest
+ * answer: it was there and this row does not carry it.
+ */
+export const AUDIT_INPUT_MAX_DEPTH = 12;
+
+/**
+ * `undefined` in, `undefined` out — an input that never parsed is a row with no input, not a row
+ * whose input was null.
+ *
+ * A cycle is CUT rather than raised on, and that is a cost decision as much as a correctness one:
+ * `JSON.stringify` over a self-referential value takes ~4.6s in Bun 1.4 before it throws, so
+ * leaving the detection to the serializer stalls the audited path whether or not the throw is
+ * caught. The ancestor set is the path, not everything seen — a value appearing twice as siblings
+ * is repetition and is written twice, exactly as `JSON.stringify` writes it.
+ *
+ * **`toJSON` is never called.** It is app code inside the frame that owes the caller a record, and
+ * one that throws is the second failure `jsonResult` already names; a `Map`, a `Set` and a `URL`
+ * therefore walk as their own enumerable keys, which is what `JSON.stringify` makes of them too.
+ */
+export function auditableInput(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  return walk(value, 0, new Set());
+}
+
+function walk(value: unknown, depth: number, ancestors: Set<object>): unknown {
+  if (value === null) return null;
+  const kind = typeof value;
+  if (kind === 'string' || kind === 'boolean') return value;
+  if (kind === 'number') return Number.isFinite(value) ? value : UNREPRESENTABLE;
+  // `bigint`, `function`, `symbol`, and `undefined` reached through an array hole.
+  if (kind !== 'object') return UNREPRESENTABLE;
+
+  const object = value as object;
+  if (isSecret(object)) return REDACTED;
+  if (object instanceof Date) {
+    return Number.isNaN(object.getTime()) ? UNREPRESENTABLE : object.toISOString();
+  }
+  if (depth >= AUDIT_INPUT_MAX_DEPTH || ancestors.has(object)) return UNREPRESENTABLE;
+
+  ancestors.add(object);
+  try {
+    if (Array.isArray(object)) {
+      return object.map((item) => walk(item, depth + 1, ancestors));
+    }
+    const out: Record<string, unknown> = {};
+    // `Object.entries`, so only OWN enumerable keys are read: a prototype member is not this
+    // record's data, and reading one would put `Object.prototype`'s members in every audit row.
+    for (const [key, item] of Object.entries(object)) {
+      // The key decides before the value does, so a credential under a redacted name is never
+      // walked at all — `isRedactedKey` is core's, the same table `defineEnv({ secret: true })`
+      // extends, so a value that is `[redacted]` in a log line cannot be plaintext in a table.
+      if (isRedactedKey(key)) out[key] = REDACTED;
+      else if (item !== undefined) out[key] = walk(item, depth + 1, ancestors);
+    }
+    return out;
+  } finally {
+    ancestors.delete(object);
+  }
+}

package/src/audit-memory.ts

@@ -0,0 +1,84 @@
+/**
+ * The audit seam's process-memory sink: a bounded ring that DROPS, for tests and `x dev`. Split
+ * from `audit.ts` on the seam `idempotency.ts` / `idempotency-memory.ts` already draw, so the file
+ * declaring what a record IS is not also the file deciding how many are kept.
+ */
+
+import type { AuditRecord, AuditSink } from './audit';
+
+/**
+ * Records held at once. A record pins a whole `Ctx` — the actor, the service bag, the parsed
+ * input — so its cost is the request's, not a row's: at 50 audited writes a second an unbounded
+ * array is 4.3M immortal records a day and the pod dies holding the trail it was retaining. This
+ * sink was the one memory implementation in the framework with no cap, beside five that have one
+ * (`memoryRateLimitStore`, `MemoryIdempotencyStore`, `createLimiter`, `createTotpReplayGuard`,
+ * `createMemoryEventBus`).
+ */
+export const DEFAULT_MAX_AUDIT_RECORDS = 1_000;
+
+export interface MemoryAuditSinkOptions {
+  /** Records held at once. Absent, zero, negative or NaN all read as the default — never "no cap". */
+  readonly maxRecords?: number | undefined;
+}
+
+/**
+ * The seam's memory implementation, for tests and `x dev`. **Not a system of record, and not
+ * merely because it is not durable: it DISCARDS.** Past `maxRecords` the oldest record is dropped
+ * on every write, so an audited action can run, succeed, be recorded, and leave nothing behind —
+ * which is exactly what an audit trail must never do. The trap this shape exists to make visible
+ * is that the shortest edit clearing `X_AUDIT_SINK_MISSING` is `setAuditSink(memoryAuditSink())`,
+ * and nothing about the call site says the result is amnesiac. A deployment that must keep its
+ * trail installs `postgresAuditSink({ executor })`, which drops nothing.
+ *
+ * `dropped` is what makes that statement checkable in a running process rather than a sentence
+ * here: a non-zero count on a real deployment is the sink saying it is the wrong one.
+ */
+export interface MemoryAuditSink extends AuditSink {
+  /** The retained window, oldest first. A copy — the log cannot be mutated through it. */
+  records(): readonly AuditRecord[];
+  /** Retained right now — the bound, observable. */
+  readonly size: number;
+  /** Records this sink has DISCARDED since the last `clear()`. Never a number to ignore. */
+  readonly dropped: number;
+  clear(): void;
+}
+
+/**
+ * The OLDEST goes, which is the same direction `createMemoryEventBus` evicts in and the opposite
+ * of refusing new writes: a sink that stopped recording at the cap would answer "nothing has
+ * happened since" for a process that has been serving all day, and the most recent attempts are
+ * the ones anyone reading `x dev` is looking at.
+ */
+export function memoryAuditSink(options: MemoryAuditSinkOptions = {}): MemoryAuditSink {
+  const declared = options.maxRecords;
+  const maxRecords =
+    typeof declared === 'number' && Number.isFinite(declared) && declared >= 1
+      ? Math.floor(declared)
+      : DEFAULT_MAX_AUDIT_RECORDS;
+  const log: AuditRecord[] = [];
+  let dropped = 0;
+
+  return {
+    write(record: AuditRecord): void {
+      log.push(record);
+      // `shift` in a loop, not a slice: the cap is only ever exceeded by one per write, so this
+      // runs at most once — and it releases the evicted record's `Ctx` rather than copying the
+      // array, which would hold both windows alive for the length of the copy.
+      while (log.length > maxRecords) {
+        log.shift();
+        dropped += 1;
+      }
+    },
+    records: (): readonly AuditRecord[] => [...log],
+    get size(): number {
+      return log.length;
+    },
+    get dropped(): number {
+      return dropped;
+    },
+    clear: (): void => {
+      log.length = 0;
+      dropped = 0;
+    },
+  };
+}

package/src/audit-postgres.ts

@@ -0,0 +1,175 @@
+/**
+ * The durable audit sink: one append-only Postgres table, one insert per record. Without it the
+ * shortest edit that clears `X_AUDIT_SINK_MISSING` is `setAuditSink(memoryAuditSink())`, which
+ * reads durable at the call site and is a ring that DROPS — compliant in dev, amnesiac in
+ * production. Statements are spelled out so an agent can run the exact one it saw in a log.
+ */
+
+import type { Actor } from '@ultimat3/core';
+import { uuid } from '@ultimat3/core';
+import type { AuditRecord, AuditSink } from './audit';
+import { auditableInput } from './audit-input';
+import type { PgExecutor } from './idempotency-postgres';
+
+/**
+ * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, and
+ * for the same reason: this package holds no database dependency and cannot apply its own schema.
+ * `create table if not exists` is a no-op against a database that already has it, so a new column
+ * is added by `alter table … add column if not exists` and never by editing the `create`.
+ *
+ * **Two indexes and no third.** "Who did what, when" is the only question an audit table is opened
+ * for, and an index is a write cost paid on the audited path. A SUBJECT index — which row the
+ * action was about — is deliberately absent: the framework does not know a record's subject, and
+ * guessing one is the audit ENTITY this seam refuses to ship.
+ *
+ * **`at` is the one nullable column that looks like it should not be.** It is `ctx.now()`, and a
+ * `Clock` is injectable, so an app can hand this seam an Invalid Date — whose `toISOString()`
+ * THROWS. A sink that raises fails an invocation whose handler has already committed, so an
+ * unrepresentable instant is written as "this process could not say when" and `recorded_at`, the
+ * database's own clock, still stamps the row. `not null` would have traded a lost row for a lost
+ * write.
+ *
+ * **No retention, no purge, and that is the difference from every other table this framework
+ * owns.** `x_idempotency` and `x_rate_limit` both ship a purge because a stale row there is
+ * meaningless; a stale audit row is the record. How long a trail is kept is a legal question with
+ * a different answer per app — seven years for one, thirty days for the next — so shipping a
+ * `delete` would be shipping one of those answers. The table grows until the app prunes or
+ * partitions it, and that is stated rather than solved.
+ */
+export const SQL_AUDIT_TABLE = `
+create table if not exists x_audit (
+  id                uuid        primary key,
+  at                timestamptz,
+  action            text        not null,
+  mutator           boolean     not null,
+  surface           text        not null,
+  outcome           text        not null,
+  replayed          boolean     not null,
+  idempotency_key   text,
+  failure_code      text,
+  actor_id          text        not null,
+  actor_kind        text        not null,
+  org_id            text,
+  on_behalf_of_id   text,
+  on_behalf_of_kind text,
+  request_id        text        not null,
+  trace_id          text        not null,
+  locale            text        not null,
+  tz                text        not null,
+  build_id          text        not null,
+  role              text        not null,
+  input             jsonb,
+  recorded_at       timestamptz not null default now()
+);
+
+create index if not exists x_audit_at_idx on x_audit (at desc);
+
+create index if not exists x_audit_actor_at_idx on x_audit (actor_id, at desc);
+`;
+
+/**
+ * `id` is generated per ROW and is not an idempotency key: two identical attempts are two events
+ * and an audit trail that collapsed them would be lying about how many times something was tried.
+ * There is deliberately no `on conflict` — an append-only table has nothing to reconcile.
+ *
+ * `recorded_at` defaults to `now()` and is not a parameter: `at` is the caller's clock
+ * (`ctx.now()`) and this is the database's, so the gap between them is the audit lag, and a
+ * process whose clock has drifted is visible instead of invisible.
+ */
+export const SQL_AUDIT_INSERT = `
+insert into x_audit (
+  id, at, action, mutator, surface, outcome, replayed, idempotency_key, failure_code,
+  actor_id, actor_kind, org_id, on_behalf_of_id, on_behalf_of_kind,
+  request_id, trace_id, locale, tz, build_id, role, input
+) values (
+  $1::uuid, $2::timestamptz, $3, $4, $5, $6, $7, $8, $9,
+  $10, $11, $12, $13, $14,
+  $15, $16, $17, $18, $19, $20, $21::jsonb
+)
+`;
+
+export interface PostgresAuditSinkOptions {
+  readonly executor: PgExecutor;
+}
+
+export interface PostgresAuditSink extends AuditSink {
+  write(record: AuditRecord): Promise<void>;
+}
+
+/**
+ * **Install it at boot, beside the store that declares the rest of this app's durability.** The
+ * app owes one line in `apps/web/server.ts`, over the client this process already opened:
+ *
+ * ```ts
+ * const client = db();
+ * setAuditSink(
+ *   postgresAuditSink({
+ *     executor: { query: (text, values) => client.query({ text, values }) },
+ *   }),
+ * );
+ * ```
+ *
+ * `Bun.sql` does not satisfy `PgExecutor` — `Bun.sql.query` is `undefined`; see that interface.
+ *
+ * What is written is an ALLOW-LIST of the facts the framework itself owns, never the `Ctx`. That
+ * is not tidiness: `createContext` spreads every installed service onto the context object, and on
+ * an HTTP surface the value is a `RequestContext` carrying the request's own `Authorization` and
+ * `Cookie` headers — so a projection that walked it would write an app's database clients and its
+ * caller's credentials into an audit table. An app that wants more columns writes its own
+ * `AuditSink`; the seam is one method, and that is the extension point.
+ */
+export function postgresAuditSink(options: PostgresAuditSinkOptions): PostgresAuditSink {
+  const exec = options.executor;
+  return {
+    async write(record: AuditRecord): Promise<void> {
+      const actor = record.ctx.actor;
+      const at = record.at instanceof Date && !Number.isNaN(record.at.getTime()) ? record.at : null;
+      const onBehalfOf = onBehalfOfOf(actor);
+      const input = auditableInput(record.input);
+      await exec.query(SQL_AUDIT_INSERT, [
+        uuid(),
+        at === null ? null : at.toISOString(),
+        record.action,
+        record.mutator,
+        record.surface,
+        record.outcome,
+        record.replayed,
+        record.idempotencyKey,
+        record.failure?.code ?? null,
+        actor.id,
+        actor.kind,
+        actor.orgId ?? null,
+        onBehalfOf?.actorId ?? null,
+        onBehalfOf?.actorKind ?? null,
+        record.ctx.requestId,
+        record.ctx.traceId,
+        record.ctx.locale,
+        record.ctx.tz,
+        record.ctx.buildId,
+        record.ctx.role,
+        // `undefined` in means a parse that never produced an input, which is a NULL column and
+        // not the four characters `JSON.stringify(undefined)` does not produce either.
+        input === undefined ? null : JSON.stringify(input),
+      ]);
+    },
+  };
+}
+
+/**
+ * Both halves of an impersonation, recorded and interpreted as NEITHER. `actor_id` is who the
+ * framework ran the attempt as and `on_behalf_of_*` is what `impersonate()` recorded; which of
+ * them an app calls "who did this" is the convention four apps model four ways, so the row carries
+ * the two facts and takes no position between them.
+ *
+ * Read through a guard rather than off the type: `Actor.onBehalfOf` is optional, and an actor
+ * minted by an app's own `resolveToken` is a plain object nothing in this package validated.
+ */
+function onBehalfOfOf(actor: Actor): { actorId: string; actorKind: string } | null {
+  const origin: unknown = actor.onBehalfOf;
+  if (typeof origin !== 'object' || origin === null) return null;
+  const record = origin as Record<string, unknown>;
+  const actorId = record['actorId'];
+  const actorKind = record['actorKind'];
+  if (typeof actorId !== 'string' || typeof actorKind !== 'string') return null;
+  return { actorId, actorKind };
+}

package/src/audit.ts

@@ -53,6 +53,12 @@ export interface AuditRecord {
    * a sink needs to write a row at all. Carried whole rather than projected into `actorId` +
    * `requestId` fields, because choosing WHICH context facts an audit row keeps is precisely the
    * convention four apps modelled four ways.
+   *
+   * **A sink that PERSISTS must project it, and `audit-postgres.ts` is where that is done.**
+   * `createContext` spreads every installed service onto this object and an HTTP surface's value
+   * is a `RequestContext` carrying the caller's `Authorization` and `Cookie`, so writing it down
+   * whole puts an app's database clients and its caller's credentials in a table. Whole here,
+   * allow-listed there — the seam hands over everything and each sink decides what it keeps.
    */
   readonly ctx: Ctx;
   /**
@@ -82,26 +88,6 @@ export interface AuditSink {
   write(record: AuditRecord): Promise<void> | void;
 }
 
-/** The seam's memory implementation, for tests and `x dev`. Not a system of record. */
-export interface MemoryAuditSink extends AuditSink {
-  /** In the order `invoke` produced them. A copy — the log cannot be mutated through it. */
-  records(): readonly AuditRecord[];
-  clear(): void;
-}
-
-export function memoryAuditSink(): MemoryAuditSink {
-  const log: AuditRecord[] = [];
-  return {
-    write(record: AuditRecord): void {
-      log.push(record);
-    },
-    records: (): readonly AuditRecord[] => [...log],
-    clear: (): void => {
-      log.length = 0;
-    },
-  };
-}
-
 /**
  * No default. A logger-backed default would satisfy `audit: true` with a line nobody stores,
  * which is the silent pass this seam exists to remove: an audited action with no sink installed

package/src/client.ts

@@ -16,6 +16,7 @@ import type { Action } from './action';
 import { ContractDriftError, RemoteActionError, RpcFailedError } from './errors';
 import { derivePath } from './naming';
 import { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './wire-headers';
+import { issuesFromWire } from './wire-issues';
 
 /**
  * Loose constraint on purpose: a map of concrete `Action<In, Out>` values must be
@@ -212,6 +213,9 @@ function toUltimateError(text: string, status: number, name: string): UltimateEr
     action: name,
     status,
     code,
+    // Parsed, never taken: `body` is whatever answered the request. A list this build cannot read
+    // is dropped rather than repaired, and `cause` below still carries every rejection in it.
+    issues: issuesFromWire(body['issues']),
     cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${status}`),
     fix: stringOr(body['fix'], `x actions describe ${name} --json`),
     // RFC-9457's `type` IS a documentation URI, so a server that sends no `docs` extension has

package/src/errors.ts

@@ -13,6 +13,7 @@ import {
   UltimateError,
 } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
+import type { ValidationIssue } from '@ultimat3/schema';
 
 // Re-exported, not re-declared: the five idempotency failures moved to their own file when this
 // one reached the line ceiling, and every importer still reads them from `./errors`.
@@ -177,12 +178,32 @@ export class ActionPolicyMissingError extends UltimateError {
 }
 
 export class InputInvalidError extends UltimateError {
-  constructor(name: string, detail: string) {
+  /**
+   * The rejections, addressed by path — `undefined` where the caller had only text.
+   *
+   * A `cause` is one line for a human and an agent to read; a client that renders a form needs to
+   * know WHICH field each rejection belongs to, and splitting the line back apart is guesswork the
+   * moment a message contains the separator. Both travel: the line is unchanged, and this is a
+   * structured channel beside it.
+   */
+  readonly issues: readonly ValidationIssue[] | undefined;
+
+  /**
+   * `detail` is the rendered form of `issues` and must stay so — `formatIssues(issues).join('; ')`,
+   * which is what `validate.ts` (the one caller that passes both) does, and what `validate.test.ts`
+   * pins. The rendering is NOT done here on purpose: this module is reachable from `client.ts`,
+   * which is browser-safe, and `@ultimat3/schema` declares no `sideEffects`, so a value import of
+   * `formatIssues` here would pull that package's whole barrel into every browser bundle holding
+   * the typed client.
+   */
+  constructor(name: string, detail: string, issues?: readonly ValidationIssue[]) {
     super({
       code: 'X_INPUT_INVALID',
       cause: `input for action "${name}" failed validation: ${detail}`,
       fix: `x actions describe ${name} --json  # prints the expected input schema`,
+      ...(issues === undefined ? {} : { meta: { issues } }),
     });
+    this.issues = issues;
   }
 }
 
@@ -233,6 +254,12 @@ export interface RemoteFailure {
    * a `javascript:` in the preferred slot cannot suppress a usable link behind it.
    */
   readonly docs?: readonly (string | undefined)[] | undefined;
+  /**
+   * The per-field rejections the document carried, already parsed — `issuesFromWire`'s answer,
+   * never the raw member. `undefined` where the body had none or where it had one this build
+   * refuses to read, and in both cases `cause` still holds every rejection.
+   */
+  readonly issues?: readonly ValidationIssue[] | undefined;
 }
 
 /** A link, not a string the server happened to put in a field the overlay renders as an href. */
@@ -286,7 +313,14 @@ export class RemoteActionError extends UltimateError {
       // `retryFor(code)`, which fails closed — so a 503 out of a typed call announced itself as
       // `terminal` on the one field the framework promises a client never has to infer.
       retry: retryForStatus(failure.code, failure.status),
-      meta: { origin: 'remote', action: failure.action, status: failure.status },
+      meta: {
+        origin: 'remote',
+        action: failure.action,
+        status: failure.status,
+        // Absent rather than `undefined`: `meta` is rendered into `--json` and the error reporter,
+        // and a null member reads as "the server sent an empty list" rather than "it sent none".
+        ...(failure.issues === undefined ? {} : { issues: failure.issues }),
+      },
     });
     this.status = failure.status;
   }

package/src/index.ts

@@ -67,9 +67,18 @@ export type {
   AuditOutcome,
   AuditRecord,
   AuditSink,
-  MemoryAuditSink,
 } from './audit';
-export { getAuditSink, memoryAuditSink, resetAuditSink, setAuditSink } from './audit';
+export { getAuditSink, resetAuditSink, setAuditSink } from './audit';
+export { AUDIT_INPUT_MAX_DEPTH, auditableInput, UNREPRESENTABLE } from './audit-input';
+export type { MemoryAuditSink, MemoryAuditSinkOptions } from './audit-memory';
+export { DEFAULT_MAX_AUDIT_RECORDS, memoryAuditSink } from './audit-memory';
+/**
+ * The DURABLE sink, and the only one an app that must keep its trail may install. The statements
+ * are exported beside it because the table is applied the way `SQL_IDEMPOTENCY_TABLE` is — by the
+ * boot, never by an app migration.
+ */
+export type { PostgresAuditSink, PostgresAuditSinkOptions } from './audit-postgres';
+export { postgresAuditSink, SQL_AUDIT_INSERT, SQL_AUDIT_TABLE } from './audit-postgres';
 export type {
   ActionLike,
   ActionMap,
@@ -224,3 +233,23 @@ export {
   registerActions,
   resetRegistry,
 } from './registry';
+/**
+ * A mutator FACTORY, never a ninth primitive: `transition()` returns a `mutator`, so a move through
+ * a state machine inherits the route, the OpenAPI operation, the typed client, the MCP tool, the job
+ * handle and its manifest row. The machine itself is `@ultimat3/entity`'s — this package owns the
+ * projection, not the legality rule.
+ */
+export type {
+  TransitionDef,
+  TransitionInput,
+  TransitionTarget,
+  TransitionValues,
+} from './transition';
+export { transition } from './transition';
+/**
+ * The one reader of a problem document's `issues` member. Exported because the typed client is not
+ * the only caller that meets one: an island that posts with a plain `fetch` — which is what
+ * `x g resource` emits, to keep this package out of its chunk — holds the parsed body itself and
+ * would otherwise write a second, unvalidated reader.
+ */
+export { issuesFromWire, MAX_WIRE_ISSUES } from './wire-issues';

package/src/transition.ts

@@ -0,0 +1,144 @@
+/**
+ * `transition()` — a MUTATOR factory over one entity column's state machine. Not a ninth primitive:
+ * a move is a server-authoritative write with an input schema, an output schema and a policy, which
+ * is what a `mutator` already is, so this RETURNS one and inherits the route, the OpenAPI operation,
+ * the typed client, the MCP tool, the job handle and its manifest row.
+ *
+ * It lives here and not in `@ultimat3/entity` because `mutator()` is tier 3 and entity is tier 2 —
+ * the same relationship `search()` has to `@ultimat3/query`. The mechanism underneath is entity's:
+ * this file makes no legality decision and answers no refusal of its own.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import type {
+  InferOutput,
+  ObjectSchema,
+  Schema,
+  StandardSchemaV1,
+  StringSchema,
+} from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+import { type LocalRow, type Mutator, mutator } from './mutator';
+import type { ActionPolicy } from './policy-gate';
+
+/**
+ * The one method this factory calls, declared structurally: `@ultimat3/entity`'s `Table.transition`
+ * satisfies it as written. Structural and not an import because `@ultimat3/action` holds no
+ * dependency edge on `@ultimat3/entity` — the tier table permits one (2 is below 3), the manifest
+ * and the lockfile do not — the same trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down.
+ *
+ * `id` is a plain `string` rather than entity's `IdOf<Row>`: that alias "collapses to `string` for
+ * every unbranded entity" by its own account, and a branded one still satisfies this because a
+ * method's parameters compare bivariantly. The input schema mints a `string`, so declaring anything
+ * narrower here would buy a cast and nothing else.
+ */
+/**
+ * The input every transition takes, spelled once: the row, the state the caller believes it is in,
+ * and the state it wants. Named because it is what the typed client and the MCP tool are typed by.
+ */
+/** The parsed input, spelled concretely — what `TransitionInput<S>` reduces to at every call site. */
+export interface TransitionValues<S extends string> {
+  readonly id: string;
+  readonly from: S;
+  readonly to: S;
+}
+
+export type TransitionInput<S extends string> = ObjectSchema<{
+  readonly id: StringSchema;
+  readonly from: Schema<S, S>;
+  readonly to: Schema<S, S>;
+}>;
+
+export interface TransitionTarget<Row, S extends string> {
+  transition(column: string, id: string, move: { readonly from: S; readonly to: S }): Promise<Row>;
+}
+
+export interface TransitionDef<
+  TOutput extends StandardSchemaV1,
+  Row extends InferOutput<TOutput> & object,
+  K extends keyof Row & string,
+  S extends Row[K] & string,
+> {
+  /** The request's table — `(ctx) => posts(ctx)`, so the move is tenant-scoped like every write. */
+  readonly table: (ctx: Ctx) => TransitionTarget<Row, S>;
+  /** The column whose `enumerated().transitions()` declaration IS the machine. */
+  readonly column: K;
+  /**
+   * The states, as the input schema. Typed `Row[K]`, so a state the row cannot hold is a compile
+   * error here — and every projection inherits the enum: OpenAPI documents the legal set, the MCP
+   * tool's `inputSchema` carries it, the typed client refuses a typo at COMPILE time, and a
+   * misspelled state is `X_INPUT_INVALID` before the request reaches a database.
+   *
+   * It is the one thing restated from the column's own declaration, and the reason is a boundary:
+   * reading the machine off the entity needs `@ultimat3/entity` as a real dependency of this
+   * package. Listing a SUBSET refuses a legal move at the input schema — loud, and the fix is the
+   * enum in the refusal.
+   */
+  readonly states: readonly [S, ...S[]];
+  /** The local store's name for this entity — what the optimistic twin patches. */
+  readonly localTable: string;
+  /** The projection the caller gets back. Unknown keys are dropped by the parse, so a `$view` works. */
+  readonly output: TOutput;
+  readonly policy: ActionPolicy;
+  /**
+   * OFF unless the app says otherwise, and deliberately not `?? true`.
+   *
+   * A transition is exactly the kind of event an audit sink is for — and `audit: true` with no sink
+   * installed is `X_AUDIT_SINK_MISSING`, raised before the input parse. Defaulting it on would make
+   * every `transition()` refuse in an app that has not made a separate, unrelated decision, which is
+   * a framework default holding the feature hostage. What the row is kept for, and for how long, is
+   * the same compliance question that kept a purge out of `postgresAuditSink`.
+   */
+  readonly audit?: boolean;
+}
+
+/**
+ * `from` is REQUIRED and is never defaulted or inferred. It rides in the UPDATE's own predicate, so
+ * the state observed and the state written are one decision under the row's lock — optimistic
+ * concurrency in the ETag shape. Measured on the mechanism underneath: twenty concurrent moves at
+ * one row produced 14 winners with a read-then-check-then-write, and 1 winner plus 19 refusals with
+ * `from` in the predicate. Anything that supplies `from` on the caller's behalf is the lost update
+ * coming back.
+ */
+export function transition<
+  TOutput extends StandardSchemaV1,
+  Row extends InferOutput<TOutput> & object,
+  K extends keyof Row & string,
+  const S extends Row[K] & string,
+>(def: TransitionDef<TOutput, Row, K, S>): Mutator<TransitionInput<S>, TOutput> {
+  const state = t.enum(def.states);
+  // ONE cast, and it is a compiler limitation rather than an unknown value: `t.object`'s output is
+  // a mapped type over its shape, and a mapped type does not reduce while a type parameter is still
+  // open — so `input.id` is unreachable INSIDE this function even though every call site resolves
+  // it exactly. `@ultimat3/entity`'s `transitionRow` spells its own patch this way for the same
+  // reason. What arrives here has already been parsed by the schema two lines up, and nothing else
+  // can reach these two callbacks.
+  const valuesOf = (raw: unknown): TransitionValues<S> => raw as TransitionValues<S>;
+  return mutator({
+    input: t.object({ id: t.uuid, from: state, to: state }),
+    output: def.output,
+    policy: def.policy,
+    ...(def.audit === undefined ? {} : { audit: def.audit }),
+    // Never overridable: the server is the half that REFUSED the move, and a local twin that won
+    // the rebase would leave the client showing a state the database rejected.
+    conflict: 'server-wins',
+    local: (tx, raw) => {
+      const input = valuesOf(raw);
+      // `as Partial<…>`: a computed key widens to an index signature, which is never assignable to
+      // a `Partial` of a type parameter. `def.column` is `keyof Row`, so the shape is a real one.
+      tx.table<Row & LocalRow>(def.localTable).update(input.id, {
+        [def.column]: input.to,
+      } as Partial<Row & LocalRow>);
+    },
+    // No cast on `from`/`to`: they are the enum's own union, which is `Row[K]`. And no legality
+    // check here — `X_STATE_TRANSITION_ILLEGAL`, `X_STATE_CONFLICT` and `X_STATE_UNDECLARED` are
+    // entity's and propagate as they are. A second error class over one failure is a second path.
+    server: (ctx, raw) => {
+      const input = valuesOf(raw);
+      return def.table(ctx).transition(def.column, input.id, {
+        from: input.from,
+        to: input.to,
+      });
+    },
+  });
+}

package/src/validate.ts

@@ -5,9 +5,19 @@
  */
 
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import { formatIssues, validateAsync } from '@ultimat3/schema';
+import { formatIssues, toValidationIssues, validateAsync } from '@ultimat3/schema';
 import { InputInvalidError, OutputInvalidError } from './errors';
 
+/**
+ * The refusal carries the issue list as well as the line, and the two are ONE value rendered twice:
+ * `formatIssues` reads `path` and `message`, which is exactly what `toValidationIssues` copied out
+ * of the library's own issues, so the string is byte-identical to the one this threw before.
+ *
+ * `toValidationIssues`, never the raw `result.issues`: a conforming library's issue object may
+ * carry members Ultimate's shape does not — including the rejected VALUE — and this list is
+ * handed to an HTTP surface that returns it to the caller. Four members travel, and
+ * `describeValue` is what keeps a value out of the fifth.
+ */
 export async function validateInput<S extends StandardSchemaV1>(
   schema: S,
   raw: unknown,
@@ -15,7 +25,8 @@ export async function validateInput<S extends StandardSchemaV1>(
 ): Promise<InferOutput<S>> {
   const result = await validateAsync(schema, raw);
   if (result.issues !== undefined) {
-    throw new InputInvalidError(actionName, formatIssues(result.issues).join('; '));
+    const issues = toValidationIssues(result.issues);
+    throw new InputInvalidError(actionName, formatIssues(issues).join('; '), issues);
   }
   return result.value;
 }

package/src/wire-issues.ts

@@ -0,0 +1,47 @@
+/**
+ * The one reader of a problem document's `issues` member: an untrusted array off the wire, back
+ * into the `ValidationIssue` shape `@ultimat3/schema` already mints. Its own module because it is
+ * the only place in the client where a value nobody in this process built is turned into a
+ * structure another layer will render.
+ */
+
+import { stringField } from '@ultimat3/core';
+import type { ValidationIssue } from '@ultimat3/schema';
+
+/**
+ * A list this long is not a form's worth of rejections; it is a body meant to be expensive. The
+ * entries are rendered into a DOM by whoever displays them, so the bound is here rather than there.
+ */
+export const MAX_WIRE_ISSUES = 100;
+
+/**
+ * All-or-nothing on purpose. A partly-parsed list would DROP the entries it could not read, and
+ * nothing downstream would know: a caller that finds `meta.issues` uses it INSTEAD of the
+ * flattened `cause`, so a dropped entry is a rejection the user never hears about. Refusing the
+ * whole list leaves the `cause` — which still holds every issue — as the answer.
+ */
+export function issuesFromWire(value: unknown): readonly ValidationIssue[] | undefined {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_WIRE_ISSUES) {
+    return undefined;
+  }
+  const issues: ValidationIssue[] = [];
+  for (const entry of value as readonly unknown[]) {
+    if (typeof entry !== 'object' || entry === null) return undefined;
+    // Strict on the two members that DECIDE where an issue lands, defaulted on the two that only
+    // describe it: a `path` that is not a string would bind a rejection somewhere it does not
+    // belong, while a missing `expected` cannot mis-route anything.
+    const path = stringField(entry, 'path');
+    const message = stringField(entry, 'message');
+    if (path === undefined || message === undefined || message.length === 0) return undefined;
+    // Built member by member, never spread: a foreign issue object may carry the rejected VALUE
+    // (some libraries put it in `received`), and a whole-object copy would forward it to whoever
+    // renders the list. Four members travel; everything else stops here.
+    issues.push({
+      path,
+      expected: stringField(entry, 'expected') ?? '',
+      received: stringField(entry, 'received') ?? '',
+      message,
+    });
+  }
+  return issues;
+}