@spooky-sync/core 0.0.1-canary.316 → 0.0.1-canary.317

package/AGENTS.md

@@ -33,7 +33,7 @@ re-materialized from state, never patched in place.
 
 ## Key exports (`src/index.ts`)
 
-- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Admin impersonation (`impersonation.enabled` in sp00ky.yml, admins only, server-enforced): `auth.impersonate(targetId, reason)`, `auth.stopImpersonating()`, `auth.impersonation`, `auth.subscribeImpersonation(cb)`, `auth.searchImpersonationTargets(search)`; while active the client injects a warning bar with a Stop button and shifts the page down onto a hazard-striped layer. `impersonationBanner` in the client config restyles it (`theme`), replaces it (`mode: 'custom'` + `client.acknowledgeImpersonationBanner()`, else it falls back after ~2.5s) or turns it off (`mode: 'none'`). See `/docs/client/impersonation`. Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)`. Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
+- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Admin impersonation (`impersonation.enabled` in sp00ky.yml, admins only, server-enforced): `auth.impersonate(targetId, reason)`, `auth.stopImpersonating()`, `auth.impersonation`, `auth.subscribeImpersonation(cb)`, `auth.searchImpersonationTargets(search)`; while active the client injects a warning bar with a Stop button and shifts the page down onto a hazard-striped layer. `impersonationBanner` in the client config restyles it (`theme`), replaces it (`mode: 'custom'` + `client.acknowledgeImpersonationBanner()`, else it falls back after ~2.5s) or turns it off (`mode: 'none'`). See `/docs/client/impersonation`. Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)` (queries a user waits on; a query that already shows rows and is only re-registering, as after a reload, is not counted). Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
 - `FailedMutation` — a row of the `_00_failed_mutations` tray (`mutationType`, `recordId`, `data`, `beforeRecord`, `error`, `revert`).
 - `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.

package/dist/index.d.ts

@@ -1011,6 +1011,11 @@ type OutEvent = {
  * `remote` tracks the server-side registration, `fetchDepth` is the refcount
  * behind `status: 'fetching'`, `notified` says whether subscribers received
  * at least one materialization this registration.
+ *
+ * `backgroundDepth` is the part of `fetchDepth` that re-verifies rows the
+ * query already shows: a registration of a query that is not `cold`. It still
+ * holds `status: 'fetching'` (results are not yet confirmed), but it is not
+ * traffic the user waits on, so the activity indicator leaves it out.
  */
 type QueryPhase = 'cold' | 'cached' | 'live' | 'view-lost';
 type RemotePhase = 'unregistered' | 'registering' | 'registered' | 'failed';
@@ -1018,6 +1023,7 @@ interface QueryLifecycle {
   readonly phase: QueryPhase;
   readonly remote: RemotePhase;
   readonly fetchDepth: number;
+  readonly backgroundDepth: number;
   readonly notified: boolean;
 }
 //#endregion
@@ -1143,6 +1149,8 @@ type Effect = {
 interface ServiceCalls {
   'hint.read': () => string | null;
   'hint.write': (bucketId: string) => void;
+  'salt.take': (authId: string | null) => string | null;
+  'salt.leave': (salt: string, authId: string | null) => void;
   'local.connect': (bucketId: string) => Promise<void>;
   'local.switchStore': (bucketId: string) => Promise<void>;
   'local.beginSwitch': () => () => void;

package/dist/index.js

@@ -2178,8 +2178,8 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.316";
-const WASM_VERSION = "0.0.1-canary.316";
+const CORE_VERSION = "0.0.1-canary.317";
+const WASM_VERSION = "0.0.1-canary.317";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
@@ -2910,6 +2910,7 @@ function seedLifecycle(resolvedBefore) {
 		phase: resolvedBefore ? "cached" : "cold",
 		remote: "unregistered",
 		fetchDepth: 0,
+		backgroundDepth: 0,
 		notified: false
 	};
 }
@@ -2946,12 +2947,19 @@ function transition(l, ev) {
 		};
 		case "fetch-begin": return {
 			...l,
-			fetchDepth: l.fetchDepth + 1
-		};
-		case "fetch-end": return l.fetchDepth === 0 ? l : {
-			...l,
-			fetchDepth: l.fetchDepth - 1
+			fetchDepth: l.fetchDepth + 1,
+			backgroundDepth: l.backgroundDepth + (ev.background ? 1 : 0)
 		};
+		case "fetch-end": {
+			if (l.fetchDepth === 0) return l;
+			const fetchDepth = l.fetchDepth - 1;
+			const backgroundDepth = Math.min(fetchDepth, l.backgroundDepth - (ev.background && l.backgroundDepth > 0 ? 1 : 0));
+			return {
+				...l,
+				fetchDepth,
+				backgroundDepth
+			};
+		}
 		case "notified": return l.notified ? l : {
 			...l,
 			notified: true
@@ -2965,6 +2973,8 @@ function transition(l, ev) {
 const isAuthoritative = (l) => l.phase !== "cold";
 const hasServerMembership = (l) => l.phase === "live" || l.phase === "view-lost";
 const deriveStatus = (l) => l.fetchDepth > 0 ? "fetching" : "idle";
+/** A fetch cycle the user is waiting on: rows to download, or a first registration. */
+const isForegroundFetching = (l) => l.fetchDepth > l.backgroundDepth;
 
 //#endregion
 //#region src/kernel/constants.ts
@@ -3571,7 +3581,13 @@ function retained(s) {
 const pendingDeleteIds = (s) => new Set(s.outbox.filter((i) => i.type === "delete").map((i) => i.recordId));
 const hasAckedWrites = (s) => s.outbox.some((i) => i.status === "acked");
 const pendingMutationCount = (s) => s.outbox.filter((i) => i.status === "pending").length;
-const fetchingQueryCount = (s) => [...s.queries.values()].filter((e) => e.lifecycle.fetchDepth > 0).length;
+/**
+* Queries with traffic the user is waiting on. A re-registration of a query
+* that already shows rows (every mounted query after a reload) is left out:
+* it only confirms what the cache painted, and any newer body it finds is
+* fetched by `fetchRows`, which counts.
+*/
+const fetchingQueryCount = (s) => [...s.queries.values()].filter((e) => isForegroundFetching(e.lifecycle)).length;
 /** Membership entries whose body is missing or older locally. */
 function needed(s, hash) {
 	const e = s.queries.get(hash);
@@ -4362,6 +4378,22 @@ function heartbeatBatch(ids) {
 }
 /** A heartbeat answer whose statement matched no row: the view was reclaimed. */
 const heartbeatRowGone = (result) => Array.isArray(result) && result.length === 0;
+const QUERY_ID = /^_00_query:(?:[0-9a-f]{64}|⟨[0-9a-f]{64}⟩)$/;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* The pagehide release: one bare statement for `beaconSql`, which has no params
+* channel, so ids are inlined. Only shapes the client minted itself get in, a
+* `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+* interpolated. `null` when there is nothing the server could act on: with no
+* session ids it could not tell this page's entries from anyone else's.
+*/
+function leaveViewsBeacon(ids, sessionIds) {
+	const list = ids.map((id) => String(id)).filter((id) => QUERY_ID.test(id));
+	const sids = sessionIds.filter((sid) => SESSION_ID.test(sid));
+	if (list.length === 0 || sids.length === 0) return null;
+	const sidList = sids.map((sid) => `'${sid}'`).join(", ");
+	return `FOR $id IN [${list.join(", ")}] { LET $_left = fn::query::leave($id, [${sidList}]); };`;
+}
 const bodySelect = () => "SELECT * FROM $ids";
 /** Local transaction that MERGEs many fetched bodies. */
 function upsertBodiesTx(records) {
@@ -4751,7 +4783,11 @@ function* registerRemote(env, hash, retry = false) {
 	if (!entry) return;
 	const { remote } = entry.lifecycle;
 	if (remote === "registered" || remote === "failed" || remote === "registering" && !retry) return;
-	yield fx.state.update(compose(applyLifecycle(hash, { type: "remote-registering" }), applyLifecycle(hash, { type: "fetch-begin" })));
+	const background = entry.lifecycle.phase !== "cold";
+	yield fx.state.update(compose(applyLifecycle(hash, { type: "remote-registering" }), applyLifecycle(hash, {
+		type: "fetch-begin",
+		background
+	})));
 	try {
 		const table = listRefTable(env, state);
 		const results = yield fx.remote.query(registerSelect(table), registerVars({
@@ -4839,7 +4875,10 @@ function* registerRemote(env, hash, retry = false) {
 			retry: true
 		});
 	} finally {
-		if (yield fx.state.read((s) => s.queries.has(hash))) yield fx.state.update(applyLifecycle(hash, { type: "fetch-end" }));
+		if (yield fx.state.read((s) => s.queries.has(hash))) yield fx.state.update(applyLifecycle(hash, {
+			type: "fetch-end",
+			background
+		}));
 	}
 }
 
@@ -5802,8 +5841,8 @@ function* boot(env, opts) {
 	yield fx.service("ssp.setPermissions");
 	yield fx.dispatch({ type: "PrimeCircuit" });
 	const restoredUserId = yield fx.service("auth.restoreSession");
-	const salt = yield fx.id("salt");
 	const authId = yield fx.service("auth.sessionAuthId");
+	const salt = (yield fx.service("salt.take", authId)) ?? (yield fx.id("salt"));
 	yield fx.state.update(setIdentity({
 		sessionId: salt,
 		userId: restoredUserId,
@@ -5895,9 +5934,19 @@ function* primeCircuit() {
 function* versionsPrimed(entries) {
 	yield fx.state.update(setVersions(entries));
 }
-/** Hand this tab's views back to the server when the page goes away for good. */
+/**
+* The page is going away for good: leave the salt for a reload of this tab,
+* then hand this tab's views back to the server. The release is deferred
+* server-side (`fn::query::leave`), so a reload that re-registers within the
+* grace finds its views still warm.
+*/
 function* pageHide() {
-	const ids = yield fx.state.read((s) => [...s.queries.values()].filter((e) => e.lifecycle.remote === "registered").map((e) => e.def.id));
+	const [salt, saltUserId, ids] = yield fx.state.read((s) => [
+		s.sessionId,
+		s.saltUserId,
+		[...s.queries.values()].filter((e) => e.lifecycle.remote === "registered").map((e) => e.def.id)
+	]);
+	if (salt) yield fx.service("salt.leave", salt, saltUserId);
 	if (ids.length > 0) yield fx.service("remote.releaseViews", ids);
 }
 function* warmBlobs() {
@@ -8163,6 +8212,11 @@ function resolveReconnectConfig(input) {
 * an app's own one-shot reads, small enough to stay polite to the server.
 */
 const REMOTE_MAX_CONCURRENT_QUERIES = 6;
+/**
+* Session ids a page remembers for its pagehide release. Only the sessions of
+* the last ttl matter; this many reconnects inside one ttl is a broken network.
+*/
+const MAX_SESSION_IDS = 16;
 var RemoteDatabaseService = class extends AbstractDatabaseService {
 	config;
 	eventType = DatabaseEventTypes.RemoteQuery;
@@ -8193,6 +8247,17 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 	* returns nothing, on a page that still looks signed in.
 	*/
 	authToken = null;
+	/**
+	* Every `session::id()` this page's sockets have had, oldest first.
+	*
+	* The server stamps a view's `subscribers` entry with the session that
+	* registered or heartbeated it, and every socket (an SDK reconnect, a
+	* supervisor revive) is a new session. The pagehide release goes over HTTP,
+	* whose own session id matches none of them, so it names these instead. Kept
+	* for the page, not the socket: a view registered before a reconnect still
+	* carries the old id until its next heartbeat.
+	*/
+	sessionIdsSeen = [];
 	constructor(config, logger) {
 		const events = createDatabaseEventSystem();
 		super(new Surreal({ engines: applyDiagnostics(createRemoteEngines(), ({ key, type, phase, ...other }) => {
@@ -8209,6 +8274,23 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 		this.reconnectConfig = resolveReconnectConfig(config.reconnect);
 		this.queryTimeoutMs = Math.max(0, config.queryTimeoutMs ?? 6e4);
 		this.maxConcurrentQueries = REMOTE_MAX_CONCURRENT_QUERIES;
+		this.client.subscribe("connected", () => void this.recordSessionId());
+	}
+	/** See {@link sessionIdsSeen}. */
+	sessionIds() {
+		return this.sessionIdsSeen;
+	}
+	/**
+	* Ask the socket that just connected for its session id. Straight to the
+	* SDK: it needs no namespace or identity, so it need not wait behind an
+	* in-flight connect or take a slot from the query queue.
+	*/
+	async recordSessionId() {
+		try {
+			const [sid] = await this.client.query("RETURN <string>session::id()");
+			if (typeof sid !== "string" || this.sessionIdsSeen.includes(sid)) return;
+			this.sessionIdsSeen = [...this.sessionIdsSeen, sid].slice(-MAX_SESSION_IDS);
+		} catch {}
 	}
 	getConfig() {
 		return this.config;
@@ -8225,6 +8307,10 @@ var RemoteDatabaseService = class extends AbstractDatabaseService {
 	*
 	* Best-effort by design: no await, no retry, errors swallowed. Every caller
 	* must have a server-side fallback that makes a lost beacon a non-event.
+	*
+	* The statement runs in a fresh HTTP session: `session::id()` there is a new
+	* id, not this page's socket's, so anything keyed on it must be passed the
+	* ids from {@link sessionIds} instead.
 	*/
 	beaconSql(sql) {
 		try {
@@ -14587,6 +14673,38 @@ function writeBootBucketHint(bucketId) {
 		if (typeof localStorage !== "undefined") localStorage.setItem(LAST_BUCKET_KEY, bucketId);
 	} catch {}
 }
+const RELOAD_SALT_KEY = "sp00ky:salt";
+/**
+* Take the salt this tab's previous page left on its way out, if it was minted
+* for the same principal. A reload that keeps its salt re-registers every
+* query onto the `_00_query` row it already had, which the SSP answers from
+* the live view instead of building a new one.
+*
+* Taken, not read: the key is absent while a page lives, so a duplicated tab
+* (which copies sessionStorage) mints its own salt rather than sharing this
+* tab's remote views.
+*/
+function takeReloadSalt(authId) {
+	try {
+		if (typeof sessionStorage === "undefined") return null;
+		const raw = sessionStorage.getItem(RELOAD_SALT_KEY);
+		if (raw === null) return null;
+		sessionStorage.removeItem(RELOAD_SALT_KEY);
+		const left = JSON.parse(raw);
+		return typeof left.salt === "string" && left.salt !== "" && (left.authId ?? null) === authId ? left.salt : null;
+	} catch {
+		return null;
+	}
+}
+/** Leave this page's salt for the next page in this tab; see {@link takeReloadSalt}. */
+function leaveReloadSalt(salt, authId) {
+	try {
+		if (typeof sessionStorage !== "undefined") sessionStorage.setItem(RELOAD_SALT_KEY, JSON.stringify({
+			salt,
+			authId
+		}));
+	} catch {}
+}
 function mintSalt() {
 	const c = globalThis.crypto;
 	if (c?.randomUUID) return c.randomUUID();
@@ -14648,7 +14766,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.316",
+			coreVersion: "0.0.1-canary.317",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -14752,6 +14870,8 @@ function createAdapters(config, s, host, lateModules) {
 	const services = {
 		"hint.read": readBootBucketHint,
 		"hint.write": writeBootBucketHint,
+		"salt.take": takeReloadSalt,
+		"salt.leave": leaveReloadSalt,
 		"local.connect": (bucketId) => s.local.connect(bucketId),
 		"local.switchStore": (bucketId) => s.local.switchStore(bucketId),
 		"local.beginSwitch": () => s.local.beginSwitch(),
@@ -14798,8 +14918,8 @@ function createAdapters(config, s, host, lateModules) {
 		"auth.consumeEndedImpersonation": () => s.auth.consumeEndedImpersonation(),
 		"remote.connect": () => s.remote.connect(),
 		"remote.releaseViews": (ids) => {
-			const list = ids.map((id) => String(id)).filter((id) => /^_00_query:[0-9a-f]{64}$/.test(id)).join(", ");
-			if (list) s.remote.beaconSql(`FOR $id IN [${list}] { LET $_released = fn::query::unsubscribe($id); };`);
+			const sql = leaveViewsBeacon(ids, s.remote.sessionIds());
+			if (sql) s.remote.beaconSql(sql);
 		},
 		"supervisor.start": () => s.connectionSupervisor.start(),
 		"tabs.start": (bucketId) => {

package/dist/live.js

@@ -1,4 +1,4 @@
-import { A as registerSelect, C as heartbeatRowGone, M as singleSnapshotSelect, R as sha256Hex, S as heartbeatBatch, a as metaFromRow, b as bodySelect, c as parseDuration, d as parseQueryParams, f as ANON_USER_ID, h as listRefTableFor, j as registerVars, l as parseRecordIdString, n as rowOfEdge, p as DEFAULT_REF_MODE, s as encodeRecordId, t as hashOfEdge, u as withTimeout, z as queryHashInput } from "./worker-edges.js";
+import { B as queryHashInput, C as heartbeatRowGone, M as registerVars, N as singleSnapshotSelect, S as heartbeatBatch, a as metaFromRow, b as bodySelect, c as parseDuration, d as parseQueryParams, f as ANON_USER_ID, h as listRefTableFor, j as registerSelect, l as parseRecordIdString, n as rowOfEdge, p as DEFAULT_REF_MODE, s as encodeRecordId, t as hashOfEdge, u as withTimeout, z as sha256Hex } from "./worker-edges.js";
 import { n as decodeTokenClaims } from "./worker-impersonation.js";
 import { RecordId, Surreal } from "surrealdb";
 

package/dist/pure.d.ts

@@ -217,6 +217,14 @@ declare function heartbeatBatch(ids: ReadonlyArray<RecordId<string>>): {
 };
 /** A heartbeat answer whose statement matched no row: the view was reclaimed. */
 declare const heartbeatRowGone: (result: unknown) => boolean;
+/**
+ * The pagehide release: one bare statement for `beaconSql`, which has no params
+ * channel, so ids are inlined. Only shapes the client minted itself get in, a
+ * `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+ * interpolated. `null` when there is nothing the server could act on: with no
+ * session ids it could not tell this page's entries from anyone else's.
+ */
+declare function leaveViewsBeacon(ids: ReadonlyArray<unknown>, sessionIds: ReadonlyArray<string>): string | null;
 declare const bodySelect: () => string;
 /** Local transaction that MERGEs many fetched bodies. */
 declare function upsertBodiesTx(records: ReadonlyArray<{
@@ -326,4 +334,4 @@ declare function sha256Hex(input: string): Promise<string>;
  */
 declare function queryKey(input: QueryKeyInput, sessionId: string | null): Promise<string>;
 //#endregion
-export { ANON_USER_ID, type Answer, BridgeSignOutMessage, BridgeTokenMessage, DEFAULT_REF_MODE, FAILED, IMPERSONATION_ACCESS, LEGACY_VIEW_TABLE, type ListRefSnapshot, PUSH_PAYLOAD_VERSION, PushNotification, PushNotificationAction, PushOp, PushPayload, PushPayloadKind, PushUrgency, type QueryKeyInput, type QueryMetaRow, type RefMode, RegisterPayload, type SealOptions, type SealedQuery, type SurqlHelper, type TokenClaims, type TxQuery, VIEW_TABLE, WebPushClientMessage, base64UrlToBytes, batchSnapshotSelect, bodySelect, bucketIdForUser, bytesToBase64Url, countViewRows, decodeTokenClaims, dedupeRecordVersions, encodeRecordId, hashOfEdge, heartbeatBatch, heartbeatRowGone, isPushPayload, listRefBatchSelect, listRefSelect, listRefTableFor, metaFromRow, parseDuration, parseQueryParams, parseRecordIdString, queryHashInput, queryKey, queryRowCountBatchSelect, queryRowCountSelect, readLegacyViewRows, readViewRows, registerSelect, registerVars, rowOfEdge, sameBytes, sanitizeUserId, sha256Hex, singleSnapshotSelect, snapshotFromSingle, subqueryListRefSelect, surql, upsertBodiesTx, viewKeyInput, viewRecordId, viewRow };
+export { ANON_USER_ID, type Answer, BridgeSignOutMessage, BridgeTokenMessage, DEFAULT_REF_MODE, FAILED, IMPERSONATION_ACCESS, LEGACY_VIEW_TABLE, type ListRefSnapshot, PUSH_PAYLOAD_VERSION, PushNotification, PushNotificationAction, PushOp, PushPayload, PushPayloadKind, PushUrgency, type QueryKeyInput, type QueryMetaRow, type RefMode, RegisterPayload, type SealOptions, type SealedQuery, type SurqlHelper, type TokenClaims, type TxQuery, VIEW_TABLE, WebPushClientMessage, base64UrlToBytes, batchSnapshotSelect, bodySelect, bucketIdForUser, bytesToBase64Url, countViewRows, decodeTokenClaims, dedupeRecordVersions, encodeRecordId, hashOfEdge, heartbeatBatch, heartbeatRowGone, isPushPayload, leaveViewsBeacon, listRefBatchSelect, listRefSelect, listRefTableFor, metaFromRow, parseDuration, parseQueryParams, parseRecordIdString, queryHashInput, queryKey, queryRowCountBatchSelect, queryRowCountSelect, readLegacyViewRows, readViewRows, registerSelect, registerVars, rowOfEdge, sameBytes, sanitizeUserId, sha256Hex, singleSnapshotSelect, snapshotFromSingle, subqueryListRefSelect, surql, upsertBodiesTx, viewKeyInput, viewRecordId, viewRow };

package/dist/pure.js

@@ -1,4 +1,4 @@
-import { A as registerSelect, B as viewKeyInput, C as heartbeatRowGone, D as queryRowCountSelect, E as queryRowCountBatchSelect, F as viewRecordId, I as viewRow, L as surql, M as singleSnapshotSelect, N as subqueryListRefSelect, O as readLegacyViewRows, P as upsertBodiesTx, R as sha256Hex, S as heartbeatBatch, T as listRefSelect, _ as LEGACY_VIEW_TABLE, a as metaFromRow, b as bodySelect, c as parseDuration, d as parseQueryParams, f as ANON_USER_ID, g as sanitizeUserId, h as listRefTableFor, i as dedupeRecordVersions, j as registerVars, k as readViewRows, l as parseRecordIdString, m as bucketIdForUser, n as rowOfEdge, o as snapshotFromSingle, p as DEFAULT_REF_MODE, r as FAILED, s as encodeRecordId, t as hashOfEdge, v as VIEW_TABLE, w as listRefBatchSelect, x as countViewRows, y as batchSnapshotSelect, z as queryHashInput } from "./worker-edges.js";
+import { A as readViewRows, B as queryHashInput, C as heartbeatRowGone, D as queryRowCountBatchSelect, E as listRefSelect, F as upsertBodiesTx, I as viewRecordId, L as viewRow, M as registerVars, N as singleSnapshotSelect, O as queryRowCountSelect, P as subqueryListRefSelect, R as surql, S as heartbeatBatch, T as listRefBatchSelect, V as viewKeyInput, _ as LEGACY_VIEW_TABLE, a as metaFromRow, b as bodySelect, c as parseDuration, d as parseQueryParams, f as ANON_USER_ID, g as sanitizeUserId, h as listRefTableFor, i as dedupeRecordVersions, j as registerSelect, k as readLegacyViewRows, l as parseRecordIdString, m as bucketIdForUser, n as rowOfEdge, o as snapshotFromSingle, p as DEFAULT_REF_MODE, r as FAILED, s as encodeRecordId, t as hashOfEdge, v as VIEW_TABLE, w as leaveViewsBeacon, x as countViewRows, y as batchSnapshotSelect, z as sha256Hex } from "./worker-edges.js";
 import { n as decodeTokenClaims, t as IMPERSONATION_ACCESS } from "./worker-impersonation.js";
 import { a as sameBytes, i as isPushPayload, n as base64UrlToBytes, r as bytesToBase64Url, t as PUSH_PAYLOAD_VERSION } from "./worker-types.js";
 
@@ -21,4 +21,4 @@ function queryKey(input, sessionId) {
 }
 
 //#endregion
-export { ANON_USER_ID, DEFAULT_REF_MODE, FAILED, IMPERSONATION_ACCESS, LEGACY_VIEW_TABLE, PUSH_PAYLOAD_VERSION, VIEW_TABLE, base64UrlToBytes, batchSnapshotSelect, bodySelect, bucketIdForUser, bytesToBase64Url, countViewRows, decodeTokenClaims, dedupeRecordVersions, encodeRecordId, hashOfEdge, heartbeatBatch, heartbeatRowGone, isPushPayload, listRefBatchSelect, listRefSelect, listRefTableFor, metaFromRow, parseDuration, parseQueryParams, parseRecordIdString, queryHashInput, queryKey, queryRowCountBatchSelect, queryRowCountSelect, readLegacyViewRows, readViewRows, registerSelect, registerVars, rowOfEdge, sameBytes, sanitizeUserId, sha256Hex, singleSnapshotSelect, snapshotFromSingle, subqueryListRefSelect, surql, upsertBodiesTx, viewKeyInput, viewRecordId, viewRow };
+export { ANON_USER_ID, DEFAULT_REF_MODE, FAILED, IMPERSONATION_ACCESS, LEGACY_VIEW_TABLE, PUSH_PAYLOAD_VERSION, VIEW_TABLE, base64UrlToBytes, batchSnapshotSelect, bodySelect, bucketIdForUser, bytesToBase64Url, countViewRows, decodeTokenClaims, dedupeRecordVersions, encodeRecordId, hashOfEdge, heartbeatBatch, heartbeatRowGone, isPushPayload, leaveViewsBeacon, listRefBatchSelect, listRefSelect, listRefTableFor, metaFromRow, parseDuration, parseQueryParams, parseRecordIdString, queryHashInput, queryKey, queryRowCountBatchSelect, queryRowCountSelect, readLegacyViewRows, readViewRows, registerSelect, registerVars, rowOfEdge, sameBytes, sanitizeUserId, sha256Hex, singleSnapshotSelect, snapshotFromSingle, subqueryListRefSelect, surql, upsertBodiesTx, viewKeyInput, viewRecordId, viewRow };

package/dist/types.d.ts

@@ -659,7 +659,26 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
    * returns nothing, on a page that still looks signed in.
    */
   private authToken;
+  /**
+   * Every `session::id()` this page's sockets have had, oldest first.
+   *
+   * The server stamps a view's `subscribers` entry with the session that
+   * registered or heartbeated it, and every socket (an SDK reconnect, a
+   * supervisor revive) is a new session. The pagehide release goes over HTTP,
+   * whose own session id matches none of them, so it names these instead. Kept
+   * for the page, not the socket: a view registered before a reconnect still
+   * carries the old id until its next heartbeat.
+   */
+  private sessionIdsSeen;
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger$1);
+  /** See {@link sessionIdsSeen}. */
+  sessionIds(): readonly string[];
+  /**
+   * Ask the socket that just connected for its session id. Straight to the
+   * SDK: it needs no namespace or identity, so it need not wait behind an
+   * in-flight connect or take a slot from the query queue.
+   */
+  private recordSessionId;
   getConfig(): Sp00kyConfig<any>['database'];
   /**
    * Send one SurrealQL statement so that it survives the page going away.
@@ -673,6 +692,10 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
    *
    * Best-effort by design: no await, no retry, errors swallowed. Every caller
    * must have a server-side fallback that makes a lost beacon a non-event.
+   *
+   * The statement runs in a fresh HTTP session: `session::id()` there is a new
+   * id, not this page's socket's, so anything keyed on it must be passed the
+   * ids from {@link sessionIds} instead.
    */
   beaconSql(sql: string): void;
   /**

package/dist/worker-edges.js

@@ -147,6 +147,22 @@ function heartbeatBatch(ids) {
 }
 /** A heartbeat answer whose statement matched no row: the view was reclaimed. */
 const heartbeatRowGone = (result) => Array.isArray(result) && result.length === 0;
+const QUERY_ID = /^_00_query:(?:[0-9a-f]{64}|⟨[0-9a-f]{64}⟩)$/;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* The pagehide release: one bare statement for `beaconSql`, which has no params
+* channel, so ids are inlined. Only shapes the client minted itself get in, a
+* `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+* interpolated. `null` when there is nothing the server could act on: with no
+* session ids it could not tell this page's entries from anyone else's.
+*/
+function leaveViewsBeacon(ids, sessionIds) {
+	const list = ids.map((id) => String(id)).filter((id) => QUERY_ID.test(id));
+	const sids = sessionIds.filter((sid) => SESSION_ID.test(sid));
+	if (list.length === 0 || sids.length === 0) return null;
+	const sidList = sids.map((sid) => `'${sid}'`).join(", ");
+	return `FOR $id IN [${list.join(", ")}] { LET $_left = fn::query::leave($id, [${sidList}]); };`;
+}
 const bodySelect = () => "SELECT * FROM $ids";
 /** Local transaction that MERGEs many fetched bodies. */
 function upsertBodiesTx(records) {
@@ -420,4 +436,4 @@ function rowOfEdge(value) {
 }
 
 //#endregion
-export { registerSelect as A, viewKeyInput as B, heartbeatRowGone as C, queryRowCountSelect as D, queryRowCountBatchSelect as E, viewRecordId as F, viewRow as I, surql as L, singleSnapshotSelect as M, subqueryListRefSelect as N, readLegacyViewRows as O, upsertBodiesTx as P, sha256Hex as R, heartbeatBatch as S, listRefSelect as T, LEGACY_VIEW_TABLE as _, metaFromRow as a, bodySelect as b, parseDuration as c, parseQueryParams as d, ANON_USER_ID as f, sanitizeUserId as g, listRefTableFor as h, dedupeRecordVersions as i, registerVars as j, readViewRows as k, parseRecordIdString as l, bucketIdForUser as m, rowOfEdge as n, snapshotFromSingle as o, DEFAULT_REF_MODE as p, FAILED as r, encodeRecordId as s, hashOfEdge as t, withTimeout as u, VIEW_TABLE as v, listRefBatchSelect as w, countViewRows as x, batchSnapshotSelect as y, queryHashInput as z };
+export { readViewRows as A, queryHashInput as B, heartbeatRowGone as C, queryRowCountBatchSelect as D, listRefSelect as E, upsertBodiesTx as F, viewRecordId as I, viewRow as L, registerVars as M, singleSnapshotSelect as N, queryRowCountSelect as O, subqueryListRefSelect as P, surql as R, heartbeatBatch as S, listRefBatchSelect as T, viewKeyInput as V, LEGACY_VIEW_TABLE as _, metaFromRow as a, bodySelect as b, parseDuration as c, parseQueryParams as d, ANON_USER_ID as f, sanitizeUserId as g, listRefTableFor as h, dedupeRecordVersions as i, registerSelect as j, readLegacyViewRows as k, parseRecordIdString as l, bucketIdForUser as m, rowOfEdge as n, snapshotFromSingle as o, DEFAULT_REF_MODE as p, FAILED as r, encodeRecordId as s, hashOfEdge as t, withTimeout as u, VIEW_TABLE as v, leaveViewsBeacon as w, countViewRows as x, batchSnapshotSelect as y, sha256Hex as z };

package/package.json

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

package/src/boot/boot.saga.test.ts

@@ -34,6 +34,7 @@ describe('boot', () => {
       'ssp.setPermissions',
       'auth.restoreSession',
       'auth.sessionAuthId',
+      'salt.take',
       'crdt.setSessionId',
       'auth.access',
       'ssp.setSessionAuth',
@@ -49,6 +50,18 @@ describe('boot', () => {
     expect(out.timers.get('gc')).toEqual({ ms: 30_000, event: { type: 'GcTick' } });
     expect(svc.names()).not.toContain('remote.connect');
   });
+  it('a reload keeps the salt its tab left for the same principal', async () => {
+    const svc = fakeServices({
+      'hint.read': () => 'u1',
+      'auth.restoreSession': async () => 'user:u1',
+      'auth.sessionAuthId': () => 'user:u1',
+      'salt.take': () => 'kept-salt',
+    });
+    const out = await runPure(boot(env, { sharedTabs: false }), { handlers: { service: svc.handler, 'local.query': () => [] } });
+    expect(svc.calls).toContainEqual(['salt.take', ['user:u1']]);
+    expect(svc.calls).toContainEqual(['crdt.setSessionId', ['kept-salt']]);
+    expect(out.state).toMatchObject({ sessionId: 'kept-salt', saltUserId: 'user:u1' });
+  });
   it('shared tabs: takes the role from the coordinator, or falls back to solo; schemaless engines skip provisioning; anonymous skips session auth', async () => {
     const leader = fakeServices({ 'hint.read': () => null, 'tabs.start': async () => 'leader', 'local.usesSurqlSchema': () => false, 'auth.restoreSession': async () => null, 'auth.sessionAuthId': () => null });
     const out = await runPure(boot(env, { sharedTabs: true }), { handlers: { service: leader.handler, 'local.query': () => [] } });
@@ -133,6 +146,15 @@ describe('startRemote / primeCircuit / versionsPrimed / pageHide / warmBlobs', (
     expect(f.state.primed).toBe(true);
     expect(f.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
   });
+  it('pageHide leaves the salt for a reload before releasing views', async () => {
+    const svc = fakeServices();
+    const s = { ...buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'registered' } })]), sessionId: 'salt-1', saltUserId: 'user:u1' };
+    await runPure(pageHide(), { state: s, handlers: { service: svc.handler } });
+    expect(svc.calls).toEqual([
+      ['salt.leave', ['salt-1', 'user:u1']],
+      ['remote.releaseViews', [[new RecordId('_00_query', 'a')]]],
+    ]);
+  });
   it('versionsPrimed records versions; pageHide releases registered views; warmBlobs is best-effort', async () => {
     const v = await runPure(versionsPrimed([['thing:1', 3]]), { state: buildState() });
     expect(v.state.versions.get('thing:1')).toBe(3);

package/src/boot/boot.saga.ts

@@ -43,8 +43,9 @@ export function* boot(env: SagaEnv, opts: BootOptions): Saga<void> {
   yield fx.dispatch({ type: 'PrimeCircuit' });
 
   const restoredUserId = (yield fx.service('auth.restoreSession')) as string | null;
-  const salt = (yield fx.id('salt')) as string;
   const authId = (yield fx.service('auth.sessionAuthId')) as string | null;
+  // A reload keeps the salt its tab had, so registrations land on warm views.
+  const salt = (((yield fx.service('salt.take', authId)) as string | null) ?? (yield fx.id('salt'))) as string;
   yield fx.state.update(R.setIdentity({ sessionId: salt, userId: restoredUserId, saltUserId: authId }));
   yield fx.service('crdt.setSessionId', salt);
   if (restoredUserId) yield fx.service('ssp.setSessionAuth', authId, (yield fx.service('auth.access')) as string | null);
@@ -115,9 +116,19 @@ export function* versionsPrimed(entries: Array<readonly [string, number]>): Saga
   yield fx.state.update(R.setVersions(entries));
 }
 
-/** Hand this tab's views back to the server when the page goes away for good. */
+/**
+ * The page is going away for good: leave the salt for a reload of this tab,
+ * then hand this tab's views back to the server. The release is deferred
+ * server-side (`fn::query::leave`), so a reload that re-registers within the
+ * grace finds its views still warm.
+ */
 export function* pageHide(): Saga<void> {
-  const ids = (yield fx.state.read((s) => [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered').map((e) => e.def.id))) as unknown[];
+  const [salt, saltUserId, ids] = (yield fx.state.read((s) => [
+    s.sessionId,
+    s.saltUserId,
+    [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered').map((e) => e.def.id),
+  ])) as [string | null, string | null, unknown[]];
+  if (salt) yield fx.service('salt.leave', salt, saltUserId);
   if (ids.length > 0) yield fx.service('remote.releaseViews', ids);
 }
 

package/src/client/services.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { leaveReloadSalt, takeReloadSalt } from './services';
+
+class MemoryStorage {
+  private items = new Map<string, string>();
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+  setItem(key: string, value: string): void {
+    this.items.set(key, value);
+  }
+  removeItem(key: string): void {
+    this.items.delete(key);
+  }
+}
+
+describe('reload salt', () => {
+  const g = globalThis as { sessionStorage?: unknown };
+  beforeEach(() => {
+    g.sessionStorage = new MemoryStorage();
+  });
+  afterEach(() => {
+    delete g.sessionStorage;
+  });
+
+  it('a salt left on the way out is taken once, by the same principal', () => {
+    leaveReloadSalt('s1', 'user:a');
+    expect(takeReloadSalt('user:a')).toBe('s1');
+    // Taken, not read: a tab duplicated from this page finds nothing.
+    expect(takeReloadSalt('user:a')).toBeNull();
+  });
+
+  it('another principal, or none, mints a fresh salt', () => {
+    leaveReloadSalt('s1', 'user:a');
+    expect(takeReloadSalt('user:b')).toBeNull();
+    leaveReloadSalt('s2', null);
+    expect(takeReloadSalt(null)).toBe('s2');
+    leaveReloadSalt('s3', null);
+    expect(takeReloadSalt('user:a')).toBeNull();
+  });
+
+  it('garbage or missing storage is a fresh salt, never a throw', () => {
+    (g.sessionStorage as MemoryStorage).setItem('sp00ky:salt', '{not json');
+    expect(takeReloadSalt(null)).toBeNull();
+    (g.sessionStorage as MemoryStorage).setItem('sp00ky:salt', JSON.stringify({ salt: '', authId: null }));
+    expect(takeReloadSalt(null)).toBeNull();
+    delete g.sessionStorage;
+    expect(takeReloadSalt(null)).toBeNull();
+    expect(() => leaveReloadSalt('s1', null)).not.toThrow();
+  });
+});

package/src/client/services.ts

@@ -28,6 +28,7 @@ import type { RuntimeEvent } from '../kernel/events';
 import type { ServiceCalls } from '../kernel/effects';
 import { encodeRecordId } from '../utils/index';
 import { sha256Hex } from '../utils/sha256';
+import { leaveViewsBeacon } from '../query/sql';
 import { hashOfEdge, rowOfEdge } from '../utils/edges';
 import { mintMutationId } from '../mutation/mutation-id';
 import { BucketHandle, bucketContentToBlob } from './bucket-handle';
@@ -50,6 +51,40 @@ export function writeBootBucketHint(bucketId: string): void {
   }
 }
 
+const RELOAD_SALT_KEY = 'sp00ky:salt';
+
+/**
+ * Take the salt this tab's previous page left on its way out, if it was minted
+ * for the same principal. A reload that keeps its salt re-registers every
+ * query onto the `_00_query` row it already had, which the SSP answers from
+ * the live view instead of building a new one.
+ *
+ * Taken, not read: the key is absent while a page lives, so a duplicated tab
+ * (which copies sessionStorage) mints its own salt rather than sharing this
+ * tab's remote views.
+ */
+export function takeReloadSalt(authId: string | null): string | null {
+  try {
+    if (typeof sessionStorage === 'undefined') return null;
+    const raw = sessionStorage.getItem(RELOAD_SALT_KEY);
+    if (raw === null) return null;
+    sessionStorage.removeItem(RELOAD_SALT_KEY);
+    const left = JSON.parse(raw) as { salt?: unknown; authId?: unknown };
+    return typeof left.salt === 'string' && left.salt !== '' && (left.authId ?? null) === authId ? left.salt : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Leave this page's salt for the next page in this tab; see {@link takeReloadSalt}. */
+export function leaveReloadSalt(salt: string, authId: string | null): void {
+  try {
+    if (typeof sessionStorage !== 'undefined') sessionStorage.setItem(RELOAD_SALT_KEY, JSON.stringify({ salt, authId }));
+  } catch {
+    /* private-mode storage errors: the next page mints a fresh salt */
+  }
+}
+
 // Moved to a pure module so `@spooky-sync/core/pure` and the live feed share
 // it; re-exported here for existing imports.
 export { sha256Hex };
@@ -220,6 +255,8 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
   const services: ServiceCalls = {
     'hint.read': readBootBucketHint,
     'hint.write': writeBootBucketHint,
+    'salt.take': takeReloadSalt,
+    'salt.leave': leaveReloadSalt,
     'local.connect': (bucketId) => s.local.connect(bucketId),
     'local.switchStore': (bucketId) => s.local.switchStore(bucketId),
     'local.beginSwitch': () => s.local.beginSwitch(),
@@ -260,11 +297,8 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
     'auth.consumeEndedImpersonation': () => s.auth.consumeEndedImpersonation(),
     'remote.connect': () => s.remote.connect(),
     'remote.releaseViews': (ids) => {
-      const list = ids
-        .map((id) => String(id))
-        .filter((id) => /^_00_query:[0-9a-f]{64}$/.test(id))
-        .join(', ');
-      if (list) s.remote.beaconSql(`FOR $id IN [${list}] { LET $_released = fn::query::unsubscribe($id); };`);
+      const sql = leaveViewsBeacon(ids, s.remote.sessionIds());
+      if (sql) s.remote.beaconSql(sql);
     },
     'supervisor.start': () => s.connectionSupervisor.start(),
     'tabs.start': (bucketId) => {

package/src/kernel/effects.ts

@@ -70,6 +70,8 @@ export type EffectKind = Effect['kind'];
 export interface ServiceCalls {
   'hint.read': () => string | null;
   'hint.write': (bucketId: string) => void;
+  'salt.take': (authId: string | null) => string | null;
+  'salt.leave': (salt: string, authId: string | null) => void;
   'local.connect': (bucketId: string) => Promise<void>;
   'local.switchStore': (bucketId: string) => Promise<void>;
   'local.beginSwitch': () => () => void;

package/src/query/register.saga.test.ts

@@ -156,6 +156,24 @@ describe('registerRemote', () => {
     expect(out.dispatched).toEqual([{ type: 'FetchRows' }, { type: 'FetchRows' }, { type: 'SyncOutcome', ok: true }]);
     expect(out.emitted).toContainEqual({ type: 'query:authority', hash: 'a', known: true });
   });
+  it('a cold registration is foreground; a cached or live one is background', async () => {
+    for (const [phase, background] of [['cold', 0], ['cached', 1], ['live', 1]] as const) {
+      const seen: Array<[number, number]> = [];
+      const out = await runPure(registerRemote(env, 'a'), {
+        state: buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { phase } })]),
+        handlers: {
+          'remote.query': (_e: unknown, ctx) => {
+            const l = ctx.state.queries.get('a')!.lifecycle;
+            seen.push([l.fetchDepth, l.backgroundDepth]);
+            return happy();
+          },
+          'local.upsert': () => undefined,
+        },
+      });
+      expect(seen).toEqual([[1, background]]);
+      expect(out.state.queries.get('a')!.lifecycle).toMatchObject({ fetchDepth: 0, backgroundDepth: 0 });
+    }
+  });
   it('guards: missing entry, already registered / failed, registering without retry', async () => {
     const none = await runPure(registerRemote(env, 'zzz'), { state: buildState([]) });
     expect(none.log.filter((x) => x.kind === 'remote.query')).toHaveLength(0);

package/src/query/register.saga.ts

@@ -151,8 +151,11 @@ export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): S
   if (!entry) return;
   const { remote } = entry.lifecycle;
   if (remote === 'registered' || remote === 'failed' || (remote === 'registering' && !retry)) return;
+  // A query that already shows rows (cached or live) only re-verifies them
+  // here: the cycle holds `fetching` but is not traffic the user waits on.
+  const background = entry.lifecycle.phase !== 'cold';
   yield fx.state.update(
-    R.compose(R.applyLifecycle(hash, { type: 'remote-registering' }), R.applyLifecycle(hash, { type: 'fetch-begin' }))
+    R.compose(R.applyLifecycle(hash, { type: 'remote-registering' }), R.applyLifecycle(hash, { type: 'fetch-begin', background }))
   );
   try {
     const table = listRefTable(env, state);
@@ -221,6 +224,6 @@ export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): S
     }
   } finally {
     const stillThere = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
-    if (stillThere) yield fx.state.update(R.applyLifecycle(hash, { type: 'fetch-end' }));
+    if (stillThere) yield fx.state.update(R.applyLifecycle(hash, { type: 'fetch-end', background }));
   }
 }

package/src/query/sql.test.ts

@@ -50,6 +50,24 @@ describe('query sql builders (golden against the previous builders)', () => {
     expect(sql.heartbeatRowGone([{ id: a }])).toBe(false);
     expect(sql.heartbeatRowGone(undefined)).toBe(false);
   });
+  it('the pagehide beacon names the page sessions and inlines only shapes it minted', () => {
+    const a = new RecordId('_00_query', 'a'.repeat(64));
+    const b = new RecordId('_00_query', 'b'.repeat(64));
+    const s1 = 'de81a067-f4bc-4351-a2a3-1ecf06b6305a';
+    const s2 = '8A14ED5A-32B5-4B4E-973D-D2B88860932F';
+    expect(sql.leaveViewsBeacon([a, b], [s1, s2])).toBe(
+      `FOR $id IN [${a}, ${b}] { LET $_left = fn::query::leave($id, ['${s1}', '${s2}']); };`
+    );
+    const digits = new RecordId('_00_query', '1'.repeat(64));
+    expect(sql.leaveViewsBeacon([digits], [s1])).toBe(`FOR $id IN [${digits}] { LET $_left = fn::query::leave($id, ['${s1}']); };`);
+    // Anything else is dropped rather than interpolated.
+    expect(sql.leaveViewsBeacon([a, new RecordId('_00_query', "x']; DELETE user; --"), 'user:1'], [s1, "x'; DELETE user; --"])).toBe(
+      `FOR $id IN [${a}] { LET $_left = fn::query::leave($id, ['${s1}']); };`
+    );
+    // No session ids: the server could not tell this page's entries from a reload's, so send nothing.
+    expect(sql.leaveViewsBeacon([a], [])).toBeNull();
+    expect(sql.leaveViewsBeacon([], [s1])).toBeNull();
+  });
   it('upsertBodiesTx MERGEs each body inside one transaction', () => {
     const { query, vars } = sql.upsertBodiesTx([
       { id: 'thing:1', content: { a: 1 } },

package/src/query/sql.ts

@@ -76,6 +76,25 @@ export function heartbeatBatch(ids: ReadonlyArray<RecordId<string>>): { sql: str
 /** A heartbeat answer whose statement matched no row: the view was reclaimed. */
 export const heartbeatRowGone = (result: unknown): boolean => Array.isArray(result) && result.length === 0;
 
+// The SDK escapes an all-digit key as `⟨…⟩`; both forms parse back to the same id.
+const QUERY_ID = /^_00_query:(?:[0-9a-f]{64}|⟨[0-9a-f]{64}⟩)$/;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The pagehide release: one bare statement for `beaconSql`, which has no params
+ * channel, so ids are inlined. Only shapes the client minted itself get in, a
+ * `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+ * interpolated. `null` when there is nothing the server could act on: with no
+ * session ids it could not tell this page's entries from anyone else's.
+ */
+export function leaveViewsBeacon(ids: ReadonlyArray<unknown>, sessionIds: ReadonlyArray<string>): string | null {
+  const list = ids.map((id) => String(id)).filter((id) => QUERY_ID.test(id));
+  const sids = sessionIds.filter((sid) => SESSION_ID.test(sid));
+  if (list.length === 0 || sids.length === 0) return null;
+  const sidList = sids.map((sid) => `'${sid}'`).join(', ');
+  return `FOR $id IN [${list.join(', ')}] { LET $_left = fn::query::leave($id, [${sidList}]); };`;
+}
+
 export const bodySelect = (): string => 'SELECT * FROM $ids';
 
 /** Local transaction that MERGEs many fetched bodies. */

package/src/services/database/remote.ts

@@ -37,6 +37,12 @@ export type RemoteConnectionEvent = ConnectionState | 'error';
  */
 const REMOTE_MAX_CONCURRENT_QUERIES = 6;
 
+/**
+ * Session ids a page remembers for its pagehide release. Only the sessions of
+ * the last ttl matter; this many reconnects inside one ttl is a broken network.
+ */
+const MAX_SESSION_IDS = 16;
+
 export class RemoteDatabaseService extends AbstractDatabaseService {
   private config: Sp00kyConfig<any>['database'];
   protected eventType = DatabaseEventTypes.RemoteQuery;
@@ -67,6 +73,17 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
    * returns nothing, on a page that still looks signed in.
    */
   private authToken: string | null = null;
+  /**
+   * Every `session::id()` this page's sockets have had, oldest first.
+   *
+   * The server stamps a view's `subscribers` entry with the session that
+   * registered or heartbeated it, and every socket (an SDK reconnect, a
+   * supervisor revive) is a new session. The pagehide release goes over HTTP,
+   * whose own session id matches none of them, so it names these instead. Kept
+   * for the page, not the socket: a view registered before a reconnect still
+   * carries the old id until its next heartbeat.
+   */
+  private sessionIdsSeen: string[] = [];
 
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger) {
     const events = createDatabaseEventSystem();
@@ -98,6 +115,27 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
     this.reconnectConfig = resolveReconnectConfig(config.reconnect);
     this.queryTimeoutMs = Math.max(0, config.queryTimeoutMs ?? 60_000);
     this.maxConcurrentQueries = REMOTE_MAX_CONCURRENT_QUERIES;
+    this.client.subscribe('connected', () => void this.recordSessionId());
+  }
+
+  /** See {@link sessionIdsSeen}. */
+  sessionIds(): readonly string[] {
+    return this.sessionIdsSeen;
+  }
+
+  /**
+   * Ask the socket that just connected for its session id. Straight to the
+   * SDK: it needs no namespace or identity, so it need not wait behind an
+   * in-flight connect or take a slot from the query queue.
+   */
+  private async recordSessionId(): Promise<void> {
+    try {
+      const [sid] = (await this.client.query('RETURN <string>session::id()')) as unknown[];
+      if (typeof sid !== 'string' || this.sessionIdsSeen.includes(sid)) return;
+      this.sessionIdsSeen = [...this.sessionIdsSeen, sid].slice(-MAX_SESSION_IDS);
+    } catch {
+      // Without it this socket's views fall back to the TTL sweep.
+    }
   }
 
   getConfig(): Sp00kyConfig<any>['database'] {
@@ -116,6 +154,10 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
    *
    * Best-effort by design: no await, no retry, errors swallowed. Every caller
    * must have a server-side fallback that makes a lost beacon a non-event.
+   *
+   * The statement runs in a fresh HTTP session: `session::id()` there is a new
+   * id, not this page's socket's, so anything keyed on it must be passed the
+   * ids from {@link sessionIds} instead.
    */
   beaconSql(sql: string): void {
     try {

package/src/state/lifecycle.test.ts

@@ -1,11 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import type { LifecycleEvent, QueryLifecycle, QueryPhase } from './lifecycle';
-import { deriveStatus, hasServerMembership, isAuthoritative, LifecycleError, seedLifecycle, transition } from './lifecycle';
+import { deriveStatus, hasServerMembership, isAuthoritative, isForegroundFetching, LifecycleError, seedLifecycle, transition } from './lifecycle';
 
 const at = (phase: QueryPhase, over: Partial<QueryLifecycle> = {}): QueryLifecycle => ({
   phase,
   remote: 'unregistered',
   fetchDepth: 0,
+  backgroundDepth: 0,
   notified: false,
   ...over,
 });
@@ -33,7 +34,7 @@ describe('transition table (phase axis)', () => {
   });
   it('bucket-switch reseeds and clears fetch depth', () => {
     const l = transition(at('live', { fetchDepth: 3, notified: true }), { type: 'bucket-switch', resolvedBefore: true });
-    expect(l).toEqual({ phase: 'cached', remote: 'unregistered', fetchDepth: 0, notified: false });
+    expect(l).toEqual({ phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false });
   });
 });
 
@@ -63,6 +64,24 @@ describe('remote / fetch / notified axes', () => {
     const same = transition(l, { type: 'fetch-end' });
     expect(same).toBe(l);
   });
+  it('background cycles hold fetching but are not foreground', () => {
+    let l = at('cached');
+    l = transition(l, { type: 'fetch-begin', background: true });
+    expect(deriveStatus(l)).toBe('fetching');
+    expect(isForegroundFetching(l)).toBe(false);
+    l = transition(l, { type: 'fetch-begin' });
+    expect(isForegroundFetching(l)).toBe(true);
+    l = transition(l, { type: 'fetch-end' });
+    expect(l).toMatchObject({ fetchDepth: 1, backgroundDepth: 1 });
+    expect(isForegroundFetching(l)).toBe(false);
+    l = transition(l, { type: 'fetch-end', background: true });
+    expect(l).toMatchObject({ fetchDepth: 0, backgroundDepth: 0 });
+    expect(deriveStatus(l)).toBe('idle');
+  });
+  it('an unbalanced end never leaves more background cycles than cycles', () => {
+    const l = transition(at('live', { fetchDepth: 1, backgroundDepth: 1 }), { type: 'fetch-end' });
+    expect(l).toMatchObject({ fetchDepth: 0, backgroundDepth: 0 });
+  });
   it('notified is idempotent', () => {
     const l = transition(at('live'), { type: 'notified' });
     expect(transition(l, { type: 'notified' })).toBe(l);
@@ -89,6 +108,8 @@ describe('invariants over random event sequences', () => {
     { type: 'remote-dropped' },
     { type: 'fetch-begin' },
     { type: 'fetch-end' },
+    { type: 'fetch-begin', background: true },
+    { type: 'fetch-end', background: true },
     { type: 'notified' },
     { type: 'bucket-switch', resolvedBefore: false },
     { type: 'seed', resolvedBefore: true },
@@ -97,7 +118,7 @@ describe('invariants over random event sequences', () => {
   let seed = 42;
   const rand = () => (seed = (seed * 1664525 + 1013904223) % 2 ** 32) / 2 ** 32;
 
-  it('fetchDepth >= 0, notified only after live-or-cached, view-lost never from cold', () => {
+  it('0 <= backgroundDepth <= fetchDepth, notified only after live-or-cached, view-lost never from cold', () => {
     for (let run = 0; run < 200; run++) {
       let l = seedLifecycle(rand() < 0.5);
       for (let i = 0; i < 25; i++) {
@@ -110,6 +131,8 @@ describe('invariants over random event sequences', () => {
           continue;
         }
         expect(l.fetchDepth).toBeGreaterThanOrEqual(0);
+        expect(l.backgroundDepth).toBeGreaterThanOrEqual(0);
+        expect(l.backgroundDepth).toBeLessThanOrEqual(l.fetchDepth);
         if (ev.type === 'row-missing' && before.phase === 'cold') expect(l.phase).toBe('cold');
         if (l.phase === 'view-lost') expect(before.phase).not.toBe('cold');
       }

package/src/state/lifecycle.ts

@@ -14,6 +14,11 @@ import type { QueryStatus } from '../types';
  * `remote` tracks the server-side registration, `fetchDepth` is the refcount
  * behind `status: 'fetching'`, `notified` says whether subscribers received
  * at least one materialization this registration.
+ *
+ * `backgroundDepth` is the part of `fetchDepth` that re-verifies rows the
+ * query already shows: a registration of a query that is not `cold`. It still
+ * holds `status: 'fetching'` (results are not yet confirmed), but it is not
+ * traffic the user waits on, so the activity indicator leaves it out.
  */
 export type QueryPhase = 'cold' | 'cached' | 'live' | 'view-lost';
 export type RemotePhase = 'unregistered' | 'registering' | 'registered' | 'failed';
@@ -22,6 +27,7 @@ export interface QueryLifecycle {
   readonly phase: QueryPhase;
   readonly remote: RemotePhase;
   readonly fetchDepth: number;
+  readonly backgroundDepth: number;
   readonly notified: boolean;
 }
 
@@ -33,8 +39,8 @@ export type LifecycleEvent =
   | { type: 'remote-registered' }
   | { type: 'remote-failed' }
   | { type: 'remote-dropped' }
-  | { type: 'fetch-begin' }
-  | { type: 'fetch-end' }
+  | { type: 'fetch-begin'; background?: boolean }
+  | { type: 'fetch-end'; background?: boolean }
   | { type: 'notified' }
   | { type: 'bucket-switch'; resolvedBefore: boolean };
 
@@ -46,7 +52,7 @@ export class LifecycleError extends Error {
 }
 
 export function seedLifecycle(resolvedBefore: boolean): QueryLifecycle {
-  return { phase: resolvedBefore ? 'cached' : 'cold', remote: 'unregistered', fetchDepth: 0, notified: false };
+  return { phase: resolvedBefore ? 'cached' : 'cold', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false };
 }
 
 /** Total on every (lifecycle, event) pair the sagas can produce; throws on the rest. */
@@ -70,9 +76,14 @@ export function transition(l: QueryLifecycle, ev: LifecycleEvent): QueryLifecycl
     case 'remote-dropped':
       return { ...l, remote: 'unregistered', notified: false };
     case 'fetch-begin':
-      return { ...l, fetchDepth: l.fetchDepth + 1 };
-    case 'fetch-end':
-      return l.fetchDepth === 0 ? l : { ...l, fetchDepth: l.fetchDepth - 1 };
+      return { ...l, fetchDepth: l.fetchDepth + 1, backgroundDepth: l.backgroundDepth + (ev.background ? 1 : 0) };
+    case 'fetch-end': {
+      if (l.fetchDepth === 0) return l;
+      const fetchDepth = l.fetchDepth - 1;
+      // Never more background cycles than cycles: an unbalanced end clamps.
+      const backgroundDepth = Math.min(fetchDepth, l.backgroundDepth - (ev.background && l.backgroundDepth > 0 ? 1 : 0));
+      return { ...l, fetchDepth, backgroundDepth };
+    }
     case 'notified':
       return l.notified ? l : { ...l, notified: true };
     case 'bucket-switch':
@@ -84,3 +95,5 @@ export const isAuthoritative = (l: QueryLifecycle): boolean => l.phase !== 'cold
 export const hasServerMembership = (l: QueryLifecycle): boolean =>
   l.phase === 'live' || l.phase === 'view-lost';
 export const deriveStatus = (l: QueryLifecycle): QueryStatus => (l.fetchDepth > 0 ? 'fetching' : 'idle');
+/** A fetch cycle the user is waiting on: rows to download, or a first registration. */
+export const isForegroundFetching = (l: QueryLifecycle): boolean => l.fetchDepth > l.backgroundDepth;

package/src/state/reducers.test.ts

@@ -247,7 +247,7 @@ describe('bucket switch reducers', () => {
       R.outboxReplace([buildOutboxItem()])
     );
     const id = { table: '_00_query', id: 'new' } as any;
-    const s1 = R.rebindQuery('a', { id, lifecycle: { phase: 'cached', remote: 'unregistered', fetchDepth: 0, notified: false }, remoteArray: [['t:2', 1]], localArray: [] })({ ...s0, dirty: new Set() });
+    const s1 = R.rebindQuery('a', { id, lifecycle: { phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false }, remoteArray: [['t:2', 1]], localArray: [] })({ ...s0, dirty: new Set() });
     const en = s1.queries.get('a')!;
     expect(en.def.id).toBe(id);
     expect(en.lifecycle.phase).toBe('cached');

package/src/state/selectors.test.ts

@@ -81,6 +81,14 @@ describe('needed / planFetch / settled', () => {
     const s = buildState([e('a', { lifecycle: { fetchDepth: 2 } }), e('b')]);
     expect(S.fetchingQueryCount(s)).toBe(1);
   });
+  it('fetchingQueryCount leaves out background re-verification', () => {
+    const s = buildState([
+      e('verifying', { lifecycle: { phase: 'cached', fetchDepth: 1, backgroundDepth: 1 } }),
+      e('downloading', { lifecycle: { phase: 'live', fetchDepth: 2, backgroundDepth: 1 } }),
+    ]);
+    expect(S.fetchingQueryCount(s)).toBe(1);
+    expect(S.queryStatus(s, 'verifying')).toBe('fetching');
+  });
 });
 
 describe('registration / eviction / ttl', () => {

package/src/state/selectors.ts

@@ -1,6 +1,6 @@
 import type { PhaseStat, QueryHash, QueryState, QueryStatus, QueryTimings, RecordVersionArray } from '../types';
 import type { ClientState, QueryEntry } from './client-state';
-import { deriveStatus, hasServerMembership, isAuthoritative } from './lifecycle';
+import { deriveStatus, hasServerMembership, isAuthoritative, isForegroundFetching } from './lifecycle';
 import { FETCH_CHUNK } from '../kernel/constants';
 
 /** Pure reads over `ClientState`. Sagas use them through `state.read`. */
@@ -75,8 +75,14 @@ export const hasAckedWrites = (s: ClientState): boolean => s.outbox.some((i) =>
 export const pendingMutationCount = (s: ClientState): number =>
   s.outbox.filter((i) => i.status === 'pending').length;
 
+/**
+ * Queries with traffic the user is waiting on. A re-registration of a query
+ * that already shows rows (every mounted query after a reload) is left out:
+ * it only confirms what the cache painted, and any newer body it finds is
+ * fetched by `fetchRows`, which counts.
+ */
 export const fetchingQueryCount = (s: ClientState): number =>
-  [...s.queries.values()].filter((e) => e.lifecycle.fetchDepth > 0).length;
+  [...s.queries.values()].filter((e) => isForegroundFetching(e.lifecycle)).length;
 
 /** Membership entries whose body is missing or older locally. */
 export function needed(s: ClientState, hash: QueryHash): RecordVersionArray {