@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.148

package/src/rsc/shell-capture.ts

@@ -20,10 +20,13 @@ import React from "react";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
+import { enqueueSerializedCapture } from "./capture-queue.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
+  wireRenderBarrier,
   UNTRACKED_BACKGROUND_TASK,
   type RequestContext,
 } from "../server/request-context.js";
@@ -76,8 +79,12 @@ import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
  */
 const FLIGHT_QUIET_HOPS = 2;
 
-/** Default upper bound on the capture prerender wait before forcing the abort. */
-const SHELL_CAPTURE_MAX_WAIT_MS = 5000;
+/**
+ * Default upper bound on the capture prerender wait before forcing the abort.
+ * Single owner of the default budget — shell-build-manifest.ts imports it so
+ * the dev fetch bound's envelope math cannot drift from the capture.
+ */
+export const SHELL_CAPTURE_MAX_WAIT_MS = 5000;
 
 /**
  * Upper bound on waiting for the capture's DEFERRED cache writes to settle before
@@ -367,6 +374,254 @@ function warnUntaggedShellBakeOnce(key: string): void {
   );
 }
 
+/**
+ * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
+ * inside a shell entry, when the route's `ppr` option does not set
+ * `maxSnapshotBytes`. 8 MiB: the snapshot shares the stored envelope with the
+ * base64 prelude and the postponed blob, and the tightest store value limit is
+ * Cloudflare KV's 25 MiB — 8 MiB of snapshot leaves the envelope well under it
+ * while still fitting any sane pinned-ring payload. Applied ONLY in
+ * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
+ * the option through undefaulted), so every producer and direct caller gets
+ * the same policy. Over the cap the snapshot is skipped (shell still stored;
+ * pinned reads drift — see PartialPrerenderProps.maxSnapshotBytes).
+ */
+export const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number = 8 * 1024 * 1024;
+
+/** Cached encoder for the snapshot byte measurement (one per module, not per capture). */
+const SNAPSHOT_BYTE_ENCODER = new TextEncoder();
+
+/** Keys already warned about an over-cap snapshot (once per key per isolate). */
+const warnedOverCapSnapshots = new Set<string>();
+
+/**
+ * Warn once per key that the capture data snapshot exceeded the route's
+ * `maxSnapshotBytes` cap and was skipped. The shell entry is still stored and
+ * served — only the pinned-read replay is lost, so shell-baked cached content
+ * can drift from the frozen prelude between capture and HIT and hydration
+ * repairs it client-side (the pre-snapshot behavior). Once per key: the same
+ * page recaptures on every TTL roll and would otherwise re-warn forever.
+ */
+function warnSnapshotOverCapOnce(
+  key: string,
+  snapshotBytes: number,
+  capBytes: number,
+): void {
+  if (warnedOverCapSnapshots.has(key)) return;
+  warnedOverCapSnapshots.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" recorded a ${snapshotBytes}-byte data ` +
+      `snapshot, over the ${capBytes}-byte cap — the snapshot was skipped and ` +
+      "the shell was stored without it. The page keeps serving, but cached " +
+      "content baked into the shell is no longer pinned: if it drifts before " +
+      "the shell's TTL, hydration repairs the mismatch client-side. Raise the " +
+      "cap via the route's ppr option ({ maxSnapshotBytes }) if the entry " +
+      "still fits your store's value limit (Cloudflare KV: 25 MiB per value), " +
+      "or shrink the cache()'d data the shell bakes.",
+  );
+}
+
+/**
+ * One structured event from the background capture pipeline, mirroring the
+ * CFCacheReadDebugEvent pattern (cache/cf/cf-cache-types.ts): typed fields an
+ * operator can assert against, emitted per attempt and per skip, so the
+ * stored / no-shell / refused / backed-off lifecycle is observable outside
+ * dev console warnings. Configured via `createRouter({ debugShellCapture })`.
+ */
+export interface ShellCaptureDebugEvent {
+  /** Shell cache key the event is about. */
+  key: string;
+  /**
+   * What happened:
+   * - stored / redirect / no-shell / refused: one capture ATTEMPT's outcome
+   *   (see CaptureAttemptOutcome for the semantics of each)
+   * - error: the capture task failed with a genuine error (also routed through
+   *   reportCacheError; the key is backed off)
+   * - skip-in-flight: scheduleShellCapture found a capture already running for
+   *   the key (stampede guard) and scheduled nothing
+   * - skip-backoff: the key is inside its refused-capture backoff window and
+   *   the capture was not attempted
+   * - backoff: the key entered (or escalated) backoff after a terminal
+   *   no-shell — carries the new backoff state
+   */
+  outcome:
+    | "stored"
+    | "redirect"
+    | "no-shell"
+    | "refused"
+    | "error"
+    | "skip-in-flight"
+    | "skip-backoff"
+    | "backoff";
+  /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
+  attempt?: number;
+  /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
+  attemptMs?: number;
+  /**
+   * Wall-clock ms the pre-render WRITE BARRIER waited on the foreground
+   * request's deferred cache writes (bounded by SHELL_CAPTURE_WRITE_BARRIER_MS).
+   */
+  barrierWaitMs?: number;
+  /**
+   * Wall-clock ms spent awaiting the capture's own deferred cache writes
+   * before the snapshot drain (bounded by SHELL_SNAPSHOT_WRITE_SETTLE_MS).
+   */
+  writeSettleMs?: number;
+  /** Stored prelude size in bytes (pre-base64). */
+  preludeBytes?: number;
+  /** Serialized snapshot size in UTF-8 bytes. Absent when nothing was recorded. */
+  snapshotBytes?: number;
+  /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
+  snapshotSkipped?: boolean;
+  /** Consecutive failure count in the key's backoff entry, when one exists. */
+  backoffFailures?: number;
+  /** Ms remaining in the key's backoff window, when one exists. */
+  backoffRemainingMs?: number;
+}
+
+/**
+ * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
+ * logs each event to console (visible via `wrangler tail`), a function
+ * receives the events for programmatic capture. Off by default.
+ */
+export type ShellCaptureDebug =
+  | boolean
+  | ((event: ShellCaptureDebugEvent) => void);
+
+/**
+ * Compact single-line form of an event's fields, shared by the console sink
+ * and the dev Server-Timing mirror's `desc` (rsc-rendering). Plain
+ * alphanumerics/`=`/`-`/`()` only, so it needs no quoted-string escaping.
+ */
+export function describeShellCaptureEvent(
+  event: ShellCaptureDebugEvent,
+): string {
+  const parts: string[] = [event.outcome];
+  if (event.attempt !== undefined) parts.push(`attempt=${event.attempt}`);
+  if (event.attemptMs !== undefined) parts.push(`${event.attemptMs}ms`);
+  if (event.barrierWaitMs !== undefined) {
+    parts.push(`barrier=${event.barrierWaitMs}ms`);
+  }
+  if (event.writeSettleMs !== undefined) {
+    parts.push(`write-settle=${event.writeSettleMs}ms`);
+  }
+  if (event.preludeBytes !== undefined) {
+    parts.push(`prelude=${event.preludeBytes}b`);
+  }
+  if (event.snapshotBytes !== undefined) {
+    parts.push(
+      `snapshot=${event.snapshotBytes}b${event.snapshotSkipped ? " (over cap, skipped)" : ""}`,
+    );
+  }
+  if (event.backoffFailures !== undefined) {
+    parts.push(`backoff-failures=${event.backoffFailures}`);
+  }
+  if (event.backoffRemainingMs !== undefined) {
+    parts.push(`backoff-remaining=${event.backoffRemainingMs}ms`);
+  }
+  return parts.join(" ");
+}
+
+/** The `debugShellCapture: true` console sink: one compact line per event. */
+function consoleCaptureDebugSink(event: ShellCaptureDebugEvent): void {
+  console.log(
+    `[ShellCache][debug] ${event.key} ${describeShellCaptureEvent(event)}`,
+  );
+}
+
+/**
+ * Resolve the `debugShellCapture` router option to a callable sink, or
+ * undefined when off. The INTERNAL_RANGO_DEBUG env-flag fallback lives HERE
+ * (not at a call site) so every producer that resolves a sink inherits it;
+ * an explicit `false` wins over the env flag.
+ */
+export function resolveShellCaptureDebugSink(
+  option: ShellCaptureDebug | undefined,
+): ((event: ShellCaptureDebugEvent) => void) | undefined {
+  if (option === false) return undefined;
+  if (option === true) return consoleCaptureDebugSink;
+  if (typeof option === "function") return option;
+  return INTERNAL_RANGO_DEBUG ? consoleCaptureDebugSink : undefined;
+}
+
+/**
+ * Attempt-terminal outcomes recorded for the dev Server-Timing mirror. Skip
+ * events are excluded so a later request's skip cannot overwrite the
+ * interesting terminal event before a metrics-enabled request reads it.
+ */
+const TIMING_RECORDED_OUTCOMES = new Set<ShellCaptureDebugEvent["outcome"]>([
+  "stored",
+  "redirect",
+  "no-shell",
+  "refused",
+  "error",
+]);
+
+/**
+ * Dev-only last-terminal-event-per-key buffer backing the Server-Timing
+ * mirror: the capture runs AFTER its triggering response is committed, so its
+ * outcome can only ride a LATER response's header. rsc-rendering consumes this
+ * on the next ppr GET for the key when the metrics store is active
+ * (debugPerformance) and appends a `ppr:capture` Server-Timing entry. Dev-only
+ * (isDevMode) so production isolates never grow the map; FIFO-capped because
+ * with debugPerformance OFF nothing ever drains it, and a long dev session
+ * sweeping many URLs would otherwise accumulate one entry per shell key
+ * forever.
+ */
+const lastCaptureEventsForTiming = new Map<string, ShellCaptureDebugEvent>();
+const MAX_TIMING_EVENT_KEYS = 100;
+
+/**
+ * Consume (read-and-clear) the buffered terminal capture event for `key`, so
+ * one capture reports into exactly one later response's Server-Timing.
+ */
+export function takeCaptureDebugEventForTiming(
+  key: string,
+): ShellCaptureDebugEvent | undefined {
+  const event = lastCaptureEventsForTiming.get(key);
+  if (event) lastCaptureEventsForTiming.delete(key);
+  return event;
+}
+
+/**
+ * Publish one capture debug event: buffer terminal outcomes for the dev
+ * Server-Timing mirror, then hand the event to the configured sink. A
+ * throwing sink is swallowed — diagnostics must never fail a capture.
+ */
+function publishCaptureDebugEvent(
+  descriptor: Pick<ShellCaptureDescriptor, "debugSink">,
+  event: ShellCaptureDebugEvent,
+): void {
+  if (isDevMode() && TIMING_RECORDED_OUTCOMES.has(event.outcome)) {
+    // Refresh insertion order for the FIFO cap, then evict the oldest key.
+    lastCaptureEventsForTiming.delete(event.key);
+    if (lastCaptureEventsForTiming.size >= MAX_TIMING_EVENT_KEYS) {
+      const oldest = lastCaptureEventsForTiming.keys().next().value;
+      if (oldest !== undefined) lastCaptureEventsForTiming.delete(oldest);
+    }
+    lastCaptureEventsForTiming.set(event.key, event);
+  }
+  const sink = descriptor.debugSink;
+  if (!sink) return;
+  try {
+    sink(event);
+  } catch {
+    // Diagnostics only: a throwing consumer sink must never fail the capture.
+  }
+}
+
+/** Current backoff state fields for `key` (empty when no backoff entry). */
+function backoffFields(
+  key: string,
+): Pick<ShellCaptureDebugEvent, "backoffFailures" | "backoffRemainingMs"> {
+  const entry = refusedCaptures.get(key);
+  if (!entry) return {};
+  return {
+    backoffFailures: entry.failures,
+    backoffRemainingMs: Math.max(0, entry.until - Date.now()),
+  };
+}
+
 export interface FlightCaptureGate {
   /** Identity passthrough of the source stream; feed this to captureShellHTML. */
   stream: ReadableStream<Uint8Array>;
@@ -546,9 +801,32 @@ export interface ShellCaptureDescriptor {
   ttl?: number;
   swr?: number;
   tags?: string[];
+  /**
+   * Per-route capture settle budget in ms (`ppr.captureTimeout`, resolved by
+   * resolvePprConfig). Feeds captureShellHTML's maxWaitMs — the ONE deadline
+   * bounding the whole capture, so it covers BOTH the fizz prerender AND the
+   * deferred-material settle window (the handlesBaked/loader-container
+   * holdUntil that keeps the gate from freezing while top-level pushes are
+   * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (5000).
+   */
+  captureTimeout?: number;
   store?: SegmentCacheStore<any>;
   /** Gates the concise per-attempt capture breadcrumbs (INTERNAL_RANGO_DEBUG). */
   debug?: boolean;
+  /**
+   * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
+   * the snapshot is skipped and the shell stored without it (reported once per
+   * key). Absent = DEFAULT_PPR_MAX_SNAPSHOT_BYTES, applied in
+   * captureAndStoreShell — the single defaulting site.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Structured capture-pipeline debug sink, resolved from
+   * `createRouter({ debugShellCapture })` (or INTERNAL_RANGO_DEBUG) via
+   * {@link resolveShellCaptureDebugSink}. Receives one
+   * {@link ShellCaptureDebugEvent} per attempt/skip.
+   */
+  debugSink?: (event: ShellCaptureDebugEvent) => void;
 }
 
 /**
@@ -572,10 +850,20 @@ export function scheduleShellCapture(
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
-  if (inFlightCaptures.has(key)) return;
+  if (inFlightCaptures.has(key)) {
+    publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
+    return;
+  }
   // Refused/failed within the window → skip the doomed re-render (one probe per
   // key per window per isolate). Expired entries self-evict inside the check.
-  if (isCaptureBackedOff(key)) return;
+  if (isCaptureBackedOff(key)) {
+    publishCaptureDebugEvent(descriptor, {
+      key,
+      outcome: "skip-backoff",
+      ...backoffFields(key),
+    });
+    return;
+  }
   inFlightCaptures.add(key);
   const captureTask = async () => {
     try {
@@ -593,25 +881,43 @@ export function scheduleShellCapture(
       // off so the next requests don't re-probe it. A `redirect` has no shell but
       // is not a doomed render — leave the backoff untouched.
       if (outcome === "stored") clearCaptureBackoff(key);
-      else if (outcome === "no-shell") markCaptureBackoff(key);
+      else if (outcome === "no-shell") {
+        markCaptureBackoff(key);
+        publishCaptureDebugEvent(descriptor, {
+          key,
+          outcome: "backoff",
+          ...backoffFields(key),
+        });
+      }
     } catch (error) {
       // Detached background task — pass reqCtx so onError still fires when the ALS
       // context is gone. A genuine failure recurs, so back it off too (re-probe
       // once per window, not every request) and report it once.
       markCaptureBackoff(key);
+      publishCaptureDebugEvent(descriptor, {
+        key,
+        outcome: "error",
+        ...backoffFields(key),
+      });
       reportCacheError(error, "cache-write", "[ShellCache] capture", reqCtx);
     } finally {
       inFlightCaptures.delete(key);
     }
   };
+  // Serialize capture EXECUTION per isolate (capture-queue.ts): concurrent
+  // captures starve each other's task-quantized quiet windows — one grinding
+  // capture makes the sibling freeze a trivial prelude and store nothing
+  // (rotating eternal-MISS victims on GH runners). The stampede guard above
+  // stays per-key (dedupe while queued); the queue is cross-key.
+  const serializedTask = () => enqueueSerializedCapture(captureTask);
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),
   // and awaiting its own still-running promise would burn the whole barrier
   // deadline on every capture.
-  (captureTask as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
+  (serializedTask as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
     UNTRACKED_BACKGROUND_TASK
   ] = true;
-  runBackground(reqCtx, captureTask);
+  runBackground(reqCtx, serializedTask);
 }
 
 /**
@@ -625,6 +931,21 @@ export function scheduleShellCapture(
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
+/**
+ * Per-attempt observability fields, filled along the capture path (barrier in
+ * attemptCapture, the rest in captureAndStoreShell) and folded into the
+ * attempt's {@link ShellCaptureDebugEvent} by runShellCapture. A plain mutable
+ * bag, not a return value: captureAndStoreShell's outcome type stays a string
+ * union its existing callers (producer B, tests) consume unchanged.
+ */
+interface CaptureAttemptStats {
+  barrierWaitMs?: number;
+  writeSettleMs?: number;
+  preludeBytes?: number;
+  snapshotBytes?: number;
+  snapshotSkipped?: boolean;
+}
+
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -657,15 +978,37 @@ async function runShellCapture(
     ? (message: string) => console.log(message)
     : () => {};
 
-  const first = await attemptCapture(
-    ctx,
-    request,
-    env,
-    url,
-    reqCtx,
-    ssrModule,
-    descriptor,
-  );
+  // One attempt + its structured debug event: the stats object rides through
+  // attemptCapture/captureAndStoreShell collecting the observability fields
+  // (barrier wait, write-settle wait, prelude/snapshot bytes), and the event
+  // folds them with the outcome. A genuine render error skips the attempt
+  // event — scheduleShellCapture's catch publishes the terminal `error` event.
+  const timedAttempt = async (
+    attempt: number,
+  ): Promise<CaptureAttemptOutcome> => {
+    const stats: CaptureAttemptStats = {};
+    const start = performance.now();
+    const outcome = await attemptCapture(
+      ctx,
+      request,
+      env,
+      url,
+      reqCtx,
+      ssrModule,
+      descriptor,
+      stats,
+    );
+    publishCaptureDebugEvent(descriptor, {
+      key: descriptor.key,
+      outcome,
+      attempt,
+      attemptMs: Math.round(performance.now() - start),
+      ...stats,
+    });
+    return outcome;
+  };
+
+  const first = await timedAttempt(1);
   // "refused" is deterministic (identity guard / rejected bake-lane loader —
   // its own warning already fired): no retry, and the caller backs the key off
   // exactly like a structural no-shell.
@@ -682,15 +1025,7 @@ async function runShellCapture(
     `[ShellCache] capture attempt 1/2 for ${descriptor.key} aborted before shell completed (cold modules?) — retrying`,
   );
   await delay(retryDelayMs);
-  const second = await attemptCapture(
-    ctx,
-    request,
-    env,
-    url,
-    reqCtx,
-    ssrModule,
-    descriptor,
-  );
+  const second = await timedAttempt(2);
   if (second === "refused") return "no-shell";
   if (second !== "no-shell") return second;
 
@@ -737,6 +1072,9 @@ function handlerLayerIsLive(
  *   - _shellCaptureRun: true — the switch loaders/cookies/headers guards read.
  *   - _metricsStore: undefined so the capture never appends to the foreground's
  *     (already-finalized) metrics.
+ *   - _renderBarrier family: an own barrier wired to the fresh handle store
+ *     (wireRenderBarrier), plus _treeHasStreaming/deadlock-guard resets — the
+ *     capture's rendered() lifecycle is its own, not the foreground's.
  *
  * The capture is MIXED-CHAIN: its match() behaves like a normal render with
  * respect to the segment cache — cache()'d segments replay from ring 3, UNCACHED
@@ -756,6 +1094,7 @@ async function attemptCapture(
   reqCtx: RequestContext<any>,
   ssrModule: SSRModule,
   descriptor: ShellCaptureDescriptor,
+  stats: CaptureAttemptStats,
 ): Promise<CaptureAttemptOutcome> {
   // WRITE BARRIER (ordering edge, not a narrower race): settle the foreground's
   // already-scheduled background tasks — its deferred ring-3/ring-1 cache writes —
@@ -766,8 +1105,79 @@ async function attemptCapture(
   // skipped, cache-store middleware's write path gated off by state.cacheHit), so
   // prelude, snapshot, and ring-3 agree on the foreground's generation. Runs per
   // attempt (the retry re-checks; already-settled promises are free).
+  const barrierStart = performance.now();
   await settleTrackedBackgroundTasks(reqCtx, SHELL_CAPTURE_WRITE_BARRIER_MS);
+  stats.barrierWaitMs = Math.round(performance.now() - barrierStart);
+
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
+    reqCtx,
+    descriptor,
+  );
+
+  return runWithRequestContext(derivedCtx, async () => {
+    const match = await ctx.router.match(request, { env });
+    // A route that redirects has no shell to capture — bail (no store write, no
+    // retry: a redirect is deterministic).
+    if (match.redirect) return "redirect";
+
+    setRequestContextParams(match.params, match.routeName);
 
+    const payload = buildFullPayload(
+      match,
+      ctx,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+
+    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
+    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
+    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
+    // content (and tags propagated by async cache()/"use cache" reads) lands after
+    // this synchronous construction point, so snapshotting here dropped it — the
+    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
+    return captureAndStoreShell(
+      ssrModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+      stats,
+    );
+  });
+}
+
+/**
+ * The derived capture context and its fresh (mask-funneled) handle store,
+ * shared by BOTH shell producers: the runtime background capture
+ * (attemptCapture, producer A) and the build-time prerender shell capture
+ * (prerender/build-shell-capture.ts, producer B — issue #699). One
+ * implementation so the capture semantics — the nested-thenable mask funnel,
+ * handler-liveness bookkeeping, snapshot recording, the implicit doc-cache
+ * scope — cannot drift between producers.
+ */
+export interface CaptureContextDerivation {
+  derivedCtx: RequestContext;
+  freshHandleStore: HandleStore;
+}
+
+/**
+ * Derive the capture request context from a base context. Producer A passes
+ * the foreground request's post-middleware context (the derived context
+ * inherits its variables/env/cookie machinery through the prototype);
+ * producer B passes a synthetic build-request context created by
+ * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
+ * as `_cacheStore` so the recording/snapshot machinery arms identically.
+ */
+export function deriveShellCaptureContext(
+  reqCtx: RequestContext<any>,
+  descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">,
+): CaptureContextDerivation {
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
   // Shape = liveness for handles, exactly as for bake-lane loader containers
@@ -839,6 +1249,15 @@ async function attemptCapture(
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
   derivedCtx._handleStore = freshHandleStore;
+  // Own render barrier, closure-bound to the derived ctx and the fresh store
+  // (issue #684, plan 009). Without this every _renderBarrier* read fell
+  // through the prototype to the foreground's ALREADY-RESOLVED barrier: a
+  // bake-lane loader's `await ctx.rendered()` resolved instantly and
+  // ctx.use(handle) read the FOREGROUND handle snapshot — foreground
+  // per-request handle data could bake into the shared shell. wireRenderBarrier
+  // also resets _treeHasStreaming (recomputed for the capture's tree) and the
+  // deadlock-guard fields as own properties.
+  wireRenderBarrier(derivedCtx, freshHandleStore);
   derivedCtx._shellCaptureLoaderHandleValues = loaderScopedPushValues;
   derivedCtx._requestTags = new Set<string>();
   // Own explicit-store registry: cache-store resolutions during the capture
@@ -904,41 +1323,7 @@ async function attemptCapture(
     };
   }
 
-  return runWithRequestContext(derivedCtx, async () => {
-    const match = await ctx.router.match(request, { env });
-    // A route that redirects has no shell to capture — bail (no store write, no
-    // retry: a redirect is deterministic).
-    if (match.redirect) return "redirect";
-
-    setRequestContextParams(match.params, match.routeName);
-
-    const payload = buildFullPayload(
-      match,
-      ctx,
-      url,
-      derivedCtx,
-      freshHandleStore,
-    );
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
-      },
-    });
-
-    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
-    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
-    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
-    // content (and tags propagated by async cache()/"use cache" reads) lands after
-    // this synchronous construction point, so snapshotting here dropped it — the
-    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
-    return captureAndStoreShell(
-      ssrModule,
-      rscStream,
-      freshHandleStore,
-      derivedCtx,
-      descriptor,
-    );
-  });
+  return { derivedCtx, freshHandleStore };
 }
 
 /**
@@ -960,6 +1345,7 @@ async function captureAndStoreShell(
   handleStore: HandleStore,
   reqCtx: RequestContext<any>,
   capture: ShellCaptureDescriptor,
+  stats?: CaptureAttemptStats,
 ): Promise<Exclude<CaptureAttemptOutcome, "redirect">> {
   const captureShellHTML = ssrModule.captureShellHTML!;
 
@@ -1048,10 +1434,12 @@ async function captureAndStoreShell(
     // captureShellHTML CONSUMES the (gated) stream — it is not also SSR'd.
     let result: Awaited<ReturnType<typeof captureShellHTML>>;
     try {
+      // One deadline for the whole capture — semantics spec'd on the option
+      // (PartialPrerenderProps.captureTimeout, urls/pattern-types.ts).
       result = await observePhase(PHASES.ssr, () =>
         captureShellHTML(gate.stream, {
           quiesce,
-          maxWaitMs: SHELL_CAPTURE_MAX_WAIT_MS,
+          maxWaitMs: capture.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS,
         }),
       );
     } catch (error) {
@@ -1087,6 +1475,7 @@ async function captureAndStoreShell(
     if (result === null) {
       return "no-shell";
     }
+    if (stats) stats.preludeBytes = result.prelude.length;
 
     // Store per the flag's key/ttl/swr/tags, into the flag's store: the middleware
     // threads the SAME store it resolved for its getShell read (options.store ??
@@ -1126,7 +1515,11 @@ async function captureAndStoreShell(
     const recording = getRecordingStore(reqCtx._cacheStore);
     let snapshot: ShellSnapshotRecord[] | undefined;
     if (recording) {
+      const settleStart = performance.now();
       await recording.settleWrites(SHELL_SNAPSHOT_WRITE_SETTLE_MS);
+      if (stats) {
+        stats.writeSettleMs = Math.round(performance.now() - settleStart);
+      }
       snapshot = recording.drainSnapshot();
     }
 
@@ -1185,6 +1578,29 @@ async function captureAndStoreShell(
       }
     }
 
+    // Snapshot size guard (issue #651): the snapshot duplicates every pinned
+    // cache value inside the shell entry, so a page over a large cache()
+    // segment can push the stored envelope toward store value limits (KV caps
+    // a value at 25 MiB) with no signal — the kv.put rejects deep inside
+    // waitUntil. Measure the serialized snapshot (UTF-8 bytes of the JSON that
+    // rides in the envelope) AFTER the loader family is appended, and over the
+    // cap store the shell WITHOUT it: pinned reads then fall back to the live
+    // store on a HIT (documented drift — hydration repairs a mismatch
+    // client-side, the pre-snapshot behavior), which beats losing the whole
+    // entry to a store-side write rejection. Reported once per key.
+    if (snapshot && snapshot.length > 0) {
+      const snapshotBytes = SNAPSHOT_BYTE_ENCODER.encode(
+        JSON.stringify(snapshot),
+      ).length;
+      if (stats) stats.snapshotBytes = snapshotBytes;
+      const cap = capture.maxSnapshotBytes ?? DEFAULT_PPR_MAX_SNAPSHOT_BYTES;
+      if (snapshotBytes > cap) {
+        warnSnapshotOverCapOnce(capture.key, snapshotBytes, cap);
+        snapshot = undefined;
+        if (stats) stats.snapshotSkipped = true;
+      }
+    }
+
     // Shell tags snapshot at the WRITE BARRIER, not at stream construction: by
     // here the capture has quiesced and the deferred cache writes were awaited, so
     // tags recorded AFTER an await in async shell content (and by async
@@ -1262,8 +1678,15 @@ async function captureAndStoreShell(
   }
 }
 
-// Exported for unit tests that drive the capture core directly.
-export { runShellCapture, captureAndStoreShell };
+// Exported for unit tests that drive the capture core directly, and — with the
+// cold-graph retry pieces — for producer B (prerender/build-shell-capture.ts),
+// which mirrors the runtime capture's retry-in-place with the same delay.
+export {
+  runShellCapture,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+};
 
 // Exported for unit tests that pin the refused-capture backoff policy directly
 // (dev cap vs production exponential growth, stored-clears, cold-start re-probe).