@spooky-sync/core 0.0.1-canary.7 → 0.0.1-canary.70

package/src/modules/data/window-query.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { buildWindowMaterialization } from './window-query';
+
+describe('buildWindowMaterialization', () => {
+  it('rewrites the game-list window query (START 30) to select the id-set, keeping ORDER BY', () => {
+    const surql =
+      'SELECT * FROM game WHERE database = $database ORDER BY sort_index asc, date desc LIMIT 30 START 30;';
+    const r = buildWindowMaterialization(surql);
+    expect(r).not.toBeNull();
+    expect(r!.query).toBe('SELECT * FROM $__win ORDER BY sort_index asc, date desc');
+  });
+
+  it('returns null for START 0 (offset-free windows still work via the normal re-query)', () => {
+    const surql =
+      'SELECT * FROM game WHERE database = $database ORDER BY sort_index asc, date desc LIMIT 30 START 0;';
+    expect(buildWindowMaterialization(surql)).toBeNull();
+  });
+
+  it('returns null when there is no START clause', () => {
+    expect(
+      buildWindowMaterialization('SELECT * FROM game WHERE database = $database LIMIT 30;')
+    ).toBeNull();
+    expect(buildWindowMaterialization('SELECT * FROM game;')).toBeNull();
+  });
+
+  it('preserves a custom projection', () => {
+    const surql = 'SELECT id, white, black FROM game ORDER BY date desc LIMIT 30 START 60;';
+    expect(buildWindowMaterialization(surql)!.query).toBe(
+      'SELECT id, white, black FROM $__win ORDER BY date desc'
+    );
+  });
+
+  it('omits ORDER BY when the query had none', () => {
+    const surql = 'SELECT * FROM game LIMIT 30 START 30;';
+    expect(buildWindowMaterialization(surql)!.query).toBe('SELECT * FROM $__win');
+  });
+
+  it('ignores FROM/ORDER BY/LIMIT/START inside subqueries (paren-aware)', () => {
+    const surql =
+      'SELECT *, (SELECT * FROM comment WHERE game = $parent.id ORDER BY created_at desc LIMIT 5) AS comments ' +
+      'FROM game ORDER BY sort_index asc LIMIT 30 START 90;';
+    expect(buildWindowMaterialization(surql)!.query).toBe(
+      'SELECT *, (SELECT * FROM comment WHERE game = $parent.id ORDER BY created_at desc LIMIT 5) AS comments FROM $__win ORDER BY sort_index asc'
+    );
+  });
+
+  it('does not treat a START inside a string literal as the offset', () => {
+    const surql = "SELECT * FROM game WHERE note = 'LIMIT 30 START 30' ORDER BY date desc LIMIT 30 START 30;";
+    const r = buildWindowMaterialization(surql);
+    expect(r!.query).toBe('SELECT * FROM $__win ORDER BY date desc');
+  });
+});

package/src/modules/data/window-query.ts

@@ -0,0 +1,130 @@
+/**
+ * Rewrite a windowed (`LIMIT n START m`, m>0) SELECT so its rows are
+ * materialized from an explicit record-id set — the window the SSP already
+ * computed — instead of re-running the original query (with its `START m`)
+ * against the shared local DB.
+ *
+ * Why: `DataModule.processStreamUpdate` materializes a query's rows by
+ * re-querying the local in-browser SurrealDB with the original surql. For an
+ * offset query that re-applies `START m` against the *shared* local store —
+ * which, with sparse windowing, may hold only this window's rows — so it skips
+ * them all and returns nothing (the "page 2 returns 0 rows" bug). The SSP's
+ * materialized view (`StreamUpdate.localArray`) is exactly this window's row
+ * ids, so we select those ids directly and re-apply the original `ORDER BY` for
+ * stable display order.
+ *
+ * Returns `null` for non-offset queries (`START` absent or 0) — the caller
+ * keeps the normal re-query path, so only the broken case changes behavior.
+ *
+ * Preserves the `SELECT <projection>` clause and the top-level `ORDER BY`;
+ * drops the original `FROM`/`WHERE`/`LIMIT`/`START`. Subqueries inside the
+ * projection are preserved verbatim (the scanner is paren/quote aware), with
+ * one caveat: SurrealDB v3 drops `*` in the `SELECT *, <subquery> FROM $param`
+ * shape — such windowed+subquery queries are rare and were already returning 0,
+ * so this is no regression.
+ */
+export function buildWindowMaterialization(
+  surql: string,
+  idsParam = '__win'
+): { query: string } | null {
+  const kw = scanTopLevelClauses(surql);
+  if (kw.startValue === null || kw.startValue <= 0) return null;
+  if (kw.fromIndex === null) return null;
+
+  const selectClause = surql.slice(0, kw.fromIndex).trimEnd(); // "SELECT <projection>"
+
+  let orderBy = '';
+  if (kw.orderByIndex !== null) {
+    const ends = [kw.limitIndex, kw.startIndex, kw.semicolonIndex, surql.length].filter(
+      (n): n is number => n !== null && n > kw.orderByIndex!
+    );
+    const end = Math.min(...ends);
+    orderBy = ' ' + surql.slice(kw.orderByIndex, end).trim();
+  }
+
+  return { query: `${selectClause} FROM $${idsParam}${orderBy}` };
+}
+
+interface TopLevelClauses {
+  fromIndex: number | null;
+  orderByIndex: number | null;
+  limitIndex: number | null;
+  startIndex: number | null;
+  startValue: number | null;
+  semicolonIndex: number | null;
+}
+
+// Single pass over the query, tracking paren depth and single-quoted strings so
+// that clauses inside subqueries (which live in parens) are ignored — only the
+// outermost (depth-0) clause keywords are recorded.
+function scanTopLevelClauses(sql: string): TopLevelClauses {
+  const out: TopLevelClauses = {
+    fromIndex: null,
+    orderByIndex: null,
+    limitIndex: null,
+    startIndex: null,
+    startValue: null,
+    semicolonIndex: null,
+  };
+  let depth = 0;
+  let inStr = false;
+
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i];
+    if (inStr) {
+      if (ch === '\\') i++; // skip escaped char
+      else if (ch === "'") inStr = false;
+      continue;
+    }
+    if (ch === "'") { inStr = true; continue; }
+    if (ch === '(') { depth++; continue; }
+    if (ch === ')') { depth--; continue; }
+    if (depth !== 0) continue;
+    if (ch === ';' && out.semicolonIndex === null) { out.semicolonIndex = i; continue; }
+
+    // Only test keywords at a word boundary.
+    if (!isWordBoundary(sql, i)) continue;
+    if (out.fromIndex === null && matchKeyword(sql, i, 'FROM')) { out.fromIndex = i; continue; }
+    // FROM must come before the trailing clauses; only record them once seen.
+    if (out.fromIndex === null) continue;
+    if (out.orderByIndex === null && matchKeyword(sql, i, 'ORDER BY')) { out.orderByIndex = i; continue; }
+    if (out.limitIndex === null && matchKeyword(sql, i, 'LIMIT')) { out.limitIndex = i; continue; }
+    if (out.startIndex === null && matchKeyword(sql, i, 'START')) {
+      out.startIndex = i;
+      out.startValue = readNumberAfter(sql, i + 'START'.length);
+      continue;
+    }
+  }
+  return out;
+}
+
+function isWordBoundary(sql: string, i: number): boolean {
+  if (i === 0) return true;
+  return !/[A-Za-z0-9_]/.test(sql[i - 1]);
+}
+
+// Case-insensitive keyword match where internal whitespace (e.g. "ORDER BY")
+// matches any run of whitespace, and the keyword ends on a non-word char.
+function matchKeyword(sql: string, i: number, keyword: string): boolean {
+  const parts = keyword.split(' ');
+  let pos = i;
+  for (let p = 0; p < parts.length; p++) {
+    const word = parts[p];
+    if (sql.slice(pos, pos + word.length).toUpperCase() !== word) return false;
+    pos += word.length;
+    if (p < parts.length - 1) {
+      const wsStart = pos;
+      while (pos < sql.length && /\s/.test(sql[pos])) pos++;
+      if (pos === wsStart) return false; // required whitespace
+    }
+  }
+  // Must end on a non-word char (or end of string).
+  return pos >= sql.length || !/[A-Za-z0-9_]/.test(sql[pos]);
+}
+
+function readNumberAfter(sql: string, from: number): number | null {
+  let pos = from;
+  while (pos < sql.length && /\s/.test(sql[pos])) pos++;
+  const m = /^\d+/.exec(sql.slice(pos));
+  return m ? parseInt(m[0], 10) : null;
+}

package/src/modules/devtools/index.ts

@@ -1,8 +1,8 @@
-import { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
-import { Logger } from '../../services/logger/index';
-import { SchemaStructure } from '@spooky-sync/query-builder';
+import type { LocalDatabaseService, RemoteDatabaseService } from '../../services/database/index';
+import type { Logger } from '../../services/logger/index';
+import type { SchemaStructure } from '@spooky-sync/query-builder';
 import { RecordId } from 'surrealdb';
-import { StreamUpdate, StreamUpdateReceiver } from '../../services/stream-processor/index';
+import type { StreamUpdate, StreamUpdateReceiver } from '../../services/stream-processor/index';
 import { encodeRecordId } from '../../utils/index';
 
 // DevTools interfaces (matching extension expectations)
@@ -13,14 +13,23 @@ export interface DevToolsEvent {
   payload: any;
 }
 
-import { DataModule } from '../data/index';
-import { AuthService } from '../auth/index';
+import type { DataModule } from '../data/index';
+import type { AuthService } from '../auth/index';
 import { AuthEventTypes } from '../auth/events/index';
+import {
+  type BackendInfo,
+  emptyBackendInfo,
+  parseBackendInfo,
+} from './versions';
 
 export class DevToolsService implements StreamUpdateReceiver {
   private eventsHistory: DevToolsEvent[] = [];
   private eventIdCounter = 0;
-  private version = '1.0.0';
+  // Real bundled frontend version (injected at build time via tsdown `define`).
+  private version = __SP00KY_CORE_VERSION__;
+  // Backend stack info (versions + per-entity status), read via the
+  // `fn::spooky::info()` SurrealQL function; empty/'unavailable' until resolved.
+  private backendInfo: BackendInfo = emptyBackendInfo();
 
   constructor(
     private databaseService: LocalDatabaseService,
@@ -37,7 +46,33 @@ export class DevToolsService implements StreamUpdateReceiver {
       this.notifyDevTools();
     });
 
-    this.logger.debug({ Category: 'spooky-client::DevToolsService::init' }, 'Service initialized');
+    // Fire-and-forget backend version discovery; re-push state when it lands.
+    void this.refreshBackendVersions();
+
+    this.logger.debug({ Category: 'sp00ky-client::DevToolsService::init' }, 'Service initialized');
+  }
+
+  /**
+   * Re-read backend stack info via the `fn::spooky::info()` SurrealQL function
+   * over the open remote connection (no HTTP/CORS), then notify the panel.
+   * Never throws: on failure the info stays empty/'unavailable'.
+   */
+  private async refreshBackendVersions(): Promise<void> {
+    try {
+      // `RETURN fn::spooky::info()` → one statement result: the /info entity array.
+      const result = await this.remoteDatabaseService.query<unknown[]>(
+        'RETURN fn::spooky::info()'
+      );
+      const first = Array.isArray(result) ? result[0] : result;
+      this.backendInfo = parseBackendInfo(first);
+    } catch (err) {
+      this.logger.debug(
+        { err, Category: 'sp00ky-client::DevToolsService::versions' },
+        'fn::spooky::info() unavailable; backend versions stay unavailable'
+      );
+      this.backendInfo = emptyBackendInfo();
+    }
+    this.notifyDevTools();
   }
 
   // Get active queries directly from DataManager (single source of truth)
@@ -51,6 +86,10 @@ export class DevToolsService implements StreamUpdateReceiver {
       result.set(queryHash, {
         queryHash,
         status: 'active',
+        // Runtime fetch status, distinct from the `status: 'active'`
+        // registration flag above. `fetchStatus` is 'idle' | 'fetching'.
+        fetchStatus: q.status,
+        isFetching: q.status === 'fetching',
         createdAt:
           q.config.lastActiveAt instanceof Date
             ? q.config.lastActiveAt.getTime()
@@ -63,6 +102,10 @@ export class DevToolsService implements StreamUpdateReceiver {
         data: q.records,
         localArray: q.config.localArray,
         remoteArray: q.config.remoteArray,
+        // Detailed per-phase processing-time breakdown (SSP sub-phases, local/
+        // remote record fetch, frontend reconcile, registration). Flows to both
+        // the DevTools panel and the MCP (which returns activeQueries verbatim).
+        timings: this.dataManager.phaseTimings(q),
       });
     });
     return result;
@@ -70,7 +113,7 @@ export class DevToolsService implements StreamUpdateReceiver {
 
   public onQueryInitialized(payload: any) {
     this.logger.debug(
-      { payload, Category: 'spooky-client::DevToolsService::onQueryInitialized' },
+      { payload, Category: 'sp00ky-client::DevToolsService::onQueryInitialized' },
       'QueryInitialized'
     );
     const queryHash = this.hashString(payload.queryId.toString());
@@ -87,7 +130,7 @@ export class DevToolsService implements StreamUpdateReceiver {
     this.logger.debug(
       {
         id: payload.queryId?.toString(),
-        Category: 'spooky-client::DevToolsService::onQueryUpdated',
+        Category: 'sp00ky-client::DevToolsService::onQueryUpdated',
       },
       'QueryUpdated'
     );
@@ -102,7 +145,7 @@ export class DevToolsService implements StreamUpdateReceiver {
 
   public onStreamUpdate(update: StreamUpdate) {
     this.logger.debug(
-      { update, Category: 'spooky-client::DevToolsService::onStreamUpdate' },
+      { update, Category: 'sp00ky-client::DevToolsService::onStreamUpdate' },
       'StreamUpdate'
     );
     this.addEvent('STREAM_UPDATE', {
@@ -160,6 +203,15 @@ export class DevToolsService implements StreamUpdateReceiver {
         userId: this.authService.currentUser?.id,
       },
       version: this.version,
+      versions: {
+        frontend: {
+          core: __SP00KY_CORE_VERSION__,
+          wasm: __SP00KY_WASM_VERSION__,
+          surrealdb: __SP00KY_SURREAL_VERSION__,
+        },
+        backend: this.backendInfo.versions,
+        entities: this.backendInfo.entities,
+      },
       database: {
         tables: this.schema.tables.map((t) => t.name),
         tableData: {},
@@ -171,8 +223,8 @@ export class DevToolsService implements StreamUpdateReceiver {
     if (typeof window !== 'undefined') {
       window.postMessage(
         {
-          type: 'SPOOKY_STATE_CHANGED',
-          source: 'spooky-devtools-page',
+          type: 'SP00KY_STATE_CHANGED',
+          source: 'sp00ky-devtools-page',
           state: this.getState(),
         },
         '*'
@@ -229,13 +281,14 @@ export class DevToolsService implements StreamUpdateReceiver {
 
   private exposeToWindow() {
     if (typeof window !== 'undefined') {
-      (window as any).__SPOOKY__ = {
+      (window as any).__00__ = {
         version: this.version,
         getState: () => this.getState(),
         clearHistory: () => {
           this.eventsHistory = [];
           this.notifyDevTools();
         },
+        refreshVersions: () => this.refreshBackendVersions(),
         getTableData: async (tableName: string) => {
           try {
             // Returns the first statement result as T.
@@ -270,7 +323,7 @@ export class DevToolsService implements StreamUpdateReceiver {
             return this.serializeForDevTools(records) || [];
           } catch (e) {
             this.logger.error(
-              { err: e, Category: 'spooky-client::DevToolsService::exposeToWindow' },
+              { err: e, Category: 'sp00ky-client::DevToolsService::exposeToWindow' },
               'Failed to get table data'
             );
             return [];
@@ -299,7 +352,7 @@ export class DevToolsService implements StreamUpdateReceiver {
         runQuery: async (query: string, target: 'local' | 'remote' = 'local') => {
           try {
             this.logger.debug(
-              { query, target, Category: 'spooky-client::DevToolsService::runQuery' },
+              { query, target, Category: 'sp00ky-client::DevToolsService::runQuery' },
               'Running query (START)'
             );
             const service = target === 'remote' ? this.remoteDatabaseService : this.databaseService;
@@ -314,7 +367,7 @@ export class DevToolsService implements StreamUpdateReceiver {
                 time: queryTime,
                 resultType: typeof result,
                 isArray: Array.isArray(result),
-                Category: 'spooky-client::DevToolsService::runQuery',
+                Category: 'sp00ky-client::DevToolsService::runQuery',
               },
               'Database returned result'
             );
@@ -328,7 +381,7 @@ export class DevToolsService implements StreamUpdateReceiver {
               {
                 serializeTime,
                 serializedLength: JSON.stringify(serialized).length,
-                Category: 'spooky-client::DevToolsService::runQuery',
+                Category: 'sp00ky-client::DevToolsService::runQuery',
               },
               'Serialization complete'
             );
@@ -340,7 +393,7 @@ export class DevToolsService implements StreamUpdateReceiver {
             };
           } catch (e: any) {
             this.logger.error(
-              { err: e, query, target, Category: 'spooky-client::DevToolsService::runQuery' },
+              { err: e, query, target, Category: 'sp00ky-client::DevToolsService::runQuery' },
               'Query execution failed'
             );
             // Ensure we always return a string for error
@@ -353,12 +406,15 @@ export class DevToolsService implements StreamUpdateReceiver {
 
       window.postMessage(
         {
-          type: 'SPOOKY_DETECTED',
-          source: 'spooky-devtools-page',
+          type: 'SP00KY_DETECTED',
+          source: 'sp00ky-devtools-page',
           data: { version: this.version, detected: true },
         },
         '*'
       );
+
+      // Dispatch custom event so the devtools page-script can detect late initialization
+      window.dispatchEvent(new CustomEvent('sp00ky:init'));
     }
   }
 }

package/src/modules/devtools/versions.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import {
+  emptyBackendInfo,
+  emptyBackendVersions,
+  parseBackendInfo,
+  toEntityArray,
+  UNAVAILABLE,
+} from './versions';
+
+describe('toEntityArray', () => {
+  it('passes through an array, dropping non-objects', () => {
+    expect(toEntityArray([{ entity: 'ssp' }, null, 'x'])).toEqual([{ entity: 'ssp' }]);
+  });
+
+  it('wraps a single object', () => {
+    expect(toEntityArray({ entity: 'ssp' })).toEqual([{ entity: 'ssp' }]);
+  });
+
+  it('returns [] for null/undefined/primitives', () => {
+    expect(toEntityArray(null)).toEqual([]);
+    expect(toEntityArray(undefined)).toEqual([]);
+    expect(toEntityArray(42)).toEqual([]);
+  });
+});
+
+describe('parseBackendInfo', () => {
+  it('parses the singlenode shape (ssp only) incl. surrealdb_version', () => {
+    const { versions, entities } = parseBackendInfo([
+      { entity: 'ssp', version: '0.0.1-canary.69', surrealdb_version: '2.0.3', status: 'ready' },
+    ]);
+    expect(versions.ssp).toBe('0.0.1-canary.69');
+    expect(versions.surrealdb).toBe('2.0.3');
+    expect(versions.scheduler).toBe(UNAVAILABLE);
+    expect(entities).toHaveLength(1);
+  });
+
+  it('parses the cluster shape (scheduler + ssp + backend)', () => {
+    const { versions, entities } = parseBackendInfo([
+      { entity: 'scheduler', version: '0.9.0', surrealdb_version: '2.0.3', status: 'ready' },
+      { entity: 'ssp', version: '0.9.0', status: 'ready' },
+      { entity: 'backend', id: 'surrealdb', status: 'healthy' },
+    ]);
+    expect(versions.scheduler).toBe('0.9.0');
+    expect(versions.ssp).toBe('0.9.0');
+    expect(versions.surrealdb).toBe('2.0.3');
+    expect(entities).toHaveLength(3);
+  });
+
+  it('strips a leading surrealdb- prefix', () => {
+    const { versions } = parseBackendInfo([
+      { entity: 'ssp', version: '1.0.0', surrealdb_version: 'surrealdb-2.1.0' },
+    ]);
+    expect(versions.surrealdb).toBe('2.1.0');
+  });
+
+  it('takes surrealdb_version from whichever entity reports it', () => {
+    const { versions } = parseBackendInfo([
+      { entity: 'scheduler', version: '0.9.0' },
+      { entity: 'ssp', version: '0.9.0', surrealdb_version: '3.1.0' },
+    ]);
+    expect(versions.surrealdb).toBe('3.1.0');
+  });
+
+  it('tolerates a single object instead of an array', () => {
+    const { versions } = parseBackendInfo({ entity: 'ssp', version: '1.2.3' });
+    expect(versions.ssp).toBe('1.2.3');
+  });
+
+  it('returns all-unavailable / empty for null or garbage', () => {
+    expect(parseBackendInfo(null)).toEqual(emptyBackendInfo());
+    expect(parseBackendInfo('nope').versions).toEqual(emptyBackendVersions());
+    expect(parseBackendInfo([{ foo: 'bar' }]).versions).toEqual(emptyBackendVersions());
+  });
+});

package/src/modules/devtools/versions.ts

@@ -0,0 +1,81 @@
+/**
+ * Backend versions of the stack components, derived from the entity list the
+ * backend `/info` endpoint exposes (read via the `fn::spooky::info()` SurrealQL
+ * function). Any component that isn't reported degrades to `'unavailable'`.
+ */
+export interface BackendVersions {
+  ssp: string;
+  scheduler: string;
+  surrealdb: string;
+}
+
+export const UNAVAILABLE = 'unavailable';
+
+/**
+ * A single stack entity as reported by `/info` (one per ssp / scheduler /
+ * backend). Carries far more than versions — status, uptime, ip, views — so the
+ * DevTools can render the whole stack. Extra fields are preserved verbatim.
+ */
+export interface BackendEntity {
+  entity: string;
+  id?: string;
+  ip?: string | null;
+  status?: string;
+  version?: string;
+  surrealdb_version?: string;
+  uptime_seconds?: number;
+  views?: number;
+  [key: string]: unknown;
+}
+
+export interface BackendInfo {
+  versions: BackendVersions;
+  entities: BackendEntity[];
+}
+
+export function emptyBackendVersions(): BackendVersions {
+  return { ssp: UNAVAILABLE, scheduler: UNAVAILABLE, surrealdb: UNAVAILABLE };
+}
+
+export function emptyBackendInfo(): BackendInfo {
+  return { versions: emptyBackendVersions(), entities: [] };
+}
+
+/** Strip a leading `surrealdb-` so versions read as bare semver (e.g. `2.0.3`). */
+function normalizeServerVersion(v: string): string {
+  return String(v).replace(/^surrealdb-/i, '').trim();
+}
+
+/**
+ * Normalize whatever `RETURN fn::spooky::info()` resolves to into the entity
+ * array. The SurrealQL function returns the parsed `/info` array; depending on
+ * how the result is unwrapped it may arrive as the array itself, a single
+ * object, or `null`. Tolerant of all three.
+ */
+export function toEntityArray(raw: unknown): BackendEntity[] {
+  if (Array.isArray(raw)) return raw.filter((e): e is BackendEntity => !!e && typeof e === 'object');
+  if (raw && typeof raw === 'object') return [raw as BackendEntity];
+  return [];
+}
+
+/**
+ * Derive component versions + the full entity list from a `/info` entity array.
+ * `surrealdb` is taken from whichever entity reports `surrealdb_version` (ssp or
+ * scheduler). Never throws; missing pieces stay `'unavailable'`.
+ */
+export function parseBackendInfo(raw: unknown): BackendInfo {
+  const entities = toEntityArray(raw);
+  const versions = emptyBackendVersions();
+
+  for (const entity of entities) {
+    const version = entity.version ? String(entity.version) : undefined;
+    if (entity.entity === 'ssp' && version) versions.ssp = version;
+    else if (entity.entity === 'scheduler' && version) versions.scheduler = version;
+
+    if (versions.surrealdb === UNAVAILABLE && entity.surrealdb_version) {
+      versions.surrealdb = normalizeServerVersion(String(entity.surrealdb_version));
+    }
+  }
+
+  return { versions, entities };
+}

package/src/modules/ref-tables.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { listRefTableFor, sanitizeUserId } from './ref-tables';
+
+describe('listRefTableFor', () => {
+  it('returns global table in single mode regardless of user', () => {
+    expect(listRefTableFor('single', 'user:abc')).toBe('_00_list_ref');
+    expect(listRefTableFor('single', null)).toBe('_00_list_ref');
+    expect(listRefTableFor('single', undefined)).toBe('_00_list_ref');
+  });
+
+  it('returns per-user table in dedicated mode with valid user id', () => {
+    expect(listRefTableFor('dedicated', 'user:abc')).toBe(
+      '_00_list_ref_user_abc'
+    );
+  });
+
+  it('accepts a RecordId object in dedicated mode', () => {
+    const rid = new RecordId('user', 'def');
+    expect(listRefTableFor('dedicated', rid)).toBe('_00_list_ref_user_def');
+  });
+
+  it('falls back to global in dedicated mode when user id is missing', () => {
+    expect(listRefTableFor('dedicated', null)).toBe('_00_list_ref');
+    expect(listRefTableFor('dedicated', undefined)).toBe('_00_list_ref');
+  });
+
+  it('falls back to global in dedicated mode when user id has invalid chars', () => {
+    // SurrealDB table identifiers only accept alphanumerics + underscore.
+    expect(listRefTableFor('dedicated', 'user:abc-with-dash')).toBe(
+      '_00_list_ref'
+    );
+    expect(listRefTableFor('dedicated', 'user:abc.dot')).toBe('_00_list_ref');
+  });
+});
+
+describe('sanitizeUserId', () => {
+  it('strips the user: prefix', () => {
+    expect(sanitizeUserId('user:abc123')).toBe('abc123');
+  });
+
+  it('accepts plain ids without the user: prefix', () => {
+    expect(sanitizeUserId('abc123')).toBe('abc123');
+  });
+
+  it('accepts RecordId objects', () => {
+    expect(sanitizeUserId(new RecordId('user', 'xyz'))).toBe('xyz');
+  });
+
+  it('returns null for invalid id shapes', () => {
+    expect(sanitizeUserId(null)).toBeNull();
+    expect(sanitizeUserId(undefined)).toBeNull();
+    expect(sanitizeUserId('user:')).toBeNull();
+    expect(sanitizeUserId('user:has-dash')).toBeNull();
+  });
+});

package/src/modules/ref-tables.ts

@@ -0,0 +1,57 @@
+// Client-side mirror of `packages/ssp-protocol/src/lib.rs`'s
+// `query_table_for` / `list_ref_table_for`. Same naming convention so
+// the LIVE subscription, the initial-fetch read, and the SSP's writes
+// all land on the same table.
+//
+// The mode is currently hardcoded to `dedicated` because that's the
+// only mode the e2e suite exercises and threading the value through
+// codegen wasn't necessary to land the cross-session fix. If single
+// mode ever needs to be exposed from the TS client too, the SSP server
+// already reads it from `SPKY_SSP_REF_MODE`; add a matching codegen
+// export then.
+
+export type RefMode = 'single' | 'dedicated';
+
+/**
+ * Default ref-storage mode for this client build. Mirrors the SSP's
+ * default (`RefMode::Dedicated`) so cross-session sync works out of the
+ * box.
+ */
+export const DEFAULT_REF_MODE: RefMode = 'dedicated';
+
+/**
+ * Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+ * goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+ * the id is missing the `user:` prefix or contains characters that
+ * aren't valid in a SurrealDB table identifier — the server-side
+ * `ssp_protocol::sanitize_user_id` uses the same predicate.
+ *
+ * Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+ * objects (which only stringify cleanly via `.toString()`), since
+ * `AuthService` passes the record-id object as-is to its subscribers.
+ */
+export function sanitizeUserId(userId: unknown): string | null {
+  if (userId === null || userId === undefined) return null;
+  const asString =
+    typeof userId === 'string'
+      ? userId
+      : typeof (userId as { toString?: unknown }).toString === 'function'
+        ? (userId as { toString: () => string }).toString()
+        : null;
+  if (!asString) return null;
+  const raw = asString.startsWith('user:') ? asString.slice('user:'.length) : asString;
+  if (raw.length === 0) return null;
+  if (!/^[A-Za-z0-9_]+$/.test(raw)) return null;
+  return raw;
+}
+
+/**
+ * Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+ * back to the global `_00_list_ref` when sanitization fails or in
+ * single mode.
+ */
+export function listRefTableFor(mode: RefMode, userId: unknown): string {
+  if (mode === 'single') return '_00_list_ref';
+  const uid = sanitizeUserId(userId);
+  return uid ? `_00_list_ref_user_${uid}` : '_00_list_ref';
+}