@ultimat3/realtime 20.2.1 → 21.0.0

package/src/socket.ts

@@ -16,6 +16,8 @@ import {
   systemClock,
   uuid,
 } from '@ultimat3/core';
+import { GapRepairs } from './channel-gaps';
+import type { ChannelRecordsFrame } from './channel-wire';
 import { CLOSE } from './close-codes';
 import { encode, type Frame } from './sync-protocol';
 import { AcceptBudget } from './thundering-herd';
@@ -81,10 +83,10 @@ export const DEFAULT_FRAME_BURST = 256;
 export const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024;
 
 /**
- * Channel frames this process dropped under backpressure. A DATA-LOSS counter, not a saturation
- * one: the live-query path repairs a dropped patch (the subscriber is marked desynced and the next
- * change re-snapshots it), and a channel has no cursor, no mark and no re-snapshot — so this is the
- * only trace a lost channel message leaves anywhere.
+ * Channel frames this process dropped under backpressure. A dropped `records` frame is now marked
+ * and REPAIRED — the socket is sent `replay-gap` once it drains and re-reads the channel's catch-up
+ * query (`channel_replay_gaps_total` counts those) — while a dropped `events` frame is ephemeral
+ * by definition and is only counted. The two series side by side are the whole delivery story.
  *
  * Declared here rather than in `@ultimat3/core`'s `runtime-metrics.ts` because that file is the
  * series EVERY Ultimate process emits and the deploy chart scales on; this one exists only where
@@ -94,7 +96,7 @@ export const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024;
  */
 const channelFramesDropped: Counter = counter('channel_frames_dropped_total', {
   unit: '{frame}',
-  description: 'Channel frames dropped by socket backpressure — unrecoverable, nothing replays one',
+  description: 'Channel frames dropped by socket backpressure',
 });
 
 export function actorIdOf(actor: Actor | null): string | null {
@@ -123,6 +125,12 @@ export class SyncSocket {
    * flush re-snapshots instead of silently diverging.
    */
   readonly desynced = new Set<string>();
+  /**
+   * Channel topics whose `records` stream this socket lost a frame of, with the epoch it was lost
+   * in. The channel twin of `desynced`: written on a drop, read on the next delivery or drain, which
+   * sends `replay-gap` and clears it. Bounded by `topics`, so it adds nothing a socket did not hold.
+   */
+  readonly gaps = new Map<string, string>();
   /**
    * Inbound frames this socket may still have routed. The accept budget spends one token per
    * UPGRADE, so nothing bounded what happened after: one authenticated socket reached a DB read,
@@ -255,6 +263,7 @@ export class SyncSocket {
 
   unsubscribeTopic(topic: string): void {
     this.topics.delete(topic);
+    this.gaps.delete(topic);
   }
 
   touch(): void {
@@ -313,6 +322,8 @@ export class SocketRegistry {
   readonly #clock: Clock;
   readonly #idleTimeoutMs: number;
   #droppedChannelFrames = 0;
+  /** The repair side of `SyncSocket.gaps`: `repairAll(socket)` is what Bun's `drain` calls. */
+  readonly gapRepairs = new GapRepairs();
 
   constructor(options: SocketRegistryOptions = {}) {
     this.#clock = options.clock ?? systemClock;
@@ -425,17 +436,45 @@ export class SocketRegistry {
       else dropped += 1;
     }
     if (members.size === 0) this.#byTopic.delete(topic);
-    if (dropped > 0) {
-      this.#droppedChannelFrames += dropped;
-      // Two readers, one event, one spelling: the series an operator alerts on and the line that
-      // says which topic it was. `deliver` ignored `send`'s answer and so did the hub above it, so
-      // until both existed a lost channel message left no trace at all.
-      channelFramesDropped.add(dropped);
-      logger.warn('channel.frames_dropped', { topic, dropped, total: this.#droppedChannelFrames });
+    if (dropped > 0) this.#countDropped(topic, dropped);
+    return sent;
+  }
+
+  /**
+   * A `records` delivery. An owed `replay-gap` goes out first; a socket that then drops the frame is
+   * marked for the next one. `deliver`'s twin, because only a records stream can be repaired.
+   */
+  deliverRecords(topic: string, epoch: string, frame: ChannelRecordsFrame): number {
+    const members = this.#byTopic.get(topic);
+    if (!members) return 0;
+    let sent = 0;
+    let dropped = 0;
+    for (const socket of members) {
+      if (socket.closed) {
+        members.delete(socket);
+        continue;
+      }
+      this.gapRepairs.repair(socket, topic);
+      if (socket.send(frame)) {
+        sent += 1;
+        continue;
+      }
+      dropped += 1;
+      socket.gaps.set(topic, epoch);
     }
+    if (members.size === 0) this.#byTopic.delete(topic);
+    if (dropped > 0) this.#countDropped(topic, dropped);
     return sent;
   }
 
+  #countDropped(topic: string, dropped: number): void {
+    this.#droppedChannelFrames += dropped;
+    // Two readers, one event, one spelling: the series an operator alerts on and the line that
+    // says which topic it was.
+    channelFramesDropped.add(dropped);
+    logger.warn('channel.frames_dropped', { topic, dropped, total: this.#droppedChannelFrames });
+  }
+
   /**
    * Channel frames backpressure refused since boot, node-wide and cumulative — the in-process read
    * of `channel_frames_dropped_total`, for a test or a benchmark that cannot scrape.

package/src/sync-auth.ts

@@ -1,6 +1,6 @@
 // Who a socket is, and for how long. The `sync` node evaluates no credential of its own — an app
-// supplies `authenticate`, exactly as it supplies `onMutate` — so this file owns the shape of that
-// answer, the per-node book that holds it, and the pass that re-decides one whose window has closed.
+// supplies `authenticate` — so this file owns the shape of that answer, the per-node book that
+// holds it, and the pass that re-decides one whose window has closed.
 
 import type { Actor, Clock } from '@ultimat3/core';
 

package/src/sync-frames.ts

@@ -4,52 +4,55 @@
 
 import { logger } from '@ultimat3/core';
 import type { ChannelHub } from './channel';
-import { topic as makeTopic } from './channel';
+import type { Topic } from './channel-decl';
 import { FrameRateLimitError } from './errors';
 import { FrameLanes, laneKeyOf } from './frame-lanes';
-import type { JsonValue, Row } from './json';
 import type { LiveQueryRegistry } from './live-query';
 import { type PresenceRegistry, presenceFrame } from './presence';
-import { CLOSE, type SyncSocket } from './socket';
-import { type Frame, PROTOCOL_VERSION, toWireError } from './sync-protocol';
-
-/** Server-authoritative mutation execution. Injected: `sync` never owns business logic. */
-export type MutationHandler = (args: {
-  socket: SyncSocket;
-  name: string;
-  key: string;
-  seq: number;
-  input: JsonValue;
-}) => Promise<{ lsn?: string | null; entity?: string; row?: Row | null }>;
+import type { SyncSocket } from './socket';
+import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
 export interface FrameRouterOptions {
   readonly hub: ChannelHub;
   readonly registry: LiveQueryRegistry;
   readonly buildId: string;
   readonly presence?: PresenceRegistry | undefined;
-  readonly onMutate?: MutationHandler | undefined;
 }
 
 export type FrameRouter = (socket: SyncSocket, frame: Frame) => Promise<void>;
 
 /**
- * What a failure ack refers to. `ack.ref` is how a client finds the thing that failed —
- * `queue.fail(frame.ref)` looks up a mutation by its idempotency key — so an ack built with the
- * SOCKET id names a key no queue can hold and the whole rollback path is inert end to end: the
- * optimistic write stays on screen and the mutation stays queued.
- *
- * The socket id is the answer for a frame nothing could read (a decode failure) and for the kinds
- * that carry no reference of their own, because there is nothing else true to say.
+ * What a refusal ack refers to. `ack.ref` is how a client finds the thing that failed — the sid
+ * of the subscription it refused, so that one window renders `failed` and no other does. The
+ * socket id is the answer for a frame nothing could read (a decode failure) and for the kinds that
+ * carry no reference of their own, because there is nothing else true to say.
  */
 export function ackRefOf(frame: Frame | null, socketId: string): string {
   if (frame === null) return socketId;
-  if (frame.type === 'mutate') return frame.key;
   if (frame.type === 'subscribe') 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>>();
+
+  /**
+   * 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.
+   */
+  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 });
+    if (!socket.send(presenceFrame(name, 'sync', roster.members, roster.total))) {
+      logger.warn('sync.presence_roster_dropped', { topic: name, socketId: socket.id });
+    }
+  };
   // Weakly keyed, so one socket's lanes die with it and no close path has to remember them.
   const lanes = new WeakMap<SyncSocket, FrameLanes>();
 
@@ -94,29 +97,23 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
         return;
       }
       case 'subscribe': {
-        if (frame.target.kind === 'topic') {
-          const name = makeTopic(...frame.target.topic.split('.'));
+        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);
+            if (name === undefined) return;
+            topics.delete(frame.sid);
+            const events = options.hub.channelOf(name)?.channel.events === true;
             options.hub.unsubscribe(socket, name);
-            if (presence) await presence.leave(name, socket.id);
+            if (presence && events) await presence.leave(name, socket.id);
             return;
           }
-          await options.hub.subscribe(socket, name);
-          // Subscribing to a topic IS joining its presence set: presence has no frame of its own,
-          // so a second round trip saying "and I am here" would be a second way to do one thing,
-          // and a client that skipped it would be invisible in a room it is receiving from.
-          // Repeating the frame is therefore also the heartbeat — `join` re-`put`s the member.
-          if (presence) {
-            const roster = await presence.join(name, { id: socket.id, actorId: socket.actorId });
-            // The answer is read even though nothing here can repair it. A roster has no cursor and
-            // no re-send path of its own: the client renders an empty room until it repeats this
-            // very frame as its heartbeat, which re-joins and re-rosters. Membership on the shared
-            // set is already correct, so the drop costs one client one heartbeat of blank room —
-            // and the log is the only trace it leaves anywhere.
-            if (!socket.send(presenceFrame(name, 'sync', roster.members, roster.total))) {
-              logger.warn('sync.presence_roster_dropped', { topic: name, socketId: socket.id });
-            }
-          }
+          const name = await options.hub.subscribeChannel(socket, frame.target);
+          topics.set(frame.sid, name);
+          await joinPresence(socket, name);
           return;
         }
         if (frame.op === 'drop') {
@@ -140,86 +137,16 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
         if (!socket.send(reply)) socket.markDesynced(frame.sid);
         return;
       }
-      case 'mutate': {
-        if (!options.onMutate) {
-          // A failure receipt is still a receipt: dropped, the client's mutation stays `inflight`
-          // and is neither rolled back nor retried, so this one reads the answer too.
-          const sent = socket.send({
-            type: 'ack',
-            v: PROTOCOL_VERSION,
-            ref: frame.key,
-            lsn: null,
-            error: toWireError({
-              code: 'X_NOT_IMPLEMENTED',
-              cause: 'this sync node was started without a mutation handler',
-              fix: 'pass onMutate to createSyncNode({ onMutate })',
-            }),
-          });
-          if (!sent) undeliverable(socket, frame.key, 'ack');
-          return;
-        }
-        const result = await options.onMutate({
-          socket,
-          name: frame.name,
-          key: frame.key,
-          seq: frame.seq,
-          input: frame.input,
-        });
-        // The rebase FIRST, and the ack last. The ack is the receipt, and a receipt is what
-        // retires the client's record of the mutation — its journal row and its rebase-log entry,
-        // both of which stay forever otherwise. A rebase that lands after that has no entry left
-        // to read the mutator's conflict strategy off (every merge silently becomes server-wins)
-        // and no sequence to decide which later optimistic writes to replay over server truth.
-        // These are two frames on one socket, so the order is the only coordination there is.
-        if (result.entity !== undefined) {
-          const sent = socket.send({
-            type: 'rebase',
-            v: PROTOCOL_VERSION,
-            key: frame.key,
-            entity: result.entity,
-            strategy: 'server-wins',
-            row: result.row ?? null,
-          });
-          // The ack retires the client's rebase-log entry, so acking a rebase that never left is
-          // the divergence the ordering above exists to prevent — one frame later instead of one
-          // frame earlier. Nothing is acked; the mutation stays unsettled and is replayed.
-          if (!sent) return undeliverable(socket, frame.key, 'rebase');
-        }
-        if (
-          !socket.send({
-            type: 'ack',
-            v: PROTOCOL_VERSION,
-            ref: frame.key,
-            lsn: result.lsn ?? null,
-            error: null,
-          })
-        ) {
-          undeliverable(socket, frame.key, 'ack');
-        }
-        return;
-      }
       // Server-authored frames are never received from a client.
       case 'snapshot':
       case 'patch':
       case 'ack':
-      case 'rebase':
-      case 'presence':
+      case 'records':
+      case 'events':
+      case 'replay-gap':
       case 'reconnect':
       case 'update-available':
         return;
     }
   }
 }
-
-/**
- * A settlement the socket refused. There is nothing on the node to mark — the mutation is applied
- * and the server keeps no per-mutation state — and a client only returns an `inflight` mutation to
- * its queue when the connection dies (`requeueInflight`), so a receipt dropped on a socket that
- * stays up is a write the client neither retires nor retries, with the server believing it settled.
- * Closing IS the repair: the queue hands the mutation back and the reconnect replays it under the
- * same idempotency key.
- */
-function undeliverable(socket: SyncSocket, key: string, kind: 'rebase' | 'ack'): void {
-  logger.warn('sync.settlement_dropped', { socketId: socket.id, key, kind });
-  socket.close(CLOSE.overloaded, 'settlement undeliverable');
-}

package/src/sync-meta.ts

@@ -0,0 +1,42 @@
+// The page's sync target, read off the `<meta>` tags the document shell renders — the default
+// when the island bootstrap passed none. The names are core's (`page-meta.ts`): one literal per
+// fact, written by `@ultimat3/render`, read here.
+
+import { CLIENT_BUILD_META, CLIENT_SYNC_META, CLIENT_SYNC_WORKER_META } from '@ultimat3/core/page';
+import type { SyncTarget } from './page-store';
+
+/** The minimum of a DOM this reads — so a test can hand one in without a browser. */
+export interface MetaDocument {
+  querySelector(selector: string): { getAttribute(name: string): string | null } | null;
+}
+
+function meta(doc: MetaDocument, name: string): string | undefined {
+  const content = doc.querySelector(`meta[name="${name}"]`)?.getAttribute('content');
+  return content === null || content === undefined || content === '' ? undefined : content;
+}
+
+/**
+ * `ultimate-sync` resolved against the page (`/_x/sync` is same-origin), with the scheme turned
+ * to the socket's: `https:` → `wss:`, `http:` → `ws:`; an absolute `ws(s)://` stays as written.
+ * `undefined` when the document names no sync node — a page with no realtime.
+ */
+export function syncTargetFromMeta(doc: MetaDocument, href: string): SyncTarget | undefined {
+  const sync = meta(doc, CLIENT_SYNC_META);
+  if (sync === undefined) return undefined;
+  const url = new URL(sync, href);
+  if (url.protocol === 'https:') url.protocol = 'wss:';
+  else if (url.protocol === 'http:') url.protocol = 'ws:';
+  return { url: url.toString(), buildId: meta(doc, CLIENT_BUILD_META) ?? '' };
+}
+
+/** The worker script URL, or `undefined` when the app built none (the in-page host is used). */
+export function syncWorkerFromMeta(doc: MetaDocument, href: string): string | undefined {
+  const worker = meta(doc, CLIENT_SYNC_WORKER_META);
+  return worker === undefined ? undefined : new URL(worker, href).toString();
+}
+
+/** This page's target, when there is a page to read. */
+export function pageSyncTarget(): SyncTarget | undefined {
+  if (typeof document === 'undefined' || typeof location === 'undefined') return undefined;
+  return syncTargetFromMeta(document, location.href);
+}

package/src/sync-node-contract.ts

@@ -0,0 +1,100 @@
+// What a `sync` node IS, as types: the options `createSyncNode` takes, the node it returns and the
+// socket Bun hands its handlers. Apart from `sync-node.ts` so the lifecycle there stays under the
+// file ceiling, and so a host can name the shapes without reading the lifecycle.
+
+import type { Clock } from '@ultimat3/core';
+import type { ChannelHub } from './channel';
+import type { Transport } from './fanout';
+import type { LiveQueryRegistry } from './live-query';
+import type { PresenceRegistry } from './presence';
+import type { SocketRegistry, WsLike } from './socket';
+import type { SyncAuthenticator } from './sync-auth';
+import type { UpgradeTarget, WsData } from './sync-upgrade';
+import type { AcceptBudget, DrainedSocket, Rng } from './thundering-herd';
+
+export type SyncWs = WsLike & { readonly data: WsData };
+
+export interface SyncNodeOptions {
+  readonly hub: ChannelHub;
+  readonly registry: LiveQueryRegistry;
+  readonly transport: Transport;
+  readonly buildId: string;
+  readonly presence?: PresenceRegistry;
+  readonly sockets?: SocketRegistry;
+  readonly accept?: AcceptBudget;
+  /** Concurrent sockets this node will hold. The count the accept budget does not bound. */
+  readonly maxConnections?: number;
+  /** Inbound bytes one frame may carry, handed to whatever server mounts `websocket`. */
+  readonly maxFrameBytes?: number;
+  /** Sustained inbound frames one socket may have routed per second. */
+  readonly maxFramesPerSecond?: number;
+  /** Burst allowance on that rate, per socket. */
+  readonly frameBurst?: number;
+  /**
+   * When a socket starts dropping frames, and how many drops close it. On `SyncSocket` too, but
+   * this node builds every socket it holds — so unforwarded they were reachable only by abandoning
+   * `createSyncNode`, and a dropped channel frame is the one loss nothing replays.
+   */
+  readonly maxBufferedBytes?: number;
+  readonly maxDroppedFrames?: number;
+  /**
+   * How long a socket may route no frame before this node evicts it. Every ceiling on a socket
+   * `sync` builds has to be reachable from here, and this one was not: `SocketRegistry`'s default
+   * was only settable by constructing the registry yourself, and nothing swept it either way.
+   */
+  readonly idleTimeoutMs?: number;
+  /**
+   * Who is dialling. Injected because `sync` owns no business logic and
+   * imports no authenticator, so an app supplies the one function that turns an upgrade request
+   * into an actor — from `@ultimat3/auth` or from anywhere else.
+   *
+   * **Omitted, every socket on this node is anonymous** and every policy downstream — the topic
+   * guard, `authorize`, `visible`, the per-tenant subscription cap — decides against `null`. That
+   * is a single-tenant node, and `start()` says so in the log.
+   */
+  readonly authenticate?: SyncAuthenticator;
+  /** How often an expired grant is re-decided. The clock a socket's authority runs on. */
+  readonly reauthenticateIntervalMs?: number;
+  readonly clock?: Clock;
+  readonly rng?: Rng;
+  /** WS endpoint. One path, no negotiation — the protocol version lives in the frames. */
+  readonly path?: string;
+  readonly drainSpreadMs?: number;
+}
+
+export interface SyncNode {
+  readonly sockets: SocketRegistry;
+  readonly ready: boolean;
+  /** The one path it answers an upgrade on: a HOST has to route it, and must not restate it. */
+  readonly path: string;
+  start(): Promise<void>;
+  /**
+   * Refuse new connections, keep every one this node holds. The SIGTERM `accept` phase calls it —
+   * `/readyz` answers 503 so the load balancer stops routing here, and an upgrade arriving in the
+   * meantime is shed with a retry delay instead of landing on a process that is going away. It is
+   * NOT `stop()`: a draining node still owes its clients their patches, and `stop()` releases the
+   * change subscription that carries them.
+   */
+  stopAccepting(): void;
+  stop(): Promise<void>;
+  /**
+   * Async because `authenticate` is: the credential is decided *before* `server.upgrade`, so a
+   * refused one never costs a websocket. Bun's `fetch` may return a promise, and an upgrade that
+   * awaits first is still an upgrade.
+   */
+  fetch(request: Request, server: UpgradeTarget): Promise<Response | undefined>;
+  readonly websocket: {
+    idleTimeout: number;
+    backpressureLimit: number;
+    /** Inbound ceiling. Declared here so every host that mounts this handler inherits it. */
+    maxPayloadLength: number;
+    sendPings: boolean;
+    open(ws: SyncWs): void;
+    message(ws: SyncWs, message: string | Uint8Array): void;
+    /** Bun calls it when a backed-up socket has drained: owed `replay-gap` frames go out here. */
+    drain(ws: SyncWs): void;
+    close(ws: SyncWs): void;
+  };
+  /** Sends every client a distinct reconnect delay, then closes. Returns the plan for tests/logs. */
+  drain(options?: { graceMs?: number }): Promise<readonly DrainedSocket[]>;
+}

package/src/sync-node.ts

@@ -4,40 +4,27 @@
 // client may reconnect to any node and resume from its cursor, which is why drain is allowed to
 // redistribute connections at all.
 
-import { type Clock, logger, markReady, reportError, systemClock, uuid } from '@ultimat3/core';
-import type { ChannelHub, Topic } from './channel';
+import { logger, markReady, reportError, systemClock, uuid } from '@ultimat3/core';
+import type { Topic } from './channel';
 import { detach } from './detach';
 import { evictInChunks } from './drain-evictions';
 import { isClientFault } from './errors';
-import type { Transport, TransportSubscription } from './fanout';
-import type { LiveQueryRegistry } from './live-query';
-import type { PresenceRegistry } from './presence';
-import { CHANGE_SUBJECT_PREFIX, parseEnvelope, SeqGapDetector } from './replicator';
+import type { TransportSubscription } from './fanout';
+import { CHANGE_SUBJECT_ALL, parseEnvelope, SeqGapDetector } from './replicator';
 import {
   CLOSE,
   DEFAULT_MAX_BUFFERED_BYTES,
   idleSweepPeriodMs,
   SocketRegistry,
   SyncSocket,
-  type WsLike,
 } from './socket';
-import { GrantBook, type SyncAuthenticator, sweepGrants } from './sync-auth';
-import { ackRefOf, createFrameRouter, type MutationHandler } from './sync-frames';
+import { GrantBook, sweepGrants } from './sync-auth';
+import { ackRefOf, createFrameRouter } from './sync-frames';
 import { 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, type WsData } from './sync-upgrade';
-import {
-  AcceptBudget,
-  type DrainedSocket,
-  drainPlan,
-  type Rng,
-  reconnectFrame,
-} from './thundering-herd';
-
-/** Declared with the upgrade that builds it — this file only ever reads one. */
-export type { UpgradeTarget, WsData } from './sync-upgrade';
-
-export type SyncWs = WsLike & { readonly data: WsData };
+import { handleUpgrade, type UpgradeTarget } from './sync-upgrade';
+import { AcceptBudget, type DrainedSocket, drainPlan, reconnectFrame } from './thundering-herd';
 
 // Moved to `sync-node-bounds.ts` with the refusals that read them, and re-exported here because
 // `server.ts` publishes all three and a moved constant must not become a moved import path.
@@ -47,89 +34,10 @@ export {
   DEFAULT_REAUTH_INTERVAL_MS,
 } from './sync-node-bounds';
 
-export interface SyncNodeOptions {
-  readonly hub: ChannelHub;
-  readonly registry: LiveQueryRegistry;
-  readonly transport: Transport;
-  readonly buildId: string;
-  readonly presence?: PresenceRegistry;
-  readonly sockets?: SocketRegistry;
-  readonly accept?: AcceptBudget;
-  /** Concurrent sockets this node will hold. The count the accept budget does not bound. */
-  readonly maxConnections?: number;
-  /** Inbound bytes one frame may carry, handed to whatever server mounts `websocket`. */
-  readonly maxFrameBytes?: number;
-  /** Sustained inbound frames one socket may have routed per second. */
-  readonly maxFramesPerSecond?: number;
-  /** Burst allowance on that rate, per socket. */
-  readonly frameBurst?: number;
-  /**
-   * When a socket starts dropping frames, and how many drops close it. On `SyncSocket` too, but
-   * this node builds every socket it holds — so unforwarded they were reachable only by abandoning
-   * `createSyncNode`, and a dropped channel frame is the one loss nothing replays.
-   */
-  readonly maxBufferedBytes?: number;
-  readonly maxDroppedFrames?: number;
-  /**
-   * How long a socket may route no frame before this node evicts it. Every ceiling on a socket
-   * `sync` builds has to be reachable from here, and this one was not: `SocketRegistry`'s default
-   * was only settable by constructing the registry yourself, and nothing swept it either way.
-   */
-  readonly idleTimeoutMs?: number;
-  readonly onMutate?: MutationHandler;
-  /**
-   * Who is dialling. Injected for the same reason `onMutate` is: `sync` owns no business logic and
-   * imports no authenticator, so an app supplies the one function that turns an upgrade request
-   * into an actor — from `@ultimat3/auth` or from anywhere else.
-   *
-   * **Omitted, every socket on this node is anonymous** and every policy downstream — the topic
-   * guard, `authorize`, `visible`, the per-tenant subscription cap — decides against `null`. That
-   * is a single-tenant node, and `start()` says so in the log.
-   */
-  readonly authenticate?: SyncAuthenticator;
-  /** How often an expired grant is re-decided. The clock a socket's authority runs on. */
-  readonly reauthenticateIntervalMs?: number;
-  readonly clock?: Clock;
-  readonly rng?: Rng;
-  /** WS endpoint. One path, no negotiation — the protocol version lives in the frames. */
-  readonly path?: string;
-  readonly drainSpreadMs?: number;
-}
-
-export interface SyncNode {
-  readonly sockets: SocketRegistry;
-  readonly ready: boolean;
-  /** The one path it answers an upgrade on: a HOST has to route it, and must not restate it. */
-  readonly path: string;
-  start(): Promise<void>;
-  /**
-   * Refuse new connections, keep every one this node holds. The SIGTERM `accept` phase calls it —
-   * `/readyz` answers 503 so the load balancer stops routing here, and an upgrade arriving in the
-   * meantime is shed with a retry delay instead of landing on a process that is going away. It is
-   * NOT `stop()`: a draining node still owes its clients their patches, and `stop()` releases the
-   * change subscription that carries them.
-   */
-  stopAccepting(): void;
-  stop(): Promise<void>;
-  /**
-   * Async because `authenticate` is: the credential is decided *before* `server.upgrade`, so a
-   * refused one never costs a websocket. Bun's `fetch` may return a promise, and an upgrade that
-   * awaits first is still an upgrade.
-   */
-  fetch(request: Request, server: UpgradeTarget): Promise<Response | undefined>;
-  readonly websocket: {
-    idleTimeout: number;
-    backpressureLimit: number;
-    /** Inbound ceiling. Declared here so every host that mounts this handler inherits it. */
-    maxPayloadLength: number;
-    sendPings: boolean;
-    open(ws: SyncWs): void;
-    message(ws: SyncWs, message: string | Uint8Array): void;
-    close(ws: SyncWs): void;
-  };
-  /** Sends every client a distinct reconnect delay, then closes. Returns the plan for tests/logs. */
-  drain(options?: { graceMs?: number }): Promise<readonly DrainedSocket[]>;
-}
+/** The node's shapes — options, the node itself, its socket — live beside it, in their own file. */
+export type { SyncNode, SyncNodeOptions, SyncWs } from './sync-node-contract';
+/** Declared with the upgrade that builds it — this file only ever reads one. */
+export type { UpgradeTarget, WsData } from './sync-upgrade';
 
 export function createSyncNode(options: SyncNodeOptions): SyncNode {
   const sockets =
@@ -277,7 +185,6 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     registry: options.registry,
     buildId: options.buildId,
     presence,
-    onMutate: options.onMutate,
   });
 
   return {
@@ -289,7 +196,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     },
 
     async start(): Promise<void> {
-      changes = await options.transport.subscribe(`${CHANGE_SUBJECT_PREFIX}.>`, (payload) => {
+      changes = await options.transport.subscribe(CHANGE_SUBJECT_ALL, (payload) => {
         const envelope = parseEnvelope(payload);
         if (!envelope) return;
         // Fanout is at-most-once over core NATS, so a reconnect is changes this node never saw.
@@ -304,6 +211,9 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
         // 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.
         detach(options.registry.deliver(envelope.change), 'live.deliver', envelope.change.entity);
+        // 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.
+        options.hub.deliverChange(envelope.change);
       });
       // 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.
@@ -434,6 +344,13 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
         })();
       },
 
+      drain(ws: SyncWs): void {
+        // A `records` frame backpressure refused left this socket gapped on that channel; the
+        // repair is the node's verdict, sent the moment the socket can take a frame again.
+        const socket = sockets.get(ws.data.socketId);
+        if (socket) sockets.gapRepairs.repairAll(socket);
+      },
+
       close(ws: SyncWs): void {
         const socket = sockets.get(ws.data.socketId);
         if (!socket) {