@rangojs/router 0.17.0 → 0.19.0

package/src/cache/cache-scope.ts

@@ -17,8 +17,17 @@ 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";
+import {
+  predatesInvalidation,
+  type ExecutionStart,
+} from "./tag-invalidation.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
 // resolve). It is imported LAZILY at the two call sites below (deserializeSegments
@@ -30,10 +39,11 @@ import {
   captureHandles,
   captureHandleOwners,
   restoreHandles,
+  type OwnedPushDelivery,
   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,
@@ -42,13 +52,38 @@ import {
   resolveTagsOption,
 } from "./cache-policy.js";
 import type { RequestContext } from "../server/request-context.js";
+import { runIdentityExempt } from "./cache-exec-scope.js";
 
-export function resolveCacheTags(
-  config: PartialCacheOptions | false,
-  ctx: RequestContext | undefined,
-): string[] | undefined {
-  if (config === false) return undefined;
-  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 {
@@ -110,7 +145,95 @@ function getDefaultRouteCacheKey(
 // CacheScope
 // ============================================================================
 
-const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
+type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
+type CacheConditionFn = NonNullable<PartialCacheOptions["condition"]>;
+type CacheTagsOption = NonNullable<PartialCacheOptions["tags"]>;
+
+/** `inherited`, plus `own` when set. */
+function appendOwn<T>(
+  inherited: readonly T[] | undefined,
+  own: T | undefined,
+): readonly T[] {
+  if (own === undefined) return inherited ?? [];
+  return inherited ? [...inherited, own] : [own];
+}
+
+/**
+ * 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",
+  );
+}
+
+/** keyGenerators already warned about returning an empty key. */
+const EMPTY_KEY_WARNED = new WeakSet<object>();
+
+/**
+ * A keyGenerator result as a partition part: null when it is the default key.
+ * An empty result rejects (the request renders uncached, as for a throwing
+ * keyGenerator): positionalParts writes a default result as the empty part,
+ * so an empty result would name the partition of a store that returned the
+ * default key. Warned once per keyGenerator, naming its store.
+ */
+function generatedPart(
+  store: SegmentCacheStore | null,
+  generated: Promise<string>,
+  defaultKey: string,
+): Promise<string | null> {
+  return generated.then((key) => {
+    if (key === defaultKey) return null;
+    if (key !== "") return key;
+    const name = store?.constructor?.name ?? "store";
+    const keyGenerator = store?.keyGenerator;
+    if (keyGenerator && !EMPTY_KEY_WARNED.has(keyGenerator)) {
+      EMPTY_KEY_WARNED.add(keyGenerator);
+      console.warn(
+        `[CacheScope] ${name}'s keyGenerator returned an empty key; rendering uncached. Return the default key to leave a request unpartitioned.`,
+      );
+    }
+    throw new Error(
+      `[CacheScope] ${name}'s keyGenerator returned an empty key; rendering uncached`,
+    );
+  });
+}
+
+/**
+ * keyGenerator parts by position: none when every one returned the default
+ * key (the key stays as it was), else all of them, an empty part for each
+ * default. Dropping only the defaults lost the positions: with a locale
+ * store that returns the default key for `en` and a region store that does
+ * for `us`, `{ en, de }` and `{ de, us }` both kept one part `…|de` and
+ * shared a record and a shell.
+ */
+function positionalParts(parts: readonly (string | null)[]): string[] {
+  return parts.every((part) => part === null)
+    ? []
+    : parts.map((part) => part ?? "");
+}
+
+/**
+ * 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 +268,41 @@ 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;
+  /**
+   * The `condition()` predicates gating this scope, outermost first: every
+   * cache() on the parent chain that sets one, this scope's last (#974). A
+   * read or write needs all of them to allow it (conditionAllows). Before,
+   * only the innermost config's predicate ran, so an outer condition()
+   * refusing a request still let a nested cache() read and write.
+   */
+  private readonly conditions: readonly CacheConditionFn[];
+  /**
+   * The `tags` options of this scope and every cache() on the parent chain,
+   * outermost first (#974): a nested record carries them all (resolveTags),
+   * so `updateTag(outerTag)` evicts it and the shells built from it.
+   */
+  private readonly tagOptions: readonly CacheTagsOption[];
+  /**
+   * The enclosing enabled scopes without a `key()` of their own whose
+   * `store` option differs from this scope's, outermost first: a store
+   * keyGenerator of theirs partitions this scope's records too (#974,
+   * resolvePartitionParts). On the same store the keyGenerator already
+   * applies through this scope's own default key, or its own `key()`
+   * overrides it (#970).
+   */
+  private readonly storeScopes: readonly CacheScope[];
 
   constructor(
     config: PartialCacheOptions | false,
@@ -158,11 +316,46 @@ export class CacheScope {
      * a ppr route).
      */
     readonly boundary?: string,
+    /**
+     * Awaited on every lookup HIT: the implicit doc scope's marker `onHit`
+     * (createShellImplicitDocScope), which arms a partial replay's bake-lane
+     * loader pins before the route's loaders resolve.
+     */
+    private readonly onHit?: () => void | Promise<void>,
+    /**
+     * The record key of the implicit doc scope of a document HIT tail
+     * (createShellImplicitDocScope): the shell entry's own `docKey`, used as
+     * is. Not a `key()`, which would be namespaced (#975) and miss the
+     * record.
+     */
+    private readonly fixedKey?: string,
   ) {
     this.config = config;
     this.parent = parent;
+    const own = config === false ? undefined : config;
     // Extract and store explicit store reference
-    this.explicitStore = config !== false ? config.store : undefined;
+    this.explicitStore = own?.store;
+    // Only a function counts: a conditional `key: flag ? fn : null` from
+    // untyped code is no key(), as resolveCacheKey always treated it.
+    const ownKey = typeof own?.key === "function" ? own.key : undefined;
+    this.hasOwnKey = ownKey !== undefined;
+    this.keyFns = appendOwn(parent?.keyFns, ownKey);
+    this.conditions = appendOwn(
+      parent?.conditions,
+      own?.condition || undefined,
+    );
+    this.tagOptions = appendOwn(parent?.tagOptions, own?.tags || undefined);
+    const storeScopes: CacheScope[] = [];
+    for (let scope = parent; scope; scope = scope.parent) {
+      if (
+        scope.enabled &&
+        !scope.hasOwnKey &&
+        scope.explicitStore !== this.explicitStore
+      ) {
+        storeScopes.unshift(scope);
+      }
+    }
+    this.storeScopes = storeScopes;
   }
 
   /**
@@ -242,6 +435,15 @@ export class CacheScope {
    * 2. App-level store from request context
    */
   getStore(): SegmentCacheStore | null {
+    // The implicit doc scope's store is a per-request overlay
+    // (createShellImplicitDocScope: SeededShellStore on a HIT tail or a
+    // partial replay, SnapshotOnlySegmentStore at capture), never a tag
+    // invalidation target. Registered like a cache({ store }), every HIT
+    // left one in the handler's explicit-store registry, and each
+    // updateTag()/revalidateTag() then warned about it.
+    if (this.isShellImplicitDocScope && this.explicitStore) {
+      return this.explicitStore;
+    }
     return resolveCacheStore(this.explicitStore);
   }
 
@@ -249,19 +451,200 @@ 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 partition parts on the chain (resolvePartitionParts: the `key()`
+   * results, and the keyGenerator results of enclosing scopes on another
+   * store), they are composed by composeCacheKeys, which namespaces every
+   * `key()` result (#975), so a nested cache() keys its records within the
+   * enclosing partition (#970, #974). A scope whose own config sets no
+   * `key()` appends its own default key (resolveDefaultKey). Reusing the
+   * outer `key()` result alone would give every route under the inner
+   * cache() one record: a `key()` replaces the whole default key, so an
+   * outer key that names no route (`tier:gold`) would make `/a` HIT `/b`'s
+   * record. A scope with its own `key()` adds no default key: a `key()` is a
+   * full override, and its store's keyGenerator does not run. With no
+   * partition part it is resolveDefaultKey alone. With a `key()` on the
+   * chain but no request context it rejects (keyWithoutContextError).
+   * `partitionedPrefix` prefixes a key built from partition parts only (the
+   * response family's `response:`).
+   *
+   * 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, partitionedPrefix = ""): Promise<string> {
+    if (this.fixedKey !== undefined) return Promise.resolve(this.fixedKey);
+    const requestCtx = _getRequestContext();
+    if (!requestCtx || !this.mayPartition) {
+      return this.keyFns.length > 0
+        ? Promise.reject(keyWithoutContextError())
+        : this.resolveDefaultKey(requestCtx, defaultKey);
+    }
+    return Promise.all([
+      this.resolvePartitionParts(requestCtx, defaultKey),
+      this.hasOwnKey
+        ? undefined
+        : this.resolveDefaultKey(requestCtx, defaultKey),
+    ]).then(([[keys, storeParts], ownDefault]) => {
+      const generated = positionalParts(storeParts);
+      if (keys.length === 0 && generated.length === 0) return ownDefault!;
+      if (ownDefault !== undefined) generated.push(ownDefault);
+      return partitionedPrefix + composeCacheKeys(keys, generated);
+    });
+  }
+
+  /**
+   * @internal The request partition of a ppr route's shell under this scope
+   * (resolveShellPartition): its partition parts (resolvePartitionParts),
+   * 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.mayPartition && !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);
+    }
+    return Promise.all([
+      this.resolvePartitionParts(requestCtx, defaultKey),
+      keyGenerator
+        ? generatedPart(
+            this.getStore(),
+            this.resolveDefaultKey(requestCtx, defaultKey),
+            defaultKey,
+          )
+        : null,
+    ]).then(([[keys, storeParts], ownGenerated]) => {
+      const generated = positionalParts(
+        keyGenerator ? [...storeParts, ownGenerated] : storeParts,
+      );
+      return keys.length === 0 && generated.length === 0
+        ? null
+        : composeCacheKeys(keys, generated);
+    });
+  }
+
+  /** Whether a partition part can apply: a `key()` or a store scope above. */
+  private get mayPartition(): boolean {
+    return this.keyFns.length > 0 || this.storeScopes.length > 0;
+  }
+
+  /**
+   * The parts partitioning this scope's records, outermost first: the
+   * chain's `key()` results (each once per request, memoizedKey) and the
+   * keyGenerator result of each enclosing scope on another store (once per
+   * keyGenerator, #974), null where it is `defaultKey`. The callers keep those
+   * positions (positionalParts): a result equal to the default key
+   * partitions nothing only when every one does (#970).
+   */
+  private resolvePartitionParts(
+    requestCtx: RequestContext,
+    defaultKey: string,
+  ): Promise<[string[], (string | null)[]]> {
+    const keys = this.keyFns.map((keyFn) =>
+      memoizedKey(requestCtx, keyFn, "", () =>
+        resolveCacheKey(keyFn, null, defaultKey),
+      ),
     );
-    const keyFn = this.config !== false ? this.config.key : undefined;
-    return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
+    const generated: Promise<string | null>[] = [];
+    if (this.storeScopes.length > 0) {
+      // By keyGenerator, not by store: a capture wraps the app store
+      // (shell-capture.ts RecordingShellStore) but not an explicit one, and
+      // the wrapper hands back the inner store's keyGenerator. By store, a
+      // chain naming the app store explicitly added its keyGenerator a second
+      // time in the capture, and the capture's record key was not the
+      // request's.
+      const seen = new Set([this.getStore()?.keyGenerator]);
+      for (const scope of this.storeScopes) {
+        const store = scope.getStore();
+        const keyGenerator = store?.keyGenerator;
+        if (!keyGenerator || seen.has(keyGenerator)) continue;
+        seen.add(keyGenerator);
+        generated.push(
+          generatedPart(
+            store,
+            scope.resolveDefaultKey(requestCtx, defaultKey),
+            defaultKey,
+          ),
+        );
+      }
+    }
+    return Promise.all([Promise.all(keys), Promise.all(generated)]);
+  }
+
+  /**
+   * 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);
+    return requestCtx && keyGenerator
+      ? memoizedKey(requestCtx, keyGenerator, defaultKey, resolve)
+      : resolve();
   }
 
   /**
@@ -292,11 +675,11 @@ export class CacheScope {
   }
 
   /**
-   * Evaluate the cache `condition` predicate. Returns false (skip the cache
-   * operation) when the predicate returns false or throws; returns true when
-   * there is no condition or no request context to evaluate it against.
-   */
-  /**
+   * Evaluate the cache `condition` predicates of this scope and every
+   * enclosing cache() (`conditions`, #974), outermost first. Returns false
+   * (skip the cache operation) when one returns false or throws; returns
+   * true when there is none or no request context to evaluate them against.
+   *
    * One WRITE decision per (scope, request), memoized on the request context.
    * A capture render has TWO writers consulting the same predicate — the
    * explicit tier's cacheRoute and the snapshot-only doc record gate
@@ -309,28 +692,37 @@ export class CacheScope {
    */
   private readonly writeConditionMemo = new WeakMap<RequestContext, boolean>();
 
+  /**
+   * Evaluate the cache `condition` predicate. Returns false (skip the cache
+   * operation) when the predicate returns false or throws; returns true when
+   * there is no condition or no request context to evaluate it against. A
+   * write decision is memoized (writeConditionMemo).
+   */
   private conditionAllows(op: "read" | "write"): boolean {
-    if (this.config === false || !this.config.condition) return true;
-    const requestCtx = getRequestContext();
+    if (this.conditions.length === 0) return true;
+    const requestCtx = _getRequestContext();
     if (!requestCtx) return true;
     if (op === "write") {
       const memoized = this.writeConditionMemo.get(requestCtx);
       if (memoized !== undefined) return memoized;
     }
-    let allowed: boolean;
-    try {
-      allowed = !!this.config.condition(requestCtx);
-      if (!allowed) {
-        debugCacheLog(
-          `[CacheScope] condition returned false, skipping cache ${op}`,
+    let allowed = true;
+    for (const condition of this.conditions) {
+      try {
+        allowed = !!runIdentityExempt(() => condition(requestCtx));
+        if (!allowed) {
+          debugCacheLog(
+            `[CacheScope] condition returned false, skipping cache ${op}`,
+          );
+        }
+      } catch (error) {
+        console.error(
+          `[CacheScope] condition function threw, skipping cache ${op}:`,
+          error,
         );
+        allowed = false;
       }
-    } catch (error) {
-      console.error(
-        `[CacheScope] condition function threw, skipping cache ${op}:`,
-        error,
-      );
-      allowed = false;
+      if (!allowed) break;
     }
     if (op === "write") this.writeConditionMemo.set(requestCtx, allowed);
     return allowed;
@@ -343,14 +735,15 @@ 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
+   * @param ownedPushes - How restoreHandles delivers the record's
+   *   loader-owned values (withCacheLookup: the handler context's
+   *   _claimLoaderPushes, and on a document HIT tail the owners it restores)
    */
   async lookupRoute(
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
-    claimLoaderPushes?: (loaderId: string) => boolean,
+    ownedPushes?: OwnedPushDelivery,
   ): Promise<{
     segments: ResolvedSegment[];
     shouldRevalidate: boolean;
@@ -359,7 +752,7 @@ export class CacheScope {
       pathname,
       params,
       isIntercept,
-      claimLoaderPushes,
+      ownedPushes,
     );
     return outcome.status === "hit" ? outcome.result : null;
   }
@@ -386,7 +779,7 @@ export class CacheScope {
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
-    claimLoaderPushes?: (loaderId: string) => boolean,
+    ownedPushes?: OwnedPushDelivery,
   ): Promise<CacheRouteLookupOutcome> {
     if (!this.enabled) return { status: "bypass" };
     if (!this.conditionAllows("read")) return { status: "bypass" };
@@ -431,7 +824,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 +861,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 (resolveTags); 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
@@ -488,7 +888,7 @@ export class CacheScope {
             handlesRecord,
             handleStore,
             cached.handleOwners,
-            claimLoaderPushes,
+            ownedPushes,
           );
         }
       }
@@ -502,7 +902,10 @@ export class CacheScope {
         );
       }
 
-      CACHE_HIT_OBSERVERS.get(this)?.();
+      if (ambientContext)
+        this.noteRecordWindow(ambientContext, cached.expiresAt, false);
+
+      await this.onHit?.();
       return { status: "hit", result: { segments, shouldRevalidate } };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
@@ -535,7 +938,26 @@ export class CacheScope {
   recordTags(requestCtx: RequestContext | undefined): void {
     if (!this.enabled) return;
     if (!this.conditionAllows("write")) return;
-    recordRequestTags(resolveCacheTags(this.config, requestCtx), requestCtx);
+    recordRequestTags(this.resolveTags(requestCtx), requestCtx);
+  }
+
+  /**
+   * @internal The `tags` of this scope and every enclosing cache()
+   * (`tagOptions`, #974), static and function forms, for `ctx`: the tags its
+   * records carry. Undefined when none resolve (a disabled scope has none).
+   */
+  resolveTags(ctx: RequestContext | undefined): string[] | undefined {
+    if (!this.enabled || this.tagOptions.length === 0) return undefined;
+    if (this.tagOptions.length === 1) {
+      return resolveTagsOption(this.tagOptions[0], ctx, "CacheScope");
+    }
+    const tags = new Set<string>();
+    for (const option of this.tagOptions) {
+      for (const tag of resolveTagsOption(option, ctx, "CacheScope") ?? []) {
+        tags.add(tag);
+      }
+    }
+    return tags.size > 0 ? [...tags] : undefined;
   }
 
   /**
@@ -547,12 +969,17 @@ export class CacheScope {
    * @param params - Route params for cache key generation
    * @param segments - All resolved segments to cache
    * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+   * @param start - Where the render of `segments` started: the record is not
+   *   written when one of its tags was invalidated since (#977,
+   *   predatesInvalidation). A shell capture's doc record passes none: it
+   *   lives only in the shell entry, which putShell gates by its own start.
    */
   async cacheRoute(
     pathname: string,
     params: Record<string, string>,
     segments: ResolvedSegment[],
     isIntercept?: boolean,
+    start?: ExecutionStart,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
     if (!this.conditionAllows("write")) return;
@@ -575,6 +1002,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);
@@ -589,7 +1017,7 @@ export class CacheScope {
     }
 
     // Resolve tags early (while request context is available, before waitUntil)
-    const tags = resolveCacheTags(this.config, requestCtx);
+    const tags = this.resolveTags(requestCtx);
     recordRequestTags(tags, requestCtx);
 
     // Check if this is a partial request (navigation) vs document request
@@ -657,9 +1085,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,10 +1110,18 @@ 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;
 
+        if (start && (await predatesInvalidation(store, data.tags, start))) {
+          debugCacheLog(`[CacheScope] ${key}: invalidated since render`);
+          return;
+        }
+
         if (INTERNAL_RANGO_DEBUG) {
           debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
         }
@@ -699,6 +1147,56 @@ 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, namespaced and composed (#975), plus the keyGenerator results of
+ * enclosing scopes on another store (#974) and of 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).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,41 +1223,47 @@ 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 implicitScope = new CacheScope(
+  return new CacheScope(
     { ttl: marker.ttl, swr: marker.swr, store: marker.store },
     null,
     marker.keyPrefix,
+    undefined,
+    marker.onHit,
+    marker.fixedDocKey,
   );
-  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
-  return implicitScope;
 }
 
 /**
- * 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);
 }