@spooky-sync/core 0.0.1-canary.34 → 0.0.1-canary.340

package/src/query/register.saga.ts

@@ -0,0 +1,235 @@
+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,
+        ...(state.ownerSecret ? { owner: state.ownerSecret } : {}),
+      }),
+      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/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);
+  });
+});