@ultimat3/realtime 23.0.0 → 25.0.0

package/src/sync-protocol.ts

@@ -2,7 +2,12 @@
 // patches, presence and refusals come down. A client write is HTTP (`useMutation`), never a frame —
 // so there is one write path, with the action's authz, idempotency store and contract behind it.
 
-import { renderThrowable, stringField } from '@ultimat3/core/page';
+import {
+  isWriteDigest,
+  renderThrowable,
+  stringField,
+  WRITE_DIGEST_LENGTH,
+} from '@ultimat3/core/page';
 import type {
   ChannelEventsFrame,
   ChannelRecordsFrame,
@@ -11,7 +16,7 @@ import type {
 } from './channel-wire';
 import type { LiveCursor } from './cursor';
 import {
-  isJsonObject,
+  isParsedJsonObject,
   isRow,
   type JsonObject,
   type JsonValue,
@@ -37,6 +42,8 @@ export interface WireError {
   readonly cause: string;
   readonly fix: string;
   readonly docs?: string;
+  /** When a retry can succeed — a rate-limited subscribe's refill. Whole seconds, positive. */
+  readonly retryAfterSeconds?: number;
 }
 
 export interface PresenceMember {
@@ -80,6 +87,12 @@ export interface HelloFrame {
   /** Server-assigned on the reply, `null` on the client's opening frame. */
   readonly sessionId: string | null;
   readonly actorId: string | null;
+  /**
+   * On the NODE's reply only: how often this client must beat, in ms — a third of the node's real
+   * presence ttl, and never slower than the node's idle budget allows. Additive and optional, so
+   * no version bump: a node that says nothing leaves the client on its own default.
+   */
+  readonly heartbeatMs?: number;
 }
 
 export interface SubscribeFrame {
@@ -110,6 +123,12 @@ export interface SnapshotFrame {
    * derives a key.
    */
   readonly keys?: readonly string[];
+  /**
+   * The writes this server truth already holds, named as `PatchFrame.writes` names them — only
+   * writes behind a row in `rows`, so never one this subscriber may not see. Optional and additive:
+   * no `PROTOCOL_VERSION` bump, for the reason `entity` needs none.
+   */
+  readonly writes?: readonly string[];
 }
 
 export interface PatchFrame {
@@ -118,6 +137,15 @@ export interface PatchFrame {
   readonly sid: string;
   readonly patches: readonly RowPatch[];
   readonly lsn: string;
+  /**
+   * The writes that made these patches: `writeDigest` of each keyed request's idempotency key
+   * (`@ultimat3/core`), never the key, as `ChannelRecordsFrame.write` names one. A live patch names
+   * at most one; a delta resume names every write behind a patch it replays. Absent when no keyed
+   * request made any of them. The page that holds one pending settles it in the frame's own batch.
+   * Additive and optional: a decoder one deploy behind drops it, and a frame without it is read as
+   * it always was — so no `PROTOCOL_VERSION` bump.
+   */
+  readonly writes?: readonly string[];
 }
 
 export interface AckFrame {
@@ -186,21 +214,25 @@ export function decode(raw: string | Uint8Array): Frame {
   } catch {
     throw fail('frame is not JSON');
   }
-  if (!isJsonObject(parsed)) throw fail('frame is not an object');
+  if (!isParsedJsonObject(parsed)) throw fail('frame is not an object');
   const version = parsed['v'];
   if (version !== PROTOCOL_VERSION) {
     throw new ProtocolVersionError({ got: version, expected: PROTOCOL_VERSION });
   }
   const kind = parsed['type'];
   switch (kind) {
-    case 'hello':
-      return {
+    case 'hello': {
+      const hello = {
         type: 'hello',
         v: PROTOCOL_VERSION,
         buildId: str(parsed, 'buildId'),
         sessionId: nullableStr(parsed, 'sessionId'),
         actorId: nullableStr(parsed, 'actorId'),
-      };
+      } as const;
+      return parsed['heartbeatMs'] === undefined
+        ? hello
+        : { ...hello, heartbeatMs: num(parsed, 'heartbeatMs') };
+    }
     case 'subscribe':
       return {
         type: 'subscribe',
@@ -218,7 +250,9 @@ export function decode(raw: string | Uint8Array): Frame {
         cursor: cursor(parsed['cursor']),
       } as const;
       const entity = nullableStr(parsed, 'entity');
-      const scoped = entity === null ? base : { ...base, entity };
+      const writes = writesOf(parsed, 'snapshot.writes');
+      const named = writes.length === 0 ? base : { ...base, writes };
+      const scoped = entity === null ? named : { ...named, entity };
       if (parsed['keys'] === undefined) return scoped;
       const keys = list(parsed, 'keys', FRAME_LIMITS.rows).map((key) => {
         if (typeof key !== 'string') throw fail('snapshot.keys must hold strings');
@@ -227,14 +261,17 @@ export function decode(raw: string | Uint8Array): Frame {
       if (keys.length !== base.rows.length) throw fail('snapshot.keys must pair with rows');
       return { ...scoped, keys };
     }
-    case 'patch':
-      return {
+    case 'patch': {
+      const base = {
         type: 'patch',
         v: PROTOCOL_VERSION,
         sid: str(parsed, 'sid'),
         patches: list(parsed, 'patches', FRAME_LIMITS.patches).map(patch),
         lsn: str(parsed, 'lsn'),
-      };
+      } as const;
+      const writes = writesOf(parsed, 'patch.writes');
+      return writes.length === 0 ? base : { ...base, writes };
+    }
     case 'ack':
       return {
         type: 'ack',
@@ -275,7 +312,37 @@ export function toWireError(error: unknown): WireError {
   const cause = stringField(error, 'cause') ?? renderThrowable(error);
   const fix = stringField(error, 'fix') ?? 'x doctor realtime';
   const docs = stringField(error, 'docs');
-  return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
+  const base = docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
+  const retryAfterSeconds = retryHintOf(error);
+  return retryAfterSeconds === undefined ? base : { ...base, retryAfterSeconds };
+}
+
+/**
+ * `meta.retryAfterSeconds`, the field `@ultimat3/http`'s `X_RATE_LIMITED` carries — read as totally
+ * as `stringField` reads the rest, because the throwable is app code's and its getters may throw.
+ */
+function retryHintOf(error: unknown): number | undefined {
+  try {
+    const meta: unknown = (error as { readonly meta?: unknown } | null)?.meta;
+    const held: unknown = isParsedJsonObject(meta) ? meta['retryAfterSeconds'] : undefined;
+    return typeof held === 'number' && Number.isFinite(held) && held > 0 ? held : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `writes` on a `patch` or `snapshot`: digests only, capped at the patch ceiling (one write per
+ * patch at most; `snapshotFrame` caps what it sends to the same number). Absent, `null` and `[]`
+ * all name nothing, and read as the frame an older node sends.
+ */
+function writesOf(parsed: JsonObject, label: string): readonly string[] {
+  return list(parsed, 'writes', FRAME_LIMITS.patches, label).map((write) => {
+    if (!isWriteDigest(write)) {
+      throw fail(`${label} must hold ${WRITE_DIGEST_LENGTH}-character lowercase hex digests`);
+    }
+    return write;
+  });
 }
 
 function row(value: unknown): Row {
@@ -284,7 +351,7 @@ function row(value: unknown): Row {
 }
 
 function cursor(value: unknown): LiveCursor {
-  if (!isJsonObject(value)) throw fail('cursor must be an object');
+  if (!isParsedJsonObject(value)) throw fail('cursor must be an object');
   return {
     qid: str(value, 'qid'),
     lsn: str(value, 'lsn'),
@@ -297,7 +364,7 @@ function cursor(value: unknown): LiveCursor {
 }
 
 function patch(value: unknown): RowPatch {
-  if (!isJsonObject(value)) throw fail('patch must be an object');
+  if (!isParsedJsonObject(value)) throw fail('patch must be an object');
   const base = {
     op: pick(value, 'op', ['insert', 'update', 'delete'] as const),
     id: str(value, 'id'),
@@ -310,7 +377,7 @@ function patch(value: unknown): RowPatch {
 }
 
 function target(value: unknown): SubscribeTarget {
-  if (!isJsonObject(value)) throw fail('subscribe.target must be an object');
+  if (!isParsedJsonObject(value)) throw fail('subscribe.target must be an object');
   const kind = pick(value, 'kind', ['query', 'channel'] as const);
   if (kind === 'channel') return channelTarget(value);
   return {
@@ -324,7 +391,10 @@ function target(value: unknown): SubscribeTarget {
 
 function wireError(value: unknown): WireError | null {
   if (value === null || value === undefined) return null;
-  if (!isJsonObject(value)) throw fail('ack.error must be an object or null');
+  if (!isParsedJsonObject(value)) throw fail('ack.error must be an object or null');
   const base = { code: str(value, 'code'), cause: str(value, 'cause'), fix: str(value, 'fix') };
-  return value['docs'] === undefined ? base : { ...base, docs: str(value, 'docs') };
+  const documented = value['docs'] === undefined ? base : { ...base, docs: str(value, 'docs') };
+  return value['retryAfterSeconds'] === undefined
+    ? documented
+    : { ...documented, retryAfterSeconds: num(value, 'retryAfterSeconds') };
 }

package/src/sync-upgrade.ts

@@ -2,12 +2,22 @@
 // from `sync-node.ts` because deciding whether a request becomes a websocket is a different job
 // from what the socket then does — the same line `sync-frames.ts` and `sync-listen.ts` already draw.
 
-import { healthzPayload, readyzPayload, reportError } from '@ultimat3/core';
+import {
+  type HealthPayload,
+  healthBody,
+  healthPeerListed,
+  healthzPayload,
+  readyzPayload,
+  reportError,
+} from '@ultimat3/core';
 import {
   SocketAuthUnavailableError,
+  SocketLimitError,
   SocketOriginRefusedError,
   SocketUnauthenticatedError,
 } from './errors';
+import type { PrincipalSockets } from './principal-sockets';
+import { principalFor } from './subscription-book';
 import type { SyncAuthenticator, SyncGrant } from './sync-auth';
 import { upgradeOrigin } from './sync-origin';
 import { toWireError } from './sync-protocol';
@@ -26,11 +36,21 @@ export interface WsData {
    * forever for having sent no query.
    */
   readonly clientBuildId: string;
+  /**
+   * The caller's address, resolved here once (`clientAddressOf`); `null` when nothing can say.
+   * Optional only for a socket a host builds without this upgrade (a test harness).
+   */
+  readonly clientAddress?: string | null;
 }
 
 /** Structural view of `Bun.serve`'s server object; keeps this module free of a Bun import. */
 export interface UpgradeTarget {
   upgrade(request: Request, options: { data: WsData }): boolean;
+  /**
+   * The peer's SOCKET address, as `Bun.serve`'s server answers it — what decides who is told the
+   * health detail. `null` when the host cannot say, which is told the verdict only.
+   */
+  requestIP(request: Request): { readonly address: string } | null;
 }
 
 /**
@@ -49,10 +69,26 @@ export interface UpgradeDeps {
   newSocketId(): string;
   readonly authenticate?: SyncAuthenticator | undefined;
   /**
-   * Exact origins a page may dial from besides the node's own host name — `APP_URL`'s, when the
-   * page is served on another host than the node (`sync-origin.ts`).
+   * Exact origins a page may dial from — `APP_URL`'s. Declared, they are the WHOLE list: the
+   * origin the node sees is `Host`-derived and is admitted only when nothing is declared
+   * (`sync-origin.ts`).
    */
   readonly allowedOrigins?: readonly string[] | undefined;
+  /**
+   * Who the caller is, for keying an anonymous reader's rate limit: the deployment's own rule —
+   * `@ultimat3/http`'s `clientAddress()` under its `TRUSTED_PROXY_HOPS`, injected by the boot so
+   * this package reads no proxy header itself. Absent, the socket's address is the caller.
+   */
+  readonly clientAddressOf?:
+    | ((request: Request, socketAddress: string | null) => string | null)
+    | undefined;
+  /** The `Host`-derived origin admitted beside a declared list too — `x dev` only. */
+  readonly admitReachedOrigin?: boolean | undefined;
+  /**
+   * Peers told the whole health report — address classes or exact IP literals, the app's
+   * `http.healthDetailPeers`. Everyone else gets `{ state, ready, role }`.
+   */
+  readonly healthDetailPeers: readonly string[];
   /**
    * Recorded BEFORE `server.upgrade`, because Bun runs `websocket.open` synchronously inside it
    * (measured on bun 1.4.0) and `open` is where the node reads this grant to build the socket's
@@ -69,6 +105,11 @@ export interface UpgradeDeps {
    * same "reserve, then release" shape `channel.ts` uses for a topic slot.
    */
   onUngranted(socketId: string): void;
+  /**
+   * One principal's sockets on this node, keyed as the live-query principal is. Admitted right
+   * before `server.upgrade`; `onUngranted` and the socket's close give the slot back.
+   */
+  readonly principals?: PrincipalSockets | undefined;
 }
 
 /**
@@ -83,16 +124,21 @@ export async function handleUpgrade(
   const url = new URL(request.url);
   // Health is the process's, readiness is this node's: a draining node stays healthy while it hands
   // its sockets to the rest of the fleet.
-  if (url.pathname === '/healthz') return json(healthzPayload());
+  if (url.pathname === '/healthz') return health(deps, request, server, healthzPayload());
   if (url.pathname === '/readyz') {
     const payload = readyzPayload({ deep: url.searchParams.get('deep') === '1' });
-    return deps.ready() ? json(payload) : json({ status: 503, body: payload.body });
+    return health(deps, request, server, deps.ready() ? payload : { ...payload, status: 503 });
   }
   if (url.pathname !== deps.path) return new Response('not found', { status: 404 });
   // First, and before anything is spent: a foreign page is refused whatever the node's load.
-  const origin = upgradeOrigin(request, url, deps.allowedOrigins ?? []);
-  if (!origin.ok)
-    return wireErrorResponse(403, new SocketOriginRefusedError({ reason: origin.reason }));
+  const origin = upgradeOrigin(request, url, deps.allowedOrigins ?? [], deps.admitReachedOrigin);
+  if (!origin.ok) {
+    const asked = { asked: request.headers.get('origin'), admitted: admittedList(deps) };
+    return wireErrorResponse(
+      403,
+      new SocketOriginRefusedError({ reason: origin.reason, ...asked }),
+    );
+  }
   // The count and readiness. Decided before `authenticate` so a full node costs no token service
   // call.
   if (deps.socketCount() >= deps.maxConnections || !deps.ready()) return shed(deps);
@@ -148,7 +194,18 @@ export async function handleUpgrade(
     socketId: deps.newSocketId(),
     // The node's own id is "not skewed until the hello says so", never "current forever".
     clientBuildId: url.searchParams.get('build') ?? deps.buildId,
+    clientAddress: callerAddress(deps, request, server),
   };
+  // Beside the count recheck and for its reason: no await between this and `server.upgrade`, so a
+  // herd of one principal parked in `authenticate` cannot all pass one count.
+  const principal = principalFor(grant?.actor ?? null, data.clientAddress ?? null);
+  if (deps.principals !== undefined && !deps.principals.admit(data.socketId, principal)) {
+    refund();
+    return wireErrorResponse(
+      429,
+      new SocketLimitError({ principal, limit: deps.principals.limitFor(principal) }),
+    );
+  }
   // Before the upgrade, never after: `server.upgrade` runs `websocket.open` synchronously and does
   // not return until it has, so a grant recorded on the next line is one the socket was already
   // built without.
@@ -177,6 +234,49 @@ export async function handleUpgrade(
   return undefined;
 }
 
+/**
+ * What a proxy writes. Any one of them means the socket's address is the proxy's, not the
+ * caller's — and a proxy that writes none of them is indistinguishable from a direct peer, so a
+ * header-less proxy must not route the health paths at all.
+ */
+const FORWARDED_HEADERS = [
+  'forwarded',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-proto',
+  'x-real-ip',
+  'via',
+] as const;
+
+/**
+ * The STATUS is everyone's, which is all a probe reads. The body beyond the verdict is for a peer
+ * the app listed, on a DIRECT socket: these paths answer before the origin check, the accept
+ * budget and `authenticate`. This node declares no trusted proxy, so a request that says it was
+ * forwarded is never told the detail — a proxy on this box makes every caller's socket loopback.
+ */
+function health(
+  deps: UpgradeDeps,
+  request: Request,
+  server: UpgradeTarget,
+  payload: HealthPayload,
+): Response {
+  const forwarded = FORWARDED_HEADERS.some((header) => request.headers.has(header));
+  const detailed =
+    !forwarded &&
+    healthPeerListed(deps.healthDetailPeers, server.requestIP(request)?.address ?? null);
+  return new Response(JSON.stringify(healthBody(payload.body, 'sync', detailed)), {
+    status: payload.status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+  });
+}
+
+function callerAddress(deps: UpgradeDeps, request: Request, server: UpgradeTarget): string | null {
+  const socketAddress = server.requestIP(request)?.address ?? null;
+  return deps.clientAddressOf === undefined
+    ? socketAddress
+    : deps.clientAddressOf(request, socketAddress);
+}
+
 /** Load shedding with a delay attached: refusing without one just moves the herd next door. */
 function shed(deps: UpgradeDeps): Response {
   return new Response('retry', {
@@ -185,6 +285,13 @@ function shed(deps: UpgradeDeps): Response {
   });
 }
 
+/** What the refusal says this node admits: the declared list, and under `x dev` the reached-on origin. */
+function admittedList(deps: UpgradeDeps): readonly string[] {
+  const declared = deps.allowedOrigins ?? [];
+  if (declared.length === 0 || deps.admitReachedOrigin !== true) return declared;
+  return [...declared, 'the origin it was reached on'];
+}
+
 function wireErrorResponse(status: number, error: unknown): Response {
   return json({ status, body: { error: toWireError(error) } });
 }

package/src/type-pins.ts

@@ -6,7 +6,7 @@
 import type { AsyncState, Row } from '@ultimat3/core';
 import type { LiveHandle, Unsubscribe } from './client-contract';
 import type { QueryAccessor, QueryRef } from './use-query';
-import type { RecordAccessor } from './use-record';
+import type { RecordAccessor, useRecords } from './use-record';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -31,6 +31,14 @@ export type _RecordAnswersAsyncState = Assert<
   Equals<ReturnType<RecordAccessor<FeedRow>>, AsyncState<FeedRow | undefined>>
 >;
 
+/**
+ * `useRecords` takes its selection EXPLICITLY — a key list, or `{}` / `{ where, order }` for the
+ * whole type. A default turned a call that forgot its keys into "every record of the type".
+ */
+export type _UseRecordsSelectionRequired = Assert<
+  Equals<Parameters<typeof useRecords>['length'], 2>
+>;
+
 /**
  * A query ref carries no server field: a `Query` VALUE in an island drags its whole read path into
  * the bundle, so the ref is a name and two declared facts. A `sql` key is refused.

package/src/use-channel.ts

@@ -1,9 +1,10 @@
 // A declared channel, held by a component. Every holder of one topic on the page shares ONE
-// membership on the page socket; its `records` land in the store (read them with `useRecord` /
-// `useQuery`), and only `events` and presence reach the handlers given here.
+// membership on the page socket — the page runtime's, reached off the page, never bundled here;
+// its `records` land in the store (read them with `useRecord` / `useQuery`), and only `events`
+// and presence reach the handlers given here.
 
 import type { ChannelHandlers, ChannelRef, ChannelState } from './client-channels';
-import { pageSocket } from './page-socket';
+import { installedPage } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import type { PresenceMember } from './sync-protocol';
 
@@ -32,7 +33,9 @@ export function useChannel<K extends string>(
       [Symbol.dispose]: nothing,
     });
   }
-  const membership = pageSocket('useChannel').holdChannel(declared, params, handlers);
+  const membership = installedPage('useChannel')
+    .services.socket('useChannel')
+    .holdChannel(declared, params, handlers);
   const [version, setVersion] = signal(0);
   const off = membership.onChange(() => setVersion(version() + 1));
   const read = (): ChannelState => {
@@ -70,16 +73,18 @@ export function usePresence<K extends string>(
   }
   const [version, setVersion] = signal(0);
   let members = new Map<string, PresenceMember>();
-  const membership = pageSocket('usePresence').holdChannel(declared, params, {
-    onPresence: (event) => {
-      if (event.presence === 'sync') members = new Map();
-      for (const member of event.members) {
-        if (event.presence === 'leave') members.delete(member.id);
-        else members.set(member.id, member);
-      }
-      setVersion(version() + 1);
-    },
-  });
+  const membership = installedPage('usePresence')
+    .services.socket('usePresence')
+    .holdChannel(declared, params, {
+      onPresence: (event) => {
+        if (event.presence === 'sync') members = new Map();
+        for (const member of event.members) {
+          if (event.presence === 'leave') members.delete(member.id);
+          else members.set(member.id, member);
+        }
+        setVersion(version() + 1);
+      },
+    });
   const read = (): readonly PresenceMember[] => {
     version();
     return [...members.values()];

package/src/use-connection.ts

@@ -1,8 +1,8 @@
 // The page socket, as four getters: whether it is up, when it redials, and whether a newer build
 // is live. Getters, never a snapshot, so a read inside a tracking scope stays live. Asking opens
-// the socket — this hook IS a question about it.
+// the socket — this hook IS a question about it — and the socket is the page runtime's.
 
-import { pageSocket } from './page-socket';
+import { installedPage } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 
 export interface Connection extends Disposable {
@@ -33,7 +33,7 @@ const SERVER_RENDER: Connection = Object.freeze({
 export function useConnection(): Connection {
   const signal = signalFor('useConnection');
   if (isServerRender()) return SERVER_RENDER;
-  const client = pageSocket('useConnection');
+  const client = installedPage('useConnection').services.socket('useConnection');
   const [version, setVersion] = signal(0);
   const release = client.onStatus(() => setVersion(version() + 1));
   return {

package/src/use-mutation.ts

@@ -1,20 +1,14 @@
 // A client write, the one way: the mutator's optimistic twin into the store's OVERLAY (visible to
-// every island before this returns), then its action over HTTP through core's one transport with
-// an idempotency key. The answer's records are adopted before the overlay goes — no flicker — and
-// a refusal takes the overlay back. The socket carries no writes.
+// every island before this returns), then its action over HTTP through core's one transport — the
+// page runtime's, called off the page — with an idempotency key. The answer's records are adopted
+// before the overlay goes — no flicker — and a refusal takes the overlay back. No socket writes.
 
 import type { ConflictPolicy } from '@ultimat3/core/page';
-import {
-  actionPath,
-  clientTransport,
-  isSuperseded,
-  isUltimateError,
-  uuid,
-} from '@ultimat3/core/page';
+import { actionPath, isSuperseded, isUltimateError, pageClient, uuidV7 } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
 import { type OutboxHandle, peekOutbox } from './outbox-slot';
-import { ServerRenderLiveError } from './page-errors';
-import { type PageWrites, pageRealtime } from './page-store';
+import { OfflineQueueAbandonedError, ServerRenderLiveError } from './page-errors';
+import { installedPage, type PageWrites, pageRealtime } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import { carriedBy } from './record-store';
 
@@ -92,7 +86,7 @@ function watch(hook: string, writes: PageWrites | undefined): [() => number, ()
 function restoreOverlays(mutator: MutatorLike): void {
   const local = mutator.local;
   if (local === undefined) return;
-  const page = pageRealtime();
+  const page = installedPage('useMutation');
   // The boot opens the outbox; after it, so a queue the previous load left is on disk to read.
   void page.booted.then(async () => {
     const outbox = peekOutbox();
@@ -126,8 +120,9 @@ export function useMutation(mutator: MutatorLike): Mutate {
   const [version, release] = watch('useMutation', writes);
   const call = async (input: JsonValue): Promise<unknown> => {
     if (writes === undefined) throw new ServerRenderLiveError({ operation: 'useMutation()' });
-    const page = pageRealtime();
-    const key = `${mutator.name}:${uuid()}`;
+    const page = installedPage('useMutation');
+    const issued = pageClient().scope.epoch;
+    const key = `${mutator.name}:${uuidV7()}`;
     const local = mutator.local;
     // Called back through the mutator: `local` may be a method, and an unbound one loses `this`.
     if (local !== undefined) {
@@ -138,9 +133,31 @@ export function useMutation(mutator: MutatorLike): Mutate {
     // them over HTTP — a like queued offline and the unlike made once the network was back could
     // otherwise land swapped. The replay sends the queue in order, this write last, under its key.
     const queued = peekOutbox();
+    // The outbox may REFUSE: its queue's principal left mid-write (`X_OFFLINE_QUEUE_ABANDONED`),
+    // or the disk would not take it. Nothing will ever send this write then, so its twin comes
+    // off the screen and the caller is told — a rejected `mutate`, by code.
+    //
+    // And the hook has an await of its own — the POST — so WHOSE write this is was decided at the
+    // call (`issued`): asked for after a principal change, the outbox is the next principal's, and
+    // a write handed to it then would be queued, and sent, as them.
+    const enqueue = async (outbox: OutboxHandle): Promise<void> => {
+      try {
+        if (pageClient().scope.epoch !== issued) {
+          throw new OfflineQueueAbandonedError({ name: mutator.name });
+        }
+        await outbox.enqueue({ key, name: mutator.name, input });
+      } catch (error) {
+        page.store.drop(key);
+        // A principal change is nobody's failure to report; a disk that refused the write is.
+        if (!isUltimateError(error) || error.code !== 'X_OFFLINE_QUEUE_ABANDONED') {
+          writes.failed += 1;
+        }
+        throw error;
+      }
+    };
     if (queued !== undefined && queued.pending().length > 0) {
       try {
-        await queued.enqueue({ key, name: mutator.name, input });
+        await enqueue(queued);
         void queued.replay().catch(() => undefined);
         return undefined;
       } finally {
@@ -151,7 +168,7 @@ export function useMutation(mutator: MutatorLike): Mutate {
     /** The records the answer carried, `type:key` — what the overlay may be settled against. */
     const carried = new Set<string>();
     try {
-      output = await clientTransport({
+      output = await page.services.send({
         method: 'POST',
         url: actionPath(mutator.name),
         body: input,
@@ -160,13 +177,17 @@ export function useMutation(mutator: MutatorLike): Mutate {
       });
     } catch (error) {
       const failure = transportFailure(error);
-      // No response at all: the write is the outbox's now, under the SAME idempotency key, and its
-      // overlay stays on screen until the replay settles or refuses it. Only a page the boot opened
+      // No response at all — which is NOT "the write did not land": the POST may have committed
+      // and lost its answer. The write is the outbox's now, under the SAME idempotency key, and
+      // that replay is safe only because `mutator()` refuses a declaration without
+      // `idempotent: true` (`X_MUTATOR_NOT_IDEMPOTENT`): the server reads the key and answers the
+      // replay from its idempotency store, so the handler never runs twice. The overlay stays on
+      // screen until the replay settles or refuses it. Only a page the boot opened
       // an outbox on can promise that; with none (no boot, so nothing on this page persists) the
       // write is refused like any other, never held in a memory queue a reload would silently lose.
       const outbox = failure === 'network' ? await bootedOutbox(page) : undefined;
       if (outbox !== undefined) {
-        await outbox.enqueue({ key, name: mutator.name, input });
+        await enqueue(outbox);
         return undefined;
       }
       if (failure === 'body') {