@spooky-sync/core 0.0.1-canary.237 → 0.0.1-canary.239

package/dist/index.js

@@ -148,7 +148,12 @@ const NETWORK_ERROR_PATTERNS = [
 	"econnreset",
 	"enotfound",
 	"epipe",
-	"abort"
+	"abort",
+	"transaction conflict",
+	"resource busy",
+	"can be retried",
+	"specify a namespace",
+	"specify a database"
 ];
 function classifySyncError(error) {
 	const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
@@ -3510,13 +3515,6 @@ function mutationOwnerTabId(mutationId) {
 
 //#endregion
 //#region src/modules/data/index.ts
-/**
-* How many consecutive empty `_00_list_ref` reads it takes to believe a query
-* really is empty, before any non-empty set has been seen this session. One
-* read is the registration race (the SSP flushes a view's initial edges
-* asynchronously); the second comes from the poll a cycle later.
-*/
-const EMPTY_MEMBERSHIP_CONFIRMATIONS = 2;
 /** Push a timing sample (ms) into a rolling window, capped at the sample window. */
 function pushSample(samples, ms) {
 	samples.push(ms);
@@ -3549,6 +3547,8 @@ function phaseStatOf(samples, lastMs) {
 * is LIVE on those edges, so a swept-but-still-watched view empties the UI.
 */
 const TTL_HEARTBEAT_FRACTION = .5;
+/** A query beaten this recently is skipped by `heartbeatOnWake`. */
+const WAKE_HEARTBEAT_MIN_GAP_MS = 3e4;
 var DataModule = class DataModule {
 	/** Tab identity baked into mutation ids (shared-tabs rollback routing);
 	*  undefined in solo mode, where mutation-id falls back to a session id. */
@@ -3557,10 +3557,18 @@ var DataModule = class DataModule {
 	pendingQueries = /* @__PURE__ */ new Map();
 	subscriptions = /* @__PURE__ */ new Map();
 	statusSubscriptions = /* @__PURE__ */ new Map();
+	/** Observers of a query's authority (`membershipKnown`) flips, keyed like `statusSubscriptions`. */
+	authoritySubscriptions = /* @__PURE__ */ new Map();
 	mutationCallbacks = /* @__PURE__ */ new Set();
 	debounceTimers = /* @__PURE__ */ new Map();
 	pendingStreamUpdates = /* @__PURE__ */ new Map();
 	fetchDepth = /* @__PURE__ */ new Map();
+	/**
+	* Observers of the AGGREGATE fetch activity: how many queries are mid-fetch
+	* right now. What a "downloading" indicator in the app chrome hangs off,
+	* instead of subscribing to every query's status one by one.
+	*/
+	activitySubscriptions = /* @__PURE__ */ new Set();
 	logger;
 	/**
 	* Optional observer notified whenever a query's fetch status changes.
@@ -3579,6 +3587,15 @@ var DataModule = class DataModule {
 	*/
 	onHeartbeat;
 	/**
+	* Fired once per episode when the server's `_00_query` row for a query we
+	* hold membership for is found missing (see `updateQueryRemoteArray`). Wired
+	* by Sp00kyClient to enqueue a `register` down-event so the SSP rebuilds the
+	* view; the client keeps rendering what it has meanwhile.
+	*/
+	onViewLost;
+	/** DevTools observer for authority flips; mirrors `onQueryStatusChange`. */
+	onQueryAuthorityChange;
+	/**
 	* Optional hook fired by {@link deregisterQuery} when an opt-in query (e.g. a
 	* viewport-windowed list cancelling an off-screen window) loses its last
 	* subscriber. Wired by Sp00kyClient to enqueue a `cleanup` down-event, which
@@ -3712,6 +3729,42 @@ var DataModule = class DataModule {
 		};
 	}
 	/**
+	* Subscribe to a query's authority flips: whether server membership is known
+	* for it. With `{ immediate: true }` the callback fires synchronously with
+	* the current value (`false` for an unknown query).
+	*/
+	subscribeAuthority(queryHash, callback, options = {}) {
+		if (!this.authoritySubscriptions.has(queryHash)) this.authoritySubscriptions.set(queryHash, /* @__PURE__ */ new Set());
+		this.authoritySubscriptions.get(queryHash)?.add(callback);
+		if (options.immediate) callback(this.activeQueries.get(queryHash)?.config.membershipKnown === true);
+		return () => {
+			const subs = this.authoritySubscriptions.get(queryHash);
+			if (subs) {
+				subs.delete(callback);
+				if (subs.size === 0) this.authoritySubscriptions.delete(queryHash);
+			}
+		};
+	}
+	/** Whether server membership is known for `queryHash` (see `QueryConfig.membershipKnown`). */
+	isAuthoritative(queryHash) {
+		return this.activeQueries.get(queryHash)?.config.membershipKnown === true;
+	}
+	/**
+	* The single writer of `config.membershipKnown` for a live query. Fans out
+	* to `subscribeAuthority` listeners and DevTools on a change; no-op when
+	* unchanged or the query is unknown.
+	*/
+	setMembershipKnown(queryHash, known) {
+		const queryState = this.activeQueries.get(queryHash);
+		if (!queryState) return;
+		const was = queryState.config.membershipKnown === true;
+		queryState.config.membershipKnown = known;
+		if (was === known) return;
+		this.onQueryAuthorityChange?.(queryHash, known);
+		const subs = this.authoritySubscriptions.get(queryHash);
+		if (subs) for (const callback of subs) callback(known);
+	}
+	/**
 	* Set a query's fetch status and notify status observers (DevTools +
 	* `subscribeStatus` listeners). No-op when the status is unchanged or the
 	* query is unknown.
@@ -3733,7 +3786,10 @@ var DataModule = class DataModule {
 	beginFetching(queryHash) {
 		const depth = this.fetchDepth.get(queryHash) ?? 0;
 		this.fetchDepth.set(queryHash, depth + 1);
-		if (depth === 0) this.setQueryStatus(queryHash, "fetching");
+		if (depth === 0) {
+			this.setQueryStatus(queryHash, "fetching");
+			this.notifyActivity();
+		}
 	}
 	/** Leave a fetch cycle started with {@link beginFetching}; emits `idle` on the last exit. */
 	endFetching(queryHash) {
@@ -3741,10 +3797,40 @@ var DataModule = class DataModule {
 		if (depth <= 1) {
 			this.fetchDepth.delete(queryHash);
 			this.setQueryStatus(queryHash, "idle");
+			this.notifyActivity();
 			return;
 		}
 		this.fetchDepth.set(queryHash, depth - 1);
 	}
+	/** How many queries are mid-fetch right now (see {@link subscribeActivity}). */
+	get fetchingQueryCount() {
+		return this.fetchDepth.size;
+	}
+	/**
+	* Observe the number of queries currently fetching. Fires on every change of
+	* that number (a query entering or leaving its outermost fetch cycle), and
+	* synchronously with the current value when `immediate` is set. One
+	* subscription per indicator, however many queries the page holds.
+	*/
+	subscribeActivity(callback, options = {}) {
+		this.activitySubscriptions.add(callback);
+		if (options.immediate) callback(this.fetchDepth.size);
+		return () => {
+			this.activitySubscriptions.delete(callback);
+		};
+	}
+	notifyActivity() {
+		if (this.activitySubscriptions.size === 0) return;
+		const n = this.fetchDepth.size;
+		for (const cb of this.activitySubscriptions) try {
+			cb(n);
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::DataModule::notifyActivity"
+			}, "Activity subscriber threw");
+		}
+	}
 	/**
 	* Subscribe to mutations (for sync)
 	*/
@@ -4236,7 +4322,7 @@ var DataModule = class DataModule {
 		if (epoch !== this.local.epoch) return;
 		if (queryState.serverMembership) return;
 		queryState.config.remoteArray = rows.map((r) => [encodeRecordId(r.id), r._00_rv || 1]);
-		queryState.config.membershipKnown = true;
+		this.setMembershipKnown(hash, true);
 		queryState.records = await this.materializeRecords(queryState);
 		const subscribers = this.subscriptions.get(hash);
 		if (subscribers) for (const cb of subscribers) cb(queryState.records);
@@ -4463,6 +4549,7 @@ var DataModule = class DataModule {
 		this.cache.unregisterQuery(hash);
 		this.activeQueries.delete(hash);
 		this.subscriptions.delete(hash);
+		this.authoritySubscriptions.delete(hash);
 	}
 	/**
 	* Get query state by id (for sync and devtools)
@@ -4507,45 +4594,57 @@ var DataModule = class DataModule {
 				hash,
 				Category: "sp00ky-client::DataModule::updateQueryRemoteArray"
 			}, "Query to update remote array not found");
-			return;
-		}
-		let confirmed = remoteArray.length > 0 || queryState.config.remoteSeen === true;
-		if (remoteArray.length === 0 && !queryState.config.remoteSeen) {
-			const serverRowCount = opts?.serverRowCount;
-			const knownEmpty = serverRowCount === 0;
-			confirmed = knownEmpty;
-			if (!knownEmpty) {
-				const emptyReads = (queryState.config.emptyReads ?? 0) + 1;
-				queryState.config.emptyReads = emptyReads;
-				if (!(serverRowCount === null || serverRowCount === void 0 ? emptyReads >= EMPTY_MEMBERSHIP_CONFIRMATIONS : false)) {
-					this.logger.debug({
-						hash,
-						emptyReads,
-						serverRowCount,
-						Category: "sp00ky-client::DataModule::updateQueryRemoteArray"
-					}, "Ignoring empty membership: the server still reports rows for this query");
-					return;
+			return "ignored";
+		}
+		const meta = opts?.meta;
+		if (meta) queryState.serverState = meta.present ? meta.state : null;
+		const held = queryState.config.remoteArray ?? [];
+		if (remoteArray.length === 0 && !opts?.verifiedRemoval) {
+			if (!meta || !meta.present) {
+				if (held.length > 0 || queryState.config.membershipKnown) {
+					if (!queryState.viewLost) {
+						queryState.viewLost = true;
+						this.logger.warn({
+							hash,
+							held: held.length,
+							Category: "sp00ky-client::DataModule::updateQueryRemoteArray"
+						}, "Server has no _00_query row for a query we hold membership for; keeping local state and re-registering");
+						this.onViewLost?.(hash);
+					}
+					return "view-lost";
 				}
+				this.logger.debug({
+					hash,
+					Category: "sp00ky-client::DataModule::updateQueryRemoteArray"
+				}, "Ignoring empty membership: the _00_query row is not readable yet");
+				return "ignored";
+			}
+			if (!(meta.rowCount === 0 && meta.state !== "materializing")) {
+				this.logger.debug({
+					hash,
+					state: meta.state,
+					rowCount: meta.rowCount,
+					Category: "sp00ky-client::DataModule::updateQueryRemoteArray"
+				}, "Ignoring empty membership: the server has not confirmed this query empty");
+				return "ignored";
 			}
 		}
+		if (meta?.present) queryState.viewLost = false;
 		const epoch = this.local.epoch;
 		queryState.config.remoteArray = remoteArray;
-		queryState.config.membershipKnown = true;
+		this.setMembershipKnown(hash, true);
 		queryState.serverMembership = true;
-		if (remoteArray.length > 0) {
-			queryState.config.remoteSeen = true;
-			queryState.config.emptyReads = 0;
-		}
-		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray, confirmed);
+		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray, true);
 		try {
 			await this.local.query(surql.seal(surql.updateSet("id", ["remoteArray"])), {
 				id: queryState.config.id,
 				remoteArray
 			}, { epoch });
 		} catch (err) {
-			if (err instanceof StaleEpochError) return;
+			if (err instanceof StaleEpochError) return "applied";
 			throw err;
 		}
+		return "applied";
 	}
 	/**
 	* Cancel every armed timer ahead of a local-bucket switch: stream-update
@@ -4557,7 +4656,9 @@ var DataModule = class DataModule {
 		for (const timer of this.debounceTimers.values()) clearTimeout(timer);
 		this.debounceTimers.clear();
 		this.pendingStreamUpdates.clear();
+		const wasFetching = this.fetchDepth.size > 0;
 		this.fetchDepth.clear();
+		if (wasFetching) this.notifyActivity();
 		for (const queryState of this.activeQueries.values()) if (queryState.ttlTimer) {
 			clearTimeout(queryState.ttlTimer);
 			queryState.ttlTimer = null;
@@ -4584,14 +4685,14 @@ var DataModule = class DataModule {
 			config.localArray = [];
 			config.remoteArray = [];
 			config.subqueryRemoteArray = void 0;
-			config.membershipKnown = false;
-			config.remoteSeen = false;
-			config.emptyReads = 0;
+			this.setMembershipKnown(hash, false);
+			queryState.viewLost = false;
+			queryState.serverState = null;
 			if (config.membershipKey) {
 				const durable = await this.getWindowMembership(config.membershipKey);
 				if (durable && (durable.ids.length > 0 || durable.confirmed)) {
 					config.remoteArray = durable.ids;
-					config.membershipKnown = true;
+					this.setMembershipKnown(hash, true);
 				}
 			}
 			queryState.hydrated = false;
@@ -5130,6 +5231,7 @@ var DataModule = class DataModule {
 				}, "TTL heartbeat: no subscribers, stopping");
 				return;
 			}
+			queryState.lastHeartbeatAt = Date.now();
 			this.onHeartbeat?.(hash);
 			this.logger.debug({
 				hash,
@@ -5139,6 +5241,46 @@ var DataModule = class DataModule {
 			this.startTTLHeartbeat(queryState, hash);
 		}, heartbeatTime);
 	}
+	/**
+	* Heartbeat every watched query NOW and re-anchor its timer.
+	*
+	* The TTL timer is the only thing keeping a view alive on the server, and
+	* browsers throttle timers in hidden tabs (Chrome aligns them to one-minute
+	* ticks after five minutes hidden, and suspends them outright on some
+	* mobile platforms). A tab that comes back after a long stretch may have
+	* missed its beat by more than the server's slack, and the sweep will have
+	* taken the row and its edges. The client does not blank on that any more
+	* (`updateQueryRemoteArray` treats a missing row as "view lost"), but the
+	* sooner it finds out, the sooner the view is rebuilt: `heartbeatQuery`
+	* re-registers a query whose row is gone. Called on `visibilitychange` (to
+	* visible) and `online`.
+	*
+	* Queries beaten within the last `minGapMs` are skipped, so a flurry of
+	* wake events costs one beat per query. There is deliberately no local
+	* expiry anywhere in this module: the TTL is the server's, and the client's
+	* only duty is to keep asserting liveness while something is watching.
+	*/
+	heartbeatOnWake(minGapMs = WAKE_HEARTBEAT_MIN_GAP_MS) {
+		const now = Date.now();
+		let beaten = 0;
+		for (const [hash, queryState] of this.activeQueries.entries()) {
+			if ((this.subscriptions.get(hash)?.size ?? 0) === 0) continue;
+			if (queryState.lastHeartbeatAt !== void 0 && now - queryState.lastHeartbeatAt < minGapMs) continue;
+			if (queryState.ttlTimer) {
+				clearTimeout(queryState.ttlTimer);
+				queryState.ttlTimer = null;
+			}
+			queryState.lastHeartbeatAt = now;
+			this.onHeartbeat?.(hash);
+			this.startTTLHeartbeat(queryState, hash);
+			beaten++;
+		}
+		if (beaten > 0) this.logger.debug({
+			beaten,
+			Category: "sp00ky-client::DataModule::heartbeatOnWake"
+		}, "Wake heartbeat sent for watched queries");
+		return beaten;
+	}
 	async replaceRecordInQueries(record) {
 		for (const [queryHash, queryState] of this.activeQueries.entries()) {
 			const index = queryState.records.findIndex((r) => r.id === record.id);
@@ -5730,11 +5872,19 @@ function buildListRefSelect(table) {
 * no matter how long it waits, which is why this is read alongside them rather
 * than a retry counter.
 *
+* `state` rides along: the SSP writes `materializing` when it hands a full
+* publish to its edge flusher and flips it to `ready` INSIDE the transaction
+* that writes the edges. So `ready` + no edges + `rowCount 0` is a real empty
+* result, `materializing` + no edges is "still publishing", and a missing row
+* (the whole object is `NONE`) is "the server no longer has this view". A
+* server that predates the marker returns `state: NONE` and callers fall back
+* to `rowCount` alone.
+*
 * Returns `NONE` (→ null) when the row is not readable or does not exist yet;
 * callers must treat that as "unknown", not as zero.
 */
 function buildQueryRowCountSelect() {
-	return "SELECT VALUE rowCount FROM ONLY $in";
+	return "SELECT VALUE { rowCount: rowCount, state: state } FROM ONLY $in";
 }
 /**
 * Build the SurrealQL select for a query's SUBQUERY child edges — the
@@ -5767,7 +5917,7 @@ function buildListRefBatchSelect(table) {
 * without an id and must be treated as "unknown".
 */
 function buildQueryRowCountBatchSelect() {
-	return "SELECT VALUE { id: id, rowCount: rowCount } FROM $ins";
+	return "SELECT VALUE { id: id, rowCount: rowCount, state: state } FROM $ins";
 }
 /** Known edges one poll round trip may carry before the cycle is split. */
 const LIST_REF_POLL_ROW_BUDGET = 1500;
@@ -5897,14 +6047,16 @@ var SyncEngine = class {
 			Category: "sp00ky-client::SyncEngine::syncRecords"
 		}, "SyncEngine.syncRecords diff");
 		let stillRemoteIds = [];
-		if (removed.length > 0) stillRemoteIds = await this.handleRemovedRecords(removed);
+		let confirmedRemovedIds = [];
+		if (removed.length > 0) ({stillRemoteIds, confirmedRemovedIds} = await this.handleRemovedRecords(removed));
 		const toFetch = [...added, ...updated].filter((item) => {
 			const localVersion = this.cache.lookup(encodeRecordId(item.id));
 			return !(localVersion && item.version <= localVersion);
 		});
 		if (toFetch.length === 0) return {
 			remoteFetchMs: 0,
-			stillRemoteIds
+			stillRemoteIds,
+			confirmedRemovedIds
 		};
 		const versionMap = /* @__PURE__ */ new Map();
 		for (const item of toFetch) versionMap.set(encodeRecordId(item.id), item.version);
@@ -5954,7 +6106,8 @@ var SyncEngine = class {
 		this.events.emit(SyncEventTypes.RemoteDataIngested, { records: remoteResults });
 		return {
 			remoteFetchMs,
-			stillRemoteIds
+			stillRemoteIds,
+			confirmedRemovedIds
 		};
 	}
 	/**
@@ -5986,9 +6139,13 @@ var SyncEngine = class {
 				removed: removed.map((r) => r.toString()),
 				Category: "sp00ky-client::SyncEngine::handleRemovedRecords"
 			}, "Remote existence check failed, skipping deletion to avoid clobbering fresh data");
-			return [];
+			return {
+				stillRemoteIds: [],
+				confirmedRemovedIds: []
+			};
 		}
 		const stillRemoteIds = [];
+		const confirmedRemovedIds = [];
 		for (const recordId of removed) {
 			const recordIdStr = encodeRecordId(recordId);
 			if (!existingRemoteIds.has(recordIdStr)) {
@@ -5997,9 +6154,13 @@ var SyncEngine = class {
 					Category: "sp00ky-client::SyncEngine::handleRemovedRecords"
 				}, "Deleting confirmed removed record");
 				await this.cache.delete(recordId.table.name, recordIdStr);
+				confirmedRemovedIds.push(recordIdStr);
 			} else stillRemoteIds.push(recordIdStr);
 		}
-		return stillRemoteIds;
+		return {
+			stillRemoteIds,
+			confirmedRemovedIds
+		};
 	}
 };
 
@@ -6211,6 +6372,55 @@ var SyncScheduler = class {
 
 //#endregion
 //#region src/modules/sync/sync.ts
+/** Fold a row-count select result into {@link ServerViewMeta}. */
+function metaFromRow(row) {
+	if (!row || typeof row !== "object") return {
+		present: false,
+		rowCount: null,
+		state: null
+	};
+	const state = row.state === "materializing" || row.state === "ready" ? row.state : null;
+	return {
+		present: true,
+		rowCount: typeof row.rowCount === "number" ? row.rowCount : null,
+		state
+	};
+}
+/**
+* Re-read ladder for a registration that answered while the SSP was still
+* publishing (`state = 'materializing'`): the flusher window is ~100ms, so the
+* first rung usually lands it; the rest cover a slow write without waiting
+* for a backed-off poll tick.
+*/
+const MATERIALIZING_REFETCH_LADDER_MS = [
+	150,
+	400,
+	1e3
+];
+/**
+* How long LIVE `_00_list_ref` DELETEs for one query are held before they are
+* verified upstream as a batch. A view teardown (sweep, reset, republish)
+* arrives as one DELETE per edge within a few ms; a single peer delete costs
+* this plus one round trip.
+*/
+const LIVE_REMOVAL_COALESCE_MS = 100;
+/**
+* Collapse duplicate `(id, version)` pairs to one per id, keeping the highest
+* version. `_00_list_ref` has no unique index on `(in, out)`, and a full
+* republish over edges that were never cleaned up (a scheduler restart
+* orphans them) used to leave two rows per record; the client must render
+* each record once regardless.
+*/
+function dedupeRecordVersions(pairs) {
+	if (pairs.length < 2) return pairs;
+	const best = /* @__PURE__ */ new Map();
+	for (const [id, version] of pairs) {
+		const prev = best.get(id);
+		if (prev === void 0 || version > prev) best.set(id, version);
+	}
+	if (best.size === pairs.length) return pairs;
+	return Array.from(best.entries());
+}
 /**
 * The main synchronization engine for Sp00ky.
 * Handles the bidirectional synchronization between the local database and the remote backend.
@@ -6676,6 +6886,8 @@ var Sp00kySync = class Sp00kySync {
 	async prepareBucketSwitch() {
 		this.stopSelfHeal();
 		this.stopListRefPoll();
+		this.clearListRefRefetches();
+		this.clearLiveRemovals();
 		if (this.listRefPollInFlight) await this.listRefPollInFlight;
 		await this.killRefLiveQuery();
 		this.upQueue.clearDebounceTimers();
@@ -6849,7 +7061,7 @@ var Sp00kySync = class Sp00kySync {
 				if (!snapshot) continue;
 				this.listRefPolledAt.set(hash, now);
 				try {
-					if (await this.applyListRefSnapshot(hash, snapshot)) anyChanged = true;
+					if ((await this.applyListRefSnapshot(hash, snapshot)).changed) anyChanged = true;
 				} catch (err) {
 					this.logger.debug({
 						err: err?.message ?? err,
@@ -6901,7 +7113,12 @@ var Sp00kySync = class Sp00kySync {
 		for (const hash of hashById.values()) out.set(hash, {
 			primary: [],
 			subquery: [],
-			rowCount: null
+			rowCount: null,
+			meta: {
+				present: false,
+				rowCount: null,
+				state: null
+			}
 		});
 		for (const row of edges) {
 			const hash = hashById.get(encodeRecordId(row.in));
@@ -6911,19 +7128,27 @@ var Sp00kySync = class Sp00kySync {
 			if (row.parent == null) snapshot.primary.push(pair);
 			else snapshot.subquery.push(pair);
 		}
+		for (const snapshot of out.values()) {
+			snapshot.primary = dedupeRecordVersions(snapshot.primary);
+			snapshot.subquery = dedupeRecordVersions(snapshot.subquery);
+		}
 		for (const count of Array.isArray(counts) ? counts : []) {
 			if (!count || !count.id) continue;
 			const hash = hashById.get(encodeRecordId(count.id));
 			if (!hash) continue;
-			out.get(hash).rowCount = typeof count.rowCount === "number" ? count.rowCount : null;
+			const snapshot = out.get(hash);
+			snapshot.meta = metaFromRow(count);
+			snapshot.rowCount = snapshot.meta.rowCount;
 		}
-		if (edges.length === 0 && Array.from(out.entries()).some(([hash, snapshot]) => {
-			return (this.dataModule.getQueryByHash(hash)?.config.remoteArray?.length ?? 0) > 0 && (snapshot.rowCount ?? 0) > 0;
+		if (Array.from(out.entries()).some(([hash, snapshot]) => {
+			if ((this.dataModule.getQueryByHash(hash)?.config.remoteArray?.length ?? 0) === 0) return false;
+			if (!snapshot.meta.present) return true;
+			return edges.length === 0 && (snapshot.rowCount ?? 0) > 0;
 		})) {
 			this.logger.warn({
 				hashes,
 				Category: "sp00ky-client::Sp00kySync::fetchListRefSnapshots"
-			}, "Batched list_ref select returned no edges for queries that hold rows; re-reading one query at a time");
+			}, "Batched list_ref select is not trusted for queries that hold rows (no edges, or a missing _00_query row); re-reading one query at a time");
 			for (const hash of Array.from(out.keys())) {
 				const queryState = this.dataModule.getQueryByHash(hash);
 				if (!queryState) {
@@ -6944,13 +7169,15 @@ var Sp00kySync = class Sp00kySync {
 	*/
 	async fetchListRefSnapshot(id) {
 		const listRefTbl = this.listRefTable();
-		const [items, serverRowCount, children] = await this.remote.query(`${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()};\n${buildSubqueryListRefSelect(listRefTbl)}`, { in: id });
+		const [items, metaRow, children] = await this.remote.query(`${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()};\n${buildSubqueryListRefSelect(listRefTbl)}`, { in: id });
 		if (!Array.isArray(items)) return null;
-		const toPairs = (rows) => Array.isArray(rows) ? rows.map((item) => [encodeRecordId(item.out), item.version]) : [];
+		const toPairs = (rows) => dedupeRecordVersions(Array.isArray(rows) ? rows.map((item) => [encodeRecordId(item.out), item.version]) : []);
+		const meta = metaFromRow(metaRow);
 		return {
 			primary: toPairs(items),
 			subquery: toPairs(children),
-			rowCount: typeof serverRowCount === "number" ? serverRowCount : null
+			rowCount: meta.rowCount,
+			meta
 		};
 	}
 	/**
@@ -6964,14 +7191,18 @@ var Sp00kySync = class Sp00kySync {
 	*/
 	async applyListRefSnapshot(queryHash, snapshot) {
 		const queryState = this.dataModule.getQueryByHash(queryHash);
-		if (!queryState) return false;
+		if (!queryState) return {
+			changed: false,
+			outcome: "unchanged"
+		};
 		const fresh = snapshot.primary;
-		const serverRowCount = snapshot.rowCount;
 		const prevRemote = queryState.config.remoteArray ?? [];
+		const differs = !recordVersionArraysEqual(fresh, queryState.config.remoteArray);
+		let outcome = "unchanged";
+		if (differs) outcome = await this.dataModule.updateQueryRemoteArray(queryHash, fresh, { meta: snapshot.meta });
+		const applied = differs && outcome === "applied";
 		const freshIds = new Set(fresh.map(([id]) => id));
-		const removedIds = prevRemote.filter(([id]) => !freshIds.has(id)).map(([id]) => id);
-		const changed = !recordVersionArraysEqual(fresh, queryState.config.remoteArray);
-		if (changed) await this.dataModule.updateQueryRemoteArray(queryHash, fresh, { serverRowCount });
+		const removedIds = applied ? prevRemote.filter(([id]) => !freshIds.has(id)).map(([id]) => id) : [];
 		try {
 			await this.syncQuery(queryHash);
 		} catch (err) {
@@ -6981,8 +7212,8 @@ var Sp00kySync = class Sp00kySync {
 				Category: "sp00ky-client::Sp00kySync::applyListRefSnapshot"
 			}, "syncQuery failed during poll");
 		}
-		if (changed) this.dataModule.scheduleRematerialize(queryHash);
-		await this.applySubqueryChildren(queryHash, snapshot.subquery).catch((err) => {
+		if (applied) this.dataModule.scheduleRematerialize(queryHash);
+		if (outcome === "applied" || outcome === "unchanged") await this.applySubqueryChildren(queryHash, snapshot.subquery).catch((err) => {
 			this.logger.info({
 				err: err?.message ?? err,
 				queryHash,
@@ -6998,7 +7229,66 @@ var Sp00kySync = class Sp00kySync {
 				Category: "sp00ky-client::Sp00kySync::applyListRefSnapshot"
 			}, "notifyQuerySynced failed during poll-removal re-render");
 		}
-		return changed;
+		return {
+			changed: applied,
+			outcome
+		};
+	}
+	/**
+	* Re-read ONE query's server state now (edges + `_00_query` row) and land
+	* it through {@link applyListRefSnapshot}. The targeted form of the poll,
+	* for the moments that cannot wait for the next tick: a registration that
+	* answered `materializing`, and a LIVE removal that has to be checked
+	* against the row before it may empty a painted list.
+	*/
+	async refetchListRefForQuery(queryHash) {
+		const queryState = this.dataModule.getQueryByHash(queryHash);
+		if (!queryState) return null;
+		const snapshot = await this.fetchListRefSnapshot(queryState.config.id);
+		if (!snapshot) return null;
+		return this.applyListRefSnapshot(queryHash, snapshot);
+	}
+	/** Per-query pending targeted re-reads: one timer and the ladder still to walk. */
+	listRefRefetches = /* @__PURE__ */ new Map();
+	/**
+	* Schedule a targeted re-read of `queryHash` after `delays[0]` ms. If the
+	* read still says the server is publishing (`materializing`), the next rung
+	* of the ladder is armed; any other outcome ends it. Re-scheduling a hash
+	* that already has a timer replaces it (latest wins), so bursts coalesce.
+	*/
+	scheduleListRefRefetch(queryHash, delays) {
+		const ladder = typeof delays === "number" ? [delays] : [...delays];
+		if (ladder.length === 0) return;
+		this.clearListRefRefetch(queryHash);
+		const [first, ...rest] = ladder;
+		const timer = setTimeout(() => {
+			this.listRefRefetches.delete(queryHash);
+			this.refetchListRefForQuery(queryHash).then((result) => {
+				const queryState = this.dataModule.getQueryByHash(queryHash);
+				if (result?.outcome === "ignored" && queryState?.serverState === "materializing" && rest.length > 0) this.scheduleListRefRefetch(queryHash, rest);
+			}).catch((err) => {
+				this.logger.info({
+					err: err?.message ?? err,
+					queryHash,
+					Category: "sp00ky-client::Sp00kySync::scheduleListRefRefetch"
+				}, "Targeted list_ref re-read failed; the poll will retry");
+			});
+		}, first);
+		this.listRefRefetches.set(queryHash, {
+			timer,
+			ladder: rest
+		});
+	}
+	clearListRefRefetch(queryHash) {
+		const pending = this.listRefRefetches.get(queryHash);
+		if (pending) {
+			clearTimeout(pending.timer);
+			this.listRefRefetches.delete(queryHash);
+		}
+	}
+	clearListRefRefetches() {
+		for (const { timer } of this.listRefRefetches.values()) clearTimeout(timer);
+		this.listRefRefetches.clear();
 	}
 	/**
 	* Resolve the current `_00_list_ref` table name for the active auth
@@ -7214,12 +7504,12 @@ var Sp00kySync = class Sp00kySync {
 		}, "Live update is being processed");
 		const diff = createDiffFromDbOp(action, recordId, version, localArray);
 		const hash = extractIdPart(existing.config.id);
+		if (action === "DELETE") {
+			this.queueLiveRemoval(hash, recordId);
+			return;
+		}
 		if (existing.config.membershipKnown) {
-			const membershipDiff = action === "DELETE" ? {
-				added: [],
-				updated: [],
-				removed: [recordId]
-			} : {
+			const membershipDiff = {
 				added: [{
 					id: recordId,
 					version
@@ -7231,8 +7521,69 @@ var Sp00kySync = class Sp00kySync {
 			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);
-		else if (diff.added.length === 0 && diff.updated.length === 0) this.dataModule.scheduleRematerialize(hash);
+		if (diff.added.length === 0 && diff.updated.length === 0) this.dataModule.scheduleRematerialize(hash);
+	}
+	/** LIVE removals awaiting verification, per query, with their coalescing timer. */
+	pendingLiveRemovals = /* @__PURE__ */ new Map();
+	/**
+	* Hold a LIVE `_00_list_ref` DELETE for {@link LIVE_REMOVAL_COALESCE_MS},
+	* then verify the batch (see {@link flushLiveRemovals}). A sweep or a
+	* republish delivers a view's whole set as one burst, so one verification
+	* round covers it.
+	*/
+	queueLiveRemoval(hash, recordId) {
+		const key = encodeRecordId(recordId);
+		const pending = this.pendingLiveRemovals.get(hash);
+		if (pending) {
+			pending.ids.set(key, recordId);
+			return;
+		}
+		const ids = new Map([[key, recordId]]);
+		const timer = setTimeout(() => {
+			this.pendingLiveRemovals.delete(hash);
+			this.flushLiveRemovals(hash, Array.from(ids.values())).catch((err) => {
+				this.logger.info({
+					err: err?.message ?? err,
+					hash,
+					Category: "sp00ky-client::Sp00kySync::flushLiveRemovals"
+				}, "LIVE removal verification failed; the poll will converge");
+			});
+		}, LIVE_REMOVAL_COALESCE_MS);
+		this.pendingLiveRemovals.set(hash, {
+			ids,
+			timer
+		});
+	}
+	/**
+	* Verify a coalesced batch of LIVE removals against the upstream records.
+	* Ids that no longer exist upstream are dropped from membership (the body
+	* delete already happened inside `syncRecords`) and the query re-renders.
+	* Anything still present upstream - or a verification that could not run -
+	* is settled by a targeted re-read of the server's set for this query,
+	* where the `_00_query` row decides: gone = view lost (keep rows,
+	* re-register), `materializing` = wait, `ready` = adopt the smaller set.
+	*/
+	async flushLiveRemovals(hash, ids) {
+		const existing = this.dataModule.getQueryByHash(hash);
+		if (!existing || ids.length === 0) return;
+		const { confirmedRemovedIds, stillRemoteIds } = await this.runSyncForQuery(hash, {
+			added: [],
+			updated: [],
+			removed: ids
+		});
+		if (confirmedRemovedIds.length > 0 && existing.config.membershipKnown) {
+			const gone = new Set(confirmedRemovedIds);
+			const held = existing.config.remoteArray ?? [];
+			const next = held.filter(([id]) => !gone.has(id));
+			if (next.length !== held.length) await this.dataModule.updateQueryRemoteArray(hash, next, { verifiedRemoval: true });
+			await this.dataModule.notifyQuerySynced(hash);
+		}
+		const unverified = confirmedRemovedIds.length + stillRemoteIds.length < ids.length;
+		if (stillRemoteIds.length > 0 || unverified) this.scheduleListRefRefetch(hash, 0);
+	}
+	clearLiveRemovals() {
+		for (const { timer } of this.pendingLiveRemovals.values()) clearTimeout(timer);
+		this.pendingLiveRemovals.clear();
 	}
 	/**
 	* Handle a LIVE change to a SUBQUERY child edge (a `_00_list_ref` row with
@@ -7433,7 +7784,7 @@ var Sp00kySync = class Sp00kySync {
 		}
 		const diff = new ArraySyncer(queryState.config.localArray, queryState.config.remoteArray).nextSet();
 		if (!diff) return;
-		return this.runSyncForQuery(hash, diff);
+		await this.runSyncForQuery(hash, diff);
 	}
 	/**
 	* Run a sync for a single query while reflecting its fetch status. Marks the
@@ -7443,14 +7794,18 @@ var Sp00kySync = class Sp00kySync {
 	* means the single resulting UI update lands after this completes.
 	*/
 	async runSyncForQuery(hash, diff) {
+		const nothing = {
+			confirmedRemovedIds: [],
+			stillRemoteIds: []
+		};
 		const prime = this.primeGate();
 		if (prime !== this.settledPrime) {
 			await prime;
 			this.settledPrime = prime;
 			const fresh = this.dataModule.getQueryByHash(hash);
-			if (!fresh) return;
+			if (!fresh) return nothing;
 			const recomputed = new ArraySyncer(fresh.config.localArray, fresh.config.remoteArray).nextSet();
-			if (!recomputed) return;
+			if (!recomputed) return nothing;
 			diff = recomputed;
 		}
 		if (diff.added.length > 0 || diff.updated.length > 0) {
@@ -7463,8 +7818,13 @@ var Sp00kySync = class Sp00kySync {
 		}
 		const fetching = diff.added.length + diff.updated.length > 0;
 		if (fetching) this.dataModule.beginFetching(hash);
+		let summary = nothing;
 		try {
-			const { remoteFetchMs, stillRemoteIds } = await this.syncEngine.syncRecords(diff);
+			const { remoteFetchMs, stillRemoteIds, confirmedRemovedIds } = await this.syncEngine.syncRecords(diff);
+			summary = {
+				confirmedRemovedIds,
+				stillRemoteIds
+			};
 			if (fetching) this.dataModule.recordRemoteFetch(hash, remoteFetchMs);
 			if (stillRemoteIds.length > 0) {
 				const CONVERGE_AFTER = 3;
@@ -7503,6 +7863,7 @@ var Sp00kySync = class Sp00kySync {
 				this.dataModule.endFetching(hash);
 			}
 		}
+		return summary;
 	}
 	/**
 	* Record ids with a pending local DELETE in the outbox (`_00_pending_mutations`).
@@ -7596,19 +7957,20 @@ var Sp00kySync = class Sp00kySync {
 			ttl: queryState.config.ttl
 		} });
 		const listRefTbl = this.listRefTable();
-		const [items, serverRowCount] = await this.remote.query(`${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()}`, { in: queryState.config.id });
+		const [items, metaRow] = await this.remote.query(`${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()}`, { in: queryState.config.id });
+		const meta = metaFromRow(metaRow);
 		this.logger.trace({
 			queryId: encodeRecordId(queryState.config.id),
 			items,
 			Category: "sp00ky-client::Sp00kySync::createRemoteQuery"
 		}, "Got query record version array from remote");
-		const array = items.map((item) => [encodeRecordId(item.out), item.version]);
+		const array = dedupeRecordVersions(items.map((item) => [encodeRecordId(item.out), item.version]));
 		this.logger.debug({
 			queryId: encodeRecordId(queryState.config.id),
 			array,
 			Category: "sp00ky-client::Sp00kySync::createRemoteQuery"
 		}, "createdRemoteQuery");
-		if (array) await this.dataModule.updateQueryRemoteArray(queryHash, array, { serverRowCount });
+		if (await this.dataModule.updateQueryRemoteArray(queryHash, array, { meta }) === "ignored" && meta.present && meta.state === "materializing") this.scheduleListRefRefetch(queryHash, MATERIALIZING_REFETCH_LADDER_MS);
 		await this.syncSubqueryChildren(queryHash).catch((err) => {
 			this.logger.info({
 				err: err?.message ?? err,
@@ -7700,6 +8062,12 @@ var Sp00kySync = class Sp00kySync {
 				return;
 			}
 		}
+		this.clearListRefRefetch(queryHash);
+		const pendingRemoval = this.pendingLiveRemovals.get(queryHash);
+		if (pendingRemoval) {
+			clearTimeout(pendingRemoval.timer);
+			this.pendingLiveRemovals.delete(queryHash);
+		}
 		this.dataModule.finalizeDeregister(queryHash);
 	}
 };
@@ -8019,8 +8387,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.237";
-const WASM_VERSION = "0.0.1-canary.237";
+const CORE_VERSION = "0.0.1-canary.239";
+const WASM_VERSION = "0.0.1-canary.239";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -8132,8 +8500,9 @@ var DevToolsService = class DevToolsService {
 				remoteIds: remoteArray.slice(0, DevToolsService.STATE_IDS_CAP).map(([id]) => id),
 				idsTruncated: localArray.length > DevToolsService.STATE_IDS_CAP || remoteArray.length > DevToolsService.STATE_IDS_CAP,
 				membershipKnown: q.config.membershipKnown === true,
-				remoteSeen: q.config.remoteSeen === true,
-				emptyReads: q.config.emptyReads ?? 0,
+				authoritative: q.config.membershipKnown === true,
+				viewLost: q.viewLost === true,
+				serverState: q.serverState ?? null,
 				timings: this.dataManager.phaseTimings(q)
 			});
 		});
@@ -12909,6 +13278,19 @@ var Sp00kyClient = class {
 	subscribeToPendingMutations(cb) {
 		return this.sync.subscribeToPendingMutations(cb);
 	}
+	/** Number of queries mid-fetch right now. See {@link subscribeToFetchActivity}. */
+	get fetchingQueryCount() {
+		return this.dataModule.fetchingQueryCount;
+	}
+	/**
+	* Observe how many queries are fetching from the server. Fires immediately
+	* with the current count and again on every change, so one subscription can
+	* drive a "downloading" indicator for the whole app. Pair with
+	* {@link subscribeToPendingMutations} for the "uploading" half.
+	*/
+	subscribeToFetchActivity(cb) {
+		return this.dataModule.subscribeActivity(cb, { immediate: true });
+	}
 	/** Current sync-health snapshot. See {@link Sp00kyConfig.syncHealth}. */
 	get syncHealth() {
 		return this.sync.syncHealth;
@@ -13035,7 +13417,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.237",
+				coreVersion: "0.0.1-canary.239",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -13102,6 +13484,19 @@ var Sp00kyClient = class {
 				}, "TTL heartbeat failed");
 			});
 		};
+		this.dataModule.onViewLost = (queryHash) => {
+			this.devTools.logEvent("QUERY_VIEW_LOST", { queryHash });
+			this.sync.enqueueDownEvent({
+				type: "register",
+				payload: { hash: queryHash }
+			});
+		};
+		this.dataModule.onQueryAuthorityChange = (queryHash, known) => {
+			this.devTools.logEvent("QUERY_AUTHORITY_CHANGED", {
+				queryHash,
+				known
+			});
+		};
 		this.dataModule.onDeregister = (queryHash) => {
 			this.sync.enqueueDownEvent({
 				type: "cleanup",
@@ -13236,7 +13631,17 @@ var Sp00kyClient = class {
 					this.sync.releaseViewsOnUnload();
 				};
 				window.addEventListener("pagehide", onPageHide);
-				this.detachUnloadRelease = () => window.removeEventListener("pagehide", onPageHide);
+				const onWake = () => {
+					if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+					this.dataModule.heartbeatOnWake();
+				};
+				if (typeof document !== "undefined" && typeof document.addEventListener === "function") document.addEventListener("visibilitychange", onWake);
+				window.addEventListener("online", onWake);
+				this.detachUnloadRelease = () => {
+					window.removeEventListener("pagehide", onPageHide);
+					window.removeEventListener("online", onWake);
+					if (typeof document !== "undefined" && typeof document.removeEventListener === "function") document.removeEventListener("visibilitychange", onWake);
+				};
 			}
 			this.featureFlags.init();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "FeatureFlagModule initialized");
@@ -13677,6 +14082,16 @@ var Sp00kyClient = class {
 		return this.dataModule.subscribeStatus(queryHash, callback, options);
 	}
 	/**
+	* Subscribe to a query's authority flips: `true` once server membership is
+	* known for it (a registration or poll landed, or a durable `_00_window`
+	* seed was read on boot), `false` when it is reset (bucket switch). With
+	* `{ immediate: true }` the callback fires synchronously with the current
+	* value. Powers the bindings' `isAuthoritative()` / cold-only `isLoading()`.
+	*/
+	subscribeQueryAuthority(queryHash, callback, options) {
+		return this.dataModule.subscribeAuthority(queryHash, callback, options);
+	}
+	/**
 	* Report the frontend processing time (ms) a client framework spent applying
 	* an update for a query (e.g. `useQuery`'s `reconcile()`), so DevTools/MCP can
 	* surface the "frontend" phase of the per-query timing breakdown.