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

package/dist/index.d.ts

@@ -693,6 +693,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",
@@ -2917,20 +2919,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 +3512,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.101";
+const WASM_VERSION = "0.0.1-canary.101";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.100",
+  "version": "0.0.1-canary.101",
   "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.101",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.101",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

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

@@ -0,0 +1,116 @@
+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');
+  });
+});

package/src/modules/sync/sync.ts

@@ -485,21 +485,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/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',