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

package/dist/sqlite-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sqlite-worker.js

@@ -0,0 +1,107 @@
+import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+
+//#region src/services/database/sqlite-worker.ts
+/**
+* Dedicated Web Worker that owns the SQLite-WASM handle. All DB access is
+* funnelled through here (the main thread never touches the wasm module), which
+* is also what the OPFS VFS requires — file access must happen off the main
+* thread. Persistence uses the **OPFS SAHPool VFS**: durable, and (unlike the
+* classic OPFS VFS) it does NOT require COOP/COEP cross-origin isolation
+* headers, so host apps embedding the client need no server changes. Falls back
+* to an in-memory DB when OPFS is unavailable.
+*
+* Message protocol (request/response keyed by `id`):
+*   { id, type: 'open',  payload: { dbName, useOpfs } }
+*   { id, type: 'exec',  payload: { sql, bind } }  -> { id, ok, rows }
+*   { id, type: 'run',   payload: { sql, bind } }  -> { id, ok }
+*   { id, type: 'batch', payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+*   { id, type: 'close' }
+*/
+let db = null;
+async function open(dbName, useOpfs) {
+	const sqlite3 = await sqlite3InitModule();
+	let persisted = false;
+	if (useOpfs && sqlite3.installOpfsSAHPoolVfs) try {
+		db = new (await (sqlite3.installOpfsSAHPoolVfs({ name: `sp00ky-${dbName}` }))).OpfsSAHPoolDb(`/${dbName}.sqlite3`);
+		persisted = true;
+	} catch {}
+	if (!db) db = new sqlite3.oo1.DB(":memory:", "c");
+	try {
+		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
+	} catch {}
+	return { persisted };
+}
+function exec(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	return db.exec({
+		sql,
+		bind,
+		rowMode: "object",
+		returnValue: "resultRows"
+	});
+}
+function run(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({
+		sql,
+		bind
+	});
+}
+function batch(stmts) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({ sql: "BEGIN" });
+	try {
+		for (const s of stmts) db.exec({
+			sql: s.sql,
+			bind: s.bind
+		});
+		db.exec({ sql: "COMMIT" });
+	} catch (e) {
+		try {
+			db.exec({ sql: "ROLLBACK" });
+		} catch {}
+		throw e;
+	}
+}
+self.onmessage = async (ev) => {
+	const { id, type, payload } = ev.data ?? {};
+	try {
+		let result;
+		switch (type) {
+			case "open":
+				result = await open(payload.dbName, payload.useOpfs);
+				break;
+			case "exec":
+				result = { rows: exec(payload.sql, payload.bind) };
+				break;
+			case "run":
+				run(payload.sql, payload.bind);
+				result = {};
+				break;
+			case "batch":
+				batch(payload);
+				result = {};
+				break;
+			case "close":
+				db?.close();
+				db = null;
+				result = {};
+				break;
+			default: throw new Error(`sqlite worker: unknown message ${type}`);
+		}
+		self.postMessage({
+			id,
+			ok: true,
+			...result
+		});
+	} catch (err) {
+		self.postMessage({
+			id,
+			ok: false,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+};
+
+//#endregion
+export {  };

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { RecordId } from "surrealdb";
-import { RecordId as RecordId$1, SchemaStructure } from "@spooky-sync/query-builder";
+import { QueryPlan, QueryPlan as QueryPlan$1, RecordId as RecordId$1, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
 import { Level, Level as Level$1, Logger, LoggerOptions } from "pino";
 
 //#region src/events/index.d.ts
@@ -154,6 +154,146 @@ type SyncEventSystem = EventSystem<SyncEventTypeMap>;
 //#region src/services/logger/index.d.ts
 type Logger$1 = Logger;
 //#endregion
+//#region src/services/database/events/index.d.ts
+declare const DatabaseEventTypes: {
+  readonly LocalQuery: "DATABASE_LOCAL_QUERY";
+  readonly RemoteQuery: "DATABASE_REMOTE_QUERY";
+};
+interface DatabaseQueryEventPayload {
+  query: string;
+  vars?: Record<string, unknown>;
+  duration: number;
+  success: boolean;
+  error?: string;
+  timestamp: number;
+}
+type DatabaseEventTypeMap = {
+  [DatabaseEventTypes.LocalQuery]: EventDefinition<typeof DatabaseEventTypes.LocalQuery, DatabaseQueryEventPayload>;
+  [DatabaseEventTypes.RemoteQuery]: EventDefinition<typeof DatabaseEventTypes.RemoteQuery, DatabaseQueryEventPayload>;
+};
+type DatabaseEventSystem = EventSystem<DatabaseEventTypeMap>;
+//#endregion
+//#region src/utils/surql.d.ts
+interface SealedQuery<T = void> {
+  readonly sql: string;
+  readonly extract: (results: unknown[]) => T;
+}
+//#endregion
+//#region src/services/database/cache-engine.d.ts
+/**
+ * A materialized row. Keys are field names; values are already decoded to the
+ * client's runtime shapes (RecordId stays a RecordId, bytes a Uint8Array, …) so
+ * every backend hands `DataModule` the same shape SurrealDB does today.
+ */
+type Row = Record<string, unknown>;
+/** A record identifier — a `RecordId` or its stable string form (`table:id`). */
+type Id = unknown;
+/** How an order clause is expressed everywhere in the engine layer. */
+type OrderBy = [field: string, direction: 'asc' | 'desc'][];
+/**
+ * Batched relation fetch: "give me every row of `table` whose `matchField` is
+ * one of `keys`, filtered by `where`, ordered by `orderBy`". This is the single
+ * primitive relation decomposition (§3) leans on — implemented as
+ * `SELECT … WHERE <matchField> IN (…)` on SQLite, `SELECT … FROM $keys` /
+ * `WHERE <matchField> IN $keys` on SurrealDB, or an index scan elsewhere. Order
+ * here is a hint; the resolver re-applies order+limit PER PARENT after grouping.
+ */
+interface RelationFetch {
+  table: string;
+  matchField: string;
+  keys: Id[];
+  where?: WhereNode[];
+  orderBy?: OrderBy;
+  select?: string[];
+}
+/**
+ * The read side of an engine, minus relation resolution — the surface a
+ * {@link RelationResolver} needs. Kept separate so the resolver can be unit
+ * tested against an in-memory fake without a full engine.
+ */
+interface RowFetcher {
+  /** Batched fan-out fetch. See {@link RelationFetch}. */
+  fetchRelation(req: RelationFetch): Promise<Row[]>;
+}
+/** A transaction handle — the same verbs as the engine, but atomic. */
+interface EngineTx {
+  upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void>;
+  patch(table: string, id: Id, patches: unknown[]): Promise<void>;
+  delete(table: string, id: Id): Promise<void>;
+}
+/**
+ * A pluggable local cache backend. SurrealDB (the default) and SQLite both
+ * implement this; the rest of the client talks verbs, never SurrealQL.
+ *
+ * Reactivity is NOT part of this contract: the local cache is passive. The SSP
+ * (remote) drives change; `DataModule` writes rows here and re-reads them. The
+ * `epoch` field preserves the existing bucket-switch fencing (see
+ * `LocalDatabaseService.epoch`): an async chain captures it at start and its
+ * write is dropped if the epoch moved (a bucket switch) in between.
+ */
+interface LocalCacheEngine extends RowFetcher {
+  /** Monotonic store generation; bumped on every bucket switch. */
+  readonly epoch: number;
+  connect(bucketId: string): Promise<void>;
+  switchBucket(bucketId: string): Promise<void>;
+  close(): Promise<void>;
+  /** Run `fn` inside a single atomic transaction. */
+  transaction<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T>;
+  /**
+   * Materialize a query, including its `.related()` tree (via §3
+   * decomposition). Params bind `where` `paramRef`s and any windowing id-set.
+   */
+  select(plan: QueryPlan$1, params?: Record<string, unknown>): Promise<Row[]>;
+  /** Fetch rows by primary id, preserving `ids` order; missing ids are skipped. */
+  selectByIds(table: string, ids: Id[], opts?: {
+    select?: string[];
+    orderBy?: OrderBy;
+  }): Promise<Row[]>;
+  /** Single-record read by primary id, or `null`. */
+  getById(table: string, id: Id): Promise<Row | null>;
+  upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void>;
+  patch(table: string, id: Id, patches: unknown[]): Promise<void>;
+  delete(table: string, id: Id): Promise<void>;
+}
+/**
+ * The full surface the client's `this.local` field depends on: the
+ * engine-neutral {@link LocalCacheEngine} verbs PLUS the legacy
+ * SurrealQL/lifecycle methods the not-yet-migrated call sites still use.
+ * `SurrealCacheEngine` (subclass of `LocalDatabaseService`) and
+ * `SqliteCacheEngine` (via a SurrealQL-vocabulary shim) both satisfy this, so
+ * either can back `this.local`.
+ *
+ * `getClient()` returns the underlying SurrealDB `Surreal` handle where one
+ * exists (SurrealDB backend); backends without one (SQLite) throw — it is only
+ * used by advanced/DevTools paths, never on the hot path.
+ */
+interface LocalStore extends LocalCacheEngine {
+  /**
+   * Whether this engine needs SurrealQL schema provisioning (`DEFINE TABLE`,
+   * `DEFINE FIELD`, …) run against it at init / bucket switch. SurrealDB → true;
+   * schemaless engines (SQLite creates tables lazily) → false, so the client
+   * skips the `LocalMigrator` entirely for them.
+   */
+  readonly usesSurqlSchema: boolean;
+  query<T extends unknown[]>(query: string, vars?: Record<string, unknown>, opts?: {
+    epoch?: number;
+  }): Promise<T>;
+  execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>, opts?: {
+    epoch?: number;
+  }): Promise<T>;
+  queryUngated<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+  switchStore(bucketId: string): Promise<void>;
+  beginSwitch(): () => void;
+  getEvents(): DatabaseEventSystem;
+  getClient(): unknown;
+  getConfig(): Sp00kyConfig<any>['database'];
+  readonly currentBucketId: string;
+}
+/** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
+type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
+/** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
+ *  a guard against a cyclic schema producing unbounded fan-out. */
+//#endregion
 //#region src/modules/sync/queue/queue-up.d.ts
 type CreateEvent = {
   type: 'create';
@@ -260,6 +400,14 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * Can be a custom implementation, 'surrealdb' (default), or 'localstorage'.
    */
   persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
+  /**
+   * Local cache engine backend. `'surrealdb'` (default) uses the in-browser
+   * SurrealDB-WASM store; `'sqlite'` uses official SQLite-WASM in a Worker with
+   * OPFS persistence; or pass a custom {@link LocalCacheEngine}. The local cache
+   * is a passive queryable store — reactivity is driven by the remote SSP, not
+   * this engine. See `services/database/cache-engine.ts`.
+   */
+  localEngine?: LocalEngineChoice;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**
@@ -377,6 +525,13 @@ interface QueryConfig {
   id: RecordId$1<string>;
   /** The SURQL query string. */
   surql: string;
+  /**
+   * Engine-neutral plan for `surql` (in-memory only; not persisted to
+   * `_00_query`). Present when the query came from the query-builder. Non-
+   * SurrealQL local engines (SQLite) materialize via `engine.select(plan)`
+   * instead of re-running `surql`, which they cannot parse.
+   */
+  plan?: QueryPlan;
   /** Parameters used in the query. */
   params: Record<string, any>;
   /** The version array representing the local state of results. */
@@ -563,4 +718,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { SyncHealthStatus as A, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SyncEventSystem as F, EventDefinition as I, EventSystem as L, UpdateOptions as M, UpEvent as N, SyncHealth as O, Logger$1 as P, RegistrationTimings as S, Sp00kyQueryResult as T, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, TimingPhase as j, SyncHealthConfig as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y };
+export { SyncHealthStatus as A, EventDefinition as B, RunOptions as C, StoreType as D, Sp00kyQueryResultPromise as E, SealedQuery as F, DatabaseEventSystem as I, DatabaseEventTypes as L, UpdateOptions as M, UpEvent as N, SyncHealth as O, LocalStore as P, Logger$1 as R, RegistrationTimings as S, Sp00kyQueryResult as T, EventSystem as V, QueryTimeToLive as _, MutationCallback as a, RecordVersionArray as b, PersistenceClient as c, QueryConfig as d, QueryConfigRecord as f, QueryStatusCallback as g, QueryStatus as h, MATERIALIZATION_SAMPLE_WINDOW as i, TimingPhase as j, SyncHealthConfig as k, PhaseStat as l, QueryState as m, EventSubscriptionOptions as n, MutationEvent as o, QueryHash as p, Level$1 as r, MutationEventType as s, DebounceOptions as t, PinoTransmit as u, QueryTimings as v, Sp00kyConfig as w, RecordVersionDiff as x, QueryUpdateCallback as y, SyncEventSystem as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.108",
+  "version": "0.0.1-canary.109",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,9 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.108",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.108",
+    "@spooky-sync/query-builder": "0.0.1-canary.109",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.109",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/cache/index.ts

@@ -1,4 +1,4 @@
-import type { LocalDatabaseService } from '../../services/database/index';
+import type { LocalStore } from '../../services/database/index';
 import { StaleEpochError } from '../../services/database/index';
 import type {
   StreamProcessorService,
@@ -24,7 +24,7 @@ export class CacheModule implements StreamUpdateReceiver {
   private versionLookups: Record<string, number> = {};
 
   constructor(
-    private local: LocalDatabaseService,
+    private local: LocalStore,
     private streamProcessor: StreamProcessorService,
     streamUpdateCallback: (update: StreamUpdate) => void,
     logger: Logger

package/src/modules/crdt/crdt-field.ts

@@ -1,5 +1,5 @@
 import { LoroDoc } from 'loro-crdt';
-import type { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
 import type { Logger } from '../../services/logger/index';
 import { parseRecordIdString } from '../../utils/index';
 
@@ -23,7 +23,7 @@ export function cursorColorFromName(name: string): string {
 export class CrdtField {
   private doc: LoroDoc;
   private pushTimer: ReturnType<typeof setTimeout> | null = null;
-  private local: LocalDatabaseService | null = null;
+  private local: LocalStore | null = null;
   private remote: RemoteDatabaseService | null = null;
   private recordId: string | null = null;
   private sessionId: string = '';
@@ -102,7 +102,7 @@ export class CrdtField {
   }
 
   startSync(
-    local: LocalDatabaseService,
+    local: LocalStore,
     remote: RemoteDatabaseService,
     recordId: string,
     sessionId: string,

package/src/modules/crdt/crdt-hydration.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { LoroDoc } from 'loro-crdt';
 import type { SchemaStructure } from '@spooky-sync/query-builder';
 import { CrdtManager } from './index';
-import type { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
 import type { Logger } from '../../services/logger/index';
 
 // Regression test for the offline-reload formatting-loss class of bug.
@@ -89,7 +89,7 @@ describe('CrdtManager.open hydration', () => {
         if (sql.includes('SELECT VALUE body FROM ONLY')) return [null];
         return [];
       }),
-    } satisfies Partial<LocalDatabaseService> as unknown as LocalDatabaseService;
+    } satisfies Partial<LocalStore> as unknown as LocalStore;
 
     const remote = makeRemote({
       selectRow: () => ({ id: 'thread:abc', body: remoteSnapshot }),
@@ -115,7 +115,7 @@ describe('CrdtManager.open hydration', () => {
 
     const local = {
       query: vi.fn().mockImplementation(async () => [null]),
-    } satisfies Partial<LocalDatabaseService> as unknown as LocalDatabaseService;
+    } satisfies Partial<LocalStore> as unknown as LocalStore;
 
     // Cursor-enabled field stores `{ state, cursors }`. The remote row
     // returns this shape; the manager must drill into `.state` for the
@@ -150,7 +150,7 @@ describe('CrdtManager.open hydration', () => {
         if (sql.includes('SELECT VALUE body FROM ONLY')) return [localSnapshot];
         return [];
       }),
-    } satisfies Partial<LocalDatabaseService> as unknown as LocalDatabaseService;
+    } satisfies Partial<LocalStore> as unknown as LocalStore;
 
     const remote = makeRemote({});
 
@@ -187,7 +187,7 @@ describe('CrdtManager.open hydration', () => {
         }
         return [];
       }),
-    } satisfies Partial<LocalDatabaseService> as unknown as LocalDatabaseService;
+    } satisfies Partial<LocalStore> as unknown as LocalStore;
 
     const remote = makeRemote({});
 

package/src/modules/crdt/index.ts

@@ -1,5 +1,5 @@
 import type { SchemaStructure } from '@spooky-sync/query-builder';
-import type { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
 import type { Logger } from '../../services/logger/index';
 import type { Uuid } from 'surrealdb';
 import { CrdtField } from './crdt-field';
@@ -40,7 +40,7 @@ export class CrdtManager {
 
   constructor(
     private schema: SchemaStructure,
-    private local: LocalDatabaseService,
+    private local: LocalStore,
     private remote: RemoteDatabaseService,
     logger: Logger,
     private debounceMs: number = 500,

package/src/modules/data/index.ts

@@ -5,8 +5,9 @@ import type {
   BackendNames,
   BackendRoutes,
   RoutePayload,
+  QueryPlan,
 } from '@spooky-sync/query-builder';
-import type { LocalDatabaseService } from '../../services/database/index';
+import type { LocalStore } from '../../services/database/index';
 import { StaleEpochError } from '../../services/database/index';
 import type { CacheModule, RecordWithId, CacheRecord } from '../cache/index';
 import type { Logger } from '../../services/logger/index';
@@ -42,7 +43,7 @@ import {
 } from '../../utils/index';
 import type { CreateEvent, DeleteEvent, UpdateEvent } from '../sync/index';
 import type { PushEventOptions } from '../../events/index';
-import { buildWindowMaterialization } from './window-query';
+import { buildWindowMaterialization, buildWindowMaterializationPlan } from './window-query';
 
 /** Push a timing sample (ms) into a rolling window, capped at the sample window. */
 function pushSample(samples: number[], ms: number): void {
@@ -124,7 +125,7 @@ export class DataModule<S extends SchemaStructure> {
 
   constructor(
     private cache: CacheModule,
-    private local: LocalDatabaseService,
+    private local: LocalStore,
     private schema: S,
     logger: Logger,
     // Client-side SSP aggregation throttle: coalesces the in-browser
@@ -180,7 +181,8 @@ export class DataModule<S extends SchemaStructure> {
     tableName: T,
     surqlString: string,
     params: Record<string, any>,
-    ttl: QueryTimeToLive
+    ttl: QueryTimeToLive,
+    plan?: QueryPlan
   ): Promise<QueryHash> {
     const hash = await this.calculateHash({ surql: surqlString, params });
     this.logger.debug(
@@ -216,7 +218,7 @@ export class DataModule<S extends SchemaStructure> {
     );
 
     // Create the query and track the pending promise
-    const promise = this.createAndRegisterQuery<T>(hash, recordId, surqlString, params, ttl, tableName);
+    const promise = this.createAndRegisterQuery<T>(hash, recordId, surqlString, params, ttl, tableName, plan);
     this.pendingQueries.set(hash, promise);
     try {
       await promise;
@@ -433,6 +435,7 @@ export class DataModule<S extends SchemaStructure> {
     sspArray?: Array<[string, number]>
   ): Promise<Record<string, any>[]> {
     const t0 = performance.now();
+    const plan = queryState.config.plan;
     const windowMat = buildWindowMaterialization(queryState.config.surql);
     let records: Record<string, any>[];
     if (windowMat) {
@@ -442,11 +445,20 @@ export class DataModule<S extends SchemaStructure> {
         queryState.config.localArray ||
         [];
       const winIds = win.map(([id]) => parseRecordIdString(id));
-      const [rows] = await this.local.query<[Record<string, any>[]]>(windowMat.query, {
-        ...queryState.config.params,
-        __win: winIds,
-      });
-      records = rows || [];
+      if (plan) {
+        // Engine-neutral window materialization: select exactly the id-set,
+        // keeping ORDER BY + relations. Works on any local engine.
+        const winPlan = buildWindowMaterializationPlan(plan, winIds) ?? { ...plan, ids: winIds };
+        records = await this.local.select(winPlan, queryState.config.params);
+      } else {
+        const [rows] = await this.local.query<[Record<string, any>[]]>(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<[Record<string, any>[]]>(
         queryState.config.surql,
@@ -1436,7 +1448,8 @@ export class DataModule<S extends SchemaStructure> {
     surqlString: string,
     params: Record<string, any>,
     ttl: QueryTimeToLive,
-    tableName: T
+    tableName: T,
+    plan?: QueryPlan
   ): Promise<QueryHash> {
     const queryState = await this.createNewQuery<T>({
       recordId,
@@ -1444,6 +1457,7 @@ export class DataModule<S extends SchemaStructure> {
       params,
       ttl,
       tableName,
+      plan,
     });
 
     const t0 = performance.now();
@@ -1487,11 +1501,16 @@ export class DataModule<S extends SchemaStructure> {
     if (windowMat && localArray.length > 0) {
       try {
         const winIds = localArray.map(([id]) => parseRecordIdString(id));
-        const [seeded] = await this.local.query<[Record<string, any>[]]>(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<[Record<string, any>[]]>(windowMat.query, {
+            ...params,
+            __win: winIds,
+          });
+          queryState.records = seeded || [];
+        }
       } catch (err) {
         this.logger.warn(
           { err, hash, Category: 'sp00ky-client::DataModule::createAndRegisterQuery' },
@@ -1521,12 +1540,14 @@ export class DataModule<S extends SchemaStructure> {
     params,
     ttl,
     tableName,
+    plan,
   }: {
     recordId: RecordId;
     surql: string;
     params: Record<string, any>;
     ttl: QueryTimeToLive;
     tableName: T;
+    plan?: QueryPlan;
   }): Promise<QueryState> {
     const tableSchema = this.schema.tables.find((t) => t.name === tableName);
     if (!tableSchema) {
@@ -1564,6 +1585,9 @@ export class DataModule<S extends SchemaStructure> {
     const config: QueryConfig = {
       ...configRecord,
       id: recordId,
+      // In-memory only — carries the engine-neutral plan so non-SurrealQL local
+      // engines materialize via `select(plan)` instead of parsing `surql`.
+      plan,
       params: parseParams(tableSchema.columns, configRecord.params),
     };
 
@@ -1575,7 +1599,11 @@ export class DataModule<S extends SchemaStructure> {
     // seeded from the SSP `localArray` in `createAndRegisterQuery` instead.
     if (buildWindowMaterialization(surqlString) === null) {
       try {
-        const [result] = await this.local.query<[Record<string, any>[]]>(surqlString, params);
+        // Prefer the engine-neutral plan (required for non-SurrealQL engines);
+        // fall back to running the raw surql on the SurrealDB engine.
+        const result = plan
+          ? await this.local.select(plan, params)
+          : (await this.local.query<[Record<string, any>[]]>(surqlString, params))[0];
         records = result || [];
       } catch (err) {
         this.logger.warn(

package/src/modules/data/window-query.ts

@@ -23,6 +23,30 @@
  * shape — such windowed+subquery queries are rare and were already returning 0,
  * so this is no regression.
  */
+import type { QueryPlan } from '@spooky-sync/query-builder';
+
+/**
+ * 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.
+ */
+export function buildWindowMaterializationPlan(
+  plan: QueryPlan,
+  ids: unknown[]
+): QueryPlan | null {
+  if (plan.offset === undefined || plan.offset <= 0) return null;
+  return {
+    ...plan,
+    ids,
+    where: undefined,
+    limit: undefined,
+    offset: undefined,
+  };
+}
+
 export function buildWindowMaterialization(
   surql: string,
   idsParam = '__win'

package/src/modules/devtools/index.ts

@@ -1,4 +1,4 @@
-import type { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
 import type { Logger } from '../../services/logger/index';
 import type { SchemaStructure } from '@spooky-sync/query-builder';
 import { RecordId } from 'surrealdb';
@@ -57,7 +57,7 @@ export class DevToolsService implements StreamUpdateReceiver {
   private localTablesAt = 0;
 
   constructor(
-    private databaseService: LocalDatabaseService,
+    private databaseService: LocalStore,
     private remoteDatabaseService: RemoteDatabaseService,
     private logger: Logger,
     private schema: SchemaStructure,

package/src/modules/sync/queue/queue-down.ts

@@ -1,4 +1,4 @@
-import type { LocalDatabaseService } from '../../../services/database/index';
+import type { LocalStore } from '../../../services/database/index';
 import type {
   SyncQueueEventSystem} from '../events/index';
 import {
@@ -47,7 +47,7 @@ export class DownQueue {
   }
 
   constructor(
-    private local: LocalDatabaseService,
+    private local: LocalStore,
     logger: Logger
   ) {
     this._events = createSyncQueueEventSystem();

package/src/modules/sync/queue/queue-up.ts

@@ -1,5 +1,5 @@
 import type { RecordId } from 'surrealdb';
-import type { LocalDatabaseService } from '../../../services/database/index';
+import type { LocalStore } from '../../../services/database/index';
 import type {
   SyncQueueEventSystem} from '../events/index';
 import {
@@ -52,7 +52,7 @@ export class UpQueue {
   }
 
   constructor(
-    private local: LocalDatabaseService,
+    private local: LocalStore,
     logger: Logger
   ) {
     this._events = createSyncQueueEventSystem();