@ultimat3/realtime 2.0.0 → 4.0.0

package/src/socket.ts

@@ -126,7 +126,13 @@ export class SyncSocket {
   readonly frameBudget: AcceptBudget;
 
   actor: Actor | null;
-  lastSeenAt: number;
+  /**
+   * MONOTONIC milliseconds, not an instant — the idle sweep measures a duration, and a duration
+   * read off the wall clock is decided by whatever NTP last wrote. A step forward evicts sockets
+   * that are talking; a step backward makes `idleFor` negative and spares sockets that are dead.
+   * Named for the units so nobody hands it to `new Date()`; `openedAt` is the wall-clock one.
+   */
+  lastSeenMonotonicMs: number;
   droppedFrames = 0;
   sentFrames = 0;
 
@@ -150,8 +156,10 @@ export class SyncSocket {
       burst: options.frameBurst ?? DEFAULT_FRAME_BURST,
       clock: this.#clock,
     });
+    // Two clocks on purpose: `openedAt` is an instant a human reads, `lastSeenMonotonicMs` is the
+    // start of a duration only this process compares.
     this.openedAt = this.#clock.now().getTime();
-    this.lastSeenAt = this.openedAt;
+    this.lastSeenMonotonicMs = this.#clock.monotonic();
   }
 
   get actorId(): string | null {
@@ -206,11 +214,12 @@ export class SyncSocket {
   }
 
   touch(): void {
-    this.lastSeenAt = this.#clock.now().getTime();
+    this.lastSeenMonotonicMs = this.#clock.monotonic();
   }
 
-  idleFor(now: number): number {
-    return now - this.lastSeenAt;
+  /** `nowMonotonicMs` comes from the SAME clock — `Clock.monotonic()`, never `now().getTime()`. */
+  idleFor(nowMonotonicMs: number): number {
+    return nowMonotonicMs - this.lastSeenMonotonicMs;
   }
 
   close(code: number = CLOSE.normal, reason = ''): void {
@@ -220,9 +229,28 @@ export class SyncSocket {
   }
 }
 
+/**
+ * How long a socket may route no frame before `sync-node` evicts it. It is an APPLICATION
+ * 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.
+ */
+export const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
+
+/**
+ * How often to ask. A quarter of the budget, floored at a second: a socket is evicted within 25%
+ * of its window of going quiet, and a node holding 50,000 of them pays one pass over the table
+ * four times per window rather than once a second. Derived rather than configured — a second knob
+ * is a second number that can disagree with the one it is a fraction of.
+ */
+export function idleSweepPeriodMs(idleTimeoutMs: number): number {
+  return Math.max(1_000, Math.floor(idleTimeoutMs / 4));
+}
+
 export interface SocketRegistryOptions {
   readonly clock?: Clock;
-  /** Bun also enforces its own `idleTimeout`; this sweep catches half-open connections. */
+  /** Bun's own `idleTimeout` is renewed by its ping/pong; this budget counts routed FRAMES. */
   readonly idleTimeoutMs?: number;
 }
 
@@ -244,7 +272,7 @@ export class SocketRegistry {
 
   constructor(options: SocketRegistryOptions = {}) {
     this.#clock = options.clock ?? systemClock;
-    this.#idleTimeoutMs = options.idleTimeoutMs ?? 120_000;
+    this.#idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
   }
 
   /**
@@ -310,19 +338,26 @@ export class SocketRegistry {
     return this.#sockets.size;
   }
 
-  /** Closes and returns everything past the idle budget. Called on an interval by `sync-node`. */
-  sweepIdle(): SyncSocket[] {
-    const now = this.#clock.now().getTime();
-    const closed: SyncSocket[] = [];
-    for (const socket of this.#sockets.values()) {
-      if (socket.idleFor(now) > this.#idleTimeoutMs) {
-        socket.close(CLOSE.idle, 'idle timeout');
-        // Through `remove`, not the map: the sweep is exactly the abnormal close a gauge leaks on.
-        this.remove(socket.id);
-        closed.push(socket);
-      }
-    }
-    return closed;
+  /** The budget `idle()` answers against, so a caller can size its own sweep from one number. */
+  get idleTimeoutMs(): number {
+    return this.#idleTimeoutMs;
+  }
+
+  /**
+   * Everything past the idle budget. A QUERY, and deliberately not an eviction: this table is three
+   * of the five things a socket holds, and the other two — its live subscriptions and its presence
+   * membership on the SHARED set — are only reachable from `sync-node`'s `teardown`. A sweep that
+   * closed and `remove`d here left a member every other node renders until its TTL and a
+   * `QueryEntry` whose `subscribers` map never empties. `sync-node` is the one caller and it
+   * releases each one the way the close callback does.
+   */
+  idle(): SyncSocket[] {
+    // Monotonic, because this is the one comparison an operator's clock could otherwise decide:
+    // `sync-node` hands this registry and every socket it builds the same `Clock`.
+    const now = this.#clock.monotonic();
+    return [...this.#sockets.values()].filter(
+      (socket) => socket.idleFor(now) > this.#idleTimeoutMs,
+    );
   }
 
   /**

package/src/subscriber-gate.ts

@@ -129,7 +129,24 @@ export class SubscriberGate {
     patch: RowPatch,
     holds: boolean,
   ): Promise<RowPatch | null> {
-    if (patch.op === 'delete' || patch.row === null) return patch;
+    // A delete carries no row, so there is nothing to put in front of the rule — `holds` IS the
+    // decision, the same one the two branches below take for a row a rule has just refused.
+    // Returned unconditionally it was a leak with no upper bound: the shared window is pre-policy,
+    // so every subscriber learned the id and the instant of every OTHER tenant's row as it was
+    // deleted, on a query whose `visible` rule had never let them see one of them.
+    //
+    // `holds` comes from `subscription.cursor.ids`, truncated at `CURSOR_ID_LIMIT` — so on a window
+    // wider than 512 rows a legitimate delete past position 512 is dropped and that row stays on
+    // screen until the subscriber re-snapshots. That is the trade the denied-update branch below
+    // already makes, and it is the right way round: a stale row is a bug, a row id leaked to
+    // another tenant is a breach.
+    if (patch.op === 'delete' || patch.row === null) {
+      if (holds) return patch;
+      // Counted, or a withheld delete is invisible in exactly the way `onRowDenied` exists to
+      // stop — and the rate of it is how an operator sees a window shared across tenants at all.
+      this.#denied(target.qid, who, patch.id);
+      return null;
+    }
     const full = target.rows.find((row) => row.id === patch.id);
     // No whole row means no decision to take. An update patch carries the changed columns only, so
     // a rule reading `row.ownerId` on one reads `undefined` and answers as if the row had said so —

package/src/sync-frames.ts

@@ -2,6 +2,7 @@
 // inbound surface the `sync` node exposes. Every dependency is injected, so the router is
 // exercisable without a socket, a bus or a server.
 
+import { logger } from '@ultimat3/core';
 import type { ChannelHub } from './channel';
 import { topic as makeTopic } from './channel';
 import { FrameRateLimitError } from './errors';
@@ -9,7 +10,7 @@ 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 type { SyncSocket } from './socket';
+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. */
@@ -104,7 +105,14 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
           // 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 });
-            socket.send(presenceFrame(name, 'sync', roster.members, roster.total));
+            // 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 });
+            }
           }
           return;
         }
@@ -121,12 +129,19 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
           sid: frame.sid,
           cursor: frame.target.cursor,
         });
-        socket.send(reply);
+        // `subscribe` has already seated the subscription and cleared its desync mark, so a reply
+        // the socket refuses leaves the server believing a client that holds no rows is in sync:
+        // the next change reaches it as a PATCH folded onto nothing, forever, on a socket that has
+        // since drained. Marked instead, which is the state it is actually in — the next delivery
+        // re-snapshots it out of the shared window, exactly as `live-fanout` does for a lost patch.
+        if (!socket.send(reply)) socket.markDesynced(frame.sid);
         return;
       }
       case 'mutate': {
         if (!options.onMutate) {
-          socket.send({
+          // 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,
@@ -137,6 +152,7 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
               fix: 'pass onMutate to createSyncNode({ onMutate })',
             }),
           });
+          if (!sent) undeliverable(socket, frame.key, 'ack');
           return;
         }
         const result = await options.onMutate({
@@ -153,7 +169,7 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
         // 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) {
-          socket.send({
+          const sent = socket.send({
             type: 'rebase',
             v: PROTOCOL_VERSION,
             key: frame.key,
@@ -161,14 +177,22 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
             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');
         }
-        socket.send({
-          type: 'ack',
-          v: PROTOCOL_VERSION,
-          ref: frame.key,
-          lsn: result.lsn ?? null,
-          error: null,
-        });
         return;
       }
       // Server-authored frames are never received from a client.
@@ -183,3 +207,16 @@ export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
     }
   }
 }
+
+/**
+ * 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-node.ts

@@ -14,6 +14,7 @@ import { CHANGE_SUBJECT_PREFIX, parseEnvelope, SeqGapDetector } from './replicat
 import {
   CLOSE,
   DEFAULT_MAX_BUFFERED_BYTES,
+  idleSweepPeriodMs,
   SocketRegistry,
   SyncSocket,
   type WsLike,
@@ -22,7 +23,13 @@ import { GrantBook, type SyncAuthenticator, sweepGrants } from './sync-auth';
 import { ackRefOf, createFrameRouter, type MutationHandler } from './sync-frames';
 import { decode, type Frame, PROTOCOL_VERSION, toWireError } from './sync-protocol';
 import { handleUpgrade, type UpgradeTarget, type WsData } from './sync-upgrade';
-import { AcceptBudget, drainPlan, type Rng, reconnectFrame } from './thundering-herd';
+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';
@@ -76,6 +83,12 @@ export interface SyncNodeOptions {
    */
   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
@@ -126,12 +139,16 @@ export interface SyncNode {
     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 { socketId: string; afterMs: number }[]>;
+  drain(options?: { graceMs?: number }): Promise<readonly DrainedSocket[]>;
 }
 
 export function createSyncNode(options: SyncNodeOptions): SyncNode {
   const sockets =
-    options.sockets ?? new SocketRegistry({ ...(options.clock ? { clock: options.clock } : {}) });
+    options.sockets ??
+    new SocketRegistry({
+      ...(options.clock ? { clock: options.clock } : {}),
+      ...(options.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: options.idleTimeoutMs }),
+    });
   const clock = options.clock ?? systemClock;
   const accept = options.accept ?? new AcceptBudget({ perSecond: 500, burst: 2000, clock });
   const maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
@@ -143,6 +160,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
   let changes: TransportSubscription | null = null;
   let sweeping: ReturnType<typeof setInterval> | null = null;
   let reauthing: ReturnType<typeof setInterval> | null = null;
+  let idling: ReturnType<typeof setInterval> | null = null;
 
   /**
    * Work nobody is waiting on — a presence leave from a synchronous close, a sweep on a timer, a
@@ -178,6 +196,8 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     sweeping = null;
     if (reauthing !== null) clearInterval(reauthing);
     reauthing = null;
+    if (idling !== null) clearInterval(idling);
+    idling = null;
     gaps.forget();
   };
 
@@ -200,6 +220,17 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
     }
   };
 
+  /**
+   * The node's one eviction: close, then release everything the socket held. Every path that ends
+   * a socket without a `close` callback behind it — the drain, the idle sweep — goes through it,
+   * because dropping the socket from the table is three of `teardown`'s five steps and the two it
+   * misses are the ones another node can see.
+   */
+  const evict = (socket: SyncSocket, code: number, reason: string): void => {
+    socket.close(code, reason);
+    teardown(socket);
+  };
+
   /**
    * One pass over the grants whose window has closed. This is the half R2 was missing: `reauthorize`
    * and `onActorChange` were both written and neither had a caller, so a socket that was accepted
@@ -222,8 +253,12 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       onRevoked: (socketId) => {
         const socket = sockets.get(socketId);
         if (!socket) return;
-        teardown(socket);
-        socket.close(CLOSE.policy, 'grant expired');
+        // Through `evict`, which closes BEFORE it releases. The other order was a close that never
+        // happened: `teardown` reaches `sockets.remove`, which closes the socket itself with
+        // `1001 connection closed`, and `SyncSocket.close` returns once `#closed` — so a revoked
+        // grant reached the client as a normal shutdown, which it retries against this node with
+        // the same dead credential, instead of the `1008` that tells it to re-dial with a new one.
+        evict(socket, CLOSE.policy, 'grant expired');
       },
       onRefreshFailed: (socketId, error) => {
         // Not a denial: the grant is kept and retried next pass. Reported because a socket nobody
@@ -277,6 +312,14 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
         );
         sweeping.unref();
       }
+      // The half-open connection Bun's own `idleTimeout` renews through its ping/pong: a client
+      // whose frame loop is wedged answers pings and keeps its grant, its subscriptions and its
+      // topic membership. `sweepIdle` was written for this and never called, so `touch()` and the
+      // 120s budget under it decided nothing.
+      idling = setInterval(() => {
+        for (const socket of sockets.idle()) evict(socket, CLOSE.idle, 'idle timeout');
+      }, idleSweepPeriodMs(sockets.idleTimeoutMs));
+      idling.unref();
       if (options.authenticate) {
         reauthing = setInterval(
           () => detach(reauthenticate(), 'sync.reauthenticate'),
@@ -320,6 +363,9 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           newSocketId: () => uuid(),
           authenticate: options.authenticate,
           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.
+          onUngranted: (socketId) => grants.delete(socketId),
         },
         request,
         server,
@@ -407,23 +453,34 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
       },
     },
 
-    async drain(drainOptions = {}): Promise<readonly { socketId: string; afterMs: number }[]> {
+    async drain(drainOptions = {}): Promise<readonly DrainedSocket[]> {
       ready = false;
       const ids = [...sockets.all()].map((socket) => socket.id);
-      const plan = drainPlan(ids, {
+      const spread = drainPlan(ids, {
         spreadMs: options.drainSpreadMs ?? 30_000,
         ...(options.rng ? { rng: options.rng } : {}),
       });
-      for (const entry of plan) {
-        sockets.get(entry.socketId)?.send(reconnectFrame(entry.afterMs, 'drain'));
+      // The answer is read, not assumed: this frame IS the socket's slot, so a client that never
+      // received one reconnects on its own backoff — the herd the spread exists to break, minus
+      // that client. Nothing repairs it, so what the drop owes is a count.
+      const plan: DrainedSocket[] = spread.map((entry) => ({
+        ...entry,
+        notified:
+          sockets.get(entry.socketId)?.send(reconnectFrame(entry.afterMs, 'drain')) === true,
+      }));
+      const notified = plan.reduce((total, entry) => total + (entry.notified ? 1 : 0), 0);
+      if (notified < plan.length) {
+        logger.warn('sync.drain_frames_dropped', { sockets: plan.length, notified });
       }
       const graceMs = drainOptions.graceMs ?? 5_000;
       if (graceMs > 0) await new Promise((resolve) => setTimeout(resolve, graceMs));
-      for (const socket of [...sockets.all()]) {
-        socket.close(CLOSE.goingAway, 'drain');
-        sockets.remove(socket.id);
-        grants.delete(socket.id);
-      }
+      // Through `evict`, never `sockets.remove` + `grants.delete`: those are three of `teardown`'s
+      // five steps, and the two they skip are the ones the rest of the fleet can see. A drained
+      // socket that never left its presence set is a member every other node renders for a full
+      // TTL — during a rolling restart, beside the same client's reconnection under a new id —
+      // and its live subscriptions stay in the registry, so `entry.subscribers` never empties and
+      // the matcher, the shared window and the retained ring are pinned for the process's life.
+      for (const socket of [...sockets.all()]) evict(socket, CLOSE.goingAway, 'drain');
       // Released once the sockets are gone rather than at the top: a client is entitled to its
       // patches for the whole grace window, and it is entitled to them *before* the hub the
       // fanout writes through is closed.

package/src/sync-protocol.ts

@@ -72,7 +72,7 @@ export type SubscribeTarget =
  * The opening frame, and the heartbeat's. It carries **no cursors**: resume is decided per
  * subscription by `subscribe`, whose target already carries the cursor and whose `(name, input)`
  * is what the node needs to authorize the read and reach the retained window at all. A cursor's
- * `qid` is `qidOf(name, input)` — a digest, not an input — so a resume list here could never be
+ * `qid` is `queryHash(name, input)` — a digest, not an input — so a resume list here could never be
  * more than a second, unauthorized restatement of that decision, and it cost every reconnect a
  * duplicate copy of up to `CURSOR_ID_LIMIT` ids per subscription during the exact restart storm
  * `thundering-herd.ts` exists to bound. Removing it needs no `PROTOCOL_VERSION` bump: `decode`
@@ -375,7 +375,7 @@ function list(obj: JsonObject, key: string, max: number, label = key): JsonValue
 
 /**
  * A client-supplied value, walked ITERATIVELY to its limits. Iteratively because the thing being
- * refused is a stack overflow: `qidOf` -> `canonicalJson` recurses over exactly this value, so a
+ * refused is a stack overflow: `queryHash` -> `canonicalJson` recurses over exactly this value, so a
  * depth check that recursed would be the same crash one frame earlier.
  */
 function bounded(value: JsonValue, label: string): JsonValue {

package/src/sync-upgrade.ts

@@ -37,8 +37,22 @@ export interface UpgradeDeps {
   socketCount(): number;
   newSocketId(): string;
   readonly authenticate?: SyncAuthenticator | undefined;
-  /** Recorded only after the upgrade took: a grant for a socket that never opened is never closed. */
+  /**
+   * Recorded BEFORE `server.upgrade`, because Bun runs `websocket.open` synchronously inside it
+   * (measured on bun 1.3.14) and `open` is where the node reads this grant to build the socket's
+   * actor. Recorded after, every authenticated socket carried `actor: null` — the topic guard,
+   * `authorize`, `visible` and the per-tenant cap all deciding about nobody — and it never
+   * repaired, because the re-auth sweep only visits grants with an `expiresAt`.
+   */
   onGranted(socketId: string, grant: SyncGrant): void;
+  /**
+   * The grant given back on the one path that will never open a socket. Recording first is only
+   * safe because this exists: nothing but a `close` callback deletes a grant, and there is no
+   * callback for an upgrade that never took. Required, not optional — a host that reserves and
+   * cannot release is a leak the type refuses rather than a rule a reviewer has to remember. The
+   * same "reserve, then release" shape `channel.ts` uses for a topic slot.
+   */
+  onUngranted(socketId: string): void;
 }
 
 /**
@@ -97,10 +111,14 @@ export async function handleUpgrade(
     socketId: deps.newSocketId(),
     clientBuildId: url.searchParams.get('build') ?? deps.buildId,
   };
+  // Before the upgrade, never after: `server.upgrade` runs `websocket.open` synchronously and does
+  // not return until it has, so a grant recorded on the next line is one the socket was already
+  // built without.
+  if (grant) deps.onGranted(data.socketId, grant);
   if (!server.upgrade(request, { data })) {
+    deps.onUngranted(data.socketId);
     return new Response('expected websocket', { status: 426 });
   }
-  if (grant) deps.onGranted(data.socketId, grant);
   return undefined;
 }
 

package/src/thundering-herd.ts

@@ -72,6 +72,16 @@ export interface DrainPlanEntry {
   readonly afterMs: number;
 }
 
+/**
+ * A plan entry and what became of it — what `SyncNode.drain` returns. `notified: false` means
+ * backpressure dropped that socket's `reconnect` frame: the frame is what carries the slot, nothing
+ * re-sends it, so that client reconnects on its own backoff and the count is the only place a log
+ * can say how much of the spread actually shipped.
+ */
+export interface DrainedSocket extends DrainPlanEntry {
+  readonly notified: boolean;
+}
+
 export interface DrainPlanOptions {
   /** Window across which reconnects are spread. Must exceed the node's own drain grace period. */
   readonly spreadMs?: number;