@spooky-sync/core 0.0.1-canary.13 → 0.0.1-canary.130

package/src/services/stream-processor/permissions.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { extractSelectPermissions } from './permissions';
+
+describe('extractSelectPermissions', () => {
+  it('maps a permissive multi-action table to true', () => {
+    const surql = `DEFINE TABLE game SCHEMAFULL
+      PERMISSIONS FOR select, create, update, delete WHERE true;`;
+    expect(extractSelectPermissions(surql)).toEqual({ game: 'true' });
+  });
+
+  it('handles FULL and NONE', () => {
+    const surql = `
+      DEFINE TABLE a PERMISSIONS FULL;
+      DEFINE TABLE b PERMISSIONS NONE;`;
+    expect(extractSelectPermissions(surql)).toEqual({ a: 'true', b: 'false' });
+  });
+
+  it('extracts the select predicate from multiple FOR groups', () => {
+    const surql = `DEFINE TABLE doc SCHEMAFULL
+      PERMISSIONS
+        FOR create, update, delete WHERE owner = $auth.id
+        FOR select WHERE owner = $auth.id OR public = true;`;
+    expect(extractSelectPermissions(surql)).toEqual({
+      doc: 'owner = $auth.id OR public = true',
+    });
+  });
+
+  it('returns false when permissions exist but none grant select', () => {
+    const surql = `DEFINE TABLE log PERMISSIONS FOR create WHERE true;`;
+    expect(extractSelectPermissions(surql)).toEqual({ log: 'false' });
+  });
+
+  it('treats a missing PERMISSIONS clause as default-deny', () => {
+    const surql = `DEFINE TABLE bare SCHEMALESS;`;
+    expect(extractSelectPermissions(surql)).toEqual({ bare: 'false' });
+  });
+
+  it('ignores commented-out clauses and handles OVERWRITE / IF NOT EXISTS', () => {
+    const surql = `
+      -- DEFINE TABLE ghost PERMISSIONS FULL;
+      DEFINE TABLE OVERWRITE u PERMISSIONS FOR select WHERE true;
+      DEFINE TABLE IF NOT EXISTS v PERMISSIONS FULL;`;
+    const perms = extractSelectPermissions(surql);
+    expect(perms).toEqual({ u: 'true', v: 'true' });
+    expect(perms.ghost).toBeUndefined();
+  });
+});

package/src/services/stream-processor/permissions.ts

@@ -0,0 +1,53 @@
+/**
+ * Extract per-table `select` permission predicates from a raw `.surql` schema.
+ *
+ * The in-browser SSP default-denies any non-`_00_` table that has no permission
+ * predicate registered (see `permission_inject::build_predicate`). The client
+ * already holds the full schema text (`config.schemaSurql`), so we parse each
+ * `DEFINE TABLE … PERMISSIONS …` clause and hand the `select` predicate to the
+ * processor via `set_permissions` at boot — mirroring the native path that
+ * seeds the same map from `INFO FOR DB`.
+ *
+ * Returns `{ [table]: whereText }` where `whereText` is the raw SurrealQL
+ * expression (`'true'` for `FULL`, `'false'` for `NONE` or a table with no
+ * `select` permission).
+ */
+export function extractSelectPermissions(schemaSurql: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!schemaSurql) return out;
+
+  // Drop line comments so a `--` comment can't contain a stray PERMISSIONS/FOR.
+  const cleaned = schemaSurql.replace(/--[^\n]*/g, '');
+
+  // One entry per `DEFINE TABLE … ;` statement.
+  const tableStmt = /DEFINE\s+TABLE\s+(?:OVERWRITE\s+|IF\s+NOT\s+EXISTS\s+)?([A-Za-z_][\w]*)\b([^;]*);/gi;
+  let m: RegExpExecArray | null;
+  while ((m = tableStmt.exec(cleaned)) !== null) {
+    const table = m[1];
+    const body = m[2];
+    out[table] = selectPredicateFromBody(body);
+  }
+  return out;
+}
+
+function selectPredicateFromBody(body: string): string {
+  const permIdx = body.search(/\bPERMISSIONS\b/i);
+  if (permIdx === -1) return 'false'; // no clause → SurrealDB default-deny
+  const perms = body.slice(permIdx + 'PERMISSIONS'.length).trim();
+
+  if (/^FULL\b/i.test(perms)) return 'true';
+  if (/^NONE\b/i.test(perms)) return 'false';
+
+  // `FOR <actions> WHERE <expr>` groups, possibly several. Split on the FOR
+  // boundary; the leading empty segment (before the first FOR) is ignored.
+  const groups = perms.split(/\bFOR\b/i).map((g) => g.trim()).filter(Boolean);
+  for (const group of groups) {
+    const where = group.search(/\bWHERE\b/i);
+    if (where === -1) continue;
+    const actions = group.slice(0, where).toLowerCase();
+    if (/\bselect\b/.test(actions)) {
+      return group.slice(where + 'WHERE'.length).trim();
+    }
+  }
+  return 'false'; // permissions present but none grant select
+}

package/src/services/stream-processor/stream-processor.batch.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { StreamProcessorService } from './index';
+import type { StreamUpdate, StreamUpdateReceiver } from './index';
+import type { WasmProcessor, WasmStreamUpdate } from './wasm-types';
+
+/**
+ * Tests for `ingestMany` bulk insert on StreamProcessorService.
+ *
+ * A batched ingest (e.g. sync fetching N missing records) used to emit one
+ * stream update per record, making the UI render row-by-row. ingestMany
+ * collapses those into a single coalesced update per affected query.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    trace: noop,
+  };
+  logger.child = () => logger;
+  return logger;
+}
+
+/** Records every dispatched update so we can count notifications. */
+class RecordingReceiver implements StreamUpdateReceiver {
+  public received: StreamUpdate[] = [];
+  onStreamUpdate(update: StreamUpdate): void {
+    this.received.push(update);
+  }
+}
+
+/**
+ * Build a service with a stubbed WASM processor. The processor accumulates
+ * ingested ids and returns the *full* materialized array on every call (as the
+ * real WASM does), so coalescing's last-write-wins must yield the final array.
+ */
+function makeService(queryHashesFor: (id: string) => string[]) {
+  const svc = new StreamProcessorService(
+    {} as any,
+    {} as any,
+    { get: async () => undefined, set: async () => {} } as any,
+    makeLogger()
+  );
+
+  const ingestedByQuery = new Map<string, Array<[string, number]>>();
+  const mockProcessor: Partial<WasmProcessor> = {
+    ingest: (_table, _op, id, record: any): WasmStreamUpdate[] => {
+      const version = record?._00_rv ?? 1;
+      const updates: WasmStreamUpdate[] = [];
+      for (const queryHash of queryHashesFor(id)) {
+        const arr = ingestedByQuery.get(queryHash) ?? [];
+        arr.push([id, version]);
+        ingestedByQuery.set(queryHash, arr);
+        updates.push({ query_id: queryHash, result_data: [...arr] });
+      }
+      return updates;
+    },
+  };
+  // processor is private and normally set by init() via WASM; inject the stub.
+  (svc as any).processor = mockProcessor;
+  return svc;
+}
+
+describe('StreamProcessor ingestMany bulk insert', () => {
+  let receiver: RecordingReceiver;
+
+  beforeEach(() => {
+    receiver = new RecordingReceiver();
+  });
+
+  it('emits one update per record when ingesting one-by-one (baseline)', () => {
+    const svc = makeService(() => ['q1']);
+    svc.addReceiver(receiver);
+
+    svc.ingest('user', 'CREATE', 'user:1', { id: 'user:1', _00_rv: 1 });
+    svc.ingest('user', 'CREATE', 'user:2', { id: 'user:2', _00_rv: 1 });
+    svc.ingest('user', 'CREATE', 'user:3', { id: 'user:3', _00_rv: 1 });
+
+    expect(receiver.received).toHaveLength(3);
+  });
+
+  it('coalesces a bulk insert into a single update per query with the final array', () => {
+    const svc = makeService(() => ['q1']);
+    svc.addReceiver(receiver);
+
+    svc.ingestMany([
+      { table: 'user', op: 'CREATE', id: 'user:1', record: { id: 'user:1', _00_rv: 1 } },
+      { table: 'user', op: 'CREATE', id: 'user:2', record: { id: 'user:2', _00_rv: 1 } },
+      { table: 'user', op: 'CREATE', id: 'user:3', record: { id: 'user:3', _00_rv: 1 } },
+    ]);
+
+    // Nothing dispatched until the whole batch is ingested, then exactly one
+    // coalesced update.
+    expect(receiver.received).toHaveLength(1);
+    const update = receiver.received[0];
+    expect(update.queryHash).toBe('q1');
+    // Last-write-wins carries the full materialized array (all 3 records).
+    expect(update.localArray).toHaveLength(3);
+    // Coalesced updates take DataModule's immediate (non-debounced) path.
+    expect(update.op).toBe('CREATE');
+    expect(typeof update.materializationTimeMs).toBe('number');
+  });
+
+  it('coalesces independently per affected query', () => {
+    // user:1 -> q1, user:2 -> q1 & q2, user:3 -> q2
+    const svc = makeService((id) =>
+      id === 'user:1' ? ['q1'] : id === 'user:2' ? ['q1', 'q2'] : ['q2']
+    );
+    svc.addReceiver(receiver);
+
+    svc.ingestMany([
+      { table: 'user', op: 'CREATE', id: 'user:1', record: { id: 'user:1', _00_rv: 1 } },
+      { table: 'user', op: 'CREATE', id: 'user:2', record: { id: 'user:2', _00_rv: 1 } },
+      { table: 'user', op: 'CREATE', id: 'user:3', record: { id: 'user:3', _00_rv: 1 } },
+    ]);
+
+    expect(receiver.received).toHaveLength(2);
+    const byHash = Object.fromEntries(receiver.received.map((u) => [u.queryHash, u]));
+    expect(Object.keys(byHash).sort()).toEqual(['q1', 'q2']);
+  });
+
+  it('is a no-op for an empty batch and leaves the window closed', () => {
+    const svc = makeService(() => ['q1']);
+    svc.addReceiver(receiver);
+
+    svc.ingestMany([]);
+
+    expect(receiver.received).toHaveLength(0);
+    // A subsequent single ingest dispatches normally (window never opened).
+    svc.ingest('user', 'CREATE', 'user:1', { id: 'user:1', _00_rv: 1 });
+    expect(receiver.received).toHaveLength(1);
+  });
+});

package/src/services/stream-processor/stream-processor.reset.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// `StreamProcessorService.reset()` is the SSP half of a local-bucket switch:
+// the old circuit holds the previous user's rows and views registered with the
+// previous `$auth`, so reset must swap in a FRESH processor (no state load),
+// and a `saveState` racing the reset must not persist the old circuit into the
+// new bucket's key.
+
+const processorInstances: any[] = [];
+
+vi.mock('@spooky-sync/ssp-wasm', () => ({
+  default: vi.fn(async () => {}),
+  Sp00kyProcessor: vi.fn(() => {
+    const instance = {
+      ingest: vi.fn(() => []),
+      register_view: vi.fn(() => ({ query_id: 'q1', result_data: [] })),
+      unregister_view: vi.fn(),
+      set_permissions: vi.fn(),
+      save_state: vi.fn(() => 'state-bytes'),
+      load_state: vi.fn(),
+    };
+    processorInstances.push(instance);
+    return instance;
+  }),
+}));
+
+import { StreamProcessorService } from './index';
+
+const silentLogger = {
+  child: () => silentLogger,
+  trace: () => {},
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as any;
+
+function makeService() {
+  const persisted: Record<string, unknown> = {};
+  const persistence = {
+    set: vi.fn(async (key: string, value: unknown) => {
+      persisted[key] = value;
+    }),
+    get: vi.fn(async () => null),
+    remove: vi.fn(async () => {}),
+  };
+  const service = new StreamProcessorService({} as any, {} as any, persistence as any, silentLogger);
+  return { service, persistence, persisted };
+}
+
+beforeEach(() => {
+  processorInstances.length = 0;
+});
+
+describe('StreamProcessorService.reset', () => {
+  it('swaps in a fresh processor without loading persisted state', async () => {
+    const { service } = makeService();
+    await service.init();
+    expect(processorInstances).toHaveLength(1);
+    const first = processorInstances[0];
+
+    await service.reset();
+    expect(processorInstances).toHaveLength(2);
+    const second = processorInstances[1];
+    // Fresh circuit: nothing loaded into it (a persisted snapshot references
+    // views under a dead sessionId salt and the previous user's data).
+    expect(second.load_state).not.toHaveBeenCalled();
+
+    // New registrations land on the fresh processor, not the old circuit.
+    service.registerQueryPlan({
+      queryHash: 'q1',
+      surql: 'SELECT * FROM thing;',
+      params: {},
+      ttl: '10m',
+      lastActiveAt: new Date(),
+      localArray: [],
+      remoteArray: [],
+      meta: { tableName: 'thing' },
+    } as any);
+    expect(second.register_view).toHaveBeenCalled();
+    expect(first.register_view).not.toHaveBeenCalled();
+  });
+
+  it('routes persisted state to the per-bucket key', async () => {
+    const { service, persistence } = makeService();
+    await service.init();
+    service.setStateKeySuffix('u1');
+    await service.saveState();
+    expect(persistence.set).toHaveBeenCalledWith('_00_stream_processor_state:u1', 'state-bytes');
+  });
+
+  it('drops a saveState that raced a reset (old circuit never persists into the new key)', async () => {
+    const { service, persistence } = makeService();
+    await service.init();
+    // The snapshot is taken, then a reset lands before the persist step —
+    // simulated by bumping the generation from inside save_state().
+    processorInstances[0].save_state.mockImplementation(() => {
+      void service.reset();
+      return 'stale-circuit';
+    });
+    await service.saveState();
+    expect(persistence.set).not.toHaveBeenCalled();
+  });
+});

package/src/services/stream-processor/stream-processor.test.ts

@@ -127,7 +127,7 @@ describe('StreamProcessor Ingest Behavior', () => {
     const params = { id: new MockRecordId('user', '2dng4ngbicbl0scod87i') };
     const normalizedParams = normalizeValue(params);
 
-    const ingestedRecord = {
+    const _ingestedRecord = {
       id: 'user:2dng4ngbicbl0scod87i',
       username: 'sara',
     };

package/src/services/stream-processor/wasm-types.ts

@@ -1,9 +1,17 @@
-import { RecordVersionArray } from '../../types';
+import type { RecordVersionArray } from '../../types';
 
 export interface WasmStreamUpdate {
   query_id: string;
   result_hash: string;
   result_data: RecordVersionArray; // Match Rust 'result_data' field
+  // Per-phase SSP processing time (ms). Ingest path: store_apply/circuit_step/
+  // transform. Register path: parse/plan/snapshot. Unused side is 0.
+  timing_store_apply_ms?: number;
+  timing_circuit_step_ms?: number;
+  timing_transform_ms?: number;
+  timing_parse_ms?: number;
+  timing_plan_ms?: number;
+  timing_snapshot_ms?: number;
 }
 
 export interface WasmQueryConfig {
@@ -23,9 +31,17 @@ export interface WasmIngestItem {
   version?: number;
 }
 
-// Interface matching the SpookyProcessor class from WASM
+// Interface matching the Sp00kyProcessor class from WASM
 export interface WasmProcessor {
   ingest(table: string, op: string, id: string, record: any): WasmStreamUpdate[];
   register_view(config: WasmQueryConfig): WasmStreamUpdate | undefined;
   unregister_view(id: string): void;
+  // Seed per-table `select` permission predicates ({ [table]: whereText }) so
+  // register_view can inject them instead of default-denying the table.
+  set_permissions(permissions: Record<string, string>): void;
+  // Persistence hooks: present on current WASM builds, absent on stale ones.
+  // Always guarded with `typeof x === 'function'` before calling so an older
+  // build degrades gracefully instead of throwing.
+  load_state?(state: string): void;
+  save_state?(): string;
 }

package/src/sp00ky.auth-order.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// Regression guard for the auth-callback ordering bug we fixed in
+// `Sp00kyClient.init()`. The contract:
+//
+//   this.auth.subscribe(async (userId) => {
+//     this.dataModule.setCurrentUserId(userId);   // ← must be first
+//     // ... awaits and other work ...
+//   });
+//
+// If any future refactor moves `setCurrentUserId` after the first
+// `await`, the AuthProvider's sibling subscriber gets to run with a
+// stale `dataModule.currentUserId` and registers queries against the
+// wrong `_00_query[_user_*]` / `_00_list_ref_user_<id>` tables.
+//
+// A runtime mock test for this is heavy — Sp00kyClient drags in
+// SurrealDB, the WASM SSP, the persistence client, etc. A
+// structural regex test is enough: it catches the only failure mode
+// (someone moves the synchronous setCurrentUserId call) without
+// needing the full graph.
+
+describe('Sp00kyClient.auth.subscribe ordering invariant', () => {
+  const sourcePath = resolve(__dirname, 'sp00ky.ts');
+  const source = readFileSync(sourcePath, 'utf-8');
+
+  it('source file is readable', () => {
+    expect(source.length).toBeGreaterThan(0);
+  });
+
+  it('auth.subscribe sets currentUserId before any await', () => {
+    // Find the auth.subscribe arrow body. Match the contents of the
+    // outermost `{}` after `this.auth.subscribe(async (userId) => `.
+    const match = source.match(
+      /this\.auth\.subscribe\(\s*async\s*\(\s*userId\s*[^)]*\)\s*=>\s*\{([\s\S]*?)\n {6}\}\s*\)/
+    );
+    expect(
+      match,
+      'expected an auth.subscribe(async (userId) => { ... }) block in sp00ky.ts'
+    ).not.toBeNull();
+
+    const body = match![1];
+
+    // Strip line comments so a stray `//` doesn't trick the regex.
+    const stripped = body
+      .split('\n')
+      .map((line) => line.replace(/\/\/.*$/, ''))
+      .join('\n');
+
+    const setUserIdIdx = stripped.indexOf('this.dataModule.setCurrentUserId(userId)');
+    expect(
+      setUserIdIdx,
+      'dataModule.setCurrentUserId(userId) must appear in the auth.subscribe body'
+    ).toBeGreaterThanOrEqual(0);
+
+    const firstAwaitIdx = stripped.search(/\bawait\b/);
+    if (firstAwaitIdx >= 0) {
+      expect(
+        setUserIdIdx,
+        `dataModule.setCurrentUserId(userId) (idx ${setUserIdIdx}) must come BEFORE the first \`await\` (idx ${firstAwaitIdx}) so the AuthProvider's sibling subscriber sees a fresh user id when it fires synchronously after our callback. Moving the call past an \`await\` reintroduces the stale-user-id race documented in docs/surrealdb-bugs/ if a related gap is found, and the prior session's retrospective.`
+      ).toBeLessThan(firstAwaitIdx);
+    }
+  });
+
+  it('writes the boot-bucket hint synchronously and switches buckets before sync.setCurrentUserId', () => {
+    const match = source.match(
+      /this\.auth\.subscribe\(\s*async\s*\(\s*userId\s*[^)]*\)\s*=>\s*\{([\s\S]*?)\n {6}\}\s*\)/
+    );
+    expect(match).not.toBeNull();
+    const stripped = match![1]
+      .split('\n')
+      .map((line) => line.replace(/\/\/.*$/, ''))
+      .join('\n');
+
+    const hintIdx = stripped.indexOf('writeBootBucketHint(');
+    const bucketIdx = stripped.indexOf('this.ensureLocalBucket(userId)');
+    const syncUserIdx = stripped.indexOf('this.sync.setCurrentUserId(userId)');
+    const firstAwaitIdx = stripped.search(/\bawait\b/);
+
+    // The hint must be written before the first await: a reload landing
+    // mid-switch has to boot straight into the target bucket.
+    expect(hintIdx, 'writeBootBucketHint must appear in the auth.subscribe body').toBeGreaterThanOrEqual(0);
+    expect(hintIdx, 'writeBootBucketHint must run before the first await').toBeLessThan(firstAwaitIdx);
+
+    // The bucket switch must complete before the sync module re-registers
+    // LIVE/poll for the new user — those immediately write to the local store.
+    expect(bucketIdx, 'ensureLocalBucket must appear in the auth.subscribe body').toBeGreaterThanOrEqual(0);
+    expect(syncUserIdx, 'sync.setCurrentUserId must appear in the auth.subscribe body').toBeGreaterThanOrEqual(0);
+    expect(bucketIdx, 'ensureLocalBucket must run before sync.setCurrentUserId').toBeLessThan(syncUserIdx);
+  });
+});

package/src/sp00ky.init-query.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Sp00kyClient } from './sp00ky';
+
+// Guards for the local-first paint contract of `Sp00kyClient.initQuery`:
+// the hash must resolve (and the hook paint from local cache) without any
+// network on the awaited path, while instant-hydrate + the `register`
+// down-event run in a background chain that (a) keeps hydrate strictly
+// before the enqueue, (b) skips the duplicate one-shot fetch for freshly
+// preloaded queries, (c) never rejects, and (d) is shared by concurrent
+// mounts of the same query.
+//
+// Structural half: like sp00ky.auth-order.test.ts, a regex over the source
+// catches the ordering regressions a runtime mock can't cheaply cover
+// (Sp00kyClient's constructor drags in SurrealDB + the WASM SSP).
+// Behavioral half: `finishQueryInit`/`initQuery` only touch a handful of
+// injected fields, so a bare `Object.create(Sp00kyClient.prototype)` with
+// stubs exercises the real method bodies without the constructor.
+
+describe('Sp00kyClient.initQuery structural invariants', () => {
+  const source = readFileSync(resolve(__dirname, 'sp00ky.ts'), 'utf-8');
+
+  const methodBody = (name: string): string => {
+    const match = source.match(new RegExp(`private async ${name}[\\s\\S]*?\\n  \\}`));
+    expect(match, `expected a "private async ${name}" method in sp00ky.ts`).not.toBeNull();
+    // Strip line comments so prose mentioning awaits/calls can't trip the checks.
+    return match![0]
+      .split('\n')
+      .map((line) => line.replace(/\/\/.*$/, ''))
+      .join('\n');
+  };
+
+  it('initQuery returns the hash with no network on the awaited path', () => {
+    const body = methodBody('initQuery');
+    expect(body).toContain('return hash');
+    expect(body, 'initQuery must not await the remote (paint path is network-free)').not.toMatch(
+      /await this\.remote\./
+    );
+    expect(body, 'the register enqueue belongs to the background chain').not.toMatch(
+      /await this\.sync\.enqueueDownEvent/
+    );
+  });
+
+  it('finishQueryInit hydrates strictly before enqueuing register', () => {
+    const body = methodBody('finishQueryInit');
+    const fetchIdx = body.indexOf('this.remote.query');
+    const enqueueIdx = body.indexOf('this.sync.enqueueDownEvent');
+    expect(fetchIdx).toBeGreaterThanOrEqual(0);
+    expect(enqueueIdx).toBeGreaterThanOrEqual(0);
+    expect(
+      fetchIdx,
+      'hydrate must settle before the register enqueue so a stale one-shot snapshot can never land after the authoritative _00_list_ref overwrite'
+    ).toBeLessThan(enqueueIdx);
+  });
+
+  it('finishQueryInit captures the bucket epoch before the remote fetch', () => {
+    const body = methodBody('finishQueryInit');
+    const epochIdx = body.indexOf('this.local.epoch');
+    const fetchIdx = body.indexOf('this.remote.query');
+    expect(epochIdx).toBeGreaterThanOrEqual(0);
+    expect(epochIdx, 'epoch must be read before the fetch to fence bucket switches').toBeLessThan(
+      fetchIdx
+    );
+  });
+});
+
+describe('Sp00kyClient.finishQueryInit behavior', () => {
+  const hash = 'sha-hash';
+  const q: any = { hash: 42, selectQuery: { query: 'SELECT * FROM user', vars: {} } };
+
+  let client: any;
+  let calls: string[];
+  let enqueued: any[];
+  let epoch: number;
+  let preloadFresh: boolean;
+  let cold: boolean;
+  let remoteImpl: () => Promise<any>;
+
+  beforeEach(() => {
+    calls = [];
+    enqueued = [];
+    epoch = 1;
+    preloadFresh = false;
+    cold = true;
+    remoteImpl = async () => {
+      calls.push('fetch');
+      return [[{ id: 'user:a' }]];
+    };
+
+    const noop = () => {};
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+
+    client = Object.create(Sp00kyClient.prototype);
+    Object.assign(client, {
+      config: { instantHydrate: true, schema: { tables: [{ name: 'user', columns: {} }] } },
+      logger,
+      preloadedHashes: new Set<number>(),
+      pendingQueryInits: new Map<string, Promise<void>>(),
+      local: {
+        get epoch() {
+          return epoch;
+        },
+      },
+      remote: { query: (...args: any[]) => remoteImpl() },
+      sync: {
+        enqueueDownEvent: (event: any) => {
+          calls.push('enqueue');
+          enqueued.push(event);
+        },
+      },
+      dataModule: {
+        isCold: () => cold,
+        isPreloadFresh: async () => preloadFresh,
+        applyHydration: async () => {
+          calls.push('hydrate');
+        },
+        query: async () => hash,
+      },
+    });
+  });
+
+  it('cold path: fetch → hydrate → enqueue, in order', async () => {
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(enqueued).toEqual([{ type: 'register', payload: { hash } }]);
+  });
+
+  it('session-preloaded query skips the fetch but still enqueues register', async () => {
+    client.preloadedHashes.add(q.hash);
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('fresh preload marker skips the fetch but still enqueues register', async () => {
+    preloadFresh = true;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('warm query (not cold) goes straight to enqueue', async () => {
+    cold = false;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('a rejected hydrate fetch still enqueues register and never rejects', async () => {
+    remoteImpl = async () => {
+      calls.push('fetch');
+      throw new Error('offline');
+    };
+    await expect(client.finishQueryInit(hash, q, {})).resolves.toBeUndefined();
+    expect(calls).toEqual(['fetch', 'enqueue']);
+  });
+
+  it('a bucket switch during the fetch skips applyHydration', async () => {
+    remoteImpl = async () => {
+      calls.push('fetch');
+      epoch = 2; // switch lands while the fetch is in flight
+      return [[{ id: 'user:a' }]];
+    };
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['fetch', 'enqueue']);
+  });
+
+  it('instantHydrate: false disables the hydrate fetch entirely', async () => {
+    client.config.instantHydrate = false;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('concurrent initQuery calls for the same hash share one background chain', async () => {
+    const [h1, h2] = await Promise.all([
+      client.initQuery('user', q, '10m'),
+      client.initQuery('user', q, '10m'),
+    ]);
+    expect(h1).toBe(hash);
+    expect(h2).toBe(hash);
+    // Let the shared chain drain.
+    await Promise.all([...client.pendingQueryInits.values()]);
+    expect(calls).toEqual(['fetch', 'hydrate', 'enqueue']);
+    expect(client.pendingQueryInits.size).toBe(0);
+  });
+});