@spooky-sync/core 0.0.1-canary.163 → 0.0.1-canary.165

package/dist/index.d.ts

@@ -119,8 +119,12 @@ declare class ConnectionSupervisor {
   private disposed;
   private heartbeatTimer;
   private heartbeatInFlight;
+  /** Consecutive failed probes. See {@link FAILURES_BEFORE_TEARDOWN}. */
+  private heartbeatFailures;
   private reviveTimer;
   private reviveAttempts;
+  /** Timestamp of the last wake-triggered probe, for rate limiting. */
+  private lastWakeProbeAt;
   private reviving;
   /**
    * Set while the browser reports itself offline. Retrying a socket against a
@@ -129,6 +133,23 @@ declare class ConnectionSupervisor {
   private suspended;
   private teardown;
   private static readonly REVIVE_BASE_MS;
+  /**
+   * How many consecutive heartbeat failures it takes to tear the socket down.
+   *
+   * The probe rides the same serialized queue as every other RPC (deliberately
+   * — see {@link beat}), which means it cannot distinguish a WEDGED queue from
+   * a merely BUSY one. A single slow window (a large sync burst, one heavy
+   * app query) used to be enough to force-close a perfectly healthy socket,
+   * and the resulting reconnect re-registered every active query about a
+   * second later. That self-inflicted teardown manufactured the very reconnect
+   * storms this class exists to survive. A genuinely dead socket still fails
+   * every probe, so it is torn down one interval later than before.
+   */
+  private static readonly FAILURES_BEFORE_TEARDOWN;
+  /** Retry delay after an inconclusive (first) heartbeat failure. */
+  private static readonly HEARTBEAT_RETRY_MS;
+  /** Floor between probes triggered by wake events (tab focus, pageshow). */
+  private static readonly WAKE_PROBE_MIN_INTERVAL_MS;
   constructor(remote: RemoteDatabaseService, logger: Logger$1, config?: Required<ReconnectConfig>);
   /** Latest observed transport state. */
   get connection(): ConnectionState;
@@ -1068,6 +1089,14 @@ declare class Sp00kySync<S extends SchemaStructure> {
    * initial connect. See {@link subscribeToReconnect}.
    */
   private needsResubscribe;
+  /** When the last reconnect-driven full refetch ran, for burst coalescing. */
+  private lastReconnectRefetchAt;
+  /**
+   * Minimum gap between reconnect-driven full refetches. Long enough to absorb
+   * a flapping socket (the SDK reconnect ladder starts at 1s), short enough
+   * that a genuine drop minutes later still refetches.
+   */
+  private static readonly RECONNECT_REFETCH_COOLDOWN_MS;
   events: SyncEventSystem;
   private currentUserId;
   private tabRole;
@@ -1883,6 +1912,13 @@ declare class BlobCache {
   private readonly inflight;
   private flushTimer;
   private readonly onPageHide;
+  /**
+   * Resolves once the manifest has been reconciled against disk. Reads await
+   * it, so `start()` does NOT have to be awaited on the boot path — blocking
+   * boot on an OPFS directory walk delayed the WebSocket connect (and with it
+   * the connection supervisor) for no benefit.
+   */
+  private ready;
   private hits;
   private misses;
   private evictedEntries;

package/dist/index.js

@@ -1081,8 +1081,12 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 	disposed = false;
 	heartbeatTimer = null;
 	heartbeatInFlight = false;
+	/** Consecutive failed probes. See {@link FAILURES_BEFORE_TEARDOWN}. */
+	heartbeatFailures = 0;
 	reviveTimer = null;
 	reviveAttempts = 0;
+	/** Timestamp of the last wake-triggered probe, for rate limiting. */
+	lastWakeProbeAt = 0;
 	reviving = false;
 	/**
 	* Set while the browser reports itself offline. Retrying a socket against a
@@ -1091,6 +1095,23 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 	suspended = false;
 	teardown = [];
 	static REVIVE_BASE_MS = 1e3;
+	/**
+	* How many consecutive heartbeat failures it takes to tear the socket down.
+	*
+	* The probe rides the same serialized queue as every other RPC (deliberately
+	* — see {@link beat}), which means it cannot distinguish a WEDGED queue from
+	* a merely BUSY one. A single slow window (a large sync burst, one heavy
+	* app query) used to be enough to force-close a perfectly healthy socket,
+	* and the resulting reconnect re-registered every active query about a
+	* second later. That self-inflicted teardown manufactured the very reconnect
+	* storms this class exists to survive. A genuinely dead socket still fails
+	* every probe, so it is torn down one interval later than before.
+	*/
+	static FAILURES_BEFORE_TEARDOWN = 2;
+	/** Retry delay after an inconclusive (first) heartbeat failure. */
+	static HEARTBEAT_RETRY_MS = 5e3;
+	/** Floor between probes triggered by wake events (tab focus, pageshow). */
+	static WAKE_PROBE_MIN_INTERVAL_MS = 1e4;
 	constructor(remote, logger, config) {
 		this.remote = remote;
 		this.logger = logger.child({ service: "ConnectionSupervisor" });
@@ -1244,12 +1265,26 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 		this.heartbeatInFlight = true;
 		try {
 			await withTimeout(this.remote.query("RETURN true"), this.config.heartbeatTimeoutMs, `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`);
+			this.heartbeatFailures = 0;
 			this.startHeartbeat();
 		} catch (err) {
+			this.heartbeatFailures++;
+			if (this.heartbeatFailures < ConnectionSupervisor.FAILURES_BEFORE_TEARDOWN) {
+				this.logger.debug({
+					err,
+					failures: this.heartbeatFailures,
+					Category: "sp00ky-client::ConnectionSupervisor::heartbeat"
+				}, "Heartbeat failed; re-probing before tearing the socket down");
+				this.stopHeartbeat();
+				if (!this.disposed && !this.suspended) this.heartbeatTimer = setTimeout(() => void this.beat(), Math.min(ConnectionSupervisor.HEARTBEAT_RETRY_MS, this.config.heartbeatIntervalMs));
+				return;
+			}
 			this.logger.warn({
 				err,
+				failures: this.heartbeatFailures,
 				Category: "sp00ky-client::ConnectionSupervisor::heartbeat"
-			}, "Heartbeat failed; tearing the socket down to force a reconnect");
+			}, "Heartbeat failed repeatedly; tearing the socket down to force a reconnect");
+			this.heartbeatFailures = 0;
 			await this.remote.forceClose();
 			if (this.remote.getStatus() !== "connected") this.scheduleRevive();
 		} finally {
@@ -1297,6 +1332,9 @@ var ConnectionSupervisor = class ConnectionSupervisor {
 	*/
 	wake(reason) {
 		if (this.disposed || this.suspended) return;
+		const now = Date.now();
+		if (this.remote.getStatus() === "connected" && now - this.lastWakeProbeAt < ConnectionSupervisor.WAKE_PROBE_MIN_INTERVAL_MS) return;
+		this.lastWakeProbeAt = now;
 		this.logger.debug({
 			reason,
 			state: this.state,
@@ -5277,6 +5315,14 @@ var Sp00kySync = class Sp00kySync {
 	* initial connect. See {@link subscribeToReconnect}.
 	*/
 	needsResubscribe = false;
+	/** When the last reconnect-driven full refetch ran, for burst coalescing. */
+	lastReconnectRefetchAt = 0;
+	/**
+	* Minimum gap between reconnect-driven full refetches. Long enough to absorb
+	* a flapping socket (the SDK reconnect ladder starts at 1s), short enough
+	* that a genuine drop minutes later still refetches.
+	*/
+	static RECONNECT_REFETCH_COOLDOWN_MS = 1e4;
 	events = createSyncEventSystem();
 	currentUserId = null;
 	tabRole = "solo";
@@ -5902,8 +5948,21 @@ var Sp00kySync = class Sp00kySync {
 		client.subscribe("connected", () => {
 			if (!this.needsResubscribe) return;
 			this.needsResubscribe = false;
-			this.logger.info({ Category: "sp00ky-client::Sp00kySync::onReconnect" }, "Remote reconnected, refetching active queries");
-			for (const hash of this.dataModule.getActiveQueryHashes()) this.scheduler.enqueueDownEvent({
+			const sinceLast = Date.now() - this.lastReconnectRefetchAt;
+			if (sinceLast < Sp00kySync.RECONNECT_REFETCH_COOLDOWN_MS) {
+				this.logger.debug({
+					sinceLast,
+					Category: "sp00ky-client::Sp00kySync::onReconnect"
+				}, "Reconnected again within the cooldown; skipping duplicate refetch");
+				return;
+			}
+			this.lastReconnectRefetchAt = Date.now();
+			const hashes = this.dataModule.getActiveQueryHashes();
+			this.logger.info({
+				queries: hashes.length,
+				Category: "sp00ky-client::Sp00kySync::onReconnect"
+			}, "Remote reconnected, refetching active queries");
+			for (const hash of hashes) this.scheduler.enqueueDownEvent({
 				type: "register",
 				payload: { hash }
 			});
@@ -6484,8 +6543,8 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.163";
-const WASM_VERSION = "0.0.1-canary.163";
+const CORE_VERSION = "0.0.1-canary.165";
+const WASM_VERSION = "0.0.1-canary.165";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -10071,6 +10130,13 @@ var BlobCache = class {
 	onPageHide = () => {
 		this.manifest.flush();
 	};
+	/**
+	* Resolves once the manifest has been reconciled against disk. Reads await
+	* it, so `start()` does NOT have to be awaited on the boot path — blocking
+	* boot on an OPFS directory walk delayed the WebSocket connect (and with it
+	* the connection supervisor) for no benefit.
+	*/
+	ready = Promise.resolve();
 	hits = 0;
 	misses = 0;
 	evictedEntries = 0;
@@ -10102,6 +10168,7 @@ var BlobCache = class {
 	* Returns null when the file does not exist remotely and is not cached.
 	*/
 	async read(key, options = {}) {
+		await this.ready;
 		const id = blobKeyId(key);
 		const persist = options.persist !== false && !this.persistDisabled;
 		if (!options.reload) {
@@ -10413,7 +10480,8 @@ var BlobCache = class {
 	*  it lands on is the one the store was constructed with. */
 	async start(namespace) {
 		this.store.setNamespace(namespace);
-		await this.reconcile();
+		this.ready = this.reconcile().catch(() => {});
+		await this.ready;
 	}
 	/** Repoint at another local bucket. The bytes of the old one stay on disk so
 	*  switching back (or signing back in) is still warm. */
@@ -10425,7 +10493,8 @@ var BlobCache = class {
 		this.manifest.reset();
 		this.store.setNamespace(namespace);
 		this.persistPaused = false;
-		await this.reconcile();
+		this.ready = this.reconcile().catch(() => {});
+		await this.ready;
 	}
 	setMaxBytes(maxBytes) {
 		this.maxBytes = maxBytes;
@@ -10815,7 +10884,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.163",
+				coreVersion: "0.0.1-canary.165",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -10954,18 +11023,20 @@ var Sp00kyClient = class {
 				await this.migrator.provision(this.config.schemaSurql);
 				this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Schema provisioned");
 			}
-			try {
-				this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
-				await this.blobs.start(bootBucket);
-			} catch (e) {
-				this.logger.warn({
-					err: e,
-					Category: "sp00ky-client::Sp00kyClient::init"
-				}, "Blob cache failed to start; bucket files will not be cached locally");
-			}
 			await this.remote.connect();
 			this.connectionSupervisor.start();
 			this.logger.debug({ Category: "sp00ky-client::Sp00kyClient::init" }, "Remote database connected");
+			(async () => {
+				try {
+					this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
+					await this.blobs.start(bootBucket);
+				} catch (e) {
+					this.logger.warn({
+						err: e,
+						Category: "sp00ky-client::Sp00kyClient::init"
+					}, "Blob cache failed to start; bucket files will not be cached locally");
+				}
+			})();
 			this.streamProcessor.setStateKeySuffix(bootBucket);
 			await this.streamProcessor.init();
 			this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.163",
+  "version": "0.0.1-canary.165",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.163",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.163",
+    "@spooky-sync/query-builder": "0.0.1-canary.165",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.165",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/modules/sync/sync.ts

@@ -107,6 +107,14 @@ export class Sp00kySync<S extends SchemaStructure> {
    * initial connect. See {@link subscribeToReconnect}.
    */
   private needsResubscribe: boolean = false;
+  /** When the last reconnect-driven full refetch ran, for burst coalescing. */
+  private lastReconnectRefetchAt = 0;
+  /**
+   * Minimum gap between reconnect-driven full refetches. Long enough to absorb
+   * a flapping socket (the SDK reconnect ladder starts at 1s), short enough
+   * that a genuine drop minutes later still refetches.
+   */
+  private static readonly RECONNECT_REFETCH_COOLDOWN_MS = 10_000;
   public events = createSyncEventSystem();
 
   // Auth identity that drives per-user `_00_list_ref_user_<id>` routing
@@ -1034,11 +1042,26 @@ export class Sp00kySync<S extends SchemaStructure> {
     client.subscribe('connected', () => {
       if (!this.needsResubscribe) return;
       this.needsResubscribe = false;
+      // A flapping socket produces reconnecting -> connected repeatedly, and
+      // each cycle used to re-register EVERY active query (a busy app has
+      // dozens). That is the "everything reloads about a second after a blip"
+      // symptom: the SDK's retryDelay is 1s, so the refetch lands right after
+      // the drop the user never saw. Collapse bursts into one refetch.
+      const sinceLast = Date.now() - this.lastReconnectRefetchAt;
+      if (sinceLast < Sp00kySync.RECONNECT_REFETCH_COOLDOWN_MS) {
+        this.logger.debug(
+          { sinceLast, Category: 'sp00ky-client::Sp00kySync::onReconnect' },
+          'Reconnected again within the cooldown; skipping duplicate refetch'
+        );
+        return;
+      }
+      this.lastReconnectRefetchAt = Date.now();
+      const hashes = this.dataModule.getActiveQueryHashes();
       this.logger.info(
-        { Category: 'sp00ky-client::Sp00kySync::onReconnect' },
+        { queries: hashes.length, Category: 'sp00ky-client::Sp00kySync::onReconnect' },
         'Remote reconnected, refetching active queries'
       );
-      for (const hash of this.dataModule.getActiveQueryHashes()) {
+      for (const hash of hashes) {
         this.scheduler.enqueueDownEvent({ type: 'register', payload: { hash } });
       }
       // The WS reconnect leaves the server-side LIVE subscription dead — the

package/src/services/blobs/blob-cache.test.ts

@@ -304,6 +304,24 @@ describe('BlobCache namespaces', () => {
     expect(fetchRemote).toHaveBeenCalledTimes(2);
   });
 
+  it('a read issued before start() finishes waits for the reconcile', async () => {
+    // Boot fires start() without awaiting it (the OPFS walk must not delay the
+    // WebSocket connect). A read landing mid-walk must still see the rebuilt
+    // manifest rather than refetching a file that is already on disk.
+    const { cache, manifest, local, fetchRemote } = setup();
+    await cache.read(KEY);
+    await cache.flush();
+    local.rows.clear();
+    manifest.reset();
+
+    const starting = cache.start('user-1');
+    const readDuringStart = cache.read(KEY);
+    await Promise.all([starting, readDuringStart]);
+
+    expect(await readDuringStart).not.toBeNull();
+    expect(fetchRemote).toHaveBeenCalledTimes(1);
+  });
+
   it('clear() drops the current namespace', async () => {
     const { cache, store } = setup();
     await cache.read(KEY);

package/src/services/blobs/blob-cache.ts

@@ -127,6 +127,14 @@ export class BlobCache {
     void this.manifest.flush();
   };
 
+  /**
+   * Resolves once the manifest has been reconciled against disk. Reads await
+   * it, so `start()` does NOT have to be awaited on the boot path — blocking
+   * boot on an OPFS directory walk delayed the WebSocket connect (and with it
+   * the connection supervisor) for no benefit.
+   */
+  private ready: Promise<void> = Promise.resolve();
+
   private hits = 0;
   private misses = 0;
   private evictedEntries = 0;
@@ -167,6 +175,10 @@ export class BlobCache {
    * Returns null when the file does not exist remotely and is not cached.
    */
   async read(key: BlobKey, options: BlobReadOptions = {}): Promise<Blob | null> {
+    // Boot fires `start()` without awaiting it; a read that lands first must
+    // not race the reconcile, or it would refetch a file already on disk and
+    // then overwrite the row reconcile is about to rebuild.
+    await this.ready;
     const id = blobKeyId(key);
     const persist = options.persist !== false && !this.persistDisabled;
 
@@ -514,7 +526,12 @@ export class BlobCache {
    *  it lands on is the one the store was constructed with. */
   async start(namespace: string): Promise<void> {
     this.store.setNamespace(namespace);
-    await this.reconcile();
+    // Publish the in-flight reconcile so reads issued before it finishes queue
+    // behind it instead of racing it. Swallow here: `reconcile()` already logs,
+    // and an unhandled rejection on a fire-and-forget boot call must not
+    // surface as a global error.
+    this.ready = this.reconcile().catch(() => {});
+    await this.ready;
   }
 
   /** Repoint at another local bucket. The bytes of the old one stay on disk so
@@ -527,7 +544,8 @@ export class BlobCache {
     this.manifest.reset();
     this.store.setNamespace(namespace);
     this.persistPaused = false;
-    await this.reconcile();
+    this.ready = this.reconcile().catch(() => {});
+    await this.ready;
   }
 
   setMaxBytes(maxBytes: number): void {

package/src/services/database/connection-supervisor.test.ts

@@ -142,7 +142,13 @@ describe('ConnectionSupervisor', () => {
     expect(remote.query).toHaveBeenCalledWith('RETURN true');
     expect(remote.forceClose).not.toHaveBeenCalled();
 
+    // One failure is inconclusive — the probe shares a queue with ordinary
+    // traffic, so it re-probes rather than tearing down a possibly-fine socket.
     await vi.advanceTimersByTimeAsync(CONFIG.heartbeatTimeoutMs);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+
+    // The second consecutive failure is the one that tears it down.
+    await vi.advanceTimersByTimeAsync(5_000 + CONFIG.heartbeatTimeoutMs);
     expect(remote.forceClose).toHaveBeenCalledTimes(1);
 
     // The forced close published `disconnected`, so the revive loop takes over.
@@ -152,6 +158,34 @@ describe('ConnectionSupervisor', () => {
     sup.dispose();
   });
 
+  it('does not tear down a healthy socket after a single slow probe', async () => {
+    // The regression this guards: the heartbeat rides the same serialized queue
+    // as every other RPC, so one busy window (a big sync burst) used to
+    // force-close a working connection — and the reconnect then re-registered
+    // every active query about a second later.
+    const { remote, emit } = makeRemote();
+    let calls = 0;
+    remote.query.mockImplementation(() => {
+      calls++;
+      // First probe hangs past its deadline, the next answers normally.
+      return calls === 1 ? new Promise(() => {}) : Promise.resolve(true);
+    });
+
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    await vi.advanceTimersByTimeAsync(CONFIG.heartbeatIntervalMs + CONFIG.heartbeatTimeoutMs);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+
+    // The retry succeeds, so the socket survives and heartbeating continues.
+    await vi.advanceTimersByTimeAsync(5_000 + CONFIG.heartbeatIntervalMs * 2);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+    expect(sup.connection).toBe('connected');
+
+    sup.dispose();
+  });
+
   it('keeps heartbeating while the connection is healthy', async () => {
     const { remote, emit } = makeRemote();
     const sup = makeSupervisor(remote);

package/src/services/database/connection-supervisor.ts

@@ -40,9 +40,13 @@ export class ConnectionSupervisor {
 
   private heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   private heartbeatInFlight = false;
+  /** Consecutive failed probes. See {@link FAILURES_BEFORE_TEARDOWN}. */
+  private heartbeatFailures = 0;
 
   private reviveTimer: ReturnType<typeof setTimeout> | null = null;
   private reviveAttempts = 0;
+  /** Timestamp of the last wake-triggered probe, for rate limiting. */
+  private lastWakeProbeAt = 0;
   private reviving = false;
   /**
    * Set while the browser reports itself offline. Retrying a socket against a
@@ -53,6 +57,23 @@ export class ConnectionSupervisor {
   private teardown: Array<() => void> = [];
 
   private static readonly REVIVE_BASE_MS = 1_000;
+  /**
+   * How many consecutive heartbeat failures it takes to tear the socket down.
+   *
+   * The probe rides the same serialized queue as every other RPC (deliberately
+   * — see {@link beat}), which means it cannot distinguish a WEDGED queue from
+   * a merely BUSY one. A single slow window (a large sync burst, one heavy
+   * app query) used to be enough to force-close a perfectly healthy socket,
+   * and the resulting reconnect re-registered every active query about a
+   * second later. That self-inflicted teardown manufactured the very reconnect
+   * storms this class exists to survive. A genuinely dead socket still fails
+   * every probe, so it is torn down one interval later than before.
+   */
+  private static readonly FAILURES_BEFORE_TEARDOWN = 2;
+  /** Retry delay after an inconclusive (first) heartbeat failure. */
+  private static readonly HEARTBEAT_RETRY_MS = 5_000;
+  /** Floor between probes triggered by wake events (tab focus, pageshow). */
+  private static readonly WAKE_PROBE_MIN_INTERVAL_MS = 10_000;
 
   constructor(
     private readonly remote: RemoteDatabaseService,
@@ -264,12 +285,40 @@ export class ConnectionSupervisor {
         this.config.heartbeatTimeoutMs,
         `Heartbeat timed out after ${this.config.heartbeatTimeoutMs}ms`
       );
+      this.heartbeatFailures = 0;
       this.startHeartbeat();
     } catch (err) {
+      this.heartbeatFailures++;
+      if (this.heartbeatFailures < ConnectionSupervisor.FAILURES_BEFORE_TEARDOWN) {
+        // Inconclusive: the probe shares a queue with ordinary traffic, so this
+        // may just be a busy window rather than a dead socket. Re-probe soon
+        // instead of tearing down a connection that is probably fine.
+        this.logger.debug(
+          {
+            err,
+            failures: this.heartbeatFailures,
+            Category: 'sp00ky-client::ConnectionSupervisor::heartbeat',
+          },
+          'Heartbeat failed; re-probing before tearing the socket down'
+        );
+        this.stopHeartbeat();
+        if (!this.disposed && !this.suspended) {
+          this.heartbeatTimer = setTimeout(
+            () => void this.beat(),
+            Math.min(ConnectionSupervisor.HEARTBEAT_RETRY_MS, this.config.heartbeatIntervalMs)
+          );
+        }
+        return;
+      }
       this.logger.warn(
-        { err, Category: 'sp00ky-client::ConnectionSupervisor::heartbeat' },
-        'Heartbeat failed; tearing the socket down to force a reconnect'
+        {
+          err,
+          failures: this.heartbeatFailures,
+          Category: 'sp00ky-client::ConnectionSupervisor::heartbeat',
+        },
+        'Heartbeat failed repeatedly; tearing the socket down to force a reconnect'
       );
+      this.heartbeatFailures = 0;
       // Force the `close` the transport never delivered. The resulting
       // `disconnected` event drives the revive loop.
       await this.remote.forceClose();
@@ -332,6 +381,21 @@ export class ConnectionSupervisor {
    */
   private wake(reason: string): void {
     if (this.disposed || this.suspended) return;
+    // `visibilitychange` fires on every alt-tab, every window minimise and every
+    // focus change. Probing a connected socket each time meant an ordinary
+    // afternoon of tab-switching issued a steady stream of extra RPCs, each of
+    // which could trip the heartbeat teardown above. A healthy socket does not
+    // become unhealthy because the user looked away for four seconds, so probes
+    // from wake triggers are rate-limited; a genuinely dead socket is still
+    // caught by the regular heartbeat.
+    const now = Date.now();
+    if (
+      this.remote.getStatus() === 'connected' &&
+      now - this.lastWakeProbeAt < ConnectionSupervisor.WAKE_PROBE_MIN_INTERVAL_MS
+    ) {
+      return;
+    }
+    this.lastWakeProbeAt = now;
     this.logger.debug(
       { reason, state: this.state, Category: 'sp00ky-client::ConnectionSupervisor::wake' },
       'Wake trigger; probing the connection'

package/src/sp00ky.ts

@@ -706,20 +706,6 @@ export class Sp00kyClient<S extends SchemaStructure> {
         this.logger.debug({ Category: 'sp00ky-client::Sp00kyClient::init' }, 'Schema provisioned');
       }
 
-      // After the store is open (the manifest lives in it) and after
-      // provisioning (`_00_blob` has to exist), before any query can ask for a
-      // file. Best-effort: a cold blob cache is a slow first paint, not a
-      // broken client.
-      try {
-        this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
-        await this.blobs.start(bootBucket);
-      } catch (e) {
-        this.logger.warn(
-          { err: e, Category: 'sp00ky-client::Sp00kyClient::init' },
-          'Blob cache failed to start; bucket files will not be cached locally'
-        );
-      }
-
       await this.remote.connect();
       // Start supervising only after the first connect succeeds, so a boot-time
       // failure surfaces as a thrown init() rather than being silently absorbed
@@ -730,6 +716,25 @@ export class Sp00kyClient<S extends SchemaStructure> {
         'Remote database connected'
       );
 
+      // Warm the blob cache in the background. Deliberately NOT awaited, and
+      // deliberately after `remote.connect()`: this walks the OPFS directory to
+      // rebuild the manifest, and awaiting it ahead of the socket delayed the
+      // connect (and the connection supervisor with it) for no benefit. Reads
+      // await `BlobCache.ready` internally, so a bucket read that lands mid-walk
+      // still sees a reconciled manifest. Best-effort: a cold blob cache is a
+      // slow first image, not a broken client.
+      void (async () => {
+        try {
+          this.blobs.setMaxBytes(await resolveBlobBudget(this.config.blobCache?.maxBytes));
+          await this.blobs.start(bootBucket);
+        } catch (e) {
+          this.logger.warn(
+            { err: e, Category: 'sp00ky-client::Sp00kyClient::init' },
+            'Blob cache failed to start; bucket files will not be cached locally'
+          );
+        }
+      })();
+
       this.streamProcessor.setStateKeySuffix(bootBucket);
       await this.streamProcessor.init();
       // Seed table `select` permissions from the schema before any query is