@spooky-sync/core 0.0.1-canary.155 → 0.0.1-canary.157

package/src/modules/devtools/storage-info.ts

@@ -31,10 +31,37 @@ export interface EngineStorageDiagnostics {
   error?: string;
 }
 
+/**
+ * Shared-tabs coordination state. Reported ONLY when `sharedTabs: true` was
+ * configured (apps that never asked for it get `null`, so the panel shows
+ * nothing). `active: false` with a `reason` is itself the useful signal: the
+ * app asked to share one store and this tab is not, so it owns or contends for
+ * the OPFS pool alone.
+ */
+export interface SharedTabsInfo {
+  active: boolean;
+  /** Why inactive: a capability gate reason, or 'fell-back' when the broker
+   *  was reachable but no role landed (election timeout, rejected tab). */
+  reason?: string;
+  role?: 'solo' | 'leader' | 'follower';
+  /** This tab's id (also the suffix of every mutation id it mints). */
+  tabId?: string;
+  /** Monotonic id of the current leadership term; embedded in the worker lock. */
+  leadershipId?: number;
+  /** Who owns the store: this tab when leader, else the leader's tab id. */
+  leaderTabId?: string | null;
+  /** Leader only: attached follower tabs. */
+  followers?: number;
+  /** Leader only: ingest batches relayed to followers so far. */
+  relayedBatches?: number;
+}
+
 export interface StorageInfo {
   at: number;
   engine: { kind: 'surrealdb' | 'sqlite' | 'custom'; store: string; bucketId: string };
   health: { status: 'unknown' | 'persistent' | 'memory'; fallback: boolean; error?: string };
+  /** Shared-tabs state, or null when the feature was never requested. */
+  tabs?: SharedTabsInfo | null;
   browser: {
     /** `navigator.storage.persisted()` — whether the origin's storage is
      *  exempt from eviction (unrelated to the OPFS pool lock). */

package/src/services/stream-processor/index.ts

@@ -57,6 +57,21 @@ export interface StreamUpdateReceiver {
   onStreamUpdate(update: StreamUpdate): void;
 }
 
+/**
+ * Read a circuit snapshot out of the pre-`persistCircuit` persisted shape
+ * (`[[{ state }]]`, a raw SurrealDB result). Returns null for anything else.
+ */
+function extractLegacyState(result: unknown): string | null {
+  if (
+    Array.isArray(result) &&
+    Array.isArray(result[0]) &&
+    typeof result[0][0]?.state === 'string'
+  ) {
+    return result[0][0].state;
+  }
+  return null;
+}
+
 export class StreamProcessorService {
   private logger: Logger;
   private processor: WasmProcessor | undefined;
@@ -89,6 +104,32 @@ export class StreamProcessorService {
   // stomp the leader's snapshot under the same key (the pre-existing cross-tab
   // localStorage hazard); a promoted follower flips this back on.
   private persistState = true;
+  // Snapshot persistence is OPT-IN and off by default (`persistCircuit`).
+  //
+  // `Circuit::save` deep-clones the WHOLE store (every row of every ingested
+  // table, full bodies) plus every view cache and JSON-encodes the result. It
+  // used to run from `ingest`, `flushCoalescing`, `registerQueryPlan` and
+  // `unregisterQueryPlan`, i.e. once per sync batch AND once per query
+  // register/unregister. On a 3.7k-game collection whose list registers and
+  // drops one windowed query per 50 rows scrolled, that measured 220 whole-store
+  // serializations and ~1 GB of transient JSON for a single scroll, 5.5x the
+  // wall time of the same ingests without it, and it doubled the wasm heap
+  // high-water mark (wasm32 dlmalloc never returns pages, so the peak is
+  // permanent). It also ran the encode a second time in
+  // `LocalStoragePersistenceClient.set` and wrote it synchronously on the main
+  // thread. All of it was dead weight: `loadState`'s shape check could never
+  // match what either shipped persistence client returns, so the browser never
+  // restored a snapshot, and first paint comes from the local SQLite store
+  // anyway.
+  //
+  // When enabled, we mark the circuit dirty and let a checkpoint timer (plus a
+  // `pagehide` flush) do at most one snapshot per interval, mirroring
+  // `ssp-node`'s "NEVER per-ingest" rule.
+  private persistCircuit = false;
+  private checkpointMs = 30_000;
+  private checkpointTimer: ReturnType<typeof setInterval> | null = null;
+  private snapshotDirty = false;
+  private pagehideHandler: (() => void) | null = null;
 
   constructor(
     public events: EventSystem<StreamProcessorEvents>,
@@ -201,10 +242,7 @@ export class StreamProcessorService {
     if (buffered.length > 0) {
       this.dispatchUpdates(buffered);
     }
-    // The processor state after the last ingest is cumulative, so a single
-    // snapshot covers the whole batch. Kept fire-and-forget like the per-ingest
-    // call it replaces.
-    this.saveState();
+    this.markSnapshotDirty();
   }
 
   /**
@@ -265,32 +303,120 @@ export class StreamProcessorService {
     this.stateGeneration++;
     this.batching = false;
     this.batchBuffer.clear();
+    this.snapshotDirty = false;
+    const previous = this.processor;
     this.processor = new Sp00kyProcessor() as unknown as WasmProcessor;
+    this.freeProcessor(previous);
     this.logger.info(
       { Category: 'sp00ky-client::StreamProcessorService::reset' },
       'Stream processor reset (fresh circuit)'
     );
   }
 
+  /**
+   * Release the wasm circuit and stop checkpointing. Call when the client is
+   * torn down; a recreated client (provider remount, HMR) would otherwise stack
+   * one full circuit per instance.
+   */
+  dispose(): void {
+    this.stopCheckpoints();
+    const previous = this.processor;
+    this.processor = undefined;
+    this.isInitialized = false;
+    this.batching = false;
+    this.batchBuffer.clear();
+    this.receivers = [];
+    this.freeProcessor(previous);
+  }
+
+  /**
+   * Explicitly run the wasm-bindgen destructor. Guarded: stale wasm builds may
+   * not expose `free`, and a double free must not take the app down.
+   */
+  private freeProcessor(processor: WasmProcessor | undefined): void {
+    if (!processor || typeof processor.free !== 'function') return;
+    try {
+      processor.free();
+    } catch (e) {
+      this.logger.debug(
+        { error: e, Category: 'sp00ky-client::StreamProcessorService::freeProcessor' },
+        'Failed to free previous wasm circuit'
+      );
+    }
+  }
+
   /** Toggle circuit-state persistence (shared-tabs follower/leader role). */
   setPersistenceEnabled(enabled: boolean): void {
     this.persistState = enabled;
+    if (!enabled) this.stopCheckpoints();
+  }
+
+  /**
+   * Opt into snapshot persistence (`persistCircuit`). Off by default: see the
+   * `persistCircuit` field comment for why per-ingest snapshots were removed.
+   * Must be called before `init()` for a snapshot to be restored at boot.
+   */
+  configureCircuitPersistence(enabled: boolean, checkpointMs?: number): void {
+    this.persistCircuit = enabled;
+    if (checkpointMs && checkpointMs > 0) this.checkpointMs = checkpointMs;
+    if (!enabled) this.stopCheckpoints();
+  }
+
+  /**
+   * Record that the circuit changed. Cheap and O(1), the expensive snapshot is
+   * deferred to the checkpoint timer, and skipped entirely when
+   * `persistCircuit` is off (the default).
+   */
+  private markSnapshotDirty(): void {
+    if (!this.persistCircuit || !this.persistState) return;
+    this.snapshotDirty = true;
+    this.startCheckpoints();
+  }
+
+  private startCheckpoints(): void {
+    if (this.checkpointTimer) return;
+    this.checkpointTimer = setInterval(() => {
+      if (!this.snapshotDirty) return;
+      this.snapshotDirty = false;
+      void this.saveState();
+    }, this.checkpointMs);
+    // Node/test environments have no `window`; the interval alone is enough there.
+    if (typeof window !== 'undefined' && !this.pagehideHandler) {
+      this.pagehideHandler = () => {
+        if (!this.snapshotDirty) return;
+        this.snapshotDirty = false;
+        void this.saveState();
+      };
+      window.addEventListener('pagehide', this.pagehideHandler);
+    }
+  }
+
+  /** Stop checkpointing and drop the `pagehide` listener. */
+  stopCheckpoints(): void {
+    if (this.checkpointTimer) {
+      clearInterval(this.checkpointTimer);
+      this.checkpointTimer = null;
+    }
+    if (this.pagehideHandler && typeof window !== 'undefined') {
+      window.removeEventListener('pagehide', this.pagehideHandler);
+    }
+    this.pagehideHandler = null;
+    this.snapshotDirty = false;
   }
 
   async loadState() {
-    if (!this.processor || !this.persistState) return;
+    if (!this.processor || !this.persistState || !this.persistCircuit) return;
     try {
       const result = await this.persistenceClient.get(this.stateKey());
 
-      // Check if we have a valid result from the query
-      if (
-        Array.isArray(result) &&
-        result.length > 0 &&
-        Array.isArray(result[0]) &&
-        result[0].length > 0 &&
-        result[0][0]?.state
-      ) {
-        const state = result[0][0].state;
+      // `save_state` returns a JSON string and every PersistenceClient round-trips
+      // it as one: localStorage via JSON.parse(getItem(...)), surrealdb via
+      // `_00_kv:<key>.val`. This used to test for a raw SurrealDB result shape
+      // (`result[0][0].state`), which no shipped client can ever produce, so the
+      // browser wrote a snapshot on every ingest and never restored one. The legacy
+      // shape is still accepted so an old persisted row still loads.
+      const state = typeof result === 'string' ? result : extractLegacyState(result);
+      if (state) {
         this.logger.info(
           {
             stateLength: state.length,
@@ -369,7 +495,7 @@ export class StreamProcessorService {
   }
 
   async saveState() {
-    if (!this.processor || !this.persistState) return;
+    if (!this.processor || !this.persistState || !this.persistCircuit) return;
     const generation = this.stateGeneration;
     try {
       // Assuming processor has a save_state method that returns the state string/bytes
@@ -454,10 +580,10 @@ export class StreamProcessorService {
         // Direct handler call instead of event
         this.notifyUpdates(updates);
       }
-      // While batching (inside `ingestMany`), `flushCoalescing` persists once
-      // for the whole batch — skip the redundant per-record snapshot here.
+      // While batching (inside `ingestMany`), `flushCoalescing` marks dirty once
+      // for the whole batch, skip the redundant per-record mark here.
       if (!this.batching) {
-        this.saveState();
+        this.markSnapshotDirty();
       }
       return rawUpdates;
     } catch (e) {
@@ -534,7 +660,7 @@ export class StreamProcessorService {
           snapshotMs: initialUpdate.timing_snapshot_ms ?? 0,
         },
       };
-      this.saveState();
+      this.markSnapshotDirty();
       this.logger.debug(
         {
           queryHash: queryPlan.queryHash,
@@ -561,7 +687,7 @@ export class StreamProcessorService {
     if (!this.processor) return;
     try {
       this.processor.unregister_view(queryHash);
-      this.saveState();
+      this.markSnapshotDirty();
     } catch (e) {
       this.logger.error(
         { error: e, Category: 'sp00ky-client::StreamProcessorService::unregisterQueryPlan' },

package/src/services/stream-processor/stream-processor.reset.test.ts

@@ -18,6 +18,7 @@ vi.mock('@spooky-sync/ssp-wasm', () => ({
       set_permissions: vi.fn(),
       save_state: vi.fn(() => 'state-bytes'),
       load_state: vi.fn(),
+      free: vi.fn(),
     };
     processorInstances.push(instance);
     return instance;
@@ -44,7 +45,12 @@ function makeService() {
     get: vi.fn(async () => null),
     remove: vi.fn(async () => {}),
   };
-  const service = new StreamProcessorService({} as any, {} as any, persistence as any, silentLogger);
+  const service = new StreamProcessorService(
+    {} as any,
+    {} as any,
+    persistence as any,
+    silentLogger
+  );
   return { service, persistence, persisted };
 }
 
@@ -83,6 +89,7 @@ describe('StreamProcessorService.reset', () => {
 
   it('routes persisted state to the per-bucket key', async () => {
     const { service, persistence } = makeService();
+    service.configureCircuitPersistence(true);
     await service.init();
     service.setStateKeySuffix('u1');
     await service.saveState();
@@ -91,8 +98,9 @@ describe('StreamProcessorService.reset', () => {
 
   it('drops a saveState that raced a reset (old circuit never persists into the new key)', async () => {
     const { service, persistence } = makeService();
+    service.configureCircuitPersistence(true);
     await service.init();
-    // The snapshot is taken, then a reset lands before the persist step —
+    // The snapshot is taken, then a reset lands before the persist step,
     // simulated by bumping the generation from inside save_state().
     processorInstances[0].save_state.mockImplementation(() => {
       void service.reset();
@@ -101,4 +109,108 @@ describe('StreamProcessorService.reset', () => {
     await service.saveState();
     expect(persistence.set).not.toHaveBeenCalled();
   });
+
+  it('frees the replaced wasm circuit on reset', async () => {
+    const { service } = makeService();
+    await service.init();
+    const first = processorInstances[0];
+    await service.reset();
+    // V8 cannot see wasm-internal bytes, so the FinalizationRegistry may never
+    // run. The old circuit must be freed explicitly or its whole store stays
+    // resident for the rest of the session.
+    expect(first.free).toHaveBeenCalledTimes(1);
+  });
+});
+
+// The renderer-OOM guardrail. `Circuit::save` deep-clones the entire store (every
+// row of every ingested table) and JSON-encodes it. It used to run once per
+// ingest batch and once per query register/unregister, which on a large windowed
+// list meant hundreds of whole-store serializations per scroll, for a snapshot
+// the browser could never read back. Snapshots are now opt-in and checkpointed.
+describe('StreamProcessorService circuit snapshots', () => {
+  const plan = {
+    queryHash: 'q1',
+    surql: 'SELECT * FROM thing;',
+    params: {},
+    ttl: '10m',
+    lastActiveAt: new Date(),
+    localArray: [],
+    remoteArray: [],
+    meta: { tableName: 'thing' },
+  } as any;
+
+  it('never snapshots on ingest or register/unregister by default', async () => {
+    const { service, persistence } = makeService();
+    await service.init();
+    const processor = processorInstances[0];
+
+    service.registerQueryPlan(plan);
+    service.ingest('thing', 'CREATE', 'thing:a', { id: 'thing:a' });
+    service.ingestMany([
+      { table: 'thing', op: 'CREATE', id: 'thing:b', record: { id: 'thing:b' } },
+      { table: 'thing', op: 'CREATE', id: 'thing:c', record: { id: 'thing:c' } },
+    ]);
+    service.unregisterQueryPlan('q1');
+
+    expect(processor.save_state).not.toHaveBeenCalled();
+    expect(persistence.set).not.toHaveBeenCalled();
+  });
+
+  it('still never snapshots inline when persistence is opted in', async () => {
+    const { service, persistence } = makeService();
+    service.configureCircuitPersistence(true, 30_000);
+    await service.init();
+    const processor = processorInstances[0];
+
+    service.registerQueryPlan(plan);
+    service.ingest('thing', 'CREATE', 'thing:a', { id: 'thing:a' });
+    service.unregisterQueryPlan('q1');
+
+    // Marked dirty, but the write waits for the checkpoint interval.
+    expect(processor.save_state).not.toHaveBeenCalled();
+    expect(persistence.set).not.toHaveBeenCalled();
+    service.stopCheckpoints();
+  });
+
+  it('writes at most one snapshot per checkpoint tick', async () => {
+    vi.useFakeTimers();
+    try {
+      const { service } = makeService();
+      service.configureCircuitPersistence(true, 1000);
+      await service.init();
+      const processor = processorInstances[0];
+
+      for (let i = 0; i < 50; i++) {
+        service.ingest('thing', 'CREATE', `thing:${i}`, { id: `thing:${i}` });
+      }
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(processor.save_state).toHaveBeenCalledTimes(1);
+
+      // Idle interval: nothing changed, so nothing is serialized.
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(processor.save_state).toHaveBeenCalledTimes(1);
+
+      service.stopCheckpoints();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('restores a snapshot the shipped persistence clients actually return', async () => {
+    const { service, persistence } = makeService();
+    // Both clients round-trip `save_state`'s output as a bare string. The old
+    // shape check looked for a raw SurrealDB result, so it never matched and the
+    // browser never restored anything it wrote.
+    persistence.get.mockResolvedValue('state-bytes' as any);
+    service.configureCircuitPersistence(true);
+    await service.init();
+    expect(processorInstances[0].load_state).toHaveBeenCalledWith('state-bytes');
+  });
+
+  it('does not restore a snapshot when persistence is off', async () => {
+    const { service, persistence } = makeService();
+    persistence.get.mockResolvedValue('state-bytes' as any);
+    await service.init();
+    expect(processorInstances[0].load_state).not.toHaveBeenCalled();
+  });
 });

package/src/services/stream-processor/wasm-types.ts

@@ -44,4 +44,9 @@ export interface WasmProcessor {
   // build degrades gracefully instead of throwing.
   load_state?(state: string): void;
   save_state?(): string;
+  // wasm-bindgen destructor. Releases the circuit (store + every view cache)
+  // inside wasm linear memory. Without it the bytes only come back when V8
+  // happens to GC the JS wrapper, which it has no reason to hurry since it
+  // cannot see how much wasm memory the wrapper is holding.
+  free?(): void;
 }

package/src/sp00ky.ts

@@ -9,12 +9,9 @@ import type {
   UpdateOptions,
   RunOptions,
   SyncHealth,
-  StorageHealth} from './types';
-import {
-  LocalMigrator,
-  RemoteDatabaseService,
-  createLocalEngine,
-} from './services/database/index';
+  StorageHealth,
+} from './types';
+import { LocalMigrator, RemoteDatabaseService, createLocalEngine } from './services/database/index';
 import type { LocalStore } from './services/database/index';
 import { StaleEpochError } from './services/database/index';
 import type { UpEvent } from './modules/sync/index';
@@ -30,10 +27,9 @@ import type {
   BucketNames,
   BackendNames,
   BackendRoutes,
-  RoutePayload} from '@spooky-sync/query-builder';
-import {
-  QueryBuilder
+  RoutePayload,
 } from '@spooky-sync/query-builder';
+import { QueryBuilder } from '@spooky-sync/query-builder';
 
 import { DevToolsService } from './modules/devtools/index';
 import { createLogger } from './services/logger/index';
@@ -60,14 +56,19 @@ import { computeTabsFingerprint, hash53, type TabRole } from './services/tabs/pr
 import type { SqliteCacheEngine } from './services/database/sqlite-cache-engine';
 
 export class BucketHandle {
-  constructor(private bucketName: string, private remote: RemoteDatabaseService) {}
+  constructor(
+    private bucketName: string,
+    private remote: RemoteDatabaseService
+  ) {}
 
   async put(path: string, content: string | Uint8Array | Blob): Promise<void> {
     await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
   }
 
   async get(path: string): Promise<unknown> {
-    const [result] = await this.remote.query<[unknown]>(`RETURN f"${this.bucketName}:/${path}".get();`);
+    const [result] = await this.remote.query<[unknown]>(
+      `RETURN f"${this.bucketName}:/${path}".get();`
+    );
     return result;
   }
 
@@ -76,26 +77,36 @@ export class BucketHandle {
   }
 
   async exists(path: string): Promise<boolean> {
-    const [result] = await this.remote.query<[boolean]>(`RETURN f"${this.bucketName}:/${path}".exists();`);
+    const [result] = await this.remote.query<[boolean]>(
+      `RETURN f"${this.bucketName}:/${path}".exists();`
+    );
     return result;
   }
 
   async head(path: string): Promise<Record<string, unknown>> {
-    const [result] = await this.remote.query<[Record<string, unknown>]>(`RETURN f"${this.bucketName}:/${path}".head();`);
+    const [result] = await this.remote.query<[Record<string, unknown>]>(
+      `RETURN f"${this.bucketName}:/${path}".head();`
+    );
     return result;
   }
 
   async copy(sourcePath: string, targetPath: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, { target: targetPath });
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, {
+      target: targetPath,
+    });
   }
 
   async rename(sourcePath: string, targetPath: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, { target: targetPath });
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, {
+      target: targetPath,
+    });
   }
 
   async list(prefix?: string): Promise<string[]> {
     const p = prefix ?? '';
-    const [result] = await this.remote.query<[string[]]>(`RETURN f"${this.bucketName}:/${p}".list();`);
+    const [result] = await this.remote.query<[string[]]>(
+      `RETURN f"${this.bucketName}:/${p}".list();`
+    );
     return result;
   }
 }
@@ -273,6 +284,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
       this.persistenceClient,
       logger
     );
+    // Circuit snapshots are opt-in and checkpointed, never per-ingest. See
+    // `persistCircuit` in types.ts for the measurements behind that default.
+    this.streamProcessor.configureCircuitPersistence(
+      config.persistCircuit ?? false,
+      config.circuitCheckpointMs
+    );
     this.migrator = new LocalMigrator(this.local, logger);
 
     this.cache = new CacheModule(
@@ -295,7 +312,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
       this.local,
       this.remote,
       logger,
-      config.crdtDebounceMs ?? 500,
+      config.crdtDebounceMs ?? 500
     );
 
     this.dataModule = new DataModule(
@@ -325,7 +342,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
         degradeAfterConsecutiveFailures:
           this.config.syncHealth === false
             ? 0
-            : this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3,
+            : (this.config.syncHealth?.degradeAfterConsecutiveFailures ?? 3),
       }
     );
 
@@ -368,23 +385,38 @@ export class Sp00kyClient<S extends SchemaStructure> {
     // every module. Nothing starts until init() calls coordinator.start().
     if (tabsSupport.supported) {
       this.tabsCoordinator = this.buildTabsCoordinator();
+    } else if (this.config.sharedTabs) {
+      this.logger.info(
+        {
+          reason: (tabsSupport as { reason: string }).reason,
+          Category: 'sp00ky-client::Sp00kyClient::tabs',
+        },
+        'sharedTabs requested but unsupported here; running solo'
+      );
+    }
+    // Report shared-tabs state whenever the feature was REQUESTED, active or
+    // not: "asked to share one store, running alone because X" is exactly the
+    // thing you need to see in the panel. Apps that never set the flag report
+    // null and the panel shows no section at all.
+    if (this.config.sharedTabs) {
+      const unsupportedReason = tabsSupport.supported
+        ? undefined
+        : (tabsSupport as { reason: string }).reason;
       this.devTools.setTabsInfoProvider(() => {
-        if (!this.sharedActive || !this.tabsCoordinator) return null;
         const c = this.tabsCoordinator;
+        if (!this.sharedActive || !c) {
+          return { active: false, reason: unsupportedReason ?? 'fell-back' };
+        }
+        const hub = c.syncHub;
         return {
+          active: true,
           role: c.role,
           tabId: c.tabId,
           leadershipId: c.leadershipId,
-          leaderTabId: c.leaderTabId,
-          followers: c.syncHub?.followerCount ?? null,
-          relayedBatches: c.syncHub?.relayedBatches ?? null,
+          leaderTabId: c.role === 'leader' ? c.tabId : c.leaderTabId,
+          ...(hub ? { followers: hub.followerCount, relayedBatches: hub.relayedBatches } : {}),
         };
       });
-    } else if (this.config.sharedTabs) {
-      this.logger.info(
-        { reason: (tabsSupport as { reason: string }).reason, Category: 'sp00ky-client::Sp00kyClient::tabs' },
-        'sharedTabs requested but unsupported here; running solo'
-      );
     }
   }
 
@@ -437,7 +469,8 @@ export class Sp00kyClient<S extends SchemaStructure> {
         this.cache.setIngestRelay(null);
         this.sync.setTabContext('solo', tabId);
       },
-      currentStorageHealth: () => this.local.storageHealth ?? { status: 'unknown', fallback: false },
+      currentStorageHealth: () =>
+        this.local.storageHealth ?? { status: 'unknown', fallback: false },
     };
     return new TabsCoordinator({
       tabId,
@@ -515,9 +548,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
         for (const row of records) {
           const id = row?.id;
           const table =
-            id && typeof id === 'object' && id.table !== undefined
-              ? String(id.table)
-              : undefined;
+            id && typeof id === 'object' && id.table !== undefined ? String(id.table) : undefined;
           if (!table) continue;
           this.crdtManager.applyRow(table, row);
         }
@@ -594,9 +625,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
       await this.streamProcessor.init();
       // Seed table `select` permissions from the schema before any query is
       // registered — otherwise the SSP default-denies every non-`_00_` table.
-      this.streamProcessor.setPermissions(
-        extractSelectPermissions(this.config.schemaSurql)
-      );
+      this.streamProcessor.setPermissions(extractSelectPermissions(this.config.schemaSurql));
       this.logger.debug(
         { Category: 'sp00ky-client::Sp00kyClient::init' },
         'StreamProcessor initialized'
@@ -758,7 +787,11 @@ export class Sp00kyClient<S extends SchemaStructure> {
    */
   private async doSwitchBucket(target: string, gateRelease?: (() => void) | null): Promise<void> {
     this.logger.info(
-      { target, from: this.local.currentBucketId, Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket' },
+      {
+        target,
+        from: this.local.currentBucketId,
+        Category: 'sp00ky-client::Sp00kyClient::doSwitchBucket',
+      },
       'Switching local bucket'
     );
 
@@ -843,6 +876,11 @@ export class Sp00kyClient<S extends SchemaStructure> {
     if (this.tabsCoordinator) await this.tabsCoordinator.stop();
     await this.local.close();
     await this.remote.close();
+    // Free the wasm circuit explicitly. V8 cannot see wasm-internal bytes, so
+    // relying on the wasm-bindgen FinalizationRegistry leaves the whole store
+    // resident until a GC that may never come, and a client that is recreated
+    // (provider remount, HMR) would stack circuits.
+    this.streamProcessor.dispose();
   }
 
   /**
@@ -883,7 +921,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
     table: string,
     recordId: string,
     field: string,
-    fallbackText?: string,
+    fallbackText?: string
   ): Promise<CrdtField> {
     return this.crdtManager.open(table, recordId, field, fallbackText);
   }
@@ -1137,10 +1175,12 @@ export class Sp00kyClient<S extends SchemaStructure> {
     this.dataModule.recordFrontendTiming(queryHash, ms);
   }
 
-  run<
-    B extends BackendNames<S>,
-    R extends BackendRoutes<S, B>,
-  >(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions) {
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+    backend: B,
+    path: R,
+    payload: RoutePayload<S, B, R>,
+    options?: RunOptions
+  ) {
     return this.dataModule.run(backend, path, payload, options);
   }