@spooky-sync/core 0.0.1-canary.33 → 0.0.1-canary.331

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

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { DatabaseSync } from 'node:sqlite';
+import { projectedDataSql, project, reviveRow, serializeRow } from './sqlite-plan-sql';
+import type { Row } from './cache-engine';
+
+/**
+ * `projectedDataSql` is the one change in this area that alters what SQLite
+ * actually returns, and every row read goes through it — so it is verified
+ * against a REAL SQLite, not the scripted responder the parity tests use.
+ *
+ * The contract: byte-identical to parsing the whole row and running `project`
+ * over it, which is what both engine paths did before. The traps it has to
+ * clear are an ABSENT key (must stay absent, not become an explicit null — the
+ * difference `json_object`/`json_extract` would have introduced), a STORED
+ * null, nested objects/arrays, the `{__u8}` tag that carries binary, and a
+ * TOP-LEVEL boolean (SQLite has no boolean type, so an unguarded projection
+ * hands `true` back as the integer 1).
+ */
+
+function makeDb(rows: Row[]) {
+  const db = new DatabaseSync(':memory:');
+  db.exec('CREATE TABLE "game" (id TEXT PRIMARY KEY, data TEXT NOT NULL)');
+  const ins = db.prepare('INSERT INTO "game" (id,data) VALUES (?,?)');
+  for (const r of rows) ins.run(String(r.id), serializeRow(r));
+  return db;
+}
+
+/** What the code did before: read the whole row, parse it, then project. */
+function referenceRows(db: DatabaseSync, ids: string[], fields: string[]): Row[] {
+  const ph = ids.map(() => '?').join(', ');
+  return db
+    .prepare(`SELECT data FROM "game" WHERE id IN (${ph}) ORDER BY id ASC`)
+    .all(...ids)
+    .map((r) => project(reviveRow((r as { data: string }).data), fields));
+}
+
+/** What the code does now: let SQLite narrow the row before it is ever parsed. */
+function projectedRows(db: DatabaseSync, ids: string[], fields: string[]): Row[] {
+  const bind: unknown[] = [];
+  const col = projectedDataSql(fields, bind);
+  bind.push(...ids);
+  const ph = ids.map(() => '?').join(', ');
+  return db
+    .prepare(`SELECT ${col} FROM "game" WHERE id IN (${ph}) ORDER BY id ASC`)
+    .all(...(bind as string[]))
+    .map((r) => reviveRow((r as { data: string }).data));
+}
+
+const FIXTURE: Row[] = [
+  { id: 'game:1', white: 'player_name:PN_a', pgn: '[Event "x"]\n1. e4 e5', sort_index: -5 },
+  { id: 'game:2', white: null, pgn: 'heavy', sort_index: -3 }, // STORED null
+  { id: 'game:3', pgn: 'heavy', sort_index: -4 }, // 'white' ABSENT
+  { id: 'game:4', white: 'w', pgn: 'heavy', sort_index: -1, meta: { a: 1, b: [2, 3] } },
+  { id: 'game:5', white: 'w', pgn: 'heavy', sort_index: 0, rated: true, draw: false },
+];
+const IDS = ['game:1', 'game:2', 'game:3', 'game:4', 'game:5'];
+const FIELDS = ['white', 'sort_index', 'meta', 'rated', 'draw'];
+
+describe('projectedDataSql against real SQLite', () => {
+  it('is byte-identical to parse-then-project', () => {
+    const db = makeDb(FIXTURE);
+    expect(projectedRows(db, IDS, FIELDS)).toEqual(referenceRows(db, IDS, FIELDS));
+  });
+
+  it('never returns the fields that were not asked for', () => {
+    // The point of the change: `pgn` must not leave SQLite, so it is never
+    // parsed, never crosses the worker boundary, never reaches the store.
+    const db = makeDb(FIXTURE);
+    for (const row of projectedRows(db, IDS, FIELDS)) expect('pgn' in row).toBe(false);
+  });
+
+  it('keeps an absent key absent and a stored null null', () => {
+    const db = makeDb(FIXTURE);
+    const byId = new Map(projectedRows(db, IDS, FIELDS).map((r) => [r.id, r]));
+    expect('white' in byId.get('game:3')!).toBe(false); // absent stays absent
+    expect('white' in byId.get('game:2')!).toBe(true); // stored null is a real key
+    expect(byId.get('game:2')!.white).toBeNull();
+  });
+
+  it('round-trips nested objects and arrays as JSON, not as strings', () => {
+    const db = makeDb(FIXTURE);
+    const row = projectedRows(db, IDS, FIELDS).find((r) => r.id === 'game:4')!;
+    expect(row.meta).toEqual({ a: 1, b: [2, 3] });
+  });
+
+  it('round-trips binary through the {__u8} tag', () => {
+    const db = makeDb([{ id: 'game:9', blob: new Uint8Array([0, 1, 2]), pgn: 'heavy' }]);
+    const [row] = projectedRows(db, ['game:9'], ['blob']);
+    expect(row!.blob).toEqual(new Uint8Array([0, 1, 2]));
+  });
+
+  it('always includes id, even when it is not in the field list', () => {
+    const db = makeDb(FIXTURE);
+    for (const row of projectedRows(db, IDS, ['sort_index'])) expect(row.id).toBeTruthy();
+  });
+
+  it('round-trips a top-level boolean as a boolean, not as 1/0', () => {
+    // The bug this guards: `json_each` yields SQLite integers for JSON booleans,
+    // so a projected row read `rated: 1` and every `row.rated === true` in a
+    // consuming app went false as soon as the screen painted from the cache.
+    // WhitePawn's /explore detail page read exactly that as "this collection was
+    // unpublished or deleted by its author".
+    const db = makeDb(FIXTURE);
+    const row = projectedRows(db, IDS, FIELDS).find((r) => r.id === 'game:5')!;
+    expect(row.rated).toBe(true);
+    expect(row.draw).toBe(false);
+  });
+
+  it('leaves a boolean nested in an object or array alone', () => {
+    const db = makeDb([{ id: 'game:7', flags: { on: true, off: false }, list: [true, false] }]);
+    const [row] = projectedRows(db, ['game:7'], ['flags', 'list']);
+    expect(row!.flags).toEqual({ on: true, off: false });
+    expect(row!.list).toEqual([true, false]);
+  });
+
+  it('yields an empty object, not NULL, for a row sharing none of the keys', () => {
+    // Without COALESCE the subquery returns NULL here and reviveRow throws.
+    const db = makeDb([{ id: 'game:8', pgn: 'heavy' }]);
+    expect(projectedRows(db, ['game:8'], ['nothing_matches'])).toEqual([{ id: 'game:8' }]);
+  });
+});

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,261 @@
+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' },
+  ],
+  game: [
+    { id: 'game:476gsdlvro7cme8nwied', white: 'player_name:a' },
+    { id: 'game:stgyqp7fm3sc4tmyc8fm', white: 'player_name:b' },
+  ],
+};
+
+/** 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');
+    const rows = await engine.select({ table: 'comment', ids: [rid, 'comment:1'] }, {});
+    const sel = calls.find((c) => c.type === 'select')!;
+    // The raw spelling the rows are stored under, never the SDK's escaped
+    // `comment:⟨2⟩`: that one matched no stored row.
+    expect(sel.payload.plan.ids).toEqual(['comment:2', 'comment:1']);
+    expect(rows.map((r) => r.id)).toEqual(['comment:2', 'comment:1']);
+  });
+
+  it('finds a window row whose id starts with a digit (SDK 2.1.0 escapes it)', async () => {
+    // `materializeEffect` parses every window id into a RecordId, and SDK
+    // 2.1.0's `toString()` spells this one `game:⟨476g…⟩`. Keyed that way the
+    // row went missing, the window came back short and read as the list end.
+    const { engine } = makeEngine({ workerSelect: true, answerSelect: true });
+    await engine.connect('anon');
+    const ids = [new RecordId('game', '476gsdlvro7cme8nwied'), new RecordId('game', 'stgyqp7fm3sc4tmyc8fm')];
+    const rows = await engine.select({ table: 'game', ids }, {});
+    expect(rows.map((r) => r.id)).toEqual(['game:476gsdlvro7cme8nwied', 'game:stgyqp7fm3sc4tmyc8fm']);
+  });
+
+  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);
+  });
+});