@spooky-sync/core 0.0.1-canary.31 → 0.0.1-canary.310

package/src/query/membership.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import {
+  decideMembershipOutcome,
+  dedupeRecordVersions,
+  isResolvedBefore,
+  metaFromRow,
+  parseViewRow,
+  snapshotFromSingle,
+  snapshotsFromBatch,
+  suspectHashes,
+} from './membership';
+
+describe('durable view row', () => {
+  it('parses and gates resolved-before', () => {
+    expect(parseViewRow(null)).toBeNull();
+    expect(parseViewRow({ ids: 'nope' })).toBeNull();
+    expect(parseViewRow({ ids: [['t:1', 1]], confirmed: true })).toEqual({ ids: [['t:1', 1]], confirmed: true });
+    expect(parseViewRow({ ids: [] })).toEqual({ ids: [], confirmed: false });
+    expect(isResolvedBefore(null)).toBe(false);
+    expect(isResolvedBefore({ ids: [], confirmed: false })).toBe(false);
+    expect(isResolvedBefore({ ids: [], confirmed: true })).toBe(true);
+    expect(isResolvedBefore({ ids: [['t:1', 1]], confirmed: false })).toBe(true);
+  });
+});
+
+describe('metaFromRow / dedupe', () => {
+  it('folds the row-count select', () => {
+    expect(metaFromRow(null)).toEqual({ present: false, rowCount: null, state: null });
+    expect(metaFromRow({ rowCount: 3, state: 'ready' })).toEqual({ present: true, rowCount: 3, state: 'ready' });
+    expect(metaFromRow({ rowCount: null, state: 'weird' })).toEqual({ present: true, rowCount: null, state: null });
+    expect(metaFromRow({ state: 'materializing' })).toEqual({ present: true, rowCount: null, state: 'materializing' });
+  });
+  it('keeps the highest version per id', () => {
+    const single: [string, number][] = [['t:1', 1]];
+    expect(dedupeRecordVersions(single)).toBe(single);
+    const clean: [string, number][] = [['t:1', 1], ['t:2', 1]];
+    expect(dedupeRecordVersions(clean)).toBe(clean);
+    expect(dedupeRecordVersions([['t:1', 1], ['t:1', 3], ['t:1', 2]])).toEqual([['t:1', 3]]);
+  });
+});
+
+describe('decideMembershipOutcome', () => {
+  const ready0 = { present: true, rowCount: 0, state: 'ready' as const };
+  it('non-empty or verified removal is always applied', () => {
+    expect(decideMembershipOutcome({ phase: 'cold', held: 0, remoteArray: [['t:1', 1]] })).toBe('applied');
+    expect(decideMembershipOutcome({ phase: 'live', held: 2, remoteArray: [], verifiedRemoval: true })).toBe('applied');
+  });
+  it('empty with no readable row: view-lost when holding, ignored when cold and empty', () => {
+    expect(decideMembershipOutcome({ phase: 'cold', held: 0, remoteArray: [] })).toBe('ignored');
+    expect(decideMembershipOutcome({ phase: 'cold', held: 0, remoteArray: [], meta: { present: false, rowCount: null, state: null } })).toBe('ignored');
+    expect(decideMembershipOutcome({ phase: 'cold', held: 2, remoteArray: [] })).toBe('view-lost');
+    expect(decideMembershipOutcome({ phase: 'cached', held: 0, remoteArray: [] })).toBe('view-lost');
+    expect(decideMembershipOutcome({ phase: 'live', held: 1, remoteArray: [], meta: { present: false, rowCount: null, state: null } })).toBe('view-lost');
+  });
+  it('empty with a present row: applied only when ready and zero rows', () => {
+    expect(decideMembershipOutcome({ phase: 'cold', held: 0, remoteArray: [], meta: ready0 })).toBe('applied');
+    expect(decideMembershipOutcome({ phase: 'cold', held: 0, remoteArray: [], meta: { present: true, rowCount: 0, state: null } })).toBe('applied');
+    expect(decideMembershipOutcome({ phase: 'cold', held: 0, remoteArray: [], meta: { present: true, rowCount: 0, state: 'materializing' } })).toBe('ignored');
+    expect(decideMembershipOutcome({ phase: 'live', held: 3, remoteArray: [], meta: { present: true, rowCount: 3, state: 'ready' } })).toBe('ignored');
+    expect(decideMembershipOutcome({ phase: 'live', held: 3, remoteArray: [], meta: { present: true, rowCount: null, state: 'ready' } })).toBe('ignored');
+  });
+});
+
+describe('snapshots', () => {
+  const q1 = new RecordId('_00_query', 'a');
+  const q2 = new RecordId('_00_query', 'b');
+  const out = (id: string) => new RecordId('thing', id);
+  it('single: edges, meta, children; null when the primary select is not an array', () => {
+    expect(snapshotFromSingle(null, null, null)).toBeNull();
+    const snap = snapshotFromSingle(
+      [{ out: out('1'), version: 1 }, { out: out('1'), version: 2 }],
+      { rowCount: 1, state: 'ready' },
+      [{ out: out('c'), version: 1 }]
+    );
+    expect(snap).toEqual({
+      primary: [['thing:1', 2]],
+      subquery: [['thing:c', 1]],
+      meta: { present: true, rowCount: 1, state: 'ready' },
+    });
+    expect(snapshotFromSingle([], null, null)!.subquery).toEqual([]);
+  });
+  it('batch: splits by hash and parent, fills meta, marks missing rows absent', () => {
+    const hashById = new Map([['_00_query:a', 'ha'], ['_00_query:b', 'hb']]);
+    expect(snapshotsFromBatch(null, null, hashById).size).toBe(0);
+    const snaps = snapshotsFromBatch(
+      [
+        { in: q1, out: out('1'), version: 1 },
+        { in: q1, out: out('1'), version: 1 },
+        { in: q1, out: out('c'), version: 1, parent: q1 },
+        { in: new RecordId('_00_query', 'zz'), out: out('9'), version: 1 },
+      ],
+      [{ id: q1, rowCount: 1, state: 'ready' }, null, { rowCount: 5 }, { id: new RecordId('_00_query', 'zz') }],
+      hashById
+    );
+    expect(snaps.get('ha')).toEqual({
+      primary: [['thing:1', 1]],
+      subquery: [['thing:c', 1]],
+      meta: { present: true, rowCount: 1, state: 'ready' },
+    });
+    expect(snaps.get('hb')).toEqual({ primary: [], subquery: [], meta: { present: false, rowCount: null, state: null } });
+    expect(snapshotsFromBatch([], null, hashById).get('ha')!.meta.present).toBe(false);
+  });
+  it('suspectHashes flags held queries with a missing row or a silently empty batch', () => {
+    const snaps = new Map([
+      ['missing', { primary: [], subquery: [], meta: { present: false, rowCount: null, state: null } }],
+      ['empty', { primary: [], subquery: [], meta: { present: true, rowCount: 4, state: 'ready' as const } }],
+      ['fine', { primary: [], subquery: [], meta: { present: true, rowCount: 0, state: 'ready' as const } }],
+      ['unheld', { primary: [], subquery: [], meta: { present: false, rowCount: null, state: null } }],
+    ]);
+    const held = new Map([['missing', 2], ['empty', 4], ['fine', 1], ['unheld', 0]]);
+    expect(suspectHashes(snaps, held, 0)).toEqual(['missing', 'empty']);
+    expect(suspectHashes(snaps, held, 1)).toEqual(['missing']);
+    const nullCount = new Map([['q', { primary: [], subquery: [], meta: { present: true, rowCount: null, state: 'ready' as const } }]]);
+    expect(suspectHashes(nullCount, new Map([['q', 3]]), 0)).toEqual([]);
+    expect(suspectHashes(nullCount, new Map(), 0)).toEqual([]);
+  });
+});

package/src/query/membership.ts

@@ -0,0 +1,201 @@
+import type { RecordId } from 'surrealdb';
+import type { MembershipOutcome, RecordVersionArray, ServerViewMeta } from '../types';
+import type { QueryPhase } from '../state/lifecycle';
+import { encodeRecordId } from '../utils/index';
+
+/** The durable `_00_view` row: the last server-confirmed membership. */
+export interface DurableView {
+  ids: RecordVersionArray;
+  confirmed: boolean;
+}
+
+export function parseViewRow(row: unknown): DurableView | null {
+  if (!row || typeof row !== 'object') return null;
+  const ids = (row as { ids?: unknown }).ids;
+  if (!Array.isArray(ids)) return null;
+  return { ids: ids as RecordVersionArray, confirmed: (row as { confirmed?: unknown }).confirmed === true };
+}
+
+/** One `_00_view` row as the view index and the GC see it. */
+export interface ViewIndexRow {
+  key: string;
+  /** Members and subquery children: what the row vouches for. */
+  ids: string[];
+  /** Last time a session resolved the query (0 when the row predates the field). */
+  updatedAt: number;
+}
+
+const pairIds = (pairs: unknown): string[] =>
+  Array.isArray(pairs) ? pairs.filter((p): p is [string, number] => Array.isArray(p) && typeof p[0] === 'string').map((p) => p[0]) : [];
+
+/** `SELECT * FROM _00_view` rows, keyed by view key; junk rows are skipped. */
+export function parseViewIndex(rows: unknown): ViewIndexRow[] {
+  if (!Array.isArray(rows)) return [];
+  const out: ViewIndexRow[] = [];
+  for (const row of rows as Array<Record<string, unknown> | null>) {
+    if (!row || typeof row !== 'object' || !Array.isArray(row.ids)) continue;
+    const id = row.id;
+    const key = typeof id === 'string' ? id.slice(id.indexOf(':') + 1) : String((id as { id?: unknown } | undefined)?.id ?? '');
+    if (!key) continue;
+    out.push({
+      key,
+      ids: [...new Set([...pairIds(row.ids), ...pairIds(row.children)])],
+      updatedAt: typeof row.updatedAt === 'number' ? row.updatedAt : 0,
+    });
+  }
+  return out;
+}
+
+/**
+ * "Resolved before": the server answered this query on this device at some
+ * point. An unconfirmed empty row cannot be told apart from one written before
+ * the marker existed, so it does not count.
+ */
+export const isResolvedBefore = (view: DurableView | null): boolean =>
+  view !== null && (view.ids.length > 0 || view.confirmed);
+
+/** The `{ rowCount, state }` object the row-count selects return per row. */
+export interface QueryMetaRow {
+  id?: RecordId<string>;
+  rowCount?: number | null;
+  state?: string | null;
+}
+
+export function metaFromRow(row: QueryMetaRow | null | undefined): ServerViewMeta {
+  if (!row || typeof row !== 'object') return { present: false, rowCount: null, state: null };
+  const state = row.state === 'materializing' || row.state === 'ready' ? row.state : null;
+  return { present: true, rowCount: typeof row.rowCount === 'number' ? row.rowCount : null, state };
+}
+
+/** Collapse duplicate `(id, version)` pairs to one per id, keeping the highest version. */
+export function dedupeRecordVersions(pairs: RecordVersionArray): RecordVersionArray {
+  if (pairs.length < 2) return pairs;
+  const best = new Map<string, number>();
+  for (const [id, version] of pairs) {
+    const prev = best.get(id);
+    if (prev === undefined || version > prev) best.set(id, version);
+  }
+  if (best.size === pairs.length) return pairs;
+  return Array.from(best.entries());
+}
+
+export interface MembershipDecisionInput {
+  phase: QueryPhase;
+  /** Number of ids currently held as membership. */
+  held: number;
+  remoteArray: RecordVersionArray;
+  meta?: ServerViewMeta;
+  verifiedRemoval?: boolean;
+}
+
+/**
+ * Whether a server id-set may be applied. A NON-EMPTY set is always the
+ * server's answer. An EMPTY set is believed only when the server stands
+ * behind it: the `_00_query` row is present, `ready` (or pre-`state`), and
+ * reports zero rows. A missing row while we hold membership is a lost view.
+ */
+export function decideMembershipOutcome(input: MembershipDecisionInput): MembershipOutcome {
+  const { phase, held, remoteArray, meta, verifiedRemoval } = input;
+  if (remoteArray.length > 0 || verifiedRemoval) return 'applied';
+  if (!meta || !meta.present) {
+    return held > 0 || phase !== 'cold' ? 'view-lost' : 'ignored';
+  }
+  const knownEmpty = meta.rowCount === 0 && meta.state !== 'materializing';
+  return knownEmpty ? 'applied' : 'ignored';
+}
+
+// ---- list_ref snapshots ------------------------------------------------------
+
+/**
+ * A statement that did not answer (an ERR, or no result at all). Kept apart
+ * from a `null` result, which is the server saying "no such row": reading a
+ * failed statement as a missing row turned every timeout under load into a
+ * lost view and re-registered it, over and over (whitepawn, 2026-09-16).
+ */
+export const FAILED: unique symbol = Symbol('statement failed');
+export type Answer<T> = T | null | typeof FAILED;
+
+export interface ListRefEdgeRow {
+  in: RecordId<string>;
+  out: RecordId<string>;
+  version: number;
+  parent?: unknown;
+}
+
+export interface ListRefSnapshot {
+  primary: RecordVersionArray;
+  subquery: RecordVersionArray;
+  meta: ServerViewMeta;
+}
+
+const toPairs = (rows: Array<{ out: RecordId<string>; version: number }> | null | undefined): RecordVersionArray =>
+  dedupeRecordVersions(Array.isArray(rows) ? rows.map((r) => [encodeRecordId(r.out), r.version]) : []);
+
+/**
+ * Fold the single-query statement batch (edges, meta, children) into a
+ * snapshot. `null` when any of the three did not answer: half an answer is
+ * not one, and a missing meta would read as a lost view.
+ */
+export function snapshotFromSingle(
+  items: Answer<Array<{ out: RecordId<string>; version: number }>>,
+  metaRow: Answer<QueryMetaRow>,
+  children: Answer<Array<{ out: RecordId<string>; version: number }>>
+): ListRefSnapshot | null {
+  if (!Array.isArray(items) || metaRow === FAILED || children === FAILED) return null;
+  return { primary: toPairs(items), subquery: toPairs(children), meta: metaFromRow(metaRow) };
+}
+
+/**
+ * Fold the many-query statement batch into one snapshot per hash. Every hash
+ * in `hashById` gets a snapshot; a query whose row did not come back reads
+ * `present: false`. Empty when either statement did not answer.
+ */
+export function snapshotsFromBatch(
+  edges: Answer<ListRefEdgeRow[]>,
+  counts: Answer<Array<QueryMetaRow | null>>,
+  hashById: ReadonlyMap<string, string>
+): Map<string, ListRefSnapshot> {
+  const out = new Map<string, ListRefSnapshot>();
+  if (!Array.isArray(edges) || counts === FAILED) return out;
+  for (const hash of hashById.values()) {
+    out.set(hash, { primary: [], subquery: [], meta: { present: false, rowCount: null, state: null } });
+  }
+  for (const row of edges) {
+    const hash = hashById.get(encodeRecordId(row.in));
+    if (!hash) continue;
+    const snapshot = out.get(hash)!;
+    const pair: [string, number] = [encodeRecordId(row.out), row.version];
+    if (row.parent == null) snapshot.primary.push(pair);
+    else snapshot.subquery.push(pair);
+  }
+  for (const snapshot of out.values()) {
+    snapshot.primary = dedupeRecordVersions(snapshot.primary);
+    snapshot.subquery = dedupeRecordVersions(snapshot.subquery);
+  }
+  for (const count of Array.isArray(counts) ? counts : []) {
+    if (!count || !count.id) continue;
+    const hash = hashById.get(encodeRecordId(count.id));
+    if (!hash) continue;
+    out.get(hash)!.meta = metaFromRow(count);
+  }
+  return out;
+}
+
+/**
+ * A batch that must not be believed at face value: a query we hold rows for
+ * whose `_00_query` row did not come back, or no edge at all while the server
+ * still reports rows for a held query. Such hashes are re-read one at a time.
+ */
+export function suspectHashes(
+  snapshots: ReadonlyMap<string, ListRefSnapshot>,
+  heldCounts: ReadonlyMap<string, number>,
+  edgeCount: number
+): string[] {
+  const out: string[] = [];
+  for (const [hash, snapshot] of snapshots) {
+    const held = heldCounts.get(hash) ?? 0;
+    if (held === 0) continue;
+    if (!snapshot.meta.present || (edgeCount === 0 && (snapshot.meta.rowCount ?? 0) > 0)) out.push(hash);
+  }
+  return out;
+}

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

@@ -0,0 +1,293 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure, sha256Hex } from '../testing/run-pure';
+import { buildEntry, buildState } from '../testing/build';
+import { defaultEnv } from './env';
+import { queryHashInput } from './hash';
+import { ensureRegistered, isNotAllowlisted, registerLocal, registerRemote } from './register.saga';
+import * as R from '../state/reducers';
+import { emptyState } from '../state/client-state';
+import type { StatementResult } from '../kernel/effects';
+
+const env = defaultEnv({ tables: [{ name: 'thing', columns: {} }] } as any);
+const input = { tableName: 'thing', surql: 'SELECT * FROM thing', params: {}, ttl: '10m' as const };
+const sspOk = () => ({ localArray: [['thing:9', 1]], timings: { parseMs: 1, planMs: 1, snapshotMs: 1, wallMs: 1 } });
+const okStmt = (result: unknown): StatementResult => ({ status: 'OK', result });
+
+describe('registerLocal', () => {
+  it('cold: no view row -> cold entry, SSP view, EnsureRegistered', async () => {
+    const state = { ...emptyState({ tabId: 't' }), sessionId: 'sess' };
+    const out = await runPure(registerLocal(env, input), {
+      state,
+      handlers: { 'local.getById': () => null, 'ssp.register': sspOk },
+    });
+    const hash = await sha256Hex(queryHashInput(input, 'sess'));
+    expect(out.result).toBe(hash);
+    const entry = out.state.queries.get(hash)!;
+    expect(entry.lifecycle.phase).toBe('cold');
+    expect(entry.remoteArray).toEqual([]);
+    expect(entry.localArray).toEqual([['thing:9', 1]]);
+    expect(entry.def.ttlMs).toBe(600_000);
+    expect(entry.telemetry.registrationTimings.wallMs).toBe(1);
+    expect(out.state.dirty.has(hash)).toBe(true);
+    expect(out.state.registering.size).toBe(0);
+    expect(out.dispatched).toEqual([{ type: 'EnsureRegistered' }]);
+    const reg = out.log.find((e) => e.kind === 'ssp.register');
+    expect(reg).toMatchObject({ plan: { queryHash: hash, tableName: 'thing', ttl: '10m' } });
+  });
+
+  it('cached: a durable view row seeds membership; unconfirmed empty stays cold; a failing read is cold', async () => {
+    const cached = await runPure(registerLocal(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [['thing:1', 2]], confirmed: false }), 'ssp.register': sspOk },
+    });
+    const e1 = cached.state.queries.get(cached.result)!;
+    expect(e1.lifecycle.phase).toBe('cached');
+    expect(e1.remoteArray).toEqual([['thing:1', 2]]);
+    const confirmedEmpty = await runPure(registerLocal(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [], confirmed: true }), 'ssp.register': sspOk },
+    });
+    expect(confirmedEmpty.state.queries.get(confirmedEmpty.result)!.lifecycle.phase).toBe('cached');
+    const unconfirmed = await runPure(registerLocal(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [], confirmed: false }), 'ssp.register': sspOk },
+    });
+    expect(unconfirmed.state.queries.get(unconfirmed.result)!.lifecycle.phase).toBe('cold');
+    const failing = await runPure(registerLocal(env, input), {
+      handlers: {
+        'local.getById': () => {
+          throw new Error('no table');
+        },
+        'ssp.register': sspOk,
+      },
+    });
+    expect(failing.state.queries.get(failing.result)!.lifecycle.phase).toBe('cold');
+  });
+
+  it('dedupes: active returns immediately, pending waits for the other registration', async () => {
+    const hash = await sha256Hex(queryHashInput(input, null));
+    const active = buildState([buildEntry({ def: { hash } })]);
+    const a = await runPure(registerLocal(env, input), { state: active });
+    expect(a.result).toBe(hash);
+    expect(a.log.filter((e) => e.kind === 'ssp.register')).toHaveLength(0);
+    const pending = R.beginRegistering(hash)(emptyState({ tabId: 't' }));
+    const p = await runPure(registerLocal(env, input), {
+      state: pending,
+      handlers: { 'state.wait': (_e, ctx) => void (ctx.state = R.endRegistering(hash)(ctx.state)) },
+    });
+    expect(p.result).toBe(hash);
+    expect(p.log.some((e) => e.kind === 'state.wait')).toBe(true);
+  });
+
+  it('a failing SSP registration clears the in-flight marker and rethrows', async () => {
+    await expect(
+      runPure(registerLocal(env, input), {
+        handlers: {
+          'local.getById': () => null,
+          'ssp.register': () => {
+            throw new Error('wasm down');
+          },
+        },
+      })
+    ).rejects.toThrow('wasm down');
+  });
+});
+
+describe('ensureRegistered', () => {
+  it('dispatches RegisterRemote for every unregistered query only', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } }), buildEntry({ def: { hash: 'b' }, lifecycle: { remote: 'registered' } })]);
+    const out = await runPure(ensureRegistered(env), { state: s });
+    expect(out.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+    const none = await runPure(ensureRegistered(env), { state: buildState() });
+    expect(none.dispatched).toEqual([]);
+  });
+  it('with requireAuth: probes $auth.id, retries on a timer, gives up after the budget, skips when anonymous', async () => {
+    const s = { ...buildState([buildEntry({ def: { hash: 'a' } })]), userId: 'user:1' };
+    const authed = await runPure(ensureRegistered(env, { requireAuth: true }), {
+      state: s,
+      handlers: { 'remote.query': () => [okStmt('user:1')] },
+    });
+    expect(authed.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+    const notYet = await runPure(ensureRegistered(env, { requireAuth: true, attempt: 2 }), {
+      state: s,
+      handlers: { 'remote.query': () => [okStmt(null)] },
+    });
+    expect(notYet.dispatched).toEqual([]);
+    expect(notYet.timers.get('ensure-registered')).toEqual({ ms: 500, event: { type: 'EnsureRegistered', requireAuth: true, attempt: 3 } });
+    const thrown = await runPure(ensureRegistered(env, { requireAuth: true }), {
+      state: s,
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(thrown.timers.has('ensure-registered')).toBe(true);
+    const exhausted = await runPure(ensureRegistered(env, { requireAuth: true, attempt: 9 }), {
+      state: s,
+      handlers: { 'remote.query': () => [okStmt(null)] },
+    });
+    expect(exhausted.timers.size).toBe(0);
+    expect(exhausted.emitted).toEqual([expect.objectContaining({ type: 'log', level: 'warn' })]);
+    const anon = await runPure(ensureRegistered(env, { requireAuth: true }), { state: { ...s, userId: null } });
+    expect(anon.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+  });
+});
+
+describe('registerRemote', () => {
+  const entry = buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'cold' } });
+  const happy = () => [
+    okStmt(null),
+    okStmt([{ out: new RecordId('thing', '1'), version: 1 }]),
+    okStmt({ rowCount: 1, state: 'ready' }),
+    okStmt([{ out: new RecordId('child', 'c'), version: 1 }]),
+  ];
+  it('registers, applies membership + children, flips registered, fetch-begin/end balanced', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': happy, 'local.upsert': () => undefined },
+    });
+    const e = out.state.queries.get('a')!;
+    expect(e.lifecycle).toMatchObject({ phase: 'live', remote: 'registered', fetchDepth: 0 });
+    expect(e.remoteArray).toEqual([['thing:1', 1]]);
+    expect(e.subqueryRemoteArray).toEqual([['child:c', 1]]);
+    expect(e.serverState).toBe('ready');
+    const req = out.log.find((x) => x.kind === 'remote.query') as any;
+    expect(req.sql.startsWith('fn::query::register($config);')).toBe(true);
+    expect(req.vars.config).toMatchObject({ surql: entry.def.surql, ttl: '10m' });
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }, { type: 'FetchRows' }, { type: 'SyncOutcome', ok: true }]);
+    expect(out.emitted).toContainEqual({ type: 'query:authority', hash: 'a', known: true });
+  });
+  it('guards: missing entry, already registered / failed, registering without retry', async () => {
+    const none = await runPure(registerRemote(env, 'zzz'), { state: buildState([]) });
+    expect(none.log.filter((x) => x.kind === 'remote.query')).toHaveLength(0);
+    for (const remote of ['registered', 'failed', 'registering'] as const) {
+      const out = await runPure(registerRemote(env, 'a'), { state: buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote } })]) });
+      expect(out.log.filter((x) => x.kind === 'remote.query')).toHaveLength(0);
+    }
+    const retry = await runPure(registerRemote(env, 'a', true), {
+      state: buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'registering' } })]),
+      handlers: { 'remote.query': happy, 'local.upsert': () => undefined },
+    });
+    expect(retry.state.queries.get('a')!.lifecycle.remote).toBe('registered');
+  });
+  it('materializing answer schedules the re-read ladder', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': () => [okStmt(null), okStmt([]), okStmt({ rowCount: 3, state: 'materializing' }), okStmt([])] },
+    });
+    expect(out.state.membershipDirty.has('a')).toBe(true);
+    expect(out.state.membershipReread.get('a')).toBe(1);
+    expect(out.timers.get('membership')).toEqual({ ms: 150, event: { type: 'ReadDirtyMembership' } });
+    expect(out.state.queries.get('a')!.lifecycle).toMatchObject({ phase: 'cold', remote: 'registered' });
+  });
+  it('errors: transport failure backs off, statement errors count as failures, budget exhausts to failed', async () => {
+    const boom = () => {
+      throw new Error('socket closed');
+    };
+    const first = await runPure(registerRemote(env, 'a'), { state: buildState([entry]), handlers: { 'remote.query': boom } });
+    expect(first.state.queries.get('a')!.lifecycle).toMatchObject({ remote: 'registering', fetchDepth: 0 });
+    expect(first.state.queries.get('a')!.registerAttempts).toBe(1);
+    expect(first.timers.get('register:a')).toEqual({ ms: 1000, event: { type: 'RegisterRemote', hash: 'a', retry: true } });
+    expect(first.dispatched).toContainEqual({ type: 'SyncOutcome', ok: false, error: new Error('socket closed') });
+    const errStmt = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': () => [{ status: 'ERR', error: 'denied' }] },
+    });
+    expect(errStmt.state.queries.get('a')!.registerAttempts).toBe(1);
+    // The register statement answered but the read-back did not: the query
+    // IS registered, and its membership is read again rather than guessed.
+    for (const readBack of [
+      [okStmt(null), { status: 'ERR', error: 'no table' }, okStmt(null), okStmt(null)],
+      [okStmt(null), okStmt('nope'), okStmt(null), okStmt(null)],
+    ] as StatementResult[][]) {
+      const out = await runPure(registerRemote(env, 'a'), { state: buildState([entry]), handlers: { 'remote.query': () => readBack } });
+      const e = out.state.queries.get('a')!;
+      expect(e.registerAttempts).toBe(0);
+      expect(e.lifecycle).toMatchObject({ remote: 'registered', fetchDepth: 0 });
+      expect(out.state.membershipDirty.has('a')).toBe(true);
+      expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+      expect(out.dispatched).toContainEqual({ type: 'SyncOutcome', ok: false, error: 'registration read-back failed' });
+    }
+    const empty = await runPure(registerRemote(env, 'a'), { state: buildState([entry]), handlers: { 'remote.query': () => [] } });
+    expect(empty.state.queries.get('a')!.registerAttempts).toBe(1);
+    const last = await runPure(registerRemote(env, 'a'), {
+      state: buildState([buildEntry({ def: { hash: 'a' }, registerAttempts: 2 })]),
+      handlers: { 'remote.query': boom },
+    });
+    expect(last.state.queries.get('a')!.lifecycle.remote).toBe('failed');
+    expect(last.timers.size).toBe(0);
+  });
+  it('not allowlisted: 403/Forbidden/not_allowlisted fails after ONE attempt with an error log, no retry timer', async () => {
+    for (const text of ['HTTP 403 Forbidden', 'There was an error processing a remote HTTP request: {"error":"not_allowlisted"}', 'status 403']) {
+      const out = await runPure(registerRemote(env, 'a'), {
+        state: buildState([entry]),
+        handlers: { 'remote.query': () => [{ status: 'ERR', error: text }] },
+      });
+      const e = out.state.queries.get('a')!;
+      expect(e.lifecycle).toMatchObject({ remote: 'failed', phase: 'cold', fetchDepth: 0 });
+      expect(e.registerAttempts).toBe(0);
+      expect(out.timers.size).toBe(0);
+      expect(out.emitted).toContainEqual(
+        expect.objectContaining({
+          type: 'log',
+          level: 'error',
+          message: 'query refused: not allowlisted',
+          data: expect.objectContaining({ hash: 'a', table: entry.def.tableName, surql: entry.def.surql, params: [] }),
+        })
+      );
+      expect(out.dispatched).toContainEqual(expect.objectContaining({ type: 'SyncOutcome', ok: false }));
+    }
+    const thrown = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': () => {
+          throw new Error('Forbidden');
+        },
+      },
+    });
+    expect(thrown.state.queries.get('a')!.lifecycle.remote).toBe('failed');
+    expect(thrown.timers.size).toBe(0);
+    expect(isNotAllowlisted(new Error('socket closed'))).toBe(false);
+    expect(isNotAllowlisted('HTTP 4030')).toBe(false);
+  });
+
+  it('an ERR meta or children statement applies nothing and re-reads, instead of reading as a lost row', async () => {
+    const lostBefore = buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'view-lost' }, remoteArray: [['thing:1', 1]], viewLostCount: 1 });
+    for (const [meta, kids] of [
+      [{ status: 'ERR', error: 'meta' }, okStmt([])],
+      [okStmt({ rowCount: 1, state: 'ready' }), { status: 'ERR', error: 'kids' }],
+    ] as StatementResult[][]) {
+      const out = await runPure(registerRemote(env, 'a'), {
+        state: buildState([lostBefore]),
+        handlers: { 'remote.query': () => [okStmt(null), okStmt([{ out: new RecordId('thing', '1'), version: 1 }]), meta, kids] },
+      });
+      const e = out.state.queries.get('a')!;
+      expect(e.lifecycle).toMatchObject({ phase: 'view-lost', remote: 'registered' });
+      expect(e.viewLostCount).toBe(1);
+      expect(out.dispatched.filter((d) => d.type === 'EnsureRegistered')).toEqual([]);
+      expect(out.state.membershipDirty.has('a')).toBe(true);
+    }
+  });
+  it('stops when the entry disappears mid-flight', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': (_e, ctx) => {
+          ctx.state = R.removeQuery('a')(ctx.state);
+          return happy();
+        },
+      },
+    });
+    expect(out.state.queries.has('a')).toBe(false);
+    expect(out.dispatched).toEqual([]);
+    const gone = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': (_e, ctx) => {
+          ctx.state = R.removeQuery('a')(ctx.state);
+          throw new Error('x');
+        },
+      },
+    });
+    expect(gone.dispatched).toEqual([]);
+  });
+});