@rangojs/router 0.2.0 → 0.4.1

package/src/cache/search-params-filter.ts

@@ -0,0 +1,118 @@
+/**
+ * Global search-param cache-key filtering (`cache.searchParams` on the
+ * handler/createRouter cache config).
+ *
+ * Controls WHICH query params participate in default cache-key generation
+ * across every tier that keys by URL (segment, document, response, PPR shell,
+ * "use cache" ctx normalization, prerendered-shell manifest matching). The
+ * filter affects cache keys ONLY -- `ctx.searchParams` and the request URL are
+ * untouched, handlers and loaders still see the full query string.
+ *
+ * Design doc: docs/design/caching.md ("Search param filtering").
+ *
+ * The footgun this must not soften: excluding a param is a promise that
+ * rendered output does not depend on it. If it does, the first variant is
+ * cached and served to everyone (the classic CDN cache-key mistake). The
+ * default therefore stays "all" -- correct by default, opt into collapsing.
+ */
+
+/**
+ * `cache.searchParams` config value.
+ *
+ * - `"all"` (default) -- every non-reserved param keys the cache (today's
+ *   behavior; reserved = the router's own `_rsc*` / `__` allowlist params,
+ *   see cache-key-utils.ts).
+ * - `"none"` -- query params never key the cache.
+ * - `{ include }` -- allowlist: only the named params key the cache.
+ * - `{ exclude }` -- denylist: every param except the named ones keys the cache.
+ *
+ * Names match exactly, plus a `*` SUFFIX wildcard (`"utm_*"` matches every
+ * param starting with `utm_`). No RegExp: keeps the config serializable and
+ * deterministic. `include` + `exclude` together is unrepresentable -- the
+ * union forces exactly one mode.
+ */
+export type CacheSearchParams =
+  | "all"
+  | "none"
+  | { include: readonly string[]; exclude?: never }
+  | { exclude: readonly string[]; include?: never };
+
+/**
+ * Compiled form of a `CacheSearchParams` config: returns true when the param
+ * name should participate in the cache key. `undefined` means "no filter"
+ * ("all") so the unfiltered path stays byte-identical to the pre-feature key
+ * format (cacheKeyBase output is byte-stable by contract).
+ */
+export type SearchParamsFilter = (name: string) => boolean;
+
+/**
+ * Well-known tracking/click-id params that fragment caches without changing
+ * rendered output for (almost) every app. Exported so the common case is one
+ * line: `searchParams: { exclude: TRACKING_SEARCH_PARAMS }`.
+ *
+ * Sources: Google (gclid/gclsrc/dclid/gbraid/wbraid + utm_*), Meta (fbclid),
+ * Microsoft (msclkid), TikTok (ttclid), Twitter/X (twclid), LinkedIn
+ * (li_fat_id), Mailchimp (mc_cid/mc_eid), Instagram (igshid), Yandex (yclid),
+ * HubSpot (_hsenc/_hsmi).
+ */
+export const TRACKING_SEARCH_PARAMS: readonly string[] = [
+  "utm_*",
+  "gclid",
+  "gclsrc",
+  "dclid",
+  "gbraid",
+  "wbraid",
+  "fbclid",
+  "msclkid",
+  "ttclid",
+  "twclid",
+  "li_fat_id",
+  "mc_cid",
+  "mc_eid",
+  "igshid",
+  "yclid",
+  "_hsenc",
+  "_hsmi",
+];
+
+const NONE_FILTER: SearchParamsFilter = () => false;
+
+/**
+ * Build a name matcher from a pattern list: exact names into a Set, `*`-suffix
+ * patterns into prefix strings. Only a TRAILING `*` is a wildcard; a `*`
+ * anywhere else is matched literally (documented in CacheSearchParams).
+ */
+function compileMatcher(
+  patterns: readonly string[],
+): (name: string) => boolean {
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  for (const pattern of patterns) {
+    if (pattern.endsWith("*")) {
+      prefixes.push(pattern.slice(0, -1));
+    } else {
+      exact.add(pattern);
+    }
+  }
+  if (prefixes.length === 0) {
+    return (name) => exact.has(name);
+  }
+  return (name) =>
+    exact.has(name) || prefixes.some((prefix) => name.startsWith(prefix));
+}
+
+/**
+ * Compile a `cache.searchParams` config into a predicate, once per resolved
+ * cache config (handler.ts). Returns `undefined` for the default ("all") so
+ * every call site can cheaply skip filtering and keep the shipped key format
+ * byte-stable.
+ */
+export function compileSearchParamsFilter(
+  config: CacheSearchParams | undefined,
+): SearchParamsFilter | undefined {
+  if (config === undefined || config === "all") return undefined;
+  if (config === "none") return NONE_FILTER;
+  if (config.include !== undefined) return compileMatcher(config.include);
+  const excluded = compileMatcher(config.exclude ?? []);
+  return (name) => !excluded(name);
+}

package/src/cache/shell-snapshot.ts

@@ -34,7 +34,9 @@ import type {
   ShellSnapshotItemValue,
   ShellSnapshotResponseValue,
   ShellSnapshotLoaderValue,
+  CacheReadError,
 } from "./types.js";
+import { CACHE_READ_ERROR } from "./types.js";
 import { bufferToBase64, base64ToBuffer } from "./cf/cf-base64.js";
 import { isPerClientSignalHeader } from "../browser/cookie-name.js";
 
@@ -158,9 +160,11 @@ export class RecordingShellStore<
     return this.records.size > 0 ? [...this.records.values()] : undefined;
   }
 
-  async get(key: string): Promise<CacheGetResult | null> {
+  async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     const result = await this.inner.get(key);
-    if (result) this.record("segment", key, result.data);
+    if (result && result !== CACHE_READ_ERROR) {
+      this.record("segment", key, result.data);
+    }
     return result;
   }
 
@@ -283,7 +287,7 @@ export class SnapshotOnlySegmentStore<
     return this.recording.keyGenerator;
   }
 
-  async get(key: string): Promise<CacheGetResult | null> {
+  async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     return this.recording.get(key);
   }
 
@@ -417,7 +421,7 @@ export class SeededShellStore<
     return this.inner.supportsPassiveShellReads;
   }
 
-  async get(key: string): Promise<CacheGetResult | null> {
+  async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     const seeded = this.segments.get(key);
     if (seeded) return { data: seeded, shouldRevalidate: false };
     if (this.segmentsOnly) return null;

package/src/cache/types.ts

@@ -12,6 +12,22 @@
 import type { ResolvedSegment } from "../types.js";
 import type { RequestContext } from "../server/request-context.js";
 
+/**
+ * Sentinel a `SegmentCacheStore.get` MAY return instead of `null` when the
+ * read FAILED (backend error) rather than genuinely missing. For the render
+ * outcome the two are identical — render fresh, re-cache — so hit/miss-only
+ * consumers can treat it as a miss. The PPR replay composition needs the
+ * distinction: an errored explicit-tier read must render uncached
+ * (`lookupRouteDetailed` classifies it `error`), never be substituted by the
+ * seeded doc record — the built-in stores swallow backend errors internally,
+ * so without this signal their failures read as replayable misses. Third-party
+ * stores returning plain `null` on error keep the miss classification.
+ */
+export const CACHE_READ_ERROR: unique symbol = Symbol.for(
+  "rango.cache.readError",
+);
+export type CacheReadError = typeof CACHE_READ_ERROR;
+
 /**
  * Result from cache get() including data and revalidation status
  */
@@ -90,9 +106,10 @@ export interface SegmentCacheStore<TEnv = unknown> {
 
   /**
    * Get cached entry data by key
-   * @returns Cache result with data and staleness, or null if not found/expired
+   * @returns Cache result with data and staleness, null if not found/expired,
+   * or CACHE_READ_ERROR when the read failed (optional — see the sentinel).
    */
-  get(key: string): Promise<CacheGetResult | null>;
+  get(key: string): Promise<CacheGetResult | null | CacheReadError>;
 
   /**
    * Store entry data with TTL
@@ -305,6 +322,26 @@ export interface ShellCacheEntry {
    * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot?: ShellSnapshotRecord[];
+  /**
+   * The key of the CANONICAL document segment record inside `snapshot` — the
+   * one navigation replay can actually consume (resolved under the implicit
+   * doc namespace at capture; see CacheScope.cacheRoute). Replay eligibility
+   * requires this exact record: the snapshot also carries incidentally
+   * recorded explicit-tier records (RecordingShellStore passthroughs) whose
+   * keys a partial lookup can never resolve, and counting those declared
+   * entries "replayable" that always missed (`snapshot-miss` flip-flop).
+   * Absent on entries captured before the field existed OR when the capture
+   * recorded no doc record (cache(false)/condition-false routes, prerender
+   * short-circuit) — both read as `no-segment-snapshot`; recapture heals the
+   * former.
+   */
+  docKey?: string;
+  /**
+   * The entry was captured from a partial request only to produce an eligible
+   * segment snapshot. Document serving must treat its HTML prelude as a miss;
+   * the partial request's headers and middleware state are not document state.
+   */
+  navigationOnly?: true;
   /**
    * True when the capture's HANDLER layer declared per-request liveness: a
    * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the

package/src/cache/vercel/vercel-cache-store.ts

@@ -40,7 +40,9 @@ import type {
   CacheItemOptions,
   ShellCacheEntry,
   ShellSnapshotRecord,
+  CacheReadError,
 } from "../types.js";
+import { CACHE_READ_ERROR } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
 import { isPerClientSignalHeader } from "../../browser/cookie-name.js";
 import {
@@ -202,6 +204,13 @@ interface VercelShellEnvelope {
   i?: string;
   /** Capture data snapshot: recorded cache-store hits/writes for HIT parity. */
   sn?: ShellSnapshotRecord[];
+  /**
+   * ShellCacheEntry.docKey. Must round-trip: navigation-replay eligibility
+   * requires the exact canonical doc segment record named here — dropping the
+   * field reads back as "no consumable record" and every partial navigation
+   * reports `no-segment-snapshot` after a store round trip.
+   */
+  dk?: string;
   /**
    * ShellCacheEntry.handlerLiveHoles. Must round-trip: the serve side arms the
    * handler-free fast path on `!entry.handlerLiveHoles`, so dropping the flag
@@ -211,6 +220,8 @@ interface VercelShellEnvelope {
   lh?: boolean;
   /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
   tw?: true;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -389,7 +400,7 @@ export class VercelCacheStore<
 
   // --- Segment family (get/set/delete) ---
 
-  async get(key: string): Promise<CacheGetResult | null> {
+  async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     const storeKey = this.toStoreKey(key, "s");
     const started = Date.now();
     let raw: unknown;
@@ -398,7 +409,9 @@ export class VercelCacheStore<
     } catch (error) {
       reportCacheError(error, "cache-read", "[VercelCacheStore] get");
       this.emitDebug({ op: "get", key, outcome: "error" });
-      return null;
+      // Distinct from a miss so the PPR replay composition renders uncached
+      // instead of substituting the seeded doc record (CACHE_READ_ERROR).
+      return CACHE_READ_ERROR;
     }
     const readMs = Date.now() - started;
 
@@ -814,8 +827,10 @@ export class VercelCacheStore<
         buildVersion: env.bv,
         initialTheme: env.i,
         snapshot: env.sn,
+        docKey: env.dk,
         handlerLiveHoles: env.lh,
         transitionWhen: env.tw,
+        navigationOnly: env.no,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -863,8 +878,10 @@ export class VercelCacheStore<
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
         sn: entry.snapshot,
+        dk: entry.docKey,
         lh: entry.handlerLiveHoles,
         tw: entry.transitionWhen,
+        no: entry.navigationOnly,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
@@ -1192,7 +1209,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn, dk, lh, tw, no } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1208,8 +1225,10 @@ export class VercelCacheStore<
       t: Array.isArray(t) ? (t as string[]) : undefined,
       i: typeof i === "string" ? i : undefined,
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
+      dk: typeof dk === "string" ? dk : undefined,
       lh: lh === true ? true : undefined,
       tw: tw === true ? true : undefined,
+      no: no === true ? true : undefined,
     };
   }
 

package/src/index.rsc.ts

@@ -189,6 +189,10 @@ export {
 
 // RSC handler types (server-side)
 export type { HandlerCacheConfig } from "./rsc/types.js";
+export {
+  TRACKING_SEARCH_PARAMS,
+  type CacheSearchParams,
+} from "./cache/search-params-filter.js";
 
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";

package/src/index.ts

@@ -76,6 +76,12 @@ export type {
   RouteParams,
 } from "./search-params.js";
 
+// Universal cache-key filtering config and tracking-param preset.
+export {
+  TRACKING_SEARCH_PARAMS,
+  type CacheSearchParams,
+} from "./cache/search-params-filter.js";
+
 // Client-safe createLoader - only stores the $$id, function is not included
 // Use this when defining loaders that will be imported by client components
 export { createLoader } from "./loader.js";

package/src/router/match-middleware/cache-lookup.ts

@@ -92,17 +92,19 @@
  *   - Action context (if POST)
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
 import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
-import type { HandleStore } from "../../server/handle-store.js";
 import {
-  getRequestContext,
   _getRequestContext,
+  type RequestContext,
 } from "../../server/request-context.js";
+import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
+import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
 import { paramsEqual } from "../params-util.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
@@ -124,17 +126,13 @@ let _decodeHandles:
 let _hashParams:
   | typeof import("../../prerender/param-hash.js").hashParams
   | undefined;
-let _lazyGetRequestContext:
-  | typeof import("../../server/request-context.js").getRequestContext
-  | undefined;
 
 async function ensurePrerenderDeps() {
   if (!_deserializeSegments) {
-    const [codec, snapshot, paramHash, reqCtx, store] = await Promise.all([
+    const [codec, snapshot, paramHash, store] = await Promise.all([
       import("../../cache/segment-codec.js"),
       import("../../cache/handle-snapshot.js"),
       import("../../prerender/param-hash.js"),
-      import("../../server/request-context.js"),
       import("../../prerender/store.js"),
     ]);
     _deserializeSegments = codec.deserializeSegments;
@@ -142,7 +140,6 @@ async function ensurePrerenderDeps() {
     _restoreHandles = snapshot.restoreHandles;
     _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
-    _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
       prerenderStoreInstance = store.createPrerenderStore();
     }
@@ -234,18 +231,16 @@ async function* yieldFromStore<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
-  handleStoreRef?: HandleStore,
+  reqCtx: RequestContext<TEnv> | undefined,
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment> {
-  const { resolveLoadersOnlyWithRevalidation, resolveLoadersOnly } =
-    getRouterContext<TEnv>();
-
   if (
     !_deserializeSegments ||
     !_fragmentSegments ||
     !_restoreHandles ||
     !_decodeHandles ||
-    !_hashParams ||
-    !_lazyGetRequestContext
+    !_hashParams
   ) {
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
@@ -254,14 +249,14 @@ async function* yieldFromStore<TEnv>(
   // store (the prerender lookup runs before the cache scope), so the fragment
   // splice must apply here too — otherwise producer B entries re-serialize the
   // whole tree per request while producer A entries do not.
-  const segments = _getRequestContext()?._shellFragmentPayload
+  const segments = reqCtx?._shellFragmentPayload
     ? await _fragmentSegments(entry.segments)
     : await _deserializeSegments(entry.segments);
 
   // Replay handle data (same as runtime cache hit path). entry.handles is a
   // Flight-encoded string ("" when none) — decode before restore so
   // Promise/ReactNode handle values are revived, not the corrupted JSON form.
-  const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
+  const handleStore = reqCtx?._handleStore;
   if (handleStore && entry.handles) {
     const handlesRecord = await _decodeHandles(entry.handles);
     if (handlesRecord) {
@@ -275,13 +270,14 @@ async function* yieldFromStore<TEnv>(
   state.cachedMatchedIds = segments.map((s) => s.id);
 
   // Set streaming flag (once) and resolve render barrier.
-  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
-  const barrierReqCtx = reqCtx ?? _getRequestContext();
-  if (barrierReqCtx) {
-    if (barrierReqCtx._treeHasStreaming === undefined) {
-      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+  // Post-match serve-source truth for the PPR replay reporter. This overwrites
+  // `intercept` because the prerender store is the response source.
+  if (reqCtx) {
+    reqCtx._pprReplayPostMatchReason = "prerender-store";
+    if (reqCtx._treeHasStreaming === undefined) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
     }
-    barrierReqCtx._resolveRenderBarrier(segments);
+    reqCtx._resolveRenderBarrier(segments);
   }
 
   // For partial navigation, nullify components the client already has
@@ -313,6 +309,54 @@ async function* yieldFromStore<TEnv>(
   );
 }
 
+/**
+ * Whether the prerender store holds a baked entry for this route + params.
+ * Consulted by the PPR replay gate (matchPartialWithPprReplay), which must
+ * only report `prerender-store` when the short-circuit below will actually
+ * serve: a Passthrough(Prerender()) route with an unbaked/passthrough param
+ * misses the store and renders live, and replay — including its heal
+ * capture — must stay available for it (withCacheStore records the doc
+ * record on that path; state.cacheSource is not "prerender"). The store
+ * memoizes per routeKey/paramHash, so this probe and tryPrerenderLookup's
+ * subsequent get() share one underlying load.
+ */
+export async function prerenderEntryExists(
+  routeKey: string | undefined,
+  params: Record<string, string>,
+  pathname: string,
+  entries: EntryData[],
+): Promise<boolean> {
+  if (!routeKey) return false;
+  // Deliberately NOT ensurePrerenderDeps(): the probe needs only the store
+  // and the param hasher — pulling segment-codec here would drag the
+  // @vitejs/plugin-rsc virtual module onto a path that never deserializes.
+  if (!_hashParams) {
+    _hashParams = (await import("../../prerender/param-hash.js")).hashParams;
+  }
+  if (prerenderStoreInstance === undefined) {
+    prerenderStoreInstance = (
+      await import("../../prerender/store.js")
+    ).createPrerenderStore();
+  }
+  if (!prerenderStoreInstance) return false;
+  // Non-intercept variant only: whether the navigation IS an intercept (and
+  // therefore whether tryPrerenderLookup reads `paramHash + "/i"`) resolves
+  // during the match, so this pre-match fast path can only guess the normal
+  // artifact. A wrong guess is reclassified post-match from the match
+  // pipeline's `_pprReplayPostMatchReason` stamp.
+  const entry = await prerenderStoreInstance.get(
+    routeKey,
+    _hashParams!(params),
+    {
+      pathname,
+      isPassthroughRoute: entries.some(
+        (entry) => entry.type === "route" && entry.isPassthrough === true,
+      ),
+    },
+  );
+  return entry != null;
+}
+
 /**
  * Look up a prerendered (build-time cached) entry for the current route and, on
  * a hit, yield its segments. Returns true when an entry was served (the caller
@@ -325,7 +369,9 @@ async function* tryPrerenderLookup<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
-  handleStoreRef?: HandleStore,
+  reqCtx: RequestContext<TEnv> | undefined,
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment, boolean> {
   const paramHash = _hashParams!(ctx.matched.params);
   const isPassthroughPrerenderRoute = ctx.entries.some(
@@ -341,7 +387,15 @@ async function* tryPrerenderLookup<TEnv>(
     },
   );
   if (!entry) return false;
-  yield* yieldFromStore(entry, ctx, state, pipelineStart, handleStoreRef);
+  yield* yieldFromStore(
+    entry,
+    ctx,
+    state,
+    pipelineStart,
+    reqCtx,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+  );
   return true;
 }
 
@@ -380,7 +434,14 @@ export function withCacheLookup<TEnv>(
     // can disrupt AsyncLocalStorage, causing getRequestContext() to return
     // undefined afterward. Capturing the reference early ensures handle replay
     // and handler handle-push work regardless of ALS state.
-    const handleStoreRef = _getRequestContext()?._handleStore;
+    const pipelineReqCtx = _getRequestContext<TEnv>();
+    // Only the match can determine interception; the source header proves
+    // nothing in either direction. Clear a stale reason on normal matches.
+    if (pipelineReqCtx) {
+      pipelineReqCtx._pprReplayPostMatchReason = ctx.isIntercept
+        ? "intercept"
+        : undefined;
+    }
 
     const {
       evaluateRevalidation,
@@ -389,15 +450,19 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
-    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
+    if (
+      !ctx.isAction &&
+      prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)
+    ) {
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const served = yield* tryPrerenderLookup(
           ctx,
           state,
           pipelineStart,
-          handleStoreRef,
+          pipelineReqCtx,
+          resolveLoadersOnly,
+          resolveLoadersOnlyWithRevalidation,
         );
         if (served) return;
       }
@@ -418,7 +483,9 @@ export function withCacheLookup<TEnv>(
             ctx,
             state,
             pipelineStart,
-            handleStoreRef,
+            pipelineReqCtx,
+            resolveLoadersOnly,
+            resolveLoadersOnlyWithRevalidation,
           );
           if (served) return;
         }
@@ -437,11 +504,58 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    const cacheResult = await ctx.cacheScope.lookupRoute(
+    const explicitLookup = await ctx.cacheScope.lookupRouteDetailed(
       ctx.pathname,
       ctx.matched.params,
       ctx.isIntercept,
     );
+    let cacheResult =
+      explicitLookup.status === "hit" ? explicitLookup.result : null;
+
+    // PPR navigation replay composed with a route-derived cache() scope. The
+    // explicit tier stays authoritative: its hit serves under its own
+    // key/ttl/swr semantics and reports `explicit-cache-hit` — never a false
+    // replay HIT. ONLY a true `miss` lets the seeded doc record supply the
+    // match (the marker's onHit observer then reports the true HIT). The
+    // other outcomes render fresh: `bypass` (cache(false), a false
+    // condition() — absolute opt-outs even when the pre-read gate saw a
+    // different condition() result — or no store) and `error` (a throwing
+    // key()/keyGenerator/store.get keeps lookupRoute's render-uncached
+    // contract; the canonical record must not serve across a broken key
+    // partition). The outcome comes from the lookup itself, not a re-run of
+    // the condition, so a flapping predicate cannot re-admit the fallback.
+    // Gated on the marker's `onExplicitHit`, set ONLY on the
+    // navigation-replay serve path: a CAPTURE render must never fall back
+    // here — its marker store reads through to the real store, and a
+    // doc-keyed hit would replay the previous generation's segments instead
+    // of re-running handlers (breaking SWR recapture freshness). Intercepts
+    // stay source-dependent on their normal cache path (match-api never arms
+    // replay for them).
+    const replayMarker = pipelineReqCtx?._shellImplicitCache;
+    if (
+      replayMarker?.onExplicitHit &&
+      !ctx.isIntercept &&
+      !ctx.cacheScope.isShellImplicitDocScope
+    ) {
+      if (explicitLookup.status === "hit") {
+        replayMarker.onExplicitHit();
+      } else if (explicitLookup.status === "miss" && replayMarker.store) {
+        // The store gate keeps report-only markers (installed on the
+        // no-eligible-snapshot path purely for truthful status) inert: a
+        // store-less marker minting a doc scope here would resolve the APP
+        // store and read the REAL doc: partition — a cross-partition serve.
+        cacheResult = await createShellImplicitDocScope(
+          replayMarker,
+        ).lookupRoute(ctx.pathname, ctx.matched.params, ctx.isIntercept);
+      } else if (explicitLookup.status === "bypass") {
+        // condition() refused at lookup time (the gate only pre-decides the
+        // static cache(false) case) — report cache-disabled truthfully.
+        replayMarker.onExplicitBypass?.();
+      }
+      // "error" stays unreported: the render is fresh and the seeded record
+      // was not consulted, which is exactly what snapshot-miss describes; the
+      // store already routed the failure through reportCacheError.
+    }
 
     if (!cacheResult) {
       yield* source;
@@ -460,8 +574,7 @@ export function withCacheLookup<TEnv>(
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
-    const pprTransitionDecisions =
-      _getRequestContext()?._pprTransitionDecisions;
+    const pprTransitionDecisions = pipelineReqCtx?._pprTransitionDecisions;
 
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
@@ -581,7 +694,7 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    const barrierReqCtx = _getRequestContext();
+    const barrierReqCtx = pipelineReqCtx;
     if (barrierReqCtx) {
       if (barrierReqCtx._treeHasStreaming === undefined) {
         barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);