@rangojs/router 0.17.0 → 0.19.0

package/src/rsc/rsc-rendering.ts

@@ -5,6 +5,7 @@
  * (initial page load) requests.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import {
   getRequestContext,
   setRequestContextParams,
@@ -13,15 +14,20 @@ import {
 } from "../server/request-context.js";
 import {
   SeededShellStore,
+  ShellRecordUnavailableError,
   buildShellLoaderSeed,
+  countSnapshotFamilies,
+  hasDocRecord,
 } from "../cache/shell-snapshot.js";
 import { appendMetric } from "../router/metrics.js";
+import type { MetricsStore } from "../server/context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import type { TraceSpan } from "../router/tracing.js";
 import { getSSRSetup, createSsrHtmlStage, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import type { SSRModule } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import type { PprReplayBypassReason } from "./shell-capture-constants.js";
 import {
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
@@ -42,9 +48,12 @@ import {
   type RoutinePlan,
 } from "./routine-plan.js";
 import type { HandlerContext } from "./handler-context.js";
-import { gateTransitions } from "./transition-gate.js";
+import { attachTransitionWhen } from "./attach-transition-when.js";
+import { publicRouteName } from "../route-name.js";
 import { buildFullPayload } from "./full-payload.js";
 import {
+  capShellWindow,
+  lastStoredCaptureSeq,
   scheduleShellCapture,
   resolveShellCaptureDebugSink,
   takeCaptureDebugEventForTiming,
@@ -59,7 +68,15 @@ import {
   shellSearchSeed,
   isValidShellHit,
   hasIntactShellPayload,
-  base64ToBytes,
+  openShellDocument,
+  navigationShellKey,
+  partitionShellKey,
+  inlineShellScript,
+  shellReloadScript,
+  partitionBuildShellCheckDone,
+  notePartitionBuildShellCheck,
+  warnPprWindowCappedOnce,
+  SHELL_PRELUDE_CHUNK_BYTES,
   hasShellFamily,
   warnShellStoreMissingOnce,
   warnPprNonceActiveOnce,
@@ -67,13 +84,19 @@ import {
   publishShellTailTiming,
   takeShellTailTimingForServerTiming,
   type ResolvedPprConfig,
+  type ShellDocument,
   type ShellTailTiming,
 } from "./shell-serve.js";
 import {
+  hasBuildShell,
   lookupBuildShell,
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import {
+  resolveSwrWindow,
+  staleShellRecaptureDue,
+} from "../cache/cache-policy.js";
 import {
   getNavigationContextHeader,
   prerenderStoreShortCircuits,
@@ -88,13 +111,17 @@ import {
   safeSameOriginLanding,
 } from "../redirect-origin.js";
 import { nonce as nonceToken } from "./nonce.js";
+import { escapeJsonForScript } from "../escape-script.js";
+import { resolveShellPartition } from "../cache/cache-scope.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type {
-  DocumentShellCacheEntry,
   SegmentCacheStore,
   ShellCacheEntry,
+  ShellDocumentRead,
+  ShellEntryHead,
+  ShellReadStats,
   ShellSnapshotRecord,
 } from "../cache/types.js";
 import {
@@ -102,27 +129,6 @@ import {
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
 } from "../segment-fragments.js";
 
-type PprReplayBypassReason =
-  | "method"
-  | "dynamic"
-  | "nonce"
-  | "store-unavailable"
-  | "passive-read-unsupported"
-  | "no-navigation-context"
-  | "prerender-store"
-  | "intercept"
-  | "cache-disabled"
-  | "read-error"
-  | "no-entry"
-  | "invalid-version"
-  | "corrupt-entry"
-  | "handler-live-holes"
-  | "transition-when"
-  | "no-segment-snapshot"
-  | "snapshot-miss"
-  | "explicit-cache-hit"
-  | "stale-build-entry";
-
 type PprReplayStatus =
   | { outcome: "HIT"; freshness: "fresh" | "stale" }
   | { outcome: "BYPASS"; reason: PprReplayBypassReason };
@@ -143,13 +149,6 @@ function describePprReplayStatus(status: PprReplayStatus): string {
     : `bypass:${status.reason}`;
 }
 
-function buildNavigationShellKey(
-  url: URL,
-  filter?: SearchParamsFilter,
-): string {
-  return `${buildShellKey(url, filter)}:navigation`;
-}
-
 function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
@@ -173,7 +172,6 @@ function createShellCaptureDescriptor(
     tags: pprConfig.tags,
     captureTimeout: pprConfig.captureTimeout,
     store,
-    debug: INTERNAL_RANGO_DEBUG,
     maxSnapshotBytes: pprConfig.maxSnapshotBytes,
     debugSink: resolveShellCaptureDebugSink(ctx.router.debugShellCapture),
     navigationOnly,
@@ -186,8 +184,7 @@ function shouldHealReplayMiss(
   return (
     reason === undefined ||
     reason === "invalid-version" ||
-    reason === "corrupt-entry" ||
-    reason === "stale-build-entry"
+    reason === "corrupt-entry"
   );
 }
 
@@ -242,35 +239,11 @@ function replayableShellSnapshot(
   if (!entry.navigationOnly && !hasIntactShellPayload(entry)) {
     return { reason: "corrupt-entry" };
   }
-  if (entry.handlerLiveHoles) return { reason: "handler-live-holes" };
-  if (entry.transitionWhen) return { reason: "transition-when" };
-  // Eligibility requires the CANONICAL doc segment record (`docKey`), not just
-  // any segment record: captures under an explicit cache() scope also record
-  // that tier's reads/writes under keys a partial lookup can never resolve,
-  // and counting those declared entries "replayable" that then always missed
-  // (a timing-dependent snapshot-miss/no-segment-snapshot flip-flop). Entries
-  // captured before the field existed read as no-segment-snapshot and heal on
-  // recapture (pre-release, same treatment as the buildVersion field).
-  const docKey = entry.docKey;
-  const snapshot = entry.snapshot;
-  const hasDocRecord =
-    docKey !== undefined &&
-    snapshot?.some((record) => {
-      if (
-        !record ||
-        typeof record !== "object" ||
-        record.family !== "segment" ||
-        record.key !== docKey ||
-        typeof record.value !== "object" ||
-        record.value === null
-      ) {
-        return false;
-      }
-      const segments = (record.value as { segments?: unknown }).segments;
-      return Array.isArray(segments) && segments.length > 0;
-    });
-  return hasDocRecord && snapshot
-    ? { snapshot }
+  // Eligibility requires the CANONICAL doc segment record (`docKey`): replay
+  // resolves that record and nothing else. An entry without it (a
+  // prerender-served capture, a tombstone) reads as no-segment-snapshot.
+  return hasDocRecord(entry.snapshot, entry.docKey)
+    ? { snapshot: entry.snapshot }
     : { reason: "no-segment-snapshot" };
 }
 
@@ -324,10 +297,11 @@ type PreparedRender =
   | {
       kind: "payload";
       payload: RscPayload;
-      hasInterceptSlots: boolean;
+      /** The response depends on the source page: an intercept targets the route. */
+      sourceScoped: boolean;
       pprReplayStatus?: PprReplayStatus;
-      partialCaptureNeeded: boolean;
-      partialCaptureKey?: string;
+      /** The key a navigation-only heal capture stores under, when one is needed. */
+      healKey?: string;
     };
 
 async function handleRscRenderingInner<TEnv>(
@@ -439,21 +413,47 @@ function* requestRenderPlan<TEnv>(
     response.headers.set(SHELL_STATUS_HEADER, "MISS");
   }
 
+  const healKey = prepared.healKey;
   if (
     isPartial &&
-    prepared.partialCaptureNeeded &&
+    healKey !== undefined &&
     !reqCtx._dynamic &&
     response.status === 200
   ) {
-    const captureKey = prepared.partialCaptureKey;
     yield* handoff("navigation-shell-capture", () =>
-      scheduleNavigationShellCapture(input, captureKey),
+      scheduleNavigationShellCapture(input, healKey),
     );
   }
 
   return response;
 }
 
+/**
+ * Dev: warn once per route when the route's cache() entry reduces an explicit
+ * ppr window. The window is what capShellWindow gives a capture from a
+ * record written just now, the widest it can get; null (a cache() ttl + swr
+ * of 0) is the capture's own warning.
+ */
+function warnIfPprWindowReduced(
+  routeName: string,
+  pprOption: { ttl?: number; swr?: number },
+  pprConfig: ResolvedPprConfig,
+  cacheScope: { ttl: number; swr: number | undefined },
+  store: SegmentCacheStore<any>,
+): void {
+  const cache = { ttl: cacheScope.ttl, swr: cacheScope.swr ?? 0 };
+  const shell = capShellWindow(
+    pprConfig.ttl,
+    resolveSwrWindow(pprConfig.swr, store.defaults),
+    {
+      freshUntil: cache.ttl * 1000,
+      staleUntil: (cache.ttl + cache.swr) * 1000,
+    },
+    0,
+  );
+  if (shell) warnPprWindowCappedOnce(routeName, pprOption, shell, cache);
+}
+
 /**
  * Axis 2 shell serve. Sync gates stay plan code; store and SSR effects run as
  * named steps. Outcomes: serve a composed shell response, report a MISS (the
@@ -474,36 +474,88 @@ function* shellServePlan<TEnv>(
   ) {
     return { kind: "pass" };
   }
-  const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
+  const manifestEntry = reqCtx._classifiedRoute?.manifestEntry;
+  const pprConfig = resolvePprConfig(manifestEntry);
   if (!pprConfig) return { kind: "pass" };
+  // A degraded HIT's reload (shellReloadScript) renders like a cache miss:
+  // no shell read, no capture, so it can never degrade again. The handler
+  // stripped the marker from the request and left this flag.
+  if (reqCtx._shellForcedMiss) return { kind: "pass" };
 
   // A per-request CSP nonce pins the route to axis 1: a shared shell would
   // freeze the capture request's nonce and CSP would reject it for every
-  // other visitor. BOTH nonce sources must gate — the createRouter({ nonce })
-  // provider (`nonce` param) and a middleware ctx.set(nonce, …) token write;
-  // the provider-only check missed the latter (issue #656).
-  const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
+  // other visitor. Every step below, a HIT included, therefore runs without
+  // one.
   const store = reqCtx._cacheStore;
-  const key = buildShellKey(url, reqCtx._searchParamsFilter);
-  mirrorPprServerTimingsForDev(key, reqCtx);
-  if (activeNonce !== undefined) {
+  const baseKey = buildShellKey(url, reqCtx._searchParamsFilter);
+  if (activeRequestNonce(nonce, reqCtx) !== undefined) {
     // Declared intent that cannot be honored deserves a diagnostic (unlike an
     // undeclared route, which is silent): a ppr route gated off by an active
     // per-request nonce warns once per key. Axis 1 after the warning.
-    warnPprNonceActiveOnce(key);
+    warnPprNonceActiveOnce(baseKey);
     return { kind: "pass" };
   }
   if (!hasShellFamily(store)) {
     // Declared intent that cannot be honored deserves a diagnostic (unlike an
     // undeclared route, which is silent). Axis 1 after the warning.
-    warnShellStoreMissingOnce(key);
+    warnShellStoreMissingOnce(baseKey);
     return { kind: "pass" };
   }
-
+  // The route's own cache() opt-out — cache(false), or a condition() that
+  // refuses THIS request — is absolute, and a HIT tail never consults the
+  // route scope (it replays the shell's doc record), so it is decided here,
+  // before any shell byte: the request renders like a cache miss (axis 1) and
+  // schedules no capture (the capture could not record the handler layer).
+  const route = classifiedRouteSnapshot(reqCtx);
+  if (route?.cacheScope && !route.cacheScope.allowsCache("read")) {
+    return { kind: "pass" };
+  }
+  // The shell is capped to the route cache() entry it captures from
+  // (capShellWindow); an explicit ppr window the cap reduces warns in dev.
+  // resolvePprConfig returned a config, so the entry is a ppr route.
+  const pprOption = manifestEntry?.type === "route" && manifestEntry.ppr;
+  if (
+    process.env.NODE_ENV !== "production" &&
+    route?.cacheScope?.enabled &&
+    typeof pprOption === "object" &&
+    (pprOption.ttl !== undefined || pprOption.swr !== undefined)
+  ) {
+    warnIfPprWindowReduced(
+      reqCtx._classifiedRoute?.routeKey ?? url.pathname,
+      pprOption,
+      pprConfig,
+      route.cacheScope,
+      store,
+    );
+  }
+  // A route whose cache() record is partitioned by the request (its `key()`,
+  // or the store's keyGenerator) partitions its shell the same way: each
+  // partition captures and serves its own shell. A failed key resolution
+  // serves no shell, never another partition's.
+  const requestKey = resolveRequestShellKey(
+    baseKey,
+    route,
+    store,
+    reqCtx,
+    "ShellServe",
+  );
+  const key =
+    typeof requestKey === "string"
+      ? requestKey
+      : yield* step("shell-partition", () => requestKey);
+  if (key === undefined) return { kind: "pass" };
+  reqCtx._shellKey = key;
+  // The buffered capture and tail timings are keyed by the partitioned key.
+  mirrorPprServerTimings(key, reqCtx);
+
+  // A MISS schedules its capture after rendering: taken before the read, this
+  // lets that capture skip itself when another request's capture stored the
+  // shell in between (ShellCaptureDescriptor.storedSeqAtRead).
+  const storedSeqAtRead = lastStoredCaptureSeq(key);
   // SSR setup starts before route handling, so read the shell before joining it
   // to overlap the remaining setup work with cache I/O.
   const cached = yield* step("shell-read", () =>
-    readShellEntry(store, key, reqCtx),
+    readShellEntry(store, key, reqCtx, pprConfig.tags),
   );
 
   // allReady (ssr.resolveStreaming) bypasses PPR entirely: buffering defeats
@@ -527,13 +579,26 @@ function* shellServePlan<TEnv>(
     pprConfig,
     store,
   );
+  // MISS (no entry, invalid reactVersion, a tombstone, or store read
+  // failure): axis 1 + a background capture scheduled once the response is
+  // known servable.
+  const miss: ShellServeOutcome = {
+    kind: "miss",
+    descriptor: { ...descriptor, storedSeqAtRead },
+    ssrModule,
+  };
 
+  // A HIT replays the handler layer from the entry's doc record (`docKey`),
+  // or, for a Prerender route, from the prerender store. An entry that has
+  // neither is a MISS: serving it would run handlers after the commit.
   if (
     cached &&
     !cached.entry.navigationOnly &&
+    (cached.entry.docKey !== undefined || route?.matched?.pr === true) &&
     isValidShellHit(cached.entry, ctx.version)
   ) {
-    if (!hasIntactShellPayload(cached.entry)) {
+    const document = openShellDocumentMetered(reqCtx, cached);
+    if (!document) {
       // Corrupt stored payload (undecodable prelude / unparseable
       // postponed): a store-layer fault worth a diagnostic, unlike the
       // silent version-mismatch lifecycle misses above. Degrade to MISS
@@ -548,8 +613,12 @@ function* shellServePlan<TEnv>(
       );
     } else {
       // Stale (SWR) hit: serve the stale shell now, recapture in the
-      // background (stampede-guarded + backoff inside scheduleShellCapture).
-      if (cached.shouldRevalidate) {
+      // background (stampede-guarded + backoff inside scheduleShellCapture),
+      // at most once per SHELL_MIN_RECAPTURE_INTERVAL_MS of the shell's age.
+      if (
+        cached.shouldRevalidate &&
+        staleShellRecaptureDue(cached.entry, Date.now())
+      ) {
         yield* handoff("shell-recapture", () =>
           scheduleShellCapture(
             ctx,
@@ -562,7 +631,6 @@ function* shellServePlan<TEnv>(
           ),
         );
       }
-      const entry = cached.entry;
       const response = yield* step("shell-hit", () =>
         serveShellHit(
           ctx,
@@ -572,7 +640,7 @@ function* shellServePlan<TEnv>(
           reqCtx,
           handleStore,
           ssrModule,
-          entry,
+          document,
           descriptor,
         ),
       );
@@ -580,26 +648,63 @@ function* shellServePlan<TEnv>(
     }
   }
 
+  // A runtime tombstone (degradeUnreplayableShell: this key's HIT could not
+  // replay its handler layer) shadows the build shell too, or a build shell
+  // whose tail cannot be replayed would degrade on every request until a
+  // runtime capture lands.
+  if (
+    cached?.entry.navigationOnly &&
+    isValidShellHit(cached.entry, ctx.version)
+  ) {
+    return miss;
+  }
+
   // Build-time shell read-through (producer B, #699): on a runtime
   // store MISS a Prerender+ppr route serves its `vite build`-baked
-  // shell through the SAME serve path. lookupBuildShell owns every
-  // gate and fails to null (ordinary MISS path takes over); past
-  // ppr.ttl the baked entry still serves while SWR recaptures — the
-  // upgrade path from build entry to runtime entry.
-  const buildHit = yield* step("build-shell-lookup", () =>
-    lookupBuildShell(
-      url,
-      ctx.version,
-      store,
-      // Dev: no build manifest exists; producer B runs on demand via
-      // the dev server's /__rsc_shell endpoint for PRERENDERED routes
-      // only (production's exact candidate set). Folded away in
-      // production builds (NODE_ENV is a compile-time constant).
-      resolveDevShellLookup(reqCtx, pprConfig),
-      reqCtx._searchParamsFilter,
-    ),
-  );
-  if (buildHit) {
+  // shell through the SAME serve path. A partitioned route has none: the
+  // build captured one partition, which no request may be assumed to
+  // share, and a route that has a build shell says so once. lookupBuildShell
+  // owns the validity gates and fails to null; openShellDocument below is
+  // the prelude's integrity check and only decode (either failing leaves the
+  // ordinary MISS path); past ppr.ttl the baked entry still serves while SWR
+  // recaptures — the upgrade path from build entry to runtime entry.
+  //
+  // Dev: no build manifest exists; producer B runs on demand via the dev
+  // server's /__rsc_shell endpoint for PRERENDERED routes only (production's
+  // exact candidate set). Folded away in production builds (NODE_ENV is a
+  // compile-time constant).
+  const devShellLookup = resolveDevShellLookup(reqCtx, pprConfig);
+  let buildHit: Awaited<ReturnType<typeof lookupBuildShell>> = null;
+  if (key !== baseKey) {
+    // Probed once per path without a build shell, and not again once the
+    // route warned. A search-bearing URL never reads one: nothing to probe.
+    const routeName = reqCtx._classifiedRoute?.routeKey;
+    if (
+      !partitionBuildShellCheckDone(url.pathname, routeName) &&
+      shellSearchSeed(url, reqCtx._searchParamsFilter) === ""
+    ) {
+      const found = yield* step("build-shell-check", () =>
+        hasBuildShell(url.pathname, devShellLookup),
+      );
+      notePartitionBuildShellCheck(url.pathname, routeName, found);
+    }
+  } else {
+    buildHit = yield* step("build-shell-lookup", () =>
+      lookupBuildShell(
+        url,
+        ctx.version,
+        store,
+        devShellLookup,
+        reqCtx._searchParamsFilter,
+      ),
+    );
+  }
+  // The document serve decodes the baked prelude once here; an undecodable
+  // one is a MISS like a corrupt runtime entry.
+  const buildDocument = buildHit
+    ? openShellDocumentMetered(reqCtx, { entry: buildHit.entry })
+    : null;
+  if (buildHit && buildDocument) {
     // Past ppr.ttl: still serve the baked entry, recapture upgrades it.
     if (buildHit.stale) {
       yield* handoff("shell-recapture", () =>
@@ -623,16 +728,14 @@ function* shellServePlan<TEnv>(
         reqCtx,
         handleStore,
         ssrModule,
-        buildHit.entry,
+        buildDocument,
         descriptor,
       ),
     );
     return { kind: "serve", response };
   }
 
-  // MISS (no entry, invalid reactVersion, or store read failure): axis 1
-  // + a background capture scheduled once the response is known servable.
-  return { kind: "miss", descriptor, ssrModule };
+  return miss;
 }
 
 /**
@@ -652,10 +755,7 @@ function* preparePayloadPlan<TEnv>(
     );
     const result = replay.result;
     const pprReplayStatus = replay.status;
-    const partialCaptureNeeded =
-      "captureNeeded" in replay && replay.captureNeeded === true;
-    const partialCaptureKey =
-      "captureKey" in replay ? replay.captureKey : undefined;
+    const healKey = "healKey" in replay ? replay.healKey : undefined;
 
     if (!result) {
       // Fall back to full render
@@ -684,10 +784,9 @@ function* preparePayloadPlan<TEnv>(
       return {
         kind: "payload",
         payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
-        hasInterceptSlots: false,
+        sourceScoped: false,
         pprReplayStatus,
-        partialCaptureNeeded,
-        partialCaptureKey,
+        healKey,
       };
     }
 
@@ -702,15 +801,12 @@ function* preparePayloadPlan<TEnv>(
           // intercepted server-side (X-RSC-Reload) and never delivers a
           // different-router payload to the client.
           routerId: ctx.router.id,
-          segments: gateTransitions(
-            result.segments,
-            reqCtx,
-            ctx.router.onError,
-          ),
+          segments: attachTransitionWhen(result.segments, reqCtx),
           matched: result.matched,
           diff: result.diff,
           resolvedIds: result.resolvedIds,
           params: result.params,
+          routeName: publicRouteName(result.routeName),
           isPartial: true,
           slots: result.slots,
           interceptTargets: result.interceptTargets,
@@ -723,10 +819,9 @@ function* preparePayloadPlan<TEnv>(
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       },
-      hasInterceptSlots: !!result.slots,
+      sourceScoped: result.interceptTargeted === true,
       pprReplayStatus,
-      partialCaptureNeeded,
-      partialCaptureKey,
+      healKey,
     };
   }
 
@@ -745,14 +840,10 @@ function* preparePayloadPlan<TEnv>(
     };
   }
 
-  // Caching is now handled in router.match() via cache provider in request context
-  // match.segments already contains cached or fresh segments as appropriate
-
   return {
     kind: "payload",
     payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
-    hasInterceptSlots: false,
-    partialCaptureNeeded: false,
+    sourceScoped: false,
   };
 }
 
@@ -782,53 +873,227 @@ async function matchPartialAndRecordParams<TEnv>(
   return replay;
 }
 
+/**
+ * A document serve's store read: a getShell entry, or a prelude-first read
+ * (readShellDocument) whose entry is the head and whose snapshot arrives on
+ * its own promise.
+ */
+type ShellStoreRead =
+  | { entry: ShellCacheEntry; shouldRevalidate?: boolean; read?: undefined }
+  | {
+      entry: ShellEntryHead;
+      shouldRevalidate?: boolean;
+      read: ShellDocumentRead;
+    };
+
 /**
  * Shell store read that degrades to null on failure (axis 1 MISS, never a 500)
  * and records the raw `ppr:shell-read` outcome (pre-validity-gates, so a
  * version-mismatch lifecycle miss stays distinguishable from a store miss).
+ * A store with a prelude-first read (readShellDocument) resolves before the
+ * snapshot is read, so the HIT commits without waiting for it.
  */
-async function readShellEntry<
-  TStore extends { getShell(key: string): Promise<unknown> },
->(
-  store: TStore,
+async function readShellEntry(
+  store: SegmentCacheStore & {
+    getShell: NonNullable<SegmentCacheStore["getShell"]>;
+  },
   key: string,
   reqCtx: ReturnType<typeof getRequestContext>,
-): Promise<Awaited<ReturnType<TStore["getShell"]>> | null> {
-  let cached: Awaited<ReturnType<TStore["getShell"]>> | null = null;
+  tagHints: readonly string[] | undefined,
+): Promise<ShellStoreRead | null> {
+  let cached: ShellStoreRead | null = null;
   const shellReadStart = reqCtx._metricsStore ? performance.now() : 0;
   try {
-    // The constraint types the call as Promise<unknown>; the instantiated
-    // TStore carries the real entry type, so the assertion restores it.
-    cached = (await store.getShell(key)) as Awaited<
-      ReturnType<TStore["getShell"]>
-    >;
+    if (store.readShellDocument) {
+      const read = await store.readShellDocument(
+        key,
+        tagHints ? { tagHints } : undefined,
+      );
+      cached = read
+        ? { entry: read.entry, shouldRevalidate: read.shouldRevalidate, read }
+        : null;
+    } else {
+      cached = await store.getShell(key);
+    }
   } catch (error) {
     reportCacheError(error, "cache-read", "[ShellServe] getShell");
   }
   if (reqCtx._metricsStore) {
+    const stats = cached?.read?.stats;
     appendMetric(
       reqCtx._metricsStore,
       "ppr:shell-read",
       shellReadStart,
       performance.now() - shellReadStart,
       undefined,
-      cached ? "hit" : "miss",
+      cached ? (stats ? `hit ${stats.tier}` : "hit") : "miss",
     );
+    if (stats)
+      recordShellReadStats(reqCtx._metricsStore, shellReadStart, stats);
   }
   return cached;
 }
 
 /**
- * Dev Server-Timing mirror (issue #651): a capture completes AFTER its
- * triggering response committed, so its outcome can only ride a LATER
- * response's header. Read-and-clear keeps one capture = one report;
- * dev-only (see takeCaptureDebugEventForTiming).
+ * A prelude-first read's sub-steps as `debugPerformance` rows under
+ * `ppr:shell-read`. The marker row starts with the prelude row because the
+ * two run in parallel; its desc says how long the read still waited on the
+ * marker once the prelude was in. On a deployed worker the clock only
+ * advances on I/O, so the byte counts are the cost signal for the CPU parts.
+ */
+function recordShellReadStats(
+  store: MetricsStore,
+  readStart: number,
+  stats: ShellReadStats,
+): void {
+  let at = readStart;
+  const row = (label: string, ms: number | undefined, desc: string): void => {
+    if (ms !== undefined) appendMetric(store, label, at, ms, 1, desc);
+  };
+  if (stats.memo) {
+    row(
+      "ppr:shell-memo",
+      0,
+      `${stats.memo.hit ? "hit" : "miss"} size=${stats.memo.bytes}b`,
+    );
+  }
+  // A KV hit after an L1 miss: the L1 attempt first, then the KV read.
+  row("ppr:shell-l1-miss", stats.l1MissMs, stats.l1MissReason ?? "miss");
+  at += stats.l1MissMs ?? 0;
+  row("ppr:shell-match", stats.matchMs, stats.tier);
+  at += stats.matchMs ?? 0;
+  row("ppr:shell-head", stats.headMs, `bytes=${stats.headBytes ?? 0}`);
+  at += stats.headMs ?? 0;
+  row("ppr:shell-prelude", stats.preludeMs, `bytes=${stats.preludeBytes ?? 0}`);
+  let marker = `tags=${stats.tags ?? 0} ${stats.markerSerial ? "serial" : "parallel"} commit-wait=${(stats.markerWaitMs ?? 0).toFixed(2)}ms`;
+  if (stats.markerMemo) marker += ` memo=${stats.markerMemo}`;
+  if (stats.markerHinted) {
+    marker += ` hint=${stats.markerHintHits ?? 0}/${stats.markerHinted.length}`;
+    if (stats.markerLeadMs !== undefined) {
+      marker += ` lead=${stats.markerLeadMs.toFixed(2)}ms`;
+    }
+  }
+  if (stats.freshReads) marker += " fresh-reads";
+  row("ppr:shell-marker", stats.markerMs, marker);
+}
+
+/**
+ * openShellDocument (the HIT's integrity gate and only prelude decode) as a
+ * `ppr:shell-open` row: CPU only, so it reads 0 on a deployed worker.
+ */
+function openShellDocumentMetered(
+  reqCtx: RequestContext<any>,
+  stored: ShellStoreRead,
+): ShellDocument | null {
+  const read = stored.read;
+  const open = (): ShellDocument | null =>
+    stored.read
+      ? openShellDocument(stored.entry, stored.read)
+      : openShellDocument(stored.entry);
+  const store = reqCtx._metricsStore;
+  if (!store) return open();
+  const start = performance.now();
+  const document = open();
+  appendMetric(
+    store,
+    "ppr:shell-open",
+    start,
+    performance.now() - start,
+    undefined,
+    `cpu ${read ? "raw" : "base64-decode"} prelude=${document?.prelude.length ?? 0}b`,
+  );
+  return document;
+}
+
+/**
+ * The request's per-request CSP nonce. BOTH sources count: the
+ * createRouter({ nonce }) provider (`nonce`) and a middleware
+ * ctx.set(nonce, …) token write; the provider-only check missed the latter
+ * (issue #656). Read at the commit point, after the whole middleware chain.
+ */
+function activeRequestNonce(
+  nonce: string | undefined,
+  reqCtx: RequestContext<any>,
+): string | undefined {
+  return nonce ?? contextGet(reqCtx._variables, nonceToken);
+}
+
+/**
+ * The shell key a request reads and captures: `baseKey`, partitioned by the
+ * route's request partition (cache-scope.ts resolveShellPartition; a
+ * partition equal to the default key leaves it unchanged). `baseKey` itself,
+ * synchronously and with no work, when nothing partitions the route; else a
+ * promise that resolves undefined when the key failed to resolve (reported
+ * as `[source] shell key`): such a request reads and captures no shell,
+ * never another partition's.
+ */
+function resolveRequestShellKey(
+  baseKey: string,
+  route: RouteSnapshot<any> | null,
+  store: SegmentCacheStore,
+  reqCtx: RequestContext<any>,
+  source: string,
+): string | Promise<string | undefined> {
+  const partition = resolveShellPartition(
+    route?.cacheScope,
+    store,
+    reqCtx.url.pathname,
+    route?.params,
+  );
+  if (!partition) return baseKey;
+  return partition.then(
+    (resolved) =>
+      resolved === null ? baseKey : partitionShellKey(baseKey, resolved),
+    (error: unknown) => {
+      reportCacheError(error, "cache-read", `[${source}] shell key`);
+      return undefined;
+    },
+  );
+}
+
+/**
+ * Observe the explicit-scope composition in withCacheLookup: the route's own
+ * cache() scope served the request (`explicit-cache-hit`) or refused it at
+ * lookup time (`cache-disabled`). The two are exclusive per lookup, and
+ * neither fires when the seeded doc record served.
+ */
+function observeExplicitScope(): {
+  onExplicitHit: () => void;
+  onExplicitBypass: () => void;
+  bypassed: () => boolean;
+  status: (otherwise: PprReplayStatus) => PprReplayStatus;
+} {
+  let observed: "hit" | "bypass" | undefined;
+  return {
+    onExplicitHit: () => {
+      observed = "hit";
+    },
+    onExplicitBypass: () => {
+      observed = "bypass";
+    },
+    bypassed: () => observed === "bypass",
+    status: (otherwise) =>
+      observed === "hit"
+        ? { outcome: "BYPASS", reason: "explicit-cache-hit" }
+        : observed === "bypass"
+          ? { outcome: "BYPASS", reason: "cache-disabled" }
+          : otherwise,
+  };
+}
+
+/**
+ * Server-Timing mirror (issue #651): a capture or a HIT tail completes AFTER
+ * its triggering response committed, so its numbers can only ride a LATER
+ * response's header. Read-and-clear keeps one report per run. The capture
+ * half is dev-only (see takeCaptureDebugEventForTiming); the tail half runs
+ * wherever a tail was buffered (serveShellHit).
  */
-function mirrorPprServerTimingsForDev(
+function mirrorPprServerTimings(
   key: string,
   reqCtx: ReturnType<typeof getRequestContext>,
 ): void {
-  if (process.env.NODE_ENV !== "production" && reqCtx._metricsStore) {
+  if (!reqCtx._metricsStore) return;
+  if (process.env.NODE_ENV !== "production") {
     const lastCapture = takeCaptureDebugEventForTiming(key);
     if (lastCapture) {
       appendMetric(
@@ -841,22 +1106,23 @@ function mirrorPprServerTimingsForDev(
         describeShellCaptureEvent({ ...lastCapture, attemptMs: undefined }),
       );
     }
-    // Same mirror for the previous HIT's tail: its per-stage numbers
-    // (seed/match/handover/first-html/complete) finished after that
-    // response's headers were committed, so they ride THIS request's
-    // Server-Timing as `ppr:tail;dur=<complete ms>`.
-    const lastTail = takeShellTailTimingForServerTiming(key);
-    if (lastTail) {
-      appendMetric(
-        reqCtx._metricsStore,
-        "ppr:tail",
-        performance.now(),
-        lastTail.completeMs ?? 0,
-        undefined,
-        // completeMs already rides as this entry's dur — drop it from desc.
-        describeShellTailTiming({ ...lastTail, completeMs: undefined }),
-      );
-    }
+  }
+  // Same mirror for the previous HIT's tail: its per-stage numbers
+  // (snapshot/seed/match/handover/first-html/complete) finished after that
+  // response's headers were committed, so they ride THIS request's
+  // Server-Timing as `ppr:tail;dur=<complete ms>`. In production a tail is
+  // buffered only when its own HIT collected metrics (serveShellHit).
+  const lastTail = takeShellTailTimingForServerTiming(key);
+  if (lastTail) {
+    appendMetric(
+      reqCtx._metricsStore,
+      "ppr:tail",
+      performance.now(),
+      lastTail.completeMs ?? 0,
+      undefined,
+      // completeMs already rides as this entry's dur — drop it from desc.
+      describeShellTailTiming({ ...lastTail, completeMs: undefined }),
+    );
   }
 }
 
@@ -867,7 +1133,7 @@ function renderPreparedRscResponse<TEnv>(
 ): Promise<Response> {
   const { ctx, request, env, url, isPartial, nonce, reqCtx, renderSpan } =
     input;
-  const { payload, pprReplayStatus, hasInterceptSlots } = prepared;
+  const { payload, pprReplayStatus, sourceScoped } = prepared;
   const metricsStore = reqCtx._metricsStore;
 
   const rscHeaders: Record<string, string> = {
@@ -884,18 +1150,20 @@ function renderPreparedRscResponse<TEnv>(
       serializePprReplayStatus(pprReplayStatus);
   }
   // Tell the client's prefetch cache to scope this response to its source
-  // URL (instead of the default source-agnostic wildcard). Intercept
-  // responses depend on the source page matching an intercept rule, so
-  // they must not be reused for navigations from other sources.
-  if (hasInterceptSlots) {
+  // URL (instead of the default source-agnostic wildcard). A route an
+  // intercept targets renders the modal or the full page depending on the
+  // source, so neither response may be reused from another source: a full
+  // page prefetched where the intercept does not apply would otherwise
+  // serve a later click where it does (#1007).
+  if (sourceScoped) {
     rscHeaders["x-rsc-prefetch-scope"] = "source";
   }
   // Enable browser HTTP caching for prefetch responses only.
   // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
-  // non-intercept context (intercept responses depend on source page),
-  // and a configured cache-control value (false disables caching).
-  const isPrefetch = request.headers.has("X-Rango-Prefetch");
-  if (isPrefetch && isPartial && !hasInterceptSlots) {
+  // a source-agnostic response (see sourceScoped above), and a configured
+  // cache-control value (false disables caching).
+  const isPrefetch = requestHeaders(request).has("X-Rango-Prefetch");
+  if (isPrefetch && isPartial && !sourceScoped) {
     const cc = ctx.router.prefetchCacheControl;
     if (cc) {
       rscHeaders["cache-control"] = cc;
@@ -944,7 +1212,7 @@ function renderPreparedRscResponse<TEnv>(
  */
 function scheduleNavigationShellCapture<TEnv>(
   input: RequestRenderInput<TEnv>,
-  partialCaptureKey: string | undefined,
+  captureKey: string,
 ): void {
   const { ctx, request, env, url, reqCtx } = input;
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry)!;
@@ -967,8 +1235,7 @@ function scheduleNavigationShellCapture<TEnv>(
     },
     createShellCaptureDescriptor(
       ctx,
-      partialCaptureKey ??
-        buildNavigationShellKey(url, reqCtx._searchParamsFilter),
+      captureKey,
       shellSearchSeed(url, reqCtx._searchParamsFilter),
       url.origin,
       pprConfig,
@@ -981,10 +1248,11 @@ function scheduleNavigationShellCapture<TEnv>(
 /**
  * Reuse a PPR capture's canonical segment record for a partial navigation.
  * The ordinary matchPartial pipeline remains authoritative: it projects the
- * cached target tree against the client's segment ids, evaluates revalidation,
- * and resolves every loader fresh. Only segment-family records are seeded;
- * captured item/response/loader values belong to document parity and must not
- * pin navigation data.
+ * cached target tree against the client's segment ids and evaluates
+ * revalidation. Only the segment family is seeded into the store overlay, so
+ * item and response reads stay live; a record that served also arms the
+ * bake-lane loader pins (onHit), which serve as on a document HIT, while live
+ * loaders run fresh.
  */
 async function matchPartialWithPprReplay<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -1041,7 +1309,7 @@ async function matchPartialWithPprReplay<TEnv>(
     return { result, status: finalStatus };
   };
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
-  const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
+  const activeNonce = activeRequestNonce(nonce, reqCtx);
   const store = reqCtx._cacheStore;
 
   if (!pprConfig) return runMatch();
@@ -1077,8 +1345,8 @@ async function matchPartialWithPprReplay<TEnv>(
   // one-shot corruption recovery request still replay the same segment record,
   // but through the server decode path.
   armFragments =
-    request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) !== "1" &&
-    request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1";
+    requestHeaders(request).get(SEGMENT_FRAGMENT_RECOVERY_HEADER) !== "1" &&
+    requestHeaders(request).get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1";
   // The prerender probe and the cache-opt-out gate below both need the
   // classified snapshot; resolve (and persist) it once.
   const routeSnapshot = classifiedRouteSnapshot(reqCtx);
@@ -1127,8 +1395,19 @@ async function matchPartialWithPprReplay<TEnv>(
     return runMatch({ outcome: "BYPASS", reason: "cache-disabled" });
   }
 
-  const key = buildShellKey(url, reqCtx._searchParamsFilter);
-  const navigationKey = `${key}:navigation`;
+  // The visitor's own partition (resolveShellPartition): replay never
+  // crosses into another partition's shell.
+  const key = await resolveRequestShellKey(
+    buildShellKey(url, reqCtx._searchParamsFilter),
+    routeSnapshot,
+    store,
+    reqCtx,
+    "NavigationPPR",
+  );
+  if (key === undefined) {
+    return runMatch({ outcome: "BYPASS", reason: "read-error" });
+  }
+  const navigationKey = navigationShellKey(key);
   let cached: Awaited<ReturnType<typeof store.getShell>> = null;
   try {
     cached = await store.getShell(key, { claimRevalidation: false });
@@ -1152,11 +1431,7 @@ async function matchPartialWithPprReplay<TEnv>(
     }
   }
 
-  if (
-    !snapshot &&
-    bypassReason !== "handler-live-holes" &&
-    bypassReason !== "transition-when"
-  ) {
+  if (!snapshot) {
     let navigationCached: Awaited<ReturnType<typeof store.getShell>> = null;
     try {
       navigationCached = await store.getShell(navigationKey, {
@@ -1181,32 +1456,6 @@ async function matchPartialWithPprReplay<TEnv>(
     }
   }
 
-  if (!snapshot) {
-    // Production build manifests are local module data. In dev, resolving a
-    // missing build shell would foreground-fetch /__rsc_shell and block an
-    // otherwise ordinary navigation on capture, so replay remains runtime-only.
-    const buildHit = await lookupBuildShell(
-      url,
-      ctx.version,
-      store,
-      undefined,
-      reqCtx._searchParamsFilter,
-    );
-    if (buildHit?.stale) {
-      bypassReason ??= "stale-build-entry";
-    } else if (buildHit) {
-      const buildDecision = replayableShellSnapshot(
-        buildHit.entry,
-        ctx.version,
-      );
-      if ("snapshot" in buildDecision) {
-        snapshot = buildDecision.snapshot;
-      } else {
-        bypassReason ??= buildDecision.reason;
-      }
-    }
-  }
-
   if (!snapshot) {
     // Report-only marker for routes with an ENABLED route-derived scope: the
     // lookup's own outcome must stay reportable even without a replayable
@@ -1221,25 +1470,20 @@ async function matchPartialWithPprReplay<TEnv>(
     // implicit scope over the REAL doc: partition in
     // resolveShellImplicitCacheScope).
     if (routeCacheScope?.enabled) {
-      let explicitCacheHit = false;
-      let explicitCacheBypass = false;
+      const explicit = observeExplicitScope();
       const previousImplicitCache = reqCtx._shellImplicitCache;
       reqCtx._shellImplicitCache = {
-        onExplicitHit: () => {
-          explicitCacheHit = true;
-        },
-        onExplicitBypass: () => {
-          explicitCacheBypass = true;
-        },
+        onExplicitHit: explicit.onExplicitHit,
+        onExplicitBypass: explicit.onExplicitBypass,
       };
       try {
         const result = await matchPartialForReplay();
-        const provisionalStatus: PprReplayStatus = explicitCacheBypass
-          ? { outcome: "BYPASS", reason: "cache-disabled" }
-          : explicitCacheHit
-            ? { outcome: "BYPASS", reason: "explicit-cache-hit" }
-            : { outcome: "BYPASS", reason: bypassReason ?? "no-entry" };
-        const status = finalizeReplayStatus(provisionalStatus);
+        const status = finalizeReplayStatus(
+          explicit.status({
+            outcome: "BYPASS",
+            reason: bypassReason ?? "no-entry",
+          }),
+        );
         return {
           result,
           status,
@@ -1253,12 +1497,14 @@ async function matchPartialWithPprReplay<TEnv>(
           // capture derives from THIS request's context, so its doc record
           // records. Excluding it left replay dead until the document
           // recaptured. The always-false route stays protected: its every
-          // lookup refuses, so explicitCacheBypass suppresses the heal.
-          captureNeeded:
-            !explicitCacheBypass &&
+          // lookup refuses, so its bypass suppresses the heal.
+          healKey:
+            !explicit.bypassed() &&
             reqCtx._pprReplayPostMatchReason === undefined &&
             (shouldHealReplayMiss(bypassReason) ||
-              bypassReason === "no-segment-snapshot"),
+              bypassReason === "no-segment-snapshot")
+              ? navigationKey
+              : undefined,
         };
       } finally {
         reqCtx._shellImplicitCache = previousImplicitCache;
@@ -1270,26 +1516,37 @@ async function matchPartialWithPprReplay<TEnv>(
     });
     return {
       ...match,
-      captureNeeded:
+      healKey:
         reqCtx._pprReplayPostMatchReason === undefined &&
-        shouldHealReplayMiss(bypassReason),
+        shouldHealReplayMiss(bypassReason)
+          ? navigationKey
+          : undefined,
     };
   }
 
   const previousImplicitCache = reqCtx._shellImplicitCache;
+  const previousLoaderSeed = reqCtx._shellLoaderSeed;
+  let loaderSeed: ReturnType<typeof buildShellLoaderSeed> | undefined;
   let segmentReplayHit = false;
   let segmentReplayCorrupt = false;
-  let explicitCacheHit = false;
-  let explicitCacheBypass = false;
+  const explicit = observeExplicitScope();
   reqCtx._shellImplicitCache = {
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
-    store: new SeededShellStore(store, snapshot, {
-      segmentsOnly: true,
-    }),
+    store: new SeededShellStore(store, snapshot),
     keyPrefix: "doc",
-    onHit: () => {
+    // Arms the bake-lane loader pins a document HIT serves (loader-cache.ts
+    // resolveLoaderData), decoded only now: the lookup awaits this before
+    // the route's loaders resolve, and an explicit-tier hit or a miss runs
+    // the loaders fresh and never reads a pin.
+    onHit: async () => {
       segmentReplayHit = true;
+      // Never rejects: the lookup awaits this inside its own try, and an
+      // unreadable seed leaves those loaders to run fresh.
+      const seed = await (loaderSeed ??= buildShellLoaderSeed(snapshot).catch(
+        () => undefined,
+      ));
+      if (seed) reqCtx._shellLoaderSeed = seed;
     },
     onCorrupt: () => {
       segmentReplayCorrupt = true;
@@ -1297,27 +1554,18 @@ async function matchPartialWithPprReplay<TEnv>(
     // Arms the explicit-scope composition in withCacheLookup: a route-derived
     // cache() scope stays authoritative, the seeded doc record supplies the
     // match only on its miss. An explicit-tier hit must NOT report a replay
-    // HIT — it served under the consumer's own semantics.
-    onExplicitHit: () => {
-      explicitCacheHit = true;
-    },
-    // Lookup-time condition() refusal (or a scope with no store): the gate
-    // deliberately does not pre-decide predicates, so the truthful
-    // cache-disabled report comes from the lookup that actually refused.
-    onExplicitBypass: () => {
-      explicitCacheBypass = true;
-    },
+    // HIT — it served under the consumer's own semantics. A lookup-time
+    // condition() refusal (or a scope with no store) reports cache-disabled:
+    // the gate deliberately does not pre-decide predicates.
+    onExplicitHit: explicit.onExplicitHit,
+    onExplicitBypass: explicit.onExplicitBypass,
   };
 
   try {
     const result = await matchPartialForReplay();
     const provisionalStatus: PprReplayStatus = segmentReplayHit
       ? { outcome: "HIT", freshness }
-      : explicitCacheHit
-        ? { outcome: "BYPASS", reason: "explicit-cache-hit" }
-        : explicitCacheBypass
-          ? { outcome: "BYPASS", reason: "cache-disabled" }
-          : { outcome: "BYPASS", reason: "snapshot-miss" };
+      : explicit.status({ outcome: "BYPASS", reason: "snapshot-miss" });
     // A prerender serve or intercept resolution leaves the seeded record
     // unconsulted (prerender short-circuits before the scope; intercepts
     // keep snapshot.cacheScope) — the "snapshot-miss" guess would blame the
@@ -1326,17 +1574,19 @@ async function matchPartialWithPprReplay<TEnv>(
     return {
       result,
       status,
-      captureNeeded:
-        segmentReplayCorrupt && reqCtx._pprReplayPostMatchReason === undefined,
       // A corrupt document snapshot must be overwritten at the document key;
       // writing only the secondary navigation key would leave the preferred
       // document entry shadowing the repair forever. The capture remains marked
       // navigationOnly, so a document request ignores it and recaptures a
       // document-safe shell under the same key.
-      captureKey: segmentReplayCorrupt ? snapshotStoreKey : undefined,
+      healKey:
+        segmentReplayCorrupt && reqCtx._pprReplayPostMatchReason === undefined
+          ? snapshotStoreKey
+          : undefined,
     };
   } finally {
     reqCtx._shellImplicitCache = previousImplicitCache;
+    reqCtx._shellLoaderSeed = previousLoaderSeed;
   }
 }
 
@@ -1381,6 +1631,76 @@ export function resolveShellHitRedirectTarget(
   );
 }
 
+/**
+ * Buffer a finished tail timing for the next request's Server-Timing, and
+ * under debugPerformance print it for this request (whose own Server-Timing
+ * was sent at the commit, before the tail ran).
+ */
+function publishTailTiming(
+  tailTiming: ShellTailTiming | null,
+  metricsStore: MetricsStore | undefined,
+  request: Request,
+  url: URL,
+): void {
+  if (!tailTiming) return;
+  publishShellTailTiming(tailTiming);
+  if (metricsStore) {
+    console.log(
+      `[RSC Perf] ${request.method} ${url.pathname} shell tail: ${describeShellTailTiming(tailTiming)}`,
+    );
+  }
+}
+
+const PENDING = Symbol("pending");
+
+/**
+ * Whether `value` is not a promise, or a promise that has already settled:
+ * racing it against an already-resolved promise, a settled one's reaction is
+ * queued first and wins.
+ */
+async function isSettled(value: unknown): Promise<boolean> {
+  if (!(value instanceof Promise)) return true;
+  return Promise.race([value, PENDING]).then(
+    (first) => first !== PENDING,
+    () => true,
+  );
+}
+
+/**
+ * Evict a shell whose doc record cannot be replayed. The store has no shell
+ * delete, so the entry is overwritten with a tombstone: a navigationOnly
+ * entry with no document half and no snapshot, which document serving
+ * treats as a MISS (shellServePlan, the build shell included) and partial
+ * replay as `no-segment-snapshot`. The recapture overwrites it with a sound
+ * entry. Only for a broken entry: a snapshot read that was merely slow
+ * (`snapshotFailure: "unavailable"`) leaves the entry alone.
+ */
+async function degradeUnreplayableShell(
+  descriptor: ShellCaptureDescriptor,
+  entry: ShellEntryHead,
+  scheduleRecapture: () => void,
+): Promise<void> {
+  const store = descriptor.store;
+  try {
+    await store?.putShell?.(
+      descriptor.key,
+      {
+        reactVersion: entry.reactVersion,
+        buildVersion: entry.buildVersion,
+        snapshot: [],
+        navigationOnly: true,
+        createdAt: Date.now(),
+      },
+      descriptor.ttl,
+      0,
+    );
+  } catch (error) {
+    reportCacheError(error, "cache-write", "[ShellServe] tombstone");
+  }
+  store?.dropShellMemo?.(descriptor.key);
+  scheduleRecapture();
+}
+
 /**
  * Serve a validated shell HIT: commit the stored prelude bytes NOW and run the
  * live tail behind them inside the response stream. Plain byte concatenation is
@@ -1398,15 +1718,17 @@ function serveShellHit(
   reqCtx: RequestContext<any>,
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   ssrModule: SSRModule,
-  entry: DocumentShellCacheEntry,
+  document: ShellDocument,
   descriptor: ShellCaptureDescriptor,
 ): Response {
-  const preludeBytes = base64ToBytes(entry.prelude);
-  // Per-stage tail timing for the dev `ppr:tail` Server-Timing mirror. Dev
-  // only (NODE_ENV folds the branch away in production builds); offsets are
-  // relative to this commit point.
+  const { entry, prelude: preludeBytes } = document;
+  const metricsStore = reqCtx._metricsStore;
+  // Per-stage tail timing for the `ppr:tail` Server-Timing mirror and the
+  // perf console line: always in dev, in production only when this request
+  // collects debugPerformance metrics. Offsets are relative to this commit
+  // point.
   const tailTiming: ShellTailTiming | null =
-    process.env.NODE_ENV !== "production"
+    process.env.NODE_ENV !== "production" || metricsStore
       ? {
           key: descriptor.key,
           outcome: "complete",
@@ -1414,6 +1736,8 @@ function serveShellHit(
         }
       : null;
   const tailT0 = tailTiming ? performance.now() : 0;
+  const scheduleRecapture = (): void =>
+    scheduleShellCapture(ctx, request, env, url, reqCtx, ssrModule, descriptor);
 
   const createTailContext = (): RequestContext<any> => {
     const tailCtx: RequestContext<any> = Object.create(reqCtx);
@@ -1486,7 +1810,7 @@ function serveShellHit(
     }
     return observePhase(PHASES.ssr, () =>
       ssrModule.resumeShellHTML!(rscStream, {
-        postponed: entry.postponed,
+        postponed: document.postponed,
         nonce: undefined,
         // The shell key's own search — identical to the capture seed for
         // this key, so the resume tree matches the captured tree.
@@ -1505,68 +1829,77 @@ function serveShellHit(
     ReadableStream<Uint8Array> | { redirect: string }
   > = (async () => {
     // Snapshot seeding (docs/design/ppr-shell-resume.md): the tail render must
-    // match the frozen prelude, so pinned cache reads replay their capture-time
-    // values via a SeededShellStore overlay while unpinned reads (the holes)
-    // stay live. The overlay lives on a DERIVED context so the shared reqCtx is
-    // untouched.
-    if (entry.snapshot && entry.snapshot.length > 0) {
-      const seededCtx = createTailContext();
-      if (reqCtx._cacheStore) {
-        seededCtx._cacheStore = new SeededShellStore(
-          reqCtx._cacheStore,
-          entry.snapshot,
-        );
-      }
-      // Loader-family records (bake-lane containers, loader-container-bake):
-      // decode into a seed Map for the resolveLoaderData overlay, so the
-      // payload's baked container bytes match the frozen prelude while the
-      // hole-marker paths keep the fresh run's live nested promises.
-      const seedStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
-      const loaderSeed = await buildShellLoaderSeed(entry.snapshot);
-      if (tailTiming) {
-        tailTiming.seedMs = Math.round(performance.now() - tailT0);
-      }
-      if (INTERNAL_RANGO_DEBUG) {
-        console.log(
-          `[Server][ppr] shell HIT: loader seed built +${Math.round(performance.now() - seedStart)}ms (abs ${Math.round(performance.now())})`,
-        );
-      }
-      if (loaderSeed) seededCtx._shellLoaderSeed = loaderSeed;
-      // Shell fast path (serve side): if the capture recorded the implicit doc
-      // segment record and the handler layer declared no liveness, the tail's
-      // cache lookup HITs the seeded doc entry — the handler layer is REPLAYED,
-      // not re-executed (loaders still run fresh). Anything else degrades to
-      // the full tail automatically.
-      if (!entry.handlerLiveHoles && !entry.transitionWhen) {
-        seededCtx._shellImplicitCache = {
-          ttl: descriptor.ttl,
-          swr: descriptor.swr,
-          keyPrefix: "doc",
-        };
-        if (INTERNAL_RANGO_DEBUG) {
-          console.log(
-            `[Server][ppr] shell HIT: fast path armed (implicit doc cache) (abs ${Math.round(performance.now())})`,
-          );
-        }
-      } else if (INTERNAL_RANGO_DEBUG) {
-        console.log(
-          `[Server][ppr] shell HIT: fast path declined — request-dependent handler/transition state; tail re-runs handlers (abs ${Math.round(performance.now())})`,
-        );
+    // match the frozen prelude, so it replays the doc record and serves the
+    // bake-lane loader pins, on a DERIVED context so the shared reqCtx is
+    // untouched. Every cache read the tail makes, a hole's included, goes to
+    // the request's own store.
+    // A prelude-first read delivers the snapshot on its own promise: the
+    // prelude is already committed, so only the tail waits for it.
+    const inMemory = await isSettled(document.snapshot);
+    const snapshot = await document.snapshot;
+    // A snapshot already in memory (shell memo, memory store, build shells)
+    // resolves at once, and the tail's seeding and match would run ahead of
+    // the runtime writing the prelude: one macrotask first. A snapshot still
+    // arriving on I/O has yielded by the time it resolves.
+    if (inMemory) await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    if (tailTiming) {
+      tailTiming.snapshotMs = Math.round(performance.now() - tailT0);
+      if (snapshot)
+        tailTiming.snapshotRecords = countSnapshotFamilies(snapshot);
+      tailTiming.snapshotPruned = entry.prunedRecords;
+      const snapshotStats = document.stats?.snapshot;
+      if (snapshotStats) {
+        tailTiming.snapshotReadMs = Math.round(snapshotStats.readMs);
+        tailTiming.snapshotBytes = snapshotStats.bytes;
+        tailTiming.snapshotParseMs = Math.round(snapshotStats.parseMs);
       }
-      // Fragment splice (issue #700): store hits in THIS tail emit their stored
-      // segment fragments verbatim (expanded by segment-fragments.ts). The flag
-      // lives on the derived context so it can never leak into a capture render,
-      // which serializes segments and must see real elements.
-      seededCtx._shellFragmentPayload = true;
-      return runWithRequestContext(seededCtx, () => renderTail(seededCtx));
     }
-    // No snapshot (e.g. a producer B entry): still a shell-HIT tail, so arm the
-    // fragment splice on a derived context — never the shared reqCtx, from which
-    // scheduleShellCapture derives the capture context (the flag must not be
-    // inherited there).
-    const fragmentCtx = createTailContext();
-    fragmentCtx._shellFragmentPayload = true;
-    return runWithRequestContext(fragmentCtx, () => renderTail(fragmentCtx));
+    const seededCtx = createTailContext();
+    const records = snapshot ?? [];
+    // Loader-family records (bake-lane containers, loader-container-bake):
+    // decode into a seed Map for the resolveLoaderData overlay, so the
+    // payload's baked container bytes match the frozen prelude while the
+    // hole-marker paths keep the fresh run's live nested promises.
+    const seedStart =
+      INTERNAL_RANGO_DEBUG || tailTiming ? performance.now() : 0;
+    const loaderSeed =
+      records.length > 0 ? await buildShellLoaderSeed(records) : undefined;
+    if (tailTiming) {
+      const seededAt = performance.now();
+      tailTiming.seedMs = Math.round(seededAt - tailT0);
+      tailTiming.seedCpuMs = Math.round(seededAt - seedStart);
+    }
+    if (INTERNAL_RANGO_DEBUG) {
+      console.log(
+        `[Server][ppr] shell HIT: loader seed built +${Math.round(performance.now() - seedStart)}ms (abs ${Math.round(performance.now())})`,
+      );
+    }
+    if (loaderSeed) seededCtx._shellLoaderSeed = loaderSeed;
+    // The handler layer is REPLAYED from the entry's own doc record, never
+    // executed: the implicit doc scope replaces any route-derived scope
+    // (docTail), looks the record up by the key the capture wrote
+    // (fixedDocKey), and reads it from a segment-only overlay of the snapshot
+    // (the real store never holds a doc: record). A lookup that does not hit
+    // throws ShellRecordUnavailableError (withCacheLookup), handled by the
+    // degrade below. Live and promise-carrying bake-lane loaders still run
+    // fresh; a promise-free bake-lane loader is served from its pin
+    // (_shellLoaderSeed, loader-cache.ts). A Prerender route's tail takes
+    // the handler layer from the prerender store before this scope is
+    // consulted.
+    seededCtx._shellImplicitCache = {
+      ttl: descriptor.ttl,
+      swr: descriptor.swr,
+      store: new SeededShellStore(reqCtx._cacheStore!, records),
+      keyPrefix: "doc",
+      docTail: true,
+      fixedDocKey: entry.docKey,
+    };
+    // Fragment splice (issue #700): store hits in THIS tail emit their stored
+    // segment fragments verbatim (expanded by segment-fragments.ts). The flag
+    // lives on the derived context so it can never leak into a capture render,
+    // which serializes segments and must see real elements.
+    seededCtx._shellFragmentPayload = true;
+    return runWithRequestContext(seededCtx, () => renderTail(seededCtx));
   })();
   // The stream below is the only consumer; pre-attach a no-op catch so a tail
   // failure before the stream is pulled never surfaces as an unhandled rejection.
@@ -1575,7 +1908,31 @@ function serveShellHit(
   const serveStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
   const body = new ReadableStream<Uint8Array>({
     async start(controller) {
-      controller.enqueue(preludeBytes);
+      // Fixed-size chunks (SHELL_PRELUDE_CHUNK_BYTES): a compressor in front
+      // of the worker emits after each chunk instead of after the whole
+      // prelude. slice() gives every chunk its own buffer.
+      const commitStart = metricsStore ? performance.now() : 0;
+      let chunks = 0;
+      for (
+        let offset = 0;
+        offset < preludeBytes.length;
+        offset += SHELL_PRELUDE_CHUNK_BYTES
+      ) {
+        controller.enqueue(
+          preludeBytes.slice(offset, offset + SHELL_PRELUDE_CHUNK_BYTES),
+        );
+        chunks++;
+      }
+      if (metricsStore) {
+        appendMetric(
+          metricsStore,
+          "ppr:shell-commit",
+          commitStart,
+          performance.now() - commitStart,
+          undefined,
+          `cpu chunks=${chunks} prelude=${preludeBytes.length}b`,
+        );
+      }
       if (INTERNAL_RANGO_DEBUG) {
         console.log(
           `[Server][ppr] shell HIT: prelude enqueued (${preludeBytes.length}b) +${Math.round(performance.now() - serveStart)}ms`,
@@ -1647,7 +2004,9 @@ function serveShellHit(
           );
           controller.enqueue(
             new TextEncoder().encode(
-              `<script>location.replace(${JSON.stringify(safeTarget)})</script>`,
+              inlineShellScript(
+                `location.replace(${escapeJsonForScript(JSON.stringify(safeTarget))})`,
+              ),
             ),
           );
           if (tailTiming) {
@@ -1655,29 +2014,44 @@ function serveShellHit(
             tailTiming.completeMs = Math.round(performance.now() - tailT0);
           }
         }
-        if (tailTiming) publishShellTailTiming(tailTiming);
+        publishTailTiming(tailTiming, metricsStore, request, url);
         controller.close();
       } catch (error) {
+        if (error instanceof ShellRecordUnavailableError) {
+          // The doc record could not supply the handler layer, and running
+          // handlers behind a committed prelude is exactly what a HIT must
+          // never do: reload the page into a forced MISS. A broken entry is
+          // also replaced (tombstone, memo dropped, recapture); one whose
+          // snapshot read was only slow stays, and the next request reads it
+          // again.
+          if ((await document.snapshotFailure) !== "unavailable") {
+            await degradeUnreplayableShell(
+              descriptor,
+              entry,
+              scheduleRecapture,
+            );
+          }
+          controller.enqueue(new TextEncoder().encode(shellReloadScript()));
+          if (tailTiming) {
+            tailTiming.outcome = "error";
+            tailTiming.completeMs = Math.round(performance.now() - tailT0);
+          }
+          publishTailTiming(tailTiming, metricsStore, request, url);
+          controller.close();
+          return;
+        }
         // Self-heal on a failed tail: errors the pre-commit gates cannot catch
         // (mismatched postponed blob, hard render error above the holes) throw
         // here AFTER the 200 + prelude flushed and would re-fail on every
         // request until the entry ages out — recapture overwrites the entry.
         // Client disconnects land here too; the recapture is idempotent and
         // bounded by scheduleShellCapture's stampede guard + backoff.
-        scheduleShellCapture(
-          ctx,
-          request,
-          env,
-          url,
-          reqCtx,
-          ssrModule,
-          descriptor,
-        );
+        scheduleRecapture();
         if (tailTiming) {
           tailTiming.outcome = "error";
           tailTiming.completeMs = Math.round(performance.now() - tailT0);
-          publishShellTailTiming(tailTiming);
         }
+        publishTailTiming(tailTiming, metricsStore, request, url);
         controller.error(error);
       }
     },