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

package/src/query/id-set-plan.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest';
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { buildIdSetPlan, buildIdSetSurql, buildWindowMaterializationPlan } from './window-query';
+import { executeSelect, type SelectDb } from '../services/database/sqlite-select';
+import type { Row } from '../services/database/cache-engine';
+
+describe('buildWindowMaterializationPlan', () => {
+  it('returns null without an offset and an id-set plan with one', () => {
+    const plan: QueryPlan = { table: 't', where: [{ field: 'a', op: '=', value: 1 } as any], limit: 5 };
+    expect(buildWindowMaterializationPlan(plan, ['t:1'])).toBeNull();
+    expect(buildWindowMaterializationPlan({ ...plan, offset: 0 }, ['t:1'])).toBeNull();
+    const win = buildWindowMaterializationPlan({ ...plan, offset: 5 }, ['t:1']);
+    expect(win).toMatchObject({ ids: ['t:1'], where: undefined, limit: undefined, offset: undefined });
+  });
+});
+
+// `buildIdSetPlan` is what makes membership-authoritative rendering possible on
+// any local engine: it turns a query's plan into "these exact ids, ordered,
+// relations intact". Dropping `where` is the point — re-applying the predicate
+// against stale local bodies is what let removed rows keep rendering.
+
+const BASE: QueryPlan = {
+  table: 'thread',
+  where: [{ field: 'done', op: '=', value: false }],
+  limit: 50,
+  offset: 0,
+  orderBy: [['title', 'asc']],
+  relations: [
+    { alias: 'comments', table: 'comment', cardinality: 'many', foreignKeyField: 'thread' },
+  ],
+} as any;
+
+describe('buildIdSetPlan', () => {
+  it('binds the id-set and drops where/limit/offset, keeping orderBy + relations', () => {
+    const out = buildIdSetPlan(BASE, ['thread:A']);
+    expect(out.ids).toEqual(['thread:A']);
+    expect(out.where).toBeUndefined();
+    expect(out.limit).toBeUndefined();
+    expect(out.offset).toBeUndefined();
+    expect(out.orderBy).toEqual([['title', 'asc']]);
+    expect(out.relations).toEqual(BASE.relations);
+    expect(out.table).toBe('thread');
+  });
+
+  it('applies to non-offset plans, unlike the windowed-only helper', () => {
+    // The windowed helper deliberately bails so the old caller kept its scan;
+    // membership rendering needs the same rewrite for every query.
+    expect(buildWindowMaterializationPlan(BASE, ['thread:A'])).toBeNull();
+    expect(buildIdSetPlan(BASE, ['thread:A']).ids).toEqual(['thread:A']);
+  });
+
+  it('does not mutate the input plan', () => {
+    buildIdSetPlan(BASE, ['thread:A']);
+    expect(BASE.where).toEqual([{ field: 'done', op: '=', value: false }]);
+    expect(BASE.limit).toBe(50);
+  });
+});
+
+describe('buildIdSetSurql', () => {
+  it('rewrites a non-offset query to the id-set source, keeping ORDER BY', () => {
+    const out = buildIdSetSurql('SELECT * FROM thread WHERE done = false ORDER BY title ASC LIMIT 50;');
+    expect(out?.query).toBe('SELECT * FROM $__win ORDER BY title ASC');
+  });
+
+  it('preserves the projection', () => {
+    const out = buildIdSetSurql('SELECT id, title FROM thread WHERE done = false;');
+    expect(out?.query).toBe('SELECT id, title FROM $__win');
+  });
+
+  it('returns null when there is no top-level FROM to replace', () => {
+    expect(buildIdSetSurql('RETURN true;')).toBeNull();
+  });
+});
+
+// ---- Engine parity -------------------------------------------------------
+//
+// Both local engines short-circuit to `selectByIds` when `plan.ids` is set. This
+// pins that the id-set plan really does filter AND still resolves `.related()`
+// on the SQLite engine (the `where`-dropping path the SurrealDB engine shares).
+
+const FIXTURE: Record<string, Row[]> = {
+  thread: [
+    { id: 'thread:A', title: 'a thread', done: false },
+    { id: 'thread:B', title: 'b thread', done: false },
+  ],
+  comment: [
+    { id: 'comment:1', thread: 'thread:A', body: 'on A' },
+    { id: 'comment:2', thread: 'thread:B', body: 'on B' },
+  ],
+};
+
+function makeSelectDb(): SelectDb {
+  const respond = (sql: string, bind: unknown[] = []): { data: string }[] => {
+    const table = /FROM "([^"]+)"/.exec(sql)?.[1];
+    let rows = table ? (FIXTURE[table] ?? []) : [];
+    const rel = /WHERE json_extract\(data, '\$\.([A-Za-z0-9_.]+)'\) IN/.exec(sql);
+    if (rel) rows = rows.filter((r) => bind.includes(r[rel[1]]));
+    else if (/WHERE id IN/.test(sql)) rows = rows.filter((r) => bind.includes(r.id));
+    return rows.map((r) => ({ data: JSON.stringify(r) }));
+  };
+  return {
+    exec: (sql, bind) => respond(sql, bind ?? []),
+    run: () => {},
+    knownTables: new Set<string>(),
+  };
+}
+
+describe('id-set plan on the SQLite engine', () => {
+  it('returns only the id-set even though both bodies match the predicate', async () => {
+    const { rows } = await executeSelect(
+      buildIdSetPlan(BASE, ['thread:A']),
+      {},
+      makeSelectDb()
+    );
+    expect(rows.map((r) => r.id)).toEqual(['thread:A']);
+  });
+
+  it('still resolves .related() children for the id-set rows', async () => {
+    const { rows, relationFetches } = await executeSelect(
+      buildIdSetPlan(BASE, ['thread:A']),
+      {},
+      makeSelectDb()
+    );
+    expect(relationFetches).toBe(1);
+    expect((rows[0] as any).comments.map((c: Row) => c.id)).toEqual(['comment:1']);
+  });
+
+  it('renders nothing for an empty id-set (known-and-empty membership)', async () => {
+    const { rows } = await executeSelect(buildIdSetPlan(BASE, []), {}, makeSelectDb());
+    expect(rows).toEqual([]);
+  });
+});

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

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from './env';
+import { ackPrune, evictQuery, gcTick, lifecycleTick } from './lifecycle.saga';
+import type { StatementResult } from '../kernel/effects';
+
+const env = defaultEnv({ tables: [] } as any);
+const ok = (result: unknown): StatementResult => ({ status: 'OK', result });
+
+describe('lifecycleTick', () => {
+  it('evicts idle queries (even when the SSP unregister throws), heartbeats the registered rest, reschedules at half the shortest ttl', async () => {
+    const now = 1_700_000_000_000;
+    const s = buildState([
+      buildEntry({ def: { hash: 'idle', ttlMs: 100 }, lastSubscriberLeftAt: now - 200, lifecycle: { remote: 'registered' } }),
+      buildEntry({ def: { hash: 'idle2', ttlMs: 100 }, lastSubscriberLeftAt: now - 200 }),
+      buildEntry({ def: { hash: 'kept', ttlMs: 1000, id: new RecordId('_00_query', 'kept') }, subscribers: 1, lifecycle: { remote: 'registered' } }),
+      buildEntry({ def: { hash: 'unreg', ttlMs: 500 }, subscribers: 1 }),
+    ]);
+    let unregisters = 0;
+    const out = await runPure(lifecycleTick(env), {
+      state: s,
+      now,
+      handlers: {
+        'ssp.unregister': () => {
+          unregisters++;
+          if (unregisters === 1) throw new Error('gone');
+        },
+        'remote.query': (e: any) => {
+          expect(e.sql).toBe('fn::query::heartbeat($id0)');
+          expect(e.vars.id0).toEqual(new RecordId('_00_query', 'kept'));
+          return [ok([{ id: 'x' }])];
+        },
+      },
+    });
+    expect([...out.state.queries.keys()]).toEqual(['kept', 'unreg']);
+    expect(out.emitted.filter((e) => e.type === 'query:evicted')).toHaveLength(2);
+    expect(out.state.queries.get('kept')!.lastHeartbeatAt).toBe(now);
+    expect(out.dispatched).toEqual([{ type: 'SyncOutcome', ok: true }]);
+    expect(out.timers.get('lifecycle')).toEqual({ ms: 250, event: { type: 'LifecycleTick' } });
+  });
+  it('a reclaimed row drops the registration and re-registers; a failed beat reports; empty state uses the default ttl', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' }, subscribers: 1, lifecycle: { remote: 'registered' } })]);
+    const reclaimed = await runPure(lifecycleTick(env), { state: s, handlers: { 'remote.query': () => [ok([])] } });
+    expect(reclaimed.state.queries.get('a')!.lifecycle.remote).toBe('unregistered');
+    expect(reclaimed.dispatched).toEqual([{ type: 'EnsureRegistered' }, { type: 'SyncOutcome', ok: true }]);
+    const failed = await runPure(lifecycleTick(env), {
+      state: s,
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(failed.dispatched).toEqual([{ type: 'SyncOutcome', ok: false, error: new Error('offline') }]);
+    const empty = await runPure(lifecycleTick(env), { state: buildState() });
+    expect(empty.timers.get('lifecycle')!.ms).toBe(300_000);
+  });
+});
+
+describe('ackPrune', () => {
+  it('drops expired acked items and re-arms while some remain', async () => {
+    const now = 100_000;
+    const s = buildState([], R.outboxReplace([
+      buildOutboxItem({ id: 'old', status: 'acked', ackedAt: now - 31_000 }),
+      buildOutboxItem({ id: 'fresh', status: 'acked', ackedAt: now - 1000 }),
+    ]));
+    const out = await runPure(ackPrune(), { state: s, now });
+    expect(out.state.outbox.map((i) => i.id)).toEqual(['fresh']);
+    expect(out.timers.get('ack-prune')).toEqual({ ms: 30_000, event: { type: 'AckPrune' } });
+    const done = await runPure(ackPrune(), { state: out.state, now: now + 60_000 });
+    expect(done.timers.size).toBe(0);
+  });
+});
+
+describe('gcTick', () => {
+  it('deletes bodies no view names and no outbox item touches; keeps _00_ rows; reschedules', async () => {
+    const s = buildState(
+      [],
+      R.setVersions([['thing:keep', 1], ['thing:gone', 1], ['thing:pending', 1], ['_00_view:x', 1], ['thing:failed', 1]]),
+      R.outboxReplace([buildOutboxItem({ recordId: 'thing:pending' })])
+    );
+    const deleted: string[] = [];
+    const out = await runPure(gcTick(), {
+      state: s,
+      handlers: {
+        'local.query': () => [[{ ids: [['thing:keep', 1]] }, { ids: 'bad' }]],
+        'local.delete': (e: any) => {
+          deleted.push(e.id);
+          if (e.id === 'thing:failed') throw new Error('busy');
+        },
+        'ssp.ingest': () => undefined,
+      },
+    });
+    expect(deleted).toEqual(['thing:gone', 'thing:failed']);
+    expect([...out.state.versions.keys()]).toEqual(['thing:keep', 'thing:pending', '_00_view:x', 'thing:failed']);
+    const ingest = out.log.find((e) => e.kind === 'ssp.ingest') as any;
+    expect(ingest.records).toEqual([{ table: 'thing', op: 'DELETE', id: 'thing:gone', record: {} }]);
+    expect(out.timers.get('gc')!.event).toEqual({ type: 'GcTick' });
+    const failing = await runPure(gcTick(), {
+      state: s,
+      handlers: {
+        'local.query': () => {
+          throw new Error('no table');
+        },
+      },
+    });
+    expect(failing.emitted).toEqual([expect.objectContaining({ message: 'orphan gc failed' })]);
+    expect(failing.timers.has('gc')).toBe(true);
+    const nothing = await runPure(gcTick(), { state: buildState(), handlers: { 'local.query': () => [] } });
+    expect(nothing.log.filter((e) => e.kind === 'ssp.ingest')).toHaveLength(0);
+  });
+});
+
+describe('evictQuery', () => {
+  it('is a no-op for unknown hashes', async () => {
+    const out = await runPure(evictQuery('zz'), { state: buildState() });
+    expect(out.emitted).toEqual([]);
+  });
+});

package/src/query/lifecycle.saga.ts

@@ -0,0 +1,101 @@
+import type { Saga } from '../kernel/saga';
+import type { Settled, StatementResult } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import { ACK_GRACE_MS, GC_INTERVAL_MS, TTL_HEARTBEAT_FRACTION } from '../kernel/constants';
+import type { ClientState, QueryEntry } from '../state/client-state';
+import * as R from '../state/reducers';
+import { evictable, shortestTtlMs } from '../state/selectors';
+import type { SagaEnv } from './env';
+import * as sql from './sql';
+
+/**
+ * One tick for every query in state: evict the ones nobody has watched for a
+ * ttl, heartbeat the rest in one request, notice reclaimed rows. Reschedules
+ * itself at half the shortest ttl.
+ */
+export function* lifecycleTick(env: SagaEnv): Saga<void> {
+  const now = (yield fx.now()) as number;
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  for (const hash of evictable(state, now)) yield* evictQuery(hash);
+  const remaining = (yield fx.state.read((s) => [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered'))) as QueryEntry[];
+  if (remaining.length > 0) {
+    const beat = sql.heartbeatBatch(remaining.map((e) => e.def.id));
+    try {
+      const results = (yield fx.remote.query(beat.sql, beat.vars, env.remoteTimeoutMs)) as StatementResult[];
+      let reclaimed = 0;
+      for (let i = 0; i < remaining.length; i++) {
+        const r = results[i];
+        if (r?.status === 'OK' && sql.heartbeatRowGone(r.result)) {
+          reclaimed++;
+          yield fx.state.update(R.applyLifecycle(remaining[i].def.hash, { type: 'remote-dropped' }));
+        }
+      }
+      yield fx.state.update(R.stampHeartbeat(remaining.map((e) => e.def.hash), now));
+      if (reclaimed > 0) {
+        yield fx.emit({ type: 'log', level: 'warn', message: 'query rows reclaimed by the server; re-registering', data: { reclaimed } });
+        yield fx.dispatch({ type: 'EnsureRegistered' });
+      }
+      yield fx.dispatch({ type: 'SyncOutcome', ok: true });
+    } catch (error) {
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+    }
+  }
+  const ttl = (yield fx.state.read((s) => shortestTtlMs(s))) as number | null;
+  yield fx.timer.set('lifecycle', Math.floor((ttl ?? env.defaultTtlMs) * TTL_HEARTBEAT_FRACTION), { type: 'LifecycleTick' });
+}
+
+/** Free a query's local view and forget it. The server row expires by TTL. */
+export function* evictQuery(hash: string): Saga<void> {
+  const exists = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+  if (!exists) return;
+  try {
+    yield fx.ssp.unregister(hash);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'debug', message: 'unregister failed', data: { hash, error } });
+  }
+  yield fx.state.update(R.removeQuery(hash));
+  yield fx.emit({ type: 'query:evicted', hash });
+}
+
+/** Drop acked outbox items membership never named within the grace window. */
+export function* ackPrune(): Saga<void> {
+  const now = (yield fx.now()) as number;
+  yield fx.state.update(R.outboxPruneAcked(now, ACK_GRACE_MS));
+  const stillAcked = (yield fx.state.read((s) => s.outbox.some((i) => i.status === 'acked'))) as boolean;
+  if (stillAcked) yield fx.timer.set('ack-prune', ACK_GRACE_MS, { type: 'AckPrune' });
+}
+
+/**
+ * Weekly orphan collection: bodies the store holds that no `_00_view` row
+ * names and no outbox item touches are invisible; delete them in chunks.
+ */
+export function* gcTick(): Saga<void> {
+  try {
+    const views = (yield fx.local.query(`SELECT ids FROM ${sql.VIEW_TABLE}`)) as unknown[];
+    const rows = Array.isArray(views?.[0]) ? (views[0] as Array<{ ids?: unknown }>) : [];
+    const keep = new Set<string>();
+    for (const row of rows) {
+      if (!Array.isArray(row.ids)) continue;
+      for (const pair of row.ids as Array<[string, number]>) keep.add(pair[0]);
+    }
+    const state = (yield fx.state.read((s) => s)) as ClientState;
+    for (const item of state.outbox) keep.add(item.recordId);
+    const orphans = [...state.versions.keys()].filter((id) => !keep.has(id) && !id.startsWith('_00_'));
+    const deletes = orphans.map((id) => {
+      const table = id.slice(0, id.indexOf(':'));
+      return fx.local.delete(table, id);
+    });
+    for (let i = 0; i < deletes.length; i += 200) {
+      const settled = (yield fx.all(deletes.slice(i, i + 200))) as Settled[];
+      const done = orphans.slice(i, i + 200).filter((_, j) => settled[j].ok);
+      yield fx.state.update(R.deleteVersions(done));
+      if (done.length > 0) {
+        yield fx.ssp.ingest(done.map((id) => ({ table: id.slice(0, id.indexOf(':')), op: 'DELETE', id, record: {} })));
+      }
+    }
+    yield fx.emit({ type: 'log', level: 'info', message: 'orphan gc done', data: { removed: orphans.length } });
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'orphan gc failed', data: { error } });
+  }
+  yield fx.timer.set('gc', GC_INTERVAL_MS, { type: 'GcTick' });
+}

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

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { materialize, streamUpdate } from './materialize.saga';
+
+describe('materialize', () => {
+  const plan = { table: 'thing' } as any;
+  it('no entry: nothing', async () => {
+    const out = await runPure(materialize('zz'), { state: buildState() });
+    expect(out.log.filter((e) => e.kind !== 'state.read')).toHaveLength(0);
+  });
+  it('cold: predicate scan through the plan; rows land, dirt clears, subscribers hear once', async () => {
+    const s = R.markDirty(['a'])(buildState([buildEntry({ def: { hash: 'a', plan } })]));
+    const out = await runPure(materialize('a'), { state: s, handlers: { 'local.select': (e: any) => (e.plan.ids ? [] : [{ id: 'thing:1' }]) } });
+    const en = out.state.queries.get('a')!;
+    expect(en.records).toEqual([{ id: 'thing:1' }]);
+    expect(en.lifecycle.notified).toBe(true);
+    expect(en.telemetry.updateCount).toBe(1);
+    expect(en.telemetry.lastUpdatedAt).toBe(1_700_000_000_000);
+    expect(out.state.dirty.has('a')).toBe(false);
+    expect(out.emitted).toEqual([{ type: 'query:records', hash: 'a', records: [{ id: 'thing:1' }] }]);
+    const again = await runPure(materialize('a'), { state: out.state, handlers: { 'local.select': () => [{ id: 'thing:1' }] } });
+    expect(again.emitted).toEqual([]);
+    expect(again.state.queries.get('a')!.telemetry.updateCount).toBe(1);
+  });
+  it('cold window renders the SSP local window; live renders membership with the overlay', async () => {
+    const win = buildState([buildEntry({ def: { hash: 'w', plan: { ...plan, offset: 5 }, surql: 'SELECT * FROM thing LIMIT 5 START 5' }, localArray: [['thing:7', 1]] })]);
+    const w = await runPure(materialize('w'), { state: win, handlers: { 'local.select': (e: any) => e.plan.ids.map((id: any) => ({ id: `${id.table}:${id.id}` })) } });
+    expect(w.state.queries.get('w')!.records).toEqual([{ id: 'thing:7' }]);
+    const live = buildState(
+      [buildEntry({ def: { hash: 'a', plan }, lifecycle: { phase: 'live' }, remoteArray: [['thing:2', 1], ['thing:1', 1]], localArray: [['thing:9', 1]] })],
+      R.outboxReplace([buildOutboxItem({ id: 'c', type: 'create', recordId: 'thing:9' }), buildOutboxItem({ id: 'd', type: 'delete', recordId: 'thing:2' })])
+    );
+    const l = await runPure(materialize('a'), { state: live, handlers: { 'local.select': (e: any) => e.plan.ids.map((id: any) => ({ id: `${id.table}:${id.id}` })) } });
+    expect(l.state.queries.get('a')!.records).toEqual([{ id: 'thing:1' }, { id: 'thing:9' }]);
+    const ordered = buildState([buildEntry({ def: { hash: 'o', plan: { ...plan, orderBy: [['a', 'asc']] } }, lifecycle: { phase: 'live' }, remoteArray: [['thing:2', 1], ['thing:1', 1]] })]);
+    const o = await runPure(materialize('o'), { state: ordered, handlers: { 'local.select': (e: any) => e.plan.ids.map((id: any) => ({ id: `${id.table}:${id.id}` })) } });
+    expect(o.state.queries.get('o')!.records).toEqual([{ id: 'thing:2' }, { id: 'thing:1' }]);
+  });
+  it('a failing read counts an error and clears dirt; an entry removed mid-read is left alone', async () => {
+    const s = R.markDirty(['a'])(buildState([buildEntry({ def: { hash: 'a', plan } })]));
+    const fail = await runPure(materialize('a'), {
+      state: s,
+      handlers: {
+        'local.select': () => {
+          throw new Error('locked');
+        },
+      },
+    });
+    expect(fail.state.queries.get('a')!.telemetry.errorCount).toBe(1);
+    expect(fail.state.dirty.has('a')).toBe(false);
+    expect(fail.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
+    const gone = await runPure(materialize('a'), {
+      state: s,
+      handlers: {
+        'local.select': (_e, ctx) => {
+          ctx.state = R.removeQuery('a')(ctx.state);
+          return [];
+        },
+      },
+    });
+    expect(gone.emitted).toEqual([]);
+  });
+});
+
+describe('streamUpdate', () => {
+  it('takes the local id-set (dirtying the query) and records ingest timings; unknown hashes are ignored', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(streamUpdate({ queryHash: 'a', localArray: [['thing:1', 1]], op: 'CREATE', materializationTimeMs: 4, storeApplyMs: 1, circuitStepMs: 2 }), { state: s });
+    const en = out.state.queries.get('a')!;
+    expect(en.localArray).toEqual([['thing:1', 1]]);
+    expect(out.state.dirty.has('a')).toBe(true);
+    expect(en.telemetry.lastIngestLatencyMs).toBe(4);
+    expect(en.telemetry.materializationSamples).toEqual([4]);
+    expect(en.telemetry.phaseLast).toEqual({ sspStoreApply: 1, sspCircuitStep: 2 });
+    const bare = await runPure(streamUpdate({ queryHash: 'a', localArray: [] }), { state: s });
+    expect(bare.state.queries.get('a')!.telemetry.lastIngestLatencyMs).toBeNull();
+    const unknown = await runPure(streamUpdate({ queryHash: 'zz', localArray: [] }), { state: s });
+    expect(unknown.log.filter((e) => e.kind === 'state.update')).toHaveLength(0);
+  });
+});

package/src/query/materialize.saga.ts

@@ -0,0 +1,75 @@
+import type { QueryHash } from '../types';
+import type { StreamUpdate } from '../services/stream-processor/index';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import type { QueryEntry } from '../state/client-state';
+import * as R from '../state/reducers';
+import { overlay } from '../state/selectors';
+import type { Overlay } from '../state/selectors';
+import { isWindowed, materializeEffect, rowsEqual, rowsFromResult } from './materialize';
+import { buildRenderIds, resolveMembership } from './render-set';
+
+/**
+ * Render one query from state: membership (or a cold scan), the outbox
+ * overlay, one local read, then notify subscribers if the rows changed. The
+ * only writer of `records`. Runs on the `mat:<hash>` dedupe lane whenever the
+ * query is dirty.
+ */
+export function* materialize(hash: QueryHash): Saga<void> {
+  const [entry, ov] = (yield fx.state.read((s) => [s.queries.get(hash), overlay(s)])) as [QueryEntry | undefined, Overlay];
+  if (!entry) return;
+  const t0 = (yield fx.now()) as number;
+  const isWindow = isWindowed(entry.def.surql);
+  const membership = resolveMembership({
+    phase: entry.lifecycle.phase,
+    remoteArray: entry.remoteArray,
+    localArray: entry.localArray,
+    isWindow,
+  });
+  const ids = membership
+    ? buildRenderIds(membership, entry.localArray, ov, {
+        hasExplicitOrder: (entry.def.plan?.orderBy?.length ?? 0) > 0,
+        isWindow,
+      })
+    : null;
+  const effect = materializeEffect(entry.def, ids);
+  let rows: Record<string, unknown>[];
+  try {
+    rows = rowsFromResult(effect, yield effect);
+  } catch (error) {
+    yield fx.state.update(R.compose(R.recordError(hash), R.clearDirty(hash)));
+    yield fx.emit({ type: 'log', level: 'warn', message: 'materialize failed', data: { hash, error } });
+    return;
+  }
+  const current = (yield fx.state.read((s) => s.queries.get(hash))) as QueryEntry | undefined;
+  if (!current) return;
+  const t1 = (yield fx.now()) as number;
+  const changed = !rowsEqual(rows, current.records);
+  yield fx.state.update(
+    R.compose(R.setRecords(hash, rows, changed, t1 - t0), changed ? R.stampUpdated(hash, t1) : (s) => s)
+  );
+  if (changed) yield fx.emit({ type: 'query:records', hash, records: rows });
+}
+
+/**
+ * A view update from the in-browser SSP: the query's local id-set moved.
+ * State takes the array (which dirties the query); the ingest timings feed
+ * telemetry. Synthetic updates no longer exist: re-materialization is dirt.
+ */
+export function* streamUpdate(update: StreamUpdate): Saga<void> {
+  const hash = update.queryHash;
+  const exists = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
+  if (!exists) return;
+  const phases: Array<[string, number | undefined]> = [
+    ['sspStoreApply', update.storeApplyMs],
+    ['sspCircuitStep', update.circuitStepMs],
+    ['sspTransform', update.transformMs],
+  ];
+  yield fx.state.update(
+    R.compose(
+      R.setLocalArray(hash, update.localArray),
+      typeof update.materializationTimeMs === 'number' ? R.recordIngest(hash, update.materializationTimeMs) : (s) => s,
+      ...phases.filter((p): p is [string, number] => typeof p[1] === 'number').map(([phase, ms]) => R.recordPhase(hash, phase, ms))
+    )
+  );
+}

package/src/query/materialize.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { isWindowed, materializeEffect, rowsEqual, rowsFromResult } from './materialize';
+
+describe('materializeEffect', () => {
+  const plan = { table: 'thing', where: [{ field: 'a', op: '=', value: 1 }] } as any;
+  it('plan + ids: id-set plan select without where/limit/offset', () => {
+    const e = materializeEffect({ surql: 'SELECT * FROM thing', params: { a: 1 }, plan: { ...plan, limit: 5, offset: 2 } }, ['thing:1']);
+    expect(e.kind).toBe('local.select');
+    if (e.kind !== 'local.select') throw new Error();
+    expect(e.plan.ids).toEqual([new RecordId('thing', '1')]);
+    expect(e.plan.where).toBeUndefined();
+    expect(e.plan.limit).toBeUndefined();
+    expect(e.params).toEqual({ a: 1 });
+  });
+  it('surql + ids: id-set rewrite bound to __win; unparseable surql falls back to the raw query', () => {
+    const e = materializeEffect({ surql: 'SELECT * FROM thing WHERE a = $a ORDER BY b LIMIT 3', params: { a: 1 } }, ['thing:1']);
+    expect(e).toMatchObject({ kind: 'local.query', sql: 'SELECT * FROM $__win ORDER BY b' });
+    if (e.kind !== 'local.query') throw new Error();
+    expect(e.vars).toEqual({ a: 1, __win: [new RecordId('thing', '1')] });
+    const raw = materializeEffect({ surql: 'RETURN 1', params: {} }, ['thing:1']);
+    expect(raw).toMatchObject({ kind: 'local.query', sql: 'RETURN 1' });
+  });
+  it('null ids: predicate scan via plan or raw surql', () => {
+    expect(materializeEffect({ surql: 's', params: {}, plan }, null)).toMatchObject({ kind: 'local.select', plan });
+    expect(materializeEffect({ surql: 'SELECT * FROM thing', params: { x: 1 } }, null)).toMatchObject({
+      kind: 'local.query',
+      sql: 'SELECT * FROM thing',
+      vars: { x: 1 },
+    });
+  });
+  it('rowsFromResult reads both effect shapes; rowsEqual compares structurally', () => {
+    const sel = materializeEffect({ surql: 's', params: {}, plan }, null);
+    const q = materializeEffect({ surql: 'SELECT * FROM thing', params: {} }, null);
+    expect(rowsFromResult(sel, [{ id: 1 }])).toEqual([{ id: 1 }]);
+    expect(rowsFromResult(sel, undefined)).toEqual([]);
+    expect(rowsFromResult(q, [[{ id: 1 }]])).toEqual([{ id: 1 }]);
+    expect(rowsFromResult(q, [null])).toEqual([]);
+    expect(rowsFromResult(q, 'x')).toEqual([]);
+    const rows = [{ id: 1 }];
+    expect(rowsEqual(rows, rows)).toBe(true);
+    expect(rowsEqual(rows, [{ id: 1 }])).toBe(true);
+    expect(rowsEqual(rows, [{ id: 2 }])).toBe(false);
+    expect(rowsEqual(rows, [])).toBe(false);
+  });
+  it('isWindowed', () => {
+    expect(isWindowed('SELECT * FROM t LIMIT 10 START 10')).toBe(true);
+    expect(isWindowed('SELECT * FROM t LIMIT 10')).toBe(false);
+  });
+});

package/src/query/materialize.ts

@@ -0,0 +1,44 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import type { Effect } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import { parseRecordIdString } from '../utils/index';
+import { buildIdSetPlan, buildIdSetSurql, buildWindowMaterialization } from './window-query';
+
+export interface MaterializeSource {
+  surql: string;
+  params: Record<string, unknown>;
+  plan?: QueryPlan;
+}
+
+export const isWindowed = (surql: string): boolean => buildWindowMaterialization(surql) !== null;
+
+/**
+ * The one read that materializes a query. `ids` is the render set (membership
+ * with the overlay applied); `null` means "no membership yet, scan the local
+ * store with the query's own predicate".
+ */
+export function materializeEffect(src: MaterializeSource, ids: string[] | null): Effect {
+  if (ids !== null) {
+    const parsed = ids.map((id) => parseRecordIdString(id));
+    if (src.plan) return fx.local.select(buildIdSetPlan(src.plan, parsed), src.params);
+    const idSet = buildIdSetSurql(src.surql);
+    if (idSet) return fx.local.query(idSet.query, { ...src.params, __win: parsed });
+    return fx.local.query(src.surql, src.params);
+  }
+  if (src.plan) return fx.local.select(src.plan, src.params);
+  return fx.local.query(src.surql, src.params);
+}
+
+/** Rows out of either read effect's result. */
+export function rowsFromResult(effect: Effect, result: unknown): Record<string, unknown>[] {
+  if (effect.kind === 'local.select') return (result as Record<string, unknown>[] | undefined) ?? [];
+  const first = Array.isArray(result) ? result[0] : undefined;
+  return Array.isArray(first) ? (first as Record<string, unknown>[]) : [];
+}
+
+/** Cheap structural equality for the "did the rows change" check. */
+export function rowsEqual(a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}