@helipod/sync 0.1.0

package/dist/index.js

@@ -0,0 +1,1354 @@
+// src/protocol.ts
+var INITIAL_VERSION = { querySet: 0, ts: 0 };
+function versionsEqual(a, b) {
+  return a.querySet === b.querySet && a.ts === b.ts;
+}
+function compareStateVersion(a, b) {
+  if (a.querySet !== b.querySet) return a.querySet < b.querySet ? -1 : 1;
+  if (a.ts !== b.ts) return a.ts < b.ts ? -1 : 1;
+  return 0;
+}
+function isContiguous(prevEnd, nextStart) {
+  return versionsEqual(prevEnd, nextStart);
+}
+function parseClientMessage(raw) {
+  return JSON.parse(raw);
+}
+function encodeServerMessage(msg) {
+  return JSON.stringify(msg);
+}
+
+// src/change.ts
+function applyChanges(rows, changes) {
+  const out = new Map(rows);
+  for (const c of changes) {
+    if (c.t === "remove") out.delete(c.key);
+    else out.set(c.key, { row: c.row, ts: c.ts, orderKey: c.orderKey });
+  }
+  return out;
+}
+function driftChecksum(rows) {
+  let acc = 0;
+  for (const [key, rv] of rows) {
+    let h = 2166136261;
+    const mix = (byte) => {
+      h ^= byte;
+      h = Math.imul(h, 16777619) >>> 0;
+    };
+    for (let i = 0; i < key.length; i++) mix(key.charCodeAt(i) & 255);
+    mix(0);
+    const tsStr = String(rv.ts);
+    for (let i = 0; i < tsStr.length; i++) mix(tsStr.charCodeAt(i) & 255);
+    mix(0);
+    const ok = rv.orderKey ?? "";
+    for (let i = 0; i < ok.length; i++) mix(ok.charCodeAt(i) & 255);
+    acc = (acc ^ h >>> 0) >>> 0;
+  }
+  return acc.toString(16).padStart(8, "0");
+}
+
+// src/subscription-manager.ts
+import { deserializeKeyRange, IntervalIndex } from "@helipod/index-key-codec";
+function subKey(sessionId, queryId) {
+  return `${sessionId} ${queryId}`;
+}
+var SubscriptionManager = class {
+  byKey = /* @__PURE__ */ new Map();
+  byTable = /* @__PURE__ */ new Map();
+  byRange = new IntervalIndex();
+  tableFallbackKeys = /* @__PURE__ */ new Set();
+  deserializedRanges = /* @__PURE__ */ new Map();
+  /**
+   * M2c: index from global (D1) table name -> subscription keys whose read set touched it, via
+   * `Subscription.globalTables`. Populated UNCONDITIONALLY in `add` (independent of
+   * `readRanges`/`tableFallbackKeys`) so a MIXED subscription — one with both local `readRanges`
+   * and a global-table read — still lands here. Matched by a THIRD, ungated loop in
+   * `findAffectedByRanges`; the existing table-fallback loop is gated on `tableFallbackKeys`
+   * precisely because it must NOT fire for a sub with non-empty `readRanges`, but global-table
+   * reads have no `readRanges` entry of their own, so that gate would wrongly exclude a mixed sub.
+   */
+  byGlobalTable = /* @__PURE__ */ new Map();
+  add(sub) {
+    const key = subKey(sub.sessionId, sub.queryId);
+    this.removeKey(key);
+    this.byKey.set(key, sub);
+    for (const table of sub.tables) {
+      let set = this.byTable.get(table);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        this.byTable.set(table, set);
+      }
+      set.add(key);
+    }
+    if (sub.readRanges.length > 0) {
+      const ranges = sub.readRanges.map(deserializeKeyRange);
+      this.deserializedRanges.set(key, ranges);
+      for (const range of ranges) this.byRange.insert(range, key);
+    } else {
+      this.tableFallbackKeys.add(key);
+    }
+    for (const t of sub.globalTables ?? []) {
+      let s = this.byGlobalTable.get(t);
+      if (!s) {
+        s = /* @__PURE__ */ new Set();
+        this.byGlobalTable.set(t, s);
+      }
+      s.add(key);
+    }
+  }
+  removeKey(key) {
+    const existing = this.byKey.get(key);
+    if (!existing) return;
+    const ranges = this.deserializedRanges.get(key);
+    if (ranges) {
+      for (const range of ranges) this.byRange.remove(range, key);
+      this.deserializedRanges.delete(key);
+    }
+    this.tableFallbackKeys.delete(key);
+    for (const table of existing.tables) this.byTable.get(table)?.delete(key);
+    for (const t of existing.globalTables ?? []) {
+      const s = this.byGlobalTable.get(t);
+      s?.delete(key);
+      if (s && s.size === 0) this.byGlobalTable.delete(t);
+    }
+    this.byKey.delete(key);
+  }
+  remove(sessionId, queryId) {
+    this.removeKey(subKey(sessionId, queryId));
+  }
+  removeSession(sessionId) {
+    const prefix = `${sessionId} `;
+    for (const key of [...this.byKey.keys()]) if (key.startsWith(prefix)) this.removeKey(key);
+  }
+  get(sessionId, queryId) {
+    return this.byKey.get(subKey(sessionId, queryId));
+  }
+  /**
+   * Subscriptions whose read set intersects the given write ranges (surgical invalidation),
+   * unioned with table-fallback subscriptions (empty readRanges) touched by the write tables.
+   * Same result set as the retired linear scan, computed in O(log N + k) per write range.
+   */
+  findAffectedByRanges(writeRanges, writeTables) {
+    const keys = /* @__PURE__ */ new Set();
+    for (const w of writeRanges) {
+      const wr = deserializeKeyRange(w);
+      for (const key of this.byRange.queryOverlaps(wr)) keys.add(key);
+    }
+    for (const table of writeTables) {
+      const set = this.byTable.get(table);
+      if (!set) continue;
+      for (const key of set) if (this.tableFallbackKeys.has(key)) keys.add(key);
+    }
+    for (const table of writeTables) {
+      const set = this.byGlobalTable.get(table);
+      if (set) for (const key of set) keys.add(key);
+    }
+    const out = [];
+    for (const key of keys) {
+      const sub = this.byKey.get(key);
+      if (sub) out.push(sub);
+    }
+    return out;
+  }
+  /** Subscriptions whose read set touched any of the given tables (deduped). */
+  findAffectedByTables(tables) {
+    const out = /* @__PURE__ */ new Map();
+    for (const table of tables) {
+      const keys = this.byTable.get(table);
+      if (!keys) continue;
+      for (const key of keys) {
+        const sub = this.byKey.get(key);
+        if (sub) out.set(key, sub);
+      }
+    }
+    return [...out.values()];
+  }
+  /** All subscriptions for a session (e.g. to re-run them when identity changes). */
+  forSession(sessionId) {
+    const prefix = `${sessionId} `;
+    const out = [];
+    for (const [key, sub] of this.byKey) if (key.startsWith(prefix)) out.push(sub);
+    return out;
+  }
+  get size() {
+    return this.byKey.size;
+  }
+  /** Global (D1) table names with at least one live subscriber (M2c). */
+  subscribedGlobalTables() {
+    return [...this.byGlobalTable.keys()];
+  }
+};
+
+// src/resume-registry.ts
+import { deserializeKeyRange as deserializeKeyRange2, IntervalIndex as IntervalIndex2 } from "@helipod/index-key-codec";
+var TTL_MS = 6e4;
+function regKey(identity, path, argsJson) {
+  return `${identity ?? ""} ${path} ${JSON.stringify(argsJson)}`;
+}
+var ResumeRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  byTable = /* @__PURE__ */ new Map();
+  byRange = new IntervalIndex2();
+  tableFallbackKeys = /* @__PURE__ */ new Set();
+  deserializedRanges = /* @__PURE__ */ new Map();
+  upsert(key, readRanges, tables, atTs, wasDiffable, globalTables = []) {
+    const existing = this.entries.get(key);
+    const lastInvalidatedTs = Math.max(existing?.lastInvalidatedTs ?? atTs, atTs);
+    const refCount = existing?.refCount ?? 0;
+    this.unindex(key);
+    this.entries.set(key, { readRanges, tables, globalTables, lastInvalidatedTs, wasDiffable, refCount, expiresAtMs: void 0 });
+    this.index(key, readRanges, tables);
+  }
+  index(key, readRanges, tables) {
+    for (const table of tables) {
+      let set = this.byTable.get(table);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        this.byTable.set(table, set);
+      }
+      set.add(key);
+    }
+    if (readRanges.length > 0) {
+      const ranges = readRanges.map(deserializeKeyRange2);
+      this.deserializedRanges.set(key, ranges);
+      for (const range of ranges) this.byRange.insert(range, key);
+    } else {
+      this.tableFallbackKeys.add(key);
+    }
+  }
+  unindex(key) {
+    const existing = this.entries.get(key);
+    if (!existing) return;
+    const ranges = this.deserializedRanges.get(key);
+    if (ranges) {
+      for (const range of ranges) this.byRange.remove(range, key);
+      this.deserializedRanges.delete(key);
+    }
+    this.tableFallbackKeys.delete(key);
+    for (const table of existing.tables) this.byTable.get(table)?.delete(key);
+  }
+  /**
+   * Advances `lastInvalidatedTs` for every entry whose read set intersects the write — including
+   * entries with refCount 0 that are only TTL-retained (they remain indexed until swept).
+   */
+  advanceOnCommit(writtenRanges, writtenTables, commitTs) {
+    const keys = /* @__PURE__ */ new Set();
+    for (const w of writtenRanges) {
+      const wr = deserializeKeyRange2(w);
+      for (const key of this.byRange.queryOverlaps(wr)) keys.add(key);
+    }
+    for (const table of writtenTables) {
+      const set = this.byTable.get(table);
+      if (!set) continue;
+      for (const key of set) if (this.tableFallbackKeys.has(key)) keys.add(key);
+    }
+    for (const key of keys) {
+      const entry = this.entries.get(key);
+      if (entry) entry.lastInvalidatedTs = Math.max(entry.lastInvalidatedTs, commitTs);
+    }
+  }
+  lookup(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    return { readRanges: entry.readRanges, tables: entry.tables, globalTables: entry.globalTables, lastInvalidatedTs: entry.lastInvalidatedTs, wasDiffable: entry.wasDiffable };
+  }
+  retain(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return;
+    entry.refCount++;
+    entry.expiresAtMs = void 0;
+  }
+  release(key, nowMs) {
+    const entry = this.entries.get(key);
+    if (!entry) return;
+    entry.refCount--;
+    if (entry.refCount <= 0) entry.expiresAtMs = nowMs + TTL_MS;
+  }
+  /** Evicts entries with no live subscribers whose TTL has elapsed. Removes them from both indexes. */
+  sweep(nowMs) {
+    for (const [key, entry] of this.entries) {
+      if (entry.refCount <= 0 && entry.expiresAtMs !== void 0 && entry.expiresAtMs <= nowMs) {
+        this.unindex(key);
+        this.entries.delete(key);
+      }
+    }
+  }
+  /** @internal test/debug only — a live entry's current refCount, or undefined if no such entry. */
+  __refCount(key) {
+    return this.entries.get(key)?.refCount;
+  }
+  /** @internal test/debug only — a live entry's pending TTL expiry, or undefined (not pending / no
+   *  such entry). */
+  __expiresAtMs(key) {
+    return this.entries.get(key)?.expiresAtMs;
+  }
+};
+
+// src/handler.ts
+import { createHash } from "crypto";
+import { convexToJson } from "@helipod/values";
+import { isRetryableError, isHelipodError } from "@helipod/errors";
+import { tableOfKeyspaceId } from "@helipod/index-key-codec";
+
+// src/classify.ts
+import { deserializeKeyRange as deserializeKeyRange3, keySuccessor, compareKeyBytes } from "@helipod/index-key-codec";
+function isPointRange(r) {
+  if (!r.keyspace.startsWith("table:")) return false;
+  if (r.end === null) return false;
+  const { start, end } = deserializeKeyRange3(r);
+  if (end === null) return false;
+  const succ = keySuccessor(start);
+  return compareKeyBytes(end, succ) === 0;
+}
+function singleDocId(value) {
+  if (value === null || value === void 0) return "";
+  if (Array.isArray(value)) return null;
+  if (typeof value === "object") {
+    const id = value["_id"];
+    return typeof id === "string" ? id : null;
+  }
+  return null;
+}
+function classifyByIdRead(value, readRanges) {
+  if (readRanges.length !== 1) return null;
+  const r = readRanges[0];
+  if (!isPointRange(r)) return null;
+  const docId = singleDocId(value);
+  if (docId === null) return null;
+  return { keyspace: r.keyspace, key: r.start, docId };
+}
+function rangeReadFromDiffable(d) {
+  return { keyspace: d.keyspace, bounds: d.bounds, filters: d.filters, order: d.order, fields: d.fields };
+}
+function pageReadFromDiffable(d) {
+  return { keyspace: d.keyspace, bounds: d.bounds, filters: d.filters, order: d.order, fields: d.fields, pageMeta: d.pageMeta };
+}
+
+// src/commit-differ.ts
+import { evaluateFilter, extractIndexKey } from "@helipod/query-engine";
+import { deserializeKeyRange as deserializeKeyRange4, keyInRange, serializeKeyRange } from "@helipod/index-key-codec";
+function byIdChangesFor(byId, prev, wd) {
+  if (!wd) return { changes: [], next: prev };
+  if (wd.keyspace !== byId.keyspace) {
+    console.error(
+      `[sync] byIdChangesFor: wd.keyspace "${wd.keyspace}" !== byId.keyspace "${byId.keyspace}" (caller bug)`
+    );
+  }
+  const docId = wd.docId;
+  let change;
+  if (wd.newRow === null) change = { t: "remove", key: docId };
+  else if (!wd.wasPresent || !prev.has(docId)) change = { t: "add", key: docId, row: wd.newRow, ts: wd.ts };
+  else change = { t: "edit", key: docId, row: wd.newRow, ts: wd.ts };
+  const changes = [change];
+  return { changes, next: applyChanges(prev, changes) };
+}
+function byIdResetChanges(docId, row, ts) {
+  const next = /* @__PURE__ */ new Map();
+  if (row === null) return { changes: [], next };
+  next.set(docId, { row, ts });
+  return { changes: [{ t: "add", key: docId, row, ts }], next };
+}
+function toBase64(bytes) {
+  return serializeKeyRange({ keyspace: "", start: bytes, end: null }).start;
+}
+function fromBase64(b64) {
+  return deserializeKeyRange4({ keyspace: "", start: b64, end: null }).start;
+}
+function orderKeyFor(range, row) {
+  const key = extractIndexKey(row, range.fields);
+  return toBase64(key);
+}
+function inBounds(range, orderKeyB64) {
+  const bounds = deserializeKeyRange4(range.bounds);
+  return keyInRange(fromBase64(orderKeyB64), bounds);
+}
+function passesFilters(range, row) {
+  return range.filters.every((f) => evaluateFilter(row, f));
+}
+function rangeResetChanges(range, orderedDocs, ts) {
+  const changes = [];
+  const next = /* @__PURE__ */ new Map();
+  for (const row of orderedDocs) {
+    const key = String(row._id);
+    const orderKey = orderKeyFor(range, row);
+    changes.push({ t: "add", key, row, ts, orderKey });
+    next.set(key, { row, ts, orderKey });
+  }
+  return { changes, next };
+}
+function rangeChangesFor(range, prev, writtenDocs) {
+  const changes = [];
+  for (const wd of writtenDocs) {
+    const key = wd.docId;
+    const before = prev.has(key);
+    const orderKey = wd.newRow !== null ? orderKeyFor(range, wd.newRow) : void 0;
+    const after = wd.newRow !== null && orderKey !== void 0 && inBounds(range, orderKey) && passesFilters(range, wd.newRow);
+    if (!before && after) changes.push({ t: "add", key, row: wd.newRow, ts: wd.ts, orderKey });
+    else if (before && after) changes.push({ t: "edit", key, row: wd.newRow, ts: wd.ts, orderKey });
+    else if (before && !after) changes.push({ t: "remove", key });
+  }
+  return { changes, next: applyChanges(prev, changes) };
+}
+
+// src/session-controllers.ts
+var DEFAULT_HIGH_WATER = 1024 * 1024;
+var DEFAULT_MAX_QUEUED = 200;
+var DEFAULT_SLOW_CLIENT_MS = 3e4;
+var SessionBackpressureController = class {
+  constructor(socket, opts = {}, now = () => Date.now(), onOverflow = () => {
+  }) {
+    this.socket = socket;
+    this.now = now;
+    this.onOverflow = onOverflow;
+    this.highWaterBytes = opts.highWaterBytes ?? DEFAULT_HIGH_WATER;
+    this.maxQueuedFrames = opts.maxQueuedFrames ?? DEFAULT_MAX_QUEUED;
+    this.slowClientTimeoutMs = opts.slowClientTimeoutMs ?? DEFAULT_SLOW_CLIENT_MS;
+    this.maxUndroppableQueuedFrames = opts.maxUndroppableQueuedFrames ?? this.maxQueuedFrames;
+  }
+  socket;
+  now;
+  onOverflow;
+  highWaterBytes;
+  maxQueuedFrames;
+  slowClientTimeoutMs;
+  maxUndroppableQueuedFrames;
+  queue = [];
+  _droppedFrames = 0;
+  /** Count of undroppable frames currently sitting in `queue` — the separate overflow budget. */
+  undroppableQueuedCount = 0;
+  /** True once `onOverflow` has fired, so a dying session can't fire it twice. */
+  overflowed = false;
+  /** Wall-clock ms at which the current backpressure episode began, or null if not backpressured. */
+  backpressureSince = null;
+  /** True once any frame has been dropped in the current episode; resets on full drain. */
+  _droppedThisEpisode = false;
+  get droppedFrames() {
+    return this._droppedFrames;
+  }
+  /** True once anything was dropped since the last fully-drained state (the per-episode warn flag). */
+  get droppedThisEpisode() {
+    return this._droppedThisEpisode;
+  }
+  /**
+   * The ONLY way frames leave a session. Sends now, queues, or drops per the class contract.
+   * `undroppable` (default false) exempts a frame from BOTH drop paths below — the cap check
+   * and the sustained-backpressure abandon — so it only ever queues or sends, never vanishes.
+   */
+  send(data, undroppable = false) {
+    this.flush();
+    if (this.queue.length === 0 && this.socket.bufferedAmount < this.highWaterBytes) {
+      this.socket.send(data);
+      return;
+    }
+    if (undroppable) {
+      if (this.undroppableQueuedCount >= this.maxUndroppableQueuedFrames) {
+        this.overflow();
+        return;
+      }
+      this.queue.push({ data, undroppable: true });
+      this.undroppableQueuedCount += 1;
+      return;
+    }
+    if (this.backpressureSince === null) this.backpressureSince = this.now();
+    if (this.now() - this.backpressureSince >= this.slowClientTimeoutMs) {
+      this.dropQueue();
+      this.countDrop();
+      return;
+    }
+    if (this.queue.length >= this.maxQueuedFrames) {
+      this.countDrop();
+      return;
+    }
+    this.queue.push({ data, undroppable: false });
+  }
+  /**
+   * Deliver as many queued frames as the socket buffer will take. Called before each send and on a
+   * periodic sweep, so a client that recovers (or goes terminally slow) without new traffic still
+   * gets its queue drained (or abandoned). Resets the episode once fully drained.
+   */
+  flush() {
+    while (this.queue.length > 0 && this.socket.bufferedAmount < this.highWaterBytes) {
+      const frame = this.queue.shift();
+      if (frame.undroppable) this.undroppableQueuedCount -= 1;
+      this.socket.send(frame.data);
+    }
+    if (this.queue.length === 0 && this.socket.bufferedAmount < this.highWaterBytes) {
+      this.backpressureSince = null;
+      this._droppedThisEpisode = false;
+      return;
+    }
+    if (this.backpressureSince === null) this.backpressureSince = this.now();
+    if (this.queue.length > 0 && this.now() - this.backpressureSince >= this.slowClientTimeoutMs) {
+      this.dropQueue();
+    }
+  }
+  /** Abandon the queue to drops — EXCEPT undroppable frames, which stay queued for a later flush. */
+  dropQueue() {
+    const survivors = this.queue.filter((f) => f.undroppable);
+    const droppedCount = this.queue.length - survivors.length;
+    if (droppedCount === 0) return;
+    this._droppedFrames += droppedCount;
+    this.queue.length = 0;
+    this.queue.push(...survivors);
+    this.markEpisodeDropped();
+  }
+  countDrop() {
+    this._droppedFrames += 1;
+    this.markEpisodeDropped();
+  }
+  /**
+   * The undroppable queue exceeded its cap. Fires `onOverflow` exactly once (a session that's
+   * already dying doesn't need a second kill signal) with a distinct, greppable log reason —
+   * deliberately NOT reusing the backpressure-drop warning text, since this is a different failure
+   * mode (session termination, not a dropped frame) that ops needs to be able to tell apart.
+   */
+  overflow() {
+    if (this.overflowed) return;
+    this.overflowed = true;
+    console.warn(
+      `[sync] undroppable-queue-overflow: terminating session (queued undroppable frames >= cap=${this.maxUndroppableQueuedFrames})`
+    );
+    this.onOverflow();
+  }
+  markEpisodeDropped() {
+    if (this._droppedThisEpisode) return;
+    this._droppedThisEpisode = true;
+    console.warn(`[sync] backpressure: dropping frames for slow client (total dropped=${this._droppedFrames})`);
+  }
+};
+var DEFAULT_PING_INTERVAL_MS = 3e4;
+var DEFAULT_MISSED_PONG_LIMIT = 2;
+var SessionHeartbeatController = class {
+  constructor(socket, onDead, opts = {}) {
+    this.socket = socket;
+    this.onDead = onDead;
+    this.pingIntervalMs = opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+    this.missedPongLimit = opts.missedPongLimit ?? DEFAULT_MISSED_PONG_LIMIT;
+  }
+  socket;
+  onDead;
+  pingIntervalMs;
+  missedPongLimit;
+  timer = null;
+  missed = 0;
+  dead = false;
+  /** Begin pinging. No-op when the socket cannot ping (loopback exemption) or already started. */
+  start() {
+    if (!this.socket.ping) return;
+    if (this.timer !== null) return;
+    this.missed = 0;
+    this.dead = false;
+    this.timer = setInterval(() => this.tick(), this.pingIntervalMs);
+  }
+  stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** Any inbound message is liveness credit — resets the consecutive-miss counter. */
+  noteActivity() {
+    this.missed = 0;
+  }
+  tick() {
+    this.socket.ping?.(() => {
+      this.missed = 0;
+    });
+    this.missed += 1;
+    if (this.missed >= this.missedPongLimit) this.fireDead();
+  }
+  fireDead() {
+    if (this.dead) return;
+    this.dead = true;
+    this.stop();
+    this.onDead();
+  }
+};
+
+// src/handler.ts
+var FLUSH_SWEEP_MS = 1e3;
+function errMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+var COMMITTED_TS_ERROR_KEY = /* @__PURE__ */ Symbol.for("helipod.executor.committedTs");
+function committedTsOfError(e) {
+  if (e !== null && typeof e === "object") {
+    const ts = e[COMMITTED_TS_ERROR_KEY];
+    if (typeof ts === "number") return ts;
+  }
+  return void 0;
+}
+function subKey2(sessionId, queryId) {
+  return `${sessionId} ${queryId}`;
+}
+function hashValue(value) {
+  return "sha256:" + createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+var SyncProtocolHandler = class {
+  constructor(executor, options = {}) {
+    this.executor = executor;
+    this.options = options;
+    this.verifyAdmin = options.verifyAdmin ?? (() => false);
+    if (!options.disableBackgroundTimers) {
+      this.sweepTimer = setInterval(() => {
+        for (const session of this.sessions.values()) session.bp.flush();
+        this.resumeRegistry.sweep(Date.now());
+      }, FLUSH_SWEEP_MS);
+      this.sweepTimer.unref?.();
+    }
+  }
+  executor;
+  options;
+  sessions = /* @__PURE__ */ new Map();
+  subscriptions = new SubscriptionManager();
+  notifyTail = Promise.resolve();
+  /**
+   * G4 fleet fallback (client-sync verdict §(d) item 2): sessionId → the commitTs of a FORWARDED
+   * mutation whose origin tag couldn't ride this (forwarding) node's local fan-out. Satisfied with
+   * an empty ts-advancing Transition once the drain processes a commit at-or-above it (gated on the
+   * drain's last-processed commitTs — see `sweepPendingFrontiers`). Holds at most one entry per
+   * in-flight forwarded mutation per session; cleared on satisfy or disconnect, so the sweep it
+   * drives stays tiny (usually empty on a single-node deployment, where nothing is ever forwarded).
+   */
+  pendingFrontiers = /* @__PURE__ */ new Map();
+  /**
+   * DLR 2a CommitDiffer state: `${sessionId} ${queryId}` -> the current materialized 0-or-1-row map
+   * for a DIFFABLE_BYID sub whose client is diff-capable. EPHEMERAL — reseeded on every subscribe
+   * (`doModifyQuerySet`'s reset), updated on every incremental diff (`doNotifyWrites`), and dropped on
+   * unsubscribe/disconnect. NOT a durable CVR: if lost (process restart, or a sub falling back to the
+   * RERUN/QueryUpdated path for one turn) the drift checksum's client-side mismatch check is the
+   * backstop that resyncs the one affected query — see `change.ts`'s `driftChecksum` doc comment.
+   */
+  byIdRowMap = /* @__PURE__ */ new Map();
+  /**
+   * DLR 2b — the response-before-Transition gate (replaces the fragile, timer-starvable
+   * `setTimeout(0)`). `commitTs` → a one-shot latch a diff-capable origin's OWN reactive Transition
+   * parks on inside `doNotifyWrites`, released once `processMutation` has actually enqueued that
+   * commit's `MutationResponse` onto the session's outbound queue.
+   *
+   * WHY commit-time registration (via {@link registerOriginResponseGate}, called from the runtime's
+   * fan-out subscribe callback) rather than lazily inside `doNotifyWrites`: the fan-out drain is
+   * SERIAL, so under load `doNotifyWrites` for a commit can run long after that commit's response was
+   * already sent (the drain is backed up behind a flood). Registering the gate inside `doNotifyWrites`
+   * would then happen AFTER the release — the release would find no gate (no-op), and the late gate
+   * would park FOREVER, wedging the whole `notifyTail` (the backpressure-flood regression). The
+   * subscribe callback instead fires SYNCHRONOUSLY inside the commit (before `runMutation` resolves,
+   * hence before the response can be sent), so the gate always exists before its release, whatever the
+   * drain backlog.
+   *
+   * WHY a microtask latch, not `setTimeout(0)`: the release runs as `processMutation` resumes after
+   * `await runMutation` — a MICROTASK, which a tight `await`-loop of mutations (`for (…) await
+   * client.mutation(…)`) drains between every iteration. The old timer sat in Node's TIMER phase,
+   * which that same loop STARVES; because the yield sat ON the single `notifyTail`, a starved timer
+   * stalled the entire fan-out chain. A microtask cannot be starved and cannot stall the tail.
+   *
+   * Scoped to a diff-capable LOCAL origin session (see `registerOriginResponseGate`), so every gate
+   * created here is balanced by exactly one release from that session's own `processMutation` — on
+   * EVERY post-commit outcome: the success path releases inline, and a commit-then-throw (or any
+   * throw after the commit) releases from its catch via the `committedTs` the executor stamps on the
+   * error (see `releaseOriginResponseGate`/`committedTsOfError`). Entries are transient: one per
+   * in-flight diff-capable-origin commit, created at commit and dropped on release (or on
+   * `disconnect`, which resolves+drops any still-pending gate for the vanishing session so a
+   * mid-flight teardown can never strand a parked `doNotifyWrites`). The `sessionId` is retained so
+   * that disconnect backstop can find a session's gates in this commitTs-keyed map.
+   */
+  originResponseGates = /* @__PURE__ */ new Map();
+  /**
+   * DLR Stage 3: the compute-saving half of reconnect resume (see `resume-registry.ts`'s doc
+   * comment). Populated on every subscribe (`doModifyQuerySet`), advanced on every commit
+   * (`doNotifyWrites`, unconditionally — independent of `bySession`, so an entry with zero live
+   * subscribers still advances during its TTL-retained "gap"), and retain/release-tracked across
+   * subscribe/unsubscribe/disconnect. Not yet CONSULTED anywhere (that's a later task) — this task
+   * only keeps it correctly populated.
+   */
+  resumeRegistry = new ResumeRegistry();
+  /**
+   * M2c fix: callbacks registered via {@link onGlobalSubscribe}, fired whenever a subscription is
+   * (re-)registered with a non-empty `globalTables` read set — from `doModifyQuerySet` (fresh
+   * subscribe, or a resume-skip carrying a retained global-table read set), from `handleSetAuth`'s
+   * re-exec (an identity flip can make a query newly read a global table), and from
+   * `sendSessionTransition`'s live-re-run (a data/identity-dependent query can shift onto a global
+   * table across a RERUN refresh). See `DriverContext.onGlobalSubscribe`'s doc comment
+   * (`@helipod/component`) for why this exists — closing the busy-DO-late-subscribe gap in the
+   * M2c global-reactivity poller.
+   */
+  globalSubscribeListeners = [];
+  verifyAdmin;
+  /** Periodic drain sweep — drains recovered clients and abandons terminally-slow queues. */
+  sweepTimer = null;
+  connect(sessionId, socket) {
+    const bp = new SessionBackpressureController(socket, this.options.backpressure, void 0, () => this.reap(sessionId));
+    const hb = new SessionHeartbeatController(socket, () => this.reap(sessionId), this.options.heartbeat);
+    this.sessions.set(sessionId, { sessionId, socket, version: { ...INITIAL_VERSION }, identity: null, privileged: false, bp, hb, supportsQueryDiff: false });
+    if (!this.options.disableBackgroundTimers) hb.start();
+  }
+  disconnect(sessionId) {
+    const session = this.sessions.get(sessionId);
+    session?.hb.stop();
+    for (const sub of this.subscriptions.forSession(sessionId)) {
+      if (sub.resumeKey) this.resumeRegistry.release(sub.resumeKey, Date.now());
+    }
+    this.subscriptions.removeSession(sessionId);
+    this.sessions.delete(sessionId);
+    this.pendingFrontiers.delete(sessionId);
+    this.clearByIdRowMapForSession(sessionId);
+    for (const [commitTs, gate] of this.originResponseGates) {
+      if (gate.sessionId === sessionId) this.releaseOriginResponseGate(commitTs);
+    }
+  }
+  /** Drop every `byIdRowMap` entry for a session (disconnect/reap) — ephemeral per-sub state, never
+   *  durable, so there's nothing to persist on the way out. */
+  clearByIdRowMapForSession(sessionId) {
+    const prefix = `${sessionId} `;
+    for (const key of [...this.byIdRowMap.keys()]) if (key.startsWith(prefix)) this.byIdRowMap.delete(key);
+  }
+  /** Reap a session whose heartbeat went dead: close the socket, then tear down like a disconnect. */
+  reap(sessionId) {
+    this.sessions.get(sessionId)?.socket.close();
+    this.disconnect(sessionId);
+  }
+  /** Stop the background sweep. Call on shutdown; sessions must already be disconnected. */
+  dispose() {
+    if (this.sweepTimer !== null) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+  /** @internal test/debug only — the live ResumeRegistry (DLR Stage 3), for tests to assert
+   *  population/advance/retain-release wiring without duplicating its internals. */
+  get __resumeRegistry() {
+    return this.resumeRegistry;
+  }
+  /** @internal test/debug only — the live SubscriptionManager (M2c), for tests to assert
+   *  registration wiring (e.g. `globalTables`) without duplicating its internals. */
+  get __subscriptions() {
+    return this.subscriptions;
+  }
+  /**
+   * M2c Task 6: global (D1-backed) table names with at least one live subscriber right now —
+   * delegates to `SubscriptionManager.subscribedGlobalTables()`. This is the ONLY thing a
+   * `GlobalReactivityPoller` needs from the sync tier to decide which tables are worth polling D1
+   * for (its other dependency, `notifyWrites`, already exists on this class). A public method
+   * (unlike `__subscriptions` above) because it is a real runtime dependency wired onto
+   * `DriverContext`, not a test-only escape hatch.
+   */
+  subscribedGlobalTables() {
+    return this.subscriptions.subscribedGlobalTables();
+  }
+  /**
+   * M2c fix: register `cb` to fire whenever a subscription is (re-)registered with a non-empty
+   * global-table read set — a fresh `doModifyQuerySet` subscribe/resume, a `handleSetAuth` re-exec,
+   * or a `sendSessionTransition` live-re-run (see the `globalSubscribeListeners` field doc for all
+   * three sites). A driver (e.g. `GlobalReactivityPollerDriver`) uses this to arm itself on any of
+   * these late/renewed subscribes, rather than relying solely on a boot-time force-arm that a busy
+   * (never-hibernating) DO may never repeat. Not unsubscribed — callers are drivers with the same
+   * lifetime as this handler.
+   */
+  onGlobalSubscribe(cb) {
+    this.globalSubscribeListeners.push(cb);
+  }
+  /** Fire every registered {@link onGlobalSubscribe} listener. Swallows listener throws (never let a
+   *  driver's own bug break subscription registration). */
+  fireGlobalSubscribe() {
+    for (const cb of this.globalSubscribeListeners) {
+      try {
+        cb();
+      } catch (e) {
+        console.error("[sync] onGlobalSubscribe listener threw:", e);
+      }
+    }
+  }
+  send(session, msg) {
+    const undroppable = msg.type === "MutationResponse" || msg.type === "ActionResponse";
+    session.bp.send(encodeServerMessage(msg), undroppable);
+  }
+  /**
+   * `MutationResponse.ts` (W1) must be the mutation's real commitTs — a client-side optimistic-
+   * update gate treats it as an ack signal, and a `0` (or absent) commitTs there would either
+   * false-close the gate immediately or wedge a pending layer forever. `commitTs` SHOULD always
+   * be a positive integer for a committed mutation; the one known way it can leak as `<= 0` is
+   * the `?? 0n` fallback for a forwarded-fleet-write whose owner commitTs didn't make it back
+   * (`runtime-embedded/src/runtime.ts`). This codebase has no existing dev/prod split (no
+   * `NODE_ENV`/`__DEV__` convention anywhere in `packages/`), so this is unconditional: log
+   * loudly every time, and never put a lying `0` on the wire — omit `ts` instead, which is
+   * exactly the pre-W1 wire shape every client already knows how to handle.
+   */
+  mutationResponseTs(commitTs) {
+    if (commitTs > 0) return commitTs;
+    console.error(
+      `[sync] MutationResponse: commitTs invariant violated (expected > 0, got ${commitTs}); omitting ts from the wire`
+    );
+    return void 0;
+  }
+  async handleMessage(sessionId, raw) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`unknown session: ${sessionId}`);
+    session.hb.noteActivity();
+    const msg = parseClientMessage(raw);
+    switch (msg.type) {
+      case "Connect":
+        return this.handleConnect(session, msg);
+      case "ModifyQuerySet":
+        return this.handleModifyQuerySet(session, msg);
+      case "Mutation":
+        return this.handleMutation(session, msg);
+      case "MutationBatch":
+        return this.handleMutationBatch(session, msg);
+      case "Action":
+        return this.handleAction(session, msg);
+      case "EphemeralPublish":
+        this.publishEphemeral(msg.topic, msg.event, sessionId);
+        return;
+      case "SetAuth":
+        return this.handleSetAuth(session, msg);
+      case "SetAdminAuth":
+        return this.handleSetAdminAuth(session, msg);
+    }
+  }
+  /** Run a subscription's query — privileged for _admin:* on a privileged session; else identity-scoped. */
+  async execSub(session, udfPath, args) {
+    if (udfPath.startsWith("_admin:")) {
+      if (!session.privileged) throw new Error("Forbidden: admin subscription requires admin auth");
+      return this.executor.runAdminQuery(udfPath, args);
+    }
+    return this.executor.runQuery(udfPath, args, session.identity);
+  }
+  /**
+   * G1 hardening (client-sync verdict §(d) item 3): a query-set change is SERIALIZED with the
+   * reactive fan-out on the same `notifyTail`, per handler. The shipped code ran MQS inline while
+   * `notifyWrites` ran on the tail, so a concurrent invalidation could deliver a NEWER value and
+   * then MQS deliver an OLDER one under contiguous brackets — a silent base regression (with
+   * optimistic layers, "your own committed write vanishes"). Enqueuing MQS on the tail makes the two
+   * strictly ordered: the enqueued unit reads `session.version` at EXECUTION time (inside
+   * `doModifyQuerySet`), so its bracket chains contiguously off whatever notify ran just before it.
+   * `execSub`→`runQuery` never re-enters this tail (it's a pure engine read), so there is no
+   * deadlock — subscribe just waits behind any pending notifies (the accepted latency cost).
+   */
+  handleModifyQuerySet(session, msg) {
+    const run = this.notifyTail.then(() => this.doModifyQuerySet(session, msg));
+    this.notifyTail = run.catch(() => void 0);
+    return run;
+  }
+  async doModifyQuerySet(session, msg) {
+    const modifications = [];
+    for (const q of msg.add) {
+      try {
+        if (q.sinceTs !== void 0) {
+          const rrKey2 = regKey(session.identity, q.udfPath, q.args);
+          const entry = this.resumeRegistry.lookup(rrKey2);
+          if (entry && !entry.wasDiffable && entry.globalTables.length === 0 && entry.lastInvalidatedTs <= q.sinceTs) {
+            this.subscriptions.add({
+              sessionId: session.sessionId,
+              queryId: q.queryId,
+              udfPath: q.udfPath,
+              args: q.args,
+              tables: [...entry.tables],
+              readRanges: entry.readRanges,
+              globalTables: [...entry.globalTables],
+              byId: void 0,
+              resumeKey: rrKey2
+            });
+            this.resumeRegistry.retain(rrKey2);
+            if (entry.globalTables.length > 0) this.fireGlobalSubscribe();
+            modifications.push({ type: "QueryUnchanged", queryId: q.queryId });
+            continue;
+          }
+        }
+        const { value, tables, readRanges, globalTables, diffableRange, diffablePage } = await this.execSub(session, q.udfPath, q.args);
+        const byId = classifyByIdRead(value, readRanges) ?? void 0;
+        const range = diffableRange ? rangeReadFromDiffable(diffableRange) : void 0;
+        const page = diffablePage ? pageReadFromDiffable(diffablePage) : void 0;
+        const rrKey = regKey(session.identity, q.udfPath, q.args);
+        this.subscriptions.add({ sessionId: session.sessionId, queryId: q.queryId, udfPath: q.udfPath, args: q.args, tables, readRanges, globalTables, byId, range: page ?? range, resumeKey: rrKey });
+        if (globalTables.length > 0) this.fireGlobalSubscribe();
+        const wasDiffable = !!(diffableRange || diffablePage || byId);
+        this.resumeRegistry.upsert(rrKey, readRanges, tables, session.version.ts, wasDiffable, globalTables);
+        this.resumeRegistry.retain(rrKey);
+        const json = convexToJson(value);
+        if (page && session.supportsQueryDiff) {
+          const orderedRows = json.page;
+          const { changes, next } = rangeResetChanges(page, orderedRows, session.version.ts);
+          this.byIdRowMap.set(subKey2(session.sessionId, q.queryId), next);
+          const hash = hashValue(json);
+          if (q.resultHash !== void 0 && q.resultHash === hash) {
+            modifications.push({ type: "QueryUnchanged", queryId: q.queryId });
+          } else {
+            modifications.push({
+              type: "QueryDiff",
+              queryId: q.queryId,
+              changes,
+              checksum: driftChecksum(next),
+              reset: {
+                mode: "page",
+                orderDir: page.order,
+                nextCursor: page.pageMeta.nextCursor,
+                hasMore: page.pageMeta.hasMore,
+                scanCapped: page.pageMeta.scanCapped
+              },
+              hash
+            });
+          }
+        } else if (range && session.supportsQueryDiff) {
+          const { changes, next } = rangeResetChanges(range, json, session.version.ts);
+          this.byIdRowMap.set(subKey2(session.sessionId, q.queryId), next);
+          const hash = hashValue(json);
+          if (q.resultHash !== void 0 && q.resultHash === hash) {
+            modifications.push({ type: "QueryUnchanged", queryId: q.queryId });
+          } else {
+            modifications.push({
+              type: "QueryDiff",
+              queryId: q.queryId,
+              changes,
+              checksum: driftChecksum(next),
+              reset: { mode: "range", orderDir: range.order },
+              hash
+            });
+          }
+        } else if (byId && session.supportsQueryDiff) {
+          const { changes, next } = byIdResetChanges(byId.docId, json, session.version.ts);
+          this.byIdRowMap.set(subKey2(session.sessionId, q.queryId), next);
+          const hash = hashValue(json);
+          if (q.resultHash !== void 0 && q.resultHash === hash) {
+            modifications.push({ type: "QueryUnchanged", queryId: q.queryId });
+          } else {
+            modifications.push({ type: "QueryDiff", queryId: q.queryId, changes, checksum: driftChecksum(next), reset: true, hash });
+          }
+        } else {
+          const hash = hashValue(json);
+          if (q.resultHash !== void 0 && q.resultHash === hash) {
+            modifications.push({ type: "QueryUnchanged", queryId: q.queryId });
+          } else {
+            modifications.push({ type: "QueryUpdated", queryId: q.queryId, value: json, hash });
+          }
+        }
+      } catch (e) {
+        modifications.push({ type: "QueryFailed", queryId: q.queryId, error: errMessage(e) });
+      }
+    }
+    for (const queryId of msg.remove) {
+      const removedSub = this.subscriptions.get(session.sessionId, queryId);
+      if (removedSub?.resumeKey) {
+        this.resumeRegistry.release(removedSub.resumeKey, Date.now());
+      }
+      this.subscriptions.remove(session.sessionId, queryId);
+      this.byIdRowMap.delete(subKey2(session.sessionId, queryId));
+      modifications.push({ type: "QueryRemoved", queryId });
+    }
+    const start = session.version;
+    const end = { querySet: start.querySet + 1, ts: start.ts };
+    session.version = end;
+    this.send(session, { type: "Transition", startVersion: start, endVersion: end, modifications });
+  }
+  async handleMutation(session, msg) {
+    await this.processMutation(session, msg);
+  }
+  /**
+   * A drained-outbox chunk (verdict §(e)): ONE inbound message carrying N entries. Applied
+   * SEQUENTIALLY (`await` each in order) — the client sends only one unacked chunk at a time and
+   * relies on per-client FIFO, so units MUST commit in order. One `MutationResponse` is emitted per
+   * entry as it settles, EXCEPT when a unit fails TRANSIENTLY (see `processMutation`'s doc comment):
+   * that unit still gets its failure response, but the loop then STOPS — the remaining entries get
+   * NO response at all, preserving the FIFO drain obligation (a causally-dependent later unit must
+   * never apply after an earlier transient/infra failure). The client's one-unacked-chunk-at-a-time
+   * protocol resends the whole chunk on the next attempt; per-seq receipts make that resend safe
+   * (an already-applied unit replay-acks instead of re-running).
+   */
+  async handleMutationBatch(session, msg) {
+    for (const entry of msg.entries) {
+      const outcome = await this.processMutation(session, entry);
+      if (outcome === "stop") break;
+    }
+  }
+  /**
+   * The per-unit mutation core shared by `Mutation` and `MutationBatch` — threads the durable
+   * `(clientId, seq)` down to the OWNER's classification (verdict §(c)), sends the response, and
+   * (for a fresh commit only) fans out. A `MutationReplay` return skips `notifyWrites` AND the G4
+   * pending-frontier entirely (nothing was written this call — Risk R7): its `commitTs` is the
+   * ORIGINAL, long past the current frontier, so arming a frontier or fanning out would be a lie.
+   *
+   * Returns `"continue" | "stop"` — meaningful only to `handleMutationBatch`'s drain loop (a
+   * standalone `Mutation` ignores it). A thrown error is classified via the executor's retryable
+   * discipline (`isRetryableError`, `@helipod/errors` — the same classification
+   * `handleDedupError`'s dedup path already applies when deciding whether to record a verdict):
+   *  - TERMINAL (not retryable — a deterministic app error, a coded verdict failure/replay) means the
+   *    executor already recorded whatever verdict applies; the batch drain CONTINUES past it (a
+   *    poison unit never blocks the rest — matches the spec's documented mid-batch-continue case).
+   *  - TRANSIENT (retryable — infra/conflict) means nothing durable happened for this unit; the batch
+   *    drain STOPS here so a later, causally-dependent unit can never apply out of order relative to
+   *    it. The remaining units get no response and the client's FIFO resend picks them back up.
+   */
+  async processMutation(session, unit) {
+    const dedup = unit.clientId !== void 0 && unit.seq !== void 0 ? { clientId: unit.clientId, seq: unit.seq } : void 0;
+    try {
+      const r = await this.executor.runMutation(unit.udfPath, unit.args, session.identity, session.sessionId, dedup);
+      if (r.replayed) {
+        if (r.verdict === "applied") {
+          this.send(session, {
+            type: "MutationResponse",
+            requestId: unit.requestId,
+            success: true,
+            replayed: true,
+            ts: r.commitTs !== void 0 ? this.mutationResponseTs(r.commitTs) : void 0,
+            ...r.valueMissing ? { valueMissing: true } : { value: convexToJson(r.value) }
+          });
+        } else {
+          this.send(session, {
+            type: "MutationResponse",
+            requestId: unit.requestId,
+            success: false,
+            error: r.code ?? (r.verdict === "stale" ? "STALE_CLIENT" : "mutation failed"),
+            code: r.code ?? (r.verdict === "stale" ? "STALE_CLIENT" : void 0)
+          });
+        }
+        return "continue";
+      }
+      const { value, tables, writeRanges, commitTs, forwarded } = r;
+      this.send(session, {
+        type: "MutationResponse",
+        requestId: unit.requestId,
+        success: true,
+        value: convexToJson(value),
+        ts: this.mutationResponseTs(commitTs)
+      });
+      this.releaseOriginResponseGate(commitTs);
+      if (forwarded && commitTs > 0) {
+        const prev = this.pendingFrontiers.get(session.sessionId);
+        if (prev === void 0 || commitTs > prev) this.pendingFrontiers.set(session.sessionId, commitTs);
+      }
+      if (this.options.autoNotifyOnMutation !== false) {
+        await this.notifyWrites({ tables, ranges: writeRanges, commitTs }, session.sessionId);
+      }
+      return "continue";
+    } catch (e) {
+      const committedTs = committedTsOfError(e);
+      if (committedTs !== void 0) this.releaseOriginResponseGate(committedTs);
+      this.send(session, {
+        type: "MutationResponse",
+        requestId: unit.requestId,
+        success: false,
+        error: errMessage(e),
+        code: isHelipodError(e) && !isRetryableError(e) ? e.code : void 0
+      });
+      return isRetryableError(e) ? "stop" : "continue";
+    }
+  }
+  /**
+   * The `Connect` resume handshake (verdict §(e)): activated from the reserved no-op. Classifies each
+   * presented `held` seq into `ConnectAck.results`, ack-prunes the `ackedThrough` contiguous
+   * settled-prefix, and stamps the `deploymentId` (same-timeline proof, §(g) hazard 15). `known`
+   * is false when the client presents history the server recognizes NONE of (a swept/foreign timeline
+   * → the client resets). A bare `Connect` (no `clientId`/`held`/`ackedThrough`, or an executor with
+   * no receipts support) stays the pre-Outbox no-op: no ConnectAck is sent, bit-for-bit.
+   */
+  async handleConnect(session, msg) {
+    session.supportsQueryDiff = msg.supportsQueryDiff === true;
+    if (msg.clientId === void 0 && msg.held === void 0 && msg.ackedThrough === void 0) return;
+    if (!this.executor.classifyClientMutation || !this.executor.deploymentId) return;
+    const results = [];
+    let recognizedAny = false;
+    let presentedAny = false;
+    for (const ref of msg.held ?? []) {
+      presentedAny = true;
+      const v = await this.executor.classifyClientMutation(session.identity, ref.clientId, ref.seq);
+      if (v.verdict !== "unknown") recognizedAny = true;
+      results.push(v);
+    }
+    for (const ref of msg.ackedThrough ?? []) {
+      presentedAny = true;
+      if (this.executor.classifyClientMutation) {
+        const v = await this.executor.classifyClientMutation(session.identity, ref.clientId, ref.seq);
+        if (v.verdict !== "unknown") recognizedAny = true;
+      }
+      await this.executor.pruneClientMutations?.(session.identity, ref.clientId, ref.seq);
+    }
+    this.send(session, {
+      type: "ConnectAck",
+      known: presentedAny ? recognizedAny : true,
+      results,
+      deploymentId: this.executor.deploymentId()
+    });
+  }
+  /**
+   * A one-shot request→value call — NOT reactive (an action has no read/write set of its own).
+   * Deliberately does NOT call `notifyWrites`: any mutation the action invoked via
+   * `ctx.runMutation` already fanned out through that mutation's own commit.
+   */
+  async handleAction(session, msg) {
+    try {
+      const { value } = await this.executor.runAction(msg.udfPath, msg.args, session.identity);
+      this.send(session, { type: "ActionResponse", requestId: msg.requestId, success: true, value: convexToJson(value) });
+    } catch (e) {
+      this.send(session, { type: "ActionResponse", requestId: msg.requestId, success: false, error: errMessage(e) });
+    }
+  }
+  /**
+   * Reactive fan-out: recompute subscriptions a write touched and push transitions. Calls are
+   * serialized so per-session version brackets advance monotonically (concurrent notifies
+   * would otherwise reorder and trigger false client resyncs).
+   */
+  notifyWrites(invalidation, originSessionId) {
+    const run = this.notifyTail.then(() => this.doNotifyWrites(invalidation, originSessionId));
+    this.notifyTail = run.catch(() => void 0);
+    return run;
+  }
+  async doNotifyWrites(invalidation, originSessionId) {
+    if (!invalidation.global) {
+      this.resumeRegistry.advanceOnCommit(invalidation.ranges ?? [], invalidation.tables, invalidation.commitTs);
+    }
+    this.resumeRegistry.sweep(Date.now());
+    const affected = this.subscriptions.findAffectedByRanges(invalidation.ranges ?? [], invalidation.tables);
+    const bySession = /* @__PURE__ */ new Map();
+    for (const sub of affected) {
+      if (this.options.excludeOriginFromTransition && sub.sessionId === originSessionId) continue;
+      const list = bySession.get(sub.sessionId) ?? [];
+      list.push(sub);
+      bySession.set(sub.sessionId, list);
+    }
+    const originIsDiffCapable = !!originSessionId && bySession.has(originSessionId) && this.sessions.get(originSessionId)?.supportsQueryDiff === true;
+    for (const [sessionId, subs] of bySession) {
+      if (originIsDiffCapable && sessionId === originSessionId) continue;
+      const session = this.sessions.get(sessionId);
+      if (!session) continue;
+      await this.sendSessionTransition(session, subs, invalidation);
+    }
+    if (originIsDiffCapable) {
+      const originSubs = bySession.get(originSessionId);
+      const originSession = this.sessions.get(originSessionId);
+      const gate = this.originResponseGates.get(invalidation.commitTs);
+      if (gate) await gate.promise;
+      await this.sendSessionTransition(originSession, originSubs, invalidation);
+    }
+    if (!invalidation.global) {
+      this.advanceOriginFrontier(originSessionId, bySession, invalidation.commitTs);
+      this.sweepPendingFrontiers(invalidation.commitTs, bySession);
+    }
+  }
+  /**
+   * DLR 2b — register the response-before-Transition gate for `commitTs`, at COMMIT time. Called
+   * SYNCHRONOUSLY from the runtime's fan-out subscribe callback (which fires inside the commit,
+   * before `runMutation` resolves and thus before this commit's `MutationResponse` can be sent), so
+   * the gate reliably exists before {@link releaseOriginResponseGate} runs — no matter how backed up
+   * the serial fan-out drain is. Public because the decoupled runtime owns the commit-time seam.
+   *
+   * Registers ONLY for a diff-capable LOCAL origin session — exactly the case `doNotifyWrites` parks
+   * on, and exactly the case whose own `processMutation` will release it, so every gate is balanced
+   * (no leak). A no-origin commit, a foreign/absent session, or a diff-incapable session registers
+   * nothing. Idempotent per `commitTs`.
+   */
+  registerOriginResponseGate(commitTs, originSessionId) {
+    if (originSessionId === void 0) return;
+    if (this.sessions.get(originSessionId)?.supportsQueryDiff !== true) return;
+    if (this.originResponseGates.has(commitTs)) return;
+    let resolve;
+    const promise = new Promise((r) => resolve = r);
+    this.originResponseGates.set(commitTs, { promise, resolve, sessionId: originSessionId });
+  }
+  /**
+   * DLR 2b — release (and drop) the response gate for `commitTs`. Called right after the commit's
+   * `MutationResponse` is enqueued, so the parked origin Transition flushes strictly behind it. A
+   * no-op when no gate is registered (a diff-incapable / no-origin commit never registered one) — so
+   * an ordinary commit costs nothing here.
+   */
+  releaseOriginResponseGate(commitTs) {
+    const gate = this.originResponseGates.get(commitTs);
+    if (gate !== void 0) {
+      this.originResponseGates.delete(commitTs);
+      gate.resolve();
+    }
+  }
+  /**
+   * Compute one session's modifications for this commit (by-id / range `QueryDiff` incremental arms,
+   * or the RERUN `QueryUpdated`/`QueryFailed` arm) and send its Transition. Extracted from
+   * `doNotifyWrites`'s per-session loop body (byte-identical logic) so the origin session's own call
+   * can be deferred past the response-ordering macrotask yield while every non-origin session is
+   * computed+sent immediately, with no shared logic duplicated between the two call sites.
+   */
+  async sendSessionTransition(session, subs, invalidation) {
+    const modifications = [];
+    for (const sub of subs) {
+      try {
+        const key = subKey2(sub.sessionId, sub.queryId);
+        if (sub.range && session.supportsQueryDiff && invalidation.writtenDocs) {
+          const subTable = tableOfKeyspaceId(sub.range.keyspace);
+          const wds = invalidation.writtenDocs.filter((w) => tableOfKeyspaceId(w.keyspace) === subTable);
+          const prevMap = this.byIdRowMap.get(key) ?? /* @__PURE__ */ new Map();
+          const { changes, next } = rangeChangesFor(sub.range, prevMap, wds);
+          this.byIdRowMap.set(key, next);
+          modifications.push({ type: "QueryDiff", queryId: sub.queryId, changes, checksum: driftChecksum(next) });
+          continue;
+        }
+        if (sub.byId && session.supportsQueryDiff && invalidation.writtenDocs) {
+          const wd = invalidation.writtenDocs.find(
+            (w) => w.keyspace === sub.byId.keyspace && w.key === sub.byId.key
+          );
+          const prevMap = this.byIdRowMap.get(key) ?? /* @__PURE__ */ new Map();
+          const { changes, next } = byIdChangesFor(sub.byId, prevMap, wd);
+          this.byIdRowMap.set(key, next);
+          modifications.push({ type: "QueryDiff", queryId: sub.queryId, changes, checksum: driftChecksum(next) });
+          continue;
+        }
+        const { value, tables, readRanges, globalTables, diffableRange, diffablePage } = await this.execSub(session, sub.udfPath, sub.args);
+        const byId = classifyByIdRead(value, readRanges) ?? void 0;
+        const range = diffableRange ? rangeReadFromDiffable(diffableRange) : void 0;
+        const page = diffablePage ? pageReadFromDiffable(diffablePage) : void 0;
+        this.subscriptions.add({ ...sub, tables, readRanges, globalTables, byId, range: page ?? range });
+        if (globalTables.length > 0) this.fireGlobalSubscribe();
+        if (sub.resumeKey) {
+          this.resumeRegistry.upsert(sub.resumeKey, readRanges, tables, Number(invalidation.commitTs), !!(page ?? range) || !!byId, globalTables);
+        }
+        if (sub.byId && (!byId || byId.keyspace !== sub.byId.keyspace || byId.key !== sub.byId.key)) {
+          this.byIdRowMap.delete(subKey2(sub.sessionId, sub.queryId));
+        }
+        if (sub.range) {
+          this.byIdRowMap.delete(subKey2(sub.sessionId, sub.queryId));
+        }
+        const json = convexToJson(value);
+        modifications.push({ type: "QueryUpdated", queryId: sub.queryId, value: json, hash: hashValue(json) });
+      } catch (e) {
+        modifications.push({ type: "QueryFailed", queryId: sub.queryId, error: errMessage(e) });
+      }
+    }
+    const start = session.version;
+    const end = { querySet: start.querySet, ts: invalidation.global ? start.ts : invalidation.commitTs };
+    session.version = end;
+    this.send(session, { type: "Transition", startVersion: start, endVersion: end, modifications });
+  }
+  /** Emit a standalone empty ts-advancing Transition — advances `session.version.ts` to `ts` with no
+   *  modifications. The one construct that closes a client's optimistic-update gate for a commit that
+   *  touched nothing the session subscribes to. Callers guard `ts > session.version.ts` (monotone). */
+  emitEmptyFrontier(session, ts) {
+    const start = session.version;
+    const end = { querySet: start.querySet, ts };
+    session.version = end;
+    this.send(session, { type: "Transition", startVersion: start, endVersion: end, modifications: [] });
+  }
+  /** G4 primary: advance the LOCAL origin session's frontier when its own commit missed all its
+   *  subscriptions. A local commit supersedes any stale forwarded fallback entry for that session. */
+  advanceOriginFrontier(originSessionId, bySession, commitTs) {
+    if (!originSessionId || bySession.has(originSessionId)) return;
+    const session = this.sessions.get(originSessionId);
+    if (!session || commitTs <= session.version.ts) return;
+    this.emitEmptyFrontier(session, commitTs);
+    this.pendingFrontiers.delete(originSessionId);
+  }
+  /** G4 fleet fallback: satisfy pending forwarded-mutation frontiers now that the drain reached
+   *  `drainTs`. A frontier still above `drainTs` waits for a later drain; one already covered by the
+   *  session's own subscription update (in `bySession` this drain, or an earlier ts advance) clears
+   *  without a redundant frame; otherwise an empty ts-advance to the frontier is emitted. */
+  sweepPendingFrontiers(drainTs, bySession) {
+    if (this.pendingFrontiers.size === 0) return;
+    for (const [sessionId, frontierTs] of this.pendingFrontiers) {
+      if (frontierTs > drainTs) continue;
+      const session = this.sessions.get(sessionId);
+      if (session && session.version.ts < frontierTs && !bySession.has(sessionId)) {
+        this.emitEmptyFrontier(session, frontierTs);
+      }
+      this.pendingFrontiers.delete(sessionId);
+    }
+  }
+  async handleSetAdminAuth(session, msg) {
+    session.privileged = this.verifyAdmin(msg.key);
+  }
+  async handleSetAuth(session, msg) {
+    session.identity = msg.token;
+    const subs = this.subscriptions.forSession(session.sessionId);
+    const modifications = [];
+    for (const sub of subs) {
+      try {
+        const { value, tables, readRanges, globalTables, diffableRange, diffablePage } = await this.execSub(session, sub.udfPath, sub.args);
+        const byId = classifyByIdRead(value, readRanges) ?? void 0;
+        const range = diffableRange ? rangeReadFromDiffable(diffableRange) : void 0;
+        const page = diffablePage ? pageReadFromDiffable(diffablePage) : void 0;
+        const newResumeKey = regKey(session.identity, sub.udfPath, sub.args);
+        this.resumeRegistry.upsert(newResumeKey, readRanges, tables, session.version.ts, !!(page ?? range) || !!byId, globalTables);
+        if (sub.resumeKey !== newResumeKey) {
+          this.resumeRegistry.retain(newResumeKey);
+          if (sub.resumeKey) this.resumeRegistry.release(sub.resumeKey, Date.now());
+        }
+        this.subscriptions.add({ ...sub, tables, readRanges, globalTables, byId, range: page ?? range, resumeKey: newResumeKey });
+        if (globalTables.length > 0) this.fireGlobalSubscribe();
+        const key = subKey2(session.sessionId, sub.queryId);
+        const json = convexToJson(value);
+        if (byId && session.supportsQueryDiff) {
+          const { changes, next } = byIdResetChanges(byId.docId, json, session.version.ts);
+          this.byIdRowMap.set(key, next);
+          modifications.push({ type: "QueryDiff", queryId: sub.queryId, changes, checksum: driftChecksum(next), reset: true });
+        } else {
+          this.byIdRowMap.delete(key);
+          modifications.push({ type: "QueryUpdated", queryId: sub.queryId, value: json, hash: hashValue(json) });
+        }
+      } catch (e) {
+        modifications.push({ type: "QueryFailed", queryId: sub.queryId, error: errMessage(e) });
+      }
+    }
+    const start = session.version;
+    const end = { querySet: start.querySet + 1, ts: start.ts };
+    session.version = end;
+    this.send(session, { type: "Transition", startVersion: start, endVersion: end, modifications });
+  }
+  /** Ephemeral broadcast (presence/typing) — bypasses the engine entirely. */
+  publishEphemeral(topic, event, fromSessionId) {
+    for (const [sessionId, session] of this.sessions) {
+      if (sessionId === fromSessionId) continue;
+      this.send(session, { type: "Broadcast", topic, event });
+    }
+  }
+};
+
+// src/client-reducer.ts
+function createClientState() {
+  return {
+    version: { ...INITIAL_VERSION },
+    queries: /* @__PURE__ */ new Map(),
+    needsResync: false,
+    mutationResults: /* @__PURE__ */ new Map(),
+    broadcasts: []
+  };
+}
+function applyServerMessage(state, msg) {
+  switch (msg.type) {
+    case "Transition": {
+      if (!versionsEqual(msg.startVersion, state.version)) {
+        state.needsResync = true;
+        return;
+      }
+      for (const mod of msg.modifications) {
+        if (mod.type === "QueryUpdated") state.queries.set(mod.queryId, mod.value);
+        else if (mod.type === "QueryRemoved") state.queries.delete(mod.queryId);
+      }
+      state.version = msg.endVersion;
+      return;
+    }
+    case "MutationResponse":
+      state.mutationResults.set(
+        msg.requestId,
+        msg.success ? { success: true, value: msg.value } : { success: false, error: msg.error }
+      );
+      return;
+    case "Broadcast":
+      state.broadcasts.push({ topic: msg.topic, event: msg.event });
+      return;
+    default:
+      return;
+  }
+}
+export {
+  INITIAL_VERSION,
+  ResumeRegistry,
+  SessionBackpressureController,
+  SessionHeartbeatController,
+  SubscriptionManager,
+  SyncProtocolHandler,
+  TTL_MS,
+  applyChanges,
+  applyServerMessage,
+  compareStateVersion,
+  createClientState,
+  driftChecksum,
+  encodeServerMessage,
+  isContiguous,
+  parseClientMessage,
+  regKey,
+  versionsEqual
+};
+//# sourceMappingURL=index.js.map