@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

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,183 @@
+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 the opt-in instant-hydrate + the
+// `register` down-event run in a background chain that (a) keeps hydrate
+// strictly before the enqueue, (b) hydrates only when `instantHydrate:
+// true` (default off — the register lifecycle is the single freshness
+// path), (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 cold: boolean;
+  let remoteImpl: () => Promise<any>;
+
+  beforeEach(() => {
+    calls = [];
+    enqueued = [];
+    epoch = 1;
+    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,
+        applyHydration: async () => {
+          calls.push('hydrate');
+        },
+        query: async () => hash,
+      },
+    });
+  });
+
+  it('cold path with hydrate enabled: 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('a preloaded query still hydrates when enabled — cache-first never depends on WHY rows are cached', async () => {
+    client.preloadedHashes.add(q.hash);
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['fetch', 'hydrate', '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('default (instantHydrate unset) does not hydrate — register lifecycle is the only freshness path', async () => {
+    delete client.config.instantHydrate;
+    await client.finishQueryInit(hash, q, {});
+    expect(calls).toEqual(['enqueue']);
+  });
+
+  it('instantHydrate: false does not hydrate', 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);
+  });
+});

package/src/sp00ky.local-first.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Structural guard, in the spirit of sp00ky.init-query.test.ts: the paint path
+// must stay network-free. `init()` resolves as soon as the LOCAL store is
+// usable, and every consumer gates its first render on that, so anything that
+// reaches the network belongs in `initRemote()` instead.
+//
+// This is the invariant that makes a warm reload instant and an offline boot
+// possible at all. It is easy to undo by adding one innocent-looking `await`,
+// hence a test rather than a comment.
+const source = readFileSync(join(__dirname, 'sp00ky.ts'), 'utf8');
+
+function methodBody(name: string): string {
+  const re = new RegExp(`(?:private )?async ${name}\\([^)]*\\)[^{]*\\{[\\s\\S]*?\\n  \\}`);
+  const m = re.exec(source);
+  if (!m) throw new Error(`could not locate ${name}()`);
+  return m[0];
+}
+
+describe('local-first boot', () => {
+  const init = methodBody('init');
+
+  it('init() never awaits the remote', () => {
+    expect(init).not.toMatch(/await this\.remote\./);
+    expect(init).not.toMatch(/await this\.auth\.init\(\)/);
+  });
+
+  it('init() hands the network half off without awaiting it', () => {
+    expect(init).toMatch(/void this\.initRemote\(\)/);
+  });
+
+  it('init() restores the session locally and marks the client ready', () => {
+    expect(init).toMatch(/await this\.auth\.restoreSessionFromToken\(\)/);
+    expect(init).toMatch(/this\.localReady = true/);
+  });
+
+  it('the query-id salt is minted locally, not fetched from the server', () => {
+    // No remaining CALL - the surviving mentions are comments explaining why.
+    expect(source).not.toMatch(/query[^\n]*RETURN <string>session::id\(\)/);
+    expect(init).toMatch(/this\.mintSessionSalt\(\)/);
+  });
+
+  it('permissions are seeded before anything can register a view', () => {
+    const perms = init.indexOf('setPermissions(');
+    const restore = init.indexOf('restoreSessionFromToken');
+    expect(perms).toBeGreaterThan(-1);
+    expect(perms).toBeLessThan(restore);
+  });
+
+  it('initRemote() tolerates an unreachable server and still supervises', () => {
+    const remote = methodBody('initRemote');
+    // connect is wrapped, not fatal
+    expect(remote).toMatch(/try\s*\{[\s\S]*await this\.remote\.connect\(\)[\s\S]*\}\s*catch/);
+    // and the supervisor starts regardless, or a boot-time failure never heals
+    const connectCatchEnd = remote.indexOf('connectionSupervisor.start()');
+    expect(connectCatchEnd).toBeGreaterThan(-1);
+  });
+});