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

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

@@ -0,0 +1,350 @@
+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, recoverLostView } 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' }]);
+    expect(out.state.queries.get('a')!).toMatchObject({ viewLostCount: 1, viewLostRetryAt: null });
+  });
+  it('view-lost again before the row is seen: paced, and reads while it waits do nothing', async () => {
+    const lost = buildState([
+      buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'view-lost', remote: 'registered' }, remoteArray: [['t:1', 1]], viewLostCount: 1 }),
+    ]);
+    const again = await runPure(applyMembership('a', []), { state: lost, now: 1_000 });
+    expect(again.result).toBe('view-lost');
+    expect(again.emitted.filter((e) => e.type === 'query:view-lost')).toEqual([]);
+    expect(again.dispatched).toEqual([]);
+    expect(again.state.queries.get('a')!).toMatchObject({ viewLostCount: 2, viewLostRetryAt: 2_000 });
+    expect(again.state.queries.get('a')!.lifecycle.remote).toBe('registered');
+    expect(again.timers.get('view-lost:a')).toEqual({ ms: 1_000, event: { type: 'RecoverLostView', hash: 'a' } });
+
+    const waiting = await runPure(applyMembership('a', []), { state: again.state, now: 1_500 });
+    expect(waiting.dispatched).toEqual([]);
+    expect(waiting.timers.size).toBe(0);
+    expect(waiting.state.queries.get('a')!).toMatchObject({ viewLostCount: 2, viewLostRetryAt: 2_000 });
+
+    // The next retry waits longer.
+    const third = buildState([
+      buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'view-lost', remote: 'registered' }, remoteArray: [['t:1', 1]], viewLostCount: 3 }),
+    ]);
+    expect((await runPure(applyMembership('a', []), { state: third })).timers.get('view-lost:a')!.ms).toBe(4_000);
+  });
+  it('recoverLostView re-registers only while still lost and still scheduled', async () => {
+    const scheduled = (phase: 'view-lost' | 'live', retryAt: number | null) =>
+      buildState([
+        buildEntry({ def: { hash: 'a' }, lifecycle: { phase, remote: 'registered' }, remoteArray: [['t:1', 1]], viewLostCount: 2, viewLostRetryAt: retryAt }),
+      ]);
+    const due = await runPure(recoverLostView('a'), { state: scheduled('view-lost', 2_000) });
+    expect(due.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+    expect(due.state.queries.get('a')!).toMatchObject({ viewLostRetryAt: null, viewLostCount: 2 });
+    expect(due.state.queries.get('a')!.lifecycle.remote).toBe('unregistered');
+    expect((await runPure(recoverLostView('a'), { state: scheduled('view-lost', null) })).dispatched).toEqual([]);
+    expect((await runPure(recoverLostView('a'), { state: scheduled('live', 2_000) })).dispatched).toEqual([]);
+    expect((await runPure(recoverLostView('zz'), { state: scheduled('view-lost', 2_000) })).dispatched).toEqual([]);
+  });
+  it('seeing the row again resets the pacing', async () => {
+    const s = buildState([
+      buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'view-lost', remote: 'registered' }, remoteArray: [['t:1', 1]], viewLostCount: 3, viewLostRetryAt: 9_000 }),
+    ]);
+    const out = await runPure(applyMembership('a', [], { present: true, rowCount: 1, state: 'materializing' }), { state: s });
+    expect(out.result).toBe('ignored');
+    expect(out.state.queries.get('a')!).toMatchObject({ viewLostCount: 0, viewLostRetryAt: null });
+  });
+  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' }, subqueryRemoteArray: [['c:1', 1]] })],
+      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]], children: [['c:1', 1]], confirmed: true, updatedAt: 42 },
+      mode: 'replace',
+    });
+    // The index vouches for what the row now holds: members and children.
+    expect(out.state.views.get('vk')).toEqual(['t:1', 'c:1']);
+    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' }]);
+    // Cold: no `_00_view` row to record them in, and the index is untouched.
+    expect(out.log.filter((e) => e.kind === 'local.upsert')).toEqual([]);
+    expect(out.state.views.size).toBe(0);
+  });
+  it('a query with a view row records the children there and in the index; a failed write is logged', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a', viewKey: 'vk' }, lifecycle: { phase: 'live' }, remoteArray: [['t:1', 1]] })]);
+    const out = await runPure(applySubqueryChildren('a', [['c:2', 1]]), { state: s, handlers: { 'local.upsert': () => undefined } });
+    expect(out.log.find((e) => e.kind === 'local.upsert')).toEqual({
+      kind: 'local.upsert',
+      table: '_00_view',
+      id: new RecordId('_00_view', 'vk'),
+      data: { children: [['c:2', 1]] },
+      mode: 'merge',
+    });
+    expect(out.state.views.get('vk')).toEqual(['t:1', 'c:2']);
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }]);
+    const failed = await runPure(applySubqueryChildren('a', [['c:3', 1]]), {
+      state: s,
+      handlers: {
+        'local.upsert': () => {
+          throw new Error('disk');
+        },
+      },
+    });
+    expect(failed.emitted).toEqual([expect.objectContaining({ level: 'debug', message: 'view row write failed' })]);
+    expect(failed.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 $in->_00_list_ref WHERE parent IS NONE')).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('a meta statement that errored is a failed read, not a lost row', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'live', remote: 'registered' }, remoteArray: [['thing:1', 1]] })]);
+    const out = await runPure(readMembership(env, ['a']), {
+      state: s,
+      handlers: {
+        'remote.query': () => [ok([]), { status: 'ERR', error: 'The query was not executed due to a failed transaction' }, ok([])],
+      },
+    });
+    expect(out.result).toEqual({ changed: false, failed: true });
+    expect(out.state.queries.get('a')!.lifecycle).toMatchObject({ phase: 'live', remote: 'registered' });
+    expect(out.dispatched.filter((e) => e.type === 'EnsureRegistered')).toEqual([]);
+    expect(out.dispatched.at(-1)).toEqual({ type: 'SyncOutcome', ok: false, error: 'membership read failed' });
+  });
+  it('a batch whose meta statement errored is a failed read for every query in it', async () => {
+    const s = buildState([
+      buildEntry({ def: { hash: 'a', id: qid('a') }, lifecycle: { phase: 'cached', remote: 'registered' } }),
+      buildEntry({ def: { hash: 'b', id: qid('b') }, lifecycle: { phase: 'cached', remote: 'registered' } }),
+    ]);
+    const out = await runPure(readMembership(env, ['a', 'b']), {
+      state: s,
+      handlers: { 'remote.query': () => [ok([]), { status: 'ERR', error: 'timeout' }] },
+    });
+    expect(out.result.failed).toBe(true);
+    for (const h of ['a', 'b']) expect(out.state.queries.get(h)!.lifecycle.phase).toBe('cached');
+    expect(out.dispatched.filter((e) => e.type === 'EnsureRegistered')).toEqual([]);
+  });
+  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('$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 $ins->_00_list_ref;', 'SELECT out, version FROM $in->_00_list_ref WHERE 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 a failed read', 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('$ins->')) return [ok([]), ok([])];
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(rereadFail.result.failed).toBe(true);
+    expect(n).toBe(3);
+    const rereadUnusable = await runPure(readMembership(env, ['a', 'b']), {
+      state: s,
+      handlers: { 'remote.query': (e: any) => (e.sql.includes('$ins->') ? [ok([]), ok([])] : [ok('x'), ok(null), ok(null)]) },
+    });
+    expect(rereadUnusable.result).toEqual({ changed: false, failed: true });
+    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: true });
+    expect(notArray.state.queries.get('a')!.lifecycle.phase).toBe('live');
+    const batchNotArray = await runPure(readMembership(env, ['a', 'b']), { state: s, handlers: { 'remote.query': () => [ok(null), ok(null)] } });
+    expect(batchNotArray.result).toEqual({ changed: false, failed: true });
+    const undefinedResult = await runPure(readMembership(env, ['a']), { state: single, handlers: { 'remote.query': () => undefined } });
+    expect(undefinedResult.result).toEqual({ changed: false, failed: true });
+    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: true });
+    // None of those is evidence the view is gone.
+    for (const r of [notArray, undefinedResult, errStmt]) expect(r.dispatched.filter((d) => d.type === 'EnsureRegistered')).toEqual([]);
+  });
+  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,278 @@
+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,
+  VIEW_LOST_RETRY_BASE_MS,
+  VIEW_LOST_RETRY_MAX_MS,
+  backoffMs,
+} 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 {
+  FAILED,
+  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));
+  // The row is there: whatever made it read as gone has passed.
+  if (meta?.present && (entry.viewLostCount > 0 || entry.viewLostRetryAt !== null)) {
+    yield fx.state.update(R.setViewLost(hash, 0, 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 });
+    }
+    // A recovery is already scheduled: every read in the meantime would
+    // otherwise re-register again.
+    if (entry.viewLostRetryAt !== null) return outcome;
+    if (entry.viewLostCount === 0) {
+      yield fx.state.update(R.setViewLost(hash, 1, null));
+      if (entry.lifecycle.remote !== 'unregistered') {
+        yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-dropped' }));
+      }
+      yield fx.dispatch({ type: 'EnsureRegistered' });
+      return outcome;
+    }
+    // Re-registered already and the row still reads as gone. Under load that
+    // repeated every read, each one costing the server a registration while it
+    // was still publishing the last, so from here on it is paced.
+    const delay = backoffMs(entry.viewLostCount - 1, VIEW_LOST_RETRY_BASE_MS, VIEW_LOST_RETRY_MAX_MS);
+    const now = (yield fx.now()) as number;
+    yield fx.state.update(R.setViewLost(hash, entry.viewLostCount + 1, now + delay));
+    yield fx.emit({
+      type: 'log',
+      level: 'debug',
+      message: 'view still lost; re-registering after a delay',
+      data: { hash, attempt: entry.viewLostCount + 1, delayMs: delay },
+    });
+    yield fx.timer.set(`view-lost:${hash}`, delay, { type: 'RecoverLostView', hash });
+    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, entry.subqueryRemoteArray, 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;
+}
+
+/**
+ * The paced view-lost re-registration. A no-op when the row has been seen
+ * since (the pacing was reset) or the query recovered or went away.
+ */
+export function* recoverLostView(hash: QueryHash): Saga<void> {
+  const entry = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+  if (!entry || entry.viewLostRetryAt === null) return;
+  yield fx.state.update(R.setViewLost(hash, entry.viewLostCount, null));
+  if (entry.lifecycle.phase !== 'view-lost') return;
+  if (entry.lifecycle.remote !== 'unregistered') {
+    yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-dropped' }));
+  }
+  yield fx.dispatch({ type: 'RegisterRemote', hash });
+}
+
+/**
+ * Replace the subquery child set; bodies follow through the fetch plan. A
+ * query with a `_00_view` row (past `cold`) records the children there too,
+ * so the GC keeps their bodies and a cold scan may paint them.
+ */
+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));
+  if (entry.lifecycle.phase !== 'cold') {
+    try {
+      yield fx.local.upsert(sql.VIEW_TABLE, sql.viewRecordId(entry.def.viewKey), { children }, 'merge');
+    } catch (err) {
+      yield fx.emit({ type: 'log', level: 'debug', message: 'view row write failed', data: { hash, err } });
+    }
+  }
+  yield fx.dispatch({ type: 'FetchRows' });
+}
+
+const ok = (r: Settled): r is { ok: true; value: unknown } => r.ok;
+/** One statement's result, or `FAILED` when it did not answer (see `FAILED`). */
+const stmt = (results: unknown, i: number): unknown => {
+  if (!Array.isArray(results)) return FAILED;
+  const r = (results as StatementResult[])[i];
+  return r && r.status === 'OK' ? r.result : FAILED;
+};
+
+/**
+ * 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);
+      else failed = true;
+      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 counts = stmt(r.value, 1);
+    if (!Array.isArray(edges) || counts === FAILED) {
+      failed = true;
+      return;
+    }
+    const batch = snapshotsFromBatch(edges, counts as never, hashById);
+    const held = new Map(chunk.map((h) => [h, byHash.get(h)!.remoteArray.length]));
+    const suspect = new Set(suspectHashes(batch, held, edges.length));
+    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);
+      else failed = true;
+    });
+  }
+
+  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' });
+}