@nkzw/fate 1.5.0 → 1.5.2

package/lib/persistence.mjs

@@ -1,8 +1,13 @@
+import { t as isRecord } from "./record-B07VwXd-.mjs";
 import { i as filterConnectionArgs } from "./args-CRLIRl_v.mjs";
 import { a as createNodeRef, n as decodeHydrationValue, o as getNodeRefId, r as encodeHydrationValue, s as isNodeRef, t as decodeClientHydrationState } from "./hydration-DPZRJgnu.mjs";
-import { i as getErrorStatusCode, m as toEntityId, n as getListKey, o as prepareMutation } from "./store-CeatPJeK.mjs";
+import { i as getErrorStatusCode, m as toEntityId, n as getListKey, o as prepareMutation } from "./store-CakBBzWG.mjs";
 import { t as FateRequestError } from "./protocol-DS5sf6sd.mjs";
 //#region src/persistence-codec.ts
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const isLivePolicy = (value) => isRecord(value) && (value.append === void 0 || value.append === "edge" || value.append === "visible") && (value.prepend === void 0 || value.prepend === "edge" || value.prepend === "visible");
+const isSerializedPlan = (value) => isRecord(value) && Array.isArray(value.args) && value.args.every((entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && isRecord(entry[1]) && typeof entry[1].hash === "string" && isRecord(entry[1].value) && (entry[1].ignoreKeys === void 0 || isStringArray(entry[1].ignoreKeys))) && Array.isArray(value.live) && value.live.every((entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && isLivePolicy(entry[1])) && isStringArray(value.paths);
+const isSerializedRequest = (value) => isRecord(value) && typeof value.key === "string" && Array.isArray(value.items) && value.items.every((item) => isRecord(item) && isSerializedPlan(item.plan) && (item.kind === "list" ? isStringArray(item.nodeRefViewNames) : (item.kind === "node" || item.kind === "nodes" || item.kind === "query") && isStringArray(item.refViewNames)));
 const serializePlan = (plan) => ({
 	args: [...plan.args].map(([key, value]) => [key, {
 		...value,
@@ -27,47 +32,71 @@ const encodeRequests = (requests) => encodeHydrationValue(requests.map((request)
 		..."refViewNames" in item ? { refViewNames: [...item.refViewNames] } : { nodeRefViewNames: [...item.nodeRefViewNames] }
 	}))
 })));
-const decodeRequests = (value) => decodeHydrationValue(value).map((request) => ({
-	...request,
-	items: request.items.map((item) => ({
-		...item,
-		plan: deserializePlan(item.plan),
-		..."refViewNames" in item ? { refViewNames: new Set(item.refViewNames) } : { nodeRefViewNames: new Set(item.nodeRefViewNames) }
-	}))
-}));
+const decodeItem = (item) => item.kind === "list" ? {
+	...item,
+	nodeRefViewNames: new Set(item.nodeRefViewNames),
+	plan: deserializePlan(item.plan)
+} : {
+	...item,
+	plan: deserializePlan(item.plan),
+	refViewNames: new Set(item.refViewNames)
+};
+const decodeRequests = (value) => {
+	const requests = decodeHydrationValue(value);
+	if (!Array.isArray(requests) || !requests.every(isSerializedRequest)) throw new Error("fate: Invalid persisted request descriptors.");
+	return requests.map((request) => ({
+		...request,
+		items: request.items.map(decodeItem)
+	}));
+};
+//#endregion
+//#region src/persistence-utils.ts
+const encoder = new TextEncoder();
+const persistenceEntrySize = (key, value) => encoder.encode(JSON.stringify([key, value])).byteLength;
+const yieldPersistenceTask = () => new Promise((resolve) => setTimeout(resolve, 0));
 //#endregion
 //#region src/persistence-cache.ts
+const createNodeChanges = () => ({
+	listBases: /* @__PURE__ */ new Map(),
+	recordFields: /* @__PURE__ */ new Map(),
+	referenceChanges: /* @__PURE__ */ new Set(),
+	values: /* @__PURE__ */ new Map()
+});
+const decodeStoredValue = (value) => {
+	if (value === void 0) return;
+	if (!isRecord(value) || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || !Object.hasOwn(value, "value")) throw new Error("fate: Unsupported or corrupt persisted cache data.");
+	return value;
+};
 const mergeCacheUpdate = (key, before, after) => ({
 	fields: after.fields && (!before || before.fields) ? [.../* @__PURE__ */ new Set([...before?.fields ?? [], ...after.fields])] : void 0,
 	previousList: before ? before.previousList : after.previousList,
+	referencesChanged: before?.referencesChanged || after.referencesChanged,
 	value: key.startsWith("r:") && before?.value && after.value ? applyRecordUpdate(before.value, after.value, after.fields ? new Set(after.fields) : void 0) : after.value
 });
-const encoder = new TextEncoder();
-const sized = (key, value) => {
+const withStoredSize = (key, value) => {
 	const item = {
 		bytes: 0,
 		value
 	};
 	for (;;) {
-		const bytes = encoder.encode(JSON.stringify([key, item])).byteLength;
+		const bytes = persistenceEntrySize(key, item);
 		if (bytes === item.bytes) return item;
 		item.bytes = bytes;
 	}
 };
-const yieldTask$1 = () => new Promise((resolve) => setTimeout(resolve, 0));
 const stamp = (time) => String(time).padStart(16, "0");
 const recordKey = (id) => `r:${id}`;
 const listKey = (id) => `l:${id}`;
 const queryKey = (id) => `q:${id}`;
-const matches = (path, selected) => path === selected || path.startsWith(`${selected}.`) || selected.startsWith(`${path}.`);
-const project = (value, paths) => {
+const pathsOverlap = (path, selected) => path === selected || path.startsWith(`${selected}.`) || selected.startsWith(`${path}.`);
+const projectRecord = (value, paths) => {
 	const fields = /* @__PURE__ */ new Set([
 		"id",
 		"__typename",
 		...paths.map((path) => path.split(".")[0])
 	]);
 	return {
-		paths: value.paths.filter((path) => paths.some((selected) => matches(path, selected))),
+		paths: value.paths.filter((path) => paths.some((selected) => pathsOverlap(path, selected))),
 		record: Object.fromEntries(Object.entries(value.record).filter(([field]) => fields.has(field)))
 	};
 };
@@ -138,12 +167,6 @@ const applyListUpdate = (latest, before, after) => {
 	};
 	return result;
 };
-const references = (value) => {
-	if (isNodeRef(value)) return JSON.stringify(["ref", getNodeRefId(value)]);
-	if (Array.isArray(value)) return JSON.stringify(value.map(references));
-	if (value && typeof value === "object") return JSON.stringify(Object.entries(value).map(([key, entry]) => [key, references(entry)]));
-	return "";
-};
 /** Independently addressable normalized disk data. No in-memory retention roots. */
 var PersistenceCache = class {
 	constructor(client, storage, key, maxAge, maxBytes) {
@@ -152,14 +175,10 @@ var PersistenceCache = class {
 		this.key = key;
 		this.maxAge = maxAge;
 		this.maxBytes = maxBytes;
-		this.changed = /* @__PURE__ */ new Map();
-		this.updates = /* @__PURE__ */ new Map();
-		this.listBases = /* @__PURE__ */ new Map();
-		this.updateListBases = /* @__PURE__ */ new Map();
-		this.fields = /* @__PURE__ */ new Map();
-		this.updateFields = /* @__PURE__ */ new Map();
-		this.recoveryChanges = /* @__PURE__ */ new Map();
-		this.pending = /* @__PURE__ */ new Map();
+		this.pendingNodes = createNodeChanges();
+		this.flushingNodes = createNodeChanges();
+		this.recoveryUpdates = /* @__PURE__ */ new Map();
+		this.pendingRequests = /* @__PURE__ */ new Map();
 		this.suppressed = false;
 		this.disposed = false;
 		this.work = 0;
@@ -172,7 +191,7 @@ var PersistenceCache = class {
 			this.assertActive();
 			if (await this.read(`${this.prefix}scope`) !== this.client.getPersistenceScope()) {
 				await this.clear();
-				if (sized(`${this.prefix}scope`, this.client.getPersistenceScope()).bytes + this.overhead <= this.maxBytes) await this.put([[`${this.prefix}scope`, this.client.getPersistenceScope()]]);
+				if (withStoredSize(`${this.prefix}scope`, this.client.getPersistenceScope()).bytes + this.overhead <= this.maxBytes) await this.put([[`${this.prefix}scope`, this.client.getPersistenceScope()]]);
 			}
 		});
 	}
@@ -228,10 +247,10 @@ var PersistenceCache = class {
 			} : void 0;
 			const memory = this.client.store.readConfirmed(id);
 			const disk = memory || before ? void 0 : await this.node(key);
-			const recovery = this.recoveryChanges.get(key);
-			const update = this.changed.has(key) ? mergeCacheUpdate(key, recovery, {
-				fields: this.fields.get(key) ? [...this.fields.get(key)] : void 0,
-				value: this.changed.get(key)
+			const recovery = this.recoveryUpdates.get(key);
+			const update = this.pendingNodes.values.has(key) ? mergeCacheUpdate(key, recovery, {
+				fields: this.pendingNodes.recordFields.get(key) ? [...this.pendingNodes.recordFields.get(key)] : void 0,
+				value: this.pendingNodes.values.get(key)
 			}) : recovery;
 			const incoming = update?.value;
 			const value = update ? incoming && (before ? applyRecordUpdate(before, incoming, update.fields ? new Set(update.fields) : void 0) : incoming) : before ?? memory ?? (disk ? decodeHydrationValue(disk.value) : void 0);
@@ -245,7 +264,7 @@ var PersistenceCache = class {
 		}
 		const listValues = [];
 		for (const key of lists) {
-			const value = this.changed.has(listKey(key)) ? this.changed.get(listKey(key)) : this.recoveryChanges.has(listKey(key)) ? this.recoveryChanges.get(listKey(key)).value : previousLists.get(key) ?? this.client.store.readConfirmedList(key);
+			const value = this.pendingNodes.values.has(listKey(key)) ? this.pendingNodes.values.get(listKey(key)) : this.recoveryUpdates.has(listKey(key)) ? this.recoveryUpdates.get(listKey(key)).value : previousLists.get(key) ?? this.client.store.readConfirmedList(key);
 			if (value) listValues.push([key, value]);
 			await this.step();
 		}
@@ -264,12 +283,12 @@ var PersistenceCache = class {
 		};
 	}
 	get overhead() {
-		return encoder.encode(JSON.stringify([`${this.prefix}bytes`, this.maxBytes])).byteLength;
+		return persistenceEntrySize(`${this.prefix}bytes`, this.maxBytes);
 	}
 	async step() {
 		this.assertActive();
 		if (++this.work % 64 === 0) {
-			await yieldTask$1();
+			await yieldPersistenceTask();
 			this.assertActive();
 		}
 	}
@@ -280,17 +299,22 @@ var PersistenceCache = class {
 		return `${this.prefix}root:${key}`;
 	}
 	async read(key) {
-		return (await this.storage.read(key))?.value;
+		return (await this.readStored(key))?.value;
+	}
+	async readStored(key) {
+		return decodeStoredValue(await this.storage.read(key));
 	}
 	async put(entries) {
 		let bytes = await this.storage.read(`${this.prefix}bytes`) ?? 0;
 		const writes = [];
-		for (const [key, value] of new Map(entries)) {
-			const previous = await this.storage.read(key);
-			bytes -= previous?.bytes ?? 0;
+		const unique = /* @__PURE__ */ new Map();
+		for (const [key, value, previousBytes] of entries) unique.set(key, [value, previousBytes]);
+		for (const [key, [value, knownPreviousBytes]] of unique) {
+			const previousBytes = knownPreviousBytes ?? (await this.readStored(key))?.bytes ?? 0;
+			bytes -= previousBytes;
 			if (value === void 0) writes.push([key, void 0]);
 			else {
-				const item = sized(key, value);
+				const item = withStoredSize(key, value);
 				bytes += item.bytes;
 				writes.push([key, item]);
 			}
@@ -301,25 +325,27 @@ var PersistenceCache = class {
 		await this.storage.writeBatch(writes);
 	}
 	get hasChanges() {
-		return this.changed.size > 0 || this.recoveryChanges.size > 0;
-	}
-	changedNode(kind, key, paths, previousList) {
-		if (!this.suppressed && key) {
-			const selected = paths ? new Set([...paths].map((path) => path.split(".")[0])) : void 0;
-			if (kind === "record") {
-				const id = recordKey(key);
-				const previous = this.fields.get(id);
-				this.fields.set(id, selected?.size && (!this.fields.has(id) || previous) ? /* @__PURE__ */ new Set([...previous ?? [], ...selected]) : void 0);
+		return this.pendingNodes.values.size > 0 || this.recoveryUpdates.size > 0;
+	}
+	changedNode(change) {
+		if (!this.suppressed && change) {
+			const selected = change.kind === "record" && change.paths ? new Set([...change.paths].map((path) => path.split(".")[0])) : void 0;
+			if (change.kind === "record") {
+				const id = recordKey(change.key);
+				const previous = this.pendingNodes.recordFields.get(id);
+				this.pendingNodes.recordFields.set(id, selected?.size && (!this.pendingNodes.recordFields.has(id) || previous) ? /* @__PURE__ */ new Set([...previous ?? [], ...selected]) : void 0);
+				if (change.referencesChanged) this.pendingNodes.referenceChanges.add(id);
 			}
-			const id = kind === "record" ? recordKey(key) : listKey(key);
-			const value = kind === "record" ? this.client.store.readConfirmed(key) : this.client.store.readConfirmedList(key);
-			if (kind === "list" && !this.changed.has(id)) this.listBases.set(id, previousList);
-			this.changed.set(id, value);
+			const id = change.kind === "record" ? recordKey(change.key) : listKey(change.key);
+			const value = change.kind === "record" ? this.client.store.readConfirmed(change.key) : this.client.store.readConfirmedList(change.key);
+			if (change.kind === "list" && !this.pendingNodes.values.has(id)) this.pendingNodes.listBases.set(id, change.previousList);
+			this.pendingNodes.values.set(id, value);
 			if (this.capturing) {
 				const previous = this.capturing.get(id);
 				this.capturing.set(id, {
 					fields: selected?.size && (!previous || previous.fields) ? [.../* @__PURE__ */ new Set([...previous?.fields ?? [], ...selected])] : void 0,
-					previousList: previous ? previous.previousList : previousList,
+					previousList: previous ? previous.previousList : change.kind === "list" ? change.previousList : void 0,
+					referencesChanged: previous?.referencesChanged || change.kind === "record" && change.referencesChanged,
 					value
 				});
 			}
@@ -347,28 +373,36 @@ var PersistenceCache = class {
 		}
 		for (const [key, update] of changes) {
 			changes.set(key, {
-				fields: this.fields.get(key) ? [...this.fields.get(key)] : void 0,
-				previousList: this.listBases.has(key) ? this.listBases.get(key) : update.previousList,
-				value: this.changed.get(key)
+				fields: this.pendingNodes.recordFields.get(key) ? [...this.pendingNodes.recordFields.get(key)] : void 0,
+				previousList: this.pendingNodes.listBases.has(key) ? this.pendingNodes.listBases.get(key) : update.previousList,
+				referencesChanged: this.pendingNodes.referenceChanges.has(key),
+				value: this.pendingNodes.values.get(key)
 			});
-			this.changed.delete(key);
-			this.fields.delete(key);
-			this.listBases.delete(key);
+			this.pendingNodes.values.delete(key);
+			this.pendingNodes.recordFields.delete(key);
+			this.pendingNodes.referenceChanges.delete(key);
+			this.pendingNodes.listBases.delete(key);
 		}
 		return encodeHydrationValue([...changes]);
 	}
 	replayChanges(updates) {
-		this.recoveryChanges.clear();
-		for (const encoded of updates) for (const [key, update] of decodeHydrationValue(encoded)) this.recoveryChanges.set(key, mergeCacheUpdate(key, this.recoveryChanges.get(key), update));
+		this.recoveryUpdates.clear();
+		for (const encoded of updates) for (const [key, update] of decodeHydrationValue(encoded)) {
+			const compatible = key.startsWith("r:") && update.referencesChanged === void 0 ? {
+				...update,
+				referencesChanged: true
+			} : update;
+			this.recoveryUpdates.set(key, mergeCacheUpdate(key, this.recoveryUpdates.get(key), compatible));
+		}
 	}
 	fetched(request, maxAge = this.maxAge, fromNetwork = true) {
 		if (!Number.isSafeInteger(maxAge) || maxAge < 0 || maxAge > Number.MAX_SAFE_INTEGER - Date.now()) throw new Error("fate: Persistence maxAge must be a non-negative finite duration.");
 		if (!fromNetwork && this.policies.get(request) === maxAge) return;
 		this.policies.set(request, maxAge);
-		const previous = this.pending.get(request.key);
+		const previous = this.pendingRequests.get(request.key);
 		const retain = this.client.retainPersistenceRequest(request);
 		previous?.release();
-		this.pending.set(request.key, {
+		this.pendingRequests.set(request.key, {
 			fetchedAt: fromNetwork ? Date.now() : previous?.fetchedAt,
 			maxAge,
 			release: retain.dispose,
@@ -382,46 +416,48 @@ var PersistenceCache = class {
 		if (!Object.keys(node.claims).length) return;
 		if (key.startsWith("r:")) {
 			const paths = Object.values(node.claims).flatMap((claim) => claim.paths);
-			node.value = encodeHydrationValue(project(decodeHydrationValue(node.value), paths));
+			node.value = encodeHydrationValue(projectRecord(decodeHydrationValue(node.value), paths));
 		}
 		return node;
 	}
 	/** Walk only the requested selection, yielding between small pieces of work. */
-	async collect(request, memory, fromNetwork = false) {
+	async collect(request, source) {
+		const readsMemory = source !== "disk";
+		const prefersNetworkResult = source === "network";
 		const nodes = /* @__PURE__ */ new Map();
 		const visited = /* @__PURE__ */ new Map();
 		let complete = true;
 		let fetchedAt = Infinity;
 		const queue = [];
-		const read = async (key) => {
+		const readNode = async (key) => {
 			await this.step();
-			if (memory) {
-				if (this.updates.has(key)) {
-					const incoming = this.updates.get(key);
-					const base = this.updateListBases.get(key);
-					if (!fromNetwork && incoming && base && key.startsWith("l:")) {
+			if (readsMemory) {
+				if (this.flushingNodes.values.has(key)) {
+					const incoming = this.flushingNodes.values.get(key);
+					const base = this.flushingNodes.listBases.get(key);
+					if (!prefersNetworkResult && incoming && base && key.startsWith("l:")) {
 						const stored = await this.node(key);
 						if (stored) return applyListUpdate(decodeHydrationValue(stored.value), base, incoming);
 					}
-					if (incoming && key.startsWith("r:") && this.updateFields.get(key)) {
+					if (incoming && key.startsWith("r:") && this.flushingNodes.recordFields.get(key)) {
 						const stored = await this.node(key);
-						if (stored) return applyRecordUpdate(decodeHydrationValue(stored.value), incoming, this.updateFields.get(key));
+						if (stored) return applyRecordUpdate(decodeHydrationValue(stored.value), incoming, this.flushingNodes.recordFields.get(key));
 					}
 					return incoming;
 				}
-				if (fromNetwork) {
+				if (prefersNetworkResult) {
 					const id = key.slice(2);
 					const value = key.startsWith("r:") ? this.client.store.readConfirmed(id) : key.startsWith("l:") ? this.client.store.readConfirmedList(id) : this.client.getPersistenceQuery(id);
 					if (value !== void 0) return value;
-					if (this.changed.has(key)) return;
+					if (this.pendingNodes.values.has(key)) return;
 				}
 			}
 			const stored = await this.node(key);
 			if (stored) for (const claim of Object.values(stored.claims)) fetchedAt = Math.min(fetchedAt, claim.fetchedAt);
-			if (!stored) return memory && key.startsWith("r:") ? this.client.store.readConfirmed(key.slice(2)) : void 0;
+			if (!stored) return readsMemory && key.startsWith("r:") ? this.client.store.readConfirmed(key.slice(2)) : void 0;
 			const value = decodeHydrationValue(stored.value);
-			if (!memory) return value;
-			const deleted = (id) => this.updates.has(recordKey(id)) && this.updates.get(recordKey(id)) === void 0;
+			if (!readsMemory) return value;
+			const deleted = (id) => this.flushingNodes.values.has(recordKey(id)) && this.flushingNodes.values.get(recordKey(id)) === void 0;
 			if (key.startsWith("l:")) {
 				const list = value;
 				return {
@@ -444,7 +480,7 @@ var PersistenceCache = class {
 			return typeof value === "string" && deleted(value) ? null : value;
 		};
 		const addList = async (key, paths, plan, prefix) => {
-			const list = await read(listKey(key));
+			const list = await readNode(listKey(key));
 			if (!list) {
 				complete = false;
 				return;
@@ -475,7 +511,7 @@ var PersistenceCache = class {
 				prefix: ""
 			});
 			else if (item.kind === "query") {
-				const id = await read(queryKey(item.queryKey));
+				const id = await readNode(queryKey(item.queryKey));
 				if (id === void 0) {
 					complete = false;
 					continue;
@@ -503,16 +539,16 @@ var PersistenceCache = class {
 			const needed = paths.filter((path) => !traversed?.has(path));
 			if (traversed && !needed.length) continue;
 			contexts.set(context, /* @__PURE__ */ new Set([...traversed ?? [], ...paths]));
-			const source = await read(key);
-			if (!source) {
+			const record = await readNode(key);
+			if (!record) {
 				complete = false;
 				continue;
 			}
-			if (paths.some((path) => !source.paths.some((covered) => path === covered || path.startsWith(`${covered}.`)))) complete = false;
+			if (paths.some((path) => !record.paths.some((covered) => path === covered || path.startsWith(`${covered}.`)))) complete = false;
 			const all = /* @__PURE__ */ new Set([...seen?.paths ?? [], ...paths]);
 			nodes.set(key, {
 				paths: all,
-				value: project(source, [...all])
+				value: projectRecord(record, [...all])
 			});
 			const groups = /* @__PURE__ */ new Map();
 			for (const path of needed) {
@@ -536,10 +572,10 @@ var PersistenceCache = class {
 			};
 			for (const [field, children] of groups) {
 				const childPrefix = prefix ? `${prefix}.${field}` : field;
-				const value = source.record[field];
+				const value = record.record[field];
 				if (Array.isArray(value)) {
 					const nestedKey = getListKey(id, field, plan.args.get(childPrefix)?.hash);
-					const list = await read(listKey(nestedKey));
+					const list = await readNode(listKey(nestedKey));
 					if (list) {
 						const projected = nodes.get(key).value;
 						projected.record[field] = list.ids.map(createNodeRef);
@@ -557,7 +593,7 @@ var PersistenceCache = class {
 	async restore(request) {
 		await this.storage.exclusive(`${this.key}:write`, async () => {
 			if (!await this.active()) return;
-			const { complete, nodes } = await this.collect(request, false);
+			const { complete, nodes } = await this.collect(request, "disk");
 			if (!complete) return;
 			for (const [key, node] of nodes) {
 				this.assertActive();
@@ -602,16 +638,28 @@ var PersistenceCache = class {
 	async remove(rootId) {
 		const root = await this.read(this.rootKey(rootId));
 		if (!root) return;
+		let writes = [];
 		for (const key of root.nodes) {
-			const node = await this.read(this.nodeKey(key));
+			const storageKey = this.nodeKey(key);
+			const stored = await this.readStored(storageKey);
+			const node = stored?.value;
 			if (node) {
 				delete node.claims[rootId];
 				const live = Object.values(node.claims).filter((claim) => claim.expiresAt > Date.now());
-				if (key.startsWith("r:") && live.length) node.value = encodeHydrationValue(project(decodeHydrationValue(node.value), live.flatMap((claim) => claim.paths)));
-				await this.put([[this.nodeKey(key), live.length ? node : void 0]]);
+				if (key.startsWith("r:") && live.length) node.value = encodeHydrationValue(projectRecord(decodeHydrationValue(node.value), live.flatMap((claim) => claim.paths)));
+				writes.push([
+					storageKey,
+					live.length ? node : void 0,
+					stored.bytes
+				]);
+				if (writes.length === 64) {
+					await this.put(writes);
+					writes = [];
+				}
 			}
 			await this.step();
 		}
+		if (writes.length) await this.put(writes);
 		await this.put([
 			[this.rootKey(rootId), void 0],
 			[`${this.prefix}lru:${stamp(root.usedAt)}:${rootId}`, void 0],
@@ -623,7 +671,7 @@ var PersistenceCache = class {
 			await this.remove(request.key);
 			return;
 		}
-		const { nodes } = await this.collect(request, true, fromNetwork);
+		const { nodes } = await this.collect(request, fromNetwork ? "network" : "memory");
 		const root = {
 			fetchedAt,
 			maxAge,
@@ -631,9 +679,9 @@ var PersistenceCache = class {
 			request: encodeRequests([request]),
 			usedAt
 		};
-		let minimum = sized(this.rootKey(request.key), root).bytes + sized(`${this.prefix}lru:${stamp(usedAt)}:${request.key}`, request.key).bytes + sized(`${this.prefix}expiry:${stamp(fetchedAt + maxAge)}:${request.key}`, request.key).bytes + sized(`${this.prefix}scope`, this.client.getPersistenceScope()).bytes;
+		let minimum = withStoredSize(this.rootKey(request.key), root).bytes + withStoredSize(`${this.prefix}lru:${stamp(usedAt)}:${request.key}`, request.key).bytes + withStoredSize(`${this.prefix}expiry:${stamp(fetchedAt + maxAge)}:${request.key}`, request.key).bytes + withStoredSize(`${this.prefix}scope`, this.client.getPersistenceScope()).bytes;
 		for (const [key, node] of nodes) {
-			minimum += sized(this.nodeKey(key), {
+			minimum += withStoredSize(this.nodeKey(key), {
 				claims: { [request.key]: {
 					expiresAt: fetchedAt + maxAge,
 					fetchedAt,
@@ -674,7 +722,7 @@ var PersistenceCache = class {
 				if (previous && key.startsWith("r:")) {
 					const before = decodeHydrationValue(previous.value);
 					const after = next?.value;
-					value = project({
+					value = projectRecord({
 						paths: [.../* @__PURE__ */ new Set([...before.paths, ...after?.paths ?? []])],
 						record: {
 							...before.record,
@@ -694,17 +742,17 @@ var PersistenceCache = class {
 		for (;;) {
 			let added = 0;
 			for (const [key, value] of writes) {
-				const before = await this.storage.read(key);
-				added += Math.max(0, (value === void 0 ? 0 : sized(key, value).bytes) - (before?.bytes ?? 0));
+				const before = await this.readStored(key);
+				added += Math.max(0, (value === void 0 ? 0 : withStoredSize(key, value).bytes) - (before?.bytes ?? 0));
 				await this.step();
 			}
 			if ((await this.storage.read(`${this.prefix}bytes`) ?? 0) + added + this.journalBytes + this.overhead <= this.maxBytes) break;
-			const candidate = (await this.storage.scan(`${this.prefix}lru:`, void 0, 2)).find((entry) => entry.value.value !== request.key);
+			const candidate = (await this.storage.scan(`${this.prefix}lru:`, void 0, 2)).find((entry) => decodeStoredValue(entry.value)?.value !== request.key);
 			if (!candidate) {
 				await this.remove(request.key);
 				return;
 			}
-			const id = candidate.value.value;
+			const id = decodeStoredValue(candidate.value).value;
 			if (await this.read(this.rootKey(id))) await this.remove(id);
 			else await this.put([[candidate.key, void 0]]);
 			writes = await prepare();
@@ -712,7 +760,7 @@ var PersistenceCache = class {
 		const entries = [...writes];
 		for (let index = 0; index < entries.length; index += 64) {
 			await this.put(entries.slice(index, index + 64));
-			await yieldTask$1();
+			await yieldPersistenceTask();
 		}
 		await this.put([[this.rootKey(request.key), root]]);
 	}
@@ -722,7 +770,7 @@ var PersistenceCache = class {
 		while (true) {
 			const [entry] = await this.storage.scan(`${this.prefix}expiry:`, void 0, 1);
 			if (!entry) break;
-			const id = entry.value.value;
+			const id = decodeStoredValue(entry.value).value;
 			const root = await this.read(this.rootKey(id));
 			if (root && root.fetchedAt + root.maxAge > Date.now()) break;
 			if (root) await this.remove(id);
@@ -732,7 +780,7 @@ var PersistenceCache = class {
 		while ((await this.storage.read(`${this.prefix}bytes`) ?? 0) + journalBytes + this.overhead > this.maxBytes) {
 			const [entry] = await this.storage.scan(`${this.prefix}lru:`, void 0, 1);
 			if (!entry) break;
-			const id = entry.value.value;
+			const id = decodeStoredValue(entry.value).value;
 			if (await this.read(this.rootKey(id))) await this.remove(id);
 			else await this.put([[entry.key, void 0]]);
 			await this.step();
@@ -741,66 +789,69 @@ var PersistenceCache = class {
 	async fits(journalBytes) {
 		return (await this.storage.read(`${this.prefix}bytes`) ?? 0) + journalBytes + this.overhead <= this.maxBytes;
 	}
+	/** Check fixed cache metadata before evicting any saved requests for a new journal entry. */
+	async fitsWithoutEviction(journalBytes) {
+		this.assertActive();
+		const scope = await this.storage.read(`${this.prefix}scope`);
+		this.assertActive();
+		return (scope?.bytes ?? 0) + journalBytes + this.overhead <= this.maxBytes;
+	}
 	async flush(journalBytes) {
 		if (!await this.active()) {
 			this.reset();
 			return;
 		}
 		await this.prune(journalBytes);
-		const pending = this.pending;
-		this.pending = /* @__PURE__ */ new Map();
-		const changes = this.changed;
-		const fields = this.fields;
-		const listBases = this.listBases;
-		this.listBases = /* @__PURE__ */ new Map();
-		const recovery = this.recoveryChanges;
-		this.recoveryChanges = /* @__PURE__ */ new Map();
+		const pending = this.pendingRequests;
+		this.pendingRequests = /* @__PURE__ */ new Map();
+		const pendingNodes = this.pendingNodes;
+		this.pendingNodes = createNodeChanges();
+		const { listBases, recordFields, referenceChanges, values } = pendingNodes;
+		const recovery = this.recoveryUpdates;
+		this.recoveryUpdates = /* @__PURE__ */ new Map();
 		const updates = new Map(recovery);
-		for (const [key, value] of changes) updates.set(key, mergeCacheUpdate(key, updates.get(key), {
-			fields: fields.get(key) ? [...fields.get(key)] : void 0,
+		for (const [key, value] of values) updates.set(key, mergeCacheUpdate(key, updates.get(key), {
+			fields: recordFields.get(key) ? [...recordFields.get(key)] : void 0,
 			previousList: listBases.get(key),
+			referencesChanged: referenceChanges.has(key),
 			value
 		}));
-		this.updates = new Map([...updates].map(([key, update]) => [key, update.value]));
-		this.changed = /* @__PURE__ */ new Map();
-		this.updateListBases = new Map([...updates].map(([key, update]) => [key, update.previousList]));
-		this.updateFields = new Map([...updates].map(([key, update]) => [key, update.fields ? new Set(update.fields) : void 0]));
-		this.fields = /* @__PURE__ */ new Map();
+		this.flushingNodes = {
+			listBases: new Map([...updates].map(([key, update]) => [key, update.previousList])),
+			recordFields: new Map([...updates].map(([key, update]) => [key, update.fields ? new Set(update.fields) : void 0])),
+			referenceChanges: new Set([...updates].filter(([, update]) => update.referencesChanged).map(([key]) => key)),
+			values: new Map([...updates].map(([key, update]) => [key, update.value]))
+		};
 		try {
 			const affected = /* @__PURE__ */ new Map();
-			for (const key of this.updates.keys()) {
+			for (const key of this.flushingNodes.values.keys()) {
 				const node = await this.node(key);
-				const incoming = this.updates.get(key);
-				if (node && incoming && key.startsWith("r:")) {
+				const incoming = this.flushingNodes.values.get(key);
+				if (node && incoming && key.startsWith("r:") && !this.flushingNodes.referenceChanges.has(key)) {
 					const before = decodeHydrationValue(node.value);
-					const after = applyRecordUpdate(before, incoming, this.updateFields.get(key));
-					if (!Object.keys({
-						...before.record,
-						...after.record
-					}).some((field) => references(before.record[field]) !== references(after.record[field]))) {
-						const value = encodeHydrationValue(project({
-							paths: [.../* @__PURE__ */ new Set([...before.paths, ...after.paths])],
-							record: {
-								...before.record,
-								...after.record
-							}
-						}, Object.values(node.claims).flatMap((claim) => claim.paths)));
-						const next = {
-							...node,
-							value
-						};
-						const beforeSize = (await this.storage.read(this.nodeKey(key))).bytes;
-						const growth = Math.max(0, sized(this.nodeKey(key), next).bytes - beforeSize);
-						await this.prune(journalBytes + growth);
-						const retained = await this.node(key);
-						if (retained) {
-							next.claims = retained.claims;
-							next.value = encodeHydrationValue(project(decodeHydrationValue(value), Object.values(retained.claims).flatMap((claim) => claim.paths)));
-							await this.put([[this.nodeKey(key), next]]);
+					const after = applyRecordUpdate(before, incoming, this.flushingNodes.recordFields.get(key));
+					const value = encodeHydrationValue(projectRecord({
+						paths: [.../* @__PURE__ */ new Set([...before.paths, ...after.paths])],
+						record: {
+							...before.record,
+							...after.record
 						}
-						this.journalBytes = journalBytes;
-						continue;
+					}, Object.values(node.claims).flatMap((claim) => claim.paths)));
+					const next = {
+						...node,
+						value
+					};
+					const beforeSize = (await this.readStored(this.nodeKey(key))).bytes;
+					const growth = Math.max(0, withStoredSize(this.nodeKey(key), next).bytes - beforeSize);
+					await this.prune(journalBytes + growth);
+					const retained = await this.node(key);
+					if (retained) {
+						next.claims = retained.claims;
+						next.value = encodeHydrationValue(projectRecord(decodeHydrationValue(value), Object.values(retained.claims).flatMap((claim) => claim.paths)));
+						await this.put([[this.nodeKey(key), next]]);
 					}
+					this.journalBytes = journalBytes;
+					continue;
 				}
 				for (const rootId of Object.keys(node?.claims ?? {})) {
 					if (pending.has(rootId) || affected.has(rootId)) continue;
@@ -817,48 +868,50 @@ var PersistenceCache = class {
 					await this.remove(request.key);
 					continue;
 				}
-				const cached = await this.collect(request, false);
+				const cached = await this.collect(request, "disk");
 				if (cached.complete && Number.isFinite(cached.fetchedAt)) {
 					const root = await this.read(this.rootKey(request.key));
 					await this.save(request, root?.fetchedAt ?? cached.fetchedAt, maxAge);
 				}
 			}
-			this.updates.clear();
+			this.flushingNodes.values.clear();
 			await this.prune(journalBytes);
 		} catch (error) {
 			if (!this.disposed) {
-				for (const [key, update] of recovery) this.recoveryChanges.set(key, this.recoveryChanges.has(key) ? mergeCacheUpdate(key, update, this.recoveryChanges.get(key)) : update);
-				for (const [key, value] of changes) {
-					if (key.startsWith("l:")) this.listBases.set(key, listBases.get(key));
-					if (!this.changed.has(key)) {
-						this.changed.set(key, value);
-						this.fields.set(key, fields.get(key));
+				for (const [key, update] of recovery) this.recoveryUpdates.set(key, this.recoveryUpdates.has(key) ? mergeCacheUpdate(key, update, this.recoveryUpdates.get(key)) : update);
+				for (const [key, value] of values) {
+					if (referenceChanges.has(key)) this.pendingNodes.referenceChanges.add(key);
+					if (key.startsWith("l:")) this.pendingNodes.listBases.set(key, listBases.get(key));
+					if (!this.pendingNodes.values.has(key)) {
+						this.pendingNodes.values.set(key, value);
+						this.pendingNodes.recordFields.set(key, recordFields.get(key));
 					} else if (key.startsWith("r:")) {
-						const before = fields.get(key);
-						const after = this.fields.get(key);
-						this.fields.set(key, before && after ? /* @__PURE__ */ new Set([...before, ...after]) : void 0);
+						const before = recordFields.get(key);
+						const after = this.pendingNodes.recordFields.get(key);
+						this.pendingNodes.recordFields.set(key, before && after ? /* @__PURE__ */ new Set([...before, ...after]) : void 0);
 					}
 				}
-				for (const [key, entry] of pending) if (!this.pending.has(key)) {
-					this.pending.set(key, entry);
+				for (const [key, entry] of pending) if (!this.pendingRequests.has(key)) {
+					this.pendingRequests.set(key, entry);
 					pending.delete(key);
 				}
 			}
 			throw error;
 		} finally {
-			this.updates.clear();
-			this.updateFields.clear();
-			this.updateListBases.clear();
+			this.flushingNodes = createNodeChanges();
 			for (const entry of pending.values()) entry.release();
 		}
 	}
 	async clear() {
+		this.assertActive();
 		this.reset();
 		while (true) {
 			const entries = await this.storage.scan(this.prefix, void 0, 64);
+			this.assertActive();
 			if (!entries.length) return;
 			await this.storage.writeBatch(entries.map(({ key }) => [key, void 0]));
-			await yieldTask$1();
+			await yieldPersistenceTask();
+			this.assertActive();
 		}
 	}
 	dispose() {
@@ -866,32 +919,28 @@ var PersistenceCache = class {
 		this.reset();
 	}
 	reset() {
-		this.recoveryChanges.clear();
+		this.recoveryUpdates.clear();
 		this.policies = /* @__PURE__ */ new WeakMap();
-		for (const entry of this.pending.values()) entry.release();
-		this.pending.clear();
-		this.changed.clear();
-		this.updates.clear();
-		this.fields.clear();
-		this.updateFields.clear();
-		this.listBases.clear();
-		this.updateListBases.clear();
+		for (const entry of this.pendingRequests.values()) entry.release();
+		this.pendingRequests.clear();
+		this.pendingNodes = createNodeChanges();
+		this.flushingNodes = createNodeChanges();
 	}
 };
 //#endregion
 //#region src/persistence-journal.ts
 const invalid = () => /* @__PURE__ */ new Error("fate: Unsupported or corrupt persistence data. It has not been overwritten.");
-const valid = (entry) => entry && typeof entry.id === "string" && typeof entry.scope === "string" && [
-	"queued",
-	"sending",
-	"failed",
-	"confirmed"
-].includes(entry.status) && Number.isInteger(entry.attempts) && entry.attempts >= 0;
-const same = (left, right) => {
+const valid = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const entry = value;
+	if (typeof entry.id !== "string" || typeof entry.scope !== "string" || !Number.isInteger(entry.attempts) || entry.attempts < 0) return false;
+	if (entry.status === "failed") return !!entry.error && typeof entry.error === "object" && typeof entry.error.message === "string";
+	if (entry.status === "confirmed") return "cacheUpdates" in entry && "result" in entry;
+	return entry.status === "queued" || entry.status === "sending";
+};
+const hasSameFields = (left, right) => {
 	return [.../* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)])].every((key) => left[key] === right[key]);
 };
-const size = (key, value) => new TextEncoder().encode(JSON.stringify([key, value])).byteLength;
-const yieldTask = () => new Promise((resolve) => setTimeout(resolve, 0));
 /** All methods run under the account's write lock, including reads across scan pages. */
 var PersistenceJournal = class {
 	constructor(storage, key, validate) {
@@ -905,7 +954,6 @@ var PersistenceJournal = class {
 	dispose() {
 		this.disposed = true;
 		this.entries.clear();
-		this.prepared = void 0;
 	}
 	assertActive() {
 		if (this.disposed) throw new Error("fate: Persistence was disposed.");
@@ -923,7 +971,7 @@ var PersistenceJournal = class {
 			for (const entry of value.mutations) {
 				this.validate?.(entry);
 				if (++checked % 64 === 0) {
-					await yieldTask();
+					await yieldPersistenceTask();
 					this.assertActive();
 				}
 			}
@@ -940,6 +988,7 @@ var PersistenceJournal = class {
 				for (const { key, value } of page) {
 					const stored = value;
 					if (!stored || !valid(stored.entry) || !Number.isSafeInteger(stored.bytes) || stored.bytes <= 0 || entries.has(stored.entry.id)) throw invalid();
+					this.validate?.(stored.entry);
 					entries.set(stored.entry.id, {
 						...stored,
 						key
@@ -947,16 +996,15 @@ var PersistenceJournal = class {
 				}
 				if (page.length < 64) break;
 				after = page.at(-1).key;
-				await yieldTask();
+				await yieldPersistenceTask();
 			}
 			this.assertActive();
 			this.header = value;
 			this.entries = entries;
 		}
-		this.prepared = void 0;
 		return { mutations: [...this.entries.values()].map(({ entry }) => ({ ...entry })) };
 	}
-	async measure(data) {
+	async prepare(data) {
 		this.assertActive();
 		const header = {
 			nextSequence: this.header?.nextSequence ?? 0,
@@ -970,16 +1018,16 @@ var PersistenceJournal = class {
 		for (const entry of data.mutations) {
 			const previous = this.entries.get(entry.id);
 			let stored = previous;
-			if (!previous || !same(previous.entry, entry)) {
+			if (!previous || !hasSameFields(previous.entry, entry)) {
 				const key = previous?.key ?? `${this.prefix}${String(header.nextSequence++).padStart(16, "0")}:${entry.id}`;
 				const value = {
 					bytes: 0,
 					entry
 				};
-				let measured = size(key, value);
+				let measured = persistenceEntrySize(key, value);
 				while (measured !== value.bytes) {
 					value.bytes = measured;
-					measured = size(key, value);
+					measured = persistenceEntrySize(key, value);
 				}
 				stored = {
 					...value,
@@ -991,37 +1039,46 @@ var PersistenceJournal = class {
 			entries.set(entry.id, stored);
 			bytes += stored.bytes;
 			if (++count % 64 === 0) {
-				await yieldTask();
+				await yieldPersistenceTask();
 				this.assertActive();
 			}
 		}
 		for (const [id, { key }] of this.entries) if (!entries.has(id)) writes.push([key, void 0]);
-		bytes += size(this.key, header);
-		this.prepared = {
+		bytes += persistenceEntrySize(this.key, header);
+		return {
 			bytes,
-			data,
 			entries,
 			header,
 			writes
 		};
-		return bytes;
 	}
-	async save(data) {
-		this.assertActive();
-		if (this.prepared?.data !== data) await this.measure(data);
+	async commit(plan) {
 		this.assertActive();
-		const prepared = this.prepared;
-		if (prepared.writes.length || !this.header) {
-			await this.storage.writeBatch([...prepared.writes, [this.key, prepared.header]]);
+		if (plan.writes.length || !this.header) {
+			await this.storage.writeBatch([...plan.writes, [this.key, plan.header]]);
 			this.assertActive();
-			this.header = prepared.header;
-			this.entries = prepared.entries;
+			this.header = plan.header;
+			this.entries = plan.entries;
 		}
-		this.prepared = void 0;
+	}
+	async save(data) {
+		await this.commit(await this.prepare(data));
 	}
 };
 //#endregion
 //#region src/persistence.ts
+const isPendingMutation = (entry) => entry.status === "queued" || entry.status === "sending";
+const replaceMutation = (data, id, replace) => {
+	const index = data.mutations.findIndex((entry) => entry.id === id);
+	if (index >= 0) data.mutations[index] = replace(data.mutations[index]);
+};
+const isTerminalDeliveryError = (status) => status !== void 0 && status >= 400 && status < 500 && ![
+	401,
+	403,
+	408,
+	429
+].includes(status);
+const mutationDiscardedError = () => /* @__PURE__ */ new Error("fate: Mutation was discarded.");
 const encodeCommand = (command) => encodeHydrationValue({
 	...command,
 	plan: command.plan ? serializePlan(command.plan) : void 0
@@ -1057,7 +1114,6 @@ var Session = class {
 		this.key = key;
 		this.online = online;
 		this.retryDelay = retryDelay;
-		this.maxBytes = maxBytes;
 		this.snapshot = {
 			mutations: [],
 			status: "restoring"
@@ -1066,11 +1122,16 @@ var Session = class {
 		this.commands = /* @__PURE__ */ new Map();
 		this.operations = /* @__PURE__ */ new Map();
 		this.mutationAdmission = Promise.resolve();
+		this.cacheChangeRevision = 0;
+		this.baseCheckpointRevision = 0;
+		this.checkpointedCacheUpdates = /* @__PURE__ */ new Set();
 		this.needsCacheRecovery = false;
 		this.needsCheckpoint = false;
 		this.waiters = /* @__PURE__ */ new Map();
 		this.disposed = false;
 		this.draining = false;
+		this.flushRequested = false;
+		this.refreshRequested = false;
 		this.onOnline = () => this.retry();
 		this.getSnapshot = () => this.snapshot;
 		this.subscribe = (listener) => {
@@ -1079,13 +1140,14 @@ var Session = class {
 				this.listeners.delete(listener);
 			};
 		};
-		this.load = () => this.storage.exclusive(`${this.key}:write`, () => this.journal.load());
-		this.update = (apply, admit = false) => this.storage.exclusive(`${this.key}:write`, async () => {
-			if (this.disposed) throw new Error("fate: Persistence was disposed.");
+		this.loadJournal = () => this.storage.exclusive(`${this.key}:write`, () => this.journal.load());
+		this.updateJournal = (apply, admit = false) => this.storage.exclusive(`${this.key}:write`, async () => {
+			this.assertActive();
 			const data = await this.journal.load();
 			const result = await apply(data);
-			const bytes = await this.journal.measure(data);
-			if (admit && bytes > this.maxBytes) throw new Error("fate: Persistence size limit exceeded; unconfirmed mutations have been preserved.");
+			const plan = await this.journal.prepare(data);
+			const { bytes } = plan;
+			if (admit && !await this.cache.fitsWithoutEviction(bytes)) throw new Error("fate: Persistence size limit exceeded; unconfirmed mutations have been preserved.");
 			try {
 				await this.cache.prune(bytes);
 			} catch (error) {
@@ -1093,8 +1155,8 @@ var Session = class {
 				this.report(error);
 			}
 			if (admit && !await this.cache.fits(bytes)) throw new Error("fate: Persistence size limit exceeded; unconfirmed mutations have been preserved.");
-			if (this.disposed) throw new Error("fate: Persistence was disposed.");
-			await this.journal.save(data);
+			this.assertActive();
+			await this.journal.commit(plan);
 			return result;
 		});
 		this.journal = new PersistenceJournal(storage, key, (entry) => {
@@ -1155,11 +1217,23 @@ var Session = class {
 		};
 		this.publish();
 	}
+	clearError() {
+		if (!this.mutationError && this.snapshot.error) {
+			this.snapshot = {
+				...this.snapshot,
+				error: void 0
+			};
+			this.publish();
+		}
+	}
+	assertActive() {
+		if (this.disposed) throw new Error("fate: Persistence was disposed.");
+	}
 	async restore() {
-		const data = await this.load();
+		const data = await this.loadJournal();
 		await this.cache.initialize();
 		if (this.disposed) return;
-		for (const entry of data.mutations) if (entry.status === "queued" || entry.status === "sending") {
+		for (const entry of data.mutations) if (isPendingMutation(entry)) {
 			if (entry.base && entry.base.scope === this.client.getPersistenceScope()) this.cache.restoreBase(decodeClientHydrationState(entry.base.data));
 		}
 		this.snapshot = {
@@ -1184,7 +1258,7 @@ var Session = class {
 		if (this.disposed) return;
 		let processed = 0;
 		for (const entry of data.mutations) {
-			if (++processed % 64 === 0) await new Promise((resolve) => setTimeout(resolve, 0));
+			if (++processed % 64 === 0) await yieldPersistenceTask();
 			if (this.disposed) return;
 			this.command(entry);
 			if (entry.status === "confirmed" || entry.status === "failed") {
@@ -1215,12 +1289,21 @@ var Session = class {
 		const operation = prepareMutation(this.client, command, this.client.getTypeConfig(command.entity), true);
 		const { promise, resolve } = Promise.withResolvers();
 		let cacheUpdates;
+		let commitError;
+		let commitFailed = false;
 		if (operation.entityId) this.client.registerPendingOptimisticMutation(operation.entityId, promise);
 		return {
 			...operation,
 			commit: (result, persist = true) => {
-				if (persist) cacheUpdates ??= this.cache.captureChanges(() => operation.commit(result));
-				else this.cache.withoutChanges(() => operation.commit(result));
+				if (commitFailed) throw commitError;
+				try {
+					if (persist) cacheUpdates ??= this.cache.captureChanges(() => operation.commit(result));
+					else this.cache.withoutChanges(() => operation.commit(result));
+				} catch (error) {
+					commitFailed = true;
+					commitError = error;
+					throw error;
+				}
 				resolve();
 			},
 			getCacheUpdates: () => cacheUpdates,
@@ -1235,22 +1318,30 @@ var Session = class {
 		};
 	}
 	refresh() {
-		return this.refreshing ??= this.load().then(async (data) => {
-			await this.reconcile(data);
+		this.refreshRequested = true;
+		return this.refreshing ??= this.drainRefreshes();
+	}
+	async drainRefreshes() {
+		try {
+			while (this.refreshRequested && !this.disposed) {
+				this.refreshRequested = false;
+				await this.reconcile(await this.loadJournal());
+			}
 			this.retry();
-		}).finally(() => {
+		} finally {
 			this.refreshing = void 0;
-		});
+			if (this.refreshRequested && !this.disposed) this.refresh().catch((error) => this.report(error));
+		}
 	}
 	async mutate(command) {
 		if (this.mutationError) throw this.mutationError;
 		const encoded = encodeCommand(command);
 		await this.ready;
-		if (this.disposed) throw new Error("fate: Persistence was disposed.");
+		this.assertActive();
 		const id = crypto.randomUUID();
 		const admission = this.mutationAdmission.then(async () => {
 			if (this.needsCheckpoint) await this.flushCache().catch((error) => this.report(error));
-			return this.update(async (data) => {
+			return this.updateJournal(async (data) => {
 				await this.reconcile(data);
 				const base = await this.cache.mutationBase(decodeCommand(encoded));
 				data.mutations.push({
@@ -1266,7 +1357,7 @@ var Session = class {
 		});
 		this.mutationAdmission = admission.catch(() => {});
 		const base = await admission;
-		if (this.disposed) throw new Error("fate: Persistence was disposed.");
+		this.assertActive();
 		this.cache.restoreBase(decodeClientHydrationState(base.data));
 		const result = new Promise((resolve, reject) => this.waiters.set(id, {
 			reject,
@@ -1283,7 +1374,7 @@ var Session = class {
 	}
 	async restoreRequest(request) {
 		await this.ready;
-		if (this.disposed) throw new Error("fate: Persistence was disposed.");
+		this.assertActive();
 		try {
 			if (this.needsCacheRecovery) await this.flush();
 			await this.cache.restore(request);
@@ -1302,41 +1393,92 @@ var Session = class {
 		this.cache.fetched(request, options?.maxAge, false);
 		this.changed();
 	}
-	changed(kind, key, paths, previousList) {
+	changed(change) {
 		if (this.disposed) return;
-		if (this.cache.changedNode(kind, key, paths, previousList)) this.needsCacheRecovery = true;
+		if (this.cache.changedNode(change)) {
+			this.needsCacheRecovery = true;
+			this.cacheChangeRevision++;
+		}
 		if (this.disposed || this.snapshot.status !== "ready") return;
-		if (!this.saveTimer) this.saveTimer = setTimeout(() => {
-			this.saveTimer = void 0;
-			this.flush().catch((error) => this.report(error));
-		}, 25);
+		if (this.flushing || this.draining) this.flushRequested = true;
+		else this.scheduleSave();
 	}
 	async flush() {
+		clearTimeout(this.saveTimer);
+		this.saveTimer = void 0;
 		await this.ready;
 		await this.flushCache();
+		this.clearError();
 	}
-	async flushCache() {
-		if (this.disposed) throw new Error("fate: Persistence was disposed.");
+	scheduleSave() {
+		if (!this.saveTimer && !this.disposed) this.saveTimer = setTimeout(() => {
+			this.saveTimer = void 0;
+			this.flush().catch((error) => this.report(error));
+		}, 25);
+	}
+	confirmedCacheEntries(data) {
+		const scope = this.client.getPersistenceScope();
+		return data.mutations.flatMap((entry) => entry.status === "confirmed" && entry.scope === scope ? [[entry.id, entry.cacheUpdates]] : []);
+	}
+	confirmedCacheUpdates(data) {
+		return this.confirmedCacheEntries(data).map(([, updates]) => updates);
+	}
+	async checkpointPendingBases(data) {
+		const revision = this.cacheChangeRevision;
+		const cacheUpdateIds = this.confirmedCacheEntries(data).map(([id]) => id);
+		if (revision === this.baseCheckpointRevision && cacheUpdateIds.every((id) => this.checkpointedCacheUpdates.has(id))) return;
+		const scope = this.client.getPersistenceScope();
+		if (!data.mutations.some((entry) => isPendingMutation(entry) && entry.scope === scope)) {
+			this.baseCheckpointRevision = revision;
+			for (const id of cacheUpdateIds) this.checkpointedCacheUpdates.add(id);
+			return;
+		}
+		for (const entry of data.mutations) if (isPendingMutation(entry) && entry.scope === scope) entry.base = await this.cache.mutationBase(this.command(entry), entry.base);
+		const plan = await this.journal.prepare(data);
+		await this.cache.prune(plan.bytes);
+		this.assertActive();
+		await this.journal.commit(plan);
+		this.baseCheckpointRevision = revision;
+		for (const id of cacheUpdateIds) this.checkpointedCacheUpdates.add(id);
+	}
+	async removeConfirmedEntries(data) {
+		const confirmedIds = new Set(data.mutations.filter((entry) => entry.status === "confirmed").map(({ id }) => id));
+		if (!confirmedIds.size) return;
+		data.mutations = data.mutations.filter(({ id }) => !confirmedIds.has(id));
+		await this.journal.commit(await this.journal.prepare(data));
+		for (const id of confirmedIds) this.checkpointedCacheUpdates.delete(id);
+	}
+	flushCache() {
+		this.assertActive();
+		this.flushRequested = true;
+		if (!this.flushing) {
+			const flushing = this.drainCacheFlushes();
+			this.flushing = flushing;
+			flushing.then(() => this.finishCacheFlush(flushing), () => this.finishCacheFlush(flushing));
+		}
+		return this.flushing;
+	}
+	finishCacheFlush(flushing) {
+		if (this.flushing !== flushing) return;
+		this.flushing = void 0;
+		if (this.flushRequested && !this.disposed) this.scheduleSave();
+	}
+	async drainCacheFlushes() {
+		while (this.flushRequested && !this.disposed) {
+			this.flushRequested = false;
+			await this.flushCacheOnce();
+		}
+	}
+	async flushCacheOnce() {
 		await this.storage.exclusive(`${this.key}:write`, async () => {
-			if (this.disposed) throw new Error("fate: Persistence was disposed.");
+			this.assertActive();
 			const data = await this.journal.load();
 			await this.reconcile(data);
-			this.cache.replayChanges(data.mutations.flatMap((entry) => entry.cacheUpdates && entry.scope === this.client.getPersistenceScope() ? [entry.cacheUpdates] : []));
-			if (data.mutations.some((entry) => entry.status === "queued" || entry.status === "sending")) {
-				for (const entry of data.mutations) if ((entry.status === "queued" || entry.status === "sending") && entry.scope === this.client.getPersistenceScope()) entry.base = await this.cache.mutationBase(this.command(entry), entry.base);
-				await this.cache.prune(await this.journal.measure(data));
-				if (this.disposed) throw new Error("fate: Persistence was disposed.");
-				await this.journal.save(data);
-			}
-			await this.cache.flush(await this.journal.measure(data));
-			if (this.disposed) throw new Error("fate: Persistence was disposed.");
-			const confirmed = data.mutations.filter((entry) => entry.status === "confirmed");
-			if (confirmed.length) {
-				const ids = new Set(confirmed.map(({ id }) => id));
-				data.mutations = data.mutations.filter(({ id }) => !ids.has(id));
-				await this.journal.measure(data);
-				await this.journal.save(data);
-			}
+			this.cache.replayChanges(this.confirmedCacheUpdates(data));
+			await this.checkpointPendingBases(data);
+			await this.cache.flush((await this.journal.prepare(data)).bytes);
+			this.assertActive();
+			await this.removeConfirmedEntries(data);
 			this.needsCacheRecovery = this.cache.hasChanges;
 			this.needsCheckpoint = false;
 		});
@@ -1358,20 +1500,129 @@ var Session = class {
 			this.retry();
 		}, delay);
 	}
-	async fail(id, error) {
+	async fail(id, error, status) {
 		const failure = error instanceof Error ? error : new Error(String(error));
-		await this.update((data) => {
-			const entry = data.mutations.find((item) => item.id === id);
-			if (entry) {
-				entry.status = "failed";
-				delete entry.base;
-				entry.error = {
+		status ??= getErrorStatusCode(failure);
+		await this.updateJournal((data) => {
+			replaceMutation(data, id, (entry) => ({
+				attempts: entry.attempts,
+				command: entry.command,
+				error: {
 					message: failure.message,
-					status: getErrorStatusCode(failure)
-				};
+					status
+				},
+				id: entry.id,
+				scope: entry.scope,
+				status: "failed"
+			}));
+		});
+		await this.reconcile(await this.loadJournal());
+	}
+	forgetOperation(id) {
+		this.operations.delete(id);
+		this.waiters.delete(id);
+	}
+	/** Resolve an operation whose journal entry another client already removed. */
+	async recoverOperation(id, operation) {
+		try {
+			const result = await operation.execute({
+				id,
+				replayOnly: true,
+				scope: this.key
+			});
+			if (this.disposed) return;
+			operation.commit(result, false);
+			this.waiters.get(id)?.resolve(result);
+		} catch (error) {
+			if (this.disposed) return;
+			if (!(error instanceof Error) || getErrorStatusCode(error) !== 404) throw error;
+			operation.rollback(false);
+			this.waiters.get(id)?.reject(mutationDiscardedError());
+		}
+		this.forgetOperation(id);
+	}
+	async recoverRemovedOperations(data) {
+		const retained = new Set(data.mutations.map(({ id }) => id));
+		for (const [id, operation] of this.operations) {
+			if (retained.has(id)) continue;
+			try {
+				await this.recoverOperation(id, operation);
+			} catch (error) {
+				this.report(error);
+				this.scheduleRetry();
+				return false;
 			}
+			if (this.disposed) return false;
+		}
+		return true;
+	}
+	async claim(entry) {
+		const data = await this.updateJournal((data) => {
+			const current = data.mutations.find((item) => item.id === entry.id);
+			if (!current || !isPendingMutation(current)) return;
+			replaceMutation(data, entry.id, () => ({
+				...current,
+				attempts: current.attempts + 1,
+				status: "sending"
+			}));
+			return data;
+		});
+		if (!data) return false;
+		await this.reconcile(data);
+		return true;
+	}
+	async confirm(entry, operation, encodedResult) {
+		const cacheUpdates = operation.getCacheUpdates();
+		if (!cacheUpdates) throw new Error("fate: Mutation confirmation did not capture its cache updates.");
+		await this.updateJournal((data) => {
+			replaceMutation(data, entry.id, (current) => ({
+				attempts: current.attempts,
+				cacheUpdates,
+				command: current.command,
+				id: current.id,
+				result: encodedResult,
+				scope: current.scope,
+				status: "confirmed"
+			}));
 		});
-		await this.reconcile(await this.load());
+		await this.reconcile(await this.loadJournal());
+	}
+	/** Deliver one claimed entry. False means the queue must pause for a retry. */
+	async deliver(entry, operation) {
+		let result;
+		try {
+			result = await operation.execute({
+				id: entry.id,
+				scope: this.key
+			});
+		} catch (error) {
+			if (this.disposed) return false;
+			const status = error instanceof Error ? getErrorStatusCode(error) : void 0;
+			if (isTerminalDeliveryError(status)) {
+				await this.fail(entry.id, error);
+				return true;
+			}
+			await this.queueRetry(entry.id, error, status);
+			return false;
+		}
+		if (this.disposed) return false;
+		let encodedResult;
+		try {
+			encodedResult = encodeHydrationValue(result);
+			operation.commit(result);
+		} catch (error) {
+			await this.fail(entry.id, error, 500);
+			return true;
+		}
+		try {
+			await this.confirm(entry, operation, encodedResult);
+			return true;
+		} catch (error) {
+			if (this.disposed) return false;
+			const status = error instanceof Error ? getErrorStatusCode(error) : void 0;
+			await this.queueRetry(entry.id, error, status);
+			return false;
+		}
 	}
 	async drain() {
 		if (this.draining || this.disposed || !this.online()) return;
@@ -1379,33 +1630,9 @@ var Session = class {
 		try {
 			await this.storage.exclusive(`${this.key}:delivery`, async () => {
 				while (!this.disposed && this.online()) {
-					const data = await this.load();
+					const data = await this.loadJournal();
 					await this.reconcile(data);
-					const retained = new Set(data.mutations.map(({ id }) => id));
-					for (const [id, operation] of this.operations) {
-						if (retained.has(id)) continue;
-						try {
-							const result = await operation.execute({
-								id,
-								replayOnly: true,
-								scope: this.key
-							});
-							if (this.disposed) return;
-							operation.commit(result, false);
-							this.waiters.get(id)?.resolve(result);
-						} catch (error) {
-							if (this.disposed) return;
-							if (!(error instanceof Error) || getErrorStatusCode(error) !== 404) {
-								this.report(error);
-								this.scheduleRetry();
-								return;
-							}
-							operation.rollback(false);
-							this.waiters.get(id)?.reject(/* @__PURE__ */ new Error("fate: Mutation was discarded."));
-						}
-						this.operations.delete(id);
-						this.waiters.delete(id);
-					}
+					if (!await this.recoverRemovedOperations(data)) return;
 					const entry = data.mutations.find((item) => item.status !== "confirmed" && item.status !== "failed");
 					if (!entry) return;
 					if (entry.nextAttemptAt && entry.nextAttemptAt > Date.now()) {
@@ -1418,90 +1645,64 @@ var Session = class {
 						continue;
 					}
 					const operation = this.operations.get(entry.id);
-					const claimed = await this.update((latest) => {
-						const item = latest.mutations.find((item) => item.id === entry.id);
-						if (!item) return false;
-						item.status = "sending";
-						item.attempts += 1;
-						return true;
-					});
+					if (!operation) throw new Error(`fate: Missing restored mutation operation '${entry.id}'.`);
+					const claimed = await this.claim(entry);
 					if (this.disposed) return;
 					if (!claimed) continue;
-					try {
-						const result = await operation.execute({
-							id: entry.id,
-							scope: this.key
-						});
-						if (this.disposed) return;
-						const encoded = encodeHydrationValue(result);
-						operation.commit(result);
-						await this.update(async (latest) => {
-							this.cache.replayChanges([operation.getCacheUpdates()]);
-							const item = latest.mutations.find((item) => item.id === entry.id);
-							if (item) {
-								item.status = "confirmed";
-								delete item.base;
-								item.result = encoded;
-								item.cacheUpdates = operation.getCacheUpdates();
-								item.error = void 0;
-							}
-							for (const pending of latest.mutations) if ((pending.status === "queued" || pending.status === "sending") && pending.scope === this.client.getPersistenceScope()) pending.base = await this.cache.mutationBase(decodeCommand(pending.command), pending.base);
-						});
-						await this.reconcile(await this.load());
-						await this.flush().catch((error) => this.report(error));
-					} catch (error) {
-						if (this.disposed) return;
-						const status = error instanceof Error ? getErrorStatusCode(error) : void 0;
-						if (status && status >= 400 && status < 500 && ![
-							401,
-							403,
-							408,
-							429
-						].includes(status)) {
-							await this.fail(entry.id, error);
-							continue;
-						}
-						await this.update((latest) => {
-							const item = latest.mutations.find((item) => item.id === entry.id);
-							if (item && item.status !== "confirmed") {
-								item.status = "queued";
-								item.nextAttemptAt = Date.now() + Math.min(3e4, this.retryDelay * 2 ** Math.min(item.attempts - 1, 10));
-								item.error = {
-									message: error instanceof Error ? error.message : String(error),
-									status
-								};
-							}
-						});
-						await this.reconcile(await this.load());
-						this.scheduleRetry();
-						return;
-					}
+					if (!await this.deliver(entry, operation)) return;
 				}
 			});
+			if ((this.needsCheckpoint || this.flushRequested) && !this.disposed) await this.flush().catch((error) => this.report(error));
 		} finally {
 			this.draining = false;
 		}
 	}
+	async queueRetry(id, error, status) {
+		await this.updateJournal((latest) => {
+			const item = latest.mutations.find((item) => item.id === id);
+			if (item && isPendingMutation(item)) replaceMutation(latest, id, () => ({
+				...item,
+				error: {
+					message: error instanceof Error ? error.message : String(error),
+					status
+				},
+				nextAttemptAt: Date.now() + Math.min(3e4, this.retryDelay * 2 ** Math.min(item.attempts - 1, 10)),
+				status: "queued"
+			}));
+		});
+		await this.reconcile(await this.loadJournal());
+		this.scheduleRetry();
+	}
 	async discard(id) {
 		await this.ready;
-		if (await this.update((data) => {
+		const outcome = await this.updateJournal((data) => {
 			const entry = data.mutations.find((entry) => entry.id === id);
 			if (entry && entry.attempts > 0 && entry.status !== "failed" && entry.status !== "confirmed") throw new Error("fate: An attempted mutation may have committed remotely and cannot be discarded until its outcome is known.");
-			if (entry?.status === "confirmed") return;
+			if (entry?.status === "confirmed") return "confirmed";
+			if (!entry) return "missing";
 			data.mutations = data.mutations.filter((entry) => entry.id !== id);
-			return true;
-		})) {
+			return "discarded";
+		});
+		if (outcome === "missing") {
+			const operation = this.operations.get(id);
+			if (operation) await this.recoverOperation(id, operation);
+		} else if (outcome === "discarded") {
 			this.operations.get(id)?.rollback();
-			this.operations.delete(id);
-			this.waiters.get(id)?.reject(/* @__PURE__ */ new Error("fate: Mutation was discarded."));
-			this.waiters.delete(id);
+			this.waiters.get(id)?.reject(mutationDiscardedError());
+			this.forgetOperation(id);
 		}
 		await this.refresh();
 	}
 	async clearCache() {
 		await this.ready;
-		await this.storage.exclusive(`${this.key}:write`, () => this.cache.clear());
+		this.assertActive();
+		await this.storage.exclusive(`${this.key}:write`, async () => {
+			this.assertActive();
+			await this.cache.clear();
+		});
+		this.assertActive();
 		await this.cache.initialize();
+		this.clearError();
 	}
 	dispose() {
 		if (this.disposed) return;