@ultimat3/realtime 21.0.0 → 22.0.0

package/README.md

@@ -69,22 +69,53 @@ class — stay on `.`.
 
 | Concern | Entry | Export |
 |---|---|---|
-| tier 1 | `./server` | `topic`, `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
+| tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
 | tier 2 | `./server` | `LiveQueryRegistry`, `InMemoryChangeFeed`, `PgLogicalReplicationFeed`, `selectChangeFeed`, `createReplicator`, `PgAdvisoryLock`, `matcherFor` |
 | replication | `./server` | `parsePgUrl`, `bunPgStream`, `PgOutputDecoder`, `entityRow`, `changeLsn`, `commitPositionOf` |
+| the in-process change source | `./server` | `startLiveReplicator` — a repository's own writes as `ChangeEvent`s, for the embedded database `x dev` runs on (PGlite has no walsender). Moved from `@ultimat3/testing`, which no longer re-exports it |
 | fanout | `./server` | `Transport`, `InProcessTransport`, `NatsTransport`, `selectTransport`, `subjectMatches` |
 | the bus, behind `NatsTransport` | `./server` | the port — `NatsClient`, `NatsMessage`, `NatsSubscription`, `NatsConnect`, `NatsTarget`, `parseNatsUrl` — plus `openNatsClient` (the `nats` adapter), `NatsKvSet`, `ensureKvBucket`, `kvGet`/`kvLast`/`kvWrite`, `assertBucket`, `encodeToken`/`decodeToken`, and `FakeNatsBroker`/`fakeNatsConnect` for tests |
-| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `backoffDelay`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
+| reconnect | both | `LiveCursor`, `resumeFrom`, `shouldResnapshot`, `defaultReconnectBudget`, `Scheduler`, `timeoutScheduler` on `.`; `RingChangeBuffer`, `drainPlan`, `AcceptBudget`, `reconnectFrame` on `./server` — the node's half of the reconnect is the node's |
 | the page's record store | `.` | `RecordStore` — one record per `type:key`, synced truth plus the optimistic overlay — `recordKey`, `LocalTx`, `RowWindows`, `applyPatches`/`orderAfterPatches` |
 | the outbox | `.` | `OfflineQueue`, `MemoryQueueStore` — replayed over HTTP from plan 101 slice 12. The conflict vocabulary is `ConflictPolicy` from `@ultimat3/core`; realtime declares none |
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `createSyncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
 | hooks | `.` | `useQuery`, `useRecord`, `useMutation`, `useMutationQueue`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
-| channels | `.` | `channel`, `topic`, `readPresence`, the channel frame types |
+| channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
 | offline | `.` | `pageOutbox`, `recordPersister`, `persistedTypes`, `openLocalStore`, `pageLocalStore`, `MemoryLocalStore` |
 | the socket's worker | `./sync-worker` | the SharedWorker entry — no exports |
 
+## `channelRef` — a channel an island can hold
+
+A channel has two halves, and they live in two files so a browser chunk never bundles an entity or
+a policy. `channelRef(name, { params, catchUp })` is the **client** half: the name, the ordered
+params and the catch-up read — nothing else. The server declares the records and who may join on
+**the same ref** with `channel(ref, { … })`, so the name and the params are written once.
+
+```ts
+// app/posts/channel-ref.ts — imported by islands
+import { channelRef } from '@ultimat3/realtime';
+
+export const ORG_POSTS = channelRef('org-posts', {
+  params: ['orgId'],
+  catchUp: { name: 'orgPosts' },   // the query a client re-runs on `replay-gap` or a new epoch
+});
+
+// The one topic spelling both halves use.
+ORG_POSTS.topic({ orgId: 'org_1' });   // 'org-posts.org_1'
+```
+
+The server half, in its own file, names the entity and the policy on the same ref —
+`channel(ORG_POSTS, { records: [posts], policy: feedRead })` — and an island subscribes with
+`useChannel(ORG_POSTS, { orgId })`.
+
+`ref.topic(params)` is the one spelling of the topic both halves use (`org-posts.<orgId>`), and
+`bun run channel-literals` refuses a hand-built topic anywhere else. A bad name or a repeated param
+is `X_CHANNEL_DECLARATION_INVALID` at declaration. `catchUp` is read on every access, so a query
+whose name `registerQueries()` stamps at boot is picked up. The reference app's
+[`app/posts/channel-ref.ts`](../../examples/dummy/apps/web/app/posts/channel-ref.ts) is the idiom.
+
 ## The hooks
 
 One record store and one socket per **page**, on `globalThis`: every island is its own bundle, so a
@@ -288,7 +319,7 @@ sends a `reconnect` frame carrying that delay — clients redistribute instead o
 because refusing without one just moves the herd next door.
 
 The client dials itself back. A closed socket arms one timer — the node's delay when a `reconnect`
-frame assigned one, otherwise `backoffDelay()` — and that timer calls `connect()`, which re-subscribes
+frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `BackoffPolicy` — and that timer calls `connect()`, which re-subscribes
 every registration **and re-announces every topic**. Topic membership is state on the node's socket
 and `hello` carries none of it, so without that half a channel goes silent from the first reconnect
 onwards while its handler is still installed — and its presence membership is swept, because
@@ -337,7 +368,8 @@ wire twice by a reconnect that raced an ack.
 | Backpressure **declines**, it does not fail | over `MAX_BUFFERED_BYTES` (1 MiB, the node's `backpressureLimit` at the other end of the same socket) the sender throws `X_TRANSPORT_UNAVAILABLE`, the mutation stays pending and the next drain resumes there. `ClientSocket.bufferedAmount` is optional; a socket that does not report it is treated as never backed up |
 | Delivery is therefore at least once | every mutation carries an idempotency key — the `key` argument, or `<mutator>:<uuid>` — and the resend carries the same one |
 | A lost connection **cancels the pass it interrupted** | the lane orders passes against each other, but a socket death is not a pass and cannot reach one parked inside `send`. `requeueInflight()` bumps a connection epoch; a pass whose epoch went stale returns and leaves the rest `pending`. Without it the parked pass resumed and marked everything behind it `inflight` for a dead socket — never re-sent (`inflight` is not sendable) and never acked |
-| The store is handed a **snapshot**, never the live entries | `QueueStore.save` is a durable write and may await before it reads; given the array itself it persists a status that was never true when it was called |
+| The store is handed **snapshots, by key**, never the live entries or the whole queue | `QueueStore.write` is a durable write and may await before it reads; given an entry itself it persists a status that was never true when it was called. By key, because two tabs of one user share the store and a whole-queue save let the last tab erase the other's write |
+| One tab drains at a time, and drains what every tab queued | the outbox's replay runs under the Web Lock `ultimate-outbox:<principal>` and re-reads the queue first, so a write another tab queued is sent, in order, and a stored `inflight` from a closed page goes back to `pending` |
 
 ### Limits, stated plainly
 
@@ -491,11 +523,15 @@ wire twice by a reconnect that raced an ack.
   pg_try_advisory_lock(hashtext('x:replicator:<slot>'))` on its own session. Session-scoped, so a
   crashed replicator releases it automatically: no lease renewal, no fencing token, no split brain.
   `InMemoryAdvisoryLock` remains the single-process default for `x dev` and tests.
-- **`selectTransport(env)` decides which transport a boot fans out on** — the same law again, and
-  the only place that reads `NATS_URL`. It returns `{ transport, mode, detail, bucket,
-  presenceTtlMs, connect }`: unset → `InProcessTransport` and `mode: 'embedded'`, set → a
-  `NatsTransport` on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so two apps on one
-  cluster do not share one presence namespace), validated here rather than on first connect.
+- **`selectTransport(env, realtime)` decides which transport a boot fans out on** — and since
+  22.0.0 the CONFIG decides it, not the environment: `realtime` is `app.config.ts`'s
+  `{ transport, urlEnv }`. It returns `{ transport, mode, detail, bucket, presenceTtlMs, connect }`:
+  `'memory'` → `InProcessTransport` and `mode: 'embedded'`; `'nats'` → a `NatsTransport` dialling
+  the variable `urlEnv` names, on the KV bucket `NATS_KV_BUCKET` names (default `x_presence`, so
+  two apps on one cluster do not share one presence namespace), validated here rather than on
+  first connect. Both mismatches refuse with `X_CONFIG_INVALID`: `'nats'` with that variable unset,
+  and `'memory'` with `NATS_URL` (or the named variable) set — an operator who set one expected
+  fanout across nodes. Until 22.0.0 `NATS_URL` alone decided and both keys were read by nothing.
   `presenceTtlMs` comes back with it because the bucket's whole-stream age limit was derived from
   it — a `PresenceRegistry` given a different number would report members leaving that never left.
   Selection is pure; `connect()` is the dial, so an unreachable bus fails at boot.
@@ -548,8 +584,9 @@ wire twice by a reconnect that raced an ack.
 `X_NOT_IMPLEMENTED` and `X_TIMEOUT` are **borrowed** from `@ultimat3/core`, which owns and titles
 them — `REALTIME_BORROWED_ERROR_CODES`. Everything else on that list is realtime's own.
 
-Topics deny by default: a topic with no matching guard is forbidden. An authz hole is not a config
-option someone forgot to set.
+Topics deny by default: a topic no `channel()` declares is forbidden, and a `channel()` with no
+`policy` is refused at declaration (`X_CHANNEL_DECLARATION_INVALID`) — a public channel writes
+`policy: allow('public')`. An authz hole is not a config option someone forgot to set.
 
 An upgrade `authenticate` refuses is `X_SOCKET_UNAUTHENTICATED` (401) and one it *could not decide*
 is `X_SOCKET_AUTH_UNAVAILABLE` (503). Two codes, because the two have opposite instructions: the
@@ -568,3 +605,32 @@ The fix is `x queries list --json`, and the name the client sent is echoed back
 never is.
 
 `As of 2026-07`: tiers 1–2 target v1, tier 3 targets v2.
+
+### 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 |
+|---|---|---|
+| `CursorStaleError` (extends `RealtimeError`) | `X_CURSOR_STALE` | `src/page-errors.ts` |
+| `FrameRateLimitError` (extends `RealtimeError`) | `X_FRAME_RATE_LIMIT` | `src/errors.ts` |
+| `LiveQueryUnknownError` (extends `RealtimeError`) | `X_LIVE_QUERY_UNKNOWN` | `src/errors.ts` |
+| `LiveRowUnidentifiedError` (extends `RealtimeError`) | `X_LIVE_ROW_UNIDENTIFIED` | `src/errors.ts` |
+| `NotImplementedError` (extends `RealtimeError`) | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `ProtocolVersionError` (extends `RealtimeError`) | `X_PROTOCOL_VERSION` | `src/page-errors.ts` |
+| `RealtimeError` | any `RealtimeErrorCode` — `REALTIME_ERROR_CODES`; the base of every other class here, thrown directly for a code none of them covers | `src/realtime-error.ts` |
+| `RealtimeUninstalledError` (extends `RealtimeError`) | `X_REALTIME_UNINSTALLED` | `src/page-errors.ts` |
+| `RebaseConflictError` (extends `RealtimeError`) | `X_REBASE_CONFLICT` | `src/page-errors.ts` |
+| `RecordRejectedError` (extends `RealtimeError`) | `X_RECORD_REJECTED` | `src/page-errors.ts` |
+| `ReplicaIdentityError` (extends `RealtimeError`) | `X_LIVE_REPLICA_IDENTITY` | `src/replication-errors.ts` |
+| `ReplicationFailedError` (extends `RealtimeError`) | `X_REPLICATION_FAILED` | `src/replication-errors.ts` |
+| `ReplicationProtocolError` (extends `RealtimeError`) | `X_REPLICATION_PROTOCOL` | `src/replication-errors.ts` |
+| `ReplicatorSlotHeldError` (extends `RealtimeError`) | `X_REPLICATOR_SLOT_HELD` | `src/replication-errors.ts` |
+| `ServerRenderLiveError` (extends `RealtimeError`) | `X_LIVE_SERVER_RENDER` | `src/page-errors.ts` |
+| `SubscriptionLimitError` (extends `RealtimeError`) | `X_SUBSCRIPTION_LIMIT` | `src/errors.ts` |
+| `SyncUnconfiguredError` (extends `RealtimeError`) | `X_SYNC_UNCONFIGURED` | `src/page-errors.ts` |
+| `TopicForbiddenError` (extends `RealtimeError`) | `X_TOPIC_FORBIDDEN` | `src/errors.ts` |
+| `TransportProtocolError` (extends `RealtimeError`) | `X_TRANSPORT_PROTOCOL` | `src/errors.ts` |
+| `TransportUnavailableError` (extends `RealtimeError`) | `X_TRANSPORT_UNAVAILABLE` | `src/errors.ts` |
+| `WindowReadTimeoutError` (extends `RealtimeError`) | `X_TIMEOUT` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "21.0.0",
-    "@ultimat3/entity": "21.0.0",
-    "@ultimat3/query": "21.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/query": "22.0.0",
     "nats": "2.29.3"
   }
 }

package/src/changefeed.ts

@@ -11,7 +11,13 @@ import type { PgTarget } from './pg-socket';
 import type { PgStream } from './pg-wire';
 import type { Rng } from './thundering-herd';
 
-export type ChangeOp = 'insert' | 'update' | 'delete';
+/**
+ * `truncate` carries no row — `before` and `after` are both `null` — and means every row of the
+ * relation is gone. A window cannot be patched from it, only re-read; a channel's members are told
+ * to re-read (`replay-gap`). It was decoded and dropped, so with the recommended `FOR ALL TABLES`
+ * publication every window and every client kept the truncated rows forever.
+ */
+export type ChangeOp = 'insert' | 'update' | 'delete' | 'truncate';
 
 export interface ChangeEvent<R extends Row = Row> {
   /** Entity name, not table name — the matcher's dependency sets are declared in entity terms. */

package/src/channel-authz.ts

@@ -2,7 +2,7 @@
 // the channel's own loader answered. Through `@ultimat3/query`'s `guard`, the package's one authz
 // seam — the same call `policy-gate.ts` makes for a live query.
 
-import type { Actor, Ctx } from '@ultimat3/core';
+import { type Actor, type Ctx, createContext, runWithContext } from '@ultimat3/core';
 import { guard, QueryDeniedError } from '@ultimat3/query';
 import type { Channel } from './channel-decl';
 import { TopicForbiddenError } from './errors';
@@ -18,10 +18,17 @@ export async function authorizeChannel(
   topic: string,
   params: Readonly<Record<string, string>>,
 ): Promise<void> {
-  if (channel.policy === undefined) return;
-  const row = channel.row === undefined ? null : await channel.row({ params, ctx });
+  // The loader and the rule run AS the subscriber, never as the node. Under the node's context — no
+  // actor, no tenant — a repository read inside the loader was scoped by nothing but what the
+  // loader happened to name, and `@ultimat3/entity`'s tenancy seam had no actor to hold it to.
+  // Services are rebuilt for this actor by `createContext`, the rule `withChildContext` follows.
+  const scoped = actor === null ? ctx : subscriberContext(ctx, actor);
+  const row =
+    channel.row === undefined
+      ? null
+      : await runWithContext(scoped, async () => await channel.row?.({ params, ctx: scoped }));
   try {
-    guard(channel.policy, { actor, input: params, row, ctx, query: channel.name }, 'live');
+    guard(channel.policy, { actor, input: params, row, ctx: scoped, query: channel.name }, 'live');
   } catch (error) {
     if (!(error instanceof QueryDeniedError)) throw error;
     throw new TopicForbiddenError({
@@ -31,3 +38,15 @@ export async function authorizeChannel(
     });
   }
 }
+
+/** The node's context, re-made for one subscriber: same deploy, role and clock, their actor. */
+function subscriberContext(node: Ctx, actor: Actor): Ctx {
+  return createContext({
+    actor,
+    role: node.role,
+    buildId: node.buildId,
+    clock: node.clock,
+    locale: node.locale,
+    tz: node.tz,
+  });
+}

package/src/channel-decl.ts

@@ -43,10 +43,12 @@ function projectionFor(name: string, entity: ChannelEntity): RecordProjection {
 export interface ChannelServerInit {
   /**
    * Evaluated on subscribe: the params are the input, and `row` is what the loader below answered
-   * (`null` without one). Omitted = any socket may join. Records are NOT gated per row — the topic's
+   * (`null` without one). REQUIRED, as on an `action` and a `query`: it was optional, and an omitted
+   * one let any socket — anonymous included — join with any param and receive every committed row.
+   * A public channel says so with `allow('public')`. Records are NOT gated per row — the topic's
    * params are the scope, so a channel that must hide rows is declared narrower.
    */
-  readonly policy?: QueryPolicy;
+  readonly policy: QueryPolicy;
   /**
    * The subject the policy decides about, loaded by the SURFACE before the rule runs — the same
    * split an action's `row:` makes, because a rule is synchronous and membership is a read.
@@ -69,7 +71,7 @@ export interface Channel<K extends string = string> {
   readonly kind: 'channel';
   readonly name: string;
   readonly params: readonly K[];
-  readonly policy: QueryPolicy | undefined;
+  readonly policy: QueryPolicy;
   readonly row: ChannelRowLoader | undefined;
   readonly catchUp: string;
   readonly records: readonly RecordProjection[];
@@ -87,7 +89,7 @@ export interface Channel<K extends string = string> {
  * Registers the declaration (`channel-registry.ts`) — a second one of the same name is refused.
  *
  * The params-matching rule, decided here once: a row belongs to the topic whose params equal the
- * row's own properties of those names. So `channel('org-feed', { params: ['orgId'], records:
+ * row's own properties of those names. So `channel('org-feed', { params: ['orgId'], policy, records:
  * [posts] })` carries every `posts` row on `org-feed.<row.orgId>`, and every listed entity must have
  * a column named after every param — refused at declaration, where the author is.
  */
@@ -103,6 +105,15 @@ export function channel<K extends string>(
   const ref =
     typeof nameOrRef === 'string' ? channelRef(nameOrRef, init as ChannelInit<K>) : nameOrRef;
   const name = ref.name;
+  // The type requires it; this is the refusal a JS caller, or a cast, reaches.
+  const policy = (init as Partial<ChannelServerInit>).policy;
+  if (policy === undefined) {
+    refuseChannel(
+      name,
+      'declares no policy, so any socket, anonymous included, could join and receive every row',
+      "add policy: can('<resource>:read') to the channel() call, or policy: allow('public') for a channel anyone may join",
+    );
+  }
   const records = (init.records ?? []).map((entity) => {
     const projection = projectionFor(name, entity);
     for (const param of ref.params) {
@@ -121,7 +132,7 @@ export function channel<K extends string>(
     kind: 'channel' as const,
     name,
     params: ref.params,
-    policy: init.policy,
+    policy,
     row: init.row,
     get catchUp(): string {
       return ref.catchUp;

package/src/channel-describe.ts

@@ -13,8 +13,11 @@ export interface ChannelDescription {
   /** Record types (entity names) the channel carries, sorted. */
   readonly records: readonly string[];
   readonly events: boolean;
-  /** The policy's display label, `null` for a channel any socket may join. */
-  readonly policy: string | null;
+  /**
+   * The policy's display label. Never absent since 22.0.0 — `channel()` requires a policy, and a
+   * channel any socket may join reads `allow('public')`'s label, said out loud.
+   */
+  readonly policy: string;
   /** Every permission the policy asserts, flattened — what a report matches a grant against. */
   readonly permissions: readonly string[];
 }
@@ -26,8 +29,7 @@ export function describeChannels(): readonly ChannelDescription[] {
     catchUp: declared.catchUp,
     records: declared.records.map((projection) => projection.type).sort(),
     events: declared.events,
-    policy: declared.policy === undefined ? null : policyCapability(declared.policy),
-    permissions:
-      declared.policy === undefined ? [] : [...policyPermissions(declared.policy)].sort(),
+    policy: policyCapability(declared.policy),
+    permissions: [...policyPermissions(declared.policy)].sort(),
   }));
 }

package/src/channel-logs.ts

@@ -5,7 +5,7 @@
 import { logger, renderThrowable, uuid } from '@ultimat3/core';
 import type { ChangeEvent } from './changefeed';
 import type { Channel } from './channel-decl';
-import { updatesFor } from './channel-records';
+import { carriesTable, updatesFor } from './channel-records';
 import { renderRecords } from './channel-render';
 import { ChannelRing } from './channel-ring';
 import type { ChannelSince, ReplayGapFrame } from './channel-wire';
@@ -59,6 +59,7 @@ export class ChannelLogs {
    * the change is somebody else's too, and one malformed image must not stop the rest.
    */
   deliverChange(channels: Iterable<Channel>, change: ChangeEvent): number {
+    if (change.op === 'truncate') return this.#truncated(change.entity);
     let frames = 0;
     let updates: ReturnType<typeof updatesFor>;
     try {
@@ -80,6 +81,23 @@ export class ChannelLogs {
     return frames;
   }
 
+  /**
+   * Every row of `table` is gone, and no frame can say which ones a member holds. Each open topic
+   * of a channel carrying it starts a NEW epoch — nothing in the old ring may be replayed onto a
+   * table that no longer has those rows — and every member is told `replay-gap` at it, which the
+   * client answers by re-running the channel's catch-up read.
+   */
+  #truncated(table: string): number {
+    let announced = 0;
+    for (const [topic, open] of [...this.#byTopic]) {
+      if (!carriesTable(open.target.channel, table)) continue;
+      this.#byTopic.delete(topic);
+      const ring = this.open(topic, open.target);
+      announced += this.#sockets.announceGap(topic, ring.epoch);
+    }
+    return announced;
+  }
+
   /**
    * A (re)subscribe `since` a position: every frame after it from the ring, or — when the ring
    * cannot prove it holds them all, or the epoch moved — one `replay-gap`.

package/src/channel-records.ts

@@ -29,6 +29,9 @@ export interface TopicUpdate {
  */
 export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): TopicUpdate[] {
   const updates: TopicUpdate[] = [];
+  // A truncate names no row, so it routes to no topic here: `ChannelLogs` announces a gap on every
+  // open topic of every channel carrying the relation instead (`truncatedTopics`).
+  if (change.op === 'truncate') return updates;
   for (const channel of channels) {
     const projection = channel.records.find((candidate) => candidate.table === change.entity);
     if (projection === undefined) continue;
@@ -77,3 +80,8 @@ function removal(
     row,
   };
 }
+
+/** The channels whose records a truncate of `table` wiped: every one listing that relation. */
+export function carriesTable(channel: Channel, table: string): boolean {
+  return channel.records.some((projection) => projection.table === table);
+}

package/src/client-channels.ts

@@ -38,6 +38,11 @@ export interface ChannelBookDeps {
   /** Re-run the channel's catch-up read; its records land in the store through the transport. */
   catchUp(query: string, params: Readonly<Record<string, string>>): Promise<unknown>;
   report(error: unknown): void;
+  /**
+   * When a failed catch-up tries again on its own, on the client's reconnect curve. Absent, a
+   * failed read waits for the next open of the socket or the next gap.
+   */
+  readonly retry?: ((attempt: number, run: () => void) => () => void) | undefined;
 }
 
 interface Entry {
@@ -57,6 +62,17 @@ interface Entry {
   readonly above: Set<number>;
   /** Frames that arrived while the catch-up read was in flight, applied after it lands. */
   buffered: ChannelRecordsFrame[] | null;
+  /**
+   * A gap announced while a read was in flight: one more read follows it, in this epoch (or the
+   * current one when the gap named none). A flag, never a count — the `coalesceReloads` shape.
+   */
+  again: { readonly epoch: string | undefined } | null;
+  /** The read is not in flight: it failed, and waits for a retry with `buffered` still held. */
+  waiting: boolean;
+  /** Consecutive failed reads — the retry curve's attempt number. */
+  failures: number;
+  /** Disarms the scheduled retry. */
+  disarm: (() => void) | null;
 }
 
 export interface ChannelMembership extends Disposable {
@@ -97,6 +113,10 @@ export class ChannelBook {
         contiguous: null,
         above: new Set(),
         buffered: null,
+        again: null,
+        waiting: false,
+        failures: 0,
+        disarm: null,
       };
       this.#byTopic.set(topic, entry);
       if (this.#deps.connected()) this.#deps.send(this.#frame(entry, 'add', true));
@@ -110,6 +130,8 @@ export class ChannelBook {
       held.holders.delete(handlers);
       if (held.holders.size > 0) return;
       this.#byTopic.delete(topic);
+      held.disarm?.();
+      held.disarm = null;
       this.#deps.send(this.#frame(held, 'drop', false));
     };
     return {
@@ -130,6 +152,12 @@ export class ChannelBook {
   /** Every membership again, on a new socket — resuming from each cursor. */
   resubscribe(): void {
     for (const entry of this.#byTopic.values()) {
+      // A catch-up that failed retries on the new socket: the read is what it was waiting for.
+      if (entry.waiting) {
+        this.#deps.send(this.#frame(entry, 'add', true));
+        this.#read(entry);
+        continue;
+      }
       this.#set(entry, 'joining');
       this.#deps.send(this.#frame(entry, 'add', true));
     }
@@ -225,32 +253,74 @@ export class ChannelBook {
   /**
    * Re-read the channel through its catch-up query, holding every frame that arrives meanwhile;
    * then apply those, in order, over the read. The cursor restarts in the new epoch.
+   *
+   * A gap that lands DURING the read is not dropped: it earns one more read after this one (it
+   * was ignored, and the hole it announced was never repaired).
    */
   #catchUp(entry: Entry, pending: ChannelRecordsFrame[], epoch?: string): void {
     if (entry.buffered !== null) {
       entry.buffered.push(...pending);
+      if (pending.length === 0) entry.again = { epoch: epoch ?? entry.again?.epoch };
+      // No read in flight — the last one failed — so this gap is the retry, now.
+      if (entry.waiting) this.#read(entry);
       return;
     }
     entry.buffered = [...pending];
-    entry.epoch = epoch ?? pending[0]?.epoch ?? entry.epoch;
+    this.#restart(entry, epoch ?? pending[0]?.epoch ?? entry.epoch);
+    this.#read(entry);
+  }
+
+  /** The cursor, reset into `epoch`: every seq before the read is the read's to answer. */
+  #restart(entry: Entry, epoch: string | null): void {
+    entry.epoch = epoch;
     entry.contiguous = null;
     entry.above.clear();
+  }
+
+  #read(entry: Entry): void {
+    entry.waiting = false;
+    entry.error = undefined;
+    entry.disarm?.();
+    entry.disarm = null;
     this.#set(entry, 'catching-up');
     this.#deps.catchUp(entry.catchUp, entry.params).then(
       () => this.#drain(entry),
       (error: unknown) => {
         this.#deps.report(error);
-        this.#drain(entry);
+        // NOT live: the frames held behind the read would land over a store it never refreshed.
+        // Failed, the error exposed, and the frames still held for the retry — which the next
+        // open of the socket runs (`resubscribe`), or the next gap.
+        entry.waiting = true;
+        entry.error = error;
+        entry.failures += 1;
+        if (this.#byTopic.get(entry.topic) !== entry) return;
+        this.#set(entry, 'failed');
+        entry.disarm =
+          this.#deps.retry?.(entry.failures, () => {
+            entry.disarm = null;
+            if (entry.waiting && this.#byTopic.get(entry.topic) === entry) this.#read(entry);
+          }) ?? null;
       },
     );
   }
 
   #drain(entry: Entry): void {
     const held = entry.buffered ?? [];
+    // A newer epoch arrived while the read was in flight (the node restarted mid-read): the read
+    // answered for the OLD one, so it is re-read in the new one, keeping only that epoch's frames.
+    // `#drain` used to discard them, and the rows they carried with them.
+    const newer = held.find((frame) => frame.epoch !== entry.epoch);
+    if (entry.again !== null || newer !== undefined) {
+      const epoch = newer?.epoch ?? entry.again?.epoch ?? entry.epoch;
+      entry.again = null;
+      entry.buffered = held.filter((frame) => frame.epoch === epoch);
+      this.#restart(entry, epoch);
+      this.#read(entry);
+      return;
+    }
     entry.buffered = null;
-    // Frames of an epoch other than the one caught up to predate it; the read already holds them.
-    const current = held.filter((frame) => frame.epoch === entry.epoch);
-    current.sort((a, b) => a.seq - b.seq);
+    entry.failures = 0;
+    const current = [...held].sort((a, b) => a.seq - b.seq);
     for (const frame of current) {
       if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
       this.#apply(entry, frame);

package/src/client.ts

@@ -19,7 +19,7 @@ import type { JsonObject, JsonValue } from './json';
 import { type LiveState, type Registration, RowWindows, unnamedType } from './live-rows';
 import { RecordStore } from './record-store';
 import { decode, encode, type Frame, PROTOCOL_VERSION } from './sync-protocol';
-import { backoffDelay, browserBackoff, timeoutScheduler } from './thundering-herd';
+import { browserBackoff, policyDelay, timeoutScheduler } from './thundering-herd';
 
 export type {
   ClientSocket,
@@ -78,6 +78,17 @@ export class LiveClient {
       connected: () => this.#connected,
       catchUp: options.catchUp,
       report: (error) => this.#onError(error),
+      // A failed catch-up retries on the reconnect curve this client already dials on.
+      retry: (attempt, run) =>
+        (this.#options.scheduler ?? timeoutScheduler)(
+          run,
+          // `attempt` is the book's failure count, 1 on the first failure: core's count as is.
+          policyDelay(
+            this.#options.backoff ?? browserBackoff,
+            attempt,
+            this.#options.rng ?? Math.random,
+          ),
+        ),
     });
     this.#heartbeat = new Heartbeat({
       intervalMs: finiteOption(
@@ -369,7 +380,8 @@ export class LiveClient {
     this.#cancelReconnect();
     const rng = this.#options.rng ?? Math.random;
     const delay =
-      serverDelayMs ?? backoffDelay(this.#attempt, this.#options.backoff ?? browserBackoff, rng);
+      // `#attempt` counts reconnects already scheduled, from 0; the wait being armed is the next one.
+      serverDelayMs ?? policyDelay(this.#options.backoff ?? browserBackoff, this.#attempt + 1, rng);
     this.#attempt += 1;
     this.#setStatus({ reconnectAt: this.#clock.now().getTime() + delay });
     const schedule = this.#options.scheduler ?? timeoutScheduler;

package/src/cursor.ts

@@ -161,6 +161,11 @@ export function advance(
   lsn: string,
   now: number,
 ): LiveCursor {
+  // An update moves no id in or out, and it is the common change: the ids are reused as they are,
+  // so a fan-out to N subscribers of a W-row window is not N rebuilds of a W-id set per change.
+  if (!patches.some((patch) => patch.op !== 'update')) {
+    return { qid: cursor.qid, lsn, ids: cursor.ids, at: now };
+  }
   const ids = new Set(cursor.ids);
   for (const patch of patches) {
     if (patch.op === 'delete') ids.delete(patch.id);

package/src/errors.ts

@@ -33,6 +33,7 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_LIVE_REPLICA_IDENTITY',
   'X_SOCKET_UNAUTHENTICATED',
   'X_SOCKET_AUTH_UNAVAILABLE',
+  'X_REALTIME_TOPOLOGY',
 ] as const;
 
 /**
@@ -140,6 +141,7 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
   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',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws
@@ -255,6 +257,25 @@ export class TransportUnavailableError extends RealtimeError {
   }
 }
 
+/**
+ * A `sync` node that can hear no change: a real database, the in-process bus, and no replicator in
+ * this process. A replicator in another process publishes into ITS in-process bus, so every live
+ * query and channel here is silent, with no error on either side. Refused at boot, where the
+ * topology is known, rather than discovered as a live feature that never updates.
+ */
+export class RealtimeTopologyError extends RealtimeError {
+  constructor() {
+    super({
+      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",
+    });
+  }
+}
+
 /**
  * The bytes on the bus socket are not the protocol we speak: an unknown NATS verb, a header block
  * that is not `NATS/1.0`, a JetStream reply in a shape the API never produces. Always a version or