@spooky-sync/core 0.0.1-canary.240 → 0.0.1-canary.241

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

@@ -0,0 +1,246 @@
+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 { applyMembership, applySubqueryChildren, markMembershipDirty, readDirtyMembership, readMembership } from './membership.saga';
+import type { StatementResult } from '../kernel/effects';
+
+const env = defaultEnv({ tables: [] } as any);
+const ok = (result: unknown): StatementResult => ({ status: 'OK', result });
+const ready = (rowCount: number) => ({ present: true, rowCount, state: 'ready' as const });
+
+describe('applyMembership', () => {
+  it('ignored: unknown hash, or an unexplained empty', async () => {
+    expect((await runPure(applyMembership('zz', [['t:1', 1]]))).result).toBe('ignored');
+    const s = buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'cold' } })]);
+    const out = await runPure(applyMembership('a', [], { present: true, rowCount: 2, state: 'ready' }), { state: s });
+    expect(out.result).toBe('ignored');
+    expect(out.state.queries.get('a')!.serverState).toBe('ready');
+  });
+  it('view-lost: flips once, drops the registration, re-registers', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live', remote: 'registered' }, remoteArray: [['t:1', 1]] })]);
+    const out = await runPure(applyMembership('a', [], { present: false, rowCount: null, state: null }), { state: s });
+    expect(out.result).toBe('view-lost');
+    expect(out.state.queries.get('a')!.lifecycle).toMatchObject({ phase: 'view-lost', remote: 'unregistered' });
+    expect(out.emitted).toEqual([{ type: 'query:view-lost', hash: 'a' }]);
+    expect(out.dispatched).toEqual([{ type: 'EnsureRegistered' }]);
+    const again = await runPure(applyMembership('a', []), { state: out.state });
+    expect(again.emitted).toEqual([]);
+    expect(again.dispatched).toEqual([{ type: 'EnsureRegistered' }]);
+  });
+  it('applied: commits, writes the view row, flips authority once, releases acked items, asks for bodies', async () => {
+    const s = buildState(
+      [buildEntry({ def: { hash: 'a', viewKey: 'vk' }, lifecycle: { phase: 'cold' } })],
+      R.outboxReplace([buildOutboxItem({ id: 'm', recordId: 't:1', status: 'acked', ackedAt: 1 })])
+    );
+    const out = await runPure(applyMembership('a', [['t:1', 1]], ready(1)), { state: s, now: 42, handlers: { 'local.upsert': () => undefined } });
+    expect(out.result).toBe('applied');
+    expect(out.state.queries.get('a')!.lifecycle.phase).toBe('live');
+    expect(out.state.outbox).toEqual([]);
+    expect(out.emitted).toEqual([{ type: 'query:authority', hash: 'a', known: true }]);
+    expect(out.log.find((e) => e.kind === 'local.upsert')).toEqual({
+      kind: 'local.upsert',
+      table: '_00_view',
+      id: new RecordId('_00_view', 'vk'),
+      data: { ids: [['t:1', 1]], confirmed: true, updatedAt: 42 },
+      mode: 'replace',
+    });
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }]);
+    const second = await runPure(applyMembership('a', [['t:1', 2]], ready(1)), {
+      state: out.state,
+      handlers: {
+        'local.upsert': () => {
+          throw new Error('disk');
+        },
+      },
+    });
+    expect(second.emitted).toEqual([expect.objectContaining({ type: 'log', level: 'debug' })]);
+  });
+  it('verified removal applies an empty set without a row', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live' }, remoteArray: [['t:1', 1]] })]);
+    const out = await runPure(applyMembership('a', [], undefined, true), { state: s, handlers: { 'local.upsert': () => undefined } });
+    expect(out.result).toBe('applied');
+    expect(out.state.queries.get('a')!.remoteArray).toEqual([]);
+  });
+});
+
+describe('applySubqueryChildren', () => {
+  it('no-op when equal or unknown; otherwise sets and asks for bodies', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' }, subqueryRemoteArray: [['c:1', 1]] })]);
+    expect((await runPure(applySubqueryChildren('a', [['c:1', 1]]), { state: s })).dispatched).toEqual([]);
+    expect((await runPure(applySubqueryChildren('zz', []), { state: s })).dispatched).toEqual([]);
+    const out = await runPure(applySubqueryChildren('a', [['c:2', 1]]), { state: s });
+    expect(out.state.queries.get('a')!.subqueryRemoteArray).toEqual([['c:2', 1]]);
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }]);
+  });
+});
+
+describe('readMembership', () => {
+  const qid = (h: string) => new RecordId('_00_query', h);
+  const out1 = (id: string, v = 1) => ({ out: new RecordId('thing', id), version: v });
+  it('nothing to read', async () => {
+    expect((await runPure(readMembership(env, ['nope']), { state: buildState() })).result).toEqual({ changed: false, failed: false });
+  });
+  it('single query: one single-shape request; applies a changed set and clears dirt', async () => {
+    const s = R.markMembershipDirty(['a'])(buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:1', 1]] })]));
+    const out = await runPure(readMembership(env, ['a']), {
+      state: s,
+      handlers: {
+        'remote.query': (e: any) => {
+          expect(e.sql.startsWith('SELECT out, version FROM _00_list_ref WHERE in = $in')).toBe(true);
+          return [ok([out1('1'), out1('2')]), ok({ rowCount: 2, state: 'ready' }), ok([])];
+        },
+        'local.upsert': () => undefined,
+      },
+    });
+    expect(out.result).toEqual({ changed: true, failed: false });
+    expect(out.state.queries.get('a')!.remoteArray).toEqual([['thing:1', 1], ['thing:2', 1]]);
+    expect(out.state.membershipDirty.size).toBe(0);
+    expect(out.dispatched.at(-1)).toEqual({ type: 'SyncOutcome', ok: true, error: undefined });
+  });
+  it('equal set on a live query applies nothing; a cached query with the same set still flips to live', async () => {
+    const live = buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:1', 1]], serverState: 'ready' })]);
+    const handlers = { 'remote.query': () => [ok([out1('1')]), ok({ rowCount: 1, state: 'ready' }), ok([])], 'local.upsert': () => undefined };
+    const a = await runPure(readMembership(env, ['a']), { state: live, handlers });
+    expect(a.result.changed).toBe(false);
+    expect(a.log.filter((e) => e.kind === 'local.upsert')).toHaveLength(0);
+    const cached = buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'cached' }, remoteArray: [['thing:1', 1]], serverState: 'ready' })]);
+    const b = await runPure(readMembership(env, ['a']), { state: cached, handlers });
+    expect(b.state.queries.get('a')!.lifecycle.phase).toBe('live');
+  });
+  it('many queries: one batch request; suspect entries are re-read singly; children applied', async () => {
+    const s = buildState([
+      buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:1', 1]] }),
+      buildEntry({ def: { hash: 'b', id: qid('b') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:2', 1]] }),
+    ]);
+    const calls: string[] = [];
+    const out = await runPure(readMembership(env, ['a', 'b']), {
+      state: s,
+      handlers: {
+        'remote.query': (e: any) => {
+          calls.push(e.sql.split('\n')[0]);
+          if (e.sql.includes('IN $ins')) {
+            return [
+              ok([{ in: qid('a'), out: new RecordId('thing', '1'), version: 1 }, { in: qid('a'), out: new RecordId('child', 'x'), version: 1, parent: qid('a') }]),
+              ok([{ id: qid('a'), rowCount: 1, state: 'ready' }]),
+            ];
+          }
+          return [ok([out1('2'), out1('3')]), ok({ rowCount: 2, state: 'ready' }), ok([])];
+        },
+        'local.upsert': () => undefined,
+      },
+    });
+    expect(calls).toEqual(['SELECT in, out, version, parent FROM _00_list_ref WHERE in IN $ins;', 'SELECT out, version FROM _00_list_ref WHERE in = $in AND parent IS NONE;']);
+    expect(out.state.queries.get('a')!.subqueryRemoteArray).toEqual([['child:x', 1]]);
+    expect(out.state.queries.get('b')!.remoteArray).toEqual([['thing:2', 1], ['thing:3', 1]]);
+    expect(out.result.changed).toBe(true);
+  });
+  it('failures: a failed chunk or re-read reports failed; a non-array primary is skipped', async () => {
+    const s = buildState([
+      buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:1', 1]] }),
+      buildEntry({ def: { hash: 'b', id: qid('b') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:2', 1]] }),
+    ]);
+    const chunkFail = await runPure(readMembership(env, ['a', 'b']), {
+      state: s,
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(chunkFail.result).toEqual({ changed: false, failed: true });
+    expect(chunkFail.dispatched.at(-1)).toMatchObject({ type: 'SyncOutcome', ok: false });
+    let n = 0;
+    const rereadFail = await runPure(readMembership(env, ['a', 'b']), {
+      state: s,
+      handlers: {
+        'remote.query': (e: any) => {
+          n++;
+          if (e.sql.includes('IN $ins')) return [ok([]), ok([])];
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(rereadFail.result.failed).toBe(true);
+    expect(n).toBe(3);
+    const single = buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live' }, remoteArray: [['thing:1', 1]] })]);
+    const notArray = await runPure(readMembership(env, ['a']), { state: single, handlers: { 'remote.query': () => [ok('x'), ok(null), ok(null)] } });
+    expect(notArray.result).toEqual({ changed: false, failed: false });
+    const batchNotArray = await runPure(readMembership(env, ['a', 'b']), { state: s, handlers: { 'remote.query': () => [ok(null), ok(null)] } });
+    expect(batchNotArray.result).toEqual({ changed: false, failed: false });
+    const undefinedResult = await runPure(readMembership(env, ['a']), { state: single, handlers: { 'remote.query': () => undefined } });
+    expect(undefinedResult.result).toEqual({ changed: false, failed: false });
+    const errStmt = await runPure(readMembership(env, ['a']), { state: single, handlers: { 'remote.query': () => [{ status: 'ERR', error: 'x' }, ok(null), ok(null)] } });
+    expect(errStmt.result).toEqual({ changed: false, failed: false });
+  });
+  it('materializing views walk the re-read ladder then stop', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'cold' } })]);
+    const mat = { 'remote.query': () => [ok([]), ok({ rowCount: 2, state: 'materializing' }), ok([])] };
+    const r1 = await runPure(readMembership(env, ['a']), { state: s, handlers: mat });
+    expect(r1.state.membershipReread.get('a')).toBe(1);
+    expect(r1.state.membershipDirty.has('a')).toBe(true);
+    expect(r1.timers.get('membership')).toEqual({ ms: 150, event: { type: 'ReadDirtyMembership' } });
+    const r2 = await runPure(readMembership(env, ['a']), { state: r1.state, handlers: mat });
+    expect(r2.timers.get('membership')!.ms).toBe(400);
+    const r3 = await runPure(readMembership(env, ['a']), { state: r2.state, handlers: mat });
+    expect(r3.timers.get('membership')!.ms).toBe(1000);
+    const r4 = await runPure(readMembership(env, ['a']), { state: r3.state, handlers: mat });
+    expect(r4.timers.size).toBe(0);
+    expect(r4.state.membershipReread.has('a')).toBe(false);
+    const landed = await runPure(readMembership(env, ['a']), {
+      state: r2.state,
+      handlers: { 'remote.query': () => [ok([out1('1')]), ok({ rowCount: 1, state: 'ready' }), ok([])], 'local.upsert': () => undefined },
+    });
+    expect(landed.state.membershipReread.has('a')).toBe(false);
+  });
+  it('skips entries that vanish between the read and the apply', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live' }, remoteArray: [] })]);
+    const out = await runPure(readMembership(env, ['a']), {
+      state: s,
+      handlers: {
+        'remote.query': (_e, ctx) => {
+          ctx.state = R.removeQuery('a')(ctx.state);
+          return [ok([out1('1')]), ok({ rowCount: 1, state: 'ready' }), ok([])];
+        },
+      },
+    });
+    expect(out.result.changed).toBe(false);
+  });
+});
+
+describe('dirty helpers', () => {
+  it('markMembershipDirty coalesces into one timer; readDirtyMembership is a no-op when clean', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(markMembershipDirty(['a']), { state: s });
+    expect(out.state.membershipDirty.has('a')).toBe(true);
+    expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+    const clean = await runPure(readDirtyMembership(env), { state: s });
+    expect(clean.log.filter((e) => e.kind === 'remote.query')).toHaveLength(0);
+    const dirty = await runPure(readDirtyMembership(env), {
+      state: out.state,
+      handlers: { 'remote.query': () => [ok([]), ok(null), ok([])] },
+    });
+    expect(dirty.log.filter((e) => e.kind === 'remote.query')).toHaveLength(1);
+  });
+
+  it('arms the window once per burst, and again for dirt the read left behind', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } }), buildEntry({ def: { hash: 'b' } })]);
+    const first = await runPure(markMembershipDirty(['a']), { state: s });
+    // A second event inside the same window must NOT push the read out: with
+    // `timer.set` replacing the pending timer, re-arming on every LIVE event
+    // starved the read on a busy table.
+    const second = await runPure(markMembershipDirty(['b']), { state: first.state });
+    expect(second.timers.has('membership')).toBe(false);
+    expect([...second.state.membershipDirty]).toEqual(['a', 'b']);
+
+    // A read that cannot answer a hash leaves it dirty, and re-arms for it.
+    const stuck = await runPure(readDirtyMembership(env), {
+      state: second.state,
+      handlers: { 'remote.query': () => { throw new Error('offline'); } },
+    });
+    expect(stuck.state.membershipDirty.size).toBe(2);
+    expect(stuck.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+  });
+});

package/src/query/membership.saga.ts

@@ -0,0 +1,208 @@
+import type { QueryHash, RecordVersionArray, ServerViewMeta } from '../types';
+import type { Saga } from '../kernel/saga';
+import type { Settled, StatementResult } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import { MATERIALIZING_REREAD_LADDER_MS, MEMBERSHIP_COALESCE_MS } from '../kernel/constants';
+import type { ClientState, QueryEntry } from '../state/client-state';
+import { isAuthoritative } from '../state/lifecycle';
+import * as R from '../state/reducers';
+import { encodeRecordId } from '../utils/index';
+import { planListRefPollChunks, recordVersionArraysEqual } from '../sync/policy';
+import type { SagaEnv } from './env';
+import { listRefTable } from './env';
+import * as sql from './sql';
+import {
+  decideMembershipOutcome,
+  snapshotFromSingle,
+  snapshotsFromBatch,
+  suspectHashes,
+  type ListRefSnapshot,
+} from './membership';
+
+type MembershipOutcome = 'applied' | 'ignored' | 'view-lost';
+
+/**
+ * Accept (or refuse) a server id-set for one query. The only writer of
+ * `remoteArray`, the `_00_view` row and the cold -> live transition.
+ */
+export function* applyMembership(
+  hash: QueryHash,
+  remoteArray: RecordVersionArray,
+  meta?: ServerViewMeta,
+  verifiedRemoval?: boolean
+): Saga<MembershipOutcome> {
+  const entry = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+  if (!entry) return 'ignored';
+  if (meta) yield fx.state.update(R.setServerState(hash, meta.present ? meta.state : null));
+  const outcome = decideMembershipOutcome({
+    phase: entry.lifecycle.phase,
+    held: entry.remoteArray.length,
+    remoteArray,
+    meta,
+    verifiedRemoval,
+  });
+  if (outcome === 'ignored') return outcome;
+  if (outcome === 'view-lost') {
+    if (entry.lifecycle.phase !== 'view-lost') {
+      yield fx.state.update(R.applyLifecycle(hash, { type: 'row-missing' }));
+      yield fx.emit({ type: 'query:view-lost', hash });
+    }
+    if (entry.lifecycle.remote !== 'unregistered') {
+      yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-dropped' }));
+    }
+    yield fx.dispatch({ type: 'EnsureRegistered' });
+    return outcome;
+  }
+  const wasAuthoritative = isAuthoritative(entry.lifecycle);
+  yield fx.state.update(R.commitMembership(hash, remoteArray, meta?.present ?? true));
+  if (!wasAuthoritative) yield fx.emit({ type: 'query:authority', hash, known: true });
+  const now = (yield fx.now()) as number;
+  try {
+    yield fx.local.upsert(sql.VIEW_TABLE, sql.viewRecordId(entry.def.viewKey), sql.viewRow(remoteArray, true, now), 'replace');
+  } catch (err) {
+    yield fx.emit({ type: 'log', level: 'debug', message: 'view row write failed', data: { hash, err } });
+  }
+  yield fx.dispatch({ type: 'FetchRows' });
+  return outcome;
+}
+
+/** Replace the subquery child set; bodies follow through the fetch plan. */
+export function* applySubqueryChildren(hash: QueryHash, children: RecordVersionArray): Saga<void> {
+  const entry = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+  if (!entry || recordVersionArraysEqual(entry.subqueryRemoteArray, children)) return;
+  yield fx.state.update(R.setSubqueryRemoteArray(hash, children));
+  yield fx.dispatch({ type: 'FetchRows' });
+}
+
+const ok = (r: Settled): r is { ok: true; value: unknown } => r.ok;
+const stmt = (results: unknown, i: number): unknown => {
+  if (!Array.isArray(results)) return null;
+  const r = (results as StatementResult[])[i];
+  return r && r.status === 'OK' ? r.result : null;
+};
+
+/**
+ * Read the server membership of many queries in as few round trips as the
+ * row budget allows, then apply each changed set. This is the ONLY place a
+ * server id-set enters state: registration, the poll, LIVE dirt and view-lost
+ * recovery all come through here.
+ */
+export function* readMembership(
+  env: SagaEnv,
+  hashes: QueryHash[],
+  opts: { force?: boolean } = {}
+): Saga<{ changed: boolean; failed: boolean }> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  const entries = hashes.map((h) => state.queries.get(h)).filter((e): e is QueryEntry => !!e);
+  if (entries.length === 0) return { changed: false, failed: false };
+  const table = listRefTable(env, state);
+  const now = (yield fx.now()) as number;
+  const chunks = planListRefPollChunks(
+    entries.map((e) => ({ hash: e.def.hash, rows: e.remoteArray.length, lastPolledAt: opts.force ? 0 : (e.lastPolledAt ?? 0) })),
+    { now }
+  );
+  const byHash = new Map(entries.map((e) => [e.def.hash, e]));
+  const single = (e: QueryEntry) =>
+    fx.remote.query(sql.singleSnapshotSelect(table), { in: e.def.id }, env.remoteTimeoutMs);
+  const requests = chunks.map((chunk) =>
+    chunk.length === 1
+      ? single(byHash.get(chunk[0])!)
+      : fx.remote.query(sql.batchSnapshotSelect(table), { ins: chunk.map((h) => byHash.get(h)!.def.id) }, env.remoteTimeoutMs)
+  );
+  const results = (yield fx.all(requests)) as Settled[];
+
+  const snapshots = new Map<QueryHash, ListRefSnapshot>();
+  let failed = false;
+  const rereads: QueryEntry[] = [];
+  chunks.forEach((chunk, i) => {
+    const r = results[i];
+    if (!ok(r)) {
+      failed = true;
+      return;
+    }
+    if (chunk.length === 1) {
+      const snap = snapshotFromSingle(stmt(r.value, 0) as never, stmt(r.value, 1) as never, stmt(r.value, 2) as never);
+      if (snap) snapshots.set(chunk[0], snap);
+      return;
+    }
+    const hashById = new Map(chunk.map((h) => [encodeRecordId(byHash.get(h)!.def.id), h]));
+    const edges = stmt(r.value, 0) as never[] | null;
+    const batch = snapshotsFromBatch(edges, stmt(r.value, 1) as never, hashById);
+    const held = new Map(chunk.map((h) => [h, byHash.get(h)!.remoteArray.length]));
+    const suspect = new Set(suspectHashes(batch, held, Array.isArray(edges) ? edges.length : 0));
+    for (const [h, snap] of batch) {
+      if (suspect.has(h)) rereads.push(byHash.get(h)!);
+      else snapshots.set(h, snap);
+    }
+  });
+  if (rereads.length > 0) {
+    const again = (yield fx.all(rereads.map(single))) as Settled[];
+    again.forEach((r, i) => {
+      if (!ok(r)) {
+        failed = true;
+        return;
+      }
+      const snap = snapshotFromSingle(stmt(r.value, 0) as never, stmt(r.value, 1) as never, stmt(r.value, 2) as never);
+      if (snap) snapshots.set(rereads[i].def.hash, snap);
+    });
+  }
+
+  let changed = false;
+  const stillMaterializing: QueryHash[] = [];
+  for (const [hash, snap] of snapshots) {
+    const current = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+    if (!current) continue;
+    const metaChanged = current.serverState !== (snap.meta.present ? snap.meta.state : null);
+    if (!recordVersionArraysEqual(snap.primary, current.remoteArray) || metaChanged || current.lifecycle.phase === 'cold' || current.lifecycle.phase === 'cached') {
+      const outcome = yield* applyMembership(hash, snap.primary, snap.meta);
+      if (outcome === 'applied') changed = true;
+      if (outcome === 'ignored' && snap.meta.present && snap.meta.state === 'materializing') stillMaterializing.push(hash);
+    }
+    yield* applySubqueryChildren(hash, snap.subquery);
+  }
+  yield fx.state.update(R.compose(R.clearMembershipDirty([...snapshots.keys()]), R.stampPolled(snapshots.keys(), now)));
+
+  // A view whose edges are still in flight: re-read on a short ladder rather
+  // than waiting for a backed-off poll tick.
+  for (const hash of stillMaterializing) {
+    const attempt = (yield fx.state.read((s) => s.membershipReread.get(hash) ?? 0)) as number;
+    if (attempt >= MATERIALIZING_REREAD_LADDER_MS.length) {
+      yield fx.state.update(R.setMembershipReread(hash, null));
+      continue;
+    }
+    yield fx.state.update(R.compose(R.setMembershipReread(hash, attempt + 1), R.markMembershipDirty([hash])));
+    yield fx.timer.set('membership', MATERIALIZING_REREAD_LADDER_MS[attempt], { type: 'ReadDirtyMembership' });
+  }
+  for (const hash of snapshots.keys()) {
+    if (!stillMaterializing.includes(hash)) yield fx.state.update(R.setMembershipReread(hash, null));
+  }
+  yield fx.dispatch({ type: 'SyncOutcome', ok: !failed, error: failed ? 'membership read failed' : undefined });
+  return { changed, failed };
+}
+
+/**
+ * LIVE handler: mark dirty and coalesce into one batched re-read.
+ *
+ * The window is armed ONCE per burst, when the dirty set goes from empty to
+ * non-empty. `timer.set` replaces a pending timer, so re-arming on every event
+ * would push the read out for as long as events keep arriving: on a busy
+ * `_00_list_ref` table (registrations, an import, another tab syncing) the
+ * events never stop for a whole 50 ms and the read simply never ran, leaving
+ * membership frozen until a poll tick happened to cover it.
+ */
+export function* markMembershipDirty(hashes: QueryHash[]): Saga<void> {
+  const armed = (yield fx.state.read((s) => s.membershipDirty.size > 0)) as boolean;
+  yield fx.state.update(R.markMembershipDirty(hashes));
+  if (!armed) yield fx.timer.set('membership', MEMBERSHIP_COALESCE_MS, { type: 'ReadDirtyMembership' });
+}
+
+export function* readDirtyMembership(env: SagaEnv): Saga<void> {
+  const dirty = (yield fx.state.read((s) => [...s.membershipDirty])) as QueryHash[];
+  if (dirty.length === 0) return;
+  yield* readMembership(env, dirty, { force: true });
+  // Dirt that arrived while the read was in flight, or a hash the read could
+  // not answer, holds the set non-empty - and with the window armed only on the
+  // empty -> non-empty edge, nothing else would arm it again.
+  const left = (yield fx.state.read((s) => s.membershipDirty.size)) as number;
+  if (left > 0) yield fx.timer.set('membership', MEMBERSHIP_COALESCE_MS, { type: 'ReadDirtyMembership' });
+}

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([]);
+  });
+});