@spooky-sync/core 0.0.1-canary.133 → 0.0.1-canary.134

package/src/services/database/sqlite-plan-sql.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import type { WhereNode } from '@spooky-sync/query-builder';
+import {
+  comparisonSql,
+  renderWhereSql,
+  renderOrderSql,
+  scalar,
+  serializeRow,
+  reviveRow,
+  project,
+} from './sqlite-plan-sql';
+
+describe('comparisonSql param slaving (aa4af79b)', () => {
+  it('prefers params[paramRef] over the baked literal', () => {
+    const bind: unknown[] = [];
+    const sql = comparisonSql(
+      { field: 'id', op: '=', value: 'thread:A', paramRef: 'id' },
+      bind,
+      { id: 'thread:B' }
+    );
+    expect(sql).toBe('id = ?');
+    expect(bind).toEqual(['thread:B']);
+  });
+
+  it('falls back to the baked literal when the param key is absent', () => {
+    const bind: unknown[] = [];
+    comparisonSql({ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }, bind, {});
+    expect(bind).toEqual(['thread:A']);
+  });
+
+  it('a pure $-ref (no baked value) always reads the param', () => {
+    const bind: unknown[] = [];
+    comparisonSql({ field: 'owner', op: '=', value: undefined, paramRef: 'auth' }, bind, {
+      auth: 'user:1',
+    });
+    expect(bind).toEqual(['user:1']);
+  });
+
+  it('renders non-id fields via json_extract and honors swap', () => {
+    const bind: unknown[] = [];
+    const sql = comparisonSql({ field: 'votes', op: '<', value: 5, swap: true }, bind, {});
+    expect(sql).toBe(`? < json_extract(data, '$.votes')`);
+    expect(bind).toEqual([5]);
+  });
+});
+
+describe('renderWhereSql', () => {
+  it('joins top-level nodes with AND and parenthesizes OR groups', () => {
+    const nodes: WhereNode[] = [
+      { field: 'kind', op: '=', value: 'a' },
+      {
+        or: [
+          { field: 'votes', op: '>', value: 1 },
+          { field: 'votes', op: '=', value: 0 },
+        ],
+      },
+    ];
+    const bind: unknown[] = [];
+    const sql = renderWhereSql(nodes, bind, {});
+    expect(sql).toBe(
+      `json_extract(data, '$.kind') = ? AND (json_extract(data, '$.votes') > ? OR json_extract(data, '$.votes') = ?)`
+    );
+    expect(bind).toEqual(['a', 1, 0]);
+  });
+});
+
+describe('renderOrderSql', () => {
+  it('renders multi-key ordering', () => {
+    expect(renderOrderSql([['a', 'desc'], ['b', 'asc']])).toBe(
+      ` ORDER BY json_extract(data, '$.a') DESC, json_extract(data, '$.b') ASC`
+    );
+  });
+});
+
+describe('scalar', () => {
+  it('binds RecordId-shaped objects as table:id strings', () => {
+    expect(scalar({ tb: 'user', id: '1' })).toBe('user:1');
+    expect(scalar('plain')).toBe('plain');
+    expect(scalar(3)).toBe(3);
+    expect(scalar(null)).toBeNull();
+    expect(scalar(undefined)).toBeNull();
+  });
+});
+
+describe('serializeRow / reviveRow round-trip', () => {
+  it('tags Uint8Array as {__u8} and revives it', () => {
+    const json = serializeRow({ id: 's:1', blob: new Uint8Array([0, 128, 255]) });
+    expect(json).toContain('"__u8"');
+    const back = reviveRow(json);
+    expect(back.blob).toBeInstanceOf(Uint8Array);
+    expect([...(back.blob as Uint8Array)]).toEqual([0, 128, 255]);
+  });
+
+  it('serializes RecordId-shaped links to strings and takes the fast parse path otherwise', () => {
+    const json = serializeRow({ id: 't:1', author: { tb: 'user', id: 'u1' }, n: 2 });
+    expect(reviveRow(json)).toEqual({ id: 't:1', author: 'user:u1', n: 2 });
+  });
+});
+
+describe('project', () => {
+  it('keeps id plus the listed fields only, skipping absent ones', () => {
+    expect(project({ id: 'a', x: 1, y: 2 }, ['x', 'missing'])).toEqual({ id: 'a', x: 1 });
+  });
+});

package/src/services/database/sqlite-plan-sql.ts

@@ -0,0 +1,106 @@
+import type { WhereComparison, WhereNode } from '@spooky-sync/query-builder';
+import { stableKey } from './relation-resolver';
+import type { OrderBy, Row } from './cache-engine';
+
+/**
+ * SQL rendering + value (de)serialization for the SQLite cache backend.
+ * Extracted from `sqlite-cache-engine.ts` so BOTH sides of the worker boundary
+ * can use it: the engine (main thread) for the legacy/shim paths, and
+ * `sqlite-worker.ts` for worker-side plan execution (`select`). Pure module —
+ * no DOM, no worker, no engine imports — mirroring `plan-render.ts`.
+ */
+
+export function renderOrderSql(orderBy: OrderBy): string {
+  return ` ORDER BY ${orderBy
+    .map(([f, d]) => `json_extract(data, '$.${f}') ${d === 'desc' ? 'DESC' : 'ASC'}`)
+    .join(', ')}`;
+}
+
+export function comparisonSql(
+  c: WhereComparison,
+  bind: unknown[],
+  params: Record<string, unknown>
+): string {
+  const lhs = c.field === 'id' ? 'id' : `json_extract(data, '$.${c.field}')`;
+  // Prefer the query's own param so a filter materializes from `params` (the
+  // query's identity), not a baked literal. A pure `$`-ref has no `value`; a
+  // slave-mode node keeps `value` as a fallback for a param absent from params.
+  const useParam =
+    c.paramRef !== undefined &&
+    (c.value === undefined || Object.prototype.hasOwnProperty.call(params, c.paramRef));
+  const value = useParam ? params[c.paramRef!] : c.value;
+  bind.push(scalar(value));
+  const op = c.op === '!=' ? '!=' : c.op;
+  return c.swap ? `? ${op} ${lhs}` : `${lhs} ${op} ?`;
+}
+
+export function renderWhereSql(
+  nodes: WhereNode[],
+  bind: unknown[],
+  params: Record<string, unknown>
+): string {
+  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 ');
+}
+
+// ==================== value (de)serialization ====================
+
+/** A comparable scalar for SQL binding: record links → `table:id`, everything
+ *  else passed through (numbers/strings/bools). */
+export function scalar(value: unknown): unknown {
+  if (value == null) return null;
+  if (typeof value === 'object') return stableKey(value);
+  return value;
+}
+
+export function serializeRow(row: Row): string {
+  return JSON.stringify(row, (_k, v) => {
+    if (v instanceof Uint8Array) return { __u8: toBase64(v) };
+    if (v && typeof v === 'object') {
+      const rid = v as { tb?: unknown; id?: unknown };
+      if (rid.tb !== undefined && rid.id !== undefined) return stableKey(v);
+    }
+    return v;
+  });
+}
+
+export function reviveRow(json: string): Row {
+  // Fast path: the per-key reviver is only needed to rebuild `Uint8Array`s from
+  // `{__u8}` tags. Most rows (e.g. game bodies) have none — a plain parse avoids
+  // invoking a JS callback for every key of every row on the read hot path.
+  if (json.indexOf('"__u8"') === -1) return JSON.parse(json);
+  return JSON.parse(json, (_k, v) => {
+    if (v && typeof v === 'object' && typeof (v as any).__u8 === 'string') {
+      return fromBase64((v as any).__u8);
+    }
+    return v;
+  });
+}
+
+export function project(row: Row, fields: string[]): Row {
+  const out: Row = {};
+  for (const f of ['id', ...fields]) if (f in row) out[f] = row[f];
+  return out;
+}
+
+export function toBase64(bytes: Uint8Array): string {
+  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');
+}
+
+export function fromBase64(b64: string): Uint8Array {
+  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'));
+}

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,279 @@
+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 { 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 }
+  );
+  (engine as any).spawnWorker = () => {
+    const w: any = {
+      onerror: null,
+      onmessageerror: null,
+      terminate() {},
+      postMessage(msg: any) {
+        calls.push({
+          type: msg.type,
+          sql: msg.payload?.sql,
+          bind: msg.payload?.bind,
+          payload: msg.payload,
+        });
+        Promise.resolve().then(async () => {
+          let ok = true;
+          let error: string | undefined;
+          let rest: Record<string, unknown> = {};
+          try {
+            if (msg.type === 'open') rest = { persisted: false };
+            else if (msg.type === 'exec') rest = { rows: respond(msg.payload.sql, msg.payload.bind ?? []) };
+            else if (msg.type === 'run' || msg.type === 'batch' || msg.type === 'close') rest = {};
+            else if (msg.type === 'select') {
+              if (!opts.answerSelect) throw new Error(`sqlite worker: unknown message ${msg.type}`);
+              const dbCalls: { sql: string; bind?: unknown[] }[] = [];
+              rest = await executeSelect(
+                msg.payload.plan,
+                msg.payload.params ?? {},
+                makeSelectDb(FIXTURE, dbCalls)
+              );
+            } else throw new Error(`sqlite worker: unknown message ${msg.type}`);
+          } catch (e) {
+            ok = false;
+            error = e instanceof Error ? e.message : String(e);
+          }
+          (engine as any).worker &&
+            (engine as any).pending.get(msg.id) &&
+            ((): void => {
+              const p = (engine as any).pending.get(msg.id);
+              (engine as any).pending.delete(msg.id);
+              if (ok) p.resolve(rest);
+              else p.reject(new Error(error));
+            })();
+        });
+      },
+    };
+    return w;
+  };
+  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);
+  });
+});