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

package/src/query/lifecycle.saga.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from './env';
+import { ackPrune, evictQuery, gcTick, lifecycleTick, loadViews } from './lifecycle.saga';
+import type { StatementResult } from '../kernel/effects';
+
+const env = defaultEnv({ tables: [] } as any);
+const ok = (result: unknown): StatementResult => ({ status: 'OK', result });
+
+describe('lifecycleTick', () => {
+  it('evicts idle queries (even when the SSP unregister throws), heartbeats the registered rest, reschedules at half the shortest ttl', async () => {
+    const now = 1_700_000_000_000;
+    const s = buildState([
+      buildEntry({ def: { hash: 'idle', ttlMs: 100 }, lastSubscriberLeftAt: now - 200, lifecycle: { remote: 'registered' } }),
+      buildEntry({ def: { hash: 'idle2', ttlMs: 100 }, lastSubscriberLeftAt: now - 200 }),
+      buildEntry({ def: { hash: 'kept', ttlMs: 1000, id: new RecordId('_00_query', 'kept') }, subscribers: 1, lifecycle: { remote: 'registered' } }),
+      buildEntry({ def: { hash: 'unreg', ttlMs: 500 }, subscribers: 1 }),
+    ]);
+    let unregisters = 0;
+    const out = await runPure(lifecycleTick(env), {
+      state: s,
+      now,
+      handlers: {
+        'ssp.unregister': () => {
+          unregisters++;
+          if (unregisters === 1) throw new Error('gone');
+        },
+        'remote.query': (e: any) => {
+          expect(e.sql).toBe('fn::query::heartbeat($id0)');
+          expect(e.vars.id0).toEqual(new RecordId('_00_query', 'kept'));
+          return [ok([{ id: 'x' }])];
+        },
+      },
+    });
+    expect([...out.state.queries.keys()]).toEqual(['kept', 'unreg']);
+    expect(out.emitted.filter((e) => e.type === 'query:evicted')).toHaveLength(2);
+    expect(out.state.queries.get('kept')!.lastHeartbeatAt).toBe(now);
+    expect(out.dispatched).toEqual([{ type: 'SyncOutcome', ok: true }]);
+    expect(out.timers.get('lifecycle')).toEqual({ ms: 250, event: { type: 'LifecycleTick' } });
+  });
+  it('a reclaimed row drops the registration and re-registers; a failed beat reports; empty state uses the default ttl', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' }, subscribers: 1, lifecycle: { remote: 'registered' } })]);
+    const reclaimed = await runPure(lifecycleTick(env), { state: s, handlers: { 'remote.query': () => [ok([])] } });
+    expect(reclaimed.state.queries.get('a')!.lifecycle.remote).toBe('unregistered');
+    expect(reclaimed.dispatched).toEqual([{ type: 'EnsureRegistered' }, { type: 'SyncOutcome', ok: true }]);
+    const failed = await runPure(lifecycleTick(env), {
+      state: s,
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(failed.dispatched).toEqual([{ type: 'SyncOutcome', ok: false, error: new Error('offline') }]);
+    const empty = await runPure(lifecycleTick(env), { state: buildState() });
+    expect(empty.timers.get('lifecycle')!.ms).toBe(300_000);
+  });
+});
+
+describe('ackPrune', () => {
+  it('drops expired acked items and re-arms while some remain', async () => {
+    const now = 100_000;
+    const s = buildState([], R.outboxReplace([
+      buildOutboxItem({ id: 'old', status: 'acked', ackedAt: now - 31_000 }),
+      buildOutboxItem({ id: 'fresh', status: 'acked', ackedAt: now - 1000 }),
+    ]));
+    const out = await runPure(ackPrune(), { state: s, now });
+    expect(out.state.outbox.map((i) => i.id)).toEqual(['fresh']);
+    expect(out.timers.get('ack-prune')).toEqual({ ms: 30_000, event: { type: 'AckPrune' } });
+    const done = await runPure(ackPrune(), { state: out.state, now: now + 60_000 });
+    expect(done.timers.size).toBe(0);
+  });
+});
+
+describe('loadViews', () => {
+  it('fills the index from every _00_view row (members and children); a failed read leaves it empty', async () => {
+    const rows = [
+      { id: '_00_view:a', ids: [['t:1', 1]], children: [['c:1', 1], 'junk'] },
+      { id: new RecordId('_00_view', 'b'), ids: [] },
+      { id: '', ids: [] },
+      { ids: [['t:no-key', 1]] },
+      null,
+    ];
+    const out = await runPure(loadViews(), { state: buildState(), handlers: { 'local.query': () => [rows] } });
+    expect(out.state.views).toEqual(new Map([['a', ['t:1', 'c:1']], ['b', []]]));
+    const odd = await runPure(loadViews(), { state: buildState(), handlers: { 'local.query': () => undefined } });
+    expect(odd.state.views.size).toBe(0);
+    const failed = await runPure(loadViews(), {
+      state: buildState(),
+      handlers: {
+        'local.query': () => {
+          throw new Error('no table');
+        },
+      },
+    });
+    expect(failed.state.views.size).toBe(0);
+    expect(failed.emitted).toEqual([expect.objectContaining({ level: 'warn', message: 'view index read failed' })]);
+  });
+});
+
+describe('gcTick', () => {
+  const day = 24 * 60 * 60 * 1000;
+  const now = 100 * day;
+  const ready = R.setIdentity({ primed: true, bucketId: 'u1' });
+  const deletedIds = (log: Array<{ kind: string }>) =>
+    log.filter((e: any) => e.kind === 'local.delete').map((e: any) => (e.table === '_00_view' ? `view:${e.id.id}` : e.id));
+
+  it('retires stale view rows, deletes the bodies nothing retains from the store and the circuit, re-fetches, reschedules', async () => {
+    const s = buildState(
+      [buildEntry({ def: { hash: 'h', viewKey: 'held' }, lifecycle: { phase: 'cached' }, remoteArray: [['thing:mem', 1]] })],
+      ready,
+      R.setVersions(
+        ['thing:keep', 'child:1', 'thing:stale', 'thing:held', 'thing:stuck', 'thing:mem', 'thing:gone', 'thing:pending', '_00_view:x', 'thing:failed'].map(
+          (id) => [id, 1] as const
+        )
+      ),
+      R.outboxReplace([buildOutboxItem({ recordId: 'thing:pending' })])
+    );
+    const rows = [
+      { id: '_00_view:fresh', ids: [['thing:keep', 1]], children: [['child:1', 1]], updatedAt: now - day },
+      // Nobody resolved this query for 15 days: the row is retired and stops vouching.
+      { id: new RecordId('_00_view', 'old'), ids: [['thing:stale', 1]], updatedAt: now - 15 * day },
+      // As old, but a query in state holds it.
+      { id: '_00_view:held', ids: [['thing:held', 1]] },
+      // As old, but its delete fails: it keeps vouching.
+      { id: '_00_view:stuck', ids: [['thing:stuck', 1]], updatedAt: 0 },
+      { ids: 'bad' },
+    ];
+    const out = await runPure(gcTick(), {
+      state: s,
+      now,
+      handlers: {
+        'local.query': (e: any) => {
+          expect(e.sql).toBe('SELECT * FROM _00_view');
+          return [rows];
+        },
+        'local.delete': (e: any) => {
+          if (e.id === 'thing:failed' || e.id?.id === 'stuck') throw new Error('busy');
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(deletedIds(out.log)).toEqual(['view:old', 'view:stuck', 'thing:stale', 'thing:gone', 'thing:failed']);
+    expect(out.state.views).toEqual(
+      new Map([
+        ['fresh', ['thing:keep', 'child:1']],
+        ['held', ['thing:held']],
+        ['stuck', ['thing:stuck']],
+      ])
+    );
+    expect([...out.state.versions.keys()]).toEqual(['thing:keep', 'child:1', 'thing:held', 'thing:stuck', 'thing:mem', 'thing:pending', '_00_view:x', 'thing:failed']);
+    const ingest = out.log.find((e) => e.kind === 'ssp.ingest') as any;
+    expect(ingest.records).toEqual([
+      { table: 'thing', op: 'DELETE', id: 'thing:stale', record: {} },
+      { table: 'thing', op: 'DELETE', id: 'thing:gone', record: {} },
+    ]);
+    // Solo: nobody to relay to.
+    expect(out.emitted.filter((e) => e.type === 'tabs:broadcast')).toEqual([]);
+    expect(out.emitted).toContainEqual(expect.objectContaining({ message: 'orphan gc done', data: { removed: 2, retiredViews: 1 } }));
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }]);
+    expect(out.timers.get('gc')).toEqual({ ms: 60 * 60 * 1000, event: { type: 'GcTick' } });
+  });
+
+  it('waits for the circuit prime (the versions); a leader relays its deletes to the other tabs', async () => {
+    const s = buildState([], R.setIdentity({ bucketId: 'u1' }), R.setTabRole('leader'), R.setVersions([['thing:gone', 1]]));
+    const out = await runPure(gcTick(), {
+      state: s,
+      handlers: {
+        'state.wait': (e: any, ctx) => {
+          expect(e.until(ctx.state)).toBe(false);
+          ctx.state = R.setIdentity({ primed: true })(ctx.state);
+        },
+        'local.query': () => [[]],
+        'local.delete': () => undefined,
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(out.emitted).toContainEqual({
+      type: 'tabs:broadcast',
+      message: { type: 'ingest', records: [{ table: 'thing', op: 'DELETE', id: 'thing:gone', record: {} }] },
+    });
+  });
+
+  it('a follower only refreshes its index: no view row or body is deleted', async () => {
+    const s = buildState([], ready, R.setTabRole('follower'), R.setVersions([['thing:gone', 1]]));
+    const out = await runPure(gcTick(), {
+      state: s,
+      now,
+      handlers: { 'local.query': () => [[{ id: '_00_view:old', ids: [['thing:x', 1]], updatedAt: 0 }]] },
+    });
+    expect(out.state.views).toEqual(new Map([['old', ['thing:x']]]));
+    expect(deletedIds(out.log)).toEqual([]);
+    expect(out.state.versions.has('thing:gone')).toBe(true);
+    expect(out.timers.has('gc')).toBe(true);
+  });
+
+  it('each chunk is re-checked against fresh state, and the sweep stops when the bucket moves', async () => {
+    const ids = Array.from({ length: 250 }, (_, i) => `thing:o${i}`);
+    const s = buildState([], ready, R.setVersions(ids.map((id) => [id, 1] as const)));
+    const handlers = (onFirst: (ctx: any) => void) => ({
+      'local.query': () => [[]],
+      'local.delete': (e: any, ctx: any) => {
+        if (e.id === 'thing:o0') onFirst(ctx);
+      },
+      'ssp.ingest': () => undefined,
+    });
+    // Meanwhile a query commits o210 and o220's body goes another way: neither is deleted.
+    const recheck = await runPure(gcTick(), {
+      state: s,
+      handlers: handlers((ctx) => {
+        ctx.state = R.compose(R.putQuery(buildEntry({ def: { hash: 'q' }, remoteArray: [['thing:o210', 1]] })), R.deleteVersions(['thing:o220']))(ctx.state);
+      }),
+    });
+    const removed = deletedIds(recheck.log);
+    expect(removed).toHaveLength(248);
+    expect(removed).not.toContain('thing:o210');
+    expect(removed).not.toContain('thing:o220');
+    expect(recheck.log.filter((e) => e.kind === 'ssp.ingest')).toHaveLength(2);
+    const moved = await runPure(gcTick(), { state: s, handlers: handlers((ctx) => (ctx.state = R.setIdentity({ bucketId: 'u2' })(ctx.state))) });
+    expect(deletedIds(moved.log)).toHaveLength(200);
+    expect(moved.timers.has('gc')).toBe(true);
+  });
+
+  it('failures are logged and the tick still reschedules; a sweep that removes nothing asks for nothing', async () => {
+    const s = buildState([], ready, R.setVersions([['thing:gone', 1]]));
+    const readFails = await runPure(gcTick(), {
+      state: s,
+      handlers: {
+        'local.query': () => {
+          throw new Error('no table');
+        },
+      },
+    });
+    expect(readFails.emitted).toEqual([expect.objectContaining({ message: 'orphan gc failed' })]);
+    expect(readFails.timers.has('gc')).toBe(true);
+    const ingestFails = await runPure(gcTick(), {
+      state: s,
+      handlers: {
+        'local.query': () => [[]],
+        'local.delete': () => undefined,
+        'ssp.ingest': () => {
+          throw new Error('wasm');
+        },
+      },
+    });
+    expect(ingestFails.emitted).toEqual([expect.objectContaining({ message: 'orphan gc failed' })]);
+    expect(ingestFails.timers.has('gc')).toBe(true);
+    const deleteFails = await runPure(gcTick(), {
+      state: s,
+      handlers: {
+        'local.query': () => [[]],
+        'local.delete': () => {
+          throw new Error('busy');
+        },
+      },
+    });
+    expect(deleteFails.log.filter((e) => e.kind === 'ssp.ingest')).toHaveLength(0);
+    expect(deleteFails.dispatched).toEqual([]);
+    expect(deleteFails.emitted).toContainEqual(expect.objectContaining({ message: 'orphan gc done', data: { removed: 0, retiredViews: 0 } }));
+    const nothing = await runPure(gcTick(), { state: buildState([], ready), handlers: { 'local.query': () => [] } });
+    expect(nothing.log.filter((e) => e.kind === 'local.delete')).toHaveLength(0);
+    expect(nothing.dispatched).toEqual([]);
+  });
+});
+
+describe('evictQuery', () => {
+  it('is a no-op for unknown hashes', async () => {
+    const out = await runPure(evictQuery('zz'), { state: buildState() });
+    expect(out.emitted).toEqual([]);
+  });
+});

package/src/query/lifecycle.saga.ts

@@ -0,0 +1,159 @@
+import type { Saga } from '../kernel/saga';
+import type { Settled, StatementResult } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import { ACK_GRACE_MS, GC_CHUNK, GC_INTERVAL_MS, TTL_HEARTBEAT_FRACTION, VIEW_RETENTION_MS } from '../kernel/constants';
+import type { IngestRecord } from '../services/stream-processor/index';
+import type { ClientState, QueryEntry, TabRole } from '../state/client-state';
+import * as R from '../state/reducers';
+import { evictable, retained, shortestTtlMs } from '../state/selectors';
+import type { SagaEnv } from './env';
+import { parseViewIndex, type ViewIndexRow } from './membership';
+import * as sql from './sql';
+
+/**
+ * One tick for every query in state: evict the ones nobody has watched for a
+ * ttl, heartbeat the rest in one request, notice reclaimed rows. Reschedules
+ * itself at half the shortest ttl.
+ */
+export function* lifecycleTick(env: SagaEnv): Saga<void> {
+  const now = (yield fx.now()) as number;
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  for (const hash of evictable(state, now)) yield* evictQuery(hash);
+  const remaining = (yield fx.state.read((s) => [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered'))) as QueryEntry[];
+  if (remaining.length > 0) {
+    const beat = sql.heartbeatBatch(remaining.map((e) => e.def.id));
+    try {
+      const results = (yield fx.remote.query(beat.sql, beat.vars, env.remoteTimeoutMs)) as StatementResult[];
+      let reclaimed = 0;
+      for (let i = 0; i < remaining.length; i++) {
+        const r = results[i];
+        if (r?.status === 'OK' && sql.heartbeatRowGone(r.result)) {
+          reclaimed++;
+          yield fx.state.update(R.applyLifecycle(remaining[i].def.hash, { type: 'remote-dropped' }));
+        }
+      }
+      yield fx.state.update(R.stampHeartbeat(remaining.map((e) => e.def.hash), now));
+      if (reclaimed > 0) {
+        yield fx.emit({ type: 'log', level: 'warn', message: 'query rows reclaimed by the server; re-registering', data: { reclaimed } });
+        yield fx.dispatch({ type: 'EnsureRegistered' });
+      }
+      yield fx.dispatch({ type: 'SyncOutcome', ok: true });
+    } catch (error) {
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+    }
+  }
+  const ttl = (yield fx.state.read((s) => shortestTtlMs(s))) as number | null;
+  yield fx.timer.set('lifecycle', Math.floor((ttl ?? env.defaultTtlMs) * TTL_HEARTBEAT_FRACTION), { type: 'LifecycleTick' });
+}
+
+/** Free a query's local view and forget it. The server row expires by TTL. */
+export function* evictQuery(hash: string): Saga<void> {
+  const exists = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+  if (!exists) return;
+  try {
+    yield fx.ssp.unregister(hash);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'debug', message: 'unregister failed', data: { hash, error } });
+  }
+  yield fx.state.update(R.removeQuery(hash));
+  yield fx.emit({ type: 'query:evicted', hash });
+}
+
+/** Drop acked outbox items membership never named within the grace window. */
+export function* ackPrune(): Saga<void> {
+  const now = (yield fx.now()) as number;
+  yield fx.state.update(R.outboxPruneAcked(now, ACK_GRACE_MS));
+  const stillAcked = (yield fx.state.read((s) => s.outbox.some((i) => i.status === 'acked'))) as boolean;
+  if (stillAcked) yield fx.timer.set('ack-prune', ACK_GRACE_MS, { type: 'AckPrune' });
+}
+
+/** Every `_00_view` row, parsed. Throws when the read fails. */
+function* readViews(): Saga<ViewIndexRow[]> {
+  const res = (yield fx.local.query(sql.readViewRows())) as unknown[];
+  return parseViewIndex(Array.isArray(res) ? res[0] : undefined);
+}
+
+const indexOf = (rows: ViewIndexRow[]): Map<string, string[]> => new Map(rows.map((r) => [r.key, r.ids]));
+
+/**
+ * Load the durable view index (boot, bucket switch). A failed read leaves it
+ * empty, which fails closed: cold scans paint nothing until the server answers.
+ */
+export function* loadViews(): Saga<void> {
+  try {
+    yield fx.state.update(R.reloadViews(indexOf(yield* readViews())));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'view index read failed', data: { error } });
+  }
+}
+
+const tableOf = (id: string): string => id.slice(0, id.indexOf(':'));
+
+/**
+ * Orphan collection, `GC_BOOT_DELAY_MS` after boot and then every
+ * `GC_INTERVAL_MS`. Re-reads every `_00_view` row into the index, retires the
+ * rows no query has resolved for `VIEW_RETENTION_MS`, then deletes the bodies
+ * nothing retains (see `retained`) from the store and the circuit, a chunk at
+ * a time. Only a leader or solo tab deletes, and a leader relays the deletes
+ * so followers drop the rows too; a follower only refreshes its index.
+ */
+export function* gcTick(): Saga<void> {
+  yield fx.state.wait((s) => s.primed);
+  try {
+    const rows = yield* readViews();
+    const [role, bucket, held] = (yield fx.state.read((s) => [
+      s.tabRole,
+      s.bucketId,
+      new Set([...s.queries.values()].map((e) => e.def.viewKey)),
+    ])) as [TabRole, string | null, Set<string>];
+    const now = (yield fx.now()) as number;
+    const expired = role === 'follower' ? [] : rows.filter((r) => !held.has(r.key) && now - r.updatedAt >= VIEW_RETENTION_MS);
+    const retired = new Set<string>();
+    for (let i = 0; i < expired.length; i += GC_CHUNK) {
+      const chunk = expired.slice(i, i + GC_CHUNK);
+      const settled = (yield fx.all(chunk.map((r) => fx.local.delete(sql.VIEW_TABLE, sql.viewRecordId(r.key))))) as Settled[];
+      chunk.forEach((r, j) => settled[j].ok && retired.add(r.key));
+    }
+    yield fx.state.update(R.reloadViews(indexOf(rows.filter((r) => !retired.has(r.key)))));
+    if (role === 'follower') return;
+    const removed = yield* collectOrphans(bucket, role === 'leader');
+    yield fx.emit({ type: 'log', level: 'info', message: 'orphan gc done', data: { removed, retiredViews: retired.size } });
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'orphan gc failed', data: { error } });
+  } finally {
+    yield fx.timer.set('gc', GC_INTERVAL_MS, { type: 'GcTick' });
+  }
+}
+
+/**
+ * Delete every body nothing retains, `GC_CHUNK` at a time. Each chunk is
+ * re-checked against fresh state (a membership committed meanwhile may name
+ * an id again) and the sweep stops if the bucket moved under it.
+ */
+function* collectOrphans(bucket: string | null, relay: boolean): Saga<number> {
+  const candidates = (yield fx.state.read((s) => {
+    const keep = retained(s);
+    return [...s.versions.keys()].filter((id) => !keep(id));
+  })) as string[];
+  let removed = 0;
+  for (let i = 0; i < candidates.length; i += GC_CHUNK) {
+    const chunk = (yield fx.state.read((s) => {
+      if (!s.primed || s.bucketId !== bucket) return null;
+      const keep = retained(s);
+      return candidates.slice(i, i + GC_CHUNK).filter((id) => s.versions.has(id) && !keep(id));
+    })) as string[] | null;
+    if (chunk === null) break;
+    const settled = (yield fx.all(chunk.map((id) => fx.local.delete(tableOf(id), id)))) as Settled[];
+    const done = chunk.filter((_, j) => settled[j].ok);
+    if (done.length === 0) continue;
+    const records: IngestRecord[] = done.map((id) => ({ table: tableOf(id), op: 'DELETE', id, record: {} }));
+    yield fx.state.update(R.deleteVersions(done));
+    yield fx.ssp.ingest(records);
+    if (relay) yield fx.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records } });
+    removed += done.length;
+  }
+  // A query may have committed a deleted id between its chunk's check and the
+  // delete; with its version gone, the fetch plan pulls it back.
+  if (removed > 0) yield fx.dispatch({ type: 'FetchRows' });
+  return removed;
+}

package/src/query/list-ref-live.integration.test.ts

@@ -0,0 +1,203 @@
+import { Socket } from 'node:net';
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { Surreal, type Uuid } from 'surrealdb';
+import { ANON_LIST_REF_TABLE } from '../modules/ref-tables';
+import { liveEndpoint } from '../live/index';
+import { hashOfEdge } from '../utils/edges';
+import { listRefLive } from './sql';
+
+/**
+ * Every signed-out session shares `_00_list_ref_anon`. Each one's LIVE must
+ * carry only its own edges, including after a reconnect, when its views' edges
+ * still name the socket that registered them.
+ *
+ * Runs against a real SurrealDB, because the filter rests on how SurrealDB
+ * evaluates a LIVE WHERE (`session::id()` in the subscriber's session, a bound
+ * param kept with the LIVE). 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
+ *
+ * Needs SurrealDB 3.1 or later: 3.0.x sends no LIVE notification for a write
+ * that follows a `LET` in the same request, which is how the SSP writes every
+ * edge (and how these tests write them).
+ *
+ * Override the endpoint with SURREAL_IT_ENDPOINT. Skips if unreachable. The
+ * Dart twin is `packages/spooky_core/test/integration/anon_live_isolation_test.dart`.
+ */
+const endpoint = liveEndpoint(process.env.SURREAL_IT_ENDPOINT ?? 'ws://127.0.0.1:18011');
+const NS = 'it';
+
+// What the SSP and the CLI define (`ensure_anon_table`, `_00_query`).
+const SCHEMA = `
+DEFINE TABLE OVERWRITE item SCHEMALESS PERMISSIONS FOR select WHERE true;
+DEFINE TABLE OVERWRITE _00_query SCHEMALESS
+  PERMISSIONS FOR select, create, update, delete
+    WHERE auth_id = 'anon' OR ($auth.id != NONE AND auth_id = <string>$auth.id);
+DEFINE TABLE OVERWRITE _00_list_ref_anon SCHEMALESS
+  PERMISSIONS FOR select WHERE true, FOR create, update WHERE false, FOR delete WHERE false;
+DEFINE FIELD OVERWRITE in ON TABLE _00_list_ref_anon TYPE record;
+DEFINE FIELD OVERWRITE out ON TABLE _00_list_ref_anon TYPE record;
+DEFINE FIELD OVERWRITE clientId ON TABLE _00_list_ref_anon TYPE string;
+DEFINE FIELD OVERWRITE auth_id ON TABLE _00_list_ref_anon TYPE string DEFAULT '';
+DEFINE FIELD OVERWRITE version ON TABLE _00_list_ref_anon TYPE int;
+CREATE item:1 SET name = 'one';
+CREATE item:2 SET name = 'two';
+CREATE item:3 SET name = 'three';
+`;
+
+// The SSP's own statements (`build_edge_batch`): the edge takes the view's
+// clientId at write time.
+const VIEW =
+  "LET $from0 = type::record('_00_query', $q); LET $cid0 = (SELECT VALUE clientId FROM $from0 LIMIT 1)[0];";
+
+interface Heard {
+  action: string;
+  value: Record<string, unknown>;
+}
+
+const waitFor = async (pred: () => boolean, ms = 3_000): Promise<void> => {
+  const deadline = Date.now() + ms;
+  while (!pred() && Date.now() < deadline) await new Promise((r) => setTimeout(r, 25));
+};
+const settle = () => new Promise((r) => setTimeout(r, 300));
+
+describe('anonymous list_ref LIVE (real SurrealDB)', () => {
+  let root: Surreal;
+  let database = '';
+  let reachable = false;
+  const open: Surreal[] = [];
+
+  // A plain TCP probe: the SDK never rejects a connect to a refused port.
+  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));
+    });
+  });
+
+  beforeEach(async () => {
+    if (!reachable) return;
+    database = `anon_live_${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(SCHEMA);
+  });
+
+  afterEach(async () => {
+    if (!reachable) return;
+    for (const db of open.splice(0)) await db.close().catch(() => undefined);
+    await root.query(`REMOVE DATABASE ${database}`).catch(() => undefined);
+    await root.close();
+  });
+
+  /** A signed-out socket and its `session::id()`. */
+  async function guest(): Promise<[Surreal, string]> {
+    const db = new Surreal();
+    open.push(db);
+    await db.connect(endpoint, { reconnect: false });
+    await db.use({ namespace: NS, database });
+    const [sid] = (await db.query('RETURN <string>session::id()')) as [string];
+    return [db, sid];
+  }
+
+  /** Open the client's anonymous LIVE and collect what it hears. */
+  async function listen(db: Surreal, earlier: string[] = []): Promise<Heard[]> {
+    const stmt = listRefLive(ANON_LIST_REF_TABLE, { inlineBodies: true, sessionIds: earlier });
+    const [uuid] = (await db.query(stmt.sql, stmt.vars)) as [Uuid];
+    const live = await db.liveOf(uuid);
+    const got: Heard[] = [];
+    live.subscribe((message) => {
+      if (message.action !== 'KILLED')
+        got.push({ action: message.action, value: message.value as Record<string, unknown> });
+    });
+    return got;
+  }
+
+  const register = (q: string, sid: string) =>
+    root.query("UPSERT type::record('_00_query', $q) SET clientId = $sid, auth_id = 'anon'", {
+      q,
+      sid,
+    });
+  const relate = (q: string, item: string) =>
+    root.query(
+      `${VIEW} RELATE $from0->_00_list_ref_anon->${item} SET version = 1, clientId = $cid0, auth_id = 'anon'`,
+      { q }
+    );
+  const bump = (q: string, item: string, version: number, restamp = true) =>
+    root.query(
+      `${VIEW} UPDATE (SELECT VALUE id FROM ${item}<-_00_list_ref_anon WHERE in = $from0) SET version = ${version}${restamp ? ', clientId = $cid0 ?? clientId' : ''} RETURN NONE`,
+      { q }
+    );
+  const remove = (q: string, item: string) =>
+    root.query(
+      `${VIEW} DELETE (SELECT VALUE id FROM ${item}<-_00_list_ref_anon WHERE in = $from0)`,
+      { q }
+    );
+
+  const heard = (got: Heard[]) =>
+    got
+      .map((m) => `${m.action} ${hashOfEdge(m.value)} ${(m.value.out as { name?: string }).name}`)
+      .join(', ');
+
+  it("two anonymous sessions do not hear each other's edges", async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [a, sidA] = await guest();
+    const [b, sidB] = await guest();
+    await register('qa', sidA);
+    await register('qb', sidB);
+    const gotA = await listen(a);
+    const gotB = await listen(b);
+
+    await relate('qa', 'item:1');
+    await relate('qb', 'item:2');
+    await bump('qa', 'item:1', 2);
+    await waitFor(() => gotA.length >= 2 && gotB.length >= 1);
+    await settle();
+
+    // The body still rides along (`FETCH out`).
+    expect(heard(gotA)).toBe('CREATE qa one, UPDATE qa one');
+    expect(heard(gotB)).toBe('CREATE qb two');
+  });
+
+  it('after a reconnect the new socket still hears the edges its old one registered, and a bystander hears none of it', async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [a, sidA] = await guest();
+    const [b, sidB] = await guest();
+    await register('qa', sidA);
+    await register('qb', sidB);
+    await relate('qa', 'item:1');
+    await relate('qa', 'item:2');
+    const gotB = await listen(b);
+
+    // New socket, new session id. The view stays registered under the old one
+    // until the client re-registers it.
+    await a.close();
+    const [a2, sidA2] = await guest();
+    const gotA2 = await listen(a2, [sidA]);
+
+    // An SSP that does not restamp: the edge keeps naming the old socket.
+    await bump('qa', 'item:1', 2, false);
+    await waitFor(() => gotA2.length >= 1);
+    expect(heard(gotA2)).toBe('UPDATE qa one');
+
+    // Re-registered: the view, and from now on each edge it bumps, names the
+    // new socket. An edge nothing bumped still names the old one when it goes.
+    await register('qa', sidA2);
+    await bump('qa', 'item:1', 3);
+    await remove('qa', 'item:2');
+    await relate('qa', 'item:3');
+    await waitFor(() => gotA2.length >= 4);
+    await settle();
+    expect(heard(gotA2)).toBe('UPDATE qa one, UPDATE qa one, DELETE qa two, CREATE qa three');
+    expect(gotB).toEqual([]);
+  });
+});