@rangojs/router 0.20.0 → 0.22.0

package/src/cache/cf/cf-cache-store.ts

@@ -1,5 +1,3 @@
-/// <reference path="../../vite/plugins/version.d.ts" />
-
 // Extend CacheStorage with Cloudflare's default cache property
 declare global {
   interface CacheStorage {
@@ -29,6 +27,7 @@ declare global {
 
 import { requestHeaders } from "../../server/request-headers.js";
 import type {
+  CacheStoreScope,
   SegmentCacheStore,
   CachedEntryData,
   CacheDefaults,
@@ -50,7 +49,10 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
-import { VERSION } from "@rangojs/router:version";
+import {
+  versionKeyPrefix,
+  type KeyVersion,
+} from "../../server/build-version-table.js";
 import {
   isPerClientSignalHeader,
   stripPerClientSignals,
@@ -117,6 +119,7 @@ import {
   DEFAULT_CF_MARKER_MAX_STALE_MS,
 } from "../isolate-tag-memo.js";
 import { createCloudflareZonePurge } from "./cf-zone-purge.js";
+import { responseStartedAt, taggedStamp } from "../invalidation-order.js";
 
 // ============================================================================
 // Constants
@@ -314,10 +317,9 @@ interface KVItemEnvelope {
 
 /**
  * Key namespace of the shell family. `shell2:` holds the prelude-first frame
- * (cf-shell-frame.ts); `shell:` held the JSON envelope. Every deploy retires
- * the old entries anyway (buildVersion gate); the new namespace also keeps
- * new code from reporting an old body as corrupt and a rollback from parsing
- * a frame. Old keys age out by their TTL.
+ * (cf-shell-frame.ts); `shell:` held the JSON envelope. The separate
+ * namespace keeps new code from reporting an old body as corrupt and a
+ * rollback from parsing a frame. Old keys age out by their TTL.
  */
 const SHELL_KEY_PREFIX = "shell2:";
 
@@ -494,7 +496,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly namespace?: string;
   private readonly explicitBaseUrl?: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
-  private readonly version?: string;
+  /** The `version` option: used for every versioned family when set. */
+  private readonly explicitVersion?: string;
   private readonly edgeLookupTimeoutMs: number;
   private readonly edgeReadTimeoutMs: number;
   private readonly kvReadTimeoutMs: number;
@@ -518,6 +521,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly kv?: KVNamespace;
   /** True when constructed without KV: no durable tag history (see ctor). */
   readonly tagHistoryInert?: boolean;
+  /**
+   * SegmentCacheStore.scope: with KV every colo's L1 miss reads the same L2
+   * entry ("global"); without it entries live in one colo's Cache API
+   * ("local"), purge mode included (a purge evicts, it stores nothing).
+   */
+  readonly scope: CacheStoreScope;
   private readonly onRevalidateTag?: (tags: string[]) => Promise<void>;
   private readonly tagPurge?: (cacheTags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
@@ -540,7 +549,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // the internal host. Only the explicit override can be captured eagerly.
     this.explicitBaseUrl = options.baseUrl;
     this.defaults = options.defaults;
-    this.version = options.version ?? VERSION;
+    this.explicitVersion = options.version;
     // Coalesce only finite numbers to the override; a non-finite value (NaN from
     // `Number(env.UNSET)`, or Infinity) would otherwise sail past `?? DEFAULT`
     // (which only replaces null/undefined) into setTimeout, where NaN/Infinity
@@ -603,6 +612,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // evict it (purge cannot delete a build asset), so the manifest gate
     // declines on this flag (shell-build-manifest.ts).
     this.tagHistoryInert = options.kv ? undefined : true;
+    this.scope = options.kv ? "global" : "local";
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -1134,7 +1144,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.isReservedSegmentKey(key, "cache-read")) return null;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(key);
+      const request = this.keyToRequest(key, "data");
       const matchStart = Date.now();
       const {
         response,
@@ -1381,20 +1391,18 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.skipUncacheableTagSet(data.tags)) return;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(key);
+      const request = this.keyToRequest(key, "data");
 
       // Extended TTL covers SWR window
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
 
-      // Stamp the tag timestamp at write time and carry it (with the tags)
-      // into both the L1 body and the KV envelope so reads can run the
-      // invalidation check.
-      const taggedAt =
-        Array.isArray(data.tags) && data.tags.length > 0
-          ? Date.now()
-          : undefined;
+      // Stamp the tag timestamp and carry it (with the tags) into both the
+      // L1 body and the KV envelope so reads can run the invalidation check.
+      // It is the render's start when the writer passed it (#1068), else the
+      // write time: a marker written while the render ran then rejects it.
+      const taggedAt = taggedStamp(data.tags, data.taggedAt);
       const dataToStore: CachedEntryData = taggedAt
         ? { ...data, taggedAt }
         : data;
@@ -1457,11 +1465,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.isReservedSegmentKey(key, "cache-delete")) return false;
     try {
       const cache = await this.getCache();
-      const result = await cache.delete(this.keyToRequest(key));
+      const result = await cache.delete(this.keyToRequest(key, "data"));
 
       // L2: delete from KV
       if (this.kv && this.waitUntil) {
-        const kvKey = await this.toKVKey(key);
+        const kvKey = await this.toKVKey(key, "data");
         this.waitUntil(() =>
           reportingAsync(
             () => this.kv!.delete(kvKey),
@@ -1492,7 +1500,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`doc:${key}`);
+      const request = this.keyToRequest(`doc:${key}`, "document");
       // The document path is outside the debug surface (op is only get/getItem),
       // so the match-timeout flag is not surfaced as an event here -- though
       // matchWithTimeout still warns on a slow match. A miss or timeout falls
@@ -1633,14 +1641,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.skipUncacheableTagSet(tags)) return;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`doc:${key}`);
+      const request = this.keyToRequest(`doc:${key}`, "document");
 
       // Extended TTL covers SWR window
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
-      const taggedAt =
-        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+      const taggedAt = taggedStamp(tags, responseStartedAt(response));
 
       // Clone body for potential KV write before consuming it for L1
       const [l1Body, kvBody] = this.kv
@@ -1747,7 +1754,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   async getItem(key: string): Promise<CacheItemResult | null> {
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`fn:${key}`);
+      const request = this.keyToRequest(`fn:${key}`, "data");
       const matchStart = Date.now();
       const {
         response,
@@ -1932,7 +1939,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.skipUncacheableTagSet(options?.tags)) return;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`fn:${key}`);
+      const request = this.keyToRequest(`fn:${key}`, "data");
 
       const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
@@ -1940,8 +1947,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const staleAt = Date.now() + ttl * 1000;
 
       const tags = options?.tags;
-      const taggedAt =
-        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
+      const taggedAt = taggedStamp(tags, options?.startedAt);
 
       // Serialize value/handles once; L1 body and KV envelope.v/h share the
       // escaped strings so a large RSC payload is not re-escaped for L2.
@@ -1984,7 +1990,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // JSON.stringify(KVItemEnvelope); field names differ from L1 so we assemble
       // from the pre-escaped value/handles pieces rather than re-stringifying.
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = await this.toKVKey(`fn:${key}`);
+        const kvKey = await this.toKVKey(`fn:${key}`, "data");
         const expiresAt = staleAt + swrWindow * 1000;
         let envelopeJson = `{"v":${valueJson}`;
         if (handlesJson !== undefined) envelopeJson += `,"h":${handlesJson}`;
@@ -2154,7 +2160,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`);
+      const request = this.shellRequest(key);
       const matchStartedAt = stats ? performance.now() : 0;
       const {
         response,
@@ -2297,14 +2303,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
-  /** The isolate marker memo's key for a tag: markers are per namespace and version. */
+  /**
+   * The isolate marker memo's key for a tag: markers are per namespace, and
+   * shared by every version (tagMarkerKey).
+   */
   private markerMemoKey(tag: string): string {
-    return `${this.namespace ?? ""}\u0000${this.version ?? ""}\u0000${tag}`;
+    return `${this.namespace ?? ""}\u0000${tag}`;
   }
 
-  /** The memo key: one per namespace, build version, base URL, and shell key. */
+  /** The memo key: one per namespace, document version, base URL, and shell key. */
   private shellMemoKey(key: string): string {
-    return `${this.namespace ?? ""}\u0000${this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`).url}`;
+    return `${this.namespace ?? ""}\u0000${this.shellRequest(key).url}`;
   }
 
   /**
@@ -2571,15 +2580,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const evict = async (): Promise<void> => {
       const cache = await this.getCache();
       await reportingAsync(
-        () => cache.delete(this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`)),
+        () => cache.delete(this.shellRequest(key)),
         "cache-delete",
         "[CFCacheStore] getShell: evict corrupt L1",
       );
       if (this.kv) {
-        await this.evictKvKey(
-          await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`),
-          "getShell",
-        );
+        await this.evictKvKey(await this.shellKVKey(key), "getShell");
       }
     };
     if (this.waitUntil) this.waitUntil(evict);
@@ -2641,9 +2647,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
       const writeKv = !!this.kv && retentionTtl > 0;
-      const kvKey = writeKv
-        ? await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`)
-        : null;
+      const kvKey = writeKv ? await this.shellKVKey(key) : null;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
@@ -2684,7 +2688,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             try {
               const cache = await this.getCache();
               await cache.put(
-                this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`),
+                this.shellRequest(key),
                 this.shellFrameResponse(frame, head),
               );
               this.debugShell(key, "l1-stored", { expiresAt: head.e });
@@ -2781,7 +2785,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // One kvReadTimeoutMs budget covers opening the value and reading its
       // head and prelude; the remainder after the open bounds the frame read.
       const deadline = Date.now() + this.kvReadTimeoutMs;
-      const kvKey = await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`);
+      const kvKey = await this.shellKVKey(key);
       // A transient read REJECTION propagates to the catch below (reported
       // cache-read, the entry left intact); only a malformed frame on a body
       // that WAS read is corruption that evicts.
@@ -2884,7 +2888,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           if (Date.now() > head.e) return;
           const cache = await this.getCache();
           await cache.put(
-            this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`),
+            this.shellRequest(key),
             this.shellFrameResponse(
               encodeShellFrame(head, prelude, snapshotBytes),
               head,
@@ -2905,18 +2909,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // Key Helpers
   // ============================================================================
 
+  private shellRequest(key: string): Request {
+    return this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`, "document");
+  }
+
+  private shellKVKey(key: string): Promise<string> {
+    return this.toKVKey(`${SHELL_KEY_PREFIX}${key}`, "document");
+  }
+
   /**
    * Convert string key to Request object for CF Cache API.
-   * Includes version in URL if specified (for cache invalidation on code changes).
+   *
+   * `family` picks the version in the URL path, so a version change misses:
+   * `"data"` for segment entries and `fn:` items (cached RSC data, valid while
+   * the router's server code is unchanged), `"document"` for `doc:` responses
+   * and `shell2:` shells (their bytes carry asset URLs and the handler
+   * version), `null` for tag markers, which apply to every version.
    * @internal
    */
-  private keyToRequest(key: string): Request {
+  private keyToRequest(key: string, family: KeyVersion): Request {
     const encodedKey = encodeURIComponent(key);
-    // Include version in URL path to invalidate cache when version changes
-    const versionPath = this.version ? `v/${this.version}/` : "";
-    return new Request(`${this.resolveBaseUrl()}${versionPath}${encodedKey}`, {
-      method: "GET",
-    });
+    return new Request(
+      `${this.resolveBaseUrl()}${versionKeyPrefix(this.explicitVersion, family)}${encodedKey}`,
+      { method: "GET" },
+    );
   }
 
   /**
@@ -2937,9 +2953,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * and delete paths agree on the stored key.
    * @internal
    */
-  private async toKVKey(key: string): Promise<string> {
-    const versionPath = this.version ? `v/${this.version}/` : "";
-    const composed = `${versionPath}${key}`;
+  private async toKVKey(key: string, family: KeyVersion): Promise<string> {
+    const composed = `${versionKeyPrefix(this.explicitVersion, family)}${key}`;
     if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
     const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
     return `${prefix}~${await kvKeyDigest(composed)}`;
@@ -2973,7 +2988,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * @internal
    */
   private toDocKVKey(key: string): Promise<string> {
-    return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
+    return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`, "document");
   }
 
   /**
@@ -3087,9 +3102,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // Tag Invalidation (single-store: markers live in this.kv)
   // ============================================================================
 
-  /** KV key for a tag's invalidation marker. */
+  /**
+   * KV key for a tag's invalidation marker. Unversioned: a content-hash
+   * version can come back (deploy A, deploy B, roll back to A), and a marker
+   * written while B was live has to be visible to A's entries. The staleness
+   * check compares the marker time with the entry's taggedAt and nothing else
+   * (isGloballyInvalidated), so one marker per tag serves every version.
+   */
   private tagMarkerKey(tag: string): Promise<string> {
-    return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`);
+    return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`, null);
   }
 
   /**
@@ -3320,9 +3341,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return false;
   }
 
-  /** Synthetic Cache API request for a tag's L1-cached invalidation marker. */
+  /**
+   * Synthetic Cache API request for a tag's L1-cached invalidation marker.
+   * Unversioned for the same reason as tagMarkerKey; the cache namespace
+   * (getCache) still scopes it.
+   */
   private tagMarkerRequest(tag: string): Request {
-    return this.keyToRequest(`${TAG_MARKER_CACHE_PREFIX}${tag}`);
+    return this.keyToRequest(`${TAG_MARKER_CACHE_PREFIX}${tag}`, null);
   }
 
   /**
@@ -3974,7 +3999,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = await this.toKVKey(key);
+      const kvKey = await this.toKVKey(key, "data");
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVSegmentEnvelope>(
           kvKey,
@@ -4076,7 +4101,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.waitUntil(() =>
       reportingAsync(
         async () =>
-          this.kv!.put(await this.toKVKey(key), envelopeJson, {
+          this.kv!.put(await this.toKVKey(key, "data"), envelopeJson, {
             expirationTtl: totalTtl,
           }),
         "cache-write",
@@ -4101,7 +4126,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             Math.floor((envelope.e - now) / 1000),
           );
           const cache = await this.getCache();
-          const request = this.keyToRequest(key);
+          const request = this.keyToRequest(key, "data");
 
           const response = new Response(JSON.stringify(envelope.d), {
             headers: {
@@ -4137,7 +4162,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = await this.toKVKey(`fn:${key}`);
+      const kvKey = await this.toKVKey(`fn:${key}`, "data");
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVItemEnvelope>(
           kvKey,
@@ -4221,7 +4246,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             Math.floor((envelope.e - now) / 1000),
           );
           const cache = await this.getCache();
-          const request = this.keyToRequest(`fn:${key}`);
+          const request = this.keyToRequest(`fn:${key}`, "data");
 
           const body = JSON.stringify({
             value: envelope.v,
@@ -4355,7 +4380,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             Math.floor((envelope.e - now) / 1000),
           );
           const cache = await this.getCache();
-          const request = this.keyToRequest(`doc:${key}`);
+          const request = this.keyToRequest(`doc:${key}`, "document");
 
           const headers = new Headers(envelope.hd);
           const originalCacheControl = headers.get("Cache-Control");

package/src/cache/cf/cf-cache-types.ts

@@ -320,11 +320,19 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
   tagCacheTtl?: number;
 
   /**
-   * Cache version string override. When this changes, all cached entries are
-   * effectively invalidated (new keys won't match old entries).
+   * Cache version string override. When set, this exact value prefixes every
+   * versioned key the store writes (`v/{version}/...`), for cached data and
+   * stored HTML alike; changing it makes every earlier entry unreachable.
    *
-   * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
+   * Leave it unset for the default: the store keys with the versions of the
+   * router serving the request. Segment entries and `"use cache"` items use
+   * the router's data version; document responses and PPR shells use its
+   * document version (see `createRouter({ version })`). Those are computed
+   * from the router's built code, so a deploy that does not change the router
+   * keeps its entries.
+   *
+   * Tag invalidation markers are never versioned: an invalidation applies to
+   * the entries of every version, including one that comes back in a rollback.
    */
   version?: string;
 

package/src/cache/document-cache.ts

@@ -22,10 +22,19 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
-import { cacheKeyBase } from "./cache-key-utils.js";
+import { requestKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import {
+  isWarmReplace,
+  noteWarmDocument,
+  noteWarmWrite,
+} from "../prerender/warm-request.js";
 import { reportCacheError } from "./cache-error.js";
-import { executionStart, predatesInvalidation } from "./tag-invalidation.js";
+import {
+  executionStart,
+  markResponseStart,
+  predatesInvalidation,
+} from "./tag-invalidation.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -239,11 +248,14 @@ export interface DocumentCacheOptions<TEnv = any> {
   /**
    * Custom cache key generator.
    *
-   * Replaces the default `host + pathname + search` key entirely. On a
-   * multi-domain deployment served by one function you MUST include `url.host`
-   * (or an equivalent tenant discriminator) yourself — the default key is
-   * host-namespaced, but a custom generator's output is used verbatim, so
-   * omitting host bleeds one hostname's cached response to another.
+   * Replaces the default `router id + host + pathname + search` key entirely.
+   * On a multi-domain deployment served by one function you MUST include
+   * `url.host` (or an equivalent tenant discriminator) yourself — the default
+   * key is host-namespaced, but a custom generator's output is used verbatim,
+   * so omitting host bleeds one hostname's cached response to another. The
+   * same goes for the router: two routers that share a cache store and can
+   * serve one host and path (a `hostOverride` cookie) need a generator that
+   * tells them apart.
    */
   keyGenerator?: (url: URL) => string;
 
@@ -347,7 +359,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
-    // The write gate's start (#977): the request's, not this middleware's. A
+    // The write gate's start (#977) and the entry's stamp (#1068): the
+    // request's, not this middleware's, also for a stale refresh. A
     // middleware ahead of this one can read tagged data the document bakes,
     // and a stale refresh re-runs the handler over what they set.
     const start = requestCtx._requestStart ?? executionStart();
@@ -392,7 +405,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // existing keys and double any host they already include).
       const cacheKey = keyGenerator
         ? keyGenerator(url) + segmentHash + fragmentSuffix + typeSuffix
-        : cacheKeyBase(
+        : requestKeyBase(
+            requestCtx,
             url.host,
             url.pathname,
             url.searchParams,
@@ -406,9 +420,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // Recovery must reach CacheScope's server decoder so it can evict the bad
       // segment. Treat it as a miss, then let the ordinary write path replace
       // the corrupt fragment-capable response with the valid fallback bytes.
-      const cached = isFragmentRecovery
-        ? null
-        : await store.getResponse(cacheKey);
+      // A router.prerender() warm is a miss too: it renders and replaces.
+      const cached =
+        isFragmentRecovery || isWarmReplace(requestCtx)
+          ? null
+          : await store.getResponse(cacheKey);
       // Every path past the lookup either returns a fresh HIT, which renders
       // nothing, or renders a response this cache may store.
       requestCtx._documentCacheRender = true;
@@ -462,11 +478,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                   if (await predatesInvalidation(store, tags, start)) return;
                   await store.putResponse!(
                     cacheKey,
-                    new Response(body, fresh),
+                    markResponseStart(new Response(body, fresh), start),
                     directives.sMaxAge!,
                     directives.staleWhileRevalidate,
                     tags,
                   );
+                  noteWarmWrite(requestCtx, "response");
+                  noteWarmDocument(requestCtx, "stored");
                   log(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
                   );
@@ -531,11 +549,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             if (await predatesInvalidation(store, tags, start)) return;
             await store.putResponse!(
               cacheKey,
-              new Response(body, originalResponse),
+              markResponseStart(new Response(body, originalResponse), start),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
               tags,
             );
+            noteWarmWrite(requestCtx, "response");
+            noteWarmDocument(requestCtx, "stored");
           } catch (error) {
             // Detached waitUntil task — pass the captured requestCtx so onError
             // fires even though the ALS context is gone (see the revalidation
@@ -556,6 +576,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       }
 
       // No cache headers - pass through
+      noteWarmDocument(requestCtx, "not-cacheable");
       return originalResponse;
     } catch (error) {
       reportCacheError(error, "cache-read", "[DocumentCache] middleware");