@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.210

package/src/services/database/sqlite-select.integration.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { executeSelect, type SelectDb } from './sqlite-select';
+import { serializeRow } from './sqlite-plan-sql';
+import type { Row } from './cache-engine';
+
+/**
+ * Integration: `executeSelect` (the worker-side plan executor) against a REAL
+ * in-memory SQLite (the same @sqlite.org/sqlite-wasm build the worker loads).
+ * The scripted-responder tests in `sqlite-select.test.ts` prove parity of the
+ * statement sequence; these prove the SQL itself is correct — json_extract
+ * filtering, ORDER BY, LIMIT/OFFSET, IN matching, per-parent relation
+ * order/limit, and the JSON round-trip of row bodies.
+ */
+
+let db: any;
+let selectDb: SelectDb;
+
+function seed(table: string, rows: Row[]): void {
+  db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+  selectDb.knownTables.add(table);
+  for (const row of rows) {
+    db.exec({
+      sql: `INSERT INTO "${table}"(id, data) VALUES(?, ?)`,
+      bind: [row.id, serializeRow(row)],
+    });
+  }
+}
+
+beforeAll(async () => {
+  const sqlite3: any = await sqlite3InitModule();
+  db = new sqlite3.oo1.DB(':memory:', 'c');
+  selectDb = {
+    exec: (sql, bind) =>
+      db.exec({ sql, bind, rowMode: 'object', returnValue: 'resultRows' }) as { data: string }[],
+    run: (sql, bind) => {
+      db.exec({ sql, bind });
+    },
+    knownTables: new Set<string>(),
+  };
+
+  seed('thread', [
+    { id: 'thread:A', title: 'alpha', createdAt: 3, author: 'user:1' },
+    { id: 'thread:B', title: 'beta', createdAt: 1, author: 'user:2' },
+    { id: 'thread:C', title: 'gamma', createdAt: 2, author: 'user:1' },
+  ]);
+  seed('comment', [
+    { id: 'comment:1', thread: 'thread:B', body: 'b-old', votes: 1, author: 'user:1' },
+    { id: 'comment:2', thread: 'thread:B', body: 'b-new', votes: 5, author: 'user:2' },
+    { id: 'comment:3', thread: 'thread:B', body: 'b-mid', votes: 3, author: 'user:1' },
+    { id: 'comment:4', thread: 'thread:A', body: 'a-only', votes: 2, author: 'user:2' },
+  ]);
+  seed('user', [
+    { id: 'user:1', name: 'ada' },
+    { id: 'user:2', name: 'grace' },
+  ]);
+  seed('snapshot', [{ id: 'snapshot:1', blob: new Uint8Array([1, 2, 250]), kind: 'crdt' }]);
+});
+
+afterAll(() => {
+  db?.close();
+});
+
+describe('executeSelect against real SQLite', () => {
+  it('filters via json_extract, slaved to params over the baked literal (aa4af79b)', async () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }],
+    };
+    const withParam = await executeSelect(plan, { id: 'thread:B' }, selectDb);
+    expect(withParam.rows.map((r) => r.id)).toEqual(['thread:B']);
+
+    const withoutParam = await executeSelect(plan, {}, selectDb);
+    expect(withoutParam.rows.map((r) => r.id)).toEqual(['thread:A']);
+  });
+
+  it('filters on a non-id field and binds a RecordId-shaped value as table:id', async () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'author', op: '=', value: { tb: 'user', id: '1' } }],
+      orderBy: [['createdAt', 'asc']],
+    };
+    const { rows } = await executeSelect(plan, {}, selectDb);
+    expect(rows.map((r) => r.id)).toEqual(['thread:C', 'thread:A']);
+  });
+
+  it('applies ORDER BY / LIMIT / OFFSET in SQL', async () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      orderBy: [['createdAt', 'desc']],
+      limit: 2,
+      offset: 1,
+    };
+    const { rows } = await executeSelect(plan, {}, selectDb);
+    expect(rows.map((r) => r.id)).toEqual(['thread:C', 'thread:B']);
+  });
+
+  it('supports OR groups', async () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [
+        {
+          or: [
+            { field: 'title', op: '=', value: 'alpha' },
+            { field: 'title', op: '=', value: 'beta' },
+          ],
+        },
+      ],
+      orderBy: [['title', 'asc']],
+    };
+    const { rows } = await executeSelect(plan, {}, selectDb);
+    expect(rows.map((r) => r.id)).toEqual(['thread:A', 'thread:B']);
+  });
+
+  it('resolves a nested relation tree with per-parent order/limit, one batch per level', async () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:B' }],
+      relations: [
+        {
+          alias: 'comments',
+          table: 'comment',
+          cardinality: 'many',
+          foreignKeyField: 'thread',
+          orderBy: [['votes', 'desc']],
+          limit: 2,
+          relations: [
+            { alias: 'author', table: 'user', cardinality: 'one', foreignKeyField: 'author' },
+          ],
+        },
+      ],
+    };
+    const { rows, relationFetches } = await executeSelect(plan, {}, selectDb);
+    expect(rows).toHaveLength(1);
+    const comments = rows[0].comments as Row[];
+    // Top-2 by votes, per parent.
+    expect(comments.map((c) => c.id)).toEqual(['comment:2', 'comment:3']);
+    // Nested `one` relation attached on each child.
+    expect(comments.map((c) => (c.author as Row).name)).toEqual(['grace', 'ada']);
+    // Level-ordered batching: one fetch for comments + one for users.
+    expect(relationFetches).toBe(2);
+  });
+
+  it('materializes an ids window preserving ids order, or ORDER BY when given', async () => {
+    const windowPlan: QueryPlan = { table: 'comment', ids: ['comment:3', 'comment:1'] };
+    const inIdsOrder = await executeSelect(windowPlan, {}, selectDb);
+    expect(inIdsOrder.rows.map((r) => r.id)).toEqual(['comment:3', 'comment:1']);
+
+    const ordered = await executeSelect(
+      { ...windowPlan, orderBy: [['votes', 'asc']] },
+      {},
+      selectDb
+    );
+    expect(ordered.rows.map((r) => r.id)).toEqual(['comment:1', 'comment:3']);
+  });
+
+  it('trims to the projection while keeping id', async () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:A' }],
+      select: ['title'],
+    };
+    const { rows } = await executeSelect(plan, {}, selectDb);
+    expect(rows).toEqual([{ id: 'thread:A', title: 'alpha' }]);
+  });
+
+  it('revives Uint8Array bodies through the {__u8} tag round-trip', async () => {
+    const plan: QueryPlan = {
+      table: 'snapshot',
+      where: [{ field: 'kind', op: '=', value: 'crdt' }],
+    };
+    const { rows } = await executeSelect(plan, {}, selectDb);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].blob).toBeInstanceOf(Uint8Array);
+    expect([...(rows[0].blob as Uint8Array)]).toEqual([1, 2, 250]);
+  });
+
+  it('creates a missing table on first touch instead of failing', async () => {
+    const plan: QueryPlan = { table: 'never_written', where: [{ field: 'x', op: '=', value: 1 }] };
+    const { rows } = await executeSelect(plan, {}, selectDb);
+    expect(rows).toEqual([]);
+    expect(selectDb.knownTables.has('never_written')).toBe(true);
+  });
+});

package/src/services/database/sqlite-select.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { executeSelect, type SelectDb } from './sqlite-select';
+import { SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
+import { stableKey } from './relation-resolver';
+import type { Row } from './cache-engine';
+
+function makeLogger(): any {
+  const noop = () => {};
+  const l: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  l.child = () => l;
+  return l;
+}
+
+/**
+ * A tiny scripted "SQL responder" for the EXACT statement shapes the SQLite
+ * renderers emit (base select by id, id-window IN, relation json_extract IN).
+ * Not a SQL engine — just enough to make legacy-vs-worker parity observable.
+ */
+function makeResponder(tables: Record<string, Row[]>) {
+  return (sql: string, bind: unknown[] = []): { data: string }[] => {
+    const table = /FROM "([^"]+)"/.exec(sql)?.[1];
+    let rows = table ? (tables[table] ?? []) : [];
+    const rel = /WHERE json_extract\(data, '\$\.([A-Za-z0-9_.]+)'\) IN/.exec(sql);
+    if (rel) {
+      rows = rows.filter((r) => bind.includes(r[rel[1]]));
+    } else if (/WHERE id IN/.test(sql)) {
+      rows = rows.filter((r) => bind.includes(r.id));
+    } else if (/WHERE id = \?/.test(sql)) {
+      rows = rows.filter((r) => r.id === bind[0]);
+    }
+    return rows.map((r) => ({ data: JSON.stringify(r) }));
+  };
+}
+
+const FIXTURE: Record<string, Row[]> = {
+  thread: [
+    { id: 'thread:A', title: 'thread A', author: 'user:1' },
+    { id: 'thread:B', title: 'thread B', author: 'user:2' },
+  ],
+  comment: [
+    { id: 'comment:1', thread: 'thread:B', body: 'first' },
+    { id: 'comment:2', thread: 'thread:B', body: 'second' },
+    { id: 'comment:3', thread: 'thread:A', body: 'other thread' },
+  ],
+};
+
+/** The `.one()` detail-view plan shape: id baked as a literal AND slaved to
+ *  the `id` param (aa4af79b), plus a `many` relation. */
+const DETAIL_PLAN: QueryPlan = {
+  table: 'thread',
+  where: [{ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }],
+  relations: [
+    { alias: 'comments', table: 'comment', cardinality: 'many', foreignKeyField: 'thread' },
+  ],
+};
+
+function makeSelectDb(
+  tables: Record<string, Row[]>,
+  calls: { sql: string; bind?: unknown[] }[]
+): SelectDb {
+  const respond = makeResponder(tables);
+  return {
+    exec: (sql, bind) => {
+      calls.push({ sql, bind });
+      return respond(sql, bind ?? []);
+    },
+    run: (sql, bind) => {
+      calls.push({ sql, bind });
+    },
+    knownTables: new Set<string>(),
+  };
+}
+
+/** An engine whose worker answers exec/run against the fixture (legacy path)
+ *  and optionally the one-hop `select` op, recording every message. */
+function makeEngine(opts: {
+  workerSelect: boolean;
+  answerSelect?: boolean;
+  calls?: { type: string; sql?: string; bind?: unknown[]; payload?: any }[];
+}) {
+  const respond = makeResponder(FIXTURE);
+  const calls = opts.calls ?? [];
+  const engine = new SqliteCacheEngine(
+    { namespace: 'n', database: 'd' } as any,
+    makeLogger(),
+    { useOpfs: false, workerSelect: opts.workerSelect }
+  );
+  stubTransport(engine, async (type, payload) => {
+    calls.push({ type, sql: payload?.sql, bind: payload?.bind, payload });
+    if (type === 'open') return { persisted: false };
+    if (type === 'exec') return { rows: respond(payload.sql, payload.bind ?? []) };
+    if (type === 'run' || type === 'batch' || type === 'close') return {};
+    if (type === 'select') {
+      if (!opts.answerSelect) throw new Error(`sqlite worker: unknown message ${type}`);
+      const dbCalls: { sql: string; bind?: unknown[] }[] = [];
+      return executeSelect(payload.plan, payload.params ?? {}, makeSelectDb(FIXTURE, dbCalls));
+    }
+    throw new Error(`sqlite worker: unknown message ${type}`);
+  });
+  return { engine, calls };
+}
+
+describe('executeSelect (worker-side plan execution)', () => {
+  it('slaves the base filter to params over the baked literal (aa4af79b guard)', async () => {
+    const calls: { sql: string; bind?: unknown[] }[] = [];
+    const { rows } = await executeSelect(DETAIL_PLAN, { id: 'thread:B' }, makeSelectDb(FIXTURE, calls));
+    // Filtered by the PARAM (thread:B), not the baked literal (thread:A).
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe('thread:B');
+    expect(rows[0].comments).toEqual([
+      { id: 'comment:1', thread: 'thread:B', body: 'first' },
+      { id: 'comment:2', thread: 'thread:B', body: 'second' },
+    ]);
+  });
+
+  it('falls back to the baked literal when the param key is absent', async () => {
+    const calls: { sql: string; bind?: unknown[] }[] = [];
+    const { rows } = await executeSelect(DETAIL_PLAN, {}, makeSelectDb(FIXTURE, calls));
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe('thread:A');
+  });
+
+  it('counts relation fetches and honors the ids window ordering', async () => {
+    const calls: { sql: string; bind?: unknown[] }[] = [];
+    const plan: QueryPlan = {
+      table: 'comment',
+      ids: ['comment:2', 'comment:1'],
+    };
+    const { rows, relationFetches } = await executeSelect(plan, {}, makeSelectDb(FIXTURE, calls));
+    expect(relationFetches).toBe(0);
+    // ids order preserved (no ORDER BY).
+    expect(rows.map((r) => r.id)).toEqual(['comment:2', 'comment:1']);
+  });
+});
+
+describe('worker-select parity with the legacy multi-hop path', () => {
+  it('produces identical rows AND an identical SQL statement sequence', async () => {
+    // Legacy: engine drives one worker round-trip per statement.
+    const legacy = makeEngine({ workerSelect: false });
+    await legacy.engine.connect('anon');
+    const legacyRows = await legacy.engine.select(DETAIL_PLAN, { id: 'thread:B' });
+    const legacySql = legacy.calls
+      .filter((c) => c.type === 'exec' || c.type === 'run')
+      .map((c) => ({ sql: c.sql, bind: c.bind ?? [] }));
+
+    // Worker path: same plan executed in one hop via executeSelect.
+    const workerCalls: { sql: string; bind?: unknown[] }[] = [];
+    const { rows: workerRows } = await executeSelect(
+      DETAIL_PLAN,
+      { id: 'thread:B' },
+      makeSelectDb(FIXTURE, workerCalls)
+    );
+
+    expect(workerRows).toEqual(legacyRows);
+    expect(workerCalls.map((c) => ({ sql: c.sql, bind: c.bind ?? [] }))).toEqual(legacySql);
+  });
+});
+
+describe('SqliteCacheEngine.select via worker (one hop)', () => {
+  it('sends exactly one select message, zero exec/run', async () => {
+    const { engine, calls } = makeEngine({ workerSelect: true, answerSelect: true });
+    await engine.connect('anon');
+    const rows = await engine.select(DETAIL_PLAN, { id: 'thread:B' });
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe('thread:B');
+    const afterOpen = calls.filter((c) => c.type !== 'open');
+    expect(afterOpen.map((c) => c.type)).toEqual(['select']);
+  });
+
+  it('normalizes RecordId param VALUES to strings but never drops param KEYS', async () => {
+    const { engine, calls } = makeEngine({ workerSelect: true, answerSelect: true });
+    await engine.connect('anon');
+    await engine.select(DETAIL_PLAN, { id: new RecordId('thread', 'B'), untouched: 7 });
+    const sel = calls.find((c) => c.type === 'select')!;
+    // VALUE normalized (a class instance would lose its prototype in the real
+    // structured clone); KEY present — comparisonSql's paramRef resolution
+    // checks hasOwnProperty, and a dropped key silently falls back to the
+    // baked literal (the aa4af79b crossed-results class).
+    expect(sel.payload.params).toEqual({ id: 'thread:B', untouched: 7 });
+    expect(Object.prototype.hasOwnProperty.call(sel.payload.params, 'id')).toBe(true);
+  });
+
+  it('normalizes a window plan\'s RecordId ids to the same strings the legacy path binds', async () => {
+    const rid = new RecordId('comment', '2');
+    const { engine, calls } = makeEngine({ workerSelect: true, answerSelect: true });
+    await engine.connect('anon');
+    await engine.select({ table: 'comment', ids: [rid, 'comment:1'] }, {});
+    const sel = calls.find((c) => c.type === 'select')!;
+    // stableKey output (surrealdb may escape the id part, e.g. comment:⟨2⟩) —
+    // identical to what the legacy `selectByIds` binds, so stored rows match.
+    expect(sel.payload.plan.ids).toEqual([stableKey(rid), 'comment:1']);
+    expect(sel.payload.plan.ids.every((i: unknown) => typeof i === 'string')).toBe(true);
+  });
+
+  it('normalizes RecordId values baked inside the plan\'s where tree', async () => {
+    const { engine, calls } = makeEngine({ workerSelect: true, answerSelect: true });
+    await engine.connect('anon');
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'author', op: '=', value: new RecordId('user', 'u1') }],
+      relations: [
+        {
+          alias: 'comments',
+          table: 'comment',
+          cardinality: 'many',
+          foreignKeyField: 'thread',
+          where: [{ field: 'author', op: '=', value: new RecordId('user', 'u1') }],
+        },
+      ],
+    };
+    await engine.select(plan, {});
+    const sel = calls.find((c) => c.type === 'select')!;
+    // Both the top-level where and the relation sub-where cross the boundary
+    // as strings — a RecordId instance would structured-clone to `{}`.
+    expect(sel.payload.plan.where[0].value).toBe('user:u1');
+    expect(sel.payload.plan.relations[0].where[0].value).toBe('user:u1');
+  });
+
+  it('folds the worker-reported relationFetches into __sqliteStats', async () => {
+    const { engine } = makeEngine({ workerSelect: true, answerSelect: true });
+    await engine.connect('anon');
+    const before = (globalThis as any).__sqliteStats?.relationFetches ?? 0;
+    await engine.select(DETAIL_PLAN, { id: 'thread:B' });
+    // DETAIL_PLAN has one relation level → executeSelect reports 1 fetch.
+    expect((globalThis as any).__sqliteStats.relationFetches).toBe(before + 1);
+  });
+
+  it('degrades to the legacy path when the worker lacks the select op', async () => {
+    const { engine, calls } = makeEngine({ workerSelect: true, answerSelect: false });
+    await engine.connect('anon');
+    const rows = await engine.select(DETAIL_PLAN, { id: 'thread:B' });
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe('thread:B');
+    // First attempt was 'select'; the rejection flipped the flag and the
+    // legacy path completed with exec/run hops.
+    expect(calls.some((c) => c.type === 'select')).toBe(true);
+    expect(calls.some((c) => c.type === 'exec')).toBe(true);
+    // The flag stays off: a second select never retries the worker op.
+    const before = calls.filter((c) => c.type === 'select').length;
+    await engine.select(DETAIL_PLAN, { id: 'thread:A' });
+    expect(calls.filter((c) => c.type === 'select').length).toBe(before);
+  });
+});

package/src/services/database/sqlite-select.ts

@@ -0,0 +1,131 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { resolveRelations, stableKey } from './relation-resolver';
+import {
+  renderOrderSql,
+  renderWhereSql,
+  reviveRow,
+  project,
+  projectedDataSql,
+} from './sqlite-plan-sql';
+import type { OrderBy, RelationFetch, Row, RowFetcher } from './cache-engine';
+
+/**
+ * Worker-side execution of a whole {@link QueryPlan} — table creation, base
+ * select (either the `ids` window or where/order/limit), projection, and the
+ * full `.related()` tree via the SHARED `resolveRelations` — against an
+ * injected DB handle. Runs inside `sqlite-worker.ts` so the engine pays ONE
+ * postMessage round-trip per select instead of one per table/relation level;
+ * extracted into its own module so the logic is unit-testable off-worker
+ * (parity with the engine's legacy multi-hop path).
+ *
+ * Semantics mirror `SqliteCacheEngine.selectLegacy` exactly: same SQL, same
+ * ordering rules, same projection, same resolver.
+ */
+
+/** The slice of the worker's DB surface `executeSelect` needs. */
+export interface SelectDb {
+  /** Run a row-returning statement; rows come back as `{ data: <json> }`. */
+  exec(sql: string, bind?: unknown[]): { data: string }[];
+  /** Run a statement for effect only (CREATE TABLE). */
+  run(sql: string, bind?: unknown[]): void;
+  /** Tables already CREATEd on this handle (caller owns the lifecycle). */
+  knownTables: Set<string>;
+}
+
+function ensureTable(db: SelectDb, table: string): void {
+  if (db.knownTables.has(table)) return;
+  db.run(`CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`);
+  db.knownTables.add(table);
+}
+
+function execRows(db: SelectDb, sql: string, bind: unknown[]): Row[] {
+  return db.exec(sql, bind).map((r) => reviveRow(r.data));
+}
+
+/** Mirrors the engine's `selectByIds`: fetch by primary id, preserving `ids`
+ *  order unless an ORDER BY overrides it. */
+function selectByIds(
+  db: SelectDb,
+  table: string,
+  ids: unknown[],
+  opts?: { select?: string[]; orderBy?: OrderBy }
+): Row[] {
+  if (ids.length === 0) return [];
+  ensureTable(db, table);
+  const keys = ids.map(stableKey);
+  const placeholders = keys.map(() => '?').join(', ');
+  // Projection binds land in the SELECT clause, so they go first.
+  const bind: unknown[] = [];
+  const dataCol = opts?.select ? projectedDataSql(opts.select, bind) : 'data';
+  bind.push(...keys);
+  let sql = `SELECT ${dataCol} FROM "${table}" WHERE id IN (${placeholders})`;
+  if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
+  let rows = execRows(db, sql, bind);
+  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 rows;
+}
+
+/** Mirrors the engine's `fetchRelation` SQL exactly. */
+function fetchRelation(db: SelectDb, req: RelationFetch): Row[] {
+  ensureTable(db, req.table);
+  const keys = req.keys.map(stableKey);
+  const placeholders = keys.map(() => '?').join(', ');
+  const bind: unknown[] = [...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 = execRows(db, sql, bind);
+  return req.select ? rows.map((r) => project(r, req.select!)) : rows;
+}
+
+export async function executeSelect(
+  plan: QueryPlan,
+  params: Record<string, unknown>,
+  db: SelectDb
+): Promise<{ rows: Row[]; relationFetches: number }> {
+  // Per-call fetch counter (the engine folds it into `__sqliteStats`).
+  const counter = { n: 0 };
+  const fetcher: RowFetcher = {
+    fetchRelation: (req) => {
+      counter.n++;
+      return Promise.resolve(fetchRelation(db, req));
+    },
+  };
+  // Window materialization: base rows are exactly `plan.ids`, ordered.
+  if (plan.ids) {
+    const rows = selectByIds(db, plan.table, plan.ids, {
+      select: plan.select,
+      orderBy: plan.orderBy,
+    });
+    await resolveRelations(rows, plan.relations, fetcher);
+    return { rows, relationFetches: counter.n };
+  }
+  ensureTable(db, plan.table);
+  const bind: unknown[] = [];
+  // Projection binds land in the SELECT clause, ahead of any WHERE binds.
+  const dataCol = plan.select ? projectedDataSql(plan.select, bind) : 'data';
+  let sql = `SELECT ${dataCol} 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);
+  // A query with no ORDER BY still has to render in SOME order, and "whatever
+  // SQLite hands back" is insertion order — which disagrees with the order the
+  // same query gets once it renders from server membership, and disagrees with
+  // SurrealDB, whose natural order is by id. That mismatch is visible: the
+  // first paint comes from this scan and the second from membership, so an
+  // unordered list visibly reshuffled about a second after load. Ordering by
+  // id here makes the two agree and makes the result stable across reloads.
+  else sql += ` ORDER BY id`;
+  if (plan.limit !== undefined) sql += ` LIMIT ${Number(plan.limit)}`;
+  if (plan.offset !== undefined) sql += ` OFFSET ${Number(plan.offset)}`;
+  const rows = execRows(db, sql, bind);
+  await resolveRelations(rows, plan.relations, fetcher);
+  return { rows, relationFetches: counter.n };
+}

package/src/services/database/sqlite-transport.fixture.ts

@@ -0,0 +1,30 @@
+/**
+ * Test-only helper: stubs `SqliteCacheEngine.createTransport` with a fake
+ * transport driven by a plain handler function, replacing the old pattern of
+ * faking a whole Worker plus the engine's pending-map wiring. Not exported
+ * from the package; imported only by *.test.ts files.
+ */
+import type { SqliteTransport } from './sqlite-transport';
+
+export type FakeTransportHandler = (type: string, payload: any) => unknown | Promise<unknown>;
+
+/** Replace the engine's transport factory. Each open spawns a fresh fake, like
+ *  the real factory spawns a fresh Worker. The handler returns the reply rest
+ *  (without id/ok/wt) or throws to produce an error reply. */
+export function stubTransport(engine: unknown, handler: FakeTransportHandler): void {
+  (engine as { createTransport: () => SqliteTransport }).createTransport = () => {
+    let closed = false;
+    return {
+      kind: 'worker',
+      get connected() {
+        return !closed;
+      },
+      call: <T>(type: string, payload?: unknown) =>
+        Promise.resolve().then(() => handler(type, payload)) as Promise<T>,
+      failAll() {},
+      close() {
+        closed = true;
+      },
+    } as SqliteTransport;
+  };
+}