@ultimat3/realtime 24.0.0 → 25.0.0

package/src/changefeed.ts

@@ -20,8 +20,13 @@ import type { Rng } from './thundering-herd';
 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. */
-  readonly entity: string;
+  /**
+   * 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
+   * `recordPublisher` sends `projection.table`. A channel matches `projection.table`, a live shape
+   * is `from('<table>', …)`; the record TYPE (entity name) is derived from it (`recordTypeForTable`).
+   */
+  readonly table: string;
   readonly op: ChangeOp;
   readonly before: R | null;
   readonly after: R | null;
@@ -34,11 +39,13 @@ export interface ChangeEvent<R extends Row = Row> {
   readonly at: number;
   /**
    * The write that made this change: `writeDigest` of the idempotency key its request carried
-   * (`@ultimat3/core`). Absent for a change no keyed request made. Read off the WAL message the
-   * Postgres driver writes first in the transaction, or off the request scope in-process; a
-   * channel stamps it on the `records` frame so the writing page recognises its own echo.
+   * (`@ultimat3/core`). `null` for a change no keyed request made — a job, a script, raw SQL. Read
+   * off the WAL message the Postgres driver writes first in the transaction, or off the request
+   * scope in-process; a channel stamps it on its `records` frame and a live query on its `patch`
+   * frame, so the writing page settles its own echo in the same batch. REQUIRED, never optional:
+   * a producer that forgets it is a type error, not a page that paints truth plus overlay.
    */
-  readonly write?: string;
+  readonly write: string | null;
   /**
    * Row properties `after` does NOT carry because Postgres did not log them: an UPDATE that left
    * an out-of-line (TOAST) value untouched sends no bytes for it, and under any replica identity
@@ -86,7 +93,7 @@ export function parseLsn(pgLsn: string): string {
   return formatLsn((BigInt(`0x${high}`) << 32n) | BigInt(`0x${low}`));
 }
 
-export interface InMemoryChangeFeedOptions {
+export interface MemoryChangeFeedOptions {
   /** Retained events, so a `start({ from })` inside the window replays instead of skipping. */
   readonly retain?: number;
 }
@@ -96,7 +103,7 @@ export interface InMemoryChangeFeedOptions {
  * ordering is the guarantee the whole pipeline is built on, so it is enforced here rather than
  * assumed downstream.
  */
-export class InMemoryChangeFeed implements ChangeFeed {
+export class MemoryChangeFeed implements ChangeFeed {
   readonly source = 'in-memory';
   readonly #retained: ChangeEvent[] = [];
   readonly #retain: number;
@@ -105,7 +112,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
   #position = 0n;
   #lastLsn: string | null = null;
 
-  constructor(options: InMemoryChangeFeedOptions = {}) {
+  constructor(options: MemoryChangeFeedOptions = {}) {
     this.#retain = finiteOption('the change feed', 'retain', options.retain ?? 1024);
   }
 
@@ -142,13 +149,19 @@ export class InMemoryChangeFeed implements ChangeFeed {
 
   /** Ergonomic emit: assigns the next lsn and txid so tests read as domain events. */
   async push(
-    entity: string,
+    table: string,
     op: ChangeOp,
-    rows: { before?: Row | null; after?: Row | null; orgId?: string | null; at?: number },
+    rows: {
+      before?: Row | null;
+      after?: Row | null;
+      orgId?: string | null;
+      at?: number;
+      write?: string | null;
+    },
   ): Promise<ChangeEvent> {
     this.#position += 1n;
     const event: ChangeEvent = {
-      entity,
+      table,
       op,
       before: rows.before ?? null,
       after: rows.after ?? null,
@@ -156,6 +169,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
       txid: this.#position.toString(10),
       orgId: rows.orgId ?? null,
       at: rows.at ?? 0,
+      write: rows.write ?? null,
     };
     await this.emit(event);
     return event;
@@ -171,7 +185,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
     // The lane chains on a SETTLED shadow, never on `result` — `window-lock.ts` solves the same
     // problem the same way. Chained on the live tail, one rejected link poisoned every link behind
     // it: later changes rejected with the FIRST error, the handler was never called again and
-    // `lastLsn()` froze. Reachable on any single-node deployment, because `createReplicator`'s
+    // `lastLsn()` froze. Reachable on any single-node deployment, because `changeFeedReplicator`'s
     // `onChange` awaits `transport.publish(...)` and a closed `InProcessTransport` refuses — one
     // transient publish failure ended change delivery for the life of the process. The rejection
     // still reaches the caller that pushed THAT event, and only it; `stop()` awaits the shadow, so
@@ -181,10 +195,15 @@ export class InMemoryChangeFeed implements ChangeFeed {
   }
 }
 
+/** The one way to build the in-process feed — the twin of `postgresChangeFeed()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function memoryChangeFeed(options: MemoryChangeFeedOptions = {}): MemoryChangeFeed {
+  return new MemoryChangeFeed(options);
+}
+
 /** Settles the shadow lane whichever way the delivery went. Nothing observes the value. */
 const ignore = (): void => undefined;
 
-export interface PgLogicalReplicationOptions {
+export interface PostgresChangeFeedOptions {
   /** Connection string for a role with REPLICATION: `postgres://user:pass@host:5432/db`. */
   readonly url: string;
   /** Replication slot name. Exactly one `replicator` process may hold it. */
@@ -210,19 +229,19 @@ export interface PgLogicalReplicationOptions {
 /**
  * The production feed: `pgoutput` decoding off a logical replication slot. Everything about *how*
  * lives in `pg-replication.ts`; what this class adds is the `ChangeFeed` contract the matcher, the
- * replicator and the fanout are written against — so swapping it for `InMemoryChangeFeed` in `x dev`
+ * replicator and the fanout are written against — so swapping it for `MemoryChangeFeed` in `x dev`
  * changes nothing downstream.
  */
-export class PgLogicalReplicationFeed implements ChangeFeed {
+export class PostgresChangeFeed implements ChangeFeed {
   readonly source = 'pg-logical-replication';
   readonly #stream: PgReplicationStream;
 
-  constructor(options: PgLogicalReplicationOptions) {
+  constructor(options: PostgresChangeFeedOptions) {
     if (options.entities.length === 0) {
       throw new ReplicationFailedError({
         stage: 'preflight',
         detail: 'the feed was given an empty entity list, so no change could ever match',
-        fix: 'pass the entities the publication covers: new PgLogicalReplicationFeed({ entities: [...] })',
+        fix: 'pass the entities the publication covers: postgresChangeFeed({ entities: [...] })',
       });
     }
     this.#stream = new PgReplicationStream(options);
@@ -253,3 +272,8 @@ export class PgLogicalReplicationFeed implements ChangeFeed {
     return this.#stream.stats();
   }
 }
+
+/** The one way to build the WAL-backed feed — the twin of `memoryChangeFeed()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function postgresChangeFeed(options: PostgresChangeFeedOptions): PostgresChangeFeed {
+  return new PostgresChangeFeed(options);
+}

package/src/channel-authz.ts

@@ -1,9 +1,9 @@
 // A declared channel's policy, asked on subscribe: the params are the input and the row is what
-// 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.
+// the channel's own loader answered. Through `@ultimat3/query`'s `guardQuery`, the package's one
+// authz seam — the same call `policy-gate.ts` makes for a live query.
 
-import { type Actor, type Ctx, createContext, runWithContext } from '@ultimat3/core';
-import { guard, QueryDeniedError } from '@ultimat3/query';
+import { type Actor, type Ctx, ctxOf, runWithContext } from '@ultimat3/core';
+import { guardQuery, QueryDeniedError } from '@ultimat3/query';
 import type { Channel } from './channel-decl';
 import { isTenancyDenial, TopicForbiddenError } from './errors';
 
@@ -34,7 +34,7 @@ export async function authorizeChannel(
     });
   }
   // The loader and the rule run AS the subscriber, never as the node. Services are rebuilt for
-  // this actor by `createContext`, the rule `withChildContext` follows.
+  // this actor by `ctxOf`, the rule `withChildContext` follows.
   const scoped = subscriberContext(ctx, actor);
   let row: unknown;
   try {
@@ -59,7 +59,7 @@ function decide(
   row: unknown,
 ): void {
   try {
-    guard(channel.policy, { actor, input: params, row, ctx, query: channel.name }, 'live');
+    guardQuery(channel.policy, { actor, input: params, row, ctx, query: channel.name }, 'live');
   } catch (error) {
     if (!(error instanceof QueryDeniedError)) throw error;
     throw new TopicForbiddenError({
@@ -72,7 +72,7 @@ function decide(
 
 /** 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({
+  return ctxOf({
     actor,
     role: node.role,
     buildId: node.buildId,

package/src/channel-describe.ts

@@ -2,7 +2,7 @@
 // flattened the way a query's is. Server-side on purpose — the policy flattening is
 // `@ultimat3/query`'s, and a browser island declaring a channel must not bundle it.
 
-import { policyCapability, policyPermissions } from '@ultimat3/query';
+import { policyCapability, policyPermissions } from '@ultimat3/policy';
 import { registeredChannels } from './channel-registry';
 
 export interface ChannelDescription {

package/src/channel-logs.ts

@@ -2,7 +2,7 @@
 // the change → frame path, and the resume a resubscribe `since` asks for. One per `ChannelHub`.
 // Records never cross the bus — each node reads every change itself — so seq is minted here.
 
-import { logger, renderThrowable, uuid } from '@ultimat3/core';
+import { logger, renderThrowable, uuidV7 } from '@ultimat3/core';
 import type { ChangeEvent } from './changefeed';
 import type { Channel } from './channel-decl';
 import { carriesTable, updatesFor } from './channel-records';
@@ -22,7 +22,7 @@ export class ChannelLogs {
   readonly #sockets: SocketRegistry;
   readonly #ringSize: number | undefined;
   /** This hub's mark on every epoch it mints: a restarted node can never reuse one. */
-  readonly #hubId = uuid();
+  readonly #hubId = uuidV7();
   #rings = 0;
   readonly #byTopic = new Map<
     string,
@@ -59,14 +59,14 @@ 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);
+    if (change.op === 'truncate') return this.invalidate(change.table);
     let frames = 0;
     let updates: ReturnType<typeof updatesFor>;
     try {
       updates = updatesFor(channels, change);
     } catch (error) {
       logger.warn('channel.records_unkeyed', {
-        table: change.entity,
+        table: change.table,
         error: renderThrowable(error),
       });
       return 0;
@@ -79,7 +79,7 @@ export class ChannelLogs {
         frames += this.#reopen(update.topic, open.target);
         continue;
       }
-      const entry = open.ring.append(update.adopt, update.remove, change.write);
+      const entry = open.ring.append(update.adopt, update.remove, change.write ?? undefined);
       const frame = renderRecords(update.topic, open.ring.epoch, entry);
       frames += this.#sockets.deliverRecords(update.topic, open.ring.epoch, frame);
     }
@@ -87,30 +87,21 @@ export class ChannelLogs {
   }
 
   /**
-   * 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;
-      announced += this.#reopen(topic, open.target);
-    }
-    return announced;
-  }
-
-  /**
-   * This node may have missed a change (the bus dropped, or skipped a sequence). Seq is minted
-   * HERE from the changes this node sees, so the hole is invisible to the ring: the next change
-   * would be appended as the next seq and a `since` replayed across it as complete history. Every
-   * open topic that carries records therefore starts a new epoch and tells its members.
+   * This node may have missed a change, and seq is minted HERE from the changes it sees, so the
+   * hole is invisible to the ring: the next change would be appended as the next seq and a
+   * `since` replayed across it as complete history. Every open topic that carries records — or,
+   * given a `table`, every one carrying THAT table — starts a new epoch and tells its members
+   * `replay-gap`, which the client answers by re-running the channel's catch-up read.
+   *
+   * With a table, three callers: a gap on the bus (none), a truncate (every row of it is gone, and
+   * no frame can say which ones a member holds), and a bulk write the in-process replicator saw
+   * as a fact rather than as rows (`live-replicator.ts`).
    */
-  invalidate(): number {
+  invalidate(table?: string): number {
     let announced = 0;
     for (const [topic, open] of [...this.#byTopic]) {
       if (open.target.channel.records.length === 0) continue;
+      if (table !== undefined && !carriesTable(open.target.channel, table)) continue;
       announced += this.#reopen(topic, open.target);
     }
     return announced;

package/src/channel-presence.ts

@@ -2,7 +2,7 @@
 // `events: true` joins its presence set, and a roster change is one `events` frame on that topic.
 // Browser-safe — the client reads the same shape back out with `readPresence`.
 
-import { isJsonObject, type JsonObject } from './json';
+import { isParsedJsonObject, type JsonObject } from './json';
 import { FRAME_LIMITS, type PresenceMember } from './sync-protocol';
 
 export type PresenceOp = 'join' | 'leave' | 'update' | 'sync';
@@ -60,9 +60,9 @@ export function readPresence(event: JsonObject): PresenceEvent | null {
 }
 
 function memberOf(value: unknown): PresenceMember | null {
-  if (!isJsonObject(value)) return null;
+  if (!isParsedJsonObject(value)) return null;
   const { id, actorId, meta, updatedAt } = value;
   if (typeof id !== 'string' || typeof updatedAt !== 'number') return null;
   if (actorId !== null && typeof actorId !== 'string') return null;
-  return { id, actorId, meta: isJsonObject(meta) ? meta : {}, updatedAt };
+  return { id, actorId, meta: isParsedJsonObject(meta) ? meta : {}, updatedAt };
 }

package/src/channel-records.ts

@@ -37,7 +37,7 @@ export function skippedRemovals(): number {
 }
 
 /**
- * `change.entity` is the replicated RELATION name (`pg-replication.ts` reads it off the Relation
+ * `change.table` is the replicated RELATION name (`pg-replication.ts` reads it off the Relation
  * message), so it is matched against each projection's `table`, never its `type`.
  *
  * - insert/update: the new row is adopted on the topic its params name.
@@ -53,7 +53,7 @@ export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): To
   // 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);
+    const projection = channel.records.find((candidate) => candidate.table === change.table);
     if (projection === undefined) continue;
     const after = change.op === 'delete' ? null : change.after;
     const before = change.before;
@@ -62,7 +62,7 @@ export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): To
     if (before !== null && beforeParams === null && channel.params.length > 0) {
       skipped += 1;
       removalsSkipped.add(1);
-      logger.warn('channel.removal_skipped', { channel: channel.name, table: change.entity });
+      logger.warn('channel.removal_skipped', { channel: channel.name, table: change.table });
     }
     const afterTopic = afterParams === null ? null : channel.topic(afterParams);
     const beforeTopic = beforeParams === null ? null : channel.topic(beforeParams);

package/src/channel-ref.ts

@@ -3,7 +3,7 @@
 // records and policy with `channel(ref, { … })`, so name and params are written once and a browser
 // chunk never carries `@ultimat3/entity`.
 
-import { invariant } from '@ultimat3/core/page';
+import { assertCoded } from '@ultimat3/core/page';
 import { TopicForbiddenError } from './errors';
 
 /** Branded so a raw string can never be published to; `topic()` is the only constructor. */
@@ -49,7 +49,7 @@ export interface ChannelHandle<K extends string = string> {
 }
 
 export function refuseChannel(name: string, detail: string, fix: string): never {
-  invariant(false, 'X_CHANNEL_DECLARATION_INVALID', `channel("${name}"): ${detail}`, fix);
+  assertCoded(false, 'X_CHANNEL_DECLARATION_INVALID', `channel("${name}"): ${detail}`, fix);
 }
 
 /** Refuses a bad name or a repeated param, and builds the ref. `channel()` is built on this. */

package/src/channel-registry.ts

@@ -3,13 +3,13 @@
 // and the manifest reads the same table (`channel-describe.ts`); a second declaration of one name
 // is refused. Browser-safe: `channel()` runs in islands too.
 
-import { invariant } from '@ultimat3/core';
+import { assertCoded } from '@ultimat3/core';
 import type { Channel } from './channel-decl';
 
 const channels = new Map<string, Channel>();
 
 export function registerChannel(declared: Channel): Channel {
-  invariant(
+  assertCoded(
     !channels.has(declared.name),
     'X_CHANNEL_DECLARATION_INVALID',
     `two channel() declarations share the name "${declared.name}"`,

package/src/channel.ts

@@ -5,10 +5,10 @@
 
 import {
   type Actor,
+  assertCoded,
   type Ctx,
-  createContext,
+  ctxOf,
   finiteOption,
-  invariant,
   logger,
   renderThrowable,
 } from '@ultimat3/core';
@@ -109,7 +109,7 @@ export class ChannelHub {
       options.maxTopicsPerNode ?? DEFAULT_MAX_TOPICS_PER_NODE,
     );
     this.#latched = new DenialLatch(this.#maxTopicsPerSocket, 'maxTopicsPerSocket');
-    this.#ctx = options.ctx ?? createContext();
+    this.#ctx = options.ctx ?? ctxOf();
     this.#logs = new ChannelLogs(options.sockets, options.ringSize);
     this.#only =
       options.channels === undefined ? null : new Map(options.channels.map((c) => [c.name, c]));
@@ -213,10 +213,11 @@ export class ChannelHub {
    * Every open records topic is presumed to have missed a change: a new epoch, and every member
    * told `replay-gap`. The `sync` node calls it beside `LiveQueryRegistry.invalidate()` — seq is
    * minted here from the changes this node SEES, so a change the bus dropped leaves a hole the
-   * ring cannot detect and would replay as complete history.
+   * ring cannot detect and would replay as complete history. Given an `entity`, only the topics
+   * carrying it: what a bulk write the in-process replicator could not shape as rows stales.
    */
-  invalidate(): number {
-    return this.#logs.invalidate();
+  invalidate(entity?: string): number {
+    return this.#logs.invalidate(entity);
   }
 
   /**
@@ -234,7 +235,7 @@ export class ChannelHub {
     params: Readonly<Record<K, string>>,
     event: JsonObject,
   ): Promise<void> {
-    invariant(
+    assertCoded(
       declared.events,
       'X_CHANNEL_DECLARATION_INVALID',
       `channel("${declared.name}") declares no events, so nothing may publish one on it`,

package/src/client-channels.ts

@@ -292,6 +292,8 @@ export class ChannelBook {
     entry.disarm?.();
     entry.disarm = null;
     this.#set(entry, 'catching-up');
+    // Names no write (#507 pt 2: owner O-507, default none) — a pending write this read already
+    // reflects settles on its own HTTP answer. Where a catch-up names its writes, it goes here.
     this.#deps.catchUp(entry.catchUp, entry.params).then(
       () => this.#drain(entry),
       (error: unknown) => {

package/src/client-frames.ts

@@ -38,6 +38,8 @@ export interface ClientFrameTarget {
   setUpdate(buildId: string | null): void;
   /** The node named the beat this socket must keep (`hello.heartbeatMs`). */
   followHeartbeat(intervalMs: number): void;
+  /** A refused registration the node said may succeed later: subscribe it again after `afterMs`. */
+  retryLater(registration: Registration, afterMs: number): void;
   /** The node assigned this socket its own delay before closing it. */
   scheduleReconnect(afterMs: number | null): void;
   closeSocket(code: number, reason: string): void;
@@ -77,7 +79,8 @@ export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
       registration.cursor = frame.cursor;
       registration.state = 'live';
       registration.error = undefined;
-      target.windows.snapshot(registration, frame.entity ?? null, frame.rows, frame.keys);
+      const { entity, rows, keys, writes } = frame;
+      target.windows.snapshot(registration, entity ?? null, rows, keys, writes);
       return;
     }
     case 'patch': {
@@ -93,7 +96,8 @@ export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
           registration.cursor = next;
         }
         registration.state = 'live';
-        target.windows.patch(registration, frame.patches);
+        // The writes the frame names settle in the window's own batch, as a `records` frame's do.
+        target.windows.patch(registration, frame.patches, frame.writes);
         return;
       }
       // A patch names a live registration or nothing: a channel's rows ride `records` frames.
@@ -112,6 +116,9 @@ export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
       registration.state = 'failed';
       registration.error = refusal;
       registration.notify();
+      // A refusal that states when it may succeed (a rate limit's refill) is not final.
+      const after = frame.error.retryAfterSeconds;
+      if (after !== undefined) target.retryLater(registration, after * 1000);
       return;
     }
     case 'reconnect': {

package/src/client.ts

@@ -4,7 +4,7 @@
 // signal belongs to one bundle's solid-js, so everything here is a plain read plus a listener.
 // Read-only: the socket carries no writes (`useMutation` is HTTP).
 
-import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core/page';
+import { type Clock, finiteOption, systemClock, uuidV7 } from '@ultimat3/core/page';
 import {
   ChannelBook,
   type ChannelHandlers,
@@ -49,6 +49,8 @@ export class LiveClient {
   readonly #clock: Clock;
   readonly #onError: (error: unknown) => void;
   readonly #registrations = new Map<string, Registration>();
+  /** A refused registration's armed re-subscribe, by sid — the node said when it may succeed. */
+  readonly #retries = new Map<string, () => void>();
   readonly #windows: RowWindows;
   readonly #channels: ChannelBook;
   readonly #heartbeat: Heartbeat;
@@ -194,6 +196,9 @@ export class LiveClient {
    */
   #offline(): void {
     this.#heartbeat.stop();
+    // The reopen replays every registration, so a timer left armed would send one twice.
+    for (const cancel of this.#retries.values()) cancel();
+    this.#retries.clear();
     this.#setStatus({ connected: false });
     // Told once, not two ways: a `useConnection().offline` that flips while a live window still
     // reads 'live' is one dead socket rendered as two states. A refused one stays refused.
@@ -230,7 +235,7 @@ export class LiveClient {
     query: LiveQueryRef,
     input: JsonValue,
   ): LiveHandle<R> {
-    const sid = uuid();
+    const sid = uuidV7();
     const listeners = new Set<() => void>();
     const registration: Registration = {
       sid,
@@ -254,6 +259,8 @@ export class LiveClient {
       if (!open) return;
       open = false;
       this.#registrations.delete(sid);
+      this.#retries.get(sid)?.();
+      this.#retries.delete(sid);
       close();
       listeners.clear();
       this.#send({
@@ -323,11 +330,31 @@ export class LiveClient {
       setUpdate: (buildId) => this.#setStatus({ update: buildId }),
       followHeartbeat: (intervalMs) => this.#heartbeat.follow(intervalMs),
       scheduleReconnect: (afterMs) => this.#scheduleReconnect(afterMs),
+      retryLater: (registration, afterMs) => this.#retryLater(registration, afterMs),
       closeSocket: (code, reason) => this.#socket?.close(code, reason),
       report: (error) => this.#onError(error),
     };
   }
 
+  /**
+   * Ask again once the node's stated delay has passed — a rate-limited subscribe, whose bucket
+   * refills. Only while the registration is still held, still refused and the socket still up:
+   * anything else and the reopen's replay, or the unsubscribe, already decided its fate.
+   */
+  #retryLater(registration: Registration, afterMs: number): void {
+    this.#retries.get(registration.sid)?.();
+    const cancel = (this.#options.scheduler ?? timeoutScheduler)(() => {
+      this.#retries.delete(registration.sid);
+      if (this.#registrations.get(registration.sid) !== registration) return;
+      if (!this.#connected || registration.state !== 'failed') return;
+      registration.state = 'loading';
+      registration.error = undefined;
+      registration.notify();
+      this.#sendSubscribe(registration);
+    }, afterMs);
+    this.#retries.set(registration.sid, cancel);
+  }
+
   /** The opening frame, and the heartbeat's. One shape, because it makes one claim: I am here. */
   #hello(): Frame {
     return {

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