@spooky-sync/core 0.0.1-canary.11 → 0.0.1-canary.111

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,154 @@
+/**
+ * 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.
+ */
+import type { QueryPlan } from '@spooky-sync/query-builder';
+
+/**
+ * Plan-level window materialization: restrict a windowed query's base rows to
+ * exactly the SSP-computed id-set, dropping `where`/`limit`/`offset` but keeping
+ * `orderBy`, `select` and `relations`. The engine-neutral counterpart of
+ * {@link buildWindowMaterialization} (which does the same by string surgery for
+ * the raw-SurrealQL path). Returns `null` for non-offset queries so the caller
+ * keeps the normal re-query path.
+ */
+export function buildWindowMaterializationPlan(
+  plan: QueryPlan,
+  ids: unknown[]
+): QueryPlan | null {
+  if (plan.offset === undefined || plan.offset <= 0) return null;
+  return {
+    ...plan,
+    ids,
+    where: undefined,
+    limit: undefined,
+    offset: undefined,
+  };
+}
+
+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 { LocalStore, 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,17 +13,51 @@ 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';
+
+// Real bundled frontend versions, injected at build time by tsdown's
+// version-define plugin (see tsdown.config.ts). The `typeof` guard keeps these
+// from throwing a ReferenceError when a downstream app bundles core from source
+// (where the plugin never runs); in that case they fall back to 'unknown' and
+// DevTools simply reports an unknown frontend version instead of crashing.
+const CORE_VERSION =
+  typeof __SP00KY_CORE_VERSION__ !== 'undefined' ? __SP00KY_CORE_VERSION__ : 'unknown';
+const WASM_VERSION =
+  typeof __SP00KY_WASM_VERSION__ !== 'undefined' ? __SP00KY_WASM_VERSION__ : 'unknown';
+const SURREAL_VERSION =
+  typeof __SP00KY_SURREAL_VERSION__ !== 'undefined' ? __SP00KY_SURREAL_VERSION__ : 'unknown';
 
 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 = 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();
+  // Dormant until a devtools consumer (extension panel or MCP) handshakes via
+  // `SP00KY_DEVTOOLS_CONNECT`. While false, `notifyDevTools()`/`addEvent()` do no
+  // work, so prod pays zero serialization/postMessage cost for an unwatched panel.
+  // `window.__00__.getState()` stays live regardless, so the panel's first paint
+  // (the on-demand GET_STATE pull) still works before the push channel turns on.
+  private enabled = false;
+
+  // Full local table list (incl. internal `_00_*`), enumerated from the local DB
+  // via our own reliable `service.query` — the DevTools panel's page-eval query
+  // bridge is unreliable under load, so the panel relies on this instead.
+  private localTables: string[] = [];
+  private localTablesFetching = false;
+  private localTablesAt = 0;
 
   constructor(
-    private databaseService: LocalDatabaseService,
+    private databaseService: LocalStore,
     private remoteDatabaseService: RemoteDatabaseService,
     private logger: Logger,
     private schema: SchemaStructure,
@@ -32,12 +66,54 @@ export class DevToolsService implements StreamUpdateReceiver {
   ) {
     this.exposeToWindow();
 
+    // Stay dormant until a devtools consumer announces itself. The extension's
+    // page-script posts this once it detects `window.__00__`; the panel can also
+    // disconnect to return us to dormant. Until then we skip all serialization.
+    if (typeof window !== 'undefined') {
+      window.addEventListener('message', (e) => {
+        if (e.source !== window) return;
+        const type = (e.data as { type?: string } | undefined)?.type;
+        if (type === 'SP00KY_DEVTOOLS_CONNECT') {
+          this.enabled = true;
+          this.notifyDevTools();
+        } else if (type === 'SP00KY_DEVTOOLS_DISCONNECT') {
+          this.enabled = false;
+        }
+      });
+    }
+
     // Subscribe to auth events
     this.authService.eventSystem.subscribe(AuthEventTypes.AuthStateChanged, () => {
       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)
@@ -48,21 +124,33 @@ export class DevToolsService implements StreamUpdateReceiver {
     const queries = this.dataManager.getActiveQueries();
     queries.forEach((q) => {
       const queryHash = this.hashString(encodeRecordId(q.config.id));
+      const createdAt =
+        q.config.lastActiveAt instanceof Date
+          ? q.config.lastActiveAt.getTime()
+          : new Date(q.config.lastActiveAt || Date.now()).getTime();
       result.set(queryHash, {
         queryHash,
         status: 'active',
-        createdAt:
-          q.config.lastActiveAt instanceof Date
-            ? q.config.lastActiveAt.getTime()
-            : new Date(q.config.lastActiveAt || Date.now()).getTime(),
-        lastUpdate: Date.now(),
+        // Runtime fetch status, distinct from the `status: 'active'`
+        // registration flag above. `fetchStatus` is 'idle' | 'fetching'.
+        fetchStatus: q.status,
+        isFetching: q.status === 'fetching',
+        createdAt,
+        // Real last-update time; before the first update it equals createdAt.
+        // (Previously Date.now(), which reset the column on every state push.)
+        lastUpdate: q.lastUpdatedAt ?? createdAt,
         updateCount: q.updateCount,
+        ttl: q.config.ttl,
         query: q.config.surql,
         variables: q.config.params || {},
         dataSize: q.records?.length || 0,
         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 +158,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 +175,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 +190,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', {
@@ -142,6 +230,8 @@ export class DevToolsService implements StreamUpdateReceiver {
   }
 
   private addEvent(eventType: string, payload: any) {
+    // No consumer attached → skip recording (and the recursive serialize it does).
+    if (!this.enabled) return;
     this.eventsHistory.push({
       id: this.eventIdCounter++,
       timestamp: Date.now(),
@@ -151,7 +241,50 @@ export class DevToolsService implements StreamUpdateReceiver {
     if (this.eventsHistory.length > 100) this.eventsHistory.shift();
   }
 
+  /** Unwrap a SurrealDB `INFO FOR DB` result to its `{ tables, ... }` object. */
+  private unwrapInfo(res: any): any {
+    if (!Array.isArray(res) || !res[0]) return null;
+    const first = res[0];
+    if (first && typeof first === 'object' && 'result' in first) return first.result;
+    if (Array.isArray(first)) return first[0];
+    return first;
+  }
+
+  /**
+   * Refresh the cached full local-table list from `INFO FOR DB`. Fire-and-forget
+   * and throttled — called from getState() so the panel gets every table
+   * (including internal `_00_*`) without running its own (flaky) queries.
+   */
+  private refreshLocalTables(): void {
+    if (this.localTablesFetching) return;
+    const now = Date.now();
+    if (now - this.localTablesAt < 3000) return;
+    this.localTablesFetching = true;
+    void this.databaseService
+      .query<any>('INFO FOR DB')
+      .then((res) => {
+        const info = this.unwrapInfo(res);
+        this.localTablesAt = Date.now();
+        if (info && info.tables) {
+          const names = Object.keys(info.tables);
+          const changed =
+            names.length !== this.localTables.length ||
+            names.some((n, i) => n !== this.localTables[i]);
+          this.localTables = names;
+          if (changed) this.notifyDevTools();
+        }
+      })
+      .catch(() => {
+        // Ignore — fall back to the declared app schema below.
+      })
+      .finally(() => {
+        this.localTablesFetching = false;
+      });
+  }
+
   private getState() {
+    // Keep the full local-table list fresh (throttled, non-blocking).
+    this.refreshLocalTables();
     return this.serializeForDevTools({
       eventsHistory: [...this.eventsHistory],
       activeQueries: Object.fromEntries(this.getActiveQueries()),
@@ -160,19 +293,34 @@ export class DevToolsService implements StreamUpdateReceiver {
         userId: this.authService.currentUser?.id,
       },
       version: this.version,
+      versions: {
+        frontend: {
+          core: CORE_VERSION,
+          wasm: WASM_VERSION,
+          surrealdb: SURREAL_VERSION,
+        },
+        backend: this.backendInfo.versions,
+        entities: this.backendInfo.entities,
+      },
       database: {
-        tables: this.schema.tables.map((t) => t.name),
+        // Prefer the live local-table list (includes internal `_00_*`); fall
+        // back to the declared app schema until the first enumeration lands.
+        tables: this.localTables.length
+          ? this.localTables
+          : this.schema.tables.map((t) => t.name),
         tableData: {},
       },
     });
   }
 
   private notifyDevTools() {
+    // No consumer attached → no getState() serialization, no postMessage broadcast.
+    if (!this.enabled) return;
     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 +377,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 +419,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 +448,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 +463,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 +477,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 +489,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 +502,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());
+  });
+});