@ultimat3/realtime 1.2.0 → 2.0.0

package/src/channel.ts

@@ -4,9 +4,9 @@
 // append-only stream, so tier 1 needs no frame of its own. That is why climbing the ladder is a
 // config change: the client's frame handler is the same code at every rung.
 
-import type { Actor } from '@ultimat3/core';
+import { type Actor, logger, renderThrowable } from '@ultimat3/core';
 import { formatLsn } from './changefeed';
-import { SubscriptionLimitError, TopicForbiddenError } from './errors';
+import { isPolicyDenial, SubscriptionLimitError, TopicForbiddenError } from './errors';
 import { subjectMatches, type Transport, type TransportSubscription } from './fanout';
 import type { JsonObject } from './json';
 import type { SocketRegistry, SyncSocket } from './socket';
@@ -46,6 +46,30 @@ export interface ChannelHubOptions {
   readonly transport: Transport;
   readonly sockets: SocketRegistry;
   readonly maxTopicsPerSocket?: number;
+  /**
+   * Distinct topics this node will bridge at once. Each one is a live transport subscription, and
+   * `topic()` admits any `[A-Za-z0-9_-]+` segment — so even a guard as tight as `org.<myorg>.>`
+   * admits unbounded distinct names inside one tenant, and a per-socket cap bounds nothing.
+   */
+  readonly maxTopicsPerNode?: number;
+}
+
+/** Distinct topics one node bridges before `X_SUBSCRIPTION_LIMIT`. */
+export const DEFAULT_MAX_TOPICS_PER_NODE = 10_000;
+
+/**
+ * One topic's fanout into this node. `sub` is the transport subscription as a PROMISE, published
+ * into the table before it is awaited: looked up before the await and written after it, two sockets
+ * reaching one topic at once opened two transport subscriptions — the second replacing the first in
+ * the table, and the first then unreachable by `#release`, by a socket dying, by `close()` or by
+ * anything else, delivering every message on that topic a second time for the life of the process.
+ *
+ * `null` means the slot is taken and nothing is open yet: the node cap is decided before the guard
+ * runs, so the reservation has to exist before there is anything to reserve it with.
+ */
+interface Bridge {
+  sub: Promise<TransportSubscription> | null;
+  refs: number;
 }
 
 /**
@@ -56,14 +80,43 @@ export class ChannelHub {
   readonly #transport: Transport;
   readonly #sockets: SocketRegistry;
   readonly #guards: Array<{ pattern: string; guard: TopicGuard }> = [];
-  readonly #bridges = new Map<string, { sub: TransportSubscription; refs: number }>();
+  readonly #bridges = new Map<string, Bridge>();
+  /**
+   * Topics this socket has asked for and not yet joined. Weakly keyed, so it needs no teardown
+   * path of its own: a socket that dies mid-subscribe takes its claims with it.
+   */
+  readonly #claimed = new WeakMap<SyncSocket, number>();
   readonly #maxTopicsPerSocket: number;
+  readonly #maxTopicsPerNode: number;
+  #guardFailures = 0;
   #sequence = 0n;
+  /** Set by `close()`. Read by `#open`, which is the only thing that can reach a late subscription. */
+  #closed = false;
 
   constructor(options: ChannelHubOptions) {
     this.#transport = options.transport;
     this.#sockets = options.sockets;
     this.#maxTopicsPerSocket = options.maxTopicsPerSocket ?? 64;
+    this.#maxTopicsPerNode = options.maxTopicsPerNode ?? DEFAULT_MAX_TOPICS_PER_NODE;
+  }
+
+  /** Sockets this node will deliver `name` to. The metric the fanout reads. */
+  subscriberCount(name: Topic): number {
+    return this.#sockets.subscriberCount(name);
+  }
+
+  /** Distinct topics bridged from this node — one live transport subscription each. */
+  get topicCount(): number {
+    return this.#bridges.size;
+  }
+
+  /**
+   * `channel.guard_failed` for this node: guards that raised instead of deciding, during a re-auth.
+   * Never a denial — the same split `LiveQueryRegistry.reauthorize` makes one layer up, and an
+   * alert fires on one of them.
+   */
+  get guardFailures(): number {
+    return this.#guardFailures;
   }
 
   /** `pattern` uses NATS wildcards: `org.*.cursors`, `org.>`. First registered match wins. */
@@ -72,36 +125,87 @@ export class ChannelHub {
     return this;
   }
 
+  /**
+   * Both caps and the node's bridge slot are taken SYNCHRONOUSLY, before the guard is awaited: read
+   * at the top and acted on after two awaits, one WebSocket write carrying N subscribe frames
+   * passed each of them N times, and `maxTopicsPerSocket`/`maxTopicsPerNode` bounded nothing.
+   */
   async subscribe(socket: SyncSocket, name: Topic): Promise<void> {
     if (socket.topics.has(name)) return;
-    if (socket.topics.size >= this.#maxTopicsPerSocket) {
+    const claimed = this.#claimed.get(socket) ?? 0;
+    if (socket.topics.size + claimed >= this.#maxTopicsPerSocket) {
       throw new SubscriptionLimitError({
         scope: 'socket',
         id: socket.id,
         limit: this.#maxTopicsPerSocket,
+        // Named, never defaulted: the default for this scope is `maxPerSocket`, which is
+        // `LiveQueryRegistry`'s cap on live subscriptions — a different ceiling in a different
+        // constructor, so an operator following this fix line would have moved the wrong number.
+        knob: 'maxTopicsPerSocket',
       });
     }
-    await this.#authorize(socket.actor, name);
-    await this.#bridge(name);
-    socket.subscribeTopic(name);
+    // Refused before the guard runs and before a transport subscription is opened: a node that is
+    // out of topics has nothing to decide, and the answer must not depend on who asked.
+    const bridge = this.#reserve(name);
+    this.#claimed.set(socket, claimed + 1);
+    try {
+      await this.#authorize(socket.actor, name);
+      await this.#open(name, bridge);
+    } catch (error) {
+      // The slot this subscribe took, given back on the one path that will never fill it.
+      this.#release(name);
+      throw error;
+    } finally {
+      const held = this.#claimed.get(socket) ?? 1;
+      if (held <= 1) this.#claimed.delete(socket);
+      else this.#claimed.set(socket, held - 1);
+    }
+    // A concurrent subscribe for this same socket and topic got there first: it holds the one
+    // membership this socket's close will give back, so the reference taken above has to go now or
+    // it is a bridge nothing will ever release.
+    if (socket.topics.has(name)) {
+      this.#release(name);
+      return;
+    }
+    // Through the registry, never `socket.subscribeTopic` directly: membership and the index the
+    // 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);
   }
 
   unsubscribe(socket: SyncSocket, name: Topic): void {
     if (!socket.topics.has(name)) return;
-    socket.unsubscribeTopic(name);
+    this.#sockets.leaveTopic(socket, name);
     this.#release(name);
   }
 
-  /** Called when a socket's session changes (login, logout, role change, token refresh). */
+  /**
+   * 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.
+   */
   async onActorChange(socket: SyncSocket, actor: Actor | null): Promise<readonly Topic[]> {
     socket.actor = actor;
     const dropped: Topic[] = [];
     for (const name of [...socket.topics] as Topic[]) {
       try {
         await this.#authorize(actor, name);
-      } catch {
-        this.unsubscribe(socket, name);
-        dropped.push(name);
+      } 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),
+        });
       }
     }
     return dropped;
@@ -120,7 +224,14 @@ export class ChannelHub {
   }
 
   async close(): Promise<void> {
-    for (const bridge of this.#bridges.values()) bridge.sub.unsubscribe();
+    // 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
+    // nothing to it and `clear()` drops the entry. That open then lands on a `Bridge` nothing can
+    // name — `#release` looks the topic up, misses and returns — and its handler keeps calling
+    // `deliver` for the life of the process. The same orphan the `Bridge` comment describes, one
+    // state earlier, so the open that creates the subscription has to be the thing that closes it.
+    this.#closed = true;
+    for (const bridge of this.#bridges.values()) unsubscribeWhenOpen(bridge);
     this.#bridges.clear();
   }
 
@@ -147,17 +258,46 @@ export class ChannelHub {
     }
   }
 
-  /** One transport subscription per topic per node, refcounted across sockets. */
-  async #bridge(name: Topic): Promise<void> {
+  /**
+   * The node's slot for this topic, taken synchronously. One bridge per topic per node, refcounted
+   * across sockets — and the refcount includes the subscribes still deciding, so the count the node
+   * cap reads is the count that will exist.
+   */
+  #reserve(name: Topic): Bridge {
     const existing = this.#bridges.get(name);
     if (existing) {
       existing.refs += 1;
-      return;
+      return existing;
+    }
+    if (this.#bridges.size >= this.#maxTopicsPerNode) {
+      throw new SubscriptionLimitError({
+        scope: 'node',
+        id: 'topics',
+        limit: this.#maxTopicsPerNode,
+        knob: 'maxTopicsPerNode',
+      });
     }
-    const sub = await this.#transport.subscribe(`${CHANNEL_SUBJECT_PREFIX}.${name}`, (payload) => {
+    const created: Bridge = { sub: null, refs: 1 };
+    this.#bridges.set(name, created);
+    return created;
+  }
+
+  /** Opens the reserved bridge once, and shares the in-flight open with everyone else waiting. */
+  async #open(name: Topic, bridge: Bridge): Promise<void> {
+    // Published into the bridge before it is awaited: that is what makes a second subscriber join
+    // this open instead of starting a second one the table can never reach again.
+    bridge.sub ??= this.#transport.subscribe(`${CHANNEL_SUBJECT_PREFIX}.${name}`, (payload) => {
       this.#sockets.deliver(name, decode(payload));
     });
-    this.#bridges.set(name, { sub, refs: 1 });
+    await bridge.sub;
+    // The hub shut down while the transport was answering. `close()` either never saw this bridge
+    // or saw it with nothing to close, so this is the last reference to the subscription: it closes
+    // here or never. The entry goes with it, so a second post-close subscribe opens and closes its
+    // own rather than double-unsubscribing this one's handle.
+    if (this.#closed) {
+      unsubscribeWhenOpen(bridge);
+      if (this.#bridges.get(name) === bridge) this.#bridges.delete(name);
+    }
   }
 
   #release(name: Topic): void {
@@ -165,11 +305,26 @@ export class ChannelHub {
     if (!bridge) return;
     bridge.refs -= 1;
     if (bridge.refs > 0) return;
-    bridge.sub.unsubscribe();
+    unsubscribeWhenOpen(bridge);
     this.#bridges.delete(name);
   }
 }
 
+/**
+ * A bridge released while its subscription is still opening still has to be closed — the transport
+ * hands the handle back after the caller has gone, and dropping the promise would leave a live
+ * subscription this node can no longer name. An open that failed has nothing to unsubscribe and its
+ * rejection was already answered to the subscriber that caused it.
+ */
+function unsubscribeWhenOpen(bridge: Bridge): void {
+  void bridge.sub?.then(
+    (sub) => {
+      sub.unsubscribe();
+    },
+    () => undefined,
+  );
+}
+
 export function channelFrame(name: Topic, lsn: string, message: JsonObject): Frame {
   return {
     type: 'patch',

package/src/client-contract.ts

@@ -0,0 +1,81 @@
+// What a client IS, as types: the injected seams, the options, and the handles a subscription
+// gives back. Declared apart from the client that implements them for the same reason
+// `live-contract.ts` is — the hooks, the typed projection, the type pins and the mutation path all
+// need these shapes, and none of them needs the connection lifecycle that runs underneath.
+
+import type { Clock } from '@ultimat3/core';
+import type { LiveCursor } from './cursor';
+import type { JsonValue, Row } from './json';
+import type { LiveState } from './live-rows';
+import type { LocalStore, LocalTx, TableMap } from './local-store';
+import type { OfflineQueue } from './offline-queue';
+import type { ConflictStrategy, RebaseLog } from './rebase';
+import type { BackoffPolicy, Rng, Scheduler } from './thundering-herd';
+
+/** Injected reactive primitive. `createSignal` from Solid satisfies this exactly. */
+export type SignalFactory = <T>(initial: T) => [get: () => T, set: (next: T) => void];
+
+/** Injected socket, so tests drive the protocol without a network. */
+export interface ClientSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onOpen(handler: () => void): void;
+  onMessage(handler: (data: string) => void): void;
+  onClose(handler: (code: number) => void): void;
+  /**
+   * Bytes queued but not yet on the wire — `WebSocket.bufferedAmount`. Optional because a socket
+   * that cannot answer is treated as never backed up; supplying it is what lets the mutation drain
+   * stop instead of pushing a queue the tab is not draining into one it cannot see.
+   */
+  readonly bufferedAmount?: number;
+}
+
+export interface LiveHandle<R extends Row = Row> extends Disposable {
+  /** The reactive accessor. In an app this is the Solid signal `useLive` returns. */
+  readonly rows: () => readonly R[];
+  readonly state: () => LiveState;
+  readonly cursor: () => LiveCursor | null;
+  unsubscribe(): void;
+  /** The same call as `unsubscribe`, so `using sub = client.useLive(...)` just works. */
+  [Symbol.dispose](): void;
+}
+
+/** What `subscribe()` returns for a tier-1 topic: callable to unsubscribe, and `using`-able too. */
+export type Unsubscribe = (() => void) & Disposable;
+
+export interface LiveQueryRef {
+  readonly name: string;
+}
+
+export interface MutatorRef<T extends TableMap = TableMap> {
+  readonly name: string;
+  /** Optimistic twin. Pure — no I/O, no Date.now(), no Math.random(). */
+  local?: (tx: LocalTx<T>, input: JsonValue) => void;
+  readonly entity?: string;
+  readonly conflict?: ConflictStrategy;
+}
+
+export interface LiveClientOptions<T extends TableMap = TableMap> {
+  readonly signal: SignalFactory;
+  /** Called for every connect attempt; returning a fresh socket keeps reconnect logic here. */
+  readonly connect: () => ClientSocket;
+  readonly buildId: string;
+  readonly actorId?: string | null;
+  /** Tier 3 only. Without these, mutations are server-only and nothing is queued offline. */
+  readonly store?: LocalStore<T>;
+  readonly queue?: OfflineQueue;
+  readonly log?: RebaseLog<T>;
+  readonly backoff?: BackoffPolicy;
+  readonly rng?: Rng;
+  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. Defaults to
+   * `DEFAULT_HEARTBEAT_MS` — the same 15s as the server's `realtime.heartbeatMs`, which browser
+   * code cannot read, so it is an option here rather than a value shipped down the wire.
+   */
+  readonly heartbeatMs?: number;
+  /** Where a dial failure inside the reconnect timer is reported. Defaults to `reportToConsole`. */
+  readonly onError?: (error: unknown) => void;
+}

package/src/client-frames.ts

@@ -0,0 +1,175 @@
+// What a RECEIVED frame does to client state — the mirror of `sync-node.ts`'s inbound handler,
+// and the only inbound surface `client.ts` exposes. `ClientFrameTarget` is the point: it names
+// 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 { advance } from './cursor';
+import type { JsonObject, JsonValue } from './json';
+import type { Registration, RowWindows } from './live-rows';
+import type { LocalStore, TableMap } from './local-store';
+import type { OfflineQueue } from './offline-queue';
+import { type RebaseLog, reconcile, rollbackMutation } from './rebase';
+import type { Frame, PresenceMember } 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';
+
+/**
+ * Everything an inbound frame is allowed to reach. Narrow on purpose — a router that took the
+ * client itself could touch the reconnect timer, the socket and the outbound path, none of which
+ * a received frame has any business writing.
+ */
+export interface ClientFrameTarget<T extends TableMap = TableMap> {
+  registration(sid: string): Registration | undefined;
+  /** The projection every live window renders through. Rows live in its map, never on a frame. */
+  readonly windows: RowWindows;
+  topicHandlers(topic: string): ReadonlySet<(message: JsonObject) => void> | undefined;
+  readonly queue: OfflineQueue | undefined;
+  readonly store: LocalStore<T> | undefined;
+  readonly log: RebaseLog<T> | undefined;
+  /** The client's clock. A cursor carries `at`, and nothing here may read `Date.now()`. */
+  now(): number;
+  /** A newer build is live; the app decides when to reload. */
+  setUpdate(buildId: string | null): void;
+  /** The node assigned this socket its own delay before closing it. */
+  scheduleReconnect(afterMs: number | null): void;
+  closeSocket(code: number, reason: string): void;
+  notifyQueueChange(): void;
+  /** Where a promise nobody awaits reports its failure. The client's `onError`, never a swallow. */
+  detach(work: Promise<unknown>): void;
+}
+
+/**
+ * The server refused a mutation: undo its optimistic half. Tier 2 has neither a store nor a log,
+ * so there is nothing optimistic to undo and the queue entry is the whole record.
+ */
+function rollbackFailed<T extends TableMap>(key: string, target: ClientFrameTarget<T>): void {
+  const store = target.store;
+  const log = target.log;
+  if (!store || !log) return;
+  // One batch for the whole undo: the rollback and every mutator replayed behind it are one
+  // frame's worth of change, so a live window holding those rows renders once.
+  store.identity.batch(() => {
+    rollbackMutation({ store, log, key });
+  });
+}
+
+/**
+ * The server took it, so the write is no longer optimistic: the journal goes (there is nothing to
+ * roll back TO any more — this write is what the server has) and the rebase entry goes with it, or
+ * every later reconcile replays a mutation the server already applied, over rows that have moved
+ * on. The row itself stays exactly as the twin left it — an accepted write does not flicker.
+ *
+ * Both calls are no-ops for a key nothing holds, which is what makes this safe as the tail of the
+ * `rebase` + `ack` pair: the rebase in front of it has already reconciled and dropped the same key.
+ */
+function commitAccepted<T extends TableMap>(key: string, target: ClientFrameTarget<T>): void {
+  target.store?.commit(key);
+  target.log?.drop(key);
+}
+
+/** Presence members cross the topic channel as plain JSON, like every other channel message. */
+function memberJson(member: PresenceMember): JsonValue {
+  return { id: member.id, actorId: member.actorId, meta: member.meta, updatedAt: member.updatedAt };
+}
+
+export function applyFrame<T extends TableMap>(frame: Frame, target: ClientFrameTarget<T>): void {
+  switch (frame.type) {
+    case 'snapshot': {
+      const registration = target.registration(frame.sid);
+      if (!registration) return;
+      // The entity is the server's, and it is what upgrades this window from its own private scope
+      // to the one every other query over the same entity shares.
+      target.windows.snapshot(registration, frame.entity ?? null, frame.rows);
+      registration.cursor = frame.cursor;
+      registration.setCursor(frame.cursor);
+      registration.setState('live');
+      return;
+    }
+    case 'patch': {
+      const registration = target.registration(frame.sid);
+      if (registration) {
+        target.windows.patch(registration, frame.patches);
+        // The cursor moves with the patches, not only with a snapshot. Left behind, `cursor.at`
+        // froze at the last snapshot and `shouldResnapshot`'s lag check answered "re-snapshot" for
+        // every client connected longer than `maxLagMs` — the delta resume the retained change
+        // window exists for, dead exactly during the deploy storm it was built for. An empty lsn
+        // is a tier-1 channel frame's, so it never rewinds one.
+        if (registration.cursor && frame.lsn !== '') {
+          const next = advance(registration.cursor, frame.patches, frame.lsn, target.now());
+          registration.cursor = next;
+          registration.setCursor(next);
+        }
+        registration.setState('live');
+        return;
+      }
+      // No registration: it is a tier-1 channel message on `sid = topic`.
+      const handlers = target.topicHandlers(frame.sid);
+      if (!handlers) return;
+      for (const patch of frame.patches) {
+        if (patch.row === null) continue;
+        for (const handler of handlers) handler(patch.row);
+      }
+      return;
+    }
+    case 'ack': {
+      const queue = target.queue;
+      // A refused mutation is not a mutation: its optimistic twin has to come off the screen, and
+      // its rebase entry has to leave the log, or a denied write stays rendered forever and every
+      // later reconcile replays it. `ref` is the mutation key — the same key the `mutate` frame
+      // carried — which is what makes both halves reachable from one frame.
+      if (frame.error) rollbackFailed(frame.ref, target);
+      else commitAccepted(frame.ref, target);
+      // `ack`/`fail` mutate the queue synchronously and persist asynchronously; chaining rather
+      // than notifying right after the call keeps this correct even if that ordering ever
+      // changes, and it still fires exactly once the persisted write actually lands.
+      const settled = frame.error ? queue?.fail(frame.ref, frame.error) : queue?.ack(frame.ref);
+      if (settled) target.detach(settled.then(() => target.notifyQueueChange()));
+      return;
+    }
+    case 'rebase': {
+      const store = target.store;
+      const log = target.log;
+      if (!store || !log) return;
+      // One batch for the whole reconcile — a rollback, server truth and every replayed mutator
+      // are one frame's worth of change, so a live window holding those rows renders once.
+      store.identity.batch(() => {
+        reconcile({
+          store,
+          log,
+          ack: {
+            key: frame.key,
+            entity: frame.entity,
+            id: frame.row?.id ?? frame.key,
+            row: frame.row,
+          },
+        });
+      });
+      return;
+    }
+    case 'reconnect': {
+      // Order is load-bearing: arming first is what makes the close this triggers keep the delay
+      // the node assigned to *this* socket instead of falling back to a local backoff.
+      target.scheduleReconnect(frame.afterMs);
+      target.closeSocket(1001, frame.reason);
+      return;
+    }
+    case 'update-available': {
+      target.setUpdate(frame.buildId);
+      return;
+    }
+    case 'presence': {
+      const handlers = target.topicHandlers(frame.topic);
+      if (!handlers) return;
+      const message: JsonObject = { op: frame.op, members: frame.members.map(memberJson) };
+      for (const handler of handlers) handler(message);
+      return;
+    }
+    case 'hello':
+    case 'subscribe':
+    case 'mutate':
+      // Client-authored frames: 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

@@ -0,0 +1,77 @@
+// The client's liveness pass: re-announce this socket before the node forgets it, and notice a
+// socket that has stopped answering. A policy (when to beat, when to give up), not a wire detail —
+// which is why it is here and not inside `client.ts`'s connection lifecycle.
+
+import type { Scheduler } from './thundering-herd';
+
+/**
+ * The same 15s as `realtime.heartbeatMs` in `@ultimat3/core`'s config, restated rather than read:
+ * that value is server configuration and this is browser code, so the client cannot reach it. The
+ * two are kept equal on purpose — a node's presence TTL is sized against this interval.
+ */
+export const DEFAULT_HEARTBEAT_MS = 15_000;
+
+export interface HeartbeatOptions {
+  /** `0` (or less) disables the pass entirely — the shape a test that owns the clock wants. */
+  readonly intervalMs: number;
+  readonly schedule: Scheduler;
+  readonly now: () => number;
+  /** Re-announces this socket. Called only while the socket is still answering. */
+  readonly beat: () => void;
+  /** Two windows of silence: the socket is half-open and only this client can end it. */
+  readonly onSilence: () => void;
+}
+
+/**
+ * One armed tick at a time, re-armed by itself. It is deliberately NOT an interval: the reconnect
+ * timer is the same injected `Scheduler` seam, and a client is either beating on a live socket or
+ * backing off towards a new one — never both, so one armed timer is the whole mechanism.
+ */
+export class Heartbeat {
+  readonly #options: HeartbeatOptions;
+  #cancel: (() => void) | null = null;
+  #lastSeen = 0;
+
+  constructor(options: HeartbeatOptions) {
+    this.#options = options;
+  }
+
+  /** 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;
+    this.#lastSeen = now;
+    this.#arm();
+  }
+
+  /** A frame arrived. Anything counts: the point is that bytes still cross in this direction. */
+  saw(now: number): void {
+    this.#lastSeen = now;
+  }
+
+  stop(): void {
+    const cancel = this.#cancel;
+    this.#cancel = null;
+    cancel?.();
+  }
+
+  #arm(): void {
+    this.#cancel = this.#options.schedule(() => {
+      this.#cancel = null;
+      this.#tick();
+    }, this.#options.intervalMs);
+  }
+
+  #tick(): void {
+    const now = this.#options.now();
+    // 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) {
+      this.#options.onSilence();
+      return;
+    }
+    this.#options.beat();
+    this.#arm();
+  }
+}