@rangojs/router 0.17.0 → 0.18.0

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

@@ -35,6 +35,11 @@ import type {
   CacheItemResult,
   CacheItemOptions,
   ShellCacheEntry,
+  ShellDocumentRead,
+  ShellDocumentReadOptions,
+  ShellReadStats,
+  ShellSnapshotFailure,
+  ShellSnapshotRecord,
   CacheReadError,
 } from "../types.js";
 import { CACHE_READ_ERROR } from "../types.js";
@@ -55,7 +60,30 @@ import {
 } from "../cache-policy.js";
 import { reportCacheError, reportingAsync } from "../cache-error.js";
 import type { CacheErrorCategory } from "../cache-error.js";
-import { bufferToBase64, base64ToBuffer } from "./cf-base64.js";
+import {
+  bufferToBase64,
+  base64ToBuffer,
+  base64ToBytes,
+  bytesToBase64,
+} from "./cf-base64.js";
+import {
+  ShellFrameReader,
+  encodeShellFrame,
+  encodeShellSnapshot,
+  parseShellSnapshot,
+  shellFrameToText,
+  type ShellFrameHead,
+} from "./cf-shell-frame.js";
+import {
+  ShellMemo,
+  RecentTagInvalidations,
+  DEFAULT_SHELL_MEMO_MS,
+  freshReadsWindowMs,
+  isShellFresh,
+  resolveShellMemoOptions,
+  shellHasAnyTag,
+  type ResolvedShellMemoOptions,
+} from "../shell-memo.js";
 import {
   KV_KEY_PRESERVED_PREFIX_BYTES,
   KV_MAX_KEY_BYTES,
@@ -70,7 +98,19 @@ import {
   TAG_MARKER_ABSENT,
   getTagMarkerMemo,
   getTagMarkerInflight,
+  getShellMarkerReads,
+  isRequestMasked,
+  maskRequestTags,
 } from "./cf-tag-marker-memo.js";
+import {
+  TagMarkerMemo,
+  TagNameHints,
+  hintedTags,
+  freshReadsRequired,
+  recordMarkerRow,
+  DEFAULT_CF_MARKER_FRESH_MS,
+  DEFAULT_CF_MARKER_MAX_STALE_MS,
+} from "../isolate-tag-memo.js";
 import { createCloudflareZonePurge } from "./cf-zone-purge.js";
 
 // ============================================================================
@@ -94,6 +134,7 @@ import {
   EDGE_LOOKUP_TIMEOUT_MS,
   EDGE_READ_TIMEOUT_MS,
   KV_READ_TIMEOUT_MS,
+  SHELL_SNAPSHOT_READ_MIN_TIMEOUT_MS,
 } from "./cf-cache-constants.js";
 
 // Re-export the public constants so consumers/tests importing them from
@@ -267,57 +308,110 @@ interface KVItemEnvelope {
 }
 
 /**
- * Coupled Cache API/KV envelope for PPR shell cache entries.
- * @internal
+ * 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.
  */
-interface CFShellEnvelope {
-  /**
-   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
-   * store no document half — ShellCacheEntry.prelude).
-   */
-  p?: string;
-  /** postponed state JSON, or null (DATA variant — no holes). Absent iff `no`. */
-  po?: string | null;
-  /** React.version captured at prerender time */
-  rv: string;
-  /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
-  bv?: string;
-  /** Capture-generation start time (ms epoch), used by tag marker checks. */
-  c: number;
-  /** When entry becomes stale (ms epoch) */
-  s: number;
-  /** When entry hard-expires (ms epoch) */
-  e: number;
-  /** Cache tags (for distributed tag invalidation) */
-  t?: string[];
-  /** Timestamp when tags were attached (ms epoch) */
-  ta?: number;
-  /** initialTheme the capture render was built with (resume theme fidelity) */
-  i?: string;
-  /** Capture data snapshot: recorded cache-store hits/writes for HIT parity */
-  sn?: import("../types.js").ShellSnapshotRecord[];
-  /**
-   * ShellCacheEntry.docKey. Must round-trip: navigation-replay eligibility
-   * requires the exact canonical doc segment record named here — dropping the
-   * field reads back as "no consumable record" and every partial navigation
-   * reports `no-segment-snapshot` after a KV round trip (the memory store
-   * passes the entry by reference, so only envelope stores can lose it).
-   */
-  dk?: string;
-  /**
-   * ShellCacheEntry.handlerLiveHoles. Must round-trip: the serve side arms the
-   * handler-free fast path on `!entry.handlerLiveHoles`, so dropping the flag
-   * here silently fast-pathed handler-live entries after a KV round trip —
-   * their holes only a handler re-run can fill.
-   */
-  lh?: boolean;
-  /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
-  tw?: true;
-  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
-  no?: true;
+const SHELL_KEY_PREFIX = "shell2:";
+
+/** A shell snapshot read's timeout, and its warning's consequence text. */
+interface SnapshotReadBudget {
+  ms: number;
+  consequence?: string;
+}
+
+/** A memoized fresh shell read (shell-memo.ts). */
+interface CFShellMemoValue {
+  head: ShellFrameHead;
+  prelude: Uint8Array;
+  snapshot: ShellSnapshotRecord[] | undefined;
+  /** L1 response headers: the KV-less purge-mode marker check reads them. */
+  headers?: Headers;
+}
+
+/** The per-isolate shell memo shared by every CFCacheStore in the isolate. */
+const cfShellMemo = new ShellMemo<CFShellMemoValue>();
+/** Per-isolate tag-marker values (isolate-tag-memo.ts), keyed per namespace. */
+const cfMarkerMemo = new TagMarkerMemo();
+/** Per-isolate shell-key -> tag-name hints for the marker prefetch. */
+const cfTagHints = new TagNameHints();
+
+/** Tags this isolate invalidated recently: they keep shells out of cfShellMemo. */
+const recentShellInvalidations = new RecentTagInvalidations();
+
+/**
+ * Whether cfShellMemo may keep or serve this shell: still fresh (a stale one
+ * stays with the store read, which schedules the recapture), and not tagged
+ * at or before an invalidation this isolate is running or just ran.
+ */
+function isMemoizableShell(head: ShellFrameHead): boolean {
+  return (
+    isShellFresh(head.s, head.e) &&
+    !recentShellInvalidations.covers(head.t, head.ta)
+  );
+}
+
+/** @internal Reset the per-isolate shell and marker memos (tests). */
+export function resetCFShellMemoForTests(): void {
+  cfShellMemo.clear();
+  recentShellInvalidations.clear();
+  cfMarkerMemo.clear();
+  cfTagHints.clear();
+}
+
+/** openShellFrame outcome: the head and prelude, or why the read failed. */
+type OpenedShellFrame =
+  | {
+      status: "ok";
+      head: ShellFrameHead;
+      prelude: Uint8Array;
+      reader: ShellFrameReader;
+    }
+  | { status: "corrupt"; error: Error; head?: undefined }
+  | { status: "expired"; head: ShellFrameHead }
+  | { status: "timeout"; head?: undefined }
+  | { status: "invalidated"; head?: undefined };
+
+/** The `[CFCacheStore][shell]` trace's timings, from a read's stats. */
+function debugTimings(
+  stats: ShellReadStats | undefined,
+): Pick<CFShellDebugDetails, "matchMs" | "readMs" | "bodyReadMs" | "markerMs"> {
+  if (!stats) return {};
+  if (stats.tier === "memo")
+    return { markerMs: Math.round(stats.markerMs ?? 0) };
+  const round = (ms: number | undefined) =>
+    ms === undefined ? undefined : Math.round(ms);
+  const bodyReadMs =
+    stats.headMs === undefined && stats.preludeMs === undefined
+      ? undefined
+      : (stats.headMs ?? 0) + (stats.preludeMs ?? 0);
+  return {
+    ...(stats.tier === "kv"
+      ? { readMs: round(stats.matchMs) }
+      : { matchMs: round(stats.matchMs) }),
+    bodyReadMs: round(bodyReadMs),
+    markerMs: round(stats.markerMs),
+  };
+}
+
+/** The public entry shape of a frame head (no prelude, no snapshot). */
+function shellHeadToEntry(head: ShellFrameHead): ShellCacheEntry {
+  return {
+    ...(head.po !== undefined ? { postponed: head.po } : {}),
+    reactVersion: head.rv,
+    buildVersion: head.bv,
+    initialTheme: head.i,
+    docKey: head.dk,
+    prunedRecords: head.pr,
+    navigationOnly: head.no,
+    createdAt: head.c,
+  };
 }
 
 type CFShellDebugOutcome =
+  | "memo-hit"
   | "l1-hit"
   | "l1-miss"
   | "kv-hit"
@@ -329,13 +423,12 @@ type CFShellDebugOutcome =
   | "write-invalidated";
 
 interface CFShellDebugDetails {
-  tier?: "l1" | "kv";
+  tier?: "memo" | "l1" | "kv";
   reason?:
     | "absent"
     | "timeout"
     | "error"
     | "non-200"
-    | "corrupt"
     | "malformed"
     | "expired"
     | "unavailable";
@@ -349,41 +442,6 @@ interface CFShellDebugDetails {
   remainingTtl?: number;
 }
 
-/** Validate the coupled PPR shell envelope before any field reaches resume. */
-function isShellEnvelope(value: unknown): value is CFShellEnvelope {
-  if (value == null || typeof value !== "object") return false;
-  const envelope = value as Partial<CFShellEnvelope>;
-  return (
-    // Document half: required unless the envelope is navigationOnly (`no`),
-    // which stores neither field. Tolerate a legacy navigationOnly envelope
-    // that still carries them.
-    (typeof envelope.p === "string" ||
-      (envelope.p === undefined && envelope.no === true)) &&
-    (envelope.po === null ||
-      typeof envelope.po === "string" ||
-      (envelope.po === undefined && envelope.no === true)) &&
-    typeof envelope.rv === "string" &&
-    (envelope.bv === undefined || typeof envelope.bv === "string") &&
-    typeof envelope.c === "number" &&
-    Number.isFinite(envelope.c) &&
-    typeof envelope.s === "number" &&
-    Number.isFinite(envelope.s) &&
-    typeof envelope.e === "number" &&
-    Number.isFinite(envelope.e) &&
-    (envelope.t === undefined ||
-      (Array.isArray(envelope.t) &&
-        envelope.t.every((tag) => typeof tag === "string"))) &&
-    (envelope.ta === undefined ||
-      (typeof envelope.ta === "number" && Number.isFinite(envelope.ta))) &&
-    (envelope.i === undefined || typeof envelope.i === "string") &&
-    (envelope.sn === undefined || Array.isArray(envelope.sn)) &&
-    (envelope.dk === undefined || typeof envelope.dk === "string") &&
-    (envelope.lh === undefined || typeof envelope.lh === "boolean") &&
-    (envelope.tw === undefined || envelope.tw === true) &&
-    (envelope.no === undefined || envelope.no === true)
-  );
-}
-
 /**
  * KV envelope for document cache entries.
  * @internal
@@ -426,6 +484,22 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly edgeLookupTimeoutMs: number;
   private readonly edgeReadTimeoutMs: number;
   private readonly kvReadTimeoutMs: number;
+  /**
+   * The shell snapshot read's budgets. `read` (getShell: partial replay, the
+   * testing helpers) has nothing committed, so a slow snapshot is a quick
+   * miss at kvReadTimeoutMs. `document` (readShellDocument, the serve path)
+   * has sent the prelude and cannot finish without the snapshot's doc
+   * record; a timeout there reloads the page, so it waits at least
+   * SHELL_SNAPSHOT_READ_MIN_TIMEOUT_MS. `kvReadTimeoutMs <= 0` keeps both
+   * unbounded.
+   */
+  private readonly snapshotBudgets: {
+    read: SnapshotReadBudget;
+    document: SnapshotReadBudget;
+  };
+  private readonly memo: ResolvedShellMemoOptions;
+  /** @internal SegmentCacheStore.freshReadsWindowMs */
+  readonly freshReadsWindowMs: number;
   private readonly debug?: (event: CFCacheReadDebugEvent) => void;
   private readonly kv?: KVNamespace;
   /** True when constructed without KV: no durable tag history (see ctor). */
@@ -476,6 +550,28 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       options.kvReadTimeoutMs,
       KV_READ_TIMEOUT_MS,
     );
+    this.snapshotBudgets = {
+      read: { ms: this.kvReadTimeoutMs },
+      document:
+        this.kvReadTimeoutMs > 0
+          ? {
+              ms: Math.max(
+                this.kvReadTimeoutMs,
+                SHELL_SNAPSHOT_READ_MIN_TIMEOUT_MS,
+              ),
+              consequence: "the HIT reloads the page into a cache-miss render",
+            }
+          : { ms: this.kvReadTimeoutMs },
+    };
+    this.memo = resolveShellMemoOptions(options.memo, {
+      markerFreshMs: DEFAULT_CF_MARKER_FRESH_MS,
+      markerMaxStaleMs: DEFAULT_CF_MARKER_MAX_STALE_MS,
+    });
+    // Without KV there are no markers, so no marker memo to outwait.
+    this.freshReadsWindowMs = freshReadsWindowMs(
+      this.memo,
+      Boolean(options.kv),
+    );
     this.debug =
       options.debug === true
         ? (event) =>
@@ -602,11 +698,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
-  /** Build-time-gated shell tier trace for deployed cross-colo diagnostics. */
+  /**
+   * Build-time-gated shell tier trace for deployed cross-colo diagnostics.
+   * A read's `stats` print as its timings, after the other details and before
+   * `expiresAt`.
+   */
   private debugShell(
     key: string,
     outcome: CFShellDebugOutcome,
-    details: CFShellDebugDetails = {},
+    details: CFShellDebugDetails & { stats?: ShellReadStats } = {},
   ): void {
     if (!INTERNAL_RANGO_DEBUG) return;
     const request = _getRequestContext()?.request as
@@ -620,6 +720,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         : ray?.includes("-")
           ? ray.slice(ray.lastIndexOf("-") + 1)
           : undefined;
+    const { stats, expiresAt, ...rest } = details;
     console.log(
       `[CFCacheStore][shell] ${JSON.stringify({
         key,
@@ -627,7 +728,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         at: Date.now(),
         ray,
         colo,
-        ...details,
+        ...rest,
+        ...debugTimings(stats),
+        expiresAt,
       })}`,
     );
   }
@@ -723,6 +826,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     read: () => Promise<T>,
     budgetMs: number,
     label: string,
+    consequence = "treating as miss",
   ): Promise<{ value: T | undefined; timedOut: boolean }> {
     if (budgetMs <= 0) return { value: await read(), timedOut: false };
 
@@ -741,7 +845,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       ]);
       if (result.timedOut) {
         console.warn(
-          `[CFCacheStore] ${label} exceeded ${budgetMs}ms; treating as miss`,
+          `[CFCacheStore] ${label} exceeded ${budgetMs}ms; ${consequence}`,
         );
         return { value: undefined, timedOut: true };
       }
@@ -1246,7 +1350,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
   /**
    * Store entry data with TTL and optional SWR window.
-   * Uses waitUntil for non-blocking write when available.
+   * Resolves once the L1 write lands, per the SegmentCacheStore.set contract
+   * (also held by waitUntil when available); the KV write stays in the
+   * background.
    * When KV is configured, also persists to L2.
    */
   async set(
@@ -1297,20 +1403,21 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       const putPromise = cache.put(request, response);
 
+      let l1Write: Promise<void> | undefined;
       if (this.waitUntil) {
-        // Non-blocking write. These store-level background tasks intentionally
-        // omit the reportingAsync ctx argument: the store is a request-agnostic
+        // These store-level background tasks intentionally omit the
+        // reportingAsync ctx argument: the store is a request-agnostic
         // singleton and this.waitUntil is the execution context's, not a single
         // request's, so a failure is reported console-loud only (it cannot be
         // attributed to one request's onError). The request-scoped tag verbs
         // (revalidateTag / stale-revalidation) DO thread their captured ctx.
-        this.waitUntil(() =>
-          reportingAsync(
-            () => putPromise,
-            "cache-write",
-            "[CFCacheStore] L1 write",
-          ),
+        const put = reportingAsync(
+          () => putPromise,
+          "cache-write",
+          "[CFCacheStore] L1 write",
         );
+        this.waitUntil(() => put);
+        l1Write = put;
       } else {
         // Blocking fallback
         await putPromise;
@@ -1318,6 +1425,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: persist to KV (reuses `body` as envelope.d)
       this.kvSetSegment(key, body, staleAt, totalTtl, swrWindow);
+
+      // The set() contract (SegmentCacheStore.set, #957): resolve once L1 is
+      // readable.
+      await l1Write;
     } catch (error) {
       reportCacheError(error, "cache-write", "[CFCacheStore] set");
     }
@@ -1952,27 +2063,96 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * Get a cached PPR shell entry from Cache API, falling through to KV and
-   * promoting a valid KV hit. Both tiers store one envelope so the prelude,
-   * postponed state, snapshot, versions, and generation metadata cannot mix.
-   * SWR remains a plain staleness flag; the capture scheduler's module-level
-   * in-flight set is the recapture stampede guard.
+   * Get a cached PPR shell entry: the public custom-store contract, built on
+   * readShellDocument. It waits for the snapshot and re-encodes the prelude to
+   * the base64 `ShellCacheEntry.prelude` the contract carries (native
+   * `toBase64` in workerd). Partial replay and the testing helpers read
+   * through here; the document serve path reads readShellDocument directly.
+   * A snapshot that failed to read is a miss here: with no committed response
+   * to protect, an entry without its pins is worse than none.
    */
   async getShell(
     key: string,
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    const read = await this.readShellDocumentWithin(
+      key,
+      undefined,
+      this.snapshotBudgets.read,
+    );
+    if (!read) return null;
+    const snapshot = await read.snapshot;
+    if (await read.snapshotFailure) return null;
+    const entry: ShellCacheEntry = { ...read.entry };
+    if (!entry.navigationOnly) entry.prelude = bytesToBase64(read.prelude);
+    if (snapshot) entry.snapshot = snapshot;
+    return { entry, shouldRevalidate: read.shouldRevalidate };
+  }
+
+  /**
+   * @internal Prelude-first read of a shell (SegmentCacheStore
+   * .readShellDocument). Cache API first, then KV; both tiers hold one
+   * cf-shell-frame body, so the prelude, postponed state, snapshot, versions,
+   * and generation metadata cannot mix. Before it resolves it reads only the
+   * head and the prelude's bytes, and the tag-marker read runs alongside the
+   * prelude read (it starts as soon as the head is parsed, and is awaited
+   * before this resolves, so an invalidated shell is never returned). The
+   * snapshot is the rest of the same body, read on its own promise, bounded
+   * by the document read's budget (`snapshotBudgets.document`; getShell uses
+   * `snapshotBudgets.read`). SWR is a plain staleness flag; the capture
+   * scheduler's in-flight set is the recapture stampede guard.
+   */
+  async readShellDocument(
+    key: string,
+    options?: ShellDocumentReadOptions,
+  ): Promise<ShellDocumentRead | null> {
+    return this.readShellDocumentWithin(
+      key,
+      options,
+      this.snapshotBudgets.document,
+    );
+  }
+
+  private async readShellDocumentWithin(
+    key: string,
+    options: ShellDocumentReadOptions | undefined,
+    snapshotBudget: SnapshotReadBudget,
+  ): Promise<ShellDocumentRead | null> {
+    const memoKey = this.shellMemoKey(key);
+    const ctx = _getRequestContext();
+    // A request after the same user's updateTag() reads past the isolate
+    // memos (isolate-tag-memo.ts freshReadsRequired).
+    const freshReads = freshReadsRequired(ctx);
+    const memoized = freshReads
+      ? undefined
+      : cfShellMemo.get(memoKey, this.memo.shellMs);
+    if (memoized) {
+      return this.readMemoizedShell(
+        key,
+        memoKey,
+        memoized,
+        options,
+        snapshotBudget,
+      );
+    }
+    const stats = this.shellReadStats("l1");
+    const l1StartedAt = stats ? performance.now() : 0;
+    const kvFallback = (reason: string): Promise<ShellDocumentRead | null> =>
+      this.kvReadShellDocument(key, snapshotBudget, stats, l1StartedAt, reason);
+    if (stats && freshReads) stats.freshReads = true;
+    this.prefetchShellMarkers(memoKey, options?.tagHints, stats);
+    if (stats && this.memo.shellMs > 0) {
+      stats.memo = { hit: false, bytes: cfShellMemo.size };
+    }
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`shell:${key}`);
-      const matchStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const request = this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`);
+      const matchStartedAt = stats ? performance.now() : 0;
       const {
         response,
         timedOut,
         error: matchError,
       } = await this.matchWithTimeout(cache, request);
-      const matchMs = INTERNAL_RANGO_DEBUG
-        ? Date.now() - matchStartedAt
-        : undefined;
+      if (stats) stats.matchMs = performance.now() - matchStartedAt;
 
       if (!response) {
         if (matchError) {
@@ -1982,116 +2162,434 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             "[CFCacheStore] getShell L1 match",
           );
         }
-        this.debugShell(key, "l1-miss", {
-          reason: matchError ? "error" : timedOut ? "timeout" : "absent",
-          matchMs,
-        });
-        return this.kvGetShell(key);
+        const reason = matchError ? "error" : timedOut ? "timeout" : "absent";
+        this.debugShell(key, "l1-miss", { reason, stats });
+        return kvFallback(reason);
       }
-      if (response.status !== 200) {
+      if (response.status !== 200 || !response.body) {
         this.debugShell(key, "l1-miss", {
           reason: "non-200",
           status: response.status,
-          matchMs,
+          stats,
         });
-        return this.kvGetShell(key);
+        return kvFallback("non-200");
       }
 
-      const bodyStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const { value, errored, error } =
-        await this.readJsonWithTimeout<unknown>(response);
-      const bodyReadMs = INTERNAL_RANGO_DEBUG
-        ? Date.now() - bodyStartedAt
-        : undefined;
-      if (value === undefined) {
-        this.debugShell(key, "l1-miss", {
-          reason: errored ? "corrupt" : "timeout",
-          matchMs,
-          bodyReadMs,
-        });
-        if (errored) {
-          return this.healCorruptL1(cache, request, error, "getShell", () =>
-            this.kvGetShell(key),
-          );
-        }
-        return this.kvGetShell(key);
-      }
-      if (!isShellEnvelope(value)) {
+      // Unlike other L1 families, shells with KV always check the durable
+      // generation marker — see the capture-start/purge race documented
+      // above. Without KV there are no markers: L1-only shells adopt the
+      // data families' purge-mode read semantics (a hit that survived the
+      // purge is trusted; the per-request memo masks this request's own
+      // updateTag() writes; entries a purge cannot reach fall back to the
+      // marker check, which fails open KV-less).
+      const opened = await this.openShellFrame(
+        response.body,
+        this.edgeReadTimeoutMs,
+        "edge cache body read",
+        (head) =>
+          this.kv
+            ? this.isGloballyInvalidated(head.t, head.ta, true)
+            : this.isL1Invalidated(head.t, head.ta, response.headers),
+        stats,
+      );
+      if (opened.status === "corrupt") {
         this.debugShell(key, "l1-miss", {
           reason: "malformed",
-          matchMs,
-          bodyReadMs,
+          stats,
         });
         return this.healCorruptL1(
           cache,
           request,
-          new Error("malformed/partial L1 shell envelope"),
+          opened.error,
           "getShell",
-          () => this.kvGetShell(key),
+          () => kvFallback("malformed"),
         );
       }
-
-      const now = Date.now();
-      if (now > value.e) {
+      if (opened.status === "timeout" || opened.status === "expired") {
         this.debugShell(key, "l1-miss", {
-          reason: "expired",
-          matchMs,
-          bodyReadMs,
-          expiresAt: value.e,
+          reason: opened.status,
+          stats,
+          expiresAt: opened.head?.e,
         });
-        return this.kvGetShell(key);
+        return kvFallback(opened.status);
       }
-
-      // Unlike other L1 families, shells with KV always check the durable
-      // generation marker — see the capture-start/purge race documented
-      // above. Without KV there are no markers: L1-only shells adopt the
-      // data families' purge-mode read semantics (a hit that survived the
-      // purge is trusted; the per-request memo masks this request's own
-      // updateTag() writes; entries a purge cannot reach fall back to the
-      // marker check, which fails open KV-less).
-      const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const invalidated = this.kv
-        ? await this.isGloballyInvalidated(value.t, value.ta)
-        : await this.isL1Invalidated(value.t, value.ta, response.headers);
-      const markerMs = INTERNAL_RANGO_DEBUG
-        ? Date.now() - markerStartedAt
-        : undefined;
-      if (invalidated) {
+      if (opened.status === "invalidated") {
         this.debugShell(key, "marker-invalidated", {
           tier: "l1",
-          matchMs,
-          bodyReadMs,
-          markerMs,
+          stats,
         });
         return null;
       }
-
-      const shouldRevalidate = value.s > 0 && now > value.s;
-      this.debugShell(key, "l1-hit", {
-        freshness: shouldRevalidate ? "stale" : "fresh",
-        matchMs,
-        bodyReadMs,
-        markerMs,
-        expiresAt: value.e,
-      });
-      return {
-        entry: this.shellEnvelopeToEntry(value),
-        shouldRevalidate,
-      };
+      const read = this.shellDocumentRead(
+        key,
+        opened,
+        snapshotBudget,
+        stats,
+        response.headers,
+      );
+      if (INTERNAL_RANGO_DEBUG) {
+        this.debugShell(key, "l1-hit", {
+          freshness: read.shouldRevalidate ? "stale" : "fresh",
+          stats,
+          expiresAt: opened.head.e,
+        });
+      }
+      return read;
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] getShell");
       this.debugShell(key, "l1-miss", { reason: "error" });
-      return this.kvGetShell(key);
+      return kvFallback("error");
+    }
+  }
+
+  /** @internal SegmentCacheStore.dropShellMemo */
+  dropShellMemo(key: string): void {
+    cfShellMemo.delete(this.shellMemoKey(key));
+  }
+
+  /**
+   * Start the marker reads of the tags this shell key carried last time (and
+   * the route's static tags) alongside the entry read (readShellTagMarker),
+   * so the marker check after the head reuses them. With KV only: without it
+   * there are no markers to read. A wrong hint costs a wasted read; the check
+   * itself uses the head's tags.
+   */
+  private prefetchShellMarkers(
+    memoKey: string,
+    routeTags: readonly string[] | undefined,
+    stats: ShellReadStats | undefined,
+  ): void {
+    if (!this.kv) return;
+    const tags = hintedTags(cfTagHints.get(memoKey), routeTags);
+    if (tags.length === 0) return;
+    if (stats) {
+      stats.markerHinted = tags;
+      stats.markerHintStartedAt = performance.now();
+    }
+    for (const tag of tags) this.readShellTagMarker(tag).catch(() => {});
+  }
+
+  /**
+   * A HIT: remember the entry's tags for the next read's hints, and fill the
+   * marker row. The shell-read marker values stay in their own record: the
+   * request's data reads (the tail's, or a partial navigation's matchPartial
+   * on the same context) read their markers as before.
+   */
+  private recordShellHit(
+    key: string,
+    tags: string[] | undefined,
+    stats: ShellReadStats | undefined,
+  ): void {
+    cfTagHints.remember(this.shellMemoKey(key), tags);
+    if (!stats) return;
+    const ctx = _getRequestContext();
+    if (ctx) {
+      recordMarkerRow(stats, tags, getShellMarkerReads(ctx, this).outcomes);
+    }
+  }
+
+  /** The isolate marker memo's key for a tag: markers are per namespace and version. */
+  private markerMemoKey(tag: string): string {
+    return `${this.namespace ?? ""}\u0000${this.version ?? ""}\u0000${tag}`;
+  }
+
+  /** The memo key: one per namespace, build version, base URL, and shell key. */
+  private shellMemoKey(key: string): string {
+    return `${this.namespace ?? ""}\u0000${this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`).url}`;
+  }
+
+  /**
+   * Serve a memoized shell (shell-memo.ts). The tag-marker check is the only
+   * store I/O left, so it is started first and awaited before anything is
+   * returned: nothing of an invalidated shell reaches the response. A shell
+   * that went stale since it was memoized, or that predates a tag this
+   * isolate is invalidating or just invalidated (RecentTagInvalidations), is
+   * dropped and read from the store (SWR recapture scheduling and each mode's
+   * invalidation semantics stay with the store read). That read keeps the
+   * caller's `tagHints`: cfTagHints may have evicted the key while the memo
+   * still holds it.
+   */
+  private async readMemoizedShell(
+    key: string,
+    memoKey: string,
+    memoized: CFShellMemoValue,
+    options: ShellDocumentReadOptions | undefined,
+    snapshotBudget: SnapshotReadBudget,
+  ): Promise<ShellDocumentRead | null> {
+    const { head } = memoized;
+    if (!isMemoizableShell(head)) {
+      cfShellMemo.delete(memoKey);
+      return this.readShellDocumentWithin(key, options, snapshotBudget);
+    }
+    const stats = this.shellReadStats("memo");
+    const markerStartedAt = stats ? performance.now() : 0;
+    const invalidated = await (this.kv
+      ? this.isGloballyInvalidated(head.t, head.ta, true)
+      : this.isL1Invalidated(
+          head.t,
+          head.ta,
+          memoized.headers ?? new Headers(),
+        ));
+    if (stats) {
+      // Nothing else to wait for: the marker IS the memo hit's critical path.
+      stats.markerMs = stats.markerWaitMs = performance.now() - markerStartedAt;
+      stats.tags = head.t?.length ?? 0;
+      stats.preludeBytes = memoized.prelude.length;
+    }
+    if (invalidated) {
+      cfShellMemo.delete(memoKey);
+      this.debugShell(key, "marker-invalidated", {
+        tier: "memo",
+        stats,
+      });
+      return null;
+    }
+    if (stats) stats.memo = { hit: true, bytes: cfShellMemo.size };
+    this.recordShellHit(key, head.t, stats);
+    this.debugShell(key, "memo-hit", {
+      freshness: "fresh",
+      stats,
+      expiresAt: head.e,
+    });
+    return {
+      entry: shellHeadToEntry(head),
+      prelude: memoized.prelude,
+      shouldRevalidate: false,
+      snapshot: Promise.resolve(memoized.snapshot),
+      ...(stats ? { stats } : {}),
+    };
+  }
+
+  /**
+   * Stats for one shell read, allocated only when the request collects
+   * `debugPerformance` metrics or the build has the internal shell trace on,
+   * so a normal HIT takes no timestamps for them.
+   */
+  private shellReadStats(
+    tier: ShellReadStats["tier"],
+  ): ShellReadStats | undefined {
+    return INTERNAL_RANGO_DEBUG || _getRequestContext()?._metricsStore
+      ? { tier }
+      : undefined;
+  }
+
+  /**
+   * Read a frame's head and prelude under one budget, starting the
+   * tag-marker read (`isInvalidated`) the moment the head is parsed so it
+   * overlaps the prelude read, then await it. Expired heads are rejected
+   * before the marker read starts.
+   */
+  private async openShellFrame(
+    body: ReadableStream<Uint8Array>,
+    budgetMs: number,
+    label: string,
+    isInvalidated: (head: ShellFrameHead) => Promise<boolean>,
+    stats: ShellReadStats | undefined,
+  ): Promise<OpenedShellFrame> {
+    const reader = new ShellFrameReader(body);
+    let marker: Promise<boolean> | undefined;
+    let markerSettledAt = 0;
+    const headStartedAt = stats ? performance.now() : 0;
+    const { value, timedOut } = await this.readWithTimeout(
+      async (): Promise<OpenedShellFrame> => {
+        const head = await reader.readHead();
+        if (!head) {
+          return {
+            status: "corrupt",
+            error: new Error("malformed/partial shell frame head"),
+          };
+        }
+        const markerStartedAt = stats ? performance.now() : 0;
+        if (stats) {
+          stats.headMs = markerStartedAt - headStartedAt;
+          stats.headBytes = reader.headBytes;
+          stats.tags = head.t?.length ?? 0;
+          if (stats.markerHintStartedAt !== undefined) {
+            stats.markerLeadMs = markerStartedAt - stats.markerHintStartedAt;
+          }
+        }
+        if (Date.now() > head.e) return { status: "expired", head };
+        marker = isInvalidated(head).then((invalidated) => {
+          if (stats) {
+            markerSettledAt = performance.now();
+            stats.markerMs = markerSettledAt - markerStartedAt;
+          }
+          return invalidated;
+        });
+        marker.catch(() => {});
+        const prelude = await reader.take(head.pl);
+        if (!prelude) {
+          return {
+            status: "corrupt",
+            error: new Error("shell frame ends inside the prelude"),
+          };
+        }
+        if (stats) {
+          stats.preludeMs = performance.now() - markerStartedAt;
+          stats.preludeBytes = prelude.length;
+        }
+        return { status: "ok", head, prelude, reader };
+      },
+      budgetMs,
+      label,
+    );
+    if (timedOut || !value) {
+      reader.cancel();
+      if (stats) {
+        // The budget ran out: the whole elapsed read, split at the head.
+        const elapsed = performance.now() - headStartedAt;
+        if (stats.headMs === undefined) stats.headMs = elapsed;
+        else stats.preludeMs = elapsed - stats.headMs;
+      }
+      return { status: "timeout" };
     }
+    if (value.status !== "ok") {
+      reader.cancel();
+      return value;
+    }
+    const preludeReadAt = stats ? performance.now() : 0;
+    const invalidated = await marker!;
+    if (stats) {
+      stats.markerWaitMs = Math.max(0, markerSettledAt - preludeReadAt);
+    }
+    if (invalidated) {
+      reader.cancel();
+      return { status: "invalidated" };
+    }
+    return value;
   }
 
   /**
-   * Store a PPR shell envelope in Cache API and, when KV is configured and
-   * the retention meets its 60-second floor, KV. The shared write is
-   * registered with waitUntil and awaited so invalidation rejection can be
-   * acknowledged to the capture scheduler. Short-lived shells remain useful
-   * in L1 even though KV rejects them; a KV-less store is L1-only by design
-   * (edge-only ppr — see the section comment).
+   * The ShellDocumentRead for an opened frame. Its snapshot promise starts
+   * reading the rest of the body now (off the commit path, not after it),
+   * bounded by `budget` ({@link snapshotReadBudget}), and is registered with
+   * waitUntil so the KV tier's L1 promotion and a corrupt entry's eviction
+   * still run when nothing awaits it (a read that is not served). A snapshot
+   * whose length differs from the head's `sl`, or that fails to parse, evicts
+   * the entry from both tiers and reports cache-corrupt. Every failure
+   * resolves undefined and names itself on `snapshotFailure` (`unavailable`
+   * for a timeout or read error, `corrupt` otherwise): a document HIT then
+   * degrades (rsc-rendering.ts serveShellHit), and getShell misses. Only
+   * a read whose snapshot parsed goes into the per-isolate memo (when still
+   * fresh), and `promote` receives its snapshot bytes (the KV tier's L1
+   * promotion). `headers` are the L1 response's, kept for the KV-less
+   * memo-hit marker check.
+   */
+  private shellDocumentRead(
+    key: string,
+    opened: Extract<OpenedShellFrame, { status: "ok" }>,
+    budget: SnapshotReadBudget,
+    stats: ShellReadStats | undefined,
+    headers?: Headers,
+    promote?: (snapshotBytes: Uint8Array) => void,
+  ): ShellDocumentRead {
+    const { head, prelude, reader } = opened;
+    this.recordShellHit(key, head.t, stats);
+    type SnapshotOutcome = {
+      records?: ShellSnapshotRecord[];
+      failure?: ShellSnapshotFailure;
+    };
+    const outcome = (async (): Promise<SnapshotOutcome> => {
+      const readStartedAt = stats ? performance.now() : 0;
+      const { value: rest, timedOut } = await this.readWithTimeout(
+        () => reader.readRest(),
+        budget.ms,
+        "shell snapshot read",
+        budget.consequence,
+      );
+      if (timedOut || !rest) {
+        reader.cancel();
+        return { failure: "unavailable" };
+      }
+      const parseStartedAt = stats ? performance.now() : 0;
+      let records: ShellSnapshotRecord[] | undefined;
+      try {
+        if (rest.length !== head.sl) {
+          throw new Error(
+            `shell snapshot is ${rest.length} bytes, the head says ${head.sl}`,
+          );
+        }
+        records = parseShellSnapshot(rest);
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          "[CFCacheStore] getShell: corrupt shell snapshot, evicting",
+        );
+        this.evictShell(key);
+        return { failure: "corrupt" };
+      }
+      if (stats) {
+        stats.snapshot = {
+          readMs: parseStartedAt - readStartedAt,
+          parseMs: performance.now() - parseStartedAt,
+          bytes: rest.length,
+        };
+      }
+      if (isMemoizableShell(head)) {
+        // A view into a larger body chunk would pin that chunk in the memo.
+        const ownPrelude =
+          prelude.byteLength === prelude.buffer.byteLength
+            ? prelude
+            : prelude.slice();
+        cfShellMemo.set(
+          this.shellMemoKey(key),
+          { head, prelude: ownPrelude, snapshot: records, headers },
+          ownPrelude.length + rest.length,
+          this.memo.shellMs,
+          this.memo.shellMaxBytes,
+        );
+      }
+      promote?.(rest);
+      return { records };
+    })().catch((error: unknown): SnapshotOutcome => {
+      reportCacheError(error, "cache-read", "[CFCacheStore] getShell snapshot");
+      return { failure: "unavailable" };
+    });
+    if (this.waitUntil) this.waitUntil(() => outcome.then(() => {}));
+    return {
+      entry: shellHeadToEntry(head),
+      prelude,
+      shouldRevalidate: head.s > 0 && Date.now() > head.s,
+      snapshot: outcome.then(({ records }) => records),
+      snapshotFailure: outcome.then(({ failure }) => failure),
+      ...(stats && { stats }),
+    };
+  }
+
+  /** Delete a shell from both tiers (non-blocking). */
+  private evictShell(key: string): void {
+    const evict = async (): Promise<void> => {
+      const cache = await this.getCache();
+      await reportingAsync(
+        () => cache.delete(this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`)),
+        "cache-delete",
+        "[CFCacheStore] getShell: evict corrupt L1",
+      );
+      if (this.kv) {
+        await this.evictKvKey(
+          await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`),
+          "getShell",
+        );
+      }
+    };
+    if (this.waitUntil) this.waitUntil(evict);
+    else void evict();
+  }
+
+  /**
+   * Store a PPR shell in Cache API and, when KV is configured, KV — the same
+   * cf-shell-frame bytes in both. The shared write is registered with
+   * waitUntil and awaited so invalidation rejection can be acknowledged to
+   * the capture scheduler. A KV-less store is L1-only by design (edge-only
+   * ppr — see the section comment).
+   *
+   * KV rejects an expirationTtl below KV_MIN_EXPIRATION_TTL, so a shorter
+   * retention (a `ppr` ttl + swr under 60, or a shell capped to a short or
+   * aging route cache() entry) is written with that floor: the frame head's deadlines (`s`, `e`) are the
+   * entry's, and every read checks `e` (openShellFrame), so the extra KV
+   * lifetime is never served, and the shell is readable from every colo, not
+   * only from the capturing colo's L1.
    */
   async putShell(
     key: string,
@@ -2111,6 +2609,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv && !this.tagPurge && Array.isArray(tags) && tags.length > 0) {
       this.warnShellTagsNoEvictionOnce();
     }
+    // This isolate serves its own new capture from the next read on.
+    cfShellMemo.delete(this.shellMemoKey(key));
+    cfTagHints.remember(this.shellMemoKey(key), tags);
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
@@ -2130,8 +2631,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const taggedAt =
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
-      const writeKv = !!this.kv && retentionTtl >= KV_MIN_EXPIRATION_TTL;
-      const kvKey = writeKv ? await this.toKVKey(`shell:${key}`) : null;
+      const writeKv = !!this.kv && retentionTtl > 0;
+      const kvKey = writeKv
+        ? await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`)
+        : null;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
@@ -2143,12 +2646,14 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           return "invalidated";
         }
 
-        const envelope: CFShellEnvelope = {
-          // Presence-keyed: a navigationOnly entry has no document half, and an
-          // omitted key (vs an explicit undefined) also keeps it out of the
-          // serialized JSON.
-          ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
-          ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
+        // A navigationOnly entry stores no document half: no prelude bytes
+        // and no postponed field (an omitted key, not an explicit undefined).
+        const prelude =
+          entry.prelude !== undefined
+            ? base64ToBytes(entry.prelude)
+            : new Uint8Array(0);
+        const snapshotBytes = encodeShellSnapshot(entry.snapshot);
+        const head: ShellFrameHead = {
           rv: entry.reactVersion,
           bv: entry.buildVersion,
           c: entry.createdAt,
@@ -2157,24 +2662,23 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           t: tags,
           ta: taggedAt,
           i: entry.initialTheme,
-          sn: entry.snapshot,
           dk: entry.docKey,
-          lh: entry.handlerLiveHoles,
-          tw: entry.transitionWhen,
+          pr: entry.prunedRecords,
           no: entry.navigationOnly,
+          ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
+          pl: prelude.length,
+          sl: snapshotBytes?.length ?? 0,
         };
-        const body = JSON.stringify(envelope);
+        const frame = encodeShellFrame(head, prelude, snapshotBytes);
         const writes: Promise<boolean>[] = [
           (async () => {
             try {
               const cache = await this.getCache();
               await cache.put(
-                this.keyToRequest(`shell:${key}`),
-                this.shellEnvelopeResponse(body, envelope),
+                this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`),
+                this.shellFrameResponse(frame, head),
               );
-              this.debugShell(key, "l1-stored", {
-                expiresAt: envelope.e,
-              });
+              this.debugShell(key, "l1-stored", { expiresAt: head.e });
               return true;
             } catch (error) {
               reportCacheError(
@@ -2190,12 +2694,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           writes.push(
             (async () => {
               try {
-                await this.kv!.put(kvKey, body, {
-                  expirationTtl: retentionTtl,
-                });
-                this.debugShell(key, "kv-stored", {
-                  expiresAt: envelope.e,
+                await this.kv!.put(kvKey, shellFrameToText(frame), {
+                  // Whole seconds, at least KV's floor: the frame head keeps
+                  // the exact deadlines the reads check.
+                  expirationTtl: Math.max(
+                    KV_MIN_EXPIRATION_TTL,
+                    Math.ceil(retentionTtl),
+                  ),
                 });
+                this.debugShell(key, "kv-stored", { expiresAt: head.e });
                 return true;
               } catch (error) {
                 reportCacheError(
@@ -2219,107 +2726,134 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
-  /** Rebuild the public shell entry from its validated storage envelope. */
-  private shellEnvelopeToEntry(envelope: CFShellEnvelope): ShellCacheEntry {
-    return {
-      prelude: envelope.p,
-      postponed: envelope.po,
-      reactVersion: envelope.rv,
-      buildVersion: envelope.bv,
-      initialTheme: envelope.i,
-      snapshot: envelope.sn,
-      docKey: envelope.dk,
-      handlerLiveHoles: envelope.lh,
-      transitionWhen: envelope.tw,
-      navigationOnly: envelope.no,
-      createdAt: envelope.c,
-    };
-  }
-
-  /** Build the Cache API representation of the coupled shell envelope. */
-  private shellEnvelopeResponse(
-    body: string,
-    envelope: CFShellEnvelope,
+  /** The Cache API representation of a shell frame. */
+  private shellFrameResponse(
+    frame: Uint8Array<ArrayBuffer>,
+    head: ShellFrameHead,
   ): Response {
-    const remainingTtl = Math.max(
-      1,
-      Math.floor((envelope.e - Date.now()) / 1000),
-    );
-    return new Response(body, {
+    const remainingTtl = Math.max(1, Math.floor((head.e - Date.now()) / 1000));
+    return new Response(frame, {
       headers: {
-        "Content-Type": "application/json",
+        "Content-Type": "application/octet-stream",
         "Cache-Control": `public, max-age=${remainingTtl}`,
-        [CACHE_STALE_AT_HEADER]: String(envelope.s),
-        [CACHE_EXPIRES_AT_HEADER]: String(envelope.e),
+        [CACHE_STALE_AT_HEADER]: String(head.s),
+        [CACHE_EXPIRES_AT_HEADER]: String(head.e),
         [CACHE_STATUS_HEADER]: "HIT",
-        ...this.tagHeaderEntries(envelope.t, envelope.ta),
+        ...this.tagHeaderEntries(head.t, head.ta),
       },
     });
   }
 
-  /** KV shell fallback with corruption checks and background L1 promotion. */
-  private async kvGetShell(
+  /**
+   * KV shell fallback: the same prelude-first read, then L1 promotion. After
+   * an L1 attempt, `stats` is that read's and gains the L1 attempt's time
+   * (`l1MissMs`) before its per-tier fields restart for KV.
+   */
+  private async kvReadShellDocument(
     key: string,
-  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    snapshotBudget: SnapshotReadBudget,
+    stats?: ShellReadStats,
+    l1StartedAt = 0,
+    l1MissReason?: string,
+  ): Promise<ShellDocumentRead | null> {
     if (!this.kv) return null;
+    if (stats) {
+      stats.l1MissMs = performance.now() - l1StartedAt;
+      stats.l1MissReason = l1MissReason;
+      stats.tier = "kv";
+      stats.matchMs = stats.headMs = stats.preludeMs = undefined;
+      stats.markerMs = stats.markerWaitMs = undefined;
+      stats.headBytes = stats.preludeBytes = stats.tags = undefined;
+    } else {
+      stats = this.shellReadStats("kv");
+    }
     try {
-      const readStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const kvKey = await this.toKVKey(`shell:${key}`);
-      const { value: envelope, timedOut } =
-        await this.kvGetOrEvict<CFShellEnvelope>(
-          kvKey,
-          isShellEnvelope,
-          "getShell",
-        );
-      const readMs = INTERNAL_RANGO_DEBUG
-        ? Date.now() - readStartedAt
-        : undefined;
-      if (timedOut || !envelope) {
+      const readStartedAt = stats ? performance.now() : 0;
+      // 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}`);
+      // 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.
+      const { value: raw, timedOut } = await this.readWithTimeout<unknown>(
+        () => this.kv!.get(kvKey, { type: "stream" }),
+        this.kvReadTimeoutMs,
+        "KV read",
+      );
+      if (stats) stats.matchMs = performance.now() - readStartedAt;
+      if (timedOut || raw == null) {
         this.debugShell(key, "kv-miss", {
           reason: timedOut ? "timeout" : "unavailable",
-          readMs,
+          stats,
         });
         return null;
       }
-
-      const now = Date.now();
-      if (now > envelope.e) {
+      // A binding that ignores `type` (a test shim) hands back the stored
+      // string itself.
+      const body =
+        raw instanceof ReadableStream
+          ? (raw as ReadableStream<Uint8Array>)
+          : new Response(raw as BodyInit).body!;
+      const opened = await this.openShellFrame(
+        body,
+        // readWithTimeout treats <= 0 as "no budget": keep a spent budget
+        // spent (1 ms) rather than unbounded.
+        this.kvReadTimeoutMs > 0 ? Math.max(1, deadline - Date.now()) : 0,
+        "KV read",
+        (head) => this.isGloballyInvalidated(head.t, head.ta, true),
+        stats,
+      );
+      if (opened.status === "corrupt") {
+        reportCacheError(
+          opened.error,
+          "cache-corrupt",
+          "[CFCacheStore] getShell: malformed shell frame in KV, evicting",
+        );
+        this.scheduleKvEvict(kvKey, "getShell");
         this.debugShell(key, "kv-miss", {
-          reason: "expired",
-          readMs,
-          expiresAt: envelope.e,
+          reason: "malformed",
+          stats,
         });
         return null;
       }
-      const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const invalidated = await this.isGloballyInvalidated(
-        envelope.t,
-        envelope.ta,
-      );
-      const markerMs = INTERNAL_RANGO_DEBUG
-        ? Date.now() - markerStartedAt
-        : undefined;
-      if (invalidated) {
+      if (opened.status === "timeout" || opened.status === "expired") {
+        this.debugShell(key, "kv-miss", {
+          reason: opened.status,
+          stats,
+          expiresAt: opened.head?.e,
+        });
+        return null;
+      }
+      if (opened.status === "invalidated") {
         this.debugShell(key, "marker-invalidated", {
           tier: "kv",
-          readMs,
-          markerMs,
+          stats,
         });
         return null;
       }
-
-      const shouldRevalidate = envelope.s > 0 && now > envelope.s;
-      this.debugShell(key, "kv-hit", {
-        freshness: shouldRevalidate ? "stale" : "fresh",
-        readMs,
-        markerMs,
-        expiresAt: envelope.e,
-      });
-      this.promoteShellToL1(key, envelope);
-      return {
-        entry: this.shellEnvelopeToEntry(envelope),
-        shouldRevalidate,
-      };
+      const read = this.shellDocumentRead(
+        key,
+        opened,
+        snapshotBudget,
+        stats,
+        undefined,
+        (snapshotBytes) =>
+          this.promoteShellToL1(
+            key,
+            opened.head,
+            opened.prelude,
+            snapshotBytes,
+          ),
+      );
+      if (INTERNAL_RANGO_DEBUG) {
+        this.debugShell(key, "kv-hit", {
+          freshness: read.shouldRevalidate ? "stale" : "fresh",
+          stats,
+          expiresAt: opened.head.e,
+        });
+      }
+      return read;
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] kvGetShell");
       this.debugShell(key, "kv-miss", { reason: "error" });
@@ -2328,24 +2862,28 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /** Promote a valid KV shell into the per-colo Cache API tier. */
-  private promoteShellToL1(key: string, envelope: CFShellEnvelope): void {
+  private promoteShellToL1(
+    key: string,
+    head: ShellFrameHead,
+    prelude: Uint8Array,
+    snapshotBytes: Uint8Array,
+  ): void {
     if (!this.waitUntil) return;
     this.waitUntil(() =>
       reportingAsync(
         async () => {
-          if (Date.now() > envelope.e) return;
+          if (Date.now() > head.e) return;
           const cache = await this.getCache();
-          const body = JSON.stringify(envelope);
           await cache.put(
-            this.keyToRequest(`shell:${key}`),
-            this.shellEnvelopeResponse(body, envelope),
+            this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`),
+            this.shellFrameResponse(
+              encodeShellFrame(head, prelude, snapshotBytes),
+              head,
+            ),
           );
           this.debugShell(key, "kv-promoted", {
-            remainingTtl: Math.max(
-              1,
-              Math.floor((envelope.e - Date.now()) / 1000),
-            ),
-            expiresAt: envelope.e,
+            remainingTtl: Math.max(1, Math.floor((head.e - Date.now()) / 1000)),
+            expiresAt: head.e,
           });
         },
         "cache-write",
@@ -2692,6 +3230,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private async isGloballyInvalidated(
     tags: string[] | undefined,
     taggedAt: number | undefined,
+    isolateMemo = false,
   ): Promise<boolean> {
     // Array.isArray (not just truthiness): a non-array tags value - direct store
     // misuse like setItem(k, v, { tags: "products" }), or a skewed KV envelope -
@@ -2704,7 +3243,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const inflight = ctx ? getTagMarkerInflight(ctx, this) : undefined;
     try {
       const markers = await Promise.all(
-        tags.map((tag) => this.readTagMarker(tag, memo, inflight)),
+        tags.map((tag) =>
+          isolateMemo
+            ? this.readShellTagMarker(tag)
+            : this.readTagMarker(tag, memo, inflight),
+        ),
       );
       for (const marker of markers) {
         if (marker != null && marker >= taggedAt) return true;
@@ -2733,7 +3276,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * entry Cache-Tag tokens (`headers`): an entry a purge cannot reach — one
    * written before the tokens existed, or whose tag set overflowed the
    * Cache-Tag header limit — keeps the full marker check, or purge mode
-   * would serve it stale until TTL with no eviction path.
+   * would serve it stale until TTL with no eviction path. KV-less there are
+   * no markers, so it gets the per-request memo check like any hit (#973).
    *
    * Without tagPurge this is the full marker cascade. KV-tier reads and
    * shells always use isGloballyInvalidated directly: purge cannot reach KV,
@@ -2747,7 +3291,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   ): Promise<boolean> {
     if (!this.tagPurge) return this.isGloballyInvalidated(tags, taggedAt);
     if (!Array.isArray(tags) || tags.length === 0 || !taggedAt) return false;
-    if (!this.hasEntryCacheTags(headers)) {
+    if (this.kv && !this.hasEntryCacheTags(headers)) {
       return this.isGloballyInvalidated(tags, taggedAt);
     }
     const ctx = _getRequestContext();
@@ -2803,6 +3347,55 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return this.fetchTagMarker(tag, memo);
   }
 
+  /**
+   * A PPR shell read's marker for `tag`: this request's own value if it has
+   * one (its invalidateTags() writes, or a store read), else through the
+   * per-isolate marker memo (isolate-tag-memo.ts, stale-while-revalidate
+   * under `markerFreshMs` / `markerMaxStaleMs`; a request carrying the
+   * fresh-reads cookie reads L1/KV). The value is kept in the request's
+   * shell-read record, never in the per-request memo the data families read,
+   * HIT or MISS. A store read still lands in the per-request memo, as any
+   * marker read does; it is not stale. A timed-out read fails open for this
+   * request and is not memoized.
+   */
+  private readShellTagMarker(tag: string): Promise<number | null> {
+    const ctx = _getRequestContext();
+    const memo = ctx ? getTagMarkerMemo(ctx, this) : undefined;
+    if (memo?.has(tag)) return Promise.resolve(memo.get(tag) ?? null);
+    const shell = ctx ? getShellMarkerReads(ctx, this) : undefined;
+    const pending = shell?.reads.get(tag);
+    if (pending) return pending;
+    const read = cfMarkerMemo.readThrough(
+      this.markerMemoKey(tag),
+      async (background) => {
+        const outcome = { timedOut: false, fromRequest: false };
+        const value = await this.fetchTagMarker(
+          tag,
+          background ? undefined : memo,
+          outcome,
+        );
+        return {
+          value,
+          memoize: !outcome.timedOut && !outcome.fromRequest,
+        };
+      },
+      {
+        freshMs: this.memo.markerFreshMs,
+        maxStaleMs: this.memo.markerMaxStaleMs,
+        bypass: freshReadsRequired(ctx),
+        keepAlive: this.waitUntil
+          ? (refresh) => this.waitUntil!(() => refresh)
+          : undefined,
+        onOutcome:
+          shell && (INTERNAL_RANGO_DEBUG || ctx?._metricsStore)
+            ? (outcome) => shell.outcomes.set(tag, outcome)
+            : undefined,
+      },
+    );
+    shell?.reads.set(tag, read);
+    return read;
+  }
+
   /**
    * Uncached body of readTagMarker: L1 (per-colo Cache API, opt-in via
    * tagCacheTtl) -> KV. Writes the resolved value back into the memo.
@@ -2811,19 +3404,33 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private async fetchTagMarker(
     tag: string,
     memo: Map<string, number | null> | undefined,
+    read?: { timedOut: boolean; fromRequest?: boolean },
   ): Promise<number | null> {
     // Write the resolved marker into the memo WITHOUT clobbering a value a
     // concurrent invalidateTags() wrote during our await. The router resolves
-    // sibling slots in parallel, so a slot's updateTag() can land the
-    // authoritative invalidatedAt into the memo while this read is still in
-    // flight; overwriting it with our (pre-invalidation) read result would break
+    // sibling slots in parallel, so a slot's updateTag() can land its
+    // invalidatedAt into the memo while this read is still in flight;
+    // overwriting it with our (pre-invalidation) read result would break
     // read-your-own-writes for the rest of the request. If the tag was memoized
     // mid-read, that value wins and is returned. Without a memo, the read result
     // stands as-is.
-    const memoize = (read: number | null): number | null => {
-      if (memo && memo.has(tag)) return memo.get(tag) ?? null;
-      memo?.set(tag, read);
-      return read;
+    //
+    // A mask memoized mid-read stays in this request: maskTagsForRequest
+    // wrote it before the KV put was confirmed, and a failed put must not
+    // reach other requests (#973). So it is not written to L1 here, and
+    // `read.fromRequest` keeps the shell read from storing it in the isolate
+    // marker memo; writeTagInvalidation writes both after the put. A value
+    // another read memoized mid-read came from KV or L1 and is published.
+    let fromRequest = false;
+    const memoize = (value: number | null): number | null => {
+      if (memo && memo.has(tag)) {
+        const ctx = _getRequestContext();
+        fromRequest = ctx !== undefined && isRequestMasked(ctx, this, tag);
+        if (read) read.fromRequest = fromRequest;
+        return memo.get(tag) ?? null;
+      }
+      memo?.set(tag, value);
+      return value;
     };
 
     // L1 (per-colo) marker cache - opt-in via tagCacheTtl. Bounded by the same
@@ -2871,6 +3478,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       "tag marker KV read",
     );
     if (timedOut) {
+      if (read) read.timedOut = true;
       // Memoize the fail-open result so the rest of this request is consistent
       // (and does not re-pay the timeout per segment sharing the tag).
       return memoize(null);
@@ -2878,10 +3486,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const value = raw != null ? Number(raw) : null;
     const resolved = memoize(value);
 
-    // Populate L1 for subsequent reads in this colo (non-blocking). Use the
-    // resolved (memo-aware) value so a marker invalidated mid-read is not
-    // re-cached stale into this colo's L1.
-    if (this.tagCacheTtl > 0) {
+    // Populate L1 for subsequent reads in this colo (non-blocking), from KV's
+    // answer only. A value memoized mid-read is skipped: KV's answer predates
+    // it, and the memo's may be an unconfirmed mask (see memoize above).
+    if (this.tagCacheTtl > 0 && !fromRequest) {
       const put = () => this.putTagMarkerL1(tag, resolved);
       if (this.waitUntil) this.waitUntil(put);
       else void put();
@@ -3056,29 +3664,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
-  /**
-   * Invalidate every entry tagged with any of `tags`. Receives the whole batch
-   * from one updateTag()/revalidateTag() call so the eager-purge hook fires
-   * ONCE (one CDN purge request, not one per tag). For each tag: records the KV
-   * marker (the durable cross-colo truth that reads compare taggedAt against),
-   * writes the fresh marker straight into this colo's L1 (write-through, NOT
-   * delete - a delete would let the next read re-read a not-yet-converged KV
-   * value and re-arm the stale window), and memoizes it for same-request
-   * read-your-own-writes. In purge mode (tagPurge) it then AWAITS the
-   * consumer's purge-by-tag call with the entry Cache-Tags — the eviction the
-   * per-read marker skip on L1 hits relies on. Finally fires onRevalidateTag
-   * with the namespaced lookup Cache-Tags so a consumer purge evicts the
-   * cached lookups in other colos promptly (otherwise they converge within
-   * tagCacheTtl).
-   *
-   * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
-   * runs ONLY after that tag's KV marker write is confirmed. If any KV write
-   * fails (transient error; over-limit keys are normalized by toKVKey rather
-   * than rejected), this rejects with the
-   * failed tags so an awaiting updateTag() surfaces the failure instead of
-   * silently reporting success while other requests/colos serve stale data. The
-   * eager purge still fires for the whole batch first (it is additive).
-   */
   /**
    * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
    * SAME KV markers used by runtime envelopes also evict immutable build shells
@@ -3094,12 +3679,77 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return this.isShellGenerationInvalidated(tags, sinceMs);
   }
 
+  /**
+   * Invalidate every entry tagged with any of `tags`. Receives the whole batch
+   * from one updateTag()/revalidateTag() call so the eager-purge hook fires
+   * ONCE (one CDN purge request, not one per tag). Before its first await it
+   * masks the tags for the rest of the request (maskTagsForRequest), which is
+   * all revalidateTag() waits for. For each tag it then records the KV marker
+   * (the durable cross-colo truth that reads compare taggedAt against) and
+   * writes the fresh marker straight into this colo's L1 (write-through, NOT
+   * delete - a delete would let the next read re-read a not-yet-converged KV
+   * value and re-arm the stale window). In purge mode (tagPurge) it then
+   * AWAITS the consumer's purge-by-tag call with the entry Cache-Tags — the
+   * eviction the per-read marker skip on L1 hits relies on. Finally fires
+   * onRevalidateTag with the namespaced lookup Cache-Tags so a consumer purge
+   * evicts the cached lookups in other colos promptly (otherwise they converge
+   * within tagCacheTtl).
+   *
+   * Durable-write integrity: the write-through other requests read (the
+   * isolate marker memo and L1) for a tag runs ONLY after that tag's KV marker
+   * write is confirmed. If any KV write fails (transient error; over-limit
+   * keys are normalized by toKVKey rather than rejected), this rejects with
+   * the failed tags so an awaiting updateTag() surfaces the failure instead of
+   * silently reporting success while other requests/colos serve stale data.
+   * The purge and onRevalidateTag still fire for the whole batch once the
+   * puts settle, whether or not one failed (they are additive); the rejection
+   * follows them.
+   */
   async invalidateTags(tags: string[]): Promise<void> {
     if (tags.length === 0) return;
     const invalidatedAt = Date.now();
+    this.maskTagsForRequest(tags, invalidatedAt);
+    // The invalidating isolate drops its memoized shells for these tags at
+    // once; with KV every isolate's per-read marker check rejects the rest.
+    // Reads already in flight must not memoize them again while the markers
+    // and the purge are written (KV-less purge mode has no marker to reject
+    // that copy): the record holds them out until one window after this
+    // settles, at least the default window so a store with the memo off still
+    // covers another store's reads in this isolate.
+    cfShellMemo.deleteWhere((shell) => shellHasAnyTag(shell.head.t, tags));
+    recentShellInvalidations.begin(tags, invalidatedAt);
+    try {
+      await this.writeTagInvalidation(tags, invalidatedAt);
+    } finally {
+      recentShellInvalidations.settle(
+        tags,
+        Math.max(this.memo.shellMs, DEFAULT_SHELL_MEMO_MS),
+      );
+    }
+  }
+
+  /**
+   * The request-local half of invalidateTags(), run before its first await
+   * (#973): this request's marker memo takes the new marker, so every later
+   * read in the request (data families, purge-mode L1 hits, shell reads)
+   * treats the tags as invalidated at `invalidatedAt` without waiting for the
+   * KV put or the purge that revalidateTag() leaves to waitUntil. Written
+   * before the durable write is confirmed: if that write fails, this request
+   * pays extra misses, never a stale read, and later requests read the
+   * durable state. Skipped where no read consults the memo (neither KV nor
+   * tagPurge).
+   */
+  private maskTagsForRequest(tags: string[], invalidatedAt: number): void {
+    if (!this.kv && !this.tagPurge) return;
     const ctx = _getRequestContext();
-    const memo = ctx ? getTagMarkerMemo(ctx, this) : undefined;
+    if (ctx) maskRequestTags(ctx, this, tags, invalidatedAt);
+  }
 
+  /** invalidateTags' marker writes, tag purge, and hooks. */
+  private async writeTagInvalidation(
+    tags: string[],
+    invalidatedAt: number,
+  ): Promise<void> {
     if (!this.kv && !this.onRevalidateTag && !this.tagPurge) {
       console.warn(
         `[CFCacheStore] invalidateTags had no effect: configure a KV namespace ` +
@@ -3110,6 +3760,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
     const failedTags = new Set<string>();
     const errors: unknown[] = [];
+    const lookupMarkerCacheActive = Boolean(this.kv) && this.tagCacheTtl > 0;
     if (this.kv) {
       // Markers written with no expiry (tagInvalidationTtl unset) never expire,
       // so high-cardinality tags accumulate KV keys unboundedly with no reaper.
@@ -3145,25 +3796,16 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           }
         }),
       );
-    }
 
-    // Write-through memo + L1 only for tags with a confirmed durable marker, and
-    // only when KV is configured. Markers are read exclusively through
-    // isGloballyInvalidated(), which short-circuits to "not invalidated" when
-    // !this.kv; writing memo/L1 markers without KV would be dead state no read
-    // path ever consults — EXCEPT the memo in purge mode: isL1Invalidated()
-    // consults it (and only it) on every L1 hit, so a KV-less purge-mode store
-    // still writes the memo for same-request read-your-own-writes. The
-    // onRevalidateTag purge below still fires regardless (it is additive and
-    // external to the marker cascade). The memo write is synchronous
-    // (read-your-own-writes); the L1 Cache API writes are independent, so fan
-    // them out in parallel rather than awaiting each.
-    const lookupMarkerCacheActive = Boolean(this.kv) && this.tagCacheTtl > 0;
-    if (this.kv || this.tagPurge) {
+      // Write-through (isolate marker memo + L1) only for tags with a
+      // confirmed durable marker; this request's own memo was written up
+      // front (maskTagsForRequest). The L1 Cache API writes are independent,
+      // so fan them out in parallel rather than awaiting each.
       const l1Writes: Promise<void>[] = [];
       for (const tag of tags) {
         if (failedTags.has(tag)) continue;
-        memo?.set(tag, invalidatedAt);
+        // Same isolate: later requests here see the invalidation at once.
+        cfMarkerMemo.store(this.markerMemoKey(tag), invalidatedAt);
         if (lookupMarkerCacheActive) {
           l1Writes.push(
             this.putTagMarkerL1(tag, invalidatedAt, { critical: true }),