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

package/dist/{sqlite-plan-sql.js → sqlite-open.js}

@@ -191,4 +191,86 @@ function fromBase64(b64) {
 }
 
 //#endregion
-export { serializeRow as a, reviveRow as i, renderOrderSql as n, resolveRelations as o, renderWhereSql as r, stableKey as s, project as t };
+//#region src/services/database/sqlite-open.ts
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Bounded on purpose: this runs on the boot path, before the first query. */
+const DEFAULT_BACKOFF_MS = [250, 500];
+/**
+* Leader-promotion profile (~5.8s worst case). A dead leader's sync access
+* handles release when the browser garbage-collects its worker, typically
+* well under a second but not synchronously with the Web Lock release the
+* election observed, so promotion retries longer than a cold boot.
+*/
+const PROMOTION_OPEN_OPTIONS = {
+	maxAttempts: 10,
+	backoffMs: [
+		50,
+		100,
+		200,
+		400,
+		800,
+		1e3
+	]
+};
+/** Failures no retry can fix: the APIs aren't there at all (insecure context,
+*  or a browser without sync access handles). Fall back immediately. */
+const UNRETRYABLE = ["Missing required OPFS APIs"];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Keep the DOMException name (e.g. `NoModificationAllowedError` for a pool
+*  locked by another tab): it is the most diagnostic part of the failure. */
+function errMessage(e) {
+	if (e instanceof Error) return e.name && e.name !== "Error" ? `${e.name}: ${e.message}` : e.message;
+	return String(e);
+}
+function fallbackToMemory(sqlite3, dbName, reason, attempts) {
+	const tried = attempts > 0 ? ` after ${attempts} attempt${attempts === 1 ? "" : "s"}` : "";
+	console.error(`[sp00ky] OPFS persistence unavailable for "${dbName}"${tried}: ${reason}. The local SQLite cache is running IN MEMORY, which keeps the whole dataset in RAM and loses every local write on reload. The usual cause is another tab of this app holding the storage lock, so closing the other tabs and reloading restores persistence.`);
+	return {
+		db: new sqlite3.oo1.DB(":memory:", "c"),
+		persisted: false,
+		opfsError: reason
+	};
+}
+/**
+* Open `dbName`'s handle. Never throws for a storage problem: a caller that
+* asked for persistence and can't have it gets a working in-memory handle plus
+* `persisted: false` and an `opfsError` to report.
+*/
+async function openDb(sqlite3, dbName, useOpfs, opts = {}) {
+	if (!useOpfs) return {
+		db: new sqlite3.oo1.DB(":memory:", "c"),
+		persisted: false
+	};
+	if (!sqlite3.installOpfsSAHPoolVfs) {
+		if (opts.disallowMemoryFallback) throw new Error("opfs-unavailable: sqlite-wasm build has no installOpfsSAHPoolVfs");
+		return fallbackToMemory(sqlite3, dbName, "sqlite-wasm build has no installOpfsSAHPoolVfs", 0);
+	}
+	const maxAttempts = Math.max(1, opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+	const backoffMs = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+	const sleep = opts.sleep ?? defaultSleep;
+	let lastError = "unknown error";
+	let attempts = 0;
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		attempts = attempt;
+		try {
+			const pool = await sqlite3.installOpfsSAHPoolVfs({
+				name: `sp00ky-${dbName}`,
+				...attempt > 1 ? { forceReinitIfPreviouslyFailed: true } : {}
+			});
+			return {
+				db: new pool.OpfsSAHPoolDb(`/${dbName}.sqlite3`),
+				persisted: true,
+				pool
+			};
+		} catch (e) {
+			lastError = errMessage(e);
+			if (attempt === maxAttempts || UNRETRYABLE.some((m) => lastError.includes(m))) break;
+			await sleep(backoffMs[Math.min(attempt - 1, backoffMs.length - 1)] ?? 0);
+		}
+	}
+	if (opts.disallowMemoryFallback) throw new Error(`opfs-unavailable: ${lastError} (after ${attempts} attempts)`);
+	return fallbackToMemory(sqlite3, dbName, lastError, attempts);
+}
+
+//#endregion
+export { renderWhereSql as a, resolveRelations as c, renderOrderSql as i, stableKey as l, openDb as n, reviveRow as o, project as r, serializeRow as s, PROMOTION_OPEN_OPTIONS as t };

package/dist/sqlite-worker.js

@@ -1,65 +1,6 @@
-import { i as reviveRow, n as renderOrderSql, o as resolveRelations, r as renderWhereSql, s as stableKey, t as project } from "./sqlite-plan-sql.js";
+import { a as renderWhereSql, c as resolveRelations, i as renderOrderSql, l as stableKey, n as openDb, o as reviveRow, r as project } from "./sqlite-open.js";
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 
-//#region src/services/database/sqlite-open.ts
-const DEFAULT_MAX_ATTEMPTS = 3;
-/** Bounded on purpose: this runs on the boot path, before the first query. */
-const DEFAULT_BACKOFF_MS = [250, 500];
-/** Failures no retry can fix: the APIs aren't there at all (insecure context,
-*  or a browser without sync access handles). Fall back immediately. */
-const UNRETRYABLE = ["Missing required OPFS APIs"];
-const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/** Keep the DOMException name (e.g. `NoModificationAllowedError` for a pool
-*  locked by another tab): it is the most diagnostic part of the failure. */
-function errMessage(e) {
-	if (e instanceof Error) return e.name && e.name !== "Error" ? `${e.name}: ${e.message}` : e.message;
-	return String(e);
-}
-function fallbackToMemory(sqlite3, dbName, reason, attempts) {
-	const tried = attempts > 0 ? ` after ${attempts} attempt${attempts === 1 ? "" : "s"}` : "";
-	console.error(`[sp00ky] OPFS persistence unavailable for "${dbName}"${tried}: ${reason}. The local SQLite cache is running IN MEMORY, which keeps the whole dataset in RAM and loses every local write on reload. The usual cause is another tab of this app holding the storage lock, so closing the other tabs and reloading restores persistence.`);
-	return {
-		db: new sqlite3.oo1.DB(":memory:", "c"),
-		persisted: false,
-		opfsError: reason
-	};
-}
-/**
-* Open `dbName`'s handle. Never throws for a storage problem: a caller that
-* asked for persistence and can't have it gets a working in-memory handle plus
-* `persisted: false` and an `opfsError` to report.
-*/
-async function openDb(sqlite3, dbName, useOpfs, opts = {}) {
-	if (!useOpfs) return {
-		db: new sqlite3.oo1.DB(":memory:", "c"),
-		persisted: false
-	};
-	if (!sqlite3.installOpfsSAHPoolVfs) return fallbackToMemory(sqlite3, dbName, "sqlite-wasm build has no installOpfsSAHPoolVfs", 0);
-	const maxAttempts = Math.max(1, opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
-	const backoffMs = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
-	const sleep = opts.sleep ?? defaultSleep;
-	let lastError = "unknown error";
-	let attempts = 0;
-	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-		attempts = attempt;
-		try {
-			return {
-				db: new (await (sqlite3.installOpfsSAHPoolVfs({
-					name: `sp00ky-${dbName}`,
-					...attempt > 1 ? { forceReinitIfPreviouslyFailed: true } : {}
-				}))).OpfsSAHPoolDb(`/${dbName}.sqlite3`),
-				persisted: true
-			};
-		} catch (e) {
-			lastError = errMessage(e);
-			if (attempt === maxAttempts || UNRETRYABLE.some((m) => lastError.includes(m))) break;
-			await sleep(backoffMs[Math.min(attempt - 1, backoffMs.length - 1)] ?? 0);
-		}
-	}
-	return fallbackToMemory(sqlite3, dbName, lastError, attempts);
-}
-
-//#endregion
 //#region src/services/database/sqlite-select.ts
 function ensureTable(db, table) {
 	if (db.knownTables.has(table)) return;
@@ -142,13 +83,37 @@ async function executeSelect(plan, params, db) {
 * is unavailable it retries, then falls back to an in-memory DB and REPORTS the
 * loss of durability (see `sqlite-open.ts`) instead of degrading silently.
 *
-* Message protocol (request/response keyed by `id`):
-*   { id, type: 'open',   payload: { dbName, useOpfs } } -> { id, ok, persisted, opfsError? }
+* Message protocol (request/response keyed by `id`; replies go to the channel
+* the request arrived on):
+*   { id, type: 'open',   payload: { dbName, useOpfs, workerLockName? } }
+*        -> { id, ok, persisted, opfsError? }
 *   { id, type: 'exec',   payload: { sql, bind } }  -> { id, ok, rows }
 *   { id, type: 'run',    payload: { sql, bind } }  -> { id, ok }
 *   { id, type: 'batch',  payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
 *   { id, type: 'select', payload: { plan, params } } -> { id, ok, rows, relationFetches }
 *   { id, type: 'close' }
+*   { id, type: 'shutdown' }                     (owner only: close + pauseVfs + self.close)
+*   { id, type: 'relock', payload: { workerLockName } }               (owner only)
+*   { id, type: 'add-client', payload: { clientId } } + ev.ports[0]   (owner only)
+*   { id, type: 'remove-client', payload: { clientId } }              (owner only)
+*
+* Multi-client (shared-tabs mode): the OWNER (the leader tab's engine) speaks
+* on the worker's own channel and controls the lifecycle. Follower tabs get a
+* MessagePort each (`add-client`) and may only issue data ops
+* (exec/run/batch/select). Every op, from any channel, runs through ONE op
+* chain so an async `select` from one client can never interleave with another
+* client's `batch` at the VFS layer.
+*
+* Leader fencing (shared-tabs mode): `open` may carry `workerLockName`, a Web
+* Lock this worker acquires BEFORE opening the pool and holds for the DB's
+* lifetime. The name is unique per leadership, so the lock being gone has
+* exactly one meaning: the broker stole it because this tab was presumed dead
+* (usually frozen). When that happens the worker FENCES itself: closes the DB,
+* releases the OPFS sync access handles (pauseVfs), tells the owner, and
+* refuses every further op. A frozen-then-thawed ex-leader therefore can never
+* write the durable file after a new leader took over. The thaw gate below
+* closes the wake-up ordering race where a queued write could run before the
+* lock-loss callback fires.
 *
 * `select` executes a whole QueryPlan — table creation, base select, the full
 * `.related()` tree (shared `resolveRelations`), and JSON row parsing — in ONE
@@ -156,18 +121,145 @@ async function executeSelect(plan, params, db) {
 * hot path; the per-statement ops remain for the write/shim paths.
 */
 let db = null;
-async function open(dbName, useOpfs, systemTables = []) {
-	const { db: handle, persisted, opfsError } = await openDb(await sqlite3InitModule(), dbName, useOpfs);
-	db = handle;
+let pool = null;
+/** Once fenced, every op is refused and the DB stays closed. Terminal. */
+let fenced = false;
+/** The per-leadership lock currently held (null = no fencing active). A
+*  relock (same-leader re-promotion after a broker restart) briefly holds two
+*  locks: the new one is installed here first, then the old one's own release
+*  is called, so there is no window where neither is held. */
+let currentLock = null;
+function workerLocks() {
+	const nav = globalThis.navigator;
+	return nav?.locks && typeof nav.locks.request === "function" ? nav.locks : null;
+}
+/**
+* Acquire `name` exclusively without waiting. Resolves with a handle when
+* granted, null when someone else holds it. If the request settles while the
+* holder still believes it owns the lock, the broker stole it: fence.
+*/
+function acquireWorkerLock(name) {
+	const locks = workerLocks();
+	if (!locks) return Promise.resolve({
+		name,
+		release() {}
+	});
+	return new Promise((resolve) => {
+		let granted = false;
+		let intentional = false;
+		let releaseGrant = null;
+		locks.request(name, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, (lock) => {
+			if (!lock) {
+				resolve(null);
+				return;
+			}
+			granted = true;
+			resolve({
+				name,
+				release() {
+					intentional = true;
+					releaseGrant?.();
+				}
+			});
+			return new Promise((release) => {
+				releaseGrant = release;
+			});
+		}).then(() => {
+			if (granted && !intentional) fence("worker lock stolen");
+		}, () => {
+			if (granted && !intentional) fence("worker lock request failed");
+		});
+	});
+}
+function releaseHeldLock() {
+	currentLock?.release();
+	currentLock = null;
+}
+/**
+* Terminal teardown after leadership loss. Closing the DB first makes
+* pauseVfs legal (it throws while files are open); pausing releases the sync
+* access handles so the NEW leader's open succeeds without waiting for this
+* worker to be garbage collected.
+*/
+async function fence(reason) {
+	if (fenced) return;
+	fenced = true;
+	console.error(`[sp00ky] sqlite worker fenced (${reason}): leadership was taken over, closing the database and refusing further ops.`);
+	try {
+		db?.close();
+	} catch {}
+	db = null;
+	try {
+		pool?.pauseVfs?.();
+	} catch {}
+	pool = null;
+	try {
+		self.postMessage({
+			type: "lock-lost",
+			reason
+		});
+	} catch {}
+	releaseHeldLock();
+	self.close();
+}
+/**
+* A frozen tab's worker resumes with its message queue intact, and a queued
+* write could run BEFORE the lock-steal callback fires. Both the 1s interval
+* and every op call `noteTick()`; whichever runs first after a long gap kicks
+* off a lock verification, and ops await it before touching the DB. The gap
+* threshold must stay BELOW the broker's pong timeout: a freeze shorter than
+* the threshold cannot have triggered a steal yet, so skipping the check for
+* small gaps is safe.
+*/
+const FREEZE_SUSPECT_MS = 1e4;
+let lastTickAt = performance.now();
+let thawVerification = null;
+function noteTick() {
+	const now = performance.now();
+	const gap = now - lastTickAt;
+	lastTickAt = now;
+	if (gap > FREEZE_SUSPECT_MS && currentLock && !fenced && !thawVerification) thawVerification = verifyLockStillHeld().finally(() => {
+		thawVerification = null;
+	});
+}
+setInterval(noteTick, 1e3);
+async function verifyLockStillHeld() {
+	const locks = workerLocks();
+	const name = currentLock?.name;
+	if (!locks || !name || typeof locks.query !== "function") return;
+	try {
+		if (!((await locks.query()).held ?? []).some((l) => l.name === name)) await fence("lock missing after suspected freeze");
+	} catch {}
+}
+async function open(dbName, useOpfs, systemTables = [], workerLockName, openOptions) {
+	if (workerLockName) {
+		const handle = await acquireWorkerLock(workerLockName);
+		if (!handle) throw new Error("worker-lock-unavailable");
+		releaseHeldLock();
+		currentLock = handle;
+	}
+	const result = await openDb(await sqlite3InitModule(), dbName, useOpfs, openOptions ?? {});
+	db = result.db;
+	pool = result.pool ?? null;
 	for (const t of systemTables) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
 	try {
 		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
 	} catch {}
 	return {
-		persisted,
-		opfsError
+		persisted: result.persisted,
+		opfsError: result.opfsError
 	};
 }
+function closeDb() {
+	db?.close();
+	db = null;
+	pool = null;
+	selectDb.knownTables.clear();
+	releaseHeldLock();
+}
 function exec(sql, bind) {
 	if (!db) throw new Error("sqlite: DB not open");
 	return db.exec({
@@ -201,59 +293,127 @@ function batch(stmts) {
 	}
 }
 /** DB handle for `executeSelect` (see `sqlite-select.ts`, the unit-testable
-*  plan executor). `knownTables` is cleared on open/close — a bucket switch
-*  spawns a fresh worker anyway. */
+*  plan executor). `knownTables` is cleared on open/close, which covers both
+*  the solo fresh-worker path and the shared-mode same-worker bucket switch. */
 const selectDb = {
 	exec: (sql, bind) => exec(sql, bind),
 	run,
 	knownTables: /* @__PURE__ */ new Set()
 };
-self.onmessage = async (ev) => {
-	const { id, type, payload } = ev.data ?? {};
-	const t0 = performance.now();
-	try {
-		let result;
-		switch (type) {
-			case "open":
-				selectDb.knownTables.clear();
-				result = await open(payload.dbName, payload.useOpfs, payload.systemTables);
+/** Follower client ports, keyed by the clientId the owner assigned. */
+const clients = /* @__PURE__ */ new Map();
+/** Data ops a follower client port may issue; lifecycle stays owner-only. */
+const CLIENT_OPS = new Set([
+	"exec",
+	"run",
+	"batch",
+	"select"
+]);
+/**
+* ONE chain for every op from every channel. The handlers for `open` and
+* `select` are async; without this, a follower's select could interleave with
+* the owner's batch mid-transaction at the VFS layer. (Solo mode kept this
+* invariant on the main thread via the engine's opQueue; with multiple client
+* ports only the worker can.)
+*/
+let opChain = Promise.resolve();
+async function handle(type, payload, source) {
+	if (fenced) throw new Error("sqlite: fenced, leadership was taken over");
+	if (source === "client" && !CLIENT_OPS.has(type)) throw new Error(`sqlite worker: op ${type} is not allowed on a client port`);
+	switch (type) {
+		case "open":
+			selectDb.knownTables.clear();
+			{
+				const result = await open(payload.dbName, payload.useOpfs, payload.systemTables, payload.workerLockName, payload.openOptions);
 				for (const t of payload.systemTables ?? []) selectDb.knownTables.add(t);
-				break;
-			case "select":
-				result = await executeSelect(payload.plan, payload.params ?? {}, selectDb);
-				break;
-			case "exec":
-				result = { rows: exec(payload.sql, payload.bind) };
-				break;
-			case "run":
-				run(payload.sql, payload.bind);
-				result = {};
-				break;
-			case "batch":
-				batch(payload);
-				result = {};
-				break;
-			case "close":
+				return result;
+			}
+		case "relock": {
+			const handle = await acquireWorkerLock(payload.workerLockName);
+			if (!handle) throw new Error("worker-lock-unavailable");
+			releaseHeldLock();
+			currentLock = handle;
+			return {};
+		}
+		case "select": return executeSelect(payload.plan, payload.params ?? {}, selectDb);
+		case "exec": return { rows: exec(payload.sql, payload.bind) };
+		case "run":
+			run(payload.sql, payload.bind);
+			return {};
+		case "batch":
+			batch(payload);
+			return {};
+		case "close":
+			closeDb();
+			return {};
+		case "shutdown":
+			try {
 				db?.close();
-				db = null;
-				selectDb.knownTables.clear();
-				result = {};
-				break;
-			default: throw new Error(`sqlite worker: unknown message ${type}`);
+			} catch {}
+			db = null;
+			try {
+				pool?.pauseVfs?.();
+			} catch {}
+			pool = null;
+			releaseHeldLock();
+			queueMicrotask(() => self.close());
+			return {};
+		case "remove-client":
+			clients.get(payload.clientId)?.close();
+			clients.delete(payload.clientId);
+			return {};
+		default: throw new Error(`sqlite worker: unknown message ${type}`);
+	}
+}
+function dispatch(target, data, source) {
+	const { id, type, payload } = data ?? {};
+	noteTick();
+	const t0 = performance.now();
+	const runOp = async () => {
+		try {
+			if (thawVerification) await thawVerification;
+			const result = await handle(type, payload, source);
+			target.postMessage({
+				id,
+				ok: true,
+				wt: performance.now() - t0,
+				...result
+			});
+		} catch (err) {
+			target.postMessage({
+				id,
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			});
 		}
+	};
+	opChain = opChain.then(runOp, runOp);
+}
+self.onmessage = (ev) => {
+	const data = ev.data ?? {};
+	if (data.type === "add-client") {
+		const port = ev.ports?.[0];
+		const clientId = data.payload?.clientId;
+		if (!port || !clientId) {
+			self.postMessage({
+				id: data.id,
+				ok: false,
+				error: "sqlite worker: add-client needs a clientId and a transferred port"
+			});
+			return;
+		}
+		clients.get(clientId)?.close();
+		clients.set(clientId, port);
+		port.onmessage = (pe) => dispatch(port, pe.data, "client");
+		port.start?.();
 		self.postMessage({
-			id,
+			id: data.id,
 			ok: true,
-			wt: performance.now() - t0,
-			...result
-		});
-	} catch (err) {
-		self.postMessage({
-			id,
-			ok: false,
-			error: err instanceof Error ? err.message : String(err)
+			wt: 0
 		});
+		return;
 	}
+	dispatch(self, data, "owner");
 };
 
 //#endregion

package/dist/tabs-broker-worker.d.ts

@@ -0,0 +1,8 @@
+//#region src/services/tabs/tabs-broker-worker.d.ts
+/** Attach a connecting tab's port. Exported for the node test harness, which
+ *  drives the broker with fake MessagePort pairs instead of a SharedWorker. */
+declare function handleConnect(port: MessagePort): void;
+/** Test-only: wipe module state so each test starts with a fresh broker. */
+declare function __resetBrokerForTests(): void;
+//#endregion
+export { __resetBrokerForTests, handleConnect };