@spooky-sync/core 0.0.1-canary.154 → 0.0.1-canary.155

package/dist/tabs-broker-worker.js

@@ -0,0 +1,434 @@
+//#region src/services/tabs/tabs-broker-worker.ts
+const PING_INTERVAL_MS = 5e3;
+const PONG_TIMEOUT_MS = 15e3;
+const FORCE_TAKEOVER_TIMEOUT_MS = 1e3;
+const LEADER_FAILURE_BACKOFF_MS = 1e3;
+const OPFS_FAILED_CYCLES_BEFORE_MEMORY = 3;
+const brokerInstanceId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `bk_${Math.random().toString(36).slice(2)}`;
+const namespaces = /* @__PURE__ */ new Map();
+/** Reverse index: which namespace a port belongs to (for pong routing). */
+const portTab = /* @__PURE__ */ new Map();
+/** The FIRST fingerprint wins for the whole broker instance; a tab from a
+*  different build gets `unsupported` and runs solo. Bucket ids may differ. */
+let canonicalFingerprint = null;
+let pingTimer = null;
+function post(port, msg, transfer) {
+	try {
+		if (transfer) port.postMessage(msg, transfer);
+		else port.postMessage(msg);
+	} catch {}
+}
+function nsKey(fingerprint, bucketId) {
+	return `${fingerprint}::${bucketId}`;
+}
+function getNamespace(fingerprint, bucketId) {
+	const key = nsKey(fingerprint, bucketId);
+	let ns = namespaces.get(key);
+	if (!ns) {
+		ns = {
+			key,
+			fingerprint,
+			bucketId,
+			tabs: /* @__PURE__ */ new Map(),
+			leader: null,
+			failedUntil: /* @__PURE__ */ new Map(),
+			opfsFailedCycles: 0,
+			electing: false,
+			attachRetry: /* @__PURE__ */ new Map(),
+			tabLockMonitor: null
+		};
+		namespaces.set(key, ns);
+	}
+	return ns;
+}
+let nextLeadershipId = 0;
+/** Duplicated from protocol.ts selectLeaderCandidate; keep in sync. */
+function pickCandidate(ns) {
+	const now = Date.now();
+	const eligible = [...ns.tabs.values()].filter((t) => {
+		if ((ns.failedUntil.get(t.tabId) ?? 0) > now) return false;
+		ns.failedUntil.delete(t.tabId);
+		return true;
+	});
+	if (eligible.length === 0) return null;
+	const holding = eligible.filter((t) => t.heldLeadership !== null);
+	const base = holding.length > 0 ? holding : eligible;
+	const visible = base.filter((t) => t.visibility === "visible");
+	return (visible.length > 0 ? visible : base).reduce((best, t) => {
+		if (t.lastVisibleAt !== best.lastVisibleAt) return t.lastVisibleAt > best.lastVisibleAt ? t : best;
+		return t.tabId > best.tabId ? t : best;
+	});
+}
+function clearLeader(ns, opts) {
+	const leader = ns.leader;
+	if (!leader) return null;
+	ns.leader = null;
+	ns.tabLockMonitor?.abort();
+	ns.tabLockMonitor = null;
+	const tab = ns.tabs.get(leader.tabId);
+	const workerLock = tab?.heldLeadership?.workerLockName ?? null;
+	if (tab && opts.demote) post(tab.port, {
+		type: "demote",
+		brokerInstanceId,
+		leadershipId: leader.leadershipId
+	});
+	if (opts.removeTab && tab) removeTab(ns, leader.tabId, { notifyLeader: false });
+	for (const t of ns.tabs.values()) if (t.tabId !== leader.tabId) post(t.port, {
+		type: "close-follower-ports",
+		brokerInstanceId,
+		leadershipId: leader.leadershipId
+	});
+	for (const [, retry] of ns.attachRetry) if (retry.timer) clearTimeout(retry.timer);
+	ns.attachRetry.clear();
+	return {
+		tabId: leader.tabId,
+		leadershipId: leader.leadershipId,
+		workerLock
+	};
+}
+/**
+* Fast crash detection: queue a Web Lock request on the leader's tab lock.
+* Locks release the instant their holder's tab dies, so being GRANTED means
+* the leader is gone; release immediately (return from the callback) and
+* re-elect. The leadershipId guard drops stale grants after a normal handoff.
+*/
+function startTabLockMonitor(ns, leadershipId) {
+	const locks = navigator.locks;
+	if (!locks) return;
+	ns.tabLockMonitor?.abort();
+	const controller = new AbortController();
+	ns.tabLockMonitor = controller;
+	const name = `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:tab`;
+	locks.request(name, {
+		mode: "exclusive",
+		signal: controller.signal
+	}, () => {
+		if (ns.leader?.leadershipId !== leadershipId) return;
+		electIfNeeded(ns, clearLeader(ns, {
+			demote: true,
+			removeTab: true
+		}));
+	}).catch(() => {});
+}
+/** Probe whether a lock name is free by acquiring-and-releasing it. */
+async function lockIsFree(name) {
+	const locks = navigator.locks;
+	if (!locks) return true;
+	try {
+		return await locks.request(name, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, (lock) => Promise.resolve(lock !== null));
+	} catch {
+		return true;
+	}
+}
+async function stealLock(name) {
+	const locks = navigator.locks;
+	if (!locks) return;
+	try {
+		await locks.request(name, {
+			mode: "exclusive",
+			steal: true
+		}, () => Promise.resolve());
+	} catch {}
+}
+/**
+* Before promoting a replacement, give the previous leader's locks a chance to
+* free naturally (dead tab: released instantly; frozen tab: never). Returns
+* whether a steal was needed, which the new leader passes to its worker open.
+*/
+async function waitForPreviousLeaderLocks(previous) {
+	if (!previous?.workerLock) return false;
+	if (await lockIsFree(previous.workerLock)) return false;
+	await new Promise((r) => setTimeout(r, FORCE_TAKEOVER_TIMEOUT_MS));
+	if (await lockIsFree(previous.workerLock)) return false;
+	await stealLock(previous.workerLock);
+	return true;
+}
+function electIfNeeded(ns, previous = null) {
+	if (ns.electing || ns.leader || ns.tabs.size === 0) return;
+	ns.electing = true;
+	(async () => {
+		try {
+			const forceTakeover = await waitForPreviousLeaderLocks(previous);
+			if (ns.leader || ns.tabs.size === 0) return;
+			const candidate = pickCandidate(ns);
+			if (!candidate) {
+				const soonest = Math.min(...[...ns.failedUntil.values()], Date.now() + LEADER_FAILURE_BACKOFF_MS);
+				setTimeout(() => electIfNeeded(ns), Math.max(50, soonest - Date.now()));
+				return;
+			}
+			const resumeHeld = candidate.heldLeadership !== null;
+			const leadershipId = ++nextLeadershipId;
+			ns.leader = {
+				tabId: candidate.tabId,
+				leadershipId,
+				ready: false
+			};
+			post(candidate.port, {
+				type: "become-leader",
+				brokerInstanceId,
+				leadershipId,
+				forceTakeover,
+				allowMemoryFallback: ns.opfsFailedCycles >= OPFS_FAILED_CYCLES_BEFORE_MEMORY,
+				resumeHeld
+			});
+		} finally {
+			ns.electing = false;
+		}
+	})();
+}
+function assignFollowerPorts(ns) {
+	const leader = ns.leader;
+	if (!leader || !leader.ready) return;
+	const leaderTab = ns.tabs.get(leader.tabId);
+	if (!leaderTab) return;
+	for (const tab of ns.tabs.values()) {
+		if (tab.tabId === leader.tabId) continue;
+		if (ns.attachRetry.has(tab.tabId)) continue;
+		mintPorts(ns, leaderTab, tab, leader.leadershipId);
+	}
+}
+function mintPorts(ns, leaderTab, follower, leadershipId) {
+	const db = new MessageChannel();
+	const sync = new MessageChannel();
+	post(leaderTab.port, {
+		type: "attach-follower-ports",
+		brokerInstanceId,
+		leadershipId,
+		followerTabId: follower.tabId
+	}, [db.port1, sync.port1]);
+	post(follower.port, {
+		type: "use-follower-ports",
+		brokerInstanceId,
+		leadershipId,
+		leaderTabId: leaderTab.tabId
+	}, [db.port2, sync.port2]);
+	const state = ns.attachRetry.get(follower.tabId) ?? {
+		count: 0,
+		timer: null
+	};
+	const delay = Math.min(1e3 * 2 ** state.count, 3e4);
+	state.count += 1;
+	state.timer = setTimeout(() => {
+		const cur = ns.attachRetry.get(follower.tabId);
+		if (!cur) return;
+		cur.timer = null;
+		const stillLeader = ns.leader && ns.leader.leadershipId === leadershipId && ns.leader.ready;
+		const stillHere = ns.tabs.get(follower.tabId);
+		const leaderNow = stillLeader ? ns.tabs.get(ns.leader.tabId) : void 0;
+		if (stillLeader && stillHere && leaderNow) mintPorts(ns, leaderNow, stillHere, leadershipId);
+		else ns.attachRetry.delete(follower.tabId);
+	}, delay);
+	ns.attachRetry.set(follower.tabId, state);
+}
+function followerAttached(ns, followerTabId) {
+	const retry = ns.attachRetry.get(followerTabId);
+	if (retry?.timer) clearTimeout(retry.timer);
+	ns.attachRetry.delete(followerTabId);
+}
+function ensurePingTimer() {
+	if (pingTimer) return;
+	pingTimer = setInterval(() => {
+		const now = Date.now();
+		for (const ns of namespaces.values()) for (const tab of [...ns.tabs.values()]) {
+			if (now - tab.lastPongAt > PONG_TIMEOUT_MS) {
+				evictTab(ns, tab.tabId, "missed pongs");
+				continue;
+			}
+			post(tab.port, {
+				type: "ping",
+				brokerInstanceId
+			});
+		}
+		stopPingTimerIfIdle();
+	}, PING_INTERVAL_MS);
+}
+function stopPingTimerIfIdle() {
+	if (pingTimer && [...namespaces.values()].every((ns) => ns.tabs.size === 0)) {
+		clearInterval(pingTimer);
+		pingTimer = null;
+		namespaces.clear();
+		canonicalFingerprint = null;
+	}
+}
+function removeTab(ns, tabId, opts) {
+	const tab = ns.tabs.get(tabId);
+	if (!tab) return;
+	ns.tabs.delete(tabId);
+	portTab.delete(tab.port);
+	if (opts.closePort !== false) try {
+		tab.port.close();
+	} catch {}
+	const retry = ns.attachRetry.get(tabId);
+	if (retry?.timer) clearTimeout(retry.timer);
+	ns.attachRetry.delete(tabId);
+	if (opts.notifyLeader && ns.leader && ns.leader.tabId !== tabId) {
+		const leaderTab = ns.tabs.get(ns.leader.tabId);
+		if (leaderTab) post(leaderTab.port, {
+			type: "close-follower-ports",
+			brokerInstanceId,
+			leadershipId: ns.leader.leadershipId
+		});
+	}
+}
+function evictTab(ns, tabId, reason, opts = {}) {
+	const wasLeader = ns.leader?.tabId === tabId;
+	const previous = wasLeader ? clearLeader(ns, {
+		demote: true,
+		removeTab: false
+	}) : null;
+	removeTab(ns, tabId, {
+		notifyLeader: !wasLeader,
+		closePort: opts.closePort
+	});
+	if (wasLeader) electIfNeeded(ns, previous);
+	stopPingTimerIfIdle();
+}
+function handleTabMessage(port, msg, ports) {
+	if (msg.type === "hello") {
+		if (canonicalFingerprint === null) canonicalFingerprint = msg.fingerprint;
+		if (msg.fingerprint !== canonicalFingerprint) {
+			post(port, {
+				type: "unsupported",
+				brokerInstanceId,
+				reason: "fingerprint-mismatch"
+			});
+			return;
+		}
+		const ns = getNamespace(msg.fingerprint, msg.bucketId);
+		for (const other of [...namespaces.values()]) if (other.tabs.has(msg.tabId)) evictTab(other, msg.tabId, "rehello", { closePort: false });
+		const tab = {
+			port,
+			tabId: msg.tabId,
+			fingerprint: msg.fingerprint,
+			bucketId: msg.bucketId,
+			visibility: msg.visibility,
+			lastVisibleAt: msg.visibility === "visible" ? Date.now() : 0,
+			lastPongAt: Date.now(),
+			heldLeadership: msg.heldLeadership
+		};
+		ns.tabs.set(msg.tabId, tab);
+		portTab.set(port, {
+			ns,
+			tabId: msg.tabId
+		});
+		ensurePingTimer();
+		post(port, {
+			type: "broker-hello",
+			brokerInstanceId
+		});
+		if (ns.leader?.ready) {
+			post(port, {
+				type: "leader-ready",
+				brokerInstanceId,
+				leadershipId: ns.leader.leadershipId,
+				leaderTabId: ns.leader.tabId
+			});
+			assignFollowerPorts(ns);
+		} else electIfNeeded(ns);
+		return;
+	}
+	const entry = portTab.get(port);
+	if (!entry) return;
+	const { ns } = entry;
+	switch (msg.type) {
+		case "pong": {
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) tab.lastPongAt = Date.now();
+			break;
+		}
+		case "visibility": {
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) {
+				tab.visibility = msg.visibility;
+				if (msg.visibility === "visible") tab.lastVisibleAt = Date.now();
+				tab.lastPongAt = Date.now();
+			}
+			break;
+		}
+		case "leader-ready": {
+			if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) {
+				post(port, {
+					type: "demote",
+					brokerInstanceId,
+					leadershipId: msg.leadershipId
+				});
+				break;
+			}
+			ns.leader.ready = true;
+			ns.opfsFailedCycles = 0;
+			startTabLockMonitor(ns, msg.leadershipId);
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) tab.heldLeadership = {
+				leadershipId: msg.leadershipId,
+				workerLockName: `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:worker:${msg.leadershipId}`
+			};
+			for (const t of ns.tabs.values()) post(t.port, {
+				type: "leader-ready",
+				brokerInstanceId,
+				leadershipId: msg.leadershipId,
+				leaderTabId: msg.tabId
+			});
+			assignFollowerPorts(ns);
+			break;
+		}
+		case "leader-failed": {
+			if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) break;
+			if (msg.reason.includes("opfs-unavailable")) ns.opfsFailedCycles += 1;
+			ns.failedUntil.set(msg.tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
+			const previous = clearLeader(ns, {
+				demote: false,
+				removeTab: false
+			});
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) tab.heldLeadership = null;
+			electIfNeeded(ns, previous);
+			break;
+		}
+		case "follower-port-attached":
+			if (ns.leader?.tabId === msg.tabId && ns.leader.leadershipId === msg.leadershipId) followerAttached(ns, msg.followerTabId);
+			break;
+		case "follower-port-closed": {
+			if (ns.leader?.tabId !== msg.tabId) break;
+			followerAttached(ns, msg.followerTabId);
+			const leaderTab = ns.tabs.get(ns.leader.tabId);
+			const follower = ns.tabs.get(msg.followerTabId);
+			if (leaderTab && follower && ns.leader.ready) mintPorts(ns, leaderTab, follower, ns.leader.leadershipId);
+			break;
+		}
+		case "shutdown":
+			evictTab(ns, msg.tabId, "shutdown");
+			break;
+	}
+}
+/** Attach a connecting tab's port. Exported for the node test harness, which
+*  drives the broker with fake MessagePort pairs instead of a SharedWorker. */
+function handleConnect(port) {
+	port.onmessage = (ev) => {
+		handleTabMessage(port, ev.data, ev.ports ?? []);
+	};
+	port.onmessageerror = () => {
+		const entry = portTab.get(port);
+		if (entry) evictTab(entry.ns, entry.tabId, "messageerror");
+	};
+	port.start?.();
+}
+/** Test-only: wipe module state so each test starts with a fresh broker. */
+function __resetBrokerForTests() {
+	if (pingTimer) clearInterval(pingTimer);
+	pingTimer = null;
+	for (const ns of namespaces.values()) for (const [, retry] of ns.attachRetry) if (retry.timer) clearTimeout(retry.timer);
+	namespaces.clear();
+	portTab.clear();
+	canonicalFingerprint = null;
+	nextLeadershipId = 0;
+}
+if (typeof self !== "undefined") self.onconnect = (event) => {
+	const port = event.ports[0];
+	if (port) handleConnect(port);
+};
+
+//#endregion
+export { __resetBrokerForTests, handleConnect };

package/dist/types.d.ts

@@ -470,6 +470,24 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * this engine. See `services/database/cache-engine.ts`.
    */
   localEngine?: LocalEngineChoice;
+  /**
+   * Share ONE durable local store across all tabs of this origin (default
+   * `false`). Requires `localEngine: 'sqlite'`. A SharedWorker broker elects a
+   * leader tab per bucket via Web Locks; the leader owns the OPFS SQLite
+   * worker and the sync loop, and follower tabs read/write the same store over
+   * MessagePorts, so every tab is durable instead of only the first one.
+   *
+   * Falls back to solo mode (exactly the flag-off behavior, including the
+   * later-tabs in-memory fallback reported via {@link StorageHealth}) whenever
+   * SharedWorker, Web Locks, or MessageChannel are unavailable, the engine is
+   * not sqlite, or the broker rejects the tab (mixed app versions).
+   *
+   * Failover: when the leader tab closes or freezes, a follower is promoted
+   * within seconds; queries briefly refetch and mutations are never lost once
+   * their local write resolved (the shared outbox survives in the store).
+   * Inspect via `window.__00__.getState().database.tabs` and `__sqliteStats`.
+   */
+  sharedTabs?: boolean;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**
@@ -593,6 +611,13 @@ interface StorageHealth {
   fallback: boolean;
   /** Reason durable storage failed (only set while `fallback` is `true`). */
   error?: string;
+  /**
+   * Shared-tabs role, set only when `sharedTabs` is active: `'leader'` owns
+   * the OPFS worker, `'follower'` shares it over a MessagePort (its data IS
+   * durable, hence `status: 'persistent'`), `'solo'` fell back to the
+   * single-tab behavior. Absent entirely when the feature is off.
+   */
+  role?: 'leader' | 'follower' | 'solo';
 }
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.154",
+  "version": "0.0.1-canary.155",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   "scripts": {
     "dev": "tsdown --watch",
     "dev:example": "pnpm dev",
-    "build": "tsdown",
+    "build": "tsdown && node scripts/check-broker-bundle.mjs",
     "test": "vitest"
   },
   "repository": {
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.154",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.154",
+    "@spooky-sync/query-builder": "0.0.1-canary.155",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.155",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/scripts/check-broker-bundle.mjs

@@ -0,0 +1,33 @@
+// Build gate: dist/tabs-broker-worker.js must be self-contained ESM.
+// Bundlers cannot trace `new SharedWorker(url)` module graphs, so any
+// import statement surviving into the emitted broker file would 404 at
+// runtime in consumers (the file is fetched as a bare URL, its relative
+// chunk siblings are not copied along). Run after `tsdown` in the build.
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dist = resolve(dirname(fileURLToPath(import.meta.url)), '../dist/tabs-broker-worker.js');
+
+let code;
+try {
+  code = readFileSync(dist, 'utf8');
+} catch {
+  console.error(`check-broker-bundle: ${dist} missing; did tsdown run?`);
+  process.exit(1);
+}
+
+const problems = [];
+// Static or dynamic imports of sibling chunks.
+const importRe = /(?:^|\n)\s*import[\s(]/;
+if (importRe.test(code)) problems.push('contains an import statement');
+if (!code.includes('onconnect')) problems.push('missing onconnect handler');
+
+if (problems.length > 0) {
+  console.error(`check-broker-bundle: dist/tabs-broker-worker.js ${problems.join('; ')}.`);
+  console.error(
+    'The broker worker must stay free of runtime imports (type-only imports are fine in source).'
+  );
+  process.exit(1);
+}
+console.log('check-broker-bundle: ok');

package/src/modules/cache/index.ts

@@ -18,10 +18,23 @@ export * from './types';
  * Single responsibility: Handle all local storage operations and DBSP ingestion.
  * This module acts as the bridge between data operations and persistence.
  */
+/** One ingested change, in exactly the shape `ingestMany` consumes. Shared
+ *  with the tabs protocol so a leader can relay its ingests to followers. */
+export interface CacheIngestTuple {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  id: string;
+  record: Record<string, unknown>;
+}
+
 export class CacheModule implements StreamUpdateReceiver {
   private logger: Logger;
   private streamUpdateCallback: (update: StreamUpdate) => void;
   private versionLookups: Record<string, number> = {};
+  /** Shared-tabs leader: fan every committed ingest out to follower circuits.
+   *  Fired AFTER the local tx (the rows are already in the shared store, so a
+   *  follower only needs the circuit feed). Never set on followers. */
+  private ingestRelay: ((tuples: CacheIngestTuple[]) => void) | null = null;
 
   constructor(
     private local: LocalStore,
@@ -51,6 +64,26 @@ export class CacheModule implements StreamUpdateReceiver {
     this.streamUpdateCallback(update);
   }
 
+  setIngestRelay(cb: ((tuples: CacheIngestTuple[]) => void) | null): void {
+    this.ingestRelay = cb;
+  }
+
+  /**
+   * Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
+   * The rows are already in the shared store (the leader wrote them), so no
+   * local write happens here; the normal chain then runs: SSP -> stream update
+   * -> DataModule debounce -> materializeRecords (re-reads via the port
+   * transport) -> this tab's subscriptions fire with this tab's hashes.
+   */
+  applyRelayedIngest(tuples: CacheIngestTuple[]): void {
+    for (const t of tuples) {
+      const rv = (t.record as { _00_rv?: number } | undefined)?._00_rv;
+      if (t.op === 'DELETE') delete this.versionLookups[t.id];
+      else if (typeof rv === 'number') this.versionLookups[t.id] = rv;
+    }
+    this.streamProcessor.ingestMany(tuples as Parameters<StreamProcessorService['ingestMany']>[0]);
+  }
+
   public lookup(recordId: string): number {
     return this.versionLookups[recordId] ?? 0;
   }
@@ -146,6 +179,7 @@ export class CacheModule implements StreamUpdateReceiver {
         return { table: record.table, op: record.op, id: recordId, record: record.record };
       });
       this.streamProcessor.ingestMany(bulk);
+      this.ingestRelay?.(bulk as CacheIngestTuple[]);
 
       this.logger.debug(
         { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
@@ -187,6 +221,7 @@ export class CacheModule implements StreamUpdateReceiver {
       // 2. Ingest deletion into DBSP (pass record data so predicates can be matched)
       delete this.versionLookups[id];
       this.streamProcessor.ingest(table, 'DELETE', id, recordData);
+      this.ingestRelay?.([{ table, op: 'DELETE', id, record: recordData }]);
 
       this.logger.debug(
         { table, id, Category: 'sp00ky-client::CacheModule::delete' },

package/src/modules/data/index.ts

@@ -44,6 +44,7 @@ import {
 import type { CreateEvent, DeleteEvent, UpdateEvent } from '../sync/index';
 import type { PushEventOptions } from '../../events/index';
 import { buildWindowMaterialization, buildWindowMaterializationPlan } from './window-query';
+import { mintMutationId } from './mutation-id';
 
 /** Push a timing sample (ms) into a rolling window, capped at the sample window. */
 function pushSample(samples: number[], ms: number): void {
@@ -68,6 +69,9 @@ function phaseStatOf(samples: number[], lastMs: number | null): PhaseStat {
  * Uses CacheModule for all storage operations.
  */
 export class DataModule<S extends SchemaStructure> {
+  /** Tab identity baked into mutation ids (shared-tabs rollback routing);
+   *  undefined in solo mode, where mutation-id falls back to a session id. */
+  private tabId: string | undefined;
   private activeQueries: Map<QueryHash, QueryState> = new Map();
   private pendingQueries: Map<QueryHash, Promise<QueryHash>> = new Map();
   private subscriptions: Map<QueryHash, Set<QueryUpdateCallback>> = new Map();
@@ -155,6 +159,12 @@ export class DataModule<S extends SchemaStructure> {
     this.sessionId = sessionId;
   }
 
+  /** Shared-tabs: bake this tab's identity into mutation ids so a rollback of
+   *  a follower's mutation routes back to the tab that made it. */
+  setTabId(tabId: string): void {
+    this.tabId = tabId;
+  }
+
   /**
    * Update the authenticated user record id. Pass `null` on sign-out.
    * Read by `Sp00kySync.listRefTable()` so the LIVE subscription and
@@ -1246,7 +1256,7 @@ export class DataModule<S extends SchemaStructure> {
 
     const rid = parseRecordIdString(id);
     const params = parseParams(tableSchema.columns, data);
-    const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
+    const mutationId = parseRecordIdString(mintMutationId(this.tabId));
 
     const dataKeys = Object.keys(params).map((key) => ({ key, variable: `data_${key}` }));
     const prefixedParams = Object.fromEntries(
@@ -1317,7 +1327,7 @@ export class DataModule<S extends SchemaStructure> {
 
     const rid = parseRecordIdString(id);
     const params = parseParams(tableSchema.columns, data);
-    const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
+    const mutationId = parseRecordIdString(mintMutationId(this.tabId));
 
     // Note: CRDT state is pushed directly to the _00_crdt table by CrdtField.pushToRemote(),
     // NOT through the record update pipeline. This keeps the record data clean.
@@ -1404,7 +1414,7 @@ export class DataModule<S extends SchemaStructure> {
     }
 
     const rid = parseRecordIdString(id);
-    const mutationId = parseRecordIdString(`_00_pending_mutations:${Date.now()}`);
+    const mutationId = parseRecordIdString(mintMutationId(this.tabId));
 
     // Fetch the record before deleting so DBSP can match it against query predicates
     const [beforeRecords] = await this.local.query<[Record<string, any>[]]>(

package/src/modules/data/mutation-id.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { mintMutationId, mutationOwnerTabId } from './mutation-id';
+
+// The old `_00_pending_mutations:${Date.now()}` collided within a millisecond
+// (guaranteed once multiple tabs share a store) and never actually ordered the
+// drain. These pin the new id's three properties: unique, sortable, routable.
+describe('mutation ids', () => {
+  it('never collides within a burst', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => mintMutationId('tabx')));
+    expect(ids.size).toBe(1000);
+  });
+
+  it('sorts lexicographically in mint order (ORDER BY id is chronological)', () => {
+    const ids = Array.from({ length: 200 }, () => mintMutationId('tabx'));
+    expect([...ids].sort()).toEqual(ids);
+  });
+
+  it('routes back to the owning tab', () => {
+    expect(mutationOwnerTabId(mintMutationId('tab-abc'))).toBe('tab-abc');
+  });
+
+  it('returns null for a legacy numeric id instead of misrouting', () => {
+    expect(mutationOwnerTabId('_00_pending_mutations:1753875000000')).toBeNull();
+  });
+});