@rangojs/router 0.15.1 → 0.17.0

package/src/browser/scroll-restoration.ts

@@ -72,6 +72,13 @@ type GetScrollKeyFunction = (location: {
 
 let customGetKey: GetScrollKeyFunction | null = null;
 
+/**
+ * Scroll key of the entry on screen. At popstate history.state already belongs
+ * to the destination, so this is the only way to save the page being left
+ * under its own key (see handleTraversalStart).
+ */
+let displayedKey: string | null = null;
+
 /**
  * Generate a unique key for the current history entry.
  * Uses history.state.key if available, otherwise generates and stores a new one.
@@ -138,7 +145,7 @@ export function initScrollRestoration(options?: {
   }
 
   // Ensure current history entry has a key
-  getHistoryStateKey();
+  trackDisplayedEntry();
 
   // Save scroll positions on pagehide (before leaving/refreshing)
   const handlePageHide = () => {
@@ -148,7 +155,14 @@ export function initScrollRestoration(options?: {
     window.history.scrollRestoration = "auto";
   };
 
+  // A bfcache restore keeps the "auto" set on pagehide; take scroll back.
+  // Only here: without <Html.ScrollRestoration> the browser owns scroll.
+  const handlePageShow = (event: PageTransitionEvent) => {
+    if (event.persisted) window.history.scrollRestoration = "manual";
+  };
+
   window.addEventListener("pagehide", handlePageHide);
+  window.addEventListener("pageshow", handlePageShow);
 
   if (IS_BROWSER_DEBUG) {
     debugLog(
@@ -160,10 +174,12 @@ export function initScrollRestoration(options?: {
   return () => {
     cancelScrollRestorationPolling();
     window.removeEventListener("pagehide", handlePageHide);
+    window.removeEventListener("pageshow", handlePageShow);
     window.history.scrollRestoration = "auto";
     initialized = false;
     savedScrollPositions = {};
     scrollKeyOrder = [];
+    displayedKey = null;
   };
 }
 
@@ -172,8 +188,10 @@ export function initScrollRestoration(options?: {
  * Maintains bounded size by evicting oldest entries when the limit is exceeded.
  */
 export function saveCurrentScrollPosition(): void {
-  const key = getScrollKey();
+  saveScrollPosition(getScrollKey(), window.scrollY);
+}
 
+function saveScrollPosition(key: string, y: number): void {
   // If this key already exists, remove it from its current position
   // in the order array so it can be re-appended at the end (most recent).
   const existingIndex = scrollKeyOrder.indexOf(key);
@@ -181,7 +199,7 @@ export function saveCurrentScrollPosition(): void {
     scrollKeyOrder.splice(existingIndex, 1);
   }
 
-  savedScrollPositions[key] = window.scrollY;
+  savedScrollPositions[key] = y;
   scrollKeyOrder.push(key);
 
   // Evict oldest entries if we exceed the limit
@@ -354,6 +372,23 @@ export function handleNavigationStart(): void {
   saveCurrentScrollPosition();
 }
 
+/**
+ * Handle scroll for a back/forward traversal, at popstate before anything
+ * renders: save the page being left under ITS key (history has already moved,
+ * so saveCurrentScrollPosition would use the destination's key) and track the
+ * destination as the displayed entry.
+ */
+export function handleTraversalStart(): void {
+  if (!initialized) return;
+  const leftKey = displayedKey;
+  trackDisplayedEntry();
+  // A key shared with the destination (a getKey that collapses entries, e.g.
+  // by pathname) keeps the destination's saved position.
+  if (leftKey !== null && leftKey !== displayedKey) {
+    saveScrollPosition(leftKey, window.scrollY);
+  }
+}
+
 /**
  * Handle scroll after navigation completes.
  * @param options.restore - If true, restore saved position (for popstate)
@@ -376,10 +411,17 @@ export function handleNavigationEnd(options: {
   // But basic scroll-to-top and hash scrolling work without it — this
   // matters during cross-app navigation where ScrollRestoration unmounts
   // and remounts, creating a brief window where initialized is false.
-  if (restore && initialized) {
-    if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
+  if (restore) {
+    if (
+      initialized &&
+      restoreScrollPosition({ retryIfStreaming: true, isStreaming })
+    ) {
       return;
     }
+    // An "auto" entry (no <Html.ScrollRestoration>, or created before it mounted)
+    // is restored by the browser. A scrollTo here races that restore, and
+    // when it runs second the page lands at the top.
+    if (window.history.scrollRestoration === "auto") return;
     // Fall through to hash or top if no saved position
   }
 
@@ -410,5 +452,10 @@ export function handleNavigationEnd(options: {
  * Call this after changing history to ensure new entry has a key.
  */
 export function ensureHistoryKey(): void {
-  getHistoryStateKey();
+  trackDisplayedEntry();
+}
+
+/** Mints the current entry's key if missing and records it as displayed. */
+function trackDisplayedEntry(): void {
+  displayedKey = getScrollKey();
 }

package/src/cache/cache-exec-scope.ts

@@ -26,19 +26,52 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { _setCacheExecScopeProbe } from "./taint.js";
 
-const cacheExecStorage = new AsyncLocalStorage<true>();
+/**
+ * One "use cache" execution. Identity matters: the execution's handle capture
+ * (cache-runtime.ts) records only pushes from its own chain, including cached
+ * functions it calls (`parent` links them), not concurrent pushes into the
+ * same request store.
+ */
+export interface CacheExecScope {
+  readonly parent?: CacheExecScope;
+}
+
+const cacheExecStorage = new AsyncLocalStorage<CacheExecScope>();
 
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ * Pass `scope` (createCacheExecScope) to test membership with
+ * isInCacheExecChain.
  */
-export function runWithCacheExecScope<T>(fn: () => T): T {
-  return cacheExecStorage.run(true, fn);
+export function runWithCacheExecScope<T>(
+  fn: () => T,
+  scope: CacheExecScope = createCacheExecScope(),
+): T {
+  return cacheExecStorage.run(scope, fn);
+}
+
+/** A scope nested in the calling chain's current one, if any. */
+export function createCacheExecScope(): CacheExecScope {
+  return { parent: cacheExecStorage.getStore() };
 }
 
 /** True when the calling async chain is inside a "use cache" body. */
 export function isInsideCacheExecScope(): boolean {
-  return cacheExecStorage.getStore() === true;
+  return cacheExecStorage.getStore() !== undefined;
+}
+
+/** The calling chain's innermost "use cache" scope, if any. */
+export function getCacheExecScope(): CacheExecScope | undefined {
+  return cacheExecStorage.getStore();
+}
+
+/** True when the calling async chain runs inside `scope`, at any depth. */
+export function isInCacheExecChain(scope: CacheExecScope): boolean {
+  for (let s = cacheExecStorage.getStore(); s; s = s.parent) {
+    if (s === scope) return true;
+  }
+  return false;
 }
 
 // Wire the ambient ctx-method guards (assertNotInsideCacheExec in taint.ts)

package/src/cache/cache-key-utils.ts

@@ -20,12 +20,7 @@ import type { SearchParamsFilter } from "./search-params-filter.js";
  * slot; an allowlist keeps the router's own params out of the key while leaving
  * consumer `__` params intact.
  */
-const RESERVED_SEARCH_PARAMS = new Set([
-  "__no_cache",
-  "__rsc",
-  "__html",
-  "__prerender_collect",
-]);
+const RESERVED_SEARCH_PARAMS = new Set(["__no_cache", "__rsc", "__html"]);
 
 function isReservedSearchParam(key: string): boolean {
   return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);

package/src/cache/cache-runtime.ts

@@ -35,14 +35,14 @@ import {
 
 export { isCachedFunction };
 import { serializeResult, deserializeResult } from "./segment-codec.js";
-import { createHandleStore } from "../server/handle-store.js";
 import {
-  restoreHandles,
+  appendHandles,
   encodeHandles,
   decodeHandles,
 } from "./handle-snapshot.js";
-import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
-import { sortedSearchString } from "./cache-key-utils.js";
+import { startHandleCapture, useCacheRecordKey } from "./handle-capture.js";
+import { isHandle } from "../handle.js";
+import { cacheKeyBase, sortedSearchString } from "./cache-key-utils.js";
 import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -51,9 +51,15 @@ import {
   recordRequestTags,
   runWithCacheTagScope,
 } from "./cache-tag.js";
-import { runWithCacheExecScope } from "./cache-exec-scope.js";
+import {
+  createCacheExecScope,
+  isInCacheExecChain,
+  runWithCacheExecScope,
+  type CacheExecScope,
+} from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
 import type { CacheItemResult } from "./types.js";
+import type { InternalHandlerContext } from "../types.js";
 
 /**
  * DJB2 hash returning an 8-char hex string. Deterministic across runtimes
@@ -125,10 +131,74 @@ export async function replyToCacheKey(
   return encodeKV(pairs, { sort: true });
 }
 
+/**
+ * An unescaped temporary-reference token in an encodeReply part. A user
+ * string "$T" encodes as "$$T", a quote inside a string is escaped, and an
+ * object key "$T" is followed by ":".
+ */
+const TEMPORARY_REFERENCE_TOKEN = /(?<!\\)"\$T"(?!:)/g;
+
+const REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element");
+const CLIENT_REFERENCE_TYPE = Symbol.for("react.client.reference");
+const SERVER_REFERENCE_TYPE = Symbol.for("react.server.reference");
+
+function countTemporaryReferences(encoded: string | FormData): number {
+  if (typeof encoded === "string") {
+    return encoded.match(TEMPORARY_REFERENCE_TOKEN)?.length ?? 0;
+  }
+  let count = 0;
+  encoded.forEach((value) => {
+    if (typeof value === "string") {
+      count += value.match(TEMPORARY_REFERENCE_TOKEN)?.length ?? 0;
+    }
+  });
+  return count;
+}
+
+/** A React element, or a client or server reference function. */
+function isRenderSlot(value: unknown): boolean {
+  if (typeof value === "object" && value !== null) {
+    return (value as { $$typeof?: unknown }).$$typeof === REACT_ELEMENT_TYPE;
+  }
+  if (typeof value === "function") {
+    const tag = (value as { $$typeof?: unknown }).$$typeof;
+    return tag === CLIENT_REFERENCE_TYPE || tag === SERVER_REFERENCE_TYPE;
+  }
+  return false;
+}
+
+/**
+ * Whether encodeReply wrote "$T" for a value that cannot be keyed. Given a
+ * temporary-reference set it does not throw on a value it cannot serialize:
+ * it writes "$T", so distinct arguments would share one key (issue #924).
+ * React elements and client/server references are render slots, left out of
+ * the key on purpose (the interleave route, e2e/use-cache-streaming.test.ts);
+ * a function, a symbol or a class instance is not.
+ *
+ * The set is the Map encodeReply fills: one entry per "$T" it writes, plus
+ * every object it visits. So more tokens than slot entries means a non-slot
+ * "$T", with no traversal of the arguments. Runs only on the encoder path.
+ */
+function hasUnkeyableReference(
+  encoded: string | FormData,
+  tempRefs: unknown,
+): boolean {
+  const tokens = countTemporaryReferences(encoded);
+  if (tokens === 0) return false;
+  let slots = 0;
+  for (const value of (tempRefs as Map<string, unknown>).values()) {
+    if (isRenderSlot(value)) slots++;
+  }
+  return tokens > slots;
+}
+
 // Cached-fn ids already warned about running uncached under a test runner, so
 // the test-ergonomics warning fires once per fn rather than once per call.
 const warnedUncachedUnderTest = new Set<string>();
 
+// Cached-fn ids already warned about arguments that cannot be keyed (dev only).
+const warnedUnkeyableArgs = new Set<string>();
+
 /**
  * Fast-path cache-key builder for JSON-safe key args. Returns a deterministic
  * string (object keys recursively sorted so insertion order can't change the
@@ -264,6 +334,30 @@ function raceLeader(
   });
 }
 
+/**
+ * A stale refresh's view of a handler ctx: loader reads run on their own
+ * executor (setupLoaderAccess _runLoaderIsolated), and an inner HIT replays in
+ * full without claiming. The refresh diverts its pushes, so the request's
+ * memoized run of a loader would take that loader's live pushes off the page,
+ * and a claim would starve the page's own replay of it.
+ */
+function refreshView(arg: unknown): unknown {
+  const ctx = arg as InternalHandlerContext<any, any>;
+  const runIsolated = isTainted(arg) ? ctx._runLoaderIsolated : undefined;
+  if (!runIsolated) return arg;
+  const runs = new Map<string, Promise<any>>();
+  const use = (item: any) => {
+    if (isHandle(item)) return ctx.use(item);
+    let run = runs.get(item.$$id);
+    if (!run) runs.set(item.$$id, (run = runIsolated(item)));
+    return run;
+  };
+  return Object.create(ctx, {
+    use: { value: use },
+    _claimLoaderPushes: { value: undefined },
+  });
+}
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -333,17 +427,33 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       );
     }
 
-    // Separate tainted args (ctx, env, req) from key-generating args.
-    // For tainted objects that carry route context (params, pathname,
-    // searchParams), extract serializable values into the key so
-    // different routes, param combinations, and query variants produce
-    // distinct cache entries.
+    // Separate request-scoped args (ctx, a Request, the request's env) from
+    // key-generating args. For those that carry route context (ctx params,
+    // pathname, searchParams; a Request's URL), extract serializable values
+    // into the key so different routes, param combinations, and query
+    // variants produce distinct cache entries.
     const keyArgs: unknown[] = [];
     let hasTaintedArgs = false;
+    // The calling segment, read synchronously as ctx.use(Handle) does: a HIT
+    // replays into it. A route's layouts and page share one handler ctx and
+    // so one key; the recorded ids are the first caller's. Its ctx's claim
+    // keeps a replayed loader's pushes to one copy per request.
+    let callerSegmentId: string | undefined;
+    let claimLoaderPushes: ((loaderId: string) => boolean) | undefined;
+    // A fetchable loader's request body (loader-fetch.ts) is an input the
+    // route fields leave out: such a call runs uncached (#940).
+    let hasBodyCtx = false;
     for (const arg of args) {
       if (isTainted(arg)) {
         hasTaintedArgs = true;
         const ctx = arg as any;
+        if (ctx.body !== undefined || ctx.formData !== undefined) {
+          hasBodyCtx = true;
+        }
+        if (callerSegmentId === undefined) {
+          callerSegmentId = ctx._currentSegmentId;
+          claimLoaderPushes = ctx._claimLoaderPushes;
+        }
         if (ctx.params && typeof ctx.params === "object") {
           // Include host to prevent cross-host cache collisions (same
           // pattern as route-level cache-scope.ts key generation).
@@ -373,6 +483,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             }
           }
         }
+      } else if (arg instanceof Request) {
+        // A raw Request (ctx.request) is request-scoped like ctx: fold in its
+        // URL with the same host-namespacing and search normalization.
+        const url = new URL(arg.url);
+        keyArgs.push(
+          cacheKeyBase(
+            url.host,
+            url.pathname,
+            url.searchParams,
+            undefined,
+            requestCtx?._searchParamsFilter,
+          ),
+        );
+      } else if (arg != null && arg === requestCtx?.env) {
+        // The request's env is left out: constant per deployment, and its
+        // bindings are not serializable.
       } else {
         keyArgs.push(arg);
       }
@@ -383,7 +509,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // gone. Throw early rather than silently dropping handle side effects.
     if (hasTaintedArgs && !requestCtx?._handleStore) {
       throw new Error(
-        `[use cache] "${id}" receives a tainted argument (ctx/env/req) but the ` +
+        `[use cache] "${id}" receives a ctx argument but the ` +
           `HandleStore is not available. This typically happens when a "use cache" ` +
           `function with ctx runs outside the request context (e.g., during late ` +
           `streaming after AsyncLocalStorage context is lost). Move the "use cache" ` +
@@ -391,10 +517,16 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           `use the route-level cache() DSL instead.`,
       );
     }
+    // Records group pushes by owning loader (useCacheRecordKey) and replay
+    // into the caller's segment; a caller without one records segment ids.
+    const ownerKeyed = callerSegmentId !== undefined;
 
     // Generate cache key
     let cacheKey: string;
     try {
+      if (hasBodyCtx) {
+        throw new Error("ctx carries a request body");
+      }
       if (keyArgs.length > 0) {
         // Fast path: when every key arg is JSON-safe, build the key with a
         // deterministic stable-stringify and skip encodeReply (the Flight reply
@@ -410,6 +542,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           const encoded = await encodeReply(keyArgs as unknown[], {
             temporaryReferences: tempRefs,
           });
+          if (hasUnkeyableReference(encoded, tempRefs)) {
+            throw new Error("unserializable key argument");
+          }
           const argsKey = await replyToCacheKey(encoded);
           cacheKey = `use-cache:${id}:${argsKey}`;
         }
@@ -420,6 +555,19 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       // Non-serializable args: run uncached (within a tag scope so cacheTag()
       // still does not throw). Record runtime tags so the document union still
       // sees them even though this call is not itself cached.
+      if (
+        process.env.NODE_ENV !== "production" &&
+        !warnedUnkeyableArgs.has(id)
+      ) {
+        warnedUnkeyableArgs.add(id);
+        console.warn(
+          `[use cache] "${id}" ran uncached: an argument, or a value nested in ` +
+            `one, cannot be serialized into the cache key (a function, class ` +
+            `instance or symbol, or a loader ctx carrying a request body). ` +
+            `Pass serializable values; ctx, a Request, the request's env and ` +
+            `React elements are handled.`,
+        );
+      }
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
       recordRequestTags(scoped.tags, requestCtx);
@@ -441,7 +589,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         const handleStore = requestCtx?._handleStore;
         if (handleStore) {
           const r = await decodeHandles(entry.handles);
-          if (r) restoreHandles(r, handleStore);
+          if (r) {
+            appendHandles(r, handleStore, callerSegmentId, claimLoaderPushes);
+          }
         }
       }
       recordRequestTags(entry.tags, requestCtx);
@@ -474,34 +624,29 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       // Stale hit: return stale value, revalidate in background
       try {
         const result = await serveCached(cached);
+        const liveStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
+        const recordKey = ownerKeyed ? useCacheRecordKey() : undefined;
         // Background revalidation — must capture handles if tainted args present.
         runBackground(requestCtx, async () => {
-          // The background body runs under a DERIVED context with an OWN
-          // _handleStore (the shell-capture isolation pattern —
-          // shell-capture.ts attemptCapture): its handle pushes land in the
-          // isolated store (captured below, persisted with the entry) while
-          // the foreground keeps pushing into the ORIGINAL store, untouched.
-          // Derivation matters because the foreground is STILL RENDERING here
-          // — runBackground/waitUntil starts the task on the next microtask,
-          // not after the response. The previous shape swapped
-          // requestCtx._handleStore in place (restore in finally), which
-          // routed the whole overlap window's foreground pushes into the
-          // background store: lost from the live document AND persisted into
-          // the revalidated entry (issue #684, plan 010).
-          const bgHandleStore =
-            hasTaintedArgs && requestCtx ? createHandleStore() : undefined;
-          const bgCtx: typeof requestCtx = bgHandleStore
-            ? Object.assign(Object.create(requestCtx), {
-                _handleStore: bgHandleStore,
+          // The background body's handle pushes belong to the refreshed entry
+          // only: the foreground already replayed the stale entry's. They
+          // reach the REQUEST's store (a handler ctx.use(Handle) binds it at
+          // setupLoaderAccess, so a derived context with its own store never
+          // sees them), so the capture accepts only this body's chain and
+          // diverts what it records away from the live store. The foreground
+          // is still rendering here (runBackground starts on the next
+          // microtask), and its concurrent pushes are neither recorded nor
+          // diverted (issue #684, plan 010). A root scope: the task is
+          // detached, so an outer "use cache" body that scheduled it must not
+          // record the refresh's pushes.
+          const bgScope: CacheExecScope = {};
+          const bgCapture = liveStore
+            ? startHandleCapture(liveStore, {
+                accept: () => isInCacheExecChain(bgScope),
+                divert: true,
+                key: recordKey,
               })
-            : requestCtx;
-          let bgCapture: HandleCapture | undefined;
-          let bgStopCapture: (() => void) | undefined;
-          if (bgHandleStore) {
-            const c = startHandleCapture(bgHandleStore);
-            bgCapture = c.capture;
-            bgStopCapture = c.stop;
-          }
+            : undefined;
 
           // Tainted args are NOT stamped here, in contrast to the foreground
           // miss path below. The args include the live HandlerContext the
@@ -522,23 +667,25 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // getRequestContext().env.ApiKey) resolves during the background
             // revalidation instead of throwing "called outside of a request
             // context". runWithRequestContext sets the store for fn's
-            // synchronous kickoff; its async continuations inherit it. The
-            // DERIVED context goes in, so ambient _handleStore reads inside
-            // the body resolve to the isolated store.
+            // synchronous kickoff; its async continuations inherit it.
             //
             // The span opens inside the request ALS and wraps the WHOLE task —
             // fn kickoff through the store write — so its platform spans nest
             // under rango.background and a slow or failing setItem is part of
             // the traced revalidation, not an untraced tail.
-            await runWithRequestContext(bgCtx, () =>
+            await runWithRequestContext(requestCtx, () =>
               observePhase(
                 PHASES.background("use-cache-revalidation"),
                 async () => {
+                  const refreshArgs = args.map(refreshView);
                   const scoped = runWithCacheTagScope(() =>
-                    runWithCacheExecScope(() => fn.apply(this, args)),
+                    runWithCacheExecScope(
+                      () => fn.apply(this, refreshArgs),
+                      bgScope,
+                    ),
                   );
                   const freshResult = await scoped.result;
-                  bgStopCapture?.();
+                  bgCapture?.stop();
                   // Merge profile/DSL tags with runtime cacheTag() tags, read
                   // after awaiting so post-await cacheTag() calls are included.
                   // Normalize (drops empty profile tags, matching the
@@ -549,11 +696,24 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                     ),
                   ];
                   recordRequestTags(freshTags, requestCtx);
-                  const serialized = await serializeResult(freshResult);
+                  const flightErrors: unknown[] = [];
+                  const onFlightError = (error: unknown): void => {
+                    flightErrors.push(error);
+                  };
+                  const serialized = await serializeResult(
+                    freshResult,
+                    onFlightError,
+                  );
                   if (serialized !== null) {
-                    const encodedHandles = bgCapture?.data
-                      ? await encodeHandles(bgCapture.data)
+                    const encodedHandles = bgCapture
+                      ? await encodeHandles(
+                          bgCapture.capture.data,
+                          onFlightError,
+                        )
                       : undefined;
+                    // An error row would replace the stale entry; the catch
+                    // below reports it and the stale entry keeps serving.
+                    if (flightErrors.length > 0) throw flightErrors[0];
                     await store.setItem!(cacheKey, serialized, {
                       handles: encodedHandles,
                       ttl: profile.ttl,
@@ -565,7 +725,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               ),
             );
           } catch (bgError) {
-            bgStopCapture?.();
+            bgCapture?.stop();
             // Pass requestCtx explicitly: this runs in a detached background
             // task where the ALS context is gone, so onError can only fire if
             // we hand it the context captured up front.
@@ -576,8 +736,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               requestCtx,
             );
           }
-          // No finally: nothing shared was mutated — the derived context and
-          // its handle store are garbage after the task settles.
         });
         return result;
       } catch (error) {
@@ -669,14 +827,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     };
 
     // execute, serialize, store
+    // Record only this execution's pushes (and cached functions it calls):
+    // the handler and loaders push into the same store concurrently, and they
+    // re-run on a hit.
     const handleStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
-    let capture: HandleCapture | undefined;
-    let stopCapture: (() => void) | undefined;
-    if (handleStore && hasTaintedArgs) {
-      const c = startHandleCapture(handleStore);
-      capture = c.capture;
-      stopCapture = c.stop;
-    }
+    const execScope = createCacheExecScope();
+    const capture = handleStore
+      ? startHandleCapture(handleStore, {
+          accept: () => isInCacheExecChain(execScope),
+          key: ownerKeyed ? useCacheRecordKey() : undefined,
+        })
+      : undefined;
 
     // Stamp tainted args so ctx.set(), ctx.header(), etc. throw if called
     // inside the cached function body (those side effects are lost on hit).
@@ -702,7 +863,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
       scoped = runWithCacheTagScope(() =>
-        runWithCacheExecScope(() => fn.apply(this, args)),
+        runWithCacheExecScope(() => fn.apply(this, args), execScope),
       );
       result = await scoped.result;
     } catch (execError) {
@@ -717,7 +878,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         unstampCacheExec(arg as object);
       }
       // Remove this capture token (order-independent, safe for concurrent use)
-      stopCapture?.();
+      capture?.stop();
     }
 
     // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
@@ -735,11 +896,19 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const finalizeAndWrite = async (): Promise<void> => {
       let serialized: string | null;
       let encodedHandles: string | undefined;
+      const flightErrors: unknown[] = [];
+      const onFlightError = (error: unknown): void => {
+        flightErrors.push(error);
+      };
       try {
-        serialized = await serializeResult(result);
-        encodedHandles = capture?.data
-          ? await encodeHandles(capture.data)
+        serialized = await serializeResult(result, onFlightError);
+        encodedHandles = capture
+          ? await encodeHandles(capture.capture.data, onFlightError)
           : undefined;
+        // Flight encodes an async component that throws, or a rejected
+        // promise in the result or a handle value, as an error row and
+        // completes normally; stored, every hit would serve that error.
+        if (flightErrors.length > 0) throw flightErrors[0];
       } catch (buildError) {
         // Serialize/handle-encode failed: no envelope for followers (they run
         // fresh) and nothing to write.