@spooky-sync/core 0.0.1-canary.240 → 0.0.1-canary.241

package/src/query/membership.ts

@@ -0,0 +1,158 @@
+import type { RecordId } from 'surrealdb';
+import type { MembershipOutcome, RecordVersionArray, ServerViewMeta } from '../types';
+import type { QueryPhase } from '../state/lifecycle';
+import { encodeRecordId } from '../utils/index';
+
+/** The durable `_00_view` row: the last server-confirmed membership. */
+export interface DurableView {
+  ids: RecordVersionArray;
+  confirmed: boolean;
+}
+
+export function parseViewRow(row: unknown): DurableView | null {
+  if (!row || typeof row !== 'object') return null;
+  const ids = (row as { ids?: unknown }).ids;
+  if (!Array.isArray(ids)) return null;
+  return { ids: ids as RecordVersionArray, confirmed: (row as { confirmed?: unknown }).confirmed === true };
+}
+
+/**
+ * "Resolved before": the server answered this query on this device at some
+ * point. An unconfirmed empty row cannot be told apart from one written before
+ * the marker existed, so it does not count.
+ */
+export const isResolvedBefore = (view: DurableView | null): boolean =>
+  view !== null && (view.ids.length > 0 || view.confirmed);
+
+/** The `{ rowCount, state }` object the row-count selects return per row. */
+export interface QueryMetaRow {
+  id?: RecordId<string>;
+  rowCount?: number | null;
+  state?: string | null;
+}
+
+export function metaFromRow(row: QueryMetaRow | null | undefined): ServerViewMeta {
+  if (!row || typeof row !== 'object') return { present: false, rowCount: null, state: null };
+  const state = row.state === 'materializing' || row.state === 'ready' ? row.state : null;
+  return { present: true, rowCount: typeof row.rowCount === 'number' ? row.rowCount : null, state };
+}
+
+/** Collapse duplicate `(id, version)` pairs to one per id, keeping the highest version. */
+export function dedupeRecordVersions(pairs: RecordVersionArray): RecordVersionArray {
+  if (pairs.length < 2) return pairs;
+  const best = new Map<string, number>();
+  for (const [id, version] of pairs) {
+    const prev = best.get(id);
+    if (prev === undefined || version > prev) best.set(id, version);
+  }
+  if (best.size === pairs.length) return pairs;
+  return Array.from(best.entries());
+}
+
+export interface MembershipDecisionInput {
+  phase: QueryPhase;
+  /** Number of ids currently held as membership. */
+  held: number;
+  remoteArray: RecordVersionArray;
+  meta?: ServerViewMeta;
+  verifiedRemoval?: boolean;
+}
+
+/**
+ * Whether a server id-set may be applied. A NON-EMPTY set is always the
+ * server's answer. An EMPTY set is believed only when the server stands
+ * behind it: the `_00_query` row is present, `ready` (or pre-`state`), and
+ * reports zero rows. A missing row while we hold membership is a lost view.
+ */
+export function decideMembershipOutcome(input: MembershipDecisionInput): MembershipOutcome {
+  const { phase, held, remoteArray, meta, verifiedRemoval } = input;
+  if (remoteArray.length > 0 || verifiedRemoval) return 'applied';
+  if (!meta || !meta.present) {
+    return held > 0 || phase !== 'cold' ? 'view-lost' : 'ignored';
+  }
+  const knownEmpty = meta.rowCount === 0 && meta.state !== 'materializing';
+  return knownEmpty ? 'applied' : 'ignored';
+}
+
+// ---- list_ref snapshots ------------------------------------------------------
+
+export interface ListRefEdgeRow {
+  in: RecordId<string>;
+  out: RecordId<string>;
+  version: number;
+  parent?: unknown;
+}
+
+export interface ListRefSnapshot {
+  primary: RecordVersionArray;
+  subquery: RecordVersionArray;
+  meta: ServerViewMeta;
+}
+
+const toPairs = (rows: Array<{ out: RecordId<string>; version: number }> | null | undefined): RecordVersionArray =>
+  dedupeRecordVersions(Array.isArray(rows) ? rows.map((r) => [encodeRecordId(r.out), r.version]) : []);
+
+/** Fold the single-query statement batch (edges, meta, children) into a snapshot. */
+export function snapshotFromSingle(
+  items: Array<{ out: RecordId<string>; version: number }> | null,
+  metaRow: QueryMetaRow | null,
+  children: Array<{ out: RecordId<string>; version: number }> | null
+): ListRefSnapshot | null {
+  if (!Array.isArray(items)) return null;
+  return { primary: toPairs(items), subquery: toPairs(children), meta: metaFromRow(metaRow) };
+}
+
+/**
+ * Fold the many-query statement batch into one snapshot per hash. Every hash
+ * in `hashById` gets a snapshot; a query whose row did not come back reads
+ * `present: false`.
+ */
+export function snapshotsFromBatch(
+  edges: ListRefEdgeRow[] | null,
+  counts: Array<QueryMetaRow | null> | null,
+  hashById: ReadonlyMap<string, string>
+): Map<string, ListRefSnapshot> {
+  const out = new Map<string, ListRefSnapshot>();
+  if (!Array.isArray(edges)) return out;
+  for (const hash of hashById.values()) {
+    out.set(hash, { primary: [], subquery: [], meta: { present: false, rowCount: null, state: null } });
+  }
+  for (const row of edges) {
+    const hash = hashById.get(encodeRecordId(row.in));
+    if (!hash) continue;
+    const snapshot = out.get(hash)!;
+    const pair: [string, number] = [encodeRecordId(row.out), row.version];
+    if (row.parent == null) snapshot.primary.push(pair);
+    else snapshot.subquery.push(pair);
+  }
+  for (const snapshot of out.values()) {
+    snapshot.primary = dedupeRecordVersions(snapshot.primary);
+    snapshot.subquery = dedupeRecordVersions(snapshot.subquery);
+  }
+  for (const count of Array.isArray(counts) ? counts : []) {
+    if (!count || !count.id) continue;
+    const hash = hashById.get(encodeRecordId(count.id));
+    if (!hash) continue;
+    out.get(hash)!.meta = metaFromRow(count);
+  }
+  return out;
+}
+
+/**
+ * A batch that must not be believed at face value: a query we hold rows for
+ * whose `_00_query` row did not come back, or no edge at all while the server
+ * still reports rows for a held query. Such hashes are re-read one at a time.
+ */
+export function suspectHashes(
+  snapshots: ReadonlyMap<string, ListRefSnapshot>,
+  heldCounts: ReadonlyMap<string, number>,
+  edgeCount: number
+): string[] {
+  const out: string[] = [];
+  for (const [hash, snapshot] of snapshots) {
+    const held = heldCounts.get(hash) ?? 0;
+    if (held === 0) continue;
+    if (!snapshot.meta.present || (edgeCount === 0 && (snapshot.meta.rowCount ?? 0) > 0)) out.push(hash);
+  }
+  return out;
+}

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

@@ -0,0 +1,251 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure, sha256Hex } from '../testing/run-pure';
+import { buildEntry, buildState } from '../testing/build';
+import { defaultEnv } from './env';
+import { queryHashInput } from './hash';
+import { ensureRegistered, registerLocal, registerRemote } from './register.saga';
+import * as R from '../state/reducers';
+import { emptyState } from '../state/client-state';
+import type { StatementResult } from '../kernel/effects';
+
+const env = defaultEnv({ tables: [{ name: 'thing', columns: {} }] } as any);
+const input = { tableName: 'thing', surql: 'SELECT * FROM thing', params: {}, ttl: '10m' as const };
+const sspOk = () => ({ localArray: [['thing:9', 1]], timings: { parseMs: 1, planMs: 1, snapshotMs: 1, wallMs: 1 } });
+const okStmt = (result: unknown): StatementResult => ({ status: 'OK', result });
+
+describe('registerLocal', () => {
+  it('cold: no view row -> cold entry, SSP view, EnsureRegistered', async () => {
+    const state = { ...emptyState({ tabId: 't' }), sessionId: 'sess' };
+    const out = await runPure(registerLocal(env, input), {
+      state,
+      handlers: { 'local.getById': () => null, 'ssp.register': sspOk },
+    });
+    const hash = await sha256Hex(queryHashInput(input, 'sess'));
+    expect(out.result).toBe(hash);
+    const entry = out.state.queries.get(hash)!;
+    expect(entry.lifecycle.phase).toBe('cold');
+    expect(entry.remoteArray).toEqual([]);
+    expect(entry.localArray).toEqual([['thing:9', 1]]);
+    expect(entry.def.ttlMs).toBe(600_000);
+    expect(entry.telemetry.registrationTimings.wallMs).toBe(1);
+    expect(out.state.dirty.has(hash)).toBe(true);
+    expect(out.state.registering.size).toBe(0);
+    expect(out.dispatched).toEqual([{ type: 'EnsureRegistered' }]);
+    const reg = out.log.find((e) => e.kind === 'ssp.register');
+    expect(reg).toMatchObject({ plan: { queryHash: hash, tableName: 'thing', ttl: '10m' } });
+  });
+
+  it('cached: a durable view row seeds membership; unconfirmed empty stays cold; a failing read is cold', async () => {
+    const cached = await runPure(registerLocal(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [['thing:1', 2]], confirmed: false }), 'ssp.register': sspOk },
+    });
+    const e1 = cached.state.queries.get(cached.result)!;
+    expect(e1.lifecycle.phase).toBe('cached');
+    expect(e1.remoteArray).toEqual([['thing:1', 2]]);
+    const confirmedEmpty = await runPure(registerLocal(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [], confirmed: true }), 'ssp.register': sspOk },
+    });
+    expect(confirmedEmpty.state.queries.get(confirmedEmpty.result)!.lifecycle.phase).toBe('cached');
+    const unconfirmed = await runPure(registerLocal(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [], confirmed: false }), 'ssp.register': sspOk },
+    });
+    expect(unconfirmed.state.queries.get(unconfirmed.result)!.lifecycle.phase).toBe('cold');
+    const failing = await runPure(registerLocal(env, input), {
+      handlers: {
+        'local.getById': () => {
+          throw new Error('no table');
+        },
+        'ssp.register': sspOk,
+      },
+    });
+    expect(failing.state.queries.get(failing.result)!.lifecycle.phase).toBe('cold');
+  });
+
+  it('dedupes: active returns immediately, pending waits for the other registration', async () => {
+    const hash = await sha256Hex(queryHashInput(input, null));
+    const active = buildState([buildEntry({ def: { hash } })]);
+    const a = await runPure(registerLocal(env, input), { state: active });
+    expect(a.result).toBe(hash);
+    expect(a.log.filter((e) => e.kind === 'ssp.register')).toHaveLength(0);
+    const pending = R.beginRegistering(hash)(emptyState({ tabId: 't' }));
+    const p = await runPure(registerLocal(env, input), {
+      state: pending,
+      handlers: { 'state.wait': (_e, ctx) => void (ctx.state = R.endRegistering(hash)(ctx.state)) },
+    });
+    expect(p.result).toBe(hash);
+    expect(p.log.some((e) => e.kind === 'state.wait')).toBe(true);
+  });
+
+  it('a failing SSP registration clears the in-flight marker and rethrows', async () => {
+    await expect(
+      runPure(registerLocal(env, input), {
+        handlers: {
+          'local.getById': () => null,
+          'ssp.register': () => {
+            throw new Error('wasm down');
+          },
+        },
+      })
+    ).rejects.toThrow('wasm down');
+  });
+});
+
+describe('ensureRegistered', () => {
+  it('dispatches RegisterRemote for every unregistered query only', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } }), buildEntry({ def: { hash: 'b' }, lifecycle: { remote: 'registered' } })]);
+    const out = await runPure(ensureRegistered(env), { state: s });
+    expect(out.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+    const none = await runPure(ensureRegistered(env), { state: buildState() });
+    expect(none.dispatched).toEqual([]);
+  });
+  it('with requireAuth: probes $auth.id, retries on a timer, gives up after the budget, skips when anonymous', async () => {
+    const s = { ...buildState([buildEntry({ def: { hash: 'a' } })]), userId: 'user:1' };
+    const authed = await runPure(ensureRegistered(env, { requireAuth: true }), {
+      state: s,
+      handlers: { 'remote.query': () => [okStmt('user:1')] },
+    });
+    expect(authed.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+    const notYet = await runPure(ensureRegistered(env, { requireAuth: true, attempt: 2 }), {
+      state: s,
+      handlers: { 'remote.query': () => [okStmt(null)] },
+    });
+    expect(notYet.dispatched).toEqual([]);
+    expect(notYet.timers.get('ensure-registered')).toEqual({ ms: 500, event: { type: 'EnsureRegistered', requireAuth: true, attempt: 3 } });
+    const thrown = await runPure(ensureRegistered(env, { requireAuth: true }), {
+      state: s,
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(thrown.timers.has('ensure-registered')).toBe(true);
+    const exhausted = await runPure(ensureRegistered(env, { requireAuth: true, attempt: 9 }), {
+      state: s,
+      handlers: { 'remote.query': () => [okStmt(null)] },
+    });
+    expect(exhausted.timers.size).toBe(0);
+    expect(exhausted.emitted).toEqual([expect.objectContaining({ type: 'log', level: 'warn' })]);
+    const anon = await runPure(ensureRegistered(env, { requireAuth: true }), { state: { ...s, userId: null } });
+    expect(anon.dispatched).toEqual([{ type: 'RegisterRemote', hash: 'a' }]);
+  });
+});
+
+describe('registerRemote', () => {
+  const entry = buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'cold' } });
+  const happy = () => [
+    okStmt(null),
+    okStmt([{ out: new RecordId('thing', '1'), version: 1 }]),
+    okStmt({ rowCount: 1, state: 'ready' }),
+    okStmt([{ out: new RecordId('child', 'c'), version: 1 }]),
+  ];
+  it('registers, applies membership + children, flips registered, fetch-begin/end balanced', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': happy, 'local.upsert': () => undefined },
+    });
+    const e = out.state.queries.get('a')!;
+    expect(e.lifecycle).toMatchObject({ phase: 'live', remote: 'registered', fetchDepth: 0 });
+    expect(e.remoteArray).toEqual([['thing:1', 1]]);
+    expect(e.subqueryRemoteArray).toEqual([['child:c', 1]]);
+    expect(e.serverState).toBe('ready');
+    const req = out.log.find((x) => x.kind === 'remote.query') as any;
+    expect(req.sql.startsWith('fn::query::register($config);')).toBe(true);
+    expect(req.vars.config).toMatchObject({ surql: entry.def.surql, ttl: '10m' });
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }, { type: 'FetchRows' }, { type: 'SyncOutcome', ok: true }]);
+    expect(out.emitted).toContainEqual({ type: 'query:authority', hash: 'a', known: true });
+  });
+  it('guards: missing entry, already registered / failed, registering without retry', async () => {
+    const none = await runPure(registerRemote(env, 'zzz'), { state: buildState([]) });
+    expect(none.log.filter((x) => x.kind === 'remote.query')).toHaveLength(0);
+    for (const remote of ['registered', 'failed', 'registering'] as const) {
+      const out = await runPure(registerRemote(env, 'a'), { state: buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote } })]) });
+      expect(out.log.filter((x) => x.kind === 'remote.query')).toHaveLength(0);
+    }
+    const retry = await runPure(registerRemote(env, 'a', true), {
+      state: buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'registering' } })]),
+      handlers: { 'remote.query': happy, 'local.upsert': () => undefined },
+    });
+    expect(retry.state.queries.get('a')!.lifecycle.remote).toBe('registered');
+  });
+  it('materializing answer schedules the re-read ladder', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': () => [okStmt(null), okStmt([]), okStmt({ rowCount: 3, state: 'materializing' }), okStmt([])] },
+    });
+    expect(out.state.membershipDirty.has('a')).toBe(true);
+    expect(out.state.membershipReread.get('a')).toBe(1);
+    expect(out.timers.get('membership')).toEqual({ ms: 150, event: { type: 'ReadDirtyMembership' } });
+    expect(out.state.queries.get('a')!.lifecycle).toMatchObject({ phase: 'cold', remote: 'registered' });
+  });
+  it('errors: transport failure backs off, statement errors count as failures, budget exhausts to failed', async () => {
+    const boom = () => {
+      throw new Error('socket closed');
+    };
+    const first = await runPure(registerRemote(env, 'a'), { state: buildState([entry]), handlers: { 'remote.query': boom } });
+    expect(first.state.queries.get('a')!.lifecycle).toMatchObject({ remote: 'registering', fetchDepth: 0 });
+    expect(first.state.queries.get('a')!.registerAttempts).toBe(1);
+    expect(first.timers.get('register:a')).toEqual({ ms: 1000, event: { type: 'RegisterRemote', hash: 'a', retry: true } });
+    expect(first.dispatched).toContainEqual({ type: 'SyncOutcome', ok: false, error: new Error('socket closed') });
+    const errStmt = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': () => [{ status: 'ERR', error: 'denied' }] },
+    });
+    expect(errStmt.state.queries.get('a')!.registerAttempts).toBe(1);
+    const edgesErr = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': () => [okStmt(null), { status: 'ERR', error: 'no table' }, okStmt(null), okStmt(null)] },
+    });
+    expect(edgesErr.state.queries.get('a')!.registerAttempts).toBe(1);
+    const noArray = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: { 'remote.query': () => [okStmt(null), okStmt('nope'), okStmt(null), okStmt(null)] },
+    });
+    expect(noArray.state.queries.get('a')!.registerAttempts).toBe(1);
+    const empty = await runPure(registerRemote(env, 'a'), { state: buildState([entry]), handlers: { 'remote.query': () => [] } });
+    expect(empty.state.queries.get('a')!.registerAttempts).toBe(1);
+    const last = await runPure(registerRemote(env, 'a'), {
+      state: buildState([buildEntry({ def: { hash: 'a' }, registerAttempts: 2 })]),
+      handlers: { 'remote.query': boom },
+    });
+    expect(last.state.queries.get('a')!.lifecycle.remote).toBe('failed');
+    expect(last.timers.size).toBe(0);
+  });
+  it('tolerates ERR meta/children statements: edges still apply, missing meta reads as no row', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': () => [okStmt(null), okStmt([{ out: new RecordId('thing', '1'), version: 1 }]), { status: 'ERR', error: 'meta' }, { status: 'ERR', error: 'kids' }],
+        'local.upsert': () => undefined,
+      },
+    });
+    const e = out.state.queries.get('a')!;
+    expect(e.lifecycle).toMatchObject({ phase: 'live', remote: 'registered' });
+    expect(e.serverState).toBeNull();
+    expect(e.subqueryRemoteArray).toEqual([]);
+  });
+  it('stops when the entry disappears mid-flight', async () => {
+    const out = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': (_e, ctx) => {
+          ctx.state = R.removeQuery('a')(ctx.state);
+          return happy();
+        },
+      },
+    });
+    expect(out.state.queries.has('a')).toBe(false);
+    expect(out.dispatched).toEqual([]);
+    const gone = await runPure(registerRemote(env, 'a'), {
+      state: buildState([entry]),
+      handlers: {
+        'remote.query': (_e, ctx) => {
+          ctx.state = R.removeQuery('a')(ctx.state);
+          throw new Error('x');
+        },
+      },
+    });
+    expect(gone.dispatched).toEqual([]);
+  });
+});

package/src/query/register.saga.ts

@@ -0,0 +1,190 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { RecordId } from 'surrealdb';
+import type { QueryHash, QueryTimeToLive } from '../types';
+import type { Saga } from '../kernel/saga';
+import type { RegisterResult, StatementResult } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import { AUTH_READY_MAX_ATTEMPTS, AUTH_READY_RETRY_MS, REGISTER_MAX_RETRIES, backoffMs } from '../kernel/constants';
+import type { ClientState, QueryEntry } from '../state/client-state';
+import { emptyTelemetry } from '../state/client-state';
+import { seedLifecycle } from '../state/lifecycle';
+import * as R from '../state/reducers';
+import { desiredRegistrations } from '../state/selectors';
+import { parseDuration } from '../utils/index';
+import type { SagaEnv } from './env';
+import { listRefTable } from './env';
+import { queryHashInput, viewKeyInput } from './hash';
+import { isResolvedBefore, parseViewRow, snapshotFromSingle } from './membership';
+import { applyMembership, applySubqueryChildren } from './membership.saga';
+import * as sql from './sql';
+
+export interface RegisterInput {
+  tableName: string;
+  surql: string;
+  params: Record<string, unknown>;
+  ttl: QueryTimeToLive;
+  plan?: QueryPlan;
+}
+
+/**
+ * Register a query locally: compute its keys, read the durable `_00_view`
+ * row, build the SSP local view and publish the entry. Returns as soon as the
+ * entry exists (the first paint comes from `materialize`); the remote
+ * registration is dispatched, never awaited.
+ */
+export function* registerLocal(env: SagaEnv, input: RegisterInput): Saga<QueryHash> {
+  const sessionId = (yield fx.state.read((s) => s.sessionId)) as string | null;
+  const hash = (yield fx.hash(queryHashInput(input, sessionId))) as string;
+  const status = (yield fx.state.read((s) => (s.queries.has(hash) ? 'active' : s.registering.has(hash) ? 'pending' : 'new'))) as
+    | 'active'
+    | 'pending'
+    | 'new';
+  if (status === 'active') return hash;
+  if (status === 'pending') {
+    yield fx.state.wait((s) => !s.registering.has(hash));
+    return hash;
+  }
+  yield fx.state.update(R.beginRegistering(hash));
+  try {
+    const viewKey = (yield fx.hash(viewKeyInput(input))) as string;
+    let viewRow: unknown = null;
+    try {
+      viewRow = yield fx.local.getById(sql.VIEW_TABLE, sql.viewRecordId(viewKey));
+    } catch {
+      viewRow = null;
+    }
+    const view = parseViewRow(viewRow);
+    const now = (yield fx.now()) as number;
+    const reg = (yield fx.ssp.register({
+      queryHash: hash,
+      surql: input.surql,
+      params: input.params,
+      ttl: input.ttl,
+      tableName: input.tableName,
+    })) as RegisterResult;
+    const entry: QueryEntry = {
+      def: {
+        id: new RecordId('_00_query', hash),
+        hash,
+        viewKey,
+        surql: input.surql,
+        params: input.params,
+        plan: input.plan,
+        ttl: input.ttl,
+        ttlMs: parseDuration(input.ttl),
+        tableName: input.tableName,
+        createdAt: now,
+      },
+      lifecycle: seedLifecycle(isResolvedBefore(view)),
+      remoteArray: view?.ids ?? [],
+      localArray: reg.localArray,
+      subqueryRemoteArray: [],
+      records: [],
+      serverState: null,
+      subscribers: 0,
+      lastSubscriberLeftAt: now,
+      lastHeartbeatAt: null,
+      lastPolledAt: null,
+      registerAttempts: 0,
+      telemetry: { ...emptyTelemetry(), registrationTimings: reg.timings },
+    };
+    yield fx.state.update(R.putQuery(entry));
+    yield fx.dispatch({ type: 'EnsureRegistered' });
+    return hash;
+  } finally {
+    yield fx.state.update(R.endRegistering(hash));
+  }
+}
+
+/**
+ * Make the remote match the desired set: start a registration for every
+ * query that has none. Idempotent. With `requireAuth` (after a reconnect or
+ * while degraded) it first waits for `$auth.id` to be visible on the socket:
+ * a register issued before that stamps the view with an empty identity.
+ */
+export function* ensureRegistered(env: SagaEnv, opts: { requireAuth?: boolean; attempt?: number } = {}): Saga<void> {
+  const [hashes, userId] = (yield fx.state.read((s) => [desiredRegistrations(s), s.userId])) as [QueryHash[], string | null];
+  if (hashes.length === 0) return;
+  if (opts.requireAuth && userId !== null) {
+    let authed = false;
+    try {
+      const res = (yield fx.remote.query('RETURN $auth.id', undefined, env.remoteTimeoutMs)) as StatementResult[];
+      authed = res[0]?.status === 'OK' && res[0].result != null;
+    } catch {
+      authed = false;
+    }
+    if (!authed) {
+      const attempt = (opts.attempt ?? 0) + 1;
+      if (attempt >= AUTH_READY_MAX_ATTEMPTS) {
+        yield fx.emit({ type: 'log', level: 'warn', message: 'auth identity never became visible; not registering', data: { attempt } });
+        return;
+      }
+      yield fx.timer.set('ensure-registered', AUTH_READY_RETRY_MS, { type: 'EnsureRegistered', requireAuth: true, attempt });
+      return;
+    }
+  }
+  for (const hash of hashes) yield fx.dispatch({ type: 'RegisterRemote', hash });
+}
+
+const stmt = (results: StatementResult[], i: number): StatementResult | undefined => results[i];
+
+/**
+ * One remote registration: `fn::query::register` plus the edge/meta/children
+ * read in ONE request, then membership application. Concurrent with every
+ * other registration; retried on its own backoff; stops when the entry is
+ * gone.
+ */
+export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  const entry = state.queries.get(hash);
+  if (!entry) return;
+  const { remote } = entry.lifecycle;
+  if (remote === 'registered' || remote === 'failed' || (remote === 'registering' && !retry)) return;
+  yield fx.state.update(
+    R.compose(R.applyLifecycle(hash, { type: 'remote-registering' }), R.applyLifecycle(hash, { type: 'fetch-begin' }))
+  );
+  try {
+    const table = listRefTable(env, state);
+    const results = (yield fx.remote.query(
+      sql.registerSelect(table),
+      sql.registerVars({ id: entry.def.id, surql: entry.def.surql, params: { ...entry.def.params }, ttl: entry.def.ttl }),
+      env.remoteTimeoutMs
+    )) as StatementResult[];
+    const stillThere = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+    if (!stillThere) return;
+    const register = stmt(results, 0);
+    if (!register || register.status === 'ERR') throw new Error(register?.status === 'ERR' ? register.error : 'register returned nothing');
+    const edges = stmt(results, 1);
+    const meta = stmt(results, 2);
+    const children = stmt(results, 3);
+    const snap = snapshotFromSingle(
+      edges?.status === 'OK' ? (edges.result as never) : null,
+      meta?.status === 'OK' ? (meta.result as never) : null,
+      children?.status === 'OK' ? (children.result as never) : null
+    );
+    if (!snap) throw new Error(edges?.status === 'ERR' ? edges.error : 'edge read returned no array');
+    const outcome = yield* applyMembership(hash, snap.primary, snap.meta);
+    if (outcome === 'ignored' && snap.meta.present && snap.meta.state === 'materializing') {
+      yield fx.state.update(R.compose(R.markMembershipDirty([hash]), R.setMembershipReread(hash, 1)));
+      yield fx.timer.set('membership', 150, { type: 'ReadDirtyMembership' });
+    }
+    yield* applySubqueryChildren(hash, snap.subquery);
+    yield fx.state.update(R.compose(R.applyLifecycle(hash, { type: 'remote-registered' }), R.resetRegisterAttempts(hash)));
+    yield fx.dispatch({ type: 'SyncOutcome', ok: true });
+  } catch (error) {
+    const current = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+    if (!current) return;
+    const attempts = current.registerAttempts + 1;
+    yield fx.state.update(R.bumpRegisterAttempts(hash));
+    yield fx.emit({ type: 'log', level: 'warn', message: 'remote registration failed', data: { hash, attempts, error } });
+    yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+    if (attempts >= REGISTER_MAX_RETRIES) {
+      yield fx.state.update(R.applyLifecycle(hash, { type: 'remote-failed' }));
+    } else {
+      yield fx.timer.set(`register:${hash}`, backoffMs(attempts), { type: 'RegisterRemote', hash, retry: true });
+    }
+  } finally {
+    const stillThere = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+    if (stillThere) yield fx.state.update(R.applyLifecycle(hash, { type: 'fetch-end' }));
+  }
+}

package/src/query/render-set.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { buildRenderIds, resolveMembership } from './render-set';
+
+const ov = (writes: string[] = [], deletes: string[] = []) => ({ writes: new Set(writes), deletes: new Set(deletes) });
+
+describe('resolveMembership', () => {
+  it('cold scans, cold window uses the local view, anything else uses membership', () => {
+    const remoteArray: [string, number][] = [['t:1', 1]];
+    const localArray: [string, number][] = [['t:2', 1]];
+    expect(resolveMembership({ phase: 'cold', remoteArray, localArray, isWindow: false })).toBeNull();
+    expect(resolveMembership({ phase: 'cold', remoteArray, localArray, isWindow: true })).toBe(localArray);
+    expect(resolveMembership({ phase: 'cached', remoteArray, localArray, isWindow: false })).toBe(remoteArray);
+    expect(resolveMembership({ phase: 'view-lost', remoteArray, localArray, isWindow: true })).toBe(remoteArray);
+  });
+});
+
+describe('buildRenderIds', () => {
+  const opts = { hasExplicitOrder: false, isWindow: false };
+  it('membership minus deletes, sorted', () => {
+    expect(buildRenderIds([['t:b', 1], ['t:a', 1], ['t:c', 1]], [], ov([], ['t:c']), opts)).toEqual(['t:a', 't:b']);
+  });
+  it('adds pending writes the local view admits, never twice, never deleted', () => {
+    const ids = buildRenderIds(
+      [['t:1', 1]],
+      [['t:1', 1], ['t:2', 1], ['t:3', 1], ['t:4', 1]],
+      ov(['t:1', 't:2', 't:3', 't:9'], ['t:3']),
+      opts
+    );
+    expect(ids).toEqual(['t:1', 't:2']);
+  });
+  it('keeps server order for windows and explicit orderBy; dedupes membership', () => {
+    const m: [string, number][] = [['t:b', 1], ['t:a', 1], ['t:b', 1]];
+    expect(buildRenderIds(m, [], ov(), { hasExplicitOrder: true, isWindow: false })).toEqual(['t:b', 't:a']);
+    expect(buildRenderIds(m, [], ov(), { hasExplicitOrder: false, isWindow: true })).toEqual(['t:b', 't:a']);
+  });
+});