local-replica 0.0.0 → 0.0.3

package/dist/createReplicaEngine-CdR-URHo.js

@@ -0,0 +1,2018 @@
+import isEqual from "fast-deep-equal";
+// src/core/resource/storageKey.ts
+/** Persisted row key: one row per entry key and query. */
+const replicaStorageKey = (key, query) => query ? `${key}?${query}` : key;
+/**
+* Whether `storageKey` is a persisted row of entry `key`, under any query.
+*
+* Entry keys are free-form, so a `?` prefix alone cannot tell `foo` + a query
+* from a plain entry `foo?bar`. A row only counts as a variant when it is
+* exactly `replicaStorageKey(key, query)` for a query this module could have
+* written: the rest after `key?` must be a canonical `stableQueryKey` (it
+* parses as JSON and serializes back to itself). Row keys and the index keep
+* their existing flat format, so rows already persisted on devices match the
+* same way.
+*/
+const isReplicaStorageKeyOf = (storageKey, key) => {
+	if (storageKey === key) return true;
+	if (!storageKey.startsWith(`${key}?`)) return false;
+	const query = storageKey.slice(key.length + 1);
+	try {
+		return stableQueryKey(JSON.parse(query)) === query;
+	} catch {
+		return false;
+	}
+};
+/** Deterministic JSON: sorted keys, `undefined` dropped. */
+const stableQueryKey = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.keys(item).sort().filter((key) => item[key] !== void 0).map((key) => [key, item[key]])) : item) ?? "";
+// src/core/resource/queryKeys.ts
+/**
+* Keys of the queries a fetch adapter runs for a replica. Hosts that sweep
+* their query cache by prefix (e.g. "refetch everything after a restore")
+* match on {@link REPLICA_KEY_PREFIX}.
+*/
+const REPLICA_KEY_PREFIX = "replica:";
+const replicaKeys = {
+	/** One-shot read of the persisted row for `storageKey`. */
+	hydrate: (name, version, scope, storageKey) => [
+		"replica:hydrate",
+		name,
+		version,
+		scope,
+		storageKey
+	],
+	/** Network sync of the head of one entry. */
+	sync: (name, version, scope, key, params) => [
+		"replica:sync",
+		name,
+		version,
+		scope,
+		key,
+		params
+	]
+};
+/** Match a resource's sync keys, optionally narrowed to one scope and/or entry key. */
+const isReplicaSyncKey = (queryKey, name, filter = {}) => Array.isArray(queryKey) && queryKey[0] === "replica:sync" && queryKey[1] === name && (filter.scope === void 0 || queryKey[3] === filter.scope) && (filter.key === void 0 || queryKey[4] === filter.key);
+// src/core/paging/operations.ts
+/**
+* First-class pagination for replicas.
+*
+* Vocabulary (direction-agnostic):
+* - HEAD page: the newest window, what a refresh re-fetches (`cursor` undefined).
+* - NEXT pages: further pages in the paging direction (older history).
+*   - `forward`: the view is head-first, next pages append at the END
+*     (sidebar lists: newest topic first, "load more" below).
+*   - `backward`: the view is oldest-first, next pages PREPEND at the start
+*     (chat transcripts: newest message last, "load older" on scroll-up).
+* - `offset` mode: the cursor is the page index (0 = head).
+*   `cursor` mode: the server hands back an opaque `nextCursor`.
+*
+* Every function is pure; the store binding owns staleness and scope.
+*/
+const dedupe = (items, getId, seen = /* @__PURE__ */ new Set()) => {
+	const out = [];
+	for (const item of items) {
+		const id = getId(item);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		out.push(item);
+	}
+	return out;
+};
+const ordered = (items, config) => config.sort ? [...items].sort(config.sort) : items;
+/** Concatenate in view order: forward = head first, backward = head last. */
+const joinPages = (head, rest, direction) => direction === "forward" ? [...head, ...rest] : [...rest, ...head];
+/** The paging config one entry reads with: `directionOf` resolved for `key`. */
+const pagingFor = (config, key) => config.directionOf ? {
+	...config,
+	direction: config.directionOf(key)
+} : config;
+const deriveHasMore = (data, serverCount) => data.total !== void 0 ? data.total > serverCount : data.nextCursor !== null;
+const offsetNext = (more, nextIndex) => more ? nextIndex : null;
+/** Offset mode: whether a page past the loaded ones exists. */
+const offsetHasMore = (page, total, serverCount, pageSize) => {
+	if (page.nextCursor !== void 0) return page.nextCursor !== null;
+	return total !== void 0 ? total > serverCount : page.items.length >= pageSize;
+};
+/**
+* Cursor to request the next page with; `null` → exhausted, `undefined` →
+* cannot page yet. Offset views without bookkeeping (seeded by legacy code or
+* an older persisted shape) derive it from `currentPage` / `hasMore`.
+*/
+const getNextPageCursor = (data, config) => {
+	if (!data) return void 0;
+	if (data.nextCursor !== void 0) return data.nextCursor;
+	if (config.mode === "offset") return data.hasMore ? (data.currentPage ?? 0) + 1 : null;
+	if (!config.deriveCursor || !data.hasMore) return void 0;
+	const boundary = farBoundary(data.items, config);
+	return boundary === void 0 ? void 0 : config.deriveCursor(boundary);
+};
+/**
+* The boundary row on the far side of `items` (forward: last, backward: first)
+* that may anchor a join or derive a cursor.
+*/
+const farBoundary = (items, config) => {
+	const eligible = config.isCursorable ?? (() => true);
+	if (config.direction === "forward") return items.findLast((item) => eligible(item));
+	return items.find((item) => eligible(item));
+};
+const syntheticIds = (items, config) => {
+	if (!config.isCursorable) return void 0;
+	const ids = items.filter((item) => !config.isCursorable(item)).map(config.getId);
+	return ids.length ? ids : void 0;
+};
+const splitClientOnly = (items, ctx) => {
+	if (!ctx.isClientOnly) return {
+		clientOnly: [],
+		server: items
+	};
+	const clientOnly = [];
+	const server = [];
+	for (const item of items) (ctx.isClientOnly(item) ? clientOnly : server).push(item);
+	return {
+		clientOnly,
+		server
+	};
+};
+/**
+* Fold a fresh HEAD page into the view.
+*
+* - First load, a query change (`reset`) or an unextended view → the head page.
+* - Extended view, `offset` mode → keep the loaded depth: fresh head first,
+*   then previously loaded rows not in it (shifted offsets self-heal by id).
+* - Extended view, `cursor` mode → keep older pages only when the fresh head
+*   still contains the join anchor and the next cursor is known; otherwise
+*   collapse to the head page (never show a hidden gap).
+*
+* Client-only rows still in the view are kept on the head side.
+*/
+const applyHeadPage = (current, page, options, config, ctx = {}) => {
+	const { getId, direction } = config;
+	const fresh = dedupe(page.items, getId);
+	const freshIds = new Set(fresh.map(getId));
+	const { clientOnly, server: currentServer } = splitClientOnly(current?.items ?? [], ctx);
+	const survivors = clientOnly.filter((item) => !freshIds.has(getId(item)));
+	const total = page.total ?? (options.reset ? void 0 : current?.total);
+	const headItems = direction === "forward" ? [...survivors, ...fresh] : [...fresh, ...survivors];
+	const headOnly = () => {
+		const nextCursor = config.mode === "offset" ? offsetNext(offsetHasMore(page, total, fresh.length, options.pageSize), 1) : page.nextCursor;
+		const data = {
+			anchorId: void 0,
+			currentPage: 0,
+			headSyntheticIds: syntheticIds(fresh, config),
+			items: ordered(headItems, config),
+			nextCursor,
+			pageSize: options.pageSize,
+			pages: [{
+				count: fresh.length,
+				next: nextCursor
+			}],
+			total
+		};
+		return {
+			...data,
+			hasMore: deriveHasMore(data, fresh.length),
+			isLoadingMore: current?.isLoadingMore,
+			loadMoreError: void 0
+		};
+	};
+	if (!(!!current && current.currentPage > 0 && !options.reset) || config.mode === "offset" && current.pageSize !== options.pageSize) return headOnly();
+	let rest;
+	let anchorId;
+	if (config.mode === "offset") {
+		const restCandidates = currentServer.filter((item) => !freshIds.has(getId(item)));
+		const visible = Math.min(currentServer.length, total ?? Number.POSITIVE_INFINITY);
+		const keep = Math.max(0, visible - fresh.length);
+		rest = direction === "forward" ? restCandidates.slice(0, keep) : restCandidates.slice(Math.max(0, restCandidates.length - keep));
+	} else {
+		const anchorIndex = current.anchorId ? currentServer.findIndex((item) => getId(item) === current.anchorId) : -1;
+		const cursorKnown = current.nextCursor !== void 0 || !!config.deriveCursor;
+		if (anchorIndex === -1 || !freshIds.has(current.anchorId) || !cursorKnown) return headOnly();
+		const farSide = direction === "forward" ? currentServer.slice(anchorIndex + 1) : currentServer.slice(0, anchorIndex);
+		const staleHead = new Set(current.headSyntheticIds);
+		rest = farSide.filter((item) => !freshIds.has(getId(item)) && !staleHead.has(getId(item)));
+		const boundary = farBoundary(fresh, config);
+		anchorId = boundary ? getId(boundary) : current.anchorId;
+	}
+	const headNext = config.mode === "cursor" ? page.nextCursor : current.pages?.[0]?.next;
+	let overlap = (current.pages ?? []).slice(1).reduce((sum, info) => sum + info.count, 0) - rest.length;
+	const olderPages = (current.pages ?? []).slice(1).map((info) => {
+		const shed = Math.min(info.count, Math.max(0, overlap));
+		overlap -= shed;
+		return shed ? {
+			...info,
+			count: info.count - shed
+		} : info;
+	});
+	const pages = [{
+		count: fresh.length,
+		next: headNext
+	}, ...olderPages];
+	const data = {
+		anchorId: anchorId ?? current.anchorId,
+		currentPage: current.currentPage,
+		headSyntheticIds: syntheticIds(fresh, config),
+		items: ordered(joinPages(headItems, rest, direction), config),
+		nextCursor: current.nextCursor,
+		pageSize: options.pageSize,
+		pages,
+		total
+	};
+	return {
+		...data,
+		hasMore: deriveHasMore(data, fresh.length + rest.length),
+		isLoadingMore: current.isLoadingMore,
+		loadMoreError: void 0
+	};
+};
+/** Merge the NEXT page (fetched with `getNextPageCursor`) into the view. */
+const applyNextPage = (current, page, config, ctx = {}) => {
+	const { getId, direction } = config;
+	const seen = new Set(current.items.map(getId));
+	const added = dedupe(page.items, getId, seen);
+	const total = page.total ?? current.total;
+	const serverCount = splitClientOnly(current.items, ctx).server.length + added.length;
+	let next;
+	if (config.mode === "offset") {
+		const more = offsetHasMore(page, total, serverCount, current.pageSize);
+		next = offsetNext(more, current.currentPage + 2);
+	} else next = page.items.length === 0 ? null : page.nextCursor;
+	let anchorId = current.anchorId;
+	if (current.currentPage === 0) {
+		const boundary = farBoundary(splitClientOnly(current.items, ctx).server, config);
+		anchorId = boundary ? getId(boundary) : void 0;
+	}
+	const items = ordered(direction === "forward" ? [...current.items, ...added] : [...added, ...current.items], config);
+	const data = {
+		...current,
+		anchorId,
+		currentPage: current.currentPage + 1,
+		isLoadingMore: false,
+		items,
+		loadMoreError: void 0,
+		nextCursor: next,
+		pages: [...current.pages?.length ? current.pages : [{ count: current.items.length }], {
+			count: added.length,
+			next
+		}],
+		total
+	};
+	return {
+		...data,
+		hasMore: deriveHasMore(data, serverCount)
+	};
+};
+/**
+* Insert new rows on the HEAD side (a streamed message, a created topic).
+* Cursors point at the far end, so they stay valid; offsets shift and are
+* healed by id de-duplication on the next page merge.
+*/
+const insertHeadItems = (current, items, config) => {
+	const seen = new Set(current.items.map(config.getId));
+	const added = dedupe(items, config.getId, seen);
+	if (added.length === 0) return current;
+	const pages = current.pages?.length ? current.pages : [{ count: current.items.length }];
+	return {
+		...current,
+		items: ordered(joinPages(added, current.items, config.direction), config),
+		pages: [{
+			...pages[0],
+			count: pages[0].count + added.length
+		}, ...pages.slice(1)],
+		total: current.total === void 0 ? void 0 : current.total + added.length
+	};
+};
+/**
+* Patch (or remove, when `fn` returns `undefined`) one row by id. Returns the
+* same reference when the row is absent or unchanged.
+*/
+const mapPagedItem = (current, id, fn, config) => {
+	const index = current.items.findIndex((item) => config.getId(item) === id);
+	if (index === -1) return current;
+	const next = fn(current.items[index]);
+	if (next === current.items[index]) return current;
+	if (next !== void 0) {
+		const items = [...current.items];
+		items[index] = next;
+		return {
+			...current,
+			items
+		};
+	}
+	const items = current.items.filter((_, i) => i !== index);
+	const total = current.total === void 0 ? void 0 : Math.max(items.length, current.total - 1);
+	return {
+		...current,
+		hasMore: total !== void 0 ? total > items.length : current.hasMore,
+		items,
+		total
+	};
+};
+/** Whether a paged view holds a row. */
+const hasPagedItem = (data, id, config) => !!data?.items.some((item) => config.getId(item) === id);
+/** Select head-side rows without losing synthetic head rows sorted among older pages. */
+const takeHeadItems = (items, count, data, config) => {
+	if (count === 0) return [];
+	const synthetic = new Set(data.headSyntheticIds);
+	const syntheticCount = items.filter((item) => synthetic.has(config.getId(item))).length;
+	const regular = items.filter((item) => !synthetic.has(config.getId(item)));
+	const regularCount = Math.max(0, count - syntheticCount);
+	const selected = config.direction === "forward" ? regular.slice(0, regularCount) : regular.slice(Math.max(0, regular.length - regularCount));
+	const ids = new Set(selected.map(config.getId));
+	return items.filter((item) => synthetic.has(config.getId(item)) || ids.has(config.getId(item))).slice(config.direction === "forward" ? 0 : -count, config.direction === "forward" ? count : void 0);
+};
+/** Drop every loaded page but the head (e.g. after an edit inside older history). */
+const collapseToHead = (current, config) => {
+	if (current.currentPage === 0) return current;
+	const head = current.pages?.[0];
+	const count = head?.count ?? current.pageSize;
+	const items = takeHeadItems(current.items, count, current, config);
+	const nextCursor = config.mode === "offset" ? 1 : head?.next ?? void 0;
+	return {
+		...current,
+		anchorId: void 0,
+		currentPage: 0,
+		hasMore: true,
+		items,
+		nextCursor,
+		pages: [{
+			count: items.length,
+			next: nextCursor
+		}]
+	};
+};
+/**
+* What survives a reload: whole pages from the head side, bounded by
+* `persist.pages` and `persist.maxItems`, client-only rows and transient
+* flags stripped. Offset views are cut at page-size boundaries so the
+* persisted `currentPage` stays a valid offset; a cut inside a cursor page
+* forgets the cursor (pagination resumes after the next server head page).
+*/
+const toPersistedPage = (data, config, ctx = {}) => {
+	const { server } = splitClientOnly(data.items, ctx);
+	const pageLimit = Math.max(1, config.persist?.pages ?? 1);
+	const maxItems = config.persist?.maxItems ?? Number.POSITIVE_INFINITY;
+	const olderCount = (data.pages ?? []).slice(1).reduce((sum, page) => sum + page.count, 0);
+	const pages = data.pages?.length ? [{
+		...data.pages[0],
+		count: Math.max(0, server.length - olderCount)
+	}, ...data.pages.slice(1)] : [{
+		count: server.length,
+		next: data.nextCursor
+	}];
+	let count = 0;
+	let keptPages = 0;
+	let aligned = true;
+	if (config.mode === "offset") {
+		const loadedPages = Math.min(pageLimit, data.currentPage + 1);
+		const byItems = Math.floor(maxItems / Math.max(1, data.pageSize));
+		keptPages = Math.max(1, Math.min(loadedPages, byItems || 1));
+		count = Math.min(server.length, keptPages * data.pageSize, maxItems);
+	} else {
+		for (const page of pages.slice(0, pageLimit)) {
+			if (count + page.count > maxItems) {
+				aligned = false;
+				count = keptPages === 0 ? Math.min(page.count, maxItems) : count;
+				if (keptPages === 0) keptPages = 1;
+				break;
+			}
+			count += page.count;
+			keptPages += 1;
+		}
+		count = Math.min(count, server.length);
+	}
+	const items = takeHeadItems(server, count, data, config);
+	const lastKept = pages[keptPages - 1];
+	const nextCursor = config.mode === "offset" ? count < (data.total ?? server.length) || count === server.length && data.total === void 0 && data.nextCursor != null ? keptPages : null : aligned ? lastKept?.next : void 0;
+	const { isLoadingMore: _loading, loadMoreError: _error, ...rest } = data;
+	return {
+		...rest,
+		anchorId: keptPages > 1 ? data.anchorId : void 0,
+		currentPage: keptPages - 1,
+		hasMore: data.total !== void 0 ? data.total > items.length : nextCursor !== null,
+		items,
+		nextCursor,
+		pages: [...pages.slice(0, keptPages - 1), {
+			count: Math.max(0, items.length - pages.slice(0, keptPages - 1).reduce((sum, page) => sum + page.count, 0)),
+			next: nextCursor
+		}]
+	};
+};
+// src/core/persistence/writeQueue.ts
+/**
+* Strict read of one row (see `ReplicaStorage.getStrict`). Rejects when the
+* storage has no strict read: its `get` swallows I/O failures into a miss, so a
+* destructive pass reading through it could take an unreadable row (the index)
+* for an empty one and report success for rows it never saw.
+*/
+const readReplicaRowStrict = (storage, key) => storage.getStrict ? storage.getStrict(key) : Promise.reject(/* @__PURE__ */ new Error("[replica] storage has no `getStrict`: destructive passes are disabled"));
+/**
+* Serializes writes for one projection key. A later snapshot can never be overwritten by an
+* earlier, slower IndexedDB write.
+*/
+var ReplicaWriteQueue = class {
+	#pending = /* @__PURE__ */ new Map();
+	#storage;
+	constructor(storage) {
+		this.#storage = storage;
+	}
+	#id = ({ queryKey, scope }) => `${scope}:${queryKey}`;
+	/** Resolves `false` when storage rejected the delete (see `ReplicaStorage.remove`). */
+	remove = (key) => this.#enqueue(key, () => this.#storage.remove(key));
+	set = (key, value) => this.#enqueue(key, () => this.#storage.set(key, value));
+	/**
+	* Serialized read-modify-write: `fn` sees the row as of every earlier queued
+	* write for this key. Return a projection to write it, `null` to remove the
+	* row, or `undefined` to leave it untouched (a missing row stays missing).
+	*
+	* `read` picks how the row is read:
+	* - `'get'` (default): best-effort `get`, a failed read passes for a miss.
+	* - `'prefer-strict'`: `getStrict` when the storage has one, so a read failure
+	*   fails the update (resolves `false`) instead of passing for a missing row
+	*   that `fn` would then overwrite; `get` otherwise.
+	* - `'strict'`: `getStrict` only; a storage without it fails the update.
+	*   Required for destructive passes (see `readReplicaRowStrict`).
+	*/
+	update = (key, fn, { read = "get" } = {}) => this.#enqueue(key, async () => {
+		const storage = this.#storage;
+		const next = fn(await (read === "strict" || read === "prefer-strict" && !!storage.getStrict ? readReplicaRowStrict(storage, key) : storage.get(key)));
+		if (next === null) await this.#storage.remove(key);
+		else if (next !== void 0) await this.#storage.set(key, next);
+	});
+	/**
+	* Queue `operation` behind the earlier writes for this key and report whether
+	* it settled successfully. A failed write never rejects the returned promise:
+	* the caller decides what to do (e.g. keep a removal retryable), while a
+	* rejection on the queue itself is already swallowed so one bad write cannot
+	* poison the chain.
+	*/
+	#enqueue = (key, operation) => {
+		const id = this.#id(key);
+		const current = (this.#pending.get(id) ?? Promise.resolve()).catch(() => void 0).then(operation);
+		this.#pending.set(id, current);
+		const settled = current.then(() => true, () => false);
+		settled.finally(() => {
+			if (this.#pending.get(id) === current) this.#pending.delete(id);
+		});
+		return settled;
+	};
+};
+// src/core/persistence/persistedRows.ts
+/** Reserved storage key of the per-scope index of persisted rows. */
+const REPLICA_INDEX_KEY = "__replica:index";
+/** Returned by a `patchRow` transform to delete the row (`null` stays a value). */
+const DROP_ROW = Symbol("replica.dropRow");
+/**
+* Bookkeeping of the rows one engine persisted: the per-scope index, the latest
+* queued write per row, what each row is known to hold, and the bounded
+* (`persist.maxEntries`) eviction. Every row write and delete of the engine
+* goes through here, so the index never misses or resurrects a row.
+*/
+const createPersistedRows = ({ commit, getSlot, isRemoved, loadingMore, resource, writeQueue }) => {
+	const indexKey = (scope) => ({
+		queryKey: REPLICA_INDEX_KEY,
+		scope
+	});
+	/** Keys known to be in the index row, per scope (skips redundant index writes). */
+	const indexed = /* @__PURE__ */ new Map();
+	const indexedKeys = (scope) => indexed.get(scope);
+	/**
+	* Latest queued write per row (`scope` + storage key), from one monotonic
+	* counter. A confirmed delete only takes its key out of the index when no
+	* later write re-created the row in the meantime.
+	*/
+	const rowWrites = /* @__PURE__ */ new Map();
+	let writeCounter = 0;
+	const writeCount = () => writeCounter;
+	const rowId = (scope, queryKey) => `${scope}\u0000${queryKey}`;
+	const noteWrite = (scope, queryKey) => {
+		const seq = ++writeCounter;
+		rowWrites.set(rowId(scope, queryKey), seq);
+		return seq;
+	};
+	const storedValues = /* @__PURE__ */ new Map();
+	const rememberStored = (scope, queryKey, data) => {
+		const rows = storedValues.get(scope) ?? /* @__PURE__ */ new Map();
+		storedValues.set(scope, rows);
+		rows.set(queryKey, data);
+	};
+	const forgetStored = (scope, queryKeys) => {
+		const rows = storedValues.get(scope);
+		if (!rows) return;
+		for (const queryKey of queryKeys) rows.delete(queryKey);
+		if (rows.size === 0) storedValues.delete(scope);
+	};
+	/** Forget every row of `scope` (memory moved to another identity, or a clear). */
+	const forgetScope = (scope) => {
+		storedValues.delete(scope);
+	};
+	const isStored = (scope, queryKey, data) => {
+		const rows = storedValues.get(scope);
+		return !!rows?.has(queryKey) && isEqual(rows.get(queryKey), data);
+	};
+	/**
+	* A hydrate read `data` back from the row: the row holds it, unless a write
+	* was queued while reading (`writesBefore` is `writeCount()` before the read).
+	*/
+	const rememberRead = (scope, queryKey, data, writesBefore) => {
+		if (writeCounter === writesBefore && !storedValues.get(scope)?.has(queryKey)) rememberStored(scope, queryKey, data);
+	};
+	const maxEntries = resource.maxPersistedEntries;
+	/** Mounted readers per storage key and per entry key (see `retain`). */
+	const retainedRows = /* @__PURE__ */ new Map();
+	const retainedKeys = /* @__PURE__ */ new Map();
+	/** Rows whose eviction delete is queued, per scope. */
+	const evicting = /* @__PURE__ */ new Map();
+	const bump = (counts, id, by) => {
+		const next = (counts.get(id) ?? 0) + by;
+		if (next > 0) counts.set(id, next);
+		else counts.delete(id);
+	};
+	/**
+	* Pin an entry (and the row of the query it asks for) while something shows
+	* it: eviction never drops a retained row or the memory entry of a retained
+	* key. `useSync` retains for as long as it is mounted. Returns the release.
+	*/
+	const retain = (key, queryKey = replicaStorageKey(key)) => {
+		bump(retainedKeys, key, 1);
+		bump(retainedRows, queryKey, 1);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			bump(retainedKeys, key, -1);
+			bump(retainedRows, queryKey, -1);
+		};
+	};
+	/** Rows the memory of `scope` holds, by storage key → entry key. */
+	const loadedRows = (scope) => {
+		const slot = getSlot();
+		const rows = /* @__PURE__ */ new Map();
+		if (slot.scope !== scope) return rows;
+		for (const [key, entry] of Object.entries(slot.entries)) rows.set(replicaStorageKey(key, entry.query), key);
+		return rows;
+	};
+	/**
+	* A row on screen, or whose entry has writes / a page load in flight.
+	* `entryKey` comes from `loadedRows`, so its entry is in the slot.
+	*/
+	const isPinned = (queryKey, entryKey) => retainedRows.has(queryKey) || entryKey !== void 0 && (retainedKeys.has(entryKey) || getSlot().entries[entryKey].pending.length > 0 || loadingMore.has(entryKey));
+	/** The oldest unpinned rows past the cap (`keys` is oldest first). */
+	const pickEvictions = (scope, keys, touched) => {
+		const going = evicting.get(scope);
+		let excess = keys.length - maxEntries - keys.filter((key) => going?.has(key)).length;
+		if (excess <= 0) return [];
+		const loaded = loadedRows(scope);
+		const picked = [];
+		for (const queryKey of keys) {
+			if (excess <= 0) break;
+			if (queryKey === touched || going?.has(queryKey)) continue;
+			if (isPinned(queryKey, loaded.get(queryKey))) continue;
+			picked.push(queryKey);
+			excess -= 1;
+		}
+		return picked;
+	};
+	/**
+	* Evict rows: drop the memory entries that answer them (one commit), then
+	* delete the rows. A row leaves the index only once its delete landed, so a
+	* failed eviction is picked again by a later use.
+	*/
+	const evictRows = (scope, queryKeys) => {
+		if (resource.scope.get() !== scope || !resource.scope.canPersist()) return;
+		const going = evicting.get(scope) ?? /* @__PURE__ */ new Set();
+		evicting.set(scope, going);
+		const loaded = loadedRows(scope);
+		const rows = queryKeys.filter((queryKey) => !going.has(queryKey) && !isPinned(queryKey, loaded.get(queryKey)));
+		if (rows.length === 0) return;
+		for (const queryKey of rows) going.add(queryKey);
+		const dropped = rows.flatMap((queryKey) => {
+			const key = loaded.get(queryKey);
+			return key === void 0 ? [] : [key];
+		});
+		if (dropped.length > 0) {
+			const entries = { ...getSlot().entries };
+			for (const key of dropped) delete entries[key];
+			commit(dropped, {
+				entries,
+				scope
+			});
+		}
+		deleteRows(scope, rows).finally(() => {
+			for (const queryKey of rows) going.delete(queryKey);
+			if (going.size === 0 && evicting.get(scope) === going) evicting.delete(scope);
+		});
+	};
+	/**
+	* A bounded resource used a row: move it to the end of the index and evict
+	* past the cap. No-op for an unbounded resource.
+	*/
+	const touchStorageKey = (scope, queryKey) => {
+		if (!writeQueue || maxEntries === void 0) return;
+		const known = indexed.get(scope) ?? /* @__PURE__ */ new Set();
+		indexed.set(scope, known);
+		known.add(queryKey);
+		let picked = [];
+		writeQueue.update(indexKey(scope), (current) => {
+			const keys = current?.data ?? [];
+			const next = [...keys.filter((key) => key !== queryKey), queryKey];
+			picked = pickEvictions(scope, next, queryKey);
+			if (keys.length === next.length && keys.at(-1) === queryKey) return void 0;
+			return {
+				data: next,
+				updatedAt: Date.now()
+			};
+		}, { read: "prefer-strict" }).then((touched) => {
+			if (!touched) return void known.delete(queryKey);
+			if (picked.length > 0) evictRows(scope, picked);
+		});
+	};
+	/** Record a persisted row in the index (queued after the row write; see `writeRow`). */
+	const trackStorageKey = (scope, queryKey) => {
+		noteWrite(scope, queryKey);
+		if (maxEntries !== void 0) return touchStorageKey(scope, queryKey);
+		const known = indexed.get(scope) ?? /* @__PURE__ */ new Set();
+		indexed.set(scope, known);
+		if (known.has(queryKey)) return;
+		known.add(queryKey);
+		writeQueue.update(indexKey(scope), (current) => {
+			const keys = new Set(current?.data ?? []);
+			if (keys.has(queryKey)) return void 0;
+			keys.add(queryKey);
+			return {
+				data: [...keys],
+				updatedAt: Date.now()
+			};
+		}, { read: "prefer-strict" }).then((tracked) => {
+			if (!tracked) known.delete(queryKey);
+		});
+	};
+	/**
+	* Read the index for a destructive pass (remove / clear / entity patch).
+	* Uses the storage's strict read when it has one, so an unreadable index
+	* rejects instead of looking empty — a purge must never report success for
+	* rows it could not enumerate.
+	*/
+	const readIndex = async (scope) => {
+		return (await readReplicaRowStrict(resource.storage, indexKey(scope)))?.data ?? [];
+	};
+	/**
+	* Drop storage keys from the index (both the session's view of it and the
+	* persisted row, which may list keys this session never wrote).
+	*/
+	const untrackStorageKeys = (scope, queryKeys) => {
+		if (!writeQueue || queryKeys.length === 0) return;
+		const known = indexed.get(scope);
+		for (const queryKey of queryKeys) known?.delete(queryKey);
+		const dropped = new Set(queryKeys);
+		writeQueue.update(indexKey(scope), (current) => {
+			const keys = current?.data ?? [];
+			const next = keys.filter((queryKey) => !dropped.has(queryKey));
+			if (!current || next.length === keys.length) return void 0;
+			return {
+				data: next,
+				updatedAt: Date.now()
+			};
+		}, { read: "prefer-strict" });
+	};
+	/** Take rows whose delete landed out of the index, unless rewritten since. */
+	const confirmDeleted = (scope, deleted) => {
+		const gone = deleted.filter(([queryKey, seq]) => rowWrites.get(rowId(scope, queryKey)) === seq).map(([queryKey]) => queryKey);
+		for (const queryKey of gone) rowWrites.delete(rowId(scope, queryKey));
+		untrackStorageKeys(scope, gone);
+	};
+	/**
+	* Queue row deletes now (ordered before any later write to the same rows).
+	* A key leaves the index only once its delete is confirmed: a failed delete
+	* stays indexed, so the next `remove` / `clear` finds and retries it.
+	* Resolves `true` when every delete landed.
+	*/
+	const deleteRows = (scope, queryKeys) => {
+		const queue = writeQueue;
+		forgetStored(scope, queryKeys);
+		const queued = queryKeys.map((queryKey) => {
+			const seq = noteWrite(scope, queryKey);
+			return queue.remove({
+				queryKey,
+				scope
+			}).then((removed) => removed ? [queryKey, seq] : void 0);
+		});
+		return Promise.all(queued).then((results) => {
+			confirmDeleted(scope, results.filter((result) => !!result));
+			return results.every(Boolean);
+		});
+	};
+	/**
+	* Delete every persisted row of entry `key` in `scope` — `current` (the row
+	* memory knows about, queued right away so it orders before any later write)
+	* plus every other query variant the index lists. Resolves `true` once all
+	* deletes landed.
+	*/
+	const removeStoredVariants = (scope, key, current) => {
+		const first = deleteRows(scope, [current]);
+		const rest = readIndex(scope).then((persisted) => {
+			const slot = getSlot();
+			const live = !isRemoved(scope, key) && slot.scope === scope ? slot.entries[key] : void 0;
+			const liveKey = live && replicaStorageKey(key, live.query);
+			const variants = new Set([...indexed.get(scope) ?? [], ...persisted].filter((queryKey) => queryKey !== current && queryKey !== liveKey && isReplicaStorageKeyOf(queryKey, key)));
+			return variants.size === 0 ? true : deleteRows(scope, [...variants]);
+		}, () => false);
+		return Promise.all([first, rest]).then((results) => results.every(Boolean));
+	};
+	/** Persist `data` to one row (the write path of a `persist` effect). */
+	const writeRow = (scope, queryKey, data) => {
+		const queue = writeQueue;
+		if (isStored(scope, queryKey, data)) {
+			touchStorageKey(scope, queryKey);
+			return;
+		}
+		forgetStored(scope, [queryKey]);
+		trackStorageKey(scope, queryKey);
+		const id = rowId(scope, queryKey);
+		const seq = rowWrites.get(id);
+		queue.set({
+			queryKey,
+			scope
+		}, {
+			data,
+			updatedAt: Date.now()
+		}).then((written) => {
+			if (written && rowWrites.get(id) === seq) rememberStored(scope, queryKey, data);
+		});
+	};
+	/**
+	* Read-modify-write one row in the per-key write queue, so it sees every
+	* earlier write; a missing row is never recreated. `transform` returns the
+	* next data, `undefined` to leave the row, or `DROP_ROW` to drop it (the row
+	* leaves the index once its delete landed). Resolves whether it settled.
+	*/
+	const patchRow = (scope, queryKey, transform) => {
+		const seq = noteWrite(scope, queryKey);
+		forgetStored(scope, [queryKey]);
+		let dropped = false;
+		return writeQueue.update({
+			queryKey,
+			scope
+		}, (current) => {
+			if (!current) return void 0;
+			const next = transform(current.data);
+			if (next === void 0) return void 0;
+			if (next === DROP_ROW) {
+				dropped = true;
+				return null;
+			}
+			return {
+				data: next,
+				updatedAt: Date.now()
+			};
+		}, { read: "strict" }).then((written) => {
+			if (written && dropped) confirmDeleted(scope, [[queryKey, seq]]);
+			return written;
+		});
+	};
+	/**
+	* Read-modify-write the persisted rows memory does not hold, keyed by row
+	* rather than by entity: a cached list for a folder the user is not viewing
+	* gets its projection patched in the per-key write queue, so a later visit
+	* hydrates the reconciled value instead of a stale page. `fn` returns the
+	* next data, the same reference (or `undefined`) to skip, or `null` to drop
+	* the row. Runs in the write queue, so it sees every earlier write.
+	*/
+	const patchStoredRows = async (fn) => {
+		if (!writeQueue || !resource.scope.canPersist()) return;
+		const scope = resource.scope.get();
+		const slot = getSlot();
+		const loaded = new Set(slot.scope === scope ? Object.entries(slot.entries).map(([key, entry]) => replicaStorageKey(key, entry.query)) : []);
+		let keys;
+		try {
+			keys = await readIndex(scope);
+		} catch (error) {
+			console.error(`[replica:${resource.name}] failed to read the persisted index`, error);
+			return;
+		}
+		if (resource.scope.get() !== scope) return;
+		const patches = [];
+		for (const queryKey of keys) {
+			if (loaded.has(queryKey)) continue;
+			patches.push(patchRow(scope, queryKey, (data) => {
+				const next = fn(data);
+				if (next === data) return void 0;
+				return next === null ? DROP_ROW : next;
+			}));
+		}
+		await Promise.all(patches);
+	};
+	return {
+		deleteRows,
+		forgetScope,
+		forgetStored,
+		indexedKeys,
+		patchRow,
+		patchStoredRows,
+		readIndex,
+		rememberRead,
+		removeStoredVariants,
+		retain,
+		touchStorageKey,
+		writeCount,
+		writeRow
+	};
+};
+// src/core/entity/propagation.ts
+/**
+* Entity propagation: a change to one entity (e.g. a topic) applied to every
+* entry that holds it — in memory, in persisted rows memory does not hold,
+* and in rows a hydrate reads back while a removal is still landing.
+*/
+const createEntityPropagation = ({ beginOptimistic, entity, entityGuards, getSlot, paging, port, remove, resource, rows, update }) => {
+	const entityKeys = (id) => {
+		return (port.keys?.() ?? Object.keys(getSlot().entries)).filter((key) => {
+			const data = port.read(key);
+			if (data === void 0) return false;
+			if (paging) return hasPagedItem(data, id, paging);
+			return entity ? entity.has(data, id) : false;
+		});
+	};
+	/** Map one entity inside a value; `undefined` means the whole value goes away. */
+	const mapEntity = (data, id, fn) => {
+		if (paging) return mapPagedItem(data, id, fn, paging);
+		if (!entity || !entity.has(data, id)) return data;
+		return entity.map(data, id, fn);
+	};
+	/** Which of `ids` are held by `data`. */
+	const heldEntities = (data, ids) => {
+		if (paging) {
+			const items = data.items ?? [];
+			const present = new Set(items.map((item) => paging.getId(item)));
+			return ids.filter((id) => present.has(id));
+		}
+		return entity ? ids.filter((id) => entity.has(data, id)) : [];
+	};
+	/** Strip entities removed in `scope` from a value read back from storage. */
+	const withoutRemovedEntities = (scope, data) => {
+		const removed = entityGuards.removedIds(scope);
+		if (removed.length === 0) return data;
+		let next = data;
+		for (const id of heldEntities(data, removed)) {
+			next = mapEntity(next, id, () => void 0);
+			if (next === void 0) break;
+		}
+		return next;
+	};
+	/** A server value holding a removed entity again (restored) lifts its guard. */
+	const forgetRestoredEntities = (scope, data) => {
+		const removed = entityGuards.removedIds(scope);
+		if (removed.length === 0 || data === void 0) return;
+		entityGuards.liftEntityGuards(scope, heldEntities(data, removed));
+	};
+	/**
+	* Apply an entity change to persisted rows that memory does not hold (the
+	* memory path already persists loaded entries). Read-modify-write runs in
+	* the per-key write queue, so it sees every earlier write; a missing row is
+	* never recreated. Resolves once the patches have settled: `true` when every
+	* unloaded row is known to be patched (or nothing is persisted), `false` when
+	* a row may still hold the old entity (untrusted scope, unreadable index or
+	* row, a failed write, an identity switch mid-pass).
+	*/
+	const patchStoredEntityRows = async (id, fn, scope = resource.scope.get()) => {
+		if (!resource.storage) return true;
+		if (!resource.scope.canPersist()) return false;
+		const offScope = scope !== resource.scope.get();
+		const slot = getSlot();
+		const loaded = new Set(!offScope && slot.scope === scope ? Object.entries(slot.entries).map(([key, entry]) => replicaStorageKey(key, entry.query)) : []);
+		let keys;
+		try {
+			keys = await rows.readIndex(scope);
+		} catch (error) {
+			console.error(`[replica:${resource.name}] failed to read the persisted index`, error);
+			return false;
+		}
+		if (!offScope && resource.scope.get() !== scope) return false;
+		for (const queryKey of rows.indexedKeys(scope) ?? []) if (!keys.includes(queryKey)) keys.push(queryKey);
+		const patches = [];
+		for (const queryKey of keys) {
+			if (loaded.has(queryKey)) continue;
+			patches.push(rows.patchRow(scope, queryKey, (data) => {
+				const next = mapEntity(data, id, fn);
+				if (next === data) return void 0;
+				return next === void 0 ? DROP_ROW : next;
+			}));
+		}
+		return (await Promise.all(patches)).every(Boolean);
+	};
+	const patchStoredEntity = async (id, fn) => {
+		await patchStoredEntityRows(id, fn);
+	};
+	/**
+	* `updateEntity`, returning the persisted-row patch (if any) to wait on —
+	* `true` once every unloaded row is patched.
+	*/
+	const applyEntity = (id, fn, { persist = true } = {}) => {
+		const patch = persist ? patchStoredEntityRows(id, fn) : void 0;
+		for (const key of entityKeys(id)) {
+			const current = port.read(key);
+			if (current === void 0) continue;
+			if (mapEntity(current, id, fn) === void 0) remove(key);
+			else update(key, (data) => data === void 0 ? data : mapEntity(data, id, fn) ?? data, { persist });
+		}
+		return patch;
+	};
+	/**
+	* An entity patch started for a scope that was not active settled. If the
+	* user switched back to that scope meanwhile, an entry may have hydrated the
+	* pre-patch row before the patch landed: apply the same change to what is
+	* loaded now, in memory only — storage already holds it.
+	*/
+	const reconcileLoaded = (scope, id, fn) => {
+		if (resource.scope.get() !== scope || getSlot().scope !== scope) return;
+		for (const key of entityKeys(id)) {
+			const current = port.read(key);
+			if (current === void 0) continue;
+			rows.forgetStored(scope, [replicaStorageKey(key, getSlot().entries[key]?.query)]);
+			if (mapEntity(current, id, fn) === void 0) remove(key);
+			else update(key, (data) => data === void 0 ? data : mapEntity(data, id, fn) ?? data, { persist: false });
+		}
+	};
+	/**
+	* Confirmed patch of one entity everywhere it is loaded and in the persisted
+	* rows of unloaded entries. `scope` targets a scope captured earlier (a
+	* write confirmed after the account switched): when it is no longer active,
+	* only that scope's persisted rows are patched and the view on screen —
+	* another identity's — is left alone.
+	*/
+	const updateEntity = (id, fn, options) => {
+		if (options?.scope !== void 0 && options.scope !== resource.scope.get()) {
+			const scope = options.scope;
+			if (options.persist === false) return;
+			const settle = () => reconcileLoaded(scope, id, fn);
+			patchStoredEntityRows(id, fn, scope).then(settle, settle);
+			return;
+		}
+		applyEntity(id, fn, options);
+	};
+	/**
+	* Confirmed removal of one entity everywhere (see `updateEntity`, including
+	* its captured `scope`). Unlike a plain mapper returning `undefined`, it is
+	* also remembered for that scope:
+	* a value hydrated afterwards — even by a read already in flight — comes
+	* back without the entity (see `createEntityRemovalGuards`).
+	*/
+	const removeEntity = (id, options) => {
+		const scope = options?.scope ?? resource.scope.get();
+		const offScope = scope !== resource.scope.get();
+		const release = entityGuards.guardEntity(scope, id);
+		const patch = offScope ? options?.persist === false ? void 0 : patchStoredEntityRows(id, () => void 0, scope).then((patched) => {
+			reconcileLoaded(scope, id, () => void 0);
+			return patched;
+		}) : applyEntity(id, () => void 0, options);
+		if (patch) patch.then((patched) => {
+			if (patched) release();
+		}, () => void 0);
+		else release();
+	};
+	const beginEntityOptimistic = (id, fn) => entityKeys(id).flatMap((key) => {
+		if (!paging) {
+			const current = port.read(key);
+			if (current !== void 0 && mapEntity(current, id, fn) === void 0) return [];
+		}
+		return [beginOptimistic(key, (data) => mapEntity(data, id, fn) ?? data)];
+	});
+	return {
+		beginEntityOptimistic,
+		entityKeys,
+		forgetRestoredEntities,
+		patchStoredEntity,
+		removeEntity,
+		updateEntity,
+		withoutRemovedEntities
+	};
+};
+// src/core/state/reducer.ts
+const createReplicaState = () => ({ entries: {} });
+const materialize = (base, pending) => base === void 0 ? void 0 : pending.reduce((data, mutation) => mutation.apply(data), base);
+const noop = (state) => ({
+	effects: [],
+	state,
+	writes: []
+});
+/**
+* Drop the seed patches a new seed write of `tag` supersedes: those of the same
+* tag after the last confirmed patch. Repeated refreshes of one source then keep
+* one patch instead of one per refresh, while the order relative to confirmed
+* writes (and to other sources' seeds) is preserved.
+*/
+const coalesceSeedPatches = (patches, isSeedWrite, tag) => {
+	if (!isSeedWrite) return patches;
+	let lastConfirmed = -1;
+	patches.forEach((patch, index) => {
+		if (!patch.seed) lastConfirmed = index;
+	});
+	return patches.filter((patch, index) => index <= lastConfirmed || !patch.seed || patch.tag !== tag);
+};
+const replicaReducer = (state, action, readView, now = Date.now()) => {
+	if (action.type === "resetScope") {
+		if (state.scope === action.scope) return noop(state);
+		return {
+			effects: [],
+			state: {
+				entries: {},
+				scope: action.scope
+			},
+			writes: state.scope === void 0 ? [] : [{ type: "clear" }]
+		};
+	}
+	if (state.scope !== void 0 && state.scope !== action.scope) return noop(state);
+	const scope = action.scope;
+	const entry = state.entries[action.key];
+	const view = readView(action.key);
+	const confirmed = entry?.pending.length ? entry.base : view;
+	const withEntry = (next) => {
+		const entries = { ...state.entries };
+		if (next) entries[action.key] = next;
+		else delete entries[action.key];
+		return {
+			entries,
+			scope
+		};
+	};
+	switch (action.type) {
+		case "hydrate": {
+			const provisionalSeed = !!entry && entry.source === "seed" && entry.pending.length === 0;
+			if (entry && !provisionalSeed) {
+				if (!action.overwrite || entry.query === action.query || entry.pending.some((mutation) => mutation.query === void 0)) return noop(state);
+			} else if (!entry && view !== void 0) return noop(state);
+			const patches = provisionalSeed && entry.seedPatches || [];
+			const data = patches.reduce((value, patch) => patch.apply(value) ?? value, action.data);
+			const confirmedPatches = patches.filter((patch) => !patch.seed);
+			return {
+				effects: confirmedPatches.some((patch) => patch.persist) ? [{
+					data,
+					key: action.key,
+					query: action.query,
+					scope,
+					type: "persist"
+				}] : [],
+				state: withEntry({
+					params: action.params,
+					pending: [],
+					query: action.query,
+					source: confirmedPatches.length ? "local" : "storage",
+					updatedAt: confirmedPatches.length ? now : action.updatedAt ?? now
+				}),
+				writes: [{
+					data,
+					key: action.key
+				}]
+			};
+		}
+		case "replace": {
+			const pending = (entry?.pending ?? []).filter((mutation) => mutation.query === void 0 || mutation.query === action.query);
+			const basis = entry && entry.query !== action.query ? entry.base ?? view : confirmed;
+			const next = action.data(basis) ?? basis;
+			const query = "query" in action ? action.query : entry?.query;
+			const nextState = withEntry({
+				base: pending.length ? next : void 0,
+				params: action.params ?? entry?.params,
+				pending,
+				query,
+				source: "server",
+				updatedAt: now
+			});
+			if (next === void 0) return {
+				effects: [],
+				state: nextState,
+				writes: []
+			};
+			const nextView = materialize(next, pending);
+			return {
+				effects: [{
+					data: next,
+					key: action.key,
+					query,
+					scope,
+					type: "persist"
+				}],
+				state: nextState,
+				writes: nextView === view ? [] : [{
+					data: nextView,
+					key: action.key
+				}]
+			};
+		}
+		case "update": {
+			const nextView = action.apply(view);
+			const pending = entry?.pending ?? [];
+			const nextBase = pending.length ? action.apply(entry.base) : nextView;
+			if (nextView === view && nextBase === confirmed) return noop(state);
+			const source = entry?.source ?? (view === void 0 ? action.source ?? "local" : "local");
+			const persist = action.persist && source !== "seed";
+			const isSeedWrite = action.source === "seed";
+			const seedPatches = source === "seed" ? [...coalesceSeedPatches(entry?.seedPatches ?? [], isSeedWrite, action.seedTag), {
+				apply: action.apply,
+				persist: !isSeedWrite && action.persist,
+				...isSeedWrite && {
+					seed: true,
+					tag: action.seedTag
+				}
+			}] : entry?.seedPatches;
+			return {
+				effects: persist && nextBase !== void 0 ? [{
+					data: nextBase,
+					key: action.key,
+					query: entry?.query,
+					scope,
+					type: "persist"
+				}] : [],
+				state: withEntry({
+					...entry,
+					base: pending.length ? nextBase : void 0,
+					pending,
+					seedPatches,
+					source,
+					updatedAt: now
+				}),
+				writes: nextView === view ? [] : [{
+					data: nextView,
+					key: action.key
+				}]
+			};
+		}
+		case "optimistic": {
+			if (view === void 0) return noop(state);
+			const pending = [...entry?.pending ?? [], {
+				apply: action.apply,
+				id: action.id,
+				query: action.query
+			}];
+			return {
+				effects: [],
+				state: withEntry({
+					...entry,
+					base: confirmed,
+					pending,
+					source: entry?.source ?? "local",
+					updatedAt: entry?.updatedAt ?? now
+				}),
+				writes: [{
+					data: action.apply(view),
+					key: action.key
+				}]
+			};
+		}
+		case "commit":
+		case "rollback": {
+			const mutation = entry?.pending.find((item) => item.id === action.id);
+			if (!entry || !mutation) return noop(state);
+			const pending = entry.pending.filter((item) => item.id !== action.id);
+			const base = action.type === "commit" && entry.base !== void 0 ? (action.confirm ?? mutation.apply)(entry.base) : entry.base;
+			const nextView = action.type === "commit" && !action.confirm ? view : materialize(base, pending);
+			return {
+				effects: action.type === "commit" && base !== void 0 ? [{
+					data: base,
+					key: action.key,
+					query: entry.query,
+					scope,
+					type: "persist"
+				}] : [],
+				state: withEntry({
+					...entry,
+					base: pending.length ? base : void 0,
+					pending,
+					source: entry.source,
+					updatedAt: action.type === "commit" ? now : entry.updatedAt
+				}),
+				writes: nextView === view ? [] : [{
+					data: nextView,
+					key: action.key
+				}]
+			};
+		}
+		case "remove": return {
+			effects: [{
+				key: action.key,
+				query: entry?.query,
+				scope,
+				type: "remove"
+			}],
+			state: withEntry(void 0),
+			writes: view === void 0 ? [] : [{
+				data: void 0,
+				key: action.key
+			}]
+		};
+	}
+};
+// src/core/engine/pagination.ts
+/**
+* The engine's paged-resource transitions: folding a head page into the loaded
+* pages, fetching the next page, head inserts and collapsing back to the head.
+* The pure page math lives in `paging/operations.ts`; this adds the entry,
+* scope and in-flight bookkeeping around it. Every method is a no-op (or a
+* pass-through) for a non-paged resource.
+*/
+const createPagination = ({ fetcher, getSlot, loadingMore, options, port, resource, update }) => {
+	const paging = resource.paging;
+	const at = (key) => pagingFor(paging, key);
+	const pagingCtx = { isClientOnly: options.isClientOnly };
+	/** The persistable part of a paged value (the value itself when not paged). */
+	const toPersisted = (data) => paging ? toPersistedPage(data, paging, pagingCtx) : data;
+	/**
+	* An overwrite hydrate repaints the entry from another query's persisted page.
+	* Client-only rows (an in-flight upload / create) have no server row yet, so
+	* that page cannot contain them — keep the ones still in the view, so a
+	* same-pool query change (a re-sort, a view-mode switch) never drops them.
+	* A cross-pool navigate is not "client-only" for the new params and is dropped.
+	*/
+	const keepClientOnlyRows = (incoming, current, key) => {
+		if (!paging || !options.isClientOnly || !current) return incoming;
+		const page = incoming;
+		const currentItems = current.items ?? [];
+		const incomingIds = new Set(page.items.map((item) => paging.getId(item)));
+		const survivors = currentItems.filter((item) => options.isClientOnly(item) && !incomingIds.has(paging.getId(item)));
+		if (survivors.length === 0) return incoming;
+		const items = joinPages(survivors, page.items, at(key).direction);
+		return {
+			...incoming,
+			items
+		};
+	};
+	const viewMatchesFields = (current, params) => {
+		const fields = options.viewFields?.(params);
+		if (!current || !fields) return true;
+		const norm = (value) => stableQueryKey(value || null);
+		return Object.entries(fields).every(([field, value]) => norm(value) === norm(current[field]));
+	};
+	const mergeHead = (key, incoming, confirmed, params, reset) => {
+		const page = incoming;
+		const pageSize = params.pageSize ?? page.items.length;
+		const merged = {
+			...applyHeadPage(confirmed, page, {
+				pageSize,
+				reset
+			}, at(key), pagingCtx),
+			...options.viewFields?.(params),
+			isLoadingMore: loadingMore.has(key)
+		};
+		const next = {
+			...confirmed,
+			...merged
+		};
+		return confirmed !== void 0 && isEqual(next, confirmed) ? void 0 : next;
+	};
+	/**
+	* Fetch and merge the next page with the params of the loaded head page
+	* (`fallbackParams` covers views seeded outside `useSync`). In `cursor` mode
+	* paging only starts from a server-confirmed head page: a hydrated cursor
+	* may be stale. A result is dropped when the scope, the query or the loaded
+	* depth changed while it was in flight.
+	*/
+	const loadMore = async (key, fallbackParams) => {
+		if (!paging || !fetcher) return;
+		const entry = getSlot().entries[key];
+		const current = port.read(key);
+		if (!current || loadingMore.has(key)) return;
+		if (paging.mode === "cursor" && entry?.source === "storage") return;
+		const params = entry?.params ?? fallbackParams;
+		if (params === void 0) return;
+		const cursor = getNextPageCursor(current, at(key));
+		if (cursor === null || cursor === void 0) return;
+		const query = entry?.query;
+		const scope = resource.scope.get();
+		const depth = current.currentPage;
+		const setLoading = (patch) => update(key, (data) => data && {
+			...data,
+			...patch
+		}, { persist: false });
+		loadingMore.add(key);
+		setLoading({
+			isLoadingMore: true,
+			loadMoreError: void 0
+		});
+		const isCurrent = () => {
+			const latest = port.read(key);
+			return resource.scope.get() === scope && getSlot().entries[key]?.query === query && latest?.currentPage === depth;
+		};
+		try {
+			const page = await fetcher(params, cursor);
+			if (!isCurrent()) return void setLoading({ isLoadingMore: false });
+			update(key, (data) => data && applyNextPage(data, page, at(key), pagingCtx), { persist: (paging.persist?.pages ?? 1) > 1 });
+		} catch (error) {
+			setLoading({
+				isLoadingMore: false,
+				loadMoreError: isCurrent() ? error : void 0
+			});
+		} finally {
+			loadingMore.delete(key);
+		}
+	};
+	/** Insert rows at the head (new / streamed items). */
+	const insertHead = (key, items, { persist = false } = {}) => paging ? update(key, (data) => data && insertHeadItems(data, items, at(key)), { persist }) : false;
+	/** Drop loaded pages, keeping the head (e.g. after an edit inside older pages). */
+	const collapse = (key) => paging ? update(key, (data) => data && collapseToHead(data, at(key)), { persist: false }) : false;
+	return {
+		collapse,
+		insertHead,
+		keepClientOnlyRows,
+		loadMore,
+		mergeHead,
+		toPersisted,
+		viewMatchesFields
+	};
+};
+// src/core/engine/tombstones.ts
+/**
+* How many removal tombstones one engine remembers. The guards exist to win a
+* race with a hydrate that started around a removal, so a modest window is
+* plenty; the cap is what keeps a long-lived session from growing forever.
+*/
+const DEFAULT_REMOVAL_TOMBSTONE_LIMIT = 5e3;
+/**
+* Scope-keyed removal tombstones with a hard size bound.
+*
+* A removal must stay visible until a server value supersedes it — including
+* across a scope switch, so the keys are bucketed per scope rather than in one
+* flat set. But the engine lives as long as the page: a session that visits tens
+* of thousands of subjects (a task list full of items that simply have no
+* acceptance) would otherwise pin one entry per subject forever. So the oldest
+* keys are evicted once the cap is reached.
+*
+* Eviction is safe for what the tombstone is for: it closes a race with a
+* hydrate that was already in flight when the removal landed. By the time a key
+* is old enough to be evicted, any such read has long since settled.
+*/
+const createTombstones = (limit = DEFAULT_REMOVAL_TOMBSTONE_LIMIT) => {
+	const byScope = /* @__PURE__ */ new Map();
+	let tracked = 0;
+	const evictOverflow = () => {
+		while (tracked > limit) {
+			const oldestScope = byScope.keys().next().value;
+			const keys = byScope.get(oldestScope);
+			keys.delete(keys.values().next().value);
+			tracked -= 1;
+			if (keys.size === 0) byScope.delete(oldestScope);
+		}
+	};
+	return {
+		add: (scope, key) => {
+			const keys = byScope.get(scope) ?? /* @__PURE__ */ new Set();
+			byScope.set(scope, keys);
+			if (keys.has(key)) return;
+			keys.add(key);
+			tracked += 1;
+			evictOverflow();
+		},
+		clear: (scope, key) => {
+			const keys = byScope.get(scope);
+			if (!keys?.delete(key)) return;
+			tracked -= 1;
+			if (keys.size === 0) byScope.delete(scope);
+		},
+		has: (scope, key) => byScope.get(scope)?.has(key) ?? false,
+		size: () => tracked
+	};
+};
+// src/core/engine/removalGuards.ts
+/**
+* Removal guard of one engine.
+*
+* An explicit removal (a deleted / unauthorized aggregate, or a subject whose
+* attachment is gone) drops the entry AND its persisted row — but a read of
+* that row that started before the removal still holds the old value, and a
+* removal leaves no trace in the slots for the `hydrate` guard to see. So a
+* scope+key is remembered as removed and refuses hydration until a server
+* value supersedes it, otherwise the late read resurrects the exact value the
+* removal just dropped.
+*/
+const createRemovalGuards = () => {
+	const removedEntries = createTombstones();
+	/**
+	* Keys whose persisted row delete was actually queued. `runEffects` refuses to
+	* write while the scope is untrusted, so a removal made on a cold boot can arm
+	* the guard without clearing the row. The guard alone must therefore not turn
+	* a later removal into a no-op, or the stale row would survive and hydrate
+	* again once the scope becomes trusted.
+	*/
+	const purgedEntries = createTombstones();
+	/**
+	* Bumped on every removal of a scope+key. A network response whose request
+	* started before the entry was removed (deleted, access revoked, pruned by an
+	* authoritative parent list) must not `replace` it back: the slice records
+	* the generation a request starts under and drops a response that crossed a
+	* removal. Bounded like the tombstones; an evicted key reads 0, which only
+	* ever drops a response (the next revalidate refetches), never admits one.
+	*/
+	const removalGenerations = /* @__PURE__ */ new Map();
+	const removalId = (scope, key) => `${scope}\u0000${key}`;
+	const removalGeneration = (scope, key) => removalGenerations.get(removalId(scope, key)) ?? 0;
+	const markRemoved = (scope, key) => {
+		removedEntries.add(scope, key);
+		const id = removalId(scope, key);
+		const next = (removalGenerations.get(id) ?? 0) + 1;
+		removalGenerations.delete(id);
+		removalGenerations.set(id, next);
+		if (removalGenerations.size > 5e3) removalGenerations.delete(removalGenerations.keys().next().value);
+	};
+	const clearRemoved = (scope, key) => {
+		removedEntries.clear(scope, key);
+		purgedEntries.clear(scope, key);
+	};
+	const isRemoved = (scope, key) => removedEntries.has(scope, key);
+	const markPurged = (scope, key) => purgedEntries.add(scope, key);
+	const isPurged = (scope, key) => purgedEntries.has(scope, key);
+	return {
+		clearRemoved,
+		isPurged,
+		isRemoved,
+		markPurged,
+		markRemoved,
+		removalGeneration
+	};
+};
+/**
+* Entity removal guards of one engine.
+*
+* A hydrate that read its row before `removeEntity` patched storage still
+* holds the entity, so it is stripped from every value that hydrates while
+* such a read may be pending. A guard's lifetime follows the hydrates, not a
+* count: it is released once its storage patch landed (`releasedAt`) and is
+* dropped as soon as no hydrate that started before that point is pending.
+* So memory stays bounded by in-flight reads, and no guard a pending read
+* still needs is ever evicted. A patch that did not land is never released:
+* the unloaded row still holds the entity, so every later hydrate needs the
+* guard. A server value holding the entity again (restored) lifts it early.
+*/
+const createEntityRemovalGuards = () => {
+	/** Logical clock shared by hydrate starts and guard releases. */
+	let guardClock = 0;
+	/** Start ticks of the hydrates in flight, per scope. */
+	const pendingHydrates = /* @__PURE__ */ new Map();
+	/** Removed entity ids per scope; `releasedAt` is unset until the storage patch landed. */
+	const removedEntities = /* @__PURE__ */ new Map();
+	const removedIds = (scope) => [...removedEntities.get(scope)?.keys() ?? []];
+	/** Drop the guards no pending hydrate of `scope` can still need. */
+	const pruneEntityGuards = (scope) => {
+		const guards = removedEntities.get(scope);
+		if (!guards) return;
+		let oldestPending = Infinity;
+		for (const start of pendingHydrates.get(scope) ?? []) oldestPending = Math.min(oldestPending, start);
+		for (const [id, guard] of guards) if (guard.releasedAt !== void 0 && guard.releasedAt <= oldestPending) guards.delete(id);
+		if (guards.size === 0) removedEntities.delete(scope);
+	};
+	/**
+	* Mark a hydrate of `scope` pending until settled: entity guards outlive every
+	* read that may hold them. Returns the settle.
+	*/
+	const startHydrate = (scope) => {
+		const start = ++guardClock;
+		const pending = pendingHydrates.get(scope) ?? /* @__PURE__ */ new Set();
+		pendingHydrates.set(scope, pending);
+		pending.add(start);
+		return () => {
+			pending.delete(start);
+			if (pending.size === 0) pendingHydrates.delete(scope);
+			pruneEntityGuards(scope);
+		};
+	};
+	/** Arm the guard of entity `id` in `scope`. Returns its release (call once the patch landed). */
+	const guardEntity = (scope, id) => {
+		const guard = {};
+		const guards = removedEntities.get(scope) ?? /* @__PURE__ */ new Map();
+		removedEntities.set(scope, guards);
+		guards.set(id, guard);
+		return () => {
+			if (guards.get(id) !== guard) return;
+			guard.releasedAt = ++guardClock;
+			pruneEntityGuards(scope);
+		};
+	};
+	/** Lift the guards of `ids` early (a server value holds them again). */
+	const liftEntityGuards = (scope, ids) => {
+		const guards = removedEntities.get(scope);
+		if (!guards) return;
+		for (const id of ids) guards.delete(id);
+		if (guards.size === 0) removedEntities.delete(scope);
+	};
+	return {
+		guardEntity,
+		liftEntityGuards,
+		removedIds,
+		startHydrate
+	};
+};
+// src/core/engine/scopeClear.ts
+/**
+* Resource-wide clear of one scope: memory, every persisted row and reads in
+* flight. A clear bumps the scope's generation so reads started before it are
+* dropped, and records its row purge so a later hydrate waits for it.
+*/
+const createScopeClear = ({ port, prefix, resource, rows, writeQueue }) => {
+	const { deleteRows, readIndex } = rows;
+	/** Bumped by every `clear()` of a scope; reads started before it are stale. */
+	const clearGenerations = /* @__PURE__ */ new Map();
+	const clearGeneration = (scope) => clearGenerations.get(scope) ?? 0;
+	/**
+	* The persisted-row purge of the last `clear()` per scope: `true` once every
+	* row delete landed. A hydrate waits for it, and refuses to read while the
+	* purge failed (an untrusted scope, a storage error) so a wiped resource can
+	* never paint a row that survived it.
+	*/
+	const scopePurges = /* @__PURE__ */ new Map();
+	const lastPurge = (scope) => scopePurges.get(scope);
+	/**
+	* Wipe the resource in the active scope: every entry leaves memory in one
+	* host commit, every persisted row (all keys, all query variants) and the
+	* index are deleted, and reads already in flight are dropped — a hydrate
+	* started before the clear never dispatches, and `useSync` discards head
+	* responses whose request started before it. Requests started afterwards
+	* apply normally. Resolves `true` once the persisted rows are gone.
+	*/
+	const clear = () => {
+		const scope = resource.scope.get();
+		clearGenerations.set(scope, clearGeneration(scope) + 1);
+		port.commit([{ type: "clear" }], {
+			entries: {},
+			scope
+		}, `${prefix}/clear`);
+		rows.forgetScope(scope);
+		const purge = purgeScope(scope);
+		scopePurges.set(scope, purge);
+		return purge;
+	};
+	/**
+	* `clear()` for any scope, including one that is not active (a user who
+	* switched away while their data was being deleted): every persisted row of
+	* `scope` and its index go, and for the active scope memory is wiped too
+	* (exactly `clear()`). An inactive scope's memory is not on screen and is
+	* left alone. The row deletes go through the write queue, so they land after
+	* any write this session already queued for that scope — a row (or index
+	* entry) written just before is purged rather than landing after the purge.
+	* A later hydrate of `scope` waits for the purge. Resolves `true` once the
+	* persisted rows are gone.
+	*/
+	const clearScope = (scope) => {
+		if (scope === resource.scope.get()) return clear();
+		clearGenerations.set(scope, clearGeneration(scope) + 1);
+		const purge = purgeScope(scope);
+		scopePurges.set(scope, purge);
+		return purge;
+	};
+	/** Delete every persisted row of `scope` (see `clear`). */
+	const purgeScope = async (scope) => {
+		if (!writeQueue) return true;
+		if (!resource.scope.canPersist()) return false;
+		const queued = deleteRows(scope, [...rows.indexedKeys(scope) ?? []]);
+		let persisted;
+		try {
+			persisted = await readIndex(scope);
+		} catch {
+			return false;
+		}
+		const known = rows.indexedKeys(scope);
+		const stale = persisted.filter((queryKey) => !known?.has(queryKey));
+		const [first, rest] = await Promise.all([queued, deleteRows(scope, stale)]);
+		return first && rest;
+	};
+	return {
+		clear,
+		clearGeneration,
+		clearScope,
+		lastPurge
+	};
+};
+// src/core/engine/createReplicaEngine.ts
+/**
+* The replica engine: every transition of one resource, independent of any
+* UI framework or state library.
+*
+* It owns hydrate-if-empty, server replace, pagination, optimistic overlays
+* with commit/rollback, entity propagation, scope isolation and serialized
+* persistence. The host store keeps the rendered value (see
+* {@link ReplicaStorePort}); fetch scheduling (when to sync, dedupe, focus
+* revalidation) belongs to an adapter such as `local-replica/zustand`.
+*/
+const createReplicaEngine = (resource, options) => {
+	const { port } = options;
+	const paging = resource.paging;
+	const prefix = options.actionPrefix ?? resource.name;
+	const writeQueue = resource.storage ? new ReplicaWriteQueue(resource.storage) : void 0;
+	const fetcher = options.fetcher ?? resource.fetcher;
+	let mutationSeq = 0;
+	/** Keys with a `loadMore` request in flight (the only valid `isLoadingMore`). */
+	const loadingMore = /* @__PURE__ */ new Set();
+	const { clearRemoved, isPurged, isRemoved, markPurged, markRemoved, removalGeneration } = createRemovalGuards();
+	const entityGuards = createEntityRemovalGuards();
+	const getSlot = port.getState;
+	const storageKey = (key, query) => ({ queryKey: replicaStorageKey(key, query) });
+	const toPersisted = (data) => {
+		const paged = pagination.toPersisted(data);
+		return options.toPersisted ? options.toPersisted(paged) : paged;
+	};
+	const rows = createPersistedRows({
+		commit: (keys, state) => port.commit(keys.map((key) => ({
+			data: void 0,
+			key
+		})), state, `${prefix}/evict`),
+		getSlot,
+		isRemoved,
+		loadingMore,
+		resource,
+		writeQueue
+	});
+	const { deleteRows, removeStoredVariants, retain, touchStorageKey } = rows;
+	const { clear, clearGeneration, clearScope, lastPurge } = createScopeClear({
+		port,
+		prefix,
+		resource,
+		rows,
+		writeQueue
+	});
+	const runEffects = (effects) => {
+		if (!writeQueue || effects.length === 0) return;
+		if (!resource.scope.canPersist()) return;
+		for (const effect of effects) {
+			if (!resource.persistKey(effect.key)) continue;
+			const key = {
+				...storageKey(effect.key, effect.query),
+				scope: effect.scope
+			};
+			if (effect.type === "remove") {
+				removeStoredVariants(effect.scope, effect.key, key.queryKey).then((removed) => {
+					if (removed) markPurged(effect.scope, effect.key);
+				});
+				continue;
+			}
+			const data = toPersisted(effect.data);
+			if (data === void 0) continue;
+			if (data === null) {
+				deleteRows(effect.scope, [key.queryKey]);
+				continue;
+			}
+			rows.writeRow(effect.scope, key.queryKey, data);
+		}
+	};
+	/** Read an entry as it will be once `writes` are applied (latest write wins). */
+	const readThrough = (writes, key) => {
+		for (let i = writes.length - 1; i >= 0; i--) {
+			const write = writes[i];
+			if ("type" in write) return void 0;
+			if (write.key === key) return write.data;
+		}
+		return port.read(key);
+	};
+	const dispatch = (action) => runActions([action]);
+	/**
+	* Fold one or more actions into a single host commit. A caller that seeds
+	* many keys (a list refresh) must not clone the view and notify subscribers
+	* once per key; every action is still reduced in order, and the accumulated
+	* writes are applied as ONE host update. A batch is dropped whole when any
+	* action belongs to another identity (see {@link dispatch}).
+	*/
+	function runActions(actions) {
+		if (actions.length === 0) return false;
+		const activeScope = resource.scope.get();
+		if (actions.some((action) => action.scope !== activeScope)) return false;
+		for (const action of actions) {
+			if (action.type === "remove") markRemoved(action.scope, action.key);
+			if (action.type === "replace") clearRemoved(action.scope, action.key);
+		}
+		const initial = getSlot();
+		let slot = initial;
+		const writes = [];
+		const effects = [];
+		const read = (key) => readThrough(writes, key);
+		if (slot.scope !== void 0 && slot.scope !== activeScope) {
+			rows.forgetScope(slot.scope);
+			const reset = replicaReducer(slot, {
+				scope: activeScope,
+				type: "resetScope"
+			}, read);
+			writes.push(...reset.writes);
+			slot = reset.state;
+		}
+		let changed = false;
+		for (const action of actions) {
+			const transition = replicaReducer(slot, action, read);
+			writes.push(...transition.writes);
+			effects.push(...transition.effects);
+			if (transition.state !== slot) {
+				slot = transition.state;
+				changed = true;
+			}
+		}
+		if (!changed && writes.length === 0 && slot === initial) return false;
+		port.commit(writes, slot, `${prefix}/${actions.length > 1 ? "batch" : actions[0].type}`);
+		runEffects(effects);
+		return true;
+	}
+	/**
+	* Drop memory owned by another identity as soon as a new scope is active —
+	* even when the new scope has nothing persisted and its fetch is slow, the
+	* previous user's / workspace's rows must not stay on screen.
+	*/
+	const ensureScope = (scope) => {
+		if (scope === resource.scope.get() && getSlot().scope !== scope) dispatch({
+			scope,
+			type: "resetScope"
+		});
+	};
+	const getConfirmed = (key) => {
+		const entry = getSlot().entries[key];
+		return entry?.pending.length ? entry.base : port.read(key);
+	};
+	const hydrate = async (params, scope = resource.scope.get(), { overwrite = false } = {}) => {
+		if (!resource.storage) return false;
+		if (resource.scope.canHydrate && !resource.scope.canHydrate()) return false;
+		const key = resource.key(params);
+		if (!resource.persistKey(key)) return false;
+		if (isRemoved(scope, key)) return false;
+		const settle = entityGuards.startHydrate(scope);
+		try {
+			return await readAndHydrate(params, key, scope, overwrite);
+		} finally {
+			settle();
+		}
+	};
+	const readAndHydrate = async (params, key, scope, overwrite) => {
+		const storage = resource.storage;
+		const generation = clearGeneration(scope);
+		const purge = lastPurge(scope);
+		if (purge && !await purge) return false;
+		const query = resource.query(params);
+		const { queryKey } = storageKey(key, query);
+		const writesBefore = rows.writeCount();
+		const cached = await storage.get({
+			queryKey,
+			scope
+		});
+		if (!cached) return false;
+		if (isRemoved(scope, key) || clearGeneration(scope) !== generation) return false;
+		rows.rememberRead(scope, queryKey, cached.data, writesBefore);
+		if (options.isHydratable && !options.isHydratable(cached.data, params)) return false;
+		const stored = withoutRemovedEntities(scope, cached.data);
+		if (stored === void 0) return false;
+		const data = overwrite ? pagination.keepClientOnlyRows(stored, port.read(key), key) : stored;
+		const applied = dispatch({
+			data,
+			key,
+			overwrite,
+			params,
+			query,
+			scope,
+			type: "hydrate",
+			updatedAt: cached.updatedAt
+		});
+		if (applied && resource.scope.canPersist()) touchStorageKey(scope, queryKey);
+		return applied;
+	};
+	/** Non-paged: whether a (prepared) head response is a terminal absence (`isMissing`). */
+	const isMissingHead = (incoming) => !paging && !!options.isMissing?.(incoming);
+	/**
+	* Fold a head response in and report what it was: dropped by `prepareHead`,
+	* a terminal absence (`isMissing`, applied as a removal) or a replacement.
+	* `changed` is whether the store moved. `replace` is the boolean shorthand;
+	* the zustand slice's settle pipeline reads the outcome to pick its effects.
+	*/
+	const applyHead = (params, fetched, scope = resource.scope.get()) => {
+		const key = resource.key(params);
+		const incoming = options.prepareHead ? options.prepareHead(fetched, port.read(key), params) : fetched;
+		if (incoming === void 0) return {
+			changed: false,
+			outcome: "dropped"
+		};
+		if (isMissingHead(incoming)) return {
+			changed: remove(key, scope),
+			outcome: "missing"
+		};
+		const query = resource.query(params);
+		const entry = getSlot().entries[key];
+		const reset = entry ? entry.query !== query : paging !== void 0 && !pagination.viewMatchesFields(port.read(key), params);
+		const applied = dispatch({
+			data: (confirmed) => paging ? pagination.mergeHead(key, incoming, confirmed, params, reset) : options.merge ? options.merge(incoming, confirmed, params) : incoming,
+			key,
+			params,
+			query,
+			scope,
+			type: "replace"
+		});
+		if (applied) forgetRestoredEntities(scope, getConfirmed(key));
+		return {
+			changed: applied,
+			outcome: "replaced"
+		};
+	};
+	const replace = (params, fetched, scope = resource.scope.get()) => applyHead(params, fetched, scope).changed;
+	/**
+	* Confirmed local write: patches the view (and the base under any overlay).
+	* Pass `source: 'seed'` for a provisional row (a list row standing in for a
+	* detail): it is hydratable and never persisted, so the authoritative value it
+	* stands in for is preserved (see `ReplicaSource`).
+	*/
+	const update = (key, apply, { persist = true, seedTag, source } = {}) => dispatch({
+		apply,
+		key,
+		persist,
+		scope: resource.scope.get(),
+		seedTag,
+		source,
+		type: "update"
+	});
+	/**
+	* Confirmed local write to several keys as ONE host update — same per-key
+	* semantics as {@link update}, but a whole list seeds in a single commit
+	* instead of one per row (no repeated view cloning or subscriber churn).
+	*/
+	const updateMany = (entries, { persist = true, seedTag, source } = {}) => {
+		const scope = resource.scope.get();
+		return runActions(entries.map(({ apply, key }) => ({
+			apply,
+			key,
+			persist,
+			scope,
+			seedTag,
+			source,
+			type: "update"
+		})));
+	};
+	/**
+	* Purge a removal that belongs to a scope which is no longer active.
+	*
+	* The in-memory view is not ours to touch — the active scope owns it — but the
+	* guard and the persisted row both belong to THAT scope. Arming the one and
+	* deleting the other keeps a switch back from hydrating a value the server
+	* just deleted or denied. `dispatch` would reject the off-scope action
+	* outright (see `replace`'s stale-scope guard), so the row would otherwise
+	* survive untouched.
+	*
+	* Like `remove`, the delete only counts as done once it was actually queued:
+	* an untrusted scope refuses writes, so the guard stays armed as `unpurged`
+	* and a later removal retries instead of reporting a no-op that never deletes.
+	*/
+	const purge = (key, scope) => {
+		if (isRemoved(scope, key) && isPurged(scope, key)) return false;
+		markRemoved(scope, key);
+		if (!writeQueue || !resource.persistKey(key)) {
+			markPurged(scope, key);
+			return false;
+		}
+		if (!resource.scope.canPersist()) return false;
+		removeStoredVariants(scope, key, storageKey(key).queryKey).then((removed) => {
+			if (removed) markPurged(scope, key);
+		});
+		return true;
+	};
+	/**
+	* Drop an entry and its persisted row.
+	*
+	* A removal is a no-op only once there is genuinely nothing left to do: the
+	* key is guarded, its value is gone, AND its stale row was already scheduled
+	* for deletion (or there is no persisted row to clear). A subject with no
+	* acceptance polls `null` every couple of seconds, and re-emitting the same
+	* delete on every tick would only churn storage. But a removal whose delete
+	* was skipped — an untrusted scope refuses writes — keeps retrying, so the row
+	* cannot survive to hydrate again once the scope is trusted.
+	*
+	* A removal captured under another identity (a late NOT_FOUND arriving after a
+	* workspace switch) is routed to {@link purge}: it must not touch the scope on
+	* screen, yet its own scope's row still has to go.
+	*/
+	const remove = (key, scope = resource.scope.get()) => {
+		if (scope !== resource.scope.get()) return purge(key, scope);
+		if ((!writeQueue || !resource.persistKey(key) || isPurged(scope, key)) && isRemoved(scope, key) && port.read(key) === void 0) return false;
+		return dispatch({
+			key,
+			scope,
+			type: "remove"
+		});
+	};
+	/**
+	* Persist the confirmed value of an entry as it is now — the flush after a
+	* burst of in-memory `update(..., { persist: false })` writes (a stream).
+	*/
+	const persist = (key) => {
+		const scope = resource.scope.get();
+		if (getSlot().scope !== void 0 && getSlot().scope !== scope) return;
+		const data = getConfirmed(key);
+		if (data === void 0) return;
+		runEffects([{
+			data,
+			key,
+			query: getSlot().entries[key]?.query,
+			scope,
+			type: "persist"
+		}]);
+	};
+	const revalidate = (key) => options.revalidate ? options.revalidate(key) : Promise.resolve();
+	/**
+	* Start an optimistic overlay now and settle it later (multi-resource flows).
+	* `query` tags the overlay with the query it describes; a caller that knows
+	* the requested query (e.g. before the first page painted) should pass it, so
+	* the overlay is scoped to that query rather than kept across every change.
+	*/
+	const beginOptimistic = (key, apply, query) => {
+		const scope = resource.scope.get();
+		const id = ++mutationSeq;
+		dispatch({
+			apply,
+			id,
+			key,
+			query: query ?? getSlot().entries[key]?.query,
+			scope,
+			type: "optimistic"
+		});
+		return {
+			commit: (confirm) => {
+				dispatch({
+					confirm,
+					id,
+					key,
+					scope,
+					type: "commit"
+				});
+			},
+			rollback: () => {
+				dispatch({
+					id,
+					key,
+					scope,
+					type: "rollback"
+				});
+			}
+		};
+	};
+	/**
+	* Apply `apply` to the view right away, run `serverCall`, then commit (the
+	* confirmed value is persisted) or roll back (the view is rebuilt from the
+	* confirmed base plus any other in-flight overlays) and rethrow.
+	*/
+	const optimistic = async (key, apply, serverCall, mutationOptions = {}) => {
+		const token = beginOptimistic(key, apply);
+		try {
+			const result = await serverCall();
+			token.commit(mutationOptions.confirm?.(result));
+			return result;
+		} catch (error) {
+			token.rollback();
+			throw error;
+		} finally {
+			if (mutationOptions.revalidate) revalidate(key);
+		}
+	};
+	const pagination = createPagination({
+		fetcher,
+		getSlot,
+		loadingMore,
+		options,
+		port,
+		resource,
+		update
+	});
+	const { collapse, insertHead, loadMore } = pagination;
+	const { beginEntityOptimistic, entityKeys, forgetRestoredEntities, patchStoredEntity, removeEntity, updateEntity, withoutRemovedEntities } = createEntityPropagation({
+		beginOptimistic,
+		entity: options.entity,
+		entityGuards,
+		getSlot,
+		paging,
+		port,
+		remove,
+		resource,
+		rows,
+		update
+	});
+	const { patchStoredRows } = rows;
+	return {
+		applyHead,
+		beginEntityOptimistic,
+		beginOptimistic,
+		clear,
+		clearGeneration,
+		clearScope,
+		removalGeneration,
+		collapse,
+		dispatch,
+		ensureScope,
+		entityKeys,
+		fetcher,
+		getConfirmed,
+		hydrate,
+		insertHead,
+		isMissingHead,
+		loadMore,
+		optimistic,
+		patchStoredEntity,
+		patchStoredRows,
+		persist,
+		remove,
+		removeEntity,
+		replace,
+		resource,
+		retain,
+		revalidate,
+		update,
+		updateEntity,
+		updateMany
+	};
+};
+export { stableQueryKey as S, REPLICA_KEY_PREFIX as _, ReplicaWriteQueue as a, isReplicaStorageKeyOf as b, applyNextPage as c, hasPagedItem as d, insertHeadItems as f, toPersistedPage as g, pagingFor as h, REPLICA_INDEX_KEY as i, collapseToHead as l, mapPagedItem as m, createReplicaState as n, readReplicaRowStrict as o, joinPages as p, replicaReducer as r, applyHeadPage as s, createReplicaEngine as t, getNextPageCursor as u, isReplicaSyncKey as v, replicaStorageKey as x, replicaKeys as y };
+
+//# sourceMappingURL=createReplicaEngine-CdR-URHo.js.map