@rangojs/router 0.17.0 → 0.19.0

package/src/cache/cache-key-utils.ts

@@ -2,8 +2,8 @@
  * Shared Cache Key Utilities
  *
  * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
+ * for cache key generation, and the composition of nested cache() keys.
+ * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 
 import { encodeKV } from "../encode-kv.js";
@@ -95,3 +95,63 @@ export function cacheKeyBase(
   if (searchStr) key += `?${searchStr}`;
   return key;
 }
+
+/**
+ * The prefix of a `key()` result's part in a record key (#975), and of a
+ * loader's own `key()` result after its `loader:<id>:` namespace (#1009,
+ * loader-cache.ts loaderKeyFromResult).
+ */
+export const KEY_PART_PREFIX = "key:";
+
+/**
+ * A cache() record key, or ppr shell partition, from its parts
+ * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
+ * results of the scope's cache() chain, outermost first, then its default
+ * parts: the keyGenerator results of enclosing scopes on another store
+ * (#974) and, for a record key under a scope without its own `key()`, its
+ * default key (or its store's keyGenerator result, #970).
+ *
+ * Key scheme invariant (#975). A `key()` result is often request input,
+ * and a record key has no route or scope discriminator (the store reads
+ * `store.get(key)`), so a result that equals another record's key writes
+ * one route's content under the other's entry. Before #975 a single
+ * `key()` result was stored raw: the header value `doc:localhost/pricing`
+ * named /pricing's default-keyed record, and `gold|doc%3Alocalhost%2Fpricing`
+ * named gold's nested /pricing record (#970). So every part is encoded:
+ *
+ * - a `key()` part is `key:` plus `encodeURIComponent(result)`: it starts
+ *   with `key:` and holds no `|` and no other `:`;
+ * - a default part is `encodeURIComponent(value)`: it holds no `:` or `|`;
+ *   an enclosing store's keyGenerator result equal to the default key is an
+ *   empty part, so each store keeps its position (CacheScope
+ *   positionalParts);
+ * - one `key()` part is the key; two or more parts are joined by `|`,
+ *   `key()` parts first;
+ * - a lone default part stays raw: with no `key()` on the chain the record
+ *   key is the default key or the store's keyGenerator result, unchanged.
+ *
+ * Why nothing collides: the router's default keys (`doc:`, `partial:`,
+ * `intercept:`, `response:<type>:`) never start with `key:` and hold a `:`.
+ * A namespaced `key()` result starts with `key:` and holds no `|`. A
+ * composed key holds a `|` and either starts with `key:` or holds no `:`.
+ * Among composed keys, splitting on `|` recovers each part, a part's kind
+ * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
+ * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
+ * result is the store's own namespace, as before.
+ *
+ * Shared with the testing helper `shellCacheKey`, so a test builds the
+ * production partition.
+ */
+export function composeCacheKeys(
+  keyResults: readonly string[],
+  defaultParts: readonly string[] = [],
+): string {
+  if (keyResults.length === 0 && defaultParts.length === 1) {
+    return defaultParts[0];
+  }
+  const parts = keyResults.map(
+    (result) => KEY_PART_PREFIX + encodeURIComponent(result),
+  );
+  for (const part of defaultParts) parts.push(encodeURIComponent(part));
+  return parts.join("|");
+}

package/src/cache/cache-policy.ts

@@ -8,6 +8,7 @@
 
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { runIdentityExempt } from "./cache-exec-scope.js";
 import type { RequestContext } from "../server/request-context.js";
 import { normalizeTags } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
@@ -83,6 +84,28 @@ export function resolveSwrWindow(
   return 0;
 }
 
+/**
+ * Minimum age (ms) of a stale PPR shell before a HIT schedules its recapture.
+ * A shell capped to a route cache() record inside its swr window is stale
+ * from the start (rsc/shell-capture.ts capShellWindow), so without a floor
+ * every HIT of it recaptured, and a capture's store write is one KV write per
+ * key: Cloudflare KV accepts one per second per key. Inside the floor the
+ * stale shell is still served. Per isolate: each isolate's stale HIT past the
+ * floor can schedule one (stampede-guarded per isolate).
+ */
+export const SHELL_MIN_RECAPTURE_INTERVAL_MS = 1_000;
+
+/**
+ * Whether a stale shell HIT schedules its recapture (see the floor above).
+ * Fails open: an entry without a numeric `createdAt` recaptures.
+ */
+export function staleShellRecaptureDue(
+  entry: { readonly createdAt?: number },
+  now: number,
+): boolean {
+  return !(now - (entry.createdAt as number) < SHELL_MIN_RECAPTURE_INTERVAL_MS);
+}
+
 /**
  * Compute staleAt and expiresAt timestamps from TTL and SWR window.
  *
@@ -105,16 +128,18 @@ export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
   defaultKey: string,
-  _label: string,
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
+  // A key reads the request to partition the entry (runIdentityExempt): the
+  // identity guards let it through, a ppr capture included.
   if (keyFn && requestCtx) {
-    return await keyFn(requestCtx);
+    return await runIdentityExempt(() => keyFn(requestCtx));
   }
 
   if (store?.keyGenerator && requestCtx) {
-    return await store.keyGenerator(requestCtx, defaultKey);
+    const keyGenerator = store.keyGenerator;
+    return await runIdentityExempt(() => keyGenerator(requestCtx, defaultKey));
   }
 
   return defaultKey;
@@ -135,7 +160,9 @@ export function resolveTagsOption<TEnv>(
       return undefined;
     }
     try {
-      return normalizeTagList(tags(ctx));
+      // Tags label the entry, never render: identity reads pass
+      // (runIdentityExempt), a ppr capture's record write included.
+      return normalizeTagList(runIdentityExempt(() => tags(ctx)));
     } catch (error) {
       reportCacheError(
         error,

package/src/cache/cache-runtime.ts

@@ -48,6 +48,7 @@ import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   normalizeTags,
+  outsideCacheTagScope,
   recordRequestTags,
   runWithCacheTagScope,
 } from "./cache-tag.js";
@@ -58,6 +59,12 @@ import {
   type CacheExecScope,
 } from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
+import {
+  executionStart,
+  invalidatedSince,
+  predatesInvalidation,
+  type ExecutionStart,
+} from "./tag-invalidation.js";
 import type { CacheItemResult } from "./types.js";
 import type { InternalHandlerContext } from "../types.js";
 
@@ -266,6 +273,12 @@ interface CacheEnvelope {
   tags: string[];
   /** RSC-encoded handle blob captured during execution, if any. */
   handles?: string;
+  /**
+   * One of `tags` was invalidated after the leader started, as the store
+   * tells it (another isolate, #977): the leader does not write it, and a
+   * follower does not serve it.
+   */
+  predates?: boolean;
 }
 
 /**
@@ -292,7 +305,10 @@ interface CacheEnvelope {
  */
 interface InFlightExecution {
   promise: Promise<CacheEnvelope>;
+  /** Date.now() at registration, for IN_FLIGHT_LEADER_MAX_WAIT_MS. */
   registeredAt: number;
+  /** Where the leader started, for invalidatedSince (#973, #977). */
+  start: ExecutionStart;
 }
 
 const inFlightExecutions = new Map<string, InFlightExecution>();
@@ -309,6 +325,18 @@ const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
 /** Distinguishes a leader timeout from a leader rejection in raceLeader. */
 const LEADER_TIMED_OUT = Symbol("leader-timed-out");
 
+/**
+ * @internal Reset this module's per-isolate state: the in-flight leaders a
+ * follower would join for up to IN_FLIGHT_LEADER_MAX_WAIT_MS, and the
+ * once-per-function warnings. Tests only (testing/serve-shell-request.ts
+ * resetShellTestState), never while a request is in flight.
+ */
+export function resetCacheRuntimeForTests(): void {
+  inFlightExecutions.clear();
+  warnedUncachedUnderTest.clear();
+  warnedUnkeyableArgs.clear();
+}
+
 /**
  * Await a leader's envelope for at most `remainingMs`. Resolves with the
  * envelope, `undefined` on leader rejection (the leader already cleared its
@@ -427,6 +455,20 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       );
     }
 
+    // An entry's tags: the profile/DSL tags plus what its execution
+    // recorded, normalized (drops empty profile tags, matching the
+    // invalidate path) and deduped.
+    const entryTags = (recorded: Set<string>): string[] => [
+      ...new Set(normalizeTags([...(profile.tags ?? []), ...recorded])),
+    ];
+    // The value's Flight encode runs back inside its execution's tag scope:
+    // it renders the server components in the value, and a "use cache" call
+    // or cacheTag() among them belongs to this entry (#980).
+    const inTagScope = <T>(
+      recorded: Set<string>,
+      encode: () => Promise<T>,
+    ): Promise<T> => runWithCacheTagScope(encode, recorded).result;
+
     // Separate request-scoped args (ctx, a Request, the request's env) from
     // key-generating args. For those that carry route context (ctx params,
     // pathname, searchParams; a Request's URL), extract serializable values
@@ -627,116 +669,121 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         const liveStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
         const recordKey = ownerKeyed ? useCacheRecordKey() : undefined;
         // Background revalidation — must capture handles if tainted args present.
-        runBackground(requestCtx, async () => {
-          // The background body's handle pushes belong to the refreshed entry
-          // only: the foreground already replayed the stale entry's. They
-          // reach the REQUEST's store (a handler ctx.use(Handle) binds it at
-          // setupLoaderAccess, so a derived context with its own store never
-          // sees them), so the capture accepts only this body's chain and
-          // diverts what it records away from the live store. The foreground
-          // is still rendering here (runBackground starts on the next
-          // microtask), and its concurrent pushes are neither recorded nor
-          // diverted (issue #684, plan 010). A root scope: the task is
-          // detached, so an outer "use cache" body that scheduled it must not
-          // record the refresh's pushes.
-          const bgScope: CacheExecScope = {};
-          const bgCapture = liveStore
-            ? startHandleCapture(liveStore, {
-                accept: () => isInCacheExecChain(bgScope),
-                divert: true,
-                key: recordKey,
-              })
-            : undefined;
-
-          // Tainted args are NOT stamped here, in contrast to the foreground
-          // miss path below. The args include the live HandlerContext the
-          // still-rendering foreground holds, and INSIDE_CACHE_EXEC is a
-          // property stamped onto that SHARED object — so for the whole
-          // revalidation window a concurrent foreground ctx.set() /
-          // ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
-          // never stamped anywhere for the same reason. In-body misuse IS
-          // still guarded here: runWithCacheExecScope below follows only this
-          // body's async chain, so a conditional cookies()/headers() read
-          // that fires only during revalidation throws instead of baking one
-          // user's value into the shared entry — with zero visibility to the
-          // concurrent foreground.
-
-          try {
-            // Re-establish the request-context ALS so a "use cache" body that
-            // reads the ambient getRequestContext() (e.g.
-            // getRequestContext().env.ApiKey) resolves during the background
-            // revalidation instead of throwing "called outside of a request
-            // context". runWithRequestContext sets the store for fn's
-            // synchronous kickoff; its async continuations inherit it.
-            //
-            // The span opens inside the request ALS and wraps the WHOLE task —
-            // fn kickoff through the store write — so its platform spans nest
-            // under rango.background and a slow or failing setItem is part of
-            // the traced revalidation, not an untraced tail.
-            await runWithRequestContext(requestCtx, () =>
-              observePhase(
-                PHASES.background("use-cache-revalidation"),
-                async () => {
-                  const refreshArgs = args.map(refreshView);
-                  const scoped = runWithCacheTagScope(() =>
-                    runWithCacheExecScope(
-                      () => fn.apply(this, refreshArgs),
-                      bgScope,
-                    ),
-                  );
-                  const freshResult = await scoped.result;
-                  bgCapture?.stop();
-                  // Merge profile/DSL tags with runtime cacheTag() tags, read
-                  // after awaiting so post-await cacheTag() calls are included.
-                  // Normalize (drops empty profile tags, matching the
-                  // invalidate path) + dedupe.
-                  const freshTags = [
-                    ...new Set(
-                      normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
-                    ),
-                  ];
-                  recordRequestTags(freshTags, requestCtx);
-                  const flightErrors: unknown[] = [];
-                  const onFlightError = (error: unknown): void => {
-                    flightErrors.push(error);
-                  };
-                  const serialized = await serializeResult(
-                    freshResult,
-                    onFlightError,
-                  );
-                  if (serialized !== null) {
-                    const encodedHandles = bgCapture
-                      ? await encodeHandles(
-                          bgCapture.capture.data,
-                          onFlightError,
-                        )
-                      : undefined;
-                    // 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];
-                    await store.setItem!(cacheKey, serialized, {
-                      handles: encodedHandles,
-                      ttl: profile.ttl,
-                      swr: profile.swr,
-                      tags: freshTags.length > 0 ? freshTags : undefined,
-                    });
-                  }
-                },
-              ),
-            );
-          } catch (bgError) {
-            bgCapture?.stop();
-            // Pass requestCtx explicitly: this runs in a detached background
-            // task where the ALS context is gone, so onError can only fire if
-            // we hand it the context captured up front.
-            reportCacheError(
-              bgError,
-              "stale-revalidation",
-              "[use cache] background revalidation failed",
-              requestCtx,
-            );
-          }
-        });
+        // Scheduled outside the caller's tag scope: an enclosing "use cache"
+        // entry bakes the stale value, not the refreshed one (#980).
+        outsideCacheTagScope(() =>
+          runBackground(requestCtx, async () => {
+            // The background body's handle pushes belong to the refreshed entry
+            // only: the foreground already replayed the stale entry's. They
+            // reach the REQUEST's store (a handler ctx.use(Handle) binds it at
+            // setupLoaderAccess, so a derived context with its own store never
+            // sees them), so the capture accepts only this body's chain and
+            // diverts what it records away from the live store. The foreground
+            // is still rendering here (runBackground starts on the next
+            // microtask), and its concurrent pushes are neither recorded nor
+            // diverted (issue #684, plan 010). A root scope: the task is
+            // detached, so an outer "use cache" body that scheduled it must not
+            // record the refresh's pushes.
+            const bgScope: CacheExecScope = {};
+            const bgCapture = liveStore
+              ? startHandleCapture(liveStore, {
+                  accept: () => isInCacheExecChain(bgScope),
+                  divert: true,
+                  key: recordKey,
+                })
+              : undefined;
+
+            // Tainted args are NOT stamped here, in contrast to the foreground
+            // miss path below. The args include the live HandlerContext the
+            // still-rendering foreground holds, and INSIDE_CACHE_EXEC is a
+            // property stamped onto that SHARED object — so for the whole
+            // revalidation window a concurrent foreground ctx.set() /
+            // ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
+            // never stamped anywhere for the same reason. In-body misuse IS
+            // still guarded here: runWithCacheExecScope below follows only this
+            // body's async chain, so a conditional cookies()/headers() read
+            // that fires only during revalidation throws instead of baking one
+            // user's value into the shared entry — with zero visibility to the
+            // concurrent foreground.
+
+            try {
+              // Re-establish the request-context ALS so a "use cache" body that
+              // reads the ambient getRequestContext() (e.g.
+              // getRequestContext().env.ApiKey) resolves during the background
+              // revalidation instead of throwing "called outside of a request
+              // context". runWithRequestContext sets the store for fn's
+              // synchronous kickoff; its async continuations inherit it.
+              //
+              // The span opens inside the request ALS and wraps the WHOLE task —
+              // fn kickoff through the store write — so its platform spans nest
+              // under rango.background and a slow or failing setItem is part of
+              // the traced revalidation, not an untraced tail.
+              await runWithRequestContext(requestCtx, () =>
+                observePhase(
+                  PHASES.background("use-cache-revalidation"),
+                  async () => {
+                    const refreshArgs = args.map(refreshView);
+                    // The refresh reads its data from here on (#973, #977).
+                    const start = executionStart();
+                    const scoped = runWithCacheTagScope(() =>
+                      runWithCacheExecScope(
+                        () => fn.apply(this, refreshArgs),
+                        bgScope,
+                      ),
+                    );
+                    const freshResult = await scoped.result;
+                    bgCapture?.stop();
+                    recordRequestTags(entryTags(scoped.tags), requestCtx);
+                    const flightErrors: unknown[] = [];
+                    const onFlightError = (error: unknown): void => {
+                      flightErrors.push(error);
+                    };
+                    const serialized = await inTagScope(scoped.tags, () =>
+                      serializeResult(freshResult, onFlightError),
+                    );
+                    if (serialized !== null) {
+                      const encodedHandles = bgCapture
+                        ? await inTagScope(scoped.tags, () =>
+                            encodeHandles(
+                              bgCapture.capture.data,
+                              onFlightError,
+                            ),
+                          )
+                        : undefined;
+                      // 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];
+                      const freshTags = entryTags(scoped.tags);
+                      // One of the refreshed value's tags was invalidated after
+                      // the refresh started: written now, a value that may
+                      // predate it would outlive it.
+                      if (await predatesInvalidation(store, freshTags, start)) {
+                        return;
+                      }
+                      await store.setItem!(cacheKey, serialized, {
+                        handles: encodedHandles,
+                        ttl: profile.ttl,
+                        swr: profile.swr,
+                        tags: freshTags.length > 0 ? freshTags : undefined,
+                      });
+                    }
+                  },
+                ),
+              );
+            } catch (bgError) {
+              bgCapture?.stop();
+              // Pass requestCtx explicitly: this runs in a detached background
+              // task where the ALS context is gone, so onError can only fire if
+              // we hand it the context captured up front.
+              reportCacheError(
+                bgError,
+                "stale-revalidation",
+                "[use cache] background revalidation failed",
+                requestCtx,
+              );
+            }
+          }),
+        );
         return result;
       } catch (error) {
         // Stale value is corrupt/partial; report and fall through to a fresh
@@ -757,8 +804,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 +827,15 @@ 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 (
+        !raced.predates &&
+        !invalidatedSince(raced.tags, existing.start.seq)
+      ) {
         try {
           return await serveCached({
             value: raced.serialized,
@@ -795,11 +849,17 @@ 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.
+      // One of the leader's tags was invalidated after it started, in any
+      // request or, as the store tells it, another isolate (#973, #977): 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 +876,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 start = executionStart();
     inFlightExecutions.set(cacheKey, {
       promise: envelopePromise,
       registeredAt: Date.now(),
+      start,
     });
     const clearSelf = (): void => {
       if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
@@ -881,13 +943,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       capture?.stop();
     }
 
-    // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
-    // after awaiting result so post-await cacheTag() calls are included.
-    // Normalize (drops empty profile tags, matching the invalidate path) + dedupe.
-    const allTags = [
-      ...new Set(normalizeTags([...(profile.tags ?? []), ...scoped!.tags])),
-    ];
-    recordRequestTags(allTags, requestCtx);
+    // Read scoped.tags after awaiting result so post-await cacheTag() calls
+    // are included.
+    const recorded = scoped!.tags;
+    recordRequestTags(entryTags(recorded), requestCtx);
 
     // Serialize + encode handles ONCE, resolve the in-flight envelope so any
     // concurrent followers can serve a synthetic hit, then persist to the store.
@@ -901,9 +960,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         flightErrors.push(error);
       };
       try {
-        serialized = await serializeResult(result, onFlightError);
+        serialized = await inTagScope(recorded, () =>
+          serializeResult(result, onFlightError),
+        );
         encodedHandles = capture
-          ? await encodeHandles(capture.capture.data, onFlightError)
+          ? await inTagScope(recorded, () =>
+              encodeHandles(capture.capture.data, onFlightError),
+            )
           : undefined;
         // Flight encodes an async component that throws, or a rejected
         // promise in the result or a handle value, as an error row and
@@ -917,8 +980,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         requestCtx?._reportBackgroundError?.(buildError, "cache-write");
         return;
       }
-      clearSelf();
       if (serialized === null) {
+        clearSelf();
         // Non-serializable result: no store write (matches the prior silent
         // skip); reject so any waiter falls through to a fresh execution.
         rejectEnvelope(
@@ -928,15 +991,32 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         );
         return;
       }
+      const tags = entryTags(recorded);
+      // One of the value's tags was invalidated after the execution started
+      // (#973, #977): written now, a value that may predate it would outlive
+      // it. Asked before the followers get the value: another isolate's
+      // invalidation is only in the store's answer, and a follower serving
+      // the value would bake it into its own entries. Yes also when the store
+      // cannot read a marker (predatesInvalidation asks it fail-closed) or
+      // throws: the cost is a later miss.
+      let predates = true;
+      try {
+        predates = await predatesInvalidation(store, tags, start);
+      } catch (gateError) {
+        requestCtx?._reportBackgroundError?.(gateError, "cache-write");
+      }
+      clearSelf();
       // Hand followers the envelope before the store write so a slow/failed
       // write never stalls them.
-      resolveEnvelope({ serialized, tags: allTags, handles: encodedHandles });
+      resolveEnvelope({ serialized, tags, handles: encodedHandles, predates });
+      // Skipped, the next read runs fresh.
+      if (predates) return;
       try {
         await store.setItem!(cacheKey, serialized, {
           handles: encodedHandles,
           ttl: profile.ttl,
           swr: profile.swr,
-          tags: allTags.length > 0 ? allTags : undefined,
+          tags: tags.length > 0 ? tags : undefined,
         });
       } catch (writeError) {
         requestCtx?._reportBackgroundError?.(writeError, "cache-write");