@rocicorp/zero 1.11.0-canary.3 → 1.11.0-canary.31

package/out/replicache/src/replicache-impl.js

@@ -3,10 +3,12 @@ import { assertCookie } from "./cookies.js";
 import { isClientStateNotFoundResponse, isVersionNotSupportedResponse } from "./error-responses.js";
 import { getDefaultPuller, isDefaultPuller } from "./get-default-puller.js";
 import { getBrowserGlobal } from "../../shared/src/browser-env.js";
-import { promiseVoid } from "../../shared/src/resolved-promises.js";
+import { promiseFalse, promiseVoid } from "../../shared/src/resolved-promises.js";
 import { deepFreeze } from "./frozen-json.js";
+import { getStorageFailure } from "./storage-failure.js";
 import { makeIDBName } from "./make-idb-name.js";
 import { AbortError } from "../../shared/src/abort-error.js";
+import { InvalidRefCountError } from "./dag/invalid-ref-count-error.js";
 import { assertHash, emptyHash, newRandomHash } from "./hash.js";
 import { ChunkNotFoundError, mustGetHeadHash } from "./dag/store.js";
 import { StoreImpl } from "./dag/store-impl.js";
@@ -18,9 +20,10 @@ import { disableClientGroup } from "./persist/client-groups.js";
 import { makeClientID } from "./persist/make-client-id.js";
 import { ClientStateNotFoundError, hasClientState, initClientV6 } from "./persist/clients.js";
 import { getKVStoreProvider } from "./get-kv-store-provider.js";
+import { MemFallbackStoreProvider } from "./kv/mem-fallback-store.js";
 import { createLogContext } from "./log-options.js";
 import { IDBDatabasesStore } from "./persist/idb-databases-store.js";
-import { COLLECT_IDB_INTERVAL, INITIAL_COLLECT_IDB_DELAY, initCollectIDBDatabases } from "./persist/collect-idb-databases.js";
+import { COLLECT_IDB_INTERVAL, INITIAL_COLLECT_IDB_DELAY, dropDatabaseInternal, initCollectIDBDatabases } from "./persist/collect-idb-databases.js";
 import { throwIfClosed } from "./transaction-closed-error.js";
 import { getDocumentVisibilityWatcher } from "../../shared/src/document-visible.js";
 import { PullDelegate, PushDelegate } from "./connection-loop-delegates.js";
@@ -89,6 +92,7 @@ var ReplicacheImpl = class {
 	*/
 	isClientGroupDisabled = false;
 	#kvStoreProvider;
+	#perKVStore;
 	lastMutationID = 0;
 	/**
 	* This is the name Replicache uses for the IndexedDB database where data is
@@ -97,6 +101,14 @@ var ReplicacheImpl = class {
 	get idbName() {
 		return makeIDBName(this.name, this.schemaVersion);
 	}
+	/**
+	* The KV store backing this instance. It is a memory store once a storage
+	* failure while opening moved the instance onto memory (see
+	* `onStorageFailure`).
+	*/
+	get kvStore() {
+		return this.#perKVStore.backing;
+	}
 	set auth(auth) {
 		if (this.#zero) this.#zero.auth = auth;
 		this.#auth = auth;
@@ -118,6 +130,12 @@ var ReplicacheImpl = class {
 	#online = true;
 	#clientID = makeClientID();
 	#ready;
+	/**
+	* Resolves if open fails, for whatever reason. `#ready` never resolves in
+	* that case, so `close()` waits on whichever of the two settles first
+	* instead of hanging forever.
+	*/
+	#openFailed = resolver();
 	#profileIDPromise;
 	#clientGroupIDPromise;
 	#mutatorRegistry = {};
@@ -155,6 +173,24 @@ var ReplicacheImpl = class {
 	#lc;
 	#zero;
 	#closeAbortController = new AbortController();
+	/**
+	* Aborted on close, on a storage failure after the open, and by
+	* {@link stopPersist}. `persist()`, the persist scheduler and the
+	* store-writing background processes (heartbeat, client and client-group
+	* GC, database collection, mutation recovery) stop on this signal, so the
+	* first detected failure stops them instead of letting each retry the
+	* fault at its interval and log `Error running.` every time. A failure
+	* during the open moves the stores onto memory instead, where they keep
+	* running.
+	*/
+	#persistAbortController = new AbortController();
+	/**
+	* Aborted on close, on a storage failure after the open, and by
+	* {@link stopRefresh}. `refresh()`, the refresh scheduler and the
+	* store-reading background process (the new-client channel's store read)
+	* stop on this signal.
+	*/
+	#refreshAbortController = new AbortController();
 	#persistLock = new Lock();
 	#enableScheduledPersist;
 	#enableScheduledRefresh;
@@ -187,9 +223,13 @@ var ReplicacheImpl = class {
 	*/
 	onSync = null;
 	/**
-	* `onClientStateNotFound` is called when the persistent client has been
-	* garbage collected. This can happen if the client has no pending mutations
-	* and has not been used for a while.
+	* `onClientStateNotFound` is called when the persistent client state can no
+	* longer be used. This happens when:
+	* - the persistent client has been garbage collected. This can happen if the
+	*   client has no pending mutations and has not been used for a while.
+	* - the persistent store was found to be corrupt. Replicache then tries to
+	*   drop the database, including any pending mutations, so that a fresh one
+	*   is created on reload.
 	*
 	* The default behavior is to reload the page (using `location.reload()`). Set
 	* this to `null` or provide your own function to prevent the page from
@@ -197,6 +237,66 @@ var ReplicacheImpl = class {
 	*/
 	onClientStateNotFound = reload;
 	/**
+	* `onStorageFailure` is called once, the first time the local kv store
+	* reports that its storage has failed rather than its data, by throwing a
+	* {@link StorageFailureError}: the device is out of space (`full`), the
+	* database cannot be opened (`cannot-open`), or a read or write to it failed
+	* (`io-error`). The SQLite stores and the IndexedDB store report these; a
+	* custom `StoreProvider` can throw a `StorageFailureError` itself.
+	*
+	* A failure while the instance is opening moves it onto memory for the
+	* session, where it runs as with `kvStore: 'mem'`: it persists and
+	* refreshes against the memory stores, and nothing reaches the disk.
+	*
+	* A failure after that stops persisting and refreshing: a rebuild would
+	* open the same failing storage, and a wipe would destroy an intact replica
+	* for a fault that is not in the data. Queries and mutations keep running
+	* against what the in-memory dag holds, and mutations keep pushing to the
+	* server, but nothing is persisted locally until the app creates a new
+	* instance. A read that needs a chunk the in-memory dag has not loaded from
+	* the store yet, or has since evicted from its cache, still goes to the
+	* store and fails the way any store read does; that failure reaches its
+	* caller, and is reported here as well, whichever caller it was (a query,
+	* a mutation, a poke, a background process). An invalid ref count reported while
+	* the store is failing with `cannot-open` or `io-error` is NOT treated as
+	* corruption (the database is not dropped and {@link onClientStateNotFound}
+	* is not called), because a store that cannot complete a read or write is
+	* what produces such readings. A `full` disk keeps the drop: a torn write
+	* there is real corruption, and deleting the database is also what frees
+	* the space.
+	*
+	* After the open, the failure is detected when a transaction on the store
+	* fails to begin or to commit, whichever caller ran it (`persist()`, the
+	* heartbeat, garbage collection, ...), when `persist()` or `refresh()`
+	* fails, when the in-memory dag fails to load a chunk from the store for
+	* any caller, and when a background process fails on a store read inside
+	* its transaction. The background maintenance processes (heartbeat, client and
+	* client-group GC, database collection, mutation recovery) stop on it
+	* instead of retrying against the store at their interval.
+	*
+	* There is no default behavior other than logging. An app that shows a
+	* "free up space" or "restart" screen can do so from here.
+	*/
+	onStorageFailure = null;
+	/**
+	* Set the first time the kv store reports a storage failure. Read by every
+	* path that writes the perdag so none of them retries against storage
+	* that has failed.
+	*/
+	#storageFailure;
+	/**
+	* The last persist queued on the persist lock, if any, so
+	* {@link stopPersist} can wait for it. The lock runs persists in order, so
+	* this one settles after every persist queued before it. Settled to
+	* `undefined` rather than left rejected.
+	*/
+	#persistInFlight;
+	/**
+	* The refresh currently running, if any, so {@link stopRefresh} can wait
+	* for it. Settled to `undefined` rather than left rejected.
+	*/
+	#refreshInFlight;
+	/**
 	* `onUpdateNeeded` is called when a code update is needed.
 	*
 	* A code update can be needed because:
@@ -248,13 +348,18 @@ var ReplicacheImpl = class {
 			name,
 			"replicache version": version
 		});
+		this.#closeAbortController.signal.addEventListener("abort", () => {
+			this.#persistAbortController.abort();
+			this.#refreshAbortController.abort();
+		}, { once: true });
 		this.#subscriptions = new SubscriptionsManagerImpl(this.#queryInternal, this.#lc, this.#closeAbortController.signal);
-		const kvStoreProvider = getKVStoreProvider(this.#lc, options.kvStore);
+		const kvStoreProvider = new MemFallbackStoreProvider(getKVStoreProvider(this.#lc, options.kvStore), (failure) => this.#onMemFallBack(failure), (failure) => this.#handleStorageFailure(failure));
 		this.#kvStoreProvider = kvStoreProvider;
 		const perKVStore = kvStoreProvider.create(this.idbName);
+		this.#perKVStore = perKVStore;
 		this.#idbDatabases = new IDBDatabasesStore(kvStoreProvider.create);
-		this.perdag = new StoreImpl(perKVStore, newRandomHash, assertHash);
-		this.memdag = new LazyStore(this.perdag, LAZY_STORE_SOURCE_CHUNK_CACHE_SIZE_LIMIT, newRandomHash, assertHash);
+		this.perdag = new StoreImpl(perKVStore, newRandomHash, assertHash, this.#onInvalidRefCount);
+		this.memdag = new LazyStore(this.perdag, LAZY_STORE_SOURCE_CHUNK_CACHE_SIZE_LIMIT, newRandomHash, assertHash, void 0, this.#reportStorageFailure);
 		const readyResolver = resolver();
 		this.#ready = readyResolver.promise;
 		const { minDelayMs = 30, maxDelayMs = MAX_DELAY_MS } = requestOptions;
@@ -273,7 +378,21 @@ var ReplicacheImpl = class {
 		this.#onPersist = initOnPersistChannel(this.name, this.#closeAbortController.signal, (persistInfo) => {
 			this.#handlePersist(persistInfo);
 		});
-		this.#open(indexes, enableClientGroupForking, enableMutationRecovery, clientMaxAgeMs, profileIDResolver.resolve, clientGroupIDResolver.resolve, readyResolver.resolve, onClientsDeleted);
+		const open = () => this.#open(indexes, enableClientGroupForking, enableMutationRecovery, clientMaxAgeMs, profileIDResolver.resolve, clientGroupIDResolver.resolve, readyResolver.resolve, onClientsDeleted);
+		open().catch((e) => {
+			if (e instanceof InvalidRefCountError) {
+				this.#openFailed.resolve();
+				this.#lc.debug?.("Open failed because the persistent store is corrupt");
+				return;
+			}
+			if (!this.#closed && this.#kvStoreProvider.fallBack(e)) return open().catch((e) => {
+				this.#openFailed.resolve();
+				if (this.#closed) this.#lc.debug?.("Open on memory ended by close", e);
+				else this.#lc.error?.("Open failed again on memory", e);
+			});
+			this.#openFailed.resolve();
+			this.#lc.error?.("Error during open", e);
+		});
 	}
 	async #open(indexes, enableClientGroupForking, enableMutationRecovery, clientMaxAgeMs, profileIDResolver, resolveClientGroupID, resolveReady, onClientsDeleted) {
 		const { clientID } = this;
@@ -288,19 +407,20 @@ var ReplicacheImpl = class {
 		if (dbOpenMs > SLOW_DB_OPEN_THRESHOLD_MS) this.#lc.warn?.(`Opening the database took ${Math.round(dbOpenMs)}ms`, { name: this.idbName });
 		else this.#lc.debug?.("Opened the database in", Math.round(dbOpenMs), "ms");
 		await this.#zero?.init(headHash, this.memdag);
+		this.#kvStoreProvider.opened();
 		resolveReady();
 		if (this.#enablePullAndPushInOpen) {
 			this.pull().catch(noop);
 			this.push().catch(noop);
 		}
-		const { signal } = this.#closeAbortController;
+		const { signal } = this.#persistAbortController;
 		startHeartbeats(clientID, this.perdag, () => {
 			this.#clientStateNotFoundOnClient(clientID);
-		}, HEARTBEAT_INTERVAL, this.#lc, signal);
-		initClientGC(clientID, this.perdag, clientMaxAgeMs, GC_INTERVAL, onClientsDeleted, this.#lc, signal);
-		initCollectIDBDatabases(this.#idbDatabases, this.#kvStoreProvider, COLLECT_IDB_INTERVAL, INITIAL_COLLECT_IDB_DELAY, 2 * clientMaxAgeMs, enableMutationRecovery, onClientsDeleted, this.#lc, signal);
-		initClientGroupGC(this.perdag, enableMutationRecovery, this.#lc, signal);
-		initNewClientChannel(this.name, this.idbName, signal, client.clientGroupID, isNewClientGroup, () => {
+		}, HEARTBEAT_INTERVAL, this.#lc, signal, this.#reportStorageFailure);
+		initClientGC(clientID, this.perdag, clientMaxAgeMs, GC_INTERVAL, onClientsDeleted, this.#lc, signal, this.#reportStorageFailure);
+		initCollectIDBDatabases(this.#idbDatabases, this.#kvStoreProvider, COLLECT_IDB_INTERVAL, INITIAL_COLLECT_IDB_DELAY, 2 * clientMaxAgeMs, enableMutationRecovery, onClientsDeleted, this.#lc, signal, (name, createKVStore) => new StoreImpl(createKVStore(name), newRandomHash, assertHash, name === this.idbName ? this.#onInvalidRefCount : void 0), this.#reportStorageFailure);
+		initClientGroupGC(this.perdag, enableMutationRecovery, this.#lc, signal, this.#reportStorageFailure);
+		initNewClientChannel(this.name, this.idbName, this.#refreshAbortController.signal, client.clientGroupID, isNewClientGroup, () => {
 			this.#fireOnUpdateNeeded(updateNeededReasonNewClientGroup);
 		}, this.perdag);
 		setIntervalWithSignal(() => this.recoverMutations(), RECOVER_MUTATIONS_INTERVAL_MS, signal);
@@ -308,7 +428,7 @@ var ReplicacheImpl = class {
 		getBrowserGlobal("document")?.addEventListener("visibilitychange", this.#onVisibilityChange);
 	}
 	#onVisibilityChange = async () => {
-		if (this.#closed) return;
+		if (this.#closed || this.#storageFailure !== void 0) return;
 		if (getBrowserGlobal("document")?.visibilityState !== "visible") return;
 		await this.#checkForClientStateNotFoundAndCallHandler();
 	};
@@ -375,7 +495,7 @@ var ReplicacheImpl = class {
 		closingInstances.set(this.name, promise);
 		this.#closeAbortController.abort();
 		getBrowserGlobal("document")?.removeEventListener("visibilitychange", this.#onVisibilityChange);
-		await this.#ready;
+		await Promise.race([this.#ready, this.#openFailed.promise]);
 		const closingPromises = [
 			this.memdag.close(),
 			this.perdag.close(),
@@ -401,11 +521,13 @@ var ReplicacheImpl = class {
 				this.#schedulePersist();
 				return;
 			}
-			const zeroData = await this.#zero?.getTxData?.(syncHead);
+			let zeroData = await this.#zero?.getTxData?.(syncHead);
 			for (const mutation of replayMutations) {
 				if (this.#subscriptions.hasPendingSubscriptionRuns) await Promise.resolve();
 				const { meta } = mutation;
-				syncHead = await withWriteNoImplicitCommit(this.memdag, (dagWrite) => rebaseMutationAndCommit(mutation, dagWrite, syncHead, SYNC_HEAD_NAME, this.#mutatorRegistry, lc, isLocalMetaDD31(meta) ? meta.clientID : clientID, 7, zeroData));
+				const { result, zeroData: next } = await withWriteNoImplicitCommit(this.memdag, (dagWrite) => rebaseMutationAndCommit(mutation, dagWrite, syncHead, SYNC_HEAD_NAME, this.#mutatorRegistry, lc, isLocalMetaDD31(meta) ? meta.clientID : clientID, 7, zeroData));
+				syncHead = result;
+				zeroData = next;
 			}
 		}
 	}
@@ -620,16 +742,24 @@ var ReplicacheImpl = class {
 		};
 	}
 	persist() {
-		return this.#persistLock.withLock(async () => {
+		const run = this.#persistLock.withLock(async () => {
 			const { clientID } = this;
 			await this.#ready;
-			if (this.#closed) return;
+			if (this.#closed || this.#storageFailure || this.#persistAbortController.signal.aborted) return;
 			try {
 				await persistDD31(this.#lc, clientID, this.memdag, this.perdag, this.#mutatorRegistry, () => this.#closed, 7, this.#zero?.getTxData);
 			} catch (e) {
 				if (e instanceof ClientStateNotFoundError) this.#clientStateNotFoundOnClient(clientID);
-				else if (this.#closed) this.#lc.debug?.("Exception persisting during close", e);
-				else throw e;
+				else if (e instanceof InvalidRefCountError) {
+					await this.#handleInvalidRefCount(e);
+					return;
+				} else if (this.#closed) this.#lc.debug?.("Exception persisting during close", e);
+				else {
+					const failure = getStorageFailure(e);
+					if (failure === void 0) throw e;
+					this.#handleStorageFailure(failure);
+					return;
+				}
 			}
 			const clientGroupID = await this.#clientGroupIDPromise;
 			assert(clientGroupID, "Expected clientGroupID to be defined");
@@ -638,18 +768,31 @@ var ReplicacheImpl = class {
 				clientGroupID
 			});
 		});
+		this.#persistInFlight = run.catch(noop);
+		return run;
+	}
+	refresh() {
+		const run = this.#refresh();
+		this.#refreshInFlight = run.catch(noop);
+		return run;
 	}
-	async refresh() {
+	async #refresh() {
 		await this.#ready;
 		const { clientID } = this;
-		if (this.#closed || !this.#enableRefresh()) return;
+		if (this.#closed || this.#storageFailure || this.#refreshAbortController.signal.aborted || !this.#enableRefresh()) return;
 		let refreshResult;
 		try {
 			refreshResult = await refresh(this.#lc, this.memdag, this.perdag, clientID, this.#mutatorRegistry, this.#subscriptions, () => this.closed, 7, this.#zero);
 		} catch (e) {
 			if (e instanceof ClientStateNotFoundError) this.#clientStateNotFoundOnClient(clientID);
+			else if (e instanceof InvalidRefCountError) await this.#handleInvalidRefCount(e);
 			else if (this.#closed) this.#lc.debug?.("Exception refreshing during close", e);
-			else throw e;
+			else {
+				const failure = getStorageFailure(e);
+				if (failure === void 0) throw e;
+				this.#handleStorageFailure(failure);
+				return;
+			}
 		}
 		if (refreshResult !== void 0) await this.#subscriptions.fire(refreshResult.diffs);
 	}
@@ -660,12 +803,159 @@ var ReplicacheImpl = class {
 		this.#lc.error?.(`Client state not found on client, clientID: ${clientID}`);
 		this.#fireOnClientStateNotFound();
 	}
+	/**
+	* Set once recovery from a corrupt database has started. Every write path
+	* into the perdag (open, persist, refresh, heartbeat, GC, ...) can trip on
+	* the same corrupt key, so recovery runs once and later reports await it.
+	*/
+	#corruptDatabaseRecovery;
+	/**
+	* Handed to the in-memory dag and the background processes, which have no
+	* other way to reach this instance when a store read inside them fails.
+	* Skipped while closing: a read that fails because the store was closed
+	* under it is not a storage failure of the instance.
+	*/
+	#reportStorageFailure = (failure) => {
+		if (!this.#closed) this.#handleStorageFailure(failure);
+	};
+	/**
+	* A storage failure after the open. Records the first one, stops the
+	* store-using background processes, logs it once and tells the app. Later
+	* failures of the same instance are the same fault and are not reported
+	* again; the scheduled persist and refresh stop asking.
+	*/
+	#handleStorageFailure(failure) {
+		if (this.#storageFailure !== void 0) return;
+		this.#storageFailure = failure;
+		this.#persistAbortController.abort();
+		this.#refreshAbortController.abort();
+		this.#lc.warn?.(`Local store storage failed (${failure.kind}) for ${this.idbName}; persistence is stopped for this instance`, failure);
+		this.#fireOnStorageFailure(failure);
+	}
+	/**
+	* A storage failure during the open: the stores have moved onto memory, so
+	* the instance runs on them for the session, as with `kvStore: 'mem'`.
+	* Reported on a
+	* later microtask: the SQLite stores open in `create`, while the
+	* constructor is still running and before the app can attach the callback.
+	*/
+	#onMemFallBack(failure) {
+		this.#lc.warn?.(`Local store storage failed (${failure.kind}) opening ${this.idbName}; running this instance in memory`, failure);
+		queueMicrotask(() => this.#fireOnStorageFailure(failure));
+	}
+	/**
+	* The app's callback must not be able to stop the recovery around it: in
+	* the open path, a throw here would skip the open on memory and leave the
+	* instance never ready.
+	*/
+	#fireOnStorageFailure(failure) {
+		try {
+			this.onStorageFailure?.(failure);
+		} catch (e) {
+			this.#lc.error?.("onStorageFailure threw", e);
+		}
+	}
+	/**
+	* Installed on the dag store that writes to our database. The store calls
+	* it after the failing transaction has been released, so dropping the
+	* database from here does not race with the rollback.
+	*/
+	#onInvalidRefCount = (e) => {
+		this.#handleInvalidRefCount(e);
+	};
+	/**
+	* The persistent dag store contains an invalid ref count. This means the
+	* store is corrupt (due to some unknown bug) and every subsequent write that
+	* touches that chunk would fail the same way. There is no way to repair it,
+	* so we treat it like the client state was lost and fire
+	* `onClientStateNotFound`.
+	*
+	* Disabling the client group is not enough: the corrupt ref count stays in
+	* the underlying kv store and any later write that touches that chunk (for
+	* example rewriting the `clients` chunk when a new client starts) would hit
+	* it again. Instead we drop the whole database so that the reload starts
+	* from a fresh store. Pending local mutations in this database are lost.
+	*
+	* This is expected to be exceedingly rare. Other instances sharing the
+	* database are not told: they simply hit the same corrupt key (or, once
+	* this instance drops the database, a generic storage error) on their own
+	* next write and recover the same way then. That's an acceptable delay for
+	* something we don't expect to ever happen.
+	*/
+	#handleInvalidRefCount(e) {
+		if (this.#storageFailure !== void 0 && this.#storageFailure.kind !== "full") {
+			this.#lc.warn?.(`Invalid ref count while the local store is failing (${this.#storageFailure.kind}); not dropping database ${this.idbName}`, e);
+			return promiseVoid;
+		}
+		if (this.#corruptDatabaseRecovery === void 0) {
+			this.#lc.error?.(`Client state is corrupt on client, clientID: ${this.clientID}. Dropping database ${this.idbName}`, e);
+			this.#corruptDatabaseRecovery = this.#dropDatabaseAndFireOnClientStateNotFound();
+		}
+		return this.#corruptDatabaseRecovery;
+	}
+	/**
+	* Drops our database, then fires `onClientStateNotFound` so the app can
+	* recover, whether or not the drop itself succeeded.
+	*
+	* Uses its own handle on the databases registry rather than `#idbDatabases`
+	* so it works even when `close()` is already closing this instance.
+	*/
+	async #dropDatabaseAndFireOnClientStateNotFound() {
+		const { idbName, clientID } = this;
+		let idbDatabases;
+		try {
+			idbDatabases = new IDBDatabasesStore(this.#kvStoreProvider.create);
+			await dropDatabaseInternal(idbName, idbDatabases, this.#kvStoreProvider.drop);
+		} catch (dropError) {
+			this.#lc.error?.(`Failed to drop database ${idbName}, clientID: ${clientID}`, dropError);
+		}
+		try {
+			await idbDatabases?.close();
+		} catch (closeError) {
+			this.#lc.debug?.(`Failed to close the databases registry after dropping ${idbName}, clientID: ${clientID}`, closeError);
+		}
+		this.#fireOnClientStateNotFound();
+	}
 	async #clientStateNotFoundOnServer() {
 		const clientGroupID = await this.#clientGroupIDPromise;
 		this.#lc.error?.(`Client state not found on server, clientGroupID: ${clientGroupID}`);
 		await this.disableClientGroup();
 		this.#fireOnClientStateNotFound();
 	}
+	/**
+	* Stops every write to the local store, for an instance whose database is
+	* about to be dropped from under it: the store-writing background
+	* processes (heartbeat, GC, collection, mutation recovery) are aborted, a
+	* `persist()` already in flight is waited for, and every later `persist()`
+	* — scheduled or explicit — is a no-op. Mutations keep running against the in-memory
+	* dag until the app replaces the instance (see `onClientStateNotFound`).
+	*
+	* Use together with {@link stopRefresh} before dropping the database, so
+	* the drop's own footprint — `database is closed` from the next scheduled
+	* persist and the background processes — is not logged as errors against a
+	* store that was deleted on purpose.
+	*/
+	async stopPersist() {
+		this.#persistAbortController.abort();
+		await this.#persistInFlight;
+	}
+	/**
+	* Stops every refresh from the local store, for an instance whose database
+	* is about to be dropped from under it: the store-reading background
+	* process (the new-client channel) is aborted, a `refresh()` already in
+	* flight is waited for, and every later `refresh()` / `runRefresh()` —
+	* scheduled or explicit — is a no-op. Queries keep running against the
+	* in-memory dag until the app replaces the instance (see
+	* `onClientStateNotFound`).
+	*
+	* Use together with {@link stopPersist} before dropping the database, so
+	* the run loop's refresh after a connect error does not run into the
+	* dropped store and log `database is closed` as an error.
+	*/
+	async stopRefresh() {
+		this.#refreshAbortController.abort();
+		await this.#refreshInFlight;
+	}
 	async disableClientGroup() {
 		const clientGroupID = await this.#clientGroupIDPromise;
 		assert(clientGroupID, "Expected clientGroupID to be defined");
@@ -677,7 +967,7 @@ var ReplicacheImpl = class {
 		this.onUpdateNeeded?.(reason);
 	}
 	async #schedulePersist() {
-		if (!this.#enableScheduledPersist) return;
+		if (!this.#enableScheduledPersist || this.#storageFailure || this.#persistAbortController.signal.aborted) return;
 		await this.#schedule("persist", this.#persistScheduler);
 	}
 	async #handlePersist(persistInfo) {
@@ -686,7 +976,7 @@ var ReplicacheImpl = class {
 		if (persistInfo.clientGroupID === clientGroupID) this.#scheduleRefresh();
 	}
 	async #scheduleRefresh() {
-		if (!this.#enableScheduledRefresh) return;
+		if (!this.#enableScheduledRefresh || this.#storageFailure || this.#refreshAbortController.signal.aborted) return;
 		await this.#schedule("refresh from storage", this.#refreshScheduler);
 	}
 	async #schedule(name, scheduler) {
@@ -844,7 +1134,9 @@ var ReplicacheImpl = class {
 		if (ex instanceof ChunkNotFoundError && await this.#checkForClientStateNotFoundAndCallHandler()) return new ClientStateNotFoundError(this.clientID);
 		return ex;
 	}
-	recoverMutations() {}
+	recoverMutations() {
+		if (this.#persistAbortController.signal.aborted) return promiseFalse;
+	}
 	/**
 	* List of pending mutations. The order of this is from oldest to newest.
 	*