@spooky-sync/core 0.0.1-canary.332 → 0.0.1-canary.334

package/src/query/session-guard.integration.test.ts

@@ -0,0 +1,302 @@
+import { Socket } from 'node:net';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { RecordId, Surreal } from 'surrealdb';
+import { liveEndpoint } from '../live/index';
+import { isRefusedSessionError } from '../utils/error-classification';
+import { heartbeatBatch, heartbeatRowGone, queryRowCountSelect } from './sql';
+
+/**
+ * The app's session guard (`sessionGuard` in sp00ky.yml, the SESSION GUARD
+ * block of `meta_tables_remote.surql`) ends sync for a WebSocket that is still
+ * open. SurrealDB checks a token only when a socket authenticates, so before
+ * the guard a socket that authenticated before a password reset kept reading
+ * its user's edges, heartbeating its views and registering new ones until it
+ * happened to reconnect.
+ *
+ * Runs the shipped guard, `_00_query` and `_00_list_ref` blocks, the
+ * `fn::query::*` functions and the per-user edge-table rule ssp-node defines,
+ * against a real SurrealDB, because the guarantee is the engine's evaluation
+ * of those rules, LIVE notifications included. Boot one first, e.g.:
+ *   docker run -d --name spooky-surreal-it -p 18011:8000 \
+ *     surrealdb/surrealdb:v3.1.5 start --user root --pass root --allow-all memory
+ *
+ * Override the endpoint with SURREAL_IT_ENDPOINT. Skips if unreachable.
+ */
+const endpoint = liveEndpoint(process.env.SURREAL_IT_ENDPOINT ?? 'ws://127.0.0.1:18011');
+const NS = 'it';
+
+/** The guard WhitePawn ships: a password reset stamps `session_epoch`. */
+const GUARD = '$auth.session_epoch = NONE OR ($token.iat ?? 0) >= $auth.session_epoch';
+
+const repoFile = (path: string) =>
+  readFileSync(fileURLToPath(new URL(`../../../../${path}`, import.meta.url)), 'utf8');
+const cliSource = (file: string) => repoFile(`apps/cli/src/${file}`);
+
+function slice(src: string, from: string, to: string): string {
+  const start = src.indexOf(from);
+  const end = src.indexOf(to, start);
+  if (start < 0 || end < start) throw new Error(`block ${from} .. ${to} not found`);
+  return src.slice(start, end);
+}
+
+/**
+ * The SESSION GUARD block, with `expr` put in the way `spky migrate` does
+ * (`schema_builder::apply_session_guard`, whose marker is read from the Rust
+ * source so the two cannot drift).
+ */
+function guardSchema(expr?: string): string {
+  const block = slice(
+    cliSource('meta_tables_remote.surql'),
+    '-- SPOOKY SESSION GUARD',
+    '-- SPOOKY INCANTATION'
+  );
+  const m = /pub const SESSION_GUARD_DEFAULT: &str = "([^"]+)";/.exec(
+    repoFile('apps/cli/src/schema_builder.rs')
+  );
+  if (!m || !block.includes(m[1])) throw new Error('session guard marker not found');
+  return expr ? block.replace(m[1], `RETURN (${expr}) == true;`) : block;
+}
+
+/** Just the tables this test needs: the rest of the file needs modules. */
+const queryTableSchema = () =>
+  slice(
+    cliSource('meta_tables_remote.surql'),
+    'DEFINE TABLE OVERWRITE _00_query SCHEMALESS',
+    '-- SPOOKY LIST REF'
+  );
+const listRefSchema = () =>
+  slice(
+    cliSource('meta_tables_remote.surql'),
+    'DEFINE TABLE OVERWRITE _00_list_ref SCHEMALESS',
+    '-- SPOOKY STREAM PROCESSOR STATE'
+  );
+
+/** The rule ssp-node puts on `_00_list_ref_user_<uid>` (`user_list_ref_ddl` in tables.rs). */
+function userListRefTable(uid: string): string {
+  const m = /PERMISSIONS FOR select WHERE (\$auth\.id = user:\{uid\}[^,]*),/.exec(
+    repoFile('packages/ssp-node/src/tables.rs')
+  );
+  if (!m) throw new Error('per-user list_ref rule not found in ssp-node/src/tables.rs');
+  return `DEFINE TABLE OVERWRITE _00_list_ref_user_${uid} SCHEMALESS
+    PERMISSIONS FOR select WHERE ${m[1].replace('{uid}', uid)}, FOR create, update, delete WHERE false;`;
+}
+
+/** An app schema: a hidden `session_epoch` and an app table that asks the guard too. */
+const APP = `
+DEFINE TABLE OVERWRITE user SCHEMAFULL PERMISSIONS FOR select WHERE id = $auth.id;
+DEFINE FIELD OVERWRITE name ON TABLE user TYPE string;
+DEFINE FIELD OVERWRITE session_epoch ON TABLE user TYPE option<int>
+  PERMISSIONS FOR select WHERE false, FOR create, update WHERE false;
+DEFINE ACCESS OVERWRITE account ON DATABASE TYPE RECORD
+  SIGNUP (CREATE ONLY type::record('user', $name) SET name = $name)
+  SIGNIN (SELECT * FROM user WHERE name = $name)
+  DURATION FOR TOKEN 1h, FOR SESSION 1h;
+DEFINE TABLE OVERWRITE game SCHEMALESS
+  PERMISSIONS FOR select WHERE owner = $auth.id AND fn::sp00ky::session_live();
+CREATE game:1 SET owner = user:alice;
+`;
+
+/** What the SSP writes, as root, when a session registers a view (`node.rs`, cold path). */
+const SSP_REGISTER = `
+UPSERT $id SET clientId = $sid, auth_id = 'user:alice', surql = 'SELECT * FROM game',
+  params = { auth: { id: 'user:alice' }, access: 'account' }, ttl = 1h, lastActiveAt = time::now(),
+  rowCount = 1, state = 'ready',
+  subscribers = array::append(
+    array::filter(subscribers ?? [], |$s| <string>$s.id != $sid AND <datetime>$s.seenAt + 1h > time::now()),
+    { id: $sid, seenAt: time::now() })`;
+
+const viewId = () =>
+  new RecordId('_00_query', createHash('sha256').update(randomUUID()).digest('hex'));
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('session guard ends sync for an open socket (real SurrealDB)', () => {
+  let root: Surreal;
+  let database = '';
+  let reachable = false;
+  const open: Surreal[] = [];
+
+  beforeAll(async () => {
+    const url = new URL(endpoint);
+    reachable = await new Promise<boolean>((resolve) => {
+      const socket = new Socket();
+      const done = (ok: boolean) => {
+        socket.destroy();
+        resolve(ok);
+      };
+      socket.setTimeout(1_000, () => done(false));
+      socket.once('error', () => done(false));
+      socket.connect(Number(url.port || 80), url.hostname, () => done(true));
+    });
+  });
+
+  /** Root, a fresh database, the app and sp00ky's rules with `guard` in place. */
+  async function boot(guard?: string): Promise<void> {
+    database = `session_guard_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    root = new Surreal();
+    await root.connect(endpoint, { reconnect: false });
+    await root.signin({ username: 'root', password: 'root' });
+    await root.use({ namespace: NS, database });
+    await root.query(guardSchema(guard));
+    await root.query(APP);
+    await root.query(queryTableSchema());
+    await root.query(listRefSchema());
+    await root.query(userListRefTable('alice'));
+    await root.query(cliSource('functions_remote.surql'));
+    // The guard throws before the post; a live session's post fails on this
+    // closed port, which is not a refused session.
+    await root.query(
+      cliSource('functions_remote_singlenode.surql')
+        .replaceAll('{{ENDPOINT}}', 'http://127.0.0.1:9')
+        .replaceAll('{{SECRET}}', 'it-secret')
+    );
+  }
+
+  afterEach(async () => {
+    if (!reachable || !root) return;
+    for (const db of open.splice(0)) await db.close().catch(() => undefined);
+    await root.query(`REMOVE DATABASE ${database}`).catch(() => undefined);
+    await root.close();
+  });
+
+  /** Alice on a socket of her own, and that socket's `session::id()`. */
+  async function alice(how: 'signup' | 'signin'): Promise<[Surreal, string]> {
+    const db = new Surreal();
+    open.push(db);
+    await db.connect(endpoint, { reconnect: false });
+    await db.use({ namespace: NS, database });
+    await db[how]({ namespace: NS, database, access: 'account', variables: { name: 'alice' } });
+    const [sid] = (await db.query('RETURN <string>session::id()')) as [string];
+    return [db, sid];
+  }
+
+  /** What a password reset does: every token issued before now stops counting. */
+  async function resetPassword(stale: Surreal): Promise<void> {
+    const [iat] = (await stale.query('RETURN $token.iat')) as [number];
+    const epoch = iat + 1;
+    await root.query('UPDATE user:alice SET session_epoch = $epoch', { epoch });
+    // `iat` has second precision: the next sign-in must land at or past the epoch.
+    while (Date.now() / 1000 < epoch) await sleep(50);
+  }
+
+  /** LIVE on the per-user edge table; returns the notifications seen so far. */
+  async function watchEdges(db: Surreal): Promise<unknown[]> {
+    const seen: unknown[] = [];
+    const [id] = (await db.query('LIVE SELECT * FROM _00_list_ref_user_alice')) as [unknown];
+    const stream = await db.liveOf(id as never);
+    stream.subscribe((message: { action: string; value: unknown }) => {
+      if (message.action !== 'KILLED') seen.push(message.value);
+    });
+    return seen;
+  }
+
+  const edge = (n: number) =>
+    root.query(
+      `CREATE type::record('_00_list_ref_user_alice', $n) SET in = _00_query:q, out = game:1, version = $n`,
+      { n }
+    );
+
+  /** The client's register read-back, as `registerSelect` sends it. */
+  const readBack = async (db: Surreal, id: RecordId<string>) =>
+    ((await db.query(queryRowCountSelect(), { in: id })) as [unknown])[0] ?? null;
+
+  const heartbeatFound = async (db: Surreal, id: RecordId<string>) => {
+    const beat = heartbeatBatch([id]);
+    const [result] = (await db.query(beat.sql, beat.vars)) as [unknown];
+    return !heartbeatRowGone(result);
+  };
+
+  const registerError = async (db: Surreal): Promise<unknown> =>
+    db
+      .query('RETURN fn::query::register($config)', {
+        config: { id: viewId(), surql: 'SELECT * FROM game', params: {}, ttl: '1h' },
+      })
+      .then(
+        () => null,
+        (error: unknown) => error
+      );
+
+  it('a socket from before the reset stops receiving edges, a fresh sign-in keeps them', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale] = await alice('signup');
+    const staleSeen = await watchEdges(stale);
+    await edge(1);
+    await expect.poll(() => staleSeen.length).toBe(1);
+
+    await resetPassword(stale);
+    const [fresh] = await alice('signin');
+    const freshSeen = await watchEdges(fresh);
+    await edge(2);
+    await edge(3);
+
+    await expect.poll(() => freshSeen.length).toBe(2);
+    await sleep(200);
+    expect(staleSeen.length).toBe(1);
+  });
+
+  it('a socket from before the reset reads none of its user\'s edges, views or rows', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale, staleSid] = await alice('signup');
+    await edge(1);
+    await root.query(
+      `CREATE _00_list_ref:1 SET in = _00_query:q, out = game:1, clientId = 'x', auth_id = 'user:alice', version = 1`
+    );
+    await resetPassword(stale);
+    const [fresh, freshSid] = await alice('signin');
+    const q = viewId();
+    await root.query(SSP_REGISTER, { id: q, sid: staleSid });
+    await root.query(SSP_REGISTER, { id: q, sid: freshSid });
+
+    for (const table of ['_00_list_ref_user_alice', '_00_list_ref', 'game']) {
+      expect(await stale.query(`SELECT VALUE id FROM ${table}`), table).toEqual([[]]);
+      expect(((await fresh.query(`SELECT VALUE id FROM ${table}`)) as [unknown[]])[0], table).toHaveLength(1);
+    }
+    expect(await readBack(stale, q)).toBeNull();
+    expect(await heartbeatFound(stale, q)).toBe(false);
+    expect(await readBack(fresh, q)).toEqual({ rowCount: 1, state: 'ready' });
+    expect(await heartbeatFound(fresh, q)).toBe(true);
+  });
+
+  it('fn::query::register refuses the stale socket as a refused session, and only that one', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale] = await alice('signup');
+    expect(isRefusedSessionError(await registerError(stale))).toBe(false);
+
+    await resetPassword(stale);
+    const [fresh] = await alice('signin');
+
+    const refused = await registerError(stale);
+    expect(isRefusedSessionError(refused), String(refused)).toBe(true);
+    expect(isRefusedSessionError(await registerError(fresh))).toBe(false);
+  });
+
+  it('without a sessionGuard every session stays live, as before the guard', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot();
+    const [stale, staleSid] = await alice('signup');
+    await edge(1);
+    const q = viewId();
+    await root.query(SSP_REGISTER, { id: q, sid: staleSid });
+    await resetPassword(stale);
+
+    expect(((await stale.query('SELECT VALUE id FROM _00_list_ref_user_alice')) as [unknown[]])[0]).toHaveLength(1);
+    expect(await heartbeatFound(stale, q)).toBe(true);
+    expect(isRefusedSessionError(await registerError(stale))).toBe(false);
+  });
+
+  it('a database without the probe row lets every registration through', async (ctx) => {
+    if (!reachable) ctx.skip();
+    await boot(GUARD);
+    const [stale] = await alice('signup');
+    await resetPassword(stale);
+    await root.query('DELETE _00_session_guard:probe');
+
+    expect(isRefusedSessionError(await registerError(stale))).toBe(false);
+  });
+});

package/src/state/lifecycle.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { LifecycleEvent, QueryLifecycle, QueryPhase } from './lifecycle';
-import { deriveStatus, hasServerMembership, isAuthoritative, isForegroundFetching, LifecycleError, seedLifecycle, transition } from './lifecycle';
+import { deriveStatus, hasServerMembership, isAnswered, isAuthoritative, isForegroundFetching, LifecycleError, seedLifecycle, transition } from './lifecycle';
 
 const at = (phase: QueryPhase, over: Partial<QueryLifecycle> = {}): QueryLifecycle => ({
   phase,
@@ -8,6 +8,7 @@ const at = (phase: QueryPhase, over: Partial<QueryLifecycle> = {}): QueryLifecyc
   fetchDepth: 0,
   backgroundDepth: 0,
   notified: false,
+  answered: false,
   ...over,
 });
 
@@ -33,8 +34,48 @@ describe('transition table (phase axis)', () => {
     expect(transition(at('view-lost'), { type: 'row-missing' }).phase).toBe('view-lost');
   });
   it('bucket-switch reseeds and clears fetch depth', () => {
-    const l = transition(at('live', { fetchDepth: 3, notified: true }), { type: 'bucket-switch', resolvedBefore: true });
-    expect(l).toEqual({ phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false });
+    const l = transition(at('live', { fetchDepth: 3, notified: true, answered: true }), { type: 'bucket-switch', resolvedBefore: true });
+    expect(l).toEqual({ phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false, answered: false });
+  });
+});
+
+describe('answered', () => {
+  it('a seed is never answered, not even a cached one: its rows are not painted yet', () => {
+    expect(seedLifecycle(true)).toMatchObject({ phase: 'cached', answered: false });
+    expect(isAnswered(seedLifecycle(true))).toBe(false);
+    expect(isAuthoritative(seedLifecycle(true))).toBe(true);
+  });
+  it('only a render of a known membership answers; a cold render is a guess', () => {
+    expect(transition(at('cold'), { type: 'notified', answered: true }).answered).toBe(false);
+    expect(transition(at('cached'), { type: 'notified' }).answered).toBe(false);
+    expect(transition(at('cached'), { type: 'notified', answered: false })).toMatchObject({ notified: true, answered: false });
+    for (const p of ['cached', 'live', 'view-lost'] as const) {
+      expect(transition(at(p), { type: 'notified', answered: true })).toMatchObject({ notified: true, answered: true });
+    }
+  });
+  it('latched through membership, a reconnect and a lost view; cleared by a re-seed', () => {
+    let l = transition(at('cached'), { type: 'notified', answered: true });
+    l = transition(l, { type: 'membership-applied', present: true });
+    expect(l).toMatchObject({ phase: 'live', answered: true });
+    l = transition(l, { type: 'notified', answered: false });
+    expect(l.answered).toBe(true);
+    l = transition(l, { type: 'remote-dropped' });
+    expect(l).toMatchObject({ notified: false, answered: true });
+    l = transition(l, { type: 'row-missing' });
+    expect(l).toMatchObject({ phase: 'view-lost', answered: true });
+    expect(transition(l, { type: 'bucket-switch', resolvedBefore: true }).answered).toBe(false);
+    expect(transition(l, { type: 'seed', resolvedBefore: true }).answered).toBe(false);
+  });
+  it('a server set applied to a cold query is not an answer until its render', () => {
+    const l = transition(at('cold'), { type: 'membership-applied', present: true });
+    expect(l).toMatchObject({ phase: 'live', answered: false });
+    expect(isAuthoritative(l)).toBe(true);
+    expect(isAnswered(l)).toBe(false);
+  });
+  it('an unchanged notified keeps identity', () => {
+    const l = transition(at('live'), { type: 'notified', answered: true });
+    expect(transition(l, { type: 'notified', answered: true })).toBe(l);
+    expect(transition(l, { type: 'notified' })).toBe(l);
   });
 });
 
@@ -111,6 +152,7 @@ describe('invariants over random event sequences', () => {
     { type: 'fetch-begin', background: true },
     { type: 'fetch-end', background: true },
     { type: 'notified' },
+    { type: 'notified', answered: true },
     { type: 'bucket-switch', resolvedBefore: false },
     { type: 'seed', resolvedBefore: true },
   ];
@@ -135,6 +177,7 @@ describe('invariants over random event sequences', () => {
         expect(l.backgroundDepth).toBeLessThanOrEqual(l.fetchDepth);
         if (ev.type === 'row-missing' && before.phase === 'cold') expect(l.phase).toBe('cold');
         if (l.phase === 'view-lost') expect(before.phase).not.toBe('cold');
+        if (l.answered) expect(l.phase).not.toBe('cold');
       }
     }
   });

package/src/state/lifecycle.ts

@@ -15,6 +15,17 @@ import type { QueryStatus } from '../types';
  * behind `status: 'fetching'`, `notified` says whether subscribers received
  * at least one materialization this registration.
  *
+ * `answered` says subscribers have been handed the rows of a known membership
+ * (the server's, or the durable one of an earlier session) at least once:
+ * a materialization ran past `cold`, with no body of a server set still to
+ * download, and the membership it drew was still the one in state when it
+ * committed. Only a re-seed (a new entry, a bucket switch) clears it, so a
+ * reconnect or a lost view does not send a painted query back to loading.
+ * It is what the bindings' `isAuthoritative()` mirrors (see `isAnswered`):
+ * a `cached` seed or a freshly applied server set alone is not enough,
+ * because `records` is still empty (or stale) until `materialize` paints, and
+ * "known and empty" read in that beat made apps create rows that existed.
+ *
  * `backgroundDepth` is the part of `fetchDepth` that re-verifies rows the
  * query already shows: a registration of a query that is not `cold`. It still
  * holds `status: 'fetching'` (results are not yet confirmed), but it is not
@@ -29,6 +40,7 @@ export interface QueryLifecycle {
   readonly fetchDepth: number;
   readonly backgroundDepth: number;
   readonly notified: boolean;
+  readonly answered: boolean;
 }
 
 export type LifecycleEvent =
@@ -41,7 +53,7 @@ export type LifecycleEvent =
   | { type: 'remote-dropped' }
   | { type: 'fetch-begin'; background?: boolean }
   | { type: 'fetch-end'; background?: boolean }
-  | { type: 'notified' }
+  | { type: 'notified'; answered?: boolean }
   | { type: 'bucket-switch'; resolvedBefore: boolean };
 
 export class LifecycleError extends Error {
@@ -52,7 +64,14 @@ export class LifecycleError extends Error {
 }
 
 export function seedLifecycle(resolvedBefore: boolean): QueryLifecycle {
-  return { phase: resolvedBefore ? 'cached' : 'cold', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false };
+  return {
+    phase: resolvedBefore ? 'cached' : 'cold',
+    remote: 'unregistered',
+    fetchDepth: 0,
+    backgroundDepth: 0,
+    notified: false,
+    answered: false,
+  };
 }
 
 /** Total on every (lifecycle, event) pair the sagas can produce; throws on the rest. */
@@ -84,14 +103,23 @@ export function transition(l: QueryLifecycle, ev: LifecycleEvent): QueryLifecycl
       const backgroundDepth = Math.min(fetchDepth, l.backgroundDepth - (ev.background && l.backgroundDepth > 0 ? 1 : 0));
       return { ...l, fetchDepth, backgroundDepth };
     }
-    case 'notified':
-      return l.notified ? l : { ...l, notified: true };
+    case 'notified': {
+      // A cold render is a guess from the local store, never an answer.
+      const answered = l.answered || (ev.answered === true && l.phase !== 'cold');
+      return l.notified && answered === l.answered ? l : { ...l, notified: true, answered };
+    }
     case 'bucket-switch':
       return { ...seedLifecycle(ev.resolvedBefore), fetchDepth: 0 };
   }
 }
 
+/** Membership is known (server set or durable seed); its rows may not be painted yet. */
 export const isAuthoritative = (l: QueryLifecycle): boolean => l.phase !== 'cold';
+/**
+ * Subscribers hold the rows of a known membership: what the authority channel
+ * (`subscribeQueryAuthority`, the bindings' `isAuthoritative()`) reports.
+ */
+export const isAnswered = (l: QueryLifecycle): boolean => l.answered;
 export const hasServerMembership = (l: QueryLifecycle): boolean =>
   l.phase === 'live' || l.phase === 'view-lost';
 export const deriveStatus = (l: QueryLifecycle): QueryStatus => (l.fetchDepth > 0 ? 'fetching' : 'idle');

package/src/state/reducers.test.ts

@@ -79,6 +79,14 @@ describe('query reducers', () => {
     expect(s2.queries.get('a')!.telemetry.phaseSamples.localFetch).toEqual([12]);
   });
 
+  it('setRecords answers a query only when told to, and never a cold one', () => {
+    const cold = buildState([e('a')]);
+    expect(R.setRecords('a', [], false, null, true)(cold).queries.get('a')!.lifecycle.answered).toBe(false);
+    const cached = buildState([e('a', { lifecycle: { phase: 'cached' } })]);
+    expect(R.setRecords('a', [], false, null)(cached).queries.get('a')!.lifecycle).toMatchObject({ notified: true, answered: false });
+    expect(R.setRecords('a', [], false, null, true)(cached).queries.get('a')!.lifecycle).toMatchObject({ notified: true, answered: true });
+  });
+
   it('sample windows are capped', () => {
     let s = buildState([e('a')]);
     for (let i = 0; i < 105; i++) s = R.recordPhase('a', 'localFetch', i)(s);
@@ -249,12 +257,14 @@ describe('bucket switch reducers', () => {
       R.outboxReplace([buildOutboxItem()])
     );
     const id = { table: '_00_query', id: 'new' } as any;
-    const s1 = R.rebindQuery('a', { id, lifecycle: { phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false }, remoteArray: [['t:2', 1]], localArray: [] })({ ...s0, dirty: new Set() });
+    const s1 = R.rebindQuery('a', { id, lifecycle: { phase: 'cached', remote: 'unregistered', fetchDepth: 0, backgroundDepth: 0, notified: false, answered: false }, remoteArray: [['t:2', 1]], localArray: [] })({ ...s0, dirty: new Set() });
     const en = s1.queries.get('a')!;
     expect(en.def.id).toBe(id);
     expect(en.lifecycle.phase).toBe('cached');
     expect(en.remoteArray).toEqual([['t:2', 1]]);
-    expect(en.records).toEqual([]);
+    // What subscribers still hold: the next render diffs against it, so a new
+    // store that renders `[]` is a change they hear about.
+    expect(en.records).toEqual([{ id: 't:1' }]);
     expect(en.serverState).toBeNull();
     expect(en.registerAttempts).toBe(0);
     expect(s1.dirty.has('a')).toBe(true);

package/src/state/reducers.ts

@@ -153,8 +153,13 @@ export const setSubqueryRemoteArray =
     return withView(next, entry.def.viewKey, vouchedIds(entry.remoteArray, subqueryRemoteArray));
   };
 
+/**
+ * Commit a materialization. `answered`: it drew a known membership with no
+ * body still to download, and that membership is still current (see
+ * `QueryLifecycle`).
+ */
 export const setRecords =
-  (hash: QueryHash, records: ReadonlyArray<Row>, changed: boolean, materializeMs: number | null): Reducer =>
+  (hash: QueryHash, records: ReadonlyArray<Row>, changed: boolean, materializeMs: number | null, answered = false): Reducer =>
   (s) => {
     const next = withEntry(s, hash, (e) => {
       const prev = e.telemetry.phaseSamples.localFetch ?? [];
@@ -171,7 +176,7 @@ export const setRecords =
         ...e,
         records: changed ? records : e.records,
         telemetry,
-        lifecycle: transition(e.lifecycle, { type: 'notified' }),
+        lifecycle: transition(e.lifecycle, { type: 'notified', answered }),
       };
     });
     return next === s ? s : { ...next, dirty: withoutAll(next.dirty, [hash]) };
@@ -454,7 +459,13 @@ export const setIdentity =
   ): Reducer =>
   (s) => ({ ...s, ...patch });
 
-/** Re-home a query after a bucket switch: new store, same hash, fresh sync state. */
+/**
+ * Re-home a query after a bucket switch: new store, same hash, fresh sync state.
+ * `records` is kept: it is what subscribers were last handed, and the next
+ * render diffs against it. Blanking it here (without telling anyone) let a
+ * new store that renders `[]` read as unchanged, so the previous principal's
+ * rows stayed on screen under an authority flip that vouched for them.
+ */
 export const rebindQuery =
   (
     hash: QueryHash,
@@ -468,7 +479,6 @@ export const rebindQuery =
       remoteArray: next.remoteArray,
       localArray: next.localArray,
       subqueryRemoteArray: [],
-      records: [],
       serverState: null,
       lastHeartbeatAt: null,
       lastPolledAt: null,

package/src/state/selectors.ts

@@ -217,6 +217,7 @@ export function toQueryState(e: QueryEntry): QueryState {
     viewLost: l.phase === 'view-lost',
     serverState: e.serverState,
     syncNotified: l.notified,
+    answered: l.answered,
     ttlTimer: null,
     ttlDurationMs: e.def.ttlMs,
     lastHeartbeatAt: e.lastHeartbeatAt ?? undefined,

package/src/types.ts

@@ -706,6 +706,12 @@ export interface QueryState {
    * always emits at least once even when its records are unchanged — otherwise
    * an empty re-registered window would never notify and stay "loading". */
   syncNotified?: boolean;
+  /**
+   * Subscribers hold the rows of a known membership (see `QueryLifecycle`'s
+   * `answered`): what the authority channel and the bindings'
+   * `isAuthoritative()` report. Ephemeral.
+   */
+  answered?: boolean;
   /** Timer for TTL expiration. */
   ttlTimer: NodeJS.Timeout | null;
   /** TTL duration in milliseconds. */
@@ -798,9 +804,12 @@ export interface QueryTimings {
 export type QueryUpdateCallback = (records: Record<string, any>[]) => void;
 export type QueryStatusCallback = (status: QueryStatus) => void;
 /**
- * Observer for a query's authority flips: `true` once server membership is
- * known for it (registration, poll, durable seed), `false` when it is reset
- * (bucket switch). What the bindings' `isAuthoritative()` mirrors.
+ * Observer for a query's authority flips: `true` once subscribers hold the
+ * rendered rows of a known membership (a server answer whose bodies are
+ * local, or the durable membership of an earlier session), delivered after
+ * the rows that vouch for it; `false` when it is reset (bucket switch). Knowing the set is
+ * not enough: a `cached` re-seed or a just-applied server set has no rows
+ * painted yet. What the bindings' `isAuthoritative()` mirrors.
  */
 export type QueryAuthorityCallback = (known: boolean) => void;
 export type MutationCallback = (mutations: MutationEvent[]) => void;

package/src/utils/error-classification.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { classifySyncError } from './error-classification';
+import { classifySyncError, isRefusedSessionError } from './error-classification';
 
 describe('classifySyncError', () => {
   it('classifies surreal ConnectionUnavailableError as network', () => {
@@ -52,3 +52,21 @@ describe('classifySyncError', () => {
     expect(classifySyncError('boom')).toBe('application');
   });
 });
+
+describe('isRefusedSessionError', () => {
+  it.each([
+    'There was a problem with authentication',
+    'An error occurred: There was a problem with authentication: this session has ended, sign in again',
+    'The session has expired',
+  ])('takes %j as a refused session', (message) => {
+    expect(isRefusedSessionError(new Error(message))).toBe(true);
+  });
+
+  it.each([
+    'There was a problem with the database: Invalid token',
+    'There was a problem with the underlying connection',
+    'Permission denied',
+  ])('does not take %j as one', (message) => {
+    expect(isRefusedSessionError(new Error(message))).toBe(false);
+  });
+});

package/src/utils/error-classification.ts

@@ -51,3 +51,15 @@ export function classifySyncError(error: unknown): 'network' | 'application' {
 
   return 'application';
 }
+
+/**
+ * Whether the server refused the SESSION rather than the statement: its own
+ * wording for a token it will not accept ("There was a problem with
+ * authentication"), which is also what an app's AUTHENTICATE clause and
+ * sp00ky's session guard throw, and a session past its `DURATION FOR SESSION`.
+ */
+export function isRefusedSessionError(error: unknown): boolean {
+  const message =
+    error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  return message.includes('problem with authentication') || message.includes('session has expired');
+}