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

package/src/query/sql.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import * as sql from './sql';
+import {
+  buildListRefBatchSelect,
+  buildListRefSelect,
+  buildQueryRowCountBatchSelect,
+  buildQueryRowCountSelect,
+  buildSubqueryListRefSelect,
+} from '../sync/policy';
+
+describe('query sql builders (golden against the previous builders)', () => {
+  it('edge and meta selects are byte-identical to the old helpers', () => {
+    expect(sql.listRefSelect('_00_list_ref_user_x')).toBe(buildListRefSelect('_00_list_ref_user_x'));
+    expect(sql.subqueryListRefSelect('t')).toBe(buildSubqueryListRefSelect('t'));
+    expect(sql.queryRowCountSelect()).toBe(buildQueryRowCountSelect());
+    expect(sql.listRefBatchSelect('t')).toBe(buildListRefBatchSelect('t'));
+    expect(sql.queryRowCountBatchSelect()).toBe(buildQueryRowCountBatchSelect());
+  });
+  it('reads edges through the graph, byte-identical to spooky_core sql.dart', () => {
+    expect(sql.listRefSelect('_00_list_ref_user_u1')).toBe(
+      'SELECT out, version FROM $in->_00_list_ref_user_u1 WHERE parent IS NONE'
+    );
+    expect(sql.subqueryListRefSelect('_00_list_ref')).toBe(
+      'SELECT out, version FROM $in->_00_list_ref WHERE parent IS NOT NONE'
+    );
+    expect(sql.listRefBatchSelect('_00_list_ref')).toBe('SELECT in, out, version, parent FROM $ins->_00_list_ref');
+  });
+  it('composes the single, batch and register requests', () => {
+    expect(sql.singleSnapshotSelect('t').split(';\n')).toEqual([
+      sql.listRefSelect('t'),
+      sql.queryRowCountSelect(),
+      sql.subqueryListRefSelect('t'),
+    ]);
+    expect(sql.batchSnapshotSelect('t')).toBe(`${sql.listRefBatchSelect('t')};\n${sql.queryRowCountBatchSelect()}`);
+    expect(sql.registerSelect('t').startsWith('fn::query::register($config);\n')).toBe(true);
+    const id = new RecordId('_00_query', 'h');
+    expect(sql.registerVars({ id, surql: 's', params: { a: 1 }, ttl: '10m' })).toEqual({
+      config: { id, surql: 's', params: { a: 1 }, ttl: '10m' },
+      in: id,
+    });
+    // The owner secret rides beside params, never inside them: params name
+    // the computation the SSP shares between views.
+    expect(sql.registerVars({ id, surql: 's', params: { a: 1 }, ttl: '10m', owner: 'k' })).toEqual({
+      config: { id, surql: 's', params: { a: 1 }, ttl: '10m', owner: 'k' },
+      in: id,
+    });
+  });
+  it('the LIVE on a per-user table is unfiltered; FETCH out only when bodies ride inline', () => {
+    expect(sql.listRefLive('_00_list_ref_user_x', { inlineBodies: true, sessionIds: ['s1'] })).toEqual({
+      sql: 'LIVE SELECT * FROM _00_list_ref_user_x FETCH out',
+    });
+    expect(sql.listRefLive('_00_list_ref', { inlineBodies: false, sessionIds: [] })).toEqual({
+      sql: 'LIVE SELECT * FROM _00_list_ref',
+    });
+  });
+  it("the anon LIVE hears only this client's sockets, current one by session::id()", () => {
+    const sids = ['earlier-1', 'earlier-2'];
+    const live = sql.listRefLive('_00_list_ref_anon', { inlineBodies: true, sessionIds: sids });
+    expect(live.sql).toBe(
+      'LIVE SELECT * FROM _00_list_ref_anon WHERE clientId = <string>session::id() OR clientId IN $sids FETCH out'
+    );
+    expect(live.vars).toEqual({ sids });
+    // A copy: the caller's list keeps growing after the LIVE is sent.
+    expect(live.vars!.sids).not.toBe(sids);
+    expect(sql.listRefLive('_00_list_ref_anon', { inlineBodies: false, sessionIds: [] })).toEqual({
+      sql: 'LIVE SELECT * FROM _00_list_ref_anon WHERE clientId = <string>session::id() OR clientId IN $sids',
+      vars: { sids: [] },
+    });
+  });
+  it('view rows and ids', () => {
+    expect(sql.viewRecordId('k')).toEqual(new RecordId('_00_view', 'k'));
+    expect(sql.viewRow([['t:1', 1]], [['c:1', 2]], true, 5)).toEqual({ ids: [['t:1', 1]], children: [['c:1', 2]], confirmed: true, updatedAt: 5 });
+    expect(sql.readViewRows()).toBe('SELECT * FROM _00_view');
+    expect(sql.readLegacyViewRows()).toBe('SELECT * FROM _00_window');
+    expect(sql.countViewRows()).toContain('_00_view');
+    expect(sql.bodySelect()).toBe('SELECT * FROM $ids');
+  });
+  it('heartbeat batch answers per index and detects reclaimed rows', () => {
+    const a = new RecordId('_00_query', 'a');
+    const b = new RecordId('_00_query', 'b');
+    expect(sql.heartbeatBatch([a, b])).toEqual({
+      sql: 'fn::query::heartbeat($id0);\nfn::query::heartbeat($id1)',
+      vars: { id0: a, id1: b },
+    });
+    expect(sql.heartbeatRowGone([])).toBe(true);
+    expect(sql.heartbeatRowGone([{ id: a }])).toBe(false);
+    expect(sql.heartbeatRowGone(undefined)).toBe(false);
+  });
+  it('the pagehide beacon names the page sessions and inlines only shapes it minted', () => {
+    const a = new RecordId('_00_query', 'a'.repeat(64));
+    const b = new RecordId('_00_query', 'b'.repeat(64));
+    const s1 = 'de81a067-f4bc-4351-a2a3-1ecf06b6305a';
+    const s2 = '8A14ED5A-32B5-4B4E-973D-D2B88860932F';
+    expect(sql.leaveViewsBeacon([a, b], [s1, s2])).toBe(
+      `FOR $id IN [${a}, ${b}] { LET $_left = fn::query::leave($id, ['${s1}', '${s2}']); };`
+    );
+    const digits = new RecordId('_00_query', '1'.repeat(64));
+    expect(sql.leaveViewsBeacon([digits], [s1])).toBe(`FOR $id IN [${digits}] { LET $_left = fn::query::leave($id, ['${s1}']); };`);
+    // Anything else is dropped rather than interpolated.
+    expect(sql.leaveViewsBeacon([a, new RecordId('_00_query', "x']; DELETE user; --"), 'user:1'], [s1, "x'; DELETE user; --"])).toBe(
+      `FOR $id IN [${a}] { LET $_left = fn::query::leave($id, ['${s1}']); };`
+    );
+    // No session ids: the server could not tell this page's entries from a reload's, so send nothing.
+    expect(sql.leaveViewsBeacon([a], [])).toBeNull();
+    expect(sql.leaveViewsBeacon([], [s1])).toBeNull();
+  });
+  it('upsertBodiesTx MERGEs each body inside one transaction', () => {
+    const { query, vars } = sql.upsertBodiesTx([
+      { id: 'thing:1', content: { a: 1 } },
+      { id: 'thing:2', content: { b: 2 } },
+    ]);
+    expect(query.sql).toBe(
+      'BEGIN TRANSACTION;\nUPSERT ONLY $id0 MERGE $content0;UPSERT ONLY $id1 MERGE $content1;\nCOMMIT TRANSACTION;'
+    );
+    expect(vars).toEqual({ id0: 'thing:1', content0: { a: 1 }, id1: 'thing:2', content1: { b: 2 } });
+  });
+});

package/src/query/sql.ts

@@ -0,0 +1,157 @@
+import { RecordId } from 'surrealdb';
+import type { RecordVersionArray } from '../types';
+import type { Vars } from '../kernel/effects';
+import { surql } from '../utils/surql';
+import type { SealedQuery } from '../utils/surql';
+import { ANON_LIST_REF_TABLE } from '../modules/ref-tables';
+
+/** Every SurrealQL statement the query side sends, as pure builders. */
+
+export const VIEW_TABLE = '_00_view';
+export const LEGACY_VIEW_TABLE = '_00_window';
+
+export const viewRecordId = (viewKey: string): RecordId<string> => new RecordId(VIEW_TABLE, viewKey);
+
+/**
+ * The durable `_00_view` row: the confirmed membership plus the subquery
+ * children, which the GC must keep and a cold scan may paint as much as the
+ * members.
+ */
+export const viewRow = (
+  ids: RecordVersionArray,
+  children: RecordVersionArray,
+  confirmed: boolean,
+  now: number
+): Record<string, unknown> => ({
+  ids,
+  children,
+  confirmed,
+  updatedAt: now,
+});
+
+/** Every `_00_view` row: the durable view index and the GC read it. */
+export const readViewRows = (): string => `SELECT * FROM ${VIEW_TABLE}`;
+
+/** Copy every legacy `_00_window` row into `_00_view` once. */
+export const readLegacyViewRows = (): string => `SELECT * FROM ${LEGACY_VIEW_TABLE}`;
+export const countViewRows = (): string => `SELECT count() FROM ${VIEW_TABLE} GROUP ALL`;
+
+// Edges are read through the graph (`$in->table`): the `_00_list_ref*` tables
+// have no index on `in`, so `WHERE in = $in` scanned the whole table, which on
+// the shared `_00_list_ref_anon` is every signed-out visitor's edges.
+export const listRefSelect = (table: string): string =>
+  `SELECT out, version FROM $in->${table} WHERE parent IS NONE`;
+export const subqueryListRefSelect = (table: string): string =>
+  `SELECT out, version FROM $in->${table} WHERE parent IS NOT NONE`;
+export const queryRowCountSelect = (): string => 'SELECT VALUE { rowCount: rowCount, state: state } FROM ONLY $in';
+export const listRefBatchSelect = (table: string): string =>
+  `SELECT in, out, version, parent FROM $ins->${table}`;
+export const queryRowCountBatchSelect = (): string => 'SELECT VALUE { id: id, rowCount: rowCount, state: state } FROM $ins';
+
+/** The single-query read: edges, meta, subquery children in one request. */
+export const singleSnapshotSelect = (table: string): string =>
+  `${listRefSelect(table)};\n${queryRowCountSelect()};\n${subqueryListRefSelect(table)}`;
+/** The many-query read: all edges + all metas in one request. */
+export const batchSnapshotSelect = (table: string): string =>
+  `${listRefBatchSelect(table)};\n${queryRowCountBatchSelect()}`;
+
+/**
+ * The session's one LIVE subscription on its `_00_list_ref` table.
+ *
+ * `inlineBodies` adds `FETCH out`, which resolves the edge's target into the
+ * notification so the body arrives with the doorbell.
+ *
+ * On the anon table it is filtered to this client's own edges. Every
+ * signed-out session shares that table, so unfiltered each one received (and
+ * the server fetched a body for) every anonymous edge change of every other
+ * session, and the client then dropped all but its own. An edge carries the
+ * `session::id()` of whichever socket last registered its view, which is a
+ * socket of this client but not necessarily the current one: a view stays
+ * registered across a reconnect, and a reload keeps its salt and its views,
+ * so their older edges still name an earlier socket. `sessionIds` are those
+ * earlier sockets. The current one is matched by `session::id()` itself,
+ * which SurrealDB evaluates in the subscriber's own session, so the filter
+ * holds before the client has learned its new id.
+ *
+ * The cast is load-bearing: `session::id()` is a uuid, `clientId` a string,
+ * and without it nothing matches. Per-user tables need no filter.
+ */
+export function listRefLive(
+  table: string,
+  opts: { inlineBodies: boolean; sessionIds: ReadonlyArray<string> }
+): { sql: string; vars?: Vars } {
+  const join = opts.inlineBodies ? ' FETCH out' : '';
+  if (table !== ANON_LIST_REF_TABLE) return { sql: `LIVE SELECT * FROM ${table}${join}` };
+  return {
+    sql: `LIVE SELECT * FROM ${table} WHERE clientId = <string>session::id() OR clientId IN $sids${join}`,
+    vars: { sids: [...opts.sessionIds] },
+  };
+}
+
+export interface RegisterPayload {
+  id: RecordId<string>;
+  surql: string;
+  params: Record<string, unknown>;
+  ttl: string;
+  /**
+   * The registering page's secret. `fn::query::register` forwards only its
+   * hash, and the SSP lets a registration onto an existing anonymous view
+   * only with the hash that view was registered with: every signed-out
+   * visitor is `anon`, and anyone can read an anonymous view's id. Kept out
+   * of `params`, which name the computation the SSP shares between views.
+   */
+  owner?: string;
+}
+
+/** Register + read back edges/meta/children in ONE request. */
+export const registerSelect = (table: string): string =>
+  `fn::query::register($config);\n${singleSnapshotSelect(table)}`;
+export const registerVars = (payload: RegisterPayload): Vars => ({ config: payload, in: payload.id });
+
+/** One heartbeat statement per view id; result index i answers id i. */
+export function heartbeatBatch(ids: ReadonlyArray<RecordId<string>>): { sql: string; vars: Vars } {
+  const vars: Vars = {};
+  const stmts = ids.map((id, i) => {
+    vars[`id${i}`] = id;
+    return `fn::query::heartbeat($id${i})`;
+  });
+  return { sql: stmts.join(';\n'), vars };
+}
+
+/** A heartbeat answer whose statement matched no row: the view was reclaimed. */
+export const heartbeatRowGone = (result: unknown): boolean => Array.isArray(result) && result.length === 0;
+
+// The SDK escapes an all-digit key as `⟨…⟩`; both forms parse back to the same id.
+const QUERY_ID = /^_00_query:(?:[0-9a-f]{64}|⟨[0-9a-f]{64}⟩)$/;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The pagehide release: one bare statement for `beaconSql`, which has no params
+ * channel, so ids are inlined. Only shapes the client minted itself get in, a
+ * `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+ * interpolated. `null` when there is nothing the server could act on: with no
+ * session ids it could not tell this page's entries from anyone else's.
+ */
+export function leaveViewsBeacon(ids: ReadonlyArray<unknown>, sessionIds: ReadonlyArray<string>): string | null {
+  const list = ids.map((id) => String(id)).filter((id) => QUERY_ID.test(id));
+  const sids = sessionIds.filter((sid) => SESSION_ID.test(sid));
+  if (list.length === 0 || sids.length === 0) return null;
+  const sidList = sids.map((sid) => `'${sid}'`).join(', ');
+  return `FOR $id IN [${list.join(', ')}] { LET $_left = fn::query::leave($id, [${sidList}]); };`;
+}
+
+export const bodySelect = (): string => 'SELECT * FROM $ids';
+
+/** Local transaction that MERGEs many fetched bodies. */
+export function upsertBodiesTx(records: ReadonlyArray<{ id: unknown; content: Record<string, unknown> }>): {
+  query: SealedQuery<unknown>;
+  vars: Vars;
+} {
+  const vars: Vars = {};
+  const stmts = records.map((r, i) => {
+    vars[`id${i}`] = r.id;
+    vars[`content${i}`] = r.content;
+    return surql.upsertMerge(`id${i}`, `content${i}`);
+  });
+  return { query: surql.seal<void>(surql.tx(stmts)) as SealedQuery<unknown>, vars };
+}

package/src/query/window-query.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { buildWindowMaterialization } from './window-query';
+
+describe('scanner edge cases', () => {
+  it('skips escaped quotes inside strings and ignores clauses in parens', () => {
+    const q = "SELECT * FROM t WHERE a = 'it\\'s (FROM)' AND b IN (SELECT id FROM u LIMIT 1 START 1) LIMIT 5 START 5";
+    expect(buildWindowMaterialization(q)).toEqual({ query: 'SELECT * FROM $__win' });
+  });
+  it('requires whitespace inside ORDER BY and a number after START', () => {
+    expect(buildWindowMaterialization('SELECT * FROM t ORDERBY a LIMIT 5 START 5')).toEqual({ query: 'SELECT * FROM $__win' });
+    expect(buildWindowMaterialization('SELECT * FROM t LIMIT 5 START $n')).toBeNull();
+    expect(buildWindowMaterialization('SELECT * FROM t LIMIT 5 START')).toBeNull();
+  });
+  it('matches a keyword at the very start and at the end of the string', () => {
+    expect(buildWindowMaterialization('FROM t LIMIT 5 START 5')).toEqual({ query: ' FROM (SELECT * FROM $__win)' });
+    expect(buildWindowMaterialization('SELECT * FROM t ORDER BY a LIMIT 5 START 5 ORDER')).toEqual({
+      query: 'SELECT * FROM (SELECT * FROM $__win) ORDER BY a',
+    });
+  });
+});
+
+describe('buildWindowMaterialization', () => {
+  it('rewrites the game-list window query (START 30) to select the id-set, keeping ORDER BY', () => {
+    const surql =
+      'SELECT * FROM game WHERE database = $database ORDER BY sort_index asc, date desc LIMIT 30 START 30;';
+    const r = buildWindowMaterialization(surql);
+    expect(r).not.toBeNull();
+    expect(r!.query).toBe('SELECT * FROM (SELECT * FROM $__win) ORDER BY sort_index asc, date desc');
+  });
+
+  it('returns null for START 0 (offset-free windows still work via the normal re-query)', () => {
+    const surql =
+      'SELECT * FROM game WHERE database = $database ORDER BY sort_index asc, date desc LIMIT 30 START 0;';
+    expect(buildWindowMaterialization(surql)).toBeNull();
+  });
+
+  it('returns null when there is no START clause', () => {
+    expect(
+      buildWindowMaterialization('SELECT * FROM game WHERE database = $database LIMIT 30;')
+    ).toBeNull();
+    expect(buildWindowMaterialization('SELECT * FROM game;')).toBeNull();
+  });
+
+  it('preserves a custom projection', () => {
+    const surql = 'SELECT id, white, black FROM game ORDER BY date desc LIMIT 30 START 60;';
+    expect(buildWindowMaterialization(surql)!.query).toBe(
+      'SELECT id, white, black FROM (SELECT * FROM $__win) ORDER BY date desc'
+    );
+  });
+
+  it('omits ORDER BY when the query had none', () => {
+    const surql = 'SELECT * FROM game LIMIT 30 START 30;';
+    expect(buildWindowMaterialization(surql)!.query).toBe('SELECT * FROM $__win');
+  });
+
+  it('ignores FROM/ORDER BY/LIMIT/START inside subqueries (paren-aware)', () => {
+    const surql =
+      'SELECT *, (SELECT * FROM comment WHERE game = $parent.id ORDER BY created_at desc LIMIT 5) AS comments ' +
+      'FROM game ORDER BY sort_index asc LIMIT 30 START 90;';
+    expect(buildWindowMaterialization(surql)!.query).toBe(
+      'SELECT *, (SELECT * FROM comment WHERE game = $parent.id ORDER BY created_at desc LIMIT 5) AS comments FROM (SELECT * FROM $__win) ORDER BY sort_index asc'
+    );
+  });
+
+  it('does not treat a START inside a string literal as the offset', () => {
+    const surql = "SELECT * FROM game WHERE note = 'LIMIT 30 START 30' ORDER BY date desc LIMIT 30 START 30;";
+    const r = buildWindowMaterialization(surql);
+    expect(r!.query).toBe('SELECT * FROM (SELECT * FROM $__win) ORDER BY date desc');
+  });
+});

package/src/query/window-query.ts

@@ -0,0 +1,208 @@
+/**
+ * Rewrite a windowed (`LIMIT n START m`, m>0) SELECT so its rows are
+ * materialized from an explicit record-id set — the window the SSP already
+ * computed — instead of re-running the original query (with its `START m`)
+ * against the shared local DB.
+ *
+ * Why: `DataModule.processStreamUpdate` materializes a query's rows by
+ * re-querying the local in-browser SurrealDB with the original surql. For an
+ * offset query that re-applies `START m` against the *shared* local store —
+ * which, with sparse windowing, may hold only this window's rows — so it skips
+ * them all and returns nothing (the "page 2 returns 0 rows" bug). The SSP's
+ * materialized view (`StreamUpdate.localArray`) is exactly this window's row
+ * ids, so we select those ids directly and re-apply the original `ORDER BY` for
+ * stable display order.
+ *
+ * Returns `null` for non-offset queries (`START` absent or 0) — the caller
+ * keeps the normal re-query path, so only the broken case changes behavior.
+ *
+ * Preserves the `SELECT <projection>` clause and the top-level `ORDER BY`;
+ * drops the original `FROM`/`WHERE`/`LIMIT`/`START`. Subqueries inside the
+ * projection are preserved verbatim (the scanner is paren/quote aware), with
+ * one caveat: SurrealDB v3 drops `*` in the `SELECT *, <subquery> FROM $param`
+ * shape — such windowed+subquery queries are rare and were already returning 0,
+ * so this is no regression.
+ */
+import type { QueryPlan } from '@spooky-sync/query-builder';
+
+/**
+ * Plan-level window materialization: restrict a windowed query's base rows to
+ * exactly the SSP-computed id-set, dropping `where`/`limit`/`offset` but keeping
+ * `orderBy`, `select` and `relations`. The engine-neutral counterpart of
+ * {@link buildWindowMaterialization} (which does the same by string surgery for
+ * the raw-SurrealQL path). Returns `null` for non-offset queries so the caller
+ * keeps the normal re-query path.
+ */
+export function buildWindowMaterializationPlan(
+  plan: QueryPlan,
+  ids: unknown[]
+): QueryPlan | null {
+  if (plan.offset === undefined || plan.offset <= 0) return null;
+  return buildIdSetPlan(plan, ids);
+}
+
+/**
+ * Raw-SurrealQL counterpart of {@link buildIdSetPlan}, for queries that arrived
+ * without a plan. Same rewrite as {@link buildWindowMaterialization} without the
+ * offset guard: keep the projection and top-level `ORDER BY`, replace the source
+ * with the bound id-set.
+ */
+export function buildIdSetSurql(
+  surql: string,
+  idsParam = '__win'
+): { query: string } | null {
+  const kw = scanTopLevelClauses(surql);
+  if (kw.fromIndex === null) return null;
+  return { query: renderIdSetSelect(surql, kw, idsParam) };
+}
+
+/** Shared body of the two id-set surql rewrites: keep the projection and the
+ *  top-level `ORDER BY`, replace the source with the bound id-set. */
+function renderIdSetSelect(surql: string, kw: TopLevelClauses, idsParam: string): string {
+  const selectClause = surql.slice(0, kw.fromIndex!).trimEnd(); // "SELECT <projection>"
+
+  let orderBy = '';
+  const orderByIndex = kw.orderByIndex;
+  if (orderByIndex !== null) {
+    const ends = [kw.limitIndex, kw.startIndex, kw.semicolonIndex, surql.length].filter(
+      (n): n is number => n !== null && n > orderByIndex
+    );
+    orderBy = ' ' + surql.slice(orderByIndex, Math.min(...ends)).trim();
+  }
+
+  return `${selectClause} FROM ${idSetSource(selectClause, idsParam, orderBy !== '')}${orderBy}`;
+}
+
+/**
+ * The FROM source for an id-set read. The in-browser SurrealDB (wasm, 3.x)
+ * reads bare record ids without loading them: a field list over them throws
+ * ("Specify a database to use") and an ORDER BY is silently ignored, while a
+ * plain `SELECT *` works. Those read from `(SELECT * FROM $ids)` instead, the
+ * same rows as documents. The SQLite translator accepts both shapes.
+ */
+export function idSetSource(selectClause: string, idsParam: string, ordered = false): string {
+  return !ordered && /^SELECT\s+(VALUE\s+)?\*/i.test(selectClause.trim())
+    ? `$${idsParam}`
+    : `(SELECT * FROM $${idsParam})`;
+}
+
+/**
+ * Restrict any plan's base rows to an explicit id-set, regardless of offset.
+ *
+ * Same rewrite as {@link buildWindowMaterializationPlan} without the offset
+ * guard, for rendering a query from its authoritative membership list rather
+ * than by re-running its predicate.
+ *
+ * `where` is dropped deliberately: the id-set already IS the answer to the
+ * predicate as the server evaluated it, and re-applying the `WHERE` locally is
+ * exactly the bug — a row that left the window keeps its (stale, never
+ * re-fetched) local body, so it keeps matching and keeps rendering.
+ * `limit`/`offset` go for the same reason: both are already baked into which ids
+ * are in the set, so the set itself is the bound. (Both engines ignore them on
+ * the `ids` path regardless — only `select` and `orderBy` are honored there.)
+ * `orderBy` is kept so display order stays deterministic.
+ */
+export function buildIdSetPlan(plan: QueryPlan, ids: unknown[]): QueryPlan {
+  return {
+    ...plan,
+    ids,
+    where: undefined,
+    limit: undefined,
+    offset: undefined,
+  };
+}
+
+export function buildWindowMaterialization(
+  surql: string,
+  idsParam = '__win'
+): { query: string } | null {
+  const kw = scanTopLevelClauses(surql);
+  // `START` is only recorded once `FROM` was seen, so a positive start value
+  // implies a FROM index.
+  if (kw.startValue === null || kw.startValue <= 0) return null;
+  return { query: renderIdSetSelect(surql, kw, idsParam) };
+}
+
+interface TopLevelClauses {
+  fromIndex: number | null;
+  orderByIndex: number | null;
+  limitIndex: number | null;
+  startIndex: number | null;
+  startValue: number | null;
+  semicolonIndex: number | null;
+}
+
+// Single pass over the query, tracking paren depth and single-quoted strings so
+// that clauses inside subqueries (which live in parens) are ignored — only the
+// outermost (depth-0) clause keywords are recorded.
+function scanTopLevelClauses(sql: string): TopLevelClauses {
+  const out: TopLevelClauses = {
+    fromIndex: null,
+    orderByIndex: null,
+    limitIndex: null,
+    startIndex: null,
+    startValue: null,
+    semicolonIndex: null,
+  };
+  let depth = 0;
+  let inStr = false;
+
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (inStr) {
+      if (ch === '\\') i++; // skip escaped char
+      else if (ch === "'") inStr = false;
+      continue;
+    }
+    if (ch === "'") { inStr = true; continue; }
+    if (ch === '(') { depth++; continue; }
+    if (ch === ')') { depth--; continue; }
+    if (depth !== 0) continue;
+    if (ch === ';' && out.semicolonIndex === null) { out.semicolonIndex = i; continue; }
+
+    // Only test keywords at a word boundary.
+    if (!isWordBoundary(sql, i)) continue;
+    if (out.fromIndex === null && matchKeyword(sql, i, 'FROM')) { out.fromIndex = i; continue; }
+    // FROM must come before the trailing clauses; only record them once seen.
+    if (out.fromIndex === null) continue;
+    if (out.orderByIndex === null && matchKeyword(sql, i, 'ORDER BY')) { out.orderByIndex = i; continue; }
+    if (out.limitIndex === null && matchKeyword(sql, i, 'LIMIT')) { out.limitIndex = i; continue; }
+    if (out.startIndex === null && matchKeyword(sql, i, 'START')) {
+      out.startIndex = i;
+      out.startValue = readNumberAfter(sql, i + 'START'.length);
+      continue;
+    }
+  }
+  return out;
+}
+
+function isWordBoundary(sql: string, i: number): boolean {
+  if (i === 0) return true;
+  return !/[A-Za-z0-9_]/.test(sql[i - 1]);
+}
+
+// Case-insensitive keyword match where internal whitespace (e.g. "ORDER BY")
+// matches any run of whitespace, and the keyword ends on a non-word char.
+function matchKeyword(sql: string, i: number, keyword: string): boolean {
+  const parts = keyword.split(' ');
+  let pos = i;
+  for (let p = 0; p < parts.length; p++) {
+    const word = parts[p];
+    if (sql.slice(pos, pos + word.length).toUpperCase() !== word) return false;
+    pos += word.length;
+    if (p < parts.length - 1) {
+      const wsStart = pos;
+      while (pos < sql.length && /\s/.test(sql[pos])) pos++;
+      if (pos === wsStart) return false; // required whitespace
+    }
+  }
+  // Must end on a non-word char (or end of string).
+  return pos >= sql.length || !/[A-Za-z0-9_]/.test(sql[pos]);
+}
+
+function readNumberAfter(sql: string, from: number): number | null {
+  let pos = from;
+  while (pos < sql.length && /\s/.test(sql[pos])) pos++;
+  const m = /^\d+/.exec(sql.slice(pos));
+  return m ? parseInt(m[0], 10) : null;
+}