@spooky-sync/core 0.0.1-canary.33 → 0.0.1-canary.331

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

@@ -0,0 +1,407 @@
+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('rows the server takes out of a query', () => {
+  it('a child nothing else holds is forgotten locally and the query re-renders; a held one stays', async () => {
+    const s = buildState(
+      [
+        buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live' }, remoteArray: [['t:1', 1]], subqueryRemoteArray: [['c:1', 1], ['c:9', 1]] }),
+        buildEntry({ def: { hash: 'b' }, lifecycle: { phase: 'live' }, remoteArray: [['c:9', 1]] }),
+      ],
+      R.setVersions([['t:1', 1], ['c:1', 1], ['c:9', 1]])
+    );
+    const out = await runPure(applySubqueryChildren('a', []), {
+      state: { ...s, dirty: new Set<string>() },
+      handlers: { 'local.upsert': () => undefined, 'local.delete': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    expect(out.log.filter((e) => e.kind === 'local.delete')).toEqual([expect.objectContaining({ table: 'c', id: 'c:1' })]);
+    expect(out.log.find((e) => e.kind === 'ssp.ingest')).toEqual(
+      expect.objectContaining({ records: [{ table: 'c', op: 'DELETE', id: 'c:1', record: {} }] })
+    );
+    expect(out.state.versions.has('c:1')).toBe(false);
+    expect(out.state.versions.has('c:9')).toBe(true);
+    expect(out.state.dirty.has('a')).toBe(true);
+  });
+  it('a row with a pending local write is kept, and a follower tab never deletes', async () => {
+    const base = buildState(
+      [buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live' }, remoteArray: [['t:1', 1]], subqueryRemoteArray: [['c:1', 1]] })],
+      R.setVersions([['t:1', 1], ['c:1', 1]])
+    );
+    const handlers = { 'local.upsert': () => undefined, 'local.delete': () => undefined, 'ssp.ingest': () => undefined };
+    const pending = { ...base, outbox: [buildOutboxItem({ recordId: 'c:1' })] };
+    expect((await runPure(applySubqueryChildren('a', []), { state: pending, handlers })).log.some((e) => e.kind === 'local.delete')).toBe(false);
+    const follower = { ...base, tabRole: 'follower' as const };
+    expect((await runPure(applySubqueryChildren('a', []), { state: follower, handlers })).log.some((e) => e.kind === 'local.delete')).toBe(false);
+    const writing = {
+      ...base,
+      pendingWrites: new Map([['k', { key: 'k', table: 'c', recordId: 'c:1', data: {}, before: null, firstAt: 0, mirrorId: null }]]),
+    };
+    expect((await runPure(applySubqueryChildren('a', []), { state: writing, handlers })).log.some((e) => e.kind === 'local.delete')).toBe(false);
+  });
+  it('a leader relays the removal to its followers; a failed local delete keeps the row known', async () => {
+    const base = buildState(
+      [buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live' }, remoteArray: [['t:1', 1]], subqueryRemoteArray: [['c:1', 1]] })],
+      R.setVersions([['t:1', 1], ['c:1', 1]])
+    );
+    const ok = { 'local.upsert': () => undefined, 'local.delete': () => undefined, 'ssp.ingest': () => undefined };
+    const leader = await runPure(applySubqueryChildren('a', []), { state: { ...base, tabRole: 'leader' as const }, handlers: ok });
+    expect(leader.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'ingest', records: [{ table: 'c', op: 'DELETE', id: 'c:1', record: {} }] } });
+    const failing = {
+      ...ok,
+      'local.delete': () => {
+        throw new Error('locked');
+      },
+    };
+    const out = await runPure(applySubqueryChildren('a', []), { state: base, handlers: failing });
+    expect(out.state.versions.has('c:1')).toBe(true);
+    expect(out.log.some((e) => e.kind === 'ssp.ingest')).toBe(false);
+  });
+});
+
+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' } });
+  });
+});