@ultimat3/realtime 23.0.0 → 24.0.0

package/src/channel.ts

@@ -16,7 +16,8 @@ import type { ChangeEvent } from './changefeed';
 import { authorizeChannel } from './channel-authz';
 import { type Bridge, unsubscribeWhenOpen } from './channel-bridge';
 import type { Channel, Topic } from './channel-decl';
-import { ChannelLogs } from './channel-logs';
+import { DenialLatch } from './channel-latch';
+import { ChannelLogs, type ChannelTopic } from './channel-logs';
 import { getChannel, registeredChannels } from './channel-registry';
 import type { ChannelEventsFrame, ChannelSubscribeTarget } from './channel-wire';
 import {
@@ -52,6 +53,12 @@ export interface ChannelHubOptions {
   readonly ringSize?: number;
 }
 
+/** The longest value one channel param may carry — a uuid is 36. */
+export const MAX_CHANNEL_PARAM_LENGTH = 128;
+
+/** `#settle`'s "nobody has decided this seat yet": distinct from `null`, which is an actor. */
+const UNDECIDED = Symbol('undecided');
+
 /** Distinct topics one node bridges before `X_SUBSCRIPTION_LIMIT`. */
 export const DEFAULT_MAX_TOPICS_PER_NODE = 10_000;
 
@@ -80,12 +87,13 @@ export class ChannelHub {
   readonly #only: ReadonlyMap<string, Channel> | null;
   readonly #logs: ChannelLogs;
   readonly #ctx: Ctx;
+  /** Topics a socket's policy refused, until its actor changes (`channel-latch.ts`). */
+  readonly #latched: DenialLatch;
   /**
-   * Topics a socket's policy refused, latched until its actor changes: a denial is a decision, so
-   * a client re-asking in a loop is answered without re-running the policy each time — and only
-   * THAT channel is refused, every other one on the socket keeps flowing.
+   * Topics whose guard could not DECIDE on a re-auth. Not a denial, so the seat and its bridge
+   * reference are kept; not a pass either, so nothing is delivered until one succeeds.
    */
-  readonly #latched = new WeakMap<SyncSocket, Set<string>>();
+  readonly #suspended = new WeakMap<SyncSocket, Set<Topic>>();
 
   constructor(options: ChannelHubOptions) {
     this.#transport = options.transport;
@@ -100,6 +108,7 @@ export class ChannelHub {
       'maxTopicsPerNode',
       options.maxTopicsPerNode ?? DEFAULT_MAX_TOPICS_PER_NODE,
     );
+    this.#latched = new DenialLatch(this.#maxTopicsPerSocket, 'maxTopicsPerSocket');
     this.#ctx = options.ctx ?? createContext();
     this.#logs = new ChannelLogs(options.sockets, options.ringSize);
     this.#only =
@@ -123,31 +132,93 @@ export class ChannelHub {
     }
     const params: Record<string, string> = {};
     for (const param of declared.params) {
-      params[param] = Object.hasOwn(target.params, param) ? (target.params[param] ?? '') : '';
+      const value = Object.hasOwn(target.params, param) ? (target.params[param] ?? '') : '';
+      // A topic is retained (the bridge table, the latch, the client's sid), and `topic()` checks
+      // a segment's alphabet, never its size — so a param is the client's to grow only this far.
+      if (value.length > MAX_CHANNEL_PARAM_LENGTH) {
+        throw new TopicForbiddenError({
+          topic: target.channel,
+          actorId: socket.actorId,
+          reason: `param "${param}" is ${value.length} characters; the limit is ${MAX_CHANNEL_PARAM_LENGTH}`,
+        });
+      }
+      params[param] = value;
     }
     const name = declared.topic(params);
-    if (this.#latched.get(socket)?.has(name) === true) {
+    if (this.#latched.has(socket, name)) {
       throw new TopicForbiddenError({
         topic: name,
         actorId: socket.actorId,
         reason: 'denied earlier on this connection; it is re-decided when the session changes',
       });
     }
+    this.#latched.assertRoom(socket);
+    const seat: ChannelTopic = { channel: declared, params };
+    // A suspended seat asked for again (the client's beat) is the next pass, never a second seat.
+    if (this.#suspended.get(socket)?.has(name) === true) {
+      await this.#settle(socket, name, seat, UNDECIDED);
+      return name;
+    }
     // Asked before the join seats it: a repeated `add` (the presence beat) is not a fresh seat.
     const fresh = !socket.topics.has(name);
+    // Captured, because the guard awaits and a re-auth may land under it: the verdict below is
+    // about THIS actor, and `onActorChange` cannot re-decide a seat that does not exist yet.
+    const actor = socket.actor;
     await this.#join(socket, name, async () => {
       try {
-        await authorizeChannel(declared, this.#ctx, socket.actor, name, params);
+        await authorizeChannel(declared, this.#ctx, actor, name, params);
       } catch (error) {
-        if (error instanceof TopicForbiddenError) this.#latch(socket, name);
+        if (error instanceof TopicForbiddenError && socket.actor === actor) {
+          this.#latched.add(socket, name);
+        }
         throw error;
       }
     });
-    this.#logs.open(name, { channel: declared, params });
+    // The socket died while the guard or the bridge was answering: `#join` gave the seat back, so
+    // there is no member to open a ring for or to resume.
+    if (!socket.topics.has(name)) return name;
+    this.#logs.open(name, seat);
+    await this.#settle(socket, name, seat, actor);
+    // Dropped is a throw; suspended is a seat nothing is delivered on, the resume included.
+    if (!socket.topics.has(name)) return name;
     this.#logs.resume(socket, name, target.since, fresh);
     return name;
   }
 
+  /**
+   * Decide a seat under the socket's CURRENT actor until the actor it was decided for is still the
+   * one on the socket. A seat granted to the actor a re-auth has since replaced was kept until the
+   * next grant expiry; a re-ask on a suspended seat ignored a denial and answered success.
+   */
+  async #settle(
+    socket: SyncSocket,
+    name: Topic,
+    seat: ChannelTopic,
+    decidedFor: Actor | null | typeof UNDECIDED,
+  ): Promise<void> {
+    let actor = decidedFor;
+    while (actor === UNDECIDED || socket.actor !== actor) {
+      actor = socket.actor;
+      if ((await this.#decide(socket, name, seat, actor)) !== 'denied') continue;
+      if (socket.actor === actor) this.#latched.add(socket, name);
+      throw new TopicForbiddenError({
+        topic: name,
+        actorId: socket.actorId,
+        reason: `channel "${seat.channel.name}" policy denied the subscribe`,
+      });
+    }
+  }
+
+  /**
+   * 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.
+   */
+  invalidate(): number {
+    return this.#logs.invalidate();
+  }
+
   /**
    * One committed change from the feed, turned into `records` frames on every declared channel it
    * touches and delivered on THIS node. Called for every change the node receives — the same
@@ -178,6 +249,9 @@ export class ChannelHub {
    * a topic a caller spelled; every `Topic` comes from a declaration.
    */
   async emit(name: Topic, event: JsonObject): Promise<void> {
+    // A topic this node holds open on a channel declared without `events` carries none: a
+    // presence leave for it was an event on a channel whose members were promised records only.
+    if (this.#logs.target(name)?.channel.events === false) return;
     const frame: ChannelEventsFrame = { type: 'events', v: PROTOCOL_VERSION, channel: name, event };
     await this.#transport.publish(`${CHANNEL_SUBJECT_PREFIX}.${name}`, JSON.stringify(frame));
   }
@@ -189,12 +263,6 @@ export class ChannelHub {
     return this.#logs.target(name);
   }
 
-  #latch(socket: SyncSocket, name: string): void {
-    const latched = this.#latched.get(socket) ?? new Set<string>();
-    latched.add(name);
-    this.#latched.set(socket, latched);
-  }
-
   /** Sockets this node will deliver `name` to. The metric the fanout reads. */
   subscriberCount(name: Topic): number {
     return this.#sockets.subscriberCount(name);
@@ -222,7 +290,8 @@ export class ChannelHub {
   async #join(socket: SyncSocket, name: Topic, authorize: () => Promise<void>): Promise<void> {
     if (socket.topics.has(name)) return;
     const claimed = this.#claimed.get(socket) ?? 0;
-    if (socket.topics.size + claimed >= this.#maxTopicsPerSocket) {
+    const held = socket.topics.size + (this.#suspended.get(socket)?.size ?? 0);
+    if (held + claimed >= this.#maxTopicsPerSocket) {
       throw new SubscriptionLimitError({
         scope: 'socket',
         id: socket.id,
@@ -263,51 +332,81 @@ export class ChannelHub {
     // fanout reads are one fact, and two call sites for one fact is the drift that makes an index
     // wrong. The registry owns it because it is the only thing that sees a socket die.
     this.#sockets.joinTopic(socket, name);
+    // The socket closed while this subscribe was parked: its teardown has already walked its
+    // topics, so a seat taken now is a bridge pinned with no member and nothing left to release it.
+    if (socket.closed) this.unsubscribe(socket, name);
   }
 
   unsubscribe(socket: SyncSocket, name: Topic): void {
-    if (!socket.topics.has(name)) return;
-    this.#sockets.leaveTopic(socket, name);
+    const suspended = this.#suspended.get(socket)?.delete(name) === true;
+    if (!suspended && !socket.topics.has(name)) return;
+    if (!suspended) this.#sockets.leaveTopic(socket, name);
     this.#release(name);
   }
 
+  /** Every topic this socket holds a seat on — the delivered ones and the suspended ones. */
+  topicsOf(socket: SyncSocket): readonly Topic[] {
+    return [...socket.topics, ...(this.#suspended.get(socket) ?? [])] as Topic[];
+  }
+
   /**
    * Called when a socket's session changes (login, logout, role change, token refresh).
    *
-   * A denial drops the topic; anything else keeps it. A guard is app code and may reach a database,
-   * so `catch { unsubscribe }` reported a store that timed out as a revoked grant — during one
-   * outage, every topic on every re-authenticated socket on the node, silently, with the client
-   * never told to resubscribe. The same split `LiveQueryRegistry.reauthorize` already makes, and
-   * for the same reason: a failure is not a decision.
+   * A denial drops the topic. Anything else is not a decision — a guard is app code and may reach
+   * a database, and reading a store that timed out as a revoked grant dropped every topic on every
+   * re-authenticated socket during one outage. It is not a pass either: the seat is kept and
+   * SUSPENDED, so nothing is delivered on it until a later pass (the next re-auth, or the client's
+   * own beat) decides. Returns the topics dropped — denials and nothing else.
    */
   async onActorChange(socket: SyncSocket, actor: Actor | null): Promise<readonly Topic[]> {
     socket.actor = actor;
     // A new session re-decides everything, the latched denials included.
-    this.#latched.delete(socket);
+    this.#latched.clear(socket);
     const dropped: Topic[] = [];
-    for (const name of [...socket.topics] as Topic[]) {
-      try {
-        const target = this.#logs.target(name);
-        if (target !== undefined) {
-          await authorizeChannel(target.channel, this.#ctx, actor, name, target.params);
-        }
-      } catch (error) {
-        if (isPolicyDenial(error) || error instanceof TopicForbiddenError) {
-          this.unsubscribe(socket, name);
-          dropped.push(name);
-          continue;
-        }
-        this.#guardFailures += 1;
-        logger.warn('channel.guard_failed', {
-          topic: name,
-          socketId: socket.id,
-          error: renderThrowable(error),
-        });
-      }
+    for (const name of this.topicsOf(socket)) {
+      const target = this.#logs.target(name);
+      if (target === undefined) continue;
+      if ((await this.#decide(socket, name, target, actor)) === 'denied') dropped.push(name);
     }
     return dropped;
   }
 
+  /** One seat, re-decided: dropped on a denial, suspended on a failure, delivered on a pass. */
+  async #decide(
+    socket: SyncSocket,
+    name: Topic,
+    target: ChannelTopic,
+    actor: Actor | null,
+  ): Promise<'allowed' | 'denied' | 'undecided'> {
+    try {
+      await authorizeChannel(target.channel, this.#ctx, actor, name, target.params);
+    } catch (error) {
+      if (isPolicyDenial(error) || error instanceof TopicForbiddenError) {
+        this.unsubscribe(socket, name);
+        return 'denied';
+      }
+      this.#guardFailures += 1;
+      logger.warn('channel.guard_failed', {
+        topic: name,
+        socketId: socket.id,
+        error: renderThrowable(error),
+      });
+      if (socket.topics.has(name)) {
+        this.#sockets.leaveTopic(socket, name);
+        const suspended = this.#suspended.get(socket) ?? new Set<Topic>();
+        this.#suspended.set(socket, suspended.add(name));
+      }
+      return 'undecided';
+    }
+    // Still suspended, and still open: a socket that closed meanwhile gave the seat back already.
+    if (this.#suspended.get(socket)?.delete(name) === true) {
+      this.#sockets.joinTopic(socket, name);
+      // What the suspension withheld is unknown to the client, so a records channel is re-read.
+      this.#logs.resume(socket, name, undefined, true);
+    }
+    return 'allowed';
+  }
+
   async close(): Promise<void> {
     // Set BEFORE the table is walked, because the table is not the whole story: a reservation an
     // in-flight `subscribe` has not opened yet is `sub === null`, so `unsubscribeWhenOpen` does

package/src/client-channels.ts

@@ -208,6 +208,10 @@ export class ChannelBook {
   event(frame: ChannelEventsFrame): void {
     const entry = this.#byTopic.get(frame.channel);
     const presence = readPresence(frame.event);
+    // The node delivers an event only to a member it has seated, and for an events-only channel
+    // (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 ?? []) {
       if (presence !== null) holder.onPresence?.(presence);
       else holder.onEvent?.(frame.event);
@@ -230,7 +234,12 @@ export class ChannelBook {
     const contiguous = entry.contiguous ?? frame.seq - 1;
     // A duplicate is dropped; a replayed seq filling a hole is new. A numeric hole on its own is
     // never a gap — a row this socket may not see is skipped for it; only `replay-gap` is.
-    if (frame.seq <= contiguous || entry.above.has(frame.seq)) return;
+    if (frame.seq <= contiguous || entry.above.has(frame.seq)) {
+      // Still a frame of THIS epoch on THIS seat — and the whole of the node's answer to a resume
+      // that was already current (`ChannelLogs.resume`): nothing to apply, and no longer joining.
+      if (entry.state !== 'live') this.#set(entry, 'live');
+      return;
+    }
     const store = this.#deps.store;
     store.batch(() => {
       for (const [type, rows] of Object.entries(frame.adopt ?? {})) store.adopt(type, rows);

package/src/client-contract.ts

@@ -63,7 +63,10 @@ export interface LiveClientOptions {
   readonly clock?: Clock;
   /** How a pending reconnect is armed. Defaults to `setTimeout`; tests fire theirs by hand. */
   readonly scheduler?: Scheduler;
-  /** How often a live socket re-announces itself, in ms. `0` disables it. Default 15s. */
+  /**
+   * How often a live socket re-announces itself, in ms, until the node names its own beat on its
+   * `hello` (`hello.heartbeatMs`). `0` disables the pass, whatever the node says. Default 10s.
+   */
   readonly heartbeatMs?: number;
   /** Where a failure nobody awaits is reported. Defaults to `console.error`. */
   readonly onError?: (error: unknown) => void;

package/src/client-frames.ts

@@ -36,6 +36,8 @@ export interface ClientFrameTarget {
   now(): number;
   /** A newer build is live; the app decides when to reload. */
   setUpdate(buildId: string | null): void;
+  /** The node named the beat this socket must keep (`hello.heartbeatMs`). */
+  followHeartbeat(intervalMs: number): void;
   /** The node assigned this socket its own delay before closing it. */
   scheduleReconnect(afterMs: number | null): void;
   closeSocket(code: number, reason: string): void;
@@ -135,8 +137,12 @@ export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
       target.channels.gap(frame);
       return;
     case 'hello':
+      // The node's reply. It carries one instruction — how often to beat — and a node that names
+      // none (an older build) leaves the client on its own default.
+      if (frame.heartbeatMs !== undefined) target.followHeartbeat(frame.heartbeatMs);
+      return;
     case 'subscribe':
-      // Client-authored frames: never received. Ignored rather than thrown, so a future
+      // A client-authored frame: never received. Ignored rather than thrown, so a future
       // bidirectional use of the same kind cannot break an old client.
       return;
   }

package/src/client-heartbeat.ts

@@ -5,15 +5,22 @@
 import type { Scheduler } from './thundering-herd';
 
 /**
- * The client's own number, and `As of 2026-08-19` the only one. It used to be described as a
- * restatement of `realtime.heartbeatMs` in `@ultimat3/core`'s config — that key was read by
- * nothing and is deleted, so there is no second value to keep this equal to. The server side of
- * the beat is DERIVED, never configured: `PresenceRegistry.heartbeatMs` is `ttlMs / 3`.
+ * A third of the node's default presence ttl (`DEFAULT_PRESENCE_TTL_MS`, 30 s), which is what the
+ * node derives for itself (`PresenceRegistry.heartbeatMs` is `ttlMs / 3`): two beats land inside
+ * every ttl, so ONE lost beat is never a false leave. It was 15 s — half the ttl, where the beat
+ * after a lost one lands on the expiry itself. `client-heartbeat.test.ts` holds the two equal;
+ * this file cannot import the server's constant (`transport-env.ts` links `nats`).
  */
-export const DEFAULT_HEARTBEAT_MS = 15_000;
+export const DEFAULT_HEARTBEAT_MS = 10_000;
+
+/** The node floors the beat it names at 1 s (`clientHeartbeatMs`); less than that is not its word. */
+export const MIN_HEARTBEAT_MS = 1_000;
 
 export interface HeartbeatOptions {
-  /** `0` (or less) disables the pass entirely — the shape a test that owns the clock wants. */
+  /**
+   * Until the node names its own (`follow`). `0` (or less) disables the pass entirely, whatever
+   * the node says — the shape a test that owns the clock wants.
+   */
   readonly intervalMs: number;
   readonly schedule: Scheduler;
   readonly now: () => number;
@@ -32,19 +39,42 @@ export class Heartbeat {
   readonly #options: HeartbeatOptions;
   #cancel: (() => void) | null = null;
   #lastSeen = 0;
+  /** The beat in force on THIS socket: the option's, until the node's `hello` names another. */
+  #intervalMs: number;
 
   constructor(options: HeartbeatOptions) {
     this.#options = options;
+    this.#intervalMs = options.intervalMs;
+  }
+
+  get intervalMs(): number {
+    return this.#intervalMs;
   }
 
   /** The socket is up. `now` seeds the silence window, so the first tick judges this connection. */
   start(now: number): void {
     this.stop();
-    if (this.#options.intervalMs <= 0) return;
+    // A new socket may be another node's: its beat is not known until its `hello` says so.
+    this.#intervalMs = this.#options.intervalMs;
+    if (this.#intervalMs <= 0) return;
     this.#lastSeen = now;
     this.#arm();
   }
 
+  /**
+   * The node named the beat (`hello.heartbeatMs`): a third of ITS presence ttl, bounded by ITS idle
+   * budget — two numbers a browser cannot read, and the reason a fixed client beat was wrong for
+   * every app that set either. Re-armed at once, so a shorter beat does not wait out the long one.
+   */
+  follow(intervalMs: number): void {
+    if (this.#options.intervalMs <= 0) return;
+    if (intervalMs < MIN_HEARTBEAT_MS || intervalMs === this.#intervalMs) return;
+    this.#intervalMs = intervalMs;
+    if (this.#cancel === null) return;
+    this.stop();
+    this.#arm();
+  }
+
   /** A frame arrived. Anything counts: the point is that bytes still cross in this direction. */
   saw(now: number): void {
     this.#lastSeen = now;
@@ -60,7 +90,7 @@ export class Heartbeat {
     this.#cancel = this.#options.schedule(() => {
       this.#cancel = null;
       this.#tick();
-    }, this.#options.intervalMs);
+    }, this.#intervalMs);
   }
 
   #tick(): void {
@@ -68,7 +98,7 @@ export class Heartbeat {
     // Two windows, not one: a beat and the answer to it share the window they were sent in, so a
     // single quiet interval is a slow round trip and not a dead socket. Nothing is re-armed after
     // a silence — `onSilence` drops the socket, and the next `start()` is the next connection's.
-    if (now - this.#lastSeen > this.#options.intervalMs * 2) {
+    if (now - this.#lastSeen > this.#intervalMs * 2) {
       this.#options.onSilence();
       return;
     }

package/src/client.ts

@@ -321,6 +321,7 @@ export class LiveClient {
       // against a re-snapshot, so the frame path reads the same clock every other path does.
       now: () => this.#clock.now().getTime(),
       setUpdate: (buildId) => this.#setStatus({ update: buildId }),
+      followHeartbeat: (intervalMs) => this.#heartbeat.follow(intervalMs),
       scheduleReconnect: (afterMs) => this.#scheduleReconnect(afterMs),
       closeSocket: (code, reason) => this.#socket?.close(code, reason),
       report: (error) => this.#onError(error),

package/src/cursor.ts

@@ -76,6 +76,17 @@ export interface ResumeSource {
    * the entry, which is the only moment anything knows the window is unreachable.
    */
   forget?(qid: string): void;
+  /**
+   * The window behind `qid` was read at `lsn`, so what is retained for it is complete from there
+   * and from nowhere earlier; `exclusive` refuses a cursor exactly at it (a forced re-read), `sole`
+   * answers that cursor and no other below the first patch (a read with no position behind it).
+   * Optional for `forget`'s reason. When it is called, and why, is one rule: `change-buffer.ts`.
+   */
+  floorAt?(
+    qid: string,
+    lsn: string,
+    options?: { readonly exclusive?: boolean; readonly sole?: boolean },
+  ): void;
 }
 
 export type ResumeResult<R extends Row = Row> =

package/src/errors.ts

@@ -1,7 +1,7 @@
 // Realtime's X_* codes. Every throw in this package goes through one of these classes so
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
-import { registerErrorCodes } from '@ultimat3/core';
+import { isFixShellSafe, registerErrorCodes, renderFixShellArg } from '@ultimat3/core';
 import { RealtimeError } from './realtime-error';
 
 /** Codes this package declares and owns. */
@@ -36,6 +36,7 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_REALTIME_TOPOLOGY',
   'X_REPLICATION_TLS',
   'X_SOCKET_ORIGIN_REFUSED',
+  'X_OFFLINE_QUEUE_ABANDONED',
 ] as const;
 
 /**
@@ -61,6 +62,24 @@ export const POLICY_DENIAL_CODES: ReadonlySet<string> = new Set([
   'X_UNAUTHENTICATED',
 ]);
 
+/**
+ * `@ultimat3/entity`'s tenant guard refusing a read FOR THIS ACTOR: it carries no org, names
+ * another one, or reached across tenants without the capability. Verdicts about who is asking, so
+ * a channel's row loader raising one is a denial. `X_TENANCY_UNSCOPED` is deliberately absent —
+ * that is a query written without a tenant predicate, which is the app's defect and no decision.
+ * Spelled by name, never matched by prefix: a code's meaning is its owner's, not its shape's.
+ */
+export const TENANCY_DENIAL_CODES: ReadonlySet<string> = new Set([
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+  'X_TENANCY_ACTOR_MISMATCH',
+  'X_TENANCY_CROSS_DENIED',
+]);
+
+/** True when the tenant guard decided against the actor — see `TENANCY_DENIAL_CODES`. */
+export function isTenancyDenial(error: unknown): boolean {
+  return TENANCY_DENIAL_CODES.has(codeOf(error) ?? '');
+}
+
 /**
  * The sync protocol's answer to "which of these is a 4xx". A denied topic, a subscription cap, a
  * skewed protocol version and a cursor that fell out of the buffer are all conditions the CLIENT
@@ -146,6 +165,7 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   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',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws
@@ -159,6 +179,7 @@ registerErrorCodes(
 export {
   CursorStaleError,
   LocalStoreUnavailableError,
+  OfflineQueueAbandonedError,
   ProtocolVersionError,
   RealtimeUninstalledError,
   RebaseConflictError,
@@ -300,17 +321,33 @@ export class TransportProtocolError extends RealtimeError {
 }
 
 /**
- * A subscribable read projected a row with no `id`. Patches, cursors and the local store all
- * address a row by `id`, so such a row cannot be delivered — and delivering it anyway produces a
- * subscription that looks correct until the first update nobody can apply.
+ * A subscribable read projected a row with no usable `id`. Patches, cursors and the local store all
+ * address a row by a text `id`, so such a row cannot be delivered — and delivering it anyway
+ * produces a subscription that looks correct until the first update nobody can apply.
+ *
+ * `idType` is set when the row HAS an id that is neither text nor a safe integer (the one numeric
+ * shape the change feed and the snapshot both stringify): "select the primary key" is then the
+ * wrong instruction, because the key is selected.
  */
 export class LiveRowUnidentifiedError extends RealtimeError {
-  constructor(args: { query: string; keys: readonly string[] }) {
-    super({
-      code: 'X_LIVE_ROW_UNIDENTIFIED',
-      cause: `live query "${args.query}" returned a row with no id (columns: ${args.keys.join(', ') || 'none'})`,
-      fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
-    });
+  constructor(args: { query: string; keys: readonly string[]; idType?: string }) {
+    const columns = args.keys.join(', ') || 'none';
+    super(
+      args.idType === undefined
+        ? {
+            code: 'X_LIVE_ROW_UNIDENTIFIED',
+            cause: `live query "${args.query}" returned a row with no id (columns: ${columns})`,
+            fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
+          }
+        : {
+            code: 'X_LIVE_ROW_UNIDENTIFIED',
+            cause: `live query "${args.query}" returned a row whose id is a ${args.idType}, not text or a safe integer — a live row is addressed by a text id, so project the key as text (a uuid or text column) or drop live: true from the query`,
+            // A name the shell would not read verbatim does not travel: the list names it instead.
+            fix: isFixShellSafe(args.query)
+              ? `x queries describe ${renderFixShellArg(args.query, 'name')} --json`
+              : 'x queries list --json',
+          },
+    );
   }
 }
 
@@ -363,11 +400,21 @@ export class SocketUnauthenticatedError extends RealtimeError {
  * the accept budget, so a hostile page costs neither.
  */
 export class SocketOriginRefusedError extends RealtimeError {
-  constructor(args: { reason: string }) {
+  constructor(args: { reason: string; asked: string | null; admitted: readonly string[] }) {
+    // The asking origin is a request header: it travels only as the origin a URL parser read out
+    // of it AND only when the shell screen carries it verbatim, so neither the cause nor the
+    // pasted `export` can hold anything the client wrote beyond a scheme, a host and a port.
+    const parsed = URL.parse(args.asked ?? '')?.origin;
+    const asked = isFixShellSafe(parsed) ? parsed : null;
+    const { admitted } = args;
+    const list =
+      admitted.length === 0
+        ? 'only the origin it was reached on (no APP_URL declared)'
+        : `only ${admitted.join(', ')}`;
     super({
       code: 'X_SOCKET_ORIGIN_REFUSED',
-      cause: `the websocket upgrade was refused: ${args.reason}`,
-      fix: 'export APP_URL="https://www.example.com"   # on the sync role: the origin the page is served on (or createSyncNode({ allowedOrigins }))',
+      cause: `the websocket upgrade was refused: ${args.reason} — asked from ${asked ?? 'an origin that cannot be rendered'}; this node admits ${list}`,
+      fix: `export APP_URL=${asked ?? 'https://www.example.com'}   # on the sync role, and only when that is the origin your pages are served on (or createSyncNode({ allowedOrigins }))`,
     });
   }
 }
@@ -405,13 +452,17 @@ export class WindowReadTimeoutError extends RealtimeError {
   }
 }
 
-/** Deep infrastructure that is interface-complete but not wired. Carries the exact next step. */
-export class NotImplementedError extends RealtimeError {
-  constructor(args: { what: string; fix: string }) {
+/**
+ * A grant's `refresh()` — the app's token service — did not answer inside its deadline. The grant
+ * is NOT renewed and NOT revoked: it stays expired and the next re-auth pass asks again. What the
+ * deadline buys is the rest of the pass, which one call that never settles used to park forever.
+ */
+export class GrantRefreshTimeoutError extends RealtimeError {
+  constructor(args: { socketId: string; afterMs: number }) {
     super({
-      code: 'X_NOT_IMPLEMENTED',
-      cause: `${args.what} is interface-complete but not implemented in this build`,
-      fix: args.fix,
+      code: 'X_TIMEOUT',
+      cause: `refresh() for the grant of socket ${args.socketId} did not answer within ${args.afterMs}ms, so the re-auth pass moved on; the grant stays expired and is asked again on the next pass`,
+      fix: 'x doctor --json',
     });
   }
 }

package/src/fanout.ts

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

package/src/index.ts

@@ -62,7 +62,7 @@ export {
   FrameRateLimitError,
   LiveQueryUnknownError,
   LiveRowUnidentifiedError,
-  NotImplementedError,
+  OfflineQueueAbandonedError,
   ProtocolVersionError,
   REALTIME_ERROR_CODES,
   REALTIME_ERROR_TITLES,