@rangojs/router 0.18.0 → 0.19.0

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

@@ -5,88 +5,72 @@
  * 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.
+ * runs on a HIT). The loader layer's part is the bake-lane (`ssr: false`)
+ * loader pins: a promise-free bake-lane loader is served from its pin and
+ * does not run; one whose return carries promises (`holes`), or whose pushes
+ * the record could not keep (`runs`), runs on the HIT. See
+ * docs/design/ppr-shell-resume.md.
  *
- * 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 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.
+ * The invariant, verbatim: the snapshot is the doc record and the bake-lane
+ * loader pins; replaying them on a HIT reproduces the shell content
+ * byte-identically; everything else a HIT reads comes from the store. A hole
+ * (a live-lane loader, or a promise nested in a bake-lane return) never reads
+ * the capture's copy of a value: it is dynamic or has its own cache. A
+ * bake-lane loader body that runs on a HIT reads the store too; its pinned
+ * container paths stay the pin's (overlayLoaderContainer), and its settled
+ * pushes stay the record's (HandleStore.pushRestored).
  */
 import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, CacheReadError } from "./types.js";
 /**
- * A store wrapper the CAPTURE render reads through. Every call passes through to
- * the underlying store unchanged; for the item/segment/response families it also
- * RECORDS, last-write-wins per (family, key):
- *   - read-hits (get/getItem/getResponse returning non-null) — the value that
- *     fed the shell,
- *   - writes (set/setItem/putResponse) — the value a MISS computed and baked.
- * The shell family (getShell/putShell) is never recorded (the snapshot rides
- * inside a shell entry). Reads that MISS are not recorded (a miss produced no
- * shell content; if the render then computed and wrote, that write is recorded).
+ * A store wrapper the CAPTURE render reads through. Every call passes through
+ * to the underlying store unchanged; the one thing it records is the doc
+ * segment record ({@link recordSegmentWrite}). No cache read is recorded: a
+ * HIT replays the handler layer from the doc record and serves a promise-free
+ * bake-lane loader from its pin, and everything else a HIT reads (a hole, a
+ * bake-lane loader body that runs there) comes from the store.
  *
  * Deferred writes: cache writes run under waitUntil (fire-and-forget on Node,
- * executionContext on workerd), so their setItem/set calls — hence their records
- * — 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.
+ * executionContext on workerd), so the doc record's write may land after the
+ * capture's match returns. The capture collects those write promises via
+ * {@link trackWrite} and awaits them ({@link settleWrites}) before reading the
+ * record and draining.
  */
 export declare class RecordingShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly inner;
+    /** The recorded segment records by key, last write wins. */
     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;
+    get isTagsInvalidatedSince(): SegmentCacheStore<TEnv>["isTagsInvalidatedSince"];
     /** Track a deferred cache-write promise so the capture can await it pre-drain. */
     trackWrite(p: Promise<unknown>): void;
     /**
-     * Record a segment-family write into the snapshot WITHOUT touching the inner
-     * store. The shell fast path's implicit doc-cache scope writes through this
-     * (via {@link SnapshotOnlySegmentStore}): the recorded doc entry must ride
-     * ONLY inside the shell entry — a passthrough write would leave a doc-keyed
-     * entry in the real store that the NEXT capture's lookup would hit, replaying
-     * the previous generation's segments instead of re-running handlers (breaking
+     * Record the doc segment record into the snapshot WITHOUT touching the
+     * inner store. The capture's implicit doc-cache scope writes through this
+     * (via {@link SnapshotOnlySegmentStore}): the record must ride ONLY inside
+     * the shell entry — a passthrough write would leave a doc-keyed entry in the
+     * real store that the NEXT capture's lookup would hit, replaying the
+     * previous generation's segments instead of re-running handlers (breaking
      * SWR recapture freshness).
      */
     recordSegmentWrite(key: string, data: CachedEntryData): void;
     /**
-     * Await the tracked deferred writes so their records are present before drain.
-     * Drains ITERATIVELY: a write task can schedule a NESTED write (the ring-3
-     * 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. 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).
+     * Await the tracked deferred writes so their records are present before
+     * drain, including a NESTED write a settled one scheduled (the ring-3
+     * cacheRoute path schedules its actual store.set in a second waitUntil).
+     * Bounded: a pathologically slow write 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); a later call still waits for what is pending.
      */
     settleWrites(timeoutMs: number): Promise<boolean>;
-    /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
+    /** The recorded segment records, or undefined if none. */
     drainSnapshot(): ShellSnapshotRecord[] | undefined;
-    /** One recorded value, by family and key. */
-    getRecord(family: ShellSnapshotRecord["family"], key: string): ShellSnapshotRecord["value"] | undefined;
+    /** One recorded segment record, by key. */
+    getRecord(key: string): CachedEntryData | undefined;
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
     delete(key: string): Promise<boolean>;
@@ -107,36 +91,23 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }
-/** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
+/** `store` when it is a RecordingShellStore (an instanceof check). */
 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.
+ * names, with at least one segment: the record partial replay and a document
+ * 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.
+ * Split a capture's snapshot into what a HIT or a partial replay reads and
+ * the rest (docs/design/shell-entry-layout.md §2). Kept: the doc record
+ * (`docKey`), as a copy inside the entry (a separately stored record could be
+ * evicted on its own, and the HIT would have nothing to replay), and the
+ * loader-family pins unless the entry is navigation-only (partial replay of
+ * such an entry seeds the doc record alone). Every other record goes.
  */
-export declare function pruneShellSnapshot(snapshot: readonly ShellSnapshotRecord[], readers: ShellSnapshotReaders, loaderKeys: ReadonlySet<string>, docKey: string): {
+export declare function pruneShellSnapshot(snapshot: readonly ShellSnapshotRecord[], navigationOnly: boolean, docKey: string | undefined): {
     kept: ShellSnapshotRecord[];
     pruned: ShellSnapshotRecord[];
 };
@@ -165,16 +136,16 @@ export declare function estimateShellEntryBytes(parts: {
     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). */
+/** Snapshot records by family, e.g. `segment:1/loader:2` (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
- * recorded, exactly like any capture read), but segment WRITES are recorded
- * into the snapshot only — see {@link RecordingShellStore.recordSegmentWrite}
- * for why passthrough would break SWR recapture. Routes with their OWN
- * cache() config never see this store (their scope resolves the app-level
- * recording store and keeps today's record-and-write behavior).
+ * The store the capture's IMPLICIT doc-cache scope resolves: reads pass
+ * through the recording store to the real one, but segment WRITES are
+ * recorded into the snapshot only — see
+ * {@link RecordingShellStore.recordSegmentWrite} for why passthrough would
+ * break SWR recapture. A route with its OWN cache() scope keeps that scope's
+ * real-store reads and writes; recordShellCaptureDocRecord (cache-store.ts)
+ * writes its doc record through this store too.
  */
 export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly recording;
@@ -185,28 +156,14 @@ export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements Segment
     set(key: string, data: CachedEntryData): Promise<void>;
     delete(key: string): Promise<boolean>;
 }
-/**
- * Materialize the loader-family seed from a shell snapshot for a HIT's tail
- * render: Flight-deserialize each recorded (promise-elided) bake-lane
- * container into a segment-key -> container Map, which serveShellHit assigns
- * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
- * Lives here so every snapshot family is decoded in this module (the
- * item/segment/response families via {@link SeededShellStore}); the loader
- * family is not a store read, so it seeds the context instead of a store.
- *
- * Deserializations run in parallel; a record that fails to decode is skipped
- * (that loader drifts — the pre-snapshot behavior — instead of failing the
- * HIT). Returns undefined when the snapshot carries no loader records, without
- * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
- */
+/** One decoded loader-family pin (buildShellLoaderSeed). */
 export interface ShellLoaderSeedEntry {
     /** The Flight-deserialized elided container (recorded paths + markers). */
     container: unknown;
     /**
-     * True when the record carries hole markers (or predates the capture-side
-     * hole bit, where hole-ness is unknown): the HIT overlay must gate on the
-     * fresh run. False = fully pinned; the payload promise resolves immediately
-     * from the pin (loader-cache.ts pin-first path).
+     * True when the record carries hole markers: the HIT overlay must gate on
+     * the fresh run. False = fully pinned; the payload promise resolves
+     * immediately from the pin (loader-cache.ts pin-first path).
      */
     holes: boolean;
     /**
@@ -216,51 +173,41 @@ export interface ShellLoaderSeedEntry {
      */
     runs: boolean;
 }
+/**
+ * Materialize the loader-family seed from a shell snapshot for a HIT's tail
+ * render: Flight-deserialize each recorded (promise-elided) bake-lane
+ * container into a segment-key -> container Map, which serveShellHit assigns
+ * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * Lives here so every snapshot family is decoded in this module (the segment
+ * family via {@link SeededShellStore}); the loader family is not a store
+ * read, so it seeds the context instead of a store.
+ *
+ * Deserializations run in parallel; a record that fails to decode is skipped
+ * (that loader drifts — the pre-snapshot behavior — instead of failing the
+ * HIT). Returns undefined when the snapshot carries no loader records, without
+ * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
+ */
 export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
 /**
- * A read-through overlay the HIT tail render reads through. For a key present in
- * the snapshot it serves the recorded value AS FRESH (shouldRevalidate: false —
- * a pinned key must NOT kick SWR background revalidation) so the tail's payload
- * matches the frozen prelude. Every other read falls through to the real store
- * (the holes — masked loaders were never recorded — stay live). Writes pass
- * through so a live hole may legitimately write, except that `segmentsOnly`
- * fully isolates the segment family: misses do not fall through, and writes or
- * deletes stay local to the navigation overlay. The shell family always passes
- * through. With `segmentsOnly`, item and response reads also pass through so a
- * partial navigation cannot freeze captured data or write a partial result into
- * the canonical document namespace.
+ * The implicit doc scope's store on a HIT tail and on a partial replay: it
+ * serves the snapshot's segment records, the doc record among them, and
+ * fully isolates the segment family. Misses do not fall through, and writes
+ * or deletes stay local to the overlay, so a partial navigation cannot write
+ * a partial result into the canonical document namespace. It carries nothing
+ * else: every other read on a HIT (a hole, a bake-lane loader body that runs
+ * there) resolves the request's own store. Loader-family records are not
+ * store reads: serveShellHit seeds them onto the tail context
+ * (_shellLoaderSeed) for the resolveLoaderData overlay instead.
  */
 export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     private readonly inner;
-    private readonly items;
     private readonly segments;
-    private readonly responses;
-    private readonly segmentsOnly;
-    constructor(inner: SegmentCacheStore<TEnv>, snapshot: ShellSnapshotRecord[], options?: {
-        segmentsOnly?: boolean;
-    });
+    constructor(inner: SegmentCacheStore<TEnv>, snapshot: readonly ShellSnapshotRecord[]);
     get defaults(): SegmentCacheStore<TEnv>["defaults"];
     get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
-    get supportsPassiveShellReads(): true | undefined;
     get(key: string): Promise<CacheGetResult | null | CacheReadError>;
-    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    set(key: string, data: CachedEntryData): Promise<void>;
     delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
-    getResponse(key: string): Promise<{
-        response: Response;
-        shouldRevalidate: boolean;
-    } | null>;
-    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
-    getItem(key: string): Promise<CacheItemResult | null>;
-    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
-    getShell(key: string, options?: {
-        claimRevalidation?: boolean;
-    }): Promise<{
-        entry: ShellCacheEntry;
-        shouldRevalidate?: boolean;
-    } | null>;
-    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

package/dist/types/cache/tag-invalidation.d.ts

@@ -30,23 +30,47 @@
  * Invariant: the mask only turns the invalidating request's hits into misses.
  * If the durable write then fails, that request paid extra misses, never a
  * stale read, and other requests read the durable state. Both also record
- * the tags on the request (markInvalidated), so a "use cache" execution or
- * stale refresh this request started before one of its own tags was
- * invalidated is neither joined nor written (cache-runtime.ts). Its own tags
- * only: a nested "use cache" function's tags do not reach the enclosing
- * entry (#980), for this gate as for eviction. Not covered (#977): such an
- * execution in another request, or a loader cache() write, still lands, and
- * the store accepts it (docs/design/caching.md "Read-your-own-writes").
+ * the tags in the isolate's invalidation order (markInvalidated), so a cache
+ * execution that started before one of its tags was invalidated, in any
+ * request, is neither joined nor written (#973, #977): see
+ * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
-import { type RequestContext } from "../server/request-context.js";
-/** The current position in that order; an execution records it at start. */
-export declare function currentCacheSeq(): number;
+import type { SegmentCacheStore } from "./types.js";
+import { type ExecutionStart } from "./invalidation-order.js";
+export { executionStart, invalidatedSince, type ExecutionStart, } from "./invalidation-order.js";
 /**
- * Whether the request invalidated any of `tags` after `since` (a
- * currentCacheSeq() value an execution recorded when it started): its value
- * may predate the invalidation, so the request neither joins nor writes it.
+ * The write gate of every cache execution (#977): whether one of `tags` was
+ * invalidated after the execution that produced the value started.
+ *
+ * Every built-in store stamps an entry when it is written (CFCacheStore's
+ * `taggedAt`, VercelCacheStore's `ta`) or checks nothing on write
+ * (MemorySegmentCacheStore), so a value read before an invalidation and
+ * written after it would be served as newer than the invalidation until it
+ * expires. Two answers, either one skips the write:
+ *
+ * - this isolate's order (invalidatedSince), which sees every request's
+ *   updateTag()/revalidateTag() here, the calling one included;
+ * - the store's markers (isTagsInvalidatedSince), for another isolate's
+ *   invalidation, as far as the store can tell: KV markers on CFCacheStore
+ *   (KV-less, only this request's own), `tm` markers on VercelCacheStore,
+ *   the process markers on MemorySegmentCacheStore. Asked about the
+ *   milliseconds after the start's: this isolate's own invalidation that
+ *   preceded the start usually shares its millisecond (Workers freeze
+ *   Date.now() between I/O), and `>=` would skip every write started right
+ *   after it. Another isolate's invalidation in the start's own millisecond
+ *   is not caught. Asked fail-closed: a marker the store cannot read
+ *   counts as an invalidation.
+ *
+ * The order is read again once the store answers: its read can be in flight
+ * while this isolate invalidates (an action awaits a "use cache" miss, whose
+ * write waits on the read, then runs updateTag()), and it then answers with
+ * the markers from before. markInvalidated is synchronous, so this second
+ * look sees every invalidation made before the answer.
+ *
+ * Invariant: a skipped write only costs a later miss, never a stale read.
+ * The caller still returns the value it computed.
  */
-export declare function invalidatedSince(ctx: RequestContext<any, any> | undefined, tags: readonly string[] | undefined, since: number): boolean;
+export declare function predatesInvalidation(store: SegmentCacheStore, tags: readonly string[] | undefined, start: ExecutionStart): Promise<boolean>;
 /**
  * Immediately expire every cache entry tagged with any of `tags`, resolving
  * once in-process invalidation across all configured stores completes.

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

@@ -67,6 +67,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * 2. Store-level `keyGenerator` (modifies default key)
      * 3. Default key generation (prefix:pathname:params)
      *
+     * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
+     * string is not a key: where the result partitions a nested cache() on
+     * another store, or a ppr shell, it fails key resolution, so the request
+     * renders uncached (as when the keyGenerator throws), and the router warns
+     * once naming the store.
+     *
      * @example Using headers for cache segmentation
      * ```typescript
      * keyGenerator: (ctx, defaultKey) => {
@@ -277,12 +283,25 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * freshness). Consulted by build-shell read-through and runtime shell stores:
      * "was it evicted" is answered by tag markers against the entry's createdAt,
      * including when invalidation races a capture that has not been written yet.
+     * Also the store's half of every cache write's gate (#977,
+     * tag-invalidation.ts predatesInvalidation): a "use cache", loader cache(),
+     * route cache() or document-cache write whose execution started before an
+     * invalidation another isolate made is skipped when this answers true, so
+     * it must reflect invalidations made after this request started reading
+     * (not a value memoized earlier in the request).
      * Optional: without it, TAGGED build entries are not served (untagged ones
-     * are unaffected — they are evictable only by deploy/buildVersion anyway).
+     * are unaffected — they are evictable only by deploy/buildVersion anyway),
+     * and writes are gated by this isolate's invalidations only.
      * Fail open to `false` on marker-read errors: a transient store fault must
      * degrade to "still valid", the same posture as the envelope tag checks.
-     */
-    isTagsInvalidatedSince?(tags: string[], sinceMs: number): Promise<boolean>;
+     * The write gate passes `{ failClosed: true }` instead: a marker it cannot
+     * read (an error, a timed-out read) answers `true`, since a skipped write
+     * only costs a later miss. A store that ignores the option still works;
+     * its fault then lets that write through.
+     */
+    isTagsInvalidatedSince?(tags: string[], sinceMs: number, options?: {
+        failClosed?: boolean;
+    }): Promise<boolean>;
 }
 /**
  * Result from getItem() for function-level caching ("use cache").
@@ -347,11 +366,10 @@ export interface ShellCacheEntry {
      * on dev RSC-module edits). The second read-time gate: a persistent shared
      * store (KV/runtime-cache) survives deploys, and an app-code change that
      * keeps the same React version would otherwise leave a stale-build
-     * prelude+postponed live under the same key. Optional only for entries
-     * stored before the field existed — those are treated as a miss and the
-     * recapture re-stamps them (pre-release, no compat shim).
+     * prelude+postponed live under the same key. A custom store returns it as
+     * putShell received it.
      */
-    buildVersion?: string;
+    buildVersion: string;
     /**
      * The initialTheme the CAPTURE render was built with: the no-cookie default
      * (payloadInitialTheme, rsc/full-payload.ts), never the capturing visitor's
@@ -366,22 +384,20 @@ export interface ShellCacheEntry {
      */
     initialTheme?: string;
     /**
-     * The CAPTURE DATA SNAPSHOT: every cache-store read-hit and write the capture
-     * render performed, in stored/serialized form. Replaying these on a HIT (via
-     * the SeededShellStore overlay, for the tail render only) reproduces the
-     * shell's cached content byte-identically, so the freshly rendered hydration
-     * payload matches the frozen prelude even after the underlying cache entries
-     * have drifted (expired, been recomputed, or been tag-invalidated).
-     *
-     * Optional: an entry captured before this field existed simply has no
-     * snapshot and keeps the pre-snapshot behavior (the tail reads live, so any
-     * shell-baked cached value that drifted mismatches the prelude). Recapture
-     * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
+     * The CAPTURE DATA SNAPSHOT, in stored/serialized form: the doc segment
+     * record every HIT replays the handler layer from (`docKey`) and the
+     * bake-lane loader pins (pruned to what a HIT reads, issue #941). Replaying
+     * them on a HIT keeps the freshly rendered hydration payload equal to the
+     * frozen prelude after the underlying cache entries have drifted; every
+     * other read on a HIT, a hole's included, reads the store. Empty when the capture
+     * recorded nothing (a prerender-served capture without bake-lane loaders,
+     * a tombstone). A custom store returns it as putShell received it. See
+     * docs/design/ppr-shell-resume.md ("the capture data snapshot").
      */
-    snapshot?: ShellSnapshotRecord[];
+    snapshot: ShellSnapshotRecord[];
     /**
      * Records the capture dropped from `snapshot` because no reader of this
-     * entry consumes them, by family (`item:4/response:1`). Diagnostic only: the
+     * entry consumes them, by family (`loader:1`). Diagnostic only: the
      * HIT tail timing reports it next to the kept records. See
      * docs/design/shell-entry-layout.md ("Record only what a HIT reads").
      */
@@ -406,6 +422,12 @@ export interface ShellCacheEntry {
     /** Capture-generation start time; tag invalidations at or after it win. */
     createdAt: number;
 }
+/**
+ * @internal A shell entry without its prelude and snapshot: what a
+ * prelude-first read (SegmentCacheStore.readShellDocument) resolves with
+ * before the snapshot bytes arrive.
+ */
+export type ShellEntryHead = Omit<ShellCacheEntry, "prelude" | "snapshot">;
 /**
  * A shell entry whose document half is present — what the document HIT path
  * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
@@ -437,7 +459,7 @@ export type ShellSnapshotFailure = "unavailable" | "corrupt";
  */
 export interface ShellDocumentRead {
     /** The entry without its prelude and snapshot (delivered separately). */
-    entry: ShellCacheEntry;
+    entry: ShellEntryHead;
     /** Raw prelude bytes (empty for a navigationOnly entry). */
     prelude: Uint8Array;
     shouldRevalidate?: boolean;
@@ -529,14 +551,13 @@ export interface ShellReadStats {
     };
 }
 /**
- * The families a shell snapshot pins. The item/segment/response families are
- * cache-store reads/writes (recorded by RecordingShellStore); the loader family
- * pins the settled CONTAINER of a bake-lane loader (lane rule: see
- * resolveLoaderData, loader-cache.ts). Excludes the shell family itself
- * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
- * it would be self-referential.
+ * The families a shell snapshot pins: the doc segment record (recorded by
+ * RecordingShellStore) and the settled CONTAINER of each bake-lane loader
+ * (lane rule: see resolveLoaderData, loader-cache.ts). No cache read is
+ * pinned: a HIT's holes, and a bake-lane loader body that runs on the HIT,
+ * read the store.
  */
-export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
+export type ShellSnapshotFamily = "segment" | "loader";
 /**
  * The stored form of a loader-family snapshot value: the bake-lane loader's
  * settled container, Flight-serialized AFTER eliding every still-pending nested
@@ -552,50 +573,34 @@ export interface ShellSnapshotLoaderValue {
      * container carries hole markers, so a HIT must gate the overlay on the
      * fresh run (only the loader body can mint the live nested promises);
      * 0 = fully pinned, so a HIT resolves the payload promise immediately from
-     * the pin and does not run the loader body (unless `runs`). Absent on
-     * pre-bit snapshots, which keep the gated path.
+     * the pin and does not run the loader body (unless `runs`).
      */
-    holes?: 0 | 1;
+    holes: 0 | 1;
     /**
      * 1 when the capture saw a loader push it could not record (a deferred
      * push, one with masked nested promises, or one made outside any loader
      * body): a HIT then still runs the loader body in the background
      * (pin-first) so those pushes reach the page. 0: a hole-free record is
-     * served from the pin alone and its body does not run on a HIT. Absent (a
-     * snapshot written before the bit, which lacks the loader-owned pushes)
-     * reads as 1, so the body supplies them.
+     * served from the pin alone and its body does not run on a HIT.
+     *
+     * Both bits are always written. A record stored before they existed (v0.17)
+     * reads each missing bit as 1 (buildShellLoaderSeed): its snapshot lacks
+     * the loader-owned pushes, so the body supplies them.
      */
-    runs?: 0 | 1;
-}
-/** A serialized cached Response for the response family of a shell snapshot. */
-export interface ShellSnapshotResponseValue {
-    status: number;
-    /** Client-facing header pairs (per-client signal headers excluded at record). */
-    headers: [string, string][];
-    /** base64-encoded response body (binary-safe, JSON-serializable). */
-    body: string;
-}
-/** The stored form of an item-family (use cache / loader cache) snapshot value. */
-export interface ShellSnapshotItemValue {
-    /** RSC-serialized return value. */
-    value: string;
-    /** RSC-encoded handle data, if any. */
-    handles?: string;
-    /** The entry's cache tags. */
-    tags?: string[];
+    runs: 0 | 1;
 }
 /**
- * One recorded cache-store read-hit or write from the capture render. `value`
- * carries the entry in its stored/serialized shape so it round-trips through a
- * JSON-serializing store (KV, CF, Vercel) with the rest of the ShellCacheEntry:
- * - `item`    -> {@link ShellSnapshotItemValue}
+ * One snapshot record: the doc segment record or a bake-lane loader pin.
+ * `value` carries it in its stored/serialized shape so it round-trips
+ * through a JSON-serializing store (KV, CF, Vercel) with the rest of the
+ * ShellCacheEntry:
  * - `segment` -> {@link CachedEntryData} (already JSON-able)
- * - `response`-> {@link ShellSnapshotResponseValue}
+ * - `loader`  -> {@link ShellSnapshotLoaderValue}
  */
 export interface ShellSnapshotRecord {
     family: ShellSnapshotFamily;
     key: string;
-    value: ShellSnapshotItemValue | CachedEntryData | ShellSnapshotResponseValue | ShellSnapshotLoaderValue;
+    value: CachedEntryData | ShellSnapshotLoaderValue;
 }
 /**
  * Options for setItem() for function-level caching ("use cache").
@@ -691,8 +696,10 @@ export type SegmentHandleData = Record<string, unknown[]>;
  * index (null: not owned). Only a PPR shell capture writes owners: the
  * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
  * the loaders it awaits, and its own cache() replays), which the record keeps
- * because the prelude rendered them. restoreHandles replays an owned value
- * through HandleStore.pushReplayed, so a loader that does run on the HIT
- * replaces it with its live push.
+ * because the prelude rendered them. A document HIT restores a bake-lane
+ * owner's value through HandleStore.pushRestored, and it stands against a run
+ * of its loader there; a live-lane owner's (a hole), and every owner's on
+ * any other replay of the record (a client navigation), go through
+ * pushReplayed, so a run of the loader replaces it with its live push.
  */
 export type HandleOwners = Record<string, Record<string, (string | null)[]>>;