@rangojs/router 0.27.0 → 0.29.0

package/src/cache/cache-runtime.ts

@@ -22,7 +22,8 @@ import {
 } from "../deps/rsc-client.js";
 import {
   getRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
+  type RequestContext,
 } from "../server/request-context.js";
 import { isUnderTestRunner } from "../runtime-env.js";
 import {
@@ -34,7 +35,12 @@ import {
 } from "./taint.js";
 
 export { isCachedFunction };
-import { serializeResult, deserializeResult } from "./segment-codec.js";
+import {
+  serializeResult,
+  deserializeResult,
+  isUnsupportedValueError,
+  teeResult,
+} from "./segment-codec.js";
 import {
   appendHandles,
   encodeHandles,
@@ -384,6 +390,23 @@ function refreshView(arg: unknown): unknown {
   });
 }
 
+/**
+ * Run `fn` inside a "use cache" execution's scopes: its exec scope
+ * (cookies()/headers() reads and ctx writes refuse) and its tag scope
+ * (cacheTag() and nested calls tag the entry, #980), `recorded` when given.
+ * The body runs here, and so does the value's encode: it renders the server
+ * components in the value, which are part of the entry. Scar: the encode ran
+ * in the tag scope only, so a returned component's cookies() read went
+ * through and the entry served the first visitor's value to the next.
+ */
+function inExecution<T>(
+  scope: CacheExecScope,
+  fn: () => T,
+  recorded?: Set<string>,
+): { result: T; tags: Set<string> } {
+  return runWithCacheTagScope(() => runWithCacheExecScope(fn, scope), recorded);
+}
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -459,14 +482,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const entryTags = (recorded: Set<string>): string[] => [
       ...new Set(normalizeTags([...(profile.tags ?? []), ...recorded])),
     ];
-    // The value's Flight encode runs back inside its execution's tag scope:
-    // it renders the server components in the value, and a "use cache" call
-    // or cacheTag() among them belongs to this entry (#980).
-    const inTagScope = <T>(
-      recorded: Set<string>,
-      encode: () => Promise<T>,
-    ): Promise<T> => runWithCacheTagScope(encode, recorded).result;
-
     // 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
@@ -712,30 +727,29 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // user's value into the shared entry — with zero visibility to the
             // concurrent foreground.
 
-            try {
-              // Re-establish the request-context ALS so a "use cache" body that
-              // reads the ambient getRequestContext() (e.g.
-              // 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 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(requestCtx, () =>
-                observePhase(
+            // Re-establish the request-context ALS so a "use cache" body that
+            // reads the ambient getRequestContext() (e.g.
+            // getRequestContext().env.ApiKey) resolves during the background
+            // revalidation instead of throwing "called outside of a request
+            // context". runAsBackgroundWork sets the store for fn's synchronous
+            // kickoff; its async continuations inherit it. No visitor made the
+            // invalidations it runs (no fresh-reads cookie), and onError marks
+            // its errors `background`, the failure caught below included.
+            //
+            // 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 runAsBackgroundWork(requestCtx, async () => {
+              try {
+                await observePhase(
                   PHASES.background("use-cache-revalidation"),
                   async () => {
                     const refreshArgs = args.map(refreshView);
                     // The refresh reads its data from here on (#973, #977).
                     const start = executionStart();
-                    const scoped = runWithCacheTagScope(() =>
-                      runWithCacheExecScope(
-                        () => fn.apply(this, refreshArgs),
-                        bgScope,
-                      ),
+                    const scoped = inExecution(bgScope, () =>
+                      fn.apply(this, refreshArgs),
                     );
                     const freshResult = await scoped.result;
                     bgCapture?.stop();
@@ -744,17 +758,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                     const onFlightError = (error: unknown): void => {
                       flightErrors.push(error);
                     };
-                    const serialized = await inTagScope(scoped.tags, () =>
-                      serializeResult(freshResult, onFlightError),
-                    );
+                    const serialized = await inExecution(
+                      bgScope,
+                      () => serializeResult(freshResult, onFlightError),
+                      scoped.tags,
+                    ).result;
                     if (serialized !== null) {
                       const encodedHandles = bgCapture
-                        ? await inTagScope(scoped.tags, () =>
-                            encodeHandles(
-                              bgCapture.capture.data,
-                              onFlightError,
-                            ),
-                          )
+                        ? await inExecution(
+                            bgScope,
+                            () =>
+                              encodeHandles(
+                                bgCapture.capture.data,
+                                onFlightError,
+                              ),
+                            scoped.tags,
+                          ).result
                         : undefined;
                       // An error row would replace the stale entry; the catch
                       // below reports it and the stale entry keeps serving.
@@ -777,20 +796,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                       noteWarmWrite(requestCtx, "item");
                     }
                   },
-                ),
-              );
-            } catch (bgError) {
-              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.
-              reportCacheError(
-                bgError,
-                "stale-revalidation",
-                "[use cache] background revalidation failed",
-                requestCtx,
-              );
-            }
+                );
+              } catch (bgError) {
+                bgCapture?.stop();
+                reportCacheError(
+                  bgError,
+                  "stale-revalidation",
+                  "[use cache] background revalidation failed",
+                  requestCtx,
+                );
+              }
+            });
           }),
         );
         return result;
@@ -921,21 +937,24 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // deliberately NOT stamped: a property on that SHARED object made every
     // parallel read on the request throw for the cached body's whole
     // execution window (a 2s cached fetch poisoned a sibling loader's
-    // cookies() — same hazard class as issue #684, plan 010).
+    // cookies() — same hazard class as issue #684, plan 010). Not as an
+    // argument either (getRequestContext(), any pass: a derived pass inherits
+    // `_requestRoot`): a derived pass's writers that it does not route to a
+    // sink check the request's own context (server/render-pass.ts), so the
+    // stamp failed a shell capture's or a background re-render's writes while
+    // a foreground body held it.
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
-      if (isTainted(arg)) {
+      if (isTainted(arg) && !(arg as RequestContext)._requestRoot) {
         stampCacheExec(arg as object);
         taintedArgs.push(arg);
       }
     }
 
     let result: any;
-    let scoped: ReturnType<typeof runWithCacheTagScope>;
+    let scoped: ReturnType<typeof inExecution>;
     try {
-      scoped = runWithCacheTagScope(() =>
-        runWithCacheExecScope(() => fn.apply(this, args), execScope),
-      );
+      scoped = inExecution(execScope, () => fn.apply(this, args));
       result = await scoped.result;
     } catch (execError) {
       // The function threw: drop the in-flight entry and reject any waiters so
@@ -957,25 +976,39 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const recorded = scoped!.tags;
     recordRequestTags(entryTags(recorded), requestCtx);
 
-    // Serialize + encode handles ONCE, resolve the in-flight envelope so any
-    // concurrent followers can serve a synthetic hit, then persist to the store.
-    // Fully non-blocking when waitUntil is available — the leader's response
-    // waits on neither serialization nor the store write.
+    // Encode the value ONCE, inside the execution's scopes, and hand the
+    // caller a decoded copy of it, as a hit does. The caller rendering
+    // `result` itself would share its lazy state (a React.lazy, a memoizing
+    // thenable) with the encode: whichever render reached it first decided
+    // its value for both, so a read the caller's render made outside the
+    // scope was stored for the next visitor. Then resolve the in-flight
+    // envelope so concurrent followers serve a synthetic hit, and persist.
+    // When waitUntil is available the leader waits for the copy's root row
+    // only, not for the rest of the encode or the store write.
+    const flightErrors: unknown[] = [];
+    const onFlightError = (error: unknown): void => {
+      flightErrors.push(error);
+    };
+    const encoded = inExecution(
+      execScope,
+      () => teeResult(result, onFlightError),
+      recorded,
+    ).result;
     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 inTagScope(recorded, () =>
-          serializeResult(result, onFlightError),
-        );
+        serialized = encoded ? await encoded.serialized : null;
+        // The returned tree renders only in the encode, so its cacheTag()
+        // calls tag the entry alone: record the entry's tags onto the
+        // request, as a hit does.
+        recordRequestTags(entryTags(recorded), requestCtx);
         encodedHandles = capture
-          ? await inTagScope(recorded, () =>
-              encodeHandles(capture.capture.data, onFlightError),
-            )
+          ? await inExecution(
+              execScope,
+              () => encodeHandles(capture.capture.data, onFlightError),
+              recorded,
+            ).result
           : undefined;
         // Flight encodes an async component that throws, or a rejected
         // promise in the result or a handle value, as an error row and
@@ -986,10 +1019,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         assertLoaderReadsClean(execScope);
       } catch (buildError) {
         // Serialize/handle-encode failed: no envelope for followers (they run
-        // fresh) and nothing to write.
+        // fresh) and nothing to write. Logged too: a read the guard refused
+        // in the value is otherwise silent with no onError. An error the call
+        // also throws reaches onError once (the request dedups by identity).
         clearSelf();
         rejectEnvelope(buildError);
-        requestCtx?._reportBackgroundError?.(buildError, "cache-write");
+        reportCacheError(
+          buildError,
+          "cache-write",
+          `[use cache] "${id}" write`,
+          requestCtx,
+        );
         return;
       }
       if (serialized === null) {
@@ -1039,7 +1079,24 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
 
     await runBackground(requestCtx, finalizeAndWrite, true);
 
-    return result;
+    // The encode could not start: nothing is stored, the value renders live.
+    if (!encoded) return result;
+    try {
+      return await encoded.decoded;
+    } catch (decodeError) {
+      // The root row failed. A value Flight cannot encode (a function, a
+      // class instance) is not cached and renders live, as it always has;
+      // anything else, a refused read above all, fails the call as the same
+      // read in the body does, with the encode's own error (production
+      // Flight redacts the decoded one).
+      if (
+        flightErrors.length > 0 &&
+        flightErrors.every(isUnsupportedValueError)
+      ) {
+        return result;
+      }
+      throw flightErrors[0] ?? decodeError;
+    }
   };
 
   // Brand the wrapper so it can be detected at runtime (e.g., to prevent

package/src/cache/cache-scope.ts

@@ -33,8 +33,9 @@ import {
 // pulls @vitejs/plugin-rsc (a virtual: module the plain node/vitest runner cannot
 // resolve). It is imported LAZILY at the two call sites below (deserializeSegments
 // in lookupRoute, serializeSegments in cacheRoute) so that requiring cache-scope —
-// e.g. dispatch's lazy `import("../cache/cache-scope.js")` for the response-route
-// cache path — does not crash a consumer test that never mocks plugin-rsc. Behavior
+// e.g. through the request stages dispatch loads for a response route
+// (rsc/request-stages.ts) — does not crash a consumer test that never mocks
+// plugin-rsc. Behavior
 // is unchanged: both methods are async and already awaited the codec.
 import {
   captureHandles,
@@ -54,14 +55,16 @@ import {
 import type { RequestContext } from "../server/request-context.js";
 import { runIdentityExempt } from "./cache-exec-scope.js";
 import { isWarmReplace, noteWarmWrite } from "../prerender/warm-request.js";
+import { WIRE } from "../wire-params.js";
 
 /**
- * Narrow the request's route-record window (RequestContext._routeRecordWindow)
- * to a record this request read or wrote: fresh until `freshUntil` (the
- * record's `expiresAt`), then stale for `swr` seconds. A shell capture starts
- * with no window of its own (shell-capture.ts deriveShellCaptureContext sets
- * it undefined), so it narrows only to the records the capture itself read
- * or wrote.
+ * Narrow a shell capture's route-record window
+ * (ShellCaptureState.routeRecordWindow) to a record the capture read or
+ * wrote: fresh until `freshUntil` (the record's `expiresAt`), then stale for
+ * `swr` seconds. A capture starts with no window of its own
+ * (RENDER_PASS_FIELDS["shell-capture"] creates it undefined), so it narrows
+ * only to the records the capture itself read or wrote. Only a capture reads
+ * the window (shell-capture.ts capShellWindow): another render notes nothing.
  */
 function noteRouteRecordWindow(
   requestCtx: RequestContext,
@@ -70,6 +73,8 @@ function noteRouteRecordWindow(
   swr: number,
   written: boolean,
 ): void {
+  const captureState = requestCtx._shellCaptureState;
+  if (!captureState) return;
   const next = {
     freshUntil,
     staleUntil: freshUntil + swr * 1000,
@@ -77,9 +82,9 @@ function noteRouteRecordWindow(
     swr,
     written,
   };
-  const current = requestCtx._routeRecordWindow;
+  const current = captureState.routeRecordWindow;
   // The record that runs out first names the config; freshness is the least.
-  requestCtx._routeRecordWindow = current
+  captureState.routeRecordWindow = current
     ? {
         ...(current.staleUntil <= next.staleUntil ? current : next),
         freshUntil: Math.min(current.freshUntil, freshUntil),
@@ -123,23 +128,36 @@ function validatedSwr(value: number | undefined): number | undefined {
   return isValidCacheSeconds(value, "swr") ? value : undefined;
 }
 
+/**
+ * The request kind a route record answers: `doc` (a document request),
+ * `partial` (a navigation) or `intercept:<intercept>`, where `intercept` is
+ * the intercept an intercept navigation selected (interceptRecordKey,
+ * router/intercept-resolution.ts). The kinds' records hold different
+ * segments (an intercept's holds its slot and no route page), so every record
+ * key names its kind, a `key()`'s included (CacheScope.resolveKeyFrom).
+ * Keyed by the URL alone, a record written under one intercept answered a
+ * navigation that selected another; keyed by a `key()` alone, a document GET
+ * rendered an intercept's record and dropped the page.
+ */
+function routeRecordKind(intercept?: string, prefixOverride?: "doc"): string {
+  if (intercept !== undefined) return `intercept:${intercept}`;
+  if (prefixOverride !== undefined) return prefixOverride;
+  const isPartial =
+    getRequestContext()?.originalUrl?.searchParams.has(WIRE.partial) ?? false;
+  return isPartial ? "partial" : "doc";
+}
+
+/** `{kind}:` + the request's key base (routeRecordKind, requestKeyBase). */
 function getDefaultRouteCacheKey(
   pathname: string,
-  params?: Record<string, string>,
-  isIntercept?: boolean,
-  prefixOverride?: "doc",
+  params: Record<string, string> | undefined,
+  kind: string,
 ): string {
   const ctx = getRequestContext();
-  const isPartial = ctx?.originalUrl?.searchParams.has("_rsc_partial") ?? false;
   const searchParams = ctx?.url.searchParams;
   const host = ctx?.url.host ?? "localhost";
 
-  // Intercept navigations get their own cache namespace
-  const prefix = isIntercept
-    ? "intercept"
-    : (prefixOverride ?? (isPartial ? "partial" : "doc"));
-
-  return `${prefix}:${requestKeyBase(ctx, host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
+  return `${kind}:${requestKeyBase(ctx, host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
 }
 
 // ============================================================================
@@ -236,15 +254,23 @@ function memoizedKey(
   return key;
 }
 
+/**
+ * A route record that answered. `restoreHandles` is set when the lookup left
+ * the handle restore to its caller (lookupRouteDetailed `deferHandles`),
+ * which names the segments it sends (handle-snapshot.ts restoreHandles).
+ */
+export interface CachedRouteHit {
+  segments: ResolvedSegment[];
+  shouldRevalidate: boolean;
+  restoreHandles?: (sentIds: ReadonlySet<string>) => Promise<void>;
+}
+
 /**
  * Discriminated outcome of a route cache lookup — see
  * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
  */
 export type CacheRouteLookupOutcome =
-  | {
-      status: "hit";
-      result: { segments: ResolvedSegment[]; shouldRevalidate: boolean };
-    }
+  | { status: "hit"; result: CachedRouteHit }
   | { status: "miss" | "bypass" | "error" };
 
 /**
@@ -455,15 +481,13 @@ export class CacheScope {
   private resolveKey(
     pathname: string,
     params: Record<string, string>,
-    isIntercept?: boolean,
+    intercept?: string,
   ): Promise<string> {
+    const kind = routeRecordKind(intercept, this.defaultKeyPrefix);
     return this.resolveKeyFrom(
-      getDefaultRouteCacheKey(
-        pathname,
-        params,
-        isIntercept,
-        this.defaultKeyPrefix,
-      ),
+      getDefaultRouteCacheKey(pathname, params, kind),
+      "",
+      kind,
     );
   }
 
@@ -500,14 +524,18 @@ export class CacheScope {
    * enclosing partition (#970, #974). A scope whose own config sets no
    * `key()` appends its own default key (resolveDefaultKey). Reusing the
    * outer `key()` result alone would give every route under the inner
-   * cache() one record: a `key()` replaces the whole default key, so an
-   * outer key that names no route (`tier:gold`) would make `/a` HIT `/b`'s
-   * record. A scope with its own `key()` adds no default key: a `key()` is a
-   * full override, and its store's keyGenerator does not run. With no
-   * partition part it is resolveDefaultKey alone. With a `key()` on the
-   * chain but no request context it rejects (keyWithoutContextError).
-   * `partitionedPrefix` prefixes a key built from partition parts only (the
-   * response family's `response:`).
+   * cache() one record: a `key()` replaces the default key's URL part, so
+   * an outer key that names no route (`tier:gold`) would make `/a` HIT
+   * `/b`'s record. A scope with its own `key()` adds no default key: its `key()`
+   * replaces the URL part, and its store's keyGenerator does not run. It
+   * appends `kind` instead (routeRecordKind): the `key()` decides which
+   * requests of one kind share a record, never that a document, a
+   * navigation and an intercept navigation do. With no partition part it is
+   * resolveDefaultKey alone. With a `key()` on the chain but no request
+   * context it rejects (keyWithoutContextError). `partitionedPrefix`
+   * prefixes a key built from partition parts only (the response family's
+   * `response:`, which passes no `kind`: a response route answers every
+   * request alike).
    *
    * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
    * by function: it runs once per request whatever the default key
@@ -518,7 +546,11 @@ export class CacheScope {
    * itself: a `key()` calling `cookies()` would trip the capture guard there,
    * and a capture must store the partition its request resolved.
    */
-  resolveKeyFrom(defaultKey: string, partitionedPrefix = ""): Promise<string> {
+  resolveKeyFrom(
+    defaultKey: string,
+    partitionedPrefix = "",
+    kind?: string,
+  ): Promise<string> {
     if (this.fixedKey !== undefined) return Promise.resolve(this.fixedKey);
     const requestCtx = _getRequestContext();
     if (!requestCtx || !this.mayPartition) {
@@ -534,7 +566,8 @@ export class CacheScope {
     ]).then(([[keys, storeParts], ownDefault]) => {
       const generated = positionalParts(storeParts);
       if (keys.length === 0 && generated.length === 0) return ownDefault!;
-      if (ownDefault !== undefined) generated.push(ownDefault);
+      const last = ownDefault ?? kind;
+      if (last !== undefined) generated.push(last);
       return partitionedPrefix + composeCacheKeys(keys, generated);
     });
   }
@@ -558,7 +591,7 @@ export class CacheScope {
       ? undefined
       : this.getStore()?.keyGenerator;
     if (!this.mayPartition && !keyGenerator) return undefined;
-    const defaultKey = getDefaultRouteCacheKey(pathname, params, false, "doc");
+    const defaultKey = getDefaultRouteCacheKey(pathname, params, "doc");
     const requestCtx = _getRequestContext();
     if (!requestCtx) {
       return this.keyFns.length > 0
@@ -735,24 +768,26 @@ 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 intercept - The intercept an intercept navigation selected
+   *   (interceptRecordKey): its record has its own key
    * @param ownedPushes - What the record is to each loader's handle pushes
    *   (withCacheLookup: loader-cache.ts loaderPins), called on a hit
+   * @param deferHandles - Restore no handle value here: the caller calls the
+   *   hit's `restoreHandles` once it decided which segments it sends
    */
   async lookupRoute(
     pathname: string,
     params: Record<string, string>,
-    isIntercept?: boolean,
+    intercept?: string,
     ownedPushes?: () => OwnedPushDelivery,
-  ): Promise<{
-    segments: ResolvedSegment[];
-    shouldRevalidate: boolean;
-  } | null> {
+    deferHandles?: boolean,
+  ): Promise<CachedRouteHit | null> {
     const outcome = await this.lookupRouteDetailed(
       pathname,
       params,
-      isIntercept,
+      intercept,
       ownedPushes,
+      deferHandles,
     );
     return outcome.status === "hit" ? outcome.result : null;
   }
@@ -778,8 +813,9 @@ export class CacheScope {
   async lookupRouteDetailed(
     pathname: string,
     params: Record<string, string>,
-    isIntercept?: boolean,
+    intercept?: string,
     ownedPushes?: () => OwnedPushDelivery,
+    deferHandles?: boolean,
   ): Promise<CacheRouteLookupOutcome> {
     if (!this.enabled) return { status: "bypass" };
     if (!this.conditionAllows("read")) return { status: "bypass" };
@@ -801,7 +837,7 @@ export class CacheScope {
     // happens here, where a miss is a safe outcome.
     let key: string | undefined;
     try {
-      key = await this.resolveKey(pathname, params, isIntercept);
+      key = await this.resolveKey(pathname, params, intercept);
 
       const result = await store.get(key);
 
@@ -882,17 +918,23 @@ export class CacheScope {
       await this.onHit?.();
 
       const handleStore = _getRequestContext()?._handleStore;
+      let restoreHandles: CachedRouteHit["restoreHandles"];
       // An empty handles string means the route pushed none (the common
       // case); a decode failure skips the restore but keeps the segments.
       if (handleStore) {
-        await restoreRecordHandles(
-          handleStore,
-          cached,
-          ownedPushes?.(),
+        const owned = ownedPushes?.();
+        const keepIds =
           this.boundary !== undefined
             ? new Set(segments.map((s) => s.id))
-            : undefined,
-        );
+            : undefined;
+        if (deferHandles) {
+          // The authority holds from here, as with the restore below.
+          if (owned) handleStore.setRecordAuthority(owned);
+          restoreHandles = (sent) =>
+            restoreRecordHandles(handleStore, cached, owned, keepIds, sent);
+        } else {
+          await restoreRecordHandles(handleStore, cached, owned, keepIds);
+        }
       }
 
       if (INTERNAL_RANGO_DEBUG) {
@@ -907,7 +949,10 @@ export class CacheScope {
       if (ambientContext)
         this.noteRecordWindow(ambientContext, cached.expiresAt, false);
 
-      return { status: "hit", result: { segments, shouldRevalidate } };
+      return {
+        status: "hit",
+        result: { segments, shouldRevalidate, restoreHandles },
+      };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
       // (resolveKey). Either way degrade to an uncached render — reported as
@@ -969,7 +1014,8 @@ export class CacheScope {
    * @param pathname - URL pathname for cache key generation
    * @param params - Route params for cache key generation
    * @param segments - All resolved segments to cache
-   * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+   * @param intercept - The intercept an intercept navigation selected
+   *   (interceptRecordKey): its record has its own key
    * @param start - Where the render of `segments` started: the record is not
    *   written when one of its tags was invalidated since (#977,
    *   predatesInvalidation). A shell capture's doc record passes none: it
@@ -979,7 +1025,7 @@ export class CacheScope {
     pathname: string,
     params: Record<string, string>,
     segments: ResolvedSegment[],
-    isIntercept?: boolean,
+    intercept?: string,
     start?: ExecutionStart,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
@@ -1006,7 +1052,7 @@ export class CacheScope {
     this.noteRecordWindow(requestCtx, Date.now() + ttl * 1000, true);
 
     // Resolve cache key early (while request context is available)
-    const key = await this.resolveKey(pathname, params, isIntercept);
+    const key = await this.resolveKey(pathname, params, intercept);
 
     // Doc-namespaced scopes (the shell implicit scope and the capture's
     // composed doc scope) publish the canonical document segment key so
@@ -1022,7 +1068,7 @@ export class CacheScope {
     recordRequestTags(tags, requestCtx);
 
     // Check if this is a partial request (navigation) vs document request
-    const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
+    const isPartial = requestCtx.originalUrl.searchParams.has(WIRE.partial);
 
     if (INTERNAL_RANGO_DEBUG) {
       debugCacheLog(
@@ -1204,7 +1250,7 @@ export function resolveShellPartition(
 ): Promise<string | null> | undefined {
   if (routeScope?.enabled) return routeScope.resolvePartition(pathname, params);
   if (!appStore?.keyGenerator) return undefined;
-  const defaultKey = getDefaultRouteCacheKey(pathname, params, false, "doc");
+  const defaultKey = getDefaultRouteCacheKey(pathname, params, "doc");
   return resolveCacheKey(undefined, appStore, defaultKey).then((resolved) =>
     resolved === defaultKey ? null : resolved,
   );
@@ -1259,7 +1305,7 @@ export function createShellImplicitDocScope(
  * normal partial navigation replay), substitute an implicit doc-level scope
  * so withCacheLookup/withCacheStore treat the WHOLE matched route as a
  * cache() boundary — the shell entry IS a cache() of the handler layer, with
- * loaders as the live carve-outs (resolveFreshLoadersAndYield).
+ * loaders as the live carve-outs (serveStoredSegments).
  *
  * A document HIT tail (`docTail`) always gets the implicit scope: it replays
  * the shell's own record and never consults a route-derived scope, whose