@ultimat3/action 20.2.0 → 21.0.0

package/CLAUDE.md

@@ -5,6 +5,7 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 ## Boundary
 
 - May import: `core`, `schema` (t0), `cache`, `i18n`, `time` (t1), `entity`, `policy`, `http` (t2).
+  `entity` is a real edge since 21.0.0 (`record-wire.ts` → `hasEntityRows`/`rowsOf`), downward 3→2.
 - Never import: `query`, `jobs`, `realtime` (sideways), or any tier 4-5 package.
 - Never re-implement authz, validation or caching — call `policy`, `schema`, `cache`.
 
@@ -20,7 +21,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call |
 | `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) |
+| `client.ts` | typed RPC client (browser-safe: no server imports) — dispatches through core's `clientTransport` |
+| `record-wire.ts` | the record envelope on the HTTP projection: `carriesRecords` (from the output schema), the enveloped 200, and its OpenAPI shape. Server-only — `client.ts` never imports it |
 | `wire-issues.ts` | the ONE reader of a problem document's `issues` member — an untrusted array back into `@ultimat3/schema`'s `ValidationIssue` shape |
 | `transition.ts` | `transition()`: a MUTATOR factory over one entity column's state machine. Declares no error code — entity's three propagate |
 | — | opt-in flight control is **`@ultimat3/core`**'s `client-flight.ts` + `client-wire.ts`, re-exported from `src/index.ts`. There is no local copy and must not be one |
@@ -46,6 +48,32 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 
 ## Invariants
 
+- **Every browser call goes through `@ultimat3/core`'s `clientTransport`, `As of 2026-09-22`.**
+  `client.ts` hands it the method, the URL (core's `actionPath`, the one path rule — `naming.ts`'s
+  `derivePath`/`pluralize`/`splitWords` are core's too, re-exported), body, headers, signal,
+  idempotency key, flight and this call's `retry`; the transport owns credentials, the JSON body,
+  the idempotency header, envelope decode, adoption into `pageClient().store`, the principal fence
+  and the terminal `fetch`. Only what the action alone knows rides in as hooks: `onResponse` (the
+  build-id check, `X_CONTRACT_DRIFT`) and `decodeError` (`RemoteActionError` for a body naming a
+  framework code; `undefined` otherwise, so the transport answers `X_CLIENT_TRANSPORT_FAILED` — the
+  same code a query gets for the same failure). `X_RPC_FAILED` / `RpcFailedError` stay registered
+  and exported — a shipped code never changes — and nothing in the framework throws them since
+  21.0.0.
+  `retry` is computed here — `{ attempts: 1 }` unless the call carries an idempotency key — so a
+  flight-wide retry never re-sends an unkeyed write.
+- **The record envelope is derived from the output schema, decided per ACTION, never per
+  response.** `carriesRecords(output)` is `@ultimat3/entity`'s `hasEntityRows`, evaluated once in
+  `toRoute`; an enveloped action answers `{ data, records }` under `x-ultimate-records: 1` even
+  when this call returned no row, so one operation has one wire shape and one OpenAPI schema. An
+  output with no entity row is byte-identical on the wire and in the spec — `record-wire.test.ts`
+  pins both, the bytes as `JSON.stringify(output)`. The envelope is HTTP-only: MCP, `.job()` and a
+  direct call still answer the bare output.
+- **`conflict` is `@ultimat3/core`'s `ConflictPolicy`, over ROWS.** `custom(merge)` builds
+  `{ kind: 'custom', merge(localRow, serverRow) }`; the output-shaped `CustomConflict`,
+  `Conflict<T>`, `strategyOf` and this package's `resolveConflict` are deleted (21.0.0) — core's
+  `resolveConflict` is the one resolver, and its `last-write-wins` compares the server's
+  `updatedAt` rather than preferring the local side. `strategyOf` survives as a private helper for
+  `describeMutator()`.
 - **`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
@@ -190,6 +218,12 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   What this does NOT close: an anonymous actor is one identity, so anonymous callers of a public
   idempotent action still share a key space — nothing at this tier can tell two apart, and keying
   on an IP or a cookie would break the retry the header exists to serve.
+- **The `idempotency-key` header also NAMES the write, on every action, idempotent or not.**
+  `http.ts` runs `invoke` inside `withWriteOrigin(writeDigest(key))` (`@ultimat3/core`), so the
+  rows the handler writes reach a channel's `records` frame carrying that digest, and the page
+  that sent the key recognises its own echo (see `packages/realtime/CLAUDE.md`). It is a label and
+  never a gate: a missing or blank header names nothing, and the blank-header refusal above still
+  belongs to `def.idempotent` alone. `http.test.ts`, "the write a request names".
 - **Both stores FENCE a settlement on the reservation `id` AND on `in-flight`**, as
   `@ultimat3/jobs`' `SQL_ACK` fences on `id = $1 and state = 'running'`. A reservation whose window
   lapsed is reclaimed by the next caller (`on conflict … do update`), so a straggler from the first
@@ -304,7 +338,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   still separates them only for a package that declared its own `docs:`, which is why the branch
   stays. The
   code must be `X_SCREAMING_SNAKE` to be taken at all — `typeof code === 'string'` accepted `""`
-  from a gateway — and anything else is `RpcFailedError`, which is what that code means.
+  from a gateway — and anything else is core's `X_CLIENT_TRANSPORT_FAILED` (it was
+  `RpcFailedError` until 21.0.0).
   `docs` and `type` travel to `remoteDocs` as an ordered pair, not `docs ?? type`: preference is
   not selection, and picking the preferred slot on presence alone let one `javascript:` string
   bury a perfectly good `type` the same response had already offered.
@@ -548,14 +583,30 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   promises. It lives in `packages/core/src/client-flight.ts` now; the tests that pin it from this
   side still drive it through this package's own client.
 - **`ClientFlight` is a TYPE inside `client.ts` and never a value.** That erasure is the entire
-  tree-shaking story: `rpc` alone is 14,759 B minified for the browser and `queryClient` alone is
-  12,755 B, against 20,292 B / 17,912 B with `createClientFlight` imported beside them — ±376 B run
-  to run, which is `Bun.build` 1.4.0 dropping core's `schema-error-codes.ts` (issue #273). A caller
-  who wants a plain typed fetch must not pay for the fence, the dedup map or the retry loop —
-  `packages/cli/src/templates/resource-form-island.ts` and `examples/dummy`'s contact-sales island
-  both write a bare `fetch` today because that bill used to be unavoidable. Never import
-  `createClientFlight` for a VALUE from `client.ts` — `ClientFlight` and `ClientRetry` are
-  `import type` from `@ultimat3/core` and must stay that way.
+  tree-shaking story: a caller who wants a plain typed call must not pay for the fence, the dedup
+  map or the retry loop. Never import `createClientFlight` for a VALUE from `client.ts` —
+  `ClientFlight` and `ClientRetry` are `import type` from `@ultimat3/core` and must stay that way.
+  **Measured, `bun build --target=browser --minify`, one entry importing from `@ultimat3/action`,
+  `As of 2026-09-22`:**
+
+  | Entry | before (HEAD `98d16d84`) | onto `clientTransport` | trace headers moved to core's outbound slot | As of 2026-09-23 |
+  |---|---|---|---|---|
+  | `rpc` | 18,097 B | 23,007 B | 18,119 B | 19,074 B |
+  | `rpc` + `createClientFlight` | 23,903 B | 28,823 B | not measured | 25,197 B |
+
+  This is the ONE table for these figures; `packages/core/CLAUDE.md` points here. The slot column
+  is the `outbound-headers.ts` change (core's `traceHeaders()` left the browser path; its own
+  "before" read 23,164 B, the transport column re-measured on a later tree). The last column is
+  one entry importing `packages/action/src/index.ts` by path, same flags.
+
+  The 14,759 B this file used to quote does not reproduce on the tree it was checked against
+  (18,097 B); the numbers above are both measured the same way, same day. The growth is +4,910 B,
+  of which the envelope decoder is ~1,020 B (`decodeRecordEnvelope` added to a
+  `UltimateError`+`problemOf`+`traceHeaders` entry: 13,059 → 14,079 B). The rest is core's
+  transport graph — the scope fence, the dispatch module, and core's shared problem decoder, which
+  now answers a body with no framework code (`X_CLIENT_TRANSPORT_FAILED`) behind `decodeError`. That is OVER the plan's bound ("must not grow beyond the envelope decoder") and is
+  reported, not hidden. After the slot moved telemetry out, the net against the pre-transport figure
+  is +977 B (18,097 → 19,074 B, As of 2026-09-23), about the envelope decoder's size.
 - **The `sideEffects` array is what makes the barrel shakable, and it is load-bearing** (`As of
   2026-08-23`). Declaring nothing meant a bundler had to assume every module ran at import, so
   `import { rpc } from '@ultimat3/action'` was 43,104 B and `import { queryClient } from

package/README.md

@@ -116,6 +116,21 @@ export const client = rpc<Api['actions']>({ baseUrl: '/' });
 declaration with no codegen step. `Api` is imported as a **type only**, which is what keeps
 a page's module graph free of any edge to a feature's implementation.
 
+Every call dispatches through `@ultimat3/core`'s `clientTransport` — the one browser HTTP function.
+It owns credentials, the JSON body, the `Idempotency-Key` header, the principal fence and the
+record envelope. The method still resolves to the action's output and nothing else.
+
+### Records — derived from the output schema
+
+An action whose `output:` references an entity row (`posts.$schema`, at any depth — inside an
+object, an array, `.nullable()`) answers `{ data, records }` with `x-ultimate-records: 1`, and the
+transport adopts `records` into the page's one record store on the way past. There is no
+`records:` option: the envelope is derived from the schema, never declared. It is decided **per
+action**, from the schema — an output that only *may* carry a row is enveloped even when this call
+returned none, so one operation has one wire shape. Every other action's body is byte-identical to
+what it was before the envelope existed, and its OpenAPI operation is unchanged; an enveloped one
+documents `data`, `records` and `removed`, and the header, generated from the declaration.
+
 ### Flight control — `createClientFlight`, opt-in
 
 Same object as `@ultimat3/query`'s, installed the same way (`rpc({ baseUrl, flight })`), and the
@@ -142,11 +157,10 @@ await api.charge({ orderId }, { idempotencyKey: `charge:${orderId}`, retry: { at
 It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
 this package exactly as before.
 
-Importing `rpc` alone from this package is **14,759 B** minified for the browser; adding
-`createClientFlight` is **20,292 B**. `ClientFlight` is a TYPE inside `client.ts` and never a
-value, which is what keeps the second number off the first caller's bill. Expect ±376 B run to
-run — `Bun.build` 1.4.0 drops `@ultimat3/core`'s `schema-error-codes.ts` from some builds even
-though `sideEffects` names it (issue #273), which is the size of the schema error titles.
+Importing `rpc` alone from this package is **23,007 B** minified for the browser; adding
+`createClientFlight` is **28,823 B** (`As of 2026-09-22`; `CLAUDE.md` carries the before/after and
+what the delta is). `ClientFlight` is a TYPE inside `client.ts` and never a value, which is what
+keeps the second number off the first caller's bill.
 
 ## Path derivation
 
@@ -217,10 +231,15 @@ export const likePost = mutator({
       p.likedByMe ? {} : { likedByMe: true, likeCount: p.likeCount + 1 });
   },
   async server(ctx, { postId }) { return ctx.posts.like(postId); },
-  conflict: 'server-wins', // | 'last-write-wins' | custom(merge)
+  conflict: 'server-wins', // | 'last-write-wins' | custom((localRow, serverRow) => row)
 });
 ```
 
+`conflict` is `@ultimat3/core`'s `ConflictPolicy` — the one vocabulary realtime's rebase reads.
+`custom(merge)` receives the local **row** and the server **row** (the store is row-shaped) and
+returns the row that survives; `resolveConflict(policy, local, server)` is core's, not this
+package's.
+
 The projected surface carries the same three names the declaration used, on top of
 every action member above:
 
@@ -236,9 +255,12 @@ denies is denied there exactly as over HTTP. `.local()` is the only half that sk
 the core, because it never leaves the client; keep it a pure function of `(tx, input)`
 — no I/O, no clock, no randomness — since every rebase replays it.
 
-`LocalTx` is the client write surface (`@ultimat3/realtime` implements it over OPFS
-SQLite). Type your tables once: `declare module '@ultimat3/action' { interface
-LocalTables { posts: PostRow } }`.
+`LocalTx` is the client write surface, implemented by `@ultimat3/realtime` over the page's
+record store — the SAME shape as that store's tx. Every table is addressed by **key**:
+`get(key)`, `all()`, `insert(key, row)`, `upsert(key, row)`, `update(key, patch | fn)`,
+`delete(key)`. The key is the caller's because the browser holds no entity schema and cannot
+derive a primary key — an optimistic insert names the key its server twin will answer under.
+Type your tables once: `declare module '@ultimat3/action' { interface LocalTables { posts: PostRow } }`.
 
 ## `transition()` — a mutator factory over a state machine
 
@@ -602,7 +624,7 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_IDEMPOTENCY_REPLAYED_FAILURE` | a retried key replays a first attempt that failed and carried no framework code of its own | read the first attempt, then send a fresh key |
 | `X_IDEMPOTENCY_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 --contract` |
-| `X_RPC_FAILED` | non-`problem+json` failure, or a body naming no `X_` code | check the gateway |
+| `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 |
 | `X_AUDIT_SINK_FAILED` | the sink refused the record for an attempt that **succeeded** | fix the sink — then retry the same `Idempotency-Key` if this call carried one, else reconcile by hand |
@@ -625,5 +647,5 @@ the body itself.
 
 ## Boundaries
 
-Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `policy`, `http`. Never imports
+Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `entity`, `policy`, `http`. Never imports
 `query`, `jobs`, `realtime` (same tier) or anything above it — those import *this*.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "20.2.0",
+  "version": "21.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,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "20.2.0",
-    "@ultimat3/core": "20.2.0",
-    "@ultimat3/http": "20.2.0",
-    "@ultimat3/policy": "20.2.0",
-    "@ultimat3/schema": "20.2.0"
+    "@ultimat3/cache": "21.0.0",
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/entity": "21.0.0",
+    "@ultimat3/http": "21.0.0",
+    "@ultimat3/policy": "21.0.0",
+    "@ultimat3/schema": "21.0.0"
   }
 }

package/src/client.ts

@@ -8,14 +8,25 @@
  * not pay a byte for any of them — an `import type` is erased and the value import would not be.
  * Dedup is deliberately unreachable from this file — a mutation may never join another mutation,
  * and the way that is guaranteed is that `keyFor` is never called here.
+ *
+ * Every call dispatches through core's `clientTransport`: credentials, the JSON body, the
+ * idempotency header, the record envelope and its adoption into the page store, and the principal
+ * fence are decided there once. This file adds only what the action alone knows — the build-id
+ * check (`onResponse`) and the action-named error decode (`decodeError`). The caller still gets exactly the action's output — the envelope
+ * never reaches the return type.
  */
-import type { ClientFlight, ClientRetry, UltimateError, WireAnswer } from '@ultimat3/core';
-import { FRAMEWORK_CODE, isJsonObject, problemOf, traceHeaders } from '@ultimat3/core';
+import type { ClientFlight, ClientRetry, FetchLike, UltimateError } from '@ultimat3/core';
+import {
+  actionPath,
+  clientTransport,
+  FRAMEWORK_CODE,
+  isJsonObject,
+  problemOf,
+} from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 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 { ContractDriftError, RemoteActionError } from './errors';
+import { BUILD_ID_HEADER } from './wire-headers';
 import { issuesFromWire } from './wire-issues';
 
 /**
@@ -52,7 +63,8 @@ export type ClientMethod<TIn extends StandardSchemaV1, TOut extends StandardSche
   options?: CallOptions,
 ) => Promise<InferOutput<TOut>>;
 
-export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Core's one declaration, re-exported by name so `import type { FetchLike }` keeps resolving. */
+export type { FetchLike } from '@ultimat3/core';
 
 export interface ClientOptions {
   readonly baseUrl: string;
@@ -61,8 +73,8 @@ export interface ClientOptions {
   readonly buildId?: string;
   readonly headers?: Readonly<Record<string, string>>;
   /**
-   * Opt-in flight control — `createClientFlight({ … })`. Absent, a call is one `fetch` and nothing
-   * else, which is what every caller written before this option existed already gets.
+   * Opt-in flight control — `createClientFlight({ … })`. Absent, a call is one dispatch and
+   * nothing else, which is what every caller written before this option existed already gets.
    */
   readonly flight?: ClientFlight;
 }
@@ -97,84 +109,44 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
   name: string,
   options: ClientOptions,
 ): ClientMethod<TInput, TOutput> {
-  const doFetch: FetchLike = options.fetch ?? ((input, init) => fetch(input, init));
-  const base = options.baseUrl.replace(/\/+$/, '');
+  const url = `${options.baseUrl.replace(/\/+$/, '')}${actionPath(name)}`;
+  const onResponse = (response: Response): void =>
+    assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);
+  const decodeError = (status: number, text: string): UltimateError | undefined =>
+    toUltimateError(text, status, name);
   // Erased at the wire seam; the response type is this action's by construction.
   return (input, callOptions = {}) =>
-    call(doFetch, base, options, name, input, callOptions) as Promise<InferOutput<TOutput>>;
+    clientTransport({
+      method: 'POST',
+      url,
+      body: input ?? {},
+      headers: headersFor(options),
+      signal: callOptions.signal,
+      idempotencyKey: callOptions.idempotencyKey,
+      flight: options.flight,
+      // Only alongside a key: a retried mutation with no key is a second write, not a second
+      // attempt, so the flight's own policy is overridden with one attempt rather than inherited.
+      // With a key, an absent per-call policy is `undefined`, which the flight reads as "mine".
+      retry: callOptions.idempotencyKey === undefined ? ONCE : callOptions.retry,
+      onResponse,
+      decodeError,
+      fetchImpl: options.fetch,
+    }) as Promise<InferOutput<TOutput>>;
 }
 
 /** One attempt, and no retry at all. What a mutation carrying no idempotency key is allowed. */
 const ONCE: ClientRetry = { attempts: 1 };
 
-async function call(
-  doFetch: FetchLike,
-  base: string,
-  options: ClientOptions,
-  name: string,
-  input: unknown,
-  callOptions: CallOptions,
-): Promise<unknown> {
-  const url = `${base}${derivePath(name).path}`;
-  const body = JSON.stringify(input ?? {});
-  const dispatch = (signal: AbortSignal | undefined): Promise<WireAnswer> =>
-    postOnce(doFetch, url, body, options, name, callOptions, signal ?? callOptions.signal);
-
-  const flight = options.flight;
-  const answer =
-    flight === undefined
-      ? await dispatch(undefined)
-      : await flight.run({
-          // `undefined`, unconditionally: a mutation may never join another mutation, and the
-          // enforcement is that this file never calls `flight.keyFor`.
-          key: undefined,
-          // NEVER aborted. A fence bump and a deadline both mean "this answer no longer matters";
-          // closing the socket does not un-commit the write, it only destroys the one chance this
-          // caller had of learning whether it landed.
-          abortable: false,
-          retry: callOptions.idempotencyKey === undefined ? ONCE : (callOptions.retry ?? ONCE),
-          run: dispatch,
-        });
-  if (answer.status === 204) return undefined;
-  return JSON.parse(answer.text) as unknown;
-}
-
-/** One dispatch. Everything above it decides how many times this happens; it decides none. */
-async function postOnce(
-  doFetch: FetchLike,
-  url: string,
-  body: string,
-  options: ClientOptions,
-  name: string,
-  callOptions: CallOptions,
-  signal: AbortSignal | undefined,
-): Promise<WireAnswer> {
-  const headers: Record<string, string> = {
-    'content-type': 'application/json',
-    // Before the caller's headers, so an explicit `traceparent` still wins. Without this a
-    // service-to-service hop started a fresh root trace on the other side, which makes "which of
-    // my downstreams is slow" unanswerable across every Ultimate-to-Ultimate call.
-    ...traceHeaders(),
-    ...options.headers,
-  };
+/**
+ * The caller's headers plus the build id. The trace and the request budget are NOT here: the
+ * transport adds them server-side from its outbound-header slot (`@ultimat3/core`'s
+ * `outbound-headers.ts`), before these, so an explicit `traceparent` still wins — and a browser,
+ * which never has a trace, no longer bundles telemetry to learn that.
+ */
+function headersFor(options: ClientOptions): Readonly<Record<string, string>> {
+  const headers: Record<string, string> = { ...options.headers };
   if (options.buildId !== undefined) headers[BUILD_ID_HEADER] = options.buildId;
-  if (callOptions.idempotencyKey !== undefined) {
-    headers[IDEMPOTENCY_HEADER] = callOptions.idempotencyKey;
-  }
-
-  const init: RequestInit = {
-    method: 'POST',
-    headers,
-    body,
-    ...(signal === undefined ? {} : { signal }),
-  };
-  const response = await doFetch(url, init);
-  assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);
-  // Read as TEXT once: a `Response` body is a single-use stream, so the failure path and the
-  // answer path cannot both have it.
-  const text = response.status === 204 ? '' : await response.text();
-  if (!response.ok) throw toUltimateError(text, response.status, name);
-  return { status: response.status, text };
+  return headers;
 }
 
 /**
@@ -198,17 +170,19 @@ function assertSameBuild(
  * `application/problem+json` back into the error the server threw. The code rides along
  * verbatim — carrying one is the point of the document — but it is a code this bundle may never
  * have registered, so the result is a `RemoteActionError`: marked remote-origin, and linked only
- * to a page that exists. A body naming no framework code is a proxy answering rather than the
- * app, which is what `RpcFailedError` already says.
+ * to a page that exists.
+ *
+ * A body naming no framework code is a proxy answering rather than the app, and that answer is
+ * `undefined` here: the transport's shared decode makes it `X_CLIENT_TRANSPORT_FAILED`, the SAME
+ * code a query gets for the same failure. `X_RPC_FAILED` was this branch until 21.0.0; the code
+ * stays registered (shipped codes never change) and nothing in the framework throws it now.
  */
-function toUltimateError(text: string, status: number, name: string): UltimateError {
+function toUltimateError(text: string, status: number, name: string): UltimateError | undefined {
   // `problemOf` is total — a gateway's HTML, an empty body and a truncated stream all answer `{}`,
-  // which carries no `code` and therefore lands on `RpcFailedError` exactly as before.
+  // which carries no `code` and therefore falls through to the transport's decode.
   const body = problemOf(text);
   const code = body['code'];
-  if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
-    return new RpcFailedError(name, status);
-  }
+  if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) return undefined;
   return new RemoteActionError({
     action: name,
     status,

package/src/errors.ts

@@ -9,6 +9,7 @@ import {
   ERROR_DOCS_URL,
   hasErrorCode,
   registerErrorCodes,
+  renderFixShellArg,
   retryForStatus,
   UltimateError,
 } from '@ultimat3/core';
@@ -50,6 +51,8 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
     'a retried Idempotency-Key replays a first attempt that failed after it may have committed',
   X_IDEMPOTENCY_STATUS_UNKNOWN: 'an idempotency record holds a status this build cannot read',
   X_INPUT_INVALID: 'input failed schema validation',
+  X_MUTATOR_CLOCK_MISSING:
+    "a mutator declares conflict: 'last-write-wins' and its entity has no number clock column",
   X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
   X_RPC_FAILED: 'an RPC call failed without a problem+json body',
 };
@@ -301,7 +304,7 @@ function remoteDocs(code: string, sent: readonly (string | undefined)[] = []): s
  * policy decision — but a code the server owns is one this bundle may never have registered, so
  * the error says where it came from rather than passing as locally declared: `name` marks it in
  * a stack trace and `meta.origin` marks it in `--json`, the dev overlay and the error reporter.
- * `RpcFailedError` stays the answer when no framework code came back at all.
+ * A body naming no framework code is core's `X_CLIENT_TRANSPORT_FAILED`, as it is for a query.
  */
 export class RemoteActionError extends UltimateError {
   override readonly name = 'RemoteActionError';
@@ -336,7 +339,12 @@ export class RemoteActionError extends UltimateError {
   }
 }
 
-/** The client got a non-`problem+json` failure — a proxy, not our server, answered. */
+/**
+ * A non-`problem+json` failure — a proxy, not our server, answered. **No framework code throws this
+ * since 21.0.0**: the typed client answers that failure with core's `X_CLIENT_TRANSPORT_FAILED`, the
+ * code a query gets. Kept exported and `X_RPC_FAILED` kept registered because a shipped code never
+ * changes and an app may still construct or match it.
+ */
 export class RpcFailedError extends UltimateError {
   constructor(name: string, status: number) {
     super({
@@ -401,6 +409,30 @@ export class AuditSinkFailedError extends UltimateError {
   }
 }
 
+/**
+ * `conflict: 'last-write-wins'` with nothing to compare. Refused at declaration, because the
+ * alternative is a policy that reads as "newest wins" and resolves to the server row every time.
+ */
+export class MutatorClockMissingError extends UltimateError {
+  constructor(entity: string | undefined, clock: string) {
+    super(
+      entity === undefined
+        ? {
+            code: 'X_MUTATOR_CLOCK_MISSING',
+            cause: `a mutator declares conflict: 'last-write-wins' and its output carries no entity row, so there is no ${clock} to compare`,
+            fix: "return the entity row from the mutator's output, or declare conflict: 'server-wins'",
+            meta: { clock },
+          }
+        : {
+            code: 'X_MUTATOR_CLOCK_MISSING',
+            cause: `a mutator declares conflict: 'last-write-wins' and entity ${entity} has no number ${clock} column the server writes, so the server row would win every time`,
+            fix: `add ${clock} (a number, epoch ms, written by the server) to ${renderFixShellArg(entity, '<entity>')}, or declare conflict: 'server-wins'`,
+            meta: { entity, clock },
+          },
+    );
+  }
+}
+
 export class ContractDriftError extends UltimateError {
   constructor(cause: string, fix: string) {
     super({ code: 'X_CONTRACT_DRIFT', cause, fix });

package/src/http.ts

@@ -6,7 +6,14 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import { isMcpExposed, isUltimateError } from '@ultimat3/core';
+import {
+  isMcpExposed,
+  isUltimateError,
+  RECORDS_OPENAPI_HEADER,
+  recordEnvelopeSchema,
+  withWriteOrigin,
+  writeDigest,
+} from '@ultimat3/core';
 import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
 // `toBucket` is `@ultimat3/http`'s, not this package's: http owns `Bucket` and the limiter maths,
 // and `@ultimat3/query` needs the identical conversion while being the same tier as this one — so
@@ -26,6 +33,7 @@ import {
   toOperationId,
 } from './naming';
 import { admitsAnonymous, policyCapability } from './policy-gate';
+import { carriesRecords, recordResponse } from './record-wire';
 import { IDEMPOTENCY_HEADER } from './wire-headers';
 
 /**
@@ -37,6 +45,12 @@ export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './wire-headers';
 
 export const REPLAYED_HEADER = 'x-ultimate-replayed';
 
+/** The digest a request's idempotency key names its write by; none for a missing or blank one. */
+async function writeOriginOf(req: UltimateRequest): Promise<string | undefined> {
+  const key = req.header(IDEMPOTENCY_HEADER);
+  return key === null || key === '' ? undefined : await writeDigest(key);
+}
+
 /**
  * `publishPost` -> `POST /api/posts/publish`. Derivation: the first camelCase word
  * is the verb, the rest is the resource with its last word pluralized and
@@ -49,6 +63,7 @@ export function toRoute(target: AnyAction): Route {
   // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
   // not a surprise on the first request — the same rule `toBucket` follows for a rate limit.
   const sunsetting = deprecationHeadersFor(name, def.deprecated);
+  const enveloped = carriesRecords(target.output);
 
   const handler = async (req: UltimateRequest): Promise<Response> => {
     if (sunsetting !== undefined) recordDeprecatedCall('action', name);
@@ -58,20 +73,30 @@ export function toRoute(target: AnyAction): Route {
       const raw = await req.bodyRaw();
       const key = def.idempotent === true ? req.header(IDEMPOTENCY_HEADER) : null;
       let replayed = false;
-      const result = await invoke(target, raw, {
-        surface: 'http',
-        idempotencyKey: key,
-        onReplay: () => {
-          replayed = true;
-        },
-      });
+      // The header NAMES the write whatever the declaration, idempotent or not: a page sends one
+      // with every mutation, and the `records` frames its rows produce carry the digest so that
+      // page can tell its own echo from somebody else's change (`@ultimat3/core`'s write origin).
+      const result = await withWriteOrigin(await writeOriginOf(req), () =>
+        invoke(target, raw, {
+          surface: 'http',
+          idempotencyKey: key,
+          onReplay: () => {
+            replayed = true;
+          },
+        }),
+      );
       // The one thing an action's return value cannot say. `setRedirect()` inside the handler
       // is how a `<form method="post">` gets an answer a browser follows — a `Location` on the
       // 200 this used to always return is a header browsers ignore, so a JS-less form left the
       // reader staring at `{"ok":true}`. Only this projection honours it: a redirect is an HTTP
       // fact, and the MCP tool and the job handle share none of it.
       const to = takeRedirect(req.ctx);
-      const response = to === undefined ? json(result) : redirect(to.location, to.status);
+      const response =
+        to !== undefined
+          ? redirect(to.location, to.status)
+          : enveloped
+            ? recordResponse(target.output, result)
+            : json(result);
       if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0');
       // On the failure path too, below: a client polling a deprecated endpoint that is currently
       // 403ing still has to learn the endpoint is going away. Announcing it only on 200 hides the
@@ -148,6 +173,8 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
   const path = derivePath(name);
   const idempotent = def.idempotent === true;
   const deprecation = deprecationMetaFor(name, def.deprecated);
+  const outputRef = schemaRef(outputSchemaName(name));
+  const enveloped = carriesRecords(target.output);
   return {
     operationId: toOperationId(name),
     tags: [path.resource],
@@ -159,10 +186,15 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
       content: { 'application/json': { schema: { $ref: schemaRef(inputSchemaName(name)) } } },
     },
     responses: {
-      '200': {
-        description: 'ok',
-        content: { 'application/json': { schema: { $ref: schemaRef(outputSchemaName(name)) } } },
-      },
+      // Only an output that references an entity row changes shape: every other operation's
+      // bytes are the ones `x verify`'s contract diff already holds.
+      '200': enveloped
+        ? {
+            description: 'ok',
+            headers: RECORDS_OPENAPI_HEADER,
+            content: { 'application/json': { schema: recordEnvelopeSchema({ $ref: outputRef }) } },
+          }
+        : { description: 'ok', content: { 'application/json': { schema: { $ref: outputRef } } } },
       // BOTH, because they are two different failures and this operation published only one of
       // them while the route answered only the other. `X_INPUT_INVALID` is the body that parsed
       // and failed THIS action's declared schema — the primitive's own code, identical over MCP,

package/src/index.ts

@@ -195,9 +195,6 @@ export { jsonSchemaOf, mcpSchemaOf } from './json-schema';
 export type { McpInvokeOptions, McpToolDescriptor } from './mcp-tool';
 export { isExposed, toMcpTool, toMcpTools } from './mcp-tool';
 export type {
-  Conflict,
-  CustomConflict,
-  LocalRow,
   LocalTable,
   LocalTableName,
   LocalTables,
@@ -206,7 +203,7 @@ export type {
   MutatorDef,
   MutatorDescriptor,
 } from './mutator';
-export { custom, isMutator, mutator, resolveConflict, strategyOf } from './mutator';
+export { custom, isMutator, mutator } from './mutator';
 export type { ActionPath } from './naming';
 export { derivePath, inputSchemaName, outputSchemaName, pluralize } from './naming';
 export type { BuildOpenApiOptions, OpenApiDocument, OpenApiInfo } from './openapi';

package/src/mutator-clock.ts

@@ -0,0 +1,22 @@
+/**
+ * The declaration-time proof `conflict: 'last-write-wins'` needs: every entity row the mutator
+ * answers carries a NUMBER clock column the server writes (`updatedAt`, epoch ms). Without one,
+ * core's `resolveConflict` can never prove the local row newer and the server row wins every time —
+ * `'last-write-wins'` silently became `'server-wins'`, which `examples/dummy`'s `setTheme` shipped.
+ */
+
+import { projectionsIn } from '@ultimat3/entity';
+import { MutatorClockMissingError } from './errors';
+
+/** The field `resolveConflict` compares by default — the one rebase reads with no option set. */
+export const CLOCK_FIELD = 'updatedAt';
+
+/** Throws `X_MUTATOR_CLOCK_MISSING` unless every entity row in `output` has a number clock. */
+export function assertConflictClock(output: unknown): void {
+  const entities = projectionsIn(output);
+  if (entities.length === 0) throw new MutatorClockMissingError(undefined, CLOCK_FIELD);
+  for (const projection of entities) {
+    const clock = projection.schema.properties?.[CLOCK_FIELD];
+    if (clock?.kind !== 'number') throw new MutatorClockMissingError(projection.type, CLOCK_FIELD);
+  }
+}

package/src/mutator.ts

@@ -5,18 +5,13 @@
  * contract tests for free, and its authz is the same single evaluation.
  */
 
-import type { Ctx } from '@ultimat3/core';
-import { assertNever } from '@ultimat3/core';
+import type { ConflictPolicy, Ctx, Row } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action, ActionCache, ActionDef, ActionDescriptor, ActionMcp } from './action';
 import { action, isAction } from './action';
+import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
 
-/** Minimum shape of a locally-stored row: an id the local twin can address. */
-export interface LocalRow {
-  readonly id: string;
-}
-
 /**
  * Augmented by the app so `tx.posts` is typed:
  *
@@ -33,34 +28,47 @@ export interface LocalTables {
 
 export type LocalTableName = Exclude<keyof LocalTables, '~ultimate'>;
 
-export interface LocalTable<TRow extends LocalRow> {
-  insert(row: TRow): void;
-  update(id: string, patch: Partial<TRow> | ((row: TRow) => Partial<TRow>)): void;
-  delete(id: string): void;
+/**
+ * One table as a mutator's `local` half sees it — the SAME shape as `@ultimat3/realtime`'s store tx
+ * (`record-tx.ts`), so a twin typed against this runs against the page's record store unchanged.
+ * Rows are addressed by KEY, never by a column: the browser holds no entity schema and cannot know
+ * a primary key, so an optimistic insert names the key its server twin will answer under.
+ */
+export interface LocalTable<TRow extends object = Row> {
+  get(key: string): TRow | undefined;
+  all(): readonly TRow[];
+  insert(key: string, row: TRow): void;
+  /** Merged over what the table holds; an `undefined` field leaves the column alone. */
+  upsert(key: string, row: TRow): void;
+  /** Changed fields only — or a function returning them. A no-op for a key the table does not hold. */
+  update(key: string, patch: Partial<TRow> | ((row: TRow) => Partial<TRow>)): void;
+  delete(key: string): void;
 }
 
 /**
- * The client-side write surface a mutator's `local()` gets. @ultimat3/realtime
- * implements it over OPFS SQLite; tests implement it over a Map.
+ * The client-side write surface a mutator's `local()` gets. `@ultimat3/realtime` implements it over
+ * the page's record store; tests implement it over a Map.
  */
 export type LocalTx = {
-  readonly [K in LocalTableName]: LocalTable<Extract<LocalTables[K], LocalRow>>;
+  readonly [K in LocalTableName]: LocalTable<Extract<LocalTables[K], object>>;
 } & {
   /** Escape hatch for generated code that only knows the table name as a string. */
-  table<TRow extends LocalRow>(name: string): LocalTable<TRow>;
+  table<TRow extends object = Row>(name: string): LocalTable<TRow>;
 };
 
-export interface CustomConflict<TOutput> {
-  readonly strategy: 'custom';
-  merge(local: TOutput, server: TOutput): TOutput;
-}
-
-export type Conflict<TOutput> = 'server-wins' | 'last-write-wins' | CustomConflict<TOutput>;
-
-export function custom<TOutput>(
-  merge: (local: TOutput, server: TOutput) => TOutput,
-): CustomConflict<TOutput> {
-  return { strategy: 'custom', merge };
+/**
+ * `conflict: custom(merge)` — core's row-shaped `ConflictPolicy`, built. `merge` receives the local
+ * ROW and the server ROW, because the client store is row-shaped: the output-shaped variant this
+ * replaced was dropped silently by realtime's rebase, which only ever had rows to hand it.
+ *
+ * `TRow` is the app's declared row shape, a caller-side annotation only — at rebase the resolver
+ * hands over whatever the store holds for that record, which is the entity's row.
+ */
+export function custom<TRow extends object = Row>(
+  merge: (local: TRow, server: TRow) => TRow,
+): ConflictPolicy {
+  // The one widening in the vocabulary: core's policy is over `Row`, the app's merge over its row.
+  return { kind: 'custom', merge: merge as unknown as (local: Row, server: Row) => Row };
 }
 
 export interface MutatorDef<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1> {
@@ -84,7 +92,7 @@ export interface MutatorDef<TInput extends StandardSchemaV1, TOutput extends Sta
     ctx: Ctx,
     input: InferOutput<TInput>,
   ): Promise<InferOutput<TOutput>> | InferOutput<TOutput>;
-  readonly conflict: Conflict<InferOutput<TOutput>>;
+  readonly conflict: ConflictPolicy;
 }
 
 export type MutatorDescriptor = Omit<ActionDescriptor, 'kind'> & {
@@ -102,7 +110,7 @@ export interface Mutator<
    * Renaming it here would silently turn every mutator back into a plain action downstream.
    */
   readonly isMutator: true;
-  readonly conflict: Conflict<InferOutput<TOutput>>;
+  readonly conflict: ConflictPolicy;
   /**
    * Applied on the client before the server round trip, and replayed on every
    * rebase — so it must stay a pure function of `(tx, input)`: no I/O, no clock,
@@ -133,6 +141,8 @@ export function mutator<TInput extends StandardSchemaV1, TOutput extends Standar
     ...(def.audit === undefined ? {} : { audit: def.audit }),
     handle: ({ input, ctx }) => def.server(ctx, input),
   };
+  // Before the action is built: a policy that cannot do what it says is refused at declaration.
+  if (def.conflict === 'last-write-wins') assertConflictClock(def.output);
   return wrap(def, action(actionDef));
 }
 
@@ -174,28 +184,7 @@ function wrap<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>
   return self;
 }
 
-export function strategyOf<TOutput>(
-  conflict: Conflict<TOutput>,
-): 'server-wins' | 'last-write-wins' | 'custom' {
-  return typeof conflict === 'string' ? conflict : conflict.strategy;
-}
-
-/**
- * Rebase decision for @ultimat3/realtime: which value survives when the local
- * twin and the server disagree.
- */
-export function resolveConflict<TOutput>(
-  conflict: Conflict<TOutput>,
-  local: TOutput,
-  server: TOutput,
-): TOutput {
-  if (typeof conflict !== 'string') return conflict.merge(local, server);
-  switch (conflict) {
-    case 'server-wins':
-      return server;
-    case 'last-write-wins':
-      return local;
-    default:
-      return assertNever(conflict);
-  }
+/** The descriptor's name for a policy — the manifest and `x actions describe` print this. */
+function strategyOf(conflict: ConflictPolicy): MutatorDescriptor['conflict'] {
+  return typeof conflict === 'string' ? conflict : conflict.kind;
 }

package/src/naming.ts

@@ -5,70 +5,25 @@
  * derived by nothing — it is the export name verbatim.
  */
 
-/** Irregular plurals we actually hit in domain models. Extend deliberately, not eagerly. */
-const IRREGULAR: Readonly<Record<string, string>> = {
-  person: 'people',
-  child: 'children',
-  man: 'men',
-  woman: 'women',
-  datum: 'data',
-  index: 'indexes',
-  entry: 'entries',
-};
-
-export interface ActionPath {
-  /** First camelCase word, kebab-cased. `publishPost` -> `publish`. */
-  readonly verb: string;
-  /** Remaining words, last one pluralized, kebab-cased. `publishPost` -> `posts`. */
-  readonly resource: string;
-  /** `POST /api/<resource>/<verb>`. */
-  readonly path: string;
-}
-
-/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
-export function splitWords(name: string): string[] {
-  return name
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-    .split(/[\s_-]+/)
-    .filter((word) => word.length > 0)
-    .map((word) => word.toLowerCase());
-}
+import type { ActionRoute } from '@ultimat3/core';
+import { actionRoute, splitWords } from '@ultimat3/core';
 
 /**
- * Naive-on-purpose English pluralizer. A word that already ends in `s` is left
- * alone, so `publishPosts` and `publishPost` agree on the `posts` resource.
+ * The path rule is `@ultimat3/core`'s `client-paths.ts` — the typed client, the route and the
+ * spec derive one URL from one function. Re-exported by name so `@ultimat3/action`'s public
+ * `derivePath` / `pluralize` / `splitWords` / `ActionPath` keep resolving; never re-declared here.
  */
-export function pluralize(word: string): string {
-  // `Object.hasOwn`, never a truthiness check on the read: `IRREGULAR['constructor']` is the
-  // `Object` FUNCTION off the prototype chain, not `undefined`, and `splitWords` lowercases —
-  // which keeps `toString` out of reach and lets `constructor` straight through. `pluralize` is
-  // public API returning `string`, and `derivePath` publishes what it answers as the action's
-  // HTTP path, its OpenAPI `paths` key and its `tags` entry.
-  if (Object.hasOwn(IRREGULAR, word)) return IRREGULAR[word] ?? word;
-  if (word.endsWith('s')) return word;
-  if (/(x|z|ch|sh)$/.test(word)) return `${word}es`;
-  if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
-  return `${word}s`;
-}
+export { pluralize, splitWords } from '@ultimat3/core';
+
+export type ActionPath = ActionRoute;
 
 /**
  * `publishPost`        -> POST /api/posts/publish
  * `updateUserProfile`  -> POST /api/user-profiles/update
- * `likePost`           -> POST /api/posts/like
  * `checkout`           -> POST /api/checkouts/invoke   (single-word fallback)
  */
 export function derivePath(name: string): ActionPath {
-  const words = splitWords(name);
-  const head = words[0] ?? 'invoke';
-  if (words.length < 2) {
-    const resource = pluralize(head);
-    return { verb: 'invoke', resource, path: `/api/${resource}/invoke` };
-  }
-  const nouns = words.slice(1);
-  const last = nouns[nouns.length - 1] ?? head;
-  const resource = [...nouns.slice(0, -1), pluralize(last)].join('-');
-  return { verb: head, resource, path: `/api/${resource}/${head}` };
+  return actionRoute(name);
 }
 
 // There is deliberately no `toToolName`. An MCP tool name is the export name verbatim — the one

package/src/record-wire.ts

@@ -0,0 +1,32 @@
+/**
+ * The record envelope, on the action's HTTP projection only. Derived from the output schema — an
+ * action whose output references an entity row answers `{ data, records }` under
+ * `x-ultimate-records: 1`; every other action's body is byte-identical to what it always was.
+ */
+
+import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
+import { hasEntityRows, rowsOf } from '@ultimat3/entity';
+import { json } from '@ultimat3/http';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+
+/** The header value that says "this body is an envelope". Presence alone is not enough. */
+const ENVELOPED = '1';
+
+// The OpenAPI half — the 200 body and its header — is core's `recordEnvelopeSchema` and
+// `RECORDS_OPENAPI_HEADER`, shared with `@ultimat3/query` so both projections describe one shape.
+
+/**
+ * Decided ONCE per action, at projection, from the schema — never per response from the data.
+ * A body whose shape depended on whether this call happened to return rows would need two
+ * OpenAPI shapes for one operation; a schema-derived answer needs exactly one.
+ */
+export function carriesRecords(output: StandardSchemaV1): boolean {
+  return hasEntityRows(output);
+}
+
+/** The 200 for an action that carries records: the envelope, and the header that names it. */
+export function recordResponse(output: StandardSchemaV1, result: unknown): Response {
+  const response = json(encodeRecordEnvelope(result, rowsOf(output, result)));
+  response.headers.set(RECORDS_HEADER, ENVELOPED);
+  return response;
+}

package/src/transition.ts

@@ -18,7 +18,7 @@ import type {
   StringSchema,
 } from '@ultimat3/schema';
 import { t } from '@ultimat3/schema';
-import { type LocalRow, type Mutator, mutator } from './mutator';
+import { type Mutator, mutator } from './mutator';
 import type { ActionPolicy } from './policy-gate';
 
 /**
@@ -126,9 +126,9 @@ export function transition<
       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, {
+      tx.table<Row>(def.localTable).update(input.id, {
         [def.column]: input.to,
-      } as Partial<Row & LocalRow>);
+      } as Partial<Row>);
     },
     // 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

package/src/type-pins.ts

@@ -3,10 +3,12 @@
 // type-level claim written in one can never fail. This module emits nothing and exports nothing
 // anybody imports — a regression here is a build error, the only enforcement that counts.
 
+import type { Row } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Action, AnyAction } from './action';
 import type { ClientMethod } from './client';
 import type { ActionJobHandle } from './job-handle';
+import type { LocalTable } from './mutator';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -43,3 +45,17 @@ export type _ErasedClientIsNotASupertype = Assert<
     ? false
     : true
 >;
+
+/**
+ * A mutator's `tx` table is `@ultimat3/realtime`'s store tx, member for member — the store is what
+ * a twin runs against, so a member here it lacks is a twin that typechecks and throws. Pinned by
+ * the member set because realtime (tier 3, sideways) cannot be imported to compare the types.
+ */
+export type _LocalTableIsTheStoreTxShape = Assert<
+  Equals<keyof LocalTable, 'get' | 'all' | 'insert' | 'upsert' | 'update' | 'delete'>
+>;
+
+/** Addressed by KEY: an insert names the key its server twin answers under, never a column. */
+export type _LocalInsertTakesTheKey = Assert<
+  Equals<Parameters<LocalTable['insert']>, [key: string, row: Row]>
+>;

package/src/wire-headers.ts

@@ -13,5 +13,8 @@
  */
 export const BUILD_ID_HEADER = 'x-ultimate-build';
 
-/** RFC 9110's spelling, lower-cased, as `Headers` normalises it. */
-export const IDEMPOTENCY_HEADER = 'idempotency-key';
+/**
+ * RFC 9110's spelling, lower-cased. Core's, re-exported by name: `clientTransport` sets it and
+ * this package's route reads it, so a second declaration here would be two answers to one header.
+ */
+export { IDEMPOTENCY_HEADER } from '@ultimat3/core';