@ultimat3/realtime 23.0.0 → 25.0.0

package/src/channel.ts

@@ -5,10 +5,10 @@
 
 import {
   type Actor,
+  assertCoded,
   type Ctx,
-  createContext,
+  ctxOf,
   finiteOption,
-  invariant,
   logger,
   renderThrowable,
 } from '@ultimat3/core';
@@ -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,7 +108,8 @@ export class ChannelHub {
       'maxTopicsPerNode',
       options.maxTopicsPerNode ?? DEFAULT_MAX_TOPICS_PER_NODE,
     );
-    this.#ctx = options.ctx ?? createContext();
+    this.#latched = new DenialLatch(this.#maxTopicsPerSocket, 'maxTopicsPerSocket');
+    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]));
@@ -123,31 +132,94 @@ 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. Given an `entity`, only the topics
+   * carrying it: what a bulk write the in-process replicator could not shape as rows stales.
+   */
+  invalidate(entity?: string): number {
+    return this.#logs.invalidate(entity);
+  }
+
   /**
    * 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
@@ -163,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`,
@@ -178,6 +250,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 +264,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 +291,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 +333,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);
@@ -283,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-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,10 @@ 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;
+  /** 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;
@@ -75,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': {
@@ -91,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.
@@ -110,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': {
@@ -135,8 +144,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

@@ -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({
@@ -321,12 +328,33 @@ 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),
+      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/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> =