@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/src/rsc/shell-capture.ts

@@ -20,15 +20,23 @@ 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 { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.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";
 import { createHandleStore, type HandleStore } from "../server/handle-store.js";
-import { maskNestedContainerThenables } from "../router/segment-resolution/mask-nested.js";
+import {
+  maskNestedContainerThenables,
+  type MaskReport,
+} from "../router/segment-resolution/mask-nested.js";
+import { isInsideLoaderScope } from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import type {
   ShellCacheEntry,
@@ -41,12 +49,14 @@ import {
 } from "../router/segment-resolution/loader-snapshot.js";
 import {
   RecordingShellStore,
+  SnapshotOnlySegmentStore,
   getRecordingStore,
 } from "../cache/shell-snapshot.js";
 import type { HandlerContext } from "./handler-context.js";
-import type { RscPayload, SSRModule } from "./types.js";
+import type { SSRModule } from "./types.js";
 import { buildFullPayload } from "./full-payload.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
+import { renderRscFlightStage } from "./render-pipeline.js";
 
 /**
  * Task-quantized quiesce: the number of consecutive macrotask hops with zero new
@@ -71,8 +81,13 @@ 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 capture budget. Canonical value, raise rationale, and ceiling math
+ * live on the leaf module (shell-capture-constants.ts, importable from the ssr
+ * graph too). Re-exported here so shell-build-manifest.ts's envelope math
+ * keeps its existing import site and cannot drift from the capture.
+ */
+export { SHELL_CAPTURE_MAX_WAIT_MS };
 
 /**
  * Upper bound on waiting for the capture's DEFERRED cache writes to settle before
@@ -362,6 +377,259 @@ 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;
+  /** Outcome reported by a store that supports shell-write acknowledgements. */
+  storeWrite?: "stored" | "invalidated";
+  /** 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.storeWrite !== undefined) {
+    parts.push(`store-write=${event.storeWrite}`);
+  }
+  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>;
@@ -541,9 +809,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 (15_000).
+   */
+  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;
 }
 
 /**
@@ -567,10 +858,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 {
@@ -588,25 +889,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);
 }
 
 /**
@@ -620,6 +939,23 @@ 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.
+ */
+type CaptureAttemptStats = Pick<
+  ShellCaptureDebugEvent,
+  | "barrierWaitMs"
+  | "writeSettleMs"
+  | "preludeBytes"
+  | "snapshotBytes"
+  | "snapshotSkipped"
+  | "storeWrite"
+>;
+
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -652,15 +988,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.
@@ -677,15 +1035,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;
 
@@ -701,6 +1051,18 @@ async function runShellCapture(
   return "no-shell";
 }
 
+/** Fold the capture's handle-liveness record into the entry flag (true | undefined). */
+function handlerLayerIsLive(
+  liveness: RequestContext["_shellCaptureHandleLiveness"],
+): true | undefined {
+  if (!liveness) return undefined;
+  return liveness.holes ||
+    liveness.pendingPushes > 0 ||
+    liveness.handlerInvokedLoader
+    ? true
+    : undefined;
+}
+
 /**
  * One capture attempt in a DERIVED request context.
  *
@@ -720,6 +1082,9 @@ async function runShellCapture(
  *   - _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
@@ -739,6 +1104,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 —
@@ -749,8 +1115,87 @@ 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,
+  );
+  const captureStartedAt = Date.now();
+
+  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 flightStage = renderRscFlightStage({
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      tracking: {
+        mode: "full",
+        routeKey: derivedCtx._routeName,
+      },
+    });
+
+    // 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,
+      flightStage.stream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+      stats,
+      captureStartedAt,
+    );
+  });
+}
+
+/**
+ * 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
@@ -764,21 +1209,83 @@ async function attemptCapture(
   // the store exists only for this capture attempt, so every push wrapper
   // (setupLoaderAccess, createUseFunction, prerender) inherits the policy and
   // the foreground store is untouched.
+  // Shell fast path bookkeeping on the same funnel:
+  //  - handleLiveness: a nested thenable in a push made OUTSIDE a DSL loader
+  //    scope (attribution read synchronously at push time — handler bodies,
+  //    handler-invoked ctx.use(loader) callbacks, defers) declares
+  //    handler-layer per-request data. Its mask is a hole only a handler
+  //    re-run can fill, so the entry must not serve handler-free
+  //    (ShellCacheEntry.handlerLiveHoles). Still-pending top-level handler
+  //    pushes at the putShell barrier count too — their liveness is unknowable.
+  //  - loaderScopedPushValues: DSL-loader pushes re-run fresh on every HIT, so
+  //    their captured values must NOT enter a segment record's handle snapshot
+  //    (replay would duplicate the fresh push, and their masked nested
+  //    promises would stall the Flight handle encode to its timeout). The set
+  //    rides the derived context (_shellCaptureLoaderHandleValues) and is
+  //    applied ONLY at the captureHandles cache-write call site — every other
+  //    getDataForSegment consumer (the render-barrier snapshot, prerender)
+  //    sees every push.
+  const handleLiveness = {
+    holes: false,
+    pendingPushes: 0,
+    handlerInvokedLoader: false,
+  };
+  const loaderScopedPushValues = new WeakSet<object>();
   const rawCapturePush = freshHandleStore.push.bind(freshHandleStore);
   freshHandleStore.push = (
     handleName: string,
     segmentId: string,
     value: unknown,
   ) => {
-    const masked = isThenable(value)
-      ? value.then((v: unknown) => maskNestedContainerThenables(v))
-      : maskNestedContainerThenables(value);
+    const pushedInLoaderScope = isInsideLoaderScope();
+    // Single walk: the mask reports whether it masked any nested thenable
+    // (the liveness declaration) while building the capture copy.
+    const maskWithLiveness = (v: unknown): unknown => {
+      const report: MaskReport = { thenable: false };
+      const masked = maskNestedContainerThenables(v, undefined, report);
+      if (!pushedInLoaderScope && report.thenable) {
+        handleLiveness.holes = true;
+      }
+      return masked;
+    };
+    let masked: unknown;
+    if (isThenable(value)) {
+      if (!pushedInLoaderScope) {
+        handleLiveness.pendingPushes++;
+        const settle = () => handleLiveness.pendingPushes--;
+        value.then(settle, settle);
+      }
+      masked = value.then(maskWithLiveness);
+    } else {
+      masked = maskWithLiveness(value);
+    }
+    if (pushedInLoaderScope && typeof masked === "object" && masked !== null) {
+      loaderScopedPushValues.add(masked);
+    }
     rawCapturePush(handleName, segmentId, masked);
   };
 
   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
+  // (the implicit scope's SnapshotOnlySegmentStore, any per-capture explicit
+  // store instance) must NOT register into the handler-lifetime
+  // _explicitTaggedStores set — a capture-ephemeral store pinned there would
+  // trip the partial-tag-store warning on every later updateTag() and retain
+  // the whole capture snapshot in memory. Capture registrations die with this
+  // context; module-singleton stores stay registered by normal renders.
+  derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
   derivedCtx._metricsStore = undefined;
@@ -812,6 +1319,7 @@ async function attemptCapture(
   // forwarding to the parent so the write persists and the worker stays alive),
   // then captureAndStoreShell awaits them before draining. Reads that HIT are
   // recorded synchronously during the render and need none of this.
+  derivedCtx._shellCaptureHandleLiveness = handleLiveness;
   if (reqCtx._cacheStore) {
     const recordingStore = new RecordingShellStore(reqCtx._cacheStore);
     derivedCtx._cacheStore = recordingStore;
@@ -820,43 +1328,21 @@ async function attemptCapture(
       recordingStore.trackWrite(p);
       reqCtx.waitUntil(() => p);
     };
+    // Shell fast path (capture side): the implicit doc-cache scope makes the
+    // capture's match write ALL matched non-loader segments as one doc-keyed
+    // segment record — into the snapshot only (SnapshotOnlySegmentStore), so
+    // the record dies with the shell entry and the next capture's lookup
+    // still misses (handlers re-run on recapture). Routes deriving their own
+    // cache scope are untouched (resolveShellImplicitCacheScope).
+    derivedCtx._shellImplicitCache = {
+      ttl: descriptor.ttl,
+      swr: descriptor.swr,
+      store: new SnapshotOnlySegmentStore(recordingStore),
+      keyPrefix: "doc",
+    };
   }
 
-  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 };
 }
 
 /**
@@ -878,6 +1364,8 @@ async function captureAndStoreShell(
   handleStore: HandleStore,
   reqCtx: RequestContext<any>,
   capture: ShellCaptureDescriptor,
+  stats?: CaptureAttemptStats,
+  captureStartedAt: number = Date.now(),
 ): Promise<Exclude<CaptureAttemptOutcome, "redirect">> {
   const captureShellHTML = ssrModule.captureShellHTML!;
 
@@ -966,10 +1454,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) {
@@ -1005,6 +1495,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 ??
@@ -1044,7 +1535,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();
     }
 
@@ -1093,7 +1588,11 @@ async function captureAndStoreShell(
             (snapshot ??= []).push({
               family: "loader",
               key: segmentKey,
-              value: { value: serialized },
+              // The hole bit rides with the record so the HIT overlay knows
+              // without rescanning whether the pin can resolve immediately
+              // (holes: 0) or must wait for the fresh run's live promises
+              // (holes: 1). See ShellSnapshotLoaderValue.
+              value: { value: serialized, holes: elided.hasHole ? 1 : 0 },
             });
           }
         } catch {
@@ -1103,6 +1602,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
@@ -1142,15 +1664,34 @@ async function captureAndStoreShell(
           // ShellCacheEntry.initialTheme.
           initialTheme: reqCtx.theme,
           snapshot,
-          createdAt: Date.now(),
+          // Handler-layer liveness folded at the barrier: nested thenables in
+          // handler-scoped pushes, handler pushes still pending (liveness
+          // unknowable), or a handler-invoked loader execution — any of them
+          // refuses the FAST PATH, not the capture. See
+          // _shellCaptureHandleLiveness.
+          handlerLiveHoles: handlerLayerIsLive(
+            reqCtx._shellCaptureHandleLiveness,
+          ),
+          transitionWhen: reqCtx._transitionWhen?.length ? true : undefined,
+          createdAt: captureStartedAt,
         };
-        await store.putShell(
+        const storeWrite = await store.putShell(
           capture.key,
           entry,
           capture.ttl,
           capture.swr,
           shellTags,
         );
+        if (stats && storeWrite) stats.storeWrite = storeWrite;
+        if (storeWrite === "invalidated") {
+          warnCaptureRefusedOnce(
+            capture.key,
+            "one of the shell's tags was invalidated after this capture generation started, so the store rejected the write. " +
+              "If capture code deterministically calls updateTag() on its own shell tag, move that mutation out of the render; " +
+              "otherwise every generation is invalidated before it can be served.",
+          );
+          return "refused";
+        }
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.
         reportCacheError(
@@ -1161,8 +1702,9 @@ async function captureAndStoreShell(
         );
       }
     }
-    // A shell was captured (the store I/O may have failed, but that is reported,
-    // not retried) — so this attempt is `stored` and the caller does not retry.
+    // A shell was captured (ordinary store I/O failure is reported, not retried).
+    // An acknowledged invalidation rejection returned `refused` above so the
+    // scheduler backs the key off instead of recapturing on every request.
     return "stored";
   } finally {
     // Stop the hop loop for the pathological never-quiets path (quiesce never
@@ -1172,8 +1714,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).