@spooky-sync/core 0.0.1-canary.164 → 0.0.1-canary.167

package/dist/index.js

@@ -6543,8 +6543,8 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.164";
-const WASM_VERSION = "0.0.1-canary.164";
+const CORE_VERSION = "0.0.1-canary.167";
+const WASM_VERSION = "0.0.1-canary.167";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -9536,6 +9536,9 @@ var TabsCoordinator = class {
 			}, "Promotion failed");
 			this.hub?.detachAll();
 			this.hub = null;
+			if (previousRole === "leader") await this.deps.hooks.releaseOwnership();
+			this.tabLock?.release();
+			this.tabLock = null;
 			this.broker.send({
 				type: "leader-failed",
 				tabId: this.deps.tabId,
@@ -10884,7 +10887,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.164",
+				coreVersion: "0.0.1-canary.167",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -10998,23 +11001,27 @@ var Sp00kyClient = class {
 		this.logger.info({ Category: "sp00ky-client::Sp00kyClient::init" }, "Sp00kyClient initialization started");
 		try {
 			const bootBucket = readBootBucketHint() ?? ANON_USER_ID;
-			if (this.tabsCoordinator) try {
-				const role = await this.tabsCoordinator.start(bootBucket);
-				this.sharedActive = true;
-				this.logger.info({
-					role,
-					bootBucket,
-					Category: "sp00ky-client::Sp00kyClient::init"
-				}, "Shared-tabs role assigned");
-			} catch (e) {
-				this.logger.warn({
-					err: e,
-					Category: "sp00ky-client::Sp00kyClient::init"
-				}, "Shared-tabs unavailable; booting solo");
-				this.sharedActive = false;
-				await this.local.connect(bootBucket);
-			}
-			else await this.local.connect(bootBucket);
+			if (this.tabsCoordinator) {
+				this.tabsCoordinator.onRoleChange((role) => {
+					this.sharedActive = role !== "solo";
+				});
+				try {
+					const role = await this.tabsCoordinator.start(bootBucket);
+					this.sharedActive = true;
+					this.logger.info({
+						role,
+						bootBucket,
+						Category: "sp00ky-client::Sp00kyClient::init"
+					}, "Shared-tabs role assigned");
+				} catch (e) {
+					this.logger.warn({
+						err: e,
+						Category: "sp00ky-client::Sp00kyClient::init"
+					}, "Shared-tabs unavailable; booting solo");
+					this.sharedActive = false;
+					await this.local.connect(bootBucket);
+				}
+			} else await this.local.connect(bootBucket);
 			this.logger.debug({
 				bootBucket,
 				Category: "sp00ky-client::Sp00kyClient::init"

package/dist/tabs-broker-worker.js

@@ -3,7 +3,7 @@ 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 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). */
@@ -32,7 +32,7 @@ function getNamespace(fingerprint, bucketId) {
 			tabs: /* @__PURE__ */ new Map(),
 			leader: null,
 			failedUntil: /* @__PURE__ */ new Map(),
-			opfsFailedCycles: 0,
+			failedCycles: 0,
 			electing: false,
 			attachRetry: /* @__PURE__ */ new Map(),
 			tabLockMonitor: null
@@ -171,7 +171,7 @@ function electIfNeeded(ns, previous = null) {
 				brokerInstanceId,
 				leadershipId,
 				forceTakeover,
-				allowMemoryFallback: ns.opfsFailedCycles >= OPFS_FAILED_CYCLES_BEFORE_MEMORY,
+				allowMemoryFallback: ns.failedCycles >= FAILED_CYCLES_BEFORE_MEMORY,
 				resumeHeld
 			});
 		} finally {
@@ -358,7 +358,7 @@ function handleTabMessage(port, msg, ports) {
 				break;
 			}
 			ns.leader.ready = true;
-			ns.opfsFailedCycles = 0;
+			ns.failedCycles = 0;
 			startTabLockMonitor(ns, msg.leadershipId);
 			const tab = ns.tabs.get(msg.tabId);
 			if (tab) tab.heldLeadership = {
@@ -376,7 +376,7 @@ function handleTabMessage(port, msg, ports) {
 		}
 		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.failedCycles += 1;
 			ns.failedUntil.set(msg.tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
 			const previous = clearLeader(ns, {
 				demote: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.164",
+  "version": "0.0.1-canary.167",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.164",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.164",
+    "@spooky-sync/query-builder": "0.0.1-canary.167",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.167",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/services/tabs/coordinator.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { handleConnect, __resetBrokerForTests } from './tabs-broker-worker';
-import { installBrokerGlobals } from './fake-ports.fixture';
+import { installBrokerGlobals, installFakeLocks } from './fake-ports.fixture';
 import { TabsCoordinator, type CoordinatorHooks, type LeaderSyncHub, type SyncForwarder } from './coordinator';
 import type { StorageHealth } from '../../types';
 import type { LeaderToFollowerMessage } from './protocol';
@@ -62,12 +62,12 @@ function makeHooks(): { hooks: CoordinatorHooks; log: HookLog } {
   return { hooks, log };
 }
 
-function makeCoordinator(tabId: string) {
+function makeCoordinator(tabId: string, overrides: Partial<CoordinatorHooks> = {}) {
   const { hooks, log } = makeHooks();
   const coordinator = new TabsCoordinator({
     tabId,
     fingerprint: 'fp-coord-test',
-    hooks,
+    hooks: { ...hooks, ...overrides },
     logger: makeLogger(),
   });
   return { coordinator, log };
@@ -171,6 +171,58 @@ describe('TabsCoordinator integration', () => {
     await b.coordinator.stop();
   });
 
+  // A failed promotion must give the leader TAB lock back. The name is shared
+  // per namespace, so a leaked one makes every later election fail with
+  // 'leader tab lock unavailable': all tabs time out in start(), boot solo, and
+  // then contend for the OPFS pool individually — one busy pool wedging the
+  // whole app into the pre-shared-tabs behavior it exists to replace.
+  describe('with Web Locks', () => {
+    let locks: ReturnType<typeof installFakeLocks>;
+    beforeEach(() => {
+      locks = installFakeLocks();
+    });
+    afterEach(() => locks.restore());
+
+    /** A tab whose store can never open. Resolves once it has failed a
+     *  promotion, so tests don't wait out start()'s 15s timeout. */
+    function makeDoomedTab(tabId: string) {
+      let failed!: () => void;
+      const hasFailed = new Promise<void>((r) => {
+        failed = r;
+      });
+      const tab = makeCoordinator(tabId, {
+        async adoptOwner() {
+          queueMicrotask(failed);
+          throw new Error('opfs-unavailable: NoModificationAllowedError (after 10 attempts)');
+        },
+      });
+      // start() only settles on a role or the timeout; neither is the point.
+      void tab.coordinator.start('anon').catch(() => {});
+      return { ...tab, hasFailed };
+    }
+
+    it('releases the leader tab lock when adoptOwner throws', async () => {
+      const a = makeDoomedTab('tab-1');
+      await a.hasFailed;
+      // Well inside the 1s re-nomination backoff, so a held lock here is a leak
+      // and not the next attempt's legitimate acquisition.
+      await new Promise((r) => setTimeout(r, 50));
+      expect(locks.heldNames()).not.toContain('sp00ky-tabs:fp-coord-test:anon:tab');
+      await a.coordinator.stop();
+    });
+
+    it('lets a later tab lead after another tab failed to open the store', async () => {
+      const a = makeDoomedTab('tab-1');
+      await a.hasFailed;
+
+      const b = makeCoordinator('tab-2');
+      await expect(b.coordinator.start('anon')).resolves.toBe('leader');
+      expect(b.log.adoptOwner).toHaveLength(1);
+      await b.coordinator.stop();
+      await a.coordinator.stop();
+    });
+  });
+
   it('moves buckets by leaving and rejoining: old namespace re-elects', async () => {
     const a = makeCoordinator('tab-1');
     await a.coordinator.start('anon');

package/src/services/tabs/coordinator.ts

@@ -424,6 +424,15 @@ export class TabsCoordinator {
       );
       this.hub?.detachAll();
       this.hub = null;
+      // Give back everything this attempt claimed. The broker does NOT demote a
+      // tab whose promotion failed (leader-failed clears leadership without a
+      // demote), so nothing else ever frees these. The tab lock name is shared
+      // per namespace, so keeping it after failing to lead makes EVERY later
+      // election in this namespace fail with 'leader tab lock unavailable' —
+      // one OPFS-busy promotion would wedge the whole app into solo mode.
+      if (previousRole === 'leader') await this.deps.hooks.releaseOwnership();
+      this.tabLock?.release();
+      this.tabLock = null;
       this.broker.send({
         type: 'leader-failed',
         tabId: this.deps.tabId,

package/src/services/tabs/fake-ports.fixture.ts

@@ -39,6 +39,48 @@ export async function flush(times = 10): Promise<void> {
   for (let i = 0; i < times; i++) await Promise.resolve();
 }
 
+/**
+ * Install a minimal exclusive-only `navigator.locks` on globalThis. Node has no
+ * Web Locks, and `acquireLeaderTabLock` treats a missing LockManager as "always
+ * granted", so without this the whole leader-tab-lock path is a no-op in tests
+ * and lock leaks are invisible. `ifAvailable` resolves null while held (what a
+ * losing tab sees), `steal` evicts the holder, and a plain request queues
+ * forever — the same shapes the real API produces.
+ */
+export function installFakeLocks(): {
+  restore: () => void;
+  heldNames: () => string[];
+} {
+  const g = globalThis as Record<string, unknown>;
+  const previous = g.navigator;
+  const held = new Map<string, () => void>();
+  const locks = {
+    async request(name: string, opts: any, cb: any) {
+      if (opts?.steal) held.get(name)?.();
+      if (held.has(name) && !opts?.steal) {
+        if (opts?.ifAvailable) return cb(null);
+        return new Promise(() => {});
+      }
+      // The holder keeps the lock until the callback's promise settles (the
+      // real contract) or someone steals it out from under them.
+      let stolen!: () => void;
+      const stealSignal = new Promise<void>((r) => {
+        stolen = r as () => void;
+      });
+      held.set(name, stolen);
+      try {
+        await Promise.race([Promise.resolve(cb({ name, mode: 'exclusive' })), stealSignal]);
+      } finally {
+        held.delete(name);
+      }
+    },
+  };
+  const define = (value: unknown) =>
+    Object.defineProperty(g, 'navigator', { value, configurable: true, writable: true });
+  define({ ...(previous ?? {}), locks });
+  return { restore: () => define(previous), heldNames: () => [...held.keys()] };
+}
+
 /** Install `MessageChannel` + `SharedWorker` fakes on globalThis; the fake
  *  SharedWorker pipes its port into `handleConnect`. Returns a restore fn. */
 export function installBrokerGlobals(handleConnect: (port: MessagePort) => void): () => void {

package/src/services/tabs/protocol.ts

@@ -44,10 +44,13 @@ export const LEADER_FAILURE_BACKOFF_MS = 1000;
 /** Follower attachment retry: initial delay, doubling per attempt, capped. */
 export const ATTACH_RETRY_INITIAL_MS = 1000;
 export const ATTACH_RETRY_MAX_MS = 30_000;
-/** After this many consecutive elections failing with opfs-unavailable, the
- *  broker allows the next leader to open in memory (reported as degraded)
- *  rather than leaving the namespace leaderless forever. */
-export const OPFS_FAILED_CYCLES_BEFORE_MEMORY = 3;
+/** After this many consecutive failed elections, the broker allows the next
+ *  leader to open in memory (reported as degraded) rather than leaving the
+ *  namespace leaderless forever. Counts EVERY failure reason, not just
+ *  opfs-unavailable: any reason that keeps recurring leaves every tab timing
+ *  out in `start()` and falling back to solo, which is strictly worse than one
+ *  shared in-memory store. */
+export const FAILED_CYCLES_BEFORE_MEMORY = 3;
 
 // ---- identity ---------------------------------------------------------------
 

package/src/services/tabs/tabs-broker-worker.ts

@@ -35,7 +35,7 @@ const PING_INTERVAL_MS = 5000;
 const PONG_TIMEOUT_MS = 15_000;
 const FORCE_TAKEOVER_TIMEOUT_MS = 1000;
 const LEADER_FAILURE_BACKOFF_MS = 1000;
-const OPFS_FAILED_CYCLES_BEFORE_MEMORY = 3;
+const FAILED_CYCLES_BEFORE_MEMORY = 3;
 
 interface BrokerTab {
   port: MessagePort;
@@ -62,8 +62,8 @@ interface Namespace {
   leader: Leader | null;
   /** Tabs whose promotion recently failed: tabId -> retry-not-before. */
   failedUntil: Map<string, number>;
-  /** Consecutive elections that failed with opfs-unavailable. */
-  opfsFailedCycles: number;
+  /** Consecutive elections whose promotion failed, for any reason. */
+  failedCycles: number;
   /** Single-flight guard for the async election path. */
   electing: boolean;
   /** Pending follower attach state: followerTabId -> retry bookkeeping. */
@@ -112,7 +112,7 @@ function getNamespace(fingerprint: string, bucketId: string): Namespace {
       tabs: new Map(),
       leader: null,
       failedUntil: new Map(),
-      opfsFailedCycles: 0,
+      failedCycles: 0,
       electing: false,
       attachRetry: new Map(),
       tabLockMonitor: null,
@@ -274,7 +274,7 @@ function electIfNeeded(ns: Namespace, previous: ClearedLeader | null = null): vo
         brokerInstanceId,
         leadershipId,
         forceTakeover,
-        allowMemoryFallback: ns.opfsFailedCycles >= OPFS_FAILED_CYCLES_BEFORE_MEMORY,
+        allowMemoryFallback: ns.failedCycles >= FAILED_CYCLES_BEFORE_MEMORY,
         resumeHeld,
       });
     } finally {
@@ -488,7 +488,7 @@ function handleTabMessage(port: MessagePort, msg: TabToBrokerMessage, ports: rea
         break;
       }
       ns.leader.ready = true;
-      ns.opfsFailedCycles = 0;
+      ns.failedCycles = 0;
       startTabLockMonitor(ns, msg.leadershipId);
       const tab = ns.tabs.get(msg.tabId);
       if (tab) {
@@ -512,7 +512,12 @@ function handleTabMessage(port: MessagePort, msg: TabToBrokerMessage, ports: rea
     }
     case 'leader-failed': {
       if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) break;
-      if (msg.reason.includes('opfs-unavailable')) ns.opfsFailedCycles += 1;
+      // Every reason counts. Gating this on 'opfs-unavailable' left any other
+      // recurring failure (e.g. a tab lock nobody frees) looping at the backoff
+      // interval forever, with allowMemoryFallback never granted, so every tab
+      // timed out in start() and booted solo — each one then contending for the
+      // OPFS pool on its own, which is exactly what shared-tabs exists to stop.
+      ns.failedCycles += 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);

package/src/sp00ky.ts

@@ -676,6 +676,13 @@ export class Sp00kyClient<S extends SchemaStructure> {
         // Any failure here (no SharedWorker start, election timeout, rejected
         // fingerprint) falls back to plain solo boot: exactly the flag-off
         // path, including the second-tab memory fallback + its warning.
+        // A role can still land AFTER start() gave up (the election that timed
+        // out here keeps running), and when it does this tab really is sharing
+        // the leader's store. Track every transition so the reported state is
+        // the current one instead of frozen at whatever boot saw.
+        this.tabsCoordinator.onRoleChange((role) => {
+          this.sharedActive = role !== 'solo';
+        });
         try {
           const role = await this.tabsCoordinator.start(bootBucket);
           this.sharedActive = true;