@rangojs/router 0.17.0 → 0.18.0

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

@@ -22,12 +22,14 @@ declare global {
  * - 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 (tests). */
+export declare function resetCFShellMemoForTests(): void;
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
     readonly defaults?: CacheDefaults;
@@ -39,6 +41,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 +87,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 +235,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>;
@@ -278,31 +299,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;
     /**
@@ -450,7 +561,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * 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,
@@ -475,6 +587,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 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;
     /**
      * Uncached body of readTagMarker: L1 (per-colo Cache API, opt-in via
      * tagCacheTtl) -> KV. Writes the resolved value back into the memo.
@@ -554,29 +678,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private putTagMarkerL1;
-    /**
-     * 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
@@ -586,7 +687,47 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * isShellGenerationInvalidated.
      */
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    /**
+     * 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.
+     */
     invalidateTags(tags: string[]): Promise<void>;
+    /**
+     * 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;
+    /** 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)
@@ -11,5 +12,38 @@ export declare const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
  * never "no marker" - absence is only ever represented by this cached sentinel.
  */
 export declare const TAG_MARKER_ABSENT = "none";
+/**
+ * Request context -> store instance -> T, both levels weakly held. Also
+ * VercelCacheStore's request tag mask (#973).
+ */
+export type PerRequestStoreMap<T> = WeakMap<object, WeakMap<object, T>>;
+/** The value for (ctx, store), created on first use. */
+export declare function perRequestStoreValue<T>(map: PerRequestStoreMap<T>, ctx: object, store: object, create: () => T): T;
 export declare function getTagMarkerMemo(ctx: object, store: object): Map<string, number | null>;
+/**
+ * Mask `tags` at `at` for the rest of the request: in the request's mask and
+ * in every memo the request's contexts hold for `store` (a memo created later
+ * starts from the mask).
+ */
+export declare function maskRequestTags(ctx: object, store: object, tags: readonly string[], at: number): void;
+/** Whether this request masked `tag` through `store` (maskRequestTags). */
+export declare function isRequestMasked(ctx: object, store: object, tag: string): boolean;
+/**
+ * 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/handle-snapshot.d.ts

@@ -50,9 +50,10 @@ export declare function captureHandleOwners(segments: ResolvedSegment[], handleS
  * cache() record owns its segments' arrays, so it REPLACES them.
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
- * recorded order, an owned value through pushReplayed: the owning loader
- * re-runs on the HIT (loaders stay live), and its live pushes replace the
- * recorded ones in place instead of appending a second copy. `claim`
+ * recorded order, an owned value through pushReplayed: if the owning loader
+ * runs on the HIT (a live loader, or a promise-carrying `ssr: false` one;
+ * a promise-free one is served from the shell and does not), its live pushes
+ * replace the recorded ones in place instead of appending a second copy. `claim`
  * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
  * loader's own cache() HIT does not replay its pushes a second time
  * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A

package/dist/types/cache/index.d.ts

@@ -1,6 +1,7 @@
 export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
 export { CACHE_READ_ERROR } from "./types.js";
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
+export type { StoreMemoOptions } from "./shell-memo.js";
 export { CFCacheStore, type CFCacheStoreOptions, type CFCacheDebug, type CFCacheReadDebugEvent, type KVNamespace, CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_REVALIDATING_AT_HEADER, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, createCloudflareZonePurge, type CloudflareZonePurgeOptions, } from "./cf/index.js";
 export { VercelCacheStore, type VercelCacheStoreOptions, type VercelRuntimeCache, type VercelCacheDebug, type VercelCacheReadDebugEvent, type VercelCacheReadOutcome, VERCEL_MAX_ITEM_BYTES, VERCEL_MAX_TAGS_PER_ITEM, VERCEL_MAX_TAG_BYTES, } from "./vercel/index.js";
 export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./search-params-filter.js";