@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.320

package/dist/worker-edges.js

@@ -0,0 +1,439 @@
+import { DateTime, Duration, RecordId } from "surrealdb";
+import { RecordId as RecordId$1, baseFieldOfParam, cyrb53 } from "@spooky-sync/query-builder";
+
+//#region src/query/hash.ts
+/** Session-salted: two tabs of one user must not share a remote view. */
+const queryHashInput = (input, sessionId) => JSON.stringify({
+	surql: input.surql,
+	params: input.params,
+	sessionId
+});
+/** Session-independent: survives reload and bucket switch. */
+const viewKeyInput = (input) => JSON.stringify({
+	surql: input.surql,
+	params: input.params
+});
+
+//#endregion
+//#region src/utils/sha256.ts
+/**
+* Lowercase hex SHA-256 of a UTF-8 string, through WebCrypto.
+*
+* Pure and dependency free so it can live in `@spooky-sync/core/pure` and run
+* in a service worker, a dedicated worker or Node (`globalThis.crypto` is
+* there on Node 19+). Query keys are `sha256Hex(JSON.stringify(..))`, see
+* `query/hash.ts`.
+*/
+async function sha256Hex(input) {
+	const bytes = new TextEncoder().encode(input);
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+//#endregion
+//#region src/utils/surql.ts
+const surql = {
+	seal(query, options) {
+		if (typeof query === "string") return `${query};`;
+		const txQuery = query;
+		const idx = options?.resultIndex ?? txQuery.statementCount - 1;
+		return {
+			sql: `${txQuery.sql};`,
+			extract(results) {
+				return results[idx + 1];
+			}
+		};
+	},
+	tx(queries) {
+		return {
+			__brand: "TxQuery",
+			sql: `BEGIN TRANSACTION;\n${queries.join(";")};\nCOMMIT TRANSACTION`,
+			statementCount: queries.length
+		};
+	},
+	selectById(idVar, returnValues) {
+		return `SELECT ${returnValues.join(",")} FROM ONLY $${idVar}`;
+	},
+	selectByFieldsAnd(table, whereVar, returnValues) {
+		return `SELECT ${returnValues.map((rv) => typeof rv === "string" ? rv : `${rv.field} as ${rv.alias}`).join(",")} FROM ${table} WHERE ${whereVar.map((wv) => typeof wv === "string" ? `${wv} = $${wv}` : `${wv.field} = $${wv.variable}`).join(" AND ")}`;
+	},
+	create(idVar, dataVar) {
+		return `CREATE ONLY $${idVar} CONTENT $${dataVar}`;
+	},
+	createSet(idVar, keyDataVars) {
+		return `CREATE ONLY $${idVar} SET ${keyDataVars.map((keyDataVar) => typeof keyDataVar === "string" ? `${keyDataVar} = $${keyDataVar}` : "statement" in keyDataVar ? keyDataVar.statement : `${keyDataVar.key} = $${keyDataVar.variable}`).join(", ")}`;
+	},
+	upsert(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
+	},
+	upsertMerge(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} MERGE $${dataVar}`;
+	},
+	updateMerge(idVar, dataVar) {
+		return `UPDATE ONLY $${idVar} MERGE $${dataVar}`;
+	},
+	updateSet(idVar, keyDataVar) {
+		return `UPDATE $${idVar} SET ${keyDataVar.map((kdv) => typeof kdv === "string" ? `${kdv} = $${kdv}` : "statement" in kdv ? kdv.statement : `${kdv.key} = $${kdv.variable}`).join(", ")}`;
+	},
+	delete(idVar) {
+		return `DELETE $${idVar}`;
+	},
+	let(name, query) {
+		return `LET $${name} = (${query})`;
+	},
+	createMutation(t, mutationIdVar, recordIdVar, dataVar, beforeRecordVar) {
+		switch (t) {
+			case "create": return dataVar ? `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}, data = $${dataVar}` : `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
+			case "update": {
+				let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
+				if (beforeRecordVar) stmt += `, beforeRecord = $${beforeRecordVar}`;
+				return stmt;
+			}
+			case "delete": return `CREATE ONLY $${mutationIdVar} SET mutationType = 'delete', recordId = $${recordIdVar}`;
+		}
+	},
+	returnObject(entries) {
+		return `RETURN {${entries.map(({ key, variable }) => `${key}: $${variable}`).join(",")}}`;
+	}
+};
+
+//#endregion
+//#region src/query/sql.ts
+/** Every SurrealQL statement the query side sends, as pure builders. */
+const VIEW_TABLE = "_00_view";
+const LEGACY_VIEW_TABLE = "_00_window";
+const viewRecordId = (viewKey) => new RecordId(VIEW_TABLE, viewKey);
+/**
+* The durable `_00_view` row: the confirmed membership plus the subquery
+* children, which the GC must keep and a cold scan may paint as much as the
+* members.
+*/
+const viewRow = (ids, children, confirmed, now) => ({
+	ids,
+	children,
+	confirmed,
+	updatedAt: now
+});
+/** Every `_00_view` row: the durable view index and the GC read it. */
+const readViewRows = () => `SELECT * FROM ${VIEW_TABLE}`;
+/** Copy every legacy `_00_window` row into `_00_view` once. */
+const readLegacyViewRows = () => `SELECT * FROM ${LEGACY_VIEW_TABLE}`;
+const countViewRows = () => `SELECT count() FROM ${VIEW_TABLE} GROUP ALL`;
+const listRefSelect = (table) => `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NONE`;
+const subqueryListRefSelect = (table) => `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NOT NONE`;
+const queryRowCountSelect = () => "SELECT VALUE { rowCount: rowCount, state: state } FROM ONLY $in";
+const listRefBatchSelect = (table) => `SELECT in, out, version, parent FROM ${table} WHERE in IN $ins`;
+const queryRowCountBatchSelect = () => "SELECT VALUE { id: id, rowCount: rowCount, state: state } FROM $ins";
+/** The single-query read: edges, meta, subquery children in one request. */
+const singleSnapshotSelect = (table) => `${listRefSelect(table)};\n${queryRowCountSelect()};\n${subqueryListRefSelect(table)}`;
+/** The many-query read: all edges + all metas in one request. */
+const batchSnapshotSelect = (table) => `${listRefBatchSelect(table)};\n${queryRowCountBatchSelect()}`;
+/** Register + read back edges/meta/children in ONE request. */
+const registerSelect = (table) => `fn::query::register($config);\n${singleSnapshotSelect(table)}`;
+const registerVars = (payload) => ({
+	config: payload,
+	in: payload.id
+});
+/** One heartbeat statement per view id; result index i answers id i. */
+function heartbeatBatch(ids) {
+	const vars = {};
+	return {
+		sql: ids.map((id, i) => {
+			vars[`id${i}`] = id;
+			return `fn::query::heartbeat($id${i})`;
+		}).join(";\n"),
+		vars
+	};
+}
+/** 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) {
+	const vars = {};
+	const stmts = records.map((r, i) => {
+		vars[`id${i}`] = r.id;
+		vars[`content${i}`] = r.content;
+		return surql.upsertMerge(`id${i}`, `content${i}`);
+	});
+	return {
+		query: surql.seal(surql.tx(stmts)),
+		vars
+	};
+}
+
+//#endregion
+//#region src/modules/ref-tables.ts
+/**
+* Sentinel user id for unauthenticated clients when anonymous live queries are
+* enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+* so it can never collide with a real user id (those arrive as `user:<id>`);
+* both sides resolve it to the shared `_00_list_ref_anon` table.
+*/
+const ANON_USER_ID = "anon";
+/**
+* Default ref-storage mode for this client build. Mirrors the SSP's
+* default (`RefMode::Dedicated`) so cross-session sync works out of the
+* box.
+*/
+const DEFAULT_REF_MODE = "dedicated";
+/**
+* Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+* goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+* the id is missing the `user:` prefix or contains characters that
+* aren't valid in a SurrealDB table identifier — the server-side
+* `ssp_protocol::sanitize_user_id` uses the same predicate.
+*
+* Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+* objects (which only stringify cleanly via `.toString()`), since
+* `AuthService` passes the record-id object as-is to its subscribers.
+*/
+function sanitizeUserId(userId) {
+	if (userId === null || userId === void 0) return null;
+	const asString = typeof userId === "string" ? userId : typeof userId.toString === "function" ? userId.toString() : null;
+	if (!asString) return null;
+	const raw = asString.startsWith("user:") ? asString.slice(5) : asString;
+	if (raw.length === 0) return null;
+	if (!/^[A-Za-z0-9_]+$/.test(raw)) return null;
+	return raw;
+}
+/**
+* Resolve the LOCAL storage bucket id for a user. Every user gets their own
+* IndexedDB-backed local store (`indxdb://sp00ky-<bucketId>`) so cached rows,
+* query state, and the mutation outbox never leak across accounts on a shared
+* device. Signed-out sessions share the `anon` bucket.
+*
+* An id that fails sanitization still gets a DETERMINISTIC per-user bucket
+* (cyrb53 hex of the raw id) — falling back to `anon` here would put an
+* authenticated user in the shared bucket and recreate the cross-user leak.
+*/
+function bucketIdForUser(userId) {
+	if (userId === null || userId === void 0 || userId === ANON_USER_ID) return ANON_USER_ID;
+	const uid = sanitizeUserId(userId);
+	if (uid) return uid;
+	return `u${cyrb53(String(userId)).toString(16)}`;
+}
+/**
+* Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+* back to the global `_00_list_ref` when sanitization fails or in
+* single mode.
+*/
+function listRefTableFor(mode, userId) {
+	if (userId === ANON_USER_ID) return "_00_list_ref_anon";
+	if (mode === "single") return "_00_list_ref";
+	const uid = sanitizeUserId(userId);
+	return uid ? `_00_list_ref_user_${uid}` : "_00_list_ref";
+}
+
+//#endregion
+//#region src/utils/parser.ts
+/**
+* Parse a QUERY's params. Unlike a record's fields, a param name is not always a
+* column: an `_or` branch binds under a synthetic `white__or0` (see
+* `orParamName` in @spooky-sync/query-builder), and the surql that references it
+* is already written. So resolve the column through the synthetic name, and keep
+* a param we cannot type rather than dropping it.
+*
+* Dropping was the bug: `parseParams` kept only column-named params, so every
+* `_or` query registered with `$or0`/`$or1` unbound and matched no rows at all,
+* silently (rowCount 0, errorCount 0).
+*/
+function parseQueryParams(tableSchema, params) {
+	const parsedParams = {};
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0) continue;
+		const column = tableSchema[key] ?? tableSchema[baseFieldOfParam(key)];
+		parsedParams[key] = column ? parseValue(key, column, value) : value;
+	}
+	return parsedParams;
+}
+function parseValue(name, column, value) {
+	if (column.recordId) {
+		if (value instanceof RecordId$1) return value;
+		if (typeof value === "string") return parseRecordIdString(value);
+		throw new Error(`Invalid value for ${name}: ${value}`);
+	}
+	if (column.dateTime) {
+		if (value instanceof Date) return value;
+		if (value instanceof DateTime) return value.toDate();
+		if (typeof value === "number" || typeof value === "string") return new Date(value);
+		throw new Error(`Invalid value for ${name}: ${value}`);
+	}
+	return value;
+}
+
+//#endregion
+//#region src/utils/index.ts
+const encodeRecordId = (recordId) => {
+	return `${recordId.table.name}:${recordId.id}`;
+};
+const parseRecordIdString = (id) => {
+	const [table, ...idParts] = id.split(":");
+	return new RecordId(table, idParts.join(":"));
+};
+/**
+* Read the millisecond count off a surrealdb `Duration`. Different `surrealdb`
+* releases expose it under `milliseconds` (current) or the older private
+* `_milliseconds` field, so read whichever is set; returns 0 when neither is.
+*/
+function durationMillis(duration) {
+	const d = duration;
+	return Number(d.milliseconds || d._milliseconds || 0);
+}
+/**
+* Parse duration string or Duration object to milliseconds
+*/
+function parseDuration(duration) {
+	if (duration instanceof Duration) {
+		const ms = durationMillis(duration);
+		if (ms) return ms;
+		const str = duration.toString();
+		if (str !== "[object Object]") return parseDuration(str);
+		return 6e5;
+	}
+	if (typeof duration === "bigint") return Number(duration);
+	if (typeof duration !== "string") return 6e5;
+	const match = duration.match(/^(\d+)([smh])$/);
+	if (!match) return 6e5;
+	const val = Number.parseInt(match[1], 10);
+	switch (match[2]) {
+		case "s": return val * 1e3;
+		case "h": return val * 36e5;
+		default: return val * 6e4;
+	}
+}
+/**
+* Reject after `timeoutMs` if `promise` hasn't settled.
+*
+* Exists because a WebSocket RPC has no deadline of its own: the SurrealDB SDK
+* parks each call in a pending map and only rejects it when the socket reports
+* a close. On a half-open socket (peer gone, no `close` event, `readyState`
+* still OPEN) the call never settles at all, which wedges anything serialized
+* behind it.
+*
+* `message` MUST contain "timed out" so `classifySyncError` treats the
+* rejection as `network` — that's what makes the sync queues retry the
+* operation instead of rolling the mutation back as an application error.
+*
+* Non-positive `timeoutMs` returns `promise` unchanged. The underlying promise
+* is NOT cancelled (nothing can cancel an in-flight RPC); its eventual
+* settlement is absorbed, so attach no expectations to it after a timeout.
+*/
+function withTimeout(promise, timeoutMs, message) {
+	if (!(timeoutMs > 0)) return promise;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(typeof message === "function" ? message() : new Error(message)), timeoutMs);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+
+//#endregion
+//#region src/query/membership.ts
+function metaFromRow(row) {
+	if (!row || typeof row !== "object") return {
+		present: false,
+		rowCount: null,
+		state: null
+	};
+	const state = row.state === "materializing" || row.state === "ready" ? row.state : null;
+	return {
+		present: true,
+		rowCount: typeof row.rowCount === "number" ? row.rowCount : null,
+		state
+	};
+}
+/** Collapse duplicate `(id, version)` pairs to one per id, keeping the highest version. */
+function dedupeRecordVersions(pairs) {
+	if (pairs.length < 2) return pairs;
+	const best = /* @__PURE__ */ new Map();
+	for (const [id, version] of pairs) {
+		const prev = best.get(id);
+		if (prev === void 0 || version > prev) best.set(id, version);
+	}
+	if (best.size === pairs.length) return pairs;
+	return Array.from(best.entries());
+}
+/**
+* A statement that did not answer (an ERR, or no result at all). Kept apart
+* from a `null` result, which is the server saying "no such row": reading a
+* failed statement as a missing row turned every timeout under load into a
+* lost view and re-registered it, over and over (whitepawn, 2026-09-16).
+*/
+const FAILED = Symbol("statement failed");
+const toPairs = (rows) => dedupeRecordVersions(Array.isArray(rows) ? rows.map((r) => [encodeRecordId(r.out), r.version]) : []);
+/**
+* Fold the single-query statement batch (edges, meta, children) into a
+* snapshot. `null` when any of the three did not answer: half an answer is
+* not one, and a missing meta would read as a lost view.
+*/
+function snapshotFromSingle(items, metaRow, children) {
+	if (!Array.isArray(items) || metaRow === FAILED || children === FAILED) return null;
+	return {
+		primary: toPairs(items),
+		subquery: toPairs(children),
+		meta: metaFromRow(metaRow)
+	};
+}
+
+//#endregion
+//#region src/utils/edges.ts
+/**
+* Reading `_00_list_ref` edges as a LIVE notification delivers them. Pure, so
+* both the full client and the wasm-free live feed (`@spooky-sync/core/live`)
+* decode the same wire shape the same way.
+*/
+/** The hash a `_00_list_ref` edge belongs to: the id part of its `in` (`_00_query:<hash>`). */
+function hashOfEdge(value) {
+	const inId = value?.in;
+	if (!inId) return null;
+	const str = inId instanceof RecordId ? String(inId.id) : String(inId).replace(/^_00_query:/, "");
+	return str.length > 0 ? str : null;
+}
+/**
+* The row an edge notification carries, when the subscription joined it on.
+*
+* Without `FETCH out` the edge's `out` is a record id and there is nothing to
+* land, so this returns null and the caller falls back to fetching the body.
+* It also returns null for a row the session may not read (the join yields
+* `out: null`) and for an edge whose target has been deleted.
+*/
+function rowOfEdge(value) {
+	const edge = value;
+	const out = edge?.out;
+	if (!out || typeof out !== "object" || Array.isArray(out) || out instanceof RecordId) return null;
+	const rid = out.id;
+	if (!(rid instanceof RecordId)) return null;
+	const id = encodeRecordId(rid);
+	const version = typeof edge?.version === "number" ? edge.version : null;
+	if (version === null) return null;
+	return {
+		id,
+		version,
+		record: out
+	};
+}
+
+//#endregion
+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/dist/worker-impersonation.js

@@ -0,0 +1,60 @@
+//#region src/modules/auth/impersonation.ts
+/**
+* Admin impersonation, client side.
+*
+* The server does the enforcing (see `impersonation_remote.surql` in the CLI):
+* an admin calls `fn::_00_impersonate::start`, receives a token for the
+* `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
+* the target user. Everything here is state and timers around that:
+*
+* - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
+*   reload in between) can return to it;
+* - the impersonation state is derived from the token's claims, never stored
+*   separately, so it cannot disagree with the session actually in use;
+* - the token is re-signed before it expires, and the session is polled so a
+*   stop or revocation made elsewhere reaches an open WebSocket quickly.
+*/
+/** Access method impersonation tokens are issued for. */
+const IMPERSONATION_ACCESS = "_00_impersonate";
+/**
+* Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+* server still enforces the token on every request; this is only so the client
+* can act on what it already holds before a round trip completes.
+*
+* Returns nulls on any malformed input.
+*/
+function decodeTokenClaims(token) {
+	const none = {
+		access: null,
+		userId: null,
+		exp: null,
+		impersonation: null
+	};
+	try {
+		const payload = token.split(".")[1];
+		if (!payload) return none;
+		let b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+		b64 += "=".repeat((4 - b64.length % 4) % 4);
+		const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("binary");
+		const claims = JSON.parse(json);
+		const ac = claims.AC ?? claims.ac;
+		const id = claims.ID ?? claims.id;
+		const access = typeof ac === "string" ? ac : null;
+		const session = claims.spky_imp;
+		const admin = claims.spky_admin;
+		return {
+			access,
+			userId: typeof id === "string" ? id : null,
+			exp: typeof claims.exp === "number" ? claims.exp : null,
+			impersonation: access === IMPERSONATION_ACCESS && typeof session === "string" && typeof admin === "string" ? {
+				session,
+				admin
+			} : null
+		};
+	} catch {
+		return none;
+	}
+}
+
+//#endregion
+export { decodeTokenClaims as n, IMPERSONATION_ACCESS as t };

package/dist/worker-ref-tables.d.ts

@@ -0,0 +1,46 @@
+//#region src/modules/ref-tables.d.ts
+type RefMode = 'single' | 'dedicated';
+/**
+ * Sentinel user id for unauthenticated clients when anonymous live queries are
+ * enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+ * so it can never collide with a real user id (those arrive as `user:<id>`);
+ * both sides resolve it to the shared `_00_list_ref_anon` table.
+ */
+declare const ANON_USER_ID = "anon";
+/**
+ * Default ref-storage mode for this client build. Mirrors the SSP's
+ * default (`RefMode::Dedicated`) so cross-session sync works out of the
+ * box.
+ */
+declare const DEFAULT_REF_MODE: RefMode;
+/**
+ * Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+ * goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+ * the id is missing the `user:` prefix or contains characters that
+ * aren't valid in a SurrealDB table identifier — the server-side
+ * `ssp_protocol::sanitize_user_id` uses the same predicate.
+ *
+ * Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+ * objects (which only stringify cleanly via `.toString()`), since
+ * `AuthService` passes the record-id object as-is to its subscribers.
+ */
+declare function sanitizeUserId(userId: unknown): string | null;
+/**
+ * Resolve the LOCAL storage bucket id for a user. Every user gets their own
+ * IndexedDB-backed local store (`indxdb://sp00ky-<bucketId>`) so cached rows,
+ * query state, and the mutation outbox never leak across accounts on a shared
+ * device. Signed-out sessions share the `anon` bucket.
+ *
+ * An id that fails sanitization still gets a DETERMINISTIC per-user bucket
+ * (cyrb53 hex of the raw id) — falling back to `anon` here would put an
+ * authenticated user in the shared bucket and recreate the cross-user leak.
+ */
+declare function bucketIdForUser(userId: unknown): string;
+/**
+ * Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+ * back to the global `_00_list_ref` when sanitization fails or in
+ * single mode.
+ */
+declare function listRefTableFor(mode: RefMode, userId: unknown): string;
+//#endregion
+export { listRefTableFor as a, bucketIdForUser as i, DEFAULT_REF_MODE as n, sanitizeUserId as o, RefMode as r, ANON_USER_ID as t };

package/dist/worker-types.d.ts

@@ -0,0 +1,112 @@
+//#region src/push/types.d.ts
+/**
+ * Web Push wire types shared by the page (`db.webPush`), the service worker
+ * bridge (`@spooky-sync/core/sw`) and the live feed. Pure: types plus a few
+ * dependency-free helpers, safe in any context.
+ *
+ * `PushPayload` mirrors `packages/push-core/src/config.rs` (`PushPayload`,
+ * `PayloadKind`, `Op`, `NotificationTemplate`). Keep the two in step.
+ */
+/** Payload format version this build understands. */
+declare const PUSH_PAYLOAD_VERSION = 1;
+type PushPayloadKind = 'rule' | 'message';
+type PushOp = 'create' | 'update' | 'delete';
+type PushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+/** One button on a notification (`NotificationAction` plus a per-action `url`). */
+interface PushNotificationAction {
+  action: string;
+  title: string;
+  icon?: string;
+  /** Opened instead of the notification's `url` when this action is clicked. */
+  url?: string;
+  [key: string]: unknown;
+}
+/**
+ * What a content push shows. Every key other than `title` and `url` is passed
+ * to `showNotification` as is, unknown ones included (`vibrate`, `timestamp`,
+ * whatever a browser adds later).
+ */
+interface PushNotification {
+  title?: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  image?: string;
+  lang?: string;
+  dir?: string;
+  /** Defaults to the push's `topic`. */
+  tag?: string;
+  /** Opened (or focused) on click. */
+  url?: string;
+  requireInteraction?: boolean;
+  renotify?: boolean;
+  silent?: boolean;
+  actions?: PushNotificationAction[];
+  /** Merged into the notification's `data` next to the bridge's own keys. */
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * The JSON every push carries (then RFC 8291 encrypted). `notification`
+ * present: a content push the service worker shows as is. Absent: a
+ * content-free nudge, the app renders from its own data.
+ */
+interface PushPayload {
+  v: number;
+  kind: PushPayloadKind;
+  /** Rule name (`kind: 'rule'`). */
+  rule?: string;
+  /** `_00_push_message` id (`kind: 'message'`). */
+  message?: string;
+  /** The row that fired the rule. */
+  table?: string;
+  id?: string;
+  op?: PushOp;
+  topic?: string;
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  /** Epoch ms when the engine built it. */
+  ts: number;
+}
+/** Page -> service worker: the session to use for live rendering. */
+interface BridgeTokenMessage {
+  type: 'sp00ky:token';
+  token: string;
+  userId: string;
+  /** The SurrealDB endpoint (`wss://host/rpc`), not the push endpoint. */
+  endpoint: string;
+  namespace: string;
+  database: string;
+  /** VAPID public key (base64url) the page subscribed with, for `pushsubscriptionchange`. */
+  publicKey?: string;
+  /** This browser's push endpoint, when subscribed. */
+  pushEndpoint?: string;
+}
+/** Page -> service worker: forget the session and close every notification. */
+interface BridgeSignOutMessage {
+  type: 'sp00ky:signout';
+}
+/** Service worker -> page messages. */
+type WebPushClientMessage = /** A push arrived while this page was visible, so nothing was shown. */
+{
+  type: 'sp00ky:push';
+  payload: PushPayload;
+}
+/** A notification was clicked and the bridge was told to route in-app. */ | {
+  type: 'sp00ky:navigate';
+  url: string;
+  payload?: PushPayload;
+  action?: string;
+}
+/** The browser rotated the push subscription; the page should `sync()`. */ | {
+  type: 'sp00ky:subscriptionchange';
+  endpoint?: string;
+};
+/** `urlBase64ToUint8Array`: the VAPID key as `applicationServerKey` wants it. */
+declare function base64UrlToBytes(value: string): Uint8Array;
+declare function bytesToBase64Url(bytes: ArrayBuffer | Uint8Array): string;
+declare function sameBytes(a: ArrayBuffer | Uint8Array | null | undefined, b: ArrayBuffer | Uint8Array | null | undefined): boolean;
+/** A payload this build can act on (`v` known, `kind` set). */
+declare function isPushPayload(value: unknown): value is PushPayload;
+//#endregion
+export { PushNotificationAction as a, PushPayloadKind as c, base64UrlToBytes as d, bytesToBase64Url as f, PushNotification as i, PushUrgency as l, sameBytes as m, BridgeTokenMessage as n, PushOp as o, isPushPayload as p, PUSH_PAYLOAD_VERSION as r, PushPayload as s, BridgeSignOutMessage as t, WebPushClientMessage as u };