@ultimat3/realtime 22.15.0 → 24.0.0

package/src/socket-engine.ts

@@ -173,6 +173,9 @@ export class SocketEngine {
     switch (frame.type) {
       case 'hello':
         this.#hello = frame;
+        // The node names the beat. Every tab hears the same number on its next beat (this frame is
+        // what `#helloReply` answers with), so the socket and the ports keep one rhythm.
+        if (frame.heartbeatMs !== undefined) this.#heartbeat.follow(frame.heartbeatMs);
         return;
       case 'snapshot':
       case 'patch':
@@ -301,12 +304,21 @@ export class SocketEngine {
     if (this.#reaper !== null) return;
     this.#reaper = this.#schedule(() => {
       this.#reaper = null;
-      const cutoff = this.#now() - REAP_AFTER_BEATS * this.#beatMs;
+      const cutoff = this.#now() - REAP_AFTER_BEATS * this.#portBeatMs();
       for (const attached of [...this.#ports.values()]) {
         if (attached.lastSeen < cutoff) this.#reap(attached);
       }
       if (this.#ports.size > 0) this.#armReaper();
-    }, this.#beatMs);
+    }, this.#portBeatMs());
+  }
+
+  /**
+   * The slowest a healthy tab can be beating: its own default until it hears the node's `hello`,
+   * the node's figure after. The LONGER of the two — a tab is never reaped for keeping a beat the
+   * node asked for, nor for not having heard a shorter one yet.
+   */
+  #portBeatMs(): number {
+    return Math.max(this.#beatMs, this.#heartbeat.intervalMs);
   }
 
   #beat(): void {

package/src/socket-idle.ts

@@ -6,7 +6,9 @@
  * inactivity budget and not Bun's transport one: Bun's `idleTimeout` is renewed by its own
  * ping/pong, so a client whose TCP stack still answers pings while its frame loop is wedged holds
  * its grant, its subscriptions and its topic membership forever. A beating client sends a `hello`
- * every `DEFAULT_HEARTBEAT_MS` (15s), so this is eight missed beats.
+ * every `DEFAULT_HEARTBEAT_MS` (10s), so this is twelve missed beats — and it stays a multiple of
+ * the beat whatever either is set to: the node TELLS the client its beat (`hello.heartbeatMs`),
+ * never slower than a quarter of this budget (`clientHeartbeatMs`, `sync-node-bounds.ts`).
  */
 export const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 

package/src/socket-routes.ts

@@ -122,9 +122,14 @@ export class PortRouter {
     }
     if (held.ports.has(attached.id)) return;
     held.ports.add(attached.id);
-    // The node never hears this add, so it cannot answer it with the `replay-gap` a fresh seat
-    // gets; the engine does. With no epoch yet, the node's own answer is still on its way and now
-    // reaches this port too.
+    // Forwarded as a BEAT (no `since`): to the node it is the seat it already holds, repeated, and
+    // what a seated socket is answered with is the room's roster — the only frame an events-only
+    // channel ever gets, so unforwarded this tab read `joining` until the next beat, and with no
+    // presence on the node, until the first app event.
+    this.#deps.send(withoutSince(held.add));
+    // A beat is never answered with the `replay-gap` a fresh seat gets, so the engine says it.
+    // With no epoch yet, the node's own answer to the first add is on its way and reaches this
+    // port too.
     if (held.epoch === null) return;
     const gap: Frame = {
       type: 'replay-gap',

package/src/subscriber-gate.ts

@@ -7,6 +7,7 @@ import type { Actor } from '@ultimat3/core';
 import { isPolicyDenial } from './errors';
 import type { JsonValue, Row, RowPatch } from './json';
 import type { LiveQueryDefinition } from './live-contract';
+import { narrowRow, projectionOf } from './matcher-bridge';
 
 /**
  * Who a decision is being made for. Every policy call in the live pipeline takes one, which is the
@@ -219,7 +220,16 @@ export class SubscriberGate {
     // subscriber is not entitled to keep, and one that holds it is told so.
     if (full === undefined) return holds ? withdrawn(patch) : null;
     const row: Row = { ...full, ...patch.row, id: patch.id };
-    if (await this.#visible(target, who, row, 'patch')) return patch;
+    if (await this.#visible(target, who, row, 'patch')) {
+      // An update carries the changed columns only. A subscriber who was never sent this row —
+      // denied at its snapshot, admitted by this change — would fold them onto nothing, and its
+      // cursor would never record the id, so the row's later delete was withheld from it. It gets
+      // the whole row as an insert, which is also what makes `Holding` and `advance` count it.
+      if (patch.op === 'update' && !holds) {
+        return { ...patch, op: 'insert', row: narrowRow(row, projectionOf(target.rows)) };
+      }
+      return patch;
+    }
     this.#denied(target.qid, who, patch.id);
     return holds ? withdrawn(patch) : null;
   }

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-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 {
   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';
 
@@ -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);
+}

package/src/sync-node-contract.ts

@@ -54,11 +54,29 @@ export interface SyncNodeOptions {
    */
   readonly authenticate?: SyncAuthenticator;
   /**
-   * Exact origins a page may open a socket from, besides this node's own host name — the page's
-   * origin when it is served on another host (`SYNC_URL` on a separate domain). Anything else is
+   * Exact origins a page may open a socket from — the app's public origin (`APP_URL`). Declared,
+   * they are the WHOLE list; with none, the node admits the origin it was reached on (its `Host`
+   * and port, and that host's https spelling when reached over plain http). Anything else is
    * refused `X_SOCKET_ORIGIN_REFUSED` before `authenticate` runs.
    */
   readonly allowedOrigins?: readonly string[];
+  /**
+   * Also admit the origin the node was reached on BESIDE a declared list. For a loopback dev
+   * server reached through a forwarded host; never a container, where `Host` is the caller's.
+   */
+  readonly admitReachedOrigin?: boolean;
+  /**
+   * Peers this node's own `/healthz` and `/readyz` tell the whole report to: address classes
+   * (`loopback`, `private`, …) or exact IP literals — the app's `http.healthDetailPeers`. Defaults
+   * to core's `DEFAULT_HEALTH_DETAIL_PEERS` (the box itself); anyone else, and any request that
+   * says it was forwarded, gets `{ state, ready, role }`.
+   */
+  readonly healthDetailPeers?: readonly string[];
+  /**
+   * How long one grant's `refresh()` may hold the re-auth pass before it is reported and skipped
+   * (`DEFAULT_GRANT_REFRESH_DEADLINE_MS`). The grant stays expired and is asked again next pass.
+   */
+  readonly grantRefreshDeadlineMs?: number;
   /** How often an expired grant is re-decided. The clock a socket's authority runs on. */
   readonly reauthenticateIntervalMs?: number;
   readonly clock?: Clock;

package/src/sync-node.ts

@@ -4,18 +4,33 @@
 // client may reconnect to any node and resume from its cursor, which is why drain is allowed to
 // redistribute connections at all.
 
-import { logger, markReady, reportError, systemClock, uuid } from '@ultimat3/core';
+import {
+  DEFAULT_HEALTH_DETAIL_PEERS,
+  logger,
+  markReady,
+  reportError,
+  systemClock,
+  uuid,
+} from '@ultimat3/core';
 import type { Topic } from './channel';
+import { ChannelSids } from './channel-sids';
 import { detach } from './detach';
 import { evictInChunks } from './drain-evictions';
-import { isClientFault } from './errors';
+import { isClientFault, TopicForbiddenError } from './errors';
 import type { TransportSubscription } from './fanout';
-import { CHANGE_SUBJECT_ALL, parseEnvelope, SeqGapDetector } from './replicator';
+import { refuseSubscription } from './live-refusal';
+import { CHANGE_SUBJECT_ALL } from './replicator';
+import { parseEnvelope, SeqGapDetector } from './replicator-envelope';
 import { CLOSE, DEFAULT_MAX_BUFFERED_BYTES, SocketRegistry, SyncSocket } from './socket';
 import { idleSweepPeriodMs } from './socket-idle';
 import { GrantBook, sweepGrants } from './sync-auth';
 import { ackRefOf, createFrameRouter } from './sync-frames';
-import { drainGraceMs, socketCeilings, syncNodeBounds } from './sync-node-bounds';
+import {
+  clientHeartbeatMs,
+  drainGraceMs,
+  socketCeilings,
+  syncNodeBounds,
+} from './sync-node-bounds';
 import type { SyncNode, SyncNodeOptions, SyncWs } from './sync-node-contract';
 import { decode, type Frame, PROTOCOL_VERSION, toWireError } from './sync-protocol';
 import { handleUpgrade, type UpgradeTarget } from './sync-upgrade';
@@ -52,6 +67,10 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
   const presence = options.presence;
   const grants = new GrantBook();
   const gaps = new SeqGapDetector();
+  const channelSids = new ChannelSids();
+  let reconnects: (() => void) | null = null;
+  /** The re-auth pass in flight, shared by every tick that lands while it runs. */
+  let reauthPass: Promise<void> | null = null;
   let ready = false;
   /** Resolved by `teardown` when the last socket leaves, for a drain that is waiting its grace. */
   let lastSocketLeft: (() => void) | null = null;
@@ -71,6 +90,8 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
   const release = (): void => {
     changes?.unsubscribe();
     changes = null;
+    reconnects?.();
+    reconnects = null;
     if (sweeping !== null) clearInterval(sweeping);
     sweeping = null;
     if (reauthing !== null) clearInterval(reauthing);
@@ -91,7 +112,10 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
    */
   const teardown = (socket: SyncSocket): readonly Promise<unknown>[] => {
     options.registry.unsubscribeSocket(socket.id);
-    const topics = [...socket.topics] as Topic[];
+    // Suspended seats included, and the presence rooms read BEFORE the seats are given back: the
+    // hub forgets a topic's declaration with its last member.
+    const topics = options.hub.topicsOf(socket);
+    const rooms = topics.filter(hasRoster);
     for (const name of topics) options.hub.unsubscribe(socket, name);
     sockets.remove(socket.id);
     grants.delete(socket.id);
@@ -101,7 +125,9 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     // bus and the close callback is synchronous, so it cannot be awaited here.
     const leaves: Promise<unknown>[] = [];
     if (presence) {
-      for (const name of topics) {
+      // Only a channel declared `events: true` has a roster: a leave on any other was a KV read,
+      // a KV write and a presence event on a channel that never carried one.
+      for (const name of rooms) {
         const leave = presence.leave(name, socket.id);
         // Detached as well as returned: `detach` attaches the reporting catch, so a caller that
         // awaits this later is awaiting a promise whose rejection is already handled.
@@ -130,6 +156,11 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       lastSocketLeft = done;
     });
 
+  /** Whether this topic's channel carries presence — asked while the hub still knows the topic. */
+  function hasRoster(name: Topic): boolean {
+    return options.hub.channelOf(name)?.channel.events === true;
+  }
+
   const evict = (socket: SyncSocket, code: number, reason: string): readonly Promise<unknown>[] => {
     socket.close(code, reason);
     return teardown(socket);
@@ -141,17 +172,47 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
    * was authorized for as long as it stayed open — and an active client's socket never idles out,
    * because every inbound frame touches it.
    */
-  const reauthenticate = async (): Promise<void> => {
+  const reauthenticate = (): Promise<void> => {
+    // One pass at a time. The interval does not wait for the pass it started: after a deploy every
+    // grant expires in one window, a pass over them can outlast the interval, and each overlapping
+    // tick then refreshed the same grants again and re-snapshotted the same subscriptions.
+    reauthPass ??= reauthPassOnce().finally(() => {
+      reauthPass = null;
+    });
+    return reauthPass;
+  };
+
+  const reauthPassOnce = async (): Promise<void> => {
     await sweepGrants({
       grants,
       clock,
+      refreshDeadlineMs: options.grantRefreshDeadlineMs,
       onActor: async (socketId, actor) => {
         const socket = sockets.get(socketId);
         if (!socket) return;
+        const rooms = new Set(options.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 and desyncs the survivors, so the next
-        // delivery re-snapshots them under the new authority rather than the old window.
-        await options.hub.onActorChange(socket, actor);
+        // 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 options.hub.onActorChange(socket, actor)) {
+          // A dropped seat is SAID: unsaid, the client kept rendering the channel as live.
+          const sid = channelSids.sidOf(socket, name);
+          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 (presence && rooms.has(name))
+            detach(presence.leave(name, socket.id), 'presence.leave', name);
+        }
         await options.registry.reauthorize(socket);
       },
       onRevoked: (socketId) => {
@@ -180,6 +241,8 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     registry: options.registry,
     buildId: options.buildId,
     presence,
+    channelSids,
+    heartbeatMs: clientHeartbeatMs(presence?.heartbeatMs, sockets.idleTimeoutMs),
   });
 
   return {
@@ -200,7 +263,14 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
         // subscribers are re-served on the next change to each query.
         if (gaps.observe(envelope)) {
           const marked = options.registry.invalidate();
-          logger.warn('live.change_gap', { entity: envelope.change.entity, desynced: marked });
+          // 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 = options.hub.invalidate();
+          logger.warn('live.change_gap', {
+            entity: envelope.change.entity,
+            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
@@ -210,6 +280,15 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
         // hub turns this change into `records` frames on every channel it touches.
         options.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.
+      reconnects = options.transport.onReconnect(() => {
+        gaps.forget();
+        const marked = options.registry.invalidate();
+        const channelGaps = options.hub.invalidate();
+        logger.warn('live.bus_reconnected', { desynced: marked, channelGaps });
+      });
       // One pass per heartbeat window: a member is swept only once it has actually missed its
       // window, and the interval never holds the process open — shutdown is the drain's job.
       if (presence) {
@@ -270,6 +349,8 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           newSocketId: () => uuid(),
           authenticate: options.authenticate,
           allowedOrigins: options.allowedOrigins,
+          admitReachedOrigin: options.admitReachedOrigin,
+          healthDetailPeers: options.healthDetailPeers ?? DEFAULT_HEALTH_DETAIL_PEERS,
           onGranted: (socketId, grant) => grants.set(socketId, grant),
           // The other half of recording the grant before the upgrade: an upgrade that never took
           // gets no `close` callback, so this is the only thing that can free its entry.
@@ -403,9 +484,3 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     },
   };
 }
-
-/**
- * An upgrade refused before a socket exists, rendered as the error contract rather than as a word.
- * There is no frame to carry it — the client never got a connection — so the body is the only
- * channel, and `--json` on every error means this one too.
- */

package/src/sync-origin.ts

@@ -1,7 +1,7 @@
 // Single responsibility: whether a websocket upgrade may carry this app's ambient credential. No
-// CORS applies to a websocket and the session cookie rides it, so without this a page on a sibling
-// host (same-site, so `SameSite=Lax` does not stop it) opened a socket as its visitor. The rule is
-// core's `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks too.
+// CORS applies to a websocket and the session cookie rides it, so without this a page that is not
+// this app opened a socket as its visitor. The rule is core's `proveSameOrigin`, the one
+// `@ultimat3/http`'s CSRF check asks too.
 
 import { type OriginVerdict, proveSameOrigin } from '@ultimat3/core';
 
@@ -9,25 +9,40 @@ import { type OriginVerdict, proveSameOrigin } from '@ultimat3/core';
  * Admitted, in order:
  * - **no `Origin`** — RFC 6455 has a browser send one on every handshake, so a dial without it is
  *   not a browser and no visitor's cookie can be riding it;
- * - **the node's own host name**, whatever the port or scheme — cookies are not port-isolated, so
- *   the page on `:3000` dialling the Compose rung's `:3001` is the same credential boundary, and a
- *   TLS-terminating ingress means the node cannot know the page's scheme;
- * - otherwise core's rule, with `allowedOrigins` as the exact list (`APP_URL`'s origin, from the
- *   CLI, when the page is served on another host than the node).
+ * - **`allowedOrigins`, exactly, when any is declared** (`APP_URL`'s origin, from the CLI). A
+ *   declaration IS the app's origin, so it is the whole list: the origin the node sees is derived
+ *   from the `Host` header, which names whatever host the request was aimed at — a sibling
+ *   subdomain pointed at this node is "its own origin" by that reading, and a `Domain=`-wide
+ *   session cookie rides its socket;
+ * - **the node's own ORIGIN, only when nothing is declared** — host and port exactly as the
+ *   request reached it (`x dev`, a combined-role container). A host name alone is not this app:
+ *   cookies are not isolated by port. `admitReached` keeps it beside a declared list (`x dev`).
  */
 export function upgradeOrigin(
   request: Request,
   url: URL,
   allowedOrigins: readonly string[],
+  admitReached = false,
 ): OriginVerdict {
   const origin = request.headers.get('origin');
   if (origin === null) return { ok: true };
-  if (URL.parse(origin)?.hostname === url.hostname) return { ok: true };
+  // Normalised once (`https://x/` and `https://x` are one origin), then matched as whole strings.
+  const admitted = allowedOrigins.map((allowed) => URL.parse(allowed)?.origin);
   return proveSameOrigin({
-    selfOrigins: allowedOrigins,
+    selfOrigins: admitted.length > 0 && !admitReached ? [] : selfOrigins(url),
     origin,
     secFetchSite: request.headers.get('sec-fetch-site'),
-    listed: () => false,
+    listed: (asked) => admitted.includes(asked),
     listName: 'APP_URL or createSyncNode({ allowedOrigins })',
   });
 }
+
+/**
+ * The origins an UNDECLARED node is reached on. TLS usually ends at a proxy, so a node reached over
+ * plain http cannot know its pages' scheme: the https spelling of the same host and port is this
+ * app too. That also admits the plain-http page, which is why a deployment behind TLS declares
+ * `APP_URL` — the chart sets it from the ingress host.
+ */
+function selfOrigins(url: URL): readonly string[] {
+  return url.protocol === 'http:' ? [url.origin, `https://${url.host}`] : [url.origin];
+}