@spooky-sync/client-solid2 0.0.1-canary.333 → 0.0.1-canary.334

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/client-solid2",
-  "version": "0.0.1-canary.333",
+  "version": "0.0.1-canary.334",
   "type": "module",
   "sideEffects": false,
   "description": "Solid 2 native bindings for the sp00ky sync client",
@@ -43,8 +43,8 @@
   },
   "packageManager": "pnpm@9.0.0",
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.333",
-    "@spooky-sync/core": "0.0.1-canary.333",
+    "@spooky-sync/query-builder": "0.0.1-canary.334",
+    "@spooky-sync/core": "0.0.1-canary.334",
     "@surrealdb/wasm": "^3.1.0",
     "surrealdb": "2.1.0"
   },

package/skills/sp00ky-solid2/SKILL.md

@@ -42,10 +42,10 @@ Returns `{ data, ready, error, isLoading, isFetching, isAuthoritative, hasData,
 - `data()` — non-suspending; `[]`/`null` before first result, keyed-reconciled live rows after.
 - `ready()` — suspending read for `<Loading fallback={...}>` (Solid 2's renamed Suspense).
 - `error()` — registration failure (SSP 503 NOT_READY etc.); never thrown into the tree, sync retries underneath.
-- `isAuthoritative()` — server membership known for this identity (latched until it changes).
+- `isAuthoritative()`: `data()` holds the rendered rows of a known membership (server answer, or a previous session's on this device); not before they are painted, e.g. right after sign-in. Latched until the identity changes.
 - `hasData()` — `data()` holds rows / the `.one()` row.
 - `isEmpty()` — authoritative AND no data: the server said "no rows". Empty states go on this, never on `!hasData()`.
-- `isSettled()` — authoritative AND not fetching; gate windowed-list end detection on this. Latch it for a sticky verdict.
+- `isSettled()`: authoritative AND not fetching; gate windowed-list end detection and create-if-missing on this (re-confirming a cached answer counts as fetching). Latch it for a sticky verdict.
 - Options: `enabled?: () => boolean`, `deregisterOnCleanup?: boolean`.
 - `useQuery` is a deprecated alias of `createQuery`.
 

package/src/lib/__tests__/create-query.rebind.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { createEffect, createRoot, flush } from 'solid-js';
+import { createQuery } from '../create-query';
+import { SyncedDb } from '../../index';
+// The real engine underneath, not a mock: the window this guards is the order
+// in which the core announces authority and rows, which a mock would script.
+import { Runtime } from '../../../../core/src/client/runtime';
+import { rebindQueries } from '../../../../core/src/boot/bucket-switch.saga';
+import { defaultEnv } from '../../../../core/src/query/env';
+import { fakeAdapters } from '../../../../core/src/testing/adapters';
+import { buildEntry, buildState } from '../../../../core/src/testing/build';
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+const settle = async () => {
+  await tick();
+  flush();
+  await tick();
+};
+
+const noop = () => {};
+const logger: any = {
+  debug: noop,
+  info: noop,
+  warn: noop,
+  trace: noop,
+  error: noop,
+  child: () => logger,
+};
+
+/** A core Runtime whose `_00_view` holds one row for query `q`, behind a SyncedDb. */
+function engine() {
+  const a = fakeAdapters({
+    local: {
+      getById: async () => ({ ids: [['thing:1', 1]], confirmed: true }),
+      select: async (plan: any) =>
+        (plan.ids ?? []).map((id: any) => ({ id: `${id.table}:${id.id}`, name: 'mine' })),
+    },
+  });
+  const rt = new Runtime({
+    env: defaultEnv({ tables: [] } as any, { materializeDebounceMs: 5 }),
+    adapters: a.adapters,
+    logger,
+    tabId: 'tab-a',
+    // Registered while still in the anon bucket: cold, nothing painted.
+    initialState: {
+      ...buildState([buildEntry({ def: { hash: 'q', plan: { table: 'thing' } as any } })]),
+      sessionId: 's',
+    },
+  });
+  const sp00ky = {
+    subscribe: async (
+      hash: string,
+      cb: (rows: Record<string, any>[]) => void,
+      o?: { immediate?: boolean }
+    ) => rt.subscribe(hash, cb, o),
+    subscribeQueryAuthority: (
+      hash: string,
+      cb: (known: boolean) => void,
+      o?: { immediate?: boolean }
+    ) => rt.subscribeAuthority(hash, cb, o),
+    subscribeQueryStatus: (hash: string, cb: (s: any) => void, o?: { immediate?: boolean }) =>
+      rt.subscribeStatus(hash, cb, o),
+    deregisterQuery: noop,
+    reportFrontendTiming: noop,
+  };
+  const db = Object.create(SyncedDb.prototype) as SyncedDb<any>;
+  (db as any).getSp00ky = () => sp00ky;
+  return { a, rt, db };
+}
+
+describe('createQuery across a bucket switch (sign-in)', () => {
+  it('never reads settled, authoritative or empty while the re-seeded rows are unpainted', async () => {
+    const { a, rt, db } = engine();
+    await createRoot(async (dispose) => {
+      const q = createQuery<any, any, any, any, false, any>(db, {
+        hash: 'q',
+        isOne: false,
+        run: async () => ({ hash: 'q' }),
+      } as any);
+      // Every state an effect could act on, e.g. "settled and no row: create one".
+      const seen: string[] = [];
+      createEffect(
+        () => ({
+          settled: q.isSettled(),
+          known: q.isAuthoritative(),
+          empty: q.isEmpty(),
+          rows: q.data().length,
+        }),
+        (v) =>
+          void seen.push(
+            `${v.settled ? 'settled' : '-'} ${v.known ? 'known' : '-'} ${v.empty ? 'empty' : '-'} ${v.rows}`
+          )
+      );
+      flush();
+      await settle();
+      expect(q.isLoading()).toBe(true);
+
+      // The AuthFlip's switch: re-seeded as `cached` from the user's durable
+      // view, `records` not painted, no fetch cycle in flight.
+      await rt.run(rebindQueries());
+      await settle();
+      expect(rt.state.queries.get('q')!.lifecycle).toMatchObject({
+        phase: 'cached',
+        fetchDepth: 0,
+      });
+      expect(q.isFetching()).toBe(false);
+      expect(q.data()).toEqual([]);
+      expect(q.isAuthoritative()).toBe(false);
+      expect(q.isSettled()).toBe(false);
+      expect(q.isEmpty()).toBe(false);
+      expect(q.isLoading()).toBe(true);
+
+      // The debounced render paints the durable rows; authority follows them.
+      a.timers.fire('mat:q');
+      await settle();
+      expect(q.data().map((r: any) => r.id)).toEqual(['thing:1']);
+      expect(q.isAuthoritative()).toBe(true);
+      expect(q.isSettled()).toBe(true);
+      expect(q.isEmpty()).toBe(false);
+
+      expect(seen.filter((s) => s.startsWith('settled') && s.endsWith(' 0'))).toEqual([]);
+      expect(seen.filter((s) => s.includes('empty'))).toEqual([]);
+      dispose();
+    });
+  });
+});

package/src/lib/create-query.ts

@@ -70,24 +70,31 @@ export type CreateQueryResult<TData> = {
   /** True while a fetch cycle is in flight (registration, a sync round). */
   isFetching: Accessor<boolean>;
   /**
-   * True once server membership is known for this identity: a registration or
-   * poll landed, or the durable membership of a previous session was read on
-   * boot. From then on `data()` is the server's answer, not a cache guess.
-   * Latched until the identity changes (or a bucket switch resets it).
+   * True once `data()` holds the rendered rows of a known membership for
+   * this identity: the server's answer (once its rows are local), or the
+   * membership an earlier session left on this device. Knowing the set is
+   * not enough: right after a sign-in re-seed, on boot, or while a server
+   * answer's rows still download, the set is known but `data()` is not
+   * painted yet, and this stays false. From then on `data()` is an answer, not
+   * a cache guess. Latched until the identity changes (or a bucket switch
+   * resets it).
    */
   isAuthoritative: Accessor<boolean>;
   /** Whether `data()` currently holds anything: rows for a list, a row for `one()`. */
   hasData: Accessor<boolean>;
   /**
-   * The server answered and the answer is "no rows". The signal to render an
+   * `isAuthoritative()` and the answer is "no rows". The signal to render an
    * empty state on; a bare `!hasData()` cannot tell empty from not-yet-loaded.
    */
   isEmpty: Accessor<boolean>;
   /**
-   * True once server membership is known AND no fetch cycle is in flight.
-   * While settled, results are authoritative: a windowed query returning fewer
-   * rows than its LIMIT really is the end of the list. Not monotonic: a later
-   * sync round re-enters `isFetching`; latch it if a verdict must stick.
+   * True once `isAuthoritative()` AND no fetch cycle is in flight. While
+   * settled, `data()` is the answer: a windowed query returning fewer rows
+   * than its LIMIT really is the end of the list, and a missing row is
+   * missing. The registration that re-confirms a cached answer after a reload
+   * or sign-in is a fetch cycle, so while it runs this waits for the server;
+   * with nothing in flight (offline) a cached answer settles. Not monotonic: a
+   * later sync round re-enters `isFetching`; latch it if a verdict must stick.
    */
   isSettled: Accessor<boolean>;
 };
@@ -252,25 +259,6 @@ export function createQuery<
             })
           );
 
-          // Mirror whether the server's membership is known. This is the
-          // channel that ends a cold load for a query whose honest answer is
-          // zero rows: the core emits no second `[]` for it, but it does flip
-          // authority once the registration (or a poll) has landed. A flip
-          // back to false is a bucket switch (a different principal), whose
-          // rebind also empties the rows, so the paint latch goes with it.
-          addCleanup(
-            sp00ky.subscribeQueryAuthority(
-              hash,
-              (known) => {
-                if (disposed || myRun !== runId) return;
-                setIsAuthoritative(known);
-                if (known) wakeReady();
-                else setHasPainted(false);
-              },
-              { immediate: true }
-            )
-          );
-
           addCleanup(
             sp00ky.subscribe(
               hash,
@@ -303,6 +291,29 @@ export function createQuery<
               { immediate: true }
             )
           );
+
+          // Mirror whether the rows of a known membership are painted. This
+          // is the channel that ends a cold load for a query whose honest
+          // answer is zero rows: the core emits no second `[]` for it, but it
+          // does flip authority once the render of the known set ran, always
+          // after the rows that render emitted, so `data()` is current when
+          // this reads true (subscribed after the rows so the immediate
+          // deliveries keep that order too). A flip back to false is a bucket
+          // switch (a different principal): what is on screen is the previous
+          // one's until the new store's render replaces it, so the paint
+          // latch goes with it.
+          addCleanup(
+            sp00ky.subscribeQueryAuthority(
+              hash,
+              (known) => {
+                if (disposed || myRun !== runId) return;
+                setIsAuthoritative(known);
+                if (known) wakeReady();
+                else setHasPainted(false);
+              },
+              { immediate: true }
+            )
+          );
         })
         .catch((err: unknown) => {
           if (disposed || myRun !== runId) return;