@rangojs/router 0.17.0 → 0.19.0

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -3,31 +3,17 @@ declare global {
         readonly default: Cache;
     }
 }
-/**
- * Cloudflare Edge Cache Store
- *
- * Production cache store using Cloudflare's Cache API (L1) with optional
- * KV persistence (L2).
- *
- * L1 (Cache API): Per-colo, fast, ephemeral. Handles SWR atomically.
- * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
- *
- * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
- * Write flow: L1 write + L2 write (both via waitUntil)
- *
- * Features:
- * - Extended TTL for SWR window (max-age = ttl + swr)
- * - Staleness via x-edge-cache-stale-at header
- * - Atomic REVALIDATING status for thundering herd prevention (L1 only)
- * - Non-blocking writes via waitUntil
- * - KV L2 for cross-colo cache persistence
- */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
 import { type RequestContext } from "../../server/request-context.js";
 import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
 export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
 import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions } from "./cf-cache-types.js";
 export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
+/**
+ * @internal Reset the per-isolate shell and marker memos and the once-per-
+ * isolate warnings (tests).
+ */
+export declare function resetCFShellMemoForTests(): void;
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
     readonly defaults?: CacheDefaults;
@@ -39,6 +25,19 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly edgeLookupTimeoutMs;
     private readonly edgeReadTimeoutMs;
     private readonly kvReadTimeoutMs;
+    /**
+     * 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;
+    private readonly memo;
+    /** @internal SegmentCacheStore.freshReadsWindowMs */
+    readonly freshReadsWindowMs: number;
     private readonly debug?;
     private readonly kv?;
     /** True when constructed without KV: no durable tag history (see ctor). */
@@ -72,7 +71,11 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private emitDebug;
-    /** 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;
     /**
      * Resolve the cache-key base URL for the current cache operation.
@@ -216,7 +219,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     /**
      * 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.
      */
     set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
@@ -269,7 +274,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /**
      * Generation gate for shell writes and the capture scheduler
      * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
-     * Without KV there are no markers: in purge mode the per-request memo is
+     * Without KV there are no markers: in purge mode the per-request mask is
      * the only signal — a capture racing THIS request's updateTag() is still
      * rejected (read-your-own-writes), while cross-request races are bounded
      * by ttl+swr exactly like the data families' purge-mode writes. Without
@@ -278,31 +283,121 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private isShellGenerationInvalidated;
     /**
-     * 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.
      */
     getShell(key: string): Promise<{
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
     /**
-     * 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).
+     * @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.
+     */
+    readShellDocument(key: string, options?: ShellDocumentReadOptions): Promise<ShellDocumentRead | null>;
+    private readShellDocumentWithin;
+    /** @internal SegmentCacheStore.dropShellMemo */
+    dropShellMemo(key: string): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** The isolate marker memo's key for a tag: markers are per namespace and version. */
+    private markerMemoKey;
+    /** The memo key: one per namespace, build version, base URL, and shell key. */
+    private shellMemoKey;
+    /**
+     * 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 readMemoizedShell;
+    /**
+     * 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;
+    /**
+     * 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 openShellFrame;
+    /**
+     * 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;
+    /** Delete a shell from both tiers (non-blocking). */
+    private evictShell;
+    /**
+     * 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.
      */
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
-    /** Rebuild the public shell entry from its validated storage envelope. */
-    private shellEnvelopeToEntry;
-    /** Build the Cache API representation of the coupled shell envelope. */
-    private shellEnvelopeResponse;
-    /** KV shell fallback with corruption checks and background L1 promotion. */
-    private kvGetShell;
+    /** The Cache API representation of a shell frame. */
+    private shellFrameResponse;
+    /**
+     * 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 kvReadShellDocument;
     /** Promote a valid KV shell into the per-colo Cache API tier. */
     private promoteShellToL1;
     /**
@@ -442,15 +537,16 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * configured), invalidateTags() evicts L1 entries via a Cloudflare
      * purge-by-tag call, so a hit that SURVIVED is trusted without a per-read
      * marker lookup — that skipped lookup is the entire point of purge mode.
-     * Only the per-request memo is consulted (synchronous, no KV read) so a
-     * request that ran updateTag() still masks its own entries during the purge
-     * propagation window (read-your-own-writes).
+     * Only the request's mask and its memo are consulted (synchronous, no KV
+     * read) so a request that ran updateTag() still misses its own entries
+     * during the purge propagation window (read-your-own-writes).
      *
      * The trust is conditional on the entry actually CARRYING this store's
      * 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 mask 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,
@@ -463,9 +559,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /**
      * Read a tag's latest invalidation timestamp (or null if never invalidated)
      * through the cascade: per-request memo -> per-colo L1 cache (only when
-     * tagCacheTtl > 0) -> KV (the global truth). The memo is always consulted
-     * first so it stays authoritative within a request (read-your-own-writes),
-     * and every KV/L1 result is written back into the memo. A Cache API miss
+     * tagCacheTtl > 0) -> KV (the global truth). Every KV/L1 result is written
+     * back into the memo, so the request reads one value per tag. A Cache API miss
      * always falls through to KV; absence is represented by a cached sentinel,
      * never by a miss.
      *
@@ -475,6 +570,18 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private readTagMarker;
+    /**
+     * A PPR shell read's marker for `tag`: this request's own store read if it
+     * has one, 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;
     /**
      * Uncached body of readTagMarker: L1 (per-colo Cache API, opt-in via
      * tagCacheTtl) -> KV. Writes the resolved value back into the memo.
@@ -554,39 +661,84 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private putTagMarkerL1;
+    /**
+     * SegmentCacheStore.isTagsInvalidatedSince: the SAME KV markers used by
+     * runtime envelopes also evict immutable build shells, and gate the writes
+     * of cache executions that started before an invalidation (#977,
+     * tag-invalidation.ts predatesInvalidation). Marker >= since. A marker read
+     * that fails or times out answers false (fail open), or true for the write
+     * gate (`failClosed`). With KV each marker is read past the per-request
+     * memo (isInvalidatedSincePastMemo); KV-less it degrades to the per-request
+     * mask in purge mode and to false otherwise — see
+     * isShellGenerationInvalidated.
+     */
+    isTagsInvalidatedSince(tags: string[], sinceMs: number, options?: {
+        failClosed?: boolean;
+    }): Promise<boolean>;
+    /**
+     * isTagsInvalidatedSince with KV, never answered from a marker value this
+     * request read before the asking gate. A write gate asks after an
+     * execution that can run for seconds, and the per-request memo can hold
+     * the marker the request read before it (a stale hit reads its entry's
+     * markers, then its refresh runs): answered from it, another isolate's
+     * invalidation in between let the refresh write.
+     *
+     * - This request's own invalidations answer from its mask, checked again
+     *   once the reads are back: a read in flight when the request invalidated
+     *   one of the tags resolved to the marker before it.
+     * - Each tag is read through gateMarkerRead (request-tag-mask.ts): gates
+     *   asking while a read is in flight share it; a settled read is not
+     *   reused.
+     * - The read returns its own value from L1 (tagCacheTtl) or KV, not one an
+     *   older read of the tag memoized while it was in flight, and fills the
+     *   memo only when it holds nothing, so a build shell's check still serves
+     *   the request's later reads. A timed-out read fills nothing.
+     * - It publishes to L1 unless the request masked the tag
+     *   (fetchTagMarker), and never without a request context (a detached
+     *   waitUntil task), where a mask cannot be told apart.
+     * - A read that fails or times out answers `failClosed`: the write gate
+     *   counts it as an invalidation, other callers as none.
+     * @internal
+     */
+    private isInvalidatedSincePastMemo;
     /**
      * 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),
+     * 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), 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).
+     * 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 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
-     * and captures whose write races updateTag(). Thin public wrapper over the
-     * shell generation check (marker >= since, fail open); KV-less it degrades
-     * to the per-request memo in purge mode and to false otherwise — see
-     * isShellGenerationInvalidated.
+     * 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.
      */
-    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
     invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * The request-local half of invalidateTags(), run before its first await
+     * (#973): the request masks the tags (request-tag-mask.ts), so every later
+     * read in the request (data families, purge-mode L1 hits, shell reads)
+     * treats them as invalidated at `invalidatedAt` without waiting for the KV
+     * put or the purge that revalidateTag() leaves to waitUntil. Skipped where
+     * no read consults the mask (neither KV nor tagPurge).
+     */
+    private maskTagsForRequest;
+    /** invalidateTags' marker writes, tag purge, and hooks. */
+    private writeTagInvalidation;
     /**
      * KV fallback for segment cache reads.
      * Returns null if KV is not configured, entry is missing, or expired.

package/dist/types/cache/cf/cf-cache-types.d.ts

@@ -2,6 +2,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.
  * Avoids hard dependency on @cloudflare/workers-types.
@@ -294,9 +295,12 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
     edgeLookupTimeoutMs?: number;
     /**
      * 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
@@ -309,7 +313,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
@@ -319,6 +327,25 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * <= 0) to disable and always await KV.
      */
     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/dist/types/cache/cf/cf-shell-frame.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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";
+/** 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;
+}
+/**
+ * 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 declare function encodeShellFrame(head: ShellFrameHead, prelude: Uint8Array, snapshot?: Uint8Array): Uint8Array<ArrayBuffer>;
+/**
+ * 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 declare function shellFrameToText(frame: Uint8Array): string;
+/** UTF-8 JSON of a snapshot, or undefined when there is none to store. */
+export declare function encodeShellSnapshot(snapshot: ShellSnapshotRecord[] | undefined): Uint8Array | 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 declare function parseShellSnapshot(bytes: Uint8Array): ShellSnapshotRecord[] | undefined;
+/**
+ * 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 declare class ShellFrameReader {
+    private readonly reader;
+    private chunks;
+    private buffered;
+    private done;
+    /** Bytes of the prefix and head, once readHead has read them. */
+    headBytes: number;
+    constructor(body: ReadableStream<Uint8Array>);
+    /** Exactly `n` bytes, or null when the stream ends first. */
+    take(n: number): Promise<Uint8Array | null>;
+    /** The head, or null when the magic, length, or JSON is malformed or short. */
+    readHead(): Promise<ShellFrameHead | null>;
+    /** Everything after what was taken, to the end of the stream. */
+    readRest(): Promise<Uint8Array>;
+    /** Stop reading and release the body. */
+    cancel(): void;
+}

package/dist/types/cache/cf/cf-tag-marker-memo.d.ts

@@ -1,3 +1,4 @@
+import type { MarkerMemoOutcome } from "../isolate-tag-memo.js";
 /**
  * Cache-API path prefix for the optional per-colo L1 cache of tag-invalidation
  * markers (enabled by tagCacheTtl). Distinct from data keys (doc:/fn:/segment)
@@ -12,4 +13,22 @@ export declare const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
  */
 export declare const TAG_MARKER_ABSENT = "none";
 export declare function getTagMarkerMemo(ctx: object, store: object): Map<string, number | null>;
+/**
+ * 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>;
+}
+export declare function getShellMarkerReads(ctx: object, store: object): ShellMarkerReads;
 export declare function getTagMarkerInflight(ctx: object, store: object): Map<string, Promise<number | null>>;

package/dist/types/cache/document-cache.d.ts

@@ -13,6 +13,16 @@
  * 4. If miss → run handler, cache if response has cache headers
  */
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
+import { type RequestContext } from "../server/request-context.js";
+/**
+ * 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 declare function documentCacheStoresRender(reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">): boolean;
 export interface DocumentCacheOptions<TEnv = any> {
     /**
      * Skip caching for specific paths (e.g., API routes)