@spooky-sync/core 0.0.1-canary.100 → 0.0.1-canary.102

package/dist/index.d.ts

@@ -638,6 +638,7 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private syncHealthStatus;
   private lastSyncErrorKind;
   private lastSyncErrorMessage;
+  private hasSyncedOnce;
   private selfHealTimer;
   private selfHealAttempts;
   private static readonly SELF_HEAL_BASE_MS;
@@ -693,6 +694,15 @@ declare class Sp00kySync<S extends SchemaStructure> {
    * One poll cycle: refetch `_00_list_ref` for every active query. Returns
    * whether ANY query's remoteArray actually changed — the scheduler uses this
    * to drive the adaptive idle backoff.
+   *
+   * Also the ONLY health signal that runs while the page is idle. Sync health is
+   * otherwise activity-driven (mutations/registrations via the scheduler,
+   * reconnect re-registration, self-heal), so on a quiet page a stale `degraded`
+   * would linger until the next mutation and a genuine idle drop would be
+   * invisible. We fold the cycle's aggregate reachability into `recordSyncOutcome`
+   * so idle health self-recovers (and self-degrades) with no user action. A clean
+   * cycle is idempotent when already healthy (`recordSyncOutcome` early-returns at
+   * `consecutiveSyncFailures === 0`), so a healthy idle page pays nothing.
    */
   private pollListRefForActiveQueries;
   /**

package/dist/index.js

@@ -110,6 +110,8 @@ function parseValue(name, column, value) {
 //#region src/utils/error-classification.ts
 const NETWORK_ERROR_PATTERNS = [
 	"connection",
+	"must be connected",
+	"connectionunavailable",
 	"timeout",
 	"timed out",
 	"websocket",
@@ -2676,6 +2678,7 @@ var Sp00kySync = class Sp00kySync {
 	syncHealthStatus = "healthy";
 	lastSyncErrorKind;
 	lastSyncErrorMessage;
+	hasSyncedOnce = false;
 	selfHealTimer = null;
 	selfHealAttempts = 0;
 	static SELF_HEAL_BASE_MS = 2e3;
@@ -2686,7 +2689,8 @@ var Sp00kySync = class Sp00kySync {
 			status: this.syncHealthStatus,
 			consecutiveFailures: this.consecutiveSyncFailures,
 			kind: this.syncHealthStatus === "degraded" ? this.lastSyncErrorKind : void 0,
-			error: this.syncHealthStatus === "degraded" ? this.lastSyncErrorMessage : void 0
+			error: this.syncHealthStatus === "degraded" ? this.lastSyncErrorMessage : void 0,
+			everConnected: this.hasSyncedOnce
 		};
 	}
 	/**
@@ -2712,6 +2716,7 @@ var Sp00kySync = class Sp00kySync {
 	recordSyncOutcome(ok, error) {
 		if (this.degradeAfterFailures <= 0) return;
 		if (ok) {
+			this.hasSyncedOnce = true;
 			if (this.consecutiveSyncFailures === 0) return;
 			this.consecutiveSyncFailures = 0;
 			if (this.syncHealthStatus !== "healthy") {
@@ -2917,20 +2922,45 @@ var Sp00kySync = class Sp00kySync {
 	* One poll cycle: refetch `_00_list_ref` for every active query. Returns
 	* whether ANY query's remoteArray actually changed — the scheduler uses this
 	* to drive the adaptive idle backoff.
+	*
+	* Also the ONLY health signal that runs while the page is idle. Sync health is
+	* otherwise activity-driven (mutations/registrations via the scheduler,
+	* reconnect re-registration, self-heal), so on a quiet page a stale `degraded`
+	* would linger until the next mutation and a genuine idle drop would be
+	* invisible. We fold the cycle's aggregate reachability into `recordSyncOutcome`
+	* so idle health self-recovers (and self-degrades) with no user action. A clean
+	* cycle is idempotent when already healthy (`recordSyncOutcome` early-returns at
+	* `consecutiveSyncFailures === 0`), so a healthy idle page pays nothing.
 	*/
 	async pollListRefForActiveQueries() {
 		const hashes = this.dataModule.getActiveQueryHashes();
-		if (hashes.length === 0) return false;
+		if (hashes.length === 0) {
+			try {
+				await this.remote.query("RETURN true");
+				this.recordSyncOutcome(true);
+			} catch (err) {
+				this.recordSyncOutcome(false, err);
+			}
+			return false;
+		}
 		let anyChanged = false;
+		let reached = false;
+		let firstNetworkErr;
 		for (const hash of hashes) try {
 			if (await this.refetchListRefForQuery(hash)) anyChanged = true;
+			reached = true;
 		} catch (err) {
+			if (classifySyncError(err) === "network") {
+				if (firstNetworkErr === void 0) firstNetworkErr = err;
+			} else reached = true;
 			this.logger.debug({
 				err: err?.message ?? err,
 				hash,
 				Category: "sp00ky-client::Sp00kySync::pollListRefForActiveQueries"
 			}, "Per-query list_ref poll failed");
 		}
+		if (reached) this.recordSyncOutcome(true);
+		else if (firstNetworkErr !== void 0) this.recordSyncOutcome(false, firstNetworkErr);
 		return anyChanged;
 	}
 	/**
@@ -3485,8 +3515,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.100";
-const WASM_VERSION = "0.0.1-canary.100";
+const CORE_VERSION = "0.0.1-canary.102";
+const WASM_VERSION = "0.0.1-canary.102";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -3494,6 +3524,9 @@ var DevToolsService = class {
 	version = CORE_VERSION;
 	backendInfo = emptyBackendInfo();
 	enabled = false;
+	localTables = [];
+	localTablesFetching = false;
+	localTablesAt = 0;
 	constructor(databaseService, remoteDatabaseService, logger, schema, authService, dataManager) {
 		this.databaseService = databaseService;
 		this.remoteDatabaseService = remoteDatabaseService;
@@ -3547,6 +3580,7 @@ var DevToolsService = class {
 				createdAt: q.config.lastActiveAt instanceof Date ? q.config.lastActiveAt.getTime() : new Date(q.config.lastActiveAt || Date.now()).getTime(),
 				lastUpdate: Date.now(),
 				updateCount: q.updateCount,
+				ttl: q.config.ttl,
 				query: q.config.surql,
 				variables: q.config.params || {},
 				dataSize: q.records?.length || 0,
@@ -3625,7 +3659,38 @@ var DevToolsService = class {
 		});
 		if (this.eventsHistory.length > 100) this.eventsHistory.shift();
 	}
+	/** Unwrap a SurrealDB `INFO FOR DB` result to its `{ tables, ... }` object. */
+	unwrapInfo(res) {
+		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.
+	*/
+	refreshLocalTables() {
+		if (this.localTablesFetching) return;
+		if (Date.now() - this.localTablesAt < 3e3) return;
+		this.localTablesFetching = true;
+		this.databaseService.query("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(() => {}).finally(() => {
+			this.localTablesFetching = false;
+		});
+	}
 	getState() {
+		this.refreshLocalTables();
 		return this.serializeForDevTools({
 			eventsHistory: [...this.eventsHistory],
 			activeQueries: Object.fromEntries(this.getActiveQueries()),
@@ -3644,7 +3709,7 @@ var DevToolsService = class {
 				entities: this.backendInfo.entities
 			},
 			database: {
-				tables: this.schema.tables.map((t) => t.name),
+				tables: this.localTables.length ? this.localTables : this.schema.tables.map((t) => t.name),
 				tableData: {}
 			}
 		});

package/dist/types.d.ts

@@ -340,6 +340,13 @@ interface SyncHealth {
   kind?: 'network' | 'application';
   /** Message of the most recent failure (only set while `degraded`). */
   error?: string;
+  /**
+   * `true` once at least one sync round has succeeded this session. Lets a UI
+   * distinguish a first-time "connecting" phase (never reached the server yet,
+   * so a cold-start failure run is expected) from a real lost connection after
+   * a working session. Never resets back to `false` once set.
+   */
+  everConnected: boolean;
 }
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.100",
+  "version": "0.0.1-canary.102",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.100",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.100",
+    "@spooky-sync/query-builder": "0.0.1-canary.102",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.102",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/devtools/index.ts

@@ -49,6 +49,13 @@ export class DevToolsService implements StreamUpdateReceiver {
   // (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 remoteDatabaseService: RemoteDatabaseService,
@@ -130,6 +137,7 @@ export class DevToolsService implements StreamUpdateReceiver {
             : new Date(q.config.lastActiveAt || Date.now()).getTime(),
         lastUpdate: Date.now(),
         updateCount: q.updateCount,
+        ttl: q.config.ttl,
         query: q.config.surql,
         variables: q.config.params || {},
         dataSize: q.records?.length || 0,
@@ -230,7 +238,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()),
@@ -249,7 +300,11 @@ export class DevToolsService implements StreamUpdateReceiver {
         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: {},
       },
     });

package/src/modules/sync/sync.health.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Sp00kySync } from './sync';
+
+// The idle list-ref poll is the only health signal that runs on a quiet page.
+// These tests exercise `pollListRefForActiveQueries` -> `recordSyncOutcome` in
+// isolation: a run of network-failed cycles degrades, and a single clean cycle
+// recovers WITHOUT any mutation (the reported bug). Construction is cheap —
+// Sp00kySync's constructor only stores refs and calls logger.child; no timers or
+// I/O start until init(), which we never call.
+
+const CONNECTION_UNAVAILABLE =
+  'You must be connected to a SurrealDB instance before performing this operation';
+
+function makeSync(hashes: string[]) {
+  const logger: any = {
+    child: () => logger,
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    trace: () => {},
+  };
+  const remote: any = { query: vi.fn().mockResolvedValue([true]) };
+  const dataModule: any = { getActiveQueryHashes: () => hashes };
+
+  const sync = new Sp00kySync(
+    {} as any,
+    remote,
+    {} as any,
+    dataModule,
+    {} as any,
+    logger,
+    { degradeAfterConsecutiveFailures: 3 }
+  );
+
+  // `refetchListRefForQuery` is what the poll calls per active hash; stub it so
+  // the test controls per-cycle reachability. `poll` invokes the private method.
+  const refetch = vi.fn();
+  (sync as any).refetchListRefForQuery = refetch;
+  const poll = () => (sync as any).pollListRefForActiveQueries() as Promise<boolean>;
+
+  return { sync, remote, refetch, poll };
+}
+
+describe('sync health via idle poll', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('degrades after N consecutive network-failed poll cycles', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+    expect(sync.syncHealth.kind).toBe('network');
+  });
+
+  it('recovers on the next clean poll cycle — no mutation needed', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+
+    // Connectivity returns; a plain idle poll (no user action) clears it.
+    refetch.mockResolvedValue(true);
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('does not degrade on application errors (server was reached)', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    refetch.mockRejectedValue(new Error('Permission denied'));
+    await poll();
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('counts a mixed cycle (one reachable hash) as reached', async () => {
+    const { sync, refetch, poll } = makeSync(['h1', 'h2']);
+    // First degrade via all-network cycles.
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+
+    // Now one hash succeeds, the other still network-fails → reached → healthy.
+    refetch.mockReset();
+    refetch
+      .mockResolvedValueOnce(true)
+      .mockRejectedValueOnce(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('probes RETURN true when there are no active queries', async () => {
+    const { sync, remote, poll } = makeSync([]);
+    remote.query.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(remote.query).toHaveBeenCalledWith('RETURN true');
+    expect(sync.syncHealth.status).toBe('degraded');
+
+    remote.query.mockResolvedValue([true]);
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+  });
+
+  it('leaves everConnected false through a cold-start failure run', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+    expect(sync.syncHealth.everConnected).toBe(false);
+
+    // Server never reached: 3 failed cycles degrade, but this is the initial
+    // "connecting" phase, not a lost connection — everConnected stays false.
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+    expect(sync.syncHealth.everConnected).toBe(false);
+  });
+
+  it('latches everConnected on the first success and keeps it through a later degrade', async () => {
+    const { sync, refetch, poll } = makeSync(['h1']);
+
+    // First successful round reaches the server: connecting phase is over.
+    refetch.mockResolvedValue(true);
+    await poll();
+    expect(sync.syncHealth.status).toBe('healthy');
+    expect(sync.syncHealth.everConnected).toBe(true);
+
+    // Connection later drops: degraded now reflects a REAL lost connection.
+    refetch.mockReset();
+    refetch.mockRejectedValue(new Error(CONNECTION_UNAVAILABLE));
+    await poll();
+    await poll();
+    await poll();
+    expect(sync.syncHealth.status).toBe('degraded');
+    expect(sync.syncHealth.everConnected).toBe(true);
+  });
+});

package/src/modules/sync/sync.ts

@@ -168,6 +168,10 @@ export class Sp00kySync<S extends SchemaStructure> {
   private syncHealthStatus: SyncHealthStatus = 'healthy';
   private lastSyncErrorKind: 'network' | 'application' | undefined;
   private lastSyncErrorMessage: string | undefined;
+  // Latched `true` on the first successful sync round; never reset. Lets a UI
+  // tell a cold-start "connecting" phase (never reached the server) apart from
+  // a real lost connection after a working session.
+  private hasSyncedOnce = false;
 
   // Self-heal: while degraded, re-drive sync on an exponential backoff so the
   // app recovers on its own — even when the socket never actually dropped (in
@@ -186,6 +190,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       consecutiveFailures: this.consecutiveSyncFailures,
       kind: this.syncHealthStatus === 'degraded' ? this.lastSyncErrorKind : undefined,
       error: this.syncHealthStatus === 'degraded' ? this.lastSyncErrorMessage : undefined,
+      everConnected: this.hasSyncedOnce,
     };
   }
 
@@ -216,6 +221,9 @@ export class Sp00kySync<S extends SchemaStructure> {
   private recordSyncOutcome(ok: boolean, error?: unknown): void {
     if (this.degradeAfterFailures <= 0) return;
     if (ok) {
+      // Latch first-ever success so a UI can drop the connecting phase. Set
+      // before the early return so a clean cold start (0 prior failures) counts.
+      this.hasSyncedOnce = true;
       if (this.consecutiveSyncFailures === 0) return;
       this.consecutiveSyncFailures = 0;
       if (this.syncHealthStatus !== 'healthy') {
@@ -485,21 +493,63 @@ export class Sp00kySync<S extends SchemaStructure> {
    * One poll cycle: refetch `_00_list_ref` for every active query. Returns
    * whether ANY query's remoteArray actually changed — the scheduler uses this
    * to drive the adaptive idle backoff.
+   *
+   * Also the ONLY health signal that runs while the page is idle. Sync health is
+   * otherwise activity-driven (mutations/registrations via the scheduler,
+   * reconnect re-registration, self-heal), so on a quiet page a stale `degraded`
+   * would linger until the next mutation and a genuine idle drop would be
+   * invisible. We fold the cycle's aggregate reachability into `recordSyncOutcome`
+   * so idle health self-recovers (and self-degrades) with no user action. A clean
+   * cycle is idempotent when already healthy (`recordSyncOutcome` early-returns at
+   * `consecutiveSyncFailures === 0`), so a healthy idle page pays nothing.
    */
   private async pollListRefForActiveQueries(): Promise<boolean> {
     const hashes = this.dataModule.getActiveQueryHashes();
-    if (hashes.length === 0) return false;
+    if (hashes.length === 0) {
+      // No active queries to piggyback on, but health still needs a heartbeat —
+      // probe connectivity directly so an idle page with no live queries doesn't
+      // go blind. Cheap, and gated by the same adaptive backoff (≤5s idle cap).
+      try {
+        await this.remote.query('RETURN true');
+        this.recordSyncOutcome(true);
+      } catch (err) {
+        this.recordSyncOutcome(false, err);
+      }
+      return false;
+    }
     let anyChanged = false;
+    // `reached` = the server answered at least once this cycle (a success, or an
+    // *application* error, which still proves reachability). `firstNetworkErr`
+    // holds the first network-classified failure. A cycle that only produced
+    // network errors reports the outcome as a down round; a mixed/app cycle counts
+    // as reached; an all-application cycle reports nothing (that's a query-shape
+    // fault owned by the registration path, not a reachability signal).
+    let reached = false;
+    let firstNetworkErr: unknown;
     for (const hash of hashes) {
       try {
         if (await this.refetchListRefForQuery(hash)) anyChanged = true;
+        reached = true;
       } catch (err) {
+        if (classifySyncError(err) === 'network') {
+          if (firstNetworkErr === undefined) firstNetworkErr = err;
+        } else {
+          reached = true;
+        }
         this.logger.debug(
           { err: (err as Error)?.message ?? err, hash, Category: 'sp00ky-client::Sp00kySync::pollListRefForActiveQueries' },
           'Per-query list_ref poll failed'
         );
       }
     }
+    // Call the private outcome recorder directly rather than routing through the
+    // scheduler — the scheduler only reports on rounds that drained ≥1 queue item
+    // (`processedAny`), and this isn't a queue round.
+    if (reached) {
+      this.recordSyncOutcome(true);
+    } else if (firstNetworkErr !== undefined) {
+      this.recordSyncOutcome(false, firstNetworkErr);
+    }
     return anyChanged;
   }
 

package/src/types.ts

@@ -193,6 +193,13 @@ export interface SyncHealth {
   kind?: 'network' | 'application';
   /** Message of the most recent failure (only set while `degraded`). */
   error?: string;
+  /**
+   * `true` once at least one sync round has succeeded this session. Lets a UI
+   * distinguish a first-time "connecting" phase (never reached the server yet,
+   * so a cold-start failure run is expected) from a real lost connection after
+   * a working session. Never resets back to `false` once set.
+   */
+  everConnected: boolean;
 }
 
 export type QueryHash = string;

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { classifySyncError } from './error-classification';
+
+describe('classifySyncError', () => {
+  it('classifies surreal ConnectionUnavailableError as network', () => {
+    // Thrown synchronously by the WS engine's send() while the socket is down
+    // but reconnect hasn't fired. Message contains "connected", not "connection".
+    const err = new Error(
+      'You must be connected to a SurrealDB instance before performing this operation'
+    );
+    expect(classifySyncError(err)).toBe('network');
+  });
+
+  it('classifies surreal CallTerminatedError as network', () => {
+    const err = new Error(
+      'The call has been terminated because the connection was closed'
+    );
+    expect(classifySyncError(err)).toBe('network');
+  });
+
+  it.each([
+    'WebSocket connection failed',
+    'fetch failed',
+    'connect ECONNREFUSED 127.0.0.1:8666',
+    'request timed out',
+    'The operation was aborted',
+    'socket hang up',
+  ])('classifies %j as network', (message) => {
+    expect(classifySyncError(new Error(message))).toBe('network');
+  });
+
+  it.each([
+    'Permission denied',
+    'There was a problem with the database: record already exists',
+    'Parse error: unexpected token',
+  ])('classifies %j as application', (message) => {
+    expect(classifySyncError(new Error(message))).toBe('application');
+  });
+
+  it('handles non-Error values', () => {
+    expect(classifySyncError('connection reset')).toBe('network');
+    expect(classifySyncError('boom')).toBe('application');
+  });
+});

package/src/utils/error-classification.ts

@@ -1,5 +1,12 @@
 const NETWORK_ERROR_PATTERNS = [
   'connection',
+  // surreal's ConnectionUnavailableError reads "You must be connected to a
+  // SurrealDB instance..." — it contains "connected", not "connection", so it
+  // slips past the pattern above. The WS engine throws it synchronously from
+  // `send()` while the socket is down but reconnect hasn't fired yet, so it's the
+  // canonical error on an idle-dropped socket; classify it as network.
+  'must be connected',
+  'connectionunavailable',
   'timeout',
   'timed out',
   'websocket',