@ultimat3/realtime 30.9.0 → 31.1.0

package/src/changefeed.ts

@@ -5,7 +5,7 @@
 import type { Clock } from '@ultimat3/core';
 import { finiteOption } from '@ultimat3/core';
 import { ReplicationFailedError } from './errors';
-import type { Row } from './json';
+import type { LiveRow } from './json';
 import { PgReplicationStream, type ReplicationStreamStats } from './pg-replication';
 import type { PgTarget } from './pg-socket';
 import type { PgStream } from './pg-wire';
@@ -19,7 +19,7 @@ import type { Rng } from './thundering-herd';
  */
 export type ChangeOp = 'insert' | 'update' | 'delete' | 'truncate';
 
-export interface ChangeEvent<R extends Row = Row> {
+export interface ChangeEvent<R extends LiveRow = LiveRow> {
   /**
    * The RELATION (table) name, on every producer: the WAL decoder reads it off the Relation
    * message, the in-process bridge maps the row observer's entity name onto it, and a
@@ -66,6 +66,12 @@ export interface ChangeFeedStartOptions {
    * was only recorded was a death nobody saw.
    */
   readonly onEnd?: (reason: string) => void;
+  /**
+   * The stream is no longer continuous with `from`: changes were committed that it will never
+   * deliver (a replication slot recreated under a resume position). Every reader must re-read
+   * now. Called at most once per `start()`, before its first change.
+   */
+  readonly onResync?: (reason: string) => void;
 }
 
 export interface ChangeFeed {
@@ -152,8 +158,8 @@ export class MemoryChangeFeed implements ChangeFeed {
     table: string,
     op: ChangeOp,
     rows: {
-      before?: Row | null;
-      after?: Row | null;
+      before?: LiveRow | null;
+      after?: LiveRow | null;
       orgId?: string | null;
       at?: number;
       write?: string | null;
@@ -252,6 +258,7 @@ export class PostgresChangeFeed implements ChangeFeed {
       from: options.from,
       onChange: options.onChange,
       onEnd: options.onEnd,
+      onResync: options.onResync,
     });
   }
 

package/src/channel-decl.ts

@@ -3,7 +3,7 @@
 // same declaration for a ref an island already holds (`channel-ref.ts`): the browser chunk then
 // carries the name and params, never `@ultimat3/entity` (plan 101, slice 09).
 
-import type { Ctx, Row } from '@ultimat3/core';
+import { assertCoded, type Ctx, type Row } from '@ultimat3/core';
 import {
   type ProjectedEntity,
   type RecordProjection,
@@ -11,9 +11,11 @@ import {
 } from '@ultimat3/entity/record';
 import type { QueryPolicy } from '@ultimat3/query';
 import {
+  type CatchUpRead,
   type ChannelHandle,
   type ChannelParams,
   type ChannelRefInit,
+  catchUpReadOf,
   channelRef,
   refuseChannel,
   SEGMENT,
@@ -39,6 +41,31 @@ function projectionFor(name: string, entity: ChannelEntity): RecordProjection {
   }
 }
 
+/**
+ * A catch-up read is served on its own route (`GET /_x/query/<name>`) with the channel params as
+ * input, so a read deciding with a WIDER policy hands any caller what the channel refuses — the
+ * demo's inbox did (plan 101 R9). Identity, not equivalence: two rules cannot be compared, one
+ * object can. A name-only read (a browser ref) carries no policy to hold.
+ */
+function assertCatchUpPolicy(
+  name: string,
+  read: CatchUpRead | undefined,
+  policy: QueryPolicy,
+): void {
+  if (read === undefined || !('policy' in read)) return;
+  if (read.policy === policy) return;
+  const label = (value: unknown): string =>
+    typeof value === 'object' && value !== null && typeof Reflect.get(value, 'label') === 'string'
+      ? String(Reflect.get(value, 'label'))
+      : 'an unlabelled policy';
+  assertCoded(
+    false,
+    'X_CHANNEL_CATCHUP_POLICY_MISMATCH',
+    `channel("${name}"): its catch-up read "${read.name || '(named at boot)'}" decides with ${label(read.policy)}, the channel with ${label(policy)} — the read is served with the channel params as input, so it would answer what the subscribe refuses`,
+    `set the catch-up query's policy: to the same object channel("${name}", { policy }) passes — export the rule from the feature's policy.ts and import it in both files`,
+  );
+}
+
 /** What only the server half declares: the rows it carries and who may join. */
 export interface ChannelServerInit {
   /**
@@ -114,6 +141,7 @@ export function channel<K extends string>(
       "add policy: can('<resource>:read') to the channel() call, or policy: allow('public') for a channel anyone may join",
     );
   }
+  assertCatchUpPolicy(name, catchUpReadOf(ref), policy);
   const records = (init.records ?? []).map((entity) => {
     const projection = projectionFor(name, entity);
     for (const param of ref.params) {

package/src/channel-publish.ts

@@ -4,6 +4,7 @@
 // The frame and its subject are spelled here once; the hub's own `emit` publishes through them.
 
 import { assertCoded } from '@ultimat3/core';
+import { adapterSlot } from '@ultimat3/core/adapter';
 import type { Channel, Topic } from './channel-decl';
 import type { ChannelEventsFrame } from './channel-wire';
 import { InProcessTransport, type Transport } from './fanout';
@@ -26,28 +27,25 @@ export async function sendChannelEvent(
 }
 
 /**
- * The bus this process publishes on. A heap bus nobody subscribes to until a boot installs the
- * real one — `jobs`' `setEventBus` arrangement — so a unit test, or a script that booted nothing,
- * publishes to nobody instead of throwing in the middle of the write it follows.
+ * The buses installed, newest last, over the heap bus a process boots with — nobody subscribes to
+ * that one, so a unit test or a script that booted nothing publishes to nobody instead of throwing
+ * in the middle of the write it follows. Core's one frame stack: a release puts back what was there
+ * before it, and one transport installed twice is two frames.
  */
-let ambient: Transport = new InProcessTransport();
+const booted: Transport = new InProcessTransport();
+const installed = adapterSlot<Transport>(() => booted);
 
 /**
- * Called by the boot (`startServices`) with the transport `selectTransport` chose, in EVERY role:
- * the same object the `sync` role's hub subscribes on, so under `x dev` a publish reaches this
- * process's own sockets and under NATS every node's. Answers the release, which puts a fresh heap
- * bus back only while this install is still the current one.
+ * Called by the boot (`startServices`) with the process's transport — `apps/<app>/runtime.ts`'s
+ * `transport`, else the one `selectTransport` chose — in EVERY role: the same object the `sync`
+ * role's hub subscribes on, so under `x dev` a publish reaches this process's own sockets and under
+ * NATS every node's. Answers the release, which takes THIS install off the stack and so restores
+ * whatever was current before it (the boot's bus under a test's override); idempotent, and a
+ * release out of order removes only its own entry. Public on `@ultimat3/realtime/adapter` only: an
+ * app swaps the bus in `runtime.ts`, never by calling this.
  */
-export function setChannelTransport(transport: Transport): () => void {
-  ambient = transport;
-  return () => {
-    if (ambient === transport) resetChannelTransport();
-  };
-}
-
-/** Test seam: back to a fresh heap bus, the state a process boots in. */
-export function resetChannelTransport(): void {
-  ambient = new InProcessTransport();
+export function installChannelTransport(transport: Transport): () => void {
+  return installed.install(transport);
 }
 
 /**
@@ -71,5 +69,5 @@ export async function publishChannelEvent<K extends string>(
     `channel("${declared.name}") declares no events, so nothing may publish one on it`,
     `declare it with events: true: channel('${declared.name}', { …, events: true })`,
   );
-  await sendChannelEvent(ambient, declared.topic(params), event);
+  await sendChannelEvent(installed.current(), declared.topic(params), event);
 }

package/src/channel-ref.ts

@@ -35,7 +35,17 @@ export interface ChannelRefInit<K extends string> {
    * The read a client re-runs on `replay-gap` or a new epoch — a query, by name. Read on every
    * access, never at declaration: `registerQueries()` stamps a declared query's name at boot.
    */
-  readonly catchUp: { readonly name: string };
+  readonly catchUp: CatchUpRead;
+}
+
+/**
+ * The read a client re-runs, as the declaration passed it: a declared query carries its `policy`,
+ * which `channel()` holds to the channel's own (`X_CHANNEL_CATCHUP_POLICY_MISMATCH`); a browser
+ * ref passes the name alone, and the server half cannot second-guess what it was not handed.
+ */
+export interface CatchUpRead {
+  readonly name: string;
+  readonly policy?: unknown;
 }
 
 /** What a browser subscribes by — `useChannel(ref, params)`. */
@@ -48,6 +58,14 @@ export interface ChannelHandle<K extends string = string> {
   topic(params: ChannelParams<K>): Topic;
 }
 
+/** Each ref's catch-up read as declared — held off the frozen ref so the ref's shape stays its own. */
+const READS = new WeakMap<ChannelHandle, CatchUpRead>();
+
+/** The catch-up read a ref was built with; `undefined` for a handle `channelRef` did not build. */
+export function catchUpReadOf(ref: ChannelHandle): CatchUpRead | undefined {
+  return READS.get(ref);
+}
+
 export function refuseChannel(name: string, detail: string, fix: string): never {
   assertCoded(false, 'X_CHANNEL_DECLARATION_INVALID', `channel("${name}"): ${detail}`, fix);
 }
@@ -71,7 +89,7 @@ export function channelRef<const K extends string>(
   // inherited member would spell a topic nobody declared. Absent is `''`, which `topic()` refuses.
   const topicOf = (params: ChannelParams<K>): Topic =>
     topic(name, ...init.params.map((param) => (Object.hasOwn(params, param) ? params[param] : '')));
-  return Object.freeze({
+  const ref: ChannelHandle<K> = Object.freeze({
     kind: 'channel-ref' as const,
     name,
     params: init.params,
@@ -80,4 +98,6 @@ export function channelRef<const K extends string>(
     },
     topic: topicOf,
   });
+  READS.set(ref, init.catchUp);
+  return ref;
 }

package/src/client-channels.ts

@@ -67,7 +67,12 @@ interface Entry {
   readonly name: string;
   readonly catchUp: string;
   readonly params: Readonly<Record<string, string>>;
-  readonly holders: Set<ChannelHandlers>;
+  /**
+   * Keyed by a token minted per `hold`, never by the handlers object: two holders passing ONE
+   * object (a module-level const) are two holds, and keyed by it the first release dropped the
+   * topic under the second.
+   */
+  readonly holders: Map<object, ChannelHandlers>;
   readonly listeners: Set<() => void>;
   state: ChannelState;
   error: unknown;
@@ -124,7 +129,7 @@ export class ChannelBook {
         name: ref.name,
         catchUp: ref.catchUp,
         params,
-        holders: new Set(),
+        holders: new Map(),
         listeners: new Set(),
         state: this.#deps.connected() ? 'joining' : 'offline',
         error: undefined,
@@ -142,12 +147,13 @@ export class ChannelBook {
       if (this.#deps.connected()) this.#deps.send(this.#frame(entry, 'add', true));
     }
     const held = entry;
-    held.holders.add(handlers);
+    const token = {};
+    held.holders.set(token, handlers);
     let open = true;
     const release = (): void => {
       if (!open) return;
       open = false;
-      held.holders.delete(handlers);
+      held.holders.delete(token);
       if (held.holders.size > 0) return;
       this.#byTopic.delete(topic);
       held.disarm?.();
@@ -247,7 +253,7 @@ export class ChannelBook {
     // (no rows, so no `records` and no `replay-gap`) the roster is the one answer a subscribe
     // gets. Only from `joining`: a read in flight, a refusal and a dead socket are not undone.
     if (entry?.state === 'joining') this.#set(entry, 'live');
-    for (const holder of entry?.holders ?? []) {
+    for (const holder of entry?.holders.values() ?? []) {
       if (presence !== null) holder.onPresence?.(presence);
       else holder.onEvent?.(frame.event);
     }

package/src/client-contract.ts

@@ -7,7 +7,7 @@ import type { CatchUpRecords } from './channel-catch-up';
 import type { LiveCursor } from './cursor';
 import type { LiveState } from './live-rows';
 import type { RecordStore } from './record-store';
-import type { BackoffPolicy, Rng, Scheduler } from './thundering-herd';
+import type { ReconnectBackoff, Rng, Scheduler } from './thundering-herd';
 
 /**
  * A reactive primitive: `createSignal` narrowed to two functions. Installed PER ISLAND BUNDLE
@@ -65,7 +65,7 @@ export interface LiveClientOptions {
   /** The page's record store every window renders out of. A client builds its own when absent. */
   readonly store?: RecordStore;
   /** Default `browserBackoff`: capped at `BROWSER_RECONNECT_MAX_MS`, never the server's 30s. */
-  readonly backoff?: BackoffPolicy;
+  readonly backoff?: ReconnectBackoff;
   readonly rng?: Rng;
   readonly clock?: Clock;
   /** How a pending reconnect is armed. Defaults to `setTimeout`; tests fire theirs by hand. */

package/src/cursor.ts

@@ -4,7 +4,7 @@
 // accidental one. See README "Reconnect is the hard part".
 
 import { type Clock, systemClock } from '@ultimat3/core/page';
-import type { Row, RowPatch } from './json';
+import type { LiveRow, RowPatch } from './json';
 import { CursorStaleError } from './page-errors';
 
 /** Ids are bounded so a cursor stays small enough to ship on every `subscribe` frame. */
@@ -89,11 +89,11 @@ export interface ResumeSource {
   ): void;
 }
 
-export type ResumeResult<R extends Row = Row> =
+export type ResumeResult<R extends LiveRow = LiveRow> =
   | { readonly kind: 'delta'; readonly patches: readonly RowPatch[]; readonly cursor: LiveCursor }
   | { readonly kind: 'snapshot'; readonly rows: readonly R[]; readonly cursor: LiveCursor };
 
-export interface ResumeDeps<R extends Row = Row> {
+export interface ResumeDeps<R extends LiveRow = LiveRow> {
   readonly source: ResumeSource;
   /** Bounded re-read of the query at a current lsn. Omit only if a stale cursor should throw. */
   readonly snapshot?: (qid: string) => Promise<{ rows: readonly R[]; lsn: string }>;
@@ -104,7 +104,7 @@ export interface ResumeDeps<R extends Row = Row> {
 export function makeCursor(
   qid: string,
   lsn: string,
-  rows: readonly Row[],
+  rows: readonly LiveRow[],
   now: number,
 ): LiveCursor {
   return {
@@ -139,7 +139,7 @@ export function shouldResnapshot(
  * snapshot. There is deliberately no third path: WAL history traversal is what turns a rolling
  * restart into a self-inflicted outage.
  */
-export async function resumeFrom<R extends Row = Row>(
+export async function resumeFrom<R extends LiveRow = LiveRow>(
   cursor: LiveCursor,
   deps: ResumeDeps<R>,
 ): Promise<ResumeResult<R>> {

package/src/device-agent.ts

@@ -6,9 +6,9 @@ import { reportError } from '@ultimat3/core';
 import { bytesOverLimit, type DeviceInbound, decodeNodeFrame } from './device-wire';
 import type { JsonValue } from './json';
 import {
-  type BackoffPolicy,
   defaultBackoff,
   policyDelay,
+  type ReconnectBackoff,
   type Rng,
   type Scheduler,
   timeoutScheduler,
@@ -48,7 +48,7 @@ export interface DeviceAgentOptions {
   readonly onRequest: (frame: JsonValue) => Promise<JsonValue> | JsonValue;
   /** What `onFrame` on the node answered, and anything else it pushes. */
   readonly onFrame?: ((frame: JsonValue) => void) | undefined;
-  readonly backoff?: BackoffPolicy | undefined;
+  readonly backoff?: ReconnectBackoff | undefined;
   readonly rng?: Rng | undefined;
   readonly schedule?: Scheduler | undefined;
   readonly dial?: AgentDial | undefined;

package/src/device-errors.ts

@@ -21,7 +21,7 @@ export class DeviceOfflineError extends RealtimeError {
     super({
       code: 'X_DEVICE_OFFLINE',
       cause: `deviceSocket("${args.path}") holds no open socket for device ${JSON.stringify(args.deviceId)} under the caller's tenant: ${args.reason}`,
-      fix: `x doctor --json   # then retry deviceLink.request(ctx, '${idArg(args.deviceId)}', frame) once the device redials; across replicas realtime.transport must be 'nats'`,
+      fix: `x doctor --json   # then retry deviceLink.request(ctx, '${idArg(args.deviceId)}', frame) once the device redials; across replicas every role needs NATS_URL set (or one transport in apps/<app>/runtime.ts)`,
     });
   }
 }

package/src/device-socket.ts

@@ -123,7 +123,7 @@ export function beginDeviceSocketGeneration(): void {
   generation += 1;
 }
 
-/** Test seam: forget every declaration, the state a process boots in — `resetChannelTransport`'s twin. */
+/** Test seam: forget every declaration, the state a process boots in. */
 export function forgetDeviceSockets(): void {
   declared.clear();
 }

package/src/error-titles-server.ts

@@ -0,0 +1,40 @@
+// @ultimat3/realtime's SERVER-ONLY codes and their titles, registered at import: raised by the
+// replicator, the change feed and the node's boot, never by a page and never inside the frame
+// router that writes a refusal onto the wire. Kept out of `error-titles.ts`, which is in every
+// island chunk; imported bare by `errors.ts` and `server.ts`, and listed in `sideEffects`.
+
+import { registerErrorCodes } from '@ultimat3/core/page';
+
+/** Codes this package owns that no browser can raise or receive. */
+export const REALTIME_SERVER_OWNED_ERROR_CODES = [
+  'X_REPLICATION_PROTOCOL',
+  'X_REPLICATION_FAILED',
+  'X_REPLICATOR_SLOT_HELD',
+  'X_LIVE_REPLICA_IDENTITY',
+  'X_REALTIME_TOPOLOGY',
+  'X_REPLICATION_TLS',
+  'X_REALTIME_PRODUCER_CONFLICT',
+  'X_REPLICATION_SLOT_INVALIDATED',
+  'X_REPLICATION_SLOT_RECREATED',
+] as const;
+
+export type RealtimeServerErrorCode = (typeof REALTIME_SERVER_OWNED_ERROR_CODES)[number];
+
+export const REALTIME_SERVER_ERROR_TITLES: Readonly<Record<RealtimeServerErrorCode, string>> = {
+  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_REPLICA_IDENTITY: 'a replicated table has no replica identity',
+  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_REALTIME_PRODUCER_CONFLICT: 'two kinds of producer carry one table on the change bus',
+  X_REPLICATION_SLOT_INVALIDATED: 'the replication slot was invalidated',
+  X_REPLICATION_SLOT_RECREATED: 'the replication slot was recreated',
+};
+
+// One unconditional call, as in `error-titles.ts`: a second claimant throws X_ERROR_CODE_DUPLICATE.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(REALTIME_SERVER_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);

package/src/error-titles.ts

@@ -1,5 +1,6 @@
-// @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
+// @ultimat3/realtime's PAGE codes and their TITLES — every code a browser can raise or receive on
+// the wire — registered at import. Server-only codes are `error-titles-server.ts`. Listed in
+// `sideEffects`, 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
@@ -10,8 +11,8 @@
 // no realtime island reads (`page-errors-bundle.test.ts`). The registry is one module either way.
 import { registerErrorCodes } from '@ultimat3/core/page';
 
-/** Codes this package declares and owns. */
-export const REALTIME_OWNED_ERROR_CODES = [
+/** Codes this package owns that a page can raise or receive; the rest are `error-titles-server.ts`'s. */
+export const REALTIME_PAGE_OWNED_ERROR_CODES = [
   'X_TOPIC_FORBIDDEN',
   'X_SUBSCRIPTION_LIMIT',
   'X_SUBSCRIPTION_ID_TAKEN',
@@ -21,9 +22,6 @@ export const REALTIME_OWNED_ERROR_CODES = [
   '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',
@@ -36,24 +34,22 @@ export const REALTIME_OWNED_ERROR_CODES = [
   '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',
   'X_MUTATION_PATH_UNFILLED',
   'X_DEVICE_OFFLINE',
   'X_DEVICE_REQUEST_TIMEOUT',
   'X_DEVICE_FRAME_TOO_LARGE',
+  'X_CHANNEL_CATCHUP_POLICY_MISMATCH',
+  'X_OFFLINE_QUEUE_FULL',
 ] as const;
 
-export type RealtimeOwnedErrorCode = (typeof REALTIME_OWNED_ERROR_CODES)[number];
+export type RealtimePageErrorCode = (typeof REALTIME_PAGE_OWNED_ERROR_CODES)[number];
 
-export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, string>> = {
+export const REALTIME_PAGE_ERROR_TITLES: Readonly<Record<RealtimePageErrorCode, 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',
@@ -63,9 +59,6 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   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:
@@ -78,25 +71,23 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   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',
   X_MUTATION_PATH_UNFILLED: "a pinned action's :param had no value in the write's input",
   X_DEVICE_OFFLINE: 'no socket is open for the device a request addressed',
   X_DEVICE_REQUEST_TIMEOUT: 'a device did not answer a request before its deadline',
   X_DEVICE_FRAME_TOO_LARGE: 'a device socket frame is over the framework frame limit',
+  X_CHANNEL_CATCHUP_POLICY_MISMATCH: "a channel's catch-up read decides with another policy",
+  X_OFFLINE_QUEUE_FULL: 'the offline queue is full',
 };
 
 // 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 }]),
+    Object.entries(REALTIME_PAGE_ERROR_TITLES).map(([code, title]) => [code, { title }]),
   ),
 );

package/src/errors.ts

@@ -2,18 +2,48 @@
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
 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`.
+// The owned codes and their titles are two LISTED modules (`sideEffects`), imported bare here and
+// from the barrels: `error-titles.ts` (every code a page can raise or receive, in every island
+// chunk) and `error-titles-server.ts` (the replicator's, the feed's, the boot's). So this module is
+// side-effect-free and a chunk keeps only the classes it constructs; the union is re-exported.
 import './error-titles';
-import { REALTIME_OWNED_ERROR_CODES } from './error-titles';
+import './error-titles-server';
+import {
+  REALTIME_PAGE_ERROR_TITLES,
+  REALTIME_PAGE_OWNED_ERROR_CODES,
+  type RealtimePageErrorCode,
+} from './error-titles';
+import {
+  REALTIME_SERVER_ERROR_TITLES,
+  REALTIME_SERVER_OWNED_ERROR_CODES,
+  type RealtimeServerErrorCode,
+} from './error-titles-server';
 import { RealtimeError } from './realtime-error';
 
 export {
-  REALTIME_ERROR_TITLES,
-  REALTIME_OWNED_ERROR_CODES,
-  type RealtimeOwnedErrorCode,
+  REALTIME_PAGE_ERROR_TITLES,
+  REALTIME_PAGE_OWNED_ERROR_CODES,
+  type RealtimePageErrorCode,
 } from './error-titles';
+export {
+  REALTIME_SERVER_ERROR_TITLES,
+  REALTIME_SERVER_OWNED_ERROR_CODES,
+  type RealtimeServerErrorCode,
+} from './error-titles-server';
+
+/** Every code this package declares and owns: the page's and the server's. */
+export const REALTIME_OWNED_ERROR_CODES = [
+  ...REALTIME_PAGE_OWNED_ERROR_CODES,
+  ...REALTIME_SERVER_OWNED_ERROR_CODES,
+] as const;
+
+export type RealtimeOwnedErrorCode = RealtimePageErrorCode | RealtimeServerErrorCode;
+
+/** Every owned code's title. Composed, never declared here: a new code goes in one of the two. */
+export const REALTIME_ERROR_TITLES = Object.freeze<Record<RealtimeOwnedErrorCode, string>>({
+  ...REALTIME_PAGE_ERROR_TITLES,
+  ...REALTIME_SERVER_ERROR_TITLES,
+});
 
 /**
  * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s, and `X_FORBIDDEN` — thrown by the surface denials this
@@ -113,6 +143,7 @@ export {
   CursorStaleError,
   LocalStoreUnavailableError,
   OfflineQueueAbandonedError,
+  OfflineQueueFullError,
   ProtocolVersionError,
   RealtimeUninstalledError,
   RebaseConflictError,
@@ -130,6 +161,8 @@ export {
   ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
+  ReplicationSlotInvalidatedError,
+  ReplicationSlotRecreatedError,
   ReplicationTlsError,
   ReplicatorSlotHeldError,
 } from './replication-errors';
@@ -233,9 +266,9 @@ export class RealtimeTopologyError extends RealtimeError {
       code: 'X_REALTIME_TOPOLOGY',
       cause:
         'role sync runs on an external database over the in-process transport with no replicator in this process, so no committed change can reach it',
-      // Since 22.0.0 NATS_URL alone selects nothing: `realtime.transport` does, and a set NATS_URL
-      // under `'memory'` is refused, so the fix has to name both halves.
-      fix: "set realtime: { transport: 'nats', urlEnv: 'NATS_URL' } in app.config.ts and NATS_URL for every realtime role (web, sync, replicator), or run ROLE=sync with the replicator in one process: x dev --role sync,replicator",
+      // Since 31.0.0 the env is the bus (`selectTransport`): NATS_URL set is NATS. A bus of the
+      // app's own is `transport` in its runtime.ts — the line to paste, never a setter to call.
+      fix: 'set NATS_URL for every realtime role (web, sync, replicator) — or, for a bus of your own, add transport: myTransport to export const runtime = { … } in apps/<app>/runtime.ts — or run the replicator in this process: x dev --role sync,replicator',
     });
   }
 }

package/src/idb-types.ts

@@ -36,6 +36,12 @@ export interface IdbTransactionLike {
 
 export interface IdbDatabaseLike {
   readonly objectStoreNames: { contains(name: string): boolean };
+  /**
+   * Another tab asked for a NEWER version. Until every open connection closes, that tab's open is
+   * `blocked` — so a connection that ignores this holds every later schema off this origin.
+   */
+  onversionchange: (() => void) | null;
+  close(): void;
   createObjectStore(name: string): unknown;
   transaction(
     names: string | readonly string[],