@spooky-sync/core 0.0.1-canary.35 → 0.0.1-canary.351

package/src/state/lifecycle.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest';
+import type { LifecycleEvent, QueryLifecycle, QueryPhase } from './lifecycle';
+import { deriveStatus, hasServerMembership, isAnswered, isAuthoritative, isForegroundFetching, LifecycleError, seedLifecycle, transition } from './lifecycle';
+
+const at = (phase: QueryPhase, over: Partial<QueryLifecycle> = {}): QueryLifecycle => ({
+  phase,
+  remote: 'unregistered',
+  fetchDepth: 0,
+  backgroundDepth: 0,
+  notified: false,
+  answered: false,
+  ...over,
+});
+
+describe('transition table (phase axis)', () => {
+  it('seed', () => {
+    expect(transition(at('live'), { type: 'seed', resolvedBefore: true }).phase).toBe('cached');
+    expect(transition(at('live'), { type: 'seed', resolvedBefore: false }).phase).toBe('cold');
+  });
+  it('membership-applied moves every phase to live', () => {
+    for (const p of ['cold', 'cached', 'live'] as const) {
+      expect(transition(at(p), { type: 'membership-applied', present: true }).phase).toBe('live');
+      expect(transition(at(p), { type: 'membership-applied', present: false }).phase).toBe('live');
+    }
+    expect(transition(at('view-lost'), { type: 'membership-applied', present: true }).phase).toBe('live');
+  });
+  it('view-lost needs a present row to recover', () => {
+    expect(() => transition(at('view-lost'), { type: 'membership-applied', present: false })).toThrow(LifecycleError);
+  });
+  it('row-missing: cold stays cold, everything else goes view-lost', () => {
+    expect(transition(at('cold'), { type: 'row-missing' }).phase).toBe('cold');
+    expect(transition(at('cached'), { type: 'row-missing' }).phase).toBe('view-lost');
+    expect(transition(at('live'), { type: 'row-missing' }).phase).toBe('view-lost');
+    expect(transition(at('view-lost'), { type: 'row-missing' }).phase).toBe('view-lost');
+  });
+  it('bucket-switch reseeds and clears fetch depth', () => {
+    const l = transition(at('live', { fetchDepth: 3, notified: true, answered: true }), { type: 'bucket-switch', resolvedBefore: true });
+    expect(l).toEqual({ phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false, answered: false });
+  });
+});
+
+describe('answered', () => {
+  it('a seed is never answered, not even a cached one: its rows are not painted yet', () => {
+    expect(seedLifecycle(true)).toMatchObject({ phase: 'cached', answered: false });
+    expect(isAnswered(seedLifecycle(true))).toBe(false);
+    expect(isAuthoritative(seedLifecycle(true))).toBe(true);
+  });
+  it('only a render of a known membership answers; a cold render is a guess', () => {
+    expect(transition(at('cold'), { type: 'notified', answered: true }).answered).toBe(false);
+    expect(transition(at('cached'), { type: 'notified' }).answered).toBe(false);
+    expect(transition(at('cached'), { type: 'notified', answered: false })).toMatchObject({ notified: true, answered: false });
+    for (const p of ['cached', 'live', 'view-lost'] as const) {
+      expect(transition(at(p), { type: 'notified', answered: true })).toMatchObject({ notified: true, answered: true });
+    }
+  });
+  it('latched through membership, a reconnect and a lost view; cleared by a re-seed', () => {
+    let l = transition(at('cached'), { type: 'notified', answered: true });
+    l = transition(l, { type: 'membership-applied', present: true });
+    expect(l).toMatchObject({ phase: 'live', answered: true });
+    l = transition(l, { type: 'notified', answered: false });
+    expect(l.answered).toBe(true);
+    l = transition(l, { type: 'remote-dropped' });
+    expect(l).toMatchObject({ notified: false, answered: true });
+    l = transition(l, { type: 'row-missing' });
+    expect(l).toMatchObject({ phase: 'view-lost', answered: true });
+    expect(transition(l, { type: 'bucket-switch', resolvedBefore: true }).answered).toBe(false);
+    expect(transition(l, { type: 'seed', resolvedBefore: true }).answered).toBe(false);
+  });
+  it('a server set applied to a cold query is not an answer until its render', () => {
+    const l = transition(at('cold'), { type: 'membership-applied', present: true });
+    expect(l).toMatchObject({ phase: 'live', answered: false });
+    expect(isAuthoritative(l)).toBe(true);
+    expect(isAnswered(l)).toBe(false);
+  });
+  it('an unchanged notified keeps identity', () => {
+    const l = transition(at('live'), { type: 'notified', answered: true });
+    expect(transition(l, { type: 'notified', answered: true })).toBe(l);
+    expect(transition(l, { type: 'notified' })).toBe(l);
+  });
+});
+
+describe('remote / fetch / notified axes', () => {
+  it('remote transitions', () => {
+    let l = at('cached');
+    l = transition(l, { type: 'remote-registering' });
+    expect(l.remote).toBe('registering');
+    l = transition(l, { type: 'remote-registered' });
+    expect(l.remote).toBe('registered');
+    l = transition(l, { type: 'notified' });
+    expect(l.notified).toBe(true);
+    l = transition(l, { type: 'remote-dropped' });
+    expect(l).toMatchObject({ remote: 'unregistered', notified: false });
+    l = transition(l, { type: 'remote-failed' });
+    expect(l.remote).toBe('failed');
+  });
+  it('fetch depth is a refcount that never goes negative', () => {
+    let l = at('live');
+    l = transition(l, { type: 'fetch-begin' });
+    l = transition(l, { type: 'fetch-begin' });
+    expect(deriveStatus(l)).toBe('fetching');
+    l = transition(l, { type: 'fetch-end' });
+    expect(deriveStatus(l)).toBe('fetching');
+    l = transition(l, { type: 'fetch-end' });
+    expect(deriveStatus(l)).toBe('idle');
+    const same = transition(l, { type: 'fetch-end' });
+    expect(same).toBe(l);
+  });
+  it('background cycles hold fetching but are not foreground', () => {
+    let l = at('cached');
+    l = transition(l, { type: 'fetch-begin', background: true });
+    expect(deriveStatus(l)).toBe('fetching');
+    expect(isForegroundFetching(l)).toBe(false);
+    l = transition(l, { type: 'fetch-begin' });
+    expect(isForegroundFetching(l)).toBe(true);
+    l = transition(l, { type: 'fetch-end' });
+    expect(l).toMatchObject({ fetchDepth: 1, backgroundDepth: 1 });
+    expect(isForegroundFetching(l)).toBe(false);
+    l = transition(l, { type: 'fetch-end', background: true });
+    expect(l).toMatchObject({ fetchDepth: 0, backgroundDepth: 0 });
+    expect(deriveStatus(l)).toBe('idle');
+  });
+  it('an unbalanced end never leaves more background cycles than cycles', () => {
+    const l = transition(at('live', { fetchDepth: 1, backgroundDepth: 1 }), { type: 'fetch-end' });
+    expect(l).toMatchObject({ fetchDepth: 0, backgroundDepth: 0 });
+  });
+  it('notified is idempotent', () => {
+    const l = transition(at('live'), { type: 'notified' });
+    expect(transition(l, { type: 'notified' })).toBe(l);
+  });
+});
+
+describe('derived predicates', () => {
+  it('authority and server membership follow the phase', () => {
+    expect(isAuthoritative(at('cold'))).toBe(false);
+    expect(isAuthoritative(at('cached'))).toBe(true);
+    expect(hasServerMembership(at('cached'))).toBe(false);
+    expect(hasServerMembership(at('live'))).toBe(true);
+    expect(hasServerMembership(at('view-lost'))).toBe(true);
+    expect(seedLifecycle(true).phase).toBe('cached');
+  });
+});
+
+describe('invariants over random event sequences', () => {
+  const events: LifecycleEvent[] = [
+    { type: 'membership-applied', present: true },
+    { type: 'row-missing' },
+    { type: 'remote-registering' },
+    { type: 'remote-registered' },
+    { type: 'remote-dropped' },
+    { type: 'fetch-begin' },
+    { type: 'fetch-end' },
+    { type: 'fetch-begin', background: true },
+    { type: 'fetch-end', background: true },
+    { type: 'notified' },
+    { type: 'notified', answered: true },
+    { type: 'bucket-switch', resolvedBefore: false },
+    { type: 'seed', resolvedBefore: true },
+  ];
+  // Deterministic LCG so the sequence is reproducible.
+  let seed = 42;
+  const rand = () => (seed = (seed * 1664525 + 1013904223) % 2 ** 32) / 2 ** 32;
+
+  it('0 <= backgroundDepth <= fetchDepth, notified only after live-or-cached, view-lost never from cold', () => {
+    for (let run = 0; run < 200; run++) {
+      let l = seedLifecycle(rand() < 0.5);
+      for (let i = 0; i < 25; i++) {
+        const ev = events[Math.floor(rand() * events.length)];
+        const before = l;
+        try {
+          l = transition(l, ev);
+        } catch (err) {
+          expect(err).toBeInstanceOf(LifecycleError);
+          continue;
+        }
+        expect(l.fetchDepth).toBeGreaterThanOrEqual(0);
+        expect(l.backgroundDepth).toBeGreaterThanOrEqual(0);
+        expect(l.backgroundDepth).toBeLessThanOrEqual(l.fetchDepth);
+        if (ev.type === 'row-missing' && before.phase === 'cold') expect(l.phase).toBe('cold');
+        if (l.phase === 'view-lost') expect(before.phase).not.toBe('cold');
+        if (l.answered) expect(l.phase).not.toBe('cold');
+      }
+    }
+  });
+});

package/src/state/lifecycle.ts

@@ -0,0 +1,127 @@
+import type { QueryStatus } from '../types';
+
+/**
+ * The query lifecycle as one explicit machine.
+ *
+ * `phase` answers "where do this query's rows come from":
+ * - `cold`      never resolved on this device: rows come from a local
+ *               predicate scan (or the SSP local window), bindings show a loader.
+ * - `cached`    a durable `_00_view` row was found: rows come from that id-set.
+ * - `live`      a server membership set was accepted this session.
+ * - `view-lost` the server's `_00_query` row vanished while we held
+ *               membership; rows are kept, a re-registration is under way.
+ *
+ * `remote` tracks the server-side registration, `fetchDepth` is the refcount
+ * behind `status: 'fetching'`, `notified` says whether subscribers received
+ * at least one materialization this registration.
+ *
+ * `answered` says subscribers have been handed the rows of a known membership
+ * (the server's, or the durable one of an earlier session) at least once:
+ * a materialization ran past `cold`, with no body of a server set still to
+ * download, and the membership it drew was still the one in state when it
+ * committed. Only a re-seed (a new entry, a bucket switch) clears it, so a
+ * reconnect or a lost view does not send a painted query back to loading.
+ * It is what the bindings' `isAuthoritative()` mirrors (see `isAnswered`):
+ * a `cached` seed or a freshly applied server set alone is not enough,
+ * because `records` is still empty (or stale) until `materialize` paints, and
+ * "known and empty" read in that beat made apps create rows that existed.
+ *
+ * `backgroundDepth` is the part of `fetchDepth` that re-verifies rows the
+ * query already shows: a registration of a query that is not `cold`. It still
+ * holds `status: 'fetching'` (results are not yet confirmed), but it is not
+ * traffic the user waits on, so the activity indicator leaves it out.
+ */
+export type QueryPhase = 'cold' | 'cached' | 'live' | 'view-lost';
+export type RemotePhase = 'unregistered' | 'registering' | 'registered' | 'failed';
+
+export interface QueryLifecycle {
+  readonly phase: QueryPhase;
+  readonly remote: RemotePhase;
+  readonly fetchDepth: number;
+  readonly backgroundDepth: number;
+  readonly notified: boolean;
+  readonly answered: boolean;
+}
+
+export type LifecycleEvent =
+  | { type: 'seed'; resolvedBefore: boolean }
+  | { type: 'membership-applied'; present: boolean }
+  | { type: 'row-missing' }
+  | { type: 'remote-registering' }
+  | { type: 'remote-registered' }
+  | { type: 'remote-failed' }
+  | { type: 'remote-dropped' }
+  | { type: 'fetch-begin'; background?: boolean }
+  | { type: 'fetch-end'; background?: boolean }
+  | { type: 'notified'; answered?: boolean }
+  | { type: 'bucket-switch'; resolvedBefore: boolean };
+
+export class LifecycleError extends Error {
+  constructor(lifecycle: QueryLifecycle, event: LifecycleEvent) {
+    super(`Impossible lifecycle transition: ${lifecycle.phase}/${lifecycle.remote} + ${event.type}`);
+    this.name = 'LifecycleError';
+  }
+}
+
+export function seedLifecycle(resolvedBefore: boolean): QueryLifecycle {
+  return {
+    phase: resolvedBefore ? 'cached' : 'cold',
+    remote: 'unregistered',
+    fetchDepth: 0,
+    backgroundDepth: 0,
+    notified: false,
+    answered: false,
+  };
+}
+
+/** Total on every (lifecycle, event) pair the sagas can produce; throws on the rest. */
+export function transition(l: QueryLifecycle, ev: LifecycleEvent): QueryLifecycle {
+  switch (ev.type) {
+    case 'seed':
+      return seedLifecycle(ev.resolvedBefore);
+    case 'membership-applied':
+      if (l.phase === 'view-lost' && !ev.present) throw new LifecycleError(l, ev);
+      return { ...l, phase: 'live' };
+    case 'row-missing':
+      // A cold query holds nothing the server could have lost: the outcome
+      // is `ignored` upstream and the phase does not move.
+      return l.phase === 'cold' ? l : { ...l, phase: 'view-lost' };
+    case 'remote-registering':
+      return { ...l, remote: 'registering' };
+    case 'remote-registered':
+      return { ...l, remote: 'registered' };
+    case 'remote-failed':
+      return { ...l, remote: 'failed' };
+    case 'remote-dropped':
+      return { ...l, remote: 'unregistered', notified: false };
+    case 'fetch-begin':
+      return { ...l, fetchDepth: l.fetchDepth + 1, backgroundDepth: l.backgroundDepth + (ev.background ? 1 : 0) };
+    case 'fetch-end': {
+      if (l.fetchDepth === 0) return l;
+      const fetchDepth = l.fetchDepth - 1;
+      // Never more background cycles than cycles: an unbalanced end clamps.
+      const backgroundDepth = Math.min(fetchDepth, l.backgroundDepth - (ev.background && l.backgroundDepth > 0 ? 1 : 0));
+      return { ...l, fetchDepth, backgroundDepth };
+    }
+    case 'notified': {
+      // A cold render is a guess from the local store, never an answer.
+      const answered = l.answered || (ev.answered === true && l.phase !== 'cold');
+      return l.notified && answered === l.answered ? l : { ...l, notified: true, answered };
+    }
+    case 'bucket-switch':
+      return { ...seedLifecycle(ev.resolvedBefore), fetchDepth: 0 };
+  }
+}
+
+/** Membership is known (server set or durable seed); its rows may not be painted yet. */
+export const isAuthoritative = (l: QueryLifecycle): boolean => l.phase !== 'cold';
+/**
+ * Subscribers hold the rows of a known membership: what the authority channel
+ * (`subscribeQueryAuthority`, the bindings' `isAuthoritative()`) reports.
+ */
+export const isAnswered = (l: QueryLifecycle): boolean => l.answered;
+export const hasServerMembership = (l: QueryLifecycle): boolean =>
+  l.phase === 'live' || l.phase === 'view-lost';
+export const deriveStatus = (l: QueryLifecycle): QueryStatus => (l.fetchDepth > 0 ? 'fetching' : 'idle');
+/** A fetch cycle the user is waiting on: rows to download, or a first registration. */
+export const isForegroundFetching = (l: QueryLifecycle): boolean => l.fetchDepth > l.backgroundDepth;

package/src/state/reducers.test.ts

@@ -0,0 +1,319 @@
+import { describe, expect, it } from 'vitest';
+import * as R from './reducers';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import { emptyState } from './client-state';
+
+const e = (hash: string, over: Parameters<typeof buildEntry>[0] = {}) => buildEntry({ ...over, def: { hash, ...over.def } });
+
+describe('query reducers', () => {
+  it('putQuery adds and dirties; removeQuery clears dirt', () => {
+    let s = R.putQuery(e('a'))(emptyState({ tabId: 't' }));
+    expect(s.queries.has('a')).toBe(true);
+    expect(s.dirty.has('a')).toBe(true);
+    s = R.markMembershipDirty(['a'])(s);
+    s = R.removeQuery('a')(s);
+    expect(s.queries.size).toBe(0);
+    expect(s.dirty.size).toBe(0);
+    expect(s.membershipDirty.size).toBe(0);
+    expect(R.removeQuery('zzz')(s)).toBe(s);
+  });
+
+  it('reducers on an unknown hash are identity', () => {
+    const s = buildState([e('a')]);
+    expect(R.applyLifecycle('x', { type: 'notified' })(s)).toBe(s);
+    expect(R.setLocalArray('x', [])(s)).toBe(s);
+    expect(R.commitMembership('x', [['thing:1', 1]], true)(s)).toBe(s);
+    expect(R.subscribe('x')(s)).toBe(s);
+    expect(R.setRecords('x', [], true, 1)(s)).toBe(s);
+  });
+
+  it('applyLifecycle / setServerState', () => {
+    const s0 = buildState([e('a')]);
+    const s1 = R.applyLifecycle('a', { type: 'remote-registering' })(s0);
+    expect(s1.queries.get('a')!.lifecycle.remote).toBe('registering');
+    const s2 = R.setServerState('a', 'ready')(s1);
+    expect(s2.queries.get('a')!.serverState).toBe('ready');
+    expect(R.setServerState('a', 'ready')(s2)).toBe(s2);
+  });
+
+  it('commitMembership sets the array, flips live, dirties, and releases acked items it names', () => {
+    const s0 = buildState(
+      [e('a', { lifecycle: { phase: 'cached' } })],
+      R.outboxReplace([
+        buildOutboxItem({ id: 'm1', recordId: 'thing:1', status: 'acked', ackedAt: 1 }),
+        buildOutboxItem({ id: 'm2', recordId: 'thing:2', status: 'acked', ackedAt: 1 }),
+        buildOutboxItem({ id: 'm3', recordId: 'thing:1', status: 'pending' }),
+      ])
+    );
+    const s1 = R.commitMembership('a', [['thing:1', 2]], true)({ ...s0, dirty: new Set() });
+    const entry = s1.queries.get('a')!;
+    expect(entry.remoteArray).toEqual([['thing:1', 2]]);
+    expect(entry.lifecycle.phase).toBe('live');
+    expect(s1.dirty.has('a')).toBe(true);
+    expect(s1.outbox.map((i) => i.id)).toEqual(['m2', 'm3']);
+  });
+
+  it('setLocalArray dirties; setSubqueryRemoteArray does not', () => {
+    const s0 = buildState([e('a')]);
+    const s1 = R.setLocalArray('a', [['thing:1', 1]])(s0);
+    expect(s1.dirty.has('a')).toBe(true);
+    const s2 = R.setSubqueryRemoteArray('a', [['child:1', 1]])({ ...s1, dirty: new Set() });
+    expect(s2.dirty.size).toBe(0);
+    expect(s2.queries.get('a')!.subqueryRemoteArray).toEqual([['child:1', 1]]);
+  });
+
+  it('setRecords clears dirt, counts changes, samples timing, marks notified', () => {
+    const s0 = R.markDirty(['a'])(buildState([e('a')]));
+    const rows = [{ id: 'thing:1' }];
+    const s1 = R.setRecords('a', rows, true, 12)(s0);
+    const en = s1.queries.get('a')!;
+    expect(en.records).toBe(rows);
+    expect(en.telemetry.updateCount).toBe(1);
+    expect(en.telemetry.phaseSamples.localFetch).toEqual([12]);
+    expect(en.telemetry.phaseLast.localFetch).toBe(12);
+    expect(en.lifecycle.notified).toBe(true);
+    expect(s1.dirty.has('a')).toBe(false);
+    const s2 = R.setRecords('a', [{ id: 'other' }], false, null)(s1);
+    expect(s2.queries.get('a')!.records).toBe(rows);
+    expect(s2.queries.get('a')!.telemetry.updateCount).toBe(1);
+    expect(s2.queries.get('a')!.telemetry.phaseSamples.localFetch).toEqual([12]);
+  });
+
+  it('setRecords answers a query only when told to, and never a cold one', () => {
+    const cold = buildState([e('a')]);
+    expect(R.setRecords('a', [], false, null, true)(cold).queries.get('a')!.lifecycle.answered).toBe(false);
+    const cached = buildState([e('a', { lifecycle: { phase: 'cached' } })]);
+    expect(R.setRecords('a', [], false, null)(cached).queries.get('a')!.lifecycle).toMatchObject({ notified: true, answered: false });
+    expect(R.setRecords('a', [], false, null, true)(cached).queries.get('a')!.lifecycle).toMatchObject({ notified: true, answered: true });
+  });
+
+  it('sample windows are capped', () => {
+    let s = buildState([e('a')]);
+    for (let i = 0; i < 105; i++) s = R.recordPhase('a', 'localFetch', i)(s);
+    const t = s.queries.get('a')!.telemetry;
+    expect(t.phaseSamples.localFetch).toHaveLength(100);
+    expect(t.phaseLast.localFetch).toBe(104);
+    for (let i = 0; i < 105; i++) s = R.setRecords('a', [], false, i)(s);
+    expect(s.queries.get('a')!.telemetry.phaseSamples.localFetch).toHaveLength(100);
+    for (let i = 0; i < 105; i++) s = R.recordIngest('a', i)(s);
+    expect(s.queries.get('a')!.telemetry.materializationSamples).toHaveLength(100);
+    expect(s.queries.get('a')!.telemetry.lastIngestLatencyMs).toBe(104);
+  });
+
+  it('telemetry helpers', () => {
+    let s = buildState([e('a')]);
+    s = R.stampUpdated('a', 5)(s);
+    s = R.recordError('a')(s);
+    s = R.setRegistrationTimings('a', { parseMs: 1, planMs: 2, snapshotMs: 3, wallMs: 4 })(s);
+    s = R.bumpRegisterAttempts('a')(s);
+    s = R.bumpRegisterAttempts('a')(s);
+    s = R.stampHeartbeat(['a', 'missing'], 9)(s);
+    s = R.stampPolled(['a'], 11)(s);
+    const en = s.queries.get('a')!;
+    expect(en.telemetry.lastUpdatedAt).toBe(5);
+    expect(en.telemetry.errorCount).toBe(1);
+    expect(en.telemetry.registrationTimings.wallMs).toBe(4);
+    expect(en.registerAttempts).toBe(2);
+    expect(en.lastHeartbeatAt).toBe(9);
+    expect(en.lastPolledAt).toBe(11);
+    const reset = R.resetRegisterAttempts('a')(s);
+    expect(reset.queries.get('a')!.registerAttempts).toBe(0);
+    expect(R.resetRegisterAttempts('a')(reset)).toBe(reset);
+    const lost = R.setViewLost('a', 2, 900)(reset);
+    expect(lost.queries.get('a')).toMatchObject({ viewLostCount: 2, viewLostRetryAt: 900 });
+    expect(R.setViewLost('a', 2, 900)(lost)).toBe(lost);
+  });
+
+  it('subscribe / unsubscribe track the eviction clock', () => {
+    let s = buildState([e('a')]);
+    s = R.subscribe('a')(s);
+    s = R.subscribe('a')(s);
+    expect(s.queries.get('a')!.subscribers).toBe(2);
+    s = R.unsubscribe('a', 100)(s);
+    expect(s.queries.get('a')!.lastSubscriberLeftAt).toBeNull();
+    s = R.unsubscribe('a', 200)(s);
+    expect(s.queries.get('a')!.lastSubscriberLeftAt).toBe(200);
+    s = R.unsubscribe('a', 300)(s);
+    expect(s.queries.get('a')!.subscribers).toBe(0);
+    s = R.subscribe('a')(s);
+    expect(s.queries.get('a')!.lastSubscriberLeftAt).toBeNull();
+  });
+});
+
+describe('registering / reread bookkeeping', () => {
+  it('tracks in-flight local registrations and reread attempts; removeQuery clears rereads', () => {
+    let s = buildState([e('a')]);
+    s = R.beginRegistering('x')(s);
+    expect(s.registering.has('x')).toBe(true);
+    s = R.endRegistering('x')(s);
+    expect(s.registering.size).toBe(0);
+    expect(R.endRegistering('x')(s)).toBe(s);
+    s = R.setMembershipReread('a', 1)(s);
+    expect(s.membershipReread.get('a')).toBe(1);
+    expect(R.setMembershipReread('zzz', null)(s)).toBe(s);
+    const cleared = R.removeQuery('a')(s);
+    expect(cleared.membershipReread.size).toBe(0);
+    s = R.setMembershipReread('a', null)(s);
+    expect(s.membershipReread.size).toBe(0);
+  });
+});
+
+describe('dirt reducers', () => {
+  it('markDirty / clearDirty / markTableDirty', () => {
+    const s0 = buildState([e('a', { def: { tableName: 't1' } }), e('b', { def: { tableName: 't2' } })]);
+    expect(R.markDirty([])(s0)).toBe(s0);
+    const s1 = R.markTableDirty('t1')(s0);
+    expect([...s1.dirty]).toEqual(['a']);
+    const s2 = R.clearDirty('a')(s1);
+    expect(s2.dirty.size).toBe(0);
+    expect(R.clearDirty('a')(s2)).toBe(s2);
+  });
+  it('membership dirt only for known hashes', () => {
+    const s0 = buildState([e('a')]);
+    expect(R.markMembershipDirty(['nope'])(s0)).toBe(s0);
+    const s1 = R.markMembershipDirty(['a', 'nope'])(s0);
+    expect([...s1.membershipDirty]).toEqual(['a']);
+    expect(R.clearMembershipDirty(['a'])(s1).membershipDirty.size).toBe(0);
+  });
+});
+
+describe('versions', () => {
+  it('setVersions dirties queries naming the id, ignores unchanged, deleteVersions removes', () => {
+    const s0 = buildState([
+      e('a', { remoteArray: [['thing:1', 1]] }),
+      e('b', { localArray: [['thing:2', 1]] }),
+      e('c'),
+      // A related row (a thread's author): a new body must re-render the list.
+      e('d', { subqueryRemoteArray: [['user:1', 1]] }),
+    ]);
+    expect(R.setVersions([])(s0)).toBe(s0);
+    const s1 = R.setVersions([['thing:1', 1], ['thing:2', 1], ['thing:9', 1], ['user:1', 2]])(s0);
+    expect([...s1.dirty].sort()).toEqual(['a', 'b', 'd']);
+    expect(R.setVersions([['thing:1', 1]])(s1)).toBe(s1);
+    const s2 = R.deleteVersions(['thing:9', 'nope'])(s1);
+    expect(s2.versions.has('thing:9')).toBe(false);
+    expect(R.deleteVersions(['nope'])(s2)).toBe(s2);
+  });
+});
+
+describe('outbox', () => {
+  it('push / ack / bump / remove / replace dirty the table', () => {
+    const s0 = buildState([e('a', { def: { tableName: 'thing' } })]);
+    const s1 = R.outboxPush(buildOutboxItem({ id: 'm1' }))(s0);
+    expect(s1.dirty.has('a')).toBe(true);
+    const s2 = R.outboxAck('m1', 50)({ ...s1, dirty: new Set() });
+    expect(s2.outbox[0]).toMatchObject({ status: 'acked', ackedAt: 50 });
+    expect(s2.dirty.size).toBe(0);
+    expect(R.outboxAck('nope', 1)(s2)).toBe(s2);
+    const s3 = R.outboxBumpAttempts('m1')(s2);
+    expect(s3.outbox[0].attempts).toBe(1);
+    expect(R.outboxBumpAttempts('nope')(s3)).toBe(s3);
+    const doubt = R.outboxMarkInDoubt(['m1', 'nope'])(s3);
+    expect(doubt.outbox[0]).toMatchObject({ id: 'm1', inDoubt: true, attempts: 1 });
+    expect(R.outboxMarkInDoubt(['m1'])(doubt)).toBe(doubt);
+    const s4 = R.outboxRemove('m1')(s3);
+    expect(s4.outbox).toEqual([]);
+    expect(s4.dirty.has('a')).toBe(true);
+    expect(R.outboxRemove('m1')(s4)).toBe(s4);
+    const s5 = R.outboxReplace([buildOutboxItem({ id: 'x', table: 'thing' })])({ ...s4, dirty: new Set() });
+    expect(s5.outbox).toHaveLength(1);
+    expect(s5.dirty.has('a')).toBe(true);
+  });
+  it('outboxPruneAcked drops only expired acked items', () => {
+    const s0 = buildState(
+      [e('a', { def: { tableName: 'thing' } })],
+      R.outboxReplace([
+        buildOutboxItem({ id: 'old', status: 'acked', ackedAt: 0 }),
+        buildOutboxItem({ id: 'fresh', status: 'acked', ackedAt: 90 }),
+        buildOutboxItem({ id: 'pending' }),
+      ])
+    );
+    const s1 = R.outboxPruneAcked(100, 50)({ ...s0, dirty: new Set() });
+    expect(s1.outbox.map((i) => i.id)).toEqual(['fresh', 'pending']);
+    expect(s1.dirty.has('a')).toBe(true);
+    expect(R.outboxPruneAcked(100, 50)(s1)).toBe(s1);
+  });
+  it('pending writes merge per key and clear', () => {
+    const w = { key: 'k', table: 'thing', recordId: 'thing:1', data: { a: 1 }, before: { a: 0 }, firstAt: 1, mirrorId: null };
+    let s = R.mergePendingWrite(w)(buildState());
+    s = R.mergePendingWrite({ ...w, data: { b: 2 }, before: null, firstAt: 9, mirrorId: '_00_pending_writes:m' })(s);
+    expect(s.pendingWrites.get('k')).toEqual({ ...w, data: { a: 1, b: 2 }, mirrorId: '_00_pending_writes:m' });
+    s = R.mergePendingWrite({ ...w, mirrorId: '_00_pending_writes:other' })(s);
+    expect(s.pendingWrites.get('k')!.mirrorId).toBe('_00_pending_writes:m');
+    s = R.clearPendingWrite('k')(s);
+    expect(s.pendingWrites.size).toBe(0);
+    expect(R.clearPendingWrite('k')(s)).toBe(s);
+  });
+  it('setFailedCount', () => {
+    const s0 = buildState();
+    const s1 = R.setFailedCount(2)(s0);
+    expect(s1.failedCount).toBe(2);
+    expect(R.setFailedCount(2)(s1)).toBe(s1);
+  });
+});
+
+describe('bucket switch reducers', () => {
+  it('rebindQuery keeps the hash, swaps the id and sync state, dirties; clearBucketState wipes per-bucket slices', () => {
+    const s0 = buildState(
+      [e('a', { lifecycle: { phase: 'live', remote: 'registered', notified: true }, remoteArray: [['t:1', 1]], records: [{ id: 't:1' }], serverState: 'ready', registerAttempts: 2 })],
+      R.setVersions([['t:1', 1]]),
+      R.outboxReplace([buildOutboxItem()])
+    );
+    const id = { table: '_00_query', id: 'new' } as any;
+    const s1 = R.rebindQuery('a', { id, lifecycle: { phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false, answered: false }, remoteArray: [['t:2', 1]], localArray: [] })({ ...s0, dirty: new Set() });
+    const en = s1.queries.get('a')!;
+    expect(en.def.id).toBe(id);
+    expect(en.lifecycle.phase).toBe('cached');
+    expect(en.remoteArray).toEqual([['t:2', 1]]);
+    // What subscribers still hold: the next render diffs against it, so a new
+    // store that renders `[]` is a change they hear about.
+    expect(en.records).toEqual([{ id: 't:1' }]);
+    expect(en.serverState).toBeNull();
+    expect(en.registerAttempts).toBe(0);
+    expect(s1.dirty.has('a')).toBe(true);
+    expect(R.rebindQuery('zz', { id, lifecycle: en.lifecycle, remoteArray: [], localArray: [] })(s1)).toBe(s1);
+    const s2 = R.clearBucketState()(s1);
+    expect(s2.versions.size).toBe(0);
+    expect(s2.outbox).toEqual([]);
+    expect(s2.dirty.size).toBe(0);
+    expect(s2.primed).toBe(false);
+  });
+});
+
+describe('identity / connection / compose', () => {
+  it('sets fields and short-circuits on no change', () => {
+    const s0 = buildState();
+    const s1 = R.setIdentity({ sessionId: 's', userId: 'u', bucketId: 'b' })(s0);
+    expect(s1).toMatchObject({ sessionId: 's', userId: 'u', bucketId: 'b' });
+    const s2 = R.setTabRole('leader')(s1);
+    expect(R.setTabRole('leader')(s2)).toBe(s2);
+    const s3 = R.setConnection('connected')(s2);
+    expect(s3.sync.health.connection).toBe('connected');
+    expect(R.setConnection('connected')(s3)).toBe(s3);
+    const s4 = R.setHealth({ ...s3.sync.health, status: 'degraded' })(s3);
+    expect(s4.sync.health.status).toBe('degraded');
+    const s5 = R.patchSync({ pollIdleStreak: 4 })(s4);
+    expect(s5.sync.pollIdleStreak).toBe(4);
+    const s6 = R.compose(R.setFailedCount(1), R.setFailedCount(3))(s5);
+    expect(s6.failedCount).toBe(3);
+  });
+});
+
+describe('durable view index', () => {
+  it('commit and children keep a view key in step with its `_00_view` row; cold children are not indexed', () => {
+    let s = buildState([e('a', { def: { viewKey: 'va' }, lifecycle: { phase: 'cold' }, subqueryRemoteArray: [['c:1', 1]] })]);
+    s = R.setSubqueryRemoteArray('a', [['c:1', 1], ['c:2', 1]])(s);
+    expect(s.views.size).toBe(0);
+    s = R.commitMembership('a', [['t:1', 1], ['c:1', 1]], true)(s);
+    expect(s.views.get('va')).toEqual(['t:1', 'c:1', 'c:2']);
+    s = R.setSubqueryRemoteArray('a', [['c:3', 1]])(s);
+    expect(s.views.get('va')).toEqual(['t:1', 'c:1', 'c:3']);
+    expect(R.setSubqueryRemoteArray('zz', [['c:9', 1]])(s)).toBe(s);
+    expect(R.clearBucketState()(s).views.size).toBe(0);
+  });
+  it('a reload takes the store, except entries of queries in state', () => {
+    const s = R.compose(R.commitMembership('a', [['t:new', 1]], true))(buildState([e('a', { def: { viewKey: 'va' } }), e('b', { def: { viewKey: 'vb' } })]));
+    const reloaded = R.reloadViews(new Map([['va', ['t:old']], ['vb', ['t:b']], ['vc', ['t:c']]]))(s);
+    expect(reloaded.views).toEqual(new Map([['va', ['t:new']], ['vb', ['t:b']], ['vc', ['t:c']]]));
+  });
+});