@ultimat3/realtime 20.2.1 → 22.0.0

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 };
+}

package/src/socket.ts

@@ -16,7 +16,11 @@ import {
   systemClock,
   uuid,
 } from '@ultimat3/core';
+import { GapRepairs } from './channel-gaps';
+import type { ChannelRecordsFrame } from './channel-wire';
 import { CLOSE } from './close-codes';
+import { DropWindow } from './socket-drops';
+import { DEFAULT_IDLE_TIMEOUT_MS } from './socket-idle';
 import { encode, type Frame } from './sync-protocol';
 import { AcceptBudget } from './thundering-herd';
 
@@ -81,10 +85,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 +98,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 +127,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,
@@ -148,6 +158,7 @@ export class SyncSocket {
   readonly #maxDroppedFrames: number;
   #clientBuildId: string;
   #closed = false;
+  readonly #drops: DropWindow;
 
   constructor(options: SyncSocketOptions) {
     this.#ws = options.ws;
@@ -160,6 +171,7 @@ export class SyncSocket {
     finiteOption('SyncSocket', 'maxBufferedBytes', this.#maxBufferedBytes);
     this.#maxDroppedFrames = options.maxDroppedFrames ?? 32;
     finiteOption('SyncSocket', 'maxDroppedFrames', this.#maxDroppedFrames);
+    this.#drops = new DropWindow(this.#maxDroppedFrames);
     this.frameBudget = new AcceptBudget({
       perSecond: finiteOption(
         'SyncSocket',
@@ -207,33 +219,34 @@ export class SyncSocket {
 
   /** `false` means the frame was dropped by backpressure — the caller must mark state stale. */
   send(frame: Frame): boolean {
+    return this.sendEncoded(encode(frame));
+  }
+
+  /** An `encode()`d frame — the fan-outs encode once for every socket. Adds no validation. */
+  sendEncoded(text: string): boolean {
     if (this.#closed) return false;
     if (this.#ws.getBufferedAmount() > this.#maxBufferedBytes) {
-      this.droppedFrames += 1;
-      if (this.droppedFrames > this.#maxDroppedFrames) {
-        this.close(CLOSE.overloaded, 'backpressure');
-      }
+      this.#dropped();
       return false;
     }
-    // `WsLike.send` is declared `: number` for this line and no other: Bun answers `0` for a
-    // message it DROPPED — the socket closed between the buffered-amount check above and this
-    // write — and `-1` under backpressure. Discarded, a dropped frame read as delivered, so
-    // `live-fanout` advanced the subscriber's cursor past a patch that never left and
-    // `sync-frames`' desync mark was never taken: permanently stale on a healthy socket, which is
-    // the exact outcome every other `socket.send` on this node reads its answer to prevent.
-    if (this.#ws.send(encode(frame)) <= 0) {
-      this.droppedFrames += 1;
-      // The same ceiling backpressure takes: a socket the runtime keeps refusing is one to close,
-      // and the two are one failure — the write went nowhere either way.
-      if (this.droppedFrames > this.#maxDroppedFrames) {
-        this.close(CLOSE.overloaded, 'backpressure');
-      }
+    // Bun answers `0` for a message it DROPPED (the socket closed after the check above) — the one
+    // drop. `-1` means QUEUED under backpressure, and it is delivered: counted as a drop it sent a
+    // spurious `replay-gap`, desynced a healthy subscriber, and closed the socket after 33.
+    if (this.#ws.send(text) === 0) {
+      this.#dropped();
       return false;
     }
     this.sentFrames += 1;
     return true;
   }
 
+  /** One frame that never left: counted for life, judged per `DROP_WINDOW_MS` (`socket-drops.ts`). */
+  #dropped(): void {
+    this.droppedFrames += 1;
+    if (this.#drops.overflowed(this.#clock.monotonic()))
+      this.close(CLOSE.overloaded, 'backpressure');
+  }
+
   /** Record a dropped or invalidated subscription so the next flush re-snapshots it. */
   markDesynced(sid: string): void {
     this.desynced.add(sid);
@@ -255,6 +268,7 @@ export class SyncSocket {
 
   unsubscribeTopic(topic: string): void {
     this.topics.delete(topic);
+    this.gaps.delete(topic);
   }
 
   touch(): void {
@@ -273,25 +287,6 @@ 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's own `idleTimeout` is renewed by its ping/pong; this budget counts routed FRAMES. */
@@ -313,6 +308,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;
@@ -414,6 +411,9 @@ export class SocketRegistry {
   deliver(topic: string, frame: Frame): number {
     const members = this.#byTopic.get(topic);
     if (!members) return 0;
+    // Encoded ONCE for every member: per socket it was 16.9 ms against 0.6 ms for a 2 kB frame to
+    // 10,000 sockets, measured.
+    const text = encode(frame);
     let sent = 0;
     let dropped = 0;
     for (const socket of members) {
@@ -421,21 +421,63 @@ export class SocketRegistry {
         members.delete(socket);
         continue;
       }
-      if (socket.send(frame)) sent += 1;
+      if (socket.sendEncoded(text)) sent += 1;
       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;
+    const text = encode(frame);
+    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.sendEncoded(text)) {
+        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;
   }
 
+  /** Every member owes a re-read (a TRUNCATE): one `replay-gap` each now, or kept as a mark. */
+  announceGap(topic: string, epoch: string): number {
+    const members = this.#byTopic.get(topic);
+    if (!members) return 0;
+    let announced = 0;
+    for (const socket of members) {
+      if (socket.closed) continue;
+      socket.gaps.set(topic, epoch);
+      if (this.gapRepairs.repair(socket, topic)) announced += 1;
+    }
+    return announced;
+  }
+
+  #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/subscriber-gate.ts

@@ -54,6 +54,55 @@ export interface GateTarget {
   readonly rows: readonly Row[];
 }
 
+/**
+ * The shared window, indexed ONCE per fan-out rather than searched per subscriber per patch: a
+ * `rows.find` inside the subscriber loop was O(subscribers × window) — 54.6 ms against 0.7 ms at
+ * 1000 subscribers over a 500-row window. `windowIndex` builds it; `filterPatches` builds its own
+ * when a caller passes none.
+ */
+export interface WindowIndex {
+  readonly byId: ReadonlyMap<string, Row>;
+  readonly position: ReadonlyMap<string, number>;
+}
+
+export function windowIndex(rows: readonly Row[]): WindowIndex {
+  const byId = new Map<string, Row>();
+  const position = new Map<string, number>();
+  rows.forEach((row, at) => {
+    byId.set(row.id, row);
+    position.set(row.id, at);
+  });
+  return { byId, position };
+}
+
+/**
+ * What a subscriber holds as a patch list is folded: the cursor's set, plus what this list has
+ * inserted, minus what it has deleted — never a copy of the set per subscriber.
+ */
+class Holding {
+  readonly #base: ReadonlySet<string>;
+  readonly #added = new Set<string>();
+  readonly #removed = new Set<string>();
+
+  constructor(base: ReadonlySet<string>) {
+    this.#base = base;
+  }
+
+  has(id: string): boolean {
+    return this.#added.has(id) || (this.#base.has(id) && !this.#removed.has(id));
+  }
+
+  fold(patch: RowPatch): void {
+    if (patch.op === 'delete') {
+      this.#added.delete(patch.id);
+      this.#removed.add(patch.id);
+    } else if (patch.op === 'insert') {
+      this.#removed.delete(patch.id);
+      this.#added.add(patch.id);
+    }
+  }
+}
+
 export interface SubscriberGateOptions {
   /**
    * `live.rows_denied`. A row an actor's policy refuses is dropped, never sent and never turned
@@ -113,11 +162,16 @@ export class SubscriberGate {
     who: Subscriber,
     patches: readonly RowPatch[],
     held: ReadonlySet<string>,
+    index: WindowIndex = windowIndex(target.rows),
   ): Promise<RowPatch[]> {
     const out: RowPatch[] = [];
+    const holding = new Holding(held);
     for (const patch of patches) {
-      const allowed = await this.patch(target, who, patch, held.has(patch.id));
-      if (allowed !== null) out.push(allowed);
+      const allowed = await this.#decide(target, who, patch, holding.has(patch.id), index);
+      if (allowed === null) continue;
+      const placed = rebase(allowed, holding, target.rows, index);
+      holding.fold(placed);
+      out.push(placed);
     }
     return out;
   }
@@ -128,6 +182,16 @@ export class SubscriberGate {
     who: Subscriber,
     patch: RowPatch,
     holds: boolean,
+  ): Promise<RowPatch | null> {
+    return await this.#decide(target, who, patch, holds, windowIndex(target.rows));
+  }
+
+  async #decide(
+    target: GateTarget,
+    who: Subscriber,
+    patch: RowPatch,
+    holds: boolean,
+    index: WindowIndex,
   ): Promise<RowPatch | null> {
     // 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.
@@ -147,7 +211,7 @@ export class SubscriberGate {
       this.#denied(target.qid, who, patch.id);
       return null;
     }
-    const full = target.rows.find((row) => row.id === patch.id);
+    const full = index.byId.get(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 —
     // fail-closed for `=== actor.id`, and a leak for every `!row.private`. It is not a gate that
@@ -218,6 +282,31 @@ const actorIdOf = (who: Subscriber): string | null => (who.actor === null ? null
  * window stopped holding it. Written once so the two paths cannot answer differently: a client left
  * holding the row instead renders a revoked grant until something else reconnects it.
  */
+/**
+ * The patch as this subscriber must read it. `index` was a position in the SHARED, pre-policy
+ * window, and forwarded unchanged it placed the row out of order for anyone who sees fewer rows —
+ * and its size told them how many rows they may not see sit ahead of it. Re-based on the rows ahead
+ * of it that this subscriber holds; dropped from a delete, which the client applies by id. Bounded
+ * by `CURSOR_ID_LIMIT` like `holds` is: a held row past it is not counted.
+ */
+function rebase(
+  patch: RowPatch,
+  holding: Holding,
+  rows: readonly Row[],
+  index: WindowIndex,
+): RowPatch {
+  if (patch.index === undefined) return patch;
+  const { index: _shared, ...rest } = patch;
+  if (patch.op === 'delete' || patch.row === null) return rest;
+  const at = index.position.get(patch.id) ?? patch.index;
+  let local = 0;
+  for (let i = 0; i < at && i < rows.length; i += 1) {
+    const id = rows[i]?.id;
+    if (id !== undefined && id !== patch.id && holding.has(id)) local += 1;
+  }
+  return { ...rest, index: local };
+}
+
 const withdrawn = (patch: RowPatch): RowPatch => ({
   op: 'delete',
   id: patch.id,

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';