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

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

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { renderBaseSelectSurql, renderRelationFetchSurql } from './plan-render';
+import { buildWindowMaterializationPlan } from '../../modules/data/window-query';
+
+describe('renderBaseSelectSurql', () => {
+  it('renders projection, where, order, limit, offset', () => {
+    const plan: QueryPlan = {
+      table: 'post',
+      select: ['title', 'body'],
+      where: [{ field: 'published', op: '=', value: true }],
+      orderBy: [['created', 'desc']],
+      limit: 10,
+      offset: 20,
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT title, body FROM post WHERE published = $__p0 ORDER BY created desc LIMIT 10 START 20;');
+    expect(vars).toEqual({ __p0: true });
+  });
+
+  it('renders OR groups and comparison ops', () => {
+    const plan: QueryPlan = {
+      table: 'game',
+      where: [
+        { or: [{ field: 'white', op: '=', value: 'u:1' }, { field: 'black', op: '=', value: 'u:1' }] },
+        { field: 'moves', op: '>=', value: 5 },
+      ],
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT * FROM game WHERE (white = $__p0 OR black = $__p1) AND moves >= $__p2;');
+    expect(vars).toEqual({ __p0: 'u:1', __p1: 'u:1', __p2: 5 });
+  });
+
+  it('honors paramRef and swap without binding a new var', () => {
+    const plan: QueryPlan = {
+      table: 't',
+      where: [{ field: 'tags', op: 'CONTAINS', value: undefined, paramRef: 'tag', swap: true }],
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan, { tag: 'x' });
+    expect(sql).toBe('SELECT * FROM t WHERE $tag CONTAINS tags;');
+    expect(vars).toEqual({ tag: 'x' });
+  });
+});
+
+// Regression guard for the "authors + comments don't load" class: any filter on
+// a RecordId column (`id`) must coerce its string value with
+// `type::record(<string> …)`. On SurrealDB `id = "thread:x"` (string) never
+// matches a RecordId, so a base select filtered by id resolves EMPTY and its
+// whole `.related()` subtree (author, comments) loads nothing. The string-based
+// MemStore in relation-resolver.test.ts can't catch this (it compares keys as
+// strings), so these assert the rendered SurrealQL directly — both the parent
+// (base select) and child (relation fetch) sides.
+describe('record-id coercion (authors/comments loading regression)', () => {
+  it('coerces a base-select `id = <value>` filter to a record id', () => {
+    const plan: QueryPlan = { table: 'thread', where: [{ field: 'id', op: '=', value: 'thread:abc' }] };
+    const { sql, vars } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $__p0);');
+    expect(vars).toEqual({ __p0: 'thread:abc' });
+  });
+
+  it('coerces a base-select `id = $paramRef` filter (the ThreadDetail path)', () => {
+    const plan: QueryPlan = { table: 'thread', where: [{ field: 'id', op: '=', value: undefined, paramRef: 'id' }] };
+    const { sql } = renderBaseSelectSurql(plan, { id: 'thread:abc' });
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $id);');
+  });
+
+  it('does NOT coerce non-id fields (plain string/bool columns stay literal)', () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'title', op: '=', value: 'hi' }, { field: 'published', op: '=', value: true }],
+    };
+    const { sql } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT * FROM thread WHERE title = $__p0 AND published = $__p1;');
+  });
+
+  // Regression guard for the thread-detail "crossed results → 404" bug: a
+  // slave-mode node carries BOTH a baked `value` and a `paramRef` (= the field
+  // name). Materialization MUST bind `params[paramRef]` (the query's identity),
+  // NOT the baked value — otherwise a stale/other plan whose baked id ≠ the
+  // query's params would surface a different record's row. So rendering a plan
+  // baked to id-A with params for id-B must filter by B.
+  it('slave-mode node binds params over the baked value (records follow identity)', () => {
+    const planBakedToA: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }],
+    };
+    const { sql, vars } = renderBaseSelectSurql(planBakedToA, { id: 'thread:B' });
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $id);');
+    expect(vars).toEqual({ id: 'thread:B' }); // B wins — the baked A is ignored
+  });
+
+  it('slave-mode node falls back to the baked value when the param is absent', () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }],
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan, {}); // no params.id
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $__p0);');
+    expect(vars).toEqual({ __p0: 'thread:A' });
+  });
+
+  it('coerces `id` inside an OR group too', () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ or: [{ field: 'id', op: '=', value: 'thread:a' }, { field: 'id', op: '=', value: 'thread:b' }] }],
+    };
+    const { sql } = renderBaseSelectSurql(plan);
+    expect(sql).toBe(
+      'SELECT * FROM thread WHERE (id = type::record(<string> $__p0) OR id = type::record(<string> $__p1));'
+    );
+  });
+
+  it('relation fetch coerces its matchField keys (the .118 fix — kept locked)', () => {
+    const { sql } = renderRelationFetchSurql({ table: 'user', matchField: 'id', keys: ['user:1'] });
+    expect(sql).toContain('id IN $__keys.map(|$__k| type::record(<string> $__k))');
+  });
+});
+
+describe('renderRelationFetchSurql', () => {
+  it('builds a WHERE ... IN $__keys batch fetch, omitting LIMIT', () => {
+    const { sql, vars } = renderRelationFetchSurql({
+      table: 'comment',
+      matchField: 'post',
+      keys: ['post:1', 'post:2'],
+      where: [{ field: 'hidden', op: '=', value: false }],
+      orderBy: [['rank', 'asc']],
+    });
+    expect(sql).toBe('SELECT * FROM comment WHERE post IN $__keys.map(|$__k| type::record(<string> $__k)) AND hidden = $__p0 ORDER BY rank asc;');
+    expect(vars).toEqual({ __keys: ['post:1', 'post:2'], __p0: false });
+  });
+});
+
+describe('buildWindowMaterializationPlan', () => {
+  it('restricts to the id-set for offset queries, dropping where/limit/offset', () => {
+    const plan: QueryPlan = {
+      table: 'post',
+      where: [{ field: 'x', op: '=', value: 1 }],
+      orderBy: [['created', 'desc']],
+      limit: 10,
+      offset: 20,
+      relations: [{ alias: 'a', table: 'u', cardinality: 'one', foreignKeyField: 'a' }],
+    };
+    const win = buildWindowMaterializationPlan(plan, ['post:5', 'post:6']);
+    expect(win).toEqual({
+      table: 'post',
+      orderBy: [['created', 'desc']],
+      relations: [{ alias: 'a', table: 'u', cardinality: 'one', foreignKeyField: 'a' }],
+      ids: ['post:5', 'post:6'],
+      where: undefined,
+      limit: undefined,
+      offset: undefined,
+    });
+  });
+
+  it('returns null for non-offset queries (keep normal path)', () => {
+    expect(buildWindowMaterializationPlan({ table: 'post', limit: 10 }, ['post:1'])).toBeNull();
+    expect(buildWindowMaterializationPlan({ table: 'post', offset: 0 }, ['post:1'])).toBeNull();
+  });
+});

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

@@ -0,0 +1,108 @@
+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 {
+  // Prefer the query's own param (`paramRef`) so a filter materializes from
+  // `params` (the query's identity), not a baked literal — this is what slaves
+  // a query's rows to its id. A pure `$`-ref node has no `value`, so it always
+  // uses the param. A slave-mode node also carries `value` as a fallback for
+  // when the param is absent (e.g. a non-column field stripped by parseParams).
+  const useParam =
+    c.paramRef !== undefined &&
+    (c.value === undefined || Object.prototype.hasOwnProperty.call(ctx.vars, c.paramRef));
+  const rawRight = useParam ? `$${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);
+    }
+  });
+});