@rangojs/router 0.17.0 → 0.18.0

package/src/cache/cache-runtime.ts

@@ -58,6 +58,7 @@ import {
   type CacheExecScope,
 } from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
+import { currentCacheSeq, invalidatedSince } from "./tag-invalidation.js";
 import type { CacheItemResult } from "./types.js";
 import type { InternalHandlerContext } from "../types.js";
 
@@ -292,7 +293,10 @@ interface CacheEnvelope {
  */
 interface InFlightExecution {
   promise: Promise<CacheEnvelope>;
+  /** Date.now() at registration, for IN_FLIGHT_LEADER_MAX_WAIT_MS. */
   registeredAt: number;
+  /** currentCacheSeq() at registration, for invalidatedSince (#973). */
+  startSeq: number;
 }
 
 const inFlightExecutions = new Map<string, InFlightExecution>();
@@ -678,6 +682,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                 PHASES.background("use-cache-revalidation"),
                 async () => {
                   const refreshArgs = args.map(refreshView);
+                  // The refresh reads its data from here on (#973).
+                  const startSeq = currentCacheSeq();
                   const scoped = runWithCacheTagScope(() =>
                     runWithCacheExecScope(
                       () => fn.apply(this, refreshArgs),
@@ -714,6 +720,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                     // An error row would replace the stale entry; the catch
                     // below reports it and the stale entry keeps serving.
                     if (flightErrors.length > 0) throw flightErrors[0];
+                    // The request invalidated one of the refreshed value's
+                    // tags after the refresh started: the value may predate
+                    // it, and written now it would outlive it.
+                    if (invalidatedSince(requestCtx, freshTags, startSeq)) {
+                      return;
+                    }
                     await store.setItem!(cacheKey, serialized, {
                       handles: encodedHandles,
                       ttl: profile.ttl,
@@ -757,8 +769,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // against its OWN handle store (gated on ITS hasTaintedArgs), and records
     // tags into its OWN request — no deserialized result is shared across
     // requests. The store write stays exactly once (the leader's).
-    const existing = inFlightExecutions.get(cacheKey);
-    if (existing) {
+    let existing = inFlightExecutions.get(cacheKey);
+    while (existing) {
       const remainingMs =
         IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
       const raced =
@@ -780,8 +792,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           "cache-read",
           `[use cache] "${id}" inflight-timeout`,
         );
-        // Fall through to a fresh execution below (this call becomes leader).
-      } else if (raced) {
+        break; // This call becomes the leader below.
+      }
+      // Leader rejected: its map entry is already cleared; run fresh.
+      if (!raced) break;
+      // Checked after the wait, so an invalidation made meanwhile counts too.
+      if (!invalidatedSince(requestCtx, raced.tags, existing.startSeq)) {
         try {
           return await serveCached({
             value: raced.serialized,
@@ -795,11 +811,16 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             "cache-corrupt",
             `[use cache] "${id}" inflight-hit`,
           );
-          // Fall through to a fresh execution below.
+          break; // Run fresh below.
         }
       }
-      // raced === undefined: leader rejected; its map entry is already
-      // cleared, so fall through to a fresh run.
+      // This request invalidated one of the leader's tags after it started
+      // (#973): its value may predate the invalidation. The leader cleared
+      // its entry before resolving, so an entry now is a newer execution
+      // (another caller that made this same decision): join it rather than
+      // start one more.
+      const next = inFlightExecutions.get(cacheKey);
+      existing = next !== existing ? next : undefined;
     }
 
     // This call becomes the leader. Register a deferred envelope so concurrent
@@ -816,9 +837,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Followers attach their own catch; guard the map's own reference so a
     // rejected envelope with no waiter is not an unhandled rejection.
     envelopePromise.catch(() => {});
+    const startSeq = currentCacheSeq();
     inFlightExecutions.set(cacheKey, {
       promise: envelopePromise,
       registeredAt: Date.now(),
+      startSeq,
     });
     const clearSelf = (): void => {
       if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
@@ -931,6 +954,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       // Hand followers the envelope before the store write so a slow/failed
       // write never stalls them.
       resolveEnvelope({ serialized, tags: allTags, handles: encodedHandles });
+      // This request invalidated one of the value's tags after the execution
+      // started (#973): the value may predate the invalidation, and written
+      // now it would outlive it. Skip the write; the next read runs fresh.
+      if (invalidatedSince(requestCtx, allTags, startSeq)) return;
       try {
         await store.setItem!(cacheKey, serialized, {
           handles: encodedHandles,

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
@@ -33,7 +38,7 @@ import {
   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,
@@ -51,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);
@@ -110,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
@@ -145,6 +218,18 @@ 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,
@@ -163,6 +248,15 @@ export class CacheScope {
     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;
   }
 
   /**
@@ -249,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,
+      ),
     );
-    const keyFn = this.config !== false ? this.config.key : undefined;
-    return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
+  }
+
+  /**
+   * 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"),
+      ),
+    );
+  }
+
+  /**
+   * 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();
   }
 
   /**
@@ -431,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 {
@@ -467,8 +694,14 @@ export class CacheScope {
       // 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
@@ -502,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
@@ -575,6 +811,7 @@ export class CacheScope {
 
     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);
@@ -657,9 +894,21 @@ export class CacheScope {
         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, onFlightError),
-          encodeHandles(handles, onFlightError),
+          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
@@ -670,7 +919,10 @@ export class CacheScope {
           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;
 
@@ -699,6 +951,55 @@ export class CacheScope {
   }
 }
 
+/**
+ * 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
@@ -725,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,
   );
@@ -740,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);
 }