@rangojs/router 0.16.0 → 0.18.0

package/dist/types/cache/handle-snapshot.d.ts

@@ -7,11 +7,18 @@
  */
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
-import type { SegmentHandleData } from "./types.js";
+import type { HandleOwners, SegmentHandleData } from "./types.js";
 type HandleRecord = Record<string, SegmentHandleData>;
-export declare function encodeHandles(handles: HandleRecord): Promise<string>;
+/**
+ * `onError` reaches the Flight encode (see serializeResult). A cache writer
+ * passes the collector it gives the value's encode, so a handle value that
+ * fails to encode (a rejected pushed promise) refuses the whole entry like a
+ * failed value does; prerender (prerender-match.ts) passes one too and
+ * hands the error to its prerender.onError policy.
+ */
+export declare function encodeHandles(handles: HandleRecord, onError?: (error: unknown) => void): Promise<string>;
 export declare function decodeHandles(encoded: string): Promise<HandleRecord | null>;
-export declare function encodeHandleValue(value: unknown): Promise<string>;
+export declare function encodeHandleValue(value: unknown, onError?: (error: unknown) => void): Promise<string>;
 /**
  * Decode a Flight-encoded handle-data string. Returns null on any decode
  * failure so the caller can skip handle restore without discarding valid
@@ -22,18 +29,52 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
  *
- * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
- * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
- * re-run fresh on every HIT, so replaying their captured values would
- * duplicate the fresh push — and their masked nested promises would stall the
- * Flight handle encode to its timeout. Threaded as an explicit argument so
- * every other getDataForSegment consumer (the render-barrier snapshot,
- * prerender) provably sees every push.
+ * DSL-loader pushes stay out of the CACHE WRITE: a HIT runs loaders exactly
+ * as an uncached render of the same request would (cache-lookup.ts
+ * resolveFreshLoadersAndYield), so replaying a recorded copy would duplicate
+ * the live push. Handler pushes, including
+ * handler-invoked ctx.use(Loader) bodies (skipped with their handler on a
+ * HIT), are kept. The store tags loader pushes by array position at push
+ * time, so primitive values are covered. A PPR shell capture untags the
+ * settled bake-lane pushes its record keeps (shell-capture.ts) and gives
+ * them an owner (captureHandleOwners). Only this call site passes
+ * excludeLoaderPushes; every other getDataForSegment consumer (the
+ * render-barrier snapshot, prerender) sees every push.
  */
-export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore, exclude?: WeakSet<object>): Record<string, SegmentHandleData>;
+export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore): Record<string, SegmentHandleData>;
+/** The owners of captureHandles' values; undefined when none is owned. */
+export declare function captureHandleOwners(segments: ResolvedSegment[], handleStore: HandleStore): HandleOwners | undefined;
 /**
  * Restore handle data from a cached snapshot into the handle store.
- * Used when serving cached segments to replay their handle data.
+ * Used when serving cached segments to replay their handle data: a route
+ * 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: 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
+ * record without owners restores as a plain replay.
+ */
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, claim?: (loaderId: string) => boolean): void;
+/**
+ * Append recorded handle pushes to the store, in recorded order, via push()
+ * so active captures and loader-scope tagging see them like live pushes. For
+ * a cached unit that shares its segments with live pushes ("use cache");
+ * restoreHandles would wipe those. `segmentId` redirects every value to one
+ * segment (the caller's).
+ *
+ * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
+ * pushes, which reach the page once per request: `claim` (setupLoaderAccess
+ * _claimLoaderPushes) skips a loader that already ran or was replayed in this
+ * request, and a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
+ * A key without ":" is a segment id (records written before owner keys) and
+ * replays unchanged. A loader's own cache() replays through loader-cache.ts
+ * replayLoaderHandles.
  */
-export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore): void;
+export declare function appendHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, segmentId?: string, claim?: (loaderId: string) => boolean): void;
 export {};

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";

package/dist/types/cache/isolate-tag-memo.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Per-isolate tag-marker memos shared by the built-in stores (issue #941;
+ * docs/design/shell-entry-layout.md "The tag-marker memo").
+ *
+ * A tagged shell HIT waits for its tag-invalidation markers before the first
+ * byte. Two things here shorten that wait:
+ *
+ * - {@link TagNameHints}: which tag NAMES a shell key carried last time, so a
+ *   HIT can start the marker reads alongside the entry read instead of after
+ *   the entry's head names its tags. Never marker values.
+ * - {@link TagMarkerMemo}: the marker VALUES (a tag's latest invalidatedAt,
+ *   or null), served stale-while-revalidate. A value younger than
+ *   `markerFreshMs` is used as is; one younger than `markerMaxStaleMs` is used
+ *   and refreshed from the store in the background; an older one blocks on
+ *   the store read as before.
+ *
+ * Simple reads get SWR; a mutation gets correct reads. The request that runs
+ * updateTag()/revalidateTag() reads its own writes through the per-request
+ * memo; the isolate that runs it writes the new value through into this memo;
+ * and its response sets the fresh-reads cookie (request-context.ts), so the
+ * same user's next requests on OTHER isolates skip this memo and the shell
+ * memo for as long as either can be stale. Other users can see a marker up to
+ * `markerMaxStaleMs` old, on top of the platform's own consistency
+ * (Cloudflare KV is eventually consistent across locations, up to about 60 s;
+ * Vercel's `tm` markers are regional).
+ *
+ * Only PPR shell reads use the value memo. Cached data families (`cache()`,
+ * `"use cache"`, responses) and the shell write gate
+ * (`isTagsInvalidatedSince`) keep reading their markers, in every request,
+ * whatever its shell read found: a shell read's memoized values never reach
+ * the data families' per-request memo (cf-tag-marker-memo.ts
+ * ShellMarkerReads).
+ */
+import type { RequestContext } from "../server/request-context.js";
+import type { ShellReadStats } from "./types.js";
+/** Default freshness of a memoized marker on CFCacheStore (ms). */
+export declare const DEFAULT_CF_MARKER_FRESH_MS = 1000;
+/** Default freshness of a memoized marker on VercelCacheStore (ms). */
+export declare const DEFAULT_VERCEL_MARKER_FRESH_MS = 300;
+/** Default oldest memoized marker served while it refreshes (ms), CF. */
+export declare const DEFAULT_CF_MARKER_MAX_STALE_MS = 10000;
+/**
+ * The same cap on VercelCacheStore: the runtime cache expires tags globally
+ * within about 300 ms, so a much longer stale window would widen that for
+ * other users more than KV's own up-to-60 s cross-location lag does on CF.
+ */
+export declare const DEFAULT_VERCEL_MARKER_MAX_STALE_MS = 2000;
+/**
+ * Most shell keys a hint map holds (least recently used evicted).
+ * @internal Exported for tests that fill the map to its cap.
+ */
+export declare const TAG_HINTS_MAX_ENTRIES = 2048;
+/** How a marker read was answered, for the debugPerformance marker row. */
+export type MarkerMemoOutcome = "fresh" | "stale" | "read" | "bypass";
+/** A memoized marker a read may use: its value, and whether it is stale. */
+export interface MarkerMemoHit {
+    value: number | null;
+    stale: boolean;
+}
+/**
+ * A store read of a marker for {@link TagMarkerMemo.readThrough}: the value,
+ * and whether it may be memoized (a timed-out read that failed open may not).
+ */
+export interface MarkerFetch {
+    value: number | null;
+    memoize: boolean;
+}
+/** Options of {@link TagMarkerMemo.readThrough}. */
+export interface MarkerReadThroughOptions {
+    /** Fresh window (ms); 0 or less reads the store and memoizes nothing. */
+    freshMs: number;
+    /** The oldest value served while it refreshes (ms). */
+    maxStaleMs: number;
+    /** The request carries the fresh-reads cookie: read the store. */
+    bypass: boolean;
+    /** Keeps a background refresh alive after the response (waitUntil). */
+    keepAlive?: (pending: Promise<void>) => void;
+    /** How the read was answered, for the debugPerformance marker row. */
+    onOutcome?: (outcome: MarkerMemoOutcome) => void;
+}
+export declare class TagMarkerMemo {
+    private readonly maxEntries;
+    private readonly slots;
+    private readonly refreshing;
+    constructor(maxEntries?: number);
+    /**
+     * The memoized marker for `key` if it is younger than `maxStaleMs` (stale
+     * when older than `freshMs`), or undefined when the caller must read the
+     * store. `freshMs <= 0` disables the memo.
+     */
+    lookup(key: string, freshMs: number, maxStaleMs: number, now?: number): MarkerMemoHit | undefined;
+    /**
+     * Record a marker the store returned to a read that started at
+     * `readStartedAt`. The age counts from the read's start, not its end: a
+     * marker written while the read was in flight may be missing from it, so
+     * the value is only known to be current as of the start. Markers only move
+     * forward, so a value older than one already held (a write-through that
+     * landed during the read) is kept at the newer value, with the later stamp.
+     */
+    store(key: string, value: number | null, readStartedAt?: number): void;
+    /**
+     * Refresh a stale marker in the background: one read per key at a time,
+     * handed to `keepAlive` (the store's waitUntil) so the runtime lets it
+     * finish after the response; without it the read runs detached. A read
+     * that fails, or may not be memoized, stores nothing.
+     */
+    refresh(key: string, read: () => Promise<MarkerFetch>, keepAlive?: (pending: Promise<void>) => void): void;
+    /**
+     * A marker through the memo, stale-while-revalidate: a value within
+     * `freshMs` is used as is; one within `maxStaleMs` is used while one
+     * background read refreshes it; otherwise, and for a request carrying the
+     * fresh-reads cookie, the store is read (`fetch(false)`) and the result
+     * memoized. `fetch(true)` is the background refresh, outside any request.
+     */
+    readThrough(key: string, fetch: (background: boolean) => Promise<MarkerFetch>, options: MarkerReadThroughOptions): Promise<number | null>;
+    clear(): void;
+}
+/**
+ * The tag names a shell key's entry carried when it was last read or written
+ * in this isolate, so the next HIT can start their marker reads before the
+ * entry names them. A wrong or missing hint costs a wasted read or nothing;
+ * the freshness check always uses the entry's own tags.
+ */
+export declare class TagNameHints {
+    private readonly maxEntries;
+    private readonly keys;
+    constructor(maxEntries?: number);
+    get(key: string): readonly string[] | undefined;
+    remember(key: string, tags: readonly string[] | undefined): void;
+    clear(): void;
+}
+/** The union of a key's remembered tag names and the route's static tags. */
+export declare function hintedTags(remembered: readonly string[] | undefined, routeTags: readonly string[] | undefined): string[];
+/**
+ * The marker row's memo outcome for a read's tags: the most store-bound one
+ * (a bypass or store read outranks a stale value, which outranks a fresh one).
+ */
+export declare function summarizeMarkerOutcomes(tags: readonly string[] | undefined, outcomes: ReadonlyMap<string, MarkerMemoOutcome>): MarkerMemoOutcome | undefined;
+/**
+ * Fill a shell read's marker-row stats (debugPerformance) for the entry's
+ * own tags: the memo outcome, and how many of them the read had hinted.
+ */
+export declare function recordMarkerRow(stats: ShellReadStats, tags: readonly string[] | undefined, outcomes: ReadonlyMap<string, MarkerMemoOutcome> | undefined): void;
+/**
+ * True when this request carries the fresh-reads cookie: a request of the same
+ * user after an updateTag()/revalidateTag(), which must not be served from an
+ * isolate memo (shell or marker) that could predate the mutation.
+ */
+export declare function freshReadsRequired(ctx: Pick<RequestContext, "_freshReads"> | undefined): boolean;

package/dist/types/cache/segment-codec.d.ts

@@ -23,7 +23,7 @@ export declare function stringToStream(str: string): ReadableStream<Uint8Array>;
  * For contexts where null is a valid result (loader caching, "use cache"),
  * use serializeResult() instead which preserves null through RSC Flight.
  */
-export declare function rscSerialize(value: unknown): Promise<string | undefined>;
+export declare function rscSerialize(value: unknown, onError?: (error: unknown) => void): Promise<string | undefined>;
 /**
  * RSC-deserialize a value from a stored string.
  */
@@ -36,7 +36,7 @@ export declare function rscDeserialize<T>(encoded: string | undefined): Promise<
  *
  * Returns null only on serialization failure.
  */
-export declare function serializeResult(value: unknown): Promise<string | null>;
+export declare function serializeResult(value: unknown, onError?: (error: unknown) => void): Promise<string | null>;
 /**
  * RSC-deserialize a cached result string.
  * Counterpart to serializeResult() — always receives a non-empty string.
@@ -52,8 +52,15 @@ export declare const deserializeComponent: (encoded: string) => Promise<unknown>
  * Serialize segments for storage.
  * Each segment's component, layout, loading, and loaderData are RSC-serialized.
  * Metadata is preserved as-is.
+ *
+ * `onError` goes to every Flight encode. A component that throws while
+ * encoding (e.g. an async server component in the tree) does not reject the
+ * encode: Flight reports it through onError and writes an error row
+ * (`1:E{...}`) that throws when the decoded tree renders. cacheRoute and the
+ * prerender producers (prerender-match.ts) pass it to refuse such an entry;
+ * without it the encode is unchanged.
  */
-export declare function serializeSegments(segments: ResolvedSegment[]): Promise<SerializedSegmentData[]>;
+export declare function serializeSegments(segments: ResolvedSegment[], onError?: (error: unknown) => void): Promise<SerializedSegmentData[]>;
 /**
  * Build ResolvedSegments that carry the STORED fragment strings verbatim
  * instead of decoding them (PPR fast-path payload splice, issue #700; see

package/dist/types/cache/shell-memo.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Per-isolate memo of fresh PPR shell reads (issue #941, decision 1;
+ * docs/design/shell-entry-layout.md).
+ *
+ * A warm isolate serving the same shell many times a second re-reads, and
+ * re-parses, the same stored entry on every HIT. The store keeps the last
+ * fresh read per key for a short window (`memo.shellMs`) and serves the next
+ * HIT from memory. What the memo does NOT skip is the part that decides
+ * whether the entry may be served: the store still runs its tag-marker check
+ * on every read, so with KV bound `updateTag()` / `revalidateTag()` stay
+ * immediate across isolates. The isolate that runs the invalidation drops its
+ * own copies and keeps reads that were in flight from memoizing them again
+ * (RecentTagInvalidations). What another isolate can serve for up to one
+ * window: a newer capture of the same key; a KV-less purge-mode purge; on
+ * Vercel, an invalidation from another region (tag markers are regional) and
+ * a platform `expireTag` issued outside rango (it writes no tag marker).
+ *
+ * Store instances are usually created per request, so the memo must outlive
+ * them: CFCacheStore keeps one module-level memo per isolate, VercelCacheStore
+ * one per runtime-cache handle (the handle carries the namespace). One byte
+ * budget (`memo.shellMaxBytes`) caps a memo; storing sweeps entries past their
+ * window, then evicts the least recently used. Measured on a 3.2 MB shell
+ * (Node 22 heap): CFCacheStore holds 1.08x what it counts (prelude plus
+ * snapshot JSON); VercelCacheStore holds 0.93x (envelope JSON plus the
+ * decoded prelude).
+ */
+/**
+ * Per-isolate memos a built-in store keeps (`CFCacheStore`: one per isolate;
+ * `VercelCacheStore`: one per `cache` handle). A window of 0 turns that memo
+ * off.
+ */
+export interface StoreMemoOptions {
+    /**
+     * PPR shell memo window (ms): after a shell read, the next HITs of that key
+     * within the window are served from memory, with no store read and no
+     * parse. Only a fresh shell whose snapshot read completed is kept. The
+     * tag-marker check still runs on every HIT, and the isolate that runs
+     * `updateTag()` / `revalidateTag()` drops its own copies, so neither that
+     * request nor a later one on the same isolate gets the invalidated shell.
+     * What ANOTHER isolate can serve for up to one window:
+     * - a newer capture of the same key;
+     * - `CFCacheStore` without KV, in purge mode: a purged shell. The purge
+     *   removes the stored entry, not other isolates' memos;
+     * - `VercelCacheStore`: an invalidation from another region (the tag
+     *   markers are a regional `cache.set`; only `expireTag` is global), and a
+     *   platform `expireTag` issued outside rango.
+     *
+     * The mutating user is not served these: the response of a request that
+     * ran `updateTag()` / `revalidateTag()` sets the fresh-reads cookie, and
+     * requests carrying it skip the memos. Set `{ shellMs: 0, markerFreshMs: 0 }`
+     * where every user's next request must see an invalidation (with KV,
+     * `CFCacheStore`'s marker memo alone can serve an invalidated shell for up
+     * to `markerMaxStaleMs`). Default 2000.
+     */
+    shellMs?: number;
+    /**
+     * Total bytes (prelude plus snapshot) the shell memo may hold; the least
+     * recently used shells are evicted first, and a shell larger than the whole
+     * budget is not kept. Default 16 MiB. 0 turns the memo off.
+     */
+    shellMaxBytes?: number;
+    /**
+     * Tag-marker memo for PPR shell reads: a tag's invalidation marker read
+     * within this many ms is used without a store read. Default 1000 on
+     * `CFCacheStore` (with KV; without KV there are no markers), 300 on
+     * `VercelCacheStore`. 0 turns the marker memo off. Cached data families
+     * (`cache()`, `"use cache"`, responses) keep reading their markers.
+     */
+    markerFreshMs?: number;
+    /**
+     * The oldest memoized marker a shell read still uses while a background
+     * read refreshes it; an older one blocks on the store read. Default 10000
+     * on `CFCacheStore`, 2000 on `VercelCacheStore`. The isolate that runs
+     * `updateTag()` / `revalidateTag()` writes the new marker into its memo,
+     * and the response sets the fresh-reads cookie, so the same user's next
+     * requests skip both memos on any isolate.
+     */
+    markerMaxStaleMs?: number;
+}
+/** Default memo window (ms). */
+export declare const DEFAULT_SHELL_MEMO_MS = 2000;
+/** Default total memo size per isolate (bytes). */
+export declare const DEFAULT_SHELL_MEMO_MAX_BYTES: number;
+/** A store's memo options, validated. */
+export interface ResolvedShellMemoOptions {
+    shellMs: number;
+    shellMaxBytes: number;
+    markerFreshMs: number;
+    markerMaxStaleMs: number;
+}
+/**
+ * Validate a store's `memo` option; the marker memo's defaults are per store
+ * (isolate-tag-memo.ts). A non-finite value (`NaN` from `Number(env.UNSET)`,
+ * `Infinity`, null) falls back to the default, like the CFCacheStore read
+ * budgets; a finite 0 or negative passes through and turns that memo off.
+ */
+export declare function resolveShellMemoOptions(memo: StoreMemoOptions | undefined, markerDefaults: {
+    markerFreshMs: number;
+    markerMaxStaleMs: number;
+}): ResolvedShellMemoOptions;
+/**
+ * Headroom on the fresh-reads cookie's lifetime: revalidateTag() writes its
+ * markers in the background, so they can land after the response that sets
+ * the cookie, and the memos' windows count from then.
+ */
+export declare const FRESH_READS_MARGIN_MS = 1000;
+/**
+ * How long the fresh-reads cookie keeps a mutating user off a store's memos:
+ * the longest either memo can still hold a value from before the mutation
+ * (the shell window; the marker memo's max-stale cap when the store reads
+ * markers through it, counted from the start of the read that filled it),
+ * plus FRESH_READS_MARGIN_MS. 0 when both memos are off: no cookie.
+ */
+export declare function freshReadsWindowMs(memo: ResolvedShellMemoOptions, markerMemo: boolean): number;
+/**
+ * Whether a shell is neither stale nor expired: the only kind a memo keeps or
+ * serves (a stale read stays with the store, which schedules the recapture).
+ */
+export declare function isShellFresh(staleAt: number, expiresAt: number, now?: number): boolean;
+/** Whether a shell's tags include any of `tags`. */
+export declare function shellHasAnyTag(shellTags: readonly string[] | undefined, tags: readonly string[]): boolean;
+export declare class ShellMemo<T> {
+    private readonly slots;
+    private totalBytes;
+    /**
+     * The value stored under `key` less than `windowMs` ago, or undefined.
+     * A hit becomes the most recently used entry.
+     */
+    get(key: string, windowMs: number, now?: number): T | undefined;
+    /**
+     * Store `value` (`bytes` counted against `maxBytes`). Entries past their own
+     * window are dropped first, so a key that is never read again does not hold
+     * memory until the cap pushes it out; then the least recently used entries
+     * are evicted until the value fits. A value larger than the whole budget, or
+     * a window of 0, is not stored.
+     */
+    set(key: string, value: T, bytes: number, windowMs: number, maxBytes: number, now?: number): void;
+    delete(key: string): void;
+    /** Drop every entry `predicate` selects. */
+    deleteWhere(predicate: (value: T) => boolean): void;
+    /** Bytes currently held. */
+    get size(): number;
+    clear(): void;
+}
+/**
+ * Tags this isolate invalidated recently, and when. `invalidateTags()` drops
+ * the isolate's memoized shells for its tags at once, but a read that was in
+ * flight (its store read done, its snapshot still arriving) can memoize one
+ * of them again while the markers or the purge are still being written. With
+ * KV that copy is harmless (every memo hit reads the markers); in KV-less
+ * purge mode the memo-hit check sees only the request's own marker memo, so
+ * nothing would reject it for a whole window, and the mutating user's next
+ * request on this isolate got the invalidated shell.
+ *
+ * A record lives from the invalidation's start until `holdMs` after it
+ * settles, which covers a read in flight when it settled (its snapshot read
+ * is bounded by the store's read budget, 170 ms by default on CFCacheStore).
+ * While it lives, a shell carrying the tag and tagged at or before the
+ * invalidation is neither memoized nor served from the memo. It only adds
+ * rejections: a shell tagged after the invalidation is not affected, and no
+ * marker read is skipped. Records are per tag across namespaces, like the
+ * memo drop in `invalidateTags()`: another namespace's shell with the same
+ * tag skips the memo for the record's life.
+ */
+export declare class RecentTagInvalidations {
+    private readonly records;
+    /** An invalidation of `tags` at `at` started. */
+    begin(tags: readonly string[], at: number, now?: number): void;
+    /** The invalidation begun for `tags` settled: hold its records `holdMs`. */
+    settle(tags: readonly string[], holdMs: number, now?: number): void;
+    /**
+     * Whether a shell carrying `tags`, tagged at `taggedAt`, predates a live
+     * record of one of them (a tagged shell with no tag time is treated as
+     * predating it).
+     */
+    covers(tags: readonly string[] | undefined, taggedAt: number | undefined, now?: number): boolean;
+    clear(): void;
+}

package/dist/types/cache/shell-snapshot.d.ts

@@ -1,26 +1,27 @@
 /**
  * Capture data snapshot: recording + seeding stores for PPR shell parity.
  *
- * The scar tissue this fixes: a PPR HIT serves frozen prelude bytes, then a
- * FULL FRESH Flight render for hydration. Any shell-baked (non-hole) content
- * that drifts between capture time and hit time — a cache() segment with a
- * shorter ttl than the shell, a tag-invalidated item — makes the fresh payload
- * disagree with the prelude, so React throws a hydration text mismatch and
- * regenerates the tree client-side (wiping the FOUC theme class, flashing
- * content). See docs/design/ppr-shell-resume.md.
+ * A PPR HIT serves frozen prelude bytes, then a Flight payload for hydration
+ * that must agree with them byte for byte. The handler layer's part of that
+ * payload is the capture's own doc segment record: the capture writes it
+ * first, renders its prelude from it, and every HIT replays it (no handler
+ * runs on a HIT). What still executes on a HIT is the loader layer: live
+ * loaders and promise-carrying bake-lane (`ssr: false`) loaders run, and the
+ * values the bake-lane ones read must match what the capture baked (a
+ * promise-free bake-lane loader is served from its pin and does not run). See docs/design/ppr-shell-resume.md.
  *
- * The fix (Next.js resume-data-cache analog, adapted to Rango's cache rings):
- * the CAPTURE render records every cache-store read-hit and write it performed
- * (the {@link RecordingShellStore}); the record rides inside the ShellCacheEntry
- * as its `snapshot`; on a HIT the tail render reads through a
- * {@link SeededShellStore} overlay that serves those recorded values AS FRESH,
- * so the shell region reproduces byte-identically while everything NOT recorded
- * (the holes — masked loaders were never executed at capture, so their reads
- * were never recorded) stays live.
+ * The mechanism (Next.js resume-data-cache analog, adapted to Rango's cache
+ * rings): the CAPTURE render records every cache-store read-hit and write it
+ * performed (the {@link RecordingShellStore}); the records ride inside the
+ * ShellCacheEntry as its `snapshot`; on a HIT the tail render reads through a
+ * {@link SeededShellStore} overlay that serves those recorded values AS FRESH.
+ * Everything NOT recorded (the holes — masked loaders were never executed at
+ * capture, so their reads were never recorded) stays live.
  *
- * The invariant, verbatim: the snapshot is exactly the set of cache-store reads
- * the capture render performed; replaying them on a HIT reproduces the shell
- * content byte-identically; everything not recorded stays live.
+ * The invariant, verbatim: the snapshot is the doc record plus the cache-store
+ * reads the capture's loaders performed; replaying them on a HIT reproduces
+ * the shell content byte-identically; everything not recorded stays live.
+ * {@link pruneShellSnapshot} drops the rest.
  */
 import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, CacheReadError } from "./types.js";
 /**
@@ -39,16 +40,26 @@ import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptio
  * — may land after the shell has quiesced. The capture collects those write
  * promises via {@link trackWrite} and awaits them ({@link settleWrites}) before
  * draining, so a MISS-at-capture value is still pinned.
+ *
+ * Loader attribution: every item/response access made inside a loader scope
+ * (hit, miss or write) marks its key in {@link loaderKeys}. A loader re-runs
+ * on every HIT, so those records stay pinned when the snapshot is pruned. A
+ * miss counts too: a loader that joins a handler's in-flight "use cache" call
+ * reads the store first (cache-runtime.ts) and finds nothing, and the record
+ * then comes from the handler's write.
  */
 export declare class RecordingShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly inner;
     private readonly records;
     private readonly writes;
+    /** Record keys ({@link recordKey}) a loader read or wrote during the capture. */
+    readonly loaderKeys: Set<string>;
     constructor(inner: SegmentCacheStore<TEnv>);
     get defaults(): SegmentCacheStore<TEnv>["defaults"];
     get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
     get supportsPassiveShellReads(): true | undefined;
     private record;
+    private noteLoaderAccess;
     /** Track a deferred cache-write promise so the capture can await it pre-drain. */
     trackWrite(p: Promise<unknown>): void;
     /**
@@ -67,12 +78,15 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
      * cacheRoute path schedules its actual store.set in a second waitUntil while the
      * first is running), so each awaited batch may enqueue more. Loop until the
      * queue empties or the deadline passes. Bounded: a pathologically slow write
-     * must never stall the capture task, so a key that does not settle in time is
-     * left unpinned (it drifts, the pre-snapshot behavior) rather than hanging.
+     * must never stall the capture task. Resolves true when every tracked write
+     * settled, false at the deadline (settleCaptureRecord then fails the capture
+     * when the doc record is among the writes still pending).
      */
-    settleWrites(timeoutMs: number): Promise<void>;
+    settleWrites(timeoutMs: number): Promise<boolean>;
     /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
     drainSnapshot(): ShellSnapshotRecord[] | undefined;
+    /** One recorded value, by family and key. */
+    getRecord(family: ShellSnapshotRecord["family"], key: string): ShellSnapshotRecord["value"] | undefined;
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
     delete(key: string): Promise<boolean>;
@@ -95,6 +109,64 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
 }
 /** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
 export declare function getRecordingStore<TEnv>(store: SegmentCacheStore<TEnv> | undefined): RecordingShellStore<TEnv> | undefined;
+/**
+ * True when `snapshot` carries the canonical doc segment record `docKey`
+ * names, with at least one segment: the record partial replay and a
+ * fast-path HIT tail consume.
+ */
+export declare function hasDocRecord(snapshot: readonly ShellSnapshotRecord[] | undefined, docKey: string | undefined): boolean;
+/**
+ * Who reads a stored snapshot besides the doc record
+ * (docs/design/shell-entry-layout.md §2):
+ * - "segments": nobody. A navigation-only entry is read only by partial
+ *   replay, which seeds the doc record alone (SeededShellStore
+ *   `segmentsOnly`, implicit doc scope only).
+ * - "loaders": the loaders a document HIT re-runs. Every HIT tail replays
+ *   the handler layer from the doc record and never runs a handler, so the
+ *   records only handler code read are dead weight.
+ */
+export type ShellSnapshotReaders = "segments" | "loaders";
+/**
+ * Split a capture's snapshot into what its readers consume and the rest: the
+ * doc record (`docKey`) always; with "loaders", the loader-family records and
+ * the item/response records a loader touched during the capture
+ * (RecordingShellStore.loaderKeys). Every other segment record goes: an
+ * explicit cache() tier's reads and writes are keyed where no HIT tail and no
+ * partial replay looks (both consult only the doc record). The doc record
+ * stays a copy inside the entry: a reference to a separately stored record
+ * could be evicted on its own, and the HIT would have nothing to replay.
+ */
+export declare function pruneShellSnapshot(snapshot: readonly ShellSnapshotRecord[], readers: ShellSnapshotReaders, loaderKeys: ReadonlySet<string>, docKey: string): {
+    kept: ShellSnapshotRecord[];
+    pruned: ShellSnapshotRecord[];
+};
+/**
+ * The shell entry head's fields estimateShellEntryBytes does not measure
+ * (versions, timestamps, theme, lengths, flags; about 200 bytes in a
+ * CFCacheStore frame) and the frame's 12-byte prefix, with room to spare.
+ */
+export declare const SHELL_ENTRY_HEAD_ALLOWANCE_BYTES: number;
+/**
+ * Bytes (UTF-8) a stored shell entry takes, as the built-in stores write it:
+ * the prelude, the snapshot's JSON, and a JSON head that carries the
+ * postponed state as an escaped string next to the tags and doc key
+ * (CFCacheStore's frame head, VercelCacheStore's envelope), plus
+ * SHELL_ENTRY_HEAD_ALLOWANCE_BYTES for the head's fixed fields and the
+ * frame prefix. Measuring the raw postponed bytes undercounted: every quote
+ * in it is escaped in the head (a /ppr-large/holes entry measured 1,098
+ * bytes under its KV value). The capture's whole-entry guard compares this
+ * with the store's value limit.
+ */
+export declare function estimateShellEntryBytes(parts: {
+    preludeBytes: number;
+    postponed: string | null | undefined;
+    snapshot: readonly ShellSnapshotRecord[] | undefined;
+    tags: readonly string[] | undefined;
+    docKey: string | undefined;
+    prunedRecords: string | undefined;
+}): number;
+/** Snapshot records by family, e.g. `segment:1/item:5` (no commas: it rides a Server-Timing desc). */
+export declare function countSnapshotFamilies(snapshot: readonly ShellSnapshotRecord[]): string;
 /**
  * The store the shell fast path's IMPLICIT doc-cache scope resolves during a
  * capture: reads pass through the recording store (a real-store hit is
@@ -137,6 +209,12 @@ export interface ShellLoaderSeedEntry {
      * from the pin (loader-cache.ts pin-first path).
      */
     holes: boolean;
+    /**
+     * The record needs its loader body to run on a HIT for pushes the capture
+     * could not record (ShellSnapshotLoaderValue.runs). Only read for a
+     * hole-free record: a hole-carrying one always runs.
+     */
+    runs: boolean;
 }
 export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
 /**
@@ -184,3 +262,14 @@ export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheSto
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }
+/**
+ * Thrown by a document HIT tail's match when its doc record cannot supply the
+ * handler layer (it failed to decode, or the entry lost it). The tail must not
+ * run handlers after the prelude committed, so withCacheLookup throws this
+ * instead of resolving segments, and serveShellHit degrades the response:
+ * the entry is replaced with a tombstone, the memo is dropped, a recapture is
+ * scheduled, and the browser reloads into a MISS.
+ */
+export declare class ShellRecordUnavailableError extends Error {
+    constructor(docKey: string | undefined);
+}