@rangojs/router 0.17.0 → 0.19.0

package/src/cache/shell-snapshot.ts

@@ -1,26 +1,24 @@
 /**
  * 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). 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 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 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 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 {
@@ -31,63 +29,45 @@ import type {
   CachedEntryData,
   ShellCacheEntry,
   ShellSnapshotRecord,
-  ShellSnapshotItemValue,
-  ShellSnapshotResponseValue,
   ShellSnapshotLoaderValue,
   CacheReadError,
 } from "./types.js";
-import { CACHE_READ_ERROR } from "./types.js";
-import { bufferToBase64, base64ToBuffer } from "./cf/cf-base64.js";
-import { isPerClientSignalHeader } from "../browser/cookie-name.js";
-
-/** Compose the last-write-wins map key. NUL (`\u0000`) cannot appear in a cache key. */
-function recordKey(family: ShellSnapshotRecord["family"], key: string): string {
-  return `${family}\u0000${key}`;
-}
+import { settleGrowing } from "./background-task.js";
 
-/** Serialize a Response to the snapshot's stored shape (base64 body). */
-async function serializeResponse(
-  response: Response,
-): Promise<ShellSnapshotResponseValue> {
-  const body = await response.clone().arrayBuffer();
-  const headers: [string, string][] = [];
-  response.headers.forEach((value, name) => {
-    // Mirror putResponse: per-client signal headers never enter a shared entry.
-    if (isPerClientSignalHeader(name)) return;
-    headers.push([name, value]);
-  });
-  return { status: response.status, headers, body: bufferToBase64(body) };
-}
-
-/** Rebuild a live Response from a snapshot's stored response shape. */
-function deserializeResponse(value: ShellSnapshotResponseValue): Response {
-  return new Response(base64ToBuffer(value.body), {
-    status: value.status,
-    headers: new Headers(value.headers),
-  });
+/**
+ * The inner store's isTagsInvalidatedSince, absent when it has none. A
+ * capture runs on RecordingShellStore as the request's store, and the writes
+ * it passes through gate on it (#977, tag-invalidation.ts
+ * predatesInvalidation).
+ */
+function forwardTagHistory<TEnv>(
+  inner: SegmentCacheStore<TEnv>,
+): SegmentCacheStore<TEnv>["isTagsInvalidatedSince"] {
+  return inner.isTagsInvalidatedSince
+    ? (tags, sinceMs, options) =>
+        inner.isTagsInvalidatedSince!(tags, sinceMs, options)
+    : undefined;
 }
 
 /**
- * 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.
+ * 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 class RecordingShellStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
-  private readonly records = new Map<string, ShellSnapshotRecord>();
+  /** The recorded segment records by key, last write wins. */
+  private readonly records = new Map<string, CachedEntryData>();
   private readonly writes: Promise<unknown>[] = [];
 
   constructor(private readonly inner: SegmentCacheStore<TEnv>) {}
@@ -101,13 +81,8 @@ export class RecordingShellStore<
   get supportsPassiveShellReads(): true | undefined {
     return this.inner.supportsPassiveShellReads;
   }
-
-  private record(
-    family: ShellSnapshotRecord["family"],
-    key: string,
-    value: ShellSnapshotRecord["value"],
-  ): void {
-    this.records.set(recordKey(family, key), { family, key, value });
+  get isTagsInvalidatedSince(): SegmentCacheStore<TEnv>["isTagsInvalidatedSince"] {
+    return forwardTagHistory(this.inner);
   }
 
   /** Track a deferred cache-write promise so the capture can await it pre-drain. */
@@ -116,56 +91,50 @@ export class RecordingShellStore<
   }
 
   /**
-   * 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 {
-    this.record("segment", key, data);
+    this.records.set(key, data);
   }
 
   /**
-   * 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, so a key that does not settle in time is
-   * left unpinned (it drifts, the pre-snapshot behavior) rather than hanging.
+   * 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.
    */
-  async settleWrites(timeoutMs: number): Promise<void> {
-    const deadline = Date.now() + timeoutMs;
-    while (this.writes.length > 0) {
-      const remaining = deadline - Date.now();
-      if (remaining <= 0) return;
-      // Take the current batch; new writes scheduled while awaiting accumulate in
-      // this.writes and are drained on the next iteration.
-      const batch = this.writes.splice(0);
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      const guard = new Promise<void>((resolve) => {
-        timer = setTimeout(resolve, remaining);
-        (timer as { unref?: () => void }).unref?.();
-      });
-      await Promise.race([Promise.allSettled(batch).then(() => {}), guard]);
-      if (timer) clearTimeout(timer);
-    }
+  settleWrites(timeoutMs: number): Promise<boolean> {
+    return settleGrowing(this.writes, Date.now() + timeoutMs);
   }
 
-  /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
+  /** The recorded segment records, or undefined if none. */
   drainSnapshot(): ShellSnapshotRecord[] | undefined {
-    return this.records.size > 0 ? [...this.records.values()] : undefined;
+    if (this.records.size === 0) return undefined;
+    return [...this.records].map(
+      ([key, value]): ShellSnapshotRecord => ({
+        family: "segment",
+        key,
+        value,
+      }),
+    );
+  }
+
+  /** One recorded segment record, by key. */
+  getRecord(key: string): CachedEntryData | undefined {
+    return this.records.get(key);
   }
 
   async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
-    const result = await this.inner.get(key);
-    if (result && result !== CACHE_READ_ERROR) {
-      this.record("segment", key, result.data);
-    }
-    return result;
+    return this.inner.get(key);
   }
 
   async set(
@@ -174,7 +143,6 @@ export class RecordingShellStore<
     ttl: number,
     swr?: number,
   ): Promise<void> {
-    this.record("segment", key, data);
     return this.inner.set(key, data, ttl, swr);
   }
 
@@ -189,11 +157,7 @@ export class RecordingShellStore<
   async getResponse(
     key: string,
   ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
-    if (!this.inner.getResponse) return null;
-    const result = await this.inner.getResponse(key);
-    if (result)
-      this.record("response", key, await serializeResponse(result.response));
-    return result;
+    return this.inner.getResponse ? this.inner.getResponse(key) : null;
   }
 
   async putResponse(
@@ -203,23 +167,11 @@ export class RecordingShellStore<
     swr?: number,
     tags?: string[],
   ): Promise<void> {
-    if (!this.inner.putResponse) return;
-    this.record("response", key, await serializeResponse(response));
-    return this.inner.putResponse(key, response, ttl, swr, tags);
+    return this.inner.putResponse?.(key, response, ttl, swr, tags);
   }
 
   async getItem(key: string): Promise<CacheItemResult | null> {
-    if (!this.inner.getItem) return null;
-    const result = await this.inner.getItem(key);
-    if (result) {
-      const value: ShellSnapshotItemValue = {
-        value: result.value,
-        handles: result.handles,
-        tags: result.tags,
-      };
-      this.record("item", key, value);
-    }
-    return result;
+    return this.inner.getItem ? this.inner.getItem(key) : null;
   }
 
   async setItem(
@@ -227,14 +179,7 @@ export class RecordingShellStore<
     value: string,
     options?: CacheItemOptions,
   ): Promise<void> {
-    if (!this.inner.setItem) return;
-    const stored: ShellSnapshotItemValue = {
-      value,
-      handles: options?.handles,
-      tags: options?.tags,
-    };
-    this.record("item", key, stored);
-    return this.inner.setItem(key, value, options);
+    return this.inner.setItem?.(key, value, options);
   }
 
   async getShell(
@@ -259,7 +204,7 @@ export class RecordingShellStore<
   }
 }
 
-/** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
+/** `store` when it is a RecordingShellStore (an instanceof check). */
 export function getRecordingStore<TEnv>(
   store: SegmentCacheStore<TEnv> | undefined,
 ): RecordingShellStore<TEnv> | undefined {
@@ -267,13 +212,119 @@ export function getRecordingStore<TEnv>(
 }
 
 /**
- * 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).
+ * True when `snapshot` carries the canonical doc segment record `docKey`
+ * names, with at least one segment: the record partial replay and a document
+ * HIT tail consume.
+ */
+export function hasDocRecord(
+  snapshot: readonly ShellSnapshotRecord[] | undefined,
+  docKey: string | undefined,
+): boolean {
+  if (docKey === undefined || !snapshot) return false;
+  return snapshot.some((record) => {
+    if (
+      !record ||
+      typeof record !== "object" ||
+      record.family !== "segment" ||
+      record.key !== docKey ||
+      typeof record.value !== "object" ||
+      record.value === null
+    ) {
+      return false;
+    }
+    const segments = (record.value as { segments?: unknown }).segments;
+    return Array.isArray(segments) && segments.length > 0;
+  });
+}
+
+/**
+ * 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 function pruneShellSnapshot(
+  snapshot: readonly ShellSnapshotRecord[],
+  navigationOnly: boolean,
+  docKey: string | undefined,
+): { kept: ShellSnapshotRecord[]; pruned: ShellSnapshotRecord[] } {
+  const kept: ShellSnapshotRecord[] = [];
+  const pruned: ShellSnapshotRecord[] = [];
+  for (const record of snapshot) {
+    const keep =
+      (record.family === "segment" && record.key === docKey) ||
+      (record.family === "loader" && !navigationOnly);
+    (keep ? kept : pruned).push(record);
+  }
+  return { kept, pruned };
+}
+
+/**
+ * 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 const SHELL_ENTRY_HEAD_ALLOWANCE_BYTES: number = 512;
+
+const ENTRY_BYTE_ENCODER = new TextEncoder();
+
+/**
+ * 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 function estimateShellEntryBytes(parts: {
+  preludeBytes: number;
+  postponed: string | null | undefined;
+  snapshot: readonly ShellSnapshotRecord[] | undefined;
+  tags: readonly string[] | undefined;
+  docKey: string | undefined;
+  prunedRecords: string | undefined;
+}): number {
+  const head = ENTRY_BYTE_ENCODER.encode(
+    JSON.stringify({
+      po: parts.postponed,
+      t: parts.tags,
+      dk: parts.docKey,
+      pr: parts.prunedRecords,
+    }),
+  ).length;
+  const snapshot =
+    parts.snapshot && parts.snapshot.length > 0
+      ? ENTRY_BYTE_ENCODER.encode(JSON.stringify(parts.snapshot)).length
+      : 0;
+  return (
+    parts.preludeBytes + head + snapshot + SHELL_ENTRY_HEAD_ALLOWANCE_BYTES
+  );
+}
+
+/** Snapshot records by family, e.g. `segment:1/loader:2` (no commas: it rides a Server-Timing desc). */
+export function countSnapshotFamilies(
+  snapshot: readonly ShellSnapshotRecord[],
+): string {
+  const counts = new Map<string, number>();
+  for (const record of snapshot) {
+    counts.set(record.family, (counts.get(record.family) ?? 0) + 1);
+  }
+  return [...counts].map(([family, n]) => `${family}:${n}`).join("/");
+}
+
+/**
+ * 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 class SnapshotOnlySegmentStore<
   TEnv = unknown,
@@ -300,32 +351,38 @@ export class SnapshotOnlySegmentStore<
   }
 }
 
+/** 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: 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;
+  /**
+   * 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;
+}
+
 /**
  * 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.
+ * 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 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).
-   */
-  holes: boolean;
-}
-
 export async function buildShellLoaderSeed(
   snapshot: ShellSnapshotRecord[],
 ): Promise<Map<string, ShellLoaderSeedEntry> | undefined> {
@@ -345,9 +402,11 @@ export async function buildShellLoaderSeed(
             rec.key,
             {
               container: await deserializeResult(stored.value),
-              // A record without the bit (pre-bit snapshot) reads as
-              // hole-carrying: unknown hole-ness must keep the gated path.
+              // A record stored before the bits existed (v0.17) lacks the
+              // loader-owned pushes: it reads as hole-carrying and as runs,
+              // so the loader body supplies them.
               holes: stored.holes !== 0,
+              runs: stored.runs !== 0,
             },
           ];
         } catch {
@@ -364,50 +423,29 @@ export async function buildShellLoaderSeed(
 }
 
 /**
- * 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 class SeededShellStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
-  private readonly items: Map<string, ShellSnapshotItemValue> | undefined;
   private readonly segments = new Map<string, CachedEntryData>();
-  private readonly responses:
-    | Map<string, ShellSnapshotResponseValue>
-    | undefined;
-  private readonly segmentsOnly: boolean;
 
   constructor(
     private readonly inner: SegmentCacheStore<TEnv>,
-    snapshot: ShellSnapshotRecord[],
-    options?: { segmentsOnly?: boolean },
+    snapshot: readonly ShellSnapshotRecord[],
   ) {
-    this.segmentsOnly = options?.segmentsOnly === true;
-    this.items = this.segmentsOnly ? undefined : new Map();
-    this.responses = this.segmentsOnly ? undefined : new Map();
     for (const rec of snapshot) {
-      if (!rec || typeof rec !== "object") continue;
-      if (rec.family === "segment") {
+      if (rec && typeof rec === "object" && rec.family === "segment") {
         this.segments.set(rec.key, rec.value as CachedEntryData);
-      } else if (this.segmentsOnly) {
-        continue;
-      } else if (rec.family === "item") {
-        this.items?.set(rec.key, rec.value as ShellSnapshotItemValue);
-      } else if (rec.family === "response") {
-        this.responses?.set(rec.key, rec.value as ShellSnapshotResponseValue);
       }
-      // "loader" family records are not store reads — serveShellHit seeds them
-      // onto the tail context (_shellLoaderSeed) for the resolveLoaderData
-      // overlay instead.
     }
   }
 
@@ -417,100 +455,34 @@ export class SeededShellStore<
   get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
     return this.inner.keyGenerator;
   }
-  get supportsPassiveShellReads(): true | undefined {
-    return this.inner.supportsPassiveShellReads;
-  }
 
   async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     const seeded = this.segments.get(key);
-    if (seeded) return { data: seeded, shouldRevalidate: false };
-    if (this.segmentsOnly) return null;
-    return this.inner.get(key);
+    return seeded ? { data: seeded, shouldRevalidate: false } : null;
   }
 
-  async set(
-    key: string,
-    data: CachedEntryData,
-    ttl: number,
-    swr?: number,
-  ): Promise<void> {
-    if (this.segmentsOnly) {
-      this.segments.set(key, data);
-      return;
-    }
-    return this.inner.set(key, data, ttl, swr);
+  async set(key: string, data: CachedEntryData): Promise<void> {
+    this.segments.set(key, data);
   }
 
   async delete(key: string): Promise<boolean> {
-    if (this.segmentsOnly) {
-      return this.segments.delete(key);
-    }
-    return this.inner.delete(key);
-  }
-
-  async clear(): Promise<void> {
-    return this.inner.clear?.();
-  }
-
-  async getResponse(
-    key: string,
-  ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
-    const seeded = this.responses?.get(key);
-    if (seeded) {
-      return { response: deserializeResponse(seeded), shouldRevalidate: false };
-    }
-    return this.inner.getResponse ? this.inner.getResponse(key) : null;
-  }
-
-  async putResponse(
-    key: string,
-    response: Response,
-    ttl: number,
-    swr?: number,
-    tags?: string[],
-  ): Promise<void> {
-    return this.inner.putResponse?.(key, response, ttl, swr, tags);
-  }
-
-  async getItem(key: string): Promise<CacheItemResult | null> {
-    const seeded = this.items?.get(key);
-    if (seeded) {
-      return {
-        value: seeded.value,
-        handles: seeded.handles,
-        tags: seeded.tags,
-        shouldRevalidate: false,
-      };
-    }
-    return this.inner.getItem ? this.inner.getItem(key) : null;
-  }
-
-  async setItem(
-    key: string,
-    value: string,
-    options?: CacheItemOptions,
-  ): Promise<void> {
-    return this.inner.setItem?.(key, value, options);
-  }
-
-  async getShell(
-    key: string,
-    options?: { claimRevalidation?: boolean },
-  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    return this.inner.getShell ? this.inner.getShell(key, options) : null;
-  }
-
-  async putShell(
-    key: string,
-    entry: ShellCacheEntry,
-    ttlSeconds?: number,
-    swrSeconds?: number,
-    tags?: string[],
-  ): Promise<"stored" | "invalidated" | "uncacheable" | void> {
-    return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
+    return this.segments.delete(key);
   }
+}
 
-  async invalidateTags(tags: string[]): Promise<void> {
-    return this.inner.invalidateTags?.(tags);
+/**
+ * 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 class ShellRecordUnavailableError extends Error {
+  constructor(docKey: string | undefined) {
+    super(
+      `PPR shell HIT: the doc record${docKey ? ` "${docKey}"` : ""} could not supply the handler layer`,
+    );
+    this.name = "ShellRecordUnavailableError";
   }
 }