@rangojs/router 0.16.0 → 0.17.0

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.

package/src/cache/cache-scope.ts

@@ -28,6 +28,7 @@ import { reportCacheError } from "./cache-error.js";
 // is unchanged: both methods are async and already awaited the codec.
 import {
   captureHandles,
+  captureHandleOwners,
   restoreHandles,
   encodeHandles,
   decodeHandles,
@@ -149,6 +150,14 @@ export class CacheScope {
     config: PartialCacheOptions | false,
     parent: CacheScope | null = null,
     private readonly defaultKeyPrefix?: "doc",
+    /**
+     * @internal shortCode of the outermost cache() entry of this scope's
+     * enabled chain (createCacheScope). Entries above it are live: their
+     * segments are not stored and resolve fresh on a hit (withCacheLookup).
+     * Undefined covers the whole matched chain (the implicit shell doc scope,
+     * a ppr route).
+     */
+    readonly boundary?: string,
   ) {
     this.config = config;
     this.parent = parent;
@@ -156,6 +165,24 @@ export class CacheScope {
     this.explicitStore = config !== false ? config.store : undefined;
   }
 
+  /**
+   * @internal Whether a segment belongs to this scope's cache entry. ShortCodes are
+   * hierarchical (server/context.ts getShortCode: parent shortCode + include
+   * scope + type letter + counter), so the boundary's subtree is every id that
+   * extends the boundary shortCode at a non-digit (`C1` must not claim `C10`).
+   * Intercept slot segments ride the target route's entry wherever the
+   * intercept is declared.
+   */
+  covers(id: string, namespace?: string): boolean {
+    const boundary = this.boundary;
+    if (boundary === undefined) return true;
+    if (id.startsWith(boundary)) {
+      const next = id.charCodeAt(boundary.length);
+      return !(next >= 48 && next <= 57);
+    }
+    return namespace?.startsWith("intercept:") === true;
+  }
+
   /**
    * Whether caching is enabled for this scope
    */
@@ -316,11 +343,14 @@ export class CacheScope {
    * @param pathname - URL pathname for cache key generation
    * @param params - Route params for cache key generation
    * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+   * @param claimLoaderPushes - The handler context's _claimLoaderPushes, for
+   *   restoreHandles' loader-owned values
    */
   async lookupRoute(
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
+    claimLoaderPushes?: (loaderId: string) => boolean,
   ): Promise<{
     segments: ResolvedSegment[];
     shouldRevalidate: boolean;
@@ -329,6 +359,7 @@ export class CacheScope {
       pathname,
       params,
       isIntercept,
+      claimLoaderPushes,
     );
     return outcome.status === "hit" ? outcome.result : null;
   }
@@ -355,6 +386,7 @@ export class CacheScope {
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
+    claimLoaderPushes?: (loaderId: string) => boolean,
   ): Promise<CacheRouteLookupOutcome> {
     if (!this.enabled) return { status: "bypass" };
     if (!this.conditionAllows("read")) return { status: "bypass" };
@@ -424,6 +456,14 @@ export class CacheScope {
         return { status: "miss" };
       }
 
+      // A record from a whole-chain writer (a previous build on an unversioned
+      // store) can hold segments above the boundary. withCacheLookup resolves
+      // those fresh, so replaying them too would duplicate them and their
+      // handle pushes.
+      if (this.boundary !== undefined) {
+        segments = segments.filter((s) => this.covers(s.id, s.namespace));
+      }
+
       // A hit serves content that was tagged at write time, so the document
       // tag union must include this entry's tags for updateTag()/revalidateTag()
       // to invalidate any full-page entry built on top of it. The write path
@@ -438,7 +478,18 @@ export class CacheScope {
       if (handleStore && cached.handles) {
         const handlesRecord = await decodeHandles(cached.handles);
         if (handlesRecord) {
-          restoreHandles(handlesRecord, handleStore);
+          if (this.boundary !== undefined) {
+            const kept = new Set(segments.map((s) => s.id));
+            for (const id of Object.keys(handlesRecord)) {
+              if (!kept.has(id)) delete handlesRecord[id];
+            }
+          }
+          restoreHandles(
+            handlesRecord,
+            handleStore,
+            cached.handleOwners,
+            claimLoaderPushes,
+          );
         }
       }
 
@@ -515,8 +566,11 @@ export class CacheScope {
     if (!handleStore || !requestCtx) return;
 
     // Exclude loader segments - loaders are always fresh by default
-    // Loaders can opt-in to caching with their own cache() config
-    const nonLoaderSegments = segments.filter((s) => s.type !== "loader");
+    // Loaders can opt-in to caching with their own cache() config.
+    // Segments above the boundary are live and never stored.
+    const nonLoaderSegments = segments.filter(
+      (s) => s.type !== "loader" && this.covers(s.id, s.namespace),
+    );
     if (nonLoaderSegments.length === 0) return;
 
     const ttl = this.ttl;
@@ -585,11 +639,8 @@ export class CacheScope {
       }
 
       // Collect handle data for non-loader segments only
-      const handles = captureHandles(
-        nonLoaderSegments,
-        handleStore,
-        requestCtx._shellCaptureLoaderHandleValues,
-      );
+      const handles = captureHandles(nonLoaderSegments, handleStore);
+      const handleOwners = captureHandleOwners(nonLoaderSegments, handleStore);
 
       try {
         if (INTERNAL_RANGO_DEBUG) {
@@ -602,10 +653,18 @@ export class CacheScope {
         // through the codec (not raw into the entry) so Promise/ReactNode handle
         // values survive a JSON-serializing store — see encodeHandles.
         const { serializeSegments } = await import("./segment-codec.js");
+        const flightErrors: unknown[] = [];
+        const onFlightError = (error: unknown): void => {
+          flightErrors.push(error);
+        };
         const [serializedSegments, encodedHandles] = await Promise.all([
-          serializeSegments(nonLoaderSegments),
-          encodeHandles(handles),
+          serializeSegments(nonLoaderSegments, onFlightError),
+          encodeHandles(handles, onFlightError),
         ]);
+        // Flight encodes a component that throws (an async server component in
+        // the tree) or a rejected handle value as an error row and completes
+        // normally; stored, every HIT would render that error until expiry.
+        if (flightErrors.length > 0) throw flightErrors[0];
 
         const data: CachedEntryData = {
           segments: serializedSegments,
@@ -613,6 +672,7 @@ export class CacheScope {
           expiresAt: Date.now() + ttl * 1000,
           tags,
         };
+        if (handleOwners && encodedHandles) data.handleOwners = handleOwners;
 
         if (INTERNAL_RANGO_DEBUG) {
           debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
@@ -640,14 +700,18 @@ export class CacheScope {
 }
 
 /**
- * Create a cache scope from entry's cache config
+ * Create a cache scope from entry's cache config. `shortCode` is the cache()
+ * entry's: a scope nested in an enabled parent keeps the parent's boundary
+ * (one entry covers both), any other opens its own at this entry.
  */
 export function createCacheScope(
   config: { options: PartialCacheOptions | false } | undefined,
   parent: CacheScope | null = null,
+  shortCode?: string,
 ): CacheScope | null {
   if (!config) return parent; // No config, inherit parent
-  return new CacheScope(config.options, parent);
+  const boundary = parent?.enabled ? parent.boundary : shortCode;
+  return new CacheScope(config.options, parent, undefined, boundary);
 }
 
 type ShellImplicitCacheMarker = NonNullable<