@spooky-sync/core 0.0.1-canary.107 → 0.0.1-canary.109

package/dist/index.js

@@ -2,6 +2,7 @@ import { DateTime, Duration, RecordId, Surreal, Uuid, applyDiagnostics, createRe
 import { createWasmWorkerEngines } from "@surrealdb/wasm";
 import { QueryBuilder, RecordId as RecordId$1, cyrb53 } from "@spooky-sync/query-builder";
 import pino from "pino";
+import { applyPatch } from "fast-json-patch";
 import init, { Sp00kyProcessor } from "@spooky-sync/ssp-wasm";
 import { LoroDoc } from "loro-crdt";
 
@@ -1046,32 +1047,1034 @@ var LocalMigrator = class {
 };
 
 //#endregion
-//#region src/modules/data/window-query.ts
+//#region src/services/database/cache-engine.ts
+/** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
+*  a guard against a cyclic schema producing unbounded fan-out. */
+var RelationCycleError = class extends Error {
+	constructor(path) {
+		super(`Relation nesting exceeded safe depth; possible cyclic schema: ${path.join(" -> ")}`);
+		this.name = "RelationCycleError";
+	}
+};
+/** Defensive ceiling on relation nesting depth. A finite plan tree never hits
+*  this in practice; it exists so a malformed/cyclic plan fails loudly instead
+*  of running away. */
+const MAX_RELATION_DEPTH = 12;
+
+//#endregion
+//#region src/services/database/relation-resolver.ts
 /**
-* Rewrite a windowed (`LIMIT n START m`, m>0) SELECT so its rows are
-* materialized from an explicit record-id set — the window the SSP already
-* computed — instead of re-running the original query (with its `START m`)
-* against the shared local DB.
+* Resolve the `.related()` tree of a query by **level-ordered, batched
+* fan-out** — the engine-neutral replacement for SurrealQL's nested
+* `(SELECT..) AS alias` projections. One batched fetch per relation per level
+* (never per-row N+1, never a flat join); grouping, per-parent ORDER/LIMIT and
+* attachment happen in JS.
 *
-* Why: `DataModule.processStreamUpdate` materializes a query's rows by
-* re-querying the local in-browser SurrealDB with the original surql. For an
-* offset query that re-applies `START m` against the *shared* local store —
-* which, with sparse windowing, may hold only this window's rows — so it skips
-* them all and returns nothing (the "page 2 returns 0 rows" bug). The SSP's
-* materialized view (`StreamUpdate.localArray`) is exactly this window's row
-* ids, so we select those ids directly and re-apply the original `ORDER BY` for
-* stable display order.
+* Correlation (mirrors `buildSubquery`):
+* - `one`  → parent[`foreignKeyField`] = child.id  → attach `bucket[0] ?? null`
+* - `many` → child[`foreignKeyField`] = parent.id   → attach `bucket`
 *
-* Returns `null` for non-offset queries (`START` absent or 0) — the caller
-* keeps the normal re-query path, so only the broken case changes behavior.
+* Cross-level dependency is handled by ordering: a child's correlation key is a
+* field on its parent, known only once the parent level has resolved, so each
+* level's batch runs after the previous level's rows exist. `parents` is
+* mutated in place — each resolved alias is appended LAST so key order matches
+* SurrealQL's `SELECT *, <sub> AS alias` (base fields, then alias).
+*
+* @throws {RelationCycleError} if nesting exceeds {@link MAX_RELATION_DEPTH}.
+*/
+async function resolveRelations(parents, relations, fetcher, depth = 0, path = []) {
+	if (!relations || relations.length === 0 || parents.length === 0) return;
+	if (depth >= MAX_RELATION_DEPTH) throw new RelationCycleError([...path, relations.map((r) => r.alias).join("|")]);
+	await Promise.all(relations.map((relation) => resolveOne(parents, relation, fetcher, depth, path)));
+}
+async function resolveOne(parents, relation, fetcher, depth, path) {
+	const isOne = relation.cardinality === "one";
+	const matchField = isOne ? "id" : relation.foreignKeyField;
+	const parentKeyOf = (parent) => isOne ? parent[relation.foreignKeyField] : parent["id"];
+	const keySet = /* @__PURE__ */ new Map();
+	for (const parent of parents) {
+		const key = parentKeyOf(parent);
+		if (key == null) continue;
+		const k = stableKey(key);
+		if (!keySet.has(k)) keySet.set(k, key);
+	}
+	const grouped = /* @__PURE__ */ new Map();
+	if (keySet.size > 0) {
+		const children = await fetcher.fetchRelation({
+			table: relation.table,
+			matchField,
+			keys: [...keySet.values()],
+			where: relation.where,
+			orderBy: relation.orderBy,
+			select: relation.select
+		});
+		await resolveRelations(children, relation.relations, fetcher, depth + 1, [...path, relation.alias]);
+		for (const child of children) {
+			const k = stableKey(child[matchField]);
+			const bucket = grouped.get(k);
+			if (bucket) bucket.push(child);
+			else grouped.set(k, [child]);
+		}
+	}
+	for (const parent of parents) {
+		const key = parentKeyOf(parent);
+		let bucket = key == null ? [] : grouped.get(stableKey(key)) ?? [];
+		if (relation.orderBy && relation.orderBy.length > 0) bucket = sortRows(bucket, relation.orderBy);
+		if (relation.limit !== void 0) bucket = bucket.slice(0, relation.limit);
+		parent[relation.alias] = isOne ? bucket[0] ?? null : bucket;
+	}
+}
+/**
+* Stable grouping key for a correlation value. A `RecordId` (duck-typed to
+* avoid a hard surrealdb dependency here) and its `table:id` string form must
+* collapse to the same key so a parent FK stored either way matches the child.
+*/
+function stableKey(value) {
+	if (value == null) return "\0null";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (typeof value === "object") {
+		const rid = value;
+		if (rid.tb !== void 0 && rid.id !== void 0) return `${String(rid.tb)}:${stableKey(rid.id)}`;
+		if (typeof rid.toString === "function") {
+			const s = rid.toString();
+			if (s !== "[object Object]") return s;
+		}
+		return JSON.stringify(value);
+	}
+	return String(value);
+}
+/**
+* Stable, multi-key sort matching SurrealQL `ORDER BY` semantics closely
+* enough for cache display order: ascending null-last, type-aware compare, and
+* a stable tiebreak (original index) so equal rows keep input order.
+*/
+function sortRows(rows, orderBy) {
+	const indexed = rows.map((row, i) => [row, i]);
+	indexed.sort((a, b) => {
+		for (const [field, direction] of orderBy) {
+			const cmp = compareValues(a[0][field], b[0][field]);
+			if (cmp !== 0) return direction === "desc" ? -cmp : cmp;
+		}
+		return a[1] - b[1];
+	});
+	return indexed.map(([row]) => row);
+}
+function compareValues(a, b) {
+	if (a == null && b == null) return 0;
+	if (a == null) return 1;
+	if (b == null) return -1;
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	const as = stableKey(a);
+	const bs = stableKey(b);
+	return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+//#endregion
+//#region src/services/database/plan-render.ts
+function bind(ctx, value) {
+	const name = `__p${ctx.n++}`;
+	ctx.vars[name] = value;
+	return `$${name}`;
+}
+function renderComparisonSurql(c, ctx) {
+	const right = c.paramRef ? `$${c.paramRef}` : bind(ctx, c.value);
+	return c.swap ? `${right} ${c.op} ${c.field}` : `${c.field} ${c.op} ${right}`;
+}
+/** Render a WHERE conjunction (AND of comparisons / OR-groups) to SurrealQL. */
+function renderWhereSurql(nodes, ctx) {
+	return nodes.map((node) => {
+		if ("or" in node) return `(${node.or.map((c) => renderComparisonSurql(c, ctx)).join(" OR ")})`;
+		return renderComparisonSurql(node, ctx);
+	}).join(" AND ");
+}
+function renderOrderBy(orderBy) {
+	return ` ORDER BY ${orderBy.map(([f, d]) => `${f} ${d}`).join(", ")}`;
+}
+/**
+* Render the BASE of a SELECT (no relations) to SurrealQL. `params` supplies
+* pre-existing bound params (e.g. `$__win` for windowing, or `paramRef` values)
+* and is merged into the returned vars.
+*/
+function renderBaseSelectSurql(plan, params = {}) {
+	const ctx = {
+		vars: { ...params },
+		n: 0
+	};
+	let sql = `SELECT ${plan.select && plan.select.length > 0 ? plan.select.join(", ") : "*"} FROM ${plan.table}`;
+	if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSurql(plan.where, ctx)}`;
+	if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderBy(plan.orderBy);
+	if (plan.limit !== void 0) sql += ` LIMIT ${plan.limit}`;
+	if (plan.offset !== void 0) sql += ` START ${plan.offset}`;
+	return {
+		sql: `${sql};`,
+		vars: ctx.vars
+	};
+}
+/**
+* Render a batched relation fetch to SurrealQL:
+* `SELECT <select> FROM <table> WHERE <matchField> IN $__keys [AND <where>] [ORDER BY]`.
+* The resolver re-applies per-parent ORDER/LIMIT after grouping, so LIMIT is
+* intentionally omitted here.
+*/
+function renderRelationFetchSurql(req) {
+	const ctx = {
+		vars: { __keys: req.keys },
+		n: 0
+	};
+	let sql = `SELECT ${req.select && req.select.length > 0 ? ["id", ...req.select].join(", ") : "*"} FROM ${req.table} WHERE ${req.matchField} IN $__keys`;
+	if (req.where && req.where.length > 0) sql += ` AND ${renderWhereSurql(req.where, ctx)}`;
+	if (req.orderBy && req.orderBy.length > 0) sql += renderOrderBy(req.orderBy);
+	return {
+		sql: `${sql};`,
+		vars: ctx.vars
+	};
+}
+
+//#endregion
+//#region src/services/database/surreal-cache-engine.ts
+/**
+* Default local cache backend: the in-browser SurrealDB-WASM store. Implemented
+* as a subclass of {@link LocalDatabaseService} so it remains a 100% drop-in for
+* every existing `this.local.query(...)` / `execute` / `switchStore` / `epoch`
+* call site (zero behavior change), while adding the engine-neutral verb surface
+* (`select`/`selectByIds`/`getById`/CRUD) used by the pluggable path.
+*
+* Relations are resolved with the SAME shared {@link resolveRelations} as the
+* SQLite backend, so the two engines decompose `.related()` identically.
+*/
+var SurrealCacheEngine = class extends LocalDatabaseService {
+	/** SurrealDB needs its SurrealQL schema provisioned locally. */
+	usesSurqlSchema = true;
+	/** {@link LocalCacheEngine} alias for {@link LocalDatabaseService.switchStore}. */
+	switchBucket(bucketId) {
+		return this.switchStore(bucketId);
+	}
+	async fetchRelation(req) {
+		const { sql, vars } = renderRelationFetchSurql(req);
+		const [rows] = await this.query(sql, vars);
+		return rows ?? [];
+	}
+	async select(plan, params = {}) {
+		if (plan.ids) {
+			const result = await this.selectByIds(plan.table, plan.ids, {
+				select: plan.select,
+				orderBy: plan.orderBy
+			});
+			await resolveRelations(result, plan.relations, this);
+			return result;
+		}
+		const { sql, vars } = renderBaseSelectSurql(plan, params);
+		const [rows] = await this.query(sql, vars);
+		const result = rows ?? [];
+		await resolveRelations(result, plan.relations, this);
+		return result;
+	}
+	async selectByIds(table, ids, opts) {
+		if (ids.length === 0) return [];
+		let sql = `SELECT ${opts?.select && opts.select.length > 0 ? ["id", ...opts.select].join(", ") : "*"} FROM $__ids`;
+		if (opts?.orderBy && opts.orderBy.length > 0) sql += ` ORDER BY ${opts.orderBy.map(([f, d]) => `${f} ${d}`).join(", ")}`;
+		const [rows] = await this.query(`${sql};`, { __ids: ids });
+		const result = rows ?? [];
+		if (!opts?.orderBy || opts.orderBy.length === 0) {
+			const pos = new Map(ids.map((id, i) => [stableKey(id), i]));
+			result.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
+		}
+		return result;
+	}
+	async getById(_table, id) {
+		const [row] = await this.query("SELECT * FROM ONLY $__id;", { __id: id });
+		return row ?? null;
+	}
+	async upsert(_table, id, data, mode) {
+		const sql = mode === "merge" ? surql.upsertMerge("__id", "__data") : surql.upsert("__id", "__data");
+		await this.query(surql.seal(sql), {
+			__id: id,
+			__data: data
+		});
+	}
+	async patch(_table, id, patches) {
+		await this.query(surql.seal("UPDATE ONLY $__id PATCH $__patches"), {
+			__id: id,
+			__patches: patches
+		});
+	}
+	async delete(_table, id) {
+		await this.query(surql.seal(surql.delete("__id")), { __id: id });
+	}
+	/**
+	* Serialized (not strictly atomic) transaction: verbs run in order on the
+	* same serialized query queue. The SurrealDB-WASM store already funnels every
+	* `query()` through one queue, so these never interleave with other work;
+	* true multi-statement atomicity is not required by the current call sites
+	* (single-record CRDT / mutation writes).
+	*/
+	async transaction(fn) {
+		return fn({
+			upsert: (t, id, data, mode) => this.upsert(t, id, data, mode),
+			patch: (t, id, patches) => this.patch(t, id, patches),
+			delete: (t, id) => this.delete(t, id)
+		});
+	}
+};
+
+//#endregion
+//#region src/services/database/surql-translate.ts
+const rid = (v) => v;
+/** Table name from a record id value (`table:id` string or RecordId). */
+function tableOf(id) {
+	return stableKey(id).split(":")[0];
+}
+function translateSurql(sql, vars) {
+	const trimmed = sql.trim().replace(/;\s*$/, "");
+	if (/^BEGIN\s+TRANSACTION/i.test(trimmed)) return {
+		transaction: true,
+		ops: splitStatements(trimmed.replace(/^BEGIN\s+TRANSACTION\s*;?/i, "").replace(/;?\s*COMMIT\s+TRANSACTION\s*$/i, "")).map((s) => translateStatement(s, vars))
+	};
+	return {
+		transaction: false,
+		ops: splitStatements(trimmed).map((s) => translateStatement(s, vars))
+	};
+}
+function splitStatements(block) {
+	return block.split(";").map((s) => s.trim()).filter(Boolean);
+}
+function translateStatement(stmt, vars) {
+	const s = stmt.trim();
+	let mLet = /^LET\s+\$(\w+)\s*=\s*\(([\s\S]+)\)$/i.exec(s);
+	if (mLet) return {
+		kind: "let",
+		var: mLet[1],
+		inner: translateStatement(mLet[2].trim(), vars)
+	};
+	let mRet = /^RETURN\s+\{([\s\S]+)\}$/i.exec(s);
+	if (mRet) return {
+		kind: "return",
+		entries: splitTopLevel(mRet[1], ",").map((pair) => {
+			const c = pair.indexOf(":");
+			const key = pair.slice(0, c).trim();
+			const v = pair.slice(c + 1).trim();
+			return {
+				key,
+				var: v.startsWith("$") ? v.slice(1) : v
+			};
+		})
+	};
+	if (/^(DEFINE|REMOVE|USE|INFO|RETURN|CANCEL|COMMIT|BEGIN)\b/i.test(s)) return { kind: "noop" };
+	let m = /^CREATE\s+ONLY\s+\$(\w+)\s+CONTENT\s+\$(\w+)$/i.exec(s) || /^UPSERT\s+ONLY\s+\$(\w+)\s+REPLACE\s+\$(\w+)$/i.exec(s);
+	if (m) return {
+		kind: "upsert",
+		id: rid(vars[m[1]]),
+		data: asRow(vars[m[2]]),
+		mode: "replace"
+	};
+	m = /^UPSERT\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s) || /^UPDATE\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s);
+	if (m) return {
+		kind: "upsert",
+		id: rid(vars[m[1]]),
+		data: asRow(vars[m[2]]),
+		mode: "merge"
+	};
+	m = /^CREATE\s+ONLY\s+\$(\w+)\s+SET\s+(.+)$/i.exec(s);
+	if (m) {
+		const data = {};
+		for (const { path, value } of parseSetClauses(m[2], vars)) setPath(data, path, value);
+		return {
+			kind: "upsert",
+			id: rid(vars[m[1]]),
+			data,
+			mode: "replace"
+		};
+	}
+	m = /^UPDATE\s+\$(\w+)\s+SET\s+(.+?)(\s+RETURN\s+NONE)?$/i.exec(s);
+	if (m) return {
+		kind: "updateSet",
+		id: rid(vars[m[1]]),
+		sets: parseSetClauses(m[2], vars),
+		returnNone: !!m[3]
+	};
+	m = /^DELETE\s+\$(\w+)$/i.exec(s);
+	if (m) return {
+		kind: "delete",
+		id: rid(vars[m[1]])
+	};
+	m = /^DELETE\s+([A-Za-z_]\w*)$/i.exec(s);
+	if (m) return {
+		kind: "deleteAll",
+		table: m[1]
+	};
+	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+ONLY\s+\$(\w+)$/i.exec(s);
+	if (m) {
+		const value = m[1] ? m[2].trim() : void 0;
+		return {
+			kind: "getById",
+			id: rid(vars[m[3]]),
+			select: projFields(m[2], !!m[1]),
+			value
+		};
+	}
+	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+\$(\w+)$/i.exec(s);
+	if (m) {
+		const value = m[1] ? m[2].trim() : void 0;
+		return {
+			kind: "selectByIds",
+			ids: vars[m[3]] ?? [],
+			select: projFields(m[2], !!m[1]),
+			value
+		};
+	}
+	m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?$/i.exec(s);
+	if (m) return {
+		kind: "selectTable",
+		table: m[3],
+		where: m[4] ? parseWhere(m[4], vars) : void 0,
+		orderBy: m[5] ? parseOrderBy(m[5]) : void 0,
+		select: projFields(m[2], !!m[1]),
+		value: m[1] ? m[2].trim() : void 0
+	};
+	throw new Error(`SqliteCacheEngine: unsupported SurrealQL for translation: ${stmt}`);
+}
+function projFields(proj, isValue) {
+	const p = proj.trim();
+	if (isValue) return void 0;
+	if (p === "*") return void 0;
+	return p.split(",").map((f) => f.trim());
+}
+function asRow(v) {
+	return v && typeof v === "object" ? v : {};
+}
+/** Parse `a = $x, b.c = 'lit', _00_rv += 1` into path/op/value triples. */
+function parseSetClauses(clause, vars) {
+	return splitTopLevel(clause, ",").map((part) => {
+		const m = /^(.+?)\s*(\+=|-=|=)\s*([\s\S]+)$/.exec(part.trim());
+		if (!m) throw new Error(`SqliteCacheEngine: cannot parse SET clause: ${part}`);
+		return {
+			path: m[1].trim(),
+			op: m[2],
+			value: literalOrVar(m[3], vars)
+		};
+	});
+}
+function literalOrVar(token, vars) {
+	const t = token.trim();
+	if (t.startsWith("$")) return vars[t.slice(1)];
+	if (/^'.*'$/.test(t) || /^".*"$/.test(t)) return t.slice(1, -1);
+	if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+	if (t === "true") return true;
+	if (t === "false") return false;
+	if (t === "NONE" || t === "NULL" || t === "null") return null;
+	return t;
+}
+function parseWhere(clause, vars) {
+	return splitTopLevel(clause, "AND").map((cond) => {
+		const m = /^(\S+)\s*(=|!=|>=|<=|>|<)\s*(.+)$/.exec(cond.trim());
+		if (!m) throw new Error(`SqliteCacheEngine: cannot parse WHERE condition: ${cond}`);
+		return {
+			field: m[1],
+			op: m[2],
+			value: literalOrVar(m[3], vars)
+		};
+	});
+}
+function parseOrderBy(clause) {
+	return clause.split(",").map((c) => {
+		const [f, dir] = c.trim().split(/\s+/);
+		return [f, (dir ?? "asc").toLowerCase() === "desc" ? "desc" : "asc"];
+	});
+}
+/** Split on a top-level separator, ignoring parens/quotes (bounded inputs). */
+function splitTopLevel(input, sep) {
+	const out = [];
+	let depth = 0;
+	let inStr = null;
+	let cur = "";
+	const isWord = /[A-Za-z]/.test(sep);
+	for (let i = 0; i < input.length; i++) {
+		const ch = input[i];
+		if (inStr) {
+			cur += ch;
+			if (ch === inStr) inStr = null;
+			continue;
+		}
+		if (ch === "'" || ch === "\"") {
+			inStr = ch;
+			cur += ch;
+			continue;
+		}
+		if (ch === "(") depth++;
+		if (ch === ")") depth--;
+		if (isWord ? depth === 0 && input.slice(i, i + sep.length).toUpperCase() === sep && /\s/.test(input[i - 1] ?? " ") : depth === 0 && ch === sep) {
+			out.push(cur.trim());
+			cur = "";
+			i += sep.length - 1;
+			continue;
+		}
+		cur += ch;
+	}
+	if (cur.trim()) out.push(cur.trim());
+	return out;
+}
+/** Read a possibly-dotted path (`a.b.c`) from an object. */
+function getPath(obj, path) {
+	let cur = obj;
+	for (const k of path.split(".")) {
+		if (cur == null || typeof cur !== "object") return void 0;
+		cur = cur[k];
+	}
+	return cur;
+}
+/** Set a possibly-dotted path (`a.b.c`) on an object. */
+function setPath(obj, path, value) {
+	const parts = path.split(".");
+	let cur = obj;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const k = parts[i];
+		if (typeof cur[k] !== "object" || cur[k] === null) cur[k] = {};
+		cur = cur[k];
+	}
+	cur[parts[parts.length - 1]] = value;
+}
+
+//#endregion
+//#region src/services/database/sqlite-cache-engine.ts
+/**
+* Local cache backend on official SQLite-WASM in a dedicated Worker (see
+* `sqlite-worker.ts`), with OPFS SAHPool persistence. Storage model: one table
+* per schema table, `id TEXT PRIMARY KEY, data TEXT` where `data` is the row as
+* JSON. Filtering/ordering use `json_extract`. Relations are decomposed by the
+* shared {@link resolveRelations} — identical to the SurrealDB backend.
+*
+* Value normalization (JSON round-trip):
+* - `Uint8Array`/bytes → `{ "__u8": <base64> }` (CRDT snapshots survive).
+* - Record links / ids → their `table:id` string form (so `json_extract`
+*   comparisons and `IN` matching are consistent). NOTE: link fields therefore
+*   read back as strings, not `RecordId` instances — the one shape difference
+*   from the SurrealDB backend, to be closed with schema-driven revival + an
+*   oracle E2E in the browser.
+*/
+var SqliteCacheEngine = class {
+	worker = null;
+	seq = 0;
+	pending = /* @__PURE__ */ new Map();
+	storeEpoch = 0;
+	knownTables = /* @__PURE__ */ new Set();
+	useOpfs;
+	events = createDatabaseEventSystem();
+	bucketId = "anon";
+	/** Schemaless — tables are created lazily on first write; no migrator. */
+	usesSurqlSchema = false;
+	constructor(config, logger, opts = {}) {
+		this.config = config;
+		this.logger = logger;
+		this.useOpfs = opts.useOpfs ?? true;
+	}
+	get epoch() {
+		return this.storeEpoch;
+	}
+	get currentBucketId() {
+		return this.bucketId;
+	}
+	getConfig() {
+		return this.config;
+	}
+	getEvents() {
+		return this.events;
+	}
+	getClient() {
+		throw new Error("SqliteCacheEngine has no SurrealDB client (getClient is unavailable).");
+	}
+	/** LocalStore alias; SQLite has no in-flight gate, so this maps to a rebuild. */
+	switchStore(bucketId) {
+		return this.switchBucket(bucketId);
+	}
+	/** SQLite has no switch gate window; the epoch bump alone fences stale writes. */
+	beginSwitch() {
+		return () => {};
+	}
+	spawnWorker() {
+		const worker = new Worker(new URL("./sqlite-worker.js", import.meta.url), { type: "module" });
+		worker.onmessage = (ev) => {
+			const { id, ok, error, ...rest } = ev.data ?? {};
+			const p = this.pending.get(id);
+			if (!p) return;
+			this.pending.delete(id);
+			if (ok) p.resolve(rest);
+			else p.reject(new Error(error));
+		};
+		const failAll = (msg) => {
+			const err = /* @__PURE__ */ new Error(`SQLite worker crashed: ${msg}`);
+			this.logger.error({
+				err,
+				Category: "sp00ky-client::SqliteCacheEngine::worker"
+			}, "Worker error");
+			for (const [, p] of this.pending) p.reject(err);
+			this.pending.clear();
+		};
+		worker.onerror = (e) => failAll(e.message || "onerror");
+		worker.onmessageerror = () => failAll("messageerror");
+		return worker;
+	}
+	/** Serializes every worker op so reads/writes never overlap at the VFS layer
+	*  (overlapping ops trip SQLITE_BUSY). Mirrors the SurrealDB engine's
+	*  single-flight query queue. */
+	opQueue = Promise.resolve();
+	call(type, payload) {
+		const run = () => this.rawCall(type, payload);
+		const result = this.opQueue.then(run, run);
+		this.opQueue = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	rawCall(type, payload) {
+		if (!this.worker) throw new Error("SqliteCacheEngine: not connected");
+		const id = ++this.seq;
+		const s = getStats();
+		s.roundTrips++;
+		s.byType[type] = (s.byType[type] ?? 0) + 1;
+		if (type === "batch" && Array.isArray(payload)) {
+			s.batchStatements += payload.length;
+			s.maxBatch = Math.max(s.maxBatch, payload.length);
+		}
+		s.inFlight++;
+		s.maxInFlight = Math.max(s.maxInFlight, s.inFlight);
+		const done = () => {
+			s.inFlight--;
+		};
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve: (v) => {
+					done();
+					resolve(v);
+				},
+				reject: (e) => {
+					done();
+					reject(e);
+				}
+			});
+			this.worker.postMessage({
+				id,
+				type,
+				payload
+			});
+		});
+	}
+	async connect(bucketId) {
+		this.worker = this.spawnWorker();
+		const { persisted } = await this.call("open", {
+			dbName: bucketId,
+			useOpfs: this.useOpfs
+		});
+		this.knownTables.clear();
+		this.bucketId = bucketId;
+		this.logger.info({
+			bucketId,
+			persisted,
+			Category: "sp00ky-client::SqliteCacheEngine::connect"
+		}, persisted ? "SQLite OPFS store opened" : "SQLite in-memory store opened (no OPFS)");
+	}
+	async switchBucket(bucketId) {
+		this.storeEpoch++;
+		if (this.worker) {
+			try {
+				await this.call("close");
+			} catch {}
+			this.worker.terminate();
+			this.worker = null;
+		}
+		await this.connect(bucketId);
+	}
+	async close() {
+		if (!this.worker) return;
+		try {
+			await this.call("close");
+		} catch {}
+		this.worker.terminate();
+		this.worker = null;
+	}
+	async ensureTable(table) {
+		if (this.knownTables.has(table)) return;
+		await this.call("run", { sql: `CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+		this.knownTables.add(table);
+	}
+	async execRows(sql, bind) {
+		const { rows } = await this.call("exec", {
+			sql,
+			bind
+		});
+		return (rows ?? []).map((r) => reviveRow(r.data));
+	}
+	async select(plan, params = {}) {
+		if (plan.ids) {
+			const result = await this.selectByIds(plan.table, plan.ids, {
+				select: plan.select,
+				orderBy: plan.orderBy
+			});
+			await resolveRelations(result, plan.relations, this);
+			return result;
+		}
+		await this.ensureTable(plan.table);
+		const bind = [];
+		let sql = `SELECT data FROM "${plan.table}"`;
+		if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
+		if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
+		if (plan.limit !== void 0) sql += ` LIMIT ${Number(plan.limit)}`;
+		if (plan.offset !== void 0) sql += ` OFFSET ${Number(plan.offset)}`;
+		const rows = await this.execRows(sql, bind);
+		const projected = plan.select ? rows.map((r) => project(r, plan.select)) : rows;
+		await resolveRelations(projected, plan.relations, this);
+		return projected;
+	}
+	async fetchRelation(req) {
+		await this.ensureTable(req.table);
+		const keys = req.keys.map(stableKey);
+		const placeholders = keys.map(() => "?").join(", ");
+		const bind = [...keys];
+		const lhs = req.matchField === "id" ? "id" : `json_extract(data, '$.${req.matchField}')`;
+		let sql = `SELECT data FROM "${req.table}" WHERE ${lhs} IN (${placeholders})`;
+		if (req.where && req.where.length > 0) sql += ` AND ${renderWhereSql(req.where, bind, {})}`;
+		if (req.orderBy && req.orderBy.length > 0) sql += renderOrderSql(req.orderBy);
+		const rows = await this.execRows(sql, bind);
+		return req.select ? rows.map((r) => project(r, req.select)) : rows;
+	}
+	async selectByIds(table, ids, opts) {
+		if (ids.length === 0) return [];
+		await this.ensureTable(table);
+		const keys = ids.map(stableKey);
+		let sql = `SELECT data FROM "${table}" WHERE id IN (${keys.map(() => "?").join(", ")})`;
+		if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
+		let rows = await this.execRows(sql, keys);
+		if (!opts?.orderBy || opts.orderBy.length === 0) {
+			const pos = new Map(keys.map((k, i) => [k, i]));
+			rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
+		}
+		return opts?.select ? rows.map((r) => project(r, opts.select)) : rows;
+	}
+	async getById(table, id) {
+		await this.ensureTable(table);
+		return (await this.execRows(`SELECT data FROM "${table}" WHERE id = ?`, [stableKey(id)]))[0] ?? null;
+	}
+	async upsert(table, id, data, mode) {
+		await this.ensureTable(table);
+		const key = stableKey(id);
+		if (mode === "merge") {
+			const full = serializeRow({
+				...data,
+				id: key
+			});
+			await this.call("run", {
+				sql: `INSERT INTO "${table}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = json_patch(data, ?)`,
+				bind: [
+					key,
+					full,
+					full
+				]
+			});
+			return;
+		}
+		await this.call("run", {
+			sql: `INSERT INTO "${table}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`,
+			bind: [key, serializeRow({
+				...data,
+				id: key
+			})]
+		});
+	}
+	async patch(table, id, patches) {
+		const next = applyPatch(await this.getById(table, id) ?? { id: stableKey(id) }, patches).newDocument;
+		await this.upsert(table, id, next, "replace");
+	}
+	async delete(table, id) {
+		await this.ensureTable(table);
+		await this.call("run", {
+			sql: `DELETE FROM "${table}" WHERE id = ?`,
+			bind: [stableKey(id)]
+		});
+	}
+	/**
+	* Execute a raw SurrealQL statement by translating the client's bounded
+	* vocabulary to verbs (see `surql-translate.ts`). Returns results shaped like
+	* SurrealDB's `.query()` (one element per statement; a tx prepends a `null`
+	* begin-result so `surql.seal` extraction lines up). Epoch-fences writes.
+	*/
+	async query(sql, vars = {}, opts) {
+		if (opts?.epoch !== void 0 && opts.epoch !== this.storeEpoch) throw new StaleEpochError();
+		const start = performance.now();
+		try {
+			const { transaction, ops } = translateSurql(sql, vars);
+			let shaped;
+			if (transaction && ops.every((o) => o.kind === "upsert" || o.kind === "delete" || o.kind === "deleteAll" || o.kind === "noop")) {
+				await this.runWriteBatch(ops);
+				shaped = [null, ...ops.map(() => [])];
+			} else {
+				const results = [];
+				const scope = {};
+				for (const op of ops) results.push(await this.execOp(op, scope, vars));
+				shaped = transaction ? [null, ...results] : results;
+			}
+			this.events.emit(DatabaseEventTypes.LocalQuery, {
+				query: sql,
+				vars,
+				duration: performance.now() - start,
+				success: true,
+				timestamp: Date.now()
+			});
+			return shaped;
+		} catch (err) {
+			this.events.emit(DatabaseEventTypes.LocalQuery, {
+				query: sql,
+				vars,
+				duration: performance.now() - start,
+				success: false,
+				error: err instanceof Error ? err.message : String(err),
+				timestamp: Date.now()
+			});
+			throw err;
+		}
+	}
+	async execute(query, vars, opts) {
+		const raw = await this.query(query.sql, vars, opts);
+		return query.extract(raw);
+	}
+	queryUngated(sql, vars) {
+		return this.query(sql, vars);
+	}
+	async execOp(op, scope, vars) {
+		switch (op.kind) {
+			case "getById": {
+				const row = await this.getById(tableOf(op.id), op.id);
+				if (op.value) return row ? row[op.value] ?? null : null;
+				return row ? op.select ? project(row, op.select) : row : null;
+			}
+			case "selectByIds": {
+				if (op.ids.length === 0) return [];
+				let rows = await this.selectByIds(tableOf(op.ids[0]), op.ids, {
+					select: op.select,
+					orderBy: op.orderBy
+				});
+				if (op.value) return rows.map((r) => r[op.value]);
+				return rows;
+			}
+			case "selectTable": {
+				const rows = await this.rawSelectTable(op.table, op.where, op.orderBy);
+				if (op.value) return rows.map((r) => r[op.value]);
+				return op.select ? rows.map((r) => project(r, op.select)) : rows;
+			}
+			case "upsert":
+				await this.upsert(tableOf(op.id), op.id, op.data, op.mode);
+				return {
+					...op.data,
+					id: stableKey(op.id)
+				};
+			case "updateSet": {
+				const existing = await this.getById(tableOf(op.id), op.id) ?? { id: stableKey(op.id) };
+				for (const { path, op: setOp, value } of op.sets) if (setOp === "+=" || setOp === "-=") {
+					const cur = Number(getPath(existing, path) ?? 0);
+					const delta = Number(value ?? 0);
+					setPath(existing, path, setOp === "+=" ? cur + delta : cur - delta);
+				} else setPath(existing, path, value);
+				await this.upsert(tableOf(op.id), op.id, existing, "replace");
+				return op.returnNone ? null : existing;
+			}
+			case "delete":
+				await this.delete(tableOf(op.id), op.id);
+				return [];
+			case "deleteAll":
+				await this.ensureTable(op.table);
+				await this.call("run", { sql: `DELETE FROM "${op.table}"` });
+				return [];
+			case "let": {
+				let result = await this.execOp(op.inner, scope, vars);
+				if (op.inner.kind === "upsert") result = await this.getById(tableOf(op.inner.id), op.inner.id) ?? result;
+				scope[op.var] = result;
+				return result;
+			}
+			case "return": {
+				const obj = {};
+				for (const { key, var: v } of op.entries) obj[key] = v in scope ? scope[v] : vars[v];
+				return obj;
+			}
+			case "noop": return null;
+		}
+	}
+	/**
+	* Compile a pure-write op list to ONE worker `batch` (single SQLite
+	* transaction). Ensures each touched table exists, then one statement per op.
+	* Merges happen in-SQL via json_patch — no read-back round-trips.
+	*/
+	async runWriteBatch(ops) {
+		const stmts = [];
+		const tables = /* @__PURE__ */ new Set();
+		const ensure = (t) => {
+			if (!tables.has(t)) {
+				tables.add(t);
+				this.knownTables.add(t);
+				stmts.push({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+			}
+		};
+		for (const op of ops) if (op.kind === "upsert") {
+			const t = tableOf(op.id);
+			const key = stableKey(op.id);
+			ensure(t);
+			if (op.mode === "merge") {
+				const full = serializeRow({
+					...op.data,
+					id: key
+				});
+				stmts.push({
+					sql: `INSERT INTO "${t}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = json_patch(data, ?)`,
+					bind: [
+						key,
+						full,
+						full
+					]
+				});
+			} else stmts.push({
+				sql: `INSERT INTO "${t}"(id, data) VALUES(?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data`,
+				bind: [key, serializeRow({
+					...op.data,
+					id: key
+				})]
+			});
+		} else if (op.kind === "delete") {
+			const t = tableOf(op.id);
+			ensure(t);
+			stmts.push({
+				sql: `DELETE FROM "${t}" WHERE id = ?`,
+				bind: [stableKey(op.id)]
+			});
+		} else if (op.kind === "deleteAll") {
+			ensure(op.table);
+			stmts.push({ sql: `DELETE FROM "${op.table}"` });
+		}
+		if (stmts.length > 0) await this.call("batch", stmts);
+	}
+	async rawSelectTable(table, where, orderBy) {
+		await this.ensureTable(table);
+		const bind = [];
+		let sql = `SELECT data FROM "${table}"`;
+		if (where && where.length > 0) sql += ` WHERE ${renderWhereSql(where, bind, {})}`;
+		if (orderBy && orderBy.length > 0) sql += renderOrderSql(orderBy);
+		return this.execRows(sql, bind);
+	}
+	async transaction(fn) {
+		return fn({
+			upsert: (t, id, data, mode) => this.upsert(t, id, data, mode),
+			patch: (t, id, p) => this.patch(t, id, p),
+			delete: (t, id) => this.delete(t, id)
+		});
+	}
+};
+/** Live stats, inspectable in the browser console via `__sqliteStats`. Counts
+*  worker round-trips (the sync-down cost driver), batch sizes, and queue depth
+*  (`maxInFlight`) so a churn OOM can be measured rather than guessed. */
+function getStats() {
+	const g = globalThis;
+	if (!g.__sqliteStats) g.__sqliteStats = {
+		roundTrips: 0,
+		batchStatements: 0,
+		maxBatch: 0,
+		inFlight: 0,
+		maxInFlight: 0,
+		byType: {}
+	};
+	return g.__sqliteStats;
+}
+function renderOrderSql(orderBy) {
+	return ` ORDER BY ${orderBy.map(([f, d]) => `json_extract(data, '$.${f}') ${d === "desc" ? "DESC" : "ASC"}`).join(", ")}`;
+}
+function comparisonSql(c, bind, params) {
+	const lhs = c.field === "id" ? "id" : `json_extract(data, '$.${c.field}')`;
+	const value = c.paramRef ? params[c.paramRef] : c.value;
+	bind.push(scalar(value));
+	const op = c.op === "!=" ? "!=" : c.op;
+	return c.swap ? `? ${op} ${lhs}` : `${lhs} ${op} ?`;
+}
+function renderWhereSql(nodes, bind, params) {
+	return nodes.map((node) => {
+		if ("or" in node) return `(${node.or.map((c) => comparisonSql(c, bind, params)).join(" OR ")})`;
+		return comparisonSql(node, bind, params);
+	}).join(" AND ");
+}
+/** A comparable scalar for SQL binding: record links → `table:id`, everything
+*  else passed through (numbers/strings/bools). */
+function scalar(value) {
+	if (value == null) return null;
+	if (typeof value === "object") return stableKey(value);
+	return value;
+}
+function serializeRow(row) {
+	return JSON.stringify(row, (_k, v) => {
+		if (v instanceof Uint8Array) return { __u8: toBase64(v) };
+		if (v && typeof v === "object") {
+			const rid = v;
+			if (rid.tb !== void 0 && rid.id !== void 0) return stableKey(v);
+		}
+		return v;
+	});
+}
+function reviveRow(json) {
+	if (json.indexOf("\"__u8\"") === -1) return JSON.parse(json);
+	return JSON.parse(json, (_k, v) => {
+		if (v && typeof v === "object" && typeof v.__u8 === "string") return fromBase64(v.__u8);
+		return v;
+	});
+}
+function project(row, fields) {
+	const out = {};
+	for (const f of ["id", ...fields]) if (f in row) out[f] = row[f];
+	return out;
+}
+function toBase64(bytes) {
+	let bin = "";
+	for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+	return typeof btoa !== "undefined" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+}
+function fromBase64(b64) {
+	if (typeof atob !== "undefined") {
+		const bin = atob(b64);
+		const out = new Uint8Array(bin.length);
+		for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+		return out;
+	}
+	return new Uint8Array(Buffer.from(b64, "base64"));
+}
+
+//#endregion
+//#region src/services/database/engine-factory.ts
+/**
+* Build the local cache engine for the given `localEngine` config choice.
 *
-* Preserves the `SELECT <projection>` clause and the top-level `ORDER BY`;
-* drops the original `FROM`/`WHERE`/`LIMIT`/`START`. Subqueries inside the
-* projection are preserved verbatim (the scanner is paren/quote aware), with
-* one caveat: SurrealDB v3 drops `*` in the `SELECT *, <subquery> FROM $param`
-* shape — such windowed+subquery queries are rare and were already returning 0,
-* so this is no regression.
+* - `'surrealdb'` / unset → {@link SurrealCacheEngine} (subclass of
+*   `LocalDatabaseService`; the historical behavior, verbatim).
+* - `'sqlite'` → {@link SqliteCacheEngine} (SQLite-WASM Worker + OPFS). Backs
+*   `this.local` through the SurrealQL-vocabulary shim + verb surface.
+* - a custom object → used as-is (must satisfy {@link LocalStore}).
+*/
+function createLocalEngine(choice, config, logger) {
+	if (choice === void 0 || choice === "surrealdb") return new SurrealCacheEngine(config, logger);
+	if (choice === "sqlite") return new SqliteCacheEngine(config, logger, { useOpfs: (config.store ?? "memory") !== "memory" });
+	return choice;
+}
+
+//#endregion
+//#region src/modules/data/window-query.ts
+/**
+* Plan-level window materialization: restrict a windowed query's base rows to
+* exactly the SSP-computed id-set, dropping `where`/`limit`/`offset` but keeping
+* `orderBy`, `select` and `relations`. The engine-neutral counterpart of
+* {@link buildWindowMaterialization} (which does the same by string surgery for
+* the raw-SurrealQL path). Returns `null` for non-offset queries so the caller
+* keeps the normal re-query path.
 */
+function buildWindowMaterializationPlan(plan, ids) {
+	if (plan.offset === void 0 || plan.offset <= 0) return null;
+	return {
+		...plan,
+		ids,
+		where: void 0,
+		limit: void 0,
+		offset: void 0
+	};
+}
 function buildWindowMaterialization(surql, idsParam = "__win") {
 	const kw = scanTopLevelClauses(surql);
 	if (kw.startValue === null || kw.startValue <= 0) return null;
@@ -1283,7 +2286,7 @@ var DataModule = class {
 	/**
 	* Register a query and return its hash for subscriptions
 	*/
-	async query(tableName, surqlString, params, ttl) {
+	async query(tableName, surqlString, params, ttl, plan) {
 		const hash = await this.calculateHash({
 			surql: surqlString,
 			params
@@ -1312,7 +2315,7 @@ var DataModule = class {
 			hash,
 			Category: "sp00ky-client::DataModule::query"
 		}, "Query Initialization: not found, creating new query");
-		const promise = this.createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName);
+		const promise = this.createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName, plan);
 		this.pendingQueries.set(hash, promise);
 		try {
 			await promise;
@@ -1443,16 +2446,26 @@ var DataModule = class {
 	}
 	async materializeRecords(queryState, sspArray) {
 		const t0 = performance.now();
+		const plan = queryState.config.plan;
 		const windowMat = buildWindowMaterialization(queryState.config.surql);
 		let records;
 		if (windowMat) {
 			const winIds = (queryState.config.remoteArray?.length && queryState.config.remoteArray || sspArray?.length && sspArray || queryState.config.localArray || []).map(([id]) => parseRecordIdString(id));
-			const [rows] = await this.local.query(windowMat.query, {
-				...queryState.config.params,
-				__win: winIds
-			});
-			records = rows || [];
-		} else {
+			if (plan) {
+				const winPlan = buildWindowMaterializationPlan(plan, winIds) ?? {
+					...plan,
+					ids: winIds
+				};
+				records = await this.local.select(winPlan, queryState.config.params);
+			} else {
+				const [rows] = await this.local.query(windowMat.query, {
+					...queryState.config.params,
+					__win: winIds
+				});
+				records = rows || [];
+			}
+		} else if (plan) records = await this.local.select(plan, queryState.config.params);
+		else {
 			const [rows] = await this.local.query(queryState.config.surql, queryState.config.params);
 			records = rows || [];
 		}
@@ -2128,13 +3141,14 @@ var DataModule = class {
 			}
 		}
 	}
-	async createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName) {
+	async createAndRegisterQuery(hash, recordId, surqlString, params, ttl, tableName, plan) {
 		const queryState = await this.createNewQuery({
 			recordId,
 			surql: surqlString,
 			params,
 			ttl,
-			tableName
+			tableName,
+			plan
 		});
 		const t0 = performance.now();
 		const { localArray, registrationTimings } = this.cache.registerQuery({
@@ -2164,11 +3178,19 @@ var DataModule = class {
 		const windowMat = buildWindowMaterialization(surqlString);
 		if (windowMat && localArray.length > 0) try {
 			const winIds = localArray.map(([id]) => parseRecordIdString(id));
-			const [seeded] = await this.local.query(windowMat.query, {
-				...params,
-				__win: winIds
-			});
-			queryState.records = seeded || [];
+			if (plan) {
+				const winPlan = buildWindowMaterializationPlan(plan, winIds) ?? {
+					...plan,
+					ids: winIds
+				};
+				queryState.records = await this.local.select(winPlan, params);
+			} else {
+				const [seeded] = await this.local.query(windowMat.query, {
+					...params,
+					__win: winIds
+				});
+				queryState.records = seeded || [];
+			}
 		} catch (err) {
 			this.logger.warn({
 				err,
@@ -2186,7 +3208,7 @@ var DataModule = class {
 		}, "Query registered");
 		return hash;
 	}
-	async createNewQuery({ recordId, surql: surqlString, params, ttl, tableName }) {
+	async createNewQuery({ recordId, surql: surqlString, params, ttl, tableName, plan }) {
 		const tableSchema = this.schema.tables.find((t) => t.name === tableName);
 		if (!tableSchema) throw new Error(`Table ${tableName} not found`);
 		let [configRecord] = await withRetry(this.logger, () => this.local.query("SELECT * FROM ONLY $id", { id: recordId }));
@@ -2212,12 +3234,12 @@ var DataModule = class {
 		const config = {
 			...configRecord,
 			id: recordId,
+			plan,
 			params: parseParams(tableSchema.columns, configRecord.params)
 		};
 		let records = [];
 		if (buildWindowMaterialization(surqlString) === null) try {
-			const [result] = await this.local.query(surqlString, params);
-			records = result || [];
+			records = (plan ? await this.local.select(plan, params) : (await this.local.query(surqlString, params))[0]) || [];
 		} catch (err) {
 			this.logger.warn({
 				err,
@@ -3933,8 +4955,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.107";
-const WASM_VERSION = "0.0.1-canary.107";
+const CORE_VERSION = "0.0.1-canary.109";
+const WASM_VERSION = "0.0.1-canary.109";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5936,7 +6958,7 @@ var Sp00kyClient = class {
 			},
 			Category: "sp00ky-client::Sp00kyClient::constructor"
 		}, "Sp00kyClient initialized");
-		this.local = new LocalDatabaseService(this.config.database, logger);
+		this.local = createLocalEngine(this.config.localEngine, this.config.database, logger);
 		this.remote = new RemoteDatabaseService(this.config.database, logger);
 		if (config.persistenceClient === "surrealdb") this.persistenceClient = new SurrealDBPersistenceClient(this.local, logger);
 		else if (config.persistenceClient === "localstorage" || !config.persistenceClient) this.persistenceClient = new LocalStoragePersistenceClient(logger);
@@ -6029,8 +7051,10 @@ var Sp00kyClient = class {
 				bootBucket,
 				Category: "sp00ky-client::Sp00kyClient::init"
 			}, "Local database connected");
-			await this.migrator.provision(this.config.schemaSurql);
-			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Schema provisioned");
+			if (this.local.usesSurqlSchema) {
+				await this.migrator.provision(this.config.schemaSurql);
+				this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Schema provisioned");
+			}
 			await this.remote.connect();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Remote database connected");
 			this.streamProcessor.setStateKeySuffix(bootBucket);
@@ -6127,7 +7151,7 @@ var Sp00kyClient = class {
 		const reopen = this.local.beginSwitch();
 		try {
 			await this.local.switchStore(target);
-			await this.migrator.provision(this.config.schemaSurql);
+			if (this.local.usesSurqlSchema) await this.migrator.provision(this.config.schemaSurql);
 			await this.local.queryUngated("DELETE _00_query;");
 			this.streamProcessor.setStateKeySuffix(target);
 			await this.streamProcessor.reset();
@@ -6202,7 +7226,7 @@ var Sp00kyClient = class {
 		const tableSchema = this.config.schema.tables.find((t) => t.name === table);
 		if (!tableSchema) throw new Error(`Table ${table} not found`);
 		const params = parseParams(tableSchema.columns, q.selectQuery.vars ?? {});
-		const hash = await this.dataModule.query(table, q.selectQuery.query, params, ttl);
+		const hash = await this.dataModule.query(table, q.selectQuery.query, params, ttl, q.selectQuery.plan);
 		if (this.config.instantHydrate !== false && this.dataModule.isCold(hash)) try {
 			const [rows] = await this.remote.query(q.selectQuery.query, params);
 			await this.dataModule.applyHydration(hash, rows ?? []);