@spooky-sync/core 0.0.1-canary.38 → 0.0.1-canary.381

package/src/query/session-guard.integration.test.ts

@@ -0,0 +1,304 @@
+import { Socket } from 'node:net';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { RecordId, Surreal } from 'surrealdb';
+import { liveEndpoint } from '../live/index';
+import { isRefusedSessionError } from '../utils/error-classification';
+import { heartbeatBatch, heartbeatRowGone, queryRowCountSelect } from './sql';
+
+/**
+ * The app's session guard (`sessionGuard` in sp00ky.yml, the SESSION GUARD
+ * block of `meta_tables_remote.surql`) ends sync for a WebSocket that is still
+ * open. SurrealDB checks a token only when a socket authenticates, so before
+ * the guard a socket that authenticated before a password reset kept reading
+ * its user's edges, heartbeating its views and registering new ones until it
+ * happened to reconnect.
+ *
+ * Runs the shipped guard, `_00_query` and `_00_list_ref` blocks, the
+ * `fn::query::*` functions and the per-user edge-table rule ssp-node defines,
+ * against a real SurrealDB, because the guarantee is the engine's evaluation
+ * of those rules, LIVE notifications included. Boot one first, e.g.:
+ *   docker run -d --name spooky-surreal-it -p 18011:8000 \
+ *     surrealdb/surrealdb:v3.1.5 start --user root --pass root --allow-all memory
+ *
+ * Override the endpoint with SURREAL_IT_ENDPOINT. Skips if unreachable.
+ */
+const endpoint = liveEndpoint(process.env.SURREAL_IT_ENDPOINT ?? 'ws://127.0.0.1:18011');
+const NS = 'it';
+
+/** The guard WhitePawn ships: a password reset stamps `session_epoch`. */
+const GUARD = '$auth.session_epoch = NONE OR ($token.iat ?? 0) >= $auth.session_epoch';
+
+const repoFile = (path: string) =>
+  readFileSync(fileURLToPath(new URL(`../../../../${path}`, import.meta.url)), 'utf8');
+const cliSource = (file: string) => repoFile(`apps/cli/src/${file}`);
+
+function slice(src: string, from: string, to: string): string {
+  const start = src.indexOf(from);
+  const end = src.indexOf(to, start);
+  if (start < 0 || end < start) throw new Error(`block ${from} .. ${to} not found`);
+  return src.slice(start, end);
+}
+
+/**
+ * The SESSION GUARD block, with `expr` put in the way `spky migrate` does
+ * (`schema_builder::apply_session_guard`, whose marker is read from the Rust
+ * source so the two cannot drift).
+ */
+function guardSchema(expr?: string): string {
+  const block = slice(
+    cliSource('meta_tables_remote.surql'),
+    '-- SPOOKY SESSION GUARD',
+    '-- SPOOKY INCANTATION'
+  );
+  const m = /pub const SESSION_GUARD_DEFAULT: &str = "([^"]+)";/.exec(
+    repoFile('apps/cli/src/schema_builder.rs')
+  );
+  if (!m || !block.includes(m[1])) throw new Error('session guard marker not found');
+  return expr ? block.replace(m[1], `RETURN (${expr}) == true;`) : block;
+}
+
+/** Just the tables this test needs: the rest of the file needs modules. */
+const queryTableSchema = () =>
+  slice(
+    cliSource('meta_tables_remote.surql'),
+    'DEFINE TABLE OVERWRITE _00_query SCHEMALESS',
+    '-- SPOOKY LIST REF'
+  );
+const listRefSchema = () =>
+  slice(
+    cliSource('meta_tables_remote.surql'),
+    'DEFINE TABLE OVERWRITE _00_list_ref SCHEMALESS',
+    '-- SPOOKY STREAM PROCESSOR STATE'
+  );
+
+/** The rule ssp-node puts on `_00_list_ref_user_<uid>` (`user_list_ref_ddl` in tables.rs). */
+function userListRefTable(uid: string): string {
+  const m = /PERMISSIONS FOR select WHERE (\$auth\.id = user:\{uid\}[^,]*),/.exec(
+    repoFile('packages/ssp-node/src/tables.rs')
+  );
+  if (!m) throw new Error('per-user list_ref rule not found in ssp-node/src/tables.rs');
+  return `DEFINE TABLE OVERWRITE _00_list_ref_user_${uid} SCHEMALESS
+    PERMISSIONS FOR select WHERE ${m[1].replace('{uid}', uid)}, FOR create, update, delete WHERE false;`;
+}
+
+/** An app schema: a hidden `session_epoch` and an app table that asks the guard too. */
+const APP = `
+DEFINE TABLE OVERWRITE user SCHEMAFULL PERMISSIONS FOR select WHERE id = $auth.id;
+DEFINE FIELD OVERWRITE name ON TABLE user TYPE string;
+DEFINE FIELD OVERWRITE session_epoch ON TABLE user TYPE option<int>
+  PERMISSIONS FOR select WHERE false, FOR create, update WHERE false;
+DEFINE ACCESS OVERWRITE account ON DATABASE TYPE RECORD
+  SIGNUP (CREATE ONLY type::record('user', $name) SET name = $name)
+  SIGNIN (SELECT * FROM user WHERE name = $name)
+  DURATION FOR TOKEN 1h, FOR SESSION 1h;
+DEFINE TABLE OVERWRITE game SCHEMALESS
+  PERMISSIONS FOR select WHERE owner = $auth.id AND fn::sp00ky::session_live();
+CREATE game:1 SET owner = user:alice;
+`;
+
+/** What the SSP writes, as root, when a session registers a view (`node.rs`, cold path). */
+const SSP_REGISTER = `
+UPSERT $id SET clientId = $sid, auth_id = 'user:alice', surql = 'SELECT * FROM game',
+  params = { auth: { id: 'user:alice' }, access: 'account' }, ttl = 1h, lastActiveAt = time::now(),
+  rowCount = 1, state = 'ready',
+  subscribers = array::append(
+    array::filter(subscribers ?? [], |$s| <string>$s.id != $sid AND <datetime>$s.seenAt + 1h > time::now()),
+    { id: $sid, seenAt: time::now() })`;
+
+const viewId = () =>
+  new RecordId('_00_query', createHash('sha256').update(randomUUID()).digest('hex'));
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('session guard ends sync for an open socket (real SurrealDB)', () => {
+  let root: Surreal;
+  let database = '';
+  let reachable = false;
+  const open: Surreal[] = [];
+
+  beforeAll(async () => {
+    const url = new URL(endpoint);
+    reachable = await new Promise<boolean>((resolve) => {
+      const socket = new Socket();
+      const done = (ok: boolean) => {
+        socket.destroy();
+        resolve(ok);
+      };
+      socket.setTimeout(1_000, () => done(false));
+      socket.once('error', () => done(false));
+      socket.connect(Number(url.port || 80), url.hostname, () => done(true));
+    });
+  });
+
+  /** Root, a fresh database, the app and sp00ky's rules with `guard` in place. */
+  async function boot(guard?: string): Promise<void> {
+    database = `session_guard_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    root = new Surreal();
+    await root.connect(endpoint, { reconnect: false });
+    await root.signin({ username: 'root', password: 'root' });
+    await root.use({ namespace: NS, database });
+    await root.query(guardSchema(guard));
+    await root.query(APP);
+    await root.query(queryTableSchema());
+    await root.query(listRefSchema());
+    await root.query(userListRefTable('alice'));
+    await root.query(cliSource('functions_remote.surql'));
+    // The guard throws before the post; a live session's post fails on this
+    // closed port, which is not a refused session.
+    await root.query(
+      cliSource('functions_remote_singlenode.surql')
+        .replaceAll('{{ENDPOINT}}', 'http://127.0.0.1:9')
+        .replaceAll('{{SECRET}}', 'it-secret')
+    );
+  }
+
+  afterEach(async () => {
+    if (!reachable || !root) return;
+    for (const db of open.splice(0)) await db.close().catch(() => undefined);
+    await root.query(`REMOVE DATABASE ${database}`).catch(() => undefined);
+    await root.close();
+  });
+
+  /** Alice on a socket of her own, and that socket's `session::id()`. */
+  async function alice(how: 'signup' | 'signin'): Promise<[Surreal, string]> {
+    const db = new Surreal();
+    open.push(db);
+    await db.connect(endpoint, { reconnect: false });
+    await db.use({ namespace: NS, database });
+    await db[how]({ namespace: NS, database, access: 'account', variables: { name: 'alice' } });
+    const [sid] = (await db.query('RETURN <string>session::id()')) as [string];
+    return [db, sid];
+  }
+
+  /** What a password reset does: every token issued before now stops counting. */
+  async function resetPassword(stale: Surreal): Promise<void> {
+    const [iat] = (await stale.query('RETURN $token.iat')) as [number];
+    const epoch = iat + 1;
+    await root.query('UPDATE user:alice SET session_epoch = $epoch', { epoch });
+    // `iat` has second precision: the next sign-in must land at or past the epoch.
+    while (Date.now() / 1000 < epoch) await sleep(50);
+  }
+
+  /** LIVE on the per-user edge table; returns the notifications seen so far. */
+  async function watchEdges(db: Surreal): Promise<unknown[]> {
+    const seen: unknown[] = [];
+    const [id] = (await db.query('LIVE SELECT * FROM _00_list_ref_user_alice')) as [unknown];
+    const stream = await db.liveOf(id as never);
+    // Typed by the SDK (`LiveMessage`), not a narrower hand-written shape:
+    // the hand-written one failed `tsc` and so the core Test job.
+    stream.subscribe((message) => {
+      if (message.action !== 'KILLED') seen.push(message.value);
+    });
+    return seen;
+  }
+
+  const edge = (n: number) =>
+    root.query(
+      `CREATE type::record('_00_list_ref_user_alice', $n) SET in = _00_query:q, out = game:1, version = $n`,
+      { n }
+    );
+
+  /** The client's register read-back, as `registerSelect` sends it. */
+  const readBack = async (db: Surreal, id: RecordId<string>) =>
+    ((await db.query(queryRowCountSelect(), { in: id })) as [unknown])[0] ?? null;
+
+  const heartbeatFound = async (db: Surreal, id: RecordId<string>) => {
+    const beat = heartbeatBatch([id]);
+    const [result] = (await db.query(beat.sql, beat.vars)) as [unknown];
+    return !heartbeatRowGone(result);
+  };
+
+  const registerError = async (db: Surreal): Promise<unknown> =>
+    db
+      .query('RETURN fn::query::register($config)', {
+        config: { id: viewId(), surql: 'SELECT * FROM game', params: {}, ttl: '1h' },
+      })
+      .then(
+        () => null,
+        (error: unknown) => error
+      );
+
+  it('a socket from before the reset stops receiving edges, a fresh sign-in keeps them', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale] = await alice('signup');
+    const staleSeen = await watchEdges(stale);
+    await edge(1);
+    await expect.poll(() => staleSeen.length).toBe(1);
+
+    await resetPassword(stale);
+    const [fresh] = await alice('signin');
+    const freshSeen = await watchEdges(fresh);
+    await edge(2);
+    await edge(3);
+
+    await expect.poll(() => freshSeen.length).toBe(2);
+    await sleep(200);
+    expect(staleSeen.length).toBe(1);
+  });
+
+  it('a socket from before the reset reads none of its user\'s edges, views or rows', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale, staleSid] = await alice('signup');
+    await edge(1);
+    await root.query(
+      `CREATE _00_list_ref:1 SET in = _00_query:q, out = game:1, clientId = 'x', auth_id = 'user:alice', version = 1`
+    );
+    await resetPassword(stale);
+    const [fresh, freshSid] = await alice('signin');
+    const q = viewId();
+    await root.query(SSP_REGISTER, { id: q, sid: staleSid });
+    await root.query(SSP_REGISTER, { id: q, sid: freshSid });
+
+    for (const table of ['_00_list_ref_user_alice', '_00_list_ref', 'game']) {
+      expect(await stale.query(`SELECT VALUE id FROM ${table}`), table).toEqual([[]]);
+      expect(((await fresh.query(`SELECT VALUE id FROM ${table}`)) as [unknown[]])[0], table).toHaveLength(1);
+    }
+    expect(await readBack(stale, q)).toBeNull();
+    expect(await heartbeatFound(stale, q)).toBe(false);
+    expect(await readBack(fresh, q)).toEqual({ rowCount: 1, state: 'ready' });
+    expect(await heartbeatFound(fresh, q)).toBe(true);
+  });
+
+  it('fn::query::register refuses the stale socket as a refused session, and only that one', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale] = await alice('signup');
+    expect(isRefusedSessionError(await registerError(stale))).toBe(false);
+
+    await resetPassword(stale);
+    const [fresh] = await alice('signin');
+
+    const refused = await registerError(stale);
+    expect(isRefusedSessionError(refused), String(refused)).toBe(true);
+    expect(isRefusedSessionError(await registerError(fresh))).toBe(false);
+  });
+
+  it('without a sessionGuard every session stays live, as before the guard', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot();
+    const [stale, staleSid] = await alice('signup');
+    await edge(1);
+    const q = viewId();
+    await root.query(SSP_REGISTER, { id: q, sid: staleSid });
+    await resetPassword(stale);
+
+    expect(((await stale.query('SELECT VALUE id FROM _00_list_ref_user_alice')) as [unknown[]])[0]).toHaveLength(1);
+    expect(await heartbeatFound(stale, q)).toBe(true);
+    expect(isRefusedSessionError(await registerError(stale))).toBe(false);
+  });
+
+  it('a database without the probe row lets every registration through', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale] = await alice('signup');
+    await resetPassword(stale);
+    await root.query('DELETE _00_session_guard:probe');
+
+    expect(isRefusedSessionError(await registerError(stale))).toBe(false);
+  });
+});

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,174 @@
+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 };
+}
+
+/**
+ * Hand back view ids this page no longer answers to. Per id,
+ * `fn::query::unsubscribe` drops this socket's entry and deletes the row when
+ * nobody else watches it; `fn::query::leave` then drops the entries of this
+ * page's earlier sockets (a reconnect re-registered under a new session id)
+ * and pulls the expiry in when none remain. Result index 2i answers the
+ * unsubscribe of id i, 2i + 1 its leave.
+ */
+export function releaseBatch(ids: ReadonlyArray<RecordId<string>>, sessionIds: ReadonlyArray<string>): { sql: string; vars: Vars } {
+  const vars: Vars = { sids: [...sessionIds] };
+  const stmts = ids.flatMap((id, i) => {
+    vars[`id${i}`] = id;
+    return [`fn::query::unsubscribe($id${i})`, `fn::query::leave($id${i}, $sids)`];
+  });
+  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');
+  });
+});