@ultimat3/action 20.2.1 → 22.0.0

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
 
@@ -601,8 +623,8 @@ never a pass — the assertion says which code got in the way and names `input:`
 | `X_IDEMPOTENCY_NOT_SHARED` | `configureIdempotency({ scope: 'shared' })` over a per-process (or scope-less) store | install `postgresIdempotencyStore({ executor })` at boot |
 | `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_CONTRACT_DRIFT` | client/server build skew, missing spec entry | reload / `x verify --only contract` |
+| `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 |
@@ -623,7 +645,34 @@ cannot read is dropped whole rather than half-kept, leaving `cause` (which still
 rejection) as the answer. It is exported for the island that posts with a plain `fetch` and holds
 the body itself.
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `ActionDeniedError` | the policy denial's own code (`X_FORBIDDEN`, `X_UNAUTHENTICATED`, …), kept on `.denial` | `src/errors.ts` |
+| `ActionDeprecationInvalidError` | `X_ACTION_DEPRECATION_INVALID` | `src/errors.ts` |
+| `ActionDuplicateError` | `X_ACTION_DUPLICATE` | `src/errors.ts` |
+| `ActionForeignError` | `X_ACTION_FOREIGN` | `src/errors.ts` |
+| `ActionPathDuplicateError` | `X_ACTION_PATH_DUPLICATE` | `src/errors.ts` |
+| `ActionPolicyMissingError` | `X_ACTION_POLICY_MISSING` | `src/errors.ts` |
+| `ActionUnregisteredError` | `X_ACTION_UNREGISTERED` | `src/errors.ts` |
+| `AuditSinkFailedError` | `X_AUDIT_SINK_FAILED` | `src/errors.ts` |
+| `AuditSinkMissingError` | `X_AUDIT_SINK_MISSING` | `src/errors.ts` |
+| `ContractDriftError` | `X_CONTRACT_DRIFT` | `src/errors.ts` |
+| `IdempotencyConflictError` | `X_IDEMPOTENCY_CONFLICT` | `src/errors-idempotency.ts` |
+| `IdempotencyKeyInvalidError` | `X_IDEMPOTENCY_KEY_INVALID` | `src/errors-idempotency.ts` |
+| `IdempotencyNotSharedError` | `X_IDEMPOTENCY_NOT_SHARED` | `src/errors-idempotency.ts` |
+| `IdempotencyReplayedFailureError` | `X_IDEMPOTENCY_REPLAYED_FAILURE` | `src/errors-idempotency.ts` |
+| `IdempotencyStatusUnknownError` | `X_IDEMPOTENCY_STATUS_UNKNOWN` | `src/errors-idempotency.ts` |
+| `InputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |
+| `OutputInvalidError` | `X_OUTPUT_INVALID` | `src/errors.ts` |
+| `RemoteActionError` | the code the server sent, verbatim — `meta.origin: 'remote'` | `src/errors.ts` |
+| `RpcFailedError` | `X_RPC_FAILED` | `src/errors.ts` |
+
 ## 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.1",
+  "version": "22.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.1",
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/http": "20.2.1",
-    "@ultimat3/policy": "20.2.1",
-    "@ultimat3/schema": "20.2.1"
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/http": "22.0.0",
+    "@ultimat3/policy": "22.0.0",
+    "@ultimat3/schema": "22.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/deprecation.ts

@@ -75,8 +75,3 @@ export function renderDeprecation(
   };
   return { ok: true, headers, meta };
 }
-
-/** Set on a response that already exists, so a redirect and a problem document carry them too. */
-export function applyHeaders(response: Response, headers: Readonly<Record<string, string>>): void {
-  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
-}

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,15 +6,21 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import { isMcpExposed, isUltimateError } from '@ultimat3/core';
+import {
+  isMcpExposed,
+  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
 // a copy here would be a second answer to "what does this limit mean" for the read half.
-import { json, problem, redirect, takeRedirect, toBucket } from '@ultimat3/http';
+import { json, redirect, takeRedirect, toBucket } from '@ultimat3/http';
 import type { ActionRateLimit, AnyAction } from './action';
 import type { Deprecation } from './deprecation';
-import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
+import { recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { ActionDeprecationInvalidError } from './errors';
 import { actionName, defOf, invoke } from './invoke';
 import {
@@ -26,6 +32,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 +44,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,43 +62,53 @@ 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);
-    try {
-      // The pipeline already parsed and size-capped the body; parsing it again here
-      // would be a second, differently-behaved parser for the same bytes.
-      const raw = await req.bodyRaw();
-      const key = def.idempotent === true ? req.header(IDEMPOTENCY_HEADER) : null;
-      let replayed = false;
-      const result = await invoke(target, raw, {
+    if (sunsetting !== undefined) {
+      recordDeprecatedCall('action', name);
+      // On the CONTEXT, before anything can fail: the pipeline's `response` stage merges
+      // `ctx.headers` into whatever answers — this handler's 200 and the `error-map` stage's
+      // problem or error page alike. A client polling a deprecated endpoint that is currently
+      // 403ing still has to learn the endpoint is going away.
+      for (const [header, value] of Object.entries(sunsetting)) req.ctx.headers.set(header, value);
+    }
+    // No `catch`: an error — framework or not — takes the path every route's error takes. This
+    // used to answer `problem(error)` itself, so the `error-map` stage never saw it: no
+    // `onError`/`reportError` on a 5xx, no HTML error page or sign-in redirect for a browser, no
+    // `requestId`, no `Retry-After`.
+    //
+    // The pipeline already parsed and size-capped the body; parsing it again here
+    // would be a second, differently-behaved parser for the same bytes.
+    const raw = await req.bodyRaw();
+    const key = def.idempotent === true ? req.header(IDEMPOTENCY_HEADER) : null;
+    let replayed = false;
+    // 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);
-      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
-      // sunset from exactly the callers most likely to be stale.
-      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
-      return response;
-    } catch (error) {
-      // Framework errors carry their own code, status and fix line; anything else is
-      // a bug and belongs to the server's error boundary, not to this route.
-      if (!isUltimateError(error)) throw error;
-      const response = problem(error);
-      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
-      return response;
-    }
+      }),
+    );
+    // 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
+        ? redirect(to.location, to.status)
+        : enveloped
+          ? recordResponse(target.output, result)
+          : json(result);
+    if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0');
+    return response;
   };
 
   const meta: RouteMeta = {
@@ -148,6 +171,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 +184,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/invoke.ts

@@ -253,7 +253,10 @@ async function perform(
     if (outcome.replayed) options.onReplay?.();
     trace.replayed = outcome.replayed;
     wrote = !outcome.replayed;
-    value = outcome.value;
+    // A replay is parsed like a first call. The memory store hands back the live value and the
+    // postgres store `JSON.parse(JSON.stringify(v))` — a `Date` on the first call and a `string`
+    // on every retry served from Postgres — so the output schema is the one answer to its shape.
+    value = outcome.replayed ? validateOutput(def.output, outcome.value, name) : outcome.value;
   }
   // Only for a run that actually happened, and only through the gate. A replay ran no handler
   // and changed nothing the first call had not already busted — re-busting per retry re-purges

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);
+  }
+}