@rangojs/router 0.16.0 → 0.18.0

package/src/cache/cache-scope.ts

@@ -17,7 +17,12 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
-import { recordRequestTags } from "./cache-tag.js";
+import {
+  getSegmentTags,
+  recordRequestTags,
+  recordSegmentTags,
+  runInSegmentTagScope,
+} from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
 // segment-codec is the only module on cache-scope's import graph that eagerly
 // pulls @vitejs/plugin-rsc (a virtual: module the plain node/vitest runner cannot
@@ -28,11 +33,12 @@ import { reportCacheError } from "./cache-error.js";
 // is unchanged: both methods are async and already awaited the codec.
 import {
   captureHandles,
+  captureHandleOwners,
   restoreHandles,
   encodeHandles,
   decodeHandles,
 } from "./handle-snapshot.js";
-import { cacheKeyBase } from "./cache-key-utils.js";
+import { cacheKeyBase, composeCacheKeys } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
   isFiniteNonNegativeSeconds,
@@ -50,6 +56,38 @@ export function resolveCacheTags(
   return resolveTagsOption(config.tags, ctx, "CacheScope");
 }
 
+/**
+ * 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.
+ */
+function noteRouteRecordWindow(
+  requestCtx: RequestContext,
+  freshUntil: number,
+  ttl: number,
+  swr: number,
+  written: boolean,
+): void {
+  const next = {
+    freshUntil,
+    staleUntil: freshUntil + swr * 1000,
+    ttl,
+    swr,
+    written,
+  };
+  const current = requestCtx._routeRecordWindow;
+  // The record that runs out first names the config; freshness is the least.
+  requestCtx._routeRecordWindow = current
+    ? {
+        ...(current.staleUntil <= next.staleUntil ? current : next),
+        freshUntil: Math.min(current.freshUntil, freshUntil),
+      }
+    : next;
+}
+
 function debugCacheLog(message: string): void {
   if (INTERNAL_RANGO_DEBUG) {
     console.log(message);
@@ -109,7 +147,43 @@ function getDefaultRouteCacheKey(
 // CacheScope
 // ============================================================================
 
-const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
+const CACHE_HIT_OBSERVERS = new WeakMap<
+  CacheScope,
+  () => void | Promise<void>
+>();
+
+type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
+
+/**
+ * A configured `key()` cannot run without a request context. Falling back to
+ * the default key would store the key()'s partitioned output under the broad
+ * key and serve it across partitions, so key resolution fails instead and
+ * every caller degrades to an uncached render (as for a throwing `key()`).
+ */
+function keyWithoutContextError(): Error {
+  return new Error(
+    "[CacheScope] a cache() key() needs a request context; rendering uncached",
+  );
+}
+
+/**
+ * One key resolution per request, resolver (`by`: a `key()` or a store's
+ * keyGenerator) and `slot`, held on the request context (`_resolvedCacheKeys`,
+ * see CacheScope.resolveKeyFrom).
+ */
+function memoizedKey(
+  requestCtx: RequestContext,
+  by: unknown,
+  slot: string,
+  resolve: () => Promise<string>,
+): Promise<string> {
+  const memo = (requestCtx._resolvedCacheKeys ??= new Map());
+  let resolved = memo.get(by);
+  if (!resolved) memo.set(by, (resolved = new Map()));
+  let key = resolved.get(slot);
+  if (!key) resolved.set(slot, (key = resolve()));
+  return key;
+}
 
 /**
  * Discriminated outcome of a route cache lookup — see
@@ -144,16 +218,63 @@ export class CacheScope {
   readonly parent: CacheScope | null;
   /** Explicit store from cache() options, if specified */
   private readonly explicitStore: SegmentCacheStore | undefined;
+  /**
+   * @internal The `key()` functions that partition this scope's records,
+   * outermost first: every cache() on the parent chain that sets one, this
+   * scope's last (#970). `cache(false)` adds none and does not cut the chain,
+   * so a cache() re-enabled under it stays in the partition. Before, the
+   * innermost config alone decided the key: an inner cache() without `key()`
+   * wrote under the default key and an inner `key()` dropped the outer one,
+   * so a request in one partition HIT another partition's inner records.
+   */
+  readonly keyFns: readonly CacheKeyFn[];
+  /** Whether this scope's own config sets `key()` (the last of keyFns). */
+  private readonly hasOwnKey: boolean;
 
   constructor(
     config: PartialCacheOptions | false,
     parent: CacheScope | null = null,
     private readonly defaultKeyPrefix?: "doc",
+    /**
+     * @internal shortCode of the outermost cache() entry of this scope's
+     * enabled chain (createCacheScope). Entries above it are live: their
+     * segments are not stored and resolve fresh on a hit (withCacheLookup).
+     * Undefined covers the whole matched chain (the implicit shell doc scope,
+     * a ppr route).
+     */
+    readonly boundary?: string,
   ) {
     this.config = config;
     this.parent = parent;
     // Extract and store explicit store reference
     this.explicitStore = config !== false ? config.store : undefined;
+    // Only a function counts: a conditional `key: flag ? fn : null` from
+    // untyped code is no key(), as resolveCacheKey always treated it.
+    const ownKey =
+      config !== false && typeof config.key === "function"
+        ? config.key
+        : undefined;
+    const inherited = parent?.keyFns ?? [];
+    this.hasOwnKey = ownKey !== undefined;
+    this.keyFns = ownKey ? [...inherited, ownKey] : inherited;
+  }
+
+  /**
+   * @internal Whether a segment belongs to this scope's cache entry. ShortCodes are
+   * hierarchical (server/context.ts getShortCode: parent shortCode + include
+   * scope + type letter + counter), so the boundary's subtree is every id that
+   * extends the boundary shortCode at a non-digit (`C1` must not claim `C10`).
+   * Intercept slot segments ride the target route's entry wherever the
+   * intercept is declared.
+   */
+  covers(id: string, namespace?: string): boolean {
+    const boundary = this.boundary;
+    if (boundary === undefined) return true;
+    if (id.startsWith(boundary)) {
+      const next = id.charCodeAt(boundary.length);
+      return !(next >= 48 && next <= 57);
+    }
+    return namespace?.startsWith("intercept:") === true;
   }
 
   /**
@@ -222,19 +343,151 @@ export class CacheScope {
    * Resolve the cache key using the shared 3-tier priority.
    * @internal
    */
-  private async resolveKey(
+  private resolveKey(
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
   ): Promise<string> {
-    const defaultKey = getDefaultRouteCacheKey(
-      pathname,
-      params,
-      isIntercept,
-      this.defaultKeyPrefix,
+    return this.resolveKeyFrom(
+      getDefaultRouteCacheKey(
+        pathname,
+        params,
+        isIntercept,
+        this.defaultKeyPrefix,
+      ),
+    );
+  }
+
+  /**
+   * A shell captured from a route record this request read or wrote must not
+   * outlive it (noteRouteRecordWindow). The implicit doc scope's own record
+   * is the shell's, so it notes nothing.
+   */
+  private noteRecordWindow(
+    requestCtx: RequestContext,
+    freshUntil: number,
+    written: boolean,
+  ): void {
+    if (!this.isShellImplicitDocScope) {
+      noteRouteRecordWindow(
+        requestCtx,
+        freshUntil,
+        this.ttl,
+        this.swr ?? 0,
+        written,
+      );
+    }
+  }
+
+  /**
+   * @internal This scope's record key for `defaultKey`, resolved once per
+   * request: a ppr route's shell partition (resolvePartition) and the record
+   * lookup share the `key()` runs, and a rejection is shared too.
+   *
+   * With `key()` functions on the chain (keyFns) the parts are their results,
+   * outermost first, composed by composeCacheKeys (a single part raw), so a
+   * nested cache() keys its records within the enclosing partition (#970).
+   * 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 no keyGenerator runs.
+   * Without `key()` on the chain it is resolveDefaultKey alone. With one but
+   * no request context it rejects (keyWithoutContextError).
+   *
+   * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
+   * by function: it runs once per request whatever the default key
+   * (document, partial or `doc` shell prefix) and however many scopes share
+   * it (sibling routes under one keyed cache()). A shell capture, whose
+   * context is `Object.create` of the request's (shell-capture.ts), reads the
+   * foreground's results through the prototype chain and never runs `key()`
+   * itself: a `key()` calling `cookies()` would trip the capture guard there,
+   * and a capture must store the partition its request resolved.
+   */
+  resolveKeyFrom(defaultKey: string): Promise<string> {
+    const requestCtx = _getRequestContext();
+    if (this.keyFns.length === 0) {
+      return this.resolveDefaultKey(requestCtx, defaultKey);
+    }
+    if (!requestCtx) return Promise.reject(keyWithoutContextError());
+    const parts = this.resolveKeyResults(requestCtx, defaultKey);
+    if (!this.hasOwnKey) {
+      parts.push(this.resolveDefaultKey(requestCtx, defaultKey));
+    }
+    return parts.length === 1
+      ? parts[0]
+      : Promise.all(parts).then(composeCacheKeys);
+  }
+
+  /**
+   * @internal The request partition of a ppr route's shell under this scope
+   * (resolveShellPartition): the chain's `key()` results, composed like the
+   * record key but without the default key, which the URL-based shell key
+   * already carries. A scope without its own `key()` whose store has a
+   * keyGenerator adds that result when it differs from the `doc` default
+   * key, as an unkeyed scope's partition always did: the record is split by
+   * it, so the shell must be too. Undefined (synchronously, with no work)
+   * when nothing can partition; null when nothing does.
+   */
+  resolvePartition(
+    pathname: string,
+    params: Record<string, string> | undefined,
+  ): Promise<string | null> | undefined {
+    const keyGenerator = this.hasOwnKey
+      ? undefined
+      : this.getStore()?.keyGenerator;
+    if (this.keyFns.length === 0 && !keyGenerator) return undefined;
+    const defaultKey = getDefaultRouteCacheKey(pathname, params, false, "doc");
+    const requestCtx = _getRequestContext();
+    if (!requestCtx) {
+      return this.keyFns.length > 0
+        ? Promise.reject(keyWithoutContextError())
+        : Promise.resolve(null);
+    }
+    const generated = keyGenerator
+      ? this.resolveDefaultKey(requestCtx, defaultKey)
+      : undefined;
+    return Promise.all([
+      Promise.all(this.resolveKeyResults(requestCtx, defaultKey)),
+      generated,
+    ]).then(([keys, generatedKey]) => {
+      const parts =
+        generatedKey === undefined || generatedKey === defaultKey
+          ? keys
+          : [...keys, generatedKey];
+      const partition = parts.length === 0 ? null : composeCacheKeys(parts);
+      return partition === defaultKey ? null : partition;
+    });
+  }
+
+  /** The chain's `key()` results, each once per request (memoizedKey). */
+  private resolveKeyResults(
+    requestCtx: RequestContext,
+    defaultKey: string,
+  ): Promise<string>[] {
+    return this.keyFns.map((keyFn) =>
+      memoizedKey(requestCtx, keyFn, "", () =>
+        resolveCacheKey(keyFn, null, defaultKey, "CacheScope"),
+      ),
     );
-    const keyFn = this.config !== false ? this.config.key : undefined;
-    return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
+  }
+
+  /**
+   * This scope's store keyGenerator result for `defaultKey` (once per request
+   * and default key), else `defaultKey` (resolveCacheKey).
+   */
+  private resolveDefaultKey(
+    requestCtx: RequestContext | undefined,
+    defaultKey: string,
+  ): Promise<string> {
+    const store = this.getStore();
+    const keyGenerator = store?.keyGenerator;
+    const resolve = () =>
+      resolveCacheKey(undefined, store, defaultKey, "CacheScope");
+    return requestCtx && keyGenerator
+      ? memoizedKey(requestCtx, keyGenerator, defaultKey, resolve)
+      : resolve();
   }
 
   /**
@@ -316,11 +569,14 @@ export class CacheScope {
    * @param pathname - URL pathname for cache key generation
    * @param params - Route params for cache key generation
    * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+   * @param claimLoaderPushes - The handler context's _claimLoaderPushes, for
+   *   restoreHandles' loader-owned values
    */
   async lookupRoute(
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
+    claimLoaderPushes?: (loaderId: string) => boolean,
   ): Promise<{
     segments: ResolvedSegment[];
     shouldRevalidate: boolean;
@@ -329,6 +585,7 @@ export class CacheScope {
       pathname,
       params,
       isIntercept,
+      claimLoaderPushes,
     );
     return outcome.status === "hit" ? outcome.result : null;
   }
@@ -355,6 +612,7 @@ export class CacheScope {
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
+    claimLoaderPushes?: (loaderId: string) => boolean,
   ): Promise<CacheRouteLookupOutcome> {
     if (!this.enabled) return { status: "bypass" };
     if (!this.conditionAllows("read")) return { status: "bypass" };
@@ -399,7 +657,8 @@ export class CacheScope {
       // expand them (segment-fragments.ts). Read off the ambient context at the
       // same point the cache key was resolved (getDefaultRouteCacheKey), so the
       // flag shares fate with the key: a disrupted ALS already missed the
-      // seeded record and degraded to the full tail.
+      // seeded record, which a document tail turns into the degrade
+      // (ShellRecordUnavailableError).
       let segments: ResolvedSegment[];
       const ambientContext = _getRequestContext();
       try {
@@ -424,11 +683,25 @@ export class CacheScope {
         return { status: "miss" };
       }
 
+      // A record from a whole-chain writer (a previous build on an unversioned
+      // store) can hold segments above the boundary. withCacheLookup resolves
+      // those fresh, so replaying them too would duplicate them and their
+      // handle pushes.
+      if (this.boundary !== undefined) {
+        segments = segments.filter((s) => this.covers(s.id, s.namespace));
+      }
+
       // A hit serves content that was tagged at write time, so the document
       // tag union must include this entry's tags for updateTag()/revalidateTag()
       // to invalidate any full-page entry built on top of it. The write path
-      // records via cacheRoute (resolveCacheTags); the hit path records here.
+      // records via cacheRoute (resolveCacheTags); the hit path records here,
+      // onto the replayed segments too, for a record written from this replay
+      // (a shell capture's doc record).
       recordRequestTags(cached.tags);
+      recordSegmentTags(
+        segments.map((s) => s.id),
+        cached.tags,
+      );
 
       // Replay handle data. An empty string means the route pushed no handles —
       // skip the decode entirely (the common case). Otherwise decode the
@@ -438,7 +711,18 @@ export class CacheScope {
       if (handleStore && cached.handles) {
         const handlesRecord = await decodeHandles(cached.handles);
         if (handlesRecord) {
-          restoreHandles(handlesRecord, handleStore);
+          if (this.boundary !== undefined) {
+            const kept = new Set(segments.map((s) => s.id));
+            for (const id of Object.keys(handlesRecord)) {
+              if (!kept.has(id)) delete handlesRecord[id];
+            }
+          }
+          restoreHandles(
+            handlesRecord,
+            handleStore,
+            cached.handleOwners,
+            claimLoaderPushes,
+          );
         }
       }
 
@@ -451,7 +735,10 @@ export class CacheScope {
         );
       }
 
-      CACHE_HIT_OBSERVERS.get(this)?.();
+      if (ambientContext)
+        this.noteRecordWindow(ambientContext, cached.expiresAt, false);
+
+      await CACHE_HIT_OBSERVERS.get(this)?.();
       return { status: "hit", result: { segments, shouldRevalidate } };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
@@ -515,12 +802,16 @@ export class CacheScope {
     if (!handleStore || !requestCtx) return;
 
     // Exclude loader segments - loaders are always fresh by default
-    // Loaders can opt-in to caching with their own cache() config
-    const nonLoaderSegments = segments.filter((s) => s.type !== "loader");
+    // Loaders can opt-in to caching with their own cache() config.
+    // Segments above the boundary are live and never stored.
+    const nonLoaderSegments = segments.filter(
+      (s) => s.type !== "loader" && this.covers(s.id, s.namespace),
+    );
     if (nonLoaderSegments.length === 0) return;
 
     const ttl = this.ttl;
     const swr = this.swr;
+    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);
@@ -585,11 +876,8 @@ export class CacheScope {
       }
 
       // Collect handle data for non-loader segments only
-      const handles = captureHandles(
-        nonLoaderSegments,
-        handleStore,
-        requestCtx._shellCaptureLoaderHandleValues,
-      );
+      const handles = captureHandles(nonLoaderSegments, handleStore);
+      const handleOwners = captureHandleOwners(nonLoaderSegments, handleStore);
 
       try {
         if (INTERNAL_RANGO_DEBUG) {
@@ -602,17 +890,41 @@ export class CacheScope {
         // through the codec (not raw into the entry) so Promise/ReactNode handle
         // values survive a JSON-serializing store — see encodeHandles.
         const { serializeSegments } = await import("./segment-codec.js");
+        const flightErrors: unknown[] = [];
+        const onFlightError = (error: unknown): void => {
+          flightErrors.push(error);
+        };
+        // Each segment serializes inside its own tag scope, and the handles
+        // inside one for this write: Flight re-renders their server
+        // components, so their render-called tags land on the record.
+        const handlesOwnerId = `${key}#handles`;
         const [serializedSegments, encodedHandles] = await Promise.all([
-          serializeSegments(nonLoaderSegments),
-          encodeHandles(handles),
+          Promise.all(
+            nonLoaderSegments.map((segment) =>
+              runInSegmentTagScope(segment.id, () =>
+                serializeSegments([segment], onFlightError),
+              ),
+            ),
+          ).then((parts) => parts.flat()),
+          runInSegmentTagScope(handlesOwnerId, () =>
+            encodeHandles(handles, onFlightError),
+          ),
         ]);
+        // Flight encodes a component that throws (an async server component in
+        // the tree) or a rejected handle value as an error row and completes
+        // normally; stored, every HIT would render that error until expiry.
+        if (flightErrors.length > 0) throw flightErrors[0];
 
         const data: CachedEntryData = {
           segments: serializedSegments,
           handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
-          tags,
+          tags: collectRecordTags(requestCtx, tags, [
+            ...nonLoaderSegments.map((s) => s.id),
+            handlesOwnerId,
+          ]),
         };
+        if (handleOwners && encodedHandles) data.handleOwners = handleOwners;
 
         if (INTERNAL_RANGO_DEBUG) {
           debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
@@ -640,14 +952,67 @@ export class CacheScope {
 }
 
 /**
- * Create a cache scope from entry's cache config
+ * A route cache() record's tags (#957): its config tags plus every tag its
+ * content recorded under `ownerIds` (cache-tag.ts getSegmentTags — the covered
+ * segments' handlers, the server components their Flight serialization
+ * re-rendered, the loaders those handlers consumed, and the handle values).
+ * A HIT replays all of that output, loading() subtrees included, so every one
+ * of these tags describes it.
+ */
+function collectRecordTags(
+  requestCtx: RequestContext,
+  configTags: string[] | undefined,
+  ownerIds: string[],
+): string[] | undefined {
+  const tags = new Set(configTags);
+  const before = tags.size;
+  for (const id of ownerIds) {
+    for (const tag of getSegmentTags(requestCtx, id)) tags.add(tag);
+  }
+  return tags.size > before ? [...tags] : configTags;
+}
+
+/**
+ * @internal The request partition of a ppr route's shell: with a route
+ * cache() scope, its CacheScope.resolvePartition (the chain's `key()`
+ * results, composed, plus a keyGenerator's contribution for a scope without
+ * its own `key()` (#970)); with none, the app store's keyGenerator result
+ * given the document default key. Undefined (synchronously, with no work)
+ * when neither applies: the shell key stays host + path + filtered search.
+ * Resolves to null when the partition is the default key itself (a
+ * keyGenerator that returns it unchanged): that partitions nothing, so the
+ * shell stays unpartitioned and keeps its build shell. The shell's key, its
+ * read and capture, and partial replay all use it, so a visitor is only
+ * served its own partition. A rejected promise is a failed key resolution:
+ * the caller serves no shell.
+ */
+export function resolveShellPartition(
+  routeScope: CacheScope | null | undefined,
+  appStore: SegmentCacheStore | null | undefined,
+  pathname: string,
+  params: Record<string, string> | undefined,
+): Promise<string | null> | undefined {
+  if (routeScope?.enabled) return routeScope.resolvePartition(pathname, params);
+  if (!appStore?.keyGenerator) return undefined;
+  const defaultKey = getDefaultRouteCacheKey(pathname, params, false, "doc");
+  return resolveCacheKey(undefined, appStore, defaultKey, "CacheScope").then(
+    (resolved) => (resolved === defaultKey ? null : resolved),
+  );
+}
+
+/**
+ * Create a cache scope from entry's cache config. `shortCode` is the cache()
+ * entry's: a scope nested in an enabled parent keeps the parent's boundary
+ * (one entry covers both), any other opens its own at this entry.
  */
 export function createCacheScope(
   config: { options: PartialCacheOptions | false } | undefined,
   parent: CacheScope | null = null,
+  shortCode?: string,
 ): CacheScope | null {
   if (!config) return parent; // No config, inherit parent
-  return new CacheScope(config.options, parent);
+  const boundary = parent?.enabled ? parent.boundary : shortCode;
+  return new CacheScope(config.options, parent, undefined, boundary);
 }
 
 type ShellImplicitCacheMarker = NonNullable<
@@ -661,13 +1026,21 @@ type ShellImplicitCacheMarker = NonNullable<
  * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
  * the explicit-scope composition sites (capture doc record in the cache-store
  * middleware, seeded replay fallback in withCacheLookup) so both ends of the
- * shell contract resolve the SAME canonical document key.
+ * shell contract resolve the SAME canonical document key. A document HIT
+ * tail's marker carries the entry's own key (`fixedDocKey`), which wins over
+ * key resolution.
  */
 export function createShellImplicitDocScope(
   marker: ShellImplicitCacheMarker,
 ): CacheScope {
+  const fixedDocKey = marker.fixedDocKey;
   const implicitScope = new CacheScope(
-    { ttl: marker.ttl, swr: marker.swr, store: marker.store },
+    {
+      ttl: marker.ttl,
+      swr: marker.swr,
+      store: marker.store,
+      ...(fixedDocKey !== undefined && { key: () => fixedDocKey }),
+    },
     null,
     marker.keyPrefix,
   );
@@ -676,26 +1049,29 @@ export function createShellImplicitDocScope(
 }
 
 /**
- * Shell fast path: when the route tree derived NO cache scope and the current
- * request context carries the `_shellImplicitCache` marker (a shell capture,
- * an eligible HIT tail, or a 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).
+ * The doc record scope: when the current request context carries the
+ * `_shellImplicitCache` marker (a shell capture, a document HIT tail, or a
+ * 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).
  *
- * An existing scope — including an explicit cache(false) opt-out — always
- * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
- * are never overridden, and cache(false) keeps the tail on the full handler
- * re-run path. On the navigation-replay serve path the marker still composes
- * with an explicit scope downstream (withCacheLookup's seeded fallback after
- * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
+ * 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
+ * opt-outs the serve gate evaluated before the commit (shellServePlan). Every
+ * other marker leaves an existing scope — including an explicit cache(false)
+ * — in place: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden. On the navigation-replay serve path the marker still
+ * composes with an explicit scope downstream (withCacheLookup's seeded
+ * fallback after an explicit-tier miss) — see `onExplicitHit` on
+ * `_shellImplicitCache`; during a capture, recordShellCaptureDocRecord
+ * (cache-store.ts) writes the record for such a scope.
  */
 export function resolveShellImplicitCacheScope(
   scope: CacheScope | null,
 ): CacheScope | null {
-  if (scope) return scope;
   const marker = getRequestContext()?._shellImplicitCache;
+  if (scope && !marker?.docTail) return scope;
   if (!marker) return null;
   return createShellImplicitDocScope(marker);
 }