@ultimat3/realtime 23.0.0 → 25.0.0

package/src/error-titles.ts

@@ -0,0 +1,91 @@
+// @ultimat3/realtime's owned codes and their TITLES, registered at import — the one module
+// `sideEffects` names, so `errors.ts` (the sync node's refusal classes) is unlisted and no hook's
+// chunk carries it (`page-errors-bundle.test.ts`): measured on Bun 1.4.2, −1,081 B on `feed`, −1,051 B on `likes-badge`, −1,047 B on
+// `run-console`, every title still registered. Imported bare by `index.ts` (a page
+// rebuilds a node's refusal by code in `refusalError`, and `page-errors.ts` constructs codes from
+// here without importing it) and by `errors.ts`, so constructing a server refusal registers too.
+
+import { registerErrorCodes } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const REALTIME_OWNED_ERROR_CODES = [
+  'X_TOPIC_FORBIDDEN',
+  'X_SUBSCRIPTION_LIMIT',
+  'X_SUBSCRIPTION_ID_TAKEN',
+  'X_FRAME_RATE_LIMIT',
+  'X_PROTOCOL_VERSION',
+  'X_CURSOR_STALE',
+  'X_REBASE_CONFLICT',
+  'X_TRANSPORT_UNAVAILABLE',
+  'X_TRANSPORT_PROTOCOL',
+  'X_REPLICATION_PROTOCOL',
+  'X_REPLICATION_FAILED',
+  'X_REPLICATOR_SLOT_HELD',
+  // Retired in 21.0.0 and never thrown since — kept registered, because a shipped code is
+  // forever: a log line from an older build still resolves through `x errors explain`.
+  'X_LIVE_CLIENT_MISSING',
+  'X_QUERY_NOT_SUBSCRIBABLE',
+  'X_REALTIME_UNINSTALLED',
+  'X_SYNC_UNCONFIGURED',
+  'X_RECORD_REJECTED',
+  'X_CHANNEL_DECLARATION_INVALID',
+  'X_LOCAL_STORE_UNAVAILABLE',
+  'X_LIVE_SERVER_RENDER',
+  'X_LIVE_ROW_UNIDENTIFIED',
+  'X_LIVE_QUERY_UNKNOWN',
+  'X_LIVE_REPLICA_IDENTITY',
+  'X_SOCKET_UNAUTHENTICATED',
+  'X_SOCKET_AUTH_UNAVAILABLE',
+  'X_REALTIME_TOPOLOGY',
+  'X_REPLICATION_TLS',
+  'X_SOCKET_ORIGIN_REFUSED',
+  'X_OFFLINE_QUEUE_ABANDONED',
+  'X_SOCKET_LIMIT',
+  'X_REALTIME_PRODUCER_CONFLICT',
+] as const;
+
+export type RealtimeOwnedErrorCode = (typeof REALTIME_OWNED_ERROR_CODES)[number];
+
+export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, string>> = {
+  X_TOPIC_FORBIDDEN: 'the actor may not subscribe to this topic',
+  X_SUBSCRIPTION_LIMIT: 'socket, actor, tenant or node hit its subscription cap',
+  X_SUBSCRIPTION_ID_TAKEN: 'a subscribe frame reused a sid this socket already holds',
+  X_FRAME_RATE_LIMIT: 'one socket sent frames faster than this node will route them',
+  X_PROTOCOL_VERSION: 'client and sync node disagree on the wire protocol',
+  X_CURSOR_STALE: 'the resume LSN is outside the change buffer',
+  X_REBASE_CONFLICT: 'a local mutation could not be rebased',
+  X_TRANSPORT_UNAVAILABLE: 'the fanout bus is unreachable',
+  X_TRANSPORT_PROTOCOL: 'the bus does not speak the protocol this build speaks',
+  X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
+  X_REPLICATION_FAILED: 'the replication connection was refused',
+  X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
+  X_LIVE_CLIENT_MISSING:
+    'retired in 21.0.0 (no LiveClient to register; see X_REALTIME_UNINSTALLED): a realtime hook ran in a browser with no LiveClient registered',
+  X_QUERY_NOT_SUBSCRIBABLE:
+    'retired in 21.0.0 (liveHookFor was deleted; useQuery reads any query): a hook was bound to a query that is not declared live',
+  X_REALTIME_UNINSTALLED: 'a realtime hook ran in an island bundle that never installed realtime',
+  X_SYNC_UNCONFIGURED: 'a live hook needed the page socket and no sync target was configured',
+  X_RECORD_REJECTED: 'a row reached the record store in a shape it cannot hold',
+  X_CHANNEL_DECLARATION_INVALID: 'a channel() declaration cannot route its rows',
+  X_LOCAL_STORE_UNAVAILABLE: "the page's durable store could not open",
+  X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
+  X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
+  X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
+  X_LIVE_REPLICA_IDENTITY: 'a replicated table has no replica identity',
+  X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
+  X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
+  X_REALTIME_TOPOLOGY: 'a sync node boots on a real database with no reachable change feed',
+  X_REPLICATION_TLS: 'the replication connection failed TLS',
+  X_SOCKET_ORIGIN_REFUSED: 'the websocket upgrade came from another origin',
+  X_OFFLINE_QUEUE_ABANDONED: 'a write was queued after its page changed principal',
+  X_SOCKET_LIMIT: 'one principal holds too many sockets on this node',
+  X_REALTIME_PRODUCER_CONFLICT: 'two kinds of producer carry one table on the change bus',
+};
+
+// One unconditional call, so a second package claiming one of realtime's codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(REALTIME_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);

package/src/errors.ts

@@ -1,42 +1,19 @@
 // Realtime's X_* codes. Every throw in this package goes through one of these classes so
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
-import { registerErrorCodes } from '@ultimat3/core';
+import { isFixShellSafe, renderFixShellArg } from '@ultimat3/core';
+// The owned code list and its titles are `error-titles.ts` — the one module `sideEffects` lists,
+// imported bare here and from the barrel — so this module is side-effect-free and a chunk keeps
+// only the classes it constructs. Re-exported, so every name is still importable from `./errors`.
+import './error-titles';
+import { REALTIME_OWNED_ERROR_CODES } from './error-titles';
 import { RealtimeError } from './realtime-error';
 
-/** Codes this package declares and owns. */
-export const REALTIME_OWNED_ERROR_CODES = [
-  'X_TOPIC_FORBIDDEN',
-  'X_SUBSCRIPTION_LIMIT',
-  'X_SUBSCRIPTION_ID_TAKEN',
-  'X_FRAME_RATE_LIMIT',
-  'X_PROTOCOL_VERSION',
-  'X_CURSOR_STALE',
-  'X_REBASE_CONFLICT',
-  'X_TRANSPORT_UNAVAILABLE',
-  'X_TRANSPORT_PROTOCOL',
-  'X_REPLICATION_PROTOCOL',
-  'X_REPLICATION_FAILED',
-  'X_REPLICATOR_SLOT_HELD',
-  // Retired in 21.0.0 and never thrown since — kept registered, because a shipped code is
-  // forever: a log line from an older build still resolves through `x errors explain`.
-  'X_LIVE_CLIENT_MISSING',
-  'X_QUERY_NOT_SUBSCRIBABLE',
-  'X_REALTIME_UNINSTALLED',
-  'X_SYNC_UNCONFIGURED',
-  'X_RECORD_REJECTED',
-  'X_CHANNEL_DECLARATION_INVALID',
-  'X_LOCAL_STORE_UNAVAILABLE',
-  'X_LIVE_SERVER_RENDER',
-  'X_LIVE_ROW_UNIDENTIFIED',
-  'X_LIVE_QUERY_UNKNOWN',
-  'X_LIVE_REPLICA_IDENTITY',
-  'X_SOCKET_UNAUTHENTICATED',
-  'X_SOCKET_AUTH_UNAVAILABLE',
-  'X_REALTIME_TOPOLOGY',
-  'X_REPLICATION_TLS',
-  'X_SOCKET_ORIGIN_REFUSED',
-] as const;
+export {
+  REALTIME_ERROR_TITLES,
+  REALTIME_OWNED_ERROR_CODES,
+  type RealtimeOwnedErrorCode,
+} from './error-titles';
 
 /**
  * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s, and `X_FORBIDDEN` — thrown by the surface denials this
@@ -61,6 +38,24 @@ export const POLICY_DENIAL_CODES: ReadonlySet<string> = new Set([
   'X_UNAUTHENTICATED',
 ]);
 
+/**
+ * `@ultimat3/entity`'s tenant guard refusing a read FOR THIS ACTOR: it carries no org, names
+ * another one, or reached across tenants without the capability. Verdicts about who is asking, so
+ * a channel's row loader raising one is a denial. `X_TENANCY_UNSCOPED` is deliberately absent —
+ * that is a query written without a tenant predicate, which is the app's defect and no decision.
+ * Spelled by name, never matched by prefix: a code's meaning is its owner's, not its shape's.
+ */
+export const TENANCY_DENIAL_CODES: ReadonlySet<string> = new Set([
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+  'X_TENANCY_ACTOR_MISMATCH',
+  'X_TENANCY_CROSS_DENIED',
+]);
+
+/** True when the tenant guard decided against the actor — see `TENANCY_DENIAL_CODES`. */
+export function isTenancyDenial(error: unknown): boolean {
+  return TENANCY_DENIAL_CODES.has(codeOf(error) ?? '');
+}
+
 /**
  * The sync protocol's answer to "which of these is a 4xx". A denied topic, a subscription cap, a
  * skewed protocol version and a cursor that fell out of the buffer are all conditions the CLIENT
@@ -112,53 +107,12 @@ export const REALTIME_ERROR_CODES = [
   ...REALTIME_BORROWED_ERROR_CODES,
 ] as const;
 
-export type RealtimeOwnedErrorCode = (typeof REALTIME_OWNED_ERROR_CODES)[number];
 export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[number];
 
-export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, string>> = {
-  X_TOPIC_FORBIDDEN: 'the actor may not subscribe to this topic',
-  X_SUBSCRIPTION_LIMIT: 'socket, tenant or node hit its subscription cap',
-  X_SUBSCRIPTION_ID_TAKEN: 'a subscribe frame reused a sid this socket already holds',
-  X_FRAME_RATE_LIMIT: 'one socket sent frames faster than this node will route them',
-  X_PROTOCOL_VERSION: 'client and sync node disagree on the wire protocol',
-  X_CURSOR_STALE: 'the resume LSN is outside the change buffer',
-  X_REBASE_CONFLICT: 'a local mutation could not be rebased',
-  X_TRANSPORT_UNAVAILABLE: 'the fanout bus is unreachable',
-  X_TRANSPORT_PROTOCOL: 'the bus does not speak the protocol this build speaks',
-  X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
-  X_REPLICATION_FAILED: 'the replication connection was refused',
-  X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
-  X_LIVE_CLIENT_MISSING:
-    'retired in 21.0.0 (no LiveClient to register; see X_REALTIME_UNINSTALLED): a realtime hook ran in a browser with no LiveClient registered',
-  X_QUERY_NOT_SUBSCRIBABLE:
-    'retired in 21.0.0 (liveHookFor was deleted; useQuery reads any query): a hook was bound to a query that is not declared live',
-  X_REALTIME_UNINSTALLED: 'a realtime hook ran in an island bundle that never installed realtime',
-  X_SYNC_UNCONFIGURED: 'a live hook needed the page socket and no sync target was configured',
-  X_RECORD_REJECTED: 'a row reached the record store in a shape it cannot hold',
-  X_CHANNEL_DECLARATION_INVALID: 'a channel() declaration cannot route its rows',
-  X_LOCAL_STORE_UNAVAILABLE: "the page's durable store could not open",
-  X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
-  X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
-  X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
-  X_LIVE_REPLICA_IDENTITY: 'a replicated table has no replica identity',
-  X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
-  X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
-  X_REALTIME_TOPOLOGY: 'a sync node boots on a real database with no reachable change feed',
-  X_REPLICATION_TLS: 'the replication connection failed TLS',
-  X_SOCKET_ORIGIN_REFUSED: 'the websocket upgrade came from another origin',
-};
-
-// One unconditional call, so a second package claiming one of realtime's codes throws
-// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
-registerErrorCodes(
-  Object.fromEntries(
-    Object.entries(REALTIME_ERROR_TITLES).map(([code, title]) => [code, { title }]),
-  ),
-);
-
 export {
   CursorStaleError,
   LocalStoreUnavailableError,
+  OfflineQueueAbandonedError,
   ProtocolVersionError,
   RealtimeUninstalledError,
   RebaseConflictError,
@@ -168,9 +122,9 @@ export {
 } from './page-errors';
 // Re-exported, never re-declared: `RealtimeError` lives in `realtime-error.ts`, the four
 // replication errors in `replication-errors.ts` and the browser-reachable refusals in
-// `page-errors.ts`, so this file is the CODE TABLE plus the server's refusals. Every name is still
-// importable from `./errors`, which is what the `pg-*` modules and the barrel already do; a
-// browser module imports `./page-errors` so it does not load the table.
+// `page-errors.ts`, and the code table in `error-titles.ts`, so this file is the server's refusals.
+// Every name is still importable from `./errors`, which is what the `pg-*` modules and the barrel
+// already do; a browser module imports `./page-errors` so it does not load these classes.
 export { RealtimeError } from './realtime-error';
 export {
   ReplicaIdentityError,
@@ -193,17 +147,19 @@ export class TopicForbiddenError extends RealtimeError {
 }
 
 /**
- * Load shedding, not a crash: a socket, a tenant or this node asked for more than its cap.
+ * Load shedding, not a crash: a socket, a tenant, an actor or this node asked for more than its cap.
  *
  * `knob` is the option that raises it, and it is passed rather than derived because the `node`
  * scope has more than one — a live-query entry ceiling and a channel-topic ceiling are two
- * different numbers on two different objects. The fix names the constructor option, never an
- * `app.config.ts` field: there is none (`docs/architecture/07-realtime-internals.md:244`), and a
- * fix line naming a field that does not exist is an instruction that cannot be followed.
+ * different numbers on two different objects. Every scope but `actor` names a CONSTRUCTOR option:
+ * those have no `app.config.ts` field, and a fix naming a field that does not exist is an
+ * instruction that cannot be followed. The actor cap is the one that is app config —
+ * `realtime.maxSubscriptionsPerActor` — so its fix names that key and that file first, then the
+ * registry option a host that builds its own `LiveQueryRegistry` sets instead.
  */
 export class SubscriptionLimitError extends RealtimeError {
   constructor(args: {
-    scope: 'socket' | 'tenant' | 'node';
+    scope: 'socket' | 'tenant' | 'actor' | 'node';
     id: string;
     limit: number;
     knob?: string;
@@ -212,7 +168,10 @@ export class SubscriptionLimitError extends RealtimeError {
     super({
       code: 'X_SUBSCRIPTION_LIMIT',
       cause: `${args.scope} ${args.id} reached the subscription cap of ${args.limit}`,
-      fix: `raise ${knob} where this sync node is constructed, or unsubscribe unused live queries`,
+      fix:
+        args.scope === 'actor'
+          ? `defineConfig({ realtime: { maxSubscriptionsPerActor: ${args.limit * 2} } })   # in app.config.ts — realtime.maxSubscriptionsPerActor; or maxPerActor on new LiveQueryRegistry({…}) where a host builds its own; or unsubscribe unused live queries`
+          : `raise ${knob} where this sync node is constructed, or unsubscribe unused live queries`,
     });
   }
 }
@@ -230,7 +189,7 @@ export class FrameRateLimitError extends RealtimeError {
     super({
       code: 'X_FRAME_RATE_LIMIT',
       cause: `socket ${args.socketId} exceeded ${args.perSecond} frames per second`,
-      fix: 'batch subscribes into one frame per subscription and retry after the delay, or raise maxFramesPerSecond where createSyncNode() is called',
+      fix: 'batch subscribes into one frame per subscription and retry after the delay, or raise maxFramesPerSecond where syncNode() is called',
     });
   }
 }
@@ -300,17 +259,33 @@ export class TransportProtocolError extends RealtimeError {
 }
 
 /**
- * A subscribable read projected a row with no `id`. Patches, cursors and the local store all
- * address a row by `id`, so such a row cannot be delivered — and delivering it anyway produces a
- * subscription that looks correct until the first update nobody can apply.
+ * A subscribable read projected a row with no usable `id`. Patches, cursors and the local store all
+ * address a row by a text `id`, so such a row cannot be delivered — and delivering it anyway
+ * produces a subscription that looks correct until the first update nobody can apply.
+ *
+ * `idType` is set when the row HAS an id that is neither text nor a safe integer (the one numeric
+ * shape the change feed and the snapshot both stringify): "select the primary key" is then the
+ * wrong instruction, because the key is selected.
  */
 export class LiveRowUnidentifiedError extends RealtimeError {
-  constructor(args: { query: string; keys: readonly string[] }) {
-    super({
-      code: 'X_LIVE_ROW_UNIDENTIFIED',
-      cause: `live query "${args.query}" returned a row with no id (columns: ${args.keys.join(', ') || 'none'})`,
-      fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
-    });
+  constructor(args: { query: string; keys: readonly string[]; idType?: string }) {
+    const columns = args.keys.join(', ') || 'none';
+    super(
+      args.idType === undefined
+        ? {
+            code: 'X_LIVE_ROW_UNIDENTIFIED',
+            cause: `live query "${args.query}" returned a row with no id (columns: ${columns})`,
+            fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
+          }
+        : {
+            code: 'X_LIVE_ROW_UNIDENTIFIED',
+            cause: `live query "${args.query}" returned a row whose id is a ${args.idType}, not text or a safe integer — a live row is addressed by a text id, so project the key as text (a uuid or text column) or drop live: true from the query`,
+            // A name the shell would not read verbatim does not travel: the list names it instead.
+            fix: isFixShellSafe(args.query)
+              ? `x queries describe ${renderFixShellArg(args.query, 'name')} --json`
+              : 'x queries list --json',
+          },
+    );
   }
 }
 
@@ -351,7 +326,26 @@ export class SocketUnauthenticatedError extends RealtimeError {
     super({
       code: 'X_SOCKET_UNAUTHENTICATED',
       cause: `the websocket upgrade was refused: ${args.reason}`,
-      fix: 'send the credential createSyncNode({ authenticate }) reads on the upgrade request, or return an anonymous Actor from it to admit this socket',
+      fix: 'send the credential syncNode({ authenticate }) reads on the upgrade request, or return an anonymous Actor from it to admit this socket',
+    });
+  }
+}
+
+/**
+ * One principal — an actor, or an anonymous caller's network — already holds this node's per-
+ * principal share of sockets. Answered on the upgrade with 429, before a socket exists. The
+ * principal is the node's own key (`actor:<id>` / `address:<network>`), never request text.
+ */
+export class SocketLimitError extends RealtimeError {
+  constructor(args: { principal: string; limit: number }) {
+    // An anonymous network's cap is 8 x `maxSocketsPerActor` (`principal-sockets.ts`), so the
+    // value to set is derived from the actor cap either way, never the limit this socket hit.
+    const network = args.principal.startsWith('address:');
+    const perActor = network ? Math.ceil(args.limit / 8) : args.limit;
+    super({
+      code: 'X_SOCKET_LIMIT',
+      cause: `${args.principal} already holds ${args.limit} sockets on this sync node — the per-principal cap${network ? ' (an anonymous network gets 8 x realtime.maxSocketsPerActor)' : ''}`,
+      fix: `defineConfig({ realtime: { maxSocketsPerActor: ${perActor * 2} } })   # in app.config.ts — or maxSocketsPerActor on syncNode({…}) where a host builds its own; or close other tabs of this app`,
     });
   }
 }
@@ -363,11 +357,21 @@ export class SocketUnauthenticatedError extends RealtimeError {
  * the accept budget, so a hostile page costs neither.
  */
 export class SocketOriginRefusedError extends RealtimeError {
-  constructor(args: { reason: string }) {
+  constructor(args: { reason: string; asked: string | null; admitted: readonly string[] }) {
+    // The asking origin is a request header: it travels only as the origin a URL parser read out
+    // of it AND only when the shell screen carries it verbatim, so neither the cause nor the
+    // pasted `export` can hold anything the client wrote beyond a scheme, a host and a port.
+    const parsed = URL.parse(args.asked ?? '')?.origin;
+    const asked = isFixShellSafe(parsed) ? parsed : null;
+    const { admitted } = args;
+    const list =
+      admitted.length === 0
+        ? 'only the origin it was reached on (no APP_URL declared)'
+        : `only ${admitted.join(', ')}`;
     super({
       code: 'X_SOCKET_ORIGIN_REFUSED',
-      cause: `the websocket upgrade was refused: ${args.reason}`,
-      fix: 'export APP_URL="https://www.example.com"   # on the sync role: the origin the page is served on (or createSyncNode({ allowedOrigins }))',
+      cause: `the websocket upgrade was refused: ${args.reason} — asked from ${asked ?? 'an origin that cannot be rendered'}; this node admits ${list}`,
+      fix: `export APP_URL=${asked ?? 'https://www.example.com'}   # on the sync role, and only when that is the origin your pages are served on (or syncNode({ allowedOrigins }))`,
     });
   }
 }
@@ -405,13 +409,17 @@ export class WindowReadTimeoutError extends RealtimeError {
   }
 }
 
-/** Deep infrastructure that is interface-complete but not wired. Carries the exact next step. */
-export class NotImplementedError extends RealtimeError {
-  constructor(args: { what: string; fix: string }) {
+/**
+ * A grant's `refresh()` — the app's token service — did not answer inside its deadline. The grant
+ * is NOT renewed and NOT revoked: it stays expired and the next re-auth pass asks again. What the
+ * deadline buys is the rest of the pass, which one call that never settles used to park forever.
+ */
+export class GrantRefreshTimeoutError extends RealtimeError {
+  constructor(args: { socketId: string; afterMs: number }) {
     super({
-      code: 'X_NOT_IMPLEMENTED',
-      cause: `${args.what} is interface-complete but not implemented in this build`,
-      fix: args.fix,
+      code: 'X_TIMEOUT',
+      cause: `refresh() for the grant of socket ${args.socketId} did not answer within ${args.afterMs}ms, so the re-auth pass moved on; the grant stays expired and is asked again on the next pass`,
+      fix: 'x doctor --json',
     });
   }
 }

package/src/fanout.ts

@@ -36,6 +36,14 @@ export interface Transport {
   publish(subject: string, payload: string): Promise<void>;
   subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription>;
   readonly shared: TransportSet;
+  /**
+   * Told each time the connection behind this transport comes back from a drop. Fanout is
+   * at-most-once, so whatever was published in between never arrived — and with no later message
+   * there is no sequence number to notice it by. A subscriber that keeps derived state (a `sync`
+   * node's windows) invalidates it here. Returns the unsubscribe. A transport with no connection
+   * to lose never calls the listener.
+   */
+  onReconnect(listener: () => void): () => void;
   close(): Promise<void>;
 }
 
@@ -125,6 +133,11 @@ export class InProcessTransport implements Transport {
     }
   }
 
+  /** One process, no connection: there is nothing to come back from, so nothing is ever said. */
+  onReconnect(): () => void {
+    return () => undefined;
+  }
+
   async subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription> {
     this.#assertOpen();
     const handlers = this.#handlers.get(subject) ?? new Set<TransportHandler>();

package/src/first-paint-hold.ts

@@ -0,0 +1,49 @@
+// What a realtime island's bootstrap awaits before its `mount` may run (#506, owner option 3): the
+// page boot's disk restore AND the outbox it opened, so the island's first render already carries
+// the overlays a reload rebuilds from the queue — never the server's stale count. Capped, because
+// an IndexedDB that hangs must cost the hold, never the island.
+
+import { peekOutbox } from './outbox-slot';
+import { pageRealtime } from './page-store';
+
+/**
+ * The longest a realtime island waits on the restore before it mounts anyway. A warm IndexedDB
+ * opens in tens of milliseconds; a second is a disk that is not answering, and past it the island
+ * paints what it has. Below `@ultimat3/render`'s `ISLAND_HOLD_MS`, which reveals the server's
+ * markup regardless — so this cap, not that one, is the one a slow disk meets.
+ */
+export const FIRST_PAINT_HOLD_MS = 1_000;
+
+/** `settled` — the restore finished (or was refused; there is nothing more to wait for). */
+export type FirstPaintHold = 'settled' | 'capped';
+
+/**
+ * Resolves once the page's records are back AND its outbox is open — what `useMutation` rebuilds a
+ * queued write's overlay from, synchronously from then on — or at the cap. Never rejects: a hold
+ * that threw would take the island's module graph, and with it the island, down with the disk.
+ * A page with no boot resolves at once (`booted` does, and no outbox is seated). No options: the
+ * cap is the constant, and an option would ship its finite-number screen (~550 B) in every
+ * realtime island to serve tests that can stub the timer instead.
+ */
+export async function holdFirstPaint(): Promise<FirstPaintHold> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const capped = new Promise<FirstPaintHold>((resolve) => {
+    timer = setTimeout(() => resolve('capped'), FIRST_PAINT_HOLD_MS);
+  });
+  try {
+    return await Promise.race([restored(), capped]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function restored(): Promise<FirstPaintHold> {
+  try {
+    await pageRealtime().booted;
+    // Read after the boot, never before: the boot seats the outbox as its last step.
+    await peekOutbox()?.ready;
+  } catch {
+    // The boot already reported what the disk refused (`boot.ts`); the hold only stops waiting.
+  }
+  return 'settled';
+}

package/src/idb-types.ts

@@ -1,7 +1,7 @@
 /**
  * The slice of IndexedDB `local-store-idb.ts` touches, as structural types: the browser's
- * `indexedDB` satisfies them and so does `idb-fake.ts`, so the store is tested against the same
- * surface it runs on without a DOM shim.
+ * `indexedDB` satisfies them and so does `idb-fake-fixture.ts`, so the store is tested against the
+ * same surface it runs on without a DOM shim.
  */
 
 export interface IdbRequestLike<T> {

package/src/index.ts

@@ -3,6 +3,12 @@
 // Nothing here reaches `nats`, a Postgres socket or the sync node; those are `./server`, and
 // `packages/cli/src/realtime-browser-barrel.test.ts` is the build error that keeps them apart.
 
+// Imported bare, and the one module `sideEffects` lists: a page rebuilds a sync node's refusal by
+// code (`refusalError`) and `page-errors.ts` constructs codes from it without importing it, so
+// every chunk reaching this barrel registers the titles. `SIDE_EFFECTS_ANCHORS` carries the
+// argument and `bun run side-effects` enforces it.
+import './error-titles';
+
 // ---- the client's one stateless piece, reusable against an app's own store ----------------------
 export { applyPatches, orderAfterPatches } from './apply-patches';
 // ---- channels: the declaration is the only way to spell a topic, and the frames it rides --------
@@ -62,7 +68,7 @@ export {
   FrameRateLimitError,
   LiveQueryUnknownError,
   LiveRowUnidentifiedError,
-  NotImplementedError,
+  OfflineQueueAbandonedError,
   ProtocolVersionError,
   REALTIME_ERROR_CODES,
   REALTIME_ERROR_TITLES,
@@ -84,10 +90,15 @@ export {
   TransportUnavailableError,
   WindowReadTimeoutError,
 } from './errors';
+// ---- the page: one record store, one socket, installed by the island bootstrap ------------------
+export {
+  FIRST_PAINT_HOLD_MS,
+  type FirstPaintHold,
+  holdFirstPaint,
+} from './first-paint-hold';
 // ---- shared value domain ---------------------------------------------------------------------
 export {
   changedColumns,
-  isJsonObject,
   isRow,
   type JsonObject,
   type JsonValue,
@@ -99,7 +110,8 @@ export { type LiveState, type Registration, RowWindows, unnamedType } from './li
 // ---- offline: the durable store, the persisted records, the one outbox (plan 101 slice 12) ------
 export {
   type LocalStore,
-  MemoryLocalStore,
+  type MemoryLocalStore,
+  memoryLocalStore,
   openLocalStore,
   pageLocalStore,
   scopeKey,
@@ -107,22 +119,22 @@ export {
 // ---- the offline outbox (wired over HTTP in plan 101 slice 12) ----------------------------------
 export {
   type DrainReport,
-  MemoryQueueStore,
+  type MemoryQueueStore,
   type MutationSender,
   type MutationStatus,
+  memoryQueueStore,
   OfflineQueue,
   type QueuedMutation,
   type QueueState,
   type QueueStore,
 } from './offline-queue';
 export {
-  createOutbox,
   listenForDrain,
+  localOutbox,
   type OutboxEntry,
   type PageOutbox,
   pageOutbox,
 } from './page-outbox';
-// ---- the page: one record store, one socket, installed by the island bootstrap ------------------
 export { hasPageSocket, type SyncTarget } from './page-store';
 export { installRealtime, type RealtimeInstall } from './reactivity';
 export { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
@@ -182,4 +194,10 @@ export {
   useMutationQueue,
 } from './use-mutation';
 export { type QueryAccessor, type QueryOptions, type QueryRef, useQuery } from './use-query';
-export { type RecordAccessor, type RecordsAccessor, useRecord, useRecords } from './use-record';
+export {
+  type RecordAccessor,
+  type RecordSelection,
+  type RecordsAccessor,
+  useRecord,
+  useRecords,
+} from './use-record';

package/src/json.ts

@@ -8,6 +8,8 @@
 // for having no reader. A 32-bit hash nothing calls is a hash the next caller reaches for as a
 // sharing key, which is the one thing it must never be.
 
+import { isJsonObject } from '@ultimat3/core/page';
+
 export type JsonValue =
   | string
   | number
@@ -39,14 +41,25 @@ export interface RowPatch {
    * projection on the server. Absent means the key is the `id`.
    */
   readonly key?: string;
+  /**
+   * The write that made this patch's change (`ChangeEvent.write`), held only on the RETAINED
+   * patch so a delta resume can name it. Server-side only: a frame names its writes once, in
+   * `PatchFrame.writes`, so `live-resume.ts` strips it before sending and `decode` never reads it.
+   */
+  readonly write?: string;
 }
 
-export function isJsonObject(value: unknown): value is JsonObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Core's `isJsonObject`, read as the wire's value domain. Sound ONLY for a value that came out of
+ * `JSON.parse` (a frame, a stored row): every member of one is a `JsonValue` by construction, which
+ * is the one thing core's shape check cannot know and so does not claim. One implementation, core's.
+ */
+export function isParsedJsonObject(value: unknown): value is JsonObject {
+  return isJsonObject(value);
 }
 
 export function isRow(value: unknown): value is Row {
-  return isJsonObject(value) && typeof value['id'] === 'string';
+  return isParsedJsonObject(value) && typeof value['id'] === 'string';
 }
 
 /** Shallow diff used to keep update patches minimal — the pipeline never ships unchanged columns. */

package/src/live-contract.ts

@@ -34,6 +34,13 @@ export interface LiveQueryDefinition<R extends Row = Row> {
   snapshot(args: { input: JsonValue; tenant: string | null }): Promise<SnapshotResult<R>>;
   /** Subscribe-time gate. Throws to deny — the same `policy` used by HTTP, jobs, and MCP. */
   authorize?(args: { actor: Actor | null; input: JsonValue }): void | Promise<void>;
+  /**
+   * The read's declared `rateLimit:`, spent once per SUBSCRIBE, after `authorize` allowed it —
+   * the same bucket HTTP, a paged read and the MCP tool spend. Per subscriber because the shared
+   * window builds with no subject and spends nothing; never on a re-authorization, because the
+   * subscription it re-decides was already paid for. Throws `X_RATE_LIMITED` to refuse.
+   */
+  spend?(caller: LiveSpender): Promise<void>;
   /** Row-level gate, evaluated per subscriber. The only row filter in the pipeline. */
   visible(args: { actor: Actor | null; row: R; input: JsonValue }): boolean | Promise<boolean>;
   /** Built once per `qid`, since a qid pins both the query and its input. */
@@ -59,6 +66,13 @@ export interface LiveQueryDefinition<R extends Row = Row> {
   prepare?(input: JsonValue): Promise<void>;
 }
 
+/** Who a live subscribe is charged to: the socket's actor, else its address, on the node's clock. */
+export interface LiveSpender {
+  readonly actor: Actor | null;
+  readonly clientAddress: string | null;
+  readonly nowMs: number;
+}
+
 export interface LiveSubscription {
   readonly sid: string;
   readonly qid: string;