@spooky-sync/core 0.0.1-canary.13 → 0.0.1-canary.131

package/src/services/database/plan-render.ts

@@ -0,0 +1,100 @@
+import type { QueryPlan, WhereNode, WhereComparison } from '@spooky-sync/query-builder';
+import type { OrderBy, RelationFetch } from './cache-engine';
+
+/**
+ * Render helpers that turn an engine-neutral {@link QueryPlan} into a concrete
+ * dialect. Two consumers: `SurrealCacheEngine` (SurrealQL) and, indirectly, the
+ * SQLite worker (which uses the SQL variants). Relations are NOT rendered here —
+ * they are resolved by `resolveRelations` via the {@link RelationFetch}
+ * primitive, so both engines share the exact same decomposition.
+ */
+
+export interface RenderedQuery {
+  sql: string;
+  vars: Record<string, unknown>;
+}
+
+interface RenderCtx {
+  vars: Record<string, unknown>;
+  n: number;
+}
+
+function bind(ctx: RenderCtx, value: unknown): string {
+  const name = `__p${ctx.n++}`;
+  ctx.vars[name] = value;
+  return `$${name}`;
+}
+
+function renderComparisonSurql(c: WhereComparison, ctx: RenderCtx): string {
+  const rawRight = c.paramRef ? `$${c.paramRef}` : bind(ctx, c.value);
+  // `id` is a RecordId, but correlation/filter values arrive as record-id
+  // STRINGS (e.g. "thread:abc"). On SurrealDB `id = "thread:abc"` never matches
+  // (string ≠ record), so a base select filtered by id (e.g. the ThreadDetail
+  // query `… FROM thread WHERE id = $id`) resolves empty — and its whole
+  // `.related()` subtree (author, comments) then loads nothing. Coerce with
+  // `type::record(<string> …)` (idempotent if already a RecordId), mirroring
+  // renderRelationFetchSurql's matchField coercion.
+  const right =
+    c.field === 'id' ? `type::record(<string> ${rawRight})` : rawRight;
+  return c.swap ? `${right} ${c.op} ${c.field}` : `${c.field} ${c.op} ${right}`;
+}
+
+/** Render a WHERE conjunction (AND of comparisons / OR-groups) to SurrealQL. */
+export function renderWhereSurql(nodes: WhereNode[], ctx: RenderCtx): string {
+  return nodes
+    .map((node) => {
+      if ('or' in node) {
+        return `(${node.or.map((c) => renderComparisonSurql(c, ctx)).join(' OR ')})`;
+      }
+      return renderComparisonSurql(node, ctx);
+    })
+    .join(' AND ');
+}
+
+function renderOrderBy(orderBy: OrderBy): string {
+  return ` ORDER BY ${orderBy.map(([f, d]) => `${f} ${d}`).join(', ')}`;
+}
+
+/**
+ * Render the BASE of a SELECT (no relations) to SurrealQL. `params` supplies
+ * pre-existing bound params (e.g. `$__win` for windowing, or `paramRef` values)
+ * and is merged into the returned vars.
+ */
+export function renderBaseSelectSurql(
+  plan: QueryPlan,
+  params: Record<string, unknown> = {}
+): RenderedQuery {
+  const ctx: RenderCtx = { vars: { ...params }, n: 0 };
+  const projection = plan.select && plan.select.length > 0 ? plan.select.join(', ') : '*';
+  let sql = `SELECT ${projection} FROM ${plan.table}`;
+  if (plan.where && plan.where.length > 0) {
+    sql += ` WHERE ${renderWhereSurql(plan.where, ctx)}`;
+  }
+  if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderBy(plan.orderBy);
+  if (plan.limit !== undefined) sql += ` LIMIT ${plan.limit}`;
+  if (plan.offset !== undefined) sql += ` START ${plan.offset}`;
+  return { sql: `${sql};`, vars: ctx.vars };
+}
+
+/**
+ * Render a batched relation fetch to SurrealQL:
+ * `SELECT <select> FROM <table> WHERE <matchField> IN $__keys [AND <where>] [ORDER BY]`.
+ * The resolver re-applies per-parent ORDER/LIMIT after grouping, so LIMIT is
+ * intentionally omitted here.
+ */
+export function renderRelationFetchSurql(req: RelationFetch): RenderedQuery {
+  const ctx: RenderCtx = { vars: { __keys: req.keys }, n: 0 };
+  const projection =
+    req.select && req.select.length > 0 ? ['id', ...req.select].join(', ') : '*';
+  // The correlation keys arrive as record-id STRINGS (`"user:abc"`), but the
+  // matched column (`id`, or a `record<…>` foreign key) is a RecordId. In
+  // SurrealDB `id IN ["user:abc"]` never matches (string ≠ record), so every
+  // `.related()` field would resolve empty. Coerce each key to a record id with
+  // `type::record(<string> …)` (idempotent if a key is already a RecordId).
+  let sql = `SELECT ${projection} FROM ${req.table} WHERE ${req.matchField} IN $__keys.map(|$__k| type::record(<string> $__k))`;
+  if (req.where && req.where.length > 0) {
+    sql += ` AND ${renderWhereSurql(req.where, ctx)}`;
+  }
+  if (req.orderBy && req.orderBy.length > 0) sql += renderOrderBy(req.orderBy);
+  return { sql: `${sql};`, vars: ctx.vars };
+}

package/src/services/database/relation-resolver.test.ts

@@ -0,0 +1,413 @@
+import { describe, it, expect } from 'vitest';
+import type { RelationPlan, WhereNode } from '@spooky-sync/query-builder';
+import { resolveRelations, sortRows, stableKey } from './relation-resolver';
+import {
+  RelationCycleError,
+  type RelationFetch,
+  type Row,
+  type RowFetcher,
+} from './cache-engine';
+
+/**
+ * Deterministic in-memory store used as the reference for decomposition. It
+ * implements the SAME fetch primitive the real engines expose
+ * (`WHERE matchField IN keys AND <where>`, ORDER BY, projection) so a passing
+ * resolver here is correct independent of SurrealDB/SQLite specifics. Rows are
+ * deep-cloned on read (as a real engine returns fresh objects), so nested
+ * attachment never mutates the store.
+ */
+class MemStore implements RowFetcher {
+  constructor(private tables: Record<string, Row[]>) {}
+
+  async fetchRelation(req: RelationFetch): Promise<Row[]> {
+    const keySet = new Set(req.keys.map(stableKey));
+    let rows = (this.tables[req.table] ?? []).filter((r) =>
+      keySet.has(stableKey(r[req.matchField]))
+    );
+    if (req.where) rows = rows.filter((r) => matchesWhere(r, req.where!));
+    rows = rows.map((r) => structuredClone(r));
+    if (req.orderBy) rows = sortRows(rows, req.orderBy);
+    if (req.select) {
+      rows = rows.map((r) => {
+        const out: Row = {};
+        for (const f of ['id', ...req.select!]) if (f in r) out[f] = r[f];
+        return out;
+      });
+    }
+    return rows;
+  }
+}
+
+function matchesWhere(row: Row, where: WhereNode[]): boolean {
+  const cmp = (c: { field: string; op: string; value: unknown }): boolean => {
+    const v = row[c.field];
+    switch (c.op) {
+      case '=':
+        return stableKey(v) === stableKey(c.value);
+      case '!=':
+        return stableKey(v) !== stableKey(c.value);
+      case '>':
+        return (v as number) > (c.value as number);
+      case '>=':
+        return (v as number) >= (c.value as number);
+      case '<':
+        return (v as number) < (c.value as number);
+      case '<=':
+        return (v as number) <= (c.value as number);
+      default:
+        return false;
+    }
+  };
+  return where.every((node) => {
+    if ('or' in node) return node.or.some(cmp);
+    return cmp(node);
+  });
+}
+
+// Convenience builder for a RelationPlan.
+function rel(p: Partial<RelationPlan> & Pick<RelationPlan, 'alias' | 'table' | 'cardinality' | 'foreignKeyField'>): RelationPlan {
+  return p as RelationPlan;
+}
+
+describe('resolveRelations — decomposition', () => {
+  it('1. flat, no relations: leaves parents untouched', async () => {
+    const store = new MemStore({});
+    const parents: Row[] = [{ id: 'post:1', title: 'a' }];
+    await resolveRelations(parents, undefined, store);
+    expect(parents).toEqual([{ id: 'post:1', title: 'a' }]);
+  });
+
+  it('2a. one-to-one match: attaches the single related row', async () => {
+    const store = new MemStore({ user: [{ id: 'user:1', name: 'ana' }] });
+    const parents: Row[] = [{ id: 'post:1', author: 'user:1' }];
+    await resolveRelations(
+      parents,
+      [rel({ alias: 'author', table: 'user', cardinality: 'one', foreignKeyField: 'author', limit: 1 })],
+      store
+    );
+    expect(parents[0].author).toEqual({ id: 'user:1', name: 'ana' });
+  });
+
+  it('2b. one-to-one no match: attaches null', async () => {
+    const store = new MemStore({ user: [] });
+    const parents: Row[] = [{ id: 'post:1', author: 'user:404' }];
+    await resolveRelations(
+      parents,
+      [rel({ alias: 'author', table: 'user', cardinality: 'one', foreignKeyField: 'author', limit: 1 })],
+      store
+    );
+    expect(parents[0].author).toBeNull();
+  });
+
+  it('3. one-to-many: empty vs N children grouped per parent', async () => {
+    const store = new MemStore({
+      comment: [
+        { id: 'comment:1', post: 'post:1', body: 'x' },
+        { id: 'comment:2', post: 'post:1', body: 'y' },
+        { id: 'comment:3', post: 'post:2', body: 'z' },
+      ],
+    });
+    const parents: Row[] = [{ id: 'post:1' }, { id: 'post:2' }, { id: 'post:3' }];
+    await resolveRelations(
+      parents,
+      [rel({ alias: 'comments', table: 'comment', cardinality: 'many', foreignKeyField: 'post' })],
+      store
+    );
+    expect((parents[0].comments as Row[]).map((c) => c.id)).toEqual(['comment:1', 'comment:2']);
+    expect((parents[1].comments as Row[]).map((c) => c.id)).toEqual(['comment:3']);
+    expect(parents[2].comments).toEqual([]);
+  });
+
+  it('4. per-parent LIMIT + ORDER applied within each group, not globally', async () => {
+    const store = new MemStore({
+      comment: [
+        { id: 'comment:1', post: 'post:1', rank: 3 },
+        { id: 'comment:2', post: 'post:1', rank: 1 },
+        { id: 'comment:3', post: 'post:1', rank: 2 },
+        { id: 'comment:4', post: 'post:2', rank: 5 },
+        { id: 'comment:5', post: 'post:2', rank: 4 },
+      ],
+    });
+    const parents: Row[] = [{ id: 'post:1' }, { id: 'post:2' }];
+    await resolveRelations(
+      parents,
+      [
+        rel({
+          alias: 'comments',
+          table: 'comment',
+          cardinality: 'many',
+          foreignKeyField: 'post',
+          orderBy: [['rank', 'asc']],
+          limit: 2,
+        }),
+      ],
+      store
+    );
+    // post:1 keeps its OWN top-2 by rank (1,2) — not a global top-2 (which would
+    // have starved post:2).
+    expect((parents[0].comments as Row[]).map((c) => c.rank)).toEqual([1, 2]);
+    expect((parents[1].comments as Row[]).map((c) => c.rank)).toEqual([4, 5]);
+  });
+
+  it('5. sub-where filters the relation batch', async () => {
+    const store = new MemStore({
+      comment: [
+        { id: 'comment:1', post: 'post:1', hidden: false },
+        { id: 'comment:2', post: 'post:1', hidden: true },
+      ],
+    });
+    const parents: Row[] = [{ id: 'post:1' }];
+    await resolveRelations(
+      parents,
+      [
+        rel({
+          alias: 'comments',
+          table: 'comment',
+          cardinality: 'many',
+          foreignKeyField: 'post',
+          where: [{ field: 'hidden', op: '=', value: false }],
+        }),
+      ],
+      store
+    );
+    expect((parents[0].comments as Row[]).map((c) => c.id)).toEqual(['comment:1']);
+  });
+
+  it('6. 2-level nested with cross-level $parent dependency (many -> one)', async () => {
+    const store = new MemStore({
+      comment: [
+        { id: 'comment:1', post: 'post:1', author: 'user:1' },
+        { id: 'comment:2', post: 'post:1', author: 'user:2' },
+      ],
+      user: [
+        { id: 'user:1', name: 'ana' },
+        { id: 'user:2', name: 'bob' },
+      ],
+    });
+    const parents: Row[] = [{ id: 'post:1' }];
+    await resolveRelations(
+      parents,
+      [
+        rel({
+          alias: 'comments',
+          table: 'comment',
+          cardinality: 'many',
+          foreignKeyField: 'post',
+          relations: [
+            rel({ alias: 'author', table: 'user', cardinality: 'one', foreignKeyField: 'author', limit: 1 }),
+          ],
+        }),
+      ],
+      store
+    );
+    const comments = parents[0].comments as Row[];
+    expect(comments.map((c) => (c.author as Row).name)).toEqual(['ana', 'bob']);
+  });
+
+  it('7. 3-level deep, mixed cardinality, O(depth) batch count', async () => {
+    let batches = 0;
+    const base = new MemStore({
+      comment: [{ id: 'comment:1', post: 'post:1', author: 'user:1' }],
+      user: [{ id: 'user:1', org: 'org:1' }],
+      org: [{ id: 'org:1', name: 'acme' }],
+    });
+    const counting: RowFetcher = {
+      fetchRelation: (req) => {
+        batches++;
+        return base.fetchRelation(req);
+      },
+    };
+    const parents: Row[] = [{ id: 'post:1' }];
+    await resolveRelations(
+      parents,
+      [
+        rel({
+          alias: 'comments',
+          table: 'comment',
+          cardinality: 'many',
+          foreignKeyField: 'post',
+          relations: [
+            rel({
+              alias: 'author',
+              table: 'user',
+              cardinality: 'one',
+              foreignKeyField: 'author',
+              limit: 1,
+              relations: [
+                rel({ alias: 'org', table: 'org', cardinality: 'one', foreignKeyField: 'org', limit: 1 }),
+              ],
+            }),
+          ],
+        }),
+      ],
+      counting
+    );
+    const org = ((parents[0].comments as Row[])[0].author as Row).org as Row;
+    expect(org.name).toBe('acme');
+    // One batch per level (3 levels), NOT per row.
+    expect(batches).toBe(3);
+  });
+
+  it('8. null/absent foreign keys mid-tree yield empty, no spurious fetch', async () => {
+    let fetchedKeys: unknown[] = [];
+    const base = new MemStore({ user: [{ id: 'user:1', name: 'ana' }] });
+    const spy: RowFetcher = {
+      fetchRelation: (req) => {
+        fetchedKeys = req.keys;
+        return base.fetchRelation(req);
+      },
+    };
+    const parents: Row[] = [
+      { id: 'post:1', author: 'user:1' },
+      { id: 'post:2', author: null },
+      { id: 'post:3' }, // absent
+    ];
+    await resolveRelations(
+      parents,
+      [rel({ alias: 'author', table: 'user', cardinality: 'one', foreignKeyField: 'author', limit: 1 })],
+      spy
+    );
+    expect(fetchedKeys).toEqual(['user:1']); // null/absent excluded
+    expect(parents[0].author).toEqual({ id: 'user:1', name: 'ana' });
+    expect(parents[1].author).toBeNull();
+    expect(parents[2].author).toBeNull();
+  });
+
+  it('9. nesting past MAX_RELATION_DEPTH throws RelationCycleError', async () => {
+    // Build a plan nested deeper than the guard.
+    let leaf: RelationPlan = rel({ alias: 'r', table: 't', cardinality: 'one', foreignKeyField: 'r' });
+    for (let i = 0; i < 20; i++) {
+      leaf = rel({ alias: 'r', table: 't', cardinality: 'one', foreignKeyField: 'r', relations: [leaf] });
+    }
+    const store = new MemStore({ t: [{ id: 't:1', r: 't:1' }] });
+    await expect(resolveRelations([{ id: 't:1', r: 't:1' }], [leaf], store)).rejects.toBeInstanceOf(
+      RelationCycleError
+    );
+  });
+
+  it('10. RecordId-shaped keys group identically to their string form', async () => {
+    // Parent FK is a RecordId-like object; child id is the string form.
+    const rid = { tb: 'user', id: '1', toString: () => 'user:1' };
+    const store = new MemStore({ user: [{ id: 'user:1', name: 'ana' }] });
+    const parents: Row[] = [{ id: 'post:1', author: rid }];
+    await resolveRelations(
+      parents,
+      [rel({ alias: 'author', table: 'user', cardinality: 'one', foreignKeyField: 'author', limit: 1 })],
+      store
+    );
+    expect((parents[0].author as Row).name).toBe('ana');
+    // alias appended LAST (key order parity with `SELECT *, <sub> AS alias`).
+    expect(Object.keys(parents[0])).toEqual(['id', 'author']);
+  });
+});
+
+describe('stableKey', () => {
+  it('collapses RecordId object and string form', () => {
+    expect(stableKey({ tb: 'user', id: '1' })).toBe('user:1');
+    expect(stableKey('user:1')).toBe('user:1');
+  });
+});
+
+/**
+ * Independent, obviously-correct reference resolver: for each parent, fetch its
+ * relations directly (no batching, no dedup) and recurse. The batched
+ * `resolveRelations` must produce byte-identical output for random trees.
+ */
+async function naiveResolve(parents: Row[], relations: RelationPlan[] | undefined, store: MemStore): Promise<void> {
+  if (!relations) return;
+  for (const parent of parents) {
+    for (const r of relations) {
+      const isOne = r.cardinality === 'one';
+      const key = isOne ? parent[r.foreignKeyField] : parent['id'];
+      let bucket: Row[] = [];
+      if (key != null) {
+        bucket = await store.fetchRelation({
+          table: r.table,
+          matchField: isOne ? 'id' : r.foreignKeyField,
+          keys: [key],
+          where: r.where,
+          orderBy: r.orderBy,
+          select: r.select,
+        });
+        await naiveResolve(bucket, r.relations, store);
+      }
+      if (r.orderBy) bucket = sortRows(bucket, r.orderBy);
+      if (r.limit !== undefined) bucket = bucket.slice(0, r.limit);
+      parent[r.alias] = isOne ? bucket[0] ?? null : bucket;
+    }
+  }
+}
+
+// Tiny seeded PRNG so failures reproduce (Math.random is nondeterministic).
+function mulberry32(seed: number): () => number {
+  return () => {
+    seed |= 0;
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+describe('resolveRelations — property: batched == naive over random trees', () => {
+  const TABLES = ['a', 'b', 'c', 'd'];
+
+  it('matches the naive reference for 200 random datasets/plans', async () => {
+    for (let seed = 0; seed < 200; seed++) {
+      const rng = mulberry32(seed + 1);
+      const pick = <T,>(arr: T[]): T => arr[Math.floor(rng() * arr.length)];
+
+      // Random dataset: each table gets a few rows with random FK fields.
+      const tables: Record<string, Row[]> = {};
+      for (const t of TABLES) {
+        const n = Math.floor(rng() * 5);
+        tables[t] = [];
+        for (let i = 0; i < n; i++) {
+          tables[t].push({
+            id: `${t}:${i}`,
+            rank: Math.floor(rng() * 5),
+            // FK columns pointing at every table (some valid, some dangling).
+            ...Object.fromEntries(
+              TABLES.map((ft) => [`${ft}_fk`, rng() < 0.7 ? `${ft}:${Math.floor(rng() * 5)}` : null])
+            ),
+          });
+        }
+      }
+
+      // Random relation tree, depth <= 4.
+      const buildPlan = (depth: number): RelationPlan[] => {
+        if (depth > 4 || rng() < 0.35) return [];
+        const count = Math.floor(rng() * 2) + 1;
+        const out: RelationPlan[] = [];
+        for (let i = 0; i < count; i++) {
+          const table = pick(TABLES);
+          const cardinality = rng() < 0.5 ? 'one' : 'many';
+          out.push(
+            rel({
+              alias: `rel_${depth}_${i}`,
+              table,
+              cardinality,
+              foreignKeyField: cardinality === 'one' ? `${table}_fk` : `${pick(TABLES)}_fk`,
+              orderBy: rng() < 0.5 ? [['rank', pick(['asc', 'desc'] as const)]] : undefined,
+              limit: rng() < 0.5 ? Math.floor(rng() * 3) + 1 : undefined,
+              relations: buildPlan(depth + 1),
+            })
+          );
+        }
+        return out;
+      };
+      const plan = buildPlan(0);
+
+      const rootTable = pick(TABLES);
+      const roots = (tables[rootTable] ?? []).map((r) => structuredClone(r));
+      if (roots.length === 0) continue;
+
+      const batched = structuredClone(roots);
+      const naive = structuredClone(roots);
+      await resolveRelations(batched, plan, new MemStore(structuredClone(tables)));
+      await naiveResolve(naive, plan, new MemStore(structuredClone(tables)));
+
+      expect(batched, `seed ${seed}`).toEqual(naive);
+    }
+  });
+});

package/src/services/database/remote.ts

@@ -1,20 +1,20 @@
+import type {
+  Diagnostic} from 'surrealdb';
 import {
   applyDiagnostics,
   createRemoteEngines,
-  Diagnostic,
   Surreal,
-  SurrealTransaction,
 } from 'surrealdb';
-import { SpookyConfig } from '../../types';
-import { Logger } from '../logger/index';
+import type { Sp00kyConfig } from '../../types';
+import type { Logger } from '../logger/index';
 import { AbstractDatabaseService } from './database';
 import { createDatabaseEventSystem, DatabaseEventTypes } from './events/index';
 
 export class RemoteDatabaseService extends AbstractDatabaseService {
-  private config: SpookyConfig<any>['database'];
+  private config: Sp00kyConfig<any>['database'];
   protected eventType = DatabaseEventTypes.RemoteQuery;
 
-  constructor(config: SpookyConfig<any>['database'], logger: Logger) {
+  constructor(config: Sp00kyConfig<any>['database'], logger: Logger) {
     const events = createDatabaseEventSystem();
     super(
       new Surreal({
@@ -29,7 +29,7 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
                   type,
                   phase,
                   service: 'surrealdb:remote',
-                  Category: 'spooky-client::RemoteDatabaseService::diagnostics',
+                  Category: 'sp00ky-client::RemoteDatabaseService::diagnostics',
                 },
                 `Remote SurrealDB diagnostics captured ${type}:${phase}`
               );
@@ -43,7 +43,7 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
     this.config = config;
   }
 
-  getConfig(): SpookyConfig<any>['database'] {
+  getConfig(): Sp00kyConfig<any>['database'] {
     return this.config;
   }
 
@@ -55,7 +55,7 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
           endpoint,
           namespace,
           database,
-          Category: 'spooky-client::RemoteDatabaseService::connect',
+          Category: 'sp00ky-client::RemoteDatabaseService::connect',
         },
         'Connecting to remote database'
       );
@@ -68,25 +68,25 @@ export class RemoteDatabaseService extends AbstractDatabaseService {
 
         if (token) {
           this.logger.debug(
-            { Category: 'spooky-client::RemoteDatabaseService::connect' },
+            { Category: 'sp00ky-client::RemoteDatabaseService::connect' },
             'Authenticating with token'
           );
           await this.client.authenticate(token);
         }
         this.logger.info(
-          { Category: 'spooky-client::RemoteDatabaseService::connect' },
+          { Category: 'sp00ky-client::RemoteDatabaseService::connect' },
           'Connected to remote database'
         );
       } catch (err) {
         this.logger.error(
-          { err, Category: 'spooky-client::RemoteDatabaseService::connect' },
+          { err, Category: 'sp00ky-client::RemoteDatabaseService::connect' },
           'Failed to connect to remote database'
         );
         throw err;
       }
     } else {
       this.logger.warn(
-        { Category: 'spooky-client::RemoteDatabaseService::connect' },
+        { Category: 'sp00ky-client::RemoteDatabaseService::connect' },
         'No endpoint configured for remote database'
       );
     }

package/src/services/database/sqlite-cache-engine.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { pureWriteOpResult } from './sqlite-cache-engine';
+import { translateSurql } from './surql-translate';
+import type { SqlOp } from './surql-translate';
+import { surql } from '../../utils/surql';
+
+// `pureWriteOpResult` is the single source of truth for what a pure-write op
+// contributes to a query's per-statement results. The batched fast path in
+// `query()` and the per-op `execOp` path BOTH route through it, so a caller that
+// reads a statement's output (e.g. `create()` reads `resultIndex:0` for the new
+// row + its id) sees the same shape either way.
+describe('pureWriteOpResult', () => {
+  it('echoes the written row (with id) for an upsert — no read-back', () => {
+    const op: SqlOp = {
+      kind: 'upsert',
+      id: 'connection:CONN_abc',
+      data: { provider: 'chesscom', username: 'hikaru' },
+      mode: 'replace',
+    };
+    expect(pureWriteOpResult(op)).toEqual({
+      provider: 'chesscom',
+      username: 'hikaru',
+      id: 'connection:CONN_abc',
+    });
+  });
+
+  it('stringifies a RecordId id via stableKey', () => {
+    const op: SqlOp = {
+      kind: 'upsert',
+      id: new RecordId('connection', 'CONN_abc'),
+      data: { provider: 'lichess' },
+      mode: 'replace',
+    };
+    expect(pureWriteOpResult(op)).toEqual({ provider: 'lichess', id: 'connection:CONN_abc' });
+  });
+
+  it('yields [] for delete / deleteAll and null for noop', () => {
+    expect(pureWriteOpResult({ kind: 'delete', id: 'game:1' })).toEqual([]);
+    expect(pureWriteOpResult({ kind: 'deleteAll', table: 'game' })).toEqual([]);
+    expect(pureWriteOpResult({ kind: 'noop' })).toBeNull();
+  });
+});
+
+// Regression: a single `create()` compiles to an all-upsert transaction
+// (createSet for the row + createMutation for the pending-mutation log) and
+// extracts `resultIndex:0` for the created row. The SQLite fast path must return
+// that row (with its id) at that index — returning `[]` there dropped the id and
+// crashed the reconcile in `encodeRecordId` ("reading 'table'").
+describe('create() tx result shaping (fast path parity)', () => {
+  it('resultIndex:0 carries the created row with its id', () => {
+    const rid = new RecordId('connection', 'CONN_abc');
+    const mid = new RecordId('_00_pending_mutations', '1');
+    const vars = {
+      id: rid,
+      mid,
+      data_provider: 'chesscom',
+      data_username: 'hikaru',
+    };
+
+    // Same statement pair DataModule.create emits.
+    const sealed = surql.seal(
+      surql.tx([
+        surql.createSet('id', [
+          { key: 'provider', variable: 'data_provider' },
+          { key: 'username', variable: 'data_username' },
+        ]),
+        surql.createMutation('create', 'mid', 'id', 'data'),
+      ]),
+      { resultIndex: 0 }
+    );
+
+    const { transaction, ops } = translateSurql(sealed.sql, vars);
+    expect(transaction).toBe(true);
+    // Both statements are upserts → the engine takes the all-write fast path.
+    expect(ops.every((o) => o.kind === 'upsert')).toBe(true);
+
+    // Fast-path shaping: [null (BEGIN), ...one result per statement].
+    const shaped = [null, ...ops.map(pureWriteOpResult)];
+    const created = sealed.extract(shaped) as unknown as { id: unknown; provider: string };
+
+    expect(created.id).toBe('connection:CONN_abc');
+    expect(created.provider).toBe('chesscom');
+  });
+});