@spooky-sync/core 0.0.1-canary.161 → 0.0.1-canary.162

package/dist/index.js

@@ -9,12 +9,260 @@ import init, { Sp00kyProcessor } from "@spooky-sync/ssp-wasm";
 /** Cap on the rolling materialization-sample window kept per query in memory. */
 const MATERIALIZATION_SAMPLE_WINDOW = 100;
 
+//#endregion
+//#region src/utils/surql.ts
+const surql = {
+	seal(query, options) {
+		if (typeof query === "string") return `${query};`;
+		const txQuery = query;
+		const idx = options?.resultIndex ?? txQuery.statementCount - 1;
+		return {
+			sql: `${txQuery.sql};`,
+			extract(results) {
+				return results[idx + 1];
+			}
+		};
+	},
+	tx(queries) {
+		return {
+			__brand: "TxQuery",
+			sql: `BEGIN TRANSACTION;\n${queries.join(";")};\nCOMMIT TRANSACTION`,
+			statementCount: queries.length
+		};
+	},
+	selectById(idVar, returnValues) {
+		return `SELECT ${returnValues.join(",")} FROM ONLY $${idVar}`;
+	},
+	selectByFieldsAnd(table, whereVar, returnValues) {
+		return `SELECT ${returnValues.map((rv) => typeof rv === "string" ? rv : `${rv.field} as ${rv.alias}`).join(",")} FROM ${table} WHERE ${whereVar.map((wv) => typeof wv === "string" ? `${wv} = $${wv}` : `${wv.field} = $${wv.variable}`).join(" AND ")}`;
+	},
+	create(idVar, dataVar) {
+		return `CREATE ONLY $${idVar} CONTENT $${dataVar}`;
+	},
+	createSet(idVar, keyDataVars) {
+		return `CREATE ONLY $${idVar} SET ${keyDataVars.map((keyDataVar) => typeof keyDataVar === "string" ? `${keyDataVar} = $${keyDataVar}` : "statement" in keyDataVar ? keyDataVar.statement : `${keyDataVar.key} = $${keyDataVar.variable}`).join(", ")}`;
+	},
+	upsert(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
+	},
+	upsertMerge(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} MERGE $${dataVar}`;
+	},
+	updateMerge(idVar, dataVar) {
+		return `UPDATE ONLY $${idVar} MERGE $${dataVar}`;
+	},
+	updateSet(idVar, keyDataVar) {
+		return `UPDATE $${idVar} SET ${keyDataVar.map((kdv) => typeof kdv === "string" ? `${kdv} = $${kdv}` : "statement" in kdv ? kdv.statement : `${kdv.key} = $${kdv.variable}`).join(", ")}`;
+	},
+	delete(idVar) {
+		return `DELETE $${idVar}`;
+	},
+	let(name, query) {
+		return `LET $${name} = (${query})`;
+	},
+	createMutation(t, mutationIdVar, recordIdVar, dataVar, beforeRecordVar) {
+		switch (t) {
+			case "create": return dataVar ? `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}, data = $${dataVar}` : `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
+			case "update": {
+				let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
+				if (beforeRecordVar) stmt += `, beforeRecord = $${beforeRecordVar}`;
+				return stmt;
+			}
+			case "delete": return `CREATE ONLY $${mutationIdVar} SET mutationType = 'delete', recordId = $${recordIdVar}`;
+		}
+	},
+	returnObject(entries) {
+		return `RETURN {${entries.map(({ key, variable }) => `${key}: $${variable}`).join(",")}}`;
+	}
+};
+
+//#endregion
+//#region src/utils/parser.ts
+function cleanRecord(tableSchema, record) {
+	const cleaned = {};
+	for (const [key, value] of Object.entries(record)) if (key === "id" || key.startsWith("_00_") || key in tableSchema) cleaned[key] = value;
+	return cleaned;
+}
+function parseParams(tableSchema, params) {
+	const parsedParams = {};
+	for (const [key, value] of Object.entries(params)) {
+		const column = tableSchema[key];
+		if (column && value !== void 0) parsedParams[key] = parseValue(key, column, value);
+	}
+	return parsedParams;
+}
+function parseValue(name, column, value) {
+	if (column.recordId) {
+		if (value instanceof RecordId$1) return value;
+		if (typeof value === "string") return parseRecordIdString(value);
+		throw new Error(`Invalid value for ${name}: ${value}`);
+	}
+	if (column.dateTime) {
+		if (value instanceof Date) return value;
+		if (value instanceof DateTime) return value.toDate();
+		if (typeof value === "number" || typeof value === "string") return new Date(value);
+		throw new Error(`Invalid value for ${name}: ${value}`);
+	}
+	return value;
+}
+
+//#endregion
+//#region src/utils/error-classification.ts
+const NETWORK_ERROR_PATTERNS = [
+	"connection",
+	"must be connected",
+	"connectionunavailable",
+	"timeout",
+	"timed out",
+	"websocket",
+	"fetch failed",
+	"disconnected",
+	"socket",
+	"network",
+	"econnrefused",
+	"econnreset",
+	"enotfound",
+	"epipe",
+	"abort"
+];
+function classifySyncError(error) {
+	const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+	for (const pattern of NETWORK_ERROR_PATTERNS) if (message.includes(pattern)) return "network";
+	return "application";
+}
+
+//#endregion
+//#region src/utils/index.ts
+const encodeRecordId = (recordId) => {
+	return `${recordId.table.toString()}:${recordId.id}`;
+};
+const extractIdPart = (id) => {
+	if (typeof id === "string") return id.split(":").slice(1).join(":");
+	const idValue = id.id;
+	if (typeof idValue === "string") return idValue;
+	return String(idValue);
+};
+const extractTablePart = (id) => {
+	if (typeof id === "string") return id.split(":")[0];
+	return id.table.toString();
+};
+const parseRecordIdString = (id) => {
+	const [table, ...idParts] = id.split(":");
+	return new RecordId(table, idParts.join(":"));
+};
+function generateId() {
+	return Uuid.v4().toString().replace(/-/g, "");
+}
+/**
+* Read the millisecond count off a surrealdb `Duration`. Different `surrealdb`
+* releases expose it under `milliseconds` (current) or the older private
+* `_milliseconds` field, so read whichever is set; returns 0 when neither is.
+*/
+function durationMillis(duration) {
+	const d = duration;
+	return Number(d.milliseconds || d._milliseconds || 0);
+}
+/**
+* Parse duration string or Duration object to milliseconds
+*/
+function parseDuration(duration) {
+	if (duration instanceof Duration) {
+		const ms = durationMillis(duration);
+		if (ms) return ms;
+		const str = duration.toString();
+		if (str !== "[object Object]") return parseDuration(str);
+		return 6e5;
+	}
+	if (typeof duration === "bigint") return Number(duration);
+	if (typeof duration !== "string") return 6e5;
+	const match = duration.match(/^(\d+)([smh])$/);
+	if (!match) return 6e5;
+	const val = Number.parseInt(match[1], 10);
+	switch (match[2]) {
+		case "s": return val * 1e3;
+		case "h": return val * 36e5;
+		default: return val * 6e4;
+	}
+}
+async function fileToUint8Array(file) {
+	const buffer = await file.arrayBuffer();
+	return new Uint8Array(buffer);
+}
+/**
+* Convert plain text to simple HTML paragraphs.
+* Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+*/
+function textToHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").split("\n").map((l) => `<p>${l || "<br>"}</p>`).join("");
+}
+/**
+* Helper for retrying DB operations with exponential backoff
+*/
+async function withRetry(logger, operation, retries = 3, delayMs = 100) {
+	let lastError;
+	for (let i = 0; i < retries; i++) try {
+		return await operation();
+	} catch (err) {
+		lastError = err;
+		if (err?.message?.includes("Can not open transaction") || err?.message?.includes("transaction") || err?.message?.includes("Database is busy")) {
+			const msg = err instanceof Error ? err.message : String(err);
+			logger.warn({
+				attempt: i + 1,
+				retries,
+				error: msg,
+				Category: "sp00ky-client::utils::withRetry"
+			}, "Retrying DB operation");
+			await new Promise((res) => setTimeout(res, delayMs * (i + 1)));
+			continue;
+		}
+		throw err;
+	}
+	throw lastError;
+}
+/**
+* Reject after `timeoutMs` if `promise` hasn't settled.
+*
+* Exists because a WebSocket RPC has no deadline of its own: the SurrealDB SDK
+* parks each call in a pending map and only rejects it when the socket reports
+* a close. On a half-open socket (peer gone, no `close` event, `readyState`
+* still OPEN) the call never settles at all, which wedges anything serialized
+* behind it.
+*
+* `message` MUST contain "timed out" so `classifySyncError` treats the
+* rejection as `network` — that's what makes the sync queues retry the
+* operation instead of rolling the mutation back as an application error.
+*
+* Non-positive `timeoutMs` returns `promise` unchanged. The underlying promise
+* is NOT cancelled (nothing can cancel an in-flight RPC); its eventual
+* settlement is absorbed, so attach no expectations to it after a timeout.
+*/
+function withTimeout(promise, timeoutMs, message) {
+	if (!(timeoutMs > 0)) return promise;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+
 //#endregion
 //#region src/services/database/database.ts
 var AbstractDatabaseService = class {
 	client;
 	logger;
 	events;
+	/**
+	* Per-query deadline in ms; `0` disables. Only the remote service sets this
+	* (see `RemoteDatabaseService`) — a local query can be legitimately slow and
+	* has its own retry ladders, and there is no half-open-socket failure mode
+	* for an in-process engine.
+	*/
+	queryTimeoutMs = 0;
 	constructor(client, logger, events) {
 		this.client = client;
 		this.logger = logger.child({ service: "Database" });
@@ -32,6 +280,11 @@ var AbstractDatabaseService = class {
 	queryQueue = Promise.resolve();
 	/**
 	* Execute a query with serialized execution to prevent WASM transaction issues.
+	*
+	* Serialization means every query waits on the previous one, so a call that
+	* never settles blocks the whole chain forever. {@link queryTimeoutMs} bounds
+	* each link: on expiry this promise rejects and the chain moves on, even
+	* though the underlying RPC is still parked in the SDK's pending map.
 	*/
 	async query(query, vars) {
 		return new Promise((resolve, reject) => {
@@ -43,7 +296,7 @@ var AbstractDatabaseService = class {
 						vars,
 						Category: "sp00ky-client::Database::query"
 					}, "Executing query");
-					const result = await this.client.query(query, vars);
+					const result = await withTimeout(this.client.query(query, vars), this.queryTimeoutMs, `Remote query timed out after ${this.queryTimeoutMs}ms`);
 					const duration = performance.now() - startTime;
 					this.events.emit(this.eventType, {
 						query,
@@ -244,217 +497,6 @@ function createDatabaseEventSystem() {
 	return createEventSystem([DatabaseEventTypes.LocalQuery, DatabaseEventTypes.RemoteQuery]);
 }
 
-//#endregion
-//#region src/utils/surql.ts
-const surql = {
-	seal(query, options) {
-		if (typeof query === "string") return `${query};`;
-		const txQuery = query;
-		const idx = options?.resultIndex ?? txQuery.statementCount - 1;
-		return {
-			sql: `${txQuery.sql};`,
-			extract(results) {
-				return results[idx + 1];
-			}
-		};
-	},
-	tx(queries) {
-		return {
-			__brand: "TxQuery",
-			sql: `BEGIN TRANSACTION;\n${queries.join(";")};\nCOMMIT TRANSACTION`,
-			statementCount: queries.length
-		};
-	},
-	selectById(idVar, returnValues) {
-		return `SELECT ${returnValues.join(",")} FROM ONLY $${idVar}`;
-	},
-	selectByFieldsAnd(table, whereVar, returnValues) {
-		return `SELECT ${returnValues.map((rv) => typeof rv === "string" ? rv : `${rv.field} as ${rv.alias}`).join(",")} FROM ${table} WHERE ${whereVar.map((wv) => typeof wv === "string" ? `${wv} = $${wv}` : `${wv.field} = $${wv.variable}`).join(" AND ")}`;
-	},
-	create(idVar, dataVar) {
-		return `CREATE ONLY $${idVar} CONTENT $${dataVar}`;
-	},
-	createSet(idVar, keyDataVars) {
-		return `CREATE ONLY $${idVar} SET ${keyDataVars.map((keyDataVar) => typeof keyDataVar === "string" ? `${keyDataVar} = $${keyDataVar}` : "statement" in keyDataVar ? keyDataVar.statement : `${keyDataVar.key} = $${keyDataVar.variable}`).join(", ")}`;
-	},
-	upsert(idVar, dataVar) {
-		return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
-	},
-	upsertMerge(idVar, dataVar) {
-		return `UPSERT ONLY $${idVar} MERGE $${dataVar}`;
-	},
-	updateMerge(idVar, dataVar) {
-		return `UPDATE ONLY $${idVar} MERGE $${dataVar}`;
-	},
-	updateSet(idVar, keyDataVar) {
-		return `UPDATE $${idVar} SET ${keyDataVar.map((kdv) => typeof kdv === "string" ? `${kdv} = $${kdv}` : "statement" in kdv ? kdv.statement : `${kdv.key} = $${kdv.variable}`).join(", ")}`;
-	},
-	delete(idVar) {
-		return `DELETE $${idVar}`;
-	},
-	let(name, query) {
-		return `LET $${name} = (${query})`;
-	},
-	createMutation(t, mutationIdVar, recordIdVar, dataVar, beforeRecordVar) {
-		switch (t) {
-			case "create": return dataVar ? `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}, data = $${dataVar}` : `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
-			case "update": {
-				let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
-				if (beforeRecordVar) stmt += `, beforeRecord = $${beforeRecordVar}`;
-				return stmt;
-			}
-			case "delete": return `CREATE ONLY $${mutationIdVar} SET mutationType = 'delete', recordId = $${recordIdVar}`;
-		}
-	},
-	returnObject(entries) {
-		return `RETURN {${entries.map(({ key, variable }) => `${key}: $${variable}`).join(",")}}`;
-	}
-};
-
-//#endregion
-//#region src/utils/parser.ts
-function cleanRecord(tableSchema, record) {
-	const cleaned = {};
-	for (const [key, value] of Object.entries(record)) if (key === "id" || key.startsWith("_00_") || key in tableSchema) cleaned[key] = value;
-	return cleaned;
-}
-function parseParams(tableSchema, params) {
-	const parsedParams = {};
-	for (const [key, value] of Object.entries(params)) {
-		const column = tableSchema[key];
-		if (column && value !== void 0) parsedParams[key] = parseValue(key, column, value);
-	}
-	return parsedParams;
-}
-function parseValue(name, column, value) {
-	if (column.recordId) {
-		if (value instanceof RecordId$1) return value;
-		if (typeof value === "string") return parseRecordIdString(value);
-		throw new Error(`Invalid value for ${name}: ${value}`);
-	}
-	if (column.dateTime) {
-		if (value instanceof Date) return value;
-		if (value instanceof DateTime) return value.toDate();
-		if (typeof value === "number" || typeof value === "string") return new Date(value);
-		throw new Error(`Invalid value for ${name}: ${value}`);
-	}
-	return value;
-}
-
-//#endregion
-//#region src/utils/error-classification.ts
-const NETWORK_ERROR_PATTERNS = [
-	"connection",
-	"must be connected",
-	"connectionunavailable",
-	"timeout",
-	"timed out",
-	"websocket",
-	"fetch failed",
-	"disconnected",
-	"socket",
-	"network",
-	"econnrefused",
-	"econnreset",
-	"enotfound",
-	"epipe",
-	"abort"
-];
-function classifySyncError(error) {
-	const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
-	for (const pattern of NETWORK_ERROR_PATTERNS) if (message.includes(pattern)) return "network";
-	return "application";
-}
-
-//#endregion
-//#region src/utils/index.ts
-const encodeRecordId = (recordId) => {
-	return `${recordId.table.toString()}:${recordId.id}`;
-};
-const extractIdPart = (id) => {
-	if (typeof id === "string") return id.split(":").slice(1).join(":");
-	const idValue = id.id;
-	if (typeof idValue === "string") return idValue;
-	return String(idValue);
-};
-const extractTablePart = (id) => {
-	if (typeof id === "string") return id.split(":")[0];
-	return id.table.toString();
-};
-const parseRecordIdString = (id) => {
-	const [table, ...idParts] = id.split(":");
-	return new RecordId(table, idParts.join(":"));
-};
-function generateId() {
-	return Uuid.v4().toString().replace(/-/g, "");
-}
-/**
-* Read the millisecond count off a surrealdb `Duration`. Different `surrealdb`
-* releases expose it under `milliseconds` (current) or the older private
-* `_milliseconds` field, so read whichever is set; returns 0 when neither is.
-*/
-function durationMillis(duration) {
-	const d = duration;
-	return Number(d.milliseconds || d._milliseconds || 0);
-}
-/**
-* Parse duration string or Duration object to milliseconds
-*/
-function parseDuration(duration) {
-	if (duration instanceof Duration) {
-		const ms = durationMillis(duration);
-		if (ms) return ms;
-		const str = duration.toString();
-		if (str !== "[object Object]") return parseDuration(str);
-		return 6e5;
-	}
-	if (typeof duration === "bigint") return Number(duration);
-	if (typeof duration !== "string") return 6e5;
-	const match = duration.match(/^(\d+)([smh])$/);
-	if (!match) return 6e5;
-	const val = Number.parseInt(match[1], 10);
-	switch (match[2]) {
-		case "s": return val * 1e3;
-		case "h": return val * 36e5;
-		default: return val * 6e4;
-	}
-}
-async function fileToUint8Array(file) {
-	const buffer = await file.arrayBuffer();
-	return new Uint8Array(buffer);
-}
-/**
-* Convert plain text to simple HTML paragraphs.
-* Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
-*/
-function textToHtml(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").split("\n").map((l) => `<p>${l || "<br>"}</p>`).join("");
-}
-/**
-* Helper for retrying DB operations with exponential backoff
-*/
-async function withRetry(logger, operation, retries = 3, delayMs = 100) {
-	let lastError;
-	for (let i = 0; i < retries; i++) try {
-		return await operation();
-	} catch (err) {
-		lastError = err;
-		if (err?.message?.includes("Can not open transaction") || err?.message?.includes("transaction") || err?.message?.includes("Database is busy")) {
-			const msg = err instanceof Error ? err.message : String(err);
-			logger.warn({
-				attempt: i + 1,
-				retries,
-				error: msg,
-				Category: "sp00ky-client::utils::withRetry"
-			}, "Retrying DB operation");
-			await new Promise((res) => setTimeout(res, delayMs * (i + 1)));
-			continue;
-		}
-		throw err;
-	}
-	throw lastError;
-}
-
 //#endregion
 //#region src/modules/ref-tables.ts
 /**
@@ -864,9 +906,31 @@ function deleteIndexedDb(name) {
 
 //#endregion
 //#region src/services/database/remote.ts
+/** Defaults for {@link ReconnectConfig}. See that type for the rationale. */
+const RECONNECT_DEFAULTS = {
+	attempts: -1,
+	retryDelayMax: 15e3,
+	heartbeatIntervalMs: 2e4,
+	heartbeatTimeoutMs: 1e4,
+	superviseRetryDelayMaxMs: 15e3
+};
+/** Fill in {@link RECONNECT_DEFAULTS} for every field the caller omitted. */
+function resolveReconnectConfig(input) {
+	return {
+		...RECONNECT_DEFAULTS,
+		...input
+	};
+}
 var RemoteDatabaseService = class extends AbstractDatabaseService {
 	config;
 	eventType = DatabaseEventTypes.RemoteQuery;
+	reconnectConfig;
+	/**
+	* In-flight `connect()`, so concurrent callers (boot + supervisor revive +
+	* an `online` event landing at the same moment) share one attempt instead of
+	* racing two sockets. Cleared on settle, so a later call always reconnects.
+	*/
+	connecting = null;
 	constructor(config, logger) {
 		const events = createDatabaseEventSystem();
 		super(new Surreal({ engines: applyDiagnostics(createRemoteEngines(), ({ key, type, phase, ...other }) => {
@@ -880,11 +944,58 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 			}, `Remote SurrealDB diagnostics captured ${type}:${phase}`);
 		}) }), logger, events);
 		this.config = config;
+		this.reconnectConfig = resolveReconnectConfig(config.reconnect);
+		this.queryTimeoutMs = Math.max(0, config.queryTimeoutMs ?? 6e4);
+	}
+	getConfig() {
+		return this.config;
+	}
+	/** Resolved reconnect tunables; the supervisor reads its own knobs here. */
+	getReconnectConfig() {
+		return this.reconnectConfig;
+	}
+	/** Current transport state as reported by the SDK. */
+	getStatus() {
+		return this.client.status;
+	}
+	/**
+	* Observe transport events. Thin passthrough so callers (the supervisor,
+	* sync, CRDT) don't have to reach through `getClient()`.
+	*/
+	subscribeConnection(event, cb) {
+		return this.client.subscribe(event, cb);
 	}
-	getConfig() {
-		return this.config;
+	/**
+	* Tear the socket down on purpose. Used by the heartbeat watchdog when a
+	* socket stops answering but never closes: `close()` makes the SDK publish
+	* `disconnected`, which is what drives the supervisor's revive loop.
+	*/
+	async forceClose() {
+		try {
+			await this.client.close();
+		} catch (err) {
+			this.logger.debug({
+				err,
+				Category: "sp00ky-client::RemoteDatabaseService::forceClose"
+			}, "forceClose failed; treating the socket as gone anyway");
+		}
 	}
+	/**
+	* Open (or re-open) the remote connection.
+	*
+	* Safe to call repeatedly: concurrent calls share the in-flight attempt, and
+	* a call after a `disconnected` builds a fresh socket. `use()` and
+	* `authenticate()` are re-applied here for the cold path; the SDK also
+	* replays them itself on its own internal reconnects.
+	*/
 	async connect() {
+		if (this.connecting) return this.connecting;
+		this.connecting = this.doConnect().finally(() => {
+			this.connecting = null;
+		});
+		return this.connecting;
+	}
+	async doConnect() {
 		const { endpoint, token, namespace, database } = this.getConfig();
 		if (endpoint) {
 			this.logger.info({
@@ -894,7 +1005,14 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 				Category: "sp00ky-client::RemoteDatabaseService::connect"
 			}, "Connecting to remote database");
 			try {
-				await this.client.connect(endpoint);
+				await this.client.connect(endpoint, { reconnect: {
+					enabled: true,
+					attempts: this.reconnectConfig.attempts,
+					retryDelay: 1e3,
+					retryDelayMax: this.reconnectConfig.retryDelayMax,
+					retryDelayMultiplier: 2,
+					retryDelayJitter: .1
+				} });
 				await this.client.use({
 					namespace,
 					database
@@ -927,6 +1045,276 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 	}
 };
 
+//#endregion
+//#region src/services/database/connection-supervisor.ts
+/**
+* Keeps the remote WebSocket alive for the whole life of the page.
+*
+* The SurrealDB SDK reconnects on its own after a socket `close`, but that
+* covers only one of three ways the connection dies:
+*
+* 1. **Socket closes, SDK recovers.** Handled entirely by the SDK. This
+*    supervisor only observes it (to report `reconnecting` upward).
+* 2. **Socket closes, SDK gives up.** With `attempts: -1` this shouldn't happen
+*    from exhaustion — but the SDK also terminates the engine permanently when
+*    its post-reconnect handshake throws (it re-runs `version()`, `use()`,
+*    `authenticate()` on every reconnect and closes the engine on any error).
+*    One transient hiccup there would otherwise kill the page's connection for
+*    good. The revive loop re-opens from scratch.
+* 3. **Socket never closes at all.** A half-open connection: the peer is gone
+*    (NAT timeout, wifi switch, laptop sleep) but no FIN ever arrives, so
+*    `readyState` stays OPEN and the SDK's own 30s ping — fire-and-forget, no
+*    response deadline — never notices. Nothing ever fires a `close` event, so
+*    nothing ever triggers a reconnect. The heartbeat detects this and forces
+*    the teardown that case 2's loop then repairs.
+*
+* Plus wake triggers: coming back `online` or un-hiding the tab probes
+* immediately rather than waiting out a backoff that was scheduled while the
+* network was known-down.
+*/
+var ConnectionSupervisor = class ConnectionSupervisor {
+	logger;
+	config;
+	state = "disconnected";
+	subscribers = /* @__PURE__ */ new Set();
+	started = false;
+	disposed = false;
+	heartbeatTimer = null;
+	heartbeatInFlight = false;
+	reviveTimer = null;
+	reviveAttempts = 0;
+	reviving = false;
+	/**
+	* Set while the browser reports itself offline. Retrying a socket against a
+	* down interface only burns backoff, so the loop parks until `online` fires.
+	*/
+	suspended = false;
+	teardown = [];
+	static REVIVE_BASE_MS = 1e3;
+	constructor(remote, logger, config) {
+		this.remote = remote;
+		this.logger = logger.child({ service: "ConnectionSupervisor" });
+		this.config = config ?? remote.getReconnectConfig();
+	}
+	/** Latest observed transport state. */
+	get connection() {
+		return this.state;
+	}
+	/**
+	* Observe transport state. Fires immediately with the current value and again
+	* on every change. Returns an unsubscribe.
+	*/
+	subscribe(cb) {
+		cb(this.state);
+		this.subscribers.add(cb);
+		return () => {
+			this.subscribers.delete(cb);
+		};
+	}
+	/**
+	* Begin supervising. Call once, after the initial {@link
+	* RemoteDatabaseService.connect}. Idempotent.
+	*/
+	start() {
+		if (this.started || this.disposed) return;
+		this.started = true;
+		this.setState(this.remote.getStatus());
+		this.teardown.push(this.remote.subscribeConnection("connecting", () => this.setState("connecting")), this.remote.subscribeConnection("reconnecting", () => {
+			this.setState("reconnecting");
+			this.stopHeartbeat();
+		}), this.remote.subscribeConnection("connected", () => {
+			this.reviveAttempts = 0;
+			this.clearReviveTimer();
+			this.setState("connected");
+			this.startHeartbeat();
+		}), this.remote.subscribeConnection("disconnected", () => {
+			this.setState("disconnected");
+			this.stopHeartbeat();
+			this.scheduleRevive();
+		}), this.remote.subscribeConnection("error", (err) => {
+			this.logger.debug({
+				err,
+				Category: "sp00ky-client::ConnectionSupervisor::error"
+			}, "Transport error");
+		}));
+		this.installWakeTriggers();
+		if (this.state === "connected") this.startHeartbeat();
+		else this.scheduleRevive();
+	}
+	/** Stop all timers and listeners. Safe to call more than once. */
+	dispose() {
+		this.disposed = true;
+		this.started = false;
+		this.stopHeartbeat();
+		this.clearReviveTimer();
+		for (const off of this.teardown) try {
+			off();
+		} catch {}
+		this.teardown = [];
+		this.subscribers.clear();
+	}
+	setState(next) {
+		if (this.state === next) return;
+		this.state = next;
+		this.logger.info({
+			state: next,
+			Category: "sp00ky-client::ConnectionSupervisor::state"
+		}, "Connection state changed");
+		for (const cb of this.subscribers) try {
+			cb(next);
+		} catch (err) {
+			this.logger.debug({
+				err,
+				Category: "sp00ky-client::ConnectionSupervisor::state"
+			}, "Connection subscriber threw");
+		}
+	}
+	clearReviveTimer() {
+		if (this.reviveTimer !== null) {
+			clearTimeout(this.reviveTimer);
+			this.reviveTimer = null;
+		}
+	}
+	/**
+	* Queue the next `connect()` attempt on exponential backoff, capped at
+	* `superviseRetryDelayMaxMs`. Never gives up — the page is expected to
+	* outlive any outage.
+	*/
+	scheduleRevive() {
+		if (this.disposed || this.suspended) return;
+		if (this.reviveTimer !== null || this.reviving) return;
+		const delay = Math.min(this.config.superviseRetryDelayMaxMs, ConnectionSupervisor.REVIVE_BASE_MS * 2 ** this.reviveAttempts);
+		this.reviveTimer = setTimeout(() => {
+			this.reviveTimer = null;
+			this.revive();
+		}, delay);
+	}
+	async revive() {
+		if (this.disposed || this.suspended || this.reviving) return;
+		if (this.remote.getStatus() === "connected") {
+			this.reviveAttempts = 0;
+			return;
+		}
+		this.reviving = true;
+		this.reviveAttempts++;
+		this.setState("reconnecting");
+		this.logger.info({
+			attempt: this.reviveAttempts,
+			Category: "sp00ky-client::ConnectionSupervisor::revive"
+		}, "Re-opening the remote connection");
+		try {
+			await this.remote.connect();
+		} catch (err) {
+			this.logger.warn({
+				err,
+				attempt: this.reviveAttempts,
+				Category: "sp00ky-client::ConnectionSupervisor::revive"
+			}, "Reconnect attempt failed; will retry");
+		} finally {
+			this.reviving = false;
+		}
+		if (this.remote.getStatus() !== "connected") this.scheduleRevive();
+	}
+	stopHeartbeat() {
+		if (this.heartbeatTimer !== null) {
+			clearTimeout(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+	startHeartbeat() {
+		this.stopHeartbeat();
+		if (this.disposed || this.suspended) return;
+		if (!(this.config.heartbeatIntervalMs > 0)) return;
+		this.heartbeatTimer = setTimeout(() => void this.beat(), this.config.heartbeatIntervalMs);
+	}
+	/**
+	* Probe the server end-to-end. Deliberately goes through
+	* `remote.query` — the same serialized queue every other remote call uses —
+	* so a queue wedged behind a stuck RPC also fails the heartbeat instead of
+	* being invisible to it.
+	*/
+	async beat() {
+		this.heartbeatTimer = null;
+		if (this.disposed || this.suspended) return;
+		if (this.remote.getStatus() !== "connected") return;
+		if (this.heartbeatInFlight) {
+			this.startHeartbeat();
+			return;
+		}
+		this.heartbeatInFlight = true;
+		try {
+			await withTimeout(this.remote.query("RETURN true"), this.config.heartbeatTimeoutMs, `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`);
+			this.startHeartbeat();
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::ConnectionSupervisor::heartbeat"
+			}, "Heartbeat failed; tearing the socket down to force a reconnect");
+			await this.remote.forceClose();
+			if (this.remote.getStatus() !== "connected") this.scheduleRevive();
+		} finally {
+			this.heartbeatInFlight = false;
+		}
+	}
+	/**
+	* A restored network or an un-hidden tab is the strongest available hint that
+	* a reconnect will now succeed, so probe immediately instead of waiting out a
+	* backoff scheduled under worse conditions.
+	*/
+	installWakeTriggers() {
+		if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+			const onOnline = () => {
+				this.suspended = false;
+				this.wake("online");
+			};
+			const onOffline = () => {
+				this.logger.info({ Category: "sp00ky-client::ConnectionSupervisor::offline" }, "Browser reports offline; parking reconnects until online");
+				this.suspended = true;
+				this.stopHeartbeat();
+				this.clearReviveTimer();
+				this.setState("disconnected");
+			};
+			window.addEventListener("online", onOnline);
+			window.addEventListener("offline", onOffline);
+			this.teardown.push(() => window.removeEventListener("online", onOnline), () => window.removeEventListener("offline", onOffline));
+			const onPageShow = () => this.wake("pageshow");
+			window.addEventListener("pageshow", onPageShow);
+			this.teardown.push(() => window.removeEventListener("pageshow", onPageShow));
+		}
+		if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+			const onVisibility = () => {
+				if (document.visibilityState !== "visible") return;
+				this.wake("visibilitychange");
+			};
+			document.addEventListener("visibilitychange", onVisibility);
+			this.teardown.push(() => document.removeEventListener("visibilitychange", onVisibility));
+		}
+	}
+	/**
+	* Reset the backoff and act on whichever problem is present: reconnect if the
+	* socket is gone, otherwise probe it (it may be half-open — which is exactly
+	* what a sleep/wake cycle produces).
+	*/
+	wake(reason) {
+		if (this.disposed || this.suspended) return;
+		this.logger.debug({
+			reason,
+			state: this.state,
+			Category: "sp00ky-client::ConnectionSupervisor::wake"
+		}, "Wake trigger; probing the connection");
+		this.reviveAttempts = 0;
+		if (this.remote.getStatus() === "connected") {
+			this.stopHeartbeat();
+			this.beat();
+			return;
+		}
+		if (this.remote.getStatus() === "disconnected") {
+			this.clearReviveTimer();
+			this.revive();
+		}
+	}
+};
+
 //#endregion
 //#region src/services/logger/index.ts
 function createLogger(level = "info", transmit) {
@@ -965,7 +1353,7 @@ var LocalMigrator = class {
 			return;
 		}
 		await this.recreateDatabase(database);
-		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_query SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_preload SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
+		const fullSchema = schemaSurql + "\n\n      DEFINE TABLE IF NOT EXISTS _00_stream_processor_state SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_query SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_preload SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_window SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_schema SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n      DEFINE TABLE IF NOT EXISTS _00_pending_mutations SCHEMALESS PERMISSIONS FOR select, create, update, delete WHERE true;\n    ";
 		const statements = this.splitStatements(fullSchema);
 		for (let i = 0; i < statements.length; i++) {
 			const statement = statements[i];
@@ -1634,6 +2022,7 @@ const SYSTEM_TABLES = [
 	"_00_stream_processor_state",
 	"_00_query",
 	"_00_preload",
+	"_00_window",
 	"_00_schema",
 	"_00_pending_mutations",
 	"_00_user_feature",
@@ -2466,6 +2855,53 @@ function createLocalEngine(choice, config, logger, opts = {}) {
 */
 function buildWindowMaterializationPlan(plan, ids) {
 	if (plan.offset === void 0 || plan.offset <= 0) return null;
+	return buildIdSetPlan(plan, ids);
+}
+/**
+* Raw-SurrealQL counterpart of {@link buildIdSetPlan}, for queries that arrived
+* without a plan. Same rewrite as {@link buildWindowMaterialization} without the
+* offset guard: keep the projection and top-level `ORDER BY`, replace the source
+* with the bound id-set.
+*/
+function buildIdSetSurql(surql, idsParam = "__win") {
+	const kw = scanTopLevelClauses(surql);
+	if (kw.fromIndex === null) return null;
+	return { query: renderIdSetSelect(surql, kw, idsParam) };
+}
+/** Shared body of the two id-set surql rewrites: keep the projection and the
+*  top-level `ORDER BY`, replace the source with the bound id-set. */
+function renderIdSetSelect(surql, kw, idsParam) {
+	const selectClause = surql.slice(0, kw.fromIndex).trimEnd();
+	let orderBy = "";
+	const orderByIndex = kw.orderByIndex;
+	if (orderByIndex !== null) {
+		const ends = [
+			kw.limitIndex,
+			kw.startIndex,
+			kw.semicolonIndex,
+			surql.length
+		].filter((n) => n !== null && n > orderByIndex);
+		orderBy = " " + surql.slice(orderByIndex, Math.min(...ends)).trim();
+	}
+	return `${selectClause} FROM $${idsParam}${orderBy}`;
+}
+/**
+* Restrict any plan's base rows to an explicit id-set, regardless of offset.
+*
+* Same rewrite as {@link buildWindowMaterializationPlan} without the offset
+* guard, for rendering a query from its authoritative membership list rather
+* than by re-running its predicate.
+*
+* `where` is dropped deliberately: the id-set already IS the answer to the
+* predicate as the server evaluated it, and re-applying the `WHERE` locally is
+* exactly the bug — a row that left the window keeps its (stale, never
+* re-fetched) local body, so it keeps matching and keeps rendering.
+* `limit`/`offset` go for the same reason: both are already baked into which ids
+* are in the set, so the set itself is the bound. (Both engines ignore them on
+* the `ids` path regardless — only `select` and `orderBy` are honored there.)
+* `orderBy` is kept so display order stays deterministic.
+*/
+function buildIdSetPlan(plan, ids) {
 	return {
 		...plan,
 		ids,
@@ -2478,19 +2914,7 @@ function buildWindowMaterialization(surql, idsParam = "__win") {
 	const kw = scanTopLevelClauses(surql);
 	if (kw.startValue === null || kw.startValue <= 0) return null;
 	if (kw.fromIndex === null) return null;
-	const selectClause = surql.slice(0, kw.fromIndex).trimEnd();
-	let orderBy = "";
-	if (kw.orderByIndex !== null) {
-		const ends = [
-			kw.limitIndex,
-			kw.startIndex,
-			kw.semicolonIndex,
-			surql.length
-		].filter((n) => n !== null && n > kw.orderByIndex);
-		const end = Math.min(...ends);
-		orderBy = " " + surql.slice(kw.orderByIndex, end).trim();
-	}
-	return { query: `${selectClause} FROM $${idsParam}${orderBy}` };
+	return { query: renderIdSetSelect(surql, kw, idsParam) };
 }
 function scanTopLevelClauses(sql) {
 	const out = {
@@ -2751,7 +3175,10 @@ var DataModule = class {
 			hash,
 			Category: "sp00ky-client::DataModule::query"
 		}, "Query Initialization: not found, creating new query");
-		const promise = this.createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName, plan);
+		const promise = this.createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName, plan, await this.calculateMembershipKey({
+			surql: surqlString,
+			params
+		}));
 		this.pendingQueries.set(hash, promise);
 		try {
 			await promise;
@@ -2880,34 +3307,108 @@ var DataModule = class {
 		this.pendingStreamUpdates.delete(queryHash);
 		await this.processStreamUpdate(pending);
 	}
+	/**
+	* Materialize a query's result rows from the local store.
+	*
+	* A query's rows are its MEMBERSHIP — the id-set the server put in
+	* `_00_list_ref` (`remoteArray`) — not "every local body that matches the
+	* WHERE". Those two disagree, and the disagreement was the bug: when a row
+	* leaves a query's window but still exists upstream, `handleRemovedRecords`
+	* keeps its local body and never re-fetches it, so a predicate re-scan finds
+	* that stale body still matching and keeps rendering the row. Selecting the
+	* id-set directly is also the only correct thing for a windowed query, where
+	* re-applying `START m` against the shared local store skips the window's own
+	* rows entirely (sparse windowing) and returns nothing.
+	*
+	* The rendered set is:
+	*
+	*     (membership ∪ (pendingWrites ∩ localArray)) − pendingDeletes
+	*
+	* The middle term keeps optimistic writes visible without re-admitting stale
+	* rows. Every local write is fed to the SSP (`cache.saveBatch` →
+	* `ingestMany`), so `localArray` answers "does this row match the predicate
+	* per LOCAL truth". A pending write that moves a row into the window is in
+	* `localArray` and shows; one that moves a row out is absent and does not; a
+	* stale body the server dropped has no pending write at all, so it stays out.
+	* `pendingDeletes` covers the reverse lag — the server still lists a row whose
+	* DELETE is sitting in our outbox.
+	*
+	* Falls back to the predicate scan only when membership has never been
+	* established (a query first run on this device), so an offline first paint
+	* still shows something.
+	*/
 	async materializeRecords(queryState, sspArray) {
 		const t0 = performance.now();
-		const plan = queryState.config.plan;
-		const windowMat = buildWindowMaterialization(queryState.config.surql);
+		const records = await this.materializeFromConfig(queryState.config, sspArray);
+		this.recordPhase(queryState, "localFetch", performance.now() - t0);
+		return records;
+	}
+	/**
+	* The materialization itself, without the DevTools timing wrapper. Split out so
+	* cold-start seeding can use it before a `QueryState` exists.
+	*/
+	async materializeFromConfig(config, sspArray) {
+		const plan = config.plan;
+		const membership = this.resolveMembership(config, sspArray);
 		let records;
-		if (windowMat) {
-			const winIds = (queryState.config.remoteArray?.length && queryState.config.remoteArray || sspArray?.length && sspArray || queryState.config.localArray || []).map(([id]) => parseRecordIdString(id));
-			if (plan) {
-				const winPlan = buildWindowMaterializationPlan(plan, winIds) ?? {
-					...plan,
-					ids: winIds
-				};
-				records = await this.local.select(winPlan, queryState.config.params);
-			} else {
-				const [rows] = await this.local.query(windowMat.query, {
-					...queryState.config.params,
-					__win: winIds
-				});
-				records = rows || [];
+		if (membership) {
+			const ids = await this.buildRenderIds(config, membership, sspArray);
+			if (plan) records = await this.local.select(buildIdSetPlan(plan, ids), config.params);
+			else {
+				const idSetSurql = buildIdSetSurql(config.surql);
+				if (idSetSurql) {
+					const [rows] = await this.local.query(idSetSurql.query, {
+						...config.params,
+						__win: ids
+					});
+					records = rows || [];
+				} else {
+					const [rows] = await this.local.query(config.surql, config.params);
+					records = rows || [];
+				}
 			}
-		} else if (plan) records = await this.local.select(plan, queryState.config.params);
+		} else if (plan) records = await this.local.select(plan, config.params);
 		else {
-			const [rows] = await this.local.query(queryState.config.surql, queryState.config.params);
+			const [rows] = await this.local.query(config.surql, config.params);
 			records = rows || [];
 		}
-		this.recordPhase(queryState, "localFetch", performance.now() - t0);
 		return records;
 	}
+	/**
+	* The authoritative membership list to render from, or `null` when membership
+	* has never been established and the caller must fall back to a scan.
+	*
+	* A windowed query has no usable fallback — re-running its `START m` locally
+	* returns the wrong rows — so it renders from whatever id-set is on hand
+	* (SSP's included) rather than degrading to a scan. That is the pre-existing
+	* behavior for windows and is preserved.
+	*/
+	resolveMembership(config, sspArray) {
+		if (config.membershipKnown) return config.remoteArray ?? [];
+		if (buildWindowMaterialization(config.surql) !== null) return config.remoteArray?.length && config.remoteArray || sspArray?.length && sspArray || config.localArray || [];
+		return null;
+	}
+	/** Apply the pending-write union and pending-delete subtraction, and map to
+	*  RecordIds for the engines' id-set path. */
+	async buildRenderIds(config, membership, sspArray) {
+		const { writes, deletes } = await this.getPendingRecordIds();
+		const ordered = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const [id] of membership) {
+			if (deletes.has(id) || seen.has(id)) continue;
+			seen.add(id);
+			ordered.push(id);
+		}
+		if (writes.size > 0) {
+			const localView = sspArray?.length && sspArray || config.localArray || [];
+			for (const [id] of localView) {
+				if (!writes.has(id) || deletes.has(id) || seen.has(id)) continue;
+				seen.add(id);
+				ordered.push(id);
+			}
+		}
+		return ordered.map((id) => parseRecordIdString(id));
+	}
 	async processStreamUpdate(update) {
 		const { queryHash, localArray, materializationTimeMs } = update;
 		const queryState = this.activeQueries.get(queryHash);
@@ -3143,6 +3644,7 @@ var DataModule = class {
 		await this.buildAndSaveCacheBatch(tableName, rows);
 		if (epoch !== this.local.epoch) return;
 		queryState.config.remoteArray = rows.map((r) => [encodeRecordId(r.id), r._00_rv || 1]);
+		queryState.config.membershipKnown = true;
 		queryState.records = await this.materializeRecords(queryState);
 		const subscribers = this.subscriptions.get(hash);
 		if (subscribers) for (const cb of subscribers) cb(queryState.records);
@@ -3205,6 +3707,72 @@ var DataModule = class {
 			rowCount
 		}, "replace");
 	}
+	/**
+	* Read the durable membership row, or `null` if this query has never had
+	* authoritative membership on this device. Any read error is treated as
+	* "unknown" so a broken row degrades to the predicate scan rather than
+	* rendering an empty list.
+	*/
+	async getWindowMembership(key) {
+		try {
+			const row = await this.local.getById("_00_window", new RecordId("_00_window", key));
+			if (!row || typeof row !== "object") return null;
+			const ids = row.ids;
+			return Array.isArray(ids) ? ids : null;
+		} catch {
+			return null;
+		}
+	}
+	/** Persist the durable membership row. Best-effort: callers must not fail a
+	*  sync round because the mirror write failed. */
+	async writeWindowMembership(key, ids) {
+		try {
+			await this.local.upsert("_00_window", new RecordId("_00_window", key), {
+				ids,
+				updatedAt: Date.now()
+			}, "replace");
+		} catch (err) {
+			this.logger.debug({
+				err,
+				key,
+				Category: "sp00ky-client::DataModule::writeWindowMembership"
+			}, "Failed to persist window membership; it will be re-derived on next register");
+		}
+	}
+	/**
+	* Record ids with a mutation still in the outbox, split by direction.
+	*
+	* Both halves feed {@link materializeRecords}: `writes` keeps optimistic
+	* creates/updates visible before the server has acknowledged them, and
+	* `deletes` suppresses rows the server still lists because our DELETE hasn't
+	* been processed yet. Reading `_00_pending_mutations` (rather than tracking
+	* ids in memory) is what makes both survive a reload.
+	*
+	* On failure returns empty sets: membership alone then decides, which can
+	* briefly hide an optimistic write but never resurrects a deleted row.
+	*/
+	async getPendingRecordIds() {
+		const writes = /* @__PURE__ */ new Set();
+		const deletes = /* @__PURE__ */ new Set();
+		try {
+			const [rows] = await this.local.query("SELECT recordId, mutationType FROM _00_pending_mutations");
+			for (const row of rows ?? []) {
+				if (!row?.recordId) continue;
+				const id = encodeRecordId(row.recordId);
+				if (row.mutationType === "delete") deletes.add(id);
+				else writes.add(id);
+			}
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::DataModule::getPendingRecordIds"
+			}, "Failed to read pending mutations; optimistic writes may be briefly hidden");
+		}
+		return {
+			writes,
+			deletes
+		};
+	}
 	/** True while ≥1 live subscriber is watching this query (refcount guard). */
 	hasSubscribers(hash) {
 		return (this.subscriptions.get(hash)?.size ?? 0) > 0;
@@ -3294,6 +3862,8 @@ var DataModule = class {
 		}
 		const epoch = this.local.epoch;
 		queryState.config.remoteArray = remoteArray;
+		queryState.config.membershipKnown = true;
+		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray);
 		try {
 			await this.local.query(surql.seal(surql.updateSet("id", ["remoteArray"])), {
 				id: queryState.config.id,
@@ -3341,6 +3911,14 @@ var DataModule = class {
 			config.localArray = [];
 			config.remoteArray = [];
 			config.subqueryRemoteArray = void 0;
+			config.membershipKnown = false;
+			if (config.membershipKey) {
+				const durable = await this.getWindowMembership(config.membershipKey);
+				if (durable) {
+					config.remoteArray = durable;
+					config.membershipKnown = true;
+				}
+			}
 			queryState.hydrated = false;
 			queryState.syncNotified = false;
 			queryState.records = [];
@@ -3661,14 +4239,15 @@ var DataModule = class {
 			}
 		}
 	}
-	async createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName, plan) {
+	async createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName, plan, membershipKey) {
 		const queryState = await this.createNewQuery({
 			recordId,
 			surql: surqlString,
 			params,
 			ttl,
 			tableName,
-			plan
+			plan,
+			membershipKey
 		});
 		const t0 = performance.now();
 		const { localArray, registrationTimings } = this.cache.registerQuery({
@@ -3728,7 +4307,7 @@ var DataModule = class {
 		}, "Query registered");
 		return hash;
 	}
-	async createNewQuery({ recordId, surql: surqlString, params, ttl, tableName, plan }) {
+	async createNewQuery({ recordId, surql: surqlString, params, ttl, tableName, plan, membershipKey }) {
 		const tableSchema = this.schema.tables.find((t) => t.name === tableName) ?? (String(tableName).startsWith("_00_") ? {
 			name: tableName,
 			columns: {}
@@ -3758,10 +4337,26 @@ var DataModule = class {
 			...configRecord,
 			id: recordId,
 			plan,
-			params: parseParams(tableSchema.columns, configRecord.params)
+			params: parseParams(tableSchema.columns, configRecord.params),
+			membershipKey
 		};
+		if (membershipKey && !config.remoteArray?.length) {
+			const durable = await this.getWindowMembership(membershipKey);
+			if (durable) {
+				config.remoteArray = durable;
+				config.membershipKnown = true;
+			}
+		} else if (config.remoteArray?.length) config.membershipKnown = true;
 		let records = [];
-		if (buildWindowMaterialization(surqlString) === null) try {
+		if (config.membershipKnown) try {
+			records = await this.materializeFromConfig(config);
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::DataModule::createNewQuery"
+			}, "Failed to seed records from durable membership");
+		}
+		else if (buildWindowMaterialization(surqlString) === null) try {
 			records = (plan ? await this.local.select(plan, params) : (await this.local.query(surqlString, params))[0]) || [];
 		} catch (err) {
 			this.logger.warn({
@@ -3793,10 +4388,25 @@ var DataModule = class {
 		};
 	}
 	async calculateHash(data) {
-		const content = JSON.stringify({
+		return this.sha256(JSON.stringify({
 			...data,
 			sessionId: this.sessionId
-		});
+		}));
+	}
+	/**
+	* Session-independent counterpart of {@link calculateHash}: the key for a
+	* query's durable `_00_window` membership row.
+	*
+	* Deliberately the SAME inputs minus the `session::id()` salt, so the two keys
+	* can never drift apart. The salt is right for `_00_query` (two tabs must not
+	* fight over one row) and wrong for membership, which has to be recognizable
+	* after a reload — a reload mints a new session id, and offline the salt is
+	* `''`, so a salted key can never match what the previous session wrote.
+	*/
+	async calculateMembershipKey(data) {
+		return this.sha256(JSON.stringify(data));
+	}
+	async sha256(content) {
 		const msgBuffer = new TextEncoder().encode(content);
 		const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
 		return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -4263,6 +4873,16 @@ function diffRecordVersionArray(local, remote) {
 		removed: removed.map(parseRecordIdString)
 	};
 }
+/**
+* Applies a RecordVersionDiff to a RecordVersionArray and returns a new sorted array.
+*/
+function applyRecordVersionDiff(current, diff) {
+	const currentMap = new Map(current);
+	for (const id of diff.removed) currentMap.delete(encodeRecordId(id));
+	for (const item of diff.added) currentMap.set(encodeRecordId(item.id), item.version);
+	for (const item of diff.updated) currentMap.set(encodeRecordId(item.id), item.version);
+	return Array.from(currentMap).toSorted((a, b) => a[0].localeCompare(b[0]));
+}
 function createDiffFromDbOp(op, recordId, version, versions) {
 	const old = versions?.find((record) => record[0] === encodeRecordId(recordId));
 	if (old && old[1] >= version) return {
@@ -4650,7 +5270,12 @@ var Sp00kySync = class Sp00kySync {
 		return this.syncEngine.events;
 	}
 	scheduler;
-	wasDisconnected = false;
+	/**
+	* Set by any event that means the socket we registered on is gone, so the
+	* next `connected` knows it must re-subscribe rather than treat itself as the
+	* initial connect. See {@link subscribeToReconnect}.
+	*/
+	needsResubscribe = false;
 	events = createSyncEventSystem();
 	currentUserId = null;
 	tabRole = "solo";
@@ -4698,6 +5323,17 @@ var Sp00kySync = class Sp00kySync {
 	selfHealAttempts = 0;
 	static SELF_HEAL_BASE_MS = 2e3;
 	static SELF_HEAL_MAX_MS = 3e4;
+	/**
+	* Transport supervisor, when one was supplied. Sync only reads state from it;
+	* it never drives reconnects itself.
+	*/
+	connectionSupervisor;
+	/**
+	* Mirror of the supervisor's state. Defaults to `connected` so a client
+	* constructed without a supervisor (tests, embedders) reports the same health
+	* shape it always has rather than a permanent false "disconnected".
+	*/
+	connectionState = "connected";
 	/** Current sync-health snapshot. */
 	get syncHealth() {
 		return {
@@ -4705,7 +5341,8 @@ var Sp00kySync = class Sp00kySync {
 			consecutiveFailures: this.consecutiveSyncFailures,
 			kind: this.syncHealthStatus === "degraded" ? this.lastSyncErrorKind : void 0,
 			error: this.syncHealthStatus === "degraded" ? this.lastSyncErrorMessage : void 0,
-			everConnected: this.hasSyncedOnce
+			everConnected: this.hasSyncedOnce,
+			connection: this.connectionState
 		};
 	}
 	/**
@@ -4722,6 +5359,24 @@ var Sp00kySync = class Sp00kySync {
 		this.events.emit(SyncEventTypes.SyncHealthChanged, this.syncHealth);
 	}
 	/**
+	* Mirror the supervisor's transport state into {@link SyncHealth} and emit on
+	* every change, so a UI can react to a dropped socket immediately instead of
+	* waiting for `degradeAfterFailures` failed rounds. `status` is untouched:
+	* a brief reconnect is not a degradation.
+	*
+	* No explicit unsubscribe: the supervisor is owned by the same client and
+	* drops all subscribers in its own `dispose()`, which `Sp00kyClient.close()`
+	* calls first.
+	*/
+	subscribeToConnectionState() {
+		if (!this.connectionSupervisor) return;
+		this.connectionSupervisor.subscribe((state) => {
+			if (this.connectionState === state) return;
+			this.connectionState = state;
+			this.emitSyncHealth();
+		});
+	}
+	/**
 	* Fed by the scheduler once per drained sync round. Individual failures are
 	* absorbed by the queue's retry; only a run of `degradeAfterFailures`
 	* consecutive failures flips the status to `degraded`, and the next clean
@@ -4823,6 +5478,7 @@ var Sp00kySync = class Sp00kySync {
 		this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
 		this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
 		this.pushTimeoutMs = Math.max(0, options?.pushTimeoutMs ?? 3e4);
+		this.connectionSupervisor = options?.connectionSupervisor;
 	}
 	/**
 	* Initializes the synchronization system.
@@ -4834,6 +5490,7 @@ var Sp00kySync = class Sp00kySync {
 		this.isInit = true;
 		await this.scheduler.init({ loadOutbox: this.tabRole !== "follower" });
 		this.subscribeToReconnect();
+		this.subscribeToConnectionState();
 		this.scheduler.syncUp();
 		this.scheduler.syncDown();
 		if (this.anonLiveEnabled && !this.currentUserId) {
@@ -5196,7 +5853,7 @@ var Sp00kySync = class Sp00kySync {
 			this.liveQueryUnsubscribe = null;
 		}
 		if (this.currentLiveQueryUuid !== null) {
-			try {
+			if (this.remote.getStatus() === "connected") try {
 				await this.remote.query("KILL $u", { u: this.currentLiveQueryUuid });
 			} catch (err) {
 				this.logger.debug({
@@ -5211,15 +5868,39 @@ var Sp00kySync = class Sp00kySync {
 		await this.killRefLiveQuery();
 		await this.startRefLiveQueries();
 	}
+	/**
+	* Drop local LIVE bookkeeping without issuing a `KILL`.
+	*
+	* Called when the socket dies. The server-side subscription is scoped to that
+	* WebSocket session and died with it, so there is nothing left to kill — and
+	* by the time the reconnect handler runs, the client reports `connected`
+	* again, which would otherwise send a `KILL` for a stale uuid on the *new*
+	* session and hold up the restart queued behind it.
+	*/
+	invalidateRefLiveQuery() {
+		if (this.liveQueryUnsubscribe) {
+			try {
+				this.liveQueryUnsubscribe();
+			} catch {}
+			this.liveQueryUnsubscribe = null;
+		}
+		this.currentLiveQueryUuid = null;
+	}
 	subscribeToReconnect() {
 		const client = this.remote.getClient();
 		client.subscribe("disconnected", () => {
-			this.wasDisconnected = true;
+			this.needsResubscribe = true;
+			this.invalidateRefLiveQuery();
 			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onDisconnect" }, "Remote disconnected");
 		});
+		client.subscribe("reconnecting", () => {
+			this.needsResubscribe = true;
+			this.invalidateRefLiveQuery();
+			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onReconnecting" }, "Remote socket dropped; awaiting reconnect");
+		});
 		client.subscribe("connected", () => {
-			if (!this.wasDisconnected) return;
-			this.wasDisconnected = false;
+			if (!this.needsResubscribe) return;
+			this.needsResubscribe = false;
 			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onReconnect" }, "Remote reconnected, refetching active queries");
 			for (const hash of this.dataModule.getActiveQueryHashes()) this.scheduler.enqueueDownEvent({
 				type: "register",
@@ -5295,7 +5976,12 @@ var Sp00kySync = class Sp00kySync {
 		}, "Live update is being processed");
 		const diff = createDiffFromDbOp(action, recordId, version, localArray);
 		const hash = extractIdPart(existing.config.id);
+		if (existing.config.membershipKnown && (diff.removed.length || diff.added.length)) {
+			const next = applyRecordVersionDiff(existing.config.remoteArray ?? [], diff);
+			if (!recordVersionArraysEqual(next, existing.config.remoteArray ?? [])) await this.dataModule.updateQueryRemoteArray(hash, next);
+		}
 		await this.runSyncForQuery(hash, diff);
+		if (diff.removed.length > 0 && diff.added.length === 0 && diff.updated.length === 0) await this.dataModule.notifyQuerySynced(hash);
 	}
 	/**
 	* Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
@@ -5360,19 +6046,7 @@ var Sp00kySync = class Sp00kySync {
 	* retries rather than rolling the mutation back.
 	*/
 	withPushTimeout(promise, label) {
-		if (!(this.pushTimeoutMs > 0)) return promise;
-		return new Promise((resolve, reject) => {
-			const timer = setTimeout(() => {
-				reject(/* @__PURE__ */ new Error(`Mutation push timed out after ${this.pushTimeoutMs}ms (${label})`));
-			}, this.pushTimeoutMs);
-			promise.then((value) => {
-				clearTimeout(timer);
-				resolve(value);
-			}, (err) => {
-				clearTimeout(timer);
-				reject(err);
-			});
-		});
+		return withTimeout(promise, this.pushTimeoutMs, `Mutation push timed out after ${this.pushTimeoutMs}ms (${label})`);
 	}
 	async processUpEvent(event) {
 		this.logger.debug({
@@ -5546,16 +6220,7 @@ var Sp00kySync = class Sp00kySync {
 	* would otherwise resurrect a just-deleted record.
 	*/
 	async getPendingDeleteIds() {
-		try {
-			const [rows] = await this.local.query("SELECT recordId FROM _00_pending_mutations WHERE mutationType = 'delete'");
-			return new Set((rows ?? []).map((r) => encodeRecordId(r.recordId)));
-		} catch (err) {
-			this.logger.warn({
-				err,
-				Category: "sp00ky-client::Sp00kySync::getPendingDeleteIds"
-			}, "Failed to read pending deletes; sync may briefly resurrect a just-deleted record");
-			return /* @__PURE__ */ new Set();
-		}
+		return (await this.dataModule.getPendingRecordIds()).deletes;
 	}
 	/**
 	* Enqueues a list of mutations (up events) to be sent to the remote.
@@ -5818,8 +6483,8 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.161";
-const WASM_VERSION = "0.0.1-canary.161";
+const CORE_VERSION = "0.0.1-canary.162";
+const WASM_VERSION = "0.0.1-canary.162";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7474,6 +8139,9 @@ var CrdtManager = class {
 	fields = /* @__PURE__ */ new Map();
 	liveByTable = /* @__PURE__ */ new Map();
 	pendingLive = /* @__PURE__ */ new Map();
+	staleTables = /* @__PURE__ */ new Set();
+	connectionGeneration = 0;
+	connectionUnsubscribes = [];
 	logger;
 	sessionId = "";
 	constructor(schema, local, remote, logger, debounceMs = 500) {
@@ -7482,6 +8150,49 @@ var CrdtManager = class {
 		this.remote = remote;
 		this.debounceMs = debounceMs;
 		this.logger = logger.child({ service: "CrdtManager" });
+		this.subscribeToReconnect();
+	}
+	/**
+	* Re-establish table LIVEs after a socket drop.
+	*
+	* A LIVE subscription lives and dies with its WebSocket session, and
+	* `ensureTableSubscription` is memoized on `liveByTable` — so without this,
+	* the first reconnect leaves CRDT realtime permanently dead: the map still
+	* holds a uuid for a subscription the server has forgotten, so every later
+	* `open()` short-circuits and no LIVE is ever re-issued.
+	*
+	* Both drop events matter: the SDK publishes `reconnecting` (not
+	* `disconnected`) when it intends to recover on its own, and `disconnected`
+	* only once it has given up.
+	*/
+	subscribeToReconnect() {
+		const onDrop = () => {
+			this.connectionGeneration++;
+			for (const table of this.liveByTable.keys()) this.staleTables.add(table);
+			for (const table of this.pendingLive.keys()) this.staleTables.add(table);
+			this.liveByTable.clear();
+		};
+		this.connectionUnsubscribes.push(this.remote.subscribeConnection("reconnecting", onDrop), this.remote.subscribeConnection("disconnected", onDrop), this.remote.subscribeConnection("connected", () => {
+			const tables = Array.from(this.staleTables);
+			this.staleTables.clear();
+			for (const table of tables) {
+				if (!this.hasOpenFieldFor(table)) continue;
+				this.ensureTableSubscription(table);
+			}
+		}));
+	}
+	/** Stop observing transport events. Separate from {@link closeAll}, which also
+	*  runs on a bucket switch where the manager keeps being used. */
+	dispose() {
+		for (const off of this.connectionUnsubscribes) try {
+			off();
+		} catch {}
+		this.connectionUnsubscribes = [];
+		this.staleTables.clear();
+	}
+	hasOpenFieldFor(table) {
+		const prefix = `${table}:`;
+		return Array.from(this.fields.keys()).some((k) => k.startsWith(prefix));
 	}
 	/** Set the session id that scopes this client's cursor entries. Must be
 	*  called before `open()` for cursors to be pushed under a stable key.
@@ -7539,8 +8250,10 @@ var CrdtManager = class {
 			crdtField.stopSync();
 			this.fields.delete(key);
 		}
-		const tablePrefix = `${table}:`;
-		if (!Array.from(this.fields.keys()).some((k) => k.startsWith(tablePrefix))) this.killTableSubscription(table);
+		if (!this.hasOpenFieldFor(table)) {
+			this.killTableSubscription(table);
+			this.staleTables.delete(table);
+		}
 		this.logger.debug({
 			key,
 			Category: "sp00ky-client::CrdtManager::close"
@@ -7555,21 +8268,38 @@ var CrdtManager = class {
 		for (const [_, field] of this.fields) field.stopSync(options);
 		this.fields.clear();
 		for (const table of Array.from(this.liveByTable.keys())) this.killTableSubscription(table);
+		this.staleTables.clear();
 	}
 	/** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
 	*  every open CrdtField on `table`. */
 	async ensureTableSubscription(table) {
 		if (this.liveByTable.has(table)) return;
+		const generation = this.connectionGeneration;
 		const pending = this.pendingLive.get(table);
-		if (pending) return pending;
+		if (pending) {
+			if (pending.generation === generation) return pending.promise;
+			await pending.promise.catch(() => {});
+			if (this.liveByTable.has(table)) return;
+			if (generation !== this.connectionGeneration) return;
+			const successor = this.pendingLive.get(table);
+			if (successor && successor.generation === generation) return successor.promise;
+		}
 		const start = (async () => {
 			try {
 				const [uuid] = await this.remote.query(`LIVE SELECT * FROM ${table}`);
+				if (generation !== this.connectionGeneration) {
+					this.logger.debug({
+						table,
+						Category: "sp00ky-client::CrdtManager::ensureTableSubscription"
+					}, "Socket dropped while registering LIVE; discarding it");
+					return;
+				}
 				(await this.remote.getClient().liveOf(uuid)).subscribe((message) => {
 					if (message.action === "KILLED") return;
 					if (message.action !== "CREATE" && message.action !== "UPDATE") return;
 					this.dispatchRow(table, message.value);
 				});
+				if (generation !== this.connectionGeneration) return;
 				this.liveByTable.set(table, uuid);
 				this.logger.info({
 					table,
@@ -7583,7 +8313,10 @@ var CrdtManager = class {
 				}, "Failed to start LIVE SELECT");
 			}
 		})();
-		this.pendingLive.set(table, start);
+		this.pendingLive.set(table, {
+			promise: start,
+			generation
+		});
 		try {
 			await start;
 		} finally {
@@ -8914,6 +9647,7 @@ function writeBootBucketHint(bucketId) {
 var Sp00kyClient = class {
 	local;
 	remote;
+	connectionSupervisor;
 	persistenceClient;
 	migrator;
 	cache;
@@ -8995,6 +9729,7 @@ var Sp00kyClient = class {
 		const tabsSupport = detectSharedTabsSupport(this.config);
 		this.local = createLocalEngine(this.config.localEngine, this.config.database, logger, { shared: tabsSupport.supported });
 		this.remote = new RemoteDatabaseService(this.config.database, logger);
+		this.connectionSupervisor = new ConnectionSupervisor(this.remote, logger);
 		if (config.persistenceClient === "surrealdb") this.persistenceClient = new SurrealDBPersistenceClient(this.local, logger);
 		else if (config.persistenceClient === "localstorage" || !config.persistenceClient) this.persistenceClient = new LocalStoragePersistenceClient(logger);
 		else this.persistenceClient = config.persistenceClient;
@@ -9011,7 +9746,9 @@ var Sp00kyClient = class {
 		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, {
 			refSyncIntervalMs: this.config.refSyncIntervalMs,
 			anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
-			degradeAfterConsecutiveFailures: this.config.syncHealth === false ? 0 : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3
+			degradeAfterConsecutiveFailures: this.config.syncHealth === false ? 0 : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3,
+			pushTimeoutMs: this.config.pushTimeoutMs,
+			connectionSupervisor: this.connectionSupervisor
 		});
 		this.featureFlags = new FeatureFlagModule({
 			dataModule: this.dataModule,
@@ -9063,7 +9800,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.161",
+				coreVersion: "0.0.1-canary.162",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -9203,6 +9940,7 @@ var Sp00kyClient = class {
 				this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Schema provisioned");
 			}
 			await this.remote.connect();
+			this.connectionSupervisor.start();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Remote database connected");
 			this.streamProcessor.setStateKeySuffix(bootBucket);
 			await this.streamProcessor.init();
@@ -9353,9 +10091,11 @@ var Sp00kyClient = class {
 		}, "Local bucket switch complete");
 	}
 	async close() {
+		this.connectionSupervisor.dispose();
 		await this.featureFlags.closeAll();
 		await this.appReleases.closeAll();
 		this.crdtManager.closeAll();
+		this.crdtManager.dispose();
 		if (this.tabsCoordinator) await this.tabsCoordinator.stop();
 		await this.local.close();
 		await this.remote.close();