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

package/dist/index.d.ts

@@ -140,6 +140,11 @@ declare class StreamProcessorService {
   private stateKeySuffix;
   private stateGeneration;
   private persistState;
+  private persistCircuit;
+  private checkpointMs;
+  private checkpointTimer;
+  private snapshotDirty;
+  private pagehideHandler;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -200,8 +205,34 @@ declare class StreamProcessorService {
    * afterwards (a fresh circuit default-denies every table).
    */
   reset(): Promise<void>;
+  /**
+   * 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;
+  /**
+   * 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;
   /** Toggle circuit-state persistence (shared-tabs follower/leader role). */
   setPersistenceEnabled(enabled: boolean): void;
+  /**
+   * 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;
+  /**
+   * 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;
+  private startCheckpoints;
+  /** Stop checkpointing and drop the `pagehide` listener. */
+  stopCheckpoints(): void;
   loadState(): Promise<void>;
   /**
    * Seed per-table `select` permission predicates ({ [table]: whereText }).

package/dist/index.js

@@ -5694,15 +5694,18 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.156";
-const WASM_VERSION = "0.0.1-canary.156";
+const CORE_VERSION = "0.0.1-canary.157";
+const WASM_VERSION = "0.0.1-canary.157";
 const SURREAL_VERSION = "3.0.3";
-var DevToolsService = class {
+var DevToolsService = class DevToolsService {
 	eventsHistory = [];
 	eventIdCounter = 0;
 	version = CORE_VERSION;
 	backendInfo = emptyBackendInfo();
 	enabled = false;
+	static NOTIFY_MIN_INTERVAL_MS = 250;
+	notifyTimer = null;
+	lastNotifyAt = 0;
 	/** Shared-tabs snapshot for the panel, wired by Sp00kyClient whenever the
 	*  feature was REQUESTED (so an inactive/degraded tab still reports why). */
 	tabsInfoProvider = null;
@@ -5971,9 +5974,30 @@ var DevToolsService = class {
 			return { granted: false };
 		}
 	}
+	/**
+	* Request a state push. Coalesced (see {@link NOTIFY_MIN_INTERVAL_MS}): the
+	* first call after an idle period pushes straight away so the panel stays
+	* responsive, and any calls during the window collapse into ONE trailing push
+	* that serializes the state as of the flush, not as of the request. Callers
+	* stay fire-and-forget.
+	*/
 	notifyDevTools() {
 		if (!this.enabled) return;
-		if (typeof window !== "undefined") window.postMessage({
+		if (typeof window === "undefined") return;
+		if (this.notifyTimer !== null) return;
+		const waited = Date.now() - this.lastNotifyAt;
+		if (waited >= DevToolsService.NOTIFY_MIN_INTERVAL_MS) {
+			this.flushNotify();
+			return;
+		}
+		this.notifyTimer = setTimeout(() => {
+			this.notifyTimer = null;
+			if (this.enabled) this.flushNotify();
+		}, DevToolsService.NOTIFY_MIN_INTERVAL_MS - waited);
+	}
+	flushNotify() {
+		this.lastNotifyAt = Date.now();
+		window.postMessage({
 			type: "SP00KY_STATE_CHANGED",
 			source: "sp00ky-devtools-page",
 			state: this.getState()
@@ -6298,6 +6322,14 @@ var AuthService = class {
 
 //#endregion
 //#region src/services/stream-processor/index.ts
+/**
+* Read a circuit snapshot out of the pre-`persistCircuit` persisted shape
+* (`[[{ state }]]`, a raw SurrealDB result). Returns null for anything else.
+*/
+function extractLegacyState(result) {
+	if (Array.isArray(result) && Array.isArray(result[0]) && typeof result[0][0]?.state === "string") return result[0][0].state;
+	return null;
+}
 var StreamProcessorService = class {
 	logger;
 	processor;
@@ -6312,6 +6344,11 @@ var StreamProcessorService = class {
 	stateKeySuffix = "";
 	stateGeneration = 0;
 	persistState = true;
+	persistCircuit = false;
+	checkpointMs = 3e4;
+	checkpointTimer = null;
+	snapshotDirty = false;
+	pagehideHandler = null;
 	constructor(events, db, persistenceClient, logger) {
 		this.events = events;
 		this.db = db;
@@ -6392,7 +6429,7 @@ var StreamProcessorService = class {
 		const buffered = Array.from(this.batchBuffer.values());
 		this.batchBuffer.clear();
 		if (buffered.length > 0) this.dispatchUpdates(buffered);
-		this.saveState();
+		this.markSnapshotDirty();
 	}
 	/**
 	* Initialize the WASM module and processor.
@@ -6436,19 +6473,99 @@ var StreamProcessorService = class {
 		this.stateGeneration++;
 		this.batching = false;
 		this.batchBuffer.clear();
+		this.snapshotDirty = false;
+		const previous = this.processor;
 		this.processor = new Sp00kyProcessor();
+		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() {
+		this.stopCheckpoints();
+		const previous = this.processor;
+		this.processor = void 0;
+		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.
+	*/
+	freeProcessor(processor) {
+		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) {
 		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, checkpointMs) {
+		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).
+	*/
+	markSnapshotDirty() {
+		if (!this.persistCircuit || !this.persistState) return;
+		this.snapshotDirty = true;
+		this.startCheckpoints();
+	}
+	startCheckpoints() {
+		if (this.checkpointTimer) return;
+		this.checkpointTimer = setInterval(() => {
+			if (!this.snapshotDirty) return;
+			this.snapshotDirty = false;
+			this.saveState();
+		}, this.checkpointMs);
+		if (typeof window !== "undefined" && !this.pagehideHandler) {
+			this.pagehideHandler = () => {
+				if (!this.snapshotDirty) return;
+				this.snapshotDirty = false;
+				this.saveState();
+			};
+			window.addEventListener("pagehide", this.pagehideHandler);
+		}
+	}
+	/** Stop checkpointing and drop the `pagehide` listener. */
+	stopCheckpoints() {
+		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());
-			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;
+			const state = typeof result === "string" ? result : extractLegacyState(result);
+			if (state) {
 				this.logger.info({
 					stateLength: state.length,
 					Category: "sp00ky-client::StreamProcessorService::loadState"
@@ -6502,7 +6619,7 @@ var StreamProcessorService = class {
 		}, "Session auth context updated");
 	}
 	async saveState() {
-		if (!this.processor || !this.persistState) return;
+		if (!this.processor || !this.persistState || !this.persistCircuit) return;
 		const generation = this.stateGeneration;
 		try {
 			if (typeof this.processor.save_state === "function") {
@@ -6561,7 +6678,7 @@ var StreamProcessorService = class {
 				}));
 				this.notifyUpdates(updates);
 			}
-			if (!this.batching) this.saveState();
+			if (!this.batching) this.markSnapshotDirty();
 			return rawUpdates;
 		} catch (e) {
 			this.logger.error({
@@ -6614,7 +6731,7 @@ var StreamProcessorService = class {
 					snapshotMs: initialUpdate.timing_snapshot_ms ?? 0
 				}
 			};
-			this.saveState();
+			this.markSnapshotDirty();
 			this.logger.debug({
 				queryHash: queryPlan.queryHash,
 				surql: queryPlan.surql,
@@ -6637,7 +6754,7 @@ var StreamProcessorService = class {
 		if (!this.processor) return;
 		try {
 			this.processor.unregister_view(queryHash);
-			this.saveState();
+			this.markSnapshotDirty();
 		} catch (e) {
 			this.logger.error({
 				error: e,
@@ -8759,6 +8876,7 @@ var Sp00kyClient = class {
 		else this.persistenceClient = config.persistenceClient;
 		this.persistenceClient = new ResilientPersistenceClient(this.persistenceClient, logger);
 		this.streamProcessor = new StreamProcessorService(new EventSystem(["stream_update"]), this.local, this.persistenceClient, logger);
+		this.streamProcessor.configureCircuitPersistence(config.persistCircuit ?? false, config.circuitCheckpointMs);
 		this.migrator = new LocalMigrator(this.local, logger);
 		this.cache = new CacheModule(this.local, this.streamProcessor, (update) => {
 			this.dataModule.onStreamUpdate(update);
@@ -8821,7 +8939,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.156",
+				coreVersion: "0.0.1-canary.157",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -9117,6 +9235,7 @@ var Sp00kyClient = class {
 		if (this.tabsCoordinator) await this.tabsCoordinator.stop();
 		await this.local.close();
 		await this.remote.close();
+		this.streamProcessor.dispose();
 	}
 	/**
 	* Subscribe to a feature flag for the current user. Returns a

package/dist/types.d.ts

@@ -495,6 +495,29 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * Inspect via `window.__00__.getState().database.tabs` and `__sqliteStats`.
    */
   sharedTabs?: boolean;
+  /**
+   * Persist the in-browser SSP circuit (store + view caches) as a snapshot so a
+   * reload can restore it instead of re-materializing. Default `false`, and
+   * that default is deliberate.
+   *
+   * The circuit is DERIVED state: the durable local store (OPFS SQLite) is the
+   * source of truth, and every first paint already reads row bodies from it
+   * (`DataManager.createNewQuery` / `materializeRecords`) using the circuit only
+   * for row identity and ordering. A snapshot buys nothing on reload while
+   * costing a full deep clone of every row of every ingested table plus a JSON
+   * encode of the result, `Circuit::save` in the Rust core, mirroring the
+   * server's rule in `ssp-node`: *never per-ingest*.
+   *
+   * When enabled, snapshots are written on a checkpoint interval
+   * ({@link circuitCheckpointMs}) and on `pagehide`, never per ingest or per
+   * query registration. Enable only for a workload that has measured a win.
+   */
+  persistCircuit?: boolean;
+  /**
+   * Checkpoint interval in milliseconds for {@link persistCircuit}. Defaults to
+   * 30000. Ignored when `persistCircuit` is off.
+   */
+  circuitCheckpointMs?: number;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**

package/package.json

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

package/src/modules/devtools/index.ts

@@ -51,6 +51,18 @@ export class DevToolsService implements StreamUpdateReceiver {
   // (the on-demand GET_STATE pull) still works before the push channel turns on.
   private enabled = false;
 
+  // A state push serializes EVERY active query's full record set (see
+  // `getActiveQueries`) and postMessage clones it again, so its cost scales with
+  // the whole client dataset — and it is triggered per event, including one per
+  // local DB query (`DATABASE_LOCAL_QUERY` → `logEvent`). Unthrottled, a single
+  // page load's few hundred local queries turn a handful of MB of rows into GBs
+  // of short-lived large-object garbage and OOM the renderer (V8
+  // "young object promotion failed"). Coalesce instead: push immediately when
+  // idle, then at most once per window, always serializing the LATEST state.
+  private static readonly NOTIFY_MIN_INTERVAL_MS = 250;
+  private notifyTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastNotifyAt = 0;
+
   /** Shared-tabs snapshot for the panel, wired by Sp00kyClient whenever the
    *  feature was REQUESTED (so an inactive/degraded tab still reports why). */
   private tabsInfoProvider: (() => SharedTabsInfo | null) | null = null;
@@ -408,19 +420,42 @@ export class DevToolsService implements StreamUpdateReceiver {
     }
   }
 
+  /**
+   * Request a state push. Coalesced (see {@link NOTIFY_MIN_INTERVAL_MS}): the
+   * first call after an idle period pushes straight away so the panel stays
+   * responsive, and any calls during the window collapse into ONE trailing push
+   * that serializes the state as of the flush, not as of the request. Callers
+   * stay fire-and-forget.
+   */
   private notifyDevTools() {
     // No consumer attached → no getState() serialization, no postMessage broadcast.
     if (!this.enabled) return;
-    if (typeof window !== 'undefined') {
-      window.postMessage(
-        {
-          type: 'SP00KY_STATE_CHANGED',
-          source: 'sp00ky-devtools-page',
-          state: this.getState(),
-        },
-        '*'
-      );
+    if (typeof window === 'undefined') return;
+    // A trailing push is already queued; it will carry this change too.
+    if (this.notifyTimer !== null) return;
+
+    const waited = Date.now() - this.lastNotifyAt;
+    if (waited >= DevToolsService.NOTIFY_MIN_INTERVAL_MS) {
+      this.flushNotify();
+      return;
     }
+    this.notifyTimer = setTimeout(() => {
+      this.notifyTimer = null;
+      // Still gated on `enabled`: the panel may have disconnected while queued.
+      if (this.enabled) this.flushNotify();
+    }, DevToolsService.NOTIFY_MIN_INTERVAL_MS - waited);
+  }
+
+  private flushNotify() {
+    this.lastNotifyAt = Date.now();
+    window.postMessage(
+      {
+        type: 'SP00KY_STATE_CHANGED',
+        source: 'sp00ky-devtools-page',
+        state: this.getState(),
+      },
+      '*'
+    );
   }
 
   private serializeForDevTools(data: any, seen = new WeakSet<object>()): any {

package/src/modules/devtools/notify-throttle.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DevToolsService } from './index';
+
+/**
+ * A state push serializes EVERY active query's full record set and postMessage
+ * clones it again, so its cost scales with the whole client dataset. It is
+ * requested per event — including one per local DB query — so without
+ * coalescing a page load's few hundred local queries turn a few MB of rows into
+ * GBs of short-lived large-object garbage and OOM the renderer. These tests pin
+ * the coalescing, not the payload.
+ */
+
+function harness(recordCount = 500) {
+  const posted: any[] = [];
+  const listeners: ((e: any) => void)[] = [];
+  const fakeWindow: any = {
+    postMessage: (msg: any) => posted.push(msg),
+    addEventListener: (_type: string, cb: (e: any) => void) => listeners.push(cb),
+    dispatchEvent: () => true,
+  };
+  fakeWindow.self = fakeWindow;
+  vi.stubGlobal('window', fakeWindow);
+  vi.stubGlobal('CustomEvent', class {
+    type: string;
+    constructor(type: string) {
+      this.type = type;
+    }
+  });
+
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+
+  const local: any = {
+    query: async () => [],
+    getConfig: () => ({ store: 'memory' }),
+    currentBucketId: 'anon',
+    storageHealth: { status: 'memory', fallback: false },
+  };
+  const remote: any = { query: async () => [] };
+  const auth: any = {
+    isAuthenticated: false,
+    currentUser: undefined,
+    eventSystem: { subscribe: noop },
+  };
+  // One query holding a lot of rows: the thing whose repeated serialization is
+  // what actually blows the heap.
+  const records = Array.from({ length: recordCount }, (_, i) => ({ id: `game:${i}`, pgn: 'x' }));
+  const dataManager: any = {
+    getActiveQueries: () => [
+      {
+        config: { id: new RecordId('_00_query', 'q1'), params: {} },
+        status: 'idle',
+        records,
+        updateCount: 1,
+      },
+    ],
+    phaseTimings: () => ({}),
+  };
+
+  const service = new DevToolsService(local, remote, logger, { tables: [] } as any, auth, dataManager);
+  // Announce a consumer, exactly like the extension's page-script does.
+  for (const cb of listeners) {
+    cb({ source: fakeWindow, data: { type: 'SP00KY_DEVTOOLS_CONNECT' } });
+  }
+  const statePushes = () => posted.filter((m) => m.type === 'SP00KY_STATE_CHANGED');
+  return { service, statePushes, posted };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe('DevToolsService state-push coalescing', () => {
+  it('pushes once immediately on connect', () => {
+    vi.useFakeTimers();
+    const { statePushes } = harness();
+    expect(statePushes().length).toBe(1);
+  });
+
+  it('collapses a burst of per-query events into ONE trailing push', () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness();
+    const before = statePushes().length;
+
+    // What a page load looks like: hundreds of LOCAL_QUERY events, each of which
+    // used to serialize the entire query state.
+    for (let i = 0; i < 400; i++) {
+      (service as any).logEvent('LOCAL_QUERY', { query: 'SELECT * FROM game', vars: {} });
+    }
+    // Nothing extra yet — the burst is queued, not serialized 400 times.
+    expect(statePushes().length).toBe(before);
+
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before + 1);
+  });
+
+  it('still pushes again once the window has passed', () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness();
+    const before = statePushes().length;
+
+    (service as any).logEvent('A', {});
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before + 1);
+
+    // An event arriving right after that flush is still inside the window, so it
+    // queues rather than pushing again...
+    (service as any).logEvent('B', {});
+    expect(statePushes().length).toBe(before + 1);
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before + 2);
+
+    // ...but once the tab has been idle past the window, the next event pushes
+    // straight away, so the panel never waits on a quiet app.
+    vi.advanceTimersByTime(1000);
+    (service as any).logEvent('C', {});
+    expect(statePushes().length).toBe(before + 3);
+  });
+
+  it('drops a queued push when the consumer disconnects mid-window', () => {
+    vi.useFakeTimers();
+    const { service, statePushes, posted } = harness();
+    const before = statePushes().length;
+
+    (service as any).logEvent('A', {});
+    (service as any).enabled = false; // panel closed while the push was queued
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before);
+    expect(posted.some((m) => m.type === 'SP00KY_STATE_CHANGED' && m.state === undefined)).toBe(false);
+  });
+
+  it('serializes the LATEST state at flush time, not at request time', () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness();
+
+    (service as any).logEvent('FIRST', {});
+    (service as any).logEvent('SECOND', {});
+    vi.advanceTimersByTime(300);
+
+    const last = statePushes().at(-1);
+    const types = last.state.eventsHistory.map((e: any) => e.eventType);
+    // Both events of the coalesced window are present in the single push.
+    expect(types).toContain('FIRST');
+    expect(types).toContain('SECOND');
+  });
+});

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),
       }
     );
 
@@ -370,7 +387,10 @@ export class Sp00kyClient<S extends SchemaStructure> {
       this.tabsCoordinator = this.buildTabsCoordinator();
     } else if (this.config.sharedTabs) {
       this.logger.info(
-        { reason: (tabsSupport as { reason: string }).reason, Category: 'sp00ky-client::Sp00kyClient::tabs' },
+        {
+          reason: (tabsSupport as { reason: string }).reason,
+          Category: 'sp00ky-client::Sp00kyClient::tabs',
+        },
         'sharedTabs requested but unsupported here; running solo'
       );
     }
@@ -449,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,
@@ -527,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);
         }
@@ -606,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'
@@ -770,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'
     );
 
@@ -855,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();
   }
 
   /**
@@ -895,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);
   }
@@ -1149,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);
   }
 

package/src/types.ts

@@ -162,6 +162,29 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * Inspect via `window.__00__.getState().database.tabs` and `__sqliteStats`.
    */
   sharedTabs?: boolean;
+  /**
+   * Persist the in-browser SSP circuit (store + view caches) as a snapshot so a
+   * reload can restore it instead of re-materializing. Default `false`, and
+   * that default is deliberate.
+   *
+   * The circuit is DERIVED state: the durable local store (OPFS SQLite) is the
+   * source of truth, and every first paint already reads row bodies from it
+   * (`DataManager.createNewQuery` / `materializeRecords`) using the circuit only
+   * for row identity and ordering. A snapshot buys nothing on reload while
+   * costing a full deep clone of every row of every ingested table plus a JSON
+   * encode of the result, `Circuit::save` in the Rust core, mirroring the
+   * server's rule in `ssp-node`: *never per-ingest*.
+   *
+   * When enabled, snapshots are written on a checkpoint interval
+   * ({@link circuitCheckpointMs}) and on `pagehide`, never per ingest or per
+   * query registration. Enable only for a workload that has measured a win.
+   */
+  persistCircuit?: boolean;
+  /**
+   * Checkpoint interval in milliseconds for {@link persistCircuit}. Defaults to
+   * 30000. Ignored when `persistCircuit` is off.
+   */
+  circuitCheckpointMs?: number;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**