@ultimat3/realtime 20.2.1 → 21.0.0

package/src/socket-engine.ts

@@ -0,0 +1,332 @@
+// The socket engine (plan 101, slice 11): ONE sync socket shared by every tab of an origin and
+// principal, talking to each tab only over a `MessagePort`. Host-agnostic — the SharedWorker entry
+// and the in-page fallback run this same code. Each tab keeps its own `LiveClient` and store; to
+// it, its port IS a socket. This file is the socket's lifecycle — dial, beat, redial, reap; the
+// multiplexing (one membership per topic, frames routed per port) is `socket-routes.ts`.
+
+import { type Clock, finiteOption, systemClock } from '@ultimat3/core/page';
+import type { ClientSocket } from './client-contract';
+import { DEFAULT_HEARTBEAT_MS, Heartbeat } from './client-heartbeat';
+import type { SyncTarget } from './page-store';
+import type { AttachedPort, PortLike, PortMessage } from './socket-port';
+import { PortRouter } from './socket-routes';
+import { decode, encode, type Frame, PROTOCOL_VERSION } from './sync-protocol';
+import {
+  type BackoffPolicy,
+  backoffDelay,
+  browserBackoff,
+  type Rng,
+  type Scheduler,
+  timeoutScheduler,
+} from './thundering-herd';
+
+// The port seam is its own module; these are the names every host already imports from here.
+export { messagePort, type PortLike, type PortMessage } from './socket-port';
+
+export interface SocketEngineOptions {
+  /** Dials the real socket. Production: `browserSocket(dialUrl(target))`. */
+  readonly dial: (target: SyncTarget) => ClientSocket;
+  readonly scheduler?: Scheduler;
+  readonly clock?: Clock;
+  readonly backoff?: BackoffPolicy;
+  readonly rng?: Rng;
+  /** The engine's own beat on the real socket, and the unit a silent port is reaped in. */
+  readonly heartbeatMs?: number;
+}
+
+/** A tab beats every heartbeat; three missed beats and its port is reaped — a tab has no close. */
+export const REAP_AFTER_BEATS = 3;
+
+export class SocketEngine {
+  readonly #options: SocketEngineOptions;
+  readonly #clock: Clock;
+  readonly #schedule: Scheduler;
+  readonly #beatMs: number;
+  readonly #ports = new Map<number, AttachedPort>();
+  readonly #router: PortRouter;
+  readonly #heartbeat: Heartbeat;
+  #next = 1;
+  #target: SyncTarget | null = null;
+  #socket: ClientSocket | null = null;
+  #up = false;
+  #attempt = 0;
+  #reconnect: (() => void) | null = null;
+  #reaper: (() => void) | null = null;
+  #hello: Frame | null = null;
+  #update: string | null = null;
+
+  constructor(options: SocketEngineOptions) {
+    this.#options = options;
+    this.#clock = options.clock ?? systemClock;
+    this.#schedule = options.scheduler ?? timeoutScheduler;
+    this.#beatMs = finiteOption(
+      'SocketEngine',
+      'heartbeatMs',
+      options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+    );
+    this.#heartbeat = new Heartbeat({
+      intervalMs: this.#beatMs,
+      schedule: this.#schedule,
+      now: () => this.#now(),
+      beat: () => this.#beat(),
+      onSilence: () => this.#lost(),
+    });
+    this.#router = new PortRouter({
+      send: (frame) => this.#send(frame),
+      post: (attached, message) => this.#post(attached, message),
+      port: (id) => this.#ports.get(id),
+      ports: () => this.#ports.values(),
+    });
+  }
+
+  /** Ports attached right now. Tests and the worker's own diagnostics read it. */
+  get ports(): number {
+    return this.#ports.size;
+  }
+
+  attach(port: PortLike): void {
+    const attached: AttachedPort = {
+      id: this.#next++,
+      port,
+      open: false,
+      asked: false,
+      lastSeen: this.#now(),
+      topics: new Set(),
+      lives: new Map(),
+    };
+    this.#ports.set(attached.id, attached);
+    port.onmessage = (event) => this.#fromPort(attached, event.data);
+    this.#armReaper();
+  }
+
+  #fromPort(attached: AttachedPort, message: unknown): void {
+    if (!this.#ports.has(attached.id) || typeof message !== 'object' || message === null) return;
+    attached.lastSeen = this.#now();
+    const typed = message as PortMessage;
+    if (typed.t === 'open') {
+      const arriving = !attached.asked;
+      attached.open = true;
+      attached.asked = true;
+      this.#target ??= typed.target;
+      if (this.#up) {
+        this.#post(attached, { t: 'open', target: typed.target });
+        return;
+      }
+      // A page arriving is a fresh reason to believe the node is back (a reload, a deploy): the
+      // wait an earlier page's failures built up is not this page's to inherit.
+      if (arriving && this.#socket === null) this.#restartCurve();
+      this.#dial();
+      return;
+    }
+    if (typed.t === 'close') {
+      // The tab closed its virtual socket — a redial on the same port. Its wants go; the port stays.
+      this.#router.release(attached);
+      attached.open = false;
+      return;
+    }
+    if (typed.t === 'bye') {
+      this.#detach(attached);
+      return;
+    }
+    if (typed.t === 'frame' && this.#up) this.#fromTab(attached, typed.data);
+  }
+
+  #fromTab(attached: AttachedPort, data: string): void {
+    let frame: Frame;
+    try {
+      frame = decode(data);
+    } catch {
+      return;
+    }
+    if (frame.type === 'hello') {
+      // The tab's beat is this engine's ping: answer it, and add the one thing a beat learns.
+      this.#post(attached, { t: 'frame', data: encode(this.#helloReply()) });
+      if (this.#update !== null) {
+        const update: Frame = {
+          type: 'update-available',
+          v: PROTOCOL_VERSION,
+          buildId: this.#update,
+        };
+        this.#post(attached, { t: 'frame', data: encode(update) });
+      }
+      return;
+    }
+    if (frame.type === 'subscribe') this.#router.subscribe(attached, frame);
+  }
+
+  /** Release the port itself: a tab that said `bye`, or one silent for three beats. */
+  #detach(attached: AttachedPort): void {
+    if (!this.#ports.delete(attached.id)) return;
+    this.#router.release(attached);
+    attached.port.onmessage = null;
+    attached.port.close?.();
+    if (this.#ports.size === 0) this.#shutdown();
+  }
+
+  #fromServer(data: string): void {
+    let frame: Frame;
+    try {
+      frame = decode(data);
+    } catch {
+      return;
+    }
+    switch (frame.type) {
+      case 'hello':
+        this.#hello = frame;
+        return;
+      case 'snapshot':
+      case 'patch':
+      case 'ack':
+      case 'records':
+      case 'replay-gap':
+      case 'events':
+        this.#router.route(frame, data);
+        return;
+      case 'update-available':
+        this.#update = frame.buildId;
+        for (const attached of this.#ports.values()) this.#post(attached, { t: 'frame', data });
+        return;
+      case 'reconnect':
+        // The node assigned this socket its slot in a drain spread: honour it, once, for everyone.
+        this.#lost(frame.afterMs);
+        return;
+      case 'subscribe':
+        return;
+    }
+  }
+
+  #dial(): void {
+    if (this.#socket !== null || this.#reconnect !== null || this.#target === null) return;
+    const target = this.#target;
+    let socket: ClientSocket;
+    try {
+      socket = this.#options.dial(target);
+    } catch {
+      this.#scheduleReconnect(null);
+      return;
+    }
+    this.#socket = socket;
+    socket.onOpen(() => {
+      if (this.#socket !== socket) return;
+      this.#up = true;
+      this.#attempt = 0;
+      socket.send(encode(this.#ownHello()));
+      this.#heartbeat.start(this.#now());
+      for (const attached of this.#ports.values()) {
+        if (attached.open) this.#post(attached, { t: 'open', target });
+      }
+    });
+    socket.onMessage((data) => {
+      if (this.#socket !== socket) return;
+      this.#heartbeat.saw(this.#now());
+      this.#fromServer(data);
+    });
+    socket.onClose(() => {
+      if (this.#socket !== socket) return;
+      this.#lost();
+    });
+  }
+
+  /**
+   * The real socket is gone. Every tab's virtual socket closes with it, and each tab's own client
+   * re-opens and resubscribes FROM ITS CURSORS — the engine keeps no subscription state across a
+   * reconnect, so there is nothing here to go stale.
+   */
+  #lost(afterMs: number | null = null): void {
+    const socket = this.#socket;
+    this.#socket = null;
+    this.#up = false;
+    this.#heartbeat.stop();
+    socket?.close(1000, 'engine reconnect');
+    this.#router.clear();
+    for (const attached of this.#ports.values()) {
+      if (attached.open) this.#post(attached, { t: 'close', code: 1006 });
+      attached.open = false;
+    }
+    if (this.#ports.size > 0) this.#scheduleReconnect(afterMs);
+  }
+
+  #scheduleReconnect(afterMs: number | null): void {
+    if (this.#reconnect !== null) return;
+    const rng = this.#options.rng ?? Math.random;
+    const delay =
+      afterMs ?? backoffDelay(this.#attempt, this.#options.backoff ?? browserBackoff, rng);
+    this.#attempt += 1;
+    this.#reconnect = this.#schedule(() => {
+      this.#reconnect = null;
+      // Dialled only for a tab that is asking: a tab re-asks through its own client's timer.
+      if ([...this.#ports.values()].some((attached) => attached.open)) this.#dial();
+    }, delay);
+  }
+
+  #restartCurve(): void {
+    this.#reconnect?.();
+    this.#reconnect = null;
+    this.#attempt = 0;
+  }
+
+  /**
+   * No page left. A SharedWorker can outlive its last page for a moment and be handed the next
+   * one, so NOTHING a page brought survives here: not the curve, and not the target — a page of
+   * the next build would otherwise dial with the old build id and be told to update forever.
+   */
+  #shutdown(): void {
+    this.#restartCurve();
+    this.#target = null;
+    this.#hello = null;
+    this.#update = null;
+    this.#reaper?.();
+    this.#reaper = null;
+    const socket = this.#socket;
+    this.#socket = null;
+    this.#up = false;
+    this.#heartbeat.stop();
+    socket?.close(1000, 'no tab left');
+  }
+
+  /** A `MessagePort` has no close event: a port silent for three beats is a closed tab. */
+  #armReaper(): void {
+    if (this.#reaper !== null) return;
+    this.#reaper = this.#schedule(() => {
+      this.#reaper = null;
+      const cutoff = this.#now() - REAP_AFTER_BEATS * this.#beatMs;
+      for (const attached of [...this.#ports.values()]) {
+        if (attached.lastSeen < cutoff) this.#detach(attached);
+      }
+      if (this.#ports.size > 0) this.#armReaper();
+    }, this.#beatMs);
+  }
+
+  #beat(): void {
+    this.#send(this.#ownHello());
+    this.#router.announce();
+  }
+
+  /** What this engine says to the node: the build every tab of it was rendered by. */
+  #ownHello(): Frame {
+    return {
+      type: 'hello',
+      v: PROTOCOL_VERSION,
+      buildId: this.#target?.buildId ?? '',
+      sessionId: null,
+      actorId: null,
+    };
+  }
+
+  /** What a tab's beat is answered with: the node's own hello once there is one. */
+  #helloReply(): Frame {
+    return this.#hello ?? this.#ownHello();
+  }
+
+  #send(frame: Frame): void {
+    if (this.#up) this.#socket?.send(encode(frame));
+  }
+
+  #post(attached: AttachedPort, message: PortMessage): void {
+    attached.port.postMessage(message);
+  }
+
+  #now(): number {
+    return this.#clock.now().getTime();
+  }
+}

package/src/socket-host.ts

@@ -0,0 +1,126 @@
+// The tab side of the page's one socket (plan 101, slice 11): pick the host — a `SharedWorker`
+// shared by every tab of this origin and principal, or the in-page engine when there is none —
+// and hand the tab's `LiveClient` a socket that is really a `MessagePort`. One engine, one
+// protocol, under both hosts: the fallback costs a socket per tab and nothing else.
+
+import { browserSocket, dialUrl } from './browser-socket';
+import type { ClientSocket } from './client-contract';
+import type { SyncTarget } from './page-store';
+import { messagePort, type PortLike, SocketEngine } from './socket-engine';
+
+export interface SocketHostOptions {
+  /** The built worker script (`<meta name="ultimate-sync-worker">`); absent = in-page host. */
+  readonly workerUrl?: string | undefined;
+  /** The principal the page acts for: one worker per principal, never a shared socket across two. */
+  readonly scope: string | null;
+  /** Injected for tests; production reads the globals. */
+  readonly sharedWorker?: SharedWorkerLike | undefined;
+  readonly inPageEngine?: () => SocketEngine;
+}
+
+export type SharedWorkerLike = new (
+  url: string,
+  options: { name: string },
+) => { port: MessagePort };
+
+export interface SocketHost {
+  /** `'worker'` or `'in-page'` — which host this page ended up on. */
+  readonly kind: 'worker' | 'in-page';
+  /** A fresh virtual socket over the port — what `LiveClient`'s `connect` option returns. */
+  socket(target: SyncTarget): ClientSocket;
+  /** The tab is going away: release the port in the engine. */
+  bye(): void;
+}
+
+/** The worker's name carries the scope, so two principals in two tabs get two workers. */
+export function workerName(scope: string | null): string {
+  return `ultimate-sync:${encodeURIComponent(scope ?? '')}`;
+}
+
+export function openHost(options: SocketHostOptions): SocketHost {
+  const worker = options.workerUrl === undefined ? undefined : workerPort(options);
+  if (worker !== undefined) return hostOver(worker, 'worker');
+  const channel = new MessageChannel();
+  const engine =
+    options.inPageEngine?.() ??
+    new SocketEngine({ dial: (target) => browserSocket(dialUrl(target)) });
+  engine.attach(messagePort(channel.port1));
+  return hostOver(messagePort(channel.port2), 'in-page');
+}
+
+/** `undefined` whenever a worker cannot be had — absent, sandboxed, or refused by the browser. */
+function workerPort(options: SocketHostOptions): PortLike | undefined {
+  const Worker =
+    options.sharedWorker ??
+    (typeof SharedWorker === 'function' ? (SharedWorker as SharedWorkerLike) : undefined);
+  if (Worker === undefined || options.workerUrl === undefined) return undefined;
+  try {
+    return messagePort(new Worker(options.workerUrl, { name: workerName(options.scope) }).port);
+  } catch {
+    return undefined;
+  }
+}
+
+function hostOver(port: PortLike, kind: 'worker' | 'in-page'): SocketHost {
+  let current: VirtualSocket | null = null;
+  port.onmessage = (event) => current?.receive(event.data);
+  return {
+    kind,
+    socket: (target) => {
+      current = new VirtualSocket(port, target);
+      return current;
+    },
+    bye: () => {
+      current = null;
+      port.postMessage({ t: 'bye' });
+      port.close?.();
+    },
+  };
+}
+
+/** The tab's socket: one `open`, frames both ways, one `close` — over the host's port. */
+class VirtualSocket implements ClientSocket {
+  readonly #port: PortLike;
+  #open: (() => void) | null = null;
+  #message: ((data: string) => void) | null = null;
+  #closed: ((code: number) => void) | null = null;
+  #live = true;
+
+  constructor(port: PortLike, target: SyncTarget) {
+    this.#port = port;
+    port.postMessage({ t: 'open', target });
+  }
+
+  send(data: string): void {
+    if (this.#live) this.#port.postMessage({ t: 'frame', data });
+  }
+
+  close(): void {
+    if (!this.#live) return;
+    this.#live = false;
+    this.#port.postMessage({ t: 'close', code: 1000 });
+  }
+
+  onOpen(handler: () => void): void {
+    this.#open = handler;
+  }
+
+  onMessage(handler: (data: string) => void): void {
+    this.#message = handler;
+  }
+
+  onClose(handler: (code: number) => void): void {
+    this.#closed = handler;
+  }
+
+  receive(message: unknown): void {
+    if (!this.#live || typeof message !== 'object' || message === null) return;
+    const typed = message as { t?: unknown; data?: unknown; code?: unknown };
+    if (typed.t === 'open') this.#open?.();
+    else if (typed.t === 'frame' && typeof typed.data === 'string') this.#message?.(typed.data);
+    else if (typed.t === 'close') {
+      this.#live = false;
+      this.#closed?.(typeof typed.code === 'number' ? typed.code : 1006);
+    }
+  }
+}

package/src/socket-port.ts

@@ -0,0 +1,55 @@
+// The engine ⇄ tab seam: the messages a `MessagePort` carries, the part of a port the engine uses,
+// and what the engine remembers about each attached one. Shared by the engine and its router.
+
+import type { SyncTarget } from './page-store';
+import type { SubscribeFrame } from './sync-protocol';
+
+/** The engine ⇄ tab messages. `frame.data` is a wire frame, encoded exactly as a socket carries it. */
+export type PortMessage =
+  | { readonly t: 'open'; readonly target: SyncTarget }
+  | { readonly t: 'frame'; readonly data: string }
+  | { readonly t: 'close'; readonly code: number }
+  /** The tab is going away (`pagehide`, a principal change): release the port itself. */
+  | { readonly t: 'bye' };
+
+/** The part of a `MessagePort` the engine uses — so a test hands in a `MessageChannel` port. */
+export interface PortLike {
+  postMessage(message: PortMessage): void;
+  onmessage: ((event: { readonly data: unknown }) => void) | null;
+  close?(): void;
+}
+
+/** One tab, as the engine knows it. */
+export interface AttachedPort {
+  readonly id: number;
+  readonly port: PortLike;
+  /** The tab asked for its virtual socket to be open. */
+  open: boolean;
+  /** It has asked before: a later `open` is the tab's own retry, not a page arriving. */
+  asked: boolean;
+  lastSeen: number;
+  /** Channel topics this port wants. */
+  readonly topics: Set<string>;
+  /** Engine sid → the add frame, for the live queries this port holds. */
+  readonly lives: Map<string, SubscribeFrame>;
+}
+
+/**
+ * A real `MessagePort` as a `PortLike`. Setting `onmessage` on a `MessagePort` starts it, which is
+ * what both hosts rely on; the wrapper exists only because the DOM types a handler over
+ * `MessageEvent` and the engine reads nothing of one but `data`.
+ */
+export function messagePort(port: MessagePort): PortLike {
+  let handler: PortLike['onmessage'] = null;
+  return {
+    postMessage: (message) => port.postMessage(message),
+    get onmessage() {
+      return handler;
+    },
+    set onmessage(next) {
+      handler = next;
+      port.onmessage = next === null ? null : (event: MessageEvent) => next({ data: event.data });
+    },
+    close: () => port.close(),
+  };
+}

package/src/socket-routes.ts

@@ -0,0 +1,170 @@
+// The engine's multiplexing: which port wants which channel topic and which live query, so the
+// one socket carries ONE membership per topic and every server frame is ROUTED only to the ports
+// that want it — never broadcast. It holds no socket; the engine hands it `send` and `post`.
+
+import { CHANNEL_SID_PREFIX } from './client-channels';
+import type { AttachedPort, PortMessage } from './socket-port';
+import { encode, type Frame, PROTOCOL_VERSION, type SubscribeFrame } from './sync-protocol';
+
+export interface RouterDeps {
+  /** To the node, when the socket is up. */
+  send(frame: Frame): void;
+  post(attached: AttachedPort, message: PortMessage): void;
+  port(id: number): AttachedPort | undefined;
+  ports(): Iterable<AttachedPort>;
+}
+
+/** The frames the router routes; the engine keeps `hello`, `update-available` and `reconnect`. */
+type RoutedFrame = Extract<
+  Frame,
+  { readonly type: 'snapshot' | 'patch' | 'ack' | 'records' | 'replay-gap' | 'events' }
+>;
+
+export class PortRouter {
+  readonly #deps: RouterDeps;
+  /**
+   * Topic → the ports that want it, the add frame that joined it, and the epoch the node last
+   * named for it — what a later port is told to re-read in.
+   */
+  readonly #topics = new Map<
+    string,
+    { readonly ports: Set<number>; readonly add: SubscribeFrame; epoch: string | null }
+  >();
+
+  constructor(deps: RouterDeps) {
+    this.#deps = deps;
+  }
+
+  /** A tab's `subscribe`: a channel membership, or a live query under a port-scoped sid. */
+  subscribe(attached: AttachedPort, frame: SubscribeFrame): void {
+    if (frame.target.kind === 'channel') {
+      this.#channel(attached, frame);
+      return;
+    }
+    if (frame.target.kind !== 'query') return;
+    // Every tab mints its own sids; the engine's sid carries the port so two tabs never collide.
+    const sid = `${attached.id}|${frame.sid}`;
+    const rewritten: SubscribeFrame = { ...frame, sid };
+    if (frame.op === 'add') attached.lives.set(sid, rewritten);
+    else attached.lives.delete(sid);
+    this.#deps.send(rewritten);
+  }
+
+  /** Release what a port held: its channel wants and its live registrations. */
+  release(attached: AttachedPort): void {
+    for (const topic of attached.topics) {
+      const add = this.#topics.get(topic)?.add;
+      if (add !== undefined) this.#leave(attached.id, topic, { ...add, op: 'drop' });
+    }
+    attached.topics.clear();
+    for (const add of attached.lives.values()) this.#deps.send({ ...add, op: 'drop' });
+    attached.lives.clear();
+  }
+
+  /** One server frame to the ports it belongs to. `data` is the frame as the socket carried it. */
+  route(frame: RoutedFrame, data: string): void {
+    switch (frame.type) {
+      case 'snapshot':
+      case 'patch':
+        this.#toLive(frame.sid, (sid) => ({ ...frame, sid }));
+        return;
+      case 'ack': {
+        const ref = frame.ref;
+        if (ref.includes('|')) this.#toLive(ref, (local) => ({ ...frame, ref: local }));
+        else if (this.#topics.has(ref)) this.#toTopic(ref, data);
+        else for (const attached of this.#deps.ports()) this.#frame(attached, data);
+        return;
+      }
+      case 'records':
+      case 'replay-gap': {
+        const held = this.#topics.get(`${CHANNEL_SID_PREFIX}${frame.channel}`);
+        if (held !== undefined) held.epoch = frame.epoch;
+        this.#toTopic(`${CHANNEL_SID_PREFIX}${frame.channel}`, data);
+        return;
+      }
+      case 'events':
+        this.#toTopic(`${CHANNEL_SID_PREFIX}${frame.channel}`, data);
+        return;
+    }
+  }
+
+  /**
+   * Re-announcing each channel IS the node's presence heartbeat — with no `since`, so it replays
+   * nothing.
+   */
+  announce(): void {
+    for (const { add } of this.#topics.values()) this.#deps.send(withoutSince(add));
+  }
+
+  /** The socket is gone: every membership goes with it; each tab resubscribes from its cursors. */
+  clear(): void {
+    this.#topics.clear();
+    for (const attached of this.#deps.ports()) {
+      attached.topics.clear();
+      attached.lives.clear();
+    }
+  }
+
+  /** One membership per topic across every port; the first `add` joins, the last leave drops. */
+  #channel(attached: AttachedPort, frame: SubscribeFrame): void {
+    const topic = frame.sid;
+    const held = this.#topics.get(topic);
+    if (frame.op !== 'add') {
+      attached.topics.delete(topic);
+      this.#leave(attached.id, topic, frame);
+      return;
+    }
+    attached.topics.add(topic);
+    if (held === undefined) {
+      this.#topics.set(topic, { ports: new Set([attached.id]), add: frame, epoch: null });
+      this.#deps.send(frame);
+      return;
+    }
+    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.
+    if (held.epoch === null) return;
+    const gap: Frame = {
+      type: 'replay-gap',
+      v: PROTOCOL_VERSION,
+      channel: topic.slice(CHANNEL_SID_PREFIX.length),
+      epoch: held.epoch,
+    };
+    this.#frame(attached, encode(gap));
+  }
+
+  #leave(id: number, topic: string, drop: SubscribeFrame): void {
+    const held = this.#topics.get(topic);
+    if (held === undefined) return;
+    held.ports.delete(id);
+    if (held.ports.size > 0) return;
+    this.#topics.delete(topic);
+    this.#deps.send(drop);
+  }
+
+  #toLive(engineSid: string, rewrite: (localSid: string) => Frame): void {
+    const bar = engineSid.indexOf('|');
+    const attached = this.#deps.port(Number(engineSid.slice(0, bar)));
+    if (attached !== undefined) this.#frame(attached, encode(rewrite(engineSid.slice(bar + 1))));
+  }
+
+  #toTopic(topic: string, data: string): void {
+    for (const id of this.#topics.get(topic)?.ports ?? []) {
+      const attached = this.#deps.port(id);
+      if (attached !== undefined) this.#frame(attached, data);
+    }
+  }
+
+  #frame(attached: AttachedPort, data: string): void {
+    this.#deps.post(attached, { t: 'frame', data });
+  }
+}
+
+/** A channel's `add` without its resume point — the beat repeats a membership, it resumes nothing. */
+function withoutSince(add: SubscribeFrame): SubscribeFrame {
+  if (add.target.kind !== 'channel') return add;
+  const { since: _since, ...target } = add.target;
+  return { ...add, target };
+}