@ultimat3/realtime 23.0.0 → 25.0.0

package/src/subscription-count.ts

@@ -0,0 +1,151 @@
+// One cap that spans sockets: live subscriptions counted per KEY (a tenant, an actor), held plus
+// reserved, with the key each socket was counted under remembered. Split from
+// `subscription-book.ts` so the tenant cap and the actor cap are one mechanism, not two copies.
+
+import { SubscriptionLimitError } from './errors';
+import type { SyncSocket } from './socket';
+
+export interface CappedCountInit {
+  /** Which key a socket's subscriptions count against, or `null` for none (uncapped here). */
+  readonly principalOf: (socket: SyncSocket) => string | null;
+  /** `undefined` counts without refusing — the tenant cap's opt-out. Screened by the caller. */
+  readonly max: number | undefined;
+  readonly scope: 'tenant' | 'actor';
+  readonly knob: string;
+}
+
+/**
+ * Every question answered from a `Map`, never a scan: the cap is asked on every subscribe frame,
+ * and walking the node's subscriptions for it was one socket consuming the node.
+ */
+export class CappedCount {
+  readonly #init: CappedCountInit;
+  readonly #held = new Map<string, number>();
+  readonly #claimed = new Map<string, number>();
+  /**
+   * The key each socket's subscriptions were counted under. Remembered rather than re-derived,
+   * because `socket.actor` is replaced by a re-auth: deriving it again at `delete` time would
+   * decrement a key that was never incremented and leave the old one counting forever.
+   */
+  readonly #principalOfSocket = new Map<string, string>();
+
+  constructor(init: CappedCountInit) {
+    this.#init = init;
+  }
+
+  count(key: string): number {
+    return this.#held.get(key) ?? 0;
+  }
+
+  /** The key a socket counts under: the remembered one, or what its actor says now. */
+  principalFor(socket: SyncSocket): string | null {
+    return this.#principalOfSocket.get(socket.id) ?? this.#init.principalOf(socket);
+  }
+
+  /** Claims count: a subscribe past this check has already committed the node to its work. */
+  assert(socket: SyncSocket): void {
+    const max = this.#init.max;
+    const key = this.principalFor(socket);
+    if (max === undefined || key === null) return;
+    if (this.count(key) + (this.#claimed.get(key) ?? 0) >= max) {
+      throw new SubscriptionLimitError({
+        scope: this.#init.scope,
+        id: key,
+        limit: max,
+        knob: this.#init.knob,
+      });
+    }
+  }
+
+  /** A reservation, given back to the key that took it even if the socket re-keys meanwhile. */
+  claim(socket: SyncSocket): { readonly principal: string | null; readonly release: () => void } {
+    const key = this.principalFor(socket);
+    if (key === null) return { principal: key, release: () => undefined };
+    bump(this.#claimed, key, 1);
+    return { principal: key, release: () => bump(this.#claimed, key, -1) };
+  }
+
+  /**
+   * A subscribe reserved under `claimedPrincipal` is attaching, and its socket now counts under another
+   * key (a re-auth landed while it was in flight): it joins the new key only if that key has room —
+   * the check the new key never got at reserve time.
+   */
+  assertIfMoved(socket: SyncSocket, claimedPrincipal: string | null): void {
+    if (this.principalFor(socket) !== claimedPrincipal) this.assert(socket);
+  }
+
+  /**
+   * How many of a socket's `held` subscriptions the key it is about to move to cannot take — `0`
+   * when it is not moving or there is room. A re-auth refuses that many rather than carrying a key
+   * past its cap: moving 128 onto a principal at 1,000 was 1,128, and filling an address then
+   * signing in was a way to repeat it.
+   */
+  overflowOnRekey(socket: SyncSocket, held: number): number {
+    const max = this.#init.max;
+    const after = this.#init.principalOf(socket);
+    if (max === undefined || after === null || held === 0) return 0;
+    if (after === (this.#principalOfSocket.get(socket.id) ?? null)) return 0;
+    const room = max - this.count(after) - (this.#claimed.get(after) ?? 0);
+    return Math.max(0, held - Math.max(0, room));
+  }
+
+  /** The refusal this cap answers for the key `socket` would count under. */
+  refusalFor(socket: SyncSocket): SubscriptionLimitError {
+    return new SubscriptionLimitError({
+      scope: this.#init.scope,
+      id: this.#init.principalOf(socket) ?? 'unknown',
+      limit: this.#init.max ?? 0,
+      knob: this.#init.knob,
+    });
+  }
+
+  /** The socket closed: nothing it remembers may outlive it. */
+  forget(socketId: string): void {
+    this.#principalOfSocket.delete(socketId);
+  }
+
+  /** Sockets this cap still remembers a key for — bounded by sockets that hold a subscription. */
+  get remembered(): number {
+    return this.#principalOfSocket.size;
+  }
+
+  added(socket: SyncSocket): void {
+    const key = this.principalFor(socket);
+    if (key === null) return;
+    this.#principalOfSocket.set(socket.id, key);
+    bump(this.#held, key, 1);
+  }
+
+  /** `emptied`: the socket now holds nothing, so its remembered key goes too. */
+  deleted(socketId: string, emptied: boolean): void {
+    const key = this.#principalOfSocket.get(socketId);
+    if (key === undefined) return;
+    bump(this.#held, key, -1);
+    if (emptied) this.#principalOfSocket.delete(socketId);
+  }
+
+  /** A re-auth moved the socket to another key: its `held` subscriptions move with it. */
+  reassign(socket: SyncSocket, held: number): void {
+    // Holding nothing, there is nothing to move and nothing to remember: `keyFor` falls back to
+    // the actor's key. Stored anyway, a re-auth on an idle socket was an entry nothing deleted.
+    if (held === 0) {
+      this.#principalOfSocket.delete(socket.id);
+      return;
+    }
+    const before = this.#principalOfSocket.get(socket.id) ?? null;
+    const after = this.#init.principalOf(socket);
+    if (before === after) return;
+    if (before !== null) bump(this.#held, before, -held);
+    if (after === null) this.#principalOfSocket.delete(socket.id);
+    else {
+      this.#principalOfSocket.set(socket.id, after);
+      if (held > 0) bump(this.#held, after, held);
+    }
+  }
+}
+
+function bump(map: Map<string, number>, key: string, by: number): void {
+  const next = (map.get(key) ?? 0) + by;
+  if (next > 0) map.set(key, next);
+  else map.delete(key);
+}

package/src/sync-actor-change.ts

@@ -0,0 +1,56 @@
+// What a socket's re-decided grant does to it: the hub re-asks every channel seat under the new
+// actor (each one it drops is refused under its sid, and left in presence), and the registry
+// re-decides every live subscription. Split from `sync-node.ts` at its size ceiling.
+
+import type { Actor } from '@ultimat3/core';
+import type { ChannelHub, Topic } from './channel';
+import type { ChannelSids } from './channel-sids';
+import { detach } from './detach';
+import { TopicForbiddenError } from './errors';
+import type { LiveQueryRegistry } from './live-query';
+import { refuseSubscription } from './live-refusal';
+import type { PresenceRegistry } from './presence';
+import type { SocketRegistry } from './socket';
+
+export interface ActorChangeDeps {
+  readonly sockets: SocketRegistry;
+  readonly hub: ChannelHub;
+  readonly registry: LiveQueryRegistry;
+  readonly channelSids: ChannelSids;
+  readonly presence: PresenceRegistry | undefined;
+}
+
+/** The `onActor` a grant sweep calls once per socket whose grant was refreshed. */
+export function actorChangeHandler(
+  deps: ActorChangeDeps,
+): (socketId: string, actor: Actor) => Promise<void> {
+  const hasRoster = (name: Topic): boolean => deps.hub.channelOf(name)?.channel.events === true;
+  return async (socketId, actor) => {
+    const socket = deps.sockets.get(socketId);
+    if (!socket) return;
+    const rooms = new Set(deps.hub.topicsOf(socket).filter(hasRoster));
+    // The hub sets `socket.actor` and drops the topics this actor may no longer read; the
+    // registry re-decides every live subscription (refusing each one it drops under its sid)
+    // and desyncs the survivors, so the next delivery re-snapshots them under the new
+    // authority rather than the old window.
+    for (const name of await deps.hub.onActorChange(socket, actor)) {
+      // A dropped seat is SAID: unsaid, the client kept rendering the channel as live.
+      const sid = deps.channelSids.sidOf(socket, name);
+      deps.channelSids.delete(socket, name);
+      if (sid !== undefined) {
+        refuseSubscription(
+          socket,
+          sid,
+          new TopicForbiddenError({
+            topic: name,
+            actorId: socket.actorId,
+            reason: 'the session changed and the channel policy no longer admits it',
+          }),
+        );
+      }
+      if (deps.presence && rooms.has(name))
+        detach(deps.presence.leave(name, socket.id), 'presence.leave', name);
+    }
+    await deps.registry.reauthorize(socket);
+  };
+}

package/src/sync-auth.ts

@@ -3,6 +3,16 @@
 // holds it, and the pass that re-decides one whose window has closed.
 
 import type { Actor, Clock } from '@ultimat3/core';
+import { finiteOption } from '@ultimat3/core';
+import { GrantRefreshTimeoutError } from './errors';
+import { type Scheduler, timeoutScheduler } from './thundering-herd';
+
+/**
+ * How long one grant's `refresh()` may hold the re-auth pass. The pass is serial and one at a
+ * time, so a single call that never settles stopped every later grant on the node from being
+ * renewed OR revoked. On by default with no "off": a non-positive value takes the default.
+ */
+export const DEFAULT_GRANT_REFRESH_DEADLINE_MS = 10_000;
 
 /**
  * One connection's identity. A grant, not an `Actor`, because a websocket outlives every credential
@@ -76,8 +86,12 @@ export interface GrantSweepDeps {
   onActor: (socketId: string, actor: Actor) => Promise<void>;
   /** Nobody may hold this socket any longer. The caller closes it. */
   onRevoked: (socketId: string) => void;
-  /** `refresh` raised instead of deciding. The grant is kept and retried on the next pass. */
+  /** `refresh` raised, or did not answer in time. The grant is kept and retried on the next pass. */
   onRefreshFailed?: (socketId: string, error: unknown) => void;
+  /** See `DEFAULT_GRANT_REFRESH_DEADLINE_MS`. */
+  readonly refreshDeadlineMs?: number | undefined;
+  /** Injected so that deadline is provable without waiting for one. Production uses `setTimeout`. */
+  readonly schedule?: Scheduler | undefined;
 }
 
 export interface GrantSweepResult {
@@ -98,18 +112,29 @@ export interface GrantSweepResult {
  */
 export async function sweepGrants(deps: GrantSweepDeps): Promise<GrantSweepResult> {
   const now = deps.clock.now().getTime();
+  const declared = finiteOption(
+    'sweepGrants',
+    'refreshDeadlineMs',
+    deps.refreshDeadlineMs ?? DEFAULT_GRANT_REFRESH_DEADLINE_MS,
+  );
+  const deadlineMs = declared > 0 ? declared : DEFAULT_GRANT_REFRESH_DEADLINE_MS;
+  const schedule = deps.schedule ?? timeoutScheduler;
   let refreshed = 0;
   let revoked = 0;
   let failed = 0;
   for (const [socketId, grant] of deps.grants.expired(now)) {
     let next: SyncGrant | null;
     try {
-      next = grant.refresh ? await grant.refresh() : null;
+      next = grant.refresh ? await within(grant.refresh(), socketId, deadlineMs, schedule) : null;
     } catch (error) {
       failed += 1;
       deps.onRefreshFailed?.(socketId, error);
       continue;
     }
+    // Asked again, because `refresh` is the app's and awaiting it is awaiting a token service: the
+    // socket may have closed meanwhile (its grant deleted) or been re-granted. Written back
+    // regardless, a closed socket's grant stayed in the book and was refreshed forever.
+    if (deps.grants.get(socketId) !== grant) continue;
     if (next === null) {
       deps.grants.delete(socketId);
       deps.onRevoked(socketId);
@@ -122,3 +147,23 @@ export async function sweepGrants(deps: GrantSweepDeps): Promise<GrantSweepResul
   }
   return { refreshed, revoked, failed };
 }
+
+/**
+ * `refresh()`, or a coded timeout. The call itself cannot be cancelled and this does not pretend
+ * to: it runs on with nobody listening, and `Promise.race` keeps its late rejection handled.
+ */
+function within(
+  refreshing: Promise<SyncGrant | null>,
+  socketId: string,
+  afterMs: number,
+  schedule: Scheduler,
+): Promise<SyncGrant | null> {
+  let disarm: () => void = () => undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    disarm = schedule(() => reject(new GrantRefreshTimeoutError({ socketId, afterMs })), afterMs);
+  });
+  const settled = Promise.race([refreshing, deadline]);
+  // An armed timer per answered refresh is a leak, and keeps a draining process alive.
+  void settled.then(disarm, disarm);
+  return settled;
+}

package/src/sync-bus-handlers.ts

@@ -0,0 +1,131 @@
+// What a sync node does with the change bus: one change in, fanned to the live queries and the
+// declared channels; a gap or a reconnect, answered by invalidating both; and one producer KIND
+// per table, the other's envelopes dropped. Split out of `sync-node.ts` so the node's lifecycle
+// (start, stop, drain) stays readable in one file.
+
+import { logger } from '@ultimat3/core';
+import type { ChannelHub } from './channel';
+import { detach } from './detach';
+import type { LiveQueryRegistry } from './live-query';
+import { RealtimeError } from './realtime-error';
+import {
+  type ChangeEnvelope,
+  type EnvelopeSource,
+  parseEnvelope,
+  type SeqGapDetector,
+} from './replicator-envelope';
+
+export interface SyncBus {
+  readonly registry: LiveQueryRegistry;
+  readonly hub: ChannelHub;
+  readonly gaps: SeqGapDetector;
+  readonly producers: ProducerKinds;
+}
+
+/**
+ * The WAL replicator and a `recordPublisher` both carrying one table is every committed row twice
+ * on every channel. Logged, never thrown: the bus handler must keep serving every other table.
+ */
+export class ProducerConflictError extends RealtimeError {
+  constructor(args: { table: string; kept: EnvelopeSource; dropped: EnvelopeSource }) {
+    super({
+      code: 'X_REALTIME_PRODUCER_CONFLICT',
+      cause:
+        `table "${args.table}" is carried by the ${args.kept} and also by a ${args.dropped}, so ` +
+        `every committed row would reach its channels twice; this node keeps the ${args.kept} ` +
+        `(seen first) and drops the ${args.dropped}'s changes`,
+      // One fix for both orders: the replicator carries every entity table it can see, so the
+      // publisher is the half that can let go of one.
+      fix: `recordPublisher({ entities: [/* every entity but table ${args.table}'s */] })   # where the replicator runs: it already carries every committed row; then restart the sync node`,
+    });
+  }
+}
+
+/**
+ * Which producer kind carries each table, decided by the first envelope this node reads for it and
+ * kept for the node's life. The other kind's envelopes for that table are dropped and the conflict
+ * said once per table (`X_REALTIME_PRODUCER_CONFLICT`). The `x dev` bridge is no producer here: it
+ * delivers in-process and stands in for the replicator, skipping a claimed table itself.
+ */
+export class ProducerKinds {
+  readonly #kinds = new Map<string, EnvelopeSource>();
+  readonly #said = new Set<string>();
+
+  /** `true` when this envelope's producer kind is the one its table is carried by. */
+  admit(envelope: ChangeEnvelope): boolean {
+    const table = envelope.change.table;
+    const kind = envelope.source ?? 'replicator';
+    const kept = this.#kinds.get(table);
+    if (kept === undefined) {
+      this.#kinds.set(table, kind);
+      return true;
+    }
+    if (kept === kind) return true;
+    if (!this.#said.has(table)) {
+      this.#said.add(table);
+      const conflict = new ProducerConflictError({ table, kept, dropped: kind });
+      // FIELDS, never interpolation, and the message is the CODE alone (`pg-preflight.ts`).
+      logger.warn(conflict.code, {
+        cause: conflict.cause,
+        fix: conflict.fix,
+        table,
+        kept,
+        dropped: kind,
+      });
+    }
+    return false;
+  }
+}
+
+/** The handler a node subscribes to `CHANGE_SUBJECT_ALL` with. */
+export function changeHandler(bus: SyncBus): (payload: string) => void {
+  return (payload) => {
+    const envelope = parseEnvelope(payload);
+    if (!envelope) return;
+    // Before the gap detector: a dropped producer's sequence is no stream this node follows.
+    if (!bus.producers.admit(envelope)) return;
+    // Fanout is at-most-once over core NATS, so a reconnect is changes this node never saw.
+    // Nothing downstream could notice: no window's lsn moved, so no cursor moved, so nothing
+    // ever asked for a re-snapshot. A gap invalidates every window here instead, and the
+    // subscribers are re-served on the next change to each query.
+    const replicated = envelope.source !== 'publisher';
+    if (bus.gaps.observe(envelope)) {
+      // A publisher's lost change was never a window's (below), so only the channels re-read.
+      const marked = replicated ? bus.registry.invalidate() : 0;
+      // Channels too: their seq is minted from what this node sees, so the hole is invisible
+      // to a ring that would otherwise replay across it as complete history.
+      const channelGaps = bus.hub.invalidate();
+      logger.warn('live.change_gap', {
+        table: envelope.change.table,
+        desynced: marked,
+        channelGaps,
+      });
+    }
+    // Not awaited: the bus handler must return before the next change, and ordering is the
+    // registry's — one serial lane per query id. What this call site owes is the failure. An
+    // unhandled rejection here is a fanout that reached nobody, reported as a dead process.
+    // A publisher's change has no commit position (its lsn orders nothing across processes), and
+    // a window refuses a change below its own lsn as stale: fed one, a live query would drop rows
+    // silently. Channels mint their own seq, so they take it (`record-publisher.ts`).
+    if (replicated) {
+      detach(bus.registry.deliver(envelope.change), 'live.deliver', envelope.change.table);
+    }
+    // The same stream feeds the declared channels: a write names no channel (axiom 2), and the
+    // hub turns this change into `records` frames on every channel it touches.
+    bus.hub.deliverChange(envelope.change);
+  };
+}
+
+/**
+ * A bus that reconnected is changes this node never saw, and the gap detector only notices on the
+ * NEXT message: with no later write, every window and cursor here stayed behind and every new
+ * subscriber joined the stale window. Said by the transport, repaired now.
+ */
+export function reconnectHandler(bus: SyncBus): () => void {
+  return () => {
+    bus.gaps.forget();
+    const marked = bus.registry.invalidate();
+    const channelGaps = bus.hub.invalidate();
+    logger.warn('live.bus_reconnected', { desynced: marked, channelGaps });
+  };
+}

package/src/sync-frames.ts

@@ -5,7 +5,8 @@
 import { logger } from '@ultimat3/core';
 import type { ChannelHub } from './channel';
 import type { Topic } from './channel-decl';
-import { FrameRateLimitError } from './errors';
+import { ChannelSids } from './channel-sids';
+import { FrameRateLimitError, ProtocolVersionError } from './errors';
 import { FrameLanes, laneKeyOf } from './frame-lanes';
 import type { LiveQueryRegistry } from './live-query';
 import { type PresenceRegistry, presenceFrame } from './presence';
@@ -17,8 +18,20 @@ export interface FrameRouterOptions {
   readonly registry: LiveQueryRegistry;
   readonly buildId: string;
   readonly presence?: PresenceRegistry | undefined;
+  /** What the `hello` reply tells a client to beat at — `clientHeartbeatMs` on a real node. */
+  readonly heartbeatMs?: number | undefined;
+  /** Shared with the node, which names a seat's sid when a re-auth drops it. */
+  readonly channelSids?: ChannelSids | undefined;
 }
 
+/**
+ * The longest `sid` a subscribe frame may carry. A sid is retained — in the subscription book, in
+ * `ChannelSids`, and echoed in every ack — so its size is the client's to choose only up to here.
+ * The bundled client sends a uuid for a live query and `channel:<topic>` for a channel, so the
+ * ceiling sits well above a topic of several uuid params.
+ */
+export const MAX_SID_LENGTH = 512;
+
 export type FrameRouter = (socket: SyncSocket, frame: Frame) => Promise<void>;
 
 /**
@@ -29,26 +42,39 @@ export type FrameRouter = (socket: SyncSocket, frame: Frame) => Promise<void>;
  */
 export function ackRefOf(frame: Frame | null, socketId: string): string {
   if (frame === null) return socketId;
-  if (frame.type === 'subscribe') return frame.sid;
+  // An oversized sid is the refusal's reason, never its echo.
+  if (frame.type === 'subscribe' && frame.sid.length <= MAX_SID_LENGTH) return frame.sid;
   return socketId;
 }
 
-export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
+export function frameRouter(options: FrameRouterOptions): FrameRouter {
   const presence = options.presence;
-  /** Per socket: the topic each channel sid was joined under. Dies with the socket. */
-  const channelTopics = new WeakMap<SyncSocket, Map<string, Topic>>();
+  const channelSids = options.channelSids ?? new ChannelSids();
 
   /**
    * Subscribing to a channel declared `events: true` IS joining its presence set: presence has no
    * frame of its own (it rides that channel's `events`), so a second round trip saying "and I am
-   * here" would be a second way to do one thing. A records-only channel has no roster. Repeating the
-   * frame is therefore also the heartbeat — `join` re-`put`s the member. The roster's answer is
-   * read though nothing here can repair it: a dropped roster costs one heartbeat of blank room, and
-   * the log is the only trace it leaves anywhere.
+   * here" would be a second way to do one thing. A records-only channel has no roster.
+   *
+   * Repeating the frame is the heartbeat. A beat renews the member's TTL (`heartbeat`) instead of
+   * joining again — that was a KV put and a fleet-wide `join` event per member per beat — and is
+   * still answered with the whole roster: a presence delta is an ephemeral frame, so the roster a
+   * beat brings back is what repairs a client that lost one. A member that had already expired is
+   * joined again in full.
+   *
+   * A node built WITHOUT presence still answers: an events-only channel is sent nothing else, so
+   * unanswered its subscriber read `joining` until the first app event. The answer is the roster
+   * this node can vouch for — nobody.
    */
-  const joinPresence = async (socket: SyncSocket, name: Topic): Promise<void> => {
-    if (!presence || options.hub.channelOf(name)?.channel.events !== true) return;
-    const roster = await presence.join(name, { id: socket.id, actorId: socket.actorId });
+  const joinPresence = async (socket: SyncSocket, name: Topic, beat: boolean): Promise<void> => {
+    if (options.hub.channelOf(name)?.channel.events !== true) return;
+    const roster = !presence
+      ? { members: [], total: 0 }
+      : beat && (await presence.heartbeat(name, socket.id))
+        ? await presence.roster(name)
+        : await presence.join(name, { id: socket.id, actorId: socket.actorId });
+    // Read, though nothing here can repair it: the next beat re-sends the set, and the log is the
+    // only trace a dropped one leaves anywhere.
     if (!socket.send(presenceFrame(name, 'sync', roster.members, roster.total))) {
       logger.warn('sync.presence_roster_dropped', { topic: name, socketId: socket.id });
     }
@@ -90,6 +116,9 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
           // The actor the upgrade resolved, so a client can render who the server thinks it is
           // rather than who it thinks it sent.
           actorId: socket.actorId,
+          // The beat this node's REAL presence ttl and idle budget need. A client cannot read
+          // either, and one beating on its own default under a shorter ttl is a false leave.
+          ...(options.heartbeatMs === undefined ? {} : { heartbeatMs: options.heartbeatMs }),
         });
         if (socket.skewed) {
           socket.send({ type: 'update-available', v: PROTOCOL_VERSION, buildId: options.buildId });
@@ -97,23 +126,47 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
         return;
       }
       case 'subscribe': {
+        if (frame.sid.length > MAX_SID_LENGTH) {
+          throw new ProtocolVersionError({
+            got: PROTOCOL_VERSION,
+            expected: PROTOCOL_VERSION,
+            detail: `subscribe.sid is ${frame.sid.length} characters; the limit is ${MAX_SID_LENGTH}`,
+          });
+        }
         if (frame.target.kind === 'channel') {
-          // The topic is the DECLARATION's to spell (`channel.topic(params)`), so a drop finds it
-          // by the sid its add was answered under — never by re-deriving it from client data.
-          const topics = channelTopics.get(socket) ?? new Map<string, Topic>();
-          channelTopics.set(socket, topics);
           if (frame.op === 'drop') {
-            const name = topics.get(frame.sid);
+            // The topic is the DECLARATION's to spell (`channel.topic(params)`), so a drop finds
+            // it by the sid its add was answered under — never by re-deriving it from client data.
+            const name = channelSids.topicOf(socket, frame.sid);
             if (name === undefined) return;
-            topics.delete(frame.sid);
+            channelSids.delete(socket, name);
             const events = options.hub.channelOf(name)?.channel.events === true;
             options.hub.unsubscribe(socket, name);
             if (presence && events) await presence.leave(name, socket.id);
             return;
           }
-          const name = await options.hub.subscribeChannel(socket, frame.target);
-          topics.set(frame.sid, name);
-          await joinPresence(socket, name);
+          // A seat this sid already names may be DENIED by this ask (a suspended seat re-decided):
+          // the hub drops it, and the sid and the presence member must not outlive it.
+          const held = channelSids.topicOf(socket, frame.sid);
+          const room = held !== undefined && options.hub.channelOf(held)?.channel.events === true;
+          let name: Topic;
+          try {
+            name = await options.hub.subscribeChannel(socket, frame.target);
+          } catch (error) {
+            if (held !== undefined && !options.hub.topicsOf(socket).includes(held)) {
+              channelSids.delete(socket, held);
+              if (presence && room) await presence.leave(held, socket.id);
+            }
+            throw error;
+          }
+          // Not seated: the socket died while the guard was answering (a presence member written
+          // now is one no close will ever remove), or the seat is SUSPENDED — its guard could not
+          // decide — and a roster is exactly the delivery a suspension withholds.
+          if (socket.closed || !socket.topics.has(name)) return;
+          // A seat this socket already held makes the frame its beat, never a second join.
+          const beat = channelSids.sidOf(socket, name) !== undefined;
+          channelSids.set(socket, name, frame.sid);
+          await joinPresence(socket, name, beat);
           return;
         }
         if (frame.op === 'drop') {

package/src/sync-node-bounds.ts

@@ -6,6 +6,7 @@
 // reads false — so `maxConnections: NaN` is a node that accepts without limit and says nothing.
 
 import { finiteOption } from '@ultimat3/core';
+import { DEFAULT_HEARTBEAT_MS } from './client-heartbeat';
 
 const SUBJECT = 'the sync node';
 
@@ -81,7 +82,7 @@ export function syncNodeBounds(options: SyncNodeNumericOptions): SyncNodeBounds
  * that `SyncSocket` — not this module — owns the default of.
  *
  * They were screened only in `SyncSocket`'s constructor, which Bun runs inside `websocket.open`,
- * which Bun runs SYNCHRONOUSLY inside `server.upgrade`. Measured: `createSyncNode` did not throw,
+ * which Bun runs SYNCHRONOUSLY inside `server.upgrade`. Measured: `syncNode` did not throw,
  * `/healthz` and `/readyz` both answered, `ready` was true, and every upgrade threw `X_INVARIANT`
  * with the node holding zero sockets — a misconfiguration that fails per connection instead of at
  * boot, and each of those throws leaked the grant `handleUpgrade` records before the upgrade.
@@ -127,3 +128,17 @@ export function socketCeilings(options: SocketCeilings): SocketCeilings {
 /** Per CALL, not per node: `drain({ graceMs })` is an argument, so it is refused where it arrives. */
 export const drainGraceMs = (graceMs: number | undefined): number =>
   finiteOption('the sync node drain', 'graceMs', graceMs ?? DEFAULT_DRAIN_GRACE_MS);
+
+/**
+ * The beat a client is TOLD (`hello.heartbeatMs`): a third of the node's real presence ttl, so one
+ * lost beat is never a false leave — and never slower than a quarter of the idle budget, or a
+ * long ttl would have this node evict a healthy socket for the silence it asked for. With no
+ * presence there is no ttl, and the client's own default is the starting point.
+ */
+export function clientHeartbeatMs(
+  presenceBeatMs: number | undefined,
+  idleTimeoutMs: number,
+): number {
+  const idleBound = Math.max(1_000, Math.floor(idleTimeoutMs / 4));
+  return Math.min(presenceBeatMs ?? DEFAULT_HEARTBEAT_MS, idleBound);
+}