@kontsedal/olas-core 0.0.6 → 0.1.0

package/dist/{root-CFgYhBd-.cjs → root-CPSL5kpR.cjs}

@@ -103,6 +103,11 @@ var DevtoolsEmitter = class {
 const defaultHandler = (err, context) => {
 	console.error("[olas]", context, err);
 };
+let eventCounter = 0;
+function nextEventId() {
+	eventCounter = eventCounter + 1 >>> 0;
+	return `e_${(Math.random() * 16777216 | 0).toString(16).padStart(6, "0")}${eventCounter.toString(16).padStart(6, "0")}`;
+}
 /**
 * Dispatch an error to a user-provided handler, falling back to console.error.
 * The handler itself is wrapped — if it throws, the throw is swallowed and
@@ -112,16 +117,46 @@ const defaultHandler = (err, context) => {
 */
 function dispatchError(handler, err, context) {
 	const fn = handler ?? defaultHandler;
+	const full = {
+		...context,
+		eventId: nextEventId(),
+		timestamp: Date.now()
+	};
 	try {
-		fn(err, context);
+		fn(err, full);
 	} catch (handlerErr) {
 		try {
 			console.error("[olas] onError handler threw:", handlerErr);
-			console.error("[olas] original error:", err, context);
+			console.error("[olas] original error:", err, full);
 		} catch {}
 	}
 }
 //#endregion
+//#region src/signals/readonly.ts
+/**
+* Project a Signal (or any object with a reactive `value` + `peek` + `subscribe`)
+* as a `ReadSignal`. The returned object does not expose `set` / `update` /
+* settable `value`, so it can be returned from APIs without callers mutating it.
+*
+* Internal helper — not exported from the package's public surface.
+*/
+function readOnly(source) {
+	return Object.freeze({
+		get value() {
+			return source.value;
+		},
+		peek() {
+			return source.peek();
+		},
+		subscribe(handler) {
+			return source.subscribe(handler);
+		},
+		subscribeChanges(handler) {
+			return source.subscribeChanges(handler);
+		}
+	});
+}
+//#endregion
 //#region src/signals/runtime.ts
 var SignalImpl = class {
 	inner;
@@ -140,6 +175,9 @@ var SignalImpl = class {
 	subscribe(handler) {
 		return this.inner.subscribe(handler);
 	}
+	subscribeChanges(handler) {
+		return subscribeChangesImpl(this.inner, handler);
+	}
 	set(value) {
 		this.inner.value = value;
 	}
@@ -161,8 +199,26 @@ var ComputedImpl = class {
 	subscribe(handler) {
 		return this.inner.subscribe(handler);
 	}
+	subscribeChanges(handler) {
+		return subscribeChangesImpl(this.inner, handler);
+	}
 };
 /**
+* Shared skip-initial wrapper around `signal.subscribe`. Preact fires the
+* subscribe callback synchronously with the current value (the "initial
+* fire"); the wrapper swallows it and forwards every subsequent change.
+*/
+function subscribeChangesImpl(inner, handler) {
+	let initial = true;
+	return inner.subscribe((value) => {
+		if (initial) {
+			initial = false;
+			return;
+		}
+		handler(value);
+	});
+}
+/**
 * Create a writable `Signal<T>`. Reads track the current auto-tracking scope
 * (effect / computed); writes notify all subscribers (deduped via `Object.is`).
 *
@@ -232,7 +288,7 @@ function isAbortError(err) {
 function abortableSleep(ms, signal) {
 	return new Promise((resolve, reject) => {
 		if (signal.aborted) {
-			reject(new DOMException("Aborted", "AbortError"));
+			reject(abortReason(signal));
 			return;
 		}
 		const timer = setTimeout(() => {
@@ -242,11 +298,93 @@ function abortableSleep(ms, signal) {
 		const onAbort = () => {
 			clearTimeout(timer);
 			signal.removeEventListener("abort", onAbort);
-			reject(new DOMException("Aborted", "AbortError"));
+			reject(abortReason(signal));
 		};
 		signal.addEventListener("abort", onAbort, { once: true });
 	});
 }
+/**
+* Read the caller-supplied abort reason if present, falling back to the
+* canonical `DOMException('Aborted', 'AbortError')`. `signal.reason` lets
+* users propagate context (e.g. "supersededByLatestWins") through abort
+* chains — discarding it would force every caller to wrap with custom
+* cancellation tokens.
+*/
+function abortReason(signal) {
+	const reason = signal.reason;
+	if (reason !== void 0) return reason;
+	return new DOMException("Aborted", "AbortError");
+}
+//#endregion
+//#region src/query/focus-online.ts
+const focusSubs = /* @__PURE__ */ new Set();
+const onlineSubs = /* @__PURE__ */ new Set();
+function fireFocus() {
+	for (const fn of focusSubs) try {
+		fn();
+	} catch {}
+}
+function fireOnline() {
+	for (const fn of onlineSubs) try {
+		fn();
+	} catch {}
+}
+let focusScheduled = false;
+function scheduleFocus() {
+	if (focusScheduled) return;
+	focusScheduled = true;
+	queueMicrotask(() => {
+		focusScheduled = false;
+		fireFocus();
+	});
+}
+function onVisibilityChange() {
+	if (document.visibilityState === "visible") scheduleFocus();
+}
+let focusInstalled = false;
+let onlineInstalled = false;
+function installFocus() {
+	if (focusInstalled) return;
+	if (typeof window === "undefined") return;
+	window.addEventListener("focus", scheduleFocus);
+	if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibilityChange);
+	focusInstalled = true;
+}
+function uninstallFocus() {
+	if (!focusInstalled) return;
+	if (typeof window === "undefined") return;
+	window.removeEventListener("focus", scheduleFocus);
+	if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibilityChange);
+	focusInstalled = false;
+}
+function installOnline() {
+	if (onlineInstalled) return;
+	if (typeof window === "undefined") return;
+	window.addEventListener("online", fireOnline);
+	onlineInstalled = true;
+}
+function uninstallOnline() {
+	if (!onlineInstalled) return;
+	if (typeof window === "undefined") return;
+	window.removeEventListener("online", fireOnline);
+	onlineInstalled = false;
+}
+function subscribeWindowFocus(fn) {
+	installFocus();
+	focusSubs.add(fn);
+	return () => {
+		focusSubs.delete(fn);
+		if (focusSubs.size === 0) uninstallFocus();
+	};
+}
+function subscribeReconnect(fn) {
+	installOnline();
+	onlineSubs.add(fn);
+	return () => {
+		onlineSubs.delete(fn);
+		if (onlineSubs.size === 0) uninstallOnline();
+	};
+}
 //#endregion
 //#region src/query/structural-share.ts
 /**
@@ -341,16 +479,33 @@ var Entry = class {
 	lastUpdatedAt;
 	hasPendingMutations = signal(false);
 	isStale = signal(true);
+	/** True while a fetch is parked waiting for reconnect (online-mode defer or
+	*  offlineFirst network-error park). See spec §5.5, T3.5. */
+	isPaused = signal(false);
 	fetcherProvider;
 	staleTime;
 	retry;
 	retryDelay;
+	networkMode;
+	structuralShareEnabled;
 	currentFetchId = 0;
 	currentAbort = null;
 	staleTimer = null;
+	/** Set by `markStale()` (invalidate without fetch); forces `isStaleNow()`
+	*  true until the next successful fetch clears it. Spec §5.7, T3.9. */
+	forcedStale = false;
 	snapshots = [];
 	nextSnapshotId = 0;
 	disposed = false;
+	/** Subscribers to reconnect — installed lazily when a deferred fetch lands. */
+	reconnectUnsub = null;
+	/**
+	* Set of deferred-fetch resolvers waiting for reconnect (online mode).
+	* Stored at `unknown` to keep `Entry<T>` covariant in `T` — same trick as
+	* `onSuccessData`. Each resolver is fed the same value from
+	* `applySuccess`, which is `T`, then cast at the fan-out call site.
+	*/
+	deferredResolvers = [];
 	events;
 	onSuccessData;
 	fetchStartTime = 0;
@@ -364,7 +519,9 @@ var Entry = class {
 		this.fetcherProvider = options.fetcher;
 		this.staleTime = options.staleTime ?? 0;
 		this.retry = options.retry ?? 0;
-		this.retryDelay = options.retryDelay ?? 1e3;
+		this.retryDelay = options.retryDelay;
+		this.networkMode = options.networkMode ?? "online";
+		this.structuralShareEnabled = options.structuralShare ?? true;
 		this.events = options.events ?? {};
 		this.onSuccessData = options.onSuccessData;
 		this.data = signal(options.initialData);
@@ -388,6 +545,7 @@ var Entry = class {
 	}
 	startFetch() {
 		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error("Entry disposed"));
+		if (this.networkMode === "online" && this.isOffline()) return this.scheduleDeferredFetch();
 		const myId = ++this.currentFetchId;
 		this.currentAbort?.abort();
 		const abort = new AbortController();
@@ -397,6 +555,7 @@ var Entry = class {
 			this.status.set("pending");
 			this.isFetching.set(true);
 			this.isLoading.set(!previouslyHadData);
+			this.isPaused.set(false);
 		});
 		this.fetchStartTime = Date.now();
 		try {
@@ -404,6 +563,34 @@ var Entry = class {
 		} catch {}
 		return this.runWithRetry(myId, abort);
 	}
+	isOffline() {
+		return typeof navigator !== "undefined" && navigator.onLine === false;
+	}
+	scheduleDeferredFetch() {
+		this.isPaused.set(true);
+		if (this.reconnectUnsub === null) this.reconnectUnsub = subscribeReconnect(() => this.drainDeferred());
+		return new Promise((resolve, reject) => {
+			this.deferredResolvers.push({
+				resolve,
+				reject
+			});
+		});
+	}
+	drainDeferred() {
+		if (this.deferredResolvers.length === 0) return;
+		if (this.disposed) return;
+		const pending = this.deferredResolvers;
+		this.deferredResolvers = [];
+		if (this.reconnectUnsub !== null) {
+			this.reconnectUnsub();
+			this.reconnectUnsub = null;
+		}
+		this.startFetch().then((value) => {
+			for (const p of pending) p.resolve(value);
+		}, (err) => {
+			for (const p of pending) p.reject(err);
+		});
+	}
 	async runWithRetry(myId, abort) {
 		let attempt = 0;
 		while (true) {
@@ -414,6 +601,14 @@ var Entry = class {
 				return this.applySuccess(result);
 			} catch (err) {
 				if (myId !== this.currentFetchId || this.disposed || isAbortError(err)) throw err;
+				if (this.networkMode === "offlineFirst" && this.isOffline() && err instanceof TypeError) {
+					batch(() => {
+						this.isFetching.set(false);
+						this.isLoading.set(false);
+						this.status.set(this.data.peek() !== void 0 ? "success" : "idle");
+					});
+					return this.scheduleDeferredFetch();
+				}
 				if (!this.shouldRetry(attempt, err)) return this.applyFailure(err);
 				await abortableSleep(this.computeDelay(attempt), abort.signal);
 				attempt += 1;
@@ -428,11 +623,13 @@ var Entry = class {
 	}
 	computeDelay(attempt) {
 		const d = this.retryDelay;
+		if (d === void 0) return Math.min(1e3 * 2 ** attempt, 3e4);
 		return typeof d === "function" ? d(attempt) : d;
 	}
 	applySuccess(result) {
 		const prev = this.data.peek();
-		const shared = prev === void 0 ? result : structuralShare(prev, result);
+		const shared = prev === void 0 || !this.structuralShareEnabled ? result : structuralShare(prev, result);
+		if (this.snapshots.length > 0) for (const s of this.snapshots) s.prev = shared;
 		batch(() => {
 			this.data.set(shared);
 			this.error.set(void 0);
@@ -442,6 +639,7 @@ var Entry = class {
 			this.lastUpdatedAt.set(Date.now());
 			this.isStale.set(this.staleTime === 0);
 		});
+		this.forcedStale = false;
 		if (this.staleTime > 0) this.scheduleStaleness();
 		try {
 			this.events.onFetchSuccess?.(Date.now() - this.fetchStartTime);
@@ -471,12 +669,66 @@ var Entry = class {
 	refetch() {
 		return this.startFetch();
 	}
-	invalidate() {
+	/**
+	* Apply a server-supplied data + timestamp without going through the
+	* fetcher path. Used by streaming SSR hydration: each `<Suspense>` boundary
+	* that resolves on the server pushes its entry's data to the client, and
+	* the client routes it through here so the entry transitions to `success`
+	* without burning the user's fetcher.
+	*
+	* Distinct from `setData`: no Snapshot returned (no rollback semantics —
+	* this is canonical data, not an optimistic patch), no
+	* `hasPendingMutations` flip, and `lastUpdatedAt` honors the supplied
+	* server timestamp instead of `Date.now()`. Also bumps `currentFetchId`
+	* so any in-flight fetch supersedes itself rather than overwriting the
+	* fresher hydrated value.
+	*/
+	applyHydration(data, lastUpdatedAt) {
+		if (this.disposed) return;
+		this.currentFetchId += 1;
+		this.currentAbort?.abort();
+		this.currentAbort = null;
+		if (this.staleTimer !== null) {
+			clearTimeout(this.staleTimer);
+			this.staleTimer = null;
+		}
+		const alreadyStale = this.staleTime === 0 || Date.now() - lastUpdatedAt >= this.staleTime;
+		batch(() => {
+			this.data.set(data);
+			this.error.set(void 0);
+			this.status.set("success");
+			this.isLoading.set(false);
+			this.isFetching.set(false);
+			this.lastUpdatedAt.set(lastUpdatedAt);
+			this.isStale.set(alreadyStale);
+		});
+		if (!alreadyStale && this.staleTime > 0) {
+			const remaining = this.staleTime - (Date.now() - lastUpdatedAt);
+			this.staleTimer = setTimeout(() => {
+				this.staleTimer = null;
+				if (!this.disposed) this.isStale.set(true);
+			}, remaining);
+		}
+		this.onSuccessData?.(data);
+		if (this.pendingFirstValueRejects.length > 0) {}
+	}
+	/**
+	* Force this entry stale WITHOUT fetching. `isStaleNow()` returns true until
+	* the next successful fetch clears the flag, so the next subscriber refetches.
+	* Used by `client.invalidate` for subscriber-less entries — spec §5.7 says
+	* invalidate refetches only IF subscribed (T3.9).
+	*/
+	markStale() {
+		if (this.disposed) return;
 		if (this.staleTimer != null) {
 			clearTimeout(this.staleTimer);
 			this.staleTimer = null;
 		}
+		this.forcedStale = true;
 		this.isStale.set(true);
+	}
+	invalidate() {
+		this.markStale();
 		return this.startFetch();
 	}
 	reset() {
@@ -486,35 +738,80 @@ var Entry = class {
 			this.status.set(this.data.peek() !== void 0 ? "success" : "idle");
 		});
 	}
-	setData(updater) {
+	/**
+	* Cancel an in-flight fetch without touching `data`. Aborts the current
+	* request and supersedes it (bumps `currentFetchId` so its result can never
+	* land), then restores a settled status: `'success'` if data exists, else
+	* `'idle'`. No-op when nothing is fetching. This is the primitive behind
+	* `query.cancel(...)` / `subscription.cancel()`: the canonical optimistic
+	* recipe cancels outgoing refetches before an optimistic `setData` so a
+	* stale response can't clobber the optimistic value (spec §5, §6.4). T3.4.
+	*/
+	cancel() {
+		if (this.disposed || !this.isFetching.peek()) return;
+		this.currentFetchId += 1;
+		this.currentAbort?.abort();
+		this.currentAbort = null;
+		batch(() => {
+			this.isFetching.set(false);
+			this.isLoading.set(false);
+			this.status.set(this.data.peek() !== void 0 ? "success" : "idle");
+		});
+	}
+	/**
+	* Write data into the entry.
+	*
+	* `track` (default `true`) is the optimistic-update path: it pushes a
+	* snapshot record and flips `hasPendingMutations`, so the returned
+	* `Snapshot.rollback()` can restore the pre-write baseline and
+	* `finalize()` commits it. This is what `query.setData(...)` inside a
+	* mutation's `onMutate` uses (spec §6.4).
+	*
+	* `track: false` is a canonical cache write — cross-tab receive, entities
+	* backprop, realtime patches (spec §13.2). It updates the data signal but
+	* pushes NO snapshot and does NOT flip `hasPendingMutations`, so a
+	* fire-and-forget plugin write can't wedge the pending flag at `true`
+	* forever. Returns a no-op `Snapshot`.
+	*/
+	setData(updater, opts) {
 		if (this.disposed) return {
 			rollback: () => {},
 			finalize: () => {}
 		};
 		const prev = this.data.peek();
 		const next = updater(prev);
-		const id = this.nextSnapshotId++;
-		const record = {
-			id,
+		const record = opts?.track ?? true ? {
+			id: this.nextSnapshotId++,
 			prev,
 			live: true
-		};
-		this.snapshots.push(record);
+		} : null;
+		if (record) this.snapshots.push(record);
 		batch(() => {
 			this.data.set(next);
 			if (this.status.peek() === "idle" || this.status.peek() === "pending") this.status.set("success");
 			this.lastUpdatedAt.set(Date.now());
-			this.hasPendingMutations.set(true);
+			if (record) this.hasPendingMutations.set(true);
 		});
+		if (!record) return {
+			rollback: () => {},
+			finalize: () => {}
+		};
+		const id = record.id;
 		return {
 			rollback: () => {
 				if (!record.live || this.disposed) return;
 				record.live = false;
 				batch(() => {
-					this.data.set(record.prev);
-					this.snapshots = this.snapshots.filter((s) => s.id !== id);
-					const anyLive = this.snapshots.some((s) => s.live);
-					this.hasPendingMutations.set(anyLive);
+					const i = this.snapshots.indexOf(record);
+					if (i !== -1) {
+						if (i === this.snapshots.length - 1) this.data.set(record.prev);
+						else {
+							const below = this.snapshots[i + 1];
+							below.prev = record.prev;
+						}
+						this.snapshots.splice(i, 1);
+					}
+					this.hasPendingMutations.set(this.snapshots.some((s) => s.live));
 				});
 			},
 			finalize: () => {
@@ -552,6 +849,7 @@ var Entry = class {
 	* Used by the query client to decide whether to refetch on subscribe.
 	*/
 	isStaleNow() {
+		if (this.forcedStale) return true;
 		const last = this.lastUpdatedAt.peek();
 		if (last === void 0) return true;
 		return Date.now() - last >= this.staleTime;
@@ -565,6 +863,20 @@ var Entry = class {
 		}
 		this.currentAbort?.abort();
 		this.currentAbort = null;
+		batch(() => {
+			this.isFetching.set(false);
+			this.isLoading.set(false);
+		});
+		if (this.reconnectUnsub !== null) {
+			this.reconnectUnsub();
+			this.reconnectUnsub = null;
+		}
+		if (this.deferredResolvers.length > 0) {
+			const disposed = new DOMException("Entry disposed", "AbortError");
+			const pending = this.deferredResolvers;
+			this.deferredResolvers = [];
+			for (const p of pending) p.reject(disposed);
+		}
 		if (this.pendingFirstValueRejects.length > 0) {
 			const disposed = new DOMException("Entry disposed", "AbortError");
 			const rejects = this.pendingFirstValueRejects;
@@ -574,51 +886,6 @@ var Entry = class {
 	}
 };
 //#endregion
-//#region src/query/focus-online.ts
-const focusSubs = /* @__PURE__ */ new Set();
-const onlineSubs = /* @__PURE__ */ new Set();
-let focusInstalled = false;
-let onlineInstalled = false;
-function fireFocus() {
-	for (const fn of focusSubs) try {
-		fn();
-	} catch {}
-}
-function fireOnline() {
-	for (const fn of onlineSubs) try {
-		fn();
-	} catch {}
-}
-function ensureFocusInstalled() {
-	if (focusInstalled) return;
-	if (typeof window === "undefined") return;
-	window.addEventListener("focus", fireFocus);
-	if (typeof document !== "undefined") document.addEventListener("visibilitychange", () => {
-		if (document.visibilityState === "visible") fireFocus();
-	});
-	focusInstalled = true;
-}
-function ensureOnlineInstalled() {
-	if (onlineInstalled) return;
-	if (typeof window === "undefined") return;
-	window.addEventListener("online", fireOnline);
-	onlineInstalled = true;
-}
-function subscribeWindowFocus(fn) {
-	ensureFocusInstalled();
-	focusSubs.add(fn);
-	return () => {
-		focusSubs.delete(fn);
-	};
-}
-function subscribeReconnect(fn) {
-	ensureOnlineInstalled();
-	onlineSubs.add(fn);
-	return () => {
-		onlineSubs.delete(fn);
-	};
-}
-//#endregion
 //#region src/query/infinite.ts
 /**
 * Holds an array of pages plus their pageParams. Supports fetchNextPage /
@@ -637,6 +904,9 @@ var InfiniteEntry = class {
 	isStale = signal(true);
 	lastUpdatedAt = signal(void 0);
 	hasPendingMutations = signal(false);
+	/** True while a fetch is parked waiting for reconnect (online-mode defer).
+	*  See spec §5.5, T3.5. Mirrors `Entry.isPaused`. */
+	isPaused = signal(false);
 	isFetchingNextPage = signal(false);
 	isFetchingPreviousPage = signal(false);
 	hasNextPage;
@@ -645,6 +915,8 @@ var InfiniteEntry = class {
 	currentFetchId = 0;
 	currentAbort = null;
 	staleTimer = null;
+	/** Set by `markStale()` (invalidate without fetch). See `Entry.forcedStale`. */
+	forcedStale = false;
 	snapshots = [];
 	nextSnapshotId = 0;
 	disposed = false;
@@ -657,6 +929,10 @@ var InfiniteEntry = class {
 	staleTime;
 	retry;
 	retryDelay;
+	networkMode;
+	structuralShareEnabled;
+	reconnectUnsub = null;
+	deferredResolvers = [];
 	itemsOf;
 	/**
 	* Mirrors `Entry.onSuccessData`. Fires from `applyFetchSuccess`-equivalent
@@ -673,7 +949,9 @@ var InfiniteEntry = class {
 		this.itemsOf = opts.itemsOf;
 		this.staleTime = opts.staleTime ?? 0;
 		this.retry = opts.retry ?? 0;
-		this.retryDelay = opts.retryDelay ?? 1e3;
+		this.retryDelay = opts.retryDelay;
+		this.networkMode = opts.networkMode ?? "online";
+		this.structuralShareEnabled = opts.structuralShare ?? true;
 		this.onSuccessData = opts.onSuccessData;
 		this.pageParams = signal([]);
 		this.data = computed(() => {
@@ -700,26 +978,82 @@ var InfiniteEntry = class {
 			return fn(ps[0], ps) !== null;
 		});
 	}
-	/** Initial / refetch — drops all pages and fetches starting from initialPageParam. */
+	/**
+	* Initial load / refetch. On the initial load (no pages yet) this fetches
+	* the first page. On a refetch of an already-loaded entry (interval,
+	* invalidate, focus/reconnect) it **refetches every currently-loaded page**
+	* sequentially, re-deriving each page's param from the freshly-fetched data
+	* via `getNextPageParam` — matching TanStack and avoiding the old
+	* "collapse to page one" truncation that dropped every loaded page but the
+	* first on each refetch (T3.7). Pages/params update atomically at the end,
+	* so subscribers never observe a mid-refetch truncation flash.
+	*/
 	startFetch() {
 		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error("Entry disposed"));
+		if (this.networkMode === "online" && this.isOffline()) return this.scheduleDeferredFetch("initial");
 		const myId = ++this.currentFetchId;
 		this.currentAbort?.abort();
 		const abort = new AbortController();
 		this.currentAbort = abort;
-		const previouslyHadPages = this.pages.peek().length > 0;
+		const previousPages = this.pages.peek();
 		batch(() => {
 			this.status.set("pending");
 			this.isFetching.set(true);
-			this.isLoading.set(!previouslyHadPages);
+			this.isLoading.set(previousPages.length === 0);
+			this.isPaused.set(false);
 		});
-		return this.runFetch(myId, abort.signal, this.initialPageParam, (page, param) => {
-			if (myId !== this.currentFetchId || this.disposed) return;
-			const prevPages = this.pages.peek();
-			const sharedPage = prevPages.length > 0 ? structuralShare(prevPages[0], page) : page;
+		return this.runRefetchAll(myId, abort.signal, Math.max(1, previousPages.length), previousPages);
+	}
+	/**
+	* Fetch `targetCount` pages from `initialPageParam`, chaining each next param
+	* via `getNextPageParam` from the freshly-fetched pages. Applies the query's
+	* retry policy per page. Stops early if the dataset shrank (a page yields
+	* `getNextPageParam === null`). Writes pages/params in ONE batch at the end;
+	* a per-page failure keeps the existing pages and surfaces the error; a
+	* supersede/dispose throws `AbortError` without writing.
+	*/
+	async runRefetchAll(myId, signal, targetCount, previousPages) {
+		const newPages = [];
+		const newParams = [];
+		let pageParam = this.initialPageParam;
+		try {
+			for (let i = 0; i < targetCount; i++) {
+				let attempt = 0;
+				while (true) {
+					if (myId !== this.currentFetchId || this.disposed) throw new DOMException("Superseded", "AbortError");
+					try {
+						const page = await this.fetcher({
+							pageParam,
+							signal
+						});
+						if (myId !== this.currentFetchId || this.disposed) throw new DOMException("Superseded", "AbortError");
+						newPages.push(page);
+						newParams.push(pageParam);
+						break;
+					} catch (err) {
+						if (myId !== this.currentFetchId || this.disposed || isAbortError(err)) throw err;
+						if (!(typeof this.retry === "number" ? attempt < this.retry : this.retry(attempt, err))) {
+							batch(() => {
+								this.error.set(err);
+								this.status.set("error");
+								this.isLoading.set(false);
+								this.isFetching.set(false);
+							});
+							throw err;
+						}
+						await abortableSleep(this.computeRetryDelay(attempt), signal);
+						attempt += 1;
+					}
+				}
+				const next = this.getNextPageParam(newPages[newPages.length - 1], newPages);
+				if (next === null) break;
+				pageParam = next;
+			}
+			if (myId !== this.currentFetchId || this.disposed) throw new DOMException("Superseded", "AbortError");
+			const finalPages = previousPages.length > 0 && this.structuralShareEnabled && newPages.length > 0 ? [structuralShare(previousPages[0], newPages[0]), ...newPages.slice(1)] : newPages;
 			batch(() => {
-				this.pages.set([sharedPage]);
-				this.pageParams.set([param]);
+				this.pages.set(finalPages);
+				this.pageParams.set(newParams);
 				this.error.set(void 0);
 				this.status.set("success");
 				this.isLoading.set(false);
@@ -727,13 +1061,18 @@ var InfiniteEntry = class {
 				this.lastUpdatedAt.set(Date.now());
 				this.isStale.set(this.staleTime === 0);
 			});
+			this.forcedStale = false;
 			if (this.staleTime > 0) this.scheduleStaleness();
 			this.onSuccessData?.(this.pages.peek());
-		}, "initial");
+			return finalPages[0];
+		} finally {
+			if (!this.disposed && this.status.peek() === "pending" && !this.isFetching.peek() && this.pages.peek().length > 0) this.status.set("success");
+		}
 	}
 	fetchNextPage() {
 		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error("Entry disposed"));
 		if (this.isFetchingNextPage.peek()) return Promise.resolve();
+		if (this.networkMode === "online" && this.isOffline()) return this.scheduleDeferredFetch("next");
 		const ps = this.pages.peek();
 		if (ps.length === 0) return this.startFetch().then(() => {});
 		const nextParam = this.getNextPageParam(ps[ps.length - 1], ps);
@@ -751,6 +1090,8 @@ var InfiniteEntry = class {
 			batch(() => {
 				this.pages.set([...this.pages.peek(), page]);
 				this.pageParams.set([...this.pageParams.peek(), param]);
+				this.error.set(void 0);
+				this.status.set("success");
 				this.isFetchingNextPage.set(false);
 				this.isFetching.set(false);
 				this.lastUpdatedAt.set(Date.now());
@@ -762,6 +1103,7 @@ var InfiniteEntry = class {
 		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error("Entry disposed"));
 		if (this.isFetchingPreviousPage.peek()) return Promise.resolve();
 		if (!this.getPreviousPageParam) return Promise.resolve();
+		if (this.networkMode === "online" && this.isOffline()) return this.scheduleDeferredFetch("prev");
 		const ps = this.pages.peek();
 		if (ps.length === 0) return this.startFetch().then(() => {});
 		const prevParam = this.getPreviousPageParam(ps[0], ps);
@@ -779,6 +1121,8 @@ var InfiniteEntry = class {
 			batch(() => {
 				this.pages.set([page, ...this.pages.peek()]);
 				this.pageParams.set([param, ...this.pageParams.peek()]);
+				this.error.set(void 0);
+				this.status.set("success");
 				this.isFetchingPreviousPage.set(false);
 				this.isFetching.set(false);
 				this.lastUpdatedAt.set(Date.now());
@@ -814,7 +1158,7 @@ var InfiniteEntry = class {
 						});
 						throw err;
 					}
-					await abortableSleep(typeof this.retryDelay === "function" ? this.retryDelay(attempt) : this.retryDelay, signal);
+					await abortableSleep(this.computeRetryDelay(attempt), signal);
 					attempt += 1;
 				}
 			}
@@ -822,18 +1166,25 @@ var InfiniteEntry = class {
 			if (!succeeded) batch(() => {
 				if (direction === "next") this.isFetchingNextPage.set(false);
 				if (direction === "prev") this.isFetchingPreviousPage.set(false);
+				if (!this.disposed && this.status.peek() === "pending" && !this.isFetching.peek() && this.pages.peek().length > 0) this.status.set("success");
 			});
 		}
 	}
 	refetch() {
 		return this.startFetch();
 	}
-	invalidate() {
+	/** Force stale without fetching — see `Entry.markStale` (spec §5.7, T3.9). */
+	markStale() {
+		if (this.disposed) return;
 		if (this.staleTimer != null) {
 			clearTimeout(this.staleTimer);
 			this.staleTimer = null;
 		}
+		this.forcedStale = true;
 		this.isStale.set(true);
+	}
+	invalidate() {
+		this.markStale();
 		return this.startFetch();
 	}
 	reset() {
@@ -843,33 +1194,73 @@ var InfiniteEntry = class {
 			this.status.set(this.pages.peek().length > 0 ? "success" : "idle");
 		});
 	}
-	setData(updater) {
+	/** Cancel an in-flight fetch (initial/refetch or paging) without touching
+	*  pages. Supersedes + aborts the current request, then restores a settled
+	*  status. No-op when idle. Mirrors `Entry.cancel` (spec §5, §6.4, T3.4). */
+	cancel() {
+		if (this.disposed || !this.isFetching.peek()) return;
+		this.currentFetchId += 1;
+		this.currentAbort?.abort();
+		this.currentAbort = null;
+		batch(() => {
+			this.isFetching.set(false);
+			this.isLoading.set(false);
+			this.isFetchingNextPage.set(false);
+			this.isFetchingPreviousPage.set(false);
+			this.status.set(this.pages.peek().length > 0 ? "success" : "idle");
+		});
+	}
+	setData(updater, opts) {
 		if (this.disposed) return {
 			rollback: () => {},
 			finalize: () => {}
 		};
 		const prev = this.pages.peek();
+		const prevParams = this.pageParams.peek();
 		const next = updater(prev.length === 0 ? void 0 : prev);
-		const id = this.nextSnapshotId++;
-		const record = {
-			id,
+		const record = opts?.track ?? true ? {
+			id: this.nextSnapshotId++,
 			prev,
+			prevParams,
 			live: true
-		};
-		this.snapshots.push(record);
+		} : null;
+		if (record) this.snapshots.push(record);
+		let nextParams = prevParams;
+		if (next.length !== prevParams.length) if (next.length < prevParams.length) nextParams = prevParams.slice(0, next.length);
+		else {
+			const pad = prevParams[prevParams.length - 1];
+			nextParams = prevParams.slice();
+			for (let i = prevParams.length; i < next.length; i++) nextParams.push(pad);
+		}
 		batch(() => {
 			this.pages.set(next);
+			if (nextParams !== prevParams) this.pageParams.set(nextParams);
 			if (this.status.peek() === "idle" || this.status.peek() === "pending") this.status.set("success");
 			this.lastUpdatedAt.set(Date.now());
-			this.hasPendingMutations.set(true);
+			if (record) this.hasPendingMutations.set(true);
 		});
+		if (!record) return {
+			rollback: () => {},
+			finalize: () => {}
+		};
+		const id = record.id;
 		return {
 			rollback: () => {
 				if (!record.live || this.disposed) return;
 				record.live = false;
 				batch(() => {
-					this.pages.set(record.prev);
-					this.snapshots = this.snapshots.filter((s) => s.id !== id);
+					const i = this.snapshots.indexOf(record);
+					if (i !== -1) {
+						if (i === this.snapshots.length - 1) {
+							this.pages.set(record.prev);
+							this.pageParams.set(record.prevParams);
+						} else {
+							const below = this.snapshots[i + 1];
+							below.prev = record.prev;
+							below.prevParams = record.prevParams;
+						}
+						this.snapshots.splice(i, 1);
+					}
 					this.hasPendingMutations.set(this.snapshots.some((s) => s.live));
 				});
 			},
@@ -904,10 +1295,61 @@ var InfiniteEntry = class {
 		});
 	}
 	isStaleNow() {
+		if (this.forcedStale) return true;
 		const last = this.lastUpdatedAt.peek();
 		if (last === void 0) return true;
 		return Date.now() - last >= this.staleTime;
 	}
+	computeRetryDelay(attempt) {
+		const d = this.retryDelay;
+		if (d === void 0) return Math.min(1e3 * 2 ** attempt, 3e4);
+		return typeof d === "function" ? d(attempt) : d;
+	}
+	isOffline() {
+		return typeof navigator !== "undefined" && navigator.onLine === false;
+	}
+	scheduleDeferredFetch(direction) {
+		this.isPaused.set(true);
+		if (this.reconnectUnsub === null) this.reconnectUnsub = subscribeReconnect(() => this.drainDeferred());
+		return new Promise((resolve, reject) => {
+			this.deferredResolvers.push({
+				direction,
+				resolve,
+				reject
+			});
+		});
+	}
+	drainDeferred() {
+		if (this.deferredResolvers.length === 0) return;
+		if (this.disposed) return;
+		this.isPaused.set(false);
+		const pending = this.deferredResolvers;
+		this.deferredResolvers = [];
+		if (this.reconnectUnsub !== null) {
+			this.reconnectUnsub();
+			this.reconnectUnsub = null;
+		}
+		const seen = /* @__PURE__ */ new Set();
+		const order = [
+			"initial",
+			"prev",
+			"next"
+		];
+		for (const d of pending) seen.add(d.direction);
+		const run = async () => {
+			for (const dir of order) {
+				if (!seen.has(dir)) continue;
+				if (dir === "initial") await this.startFetch();
+				else if (dir === "next") await this.fetchNextPage();
+				else await this.fetchPreviousPage();
+			}
+		};
+		run().then(() => {
+			for (const p of pending) p.resolve();
+		}, (err) => {
+			for (const p of pending) p.reject(err);
+		});
+	}
 	scheduleStaleness() {
 		if (this.staleTimer != null) clearTimeout(this.staleTimer);
 		if (this.staleTime > 0) this.staleTimer = setTimeout(() => {
@@ -924,6 +1366,22 @@ var InfiniteEntry = class {
 		}
 		this.currentAbort?.abort();
 		this.currentAbort = null;
+		batch(() => {
+			this.isFetching.set(false);
+			this.isLoading.set(false);
+			this.isFetchingNextPage.set(false);
+			this.isFetchingPreviousPage.set(false);
+		});
+		if (this.reconnectUnsub !== null) {
+			this.reconnectUnsub();
+			this.reconnectUnsub = null;
+		}
+		if (this.deferredResolvers.length > 0) {
+			const disposed = new DOMException("Entry disposed", "AbortError");
+			const pending = this.deferredResolvers;
+			this.deferredResolvers = [];
+			for (const p of pending) p.reject(disposed);
+		}
 		if (this.pendingFirstValueRejects.length > 0) {
 			const disposed = new DOMException("Entry disposed", "AbortError");
 			const rejects = this.pendingFirstValueRejects;
@@ -937,7 +1395,7 @@ var InfiniteEntry = class {
 /**
 * Stable string hash of a key tuple. Two equal-by-content args produce the
 * same string regardless of property iteration order. Handles primitives,
-* arrays, plain objects, Date.
+* arrays, plain objects, Date, BigInt, NaN, ±Infinity.
 *
 * Functions and symbols throw — keys must be serializable so distinct
 * subscribers can share entries.
@@ -945,13 +1403,23 @@ var InfiniteEntry = class {
 function stableHash(args) {
 	return JSON.stringify(args, replacer);
 }
-const replacer = (_key, value) => {
+const replacer = function(key, _value) {
+	const value = this[key];
 	if (typeof value === "function") throw new Error("[olas] query keys cannot contain functions");
 	if (typeof value === "symbol") throw new Error("[olas] query keys cannot contain symbols");
+	if (typeof value === "bigint") return { __bigint: value.toString() };
+	if (typeof value === "number") {
+		if (Number.isNaN(value)) return "__nan__";
+		if (value === Number.POSITIVE_INFINITY) return "__+inf__";
+		if (value === Number.NEGATIVE_INFINITY) return "__-inf__";
+		return value;
+	}
 	if (value === void 0) return "__undefined__";
 	if (value instanceof Date) return { __date: value.toISOString() };
 	if (value instanceof Map || value instanceof Set) throw new Error("[olas] query keys cannot contain Map/Set — use arrays/objects");
 	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const proto = Object.getPrototypeOf(value);
+		if (proto !== null && proto !== Object.prototype) throw new Error(`[olas] query keys cannot contain class instances (got ${proto.constructor?.name ?? "unknown"}) — pass plain object/array data`);
 		const sorted = {};
 		for (const k of Object.keys(value).sort()) sorted[k] = value[k];
 		return sorted;
@@ -960,12 +1428,31 @@ const replacer = (_key, value) => {
 };
 //#endregion
 //#region src/query/plugin.ts
-const queryRegistry = /* @__PURE__ */ new Map();
+/**
+* Back a module-level registry on `globalThis` under a shared `Symbol.for`
+* key. Guards the dual-package hazard: if a consumer ends up with both the ESM
+* and CJS build of `@kontsedal/olas-core` (common with mixed bundler configs),
+* each copy would otherwise own a SEPARATE registry `Map` — a mutation
+* registered via the ESM copy would be invisible to the mutation-queue plugin
+* loaded against the CJS copy, and cross-tab query lookups would miss. Sharing
+* one Map on `globalThis` makes both copies agree. T3.9.
+*/
+function globalRegistry(key) {
+	const store = globalThis;
+	const existing = store[key];
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	store[key] = created;
+	return created;
+}
+const queryRegistry = globalRegistry(Symbol.for("olas.queryRegistry"));
 /**
 * Register a query by its `queryId`. Internal — called from `defineQuery` /
 * `defineInfiniteQuery`. Replaces any previous registration with the same
 * id (matches Olas's "full root rebuild" HMR story; a mid-flight remote
-* message routed against the old `Query` simply misses).
+* message routed against the old `Query` simply misses). Dev-warns when a
+* *different* query overwrites an existing id — a genuine collision, since
+* cross-tab / persistence route by `queryId` (expected during HMR).
 */
 function registerQueryById(queryId, query) {
 	queryRegistry.set(queryId, query);
@@ -978,7 +1465,7 @@ function registerQueryById(queryId, query) {
 function lookupRegisteredQuery(queryId) {
 	return queryRegistry.get(queryId);
 }
-const mutationRegistry = /* @__PURE__ */ new Map();
+const mutationRegistry = globalRegistry(Symbol.for("olas.mutationRegistry"));
 /** Register a mutation by its `mutationId`. Internal — called from `defineMutation`. */
 function registerMutationById(mutationId, entry) {
 	mutationRegistry.set(mutationId, entry);
@@ -1000,6 +1487,14 @@ function _unregisterMutationById(mutationId) {
 //#endregion
 //#region src/query/client.ts
 const DEFAULT_GC_TIME = 5 * 6e4;
+/**
+* Composite hydration-buffer key: query identity + key hash. Namespacing by
+* identity stops a dehydrated entry for query A being adopted by query B that
+* merely hashes to the same key (spec §15, T1.2). `JSON.stringify` of the pair
+* is used rather than string concatenation so no separator char is ambiguous —
+* both `id` (an arbitrary user `queryId`) and `hash` are unbounded strings.
+*/
+const hydrationKey = (id, hash) => JSON.stringify([id, hash]);
 var ClientEntry = class {
 	entry;
 	/** The result of `spec.key(...args)` — used for hashing/identity. */
@@ -1038,6 +1533,8 @@ var ClientEntry = class {
 			staleTime: spec.staleTime,
 			retry: spec.retry,
 			retryDelay: spec.retryDelay,
+			networkMode: spec.networkMode,
+			structuralShare: spec.structuralShare,
 			initialData: hydrated?.data,
 			initialUpdatedAt: hydrated?.lastUpdatedAt,
 			events: void 0,
@@ -1075,6 +1572,8 @@ var ClientEntry = class {
 		if (this.refetchInterval == null) return;
 		if (this.intervalTimer != null) return;
 		this.intervalTimer = setInterval(() => {
+			if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+			if (this.entry.isFetching.peek()) return;
 			this.entry.startFetch().catch(() => {});
 		}, this.refetchInterval);
 	}
@@ -1118,6 +1617,7 @@ var ClientEntry = class {
 	/** Refetch on focus / reconnect, but only if the data is actually stale. */
 	triggerEventRefetch() {
 		if (!this.entry.isStaleNow()) return;
+		if (this.entry.isFetching.peek()) return;
 		this.entry.startFetch().catch(() => {});
 	}
 	dispose() {
@@ -1163,6 +1663,8 @@ var InfiniteClientEntry = class {
 			staleTime: spec.staleTime,
 			retry: spec.retry,
 			retryDelay: spec.retryDelay,
+			networkMode: spec.networkMode,
+			structuralShare: spec.structuralShare,
 			onSuccessData: onFetchSuccess
 		});
 	}
@@ -1174,6 +1676,9 @@ var InfiniteClientEntry = class {
 		}
 		if (this.subscriberCount === 1 && this.refetchInterval != null) this.startIntervalTimer();
 	}
+	hasSubscribers() {
+		return this.subscriberCount > 0;
+	}
 	release() {
 		this.subscriberCount -= 1;
 		if (this.subscriberCount <= 0) {
@@ -1188,6 +1693,8 @@ var InfiniteClientEntry = class {
 	startIntervalTimer() {
 		if (this.refetchInterval == null || this.intervalTimer != null) return;
 		this.intervalTimer = setInterval(() => {
+			if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+			if (this.entry.isFetching.peek()) return;
 			this.entry.startFetch().catch(() => {});
 		}, this.refetchInterval);
 	}
@@ -1263,7 +1770,7 @@ var QueryClient = class {
 		this.plugins = opts?.plugins ?? [];
 		if (opts?.hydrate) this.hydrate(opts.hydrate);
 		const api = this.makePluginApi();
-		for (const plugin of this.plugins) this.callPlugin(() => plugin.init?.(api));
+		for (const plugin of this.plugins) this.callPlugin(plugin, () => plugin.init?.(api));
 	}
 	/**
 	* Build the `QueryClientPluginApi` view that plugins receive at `init`
@@ -1288,13 +1795,14 @@ var QueryClient = class {
 		};
 	}
 	/** Invoke a plugin callback; route exceptions through `onError`. */
-	callPlugin(fn) {
+	callPlugin(plugin, fn) {
 		try {
 			fn();
 		} catch (err) {
 			dispatchError(this.onError, err, {
 				kind: "plugin",
-				controllerPath: []
+				controllerPath: [],
+				pluginName: plugin.name
 			});
 		}
 	}
@@ -1329,7 +1837,7 @@ var QueryClient = class {
 		};
 		for (const plugin of this.plugins) if (plugin.onSetData) {
 			const cb = plugin.onSetData;
-			this.callPlugin(() => cb.call(plugin, event));
+			this.callPlugin(plugin, () => cb.call(plugin, event));
 		}
 	}
 	emitInvalidate(query, keyArgs, kind) {
@@ -1344,7 +1852,7 @@ var QueryClient = class {
 		};
 		for (const plugin of this.plugins) if (plugin.onInvalidate) {
 			const cb = plugin.onInvalidate;
-			this.callPlugin(() => cb.call(plugin, event));
+			this.callPlugin(plugin, () => cb.call(plugin, event));
 		}
 	}
 	emitGc(query, keyArgs, kind) {
@@ -1358,7 +1866,7 @@ var QueryClient = class {
 		};
 		for (const plugin of this.plugins) if (plugin.onGc) {
 			const cb = plugin.onGc;
-			this.callPlugin(() => cb.call(plugin, event));
+			this.callPlugin(plugin, () => cb.call(plugin, event));
 		}
 	}
 	/**
@@ -1370,7 +1878,7 @@ var QueryClient = class {
 		if (this.plugins.length === 0) return;
 		for (const plugin of this.plugins) if (plugin.onMutationEnqueue) {
 			const cb = plugin.onMutationEnqueue;
-			this.callPlugin(() => cb.call(plugin, event));
+			this.callPlugin(plugin, () => cb.call(plugin, event));
 		}
 	}
 	/** Fan out a `MutationSettleEvent` to every installed plugin. SPEC §13.3. */
@@ -1378,7 +1886,7 @@ var QueryClient = class {
 		if (this.plugins.length === 0) return;
 		for (const plugin of this.plugins) if (plugin.onMutationSettle) {
 			const cb = plugin.onMutationSettle;
-			this.callPlugin(() => cb.call(plugin, event));
+			this.callPlugin(plugin, () => cb.call(plugin, event));
 		}
 	}
 	/** Resolve `queryId → live entry-map keys`. Empty array when unknown. */
@@ -1422,13 +1930,52 @@ var QueryClient = class {
 		if (!entry) return;
 		this.applyingRemote = true;
 		try {
-			entry.entry.setData(() => data);
+			entry.entry.setData(() => data, { track: false });
 			this.emitSetData(internal, entry.keyArgs, data, "data", "remote");
 		} finally {
 			this.applyingRemote = false;
 		}
 	}
 	/**
+	* Apply a single dehydrated entry to the cache. Idempotent across
+	* pre-bind / post-bind:
+	*
+	* - If the matching `ClientEntry` already exists (a subscriber has
+	*   bound this key), `Entry.applyHydration(data, lastUpdatedAt)` writes
+	*   through with the server's timestamp + supersedes any inflight
+	*   fetch. Plugins see a `SetDataEvent` with `source: 'remote'`.
+	* - If no `ClientEntry` exists yet (the subscribing component hasn't
+	*   mounted), the entry is buffered in `hydratedData` so the next
+	*   `bindEntry` for that hash picks it up — same path the constructor
+	*   `hydrate(state)` uses.
+	*
+	* Designed for streaming SSR: each `<Suspense>` boundary that resolves
+	* on the server pushes its dehydrated entry through this method on the
+	* client as the bootstrap script executes.
+	*/
+	applyDehydratedEntry(queryId, keyArgs, data, lastUpdatedAt) {
+		const query = lookupRegisteredQuery(queryId);
+		const hash = stableHash(keyArgs);
+		if (query && query.__olas === "query") {
+			const internal = query;
+			const entry = this.maps.get(internal)?.get(hash);
+			if (entry !== void 0) {
+				this.applyingRemote = true;
+				try {
+					entry.entry.applyHydration(data, lastUpdatedAt);
+					this.emitSetData(internal, entry.keyArgs, data, "data", "remote");
+				} finally {
+					this.applyingRemote = false;
+				}
+				return;
+			}
+		}
+		this.hydratedData.set(hydrationKey(queryId, hash), {
+			data,
+			lastUpdatedAt
+		});
+	}
+	/**
 	* Local-originated `setData` keyed by `queryId + keyArgs`. Plugin-facing
 	* (exposed via `QueryClientPluginApi.setEntryData`); used by the
 	* `@kontsedal/olas-entities` plugin to backpropagate entity patches into
@@ -1449,7 +1996,7 @@ var QueryClient = class {
 			if (!map) return;
 			const entry = map.get(hash);
 			if (!entry) return;
-			entry.entry.setData(updater);
+			entry.entry.setData(updater, { track: false });
 			this.emitSetData(internal, entry.keyArgs, entry.entry.data.peek(), "data", "set");
 			return;
 		}
@@ -1458,7 +2005,7 @@ var QueryClient = class {
 		if (!map) return;
 		const entry = map.get(hash);
 		if (!entry) return;
-		entry.entry.setData(updater);
+		entry.entry.setData(updater, { track: false });
 		this.emitSetData(internal, entry.keyArgs, entry.entry.pages.peek(), "infinite", "set");
 	}
 	applyRemoteInvalidate(queryId, keyArgs) {
@@ -1490,7 +2037,7 @@ var QueryClient = class {
 		if (state.version !== 1) return;
 		for (const entry of state.entries) {
 			const hash = stableHash(entry.key);
-			this.hydratedData.set(hash, {
+			this.hydratedData.set(hydrationKey(entry.id, hash), {
 				data: entry.data,
 				lastUpdatedAt: entry.lastUpdatedAt
 			});
@@ -1528,7 +2075,8 @@ var QueryClient = class {
 	}
 	dehydrate() {
 		const entries = [];
-		for (const map of this.maps.values()) for (const ce of map.values()) if (ce.entry.status.peek() === "success") entries.push({
+		for (const [query, map] of this.maps) for (const ce of map.values()) if (ce.entry.status.peek() === "success") entries.push({
+			id: query.__id,
 			key: ce.keyArgs,
 			data: ce.entry.data.peek(),
 			lastUpdatedAt: ce.entry.lastUpdatedAt.peek() ?? Date.now()
@@ -1554,6 +2102,19 @@ var QueryClient = class {
 			if (tasks.length === 0) return;
 			await Promise.all(tasks);
 		}
+		const unsettled = [];
+		for (const map of this.maps.values()) for (const ce of map.values()) if (ce.entry.isFetching.peek()) unsettled.push({
+			key: ce.keyArgs,
+			kind: "data"
+		});
+		for (const map of this.infiniteMaps.values()) for (const ce of map.values()) if (ce.entry.isFetching.peek()) unsettled.push({
+			key: ce.keyArgs,
+			kind: "infinite"
+		});
+		const err = /* @__PURE__ */ new Error("[olas] waitForIdle: exceeded 100-iteration safety bound — cache or mutations keep restarting");
+		err.unsettled = unsettled;
+		err.mutationsInflight = this.mutationsInflight$.peek();
+		throw err;
 	}
 	bindEntry(query, args) {
 		const internal = query;
@@ -1568,8 +2129,9 @@ var QueryClient = class {
 		const hash = stableHash(keyArgs);
 		let entry = map.get(hash);
 		if (!entry) {
-			const hydrated = this.hydratedData.get(hash);
-			if (hydrated) this.hydratedData.delete(hash);
+			const hkey = hydrationKey(internal.__id, hash);
+			const hydrated = this.hydratedData.get(hkey);
+			if (hydrated) this.hydratedData.delete(hkey);
 			const onFetchSuccess = internal.__spec.queryId != null ? (data) => this.emitSetData(internal, keyArgs, data, "data", "fetch") : void 0;
 			entry = new ClientEntry(this, internal, args, keyArgs, internal.__spec, hydrated, onFetchSuccess);
 			map.set(hash, entry);
@@ -1588,6 +2150,24 @@ var QueryClient = class {
 		if (map.size === 0) this.maps.delete(entry.query);
 		this.emitGc(entry.query, entry.keyArgs, "data");
 	}
+	/**
+	* Invalidate one entry: if it has subscribers, mark stale AND refetch; if
+	* not, mark stale only — the next subscriber refetches. Spec §5.7 says
+	* invalidate refetches only IF subscribed; the old always-fetch behavior woke
+	* orphaned entries that no one was watching (T3.9). Works for both
+	* `ClientEntry` and `InfiniteClientEntry`.
+	*/
+	invalidateEntry(entry) {
+		if (entry.hasSubscribers()) entry.entry.invalidate().catch((err) => {
+			if (isAbortError(err)) return;
+			dispatchError(this.onError, err, {
+				kind: "cache",
+				controllerPath: [],
+				queryKey: entry.keyArgs
+			});
+		});
+		else entry.entry.markStale();
+	}
 	invalidate(query, args) {
 		const internal = query;
 		const map = this.maps.get(internal);
@@ -1596,14 +2176,7 @@ var QueryClient = class {
 		const hash = stableHash(keyArgs);
 		const entry = map.get(hash);
 		if (!entry) return;
-		entry.entry.invalidate().catch((err) => {
-			if (isAbortError(err)) return;
-			dispatchError(this.onError, err, {
-				kind: "cache",
-				controllerPath: [],
-				queryKey: keyArgs
-			});
-		});
+		this.invalidateEntry(entry);
 		this.emitInvalidate(internal, keyArgs, "data");
 	}
 	invalidateAll(query) {
@@ -1611,22 +2184,35 @@ var QueryClient = class {
 		const map = this.maps.get(internal);
 		if (!map) return;
 		for (const [hash, entry] of map) {
-			entry.entry.invalidate().catch((err) => {
-				if (isAbortError(err)) return;
-				dispatchError(this.onError, err, {
-					kind: "cache",
-					controllerPath: [],
-					queryKey: entry.keyArgs
-				});
-			});
+			this.invalidateEntry(entry);
 			this.emitInvalidate(internal, entry.keyArgs, "data");
 		}
 	}
+	cancel(query, args) {
+		const internal = query;
+		const map = this.maps.get(internal);
+		if (!map) return;
+		const hash = stableHash(internal.__spec.key(...args));
+		map.get(hash)?.entry.cancel();
+	}
+	cancelAll(query) {
+		const map = this.maps.get(query);
+		if (!map) return;
+		for (const entry of map.values()) entry.entry.cancel();
+	}
 	setData(query, args, updater) {
 		const entry = this.bindEntry(query, args);
 		const snapshot = entry.entry.setData(updater);
 		this.emitSetData(entry.query, entry.keyArgs, entry.entry.data.peek(), "data", "set");
-		return snapshot;
+		return {
+			rollback: () => {
+				const before = entry.entry.data.peek();
+				snapshot.rollback();
+				const after = entry.entry.data.peek();
+				if (!Object.is(before, after)) this.emitSetData(entry.query, entry.keyArgs, after, "data", "set");
+			},
+			finalize: () => snapshot.finalize()
+		};
 	}
 	bindInfiniteEntry(query, args) {
 		const internal = query;
@@ -1666,14 +2252,7 @@ var QueryClient = class {
 		const hash = stableHash(keyArgs);
 		const entry = map.get(hash);
 		if (!entry) return;
-		entry.entry.invalidate().catch((err) => {
-			if (isAbortError(err)) return;
-			dispatchError(this.onError, err, {
-				kind: "cache",
-				controllerPath: [],
-				queryKey: entry.keyArgs
-			});
-		});
+		this.invalidateEntry(entry);
 		this.emitInvalidate(internal, keyArgs, "infinite");
 	}
 	invalidateAllInfinite(query) {
@@ -1681,22 +2260,35 @@ var QueryClient = class {
 		const map = this.infiniteMaps.get(internal);
 		if (!map) return;
 		for (const entry of map.values()) {
-			entry.entry.invalidate().catch((err) => {
-				if (isAbortError(err)) return;
-				dispatchError(this.onError, err, {
-					kind: "cache",
-					controllerPath: [],
-					queryKey: entry.keyArgs
-				});
-			});
+			this.invalidateEntry(entry);
 			this.emitInvalidate(internal, entry.keyArgs, "infinite");
 		}
 	}
+	cancelInfinite(query, args) {
+		const internal = query;
+		const map = this.infiniteMaps.get(internal);
+		if (!map) return;
+		const hash = stableHash(internal.__spec.key(...args));
+		map.get(hash)?.entry.cancel();
+	}
+	cancelAllInfinite(query) {
+		const map = this.infiniteMaps.get(query);
+		if (!map) return;
+		for (const entry of map.values()) entry.entry.cancel();
+	}
 	setInfiniteData(query, args, updater) {
 		const entry = this.bindInfiniteEntry(query, args);
 		const snapshot = entry.entry.setData(updater);
 		this.emitSetData(entry.query, entry.keyArgs, entry.entry.pages.peek(), "infinite", "set");
-		return snapshot;
+		return {
+			rollback: () => {
+				const before = entry.entry.pages.peek();
+				snapshot.rollback();
+				const after = entry.entry.pages.peek();
+				if (!Object.is(before, after)) this.emitSetData(entry.query, entry.keyArgs, after, "infinite", "set");
+			},
+			finalize: () => snapshot.finalize()
+		};
 	}
 	prefetchInfinite(query, args) {
 		const entry = this.bindInfiniteEntry(query, args);
@@ -1734,7 +2326,7 @@ var QueryClient = class {
 		this.hydratedData.clear();
 		for (const plugin of this.plugins) if (plugin.dispose) {
 			const cb = plugin.dispose;
-			this.callPlugin(() => cb.call(plugin));
+			this.callPlugin(plugin, () => cb.call(plugin));
 		}
 	}
 };
@@ -1819,12 +2411,52 @@ function createEmitter(options) {
 }
 //#endregion
 //#region src/forms/field.ts
+/**
+* Flatten a single validator result to plain message strings for a leaf field.
+* A leaf has no descendants, so a `FormIssue[]`'s paths don't route anywhere —
+* every issue's `message` applies to this field. `null` → no messages.
+*/
+function messagesFromResult(result) {
+	if (result == null) return [];
+	if (typeof result === "string") return [result];
+	return result.map((issue) => issue.message);
+}
+/**
+* Structural equality used by `Field.set` to decide whether a write returns
+* the field to its initial value (clearing `isDirty`). Cheap path for
+* primitives + `Object.is`; deep walk for arrays and plain objects. Class
+* instances, Map, Set, Date fall back to reference identity — same trade-off
+* `structural-share.ts` makes for cache data.
+*/
+function isStructurallyEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b) || a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!isStructurallyEqual(a[i], b[i])) return false;
+		return true;
+	}
+	if (Array.isArray(b)) return false;
+	const protoA = Object.getPrototypeOf(a);
+	const protoB = Object.getPrototypeOf(b);
+	if (protoA !== Object.prototype && protoA !== null) return false;
+	if (protoB !== Object.prototype && protoB !== null) return false;
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if (keysA.length !== keysB.length) return false;
+	for (const k of keysA) {
+		if (!Object.hasOwn(b, k)) return false;
+		if (!isStructurallyEqual(a[k], b[k])) return false;
+	}
+	return true;
+}
 var FieldImpl = class {
 	value$;
 	/**
 	* Validator-produced errors. The public `errors` getter merges this with
-	* `serverErrors$` so consumers see a single flat array. Kept separate so a
-	* re-run of validators (after a new value) doesn't clobber server errors.
+	* `serverErrors$` and `formErrors$` so consumers see a single flat array.
+	* Kept separate so a re-run of validators (after a new value) doesn't clobber
+	* the other two channels.
 	*/
 	validatorErrors$;
 	/**
@@ -1832,11 +2464,29 @@ var FieldImpl = class {
 	* `set()`, on `reset()`, or via an explicit `setErrors([])`.
 	*/
 	serverErrors$;
+	/**
+	* Errors routed here by a parent (or ancestor) form-level validator that
+	* targeted this field via a `FormIssue` path — the third error channel
+	* beside validator + server errors (T5.2). Owned by the routing form: cleared
+	* and re-applied on every form-level validation run, so it does NOT clear on
+	* the field's own `set()` (a stale cross-field error survives until the next
+	* form-level run recomputes it). Cleared by `reset()` / `setAsInitial()`.
+	*/
+	formErrors$;
 	errors$;
 	touched$;
 	dirty$;
 	validating$;
 	isValid$;
+	/**
+	* Validity as of the last *settled* validation pass. While a pass is in
+	* flight (`validating$`), `isValid` reads this instead of the live `errors`
+	* — otherwise a `debouncedValidator` would flip `isValid` to `false` on every
+	* keystroke (the async-start clears `validatorErrors$`), strobing a submit
+	* button. Updated only when a pass completes (T5.3). Defaults `true` (an
+	* untouched field with a pending first run reads valid, not invalid).
+	*/
+	lastValid$;
 	revalidateTrigger$;
 	validators;
 	/** The value `reset()` returns to. Mutated by `setAsInitial()` so a form
@@ -1848,25 +2498,42 @@ var FieldImpl = class {
 	disposed = false;
 	devtoolsOwner = null;
 	onValidatorError = null;
+	validateOn;
+	/** Reactive gate — when false, the validator effect skips its run. Flipped
+	* on by the relevant trigger for the field's `validateOn` mode. Once on,
+	* stays on for the lifetime of the field (matches RHF's `mode + reValidateMode`
+	* default semantics: after the first activation, subsequent changes
+	* re-validate). `reset()` flips it back to false. */
+	validateUnlocked$;
 	constructor(initial, validators = [], options) {
 		this.initial = initial;
 		this.validators = validators;
 		this.onValidatorError = options?.onValidatorError ?? null;
+		this.validateOn = options?.validateOn ?? "change";
 		this.value$ = signal(initial);
 		this.validatorErrors$ = signal([]);
 		this.serverErrors$ = signal([]);
+		this.formErrors$ = signal([]);
 		this.touched$ = signal(false);
 		this.dirty$ = signal(false);
 		this.validating$ = signal(false);
+		this.lastValid$ = signal(true);
 		this.revalidateTrigger$ = signal(0);
+		this.validateUnlocked$ = signal(this.validateOn === "change");
 		this.errors$ = computed(() => {
 			const v = this.validatorErrors$.value;
 			const s = this.serverErrors$.value;
-			if (s.length === 0) return v;
-			if (v.length === 0) return s;
-			return [...v, ...s];
+			const f = this.formErrors$.value;
+			if (s.length === 0 && f.length === 0) return v;
+			if (v.length === 0 && f.length === 0) return s;
+			if (v.length === 0 && s.length === 0) return f;
+			return [
+				...v,
+				...s,
+				...f
+			];
 		});
-		this.isValid$ = computed(() => this.errors$.value.length === 0 && !this.validating$.value);
+		this.isValid$ = computed(() => this.validating$.value ? this.lastValid$.value : this.errors$.value.length === 0);
 		if (validators.length > 0) this.validatorDispose = effect(() => {
 			this.runValidators();
 		});
@@ -1887,6 +2554,9 @@ var FieldImpl = class {
 	subscribe(handler) {
 		return this.value$.subscribe(handler);
 	}
+	subscribeChanges(handler) {
+		return this.value$.subscribeChanges(handler);
+	}
 	get errors() {
 		return this.errors$;
 	}
@@ -1906,7 +2576,7 @@ var FieldImpl = class {
 		if (this.disposed) return;
 		batch(() => {
 			this.value$.set(value);
-			this.dirty$.set(true);
+			this.dirty$.set(!isStructurallyEqual(value, this.initial));
 			if (this.serverErrors$.peek().length > 0) this.serverErrors$.set([]);
 		});
 	}
@@ -1916,6 +2586,18 @@ var FieldImpl = class {
 		this.serverErrors$.set(next);
 	}
 	/**
+	* Internal — set the parent-form-validator error channel (`formErrors$`).
+	* Called by the owning form's issue router when a `FormIssue` path resolves
+	* to this field. Guards against churning the signal when nothing changes so
+	* a whole-tree clear pass doesn't wake unrelated subscribers. See T5.2 /
+	* `routeFormIssues` in `form.ts`.
+	*/
+	setFormErrors(errors) {
+		if (this.disposed) return;
+		if (this.formErrors$.peek().length === 0 && errors.length === 0) return;
+		this.formErrors$.set(errors.length === 0 ? [] : [...errors]);
+	}
+	/**
 	* Reseat the field as if this value had been its constructor `initial`.
 	* Sets the value, re-anchors `reset()`'s target, and does NOT mark dirty.
 	* Used by `Form` when applying its own `initial` (in the constructor and
@@ -1928,6 +2610,8 @@ var FieldImpl = class {
 		batch(() => {
 			this.value$.set(value);
 			this.dirty$.set(false);
+			if (this.serverErrors$.peek().length > 0) this.serverErrors$.set([]);
+			if (this.formErrors$.peek().length > 0) this.formErrors$.set([]);
 		});
 	}
 	reset() {
@@ -1940,15 +2624,19 @@ var FieldImpl = class {
 			this.touched$.set(false);
 			this.validatorErrors$.set([]);
 			this.serverErrors$.set([]);
+			this.formErrors$.set([]);
 			this.validating$.set(false);
+			if (this.validateOn !== "change") this.validateUnlocked$.set(false);
 		});
 	}
 	markTouched() {
 		if (this.disposed) return;
 		this.touched$.set(true);
+		if (this.validateOn === "blur" && !this.validateUnlocked$.peek()) this.validateUnlocked$.set(true);
 	}
 	async revalidate() {
 		if (this.disposed) return this.isValid$.peek();
+		if (!this.validateUnlocked$.peek()) this.validateUnlocked$.set(true);
 		this.revalidateTrigger$.update((n) => n + 1);
 		await this.waitUntilSettled();
 		return this.isValid$.peek();
@@ -1987,6 +2675,14 @@ var FieldImpl = class {
 		if (this.disposed) return;
 		const value = this.value$.value;
 		this.revalidateTrigger$.value;
+		if (!this.validateUnlocked$.value) {
+			batch(() => {
+				if (this.validatorErrors$.peek().length > 0) this.validatorErrors$.set([]);
+				if (this.validating$.peek()) this.validating$.set(false);
+				this.lastValid$.set(this.errors$.peek().length === 0);
+			});
+			return;
+		}
 		this.currentAbort?.abort();
 		const abort = new AbortController();
 		this.currentAbort = abort;
@@ -1996,17 +2692,21 @@ var FieldImpl = class {
 		for (const validator of this.validators) try {
 			const result = validator(value, abort.signal);
 			if (result instanceof Promise) asyncPromises.push(result);
-			else if (result != null) syncErrors.push(result);
+			else {
+				const msgs = messagesFromResult(result);
+				if (msgs.length > 0) syncErrors.push(...msgs);
+			}
 		} catch (err) {
 			try {
 				this.onValidatorError?.(err);
 			} catch {}
-			syncErrors.push(err instanceof Error ? err.message : String(err));
+			syncErrors.push("Validation failed");
 		}
 		if (syncErrors.length > 0) {
 			batch(() => {
 				this.validatorErrors$.set(syncErrors);
 				this.validating$.set(false);
+				this.lastValid$.set(this.errors$.peek().length === 0);
 			});
 			this.emitValidated(false, syncErrors);
 			return;
@@ -2015,6 +2715,7 @@ var FieldImpl = class {
 			batch(() => {
 				this.validatorErrors$.set([]);
 				this.validating$.set(false);
+				this.lastValid$.set(this.errors$.peek().length === 0);
 			});
 			this.emitValidated(true, []);
 			return;
@@ -2026,15 +2727,15 @@ var FieldImpl = class {
 		Promise.allSettled(asyncPromises).then((results) => {
 			if (myId !== this.runId || this.disposed) return;
 			const asyncErrors = [];
-			for (const r of results) if (r.status === "fulfilled") {
-				if (r.value != null) asyncErrors.push(r.value);
-			} else if (!isAbortError(r.reason)) {
+			for (const r of results) if (r.status === "fulfilled") asyncErrors.push(...messagesFromResult(r.value));
+			else if (!isAbortError(r.reason)) {
 				const msg = r.reason instanceof Error ? r.reason.message : String(r.reason);
 				asyncErrors.push(msg);
 			}
 			batch(() => {
 				this.validatorErrors$.set(asyncErrors);
 				this.validating$.set(false);
+				this.lastValid$.set(this.errors$.peek().length === 0);
 			});
 			this.emitValidated(asyncErrors.length === 0, asyncErrors);
 		});
@@ -2065,7 +2766,9 @@ function createField(initial, validators, options) {
 /**
 * Wrap an async validator with a debounce. The debounce timer resets on every
 * value change. While debouncing or the request is in flight, the field's
-* `isValidating` is true and `isValid` is false (treat-as-invalid-until-proven-valid).
+* `isValidating` is true and `isValid` HOLDS its last settled value (T5.3) — so
+* editing an already-valid field doesn't strobe a submit button to disabled on
+* every keystroke. A field with no prior settled validation defaults to valid.
 */
 function debouncedValidator(fn, ms) {
 	return (value, signal) => new Promise((resolve, reject) => {
@@ -2091,6 +2794,73 @@ const FORM_BRAND = Symbol.for("olas.form");
 const FIELD_ARRAY_BRAND = Symbol.for("olas.fieldArray");
 const isForm = (x) => typeof x === "object" && x !== null && x[FORM_BRAND] === true;
 const isFieldArray = (x) => typeof x === "object" && x !== null && x[FIELD_ARRAY_BRAND] === true;
+/**
+* Walk a form tree from `root` following `FormIssue.path` segments. Forms walk
+* keys; field-arrays walk numeric indices. Returns the resolved node, or
+* `undefined` if the path runs off the tree (bad index, or a leaf reached with
+* an unconsumed path segment). Reads are untracked (`fields` is a static object;
+* `at()` peeks) so calling this inside a validator effect adds no dependencies.
+*/
+function resolveNode(root, segments) {
+	let cursor = root;
+	for (const seg of segments) {
+		if (cursor === void 0 || cursor === null) return void 0;
+		if (isForm(cursor)) cursor = cursor.fields[String(seg)];
+		else if (isFieldArray(cursor)) {
+			const idx = Number(seg);
+			if (!Number.isInteger(idx) || idx < 0) return void 0;
+			cursor = cursor.at(idx);
+		} else return;
+	}
+	return cursor;
+}
+/**
+* Normalize one validator result into the shared `FormIssue[]` shape. A plain
+* string is a message on the node itself (empty path); `null` contributes
+* nothing; a `FormIssue[]` is appended verbatim.
+*/
+function appendIssues(out, result) {
+	if (result == null) return;
+	if (typeof result === "string") {
+		out.push({
+			path: [],
+			message: result
+		});
+		return;
+	}
+	for (const issue of result) out.push(issue);
+}
+/**
+* Route a fully-collected issue set for one form-level validation run:
+*  - empty-path (and unresolvable) issues → `topLevelErrors$` on the owning node
+*  - path issues → the resolved descendant's `setFormErrors`
+*
+* Targets that received an error last run but not this one are cleared, so a
+* fixed cross-field rule removes its message from the field it landed on.
+* Returns the new target set for the caller to retain. MUST run inside a batch.
+*/
+function routeFormIssues(root, issues, topLevelErrors$, lastTargets) {
+	const topLevel = [];
+	const byTarget = /* @__PURE__ */ new Map();
+	for (const issue of issues) {
+		if (issue.path.length === 0) {
+			topLevel.push(issue.message);
+			continue;
+		}
+		const target = resolveNode(root, issue.path);
+		if (target === void 0 || typeof target.setFormErrors !== "function") {
+			topLevel.push(issue.message);
+			continue;
+		}
+		const list = byTarget.get(target);
+		if (list) list.push(issue.message);
+		else byTarget.set(target, [issue.message]);
+	}
+	topLevelErrors$.set(topLevel);
+	for (const t of lastTargets) if (!byTarget.has(t)) t.setFormErrors?.([]);
+	for (const [t, msgs] of byTarget) t.setFormErrors?.(msgs);
+	return new Set(byTarget.keys());
+}
 var FormImpl = class {
 	[FORM_BRAND] = true;
 	fields;
@@ -2101,9 +2871,33 @@ var FormImpl = class {
 	touched;
 	isValidating;
 	flatErrors;
+	/**
+	* Dotted paths of every leaf whose `isDirty` is `true`. Recomputes when
+	* any child's dirty state flips; ordered by depth-first traversal so two
+	* snapshots of a stable tree compare with `===`-friendly references on
+	* unchanged subsets. Useful for partial-update PATCH payloads and
+	* "highlight the changed inputs" UIs.
+	*/
+	dirtyFields;
 	topLevelErrors$ = signal([]);
-	topLevelErrors = this.topLevelErrors$;
+	/**
+	* Errors routed to THIS form by an ancestor form-level validator (a
+	* `FormIssue` whose path resolves to this node). Merged into `topLevelErrors`
+	* beside this form's own validator output, so `topLevelErrors` means "errors
+	* attached to this node itself, whatever their source". Owned by the ancestor
+	* router (T5.2) — see `setFormErrors`.
+	*/
+	parentFormErrors$ = signal([]);
+	topLevelErrors = computed(() => {
+		const own = this.topLevelErrors$.value;
+		const parent = this.parentFormErrors$.value;
+		if (parent.length === 0) return own;
+		if (own.length === 0) return parent;
+		return [...own, ...parent];
+	});
 	topLevelValidating$ = signal(false);
+	/** Targets written by the last form-level run — cleared next run if absent. */
+	lastFormErrorTargets = /* @__PURE__ */ new Set();
 	isSubmitting$ = signal(false);
 	submitCount$ = signal(0);
 	submitError$ = signal(void 0);
@@ -2157,12 +2951,17 @@ var FormImpl = class {
 			return false;
 		});
 		this.isValid = computed(() => {
-			if (this.topLevelErrors$.value.length > 0) return false;
+			if (this.topLevelErrors.value.length > 0) return false;
 			if (this.isValidating.value) return false;
 			for (const child of Object.values(this.fields)) if (!child.isValid.value) return false;
 			return true;
 		});
 		this.flatErrors = computed(() => this.computeFlatErrors());
+		this.dirtyFields = computed(() => {
+			const out = [];
+			collectDirtyFields(this.fields, "", out);
+			return out;
+		});
 		if (this.validators.length > 0) this.validatorDispose = effect(() => this.runTopLevelValidators());
 	}
 	computeValue() {
@@ -2187,7 +2986,7 @@ var FormImpl = class {
 	}
 	computeFlatErrors() {
 		const out = [];
-		const tle = this.topLevelErrors$.value;
+		const tle = this.topLevelErrors.value;
 		if (tle.length > 0) out.push({
 			path: "",
 			errors: tle
@@ -2243,11 +3042,14 @@ var FormImpl = class {
 			for (const child of Object.values(this.fields)) if (isForm(child) || isFieldArray(child)) child.reset();
 			else child.reset();
 			this.topLevelErrors$.set([]);
+			this.parentFormErrors$.set([]);
+			this.submitCount$.set(0);
+			this.submitError$.set(void 0);
+			if (this.options?.initial !== void 0) {
+				const ini = typeof this.options.initial === "function" ? this.options.initial() : this.options.initial;
+				if (ini !== void 0) this.applyPartial(ini, true);
+			}
 		});
-		if (this.options?.initial !== void 0) {
-			const ini = typeof this.options.initial === "function" ? this.options.initial() : this.options.initial;
-			if (ini !== void 0) this.applyPartial(ini, true);
-		}
 	}
 	markAllTouched() {
 		if (this.disposed) return;
@@ -2349,9 +3151,43 @@ var FormImpl = class {
 			}
 		});
 	}
+	/**
+	* Internal — receive errors routed here by an ancestor form-level validator
+	* (a `FormIssue` whose path resolved to this nested form). Guards against
+	* spurious writes so a whole-tree clear pass doesn't wake subscribers. See
+	* `routeFormIssues`.
+	*/
+	setFormErrors(errors) {
+		if (this.disposed) return;
+		if (this.parentFormErrors$.peek().length === 0 && errors.length === 0) return;
+		this.parentFormErrors$.set(errors.length === 0 ? [] : [...errors]);
+	}
+	/**
+	* Reset a named subtree to its initial. `path` uses the same dotted /
+	* bracket notation as `setErrors` / `flatErrors`. Useful when
+	* `Form.set({foo: undefined})` would be ambiguous ("clear" vs "leave
+	* alone" — the latter is what `set` does today).
+	*
+	* Walks via `resolvePath`; the resolved target must expose `reset()`
+	* (Field, Form, or FieldArray all do). Unknown paths are silently
+	* ignored — `flatErrors`-shaped paths from upstream code shouldn't
+	* crash this. Pass an empty string to reset the whole form (same as
+	* `form.reset()`).
+	*/
+	clearSubtree(path) {
+		if (this.disposed) return;
+		if (path === "") {
+			this.reset();
+			return;
+		}
+		const target = this.resolvePath(path);
+		if (target === void 0) return;
+		if (typeof target.reset === "function") target.reset();
+	}
 	resolvePath(path) {
 		if (path === "") return void 0;
-		const segments = path.split(".");
+		const segments = splitPath(path);
+		if (segments === null) return void 0;
 		let cursor = this;
 		for (const seg of segments) {
 			if (cursor === void 0 || cursor === null) return void 0;
@@ -2388,47 +3224,99 @@ var FormImpl = class {
 		const abort = new AbortController();
 		this.currentValidatorAbort = abort;
 		const myId = ++this.currentValidatorRun;
-		const syncErrors = [];
+		const syncIssues = [];
 		const asyncPromises = [];
 		for (const v of this.validators) try {
 			const r = v(value, abort.signal);
 			if (r instanceof Promise) asyncPromises.push(r);
-			else if (r != null) syncErrors.push(r);
+			else appendIssues(syncIssues, r);
 		} catch (err) {
 			try {
 				this.onValidatorError?.(err);
 			} catch {}
-			syncErrors.push(err instanceof Error ? err.message : String(err));
+			syncIssues.push({
+				path: [],
+				message: "Validation failed"
+			});
 		}
-		if (syncErrors.length > 0) {
+		if (syncIssues.length > 0) {
 			batch(() => {
-				this.topLevelErrors$.set(syncErrors);
+				this.lastFormErrorTargets = routeFormIssues(this, syncIssues, this.topLevelErrors$, this.lastFormErrorTargets);
 				this.topLevelValidating$.set(false);
 			});
 			return;
 		}
 		if (asyncPromises.length === 0) {
 			batch(() => {
-				this.topLevelErrors$.set([]);
+				this.lastFormErrorTargets = routeFormIssues(this, [], this.topLevelErrors$, this.lastFormErrorTargets);
 				this.topLevelValidating$.set(false);
 			});
 			return;
 		}
 		batch(() => {
-			this.topLevelErrors$.set([]);
+			this.lastFormErrorTargets = routeFormIssues(this, [], this.topLevelErrors$, this.lastFormErrorTargets);
 			this.topLevelValidating$.set(true);
 		});
 		Promise.allSettled(asyncPromises).then((results) => {
 			if (myId !== this.currentValidatorRun || this.disposed) return;
-			const errs = [];
-			for (const r of results) if (r.status === "fulfilled" && r.value != null) errs.push(r.value);
+			const issues = [];
+			for (const r of results) if (r.status === "fulfilled") appendIssues(issues, r.value);
 			batch(() => {
-				this.topLevelErrors$.set(errs);
+				this.lastFormErrorTargets = routeFormIssues(this, issues, this.topLevelErrors$, this.lastFormErrorTargets);
 				this.topLevelValidating$.set(false);
 			});
 		});
 	}
 };
+/**
+* Split a path string into segments, accepting both dot syntax (`users.0.name`)
+* and the bracket syntax `walkErrors` emits for array items (`users[0].name`).
+* Returns `null` if the path is malformed (unclosed bracket, empty bracket,
+* non-numeric bracket index).
+*/
+function splitPath(path) {
+	const out = [];
+	let current = "";
+	for (let i = 0; i < path.length; i++) {
+		const ch = path[i];
+		if (ch === ".") {
+			if (current !== "") {
+				out.push(current);
+				current = "";
+			}
+			continue;
+		}
+		if (ch === "[") {
+			if (current !== "") {
+				out.push(current);
+				current = "";
+			}
+			const close = path.indexOf("]", i + 1);
+			if (close === -1) return null;
+			const idx = path.slice(i + 1, close);
+			if (idx === "" || !/^\d+$/.test(idx)) return null;
+			out.push(idx);
+			i = close;
+			continue;
+		}
+		if (ch === "]") return null;
+		current += ch;
+	}
+	if (current !== "") out.push(current);
+	return out;
+}
+function collectDirtyFields(fields, prefix, out) {
+	for (const [k, child] of Object.entries(fields)) {
+		const path = prefix ? `${prefix}.${k}` : k;
+		if (isForm(child)) collectDirtyFields(child.fields, path, out);
+		else if (isFieldArray(child)) child.items.value.forEach((item, idx) => {
+			const itemPath = `${path}[${idx}]`;
+			if (isForm(item)) collectDirtyFields(item.fields, itemPath, out);
+			else if (item.isDirty.value) out.push(itemPath);
+		});
+		else if (child.isDirty.value) out.push(path);
+	}
+}
 function walkErrors(fields, prefix, out) {
 	for (const [k, child] of Object.entries(fields)) {
 		const path = prefix ? `${prefix}.${k}` : k;
@@ -2482,9 +3370,28 @@ var FieldArrayImpl = class {
 	touched;
 	isValidating;
 	items$;
+	/**
+	* Structural dirtiness — flipped by `add`/`insert`/`remove`/`move`/`clear`.
+	* Item-level `isDirty` alone misses these, so a reactive `initial` + the
+	* default `resetOnInitialChange: 'when-clean'` would re-seat the array on a
+	* background refetch and delete rows the user just added (T5.1). Reset by
+	* `reset()` and by an initial-driven re-anchor (`replaceInitialItems`).
+	*/
+	structurallyDirty$ = signal(false);
 	topLevelErrors$ = signal([]);
-	topLevelErrors = this.topLevelErrors$;
+	/** Errors routed to this array by an ancestor form-level validator (T5.2) —
+	*  merged into `topLevelErrors` beside the array's own validator output. */
+	parentFormErrors$ = signal([]);
+	topLevelErrors = computed(() => {
+		const own = this.topLevelErrors$.value;
+		const parent = this.parentFormErrors$.value;
+		if (parent.length === 0) return own;
+		if (own.length === 0) return parent;
+		return [...own, ...parent];
+	});
 	topLevelValidating$ = signal(false);
+	/** Targets written by the last array-level run — cleared next run if absent. */
+	lastFormErrorTargets = /* @__PURE__ */ new Set();
 	itemFactory;
 	initialItems = [];
 	validators;
@@ -2519,6 +3426,7 @@ var FieldArrayImpl = class {
 			return errs.length > 0 ? errs : void 0;
 		}));
 		this.isDirty = computed(() => {
+			if (this.structurallyDirty$.value) return true;
 			for (const item of this.items$.value) if (item.isDirty.value) return true;
 			return false;
 		});
@@ -2532,7 +3440,7 @@ var FieldArrayImpl = class {
 			return false;
 		});
 		this.isValid = computed(() => {
-			if (this.topLevelErrors$.value.length > 0) return false;
+			if (this.topLevelErrors.value.length > 0) return false;
 			if (this.isValidating.value) return false;
 			for (const item of this.items$.value) if (!item.isValid.value) return false;
 			return true;
@@ -2542,10 +3450,20 @@ var FieldArrayImpl = class {
 	at(index) {
 		return this.items$.peek()[index];
 	}
+	/**
+	* Internal — receive errors routed here by an ancestor form-level validator
+	* (a `FormIssue` whose path resolved to this array). See `routeFormIssues`.
+	*/
+	setFormErrors(errors) {
+		if (this.disposed) return;
+		if (this.parentFormErrors$.peek().length === 0 && errors.length === 0) return;
+		this.parentFormErrors$.set(errors.length === 0 ? [] : [...errors]);
+	}
 	add(initial) {
 		if (this.disposed) return;
 		const item = this.itemFactory(initial);
 		this.items$.set([...this.items$.peek(), item]);
+		this.structurallyDirty$.set(true);
 	}
 	insert(index, initial) {
 		if (this.disposed) return;
@@ -2553,6 +3471,7 @@ var FieldArrayImpl = class {
 		const next = [...this.items$.peek()];
 		next.splice(index, 0, item);
 		this.items$.set(next);
+		this.structurallyDirty$.set(true);
 	}
 	remove(index) {
 		if (this.disposed) return;
@@ -2560,6 +3479,7 @@ var FieldArrayImpl = class {
 		const [removed] = next.splice(index, 1);
 		if (removed) removed.dispose?.();
 		this.items$.set(next);
+		this.structurallyDirty$.set(true);
 	}
 	move(from, to) {
 		if (this.disposed) return;
@@ -2567,11 +3487,13 @@ var FieldArrayImpl = class {
 		const [item] = next.splice(from, 1);
 		if (item) next.splice(to, 0, item);
 		this.items$.set(next);
+		this.structurallyDirty$.set(true);
 	}
 	clear() {
 		if (this.disposed) return;
 		for (const item of this.items$.peek()) item.dispose?.();
 		this.items$.set([]);
+		this.structurallyDirty$.set(true);
 	}
 	/**
 	* Internal — used by `Form.resetWithInitial` to re-anchor the array's
@@ -2581,6 +3503,7 @@ var FieldArrayImpl = class {
 	*/
 	replaceInitialItems(items) {
 		this.initialItems = [...items];
+		this.structurallyDirty$.set(false);
 	}
 	reset() {
 		if (this.disposed) return;
@@ -2588,6 +3511,8 @@ var FieldArrayImpl = class {
 			this.clear();
 			for (const ini of this.initialItems) this.add(ini);
 			this.topLevelErrors$.set([]);
+			this.parentFormErrors$.set([]);
+			this.structurallyDirty$.set(false);
 		});
 	}
 	markAllTouched() {
@@ -2625,42 +3550,45 @@ var FieldArrayImpl = class {
 		const abort = new AbortController();
 		this.currentValidatorAbort = abort;
 		const myId = ++this.currentValidatorRun;
-		const syncErrors = [];
+		const syncIssues = [];
 		const asyncPromises = [];
 		for (const v of this.validators) try {
 			const r = v(value, abort.signal);
 			if (r instanceof Promise) asyncPromises.push(r);
-			else if (r != null) syncErrors.push(r);
+			else appendIssues(syncIssues, r);
 		} catch (err) {
 			try {
 				this.onValidatorError?.(err);
 			} catch {}
-			syncErrors.push(err instanceof Error ? err.message : String(err));
+			syncIssues.push({
+				path: [],
+				message: "Validation failed"
+			});
 		}
-		if (syncErrors.length > 0) {
+		if (syncIssues.length > 0) {
 			batch(() => {
-				this.topLevelErrors$.set(syncErrors);
+				this.lastFormErrorTargets = routeFormIssues(this, syncIssues, this.topLevelErrors$, this.lastFormErrorTargets);
 				this.topLevelValidating$.set(false);
 			});
 			return;
 		}
 		if (asyncPromises.length === 0) {
 			batch(() => {
-				this.topLevelErrors$.set([]);
+				this.lastFormErrorTargets = routeFormIssues(this, [], this.topLevelErrors$, this.lastFormErrorTargets);
 				this.topLevelValidating$.set(false);
 			});
 			return;
 		}
 		batch(() => {
-			this.topLevelErrors$.set([]);
+			this.lastFormErrorTargets = routeFormIssues(this, [], this.topLevelErrors$, this.lastFormErrorTargets);
 			this.topLevelValidating$.set(true);
 		});
 		Promise.allSettled(asyncPromises).then((results) => {
 			if (myId !== this.currentValidatorRun || this.disposed) return;
-			const errs = [];
-			for (const r of results) if (r.status === "fulfilled" && r.value != null) errs.push(r.value);
+			const issues = [];
+			for (const r of results) if (r.status === "fulfilled") appendIssues(issues, r.value);
 			batch(() => {
-				this.topLevelErrors$.set(errs);
+				this.lastFormErrorTargets = routeFormIssues(this, issues, this.topLevelErrors$, this.lastFormErrorTargets);
 				this.topLevelValidating$.set(false);
 			});
 		});
@@ -2797,6 +3725,9 @@ var LocalCacheImpl = class {
 	get hasPendingMutations() {
 		return this.entry.hasPendingMutations;
 	}
+	get isPaused() {
+		return this.entry.isPaused;
+	}
 	refetch = () => this.entry.refetch();
 	reset = () => this.entry.reset();
 	firstValue = () => this.entry.firstValue();
@@ -2872,6 +3803,7 @@ var MutationImpl = class {
 	data = signal(void 0);
 	error = signal(void 0);
 	isPending = signal(false);
+	status = signal("idle");
 	lastVariables = signal(void 0);
 	inflight = /* @__PURE__ */ new Set();
 	serialQueue = [];
@@ -2940,10 +3872,11 @@ var MutationImpl = class {
 			const raw = this.spec.onMutate?.(vars) ?? void 0;
 			snapshot = raw === void 0 ? void 0 : this.wrapSnapshot(raw);
 		} catch (err) {
-			dispatchError(this.onError, err, {
-				kind: "mutation",
-				controllerPath: this.controllerPath
-			});
+			this.error.set(err);
+			this.status.set("error");
+			this.safeCall(() => this.spec.onError?.(err, vars, void 0), "mutation");
+			this.safeCall(() => this.spec.onSettled?.(void 0, err, vars), "mutation");
+			throw err;
 		}
 		const handle = {
 			abort,
@@ -2953,6 +3886,7 @@ var MutationImpl = class {
 		this.inflightCounter?.update((n) => n + 1);
 		batch(() => {
 			this.isPending.set(true);
+			this.status.set("pending");
 			this.lastVariables.set(vars);
 		});
 		const runId = this.isPersistable ? makeRunId() : "";
@@ -2984,6 +3918,7 @@ var MutationImpl = class {
 			batch(() => {
 				this.data.set(result);
 				this.error.set(void 0);
+				this.status.set("success");
 			});
 			this.safeCall(() => this.spec.onSuccess?.(result, vars), "mutation");
 			snapshot?.finalize();
@@ -3005,6 +3940,7 @@ var MutationImpl = class {
 				throw err;
 			}
 			this.error.set(err);
+			this.status.set("error");
 			this.safeCall(() => this.spec.onError?.(err, vars, snapshot), "mutation");
 			snapshot?.rollback();
 			this.safeCall(() => this.spec.onSettled?.(void 0, err, vars), "mutation");
@@ -3084,6 +4020,7 @@ var MutationImpl = class {
 			this.error.set(void 0);
 			this.lastVariables.set(void 0);
 			this.isPending.set(false);
+			this.status.set("idle");
 		});
 	}
 	dispose() {
@@ -3157,6 +4094,7 @@ var SubscriptionImpl = class {
 	isStale;
 	lastUpdatedAt;
 	hasPendingMutations;
+	isPaused;
 	constructor(keepPreviousData, select) {
 		this.keepPreviousData = keepPreviousData;
 		this.select = select;
@@ -3181,6 +4119,7 @@ var SubscriptionImpl = class {
 		this.isStale = computed(() => this.current$.value?.entry.isStale.value ?? true);
 		this.lastUpdatedAt = computed(() => this.current$.value?.entry.lastUpdatedAt.value);
 		this.hasPendingMutations = computed(() => this.current$.value?.entry.hasPendingMutations.value ?? false);
+		this.isPaused = computed(() => this.current$.value?.entry.isPaused.value ?? false);
 	}
 	attach(entry) {
 		const prev = this.current$.peek();
@@ -3197,11 +4136,17 @@ var SubscriptionImpl = class {
 	refetch = () => {
 		const cur = this.current$.peek();
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
-		return cur.entry.refetch().then((v) => this.project(v));
+		return cur.entry.refetch().then((v) => this.project(v), (err) => {
+			if (isAbortError(err)) return this.firstValue();
+			throw err;
+		});
 	};
 	reset = () => {
 		this.current$.peek()?.entry.reset();
 	};
+	cancel = () => {
+		this.current$.peek()?.entry.cancel();
+	};
 	firstValue = () => {
 		const cur = this.current$.peek();
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
@@ -3229,8 +4174,10 @@ function createUse(client, query, keyOrOptions) {
 	let currentEntry = null;
 	let suspended = false;
 	const effectDispose = effect(() => {
+		const isEnabled = enabledFn ? enabledFn() : true;
+		const args = isEnabled ? keyFn ? keyFn() : [] : void 0;
 		if (suspended) return;
-		if (!(enabledFn ? enabledFn() : true)) {
+		if (!isEnabled) {
 			untracked(() => {
 				if (currentEntry) {
 					currentEntry.release();
@@ -3240,7 +4187,6 @@ function createUse(client, query, keyOrOptions) {
 			});
 			return;
 		}
-		const args = keyFn ? keyFn() : [];
 		untracked(() => {
 			const entry = client.bindEntry(query, args);
 			if (currentEntry === entry) return;
@@ -3301,6 +4247,7 @@ var InfiniteSubscriptionImpl = class {
 	isStale;
 	lastUpdatedAt;
 	hasPendingMutations;
+	isPaused;
 	hasNextPage;
 	hasPreviousPage;
 	isFetchingNextPage;
@@ -3337,6 +4284,7 @@ var InfiniteSubscriptionImpl = class {
 		this.isStale = computed(() => this.current$.value?.entry.isStale.value ?? true);
 		this.lastUpdatedAt = computed(() => this.current$.value?.entry.lastUpdatedAt.value);
 		this.hasPendingMutations = computed(() => this.current$.value?.entry.hasPendingMutations.value ?? false);
+		this.isPaused = computed(() => this.current$.value?.entry.isPaused.value ?? false);
 		this.hasNextPage = computed(() => this.current$.value?.entry.hasNextPage.value ?? false);
 		this.hasPreviousPage = computed(() => this.current$.value?.entry.hasPreviousPage.value ?? false);
 		this.isFetchingNextPage = computed(() => this.current$.value?.entry.isFetchingNextPage.value ?? false);
@@ -3357,11 +4305,17 @@ var InfiniteSubscriptionImpl = class {
 	refetch = () => {
 		const cur = this.current$.peek();
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
-		return cur.entry.refetch().then(() => cur.entry.pages.peek());
+		return cur.entry.refetch().then(() => cur.entry.pages.peek(), (err) => {
+			if (isAbortError(err)) return this.firstValue();
+			throw err;
+		});
 	};
 	reset = () => {
 		this.current$.peek()?.entry.reset();
 	};
+	cancel = () => {
+		this.current$.peek()?.entry.cancel();
+	};
 	firstValue = () => {
 		const cur = this.current$.peek();
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
@@ -3387,8 +4341,10 @@ function createInfiniteUse(client, query, keyOrOptions) {
 	let currentEntry = null;
 	let suspended = false;
 	const effectDispose = effect(() => {
+		const isEnabled = enabledFn ? enabledFn() : true;
+		const args = isEnabled ? keyFn ? keyFn() : [] : void 0;
 		if (suspended) return;
-		if (!(enabledFn ? enabledFn() : true)) {
+		if (!isEnabled) {
 			untracked(() => {
 				if (currentEntry) {
 					currentEntry.release();
@@ -3398,7 +4354,6 @@ function createInfiniteUse(client, query, keyOrOptions) {
 			});
 			return;
 		}
-		const args = keyFn ? keyFn() : [];
 		untracked(() => {
 			const entry = client.bindInfiniteEntry(query, args);
 			if (currentEntry === entry) return;
@@ -3447,17 +4402,89 @@ function createInfiniteUse(client, query, keyOrOptions) {
 }
 //#endregion
 //#region src/controller/instance.ts
+/**
+* Append-and-unlink container for `LifecycleEntry`s. Replaces the historical
+* `LifecycleEntry[]` to make per-entry removal O(1) — important for
+* controllers that churn entries (`ctx.collection` reconcile, `lazyChild`
+* loop, `attach` short-lived children).
+*
+* Iteration order is insertion order for `forward()` and reverse-insertion
+* for `reverse()`. Iteration is safe against `push` during traversal (the
+* generator captures `next`/`prev` *before* yielding) but not against
+* unlinking the current node from inside the visitor — visitors must not
+* call `unlink` on the entry they're currently inspecting.
+*/
+var LifecycleList = class {
+	head = null;
+	tail = null;
+	_size = 0;
+	get size() {
+		return this._size;
+	}
+	push(entry) {
+		const node = {
+			entry,
+			prev: this.tail,
+			next: null,
+			unlinked: false
+		};
+		if (this.tail !== null) this.tail.next = node;
+		else this.head = node;
+		this.tail = node;
+		this._size += 1;
+		return node;
+	}
+	unlink(node) {
+		if (node.unlinked) return;
+		node.unlinked = true;
+		if (node.prev !== null) node.prev.next = node.next;
+		else this.head = node.next;
+		if (node.next !== null) node.next.prev = node.prev;
+		else this.tail = node.prev;
+		this._size -= 1;
+	}
+	clear() {
+		this.head = null;
+		this.tail = null;
+		this._size = 0;
+	}
+	/** Yield entries in insertion order. */
+	*forward() {
+		let n = this.head;
+		while (n !== null) {
+			const next = n.next;
+			yield n.entry;
+			n = next;
+		}
+	}
+	/** Yield entries in reverse-insertion order — used by dispose / suspend. */
+	*reverse() {
+		let n = this.tail;
+		while (n !== null) {
+			const prev = n.prev;
+			yield n.entry;
+			n = prev;
+		}
+	}
+};
 var ControllerInstance = class ControllerInstance {
 	path;
 	deps;
 	state = "constructing";
-	entries = [];
+	entries = new LifecycleList();
 	rootShared;
 	parent;
 	childCounter = 0;
 	/** Scope values provided on this instance, keyed by `Scope.__id`. */
 	scopes = null;
 	/**
+	* Memoized result of `ctx.inject(scope)` per scope id, stamped with the
+	* `scopesVersion` the lookup observed. A bump invalidates every cache
+	* entry implicitly — the next `inject(scope)` finds a stale version
+	* stamp and re-walks. Provide is rare; reads dominate.
+	*/
+	injectCache = null;
+	/**
 	* Pre-seed scopes from outside the factory — used by `createRoot`'s
 	* `scopes:` option so an adapter (e.g. `@kontsedal/olas-router-tanstack`)
 	* can publish cross-cutting values without forcing the user to call
@@ -3492,33 +4519,31 @@ var ControllerInstance = class ControllerInstance {
 		return api;
 	}
 	rollbackPartialConstruction() {
-		for (let i = this.entries.length - 1; i >= 0; i--) {
-			const entry = this.entries[i];
-			if (!entry) continue;
-			try {
-				this.disposeEntry(entry);
-			} catch {}
+		for (const entry of this.entries.reverse()) try {
+			this.disposeEntry(entry);
+		} catch (err) {
+			dispatchError(this.rootShared.onError, err, {
+				kind: "effect",
+				controllerPath: this.path
+			});
 		}
-		this.entries.length = 0;
+		this.entries.clear();
 		this.state = "disposed";
 	}
 	dispose() {
 		if (this.state === "disposed") return;
 		this.state = "disposed";
-		for (let i = this.entries.length - 1; i >= 0; i--) {
-			const entry = this.entries[i];
-			if (!entry) continue;
-			try {
-				this.disposeEntry(entry);
-			} catch (err) {
-				dispatchError(this.rootShared.onError, err, {
-					kind: "effect",
-					controllerPath: this.path
-				});
-			}
+		for (const entry of this.entries.reverse()) try {
+			this.disposeEntry(entry);
+		} catch (err) {
+			dispatchError(this.rootShared.onError, err, {
+				kind: "effect",
+				controllerPath: this.path
+			});
 		}
-		this.entries.length = 0;
+		this.entries.clear();
 		this.scopes = null;
+		this.injectCache = null;
 	}
 	disposeEntry(entry) {
 		switch (entry.kind) {
@@ -3545,49 +4570,49 @@ var ControllerInstance = class ControllerInstance {
 			case "onResume": break;
 		}
 	}
+	isSuspended() {
+		return this.state === "suspended";
+	}
 	suspend() {
 		if (this.state !== "active") return;
 		this.state = "suspended";
-		for (let i = this.entries.length - 1; i >= 0; i--) {
-			const entry = this.entries[i];
-			if (!entry) continue;
-			try {
-				switch (entry.kind) {
-					case "effect":
-						entry.dispose?.();
-						entry.dispose = null;
-						break;
-					case "subscription-cache":
-						entry.suspend();
-						break;
-					case "child":
-						entry.instance.suspend();
-						break;
-					case "onSuspend":
-						entry.fn();
-						break;
-					default: break;
-				}
-			} catch (err) {
-				dispatchError(this.rootShared.onError, err, {
-					kind: "effect",
-					controllerPath: this.path
-				});
+		for (const entry of this.entries.reverse()) try {
+			switch (entry.kind) {
+				case "effect":
+					entry.dispose?.();
+					entry.dispose = null;
+					break;
+				case "subscription-cache":
+					entry.suspend();
+					break;
+				case "child":
+					entry.instance.suspend();
+					break;
+				case "onSuspend":
+					entry.fn();
+					break;
+				default: break;
 			}
+		} catch (err) {
+			dispatchError(this.rootShared.onError, err, {
+				kind: "effect",
+				controllerPath: this.path
+			});
 		}
 	}
 	resume() {
 		if (this.state !== "suspended") return;
 		this.state = "active";
-		for (const entry of this.entries) try {
+		for (const entry of this.entries.forward()) try {
 			switch (entry.kind) {
 				case "effect":
-					entry.dispose = effect(entry.factory);
+					if (entry.dispose === null) entry.dispose = effect(entry.factory);
 					break;
 				case "subscription-cache":
 					entry.resume();
 					break;
 				case "child":
+					if (entry.explicitlySuspended) break;
 					entry.instance.resume();
 					break;
 				case "onResume":
@@ -3604,12 +4629,15 @@ var ControllerInstance = class ControllerInstance {
 	}
 	buildCtx() {
 		const self = this;
+		const assertLive = (method) => {
+			if (self.isTerminal()) throw new Error(`[olas] ctx.${method}() called after the controller was disposed`);
+		};
 		return {
 			get deps() {
 				return self.deps;
 			},
 			effect(fn) {
-				if (self.isTerminal()) return;
+				assertLive("effect");
 				const entry = {
 					kind: "effect",
 					factory: () => fn(),
@@ -3617,7 +4645,18 @@ var ControllerInstance = class ControllerInstance {
 				};
 				const wrapped = () => {
 					try {
-						return fn();
+						const cleanup = fn();
+						if (typeof cleanup === "function") return () => {
+							try {
+								cleanup();
+							} catch (err) {
+								dispatchError(self.rootShared.onError, err, {
+									kind: "effect",
+									controllerPath: self.path
+								});
+							}
+						};
+						return cleanup;
 					} catch (err) {
 						dispatchError(self.rootShared.onError, err, {
 							kind: "effect",
@@ -3631,6 +4670,7 @@ var ControllerInstance = class ControllerInstance {
 				self.entries.push(entry);
 			},
 			cache(fetcher, options) {
+				assertLive("cache");
 				const cache = createLocalCache(fetcher, options);
 				self.entries.push({
 					kind: "cleanup",
@@ -3639,6 +4679,7 @@ var ControllerInstance = class ControllerInstance {
 				return cache;
 			},
 			use(query, keyOrOptions) {
+				assertLive("use");
 				if (query.__olas === "infiniteQuery") {
 					const handle = createInfiniteUse(self.rootShared.queryClient, query, keyOrOptions);
 					self.entries.push({
@@ -3659,6 +4700,7 @@ var ControllerInstance = class ControllerInstance {
 				return handle.subscription;
 			},
 			mutation(spec) {
+				assertLive("mutation");
 				const queryClient = self.rootShared.queryClient;
 				const m = createMutation(spec, self.rootShared.onError, self.path, queryClient.mutationsInflight$, self.rootShared.devtools, spec.persist === true ? {
 					emitEnqueue: (ev) => queryClient.emitMutationEnqueue(ev),
@@ -3671,6 +4713,7 @@ var ControllerInstance = class ControllerInstance {
 				return m;
 			},
 			emitter() {
+				assertLive("emitter");
 				const e = createEmitter({ onError: (err) => {
 					dispatchError(self.rootShared.onError, err, {
 						kind: "emitter",
@@ -3683,13 +4726,19 @@ var ControllerInstance = class ControllerInstance {
 				});
 				return e;
 			},
-			field(initial, validators) {
-				const f = createField(initial, validators, { onValidatorError: (err) => {
-					dispatchError(self.rootShared.onError, err, {
-						kind: "effect",
-						controllerPath: self.path
-					});
-				} });
+			signal,
+			computed,
+			field(initial, validators, options) {
+				assertLive("field");
+				const f = createField(initial, validators, {
+					onValidatorError: (err) => {
+						dispatchError(self.rootShared.onError, err, {
+							kind: "effect",
+							controllerPath: self.path
+						});
+					},
+					validateOn: options?.validateOn
+				});
 				self.entries.push({
 					kind: "cleanup",
 					dispose: () => f.dispose()
@@ -3702,6 +4751,7 @@ var ControllerInstance = class ControllerInstance {
 				return f;
 			},
 			form(schema, options) {
+				assertLive("form");
 				const reporter = (err) => {
 					dispatchError(self.rootShared.onError, err, {
 						kind: "effect",
@@ -3722,6 +4772,7 @@ var ControllerInstance = class ControllerInstance {
 				return f;
 			},
 			fieldArray(itemFactory, options) {
+				assertLive("fieldArray");
 				const reporter = (err) => {
 					dispatchError(self.rootShared.onError, err, {
 						kind: "effect",
@@ -3744,19 +4795,44 @@ var ControllerInstance = class ControllerInstance {
 			provide(scope, value) {
 				if (self.scopes === null) self.scopes = /* @__PURE__ */ new Map();
 				self.scopes.set(scope.__id, value);
+				self.rootShared.scopesVersion.value += 1;
 			},
 			inject(scope) {
+				const version = self.rootShared.scopesVersion.value;
+				const cache = self.injectCache;
+				if (cache !== null) {
+					const cached = cache.get(scope.__id);
+					if (cached !== void 0 && cached.version === version) return cached.value;
+				}
+				const ensureMemo = () => {
+					if (self.injectCache === null) self.injectCache = /* @__PURE__ */ new Map();
+					return self.injectCache;
+				};
 				let node = self;
 				while (node !== null) {
 					const map = node.scopes;
-					if (map?.has(scope.__id)) return map.get(scope.__id);
+					if (map?.has(scope.__id)) {
+						const value = map.get(scope.__id);
+						ensureMemo().set(scope.__id, {
+							value,
+							version
+						});
+						return value;
+					}
 					node = node.parent;
 				}
-				if (scope.hasDefault) return scope.default;
+				if (scope.hasDefault) {
+					ensureMemo().set(scope.__id, {
+						value: scope.default,
+						version
+					});
+					return scope.default;
+				}
 				const label = scope.name ?? scope.__id.description ?? "unnamed";
 				throw new Error(`[olas] ctx.inject(): no provider for scope '${label}' and no default. Provide it on an ancestor via ctx.provide(${label}, ...) or pass a default to defineScope.`);
 			},
 			on(emitter, handler) {
+				assertLive("on");
 				const wrapped = (value) => {
 					try {
 						handler(value);
@@ -3774,6 +4850,7 @@ var ControllerInstance = class ControllerInstance {
 				});
 			},
 			child(def, props, options) {
+				assertLive("child");
 				const segment = self.makeChildSegment(getFactory(def), getName(def));
 				const override = options?.deps;
 				const childDeps = override !== void 0 ? {
@@ -3789,6 +4866,7 @@ var ControllerInstance = class ControllerInstance {
 				return api;
 			},
 			attach(def, props, options) {
+				assertLive("attach");
 				const segment = self.makeChildSegment(getFactory(def), getName(def));
 				const override = options?.deps;
 				const childDeps = override !== void 0 ? {
@@ -3799,17 +4877,17 @@ var ControllerInstance = class ControllerInstance {
 				const api = childInstance.construct(getFactory(def), props);
 				const entry = {
 					kind: "child",
-					instance: childInstance
+					instance: childInstance,
+					explicitlySuspended: false
 				};
-				self.entries.push(entry);
+				const node = self.entries.push(entry);
 				let disposed = false;
 				return {
 					api,
 					dispose: () => {
 						if (disposed) return;
 						disposed = true;
-						const idx = self.entries.indexOf(entry);
-						if (idx >= 0) self.entries.splice(idx, 1);
+						self.entries.unlink(node);
 						try {
 							childInstance.dispose();
 						} catch (err) {
@@ -3821,6 +4899,7 @@ var ControllerInstance = class ControllerInstance {
 					},
 					suspend: () => {
 						if (disposed) return;
+						entry.explicitlySuspended = true;
 						try {
 							childInstance.suspend();
 						} catch (err) {
@@ -3832,6 +4911,8 @@ var ControllerInstance = class ControllerInstance {
 					},
 					resume: () => {
 						if (disposed) return;
+						entry.explicitlySuspended = false;
+						if (self.isSuspended()) return;
 						try {
 							childInstance.resume();
 						} catch (err) {
@@ -3844,6 +4925,7 @@ var ControllerInstance = class ControllerInstance {
 				};
 			},
 			session(def, props, options) {
+				assertLive("session");
 				const segment = self.makeChildSegment(getFactory(def), getName(def));
 				const override = options?.deps;
 				const childDeps = override !== void 0 ? {
@@ -3856,13 +4938,12 @@ var ControllerInstance = class ControllerInstance {
 					kind: "child",
 					instance: childInstance
 				};
-				self.entries.push(entry);
+				const node = self.entries.push(entry);
 				let disposed = false;
 				const dispose = () => {
 					if (disposed) return;
 					disposed = true;
-					const idx = self.entries.indexOf(entry);
-					if (idx >= 0) self.entries.splice(idx, 1);
+					self.entries.unlink(node);
 					try {
 						childInstance.dispose();
 					} catch (err) {
@@ -3875,6 +4956,7 @@ var ControllerInstance = class ControllerInstance {
 				return [api, dispose];
 			},
 			collection(options) {
+				assertLive("collection");
 				const childMap = /* @__PURE__ */ new Map();
 				const items$ = signal([]);
 				const size$ = computed(() => items$.value.length);
@@ -3915,8 +4997,7 @@ var ControllerInstance = class ControllerInstance {
 					const info = childMap.get(key);
 					if (info === void 0) return;
 					childMap.delete(key);
-					const idx = self.entries.indexOf(info.entry);
-					if (idx >= 0) self.entries.splice(idx, 1);
+					self.entries.unlink(info.node);
 					try {
 						info.instance.dispose();
 					} catch (err) {
@@ -3928,60 +5009,63 @@ var ControllerInstance = class ControllerInstance {
 				};
 				const reconcile = () => {
 					const source = options.source.value;
-					const itemByKey = /* @__PURE__ */ new Map();
-					for (const item of source) {
-						const key = options.keyOf(item);
-						if (!itemByKey.has(key)) itemByKey.set(key, item);
-					}
-					for (const key of [...childMap.keys()]) if (!itemByKey.has(key)) removeKey(key);
-					for (const [key, item] of itemByKey) {
-						const existing = childMap.get(key);
-						if (existing !== void 0) {
-							if (isFactoryForm) {
-								if (options.factory(item).controller !== existing.def) {
-									removeKey(key);
-									const built = buildChild(item);
-									if (built !== null) {
-										const entry = {
-											kind: "child",
-											instance: built.instance
-										};
-										self.entries.push(entry);
-										childMap.set(key, {
-											...built,
-											entry
-										});
+					untracked(() => {
+						const itemByKey = /* @__PURE__ */ new Map();
+						for (const item of source) {
+							const key = options.keyOf(item);
+							if (itemByKey.has(key)) continue;
+							itemByKey.set(key, item);
+						}
+						for (const key of [...childMap.keys()]) if (!itemByKey.has(key)) removeKey(key);
+						for (const [key, item] of itemByKey) {
+							const existing = childMap.get(key);
+							if (existing !== void 0) {
+								if (isFactoryForm) {
+									if (options.factory(item).controller !== existing.def) {
+										removeKey(key);
+										const built = buildChild(item);
+										if (built !== null) {
+											const entry = {
+												kind: "child",
+												instance: built.instance
+											};
+											const node = self.entries.push(entry);
+											childMap.set(key, {
+												...built,
+												node
+											});
+										}
 									}
 								}
+								continue;
+							}
+							const built = buildChild(item);
+							if (built !== null) {
+								const entry = {
+									kind: "child",
+									instance: built.instance
+								};
+								const node = self.entries.push(entry);
+								childMap.set(key, {
+									...built,
+									node
+								});
 							}
-							continue;
 						}
-						const built = buildChild(item);
-						if (built !== null) {
-							const entry = {
-								kind: "child",
-								instance: built.instance
-							};
-							self.entries.push(entry);
-							childMap.set(key, {
-								...built,
-								entry
+						const next = [];
+						const seen = /* @__PURE__ */ new Set();
+						for (const item of source) {
+							const key = options.keyOf(item);
+							if (seen.has(key)) continue;
+							seen.add(key);
+							const info = childMap.get(key);
+							if (info !== void 0) next.push({
+								key,
+								api: info.api
 							});
 						}
-					}
-					const next = [];
-					const seen = /* @__PURE__ */ new Set();
-					for (const item of source) {
-						const key = options.keyOf(item);
-						if (seen.has(key)) continue;
-						seen.add(key);
-						const info = childMap.get(key);
-						if (info !== void 0) next.push({
-							key,
-							api: info.api
-						});
-					}
-					items$.set(next);
+						items$.set(next);
+					});
 				};
 				const wrapped = () => {
 					try {
@@ -4001,27 +5085,45 @@ var ControllerInstance = class ControllerInstance {
 				if (self.state !== "suspended") effectEntry.dispose = effect(wrapped);
 				self.entries.push(effectEntry);
 				return {
-					items: items$,
-					size: size$,
+					items: readOnly(items$),
+					size: readOnly(size$),
 					get: (key) => childMap.get(key)?.api,
-					has: (key) => childMap.has(key)
+					has: (key) => childMap.has(key),
+					suspendItem: (key) => {
+						const info = childMap.get(key);
+						if (info === void 0) return;
+						if (info.node.entry.kind === "child") info.node.entry.explicitlySuspended = true;
+						info.instance.suspend();
+					},
+					resumeItem: (key) => {
+						const info = childMap.get(key);
+						if (info === void 0) return;
+						if (info.node.entry.kind === "child") info.node.entry.explicitlySuspended = false;
+						if (self.isSuspended()) return;
+						info.instance.resume();
+					},
+					isItemSuspended: (key) => {
+						const info = childMap.get(key);
+						if (info === void 0) return false;
+						return info.instance.isSuspended();
+					}
 				};
 			},
 			lazyChild(loader, props, options) {
+				assertLive("lazyChild");
 				const status$ = signal("idle");
 				const api$ = signal(void 0);
 				const error$ = signal(void 0);
 				let childInstance = null;
-				let childEntry = null;
+				let childNode = null;
 				let pendingLoad = null;
 				let disposed = false;
-				const flagEntry = {
+				const flagNode = self.entries.push({
 					kind: "onDispose",
 					fn: () => {
 						disposed = true;
 					}
-				};
-				self.entries.push(flagEntry);
+				});
 				const handleFailure = (err) => {
 					status$.set("error");
 					error$.set(err);
@@ -4034,7 +5136,7 @@ var ControllerInstance = class ControllerInstance {
 					if (disposed) return Promise.reject(/* @__PURE__ */ new Error("[olas] ctx.lazyChild: cannot load after dispose"));
 					if (pendingLoad !== null) return pendingLoad;
 					status$.set("loading");
-					pendingLoad = loader().then((def) => {
+					const attempt = loader().then((def) => {
 						if (disposed) throw new Error("[olas] ctx.lazyChild: disposed during load");
 						const segment = self.makeChildSegment(getFactory(def), getName(def));
 						const childDeps = options?.deps !== void 0 ? {
@@ -4045,11 +5147,10 @@ var ControllerInstance = class ControllerInstance {
 						try {
 							const api = instance.construct(getFactory(def), props);
 							childInstance = instance;
-							childEntry = {
+							childNode = self.entries.push({
 								kind: "child",
 								instance
-							};
-							self.entries.push(childEntry);
+							});
 							api$.set(api);
 							status$.set("ready");
 							return api;
@@ -4062,14 +5163,17 @@ var ControllerInstance = class ControllerInstance {
 						handleFailure(err);
 						throw err;
 					});
-					return pendingLoad;
+					pendingLoad = attempt;
+					attempt.catch(() => {
+						if (pendingLoad === attempt) pendingLoad = null;
+					});
+					return attempt;
 				};
 				const dispose = () => {
 					if (disposed) return;
 					disposed = true;
-					if (childEntry !== null && childInstance !== null) {
-						const idx = self.entries.indexOf(childEntry);
-						if (idx >= 0) self.entries.splice(idx, 1);
+					if (childNode !== null && childInstance !== null) {
+						self.entries.unlink(childNode);
 						try {
 							childInstance.dispose();
 						} catch (err) {
@@ -4079,20 +5183,20 @@ var ControllerInstance = class ControllerInstance {
 							});
 						}
 						childInstance = null;
-						childEntry = null;
+						childNode = null;
 					}
-					const flagIdx = self.entries.indexOf(flagEntry);
-					if (flagIdx >= 0) self.entries.splice(flagIdx, 1);
+					self.entries.unlink(flagNode);
 				};
 				return {
-					status: status$,
-					api: api$,
-					error: error$,
+					status: readOnly(status$),
+					api: readOnly(api$),
+					error: readOnly(error$),
 					load,
 					dispose
 				};
 			},
 			onDispose(fn) {
+				assertLive("onDispose");
 				self.entries.push({
 					kind: "onDispose",
 					fn: () => {
@@ -4108,6 +5212,7 @@ var ControllerInstance = class ControllerInstance {
 				});
 			},
 			onSuspend(fn) {
+				assertLive("onSuspend");
 				self.entries.push({
 					kind: "onSuspend",
 					fn: () => {
@@ -4123,6 +5228,7 @@ var ControllerInstance = class ControllerInstance {
 				});
 			},
 			onResume(fn) {
+				assertLive("onResume");
 				self.entries.push({
 					kind: "onResume",
 					fn: () => {
@@ -4156,6 +5262,7 @@ const ROOT_METHODS = [
 	"resume",
 	"dehydrate",
 	"waitForIdle",
+	"applyDehydratedEntry",
 	"__debug"
 ];
 /**
@@ -4178,7 +5285,8 @@ function createRootWithProps(def, props, options) {
 	const instance = new ControllerInstance(null, {
 		devtools,
 		onError: options.onError,
-		queryClient
+		queryClient,
+		scopesVersion: { value: 0 }
 	}, "root", options.deps);
 	if (options.scopes !== void 0 && options.scopes.length > 0) instance.seedScopes(options.scopes);
 	let api;
@@ -4188,8 +5296,15 @@ function createRootWithProps(def, props, options) {
 		queryClient.dispose();
 		throw err;
 	}
-	if (typeof api !== "object" || api === null) return attachRootControls({ value: api }, instance, devtools, queryClient);
-	return attachRootControls(api, instance, devtools, queryClient);
+	let target = api;
+	if (typeof api !== "object" || api === null) target = { value: api };
+	try {
+		return attachRootControls(target, instance, devtools, queryClient);
+	} catch (err) {
+		instance.dispose();
+		queryClient.dispose();
+		throw err;
+	}
 }
 function attachRootControls(api, instance, devtools, queryClient) {
 	let suspendTimer = null;
@@ -4225,36 +5340,39 @@ function attachRootControls(api, instance, devtools, queryClient) {
 		queryEntries: () => queryClient.queryEntriesSnapshot()
 	};
 	const target = api;
-	for (const method of ROOT_METHODS) if (Object.hasOwn(target, method)) throw new Error(`[olas] Root controller api defines '${method}' which conflicts with the root controls.`);
+	for (const method of ROOT_METHODS) if (method in target) throw new Error(`[olas] Root controller api defines '${method}' which conflicts with the root controls.`);
+	const lock = {
+		enumerable: false,
+		writable: false,
+		configurable: false
+	};
 	Object.defineProperty(target, "dispose", {
 		value: dispose,
-		enumerable: false,
-		configurable: true
+		...lock
 	});
 	Object.defineProperty(target, "suspend", {
 		value: suspend,
-		enumerable: false,
-		configurable: true
+		...lock
 	});
 	Object.defineProperty(target, "resume", {
 		value: resume,
-		enumerable: false,
-		configurable: true
+		...lock
 	});
 	Object.defineProperty(target, "__debug", {
 		value: debug,
-		enumerable: false,
-		configurable: true
+		...lock
 	});
 	Object.defineProperty(target, "dehydrate", {
 		value: () => queryClient.dehydrate(),
-		enumerable: false,
-		configurable: true
+		...lock
 	});
 	Object.defineProperty(target, "waitForIdle", {
 		value: () => queryClient.waitForIdle(),
-		enumerable: false,
-		configurable: true
+		...lock
+	});
+	Object.defineProperty(target, "applyDehydratedEntry", {
+		value: (queryId, keyArgs, data, lastUpdatedAt) => queryClient.applyDehydratedEntry(queryId, keyArgs, data, lastUpdatedAt),
+		...lock
 	});
 	return api;
 }
@@ -4344,6 +5462,12 @@ Object.defineProperty(exports, "lookupRegisteredQuery", {
 		return lookupRegisteredQuery;
 	}
 });
+Object.defineProperty(exports, "readOnly", {
+	enumerable: true,
+	get: function() {
+		return readOnly;
+	}
+});
 Object.defineProperty(exports, "registerQueryById", {
 	enumerable: true,
 	get: function() {
@@ -4369,4 +5493,4 @@ Object.defineProperty(exports, "untracked", {
 	}
 });
 
-//# sourceMappingURL=root-CFgYhBd-.cjs.map
+//# sourceMappingURL=root-CPSL5kpR.cjs.map