@spooky-sync/core 0.0.1-canary.331 → 0.0.1-canary.333

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/sync/live.saga.test.ts

@@ -6,6 +6,7 @@ import * as R from '../state/reducers';
 import { defaultEnv } from '../query/env';
 import { liveChange, liveInvalidate, liveStart } from './live.saga';
 import { rowOfEdge } from '../client/services';
+import { deltaOfEdge } from '../utils/edges';
 
 const env = defaultEnv({ tables: [] } as any);
 
@@ -176,3 +177,53 @@ describe('liveChange with the body joined on', () => {
     expect([...out.state.membershipDirty]).toEqual(['a']);
   });
 });
+
+describe('deltaOfEdge', () => {
+  const q = new RecordId('_00_query', 'a');
+  const rid = new RecordId('thread__crdt_log', 'x1');
+  it('reads a joining row off a CREATE or UPDATE, with or without the body joined on', () => {
+    expect(deltaOfEdge('CREATE', { in: q, out: rid, version: 2 })).toEqual({ hash: 'a', id: 'thread__crdt_log:x1', version: 2 });
+    expect(deltaOfEdge('UPDATE', { in: q, out: { id: rid, data: 'b' }, version: 3 })).toEqual({ hash: 'a', id: 'thread__crdt_log:x1', version: 3 });
+  });
+  it('leaves everything else to the re-read', () => {
+    // A row leaving, or a view's edges being rewritten.
+    expect(deltaOfEdge('DELETE', { in: q, out: rid, version: 2 })).toBeNull();
+    // A subquery child.
+    expect(deltaOfEdge('CREATE', { in: q, out: rid, version: 2, parent: new RecordId('thread', 't') })).toBeNull();
+    // Nothing to place: no version, no target, a target the session may not read, no query.
+    expect(deltaOfEdge('CREATE', { in: q, out: rid })).toBeNull();
+    expect(deltaOfEdge('CREATE', { in: q, out: null, version: 2 })).toBeNull();
+    expect(deltaOfEdge('CREATE', { in: q, out: 'thread__crdt_log:x1', version: 2 })).toBeNull();
+    expect(deltaOfEdge('CREATE', { out: rid, version: 2 })).toBeNull();
+  });
+});
+
+describe('liveChange with edge deltas', () => {
+  const live = (hash: string) =>
+    buildEntry({ def: { hash, viewKey: `vk-${hash}` }, lifecycle: { phase: 'live', remote: 'registered' }, remoteArray: [['t:1', 1]] });
+
+  it('commits a row joining a live view at once, with no re-read', async () => {
+    const out = await runPure(liveChange(env, ['a'], undefined, [{ hash: 'a', id: 't:2', version: 1 }]), {
+      state: { ...buildState([live('a')]), tabRole: 'leader' },
+      handlers: { 'local.upsert': () => undefined },
+    });
+    expect(out.state.queries.get('a')!.remoteArray).toEqual([['t:1', 1], ['t:2', 1]]);
+    expect(out.state.membershipDirty.size).toBe(0);
+    expect(out.timers.has('membership')).toBe(false);
+    // Other tabs still hear about it.
+    expect(out.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: ['a'] } });
+  });
+
+  it('re-reads what it could not settle, and ignores deltas for unknown queries', async () => {
+    const cold = buildEntry({ def: { hash: 'b' }, lifecycle: { phase: 'cold' } });
+    const out = await runPure(
+      liveChange(env, ['a', 'b'], undefined, [
+        { hash: 'b', id: 't:2', version: 1 },
+        { hash: 'zz', id: 't:9', version: 1 },
+      ]),
+      { state: buildState([live('a'), cold]) }
+    );
+    expect([...out.state.membershipDirty].sort()).toEqual(['a', 'b']);
+    expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
+  });
+});

package/src/sync/live.saga.ts

@@ -1,17 +1,18 @@
-import type { InlineRow, QueryHash } from '../types';
+import type { EdgeDelta, InlineRow, QueryHash } from '../types';
 import type { Saga } from '../kernel/saga';
 import { fx } from '../kernel/effects';
 import type { ClientState } from '../state/client-state';
 import * as R from '../state/reducers';
 import type { SagaEnv } from '../query/env';
 import { listRefTable } from '../query/env';
-import { markMembershipDirty } from '../query/membership.saga';
+import { applyEdgeDeltas, markMembershipDirty } from '../query/membership.saga';
 import { landChunk } from '../query/fetch.saga';
 
 /**
- * LIVE on the session's `_00_list_ref` table. An event marks its query's
- * membership dirty and the batched re-read decides; followers get the same
- * dirt relayed by the leader.
+ * LIVE on the session's `_00_list_ref` table. A row joining a live view is
+ * committed straight from its edge; any other event marks its query's
+ * membership dirty and the batched re-read decides. Followers get the dirt
+ * relayed by the leader.
  *
  * When the subscription was opened with the body joined on
  * (`liveInlineBodies`) the event ALSO carries the changed row. That is an
@@ -45,8 +46,12 @@ export function* liveInvalidate(): Saga<void> {
   yield fx.state.update(R.patchSync({ liveUuid: null, liveTable: null }));
 }
 
-/** One or more edges of these queries changed on the server. */
-export function* liveChange(env: SagaEnv, hashes: QueryHash[], rows?: InlineRow[]): Saga<void> {
+/**
+ * One or more edges of these queries changed on the server. A row joining a
+ * live view (`deltas`) is committed at once; anything else marks the query
+ * dirty for the batched re-read.
+ */
+export function* liveChange(env: SagaEnv, hashes: QueryHash[], rows?: InlineRow[], deltas?: EdgeDelta[]): Saga<void> {
   const [known, role, streak] = (yield fx.state.read((s) => [hashes.filter((h) => s.queries.has(h)), s.tabRole, s.sync.pollIdleStreak])) as [
     QueryHash[],
     ClientState['tabRole'],
@@ -73,7 +78,11 @@ export function* liveChange(env: SagaEnv, hashes: QueryHash[], rows?: InlineRow[
   // Before marking membership dirty: recording the version here is what makes
   // the re-read's `planFetch` find nothing left to pull for this row.
   if (rows && rows.length > 0) yield* landInlineRows(env, rows);
-  yield* markMembershipDirty(known);
+  // The edge says what a re-read would: commit it, and spare the round trip
+  // that used to sit between every remote edit and its render.
+  const settled = deltas && deltas.length > 0 ? yield* applyEdgeDeltas(deltas.filter((d) => known.includes(d.hash))) : new Set<QueryHash>();
+  const dirty = known.filter((h) => !settled.has(h));
+  if (dirty.length > 0) yield* markMembershipDirty(dirty);
   if (role === 'leader') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: known } });
 }
 

package/src/types.ts

@@ -258,14 +258,20 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    */
   streamDebounceTime?: number;
   /**
-   * Debounce time in milliseconds for syncing collaborative (CRDT) field
-   * edits to the server. Local state is kept on every change (so reload and
-   * offline work), but a field's own new ops go out as one edit-log row per
-   * pause of this length (at most 2 s apart while typing continues).
-   * Lower = snappier propagation and more rows; higher = fewer rows and more
-   * lag for other collaborators. Defaults to 300ms.
+   * How long in milliseconds the first edit to a collaborative (CRDT) field
+   * after a quiet spell waits before it goes out, so a burst of keystrokes
+   * travels as one edit-log row. Local state is kept on every change (so
+   * reload and offline work). Defaults to 50ms.
    */
   crdtDebounceMs?: number;
+  /**
+   * The shortest gap in milliseconds between two edit-log rows of one CRDT
+   * field: while someone keeps typing, their edits go out on this cadence
+   * instead of waiting for a pause. Lower = other collaborators see the text
+   * sooner and more rows are written; higher = fewer rows and more lag.
+   * Defaults to 200ms.
+   */
+  crdtSendIntervalMs?: number;
   /**
    * Enable collaborative CRDT fields. When `true`, the `loro-crdt` engine is
    * preloaded at client startup (fetched as a separate chunk on page load) so
@@ -299,15 +305,16 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * back for it.
    *
    * The client holds exactly one live subscription, on its `_00_list_ref`
-   * table, and today it is a doorbell: the notification is reduced to the
-   * query hash and the row is then pulled with `SELECT * FROM $ids`. The edge
+   * table. Without this, the notification names the row and the client then
+   * pulls it with `SELECT * FROM $ids`. The edge
    * is a real graph edge, so `FETCH out` makes SurrealDB resolve the row into
    * the notification and the body fetch disappears.
    *
    * The push stays advisory: the body is landed exactly the way a fetched body
    * is (store write, circuit ingest, version recorded), so a notification the
-   * server drops costs nothing but the old round trip. Membership is still
-   * read back; only the body fetch is saved.
+   * server drops costs nothing but the old round trip. A row joining a live
+   * view is committed to membership from the notification either way (no
+   * re-read); with this on, the body fetch is saved as well.
    *
    * Default `false`. The cost is wire bytes: one edit bumps the edge in every
    * view holding the row, and under `FETCH` each of those notifications
@@ -542,6 +549,18 @@ export interface InlineRow {
   record: Record<string, unknown>;
 }
 
+/**
+ * A row that joined a query's view, or moved to a newer version, as one LIVE
+ * notification on `_00_list_ref` reports it: the edge's `out` and `version`.
+ * The client commits it to the query's membership straight away instead of
+ * re-reading the edges (see `sync/live.saga.ts`).
+ */
+export interface EdgeDelta {
+  hash: QueryHash;
+  id: string;
+  version: number;
+}
+
 // Flat array format: [[record-id, version], [record-id, version], ...]
 export type RecordVersionArray = Array<[string, number]>;
 

package/src/utils/edges.ts

@@ -1,5 +1,5 @@
 import { RecordId } from 'surrealdb';
-import type { InlineRow } from '../types';
+import type { EdgeDelta, InlineRow } from '../types';
 import { encodeRecordId } from './index';
 
 /**
@@ -37,3 +37,21 @@ export function rowOfEdge(value: unknown): InlineRow | null {
   if (version === null) return null;
   return { id, version, record: out as Record<string, unknown> };
 }
+
+/**
+ * The membership change a `CREATE` or `UPDATE` notification reports: the
+ * edge's target joined the view (or its version moved). Null for anything a
+ * re-read must settle instead: a `DELETE` (a row leaving, or every edge of a
+ * view being rewritten), a subquery child (`parent` set), or an edge missing
+ * its target or version. With `FETCH out` the target is the joined row, whose
+ * `id` is the record id.
+ */
+export function deltaOfEdge(action: string, value: unknown): EdgeDelta | null {
+  if (action !== 'CREATE' && action !== 'UPDATE') return null;
+  const hash = hashOfEdge(value);
+  const edge = value as { out?: unknown; version?: unknown; parent?: unknown };
+  if (!hash || edge.parent != null || typeof edge.version !== 'number') return null;
+  const out = edge.out instanceof RecordId ? edge.out : (edge.out as { id?: unknown } | null | undefined)?.id;
+  if (!(out instanceof RecordId)) return null;
+  return { hash, id: encodeRecordId(out), version: edge.version };
+}

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');
+}