@rangojs/router 0.17.0 → 0.19.0

package/src/cache/tag-invalidation.ts

@@ -21,12 +21,36 @@
  * primitive for each tag. A single configured store (the common case) owns its
  * own tag index and distributed invalidation - there is no separate
  * tag-invalidation store.
+ *
+ * Both call invalidateTags() synchronously, inside the request (#973). A store
+ * masks the tags for the rest of the request before its first await (the
+ * built-in stores write their per-request marker state there), so the request
+ * that ran either verb reads its own writes; revalidateTag() leaves only the
+ * durable remainder (KV marker put, tag purge, expireTag) to waitUntil.
+ * 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 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 { _getRequestContext } from "../server/request-context.js";
 import { reportingAsync } from "./cache-error.js";
 import { normalizeTags } from "./cache-tag.js";
 import type { SegmentCacheStore } from "./types.js";
+import {
+  invalidatedSince,
+  markInvalidated,
+  type ExecutionStart,
+} from "./invalidation-order.js";
+
+export {
+  executionStart,
+  invalidatedSince,
+  type ExecutionStart,
+} from "./invalidation-order.js";
 
 /**
  * Collect every store that may hold entries tagged for this request's handler:
@@ -104,6 +128,67 @@ function warnPartialTagStore(fn: string, incapable: number): void {
   );
 }
 
+/**
+ * Set the fresh-reads cookie on this request's response for as long as the
+ * invalidated stores' isolate memos can stay stale (isolate-tag-memo.ts), so
+ * the same user's next requests read past them on every isolate.
+ */
+function markFreshReads(stores: SegmentCacheStore[]): void {
+  const ctx = _getRequestContext();
+  if (!ctx?._setFreshReadsCookie) return;
+  let windowMs = 0;
+  for (const store of stores) {
+    windowMs = Math.max(windowMs, store.freshReadsWindowMs ?? 0);
+  }
+  if (windowMs > 0) ctx._setFreshReadsCookie(windowMs);
+}
+
+/**
+ * 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 async function predatesInvalidation(
+  store: SegmentCacheStore,
+  tags: readonly string[] | undefined,
+  start: ExecutionStart,
+): Promise<boolean> {
+  if (!tags || tags.length === 0) return false;
+  if (invalidatedSince(tags, start.seq)) return true;
+  if (!store.isTagsInvalidatedSince) return false;
+  const marked = await store.isTagsInvalidatedSince([...tags], start.at + 1, {
+    failClosed: true,
+  });
+  return marked || invalidatedSince(tags, start.seq);
+}
+
 async function invalidateAcross(
   stores: SegmentCacheStore[],
   tags: string[],
@@ -163,6 +248,8 @@ export async function updateTag(...tags: string[]): Promise<void> {
   }
   if (incapable > 0) warnPartialTagStore("updateTag", incapable);
 
+  markFreshReads(capable);
+  markInvalidated(valid);
   await invalidateAcross(capable, valid);
 }
 
@@ -173,10 +260,12 @@ export async function updateTag(...tags: string[]): Promise<void> {
  * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
  * next read after the invalidation lands is a miss that re-renders fresh. The
  * only difference from updateTag() is awaitability - revalidateTag() defers the
- * purge off the response path and is not awaited.
+ * durable write off the response path and is not awaited.
  *
- * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
- * Action, use updateTag() instead so the action's own response is fresh.
+ * Read-your-own-writes (#973): each built-in store masks the tags for the rest
+ * of this request before revalidateTag() returns, so a Server Action's own
+ * re-render after it is fresh, as after `await updateTag()`. Other requests see
+ * the invalidation once the durable write lands.
  *
  * Fire-and-forget: because this returns void and runs in the background, a
  * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to
@@ -209,23 +298,25 @@ export function revalidateTag(...tags: string[]): void {
   }
   if (incapable > 0) warnPartialTagStore("revalidateTag", incapable);
 
+  markFreshReads(capable);
   const ctx = _getRequestContext();
+  // A build-time render drops background work (RequestContext.waitUntil), so
+  // it never ran this invalidation; keep it that way.
+  if (ctx?.build) return;
+  markInvalidated(valid);
+  // Started here, not in the waitUntil task, so each store masks the tags
+  // before this returns (#973, header above).
+  //
   // reportingAsync never rejects: it catches a failed durable write and routes
   // it through reportCacheError (loud log + onError). This is the only place a
   // revalidateTag failure can be observed, since it is not awaitable. Pass ctx
-  // explicitly - the run executes in a detached waitUntil where the ALS context
-  // is gone, so onError fires only if we hand it the captured context.
-  const run = () =>
-    reportingAsync(
-      () => invalidateAcross(capable, valid),
-      "cache-invalidate",
-      "[revalidateTag] background invalidation",
-      ctx,
-    );
-  if (ctx?.waitUntil) {
-    ctx.waitUntil(run);
-  } else {
-    // No request context (e.g. called outside ALS): best-effort background run.
-    void run();
-  }
+  // explicitly: the write can settle after the response, outside the
+  // request's ALS scope, and onError fires only with the captured context.
+  const pending = reportingAsync(
+    () => invalidateAcross(capable, valid),
+    "cache-invalidate",
+    "[revalidateTag] background invalidation",
+    ctx,
+  );
+  ctx?.waitUntil(() => pending);
 }

package/src/cache/types.ts

@@ -75,6 +75,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) => {
@@ -112,7 +118,11 @@ export interface SegmentCacheStore<TEnv = unknown> {
   get(key: string): Promise<CacheGetResult | null | CacheReadError>;
 
   /**
-   * Store entry data with TTL
+   * Store entry data with TTL. Resolve once a later `get(key)` from the same
+   * location observes the entry: the route cache() write runs in a background
+   * task, and a PPR shell capture awaits that task before it reads the entry
+   * back (#957). A store that resolves earlier makes the capture re-render
+   * the page instead of replaying the entry.
    * @param key - Cache key
    * @param data - Serialized entry data
    * @param ttl - Time-to-live in seconds
@@ -183,8 +193,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * upgrade — the reactVersion field on the entry gates that at read time).
    * @param key - Cache key
    * @param entry - The shell prelude/postponed/version/createdAt bundle
-   * @param ttlSeconds - Time-to-live in seconds
-   * @param swrSeconds - Optional stale-while-revalidate window in seconds
+   * @param ttlSeconds - Time-to-live in seconds: the route's `ppr.ttl`
+   *   (undefined: the store's default), capped to the route cache() entry
+   *   the capture replayed or wrote. A capped window arrives in whole
+   *   seconds, rounded up, with ttl + swr at least 1; its ttl can be 0 (a
+   *   shell stale from the start, captured from a record inside its swr
+   *   window).
+   * @param swrSeconds - Optional stale-while-revalidate window in seconds,
+   *   under the same cap
    * @param tags - Optional cache tags for invalidation (participates in
    *   invalidateTags via the same tag machinery as the item family)
    * @returns `invalidated` when a generation marker rejected the write,
@@ -203,6 +219,47 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<"stored" | "invalidated" | "uncacheable" | void>;
 
+  /**
+   * @internal The document serve path's shell read, for built-in stores. The
+   * serve path prefers it over getShell: it resolves with the entry and the
+   * raw (decoded) prelude, the snapshot on its own promise, and the read's
+   * `debugPerformance` stats. CFCacheStore's layout keeps the snapshot behind
+   * the prelude, so its HIT can commit before the snapshot is read;
+   * VercelCacheStore reads the whole entry and decodes the prelude once per
+   * memoized shell (issue #941, docs/design/shell-entry-layout.md). Not part
+   * of the custom-store contract.
+   */
+  readShellDocument?(
+    key: string,
+    options?: ShellDocumentReadOptions,
+  ): Promise<ShellDocumentRead | null>;
+
+  /**
+   * @internal How long (ms) this store's isolate memos (shell, tag markers)
+   * can serve a read that predates a tag invalidation made elsewhere. After
+   * updateTag()/revalidateTag(), the response's fresh-reads cookie lasts the
+   * longest of these, and the same user's requests skip the memos meanwhile.
+   * Absent or 0: nothing to cover.
+   */
+  readonly freshReadsWindowMs?: number;
+
+  /**
+   * @internal Drop this isolate's memoized copy of a shell (shell-memo.ts) so
+   * the next read goes to the store. A HIT whose doc record failed to decode
+   * calls it after replacing the entry with a tombstone: the memoized copy
+   * holds the same record. Built-in stores only; not part of the custom-store
+   * contract.
+   */
+  dropShellMemo?(key: string): void;
+
+  /**
+   * @internal The largest shell entry (prelude, postponed state, and snapshot
+   * bytes) this store can hold in one value. The capture refuses a bigger
+   * entry instead of letting the write fail inside waitUntil. Absent: the
+   * capture applies DEFAULT_SHELL_ENTRY_MAX_BYTES (Cloudflare KV's 25 MiB).
+   */
+  readonly maxShellEntryBytes?: number;
+
   /**
    * Declares the shell family present-but-inert: getShell/putShell exist but
    * no-op (a custom store whose backing tier is conditionally unavailable).
@@ -252,6 +309,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * APIs delegate to. Receives ALL of one invalidation call's tags at once so
    * stores can batch their work (e.g. a single CDN purge request rather than
    * one per tag). Stores that do not support tags simply omit this method.
+   *
+   * Both verbs call it synchronously, inside the request that invalidates
+   * (#973); revalidateTag() then hands the returned promise to waitUntil
+   * without awaiting it. Read-your-own-writes for that request comes from
+   * what the store does before its first await: record the tags as
+   * invalidated in state its reads consult for the rest of the request (the
+   * built-in stores key a map by the request's root context and the store,
+   * so contexts derived from the request share it, and compare each hit's
+   * tags and write time against it), then start the
+   * durable write. Such a mask must only ever turn hits into misses, and only
+   * in that request: a durable write that later fails then costs extra
+   * misses, never a stale read. A store that records nothing before its
+   * first await still works; the request that ran revalidateTag() can read
+   * entries the invalidation covers until the durable write lands.
    * @param tags - The cache tags to invalidate
    */
   invalidateTags?(tags: string[]): Promise<void>;
@@ -262,12 +333,27 @@ 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>;
 }
 
 /**
@@ -334,49 +420,51 @@ 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 derived context's
-   * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+   * The initialTheme the CAPTURE render was built with: the no-cookie default
+   * (payloadInitialTheme, rsc/full-payload.ts), never the capturing visitor's
+   * theme (#971). The resume tail must render ThemeProvider with the SAME
    * initialTheme the frozen prelude was rendered with: React resume requires the
    * tree above the holes to match the prerendered tree, and initialTheme is
    * per-request METADATA, not part of the cached segments — a visitor whose
-   * theme differs from the capturer's would otherwise produce a divergent resume
+   * theme differs from the capture's would otherwise produce a divergent resume
    * tree (broken stitching/hydration). The visitor's real theme is applied
    * pre-paint by the FOUC script and re-synced from the cookie post-mount by
    * ThemeProvider.
    */
   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").
-   */
-  snapshot?: ShellSnapshotRecord[];
-  /**
-   * The key of the CANONICAL document segment record inside `snapshot` — the
-   * one navigation replay can actually consume (resolved under the implicit
-   * doc namespace at capture; see CacheScope.cacheRoute). Replay eligibility
-   * requires this exact record: the snapshot also carries incidentally
-   * recorded explicit-tier records (RecordingShellStore passthroughs) whose
-   * keys a partial lookup can never resolve, and counting those declared
-   * entries "replayable" that always missed (`snapshot-miss` flip-flop).
-   * Absent on entries captured before the field existed OR when the capture
-   * recorded no doc record (cache(false)/condition-false routes, prerender
-   * short-circuit) — both read as `no-segment-snapshot`; recapture heals the
-   * former.
+   * 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[];
+  /**
+   * Records the capture dropped from `snapshot` because no reader of this
+   * 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").
+   */
+  prunedRecords?: string;
+  /**
+   * The key of the document segment record inside `snapshot`: the handler
+   * layer every HIT replays (a document HIT tail looks the record up by this
+   * key, so a store keyGenerator or a build-time capture host cannot send it
+   * elsewhere) and the record navigation replay consumes (resolved under the
+   * implicit doc namespace at capture; see CacheScope.cacheRoute). A capture
+   * that ran handlers always stores it; only a prerender-served entry (the
+   * prerender store supplies the handler layer) has none. A document entry
+   * without it is served as a MISS.
    */
   docKey?: string;
   /**
@@ -385,30 +473,17 @@ export interface ShellCacheEntry {
    * the partial request's headers and middleware state are not document state.
    */
   navigationOnly?: true;
-  /**
-   * True when the capture's HANDLER layer declared per-request liveness: a
-   * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
-   * capture mask turns it into a never-filling hole), such a push was still
-   * pending when the entry was written, or a handler-invoked loader
-   * (ctx.use(loader) from a handler body — the consumption lane, #672)
-   * executed during the capture. The serve tail then must NOT take the
-   * handler-free fast path (the implicit doc-cache hit): only a handler
-   * re-run can mint that hole's live promise or refresh that consumed value.
-   * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
-   * their holes always fill.
-   */
-  handlerLiveHoles?: boolean;
-  /**
-   * Legacy/fallback marker for a transition({ when }) predicate that was not
-   * evaluated by the PPR pre-handler gate. Such an entry stays conservatively
-   * ineligible for handler-free replay. New PPR matches evaluate known segment
-   * predicates before the pipeline and do not set this marker.
-   */
-  transitionWhen?: true;
   /** 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
@@ -421,15 +496,122 @@ export type DocumentShellCacheEntry = ShellCacheEntry & {
   postponed: string | null;
 };
 
+/** @internal Options of {@link SegmentCacheStore.readShellDocument}. */
+export interface ShellDocumentReadOptions {
+  /**
+   * Tag names the route declares for its shell (`ppr.tags`), known before the
+   * entry is read: their marker reads can start alongside the entry read.
+   */
+  tagHints?: readonly string[];
+}
+
+/**
+ * @internal Why a prelude-first read's snapshot is missing although the entry
+ * stored one: `unavailable` (the read timed out or failed; the entry may be
+ * sound) or `corrupt` (the bytes arrived and do not parse; the store evicted
+ * the entry).
+ */
+export type ShellSnapshotFailure = "unavailable" | "corrupt";
+
+/**
+ * @internal Result of {@link SegmentCacheStore.readShellDocument}.
+ */
+export interface ShellDocumentRead {
+  /** The entry without its prelude and snapshot (delivered separately). */
+  entry: ShellEntryHead;
+  /** Raw prelude bytes (empty for a navigationOnly entry). */
+  prelude: Uint8Array;
+  shouldRevalidate?: boolean;
+  /**
+   * The capture snapshot, read after the prelude. Resolves undefined when the
+   * entry has none or it could not be read (`snapshotFailure` says which); a
+   * document HIT then cannot replay its doc record and degrades
+   * (rsc-rendering.ts serveShellHit).
+   * Never rejects.
+   */
+  snapshot: Promise<ShellSnapshotRecord[] | undefined>;
+  /**
+   * Why `snapshot` resolved undefined although the entry stored one, or
+   * undefined when it did not fail. A document HIT that cannot replay its
+   * doc record replaces the entry only when it is broken, not when its read
+   * was merely slow (rsc-rendering.ts serveShellHit). Never rejects.
+   */
+  snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+  /**
+   * Where the read's time and bytes went, for the `debugPerformance` metrics
+   * (rsc-rendering.ts) and the store's own debug trace. Present only when one
+   * of them is on for the request.
+   */
+  stats?: ShellReadStats;
+}
+
+/**
+ * @internal Sub-steps of a prelude-first shell read. Times are ms. workerd
+ * advances its clock only on I/O, so a CPU-only field
+ * (`snapshot.parseMs`) reads 0 on a deployed worker: the byte counts are the
+ * cost signal there.
+ */
+export interface ShellReadStats {
+  /**
+   * The tier that answered: `memo` (the store's shell memo), `l1`/`kv`
+   * (CFCacheStore), or `store` (a single-tier store, VercelCacheStore).
+   */
+  tier: "memo" | "l1" | "kv" | "store";
+  /** The per-isolate memo's outcome for this read and its size after it. */
+  memo?: { hit: boolean; bytes: number };
+  /**
+   * A KV read after an L1 attempt: how long the L1 attempt took and why it
+   * missed. The KV fields below then restart from the KV read.
+   */
+  l1MissMs?: number;
+  l1MissReason?: string;
+  /** Cache API match (L1) or KV get (KV) until the body was available. */
+  matchMs?: number;
+  /** Frame head read (I/O) and parse. */
+  headMs?: number;
+  /** Prelude bytes read. */
+  preludeMs?: number;
+  /** Tag-marker read, start to resolve (runs alongside the prelude read). */
+  markerMs?: number;
+  /** How long the read waited for the marker after the prelude was read. */
+  markerWaitMs?: number;
+  /**
+   * The marker check was awaited after the entry read (VercelCacheStore), not
+   * alongside the prelude read; hinted reads still start with the entry read.
+   */
+  markerSerial?: true;
+  /**
+   * How the isolate marker memo answered the shell's tags (the most
+   * store-bound outcome across them): `fresh`, `stale` (served, refreshing in
+   * the background), `read` (from the store), `bypass` (fresh-reads cookie).
+   */
+  markerMemo?: "fresh" | "stale" | "read" | "bypass";
+  /** Tags whose marker reads were started before the entry's head (hints). */
+  markerHinted?: readonly string[];
+  /** When the hinted marker reads started (performance.now()). */
+  markerHintStartedAt?: number;
+  /** How many of the shell's tags were hinted. */
+  markerHintHits?: number;
+  /** How long the hinted marker reads ran before the entry named its tags. */
+  markerLeadMs?: number;
+  /** The request carried the fresh-reads cookie: no isolate memo was used. */
+  freshReads?: true;
+  headBytes?: number;
+  preludeBytes?: number;
+  /** Number of the shell's tags the marker read covered. */
+  tags?: number;
+  /** Filled after the commit, once the snapshot has been read. */
+  snapshot?: { readMs: number; parseMs: number; bytes: number };
+}
+
 /**
- * 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
@@ -446,49 +628,35 @@ 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 while the fresh run proceeds ungated (side effects and cache
-   * read-through writes preserved; its values were discarded either way —
-   * recorded paths win wholesale). Absent on pre-bit snapshots, which keep
-   * the gated path.
+   * the pin and does not run the loader body (unless `runs`).
    */
-  holes?: 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[];
+  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.
+   *
+   * 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;
 }
 
 /**
- * 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;
 }
 
 /**
@@ -591,8 +759,12 @@ export type SegmentHandleData = Record<string, unknown[]>;
 /**
  * segmentId -> handleName -> the owning loader id of each recorded value, by
  * index (null: not owned). Only a PPR shell capture writes owners: the
- * settled pushes of an `ssr: false` loader's own body, which the record keeps
- * because the prelude rendered them. restoreHandles replays an owned value
- * through HandleStore.pushReplayed, so that loader's live re-run replaces it.
+ * 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. 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)[]>>;