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

package/dist/index.js

@@ -311,68 +311,102 @@ var AbstractDatabaseService = class {
 	tx() {
 		return this.client.beginTransaction();
 	}
-	queryQueue = Promise.resolve();
 	/**
-	* Execute a query with serialized execution to prevent WASM transaction issues.
+	* How many statements may be in flight at once.
 	*
-	* 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.
-	*/
+	* `1` serializes every statement behind the previous one. The local engines
+	* need that: overlapping ops trip the WASM / SQLite transaction layer. The
+	* remote service raises it (`RemoteDatabaseService`): a SurrealDB socket
+	* multiplexes requests by id, and serializing them capped the client at one
+	* statement per round trip (~5/s at 170ms RTT), so the `_00_list_ref` poll
+	* alone could hold every registration behind it and one slow one-shot read
+	* stalled the whole client. The scheduler's `MAX_CONCURRENT_DOWN` only means
+	* something when this is above 1.
+	*/
+	maxConcurrentQueries = 1;
+	inFlightQueries = 0;
+	queryWaiters = [];
+	/** FIFO slot acquisition, so `maxConcurrentQueries = 1` keeps strict order. */
+	acquireQuerySlot() {
+		if (this.inFlightQueries < this.maxConcurrentQueries) {
+			this.inFlightQueries++;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			this.queryWaiters.push(() => {
+				this.inFlightQueries++;
+				resolve();
+			});
+		});
+	}
+	releaseQuerySlot() {
+		this.inFlightQueries--;
+		const next = this.queryWaiters.shift();
+		if (next) next();
+	}
 	/**
-	* Hook run inside the query queue, right before a statement is sent. The
-	* remote service uses it to hold statements while a connect is in flight,
-	* so a query never runs on a socket that is open but has not had its
-	* namespace and token applied yet. The default does nothing.
+	* Hook run right before a statement is sent, inside its slot. The remote
+	* service uses it to hold statements while a connect is in flight, so a
+	* query never runs on a socket that is open but has not had its namespace
+	* and token applied yet. The default does nothing.
 	*/
 	async beforeQuery() {}
+	/**
+	* Execute a statement under {@link maxConcurrentQueries}.
+	*
+	* A statement that never settles would hold its slot forever, and with a
+	* limit of 1 that blocks every later statement behind it. {@link
+	* queryTimeoutMs} bounds each one: on expiry this promise rejects and the
+	* slot is released, even though the underlying RPC is still parked in the
+	* SDK's pending map.
+	*/
 	async query(query, vars) {
-		return new Promise((resolve, reject) => {
-			this.queryQueue = this.queryQueue.then(async () => {
-				await this.beforeQuery();
-				const startTime = performance.now();
-				try {
-					this.logger.debug({
-						query,
-						vars,
-						Category: "sp00ky-client::Database::query"
-					}, "Executing query");
-					const result = await withTimeout(this.client.query(query, vars), this.queryTimeoutMs, () => this.timeoutError(query));
-					const duration = performance.now() - startTime;
-					this.events.emit(this.eventType, {
-						query,
-						vars,
-						duration,
-						success: true,
-						timestamp: Date.now()
-					});
-					resolve(result);
-					this.logger.trace({
-						query,
-						result,
-						Category: "sp00ky-client::Database::query"
-					}, "Query executed successfully");
-				} catch (err) {
-					const duration = performance.now() - startTime;
-					this.events.emit(this.eventType, {
-						query,
-						vars,
-						duration,
-						success: false,
-						error: err instanceof Error ? err.message : String(err),
-						timestamp: Date.now()
-					});
-					this.logger.error({
-						query,
-						vars,
-						err,
-						Category: "sp00ky-client::Database::query"
-					}, "Query execution failed");
-					reject(err);
-				}
-			}).catch(() => {});
-		});
+		await this.acquireQuerySlot();
+		try {
+			await this.beforeQuery();
+			const startTime = performance.now();
+			try {
+				this.logger.debug({
+					query,
+					vars,
+					Category: "sp00ky-client::Database::query"
+				}, "Executing query");
+				const result = await withTimeout(this.client.query(query, vars), this.queryTimeoutMs, () => this.timeoutError(query));
+				const duration = performance.now() - startTime;
+				this.events.emit(this.eventType, {
+					query,
+					vars,
+					duration,
+					success: true,
+					timestamp: Date.now()
+				});
+				this.logger.trace({
+					query,
+					result,
+					Category: "sp00ky-client::Database::query"
+				}, "Query executed successfully");
+				return result;
+			} catch (err) {
+				const duration = performance.now() - startTime;
+				this.events.emit(this.eventType, {
+					query,
+					vars,
+					duration,
+					success: false,
+					error: err instanceof Error ? err.message : String(err),
+					timestamp: Date.now()
+				});
+				this.logger.error({
+					query,
+					vars,
+					err,
+					Category: "sp00ky-client::Database::query"
+				}, "Query execution failed");
+				throw err;
+			}
+		} finally {
+			this.releaseQuerySlot();
+		}
 	}
 	async execute(query, vars) {
 		const raw = await this.query(query.sql, vars);
@@ -1002,6 +1036,12 @@ function resolveReconnectConfig(input) {
 		...input
 	};
 }
+/**
+* Statements the remote service keeps in flight at once. Enough for the sync
+* scheduler's `MAX_CONCURRENT_DOWN` registrations plus the list_ref poll and
+* an app's own one-shot reads, small enough to stay polite to the server.
+*/
+const REMOTE_MAX_CONCURRENT_QUERIES = 6;
 var RemoteDatabaseService = class extends AbstractDatabaseService {
 	config;
 	eventType = DatabaseEventTypes.RemoteQuery;
@@ -1047,6 +1087,7 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 		this.config = config;
 		this.reconnectConfig = resolveReconnectConfig(config.reconnect);
 		this.queryTimeoutMs = Math.max(0, config.queryTimeoutMs ?? 6e4);
+		this.maxConcurrentQueries = REMOTE_MAX_CONCURRENT_QUERIES;
 	}
 	getConfig() {
 		return this.config;
@@ -4187,11 +4228,13 @@ var DataModule = class DataModule {
 		const queryState = this.activeQueries.get(hash);
 		if (!queryState) return;
 		queryState.hydrated = true;
+		if (queryState.serverMembership) return;
 		if (rows.length === 0) return;
 		const epoch = this.local.epoch;
 		const tableName = queryState.config.tableName;
 		await this.buildAndSaveCacheBatch(tableName, rows);
 		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;
 		queryState.records = await this.materializeRecords(queryState);
@@ -4488,6 +4531,7 @@ var DataModule = class DataModule {
 		const epoch = this.local.epoch;
 		queryState.config.remoteArray = remoteArray;
 		queryState.config.membershipKnown = true;
+		queryState.serverMembership = true;
 		if (remoteArray.length > 0) {
 			queryState.config.remoteSeen = true;
 			queryState.config.emptyReads = 0;
@@ -4551,6 +4595,7 @@ var DataModule = class DataModule {
 				}
 			}
 			queryState.hydrated = false;
+			queryState.serverMembership = false;
 			queryState.syncNotified = false;
 			queryState.records = [];
 			this.setQueryStatus(hash, "fetching");
@@ -5707,6 +5752,59 @@ function buildSubqueryListRefSelect(table) {
 	return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NOT NONE`;
 }
 /**
+* One round trip for the edges of MANY queries: primary and subquery rows
+* together, split client-side on `parent`. Replaces two selects per query per
+* poll tick, which on a page with 20+ live queries was ~50 serialized round
+* trips per cycle and kept the remote busy full-time.
+*/
+function buildListRefBatchSelect(table) {
+	return `SELECT in, out, version, parent FROM ${table} WHERE in IN $ins`;
+}
+/**
+* `rowCount` for many `_00_query` rows at once, keyed by id so the caller does
+* not depend on the array order. Same semantics as
+* {@link buildQueryRowCountSelect}: a row the session cannot read comes back
+* without an id and must be treated as "unknown".
+*/
+function buildQueryRowCountBatchSelect() {
+	return "SELECT VALUE { id: id, rowCount: rowCount } FROM $ins";
+}
+/** Known edges one poll round trip may carry before the cycle is split. */
+const LIST_REF_POLL_ROW_BUDGET = 1500;
+/** A view at or past this many edges is "large": it rides on LIVE and is only
+*  re-polled every {@link LIST_REF_POLL_LARGE_VIEW_MIN_AGE_MS}. */
+const LIST_REF_POLL_LARGE_VIEW_ROWS = 1e3;
+const LIST_REF_POLL_LARGE_VIEW_MIN_AGE_MS = 15e3;
+/**
+* Split the active queries into the round trips of one poll cycle.
+*
+* Every query that is due is refreshed once per cycle, oldest refresh first,
+* packed greedily into chunks of at most `rowBudget` known edges so one
+* response never carries a whole page's worth of ids at once. A view with
+* `largeViewRows` or more edges is only due once `largeViewMinAgeMs` has
+* passed since its last refresh (LIVE remains its primary path); a chunk
+* always holds at least one query, so a single huge view still refreshes.
+*/
+function planListRefPollChunks(candidates, opts) {
+	const { now, rowBudget = LIST_REF_POLL_ROW_BUDGET, largeViewRows = LIST_REF_POLL_LARGE_VIEW_ROWS, largeViewMinAgeMs = LIST_REF_POLL_LARGE_VIEW_MIN_AGE_MS } = opts;
+	const due = candidates.filter((c) => c.rows < largeViewRows || now - c.lastPolledAt >= largeViewMinAgeMs).sort((a, b) => a.lastPolledAt - b.lastPolledAt || (a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0));
+	const chunks = [];
+	let current = [];
+	let currentRows = 0;
+	for (const c of due) {
+		const cost = Math.max(1, c.rows);
+		if (current.length > 0 && currentRows + cost > rowBudget) {
+			chunks.push(current);
+			current = [];
+			currentRows = 0;
+		}
+		current.push(c.hash);
+		currentRows += cost;
+	}
+	if (current.length > 0) chunks.push(current);
+	return chunks;
+}
+/**
 * Resolve the effective list-ref poll interval. Negative or zero
 * values fall back to the default — accepting them would either
 * disable polling silently or busy-loop the event loop.
@@ -6165,6 +6263,7 @@ var Sp00kySync = class Sp00kySync {
 	listRefPollInFlight = null;
 	refSyncIntervalMs;
 	listRefIdleStreak = 0;
+	listRefPolledAt = /* @__PURE__ */ new Map();
 	stillRemoteStreaks = /* @__PURE__ */ new Map();
 	lastLiveEventAt = null;
 	_liveRetryCount = 0;
@@ -6663,6 +6762,7 @@ var Sp00kySync = class Sp00kySync {
 			this.listRefPollTimer = setTimeout(async () => {
 				if (!this.listRefPollRunning) return;
 				let changed = false;
+				const startedAt = Date.now();
 				const tick = (async () => {
 					changed = await this.pollListRefForActiveQueries();
 				})();
@@ -6674,10 +6774,11 @@ var Sp00kySync = class Sp00kySync {
 					if (!this.listRefPollRunning) return;
 					const awaitingMembership = this.dataModule.hasSettledWritesPending();
 					this.listRefIdleStreak = changed || awaitingMembership ? 0 : this.listRefIdleStreak + 1;
-					schedule(listRefPollDelayMs({
+					const cycleMs = Date.now() - startedAt;
+					schedule(Math.max(listRefPollDelayMs({
 						idleStreak: this.listRefIdleStreak,
 						baseIntervalMs: this.refSyncIntervalMs
-					}));
+					}), cycleMs));
 				}
 			}, delayMs);
 		};
@@ -6691,9 +6792,10 @@ var Sp00kySync = class Sp00kySync {
 		}
 	}
 	/**
-	* One poll cycle: refetch `_00_list_ref` for every active query. Returns
-	* whether ANY query's remoteArray actually changed — the scheduler uses this
-	* to drive the adaptive idle backoff.
+	* One poll cycle: refetch `_00_list_ref` for the active queries that are due,
+	* one round trip per chunk (see `planListRefPollChunks`). Returns whether ANY
+	* query's remoteArray actually changed — the scheduler uses this to drive the
+	* adaptive idle backoff.
 	*
 	* Also the ONLY health signal that runs while the page is idle. Sync health is
 	* otherwise activity-driven (mutations/registrations via the scheduler,
@@ -6715,41 +6817,156 @@ var Sp00kySync = class Sp00kySync {
 			}
 			return false;
 		}
+		const now = Date.now();
+		const active = new Set(hashes);
+		for (const hash of this.listRefPolledAt.keys()) if (!active.has(hash)) this.listRefPolledAt.delete(hash);
+		const chunks = planListRefPollChunks(hashes.map((hash) => ({
+			hash,
+			rows: this.dataModule.getQueryByHash(hash)?.config.remoteArray?.length ?? 0,
+			lastPolledAt: this.listRefPolledAt.get(hash) ?? 0
+		})), { now });
 		let anyChanged = false;
 		let reached = false;
 		let firstNetworkErr;
-		for (const hash of hashes) try {
-			if (await this.refetchListRefForQuery(hash)) anyChanged = true;
-			reached = true;
-		} catch (err) {
-			if (classifySyncError(err) === "network") {
-				if (firstNetworkErr === void 0) firstNetworkErr = err;
-			} else reached = true;
-			this.logger.debug({
-				err: err?.message ?? err,
-				hash,
-				Category: "sp00ky-client::Sp00kySync::pollListRefForActiveQueries"
-			}, "Per-query list_ref poll failed");
+		for (const chunk of chunks) {
+			let snapshots;
+			try {
+				snapshots = await this.fetchListRefSnapshots(chunk);
+				reached = true;
+			} catch (err) {
+				if (classifySyncError(err) === "network") {
+					if (firstNetworkErr === void 0) firstNetworkErr = err;
+				} else reached = true;
+				this.logger.debug({
+					err: err?.message ?? err,
+					hashes: chunk,
+					Category: "sp00ky-client::Sp00kySync::pollListRefForActiveQueries"
+				}, "list_ref poll round trip failed");
+				continue;
+			}
+			for (const hash of chunk) {
+				const snapshot = snapshots.get(hash);
+				if (!snapshot) continue;
+				this.listRefPolledAt.set(hash, now);
+				try {
+					if (await this.applyListRefSnapshot(hash, snapshot)) anyChanged = true;
+				} catch (err) {
+					this.logger.debug({
+						err: err?.message ?? err,
+						hash,
+						Category: "sp00ky-client::Sp00kySync::pollListRefForActiveQueries"
+					}, "Per-query list_ref poll apply failed");
+				}
+			}
 		}
 		if (reached) this.recordSyncOutcome(true);
 		else if (firstNetworkErr !== void 0) this.recordSyncOutcome(false, firstNetworkErr);
 		return anyChanged;
 	}
 	/**
-	* Pull the upstream list_ref entries for `queryHash`, diff them
-	* against the local `remoteArray` cache, sync any added/updated rows
-	* through the SyncEngine, then persist the new remoteArray. This is
-	* the same shape `createRemoteQuery` does for its initial fetch and
-	* what `handleRemoteListRefChange` does per-LIVE-event — we reuse
-	* it on a timer as a fallback for missed LIVE notifications.
+	* The server's current `_00_list_ref` state for a chunk of queries in ONE
+	* round trip: primary edges, subquery-child edges and `_00_query.rowCount`.
+	* Every hash whose query still exists gets an entry (empty arrays and
+	* `rowCount: null` when nothing was readable), so a caller can tell "no
+	* edges" from "not asked". A hash is left out only when the select did not
+	* come back as an array at all — the old per-query code skipped the apply in
+	* that case too, since a non-array is not a membership set.
+	*
+	* Guarded against a batch that silently matches nothing: if the select
+	* returned no edge at all while the client holds edges for a query the
+	* server still reports rows for, the batch is not trusted and the chunk is
+	* re-read one query at a time with the single-query select. An empty set
+	* taken at face value would be recorded as the removal of every row.
+	*/
+	async fetchListRefSnapshots(hashes) {
+		const listRefTbl = this.listRefTable();
+		const ids = [];
+		const hashById = /* @__PURE__ */ new Map();
+		const out = /* @__PURE__ */ new Map();
+		for (const hash of hashes) {
+			const queryState = this.dataModule.getQueryByHash(hash);
+			if (!queryState) continue;
+			ids.push(queryState.config.id);
+			hashById.set(encodeRecordId(queryState.config.id), hash);
+		}
+		if (ids.length === 0) return out;
+		if (ids.length === 1) {
+			const hash = hashById.get(encodeRecordId(ids[0]));
+			const single = await this.fetchListRefSnapshot(ids[0]);
+			if (single) out.set(hash, single);
+			return out;
+		}
+		const [edges, counts] = await this.remote.query(`${buildListRefBatchSelect(listRefTbl)};\n${buildQueryRowCountBatchSelect()}`, { ins: ids });
+		if (!Array.isArray(edges)) return out;
+		for (const hash of hashById.values()) out.set(hash, {
+			primary: [],
+			subquery: [],
+			rowCount: null
+		});
+		for (const row of edges) {
+			const hash = hashById.get(encodeRecordId(row.in));
+			if (!hash) continue;
+			const snapshot = out.get(hash);
+			const pair = [encodeRecordId(row.out), row.version];
+			if (row.parent == null) snapshot.primary.push(pair);
+			else snapshot.subquery.push(pair);
+		}
+		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;
+		}
+		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;
+		})) {
+			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");
+			for (const hash of Array.from(out.keys())) {
+				const queryState = this.dataModule.getQueryByHash(hash);
+				if (!queryState) {
+					out.delete(hash);
+					continue;
+				}
+				const single = await this.fetchListRefSnapshot(queryState.config.id);
+				if (single) out.set(hash, single);
+				else out.delete(hash);
+			}
+		}
+		return out;
+	}
+	/**
+	* Single-query form of {@link fetchListRefSnapshots}: the selects the
+	* registration path has always used, in one statement batch. `null` when
+	* the primary select did not come back as an array.
+	*/
+	async fetchListRefSnapshot(id) {
+		const listRefTbl = this.listRefTable();
+		const [items, serverRowCount, 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]) : [];
+		return {
+			primary: toPairs(items),
+			subquery: toPairs(children),
+			rowCount: typeof serverRowCount === "number" ? serverRowCount : null
+		};
+	}
+	/**
+	* Land one poll snapshot for `queryHash`: diff the server's edges against the
+	* cached `remoteArray`, sync any added/updated rows through the SyncEngine,
+	* persist the new remoteArray and converge the subquery children. This is
+	* the same shape `createRemoteQuery` does for its initial fetch and what
+	* `handleRemoteListRefChange` does per-LIVE-event — we reuse it on a timer
+	* as a fallback for missed LIVE notifications. Returns whether membership
+	* changed.
 	*/
-	async refetchListRefForQuery(queryHash) {
+	async applyListRefSnapshot(queryHash, snapshot) {
 		const queryState = this.dataModule.getQueryByHash(queryHash);
 		if (!queryState) return false;
-		const listRefTbl = this.listRefTable();
-		const [items, serverRowCount] = await this.remote.query(`${buildListRefSelect(listRefTbl)};\n${buildQueryRowCountSelect()}`, { in: queryState.config.id });
-		if (!Array.isArray(items)) return false;
-		const fresh = items.map((item) => [encodeRecordId(item.out), item.version]);
+		const fresh = snapshot.primary;
+		const serverRowCount = snapshot.rowCount;
 		const prevRemote = queryState.config.remoteArray ?? [];
 		const freshIds = new Set(fresh.map(([id]) => id));
 		const removedIds = prevRemote.filter(([id]) => !freshIds.has(id)).map(([id]) => id);
@@ -6761,15 +6978,15 @@ var Sp00kySync = class Sp00kySync {
 			this.logger.info({
 				err: err?.message ?? err,
 				queryHash,
-				Category: "sp00ky-client::Sp00kySync::refetchListRefForQuery"
+				Category: "sp00ky-client::Sp00kySync::applyListRefSnapshot"
 			}, "syncQuery failed during poll");
 		}
 		if (changed) this.dataModule.scheduleRematerialize(queryHash);
-		await this.syncSubqueryChildren(queryHash).catch((err) => {
+		await this.applySubqueryChildren(queryHash, snapshot.subquery).catch((err) => {
 			this.logger.info({
 				err: err?.message ?? err,
 				queryHash,
-				Category: "sp00ky-client::Sp00kySync::refetchListRefForQuery"
+				Category: "sp00ky-client::Sp00kySync::applyListRefSnapshot"
 			}, "Subquery child sync failed during poll");
 		});
 		if (removedIds.length > 0) try {
@@ -6778,7 +6995,7 @@ var Sp00kySync = class Sp00kySync {
 			this.logger.info({
 				err: err?.message ?? err,
 				queryHash,
-				Category: "sp00ky-client::Sp00kySync::refetchListRefForQuery"
+				Category: "sp00ky-client::Sp00kySync::applyListRefSnapshot"
 			}, "notifyQuerySynced failed during poll-removal re-render");
 		}
 		return changed;
@@ -7426,6 +7643,17 @@ var Sp00kySync = class Sp00kySync {
 		const [items] = await this.remote.query(buildSubqueryListRefSelect(listRefTbl), { in: queryState.config.id });
 		if (!Array.isArray(items)) return;
 		const fresh = items.map((item) => [encodeRecordId(item.out), item.version]);
+		await this.applySubqueryChildren(queryHash, fresh);
+	}
+	/**
+	* Converge a `.related()` query's child bodies onto `fresh` (the server's
+	* current child edges). Shared by the registration path above and the poll,
+	* which reads the child edges in its batched round trip. See
+	* {@link syncSubqueryChildren} for the deletion-safety rules.
+	*/
+	async applySubqueryChildren(queryHash, fresh) {
+		const queryState = this.dataModule.getQueryByHash(queryHash);
+		if (!queryState) return;
 		const prev = queryState.config.subqueryRemoteArray ?? [];
 		if (recordVersionArraysEqual(fresh, prev)) return;
 		const diff = diffRecordVersionArray(prev, fresh);
@@ -7791,8 +8019,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.235";
-const WASM_VERSION = "0.0.1-canary.235";
+const CORE_VERSION = "0.0.1-canary.237";
+const WASM_VERSION = "0.0.1-canary.237";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -12807,7 +13035,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.235",
+				coreVersion: "0.0.1-canary.237",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -13314,16 +13542,34 @@ var Sp00kyClient = class {
 		return hash;
 	}
 	/**
-	* Background tail of {@link initQuery}: instant-hydrate (opt-in via
-	* `config.instantHydrate`, and only when the query is cold) followed by
-	* enqueuing the `register` down-event. Never rejects — both halves catch and
-	* log, so `void`-ing the returned promise can't produce an unhandled
-	* rejection. By default (hydrate off) the register lifecycle is the single
-	* freshness path; the one-shot fetch is an optimization apps enable
-	* explicitly, and it runs regardless of preload state — cache-first delivery
-	* never depends on WHY rows are cached.
+	* Background tail of {@link initQuery}: enqueue the `register` down-event,
+	* then instant-hydrate (opt-in via `config.instantHydrate`, and only when
+	* the query is cold). Never rejects — both halves catch and log, so
+	* `void`-ing the returned promise can't produce an unhandled rejection. By
+	* default (hydrate off) the register lifecycle is the single freshness path;
+	* the one-shot fetch is an optimization apps enable explicitly, and it runs
+	* regardless of preload state — cache-first delivery never depends on WHY
+	* rows are cached.
+	*
+	* Register goes first on purpose. The hydrate used to run strictly before
+	* the enqueue, so a windowed list's one-shot read (a full-table scan when
+	* the app has no matching index) held its own registration back by seconds
+	* per window. Now whichever answer lands first paints; a hydrate that
+	* arrives after the registration is dropped (`applyHydration`).
 	*/
 	async finishQueryInit(hash, q, params) {
+		try {
+			await this.sync.enqueueDownEvent({
+				type: "register",
+				payload: { hash }
+			});
+		} catch (err) {
+			this.logger.error({
+				err,
+				hash,
+				Category: "sp00ky-client::Sp00kyClient::initQuery"
+			}, "Failed to enqueue register down-event");
+		}
 		if (this.config.instantHydrate === true && this.dataModule.isCold(hash)) try {
 			const epoch = this.local.epoch;
 			const [rows] = await this.remote.query(q.selectQuery.query, params);
@@ -13339,18 +13585,6 @@ var Sp00kyClient = class {
 				Category: "sp00ky-client::Sp00kyClient::instantHydrate"
 			}, "Instant hydrate failed; proceeding with registration");
 		}
-		try {
-			await this.sync.enqueueDownEvent({
-				type: "register",
-				payload: { hash }
-			});
-		} catch (err) {
-			this.logger.error({
-				err,
-				hash,
-				Category: "sp00ky-client::Sp00kyClient::initQuery"
-			}, "Failed to enqueue register down-event");
-		}
 	}
 	/**
 	* Smart, awaitable preload/prewarm into the LOCAL cache — without registering a
@@ -13491,6 +13725,17 @@ var Sp00kyClient = class {
 		return fn(this.remote.getClient());
 	}
 	/**
+	* Run one raw SurrealQL statement on the remote through the client's own
+	* query path: the connect gate (it never runs on a socket whose namespace
+	* and token are not applied yet), the per-statement timeout and the
+	* concurrency limit. Prefer this over {@link useRemote} for one-shot reads
+	* such as counts; `useRemote` hands out the bare SDK client and raced a
+	* reconnect with "Specify a namespace to use".
+	*/
+	async remoteQuery(sql, vars) {
+		return this.remote.query(sql, vars);
+	}
+	/**
 	* Mint the salt used for query-id hashing, so two sessions registering the
 	* same logical query get distinct `_00_query` rows.
 	*

package/dist/types.d.ts

@@ -956,6 +956,11 @@ interface QueryState {
   /** Set once `applyHydration` has run for this query, so the cold instant-hydrate
    * path fires at most once per query (see DataModule.isCold/applyHydration). */
   hydrated?: boolean;
+  /** Set once a server-side membership set has been accepted this session
+   * (`updateQueryRemoteArray`). The `register` down-event is enqueued before
+   * the instant-hydrate, so a hydrate that finishes later must not prime
+   * membership over the authoritative set. Ephemeral. */
+  serverMembership?: boolean;
   /** Set once `notifyQuerySynced` has emitted for this registration lifetime.
    * Ephemeral (unlike the persisted `updateCount`), so a re-registered query
    * always emits at least once even when its records are unchanged — otherwise

package/package.json

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