@spooky-sync/core 0.0.1-canary.27 → 0.0.1-canary.270

package/src/state/client-state.ts

@@ -0,0 +1,191 @@
+import type { QueryPlan, RecordId } from '@spooky-sync/query-builder';
+import type {
+  ConnectionState,
+  MutationEventType,
+  QueryHash,
+  QueryTimeToLive,
+  RecordVersionArray,
+  RegistrationTimings,
+  SyncHealth,
+} from '../types';
+import type { QueryLifecycle } from './lifecycle';
+import type { LaneState } from '../kernel/saga';
+import { emptyLanes } from '../kernel/saga';
+
+export type Row = Record<string, unknown>;
+
+/** Everything a query is, minus anything that changes after registration. */
+export interface QueryDefinition {
+  /** Session-salted `_00_query:<hash>` record id: the remote view id. */
+  readonly id: RecordId<string>;
+  readonly hash: QueryHash;
+  /** Unsalted `sha256({surql, params})`: key of the durable `_00_view` row. */
+  readonly viewKey: string;
+  readonly surql: string;
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly plan?: QueryPlan;
+  readonly ttl: QueryTimeToLive;
+  readonly ttlMs: number;
+  readonly tableName: string;
+  readonly createdAt: number;
+}
+
+export type ServerViewState = 'materializing' | 'ready' | null;
+
+export interface QueryTelemetry {
+  readonly updateCount: number;
+  readonly errorCount: number;
+  readonly lastUpdatedAt: number | null;
+  readonly materializationSamples: ReadonlyArray<number>;
+  readonly lastIngestLatencyMs: number | null;
+  readonly phaseSamples: Readonly<Record<string, ReadonlyArray<number>>>;
+  readonly phaseLast: Readonly<Record<string, number | null>>;
+  readonly registrationTimings: RegistrationTimings;
+}
+
+export interface QueryEntry {
+  readonly def: QueryDefinition;
+  readonly lifecycle: QueryLifecycle;
+  /** Server membership (ids + versions) or the durable seed. */
+  readonly remoteArray: RecordVersionArray;
+  /** The in-browser SSP view's id-set: local truth for "does this row match". */
+  readonly localArray: RecordVersionArray;
+  readonly subqueryRemoteArray: RecordVersionArray;
+  readonly records: ReadonlyArray<Row>;
+  readonly serverState: ServerViewState;
+  readonly subscribers: number;
+  readonly lastSubscriberLeftAt: number | null;
+  readonly lastHeartbeatAt: number | null;
+  readonly lastPolledAt: number | null;
+  readonly registerAttempts: number;
+  /**
+   * Re-registrations issued because the `_00_query` row read as gone, since
+   * the row was last seen. Paces the next one (see `applyMembership`).
+   */
+  readonly viewLostCount: number;
+  /** When the paced re-registration is due; null when none is pending. */
+  readonly viewLostRetryAt: number | null;
+  readonly telemetry: QueryTelemetry;
+}
+
+export type OutboxStatus = 'pending' | 'acked';
+
+/** In-memory mirror of one `_00_pending_mutations` row plus its push progress. */
+export interface OutboxItem {
+  readonly id: string;
+  readonly type: MutationEventType;
+  readonly recordId: string;
+  readonly table: string;
+  readonly status: OutboxStatus;
+  readonly ackedAt: number | null;
+  readonly attempts: number;
+}
+
+export type TabRole = 'solo' | 'leader' | 'follower';
+
+/** A debounced update accumulating locally until its flush writes the outbox row. */
+export interface PendingWrite {
+  readonly key: string;
+  readonly table: string;
+  readonly recordId: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly before: Readonly<Record<string, unknown>> | null;
+  readonly firstAt: number;
+}
+
+export interface SyncSlice {
+  readonly health: SyncHealth;
+  readonly consecutiveFailures: number;
+  readonly hasSyncedOnce: boolean;
+  readonly selfHealAttempts: number;
+  readonly pollIdleStreak: number;
+  readonly lastReconnectRefetchAt: number | null;
+  readonly needsResubscribe: boolean;
+  readonly fetchAttempts: number;
+  readonly liveUuid: string | null;
+  readonly liveTable: string | null;
+  readonly lanes: LaneState;
+}
+
+export interface ClientState {
+  readonly sessionId: string | null;
+  readonly userId: string | null;
+  /** The principal the current session salt was minted for. */
+  readonly saltUserId: string | null;
+  /** Latest bucket-switch target; an older switch that wakes up to a newer target skips. */
+  readonly pendingBucket: string | null;
+  readonly tabId: string;
+  readonly tabRole: TabRole;
+  readonly bucketId: string | null;
+  readonly localReady: boolean;
+  readonly primed: boolean;
+  readonly queries: ReadonlyMap<QueryHash, QueryEntry>;
+  /** Hashes whose local registration is in flight (dedupes concurrent `query()` calls). */
+  readonly registering: ReadonlySet<QueryHash>;
+  /** Re-read attempts per hash while the server reports a view as `materializing`. */
+  readonly membershipReread: ReadonlyMap<QueryHash, number>;
+  /** Local body versions (`_00_rv`) by encoded record id. */
+  readonly versions: ReadonlyMap<string, number>;
+  readonly outbox: ReadonlyArray<OutboxItem>;
+  readonly pendingWrites: ReadonlyMap<string, PendingWrite>;
+  readonly failedCount: number;
+  /** Queries whose render inputs changed since their last materialization. */
+  readonly dirty: ReadonlySet<QueryHash>;
+  /** Queries whose server membership must be re-read. */
+  readonly membershipDirty: ReadonlySet<QueryHash>;
+  readonly sync: SyncSlice;
+}
+
+export const emptyTelemetry = (): QueryTelemetry => ({
+  updateCount: 0,
+  errorCount: 0,
+  lastUpdatedAt: null,
+  materializationSamples: [],
+  lastIngestLatencyMs: null,
+  phaseSamples: {},
+  phaseLast: {},
+  registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
+});
+
+export const initialHealth = (connection: ConnectionState = 'disconnected'): SyncHealth => ({
+  status: 'healthy',
+  consecutiveFailures: 0,
+  everConnected: false,
+  connection,
+});
+
+export function emptyState(init: { tabId: string }): ClientState {
+  return {
+    sessionId: null,
+    userId: null,
+    saltUserId: null,
+    pendingBucket: null,
+    tabId: init.tabId,
+    tabRole: 'solo',
+    bucketId: null,
+    localReady: false,
+    primed: false,
+    queries: new Map(),
+    registering: new Set(),
+    membershipReread: new Map(),
+    versions: new Map(),
+    outbox: [],
+    pendingWrites: new Map(),
+    failedCount: 0,
+    dirty: new Set(),
+    membershipDirty: new Set(),
+    sync: {
+      health: initialHealth(),
+      consecutiveFailures: 0,
+      hasSyncedOnce: false,
+      selfHealAttempts: 0,
+      pollIdleStreak: 0,
+      lastReconnectRefetchAt: null,
+      needsResubscribe: false,
+      fetchAttempts: 0,
+      liveUuid: null,
+      liveTable: null,
+      lanes: emptyLanes(),
+    },
+  };
+}

package/src/state/lifecycle.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import type { LifecycleEvent, QueryLifecycle, QueryPhase } from './lifecycle';
+import { deriveStatus, hasServerMembership, isAuthoritative, LifecycleError, seedLifecycle, transition } from './lifecycle';
+
+const at = (phase: QueryPhase, over: Partial<QueryLifecycle> = {}): QueryLifecycle => ({
+  phase,
+  remote: 'unregistered',
+  fetchDepth: 0,
+  notified: 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 }), { type: 'bucket-switch', resolvedBefore: true });
+    expect(l).toEqual({ phase: 'cached', remote: 'unregistered', fetchDepth: 0, notified: false });
+  });
+});
+
+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('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: 'notified' },
+    { 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('fetchDepth >= 0, 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);
+        if (ev.type === 'row-missing' && before.phase === 'cold') expect(l.phase).toBe('cold');
+        if (l.phase === 'view-lost') expect(before.phase).not.toBe('cold');
+      }
+    }
+  });
+});

package/src/state/lifecycle.ts

@@ -0,0 +1,86 @@
+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.
+ */
+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 notified: 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' }
+  | { type: 'fetch-end' }
+  | { type: 'notified' }
+  | { 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, notified: 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 };
+    case 'fetch-end':
+      return l.fetchDepth === 0 ? l : { ...l, fetchDepth: l.fetchDepth - 1 };
+    case 'notified':
+      return l.notified ? l : { ...l, notified: true };
+    case 'bucket-switch':
+      return { ...seedLifecycle(ev.resolvedBefore), fetchDepth: 0 };
+  }
+}
+
+export const isAuthoritative = (l: QueryLifecycle): boolean => l.phase !== 'cold';
+export const hasServerMembership = (l: QueryLifecycle): boolean =>
+  l.phase === 'live' || l.phase === 'view-lost';
+export const deriveStatus = (l: QueryLifecycle): QueryStatus => (l.fetchDepth > 0 ? 'fetching' : 'idle');

package/src/state/reducers.test.ts

@@ -0,0 +1,283 @@
+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('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'),
+    ]);
+    expect(R.setVersions([])(s0)).toBe(s0);
+    const s1 = R.setVersions([['thing:1', 1], ['thing:2', 1], ['thing:9', 1]])(s0);
+    expect([...s1.dirty].sort()).toEqual(['a', 'b']);
+    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 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 };
+    let s = R.mergePendingWrite(w)(buildState());
+    s = R.mergePendingWrite({ ...w, data: { b: 2 }, before: null, firstAt: 9 })(s);
+    expect(s.pendingWrites.get('k')).toEqual({ ...w, data: { a: 1, b: 2 } });
+    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, notified: 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]]);
+    expect(en.records).toEqual([]);
+    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);
+  });
+});