@rangojs/router 0.17.0 → 0.19.0

package/src/router/segment-resolution/loader-cache.ts

@@ -6,7 +6,8 @@
  * getItem()/setItem() methods on SegmentCacheStore.
  *
  * Cache key resolution (3-tier, matching CacheScope.resolveKey):
- *   1. options.key(requestCtx) — full override
+ *   1. options.key(requestCtx) — full override, stored namespaced as
+ *      loader:{loaderId}:key:{encodeURIComponent(result)} (#1009)
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
  *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
  *
@@ -17,18 +18,36 @@
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
  *
+ * Identity (#972): without a key() or a store keyGenerator the entry is
+ * shared across users, so a fill whose execution recorded a request-identity
+ * read fails and is not stored, whoever started that execution
+ * (server/context.ts recordLoaderIdentityRead).
+ *
  * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
  * the HIT must reproduce: the MISS records the pushes of the body and of the
  * loaders it awaits via ctx.use into the entry's `handles` blob (the
  * "use cache" capture/encode), and every HIT — stale included — replays
  * them, each loader's pushes at most once per request (a dependency another
  * reader already ran keeps its live pushes). See replayLoaderHandles.
+ *
+ * Tags too (#964): the entry stores its cache() tags plus every tag its
+ * execution recorded, those of the loader values it read included
+ * (cache-tag.ts "Recorded-tag sets"), so updateTag() of any of them drops it.
+ * Every HIT records the stored tags through the loader's tag owner
+ * (recordLoaderTags), so a route cache() record, PPR shell or document built
+ * over the HIT carries them, and a loader that reads this one takes them on.
+ * Once the binding started, a loader body's ctx.use of it gets the same
+ * dataPromise as a handler read (createLoaderExecutor's useLoader); a stale
+ * refresh does not (setupLoaderAccess _runLoaderIsolated).
  */
 
 import {
   getCurrentLoaderBodyId,
   isInsideLoaderBody,
+  loaderCacheIdentityError,
+  type EntryData,
   type LoaderEntry,
+  type LoaderIdentityRead,
 } from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import type { HandleStore } from "../../server/handle-store.js";
@@ -39,13 +58,17 @@ import {
 } from "../../cache/handle-capture.js";
 import { encodeHandles, decodeHandles } from "../../cache/handle-snapshot.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
   runWithRequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
-import { sortedRouteParams } from "../../cache/cache-key-utils.js";
+import {
+  KEY_PART_PREFIX,
+  sortedRouteParams,
+} from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -55,11 +78,29 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import {
+  executionStart,
+  predatesInvalidation,
+} from "../../cache/tag-invalidation.js";
 import {
   maskNestedContainerThenables,
   overlayLoaderContainer,
 } from "./loader-snapshot.js";
-import { recordRequestTags } from "../../cache/cache-tag.js";
+import {
+  SHELL_BAKE_TAG_OWNER,
+  captureRecordedTags,
+  earliestRecordedStart,
+  flattenRecordedTags,
+  linkLoaderTags,
+  linkLoaderTagsTo,
+  linkRecordedTags,
+  markIdentityRead,
+  markTagSetStart,
+  readValueTags,
+  recordedIdentityRead,
+  recordLoaderTags,
+  tagLoaderValue,
+} from "../../cache/cache-tag.js";
 import {
   isShellCaptureActive,
   createMaskedLoaderPromise,
@@ -98,7 +139,30 @@ function getDefaultLoaderCacheKey(
 }
 
 /**
- * Resolve cache key using the shared 3-tier priority.
+ * A loader's own `key()` result as its entry key (#1009). The result is
+ * often request input, and the item family (`getItem`/`setItem`) has no
+ * other discriminator, so stored raw it could name another loader's entry
+ * or a `"use cache"` entry (`use-cache:<id>:...`, cache-runtime.ts), which
+ * shares that family; route records use `get`/`set`. Namespaced, it can't:
+ * - it starts with `loader:`, which no `"use cache"` key does;
+ * - an encoded result holds no `:`, so the key reads unambiguously from
+ *   the right (result, `key:`, loader id), and two namespaced keys are
+ *   equal only for the same loader and result;
+ * - a default key `loader:<id>:<host><pathname>...` holds a `/` past its
+ *   id, and an encoded result holds none, so the two are equal only if one
+ *   loader's id is literally `<other id>:<host>/<path>...`. Loader ids can
+ *   hold `:` (a dev id is a root-relative path, absolute `D:/...` on
+ *   Windows), so this is the guarantee, not "ids hold no `:`".
+ * A store keyGenerator result stays the store's own namespace, as on routes
+ * (composeCacheKeys).
+ */
+function loaderKeyFromResult(loaderId: string, result: string): string {
+  return `loader:${loaderId}:${KEY_PART_PREFIX}${encodeURIComponent(result)}`;
+}
+
+/**
+ * Resolve cache key using the shared 3-tier priority. `declared`: a key() or
+ * store keyGenerator produced it, so it can carry request identity (#972).
  */
 async function resolveLoaderKey(
   loaderEntry: LoaderEntry,
@@ -106,7 +170,7 @@ async function resolveLoaderKey(
   loaderId: string,
   pathname: string,
   params: Record<string, string>,
-): Promise<string> {
+): Promise<{ key: string; declared: boolean }> {
   const options = loaderEntry.cache!.options;
   // The host is part of the loader cache identity, matching the route-level
   // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
@@ -115,8 +179,16 @@ async function resolveLoaderKey(
   // loader data to another.
   const host = getRequestContext()?.url?.host ?? "localhost";
   const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
-  if (options === false) return defaultKey;
-  return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
+  if (options === false) return { key: defaultKey, declared: false };
+  const keyFn = options.key;
+  return {
+    key: await resolveCacheKey(
+      keyFn && (async (ctx) => loaderKeyFromResult(loaderId, await keyFn(ctx))),
+      store,
+      defaultKey,
+    ),
+    declared: Boolean(keyFn || store.keyGenerator),
+  };
 }
 
 /**
@@ -131,6 +203,97 @@ function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
   return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
 }
 
+const bindsLoaderCacheMemo = new WeakMap<EntryData, boolean>();
+
+const hasLoaderCache = (loaders: readonly LoaderEntry[] | undefined) =>
+  loaders?.some((l) => l.cache !== undefined && l.cache.options !== false) ??
+  false;
+
+function entryBindsLoaderCache(entry: EntryData): boolean {
+  let binds = bindsLoaderCacheMemo.get(entry);
+  if (binds === undefined) {
+    binds =
+      hasLoaderCache(entry.loader) ||
+      (entry.intercept?.some((i) => hasLoaderCache(i.loader)) ?? false) ||
+      (entry.layout?.some(entryBindsLoaderCache) ?? false) ||
+      Object.values(entry.parallel ?? {}).some(
+        (p) => p !== undefined && entryBindsLoaderCache(p),
+      );
+    bindsLoaderCacheMemo.set(entry, binds);
+  }
+  return binds;
+}
+
+/**
+ * Whether a request over the matched chain `entries` resolves a loader bound
+ * with its own cache(): on a chain entry, or on its parallel slots, orphan
+ * layouts or intercepts. The match arms the per-execution loader tag sets on
+ * it (cache-tag.ts armLoaderTagSets), before any loader starts, so a
+ * dependency the handler or another binding starts first still records.
+ * Memoized per entry.
+ */
+export function bindsLoaderCache(entries: readonly EntryData[]): boolean {
+  return entries.some(entryBindsLoaderCache);
+}
+
+const chainLoaderEntriesMemo = new WeakMap<EntryData, readonly LoaderEntry[]>();
+
+// The loaders an entry registers, its orphan layouts' and its parallel
+// slots' included.
+function chainLoaderEntries(entry: EntryData): readonly LoaderEntry[] {
+  let loaders = chainLoaderEntriesMemo.get(entry);
+  if (loaders === undefined) {
+    loaders = [
+      ...(entry.loader ?? []),
+      ...(entry.layout ?? []).flatMap(chainLoaderEntries),
+      ...Object.values(entry.parallel ?? {}).flatMap((p) =>
+        p ? chainLoaderEntries(p) : [],
+      ),
+    ];
+    chainLoaderEntriesMemo.set(entry, loaders);
+  }
+  return loaders;
+}
+
+/**
+ * The ids of the loaders a request over the matched chain `entries` runs on
+ * the live lane (no `ssr: false`), on a chain entry, its orphan layouts or
+ * its parallel slots. A document HIT tail restores the record's pushes of
+ * every other owner as authoritative (withCacheLookup, HandleStore
+ * pushRestored); a live-lane loader is a hole, so its live run replaces its
+ * recorded pushes instead. Memoized per entry.
+ */
+export function liveLaneLoaderIds(
+  entries: readonly EntryData[],
+): ReadonlySet<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    for (const l of chainLoaderEntries(entry)) {
+      if (!l.bake) ids.add(l.loader.$$id);
+    }
+  }
+  return ids;
+}
+
+/**
+ * The lane of each loader the matched chain `entries` registers: "live" (no
+ * `ssr: false`) or "bake". A loader registered on both is "live". A PPR
+ * capture credits a push to the first registered loader around it when that
+ * one is live (shell-capture.ts deriveShellCaptureContext).
+ */
+export function routeLoaderLanes(
+  entries: readonly EntryData[],
+): ReadonlyMap<string, "live" | "bake"> {
+  const lanes = new Map<string, "live" | "bake">();
+  for (const entry of entries) {
+    for (const l of chainLoaderEntries(entry)) {
+      if (!l.bake) lanes.set(l.loader.$$id, "live");
+      else if (!lanes.has(l.loader.$$id)) lanes.set(l.loader.$$id, "bake");
+    }
+  }
+  return lanes;
+}
+
 function getLoaderStore(
   loaderEntry: LoaderEntry,
 ): import("../../cache/types.js").SegmentCacheStore | null {
@@ -158,35 +321,82 @@ function getLoaderStore(
  * keyed on that body scope (executeLoaderData), which would swallow the
  * replay; and the store reads the body scope to tell a live push from a
  * replayed one.
- * Outside it, a PPR shell capture classifies replayed pushes as
- * loader-scoped and unbaked (shell-capture.ts), so a shell HIT gets them
- * from the loader's own re-run, not twice.
+ * A PPR shell capture records the replayed pushes under this loader (its
+ * push funnel reads the pushReplayed owner, shell-capture.ts), so a shell
+ * HIT restores them owned (HandleStore.pushRestored). This replay still
+ * runs on that HIT: the store drops its settled values, which the record
+ * already restored, and keeps the thenable ones the record could not keep
+ * (a deferred push, the reason the loader's record carries `runs`).
  */
 async function replayLoaderHandles(
-  encoded: string,
+  encoded: string | undefined,
   handleStore: HandleStore,
   segmentId: string,
+  cachedLoaderId: string,
   claim: ((loaderId: string) => boolean) | undefined,
 ): Promise<void> {
-  const recorded = await decodeHandles(encoded);
+  const recorded = encoded ? await decodeHandles(encoded) : {};
   if (!recorded) return;
   const delivers = new Map<string, boolean>();
-  for (const key in recorded) {
-    const owner = key.slice(key.indexOf(":") + 1);
+  const claims = (owner: string): boolean => {
     let deliver = delivers.get(owner);
     if (deliver === undefined) {
       deliver = claim ? claim(owner) : true;
       delivers.set(owner, deliver);
     }
-    if (!deliver) continue;
-    for (const [handleName, values] of Object.entries(recorded[key])) {
-      for (const value of values) {
-        handleStore.pushReplayed(handleName, segmentId, value, owner);
+    return deliver;
+  };
+  const replay = (): void => {
+    for (const key in recorded) {
+      const owner = key.slice(key.indexOf(":") + 1);
+      if (!claims(owner)) continue;
+      for (const [handleName, values] of Object.entries(recorded[key])) {
+        for (const value of values) {
+          handleStore.pushReplayed(handleName, segmentId, value, owner);
+        }
       }
     }
+  };
+  // A hole's entry, pushes or none, takes the place of the shell copies of
+  // its pushes (HandleStore.redeliverReplays). Not once the hole delivered
+  // in this request: a run a reader started first replaces them itself.
+  if (claims(cachedLoaderId)) {
+    handleStore.redeliverReplays(cachedLoaderId, replay);
+  } else {
+    replay();
   }
 }
 
+/**
+ * Identity mark (#972): a declared-key entry whose MISS recorded a
+ * request-identity read stores that read ahead of its payload. A HIT skips the
+ * body, so without the mark an unkeyed loader reading this value on a HIT
+ * would store another user's data. The value string is this module's own
+ * (serialize/deserialize below), so the mark needs no store support; Flight
+ * and JSON payloads never start with "~".
+ */
+const IDENTITY_MARK = "~identity:";
+
+function markIdentity(
+  value: string,
+  read: LoaderIdentityRead | undefined,
+): string {
+  return read ? `${IDENTITY_MARK}${JSON.stringify(read)}\n${value}` : value;
+}
+
+function unmarkIdentity(value: string): {
+  read: LoaderIdentityRead | undefined;
+  payload: string;
+} {
+  if (!value.startsWith(IDENTITY_MARK))
+    return { read: undefined, payload: value };
+  const end = value.indexOf("\n");
+  return {
+    read: JSON.parse(value.slice(IDENTITY_MARK.length, end)),
+    payload: value.slice(end + 1),
+  };
+}
+
 /**
  * Record key for the MISS capture: run-length groups by the innermost loader
  * body, `${seq}:${loaderId}` — the cached loader or a dependency it awaits
@@ -226,18 +436,23 @@ function recordOwnerKey(cachedLoaderId: string): () => string {
  * never run under a shell capture), so the lane is decided here, per LOADER,
  * never by the entry's loading():
  *
- * - BAKE lane: `loader(Def, { ssr: false })` (awaitBeforeFlush) with a
- *   `bakeSegmentKey` from the caller. The loader EXECUTES at capture (the
+ * - BAKE lane: `loader(Def, { ssr: false })` (LoaderEntry `bake`: the
+ *   caller passes a `bakeSegmentKey` for it on document and navigation
+ *   evaluations alike; a capture, a document evaluation, also has
+ *   awaitBeforeFlush). The loader EXECUTES at capture (the
  *   flag's "data in the HTML before first flush" maps to the frozen prelude)
  *   and its settled non-promise data bakes into the shell. Promises nested in
- *   plain objects/arrays are masked (mask-nested.ts) and stay live holes at
- *   the consumer's own Suspense — per-request material must be promise-shaped
- *   (the #692 cross-session scar). The masked container registers on
- *   `_shellCaptureLoaderRecords`: it holds the capture gate (bounded by
- *   `ppr.captureTimeout`) and pins into the snapshot's loader family, and on a
- *   HIT the recorded container is overlaid onto the fresh run (below) so the
- *   payload matches the frozen prelude byte-for-byte. cookies()/headers() in
- *   its body (nested promise bodies included) trip the capture guard.
+ *   plain objects, arrays and JSX props are masked (mask-nested.ts) and stay
+ *   live holes at the consumer's own Suspense — per-request material must be
+ *   promise-shaped (the #692 cross-session scar). The masked container
+ *   registers on `_shellCaptureLoaderRecords`: it holds the capture gate
+ *   (bounded by `ppr.captureTimeout`) and pins into the snapshot's loader
+ *   family, and on a HIT the recorded container is overlaid onto the fresh
+ *   run (below) so the payload matches the frozen prelude outside the holes.
+ *   A server-component element holding a promise is a hole as a whole, so its
+ *   other props come from the fresh run (loader-snapshot.ts
+ *   elideLoaderContainer). cookies()/headers() in its body (nested promise
+ *   bodies included) trip the capture guard.
  * - LIVE lane: every other loader, whatever its entry's loading(). Never
  *   executes at capture: the slot gets a never-resolving promise
  *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an
@@ -269,6 +484,8 @@ export function resolveLoaderData<TEnv>(
       );
       maskedPromise.catch(() => {});
       reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+      // Its data bakes into the shell, so its tags tag the shell.
+      linkLoaderTagsTo(SHELL_BAKE_TAG_OWNER, loaderEntry.loader.$$id, reqCtx);
       return maskedPromise;
     }
     return createMaskedLoaderPromise();
@@ -280,31 +497,31 @@ export function resolveLoaderData<TEnv>(
       const recorded = seed.get(bakeSegmentKey)!;
       if (!recorded.holes) {
         // Pin-first (hole-free record): the pinned container is what the
-        // payload serves either way (recorded paths win wholesale), so
-        // resolve it immediately instead of gating on the fresh run's
-        // latency — a slow bake-lane loader body otherwise stalls the HIT
-        // tail for values that get discarded. The fresh run still executes
-        // for its side effects and cache read-through writes, lifetime-
-        // extended so the runtime cannot cancel it when the stream closes
-        // first; its rejection is swallowed here (the payload already
-        // matches the prelude, which a fresh error value never could).
+        // payload serves (recorded paths win wholesale), resolved
+        // immediately. The body does not run: a HIT is rendered from the
+        // shell, like the handlers it replays, and the loader's settled
+        // pushes (and those of loaders it awaits) are restored from the
+        // record. Only a record whose capture saw a push it could not keep
+        // (`runs`) still runs the body, in the background, lifetime-extended
+        // so the runtime cannot cancel it when the stream closes first; its
+        // rejection is swallowed (the payload already matches the prelude,
+        // which a fresh error value never could).
         //
         // CONTRACT (deliberate divergence from the gated overlay's
         // fresh-only-keys passthrough): a hole-free pin serves the pinned
-        // SHAPE wholesale — a key the fresh run adds mid-TTL is dropped.
-        // It could never render server-side anyway: no hole was postponed
-        // for it at capture, so the prelude froze the without-that-field
-        // branch and the resume pass has nothing to fill; passing it
-        // through only made the hydration payload disagree with the frozen
-        // prelude (client-side mismatch repair — the divergence class the
-        // snapshot exists to prevent). A field that is per-request must be
-        // promise-shaped at capture (masked -> hole marker -> holes: 1 ->
-        // the gated path below, which preserves fresh-only passthrough) or
-        // live behind loading(). Anything else is uncached nondeterminism
-        // in shell material — the documented drift residual.
-        const fresh = executeLoaderData(loaderEntry, ctx, pathname);
-        fresh.catch(() => {});
-        reqCtx?.executionContext?.waitUntil?.(fresh);
+        // SHAPE wholesale. A field the body would return now had no hole
+        // postponed for it at capture, so the prelude froze the
+        // without-that-field branch and the resume pass has nothing to
+        // fill. A field that is per-request must be promise-shaped at
+        // capture (masked -> hole marker -> holes: 1 -> the gated path
+        // below, which preserves fresh-only passthrough) or live behind
+        // loading(). Anything else is uncached nondeterminism in shell
+        // material — the documented drift residual.
+        if (recorded.runs) {
+          const fresh = executeLoaderData(loaderEntry, ctx, pathname);
+          fresh.catch(() => {});
+          reqCtx?.executionContext?.waitUntil?.(fresh);
+        }
         return Promise.resolve(
           overlayLoaderContainer(undefined, recorded.container),
         );
@@ -343,9 +560,10 @@ function executeLoaderData<TEnv>(
 
   // Evaluate runtime condition if provided
   const options = cacheConfig.options;
-  if (options.condition) {
+  const condition = options.condition;
+  if (condition) {
     const requestCtx = getRequestContext();
-    if (requestCtx && !options.condition(requestCtx)) {
+    if (requestCtx && !runIdentityExempt(() => condition(requestCtx))) {
       return ctx.use(loaderEntry.loader);
     }
   }
@@ -368,7 +586,13 @@ function executeLoaderData<TEnv>(
     internal._loaderCacheOriginalUse = originalUse;
     ctx.use = ((item: any) => {
       const cached = overrides!.get(item?.$$id);
-      if (cached) return cached;
+      if (cached) {
+        // A read is a consumption (#957, #964): see createLoaderExecutor's
+        // useLoader.
+        linkLoaderTags(item.$$id);
+        readValueTags(cached);
+        return cached;
+      }
       return originalUse(item);
     }) as typeof ctx.use;
   }
@@ -395,7 +619,14 @@ function executeLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
-  recordRequestTags(tags);
+  recordLoaderTags(loaderId, tags);
+  // The per-execution loader tag sets were armed before any loader ran: by
+  // the match (match-api.ts, bindsLoaderCache), or by runLoader.
+  // An execution of this loader outside the binding (a reader started it
+  // first, a stale refresh) answers for the cache() tags too.
+  if (tags && tags.length > 0) {
+    internal._bindLoaderCacheTags?.(loaderId, new Set(tags));
+  }
 
   // Handle pushes: the store and the owning segment are read synchronously
   // at kickoff, as createLoaderExecutor does for the body's own pushes.
@@ -406,10 +637,16 @@ function executeLoaderData<TEnv>(
   // concurrently. A dependency can still run on a HIT for another reader
   // (memoized per request); the replay's claim keeps its pushes to one copy.
   const isOwnBodyPush = () => isInsideLoaderBody(loaderId);
+  // What a reader of this value takes on (tagLoaderValue below,
+  // readValueTags): the cache() tags, plus the entry's tags on a HIT or the
+  // execution's on a MISS. A HIT's value is as old as its lookup: a cached
+  // reader gates its own write from here at the latest (#977).
+  const valueTags = new Set(tags);
+  markTagSetStart(valueTags, executionStart());
 
   const dataPromise = (async () => {
     const codec = await getCodec();
-    const key = await resolveLoaderKey(
+    const { key, declared } = await resolveLoaderKey(
       loaderEntry,
       store,
       loaderId,
@@ -428,15 +665,23 @@ function executeLoaderData<TEnv>(
 
     // One readThroughItem call runs at most one execution — the foreground
     // MISS or the background stale revalidation (flagged by wrapBackground)
-    // — so a single capture slot serves the setItem that follows it.
+    // — so one handle capture and one tag set serve the setItem after it.
+    // The entry's tags: its cache() tags plus what the execution recorded.
     let capture: HandleCapture | undefined;
+    const bodyTags = new Set(tags);
     let revalidating = false;
     let hitHandles: string | undefined;
+    let cachedRead = false;
     const onCachedRead = (label: string, cached: CacheItemResult) => {
+      cachedRead = true;
       hitHandles = cached.handles;
+      const { read } = unmarkIdentity(cached.value);
+      if (read) markIdentityRead(valueTags, read);
+      recordLoaderTags(loaderId, cached.tags);
+      for (const tag of cached.tags ?? []) valueTags.add(tag);
       debugLoaderCacheLog(`[LoaderCache] ${label}: ${key}`);
     };
-    const execute = async (): Promise<any> => {
+    const runBody = async (): Promise<any> => {
       // A stale-hit revalidation runs on its own executor: it diverts its
       // pushes (below), so sharing the page's memoized run of a dependency
       // would take that dependency's pushes off the page.
@@ -457,6 +702,26 @@ function executeLoaderData<TEnv>(
         c.stop();
       }
     };
+    // #972: the execution's identity reads, and those of the loader values it
+    // read, are on the bodyTags links whoever started them. With an undeclared
+    // key one fails the fill (the MISS or the stale refresh); one that settles
+    // after the value (a nested promise, a pending handle push) skips the write
+    // instead. With a declared key it is stored as the entry's identity mark
+    // for the HITs, as this loader's readers see it (through this loader when
+    // another made it), and a foreground execution marks the value it serves.
+    // A stale refresh does not: the page is served the stale entry, which its
+    // own mark (or its lack) describes.
+    const identityRead = (): LoaderIdentityRead | undefined => {
+      const read = recordedIdentityRead(bodyTags);
+      if (!read) return undefined;
+      if (!declared) throw loaderCacheIdentityError(read, loaderId);
+      const seen =
+        read.bodyId === undefined || read.bodyId === loaderId
+          ? { ...read, bodyId: loaderId, via: undefined }
+          : { ...read, via: loaderId };
+      if (!revalidating) markIdentityRead(valueTags, seen);
+      return seen;
+    };
 
     // Flight encodes a rejected promise in the value or a handle push as an
     // error row and completes normally. setItem runs after serialize and
@@ -473,15 +738,37 @@ function executeLoaderData<TEnv>(
       // pushes awaited up to its timeout, the whole blob dropped on a timeout
       // or a thrown encode). Encoded here, inside the deferred write, so a
       // MISS response never waits on it.
-      setItem: async (k, v, o) => {
-        const handles = capture
-          ? await encodeHandles(capture.data, onFlightError)
-          : "";
-        if (flightErrors.length > 0) throw flightErrors[0];
-        await store.setItem!(k, v, handles ? { ...o, handles } : o);
-      },
+      setItem: (k, v, o) =>
+        captureRecordedTags(bodyTags, async () => {
+          const handles = capture
+            ? await encodeHandles(capture.data, onFlightError)
+            : "";
+          if (flightErrors.length > 0) throw flightErrors[0];
+          // After the handle encode: it settles pending pushes, which can read.
+          const read = identityRead();
+          const entryTags = [...flattenRecordedTags(bodyTags)];
+          // One of the entry's tags was invalidated after the value's oldest
+          // part started (#977): this execution, or the run of this loader or
+          // of a dependency another reader started earlier. Written now, a
+          // value that may predate it would outlive it. Skip the write; the
+          // next read runs the body.
+          const start = earliestRecordedStart(bodyTags);
+          if (start && (await predatesInvalidation(store, entryTags, start))) {
+            return;
+          }
+          await store.setItem!(k, markIdentity(v, read), {
+            ...o,
+            tags: entryTags.length > 0 ? entryTags : undefined,
+            ...(handles ? { handles } : {}),
+          });
+        }),
       key,
-      execute,
+      execute: async () => {
+        markTagSetStart(bodyTags, executionStart());
+        const value = await captureRecordedTags(bodyTags, runBody);
+        identityRead();
+        return value;
+      },
       // The rango.background span (kind=loader-revalidation) wraps the WHOLE
       // stale revalidation — the re-execution AND the serialize/setItem write
       // (read-through-swr routes the full task through wrapBackground) — so
@@ -495,22 +782,30 @@ function executeLoaderData<TEnv>(
           observePhase(PHASES.background("loader-revalidation"), run),
         );
       },
-      serialize: (d) => codec.serializeResult(d, onFlightError),
-      deserialize: (v) => codec.deserializeResult(v),
+      serialize: (d) =>
+        captureRecordedTags(bodyTags, () =>
+          codec.serializeResult(d, onFlightError),
+        ),
+      deserialize: (v) => codec.deserializeResult(unmarkIdentity(v).payload),
       storeOptions: { ttl, swr, tags },
       onHit: (cached) => onCachedRead("HIT", cached),
       onStale: (cached) => onCachedRead("STALE", cached),
-      onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
+      onMiss: () => {
+        linkRecordedTags(valueTags, bodyTags);
+        debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`);
+      },
       onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
       host: requestCtxForExecute,
     });
 
-    // An entry written before handles were recorded has none: no replay.
-    if (hitHandles && handleStore && owningSegmentId) {
+    // An entry without handles (none recorded, or dropped by an encode
+    // timeout) replays none, and still stands for a hole's shell copies.
+    if (cachedRead && handleStore && owningSegmentId) {
       await replayLoaderHandles(
         hitHandles,
         handleStore,
         owningSegmentId,
+        loaderId,
         internal._claimLoaderPushes,
       );
     }
@@ -522,6 +817,7 @@ function executeLoaderData<TEnv>(
   // push after full drain throws LateHandlePushError.
   handleStore?.trackAuxiliary(dataPromise);
 
+  tagLoaderValue(dataPromise, valueTags);
   overrides.set(loaderId, dataPromise);
 
   return dataPromise;

package/src/router/segment-resolution/loader-mask.ts

@@ -8,10 +8,9 @@
  * fresh into it.
  *
  * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
- * the derived request context of the background capture task (shell-capture.ts) —
- * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
- * capture is wanted" and must not change behavior. This module is the single home
- * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * the derived request context of the background capture task (shell-capture.ts);
+ * the foreground render never sets it. This module is the single home for the
+ * mask so every loader execution site gates the same way (loader-cache.ts
  * `resolveLoaderData`, fresh.ts `resolveLoaders`).
  */