@spooky-sync/core 0.0.1-canary.315 → 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.315";
-const WASM_VERSION = "0.0.1-canary.315";
+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 {
@@ -11445,6 +11531,13 @@ var AuthService = class {
 	/** Target of an impersonation that just ended, until the client purges its
 	*  local bucket (see `consumeEndedImpersonation`). */
 	endedImpersonationTarget = null;
+	/** The way back to the admin in flight. The Stop button, the session poll,
+	*  a refused renewal and a rejected check can all end an impersonation, and
+	*  they share this one: a second stop running beside the first found the
+	*  admin token already taken and signed the admin out. */
+	stopping = null;
+	/** A token renewal in flight, which a stop waits out (see `renewImpersonation`). */
+	renewing = null;
 	impersonationTimers = new ImpersonationTimers({
 		current: () => this.impersonation,
 		renew: () => this.renewImpersonation(),
@@ -11595,9 +11688,18 @@ var AuthService = class {
 	* a full sign-out rather than staying on the target.
 	*/
 	async stopImpersonating(opts = {}) {
+		if (this.stopping) return this.stopping;
+		if (!this.impersonation) return;
+		this.stopping = this.leaveImpersonation(opts).finally(() => {
+			this.stopping = null;
+		});
+		return this.stopping;
+	}
+	async leaveImpersonation(opts) {
+		this.impersonationTimers.clear();
+		await this.renewing?.catch(() => void 0);
 		const info = this.impersonation;
 		if (!info) return;
-		this.impersonationTimers.clear();
 		if (!opts.serverEnded) try {
 			await this.remote.query("RETURN fn::_00_impersonate::stop($session)", { session: info.session });
 		} catch (error) {
@@ -11632,9 +11734,19 @@ var AuthService = class {
 	}
 	/** Re-sign the impersonation token before it expires. */
 	async renewImpersonation() {
-		if (!this.impersonation) return;
+		if (!this.impersonation || this.stopping) return;
+		const renewal = this.applyRenewal();
+		this.renewing = renewal;
+		try {
+			await renewal;
+		} finally {
+			if (this.renewing === renewal) this.renewing = null;
+		}
+	}
+	async applyRenewal() {
 		const [renewed] = await this.remote.query("RETURN fn::_00_impersonate::renew()");
 		if (!renewed?.token) throw new Error("Impersonation renewal returned no token.");
+		if (this.stopping || !this.impersonation) return;
 		this.remote.setAuthToken(renewed.token);
 		await this.remote.getClient().authenticate(renewed.token);
 		this.token = renewed.token;
@@ -11700,6 +11812,7 @@ var AuthService = class {
 	async check(accessToken) {
 		this.isLoading = true;
 		let token;
+		let accepted = false;
 		try {
 			token = accessToken || await this.persistenceClient.get("sp00ky_auth_token") || void 0;
 			if (!token) {
@@ -11711,6 +11824,7 @@ var AuthService = class {
 			}
 			this.remote.setAuthToken(token);
 			await this.remote.getClient().authenticate(token);
+			accepted = true;
 			const result = await this.remote.query("SELECT * FROM ONLY $auth.id");
 			const items = Array.isArray(result) && Array.isArray(result[0]) ? result[0] : result;
 			const user = Array.isArray(items) ? items[0] : items;
@@ -11741,7 +11855,13 @@ var AuthService = class {
 				error,
 				Category: "sp00ky-client::AuthService::check"
 			}, "Auth check unreachable; keeping the cached session and retrying later");
-			else {
+			else if (accepted && token) {
+				this.logger.warn({
+					error,
+					Category: "sp00ky-client::AuthService::check"
+				}, "Auth check accepted the token but could not read the user; keeping the session");
+				await this.keepAcceptedSession(token);
+			} else {
 				this.logger.error({
 					error,
 					stack: error.stack,
@@ -11753,6 +11873,17 @@ var AuthService = class {
 			this.isLoading = false;
 		}
 	}
+	/** Hold a session the server accepted without its user row: the id comes
+	*  from the token, as on a warm boot. A token naming no user is refused. */
+	async keepAcceptedSession(token) {
+		if (this.isAuthenticated && this.token === token && this.currentUser) return;
+		const { userId } = decodeTokenClaims(token);
+		if (!userId) {
+			await this.rejectToken(token);
+			return;
+		}
+		await this.setSession(token, { id: userId });
+	}
 	/**
 	* The server refused `token`. A refused impersonation token (stopped,
 	* expired, or revoked) returns to the admin session instead of signing the
@@ -14542,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();
@@ -14603,7 +14766,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.315",
+			coreVersion: "0.0.1-canary.317",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -14707,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(),
@@ -14753,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;
   /**
@@ -793,6 +816,13 @@ declare class AuthService<S extends SchemaStructure> {
   /** Target of an impersonation that just ended, until the client purges its
    *  local bucket (see `consumeEndedImpersonation`). */
   private endedImpersonationTarget;
+  /** The way back to the admin in flight. The Stop button, the session poll,
+   *  a refused renewal and a rejected check can all end an impersonation, and
+   *  they share this one: a second stop running beside the first found the
+   *  admin token already taken and signed the admin out. */
+  private stopping;
+  /** A token renewal in flight, which a stop waits out (see `renewImpersonation`). */
+  private renewing;
   private impersonationTimers;
   get eventSystem(): AuthEventSystem;
   constructor(schema: S, remote: RemoteDatabaseService, persistenceClient: PersistenceClient, logger: Logger$1);
@@ -839,8 +869,10 @@ declare class AuthService<S extends SchemaStructure> {
   stopImpersonating(opts?: {
     serverEnded?: boolean;
   }): Promise<void>;
+  private leaveImpersonation;
   /** Re-sign the impersonation token before it expires. */
   renewImpersonation(): Promise<void>;
+  private applyRenewal;
   /** Users an admin may pick from. Admin-only on the server. */
   searchImpersonationTargets(search: string): Promise<ImpersonationCandidate[]>;
   /** Open impersonation sessions. Admin-only on the server. */
@@ -872,6 +904,9 @@ declare class AuthService<S extends SchemaStructure> {
    * Check for existing session and validate
    */
   check(accessToken?: string): Promise<void>;
+  /** Hold a session the server accepted without its user row: the id comes
+   *  from the token, as on a warm boot. A token naming no user is refused. */
+  private keepAcceptedSession;
   /**
    * The server refused `token`. A refused impersonation token (stopped,
    * expired, or revoked) returns to the admin session instead of signing the

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.315",
+  "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.315",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.315",
+    "@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);