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

package/src/state/reducers.ts

@@ -0,0 +1,526 @@
+import type { ConnectionState, QueryHash, RecordVersionArray, SyncHealth } from '../types';
+import type {
+  ClientState,
+  OutboxItem,
+  PendingWrite,
+  QueryEntry,
+  QueryTelemetry,
+  Row,
+  ServerViewState,
+  TabRole,
+} from './client-state';
+import type { LifecycleEvent } from './lifecycle';
+import { transition } from './lifecycle';
+import { TELEMETRY_SAMPLE_WINDOW } from '../kernel/constants';
+
+/**
+ * Pure state updates. Every reducer returns a new `ClientState`; sagas apply
+ * them through `state.update`. Reducers that change a query's render inputs
+ * add it to `dirty` themselves, which is what drives materialization.
+ */
+export type Reducer = (s: ClientState) => ClientState;
+
+const addAll = <T>(set: ReadonlySet<T>, items: Iterable<T>): ReadonlySet<T> => {
+  const next = new Set(set);
+  for (const item of items) next.add(item);
+  return next;
+};
+
+const withoutAll = <T>(set: ReadonlySet<T>, items: Iterable<T>): ReadonlySet<T> => {
+  const next = new Set(set);
+  for (const item of items) next.delete(item);
+  return next;
+};
+
+function withEntry(s: ClientState, hash: QueryHash, fn: (e: QueryEntry) => QueryEntry): ClientState {
+  const entry = s.queries.get(hash);
+  if (!entry) return s;
+  const next = fn(entry);
+  if (next === entry) return s;
+  const queries = new Map(s.queries);
+  queries.set(hash, next);
+  return { ...s, queries };
+}
+
+const hashesForTable = (s: ClientState, table: string): QueryHash[] => {
+  const out: QueryHash[] = [];
+  for (const [hash, entry] of s.queries) if (entry.def.tableName === table) out.push(hash);
+  return out;
+};
+
+// ---- queries ---------------------------------------------------------------
+
+export const putQuery =
+  (entry: QueryEntry): Reducer =>
+  (s) => {
+    const queries = new Map(s.queries);
+    queries.set(entry.def.hash, entry);
+    return { ...s, queries, dirty: addAll(s.dirty, [entry.def.hash]) };
+  };
+
+export const removeQuery =
+  (hash: QueryHash): Reducer =>
+  (s) => {
+    if (!s.queries.has(hash)) return s;
+    const queries = new Map(s.queries);
+    queries.delete(hash);
+    const membershipReread = new Map(s.membershipReread);
+    membershipReread.delete(hash);
+    return {
+      ...s,
+      queries,
+      membershipReread,
+      dirty: withoutAll(s.dirty, [hash]),
+      membershipDirty: withoutAll(s.membershipDirty, [hash]),
+    };
+  };
+
+export const applyLifecycle =
+  (hash: QueryHash, ev: LifecycleEvent): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({ ...e, lifecycle: transition(e.lifecycle, ev) }));
+
+export const setServerState =
+  (hash: QueryHash, serverState: ServerViewState): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => (e.serverState === serverState ? e : { ...e, serverState }));
+
+/**
+ * Accept a server membership set. Also releases every acked outbox item the
+ * set names: membership has caught up with the write, the overlay's job is
+ * done (invariant I7).
+ */
+/** What a `_00_view` row holding these arrays vouches for. */
+const vouchedIds = (members: RecordVersionArray, children: RecordVersionArray): string[] => [
+  ...new Set([...members.map(([id]) => id), ...children.map(([id]) => id)]),
+];
+
+const withView = (s: ClientState, viewKey: string, ids: ReadonlyArray<string>): ClientState => {
+  const views = new Map(s.views);
+  views.set(viewKey, ids);
+  return { ...s, views };
+};
+
+/**
+ * Replace the durable view index with a fresh `_00_view` read (boot, bucket
+ * switch, GC). An entry of a query in state is kept: its commits update the
+ * index as they write the row, so it is never older than the read.
+ */
+export const reloadViews =
+  (fromStore: ReadonlyMap<string, ReadonlyArray<string>>): Reducer =>
+  (s) => {
+    const views = new Map(fromStore);
+    for (const e of s.queries.values()) {
+      const held = s.views.get(e.def.viewKey);
+      if (held) views.set(e.def.viewKey, held);
+    }
+    return { ...s, views };
+  };
+
+export const commitMembership =
+  (hash: QueryHash, remoteArray: RecordVersionArray, present: boolean): Reducer =>
+  (s) => {
+    const withArray = withEntry(s, hash, (e) => ({
+      ...e,
+      remoteArray,
+      lifecycle: transition(e.lifecycle, { type: 'membership-applied', present }),
+    }));
+    if (withArray === s) return s;
+    const entry = withArray.queries.get(hash)!;
+    const named = new Set(remoteArray.map(([id]) => id));
+    const outbox = withArray.outbox.filter((item) => !(item.status === 'acked' && named.has(item.recordId)));
+    const indexed = withView(withArray, entry.def.viewKey, vouchedIds(remoteArray, entry.subqueryRemoteArray));
+    return { ...indexed, outbox, dirty: addAll(withArray.dirty, [hash]) };
+  };
+
+export const setLocalArray =
+  (hash: QueryHash, localArray: RecordVersionArray): Reducer =>
+  (s) => {
+    const next = withEntry(s, hash, (e) => ({ ...e, localArray }));
+    return next === s ? s : { ...next, dirty: addAll(next.dirty, [hash]) };
+  };
+
+/**
+ * Replace a query's subquery child set. A query past `cold` has a `_00_view`
+ * row, which records the children too (see `applySubqueryChildren`).
+ */
+export const setSubqueryRemoteArray =
+  (hash: QueryHash, subqueryRemoteArray: RecordVersionArray): Reducer =>
+  (s) => {
+    const next = withEntry(s, hash, (e) => ({ ...e, subqueryRemoteArray }));
+    const entry = next.queries.get(hash);
+    if (!entry || entry.lifecycle.phase === 'cold') return next;
+    return withView(next, entry.def.viewKey, vouchedIds(entry.remoteArray, subqueryRemoteArray));
+  };
+
+export const setRecords =
+  (hash: QueryHash, records: ReadonlyArray<Row>, changed: boolean, materializeMs: number | null): Reducer =>
+  (s) => {
+    const next = withEntry(s, hash, (e) => {
+      const prev = e.telemetry.phaseSamples.localFetch ?? [];
+      const telemetry: QueryTelemetry = {
+        ...e.telemetry,
+        updateCount: changed ? e.telemetry.updateCount + 1 : e.telemetry.updateCount,
+        phaseSamples:
+          materializeMs === null
+            ? e.telemetry.phaseSamples
+            : { ...e.telemetry.phaseSamples, localFetch: [...prev, materializeMs].slice(-TELEMETRY_SAMPLE_WINDOW) },
+        phaseLast: materializeMs === null ? e.telemetry.phaseLast : { ...e.telemetry.phaseLast, localFetch: materializeMs },
+      };
+      return {
+        ...e,
+        records: changed ? records : e.records,
+        telemetry,
+        lifecycle: transition(e.lifecycle, { type: 'notified' }),
+      };
+    });
+    return next === s ? s : { ...next, dirty: withoutAll(next.dirty, [hash]) };
+  };
+
+export const stampUpdated =
+  (hash: QueryHash, now: number): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({ ...e, telemetry: { ...e.telemetry, lastUpdatedAt: now } }));
+
+export const recordPhase =
+  (hash: QueryHash, phase: string, ms: number): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => {
+      const prev = e.telemetry.phaseSamples[phase] ?? [];
+      return {
+        ...e,
+        telemetry: {
+          ...e.telemetry,
+          phaseSamples: { ...e.telemetry.phaseSamples, [phase]: [...prev, ms].slice(-TELEMETRY_SAMPLE_WINDOW) },
+          phaseLast: { ...e.telemetry.phaseLast, [phase]: ms },
+        },
+      };
+    });
+
+/** SSP ingest wall time for one update (the `ssp` phase). */
+export const recordIngest =
+  (hash: QueryHash, ms: number): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({
+      ...e,
+      telemetry: {
+        ...e.telemetry,
+        lastIngestLatencyMs: ms,
+        materializationSamples: [...e.telemetry.materializationSamples, ms].slice(-TELEMETRY_SAMPLE_WINDOW),
+      },
+    }));
+
+export const recordError =
+  (hash: QueryHash): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({ ...e, telemetry: { ...e.telemetry, errorCount: e.telemetry.errorCount + 1 } }));
+
+export const setRegistrationTimings =
+  (hash: QueryHash, registrationTimings: QueryTelemetry['registrationTimings']): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({ ...e, telemetry: { ...e.telemetry, registrationTimings } }));
+
+export const bumpRegisterAttempts =
+  (hash: QueryHash): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({ ...e, registerAttempts: e.registerAttempts + 1 }));
+
+/** View-lost recovery pacing; see `QueryEntry.viewLostCount`. */
+export const setViewLost =
+  (hash: QueryHash, viewLostCount: number, viewLostRetryAt: number | null): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) =>
+      e.viewLostCount === viewLostCount && e.viewLostRetryAt === viewLostRetryAt
+        ? e
+        : { ...e, viewLostCount, viewLostRetryAt }
+    );
+
+export const resetRegisterAttempts =
+  (hash: QueryHash): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => (e.registerAttempts === 0 ? e : { ...e, registerAttempts: 0 }));
+
+export const stampHeartbeat =
+  (hashes: Iterable<QueryHash>, now: number): Reducer =>
+  (s) => {
+    let next = s;
+    for (const hash of hashes) next = withEntry(next, hash, (e) => ({ ...e, lastHeartbeatAt: now }));
+    return next;
+  };
+
+export const beginRegistering =
+  (hash: QueryHash): Reducer =>
+  (s) => ({ ...s, registering: addAll(s.registering, [hash]) });
+
+export const endRegistering =
+  (hash: QueryHash): Reducer =>
+  (s) =>
+    s.registering.has(hash) ? { ...s, registering: withoutAll(s.registering, [hash]) } : s;
+
+export const setMembershipReread =
+  (hash: QueryHash, attempt: number | null): Reducer =>
+  (s) => {
+    const membershipReread = new Map(s.membershipReread);
+    if (attempt === null) {
+      if (!membershipReread.delete(hash)) return s;
+    } else {
+      membershipReread.set(hash, attempt);
+    }
+    return { ...s, membershipReread };
+  };
+
+export const stampPolled =
+  (hashes: Iterable<QueryHash>, now: number): Reducer =>
+  (s) => {
+    let next = s;
+    for (const hash of hashes) next = withEntry(next, hash, (e) => ({ ...e, lastPolledAt: now }));
+    return next;
+  };
+
+// ---- subscribers -----------------------------------------------------------
+
+export const subscribe =
+  (hash: QueryHash): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => ({ ...e, subscribers: e.subscribers + 1, lastSubscriberLeftAt: null }));
+
+export const unsubscribe =
+  (hash: QueryHash, now: number): Reducer =>
+  (s) =>
+    withEntry(s, hash, (e) => {
+      const subscribers = Math.max(0, e.subscribers - 1);
+      return { ...e, subscribers, lastSubscriberLeftAt: subscribers === 0 ? now : e.lastSubscriberLeftAt };
+    });
+
+// ---- dirt ------------------------------------------------------------------
+
+export const markDirty =
+  (hashes: Iterable<QueryHash>): Reducer =>
+  (s) => {
+    const dirty = addAll(s.dirty, hashes);
+    return dirty.size === s.dirty.size ? s : { ...s, dirty };
+  };
+
+export const markTableDirty =
+  (table: string): Reducer =>
+  (s) =>
+    markDirty(hashesForTable(s, table))(s);
+
+export const clearDirty =
+  (hash: QueryHash): Reducer =>
+  (s) =>
+    s.dirty.has(hash) ? { ...s, dirty: withoutAll(s.dirty, [hash]) } : s;
+
+export const markMembershipDirty =
+  (hashes: Iterable<QueryHash>): Reducer =>
+  (s) => {
+    const live = [...hashes].filter((h) => s.queries.has(h));
+    if (live.length === 0) return s;
+    return { ...s, membershipDirty: addAll(s.membershipDirty, live) };
+  };
+
+export const clearMembershipDirty =
+  (hashes: Iterable<QueryHash>): Reducer =>
+  (s) => ({ ...s, membershipDirty: withoutAll(s.membershipDirty, hashes) });
+
+// ---- versions --------------------------------------------------------------
+
+/** Record local body versions; dirties every query whose membership names one of them. */
+export const setVersions =
+  (entries: ReadonlyArray<readonly [string, number]>): Reducer =>
+  (s) => {
+    if (entries.length === 0) return s;
+    const versions = new Map(s.versions);
+    const changed = new Set<string>();
+    for (const [id, v] of entries) {
+      if (versions.get(id) !== v) {
+        versions.set(id, v);
+        changed.add(id);
+      }
+    }
+    if (changed.size === 0) return s;
+    const dirty: QueryHash[] = [];
+    for (const [hash, entry] of s.queries) {
+      if (entry.remoteArray.some(([id]) => changed.has(id)) || entry.localArray.some(([id]) => changed.has(id))) {
+        dirty.push(hash);
+      }
+    }
+    return { ...s, versions, dirty: addAll(s.dirty, dirty) };
+  };
+
+export const deleteVersions =
+  (ids: Iterable<string>): Reducer =>
+  (s) => {
+    const versions = new Map(s.versions);
+    let touched = false;
+    for (const id of ids) touched = versions.delete(id) || touched;
+    return touched ? { ...s, versions } : s;
+  };
+
+// ---- outbox ----------------------------------------------------------------
+
+export const outboxReplace =
+  (items: ReadonlyArray<OutboxItem>): Reducer =>
+  (s) => {
+    const tables = new Set([...s.outbox, ...items].map((i) => i.table));
+    let next: ClientState = { ...s, outbox: [...items] };
+    for (const table of tables) next = markTableDirty(table)(next);
+    return next;
+  };
+
+export const outboxPush =
+  (item: OutboxItem): Reducer =>
+  (s) =>
+    markTableDirty(item.table)({ ...s, outbox: [...s.outbox, item] });
+
+export const outboxAck =
+  (id: string, now: number): Reducer =>
+  (s) => {
+    const idx = s.outbox.findIndex((i) => i.id === id);
+    if (idx < 0) return s;
+    const outbox = [...s.outbox];
+    outbox[idx] = { ...outbox[idx], status: 'acked', ackedAt: now };
+    return { ...s, outbox };
+  };
+
+export const outboxRemove =
+  (id: string): Reducer =>
+  (s) => {
+    const item = s.outbox.find((i) => i.id === id);
+    if (!item) return s;
+    return markTableDirty(item.table)({ ...s, outbox: s.outbox.filter((i) => i.id !== id) });
+  };
+
+export const outboxBumpAttempts =
+  (id: string): Reducer =>
+  (s) => {
+    const idx = s.outbox.findIndex((i) => i.id === id);
+    if (idx < 0) return s;
+    const outbox = [...s.outbox];
+    outbox[idx] = { ...outbox[idx], attempts: outbox[idx].attempts + 1 };
+    return { ...s, outbox };
+  };
+
+/** Drop acked items older than `graceMs` (membership never named them). */
+export const outboxPruneAcked =
+  (now: number, graceMs: number): Reducer =>
+  (s) => {
+    const stale = s.outbox.filter((i) => i.status === 'acked' && i.ackedAt !== null && now - i.ackedAt >= graceMs);
+    if (stale.length === 0) return s;
+    let next: ClientState = { ...s, outbox: s.outbox.filter((i) => !stale.includes(i)) };
+    for (const table of new Set(stale.map((i) => i.table))) next = markTableDirty(table)(next);
+    return next;
+  };
+
+/** Merge a debounced update into its pending write (first `before` wins). */
+export const mergePendingWrite =
+  (write: PendingWrite): Reducer =>
+  (s) => {
+    const prev = s.pendingWrites.get(write.key);
+    const pendingWrites = new Map(s.pendingWrites);
+    pendingWrites.set(
+      write.key,
+      prev ? { ...prev, data: { ...prev.data, ...write.data }, mirrorId: prev.mirrorId ?? write.mirrorId } : write
+    );
+    return { ...s, pendingWrites };
+  };
+
+export const clearPendingWrite =
+  (key: string): Reducer =>
+  (s) => {
+    if (!s.pendingWrites.has(key)) return s;
+    const pendingWrites = new Map(s.pendingWrites);
+    pendingWrites.delete(key);
+    return { ...s, pendingWrites };
+  };
+
+export const setFailedCount =
+  (failedCount: number): Reducer =>
+  (s) =>
+    s.failedCount === failedCount ? s : { ...s, failedCount };
+
+// ---- identity / connection --------------------------------------------------
+
+export const setIdentity =
+  (
+    patch: Partial<
+      Pick<ClientState, 'sessionId' | 'userId' | 'saltUserId' | 'pendingBucket' | 'bucketId' | 'tabRole' | 'localReady' | 'primed'>
+    >
+  ): Reducer =>
+  (s) => ({ ...s, ...patch });
+
+/** Re-home a query after a bucket switch: new store, same hash, fresh sync state. */
+export const rebindQuery =
+  (
+    hash: QueryHash,
+    next: { id: QueryEntry['def']['id']; lifecycle: QueryEntry['lifecycle']; remoteArray: RecordVersionArray; localArray: RecordVersionArray }
+  ): Reducer =>
+  (s) => {
+    const rebound = withEntry(s, hash, (e) => ({
+      ...e,
+      def: { ...e.def, id: next.id },
+      lifecycle: next.lifecycle,
+      remoteArray: next.remoteArray,
+      localArray: next.localArray,
+      subqueryRemoteArray: [],
+      records: [],
+      serverState: null,
+      lastHeartbeatAt: null,
+      lastPolledAt: null,
+      registerAttempts: 0,
+      viewLostCount: 0,
+      viewLostRetryAt: null,
+    }));
+    return rebound === s ? s : { ...rebound, dirty: addAll(rebound.dirty, [hash]) };
+  };
+
+/** Everything a bucket switch invalidates in one go. */
+export const clearBucketState = (): Reducer => (s) => ({
+  ...s,
+  versions: new Map(),
+  views: new Map(),
+  outbox: [],
+  pendingWrites: new Map(),
+  dirty: new Set(),
+  membershipDirty: new Set(),
+  membershipReread: new Map(),
+  primed: false,
+});
+
+export const setTabRole =
+  (tabRole: TabRole): Reducer =>
+  (s) =>
+    s.tabRole === tabRole ? s : { ...s, tabRole };
+
+export const setConnection =
+  (connection: ConnectionState): Reducer =>
+  (s) =>
+    s.sync.health.connection === connection ? s : { ...s, sync: { ...s.sync, health: { ...s.sync.health, connection } } };
+
+/**
+ * Shallow value equality over {@link SyncHealth}. `nextHealth` rebuilds the
+ * snapshot on every sync round, so identity alone would report a change each
+ * time; the runtime uses identity to decide whether to notify subscribers, and
+ * this is what keeps that identity stable while nothing actually moved.
+ */
+export const sameHealth = (a: SyncHealth, b: SyncHealth): boolean =>
+  a.status === b.status &&
+  a.consecutiveFailures === b.consecutiveFailures &&
+  a.everConnected === b.everConnected &&
+  a.connection === b.connection &&
+  a.kind === b.kind &&
+  a.error === b.error;
+
+export const setHealth =
+  (health: SyncHealth): Reducer =>
+  (s) => (sameHealth(s.sync.health, health) ? s : { ...s, sync: { ...s.sync, health } });
+
+export const patchSync =
+  (patch: Partial<Omit<ClientState['sync'], 'health'>>): Reducer =>
+  (s) => ({ ...s, sync: { ...s.sync, ...patch } });
+
+/** Compose reducers left to right. */
+export const compose =
+  (...reducers: Reducer[]): Reducer =>
+  (s) =>
+    reducers.reduce((acc, r) => r(acc), s);

package/src/state/selectors.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import * as S from './selectors';
+import * as R from './reducers';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+
+const e = (hash: string, over: Parameters<typeof buildEntry>[0] = {}) => buildEntry({ ...over, def: { hash, ...over.def } });
+
+describe('basic lookups', () => {
+  it('queryByHash / activeHashes / hashesForTable / queryStatus', () => {
+    const s = buildState([e('a', { def: { tableName: 't1' } }), e('b', { def: { tableName: 't2' } })]);
+    expect(S.queryByHash(s, 'a')?.def.hash).toBe('a');
+    expect(S.activeHashes(s)).toEqual(['a', 'b']);
+    expect(S.hashesForTable(s, 't2')).toEqual(['b']);
+    expect(S.queryStatus(s, 'a')).toBe('idle');
+    expect(S.queryStatus(s, 'zz')).toBeUndefined();
+  });
+});
+
+describe('overlay and outbox counts', () => {
+  it('derives writes/deletes from pending and acked items', () => {
+    const s = buildState(
+      [],
+      R.outboxReplace([
+        buildOutboxItem({ id: '1', type: 'create', recordId: 'thing:1' }),
+        buildOutboxItem({ id: '2', type: 'update', recordId: 'thing:2', status: 'acked', ackedAt: 1 }),
+        buildOutboxItem({ id: '3', type: 'delete', recordId: 'thing:3' }),
+      ])
+    );
+    const o = S.overlay(s);
+    expect([...o.writes].sort()).toEqual(['thing:1', 'thing:2']);
+    expect([...o.deletes]).toEqual(['thing:3']);
+    expect([...S.pendingDeleteIds(s)]).toEqual(['thing:3']);
+    expect(S.hasAckedWrites(s)).toBe(true);
+    expect(S.pendingMutationCount(s)).toBe(2);
+  });
+});
+
+describe('needed / planFetch / settled', () => {
+  const live = { phase: 'live' } as const;
+  it('needed compares membership versions against local versions and skips pending deletes', () => {
+    const s = buildState(
+      [e('a', { lifecycle: live, remoteArray: [['thing:1', 2], ['thing:2', 1], ['thing:3', 1]] })],
+      R.setVersions([['thing:1', 2], ['thing:2', 0]]),
+      R.outboxReplace([buildOutboxItem({ type: 'delete', recordId: 'thing:3' })])
+    );
+    expect(S.needed(s, 'a')).toEqual([['thing:2', 1]]);
+    expect(S.needed(s, 'missing')).toEqual([]);
+    const cached = buildState([e('c', { lifecycle: { phase: 'cached' }, remoteArray: [['thing:9', 1]] })]);
+    expect(S.needed(cached, 'c')).toEqual([]);
+  });
+  it('planFetch dedupes across queries (highest version wins), includes subquery children, chunks', () => {
+    const s = buildState([
+      e('a', { lifecycle: live, remoteArray: [['thing:1', 1], ['thing:2', 3]] }),
+      e('b', { lifecycle: live, remoteArray: [['thing:2', 1], ['thing:3', 1]], subqueryRemoteArray: [['child:1', 2]] }),
+      e('c', { lifecycle: live, subqueryRemoteArray: [['child:1', 1], ['child:2', 1]] }),
+      e('d', { lifecycle: { phase: 'cached' }, remoteArray: [['thing:9', 1]] }),
+    ]);
+    const plan = S.planFetch(s, 2);
+    expect(plan.hashes).toEqual(['a', 'b']);
+    expect(plan.chunks).toEqual([['thing:1', 'thing:2'], ['thing:3', 'child:1'], ['child:2']]);
+    expect(plan.versions.get('thing:2')).toBe(3);
+    expect(plan.versions.get('child:1')).toBe(2);
+    expect(S.planFetch(buildState()).chunks).toEqual([]);
+    expect(S.neededChildren(s, 'missing')).toEqual([]);
+    expect(S.neededChildren(R.setVersions([['child:1', 2]])(s), 'b')).toEqual([]);
+  });
+  it('settled requires live, complete, clean, notified', () => {
+    const base = e('a', { lifecycle: { ...live, notified: true }, remoteArray: [['thing:1', 1]] });
+    const s = { ...buildState([base], R.setVersions([['thing:1', 1]])), dirty: new Set<string>() };
+    expect(S.settled(s, 'a')).toBe(true);
+    expect(S.settled(R.markDirty(['a'])(s), 'a')).toBe(false);
+    expect(S.settled(R.setVersions([['thing:1', 0]])(s), 'a')).toBe(false);
+    expect(S.settled(buildState([e('a', { lifecycle: { phase: 'cached', notified: true } })]), 'a')).toBe(false);
+    expect(S.settled(buildState([e('a', { lifecycle: live })]), 'a')).toBe(false);
+    expect(S.settled(s, 'missing')).toBe(false);
+    expect(S.settleFailed(s, 'missing')).toBe(true);
+    expect(S.settleFailed(s, 'a')).toBe(false);
+    expect(S.settleFailed(R.applyLifecycle('a', { type: 'remote-failed' })(s), 'a')).toBe(true);
+  });
+  it('fetchingQueryCount counts entries with fetch depth', () => {
+    const s = buildState([e('a', { lifecycle: { fetchDepth: 2 } }), e('b')]);
+    expect(S.fetchingQueryCount(s)).toBe(1);
+  });
+  it('fetchingQueryCount leaves out background re-verification', () => {
+    const s = buildState([
+      e('verifying', { lifecycle: { phase: 'cached', fetchDepth: 1, backgroundDepth: 1 } }),
+      e('downloading', { lifecycle: { phase: 'live', fetchDepth: 2, backgroundDepth: 1 } }),
+    ]);
+    expect(S.fetchingQueryCount(s)).toBe(1);
+    expect(S.queryStatus(s, 'verifying')).toBe('fetching');
+  });
+});
+
+describe('registration / eviction / ttl', () => {
+  it('desiredRegistrations lists unregistered queries', () => {
+    const s = buildState([e('a'), e('b', { lifecycle: { remote: 'registered' } }), e('c', { lifecycle: { remote: 'registering' } })]);
+    expect(S.desiredRegistrations(s)).toEqual(['a']);
+  });
+  it('evictable respects subscribers and ttl', () => {
+    const s = buildState([
+      e('gone', { lastSubscriberLeftAt: 0, def: { ttlMs: 100 } }),
+      e('fresh', { lastSubscriberLeftAt: 950, def: { ttlMs: 100 } }),
+      e('watched', { subscribers: 1, lastSubscriberLeftAt: 0, def: { ttlMs: 100 } }),
+      e('never', { def: { ttlMs: 100 } }),
+    ]);
+    expect(S.evictable(s, 1000)).toEqual(['gone']);
+  });
+  it('shortestTtlMs', () => {
+    expect(S.shortestTtlMs(buildState())).toBeNull();
+    expect(S.shortestTtlMs(buildState([e('a', { def: { ttlMs: 500 } }), e('b', { def: { ttlMs: 100 } })]))).toBe(100);
+  });
+});
+
+describe('toQueryState', () => {
+  it('projects the legacy shape with derived flags', () => {
+    const entry = e('a', {
+      lifecycle: { phase: 'view-lost', fetchDepth: 1, notified: true },
+      remoteArray: [['thing:1', 1]],
+      subqueryRemoteArray: [['child:1', 1]],
+      records: [{ id: 'thing:1' }],
+      serverState: 'ready',
+      lastHeartbeatAt: 123,
+    });
+    const qs = S.toQueryState(entry);
+    expect(qs.config.membershipKnown).toBe(true);
+    expect(qs.config.membershipKey).toBe('view-a');
+    expect(qs.viewLost).toBe(true);
+    expect(qs.serverMembership).toBe(true);
+    expect(qs.status).toBe('fetching');
+    expect(qs.syncNotified).toBe(true);
+    expect(qs.config.subqueryRemoteArray).toEqual([['child:1', 1]]);
+    expect(qs.config.lastActiveAt.getTime()).toBe(123);
+    expect(qs.records).toEqual([{ id: 'thing:1' }]);
+    const cold = S.toQueryState(e('b'));
+    expect(cold.config.membershipKnown).toBe(false);
+    expect(cold.config.subqueryRemoteArray).toBeUndefined();
+    expect(cold.lastHeartbeatAt).toBeUndefined();
+    expect(cold.config.lastActiveAt.getTime()).toBe(1_700_000_000_000);
+  });
+});
+
+describe('phaseTimings', () => {
+  it('summarizes every phase, with nulls before the first sample', () => {
+    const cold = S.phaseTimings(e('a'));
+    expect(cold.ssp).toEqual({ lastMs: null, p50: null, p90: null, p99: null, count: 0 });
+    expect(cold.localFetch.count).toBe(0);
+    let s = buildState([e('a')]);
+    for (const ms of [5, 1, 9, 3]) s = R.recordIngest('a', ms)(s);
+    s = R.recordPhase('a', 'remoteFetch', 7)(s);
+    s = R.recordError('a')(s);
+    const t = S.phaseTimings(s.queries.get('a')!);
+    expect(t.ssp).toEqual({ lastMs: 3, p50: 5, p90: 9, p99: 9, count: 4 });
+    expect(t.remoteFetch).toEqual({ lastMs: 7, p50: 7, p90: 7, p99: 7, count: 1 });
+    expect(t.errorCount).toBe(1);
+    expect(t.registration.parseMs).toBeNull();
+  });
+});
+
+describe('view index selectors', () => {
+  it('vouched is the union of every view row, memoized on the index', () => {
+    const s = R.reloadViews(new Map([['v1', ['t:1', 't:2']], ['v2', ['t:2', 'c:1']]]))(buildState());
+    expect([...S.vouched(s)]).toEqual(['t:1', 't:2', 'c:1']);
+    expect(S.vouched({ ...s, dirty: new Set(['x']) })).toBe(S.vouched(s));
+  });
+  it('retained: vouched, held in memory (members, children), in the outbox or a debounced write, or bookkeeping', () => {
+    const s = R.compose(
+      R.reloadViews(new Map([['v', ['t:vouched']]])),
+      R.outboxReplace([buildOutboxItem({ recordId: 't:outbox' })]),
+      (st) => ({ ...st, pendingWrites: new Map([['k', { key: 'k', table: 't', recordId: 't:debounced', data: {}, before: null, firstAt: 0, mirrorId: null }]]) })
+    )(buildState([e('a', { remoteArray: [['t:member', 1]], subqueryRemoteArray: [['t:child', 1]] })]));
+    const keep = S.retained(s);
+    for (const id of ['t:vouched', 't:member', 't:child', 't:outbox', 't:debounced', '_00_view:x']) expect(keep(id)).toBe(true);
+    expect(keep('t:orphan')).toBe(false);
+  });
+});