@rangojs/router 0.17.0 → 0.19.0

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

@@ -15,6 +15,7 @@ import type { ExecutionContext } from "../../types/request-scope.js";
 import type { CacheDefaults } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
 import type { CloudflareZonePurgeOptions } from "./cf-zone-purge.js";
+import type { StoreMemoOptions } from "../shell-memo.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.
@@ -340,9 +341,12 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
 
   /**
    * Latency budget (ms) for reading the BODY of a matched L1 entry
-   * (response.json()). CF streams the cache body lazily, so the multi-second
-   * tail can appear after `match` already resolved; this bounds it. On timeout
-   * the read is treated as a miss and falls through to L2/KV or render.
+   * (response.json(); for a PPR shell, only its head and prelude — the
+   * snapshot behind them is read after the HIT commits, under
+   * {@link kvReadTimeoutMs}). CF streams the cache body lazily, so the
+   * multi-second tail can appear after `match` already resolved; this bounds
+   * it. On timeout the read is treated as a miss and falls through to L2/KV or
+   * render.
    *
    * Separate from {@link edgeLookupTimeoutMs} because a healthy body read
    * (fetch + JSON parse of a potentially large Flight payload) takes a little
@@ -356,7 +360,11 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * Latency budget (ms) for an L2 (KV) read. KV is the last cache tier before a
    * full render and is a global store (~50ms healthy, seconds when degraded);
    * this bounds it so a slow namespace cannot pin the request. On timeout the
-   * read is treated as a miss (no L1 promote) and falls through to render.
+   * read is treated as a miss (no L1 promote) and falls through to render. For
+   * a PPR shell it covers opening the KV value and reading its head and
+   * prelude; separately, it bounds the shell's snapshot read (either tier),
+   * which runs off the commit path: a timeout there lets the tail run without
+   * the snapshot's pins.
    *
    * Defaults to {@link KV_READ_TIMEOUT_MS} (170) -- a few multiples above the
    * ~50ms healthy read, with headroom for legitimate tails (large payloads / far
@@ -367,6 +375,26 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   kvReadTimeoutMs?: number;
 
+  /**
+   * Per-isolate memos ({@link StoreMemoOptions}), one set per isolate and
+   * shared by every CFCacheStore in it. `shellMs` (default 2000) and
+   * `shellMaxBytes` (default 16 MiB) size the PPR shell memo;
+   * `markerFreshMs` (default 1000) and `markerMaxStaleMs` (default 10000)
+   * the tag-marker memo PPR shell reads use with KV bound (served
+   * stale-while-revalidate). A memo HIT still runs the tag-marker check; the
+   * isolate that invalidates drops its own shell copies (and keeps reads in
+   * flight from memoizing them again) and writes the new marker into its
+   * marker memo, and its own `putShell` replaces its copy. Another isolate
+   * rejects a memoized shell once its marker memo sees the invalidation (up
+   * to `markerMaxStaleMs`). Without KV, in purge mode, the purge does not
+   * reach other isolates' memos: they serve the purged shell until their
+   * window passes. The response of a request that ran `updateTag()` /
+   * `revalidateTag()` sets the fresh-reads cookie, and the same user's
+   * requests carrying it skip both memos. `{ shellMs: 0 }` turns the shell
+   * memo off, `{ markerFreshMs: 0 }` the marker memo.
+   */
+  memo?: StoreMemoOptions;
+
   /**
    * Emit a {@link CFCacheReadDebugEvent} per L1 read. `true` logs to console
    * (visible via `wrangler tail`); pass a function to capture events directly.

package/src/cache/cf/cf-shell-frame.ts

@@ -0,0 +1,258 @@
+/**
+ * Prelude-first binary layout of a CFCacheStore PPR shell entry, shared by the
+ * Cache API body and the KV value (issue #941; docs/design/shell-entry-layout.md):
+ *
+ *   "RSH1" | head length, 8 hex digits | head JSON | prelude bytes | snapshot JSON
+ *
+ * A document HIT needs the head (versions, freshness, tags, postponed) and the
+ * raw prelude before its first byte, and the capture snapshot only in the
+ * tail. Laying them out in that order lets the serve path read the head,
+ * start the tag-marker read, read exactly `pl` prelude bytes, and commit while
+ * the snapshot bytes are still arriving. One record keeps the prelude and the
+ * snapshot generation-coupled by construction: a Cache API entry and a KV
+ * value are written and read whole, so a split read can never pair one
+ * capture's prelude with another's pins.
+ *
+ * Every byte is UTF-8 text when the prelude is (React's HTML through
+ * TextEncoder always is), so the KV value is stored as a string (the
+ * KVNamespace contract's `put(key, string)`) and read back as the same bytes
+ * with `{ type: "stream" }`.
+ */
+
+import type { ShellSnapshotRecord } from "../types.js";
+
+const MAGIC = [0x52, 0x53, 0x48, 0x31]; // "RSH1"
+/** Magic (4) + head length as 8 hex digits (8). */
+const PREFIX_BYTES = 12;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const strictTextDecoder = new TextDecoder("utf-8", { fatal: true });
+
+/** The frame head: every entry field except the prelude and the snapshot. */
+export interface ShellFrameHead {
+  /** ShellCacheEntry.reactVersion */
+  rv: string;
+  /** ShellCacheEntry.buildVersion */
+  bv: string;
+  /** Capture-generation start time (ms epoch), used by tag marker checks. */
+  c: number;
+  /** When the entry becomes stale (ms epoch). */
+  s: number;
+  /** When the entry hard-expires (ms epoch). */
+  e: number;
+  /** Cache tags (for distributed tag invalidation). */
+  t?: string[];
+  /** Timestamp when tags were attached (ms epoch). */
+  ta?: number;
+  /** ShellCacheEntry.initialTheme */
+  i?: string;
+  /** ShellCacheEntry.docKey; navigation replay needs it after any round trip. */
+  dk?: string;
+  /** ShellCacheEntry.prunedRecords (diagnostic). */
+  pr?: string;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
+  /** ShellCacheEntry.postponed. Absent iff `no` (no document half is stored). */
+  po?: string | null;
+  /** Prelude byte length (0 for a navigationOnly entry). */
+  pl: number;
+  /**
+   * Snapshot byte length (0 when the entry has none). A body whose snapshot
+   * part is any other length was truncated or corrupted.
+   */
+  sl: number;
+}
+
+/** Validate a parsed head before any field reaches the serve path. */
+function isShellFrameHead(value: unknown): value is ShellFrameHead {
+  if (value == null || typeof value !== "object") return false;
+  const head = value as Partial<ShellFrameHead>;
+  return (
+    typeof head.rv === "string" &&
+    typeof head.bv === "string" &&
+    isFiniteNumber(head.c) &&
+    isFiniteNumber(head.s) &&
+    isFiniteNumber(head.e) &&
+    (head.t === undefined ||
+      (Array.isArray(head.t) &&
+        head.t.every((tag) => typeof tag === "string"))) &&
+    (head.ta === undefined || isFiniteNumber(head.ta)) &&
+    (head.i === undefined || typeof head.i === "string") &&
+    (head.dk === undefined || typeof head.dk === "string") &&
+    (head.pr === undefined || typeof head.pr === "string") &&
+    (head.no === undefined || head.no === true) &&
+    // Document half: postponed is required unless the entry is navigationOnly.
+    (head.po === null ||
+      typeof head.po === "string" ||
+      (head.po === undefined && head.no === true)) &&
+    isByteLength(head.pl) &&
+    isByteLength(head.sl)
+  );
+}
+
+function isByteLength(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * Serialize a shell entry into one prelude-first frame. Throws when the head's
+ * byte lengths (`pl`, `sl`) do not describe `prelude` and `snapshot`.
+ */
+export function encodeShellFrame(
+  head: ShellFrameHead,
+  prelude: Uint8Array,
+  snapshot?: Uint8Array,
+): Uint8Array<ArrayBuffer> {
+  const snapshotLength = snapshot?.length ?? 0;
+  if (head.pl !== prelude.length || head.sl !== snapshotLength) {
+    throw new Error("shell frame head does not match its prelude/snapshot");
+  }
+  const headBytes = textEncoder.encode(JSON.stringify(head));
+  const frame = new Uint8Array(
+    PREFIX_BYTES + headBytes.length + prelude.length + snapshotLength,
+  );
+  frame.set(MAGIC, 0);
+  frame.set(
+    textEncoder.encode(headBytes.length.toString(16).padStart(8, "0")),
+    MAGIC.length,
+  );
+  frame.set(headBytes, PREFIX_BYTES);
+  frame.set(prelude, PREFIX_BYTES + headBytes.length);
+  if (snapshot) {
+    frame.set(snapshot, PREFIX_BYTES + headBytes.length + prelude.length);
+  }
+  return frame;
+}
+
+/**
+ * The frame as the string KV stores. Throws when the prelude is not valid
+ * UTF-8, which would not round-trip through a string.
+ */
+export function shellFrameToText(frame: Uint8Array): string {
+  return strictTextDecoder.decode(frame);
+}
+
+/** UTF-8 JSON of a snapshot, or undefined when there is none to store. */
+export function encodeShellSnapshot(
+  snapshot: ShellSnapshotRecord[] | undefined,
+): Uint8Array | undefined {
+  return snapshot && snapshot.length > 0
+    ? textEncoder.encode(JSON.stringify(snapshot))
+    : undefined;
+}
+
+/**
+ * Parse the snapshot bytes that follow the prelude. Zero bytes means the entry
+ * carries no snapshot. Throws on anything else that is not a JSON array: the
+ * caller treats that as corruption.
+ */
+export function parseShellSnapshot(
+  bytes: Uint8Array,
+): ShellSnapshotRecord[] | undefined {
+  if (bytes.length === 0) return undefined;
+  const parsed: unknown = JSON.parse(textDecoder.decode(bytes));
+  if (!Array.isArray(parsed)) {
+    throw new Error("shell snapshot is not an array");
+  }
+  return parsed as ShellSnapshotRecord[];
+}
+
+/**
+ * Incremental reader over a streamed frame (a Cache API response body or a KV
+ * `{ type: "stream" }` value). The serve path reads the head and exactly the
+ * prelude's bytes before it commits; the snapshot is whatever remains.
+ */
+export class ShellFrameReader {
+  private readonly reader: ReadableStreamDefaultReader<Uint8Array>;
+  private chunks: Uint8Array[] = [];
+  private buffered = 0;
+  private done = false;
+  /** Bytes of the prefix and head, once readHead has read them. */
+  headBytes = 0;
+
+  constructor(body: ReadableStream<Uint8Array>) {
+    this.reader = body.getReader();
+  }
+
+  /** Exactly `n` bytes, or null when the stream ends first. */
+  async take(n: number): Promise<Uint8Array | null> {
+    while (this.buffered < n && !this.done) {
+      const { done, value } = await this.reader.read();
+      if (done) {
+        this.done = true;
+      } else if (value.length > 0) {
+        this.chunks.push(value);
+        this.buffered += value.length;
+      }
+    }
+    if (this.buffered < n) return null;
+    const out = concat(this.chunks, n);
+    const leftover = this.buffered - n;
+    const last = this.chunks[this.chunks.length - 1]!;
+    this.chunks = leftover > 0 ? [last.subarray(last.length - leftover)] : [];
+    this.buffered = leftover;
+    return out;
+  }
+
+  /** The head, or null when the magic, length, or JSON is malformed or short. */
+  async readHead(): Promise<ShellFrameHead | null> {
+    const prefix = await this.take(PREFIX_BYTES);
+    if (!prefix || MAGIC.some((byte, index) => prefix[index] !== byte)) {
+      return null;
+    }
+    const lengthDigits = textDecoder.decode(prefix.subarray(MAGIC.length));
+    if (!/^[0-9a-f]{8}$/.test(lengthDigits)) return null;
+    const headBytes = await this.take(Number.parseInt(lengthDigits, 16));
+    if (!headBytes) return null;
+    this.headBytes = PREFIX_BYTES + headBytes.length;
+    let head: unknown;
+    try {
+      head = JSON.parse(textDecoder.decode(headBytes));
+    } catch {
+      return null;
+    }
+    return isShellFrameHead(head) ? head : null;
+  }
+
+  /** Everything after what was taken, to the end of the stream. */
+  async readRest(): Promise<Uint8Array> {
+    while (!this.done) {
+      const { done, value } = await this.reader.read();
+      if (done) {
+        this.done = true;
+      } else if (value.length > 0) {
+        this.chunks.push(value);
+        this.buffered += value.length;
+      }
+    }
+    const out = concat(this.chunks, this.buffered);
+    this.chunks = [];
+    this.buffered = 0;
+    return out;
+  }
+
+  /** Stop reading and release the body. */
+  cancel(): void {
+    this.done = true;
+    this.reader.cancel().catch(() => {});
+  }
+}
+
+/** The first `n` bytes of `chunks` as one array (no copy for a single chunk). */
+function concat(chunks: Uint8Array[], n: number): Uint8Array {
+  if (chunks.length === 1 && chunks[0]!.length === n) return chunks[0]!;
+  const out = new Uint8Array(n);
+  let offset = 0;
+  for (const chunk of chunks) {
+    if (offset >= n) break;
+    const part = chunk.subarray(0, Math.min(chunk.length, n - offset));
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}

package/src/cache/cf/cf-tag-marker-memo.ts

@@ -2,12 +2,18 @@
 // Tag-marker memo
 // ============================================================================
 //
-// Per-request memoization of tag-invalidation marker reads, plus the prefix and
-// sentinel used by the optional per-colo L1 marker cache. Extracted from
-// cf-cache-store.ts; the WeakMaps stay MODULE SINGLETONS here (the module is
-// evaluated once), so binding-keyed memo semantics are unchanged: the maps are
-// keyed by the request-context object then the store INSTANCE, identical to
-// before the move.
+// CFCacheStore's per-request tag-marker state: the data families' marker memo
+// and in-flight reads, the PPR shell read's own marker record, and the prefix
+// and sentinel of the optional per-colo L1 marker cache. The maps are module
+// singletons keyed by the request-context object, then the store INSTANCE.
+// The request's own invalidations are not here: they are the per-request
+// mask (request-tag-mask.ts), which every marker check consults first.
+
+import type { MarkerMemoOutcome } from "../isolate-tag-memo.js";
+import {
+  perRequestStoreValue,
+  type PerRequestStoreMap,
+} from "../request-tag-mask.js";
 
 /**
  * Cache-API path prefix for the optional per-colo L1 cache of tag-invalidation
@@ -42,38 +48,28 @@ export const TAG_MARKER_ABSENT = "none";
  * short-circuits when a store has no KV — and, in purge mode, through
  * isL1Invalidated(), which consults ONLY this memo on an L1 hit (no KV read),
  * so a purge-mode store allocates the memo even without KV for same-request
- * read-your-own-writes after updateTag().
+ * read-your-own-writes after updateTag()/revalidateTag().
  *
  * Without the memo, isGloballyInvalidated() issues a KV read per tag on every
  * tagged cache read, so a page composed of many segments/items sharing a tag
  * pays that cost N times. The memo collapses it to one KV read per distinct tag
- * per (request, store). invalidateTags() writes through so a same-request
- * updateTag() stays read-your-own-writes consistent (the action's own re-render
- * sees its own invalidation from the memo, without a re-read).
+ * per (request, store). It holds only values read from L1 or KV: the request's
+ * own invalidations are the mask (request-tag-mask.ts), checked before any
+ * marker read, so a value in the memo is always safe to publish.
  *
  * It does NOT span requests, so a hot single-entry route still pays one KV read
  * per request; that read hits Cloudflare KV's own edge read cache for hot keys.
+ * A context derived from the request (Object.create(reqCtx): a PPR HIT tail, a
+ * shell capture) keeps a memo of its own, so its marker reads stay its own.
  */
-const tagMarkerMemo = new WeakMap<
-  object,
-  WeakMap<object, Map<string, number | null>>
->();
+const tagMarkerMemo: PerRequestStoreMap<Map<string, number | null>> =
+  new WeakMap();
 
 export function getTagMarkerMemo(
   ctx: object,
   store: object,
 ): Map<string, number | null> {
-  let byStore = tagMarkerMemo.get(ctx);
-  if (!byStore) {
-    byStore = new WeakMap();
-    tagMarkerMemo.set(ctx, byStore);
-  }
-  let memo = byStore.get(store);
-  if (!memo) {
-    memo = new Map();
-    byStore.set(store, memo);
-  }
-  return memo;
+  return perRequestStoreValue(tagMarkerMemo, ctx, store, () => new Map());
 }
 
 /**
@@ -85,24 +81,43 @@ export function getTagMarkerMemo(
  * collapses those to a single KV read. Entries are dropped once resolved (the
  * value is then in the memo), so this only spans the concurrent read window.
  */
-const tagMarkerInflight = new WeakMap<
-  object,
-  WeakMap<object, Map<string, Promise<number | null>>>
->();
+const tagMarkerInflight: PerRequestStoreMap<
+  Map<string, Promise<number | null>>
+> = new WeakMap();
+
+/**
+ * A request's PPR shell-read marker reads (issue #941), kept apart from the
+ * per-request memo above, HIT or MISS. A shell read may answer a marker from
+ * the isolate marker memo (isolate-tag-memo.ts), up to `markerMaxStaleMs`
+ * old; the data families must never see that value. Scar tissue: first the
+ * shell read wrote into the per-request memo, so a MISS request rendered and
+ * stored its `"use cache"` data under a stale marker; then a HIT copied its
+ * entry's tags across, which a partial navigation's matchPartial (on the same
+ * context as its replay gate's getShell) read, and a `cache()` segment it
+ * wrote kept the stale item past `markerMaxStaleMs` under a fresh taggedAt.
+ */
+export interface ShellMarkerReads {
+  /** The read of each tag, settled or in flight (collapses concurrent reads). */
+  reads: Map<string, Promise<number | null>>;
+  /** How the isolate memo answered each tag (the marker row's `memo=`). */
+  outcomes: Map<string, MarkerMemoOutcome>;
+}
+
+const shellMarkerReads: PerRequestStoreMap<ShellMarkerReads> = new WeakMap();
+
+export function getShellMarkerReads(
+  ctx: object,
+  store: object,
+): ShellMarkerReads {
+  return perRequestStoreValue(shellMarkerReads, ctx, store, () => ({
+    reads: new Map(),
+    outcomes: new Map(),
+  }));
+}
 
 export function getTagMarkerInflight(
   ctx: object,
   store: object,
 ): Map<string, Promise<number | null>> {
-  let byStore = tagMarkerInflight.get(ctx);
-  if (!byStore) {
-    byStore = new WeakMap();
-    tagMarkerInflight.set(ctx, byStore);
-  }
-  let inflight = byStore.get(store);
-  if (!inflight) {
-    inflight = new Map();
-    byStore.set(store, inflight);
-  }
-  return inflight;
+  return perRequestStoreValue(tagMarkerInflight, ctx, store, () => new Map());
 }

package/src/cache/document-cache.ts

@@ -13,6 +13,7 @@
  * 4. If miss → run handler, cache if response has cache headers
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import { hasPerClientSignal } from "../browser/cookie-name.js";
 import {
@@ -24,6 +25,7 @@ import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { cacheKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
+import { executionStart, predatesInvalidation } from "./tag-invalidation.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -109,7 +111,10 @@ function parseCacheControl(header: string | null): CacheDirectives | null {
 /**
  * Check if response should be cached based on Cache-Control headers
  */
-function shouldCacheResponse(response: Response): CacheDirectives | null {
+function shouldCacheResponse(
+  response: Response,
+  requestCtx?: Pick<RequestContext, "_payloadVisitorTheme">,
+): CacheDirectives | null {
   // Only cache successful responses
   if (response.status !== 200) {
     return null;
@@ -125,10 +130,34 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
     return null;
   }
 
+  // The payload carries the visitor's theme (#978): the render ran before the
+  // response opted in (a Cache-Control written after next()), so
+  // payloadInitialTheme could not render the default.
+  if (requestCtx?._payloadVisitorTheme) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }
 
+/**
+ * Whether this cache will store the response the current render produces, as
+ * far as the render can tell: the middleware runs it (a MISS or a stale
+ * refresh) and the response stub already opts in. payloadInitialTheme
+ * (rsc/full-payload.ts) then renders the no-cookie default theme (#978). A
+ * Cache-Control written after next() is not on the stub yet; for that render
+ * shouldCacheResponse refuses a payload marked `_payloadVisitorTheme`.
+ */
+export function documentCacheStoresRender(
+  reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">,
+): boolean {
+  return (
+    reqCtx._documentCacheRender === true &&
+    shouldCacheResponse(reqCtx.res) !== null
+  );
+}
+
 /**
  * Throw the first error the drained render reported through Flight or Fizz
  * onError. A component that throws after the 200 committed does not fail the
@@ -279,7 +308,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     // are not visible on ctx.url in production.
     const rawUrl = new URL(ctx.request.url);
     const isFragmentRecovery =
-      ctx.request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) === "1";
+      requestHeaders(ctx.request).get(SEGMENT_FRAGMENT_RECOVERY_HEADER) === "1";
 
     // Only cache GET requests — mutations and other methods must not be cached
     if (ctx.request.method !== "GET") {
@@ -318,6 +347,11 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       return next();
     }
 
+    // The write gate's start (#977): the request's, not this middleware's. 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();
+
     // Determine request type for cache key differentiation.
     // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
     // detection. Full-document RSC fetches must not share the HTML cache slot.
@@ -343,7 +377,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // match-time capability gate.
       const fragmentSuffix =
         isPartial &&
-        (ctx.request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1" ||
+        (requestHeaders(ctx.request).get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) ===
+          "1" ||
           isFragmentRecovery)
           ? ":fragments"
           : "";
@@ -374,6 +409,9 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       const cached = isFragmentRecovery
         ? 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;
 
       if (cached && cached.response.status === 200) {
         if (!cached.shouldRevalidate) {
@@ -409,7 +447,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                 PHASES.background("document-revalidation"),
                 async () => {
                   const fresh = await next();
-                  const directives = shouldCacheResponse(fresh);
+                  const directives = shouldCacheResponse(fresh, requestCtx);
 
                   if (!directives || !fresh.body) return;
 
@@ -418,12 +456,16 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                   // (same render-complete barrier as the miss path).
                   const body = await new Response(fresh.body).arrayBuffer();
                   throwIfRenderErrored(requestCtx);
+                  // Not written when one of its tags was invalidated since
+                  // the render started (#977).
+                  const tags = collectRequestTags(requestCtx);
+                  if (await predatesInvalidation(store, tags, start)) return;
                   await store.putResponse!(
                     cacheKey,
                     new Response(body, fresh),
                     directives.sMaxAge!,
                     directives.staleWhileRevalidate,
-                    collectRequestTags(requestCtx),
+                    tags,
                   );
                   log(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
@@ -456,7 +498,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       const originalResponse = await next();
 
       // 3. Cache if response has appropriate headers
-      const directives = shouldCacheResponse(originalResponse);
+      const directives = shouldCacheResponse(originalResponse, requestCtx);
 
       if (directives) {
         log(
@@ -483,12 +525,16 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             // body and its tag set consistent.
             const body = await new Response(cacheStream).arrayBuffer();
             throwIfRenderErrored(requestCtx);
+            // Not written when one of its tags was invalidated since the
+            // render started (#977).
+            const tags = collectRequestTags(requestCtx);
+            if (await predatesInvalidation(store, tags, start)) return;
             await store.putResponse!(
               cacheKey,
               new Response(body, originalResponse),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
-              collectRequestTags(requestCtx),
+              tags,
             );
           } catch (error) {
             // Detached waitUntil task — pass the captured requestCtx so onError