@ultimat3/realtime 22.15.0 → 24.0.0

package/src/channel-records.ts

@@ -2,6 +2,7 @@
 // socket, no seq, no policy — `ChannelHub` does those per node and per socket. The only derivation
 // of "which channel carries this row" lives here, so a write never names a channel (axiom 2).
 
+import { type Counter, counter, logger } from '@ultimat3/core';
 import type { Row } from '@ultimat3/core/page';
 import type { RecordProjection } from '@ultimat3/entity/record';
 import type { ChangeEvent } from './changefeed';
@@ -16,6 +17,23 @@ export interface TopicUpdate {
   readonly adopt: readonly RecordPart[];
   readonly remove: readonly { readonly type: string; readonly key: string }[];
   readonly row: Row;
+  /**
+   * The change could not carry this row whole (`ChangeEvent.omitted` names a column the record
+   * projects), so there is nothing sound to adopt: the topic's members are told to re-read.
+   */
+  readonly gap?: true;
+}
+
+const removalsSkipped: Counter = counter('channel_removals_skipped_total', {
+  unit: '{removal}',
+  description:
+    'Channel record removals that could not be routed: the old row image lacked the channel params (the table is not REPLICA IDENTITY FULL), so members keep the removed record.',
+});
+let skipped = 0;
+
+/** Removals this process could not route since boot — the in-process read of the counter above. */
+export function skippedRemovals(): number {
+  return skipped;
 }
 
 /**
@@ -25,7 +43,9 @@ export interface TopicUpdate {
  * - insert/update: the new row is adopted on the topic its params name.
  * - an update that moved the row to other params (`orgId` changed): a remove on the OLD topic too.
  * - delete: a remove on the topic the old image names — which needs the params columns in the
- *   `before` image, i.e. `REPLICA IDENTITY FULL`; a key-only image names no topic and is skipped.
+ *   `before` image, i.e. `REPLICA IDENTITY FULL`; a key-only image names no topic and is skipped
+ *   — COUNTED and logged (`channel.removal_skipped`), because the members of that topic keep a
+ *   record the database no longer has and nothing else would ever say so.
  */
 export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): TopicUpdate[] {
   const updates: TopicUpdate[] = [];
@@ -39,17 +59,28 @@ export function updatesFor(channels: Iterable<Channel>, change: ChangeEvent): To
     const before = change.before;
     const afterParams = after === null ? null : channel.paramsOf(after);
     const beforeParams = before === null ? null : channel.paramsOf(before);
+    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 });
+    }
     const afterTopic = afterParams === null ? null : channel.topic(afterParams);
     const beforeTopic = beforeParams === null ? null : channel.topic(beforeParams);
 
     if (after !== null && afterParams !== null && afterTopic !== null) {
+      // An unchanged out-of-line value Postgres logged no bytes for: adopted, the partial row
+      // would be retained in the ring as the whole record and handed to every later joiner.
+      const partial = (change.omitted ?? []).some((column) =>
+        Object.hasOwn(projection.schema.properties ?? {}, column),
+      );
       updates.push({
         channel,
         topic: afterTopic,
         params: afterParams,
-        adopt: [{ type: projection.type, key: projection.key(after), row: after }],
+        adopt: partial ? [] : [{ type: projection.type, key: projection.key(after), row: after }],
         remove: [],
         row: after,
+        ...(partial ? { gap: true as const } : {}),
       });
     }
     if (

package/src/channel-sids.ts

@@ -0,0 +1,37 @@
+// The sid each of a socket's channel seats was answered under, keyed by TOPIC. A sid is client
+// data: keyed by it, one socket minted an entry per fresh sid without bound, and two sids naming
+// one topic aliased one membership — dropping either unsubscribed the other.
+
+import type { Topic } from './channel-decl';
+import type { SyncSocket } from './socket';
+
+/** Weakly keyed by socket, so a socket's entries die with it; bounded by the hub's topic cap. */
+export class ChannelSids {
+  readonly #bySocket = new WeakMap<SyncSocket, Map<Topic, string>>();
+
+  /** The latest sid wins: a repeated `add` under a new sid re-names the one seat, never adds one. */
+  set(socket: SyncSocket, topic: Topic, sid: string): void {
+    const topics = this.#bySocket.get(socket) ?? new Map<Topic, string>();
+    this.#bySocket.set(socket, topics.set(topic, sid));
+  }
+
+  /** The sid a refusal for this seat must name — `undefined` when the socket holds no such seat. */
+  sidOf(socket: SyncSocket, topic: Topic): string | undefined {
+    return this.#bySocket.get(socket)?.get(topic);
+  }
+
+  /** The topic currently held under `sid`. A sid an earlier `add` was re-named away from holds none. */
+  topicOf(socket: SyncSocket, sid: string): Topic | undefined {
+    for (const [topic, held] of this.#bySocket.get(socket) ?? []) if (held === sid) return topic;
+    return undefined;
+  }
+
+  delete(socket: SyncSocket, topic: Topic): void {
+    this.#bySocket.get(socket)?.delete(topic);
+  }
+
+  /** Seats recorded for one socket — what a test bounds. */
+  count(socket: SyncSocket): number {
+    return this.#bySocket.get(socket)?.size ?? 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

@@ -3,11 +3,12 @@
 // every piece of the client a frame may touch, so the blast radius of a new frame kind is a
 // reviewable list rather than "whatever the router could reach through `this`".
 
+import { UltimateError } from '@ultimat3/core/page';
 import type { ChannelBook } from './client-channels';
 import { CLOSE } from './close-codes';
 import { advance } from './cursor';
 import type { Registration, RowWindows } from './live-rows';
-import type { Frame } from './sync-protocol';
+import type { Frame, WireError } from './sync-protocol';
 
 /** Declared with the window it projects; re-exported here because the router is what writes it. */
 export type { LiveState, Registration } from './live-rows';
@@ -35,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;
@@ -42,6 +45,28 @@ export interface ClientFrameTarget {
   report(error: unknown): void;
 }
 
+/** An absolute HTTP(S) link, or nothing: a node's `docs` is data and may be `javascript:`. */
+const HTTP_URL = /^https?:\/\/[^\s]+$/;
+
+/**
+ * A refusal off the wire, as the error the node raised: the same code, cause and fix, BRANDED —
+ * the shape `@ultimat3/core`'s `problemError` gives an HTTP failure, marked `origin: 'remote'` the
+ * same way. Handed over as the bare `WireError` it failed `isUltimateError`, so every reader that
+ * asks that question — `<ErrorState>`, a boundary, a reporter — fell through to "an unknown value
+ * was thrown": `X_INTERNAL`, the real error JSON-stringified into its cause, and a fix telling the
+ * reader to throw the `UltimateError` it already was.
+ */
+export function refusalError(wire: WireError): UltimateError {
+  const docs = wire.docs !== undefined && HTTP_URL.test(wire.docs) ? wire.docs : undefined;
+  return new UltimateError({
+    code: wire.code,
+    cause: wire.cause,
+    fix: wire.fix,
+    meta: { origin: 'remote' },
+    ...(docs === undefined ? {} : { docs }),
+  });
+}
+
 export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
   switch (frame.type) {
     case 'snapshot': {
@@ -78,13 +103,14 @@ export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
       // The socket carries no writes, so an `ack` is only ever a refusal: of a subscription (its
       // `ref` is the sid) or of a frame the node could not read at all (its `ref` is the socket).
       if (frame.error === null) return;
+      const refusal = refusalError(frame.error);
       const registration = target.registration(frame.ref);
       if (registration === undefined) {
-        if (!target.channels.refused(frame.ref, frame.error)) target.report(frame.error);
+        if (!target.channels.refused(frame.ref, refusal)) target.report(refusal);
         return;
       }
       registration.state = 'failed';
-      registration.error = frame.error;
+      registration.error = refusal;
       registration.notify();
       return;
     }
@@ -111,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> =