@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.321

package/src/query/register.saga.ts

@@ -0,0 +1,229 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { RecordId } from 'surrealdb';
+import type { QueryHash, QueryTimeToLive } from '../types';
+import type { Saga } from '../kernel/saga';
+import type { RegisterResult, StatementResult } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import { AUTH_READY_MAX_ATTEMPTS, AUTH_READY_RETRY_MS, REGISTER_MAX_RETRIES, backoffMs } from '../kernel/constants';
+import type { ClientState, QueryEntry } from '../state/client-state';
+import { emptyTelemetry } from '../state/client-state';
+import { seedLifecycle } from '../state/lifecycle';
+import * as R from '../state/reducers';
+import { desiredRegistrations } from '../state/selectors';
+import { parseDuration } from '../utils/index';
+import type { SagaEnv } from './env';
+import { listRefTable } from './env';
+import { queryHashInput, viewKeyInput } from './hash';
+import { FAILED, isResolvedBefore, parseViewRow, snapshotFromSingle } from './membership';
+import { applyMembership, applySubqueryChildren, markMembershipDirty } from './membership.saga';
+import * as sql from './sql';
+
+export interface RegisterInput {
+  tableName: string;
+  surql: string;
+  params: Record<string, unknown>;
+  ttl: QueryTimeToLive;
+  plan?: QueryPlan;
+}
+
+/**
+ * Register a query locally: compute its keys, read the durable `_00_view`
+ * row, build the SSP local view and publish the entry. Returns as soon as the
+ * entry exists (the first paint comes from `materialize`); the remote
+ * registration is dispatched, never awaited.
+ */
+export function* registerLocal(env: SagaEnv, input: RegisterInput): Saga<QueryHash> {
+  const sessionId = (yield fx.state.read((s) => s.sessionId)) as string | null;
+  const hash = (yield fx.hash(queryHashInput(input, sessionId))) as string;
+  const status = (yield fx.state.read((s) => (s.queries.has(hash) ? 'active' : s.registering.has(hash) ? 'pending' : 'new'))) as
+    | 'active'
+    | 'pending'
+    | 'new';
+  if (status === 'active') return hash;
+  if (status === 'pending') {
+    yield fx.state.wait((s) => !s.registering.has(hash));
+    return hash;
+  }
+  yield fx.state.update(R.beginRegistering(hash));
+  try {
+    const viewKey = (yield fx.hash(viewKeyInput(input))) as string;
+    let viewRow: unknown = null;
+    try {
+      viewRow = yield fx.local.getById(sql.VIEW_TABLE, sql.viewRecordId(viewKey));
+    } catch {
+      viewRow = null;
+    }
+    const view = parseViewRow(viewRow);
+    const now = (yield fx.now()) as number;
+    const reg = (yield fx.ssp.register({
+      queryHash: hash,
+      surql: input.surql,
+      params: input.params,
+      ttl: input.ttl,
+      tableName: input.tableName,
+    })) as RegisterResult;
+    const entry: QueryEntry = {
+      def: {
+        id: new RecordId('_00_query', hash),
+        hash,
+        viewKey,
+        surql: input.surql,
+        params: input.params,
+        plan: input.plan,
+        ttl: input.ttl,
+        ttlMs: parseDuration(input.ttl),
+        tableName: input.tableName,
+        createdAt: now,
+      },
+      lifecycle: seedLifecycle(isResolvedBefore(view)),
+      remoteArray: view?.ids ?? [],
+      localArray: reg.localArray,
+      subqueryRemoteArray: [],
+      records: [],
+      serverState: null,
+      subscribers: 0,
+      lastSubscriberLeftAt: now,
+      lastHeartbeatAt: null,
+      lastPolledAt: null,
+      registerAttempts: 0,
+      viewLostCount: 0,
+      viewLostRetryAt: null,
+      telemetry: { ...emptyTelemetry(), registrationTimings: reg.timings },
+    };
+    yield fx.state.update(R.putQuery(entry));
+    yield fx.dispatch({ type: 'EnsureRegistered' });
+    return hash;
+  } finally {
+    yield fx.state.update(R.endRegistering(hash));
+  }
+}
+
+/**
+ * Make the remote match the desired set: start a registration for every
+ * query that has none. Idempotent. With `requireAuth` (after a reconnect or
+ * while degraded) it first waits for `$auth.id` to be visible on the socket:
+ * a register issued before that stamps the view with an empty identity.
+ */
+export function* ensureRegistered(env: SagaEnv, opts: { requireAuth?: boolean; attempt?: number } = {}): Saga<void> {
+  const [hashes, userId] = (yield fx.state.read((s) => [desiredRegistrations(s), s.userId])) as [QueryHash[], string | null];
+  if (hashes.length === 0) return;
+  if (opts.requireAuth && userId !== null) {
+    let authed = false;
+    try {
+      const res = (yield fx.remote.query('RETURN $auth.id', undefined, env.remoteTimeoutMs)) as StatementResult[];
+      authed = res[0]?.status === 'OK' && res[0].result != null;
+    } catch {
+      authed = false;
+    }
+    if (!authed) {
+      const attempt = (opts.attempt ?? 0) + 1;
+      if (attempt >= AUTH_READY_MAX_ATTEMPTS) {
+        yield fx.emit({ type: 'log', level: 'warn', message: 'auth identity never became visible; not registering', data: { attempt } });
+        return;
+      }
+      yield fx.timer.set('ensure-registered', AUTH_READY_RETRY_MS, { type: 'EnsureRegistered', requireAuth: true, attempt });
+      return;
+    }
+  }
+  for (const hash of hashes) yield fx.dispatch({ type: 'RegisterRemote', hash });
+}
+
+const stmt = (results: StatementResult[], i: number): StatementResult | undefined => results[i];
+
+/**
+ * The SSP answers a registration whose shape is not on the query allowlist
+ * with HTTP 403 `{"error":"not_allowlisted"}`. It reaches the client as the
+ * `fn::query::register` statement error carrying SurrealDB's http error text
+ * (status reason and/or body), and no retry can change the answer.
+ */
+export const isNotAllowlisted = (error: unknown): boolean =>
+  /not_allowlisted|\b403\b|forbidden/i.test(String((error as { message?: unknown })?.message ?? error));
+
+/**
+ * One remote registration: `fn::query::register` plus the edge/meta/children
+ * read in ONE request, then membership application. Concurrent with every
+ * other registration; retried on its own backoff; stops when the entry is
+ * gone.
+ */
+export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  const entry = state.queries.get(hash);
+  if (!entry) return;
+  const { remote } = entry.lifecycle;
+  if (remote === 'registered' || remote === 'failed' || (remote === 'registering' && !retry)) return;
+  // A query that already shows rows (cached or live) only re-verifies them
+  // here: the cycle holds `fetching` but is not traffic the user waits on.
+  const background = entry.lifecycle.phase !== 'cold';
+  yield fx.state.update(
+    R.compose(R.applyLifecycle(hash, { type: 'remote-registering' }), R.applyLifecycle(hash, { type: 'fetch-begin', background }))
+  );
+  try {
+    const table = listRefTable(env, state);
+    const results = (yield fx.remote.query(
+      sql.registerSelect(table),
+      sql.registerVars({ id: entry.def.id, surql: entry.def.surql, params: { ...entry.def.params }, ttl: entry.def.ttl }),
+      env.remoteTimeoutMs
+    )) as StatementResult[];
+    const stillThere = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+    if (!stillThere) return;
+    const register = stmt(results, 0);
+    if (!register || register.status === 'ERR') throw new Error(register?.status === 'ERR' ? register.error : 'register returned nothing');
+    const answer = (r: StatementResult | undefined): unknown => (r?.status === 'OK' ? r.result : FAILED);
+    const snap = snapshotFromSingle(
+      answer(stmt(results, 1)) as never,
+      answer(stmt(results, 2)) as never,
+      answer(stmt(results, 3)) as never
+    );
+    if (!snap) {
+      // Registered, but the read-back did not answer. That says nothing about
+      // the row, so read membership again rather than guess: a guess of
+      // "gone" re-registered the query, and under load the next read-back
+      // failed the same way.
+      yield fx.state.update(R.compose(R.applyLifecycle(hash, { type: 'remote-registered' }), R.resetRegisterAttempts(hash)));
+      yield fx.emit({ type: 'log', level: 'debug', message: 'registration read-back did not answer; re-reading membership', data: { hash } });
+      yield* markMembershipDirty([hash]);
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error: 'registration read-back failed' });
+      return;
+    }
+    const outcome = yield* applyMembership(hash, snap.primary, snap.meta);
+    if (outcome === 'ignored' && snap.meta.present && snap.meta.state === 'materializing') {
+      yield fx.state.update(R.compose(R.markMembershipDirty([hash]), R.setMembershipReread(hash, 1)));
+      yield fx.timer.set('membership', 150, { type: 'ReadDirtyMembership' });
+    }
+    yield* applySubqueryChildren(hash, snap.subquery);
+    yield fx.state.update(R.compose(R.applyLifecycle(hash, { type: 'remote-registered' }), R.resetRegisterAttempts(hash)));
+    yield fx.dispatch({ type: 'SyncOutcome', ok: true });
+  } catch (error) {
+    const current = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+    if (!current) return;
+    if (isNotAllowlisted(error)) {
+      yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-failed' }));
+      yield fx.emit({
+        type: 'log',
+        level: 'error',
+        message: 'query refused: not allowlisted',
+        data: {
+          hash,
+          table: entry.def.tableName,
+          surql: entry.def.surql,
+          params: Object.keys(entry.def.params),
+          hint: 'Add or regenerate the query allowlist: spky generate, then spky deploy (or restart spky dev).',
+        },
+      });
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+      return;
+    }
+    const attempts = current.registerAttempts + 1;
+    yield fx.state.update(R.bumpRegisterAttempts(hash));
+    yield fx.emit({ type: 'log', level: 'warn', message: 'remote registration failed', data: { hash, attempts, error } });
+    yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+    if (attempts >= REGISTER_MAX_RETRIES) {
+      yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-failed' }));
+    } else {
+      yield fx.timer.set(`register:${hash}`, backoffMs(attempts), { type: 'RegisterRemote', hash, retry: true });
+    }
+  } finally {
+    const stillThere = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+    if (stillThere) yield fx.state.update(R.applyLifecycle(hash, { type: 'fetch-end', background }));
+  }
+}

package/src/query/render-set.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { buildRenderIds, paintsCold, resolveMembership } from './render-set';
+
+const ov = (writes: string[] = [], deletes: string[] = []) => ({ writes: new Set(writes), deletes: new Set(deletes) });
+
+describe('resolveMembership', () => {
+  it('cold scans, cold window uses the local view, anything else uses membership', () => {
+    const remoteArray: [string, number][] = [['t:1', 1]];
+    const localArray: [string, number][] = [['t:2', 1]];
+    expect(resolveMembership({ phase: 'cold', remoteArray, localArray, isWindow: false })).toBeNull();
+    expect(resolveMembership({ phase: 'cold', remoteArray, localArray, isWindow: true })).toBe(localArray);
+    expect(resolveMembership({ phase: 'cached', remoteArray, localArray, isWindow: false })).toBe(remoteArray);
+    expect(resolveMembership({ phase: 'view-lost', remoteArray, localArray, isWindow: true })).toBe(remoteArray);
+  });
+});
+
+describe('buildRenderIds', () => {
+  const opts = { hasExplicitOrder: false, isWindow: false };
+  it('membership minus deletes, sorted', () => {
+    expect(buildRenderIds([['t:b', 1], ['t:a', 1], ['t:c', 1]], [], ov([], ['t:c']), opts)).toEqual(['t:a', 't:b']);
+  });
+  it('adds pending writes the local view admits, never twice, never deleted', () => {
+    const ids = buildRenderIds(
+      [['t:1', 1]],
+      [['t:1', 1], ['t:2', 1], ['t:3', 1], ['t:4', 1]],
+      ov(['t:1', 't:2', 't:3', 't:9'], ['t:3']),
+      opts
+    );
+    expect(ids).toEqual(['t:1', 't:2']);
+  });
+  it('keeps server order for windows and explicit orderBy; dedupes membership', () => {
+    const m: [string, number][] = [['t:b', 1], ['t:a', 1], ['t:b', 1]];
+    expect(buildRenderIds(m, [], ov(), { hasExplicitOrder: true, isWindow: false })).toEqual(['t:b', 't:a']);
+    expect(buildRenderIds(m, [], ov(), { hasExplicitOrder: false, isWindow: true })).toEqual(['t:b', 't:a']);
+  });
+});
+
+describe('paintsCold', () => {
+  it('only vouched bodies, optimistic writes and bookkeeping paint before the server answers', () => {
+    const vouched = new Set(['t:1']);
+    expect(paintsCold('t:1', vouched, ov())).toBe(true);
+    expect(paintsCold('t:2', vouched, ov(['t:2']))).toBe(true);
+    expect(paintsCold('_00_user_feature:f', vouched, ov())).toBe(true);
+    expect(paintsCold('t:3', vouched, ov([], ['t:3']))).toBe(false);
+    expect(paintsCold('t:3', vouched, ov())).toBe(false);
+  });
+});

package/src/query/render-set.ts

@@ -0,0 +1,71 @@
+import type { RecordVersionArray } from '../types';
+import type { QueryPhase } from '../state/lifecycle';
+import type { Overlay } from '../state/selectors';
+
+export interface RenderInput {
+  phase: QueryPhase;
+  remoteArray: RecordVersionArray;
+  localArray: RecordVersionArray;
+  isWindow: boolean;
+}
+
+/**
+ * The id-set a query renders from, or `null` when it must fall back to a
+ * local predicate scan (a cold query that was never resolved on this device).
+ * A cold window has no usable scan (re-applying `START m` against the shared
+ * store returns the wrong rows), so it renders the SSP's local window instead.
+ */
+export function resolveMembership(input: RenderInput): RecordVersionArray | null {
+  if (input.phase !== 'cold') return input.remoteArray;
+  if (input.isWindow) return input.localArray;
+  return null;
+}
+
+/**
+ * Whether a body may paint before the server has answered (`cold`). One no
+ * durable view vouches for and no optimistic write touches is an orphan:
+ * deleted upstream while no view watched it, or dropped from every view since.
+ * The predicate scan would otherwise resurrect it until the server answers,
+ * and indefinitely offline.
+ */
+export function paintsCold(id: string, vouched: ReadonlySet<string>, overlay: Overlay): boolean {
+  return id.startsWith('_00_') || vouched.has(id) || overlay.writes.has(id);
+}
+
+export interface RenderOptions {
+  hasExplicitOrder: boolean;
+  isWindow: boolean;
+}
+
+/**
+ *   render = (membership ∪ (writes ∩ localView)) − deletes
+ *
+ * `writes`/`deletes` are the outbox overlay (pending and acked items). The
+ * middle term keeps optimistic writes visible without re-admitting stale rows:
+ * `localView` (the SSP's local id-set) says whether the written row matches
+ * the query per local truth. Sorted unless the query orders itself or is a
+ * window (whose id order is the slice order).
+ */
+export function buildRenderIds(
+  membership: RecordVersionArray,
+  localView: RecordVersionArray,
+  overlay: Overlay,
+  opts: RenderOptions
+): string[] {
+  const ordered: string[] = [];
+  const seen = new Set<string>();
+  for (const [id] of membership) {
+    if (overlay.deletes.has(id) || seen.has(id)) continue;
+    seen.add(id);
+    ordered.push(id);
+  }
+  if (overlay.writes.size > 0) {
+    for (const [id] of localView) {
+      if (!overlay.writes.has(id) || overlay.deletes.has(id) || seen.has(id)) continue;
+      seen.add(id);
+      ordered.push(id);
+    }
+  }
+  if (!opts.hasExplicitOrder && !opts.isWindow) ordered.sort();
+  return ordered;
+}

package/src/query/sql.test.ts

@@ -0,0 +1,112 @@
+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,
+    });
+  });
+  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,149 @@
+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;
+}
+
+/** 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 };
+}