@rangojs/router 0.0.0-experimental.150 → 0.0.0-experimental.151

package/src/rsc/progressive-enhancement.ts

@@ -18,9 +18,14 @@ import { gateTransitions } from "./transition-gate.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
+  RSC_RENDER_HTML_RESPONSE_PHASES,
   createResponseWithMergedHeaders,
   finalizeResponse,
   buildRouteMiddlewareEntries,
+  createRscRenderStages,
+  finishRscRenderStages,
+  observeRscHtmlStage,
+  readRscFlightStage,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 import {
@@ -327,11 +332,31 @@ export async function handleProgressiveEnhancement<TEnv>(
       },
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
+    const stageTracking = {
+      mode: "progressive-enhancement" as const,
+      routeKey: getRequestContext()._routeName,
+      actionId: directActionId ?? undefined,
+      phases: RSC_RENDER_HTML_RESPONSE_PHASES,
+    };
+    const renderStages = createRscRenderStages({
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      init: {
+        // boundarylessErrorStatus is set only when the action threw and no error
+        // boundary matched; it makes the re-render carry 500 like the JS path.
+        // The redirect branch above returns before this, so a redirect re-render
+        // keeps its 308 and is never overridden.
+        ...(boundarylessErrorStatus !== undefined
+          ? { status: boundarylessErrorStatus }
+          : {}),
+        headers: { "content-type": "text/html;charset=utf-8" },
       },
+      tracking: stageTracking,
     });
+    const flightStage = await readRscFlightStage(renderStages);
     // metricsStore=undefined is safe: the handler already stashed the early
     // SSR setup promise on request variables, so getSSRSetup returns it
     // without falling back to a fresh startSSRSetup.
@@ -344,21 +369,18 @@ export async function handleProgressiveEnhancement<TEnv>(
     );
     // reactFormState carries the useActionState payload via the SSR-option path
     // (renderToReadableStream({ formState })); it does NOT travel on RscPayload.
-    const htmlStream = await ssrModule.renderHTML(rscStream, {
-      formState: reactFormState,
-      nonce,
-      streamMode,
-    });
+    const htmlStream = await observeRscHtmlStage(
+      { url, tracking: stageTracking },
+      () =>
+        ssrModule.renderHTML(flightStage.stream, {
+          formState: reactFormState,
+          nonce,
+          streamMode,
+        }),
+    );
 
-    return createResponseWithMergedHeaders(htmlStream, {
-      // boundarylessErrorStatus is set only when the action threw and no error
-      // boundary matched; it makes the re-render carry 500 like the JS path.
-      // The redirect branch above returns before this, so a redirect re-render
-      // keeps its 308 and is never overridden.
-      ...(boundarylessErrorStatus !== undefined
-        ? { status: boundarylessErrorStatus }
-        : {}),
-      headers: { "content-type": "text/html;charset=utf-8" },
+    return finishRscRenderStages(renderStages, {
+      body: htmlStream,
     });
   };
 
@@ -475,11 +497,25 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-    onError: (error: unknown) => {
-      ctx.callOnError(error, "rendering", { request, url, env });
+  const stageTracking = {
+    mode: "progressive-enhancement-error" as const,
+    routeKey: getRequestContext()._routeName,
+    actionId: actionId ?? undefined,
+    phases: RSC_RENDER_HTML_RESPONSE_PHASES,
+  };
+  const renderStages = createRscRenderStages({
+    ctx,
+    request,
+    env,
+    url,
+    payload,
+    init: {
+      status: 500,
+      headers: { "content-type": "text/html;charset=utf-8" },
     },
+    tracking: stageTracking,
   });
+  const flightStage = await readRscFlightStage(renderStages);
   // metricsStore=undefined is safe: the handler already stashed the early
   // SSR setup promise on request variables, so getSSRSetup returns it
   // without falling back to a fresh startSSRSetup.
@@ -490,13 +526,16 @@ async function renderPeErrorBoundary<TEnv>(
     url,
     undefined,
   );
-  const htmlStream = await ssrModule.renderHTML(rscStream, {
-    nonce,
-    streamMode,
-  });
+  const htmlStream = await observeRscHtmlStage(
+    { url, tracking: stageTracking },
+    () =>
+      ssrModule.renderHTML(flightStage.stream, {
+        nonce,
+        streamMode,
+      }),
+  );
 
-  return createResponseWithMergedHeaders(htmlStream, {
-    status: 500,
-    headers: { "content-type": "text/html;charset=utf-8" },
+  return finishRscRenderStages(renderStages, {
+    body: htmlStream,
   });
 }

package/src/rsc/rsc-rendering.ts

@@ -22,9 +22,18 @@ import type { RscPayload } from "./types.js";
 import type { SSRModule } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 import {
+  RSC_FLIGHT_ONLY_PHASES,
+  RSC_RENDER_FLIGHT_RESPONSE_PHASES,
+  RSC_RENDER_HTML_RESPONSE_PHASES,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
   attachLocationStateIfPresent,
+  createRscRenderStages,
+  finishRscRenderStages,
+  observeRscHtmlStage,
+  readRscFlightStage,
+  renderRscFlightStage,
+  runRscRenderStages,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 import { gateTransitions } from "./transition-gate.js";
@@ -124,7 +133,8 @@ async function handleRscRenderingInner<TEnv>(
     !isPartial &&
     request.method === "GET" &&
     !url.searchParams.has("__prerender_collect") &&
-    !isRscRequest(request, url, false)
+    !isRscRequest(request, url, false) &&
+    !reqCtx._dynamic
   ) {
     const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
     if (pprConfig) {
@@ -428,54 +438,60 @@ async function handleRscRenderingInner<TEnv>(
 
   const metricsStore = reqCtx._metricsStore;
 
-  // Serialize to RSC stream
-  const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-    onError: (error: unknown) => {
-      ctx.callOnError(error, "rendering", { request, url, env });
+  const rscHeaders: Record<string, string> = {
+    "content-type": "text/x-component;charset=utf-8",
+    vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+    // Router identity, so the client can verify pre-decode (before importing
+    // chunks) that this content payload belongs to its app and refuse a
+    // foreign one (cache/proxy/bug). Control-only reload/redirect responses
+    // are deliberately NOT stamped. See browser/response-adapter.ts.
+    "X-RSC-Router-Id": ctx.router.id,
+  };
+  // Tell the client's prefetch cache to scope this response to its source
+  // URL (instead of the default source-agnostic wildcard). Intercept
+  // responses depend on the source page matching an intercept rule, so
+  // they must not be reused for navigations from other sources.
+  if (hasInterceptSlots) {
+    rscHeaders["x-rsc-prefetch-scope"] = "source";
+  }
+  // Enable browser HTTP caching for prefetch responses only.
+  // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
+  // non-intercept context (intercept responses depend on source page),
+  // and a configured cache-control value (false disables caching).
+  const isPrefetch = request.headers.has("X-Rango-Prefetch");
+  if (isPrefetch && isPartial && !hasInterceptSlots) {
+    const cc = ctx.router.prefetchCacheControl;
+    if (cc) {
+      rscHeaders["cache-control"] = cc;
+    }
+  }
+
+  const isFlightResponse = isRscRequest(request, url, isPartial);
+  const stageTracking = {
+    mode: isPartial ? ("partial" as const) : ("full" as const),
+    routeKey: reqCtx._routeName,
+    phases: isFlightResponse
+      ? RSC_RENDER_FLIGHT_RESPONSE_PHASES
+      : RSC_RENDER_HTML_RESPONSE_PHASES,
+  };
+  const renderStages = createRscRenderStages({
+    ctx,
+    request,
+    env,
+    url,
+    payload,
+    init: {
+      headers: rscHeaders,
     },
+    tracking: stageTracking,
   });
-  const rscSerializeDur = performance.now() - rscSerializeStart;
-  // This measures synchronous stream creation, not end-to-end stream consumption.
-  appendMetric(
-    metricsStore,
-    "rsc-serialize",
-    rscSerializeStart,
-    rscSerializeDur,
-  );
 
-  if (isRscRequest(request, url, isPartial)) {
+  const flightStage = await readRscFlightStage(renderStages);
+  const rscStream = flightStage.stream;
+
+  if (isFlightResponse) {
     // render:total is recorded by the observePhase wrapper around this function.
-    const rscHeaders: Record<string, string> = {
-      "content-type": "text/x-component;charset=utf-8",
-      vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
-      // Router identity, so the client can verify pre-decode (before importing
-      // chunks) that this content payload belongs to its app and refuse a
-      // foreign one (cache/proxy/bug). Control-only reload/redirect responses
-      // are deliberately NOT stamped. See browser/response-adapter.ts.
-      "X-RSC-Router-Id": ctx.router.id,
-    };
-    // Tell the client's prefetch cache to scope this response to its source
-    // URL (instead of the default source-agnostic wildcard). Intercept
-    // responses depend on the source page matching an intercept rule, so
-    // they must not be reused for navigations from other sources.
-    if (hasInterceptSlots) {
-      rscHeaders["x-rsc-prefetch-scope"] = "source";
-    }
-    // Enable browser HTTP caching for prefetch responses only.
-    // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
-    // non-intercept context (intercept responses depend on source page),
-    // and a configured cache-control value (false disables caching).
-    const isPrefetch = request.headers.has("X-Rango-Prefetch");
-    if (isPrefetch && isPartial && !hasInterceptSlots) {
-      const cc = ctx.router.prefetchCacheControl;
-      if (cc) {
-        rscHeaders["cache-control"] = cc;
-      }
-    }
-    return createResponseWithMergedHeaders(rscStream, {
-      headers: rscHeaders,
-    });
+    return runRscRenderStages(renderStages);
   }
 
   // Delegate to SSR for HTML response (reuse early setup if available)
@@ -489,14 +505,21 @@ async function handleRscRenderingInner<TEnv>(
 
   // ssr-render-html metric + rango.ssr span from one boundary. render:total is
   // recorded by the observePhase wrapper around this function.
-  const htmlStream = await observePhase(PHASES.ssr, () =>
-    ssrModule.renderHTML(rscStream, {
-      nonce,
-      streamMode,
-    }),
+  const htmlStream = await observeRscHtmlStage(
+    { url, tracking: stageTracking },
+    () =>
+      observePhase(PHASES.ssr, () =>
+        ssrModule.renderHTML(rscStream, {
+          nonce,
+          streamMode,
+        }),
+      ),
   );
-  const response = createResponseWithMergedHeaders(htmlStream, {
-    headers: { "content-type": "text/html;charset=utf-8" },
+  const response = await finishRscRenderStages(renderStages, {
+    body: htmlStream,
+    init: {
+      headers: { "content-type": "text/html;charset=utf-8" },
+    },
   });
 
   // --- Axis 2: PPR shell CAPTURE on MISS (background task; see design doc) ---
@@ -507,7 +530,7 @@ async function handleRscRenderingInner<TEnv>(
   // page via router.match() under a derived context (fresh handle store,
   // _shellCaptureRun: true) — middleware never re-runs; it already ran for this
   // request and guarding is serve-time.
-  if (pprMiss) {
+  if (pprMiss && !reqCtx._dynamic) {
     if (
       response.status === 200 &&
       (response.headers.get("content-type") ?? "").includes("text/html")
@@ -611,11 +634,22 @@ function serveShellHit(
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
-    let rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
+    const flightStage = renderRscFlightStage(
+      {
+        ctx,
+        request,
+        env,
+        url,
+        payload,
+        tracking: {
+          mode: "full",
+          routeKey: activeCtx._routeName,
+          phases: RSC_FLIGHT_ONLY_PHASES,
+        },
       },
-    });
+      performance.now(),
+    );
+    let rscStream = flightStage.stream;
     // Timing tap: when does the Flight render produce its FIRST byte? Compared
     // with the eager-inject/first-tail logs this proves whether hydration-start
     // latency is genuine server work (loaders) or stream plumbing holding

package/src/rsc/server-action.ts

@@ -19,7 +19,6 @@ import {
   getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
-import { appendMetric } from "../router/metrics.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { gateTransitions } from "./transition-gate.js";
 import type { RscPayload } from "./types.js";
@@ -29,6 +28,8 @@ import {
   createSimpleRedirectResponse,
   interceptRedirectForPartial,
   attachLocationStateIfPresent,
+  createRscRenderStages,
+  runRscRenderStages,
 } from "./helpers.js";
 import { warnNonRedirectActionResponse } from "./runtime-warnings.js";
 import type { HandlerContext } from "./handler-context.js";
@@ -362,8 +363,6 @@ async function revalidateAfterActionInner<TEnv>(
     errorBoundary,
   } = continuation;
   const reqCtx = getRequestContext();
-  const metricsStore = reqCtx._metricsStore;
-
   // Expose the action that triggered this revalidation to the transition({ when })
   // gate (covers both the error-boundary and success gate calls below). Mirrors
   // the action fields a revalidate() predicate sees.
@@ -412,29 +411,30 @@ async function revalidateAfterActionInner<TEnv>(
     // is a success-only semantic. Error boundary responses update the error UI
     // but should not mutate browser history state.
 
-    const errorStart = performance.now();
-    const errorStream = ctx.renderToReadableStream<RscPayload>(errorPayload, {
-      temporaryReferences,
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
-      },
-    });
-    appendMetric(
-      metricsStore,
-      "rsc-serialize",
-      errorStart,
-      performance.now() - errorStart,
+    return runRscRenderStages(
+      createRscRenderStages({
+        ctx,
+        request,
+        env,
+        url,
+        payload: errorPayload,
+        temporaryReferences,
+        init: {
+          status: actionStatus,
+          headers: {
+            "content-type": "text/x-component;charset=utf-8",
+            // Router identity for the client's pre-decode integrity check (the
+            // action apply path has no post-decode guard). See response-adapter.
+            "X-RSC-Router-Id": ctx.router.id,
+          },
+        },
+        tracking: {
+          mode: "action-revalidation",
+          routeKey: reqCtx._routeName,
+          actionId: actionContext?.actionId,
+        },
+      }),
     );
-
-    return createResponseWithMergedHeaders(errorStream, {
-      status: actionStatus,
-      headers: {
-        "content-type": "text/x-component;charset=utf-8",
-        // Router identity for the client's pre-decode integrity check (the
-        // action apply path has no post-decode guard). See response-adapter.
-        "X-RSC-Router-Id": ctx.router.id,
-      },
-    });
   }
 
   const matchResult = await ctx.router.matchPartial(
@@ -498,25 +498,28 @@ async function revalidateAfterActionInner<TEnv>(
 
   attachLocationStateIfPresent(payload);
 
-  const renderStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-    temporaryReferences,
-    onError: (error: unknown) => {
-      ctx.callOnError(error, "rendering", { request, url, env });
-    },
-  });
-  const rscSerializeDur = performance.now() - renderStart;
-  // This measures synchronous stream creation, not end-to-end stream consumption.
-  // render:total is recorded by the observePhase wrapper in revalidateAfterAction.
-  appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
-
-  return createResponseWithMergedHeaders(rscStream, {
-    status: actionStatus,
-    headers: {
-      "content-type": "text/x-component;charset=utf-8",
-      // Router identity for the client's pre-decode integrity check (the action
-      // apply path has no post-decode guard). See response-adapter.
-      "X-RSC-Router-Id": ctx.router.id,
-    },
-  });
+  return runRscRenderStages(
+    createRscRenderStages({
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      temporaryReferences,
+      init: {
+        status: actionStatus,
+        headers: {
+          "content-type": "text/x-component;charset=utf-8",
+          // Router identity for the client's pre-decode integrity check (the
+          // action apply path has no post-decode guard). See response-adapter.
+          "X-RSC-Router-Id": ctx.router.id,
+        },
+      },
+      tracking: {
+        mode: "action-revalidation",
+        routeKey: reqCtx._routeName,
+        actionId: actionContext?.actionId,
+      },
+    }),
+  );
 }

package/src/rsc/shell-build-manifest.ts

@@ -146,6 +146,32 @@ export interface DevShellLookup {
 /** Retry delay (~400ms) plus quiesce/fizz/store headroom past the budgets. */
 const DEV_SHELL_RETRY_MARGIN_MS = 5_000;
 
+/**
+ * Dev boot-race readiness (issue #719). The `/__rsc_shell` endpoint stands up
+ * the capture realm lazily on its first hit — the temp server (Cloudflare
+ * preset), the registry import, and, on either preset, a Vite dependency
+ * re-optimization that the first import of the shell-capture graph can trigger.
+ * All three are TRANSIENT: retrying the same request seconds later succeeds.
+ *
+ * Before this, the read-through fired ONCE and mapped any non-2xx to a hard
+ * MISS, so a Prerender+ppr route's FIRST request lost the race and served
+ * axis-1 (x-rango-shell: MISS) while a later poll HIT — the build-time
+ * first-request-HIT contract held only after a warm-up. A fast machine loses
+ * the race deterministically (the document request beats the boot infra);
+ * slow CI arrives after it settled, hence "0-flake on CI".
+ *
+ * Fix: the endpoint tags the transient not-ready branches with
+ * `x-rango-shell-dev: NOT-READY` (HTTP 503), and the read-through re-polls
+ * ONLY that signal — a bounded await of readiness, not a blind retry. A
+ * genuine negative (route not prerenderable, capture refused: 404) stays an
+ * immediate MISS, so a non-baked route never stalls the foreground. The window
+ * is capped by DEV_SHELL_READINESS_DEADLINE_MS; the boot infra normally
+ * settles well inside the first poll.
+ */
+const DEV_SHELL_NOT_READY = "NOT-READY";
+const DEV_SHELL_READINESS_DEADLINE_MS = 10_000;
+const DEV_SHELL_READINESS_POLL_MS = 150;
+
 /**
  * Timed out like the dev prerender store fetch (see #697): inside a workerd
  * waitUntil an unsettled fetch pends forever instead of rejecting; on timeout
@@ -192,14 +218,30 @@ async function fetchDevShellEntry(
   if (dev.captureTimeout !== undefined) {
     params.set("captureTimeout", String(dev.captureTimeout));
   }
-  try {
-    const res = await fetch(`${devUrl}/__rsc_shell?${params}`, {
-      signal: AbortSignal.timeout(devShellFetchTimeoutMs(dev.captureTimeout)),
-    });
-    if (!res.ok) return undefined;
-    return (await res.json()) as BuildShellEntry;
-  } catch {
-    return undefined;
+  const shellUrl = `${devUrl}/__rsc_shell?${params}`;
+  // Await the endpoint's boot readiness (issue #719): re-poll ONLY the
+  // NOT-READY signal, capped by DEV_SHELL_READINESS_DEADLINE_MS. Every other
+  // outcome — a served entry, a genuine negative (404), or a network fault —
+  // resolves on the first attempt, so a non-baked route never stalls here.
+  const readinessDeadline = Date.now() + DEV_SHELL_READINESS_DEADLINE_MS;
+  for (;;) {
+    try {
+      const res = await fetch(shellUrl, {
+        signal: AbortSignal.timeout(devShellFetchTimeoutMs(dev.captureTimeout)),
+      });
+      if (
+        res.status === 503 &&
+        res.headers.get("x-rango-shell-dev") === DEV_SHELL_NOT_READY &&
+        Date.now() < readinessDeadline
+      ) {
+        await new Promise((r) => setTimeout(r, DEV_SHELL_READINESS_POLL_MS));
+        continue;
+      }
+      if (!res.ok) return undefined;
+      return (await res.json()) as BuildShellEntry;
+    } catch {
+      return undefined;
+    }
   }
 }
 

package/src/rsc/shell-capture.ts

@@ -53,9 +53,10 @@ import {
   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 { RSC_FLIGHT_ONLY_PHASES, renderRscFlightStage } from "./helpers.js";
 
 /**
  * Task-quantized quiesce: the number of consecutive macrotask hops with zero new
@@ -1131,11 +1132,21 @@ async function attemptCapture(
       derivedCtx,
       freshHandleStore,
     );
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
+    const flightStage = renderRscFlightStage(
+      {
+        ctx,
+        request,
+        env,
+        url,
+        payload,
+        tracking: {
+          mode: "full",
+          routeKey: derivedCtx._routeName,
+          phases: RSC_FLIGHT_ONLY_PHASES,
+        },
       },
-    });
+      performance.now(),
+    );
 
     // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
     // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
@@ -1145,7 +1156,7 @@ async function attemptCapture(
     // shell-tag snapshot must sit behind the quiesce gate (issue #676).
     return captureAndStoreShell(
       ssrModule,
-      rscStream,
+      flightStage.stream,
       freshHandleStore,
       derivedCtx,
       descriptor,

package/src/server/context.ts

@@ -817,9 +817,14 @@ const loaderBodyScopeALS: AsyncLocalStorage<{
  */
 export function isInsideCacheScope(): boolean {
   if (RangoContext.getStore()?.insideCacheScope !== true) return false;
-  // Loaders are always fresh — even inside a cache() boundary, the loader
-  // function re-executes on every request (DSL loaders AND handler-invoked
-  // loader bodies alike), so request-scoped reads inside any loader are safe.
+  // Request-scoped READS are exempt in any loader body — DSL loaders re-run on
+  // every request (including cache() HITs via resolveLoadersOnly), and a
+  // handler-invoked loader body, though skipped with its handler on a HIT,
+  // yields a BAKED shared copy in the cached artifact — an accepted
+  // consumption-lane tradeoff (#672/#674). This is deliberately BROADER than
+  // the WRITE guard (assertCachedHeaderWriteAllowed narrows the cache()
+  // exemption to DSL scope, #725): a read bakes-and-accepts, a Set-Cookie/header
+  // write drops-and-throws because it has no baked-copy semantics on a HIT.
   if (isInsideAnyLoaderScope()) return false;
   return true;
 }
@@ -901,8 +906,11 @@ export function latchPprHeaderScopeForEntries(
 /**
  * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
  * headers — handler and loader writes throw while a scope is latched; the one
- * exemption is loaders under plain cache(). Full layer rules and rationale:
- * docs/design/ppr-shell-resume.md "The header doctrine".
+ * exemption is DSL (registered) loaders under plain cache(). A handler-invoked
+ * loader body (ctx.use from a handler, never registered with loader()) is
+ * skipped with its handler on a HIT and throws like a handler write (#725).
+ * Full layer rules and rationale: docs/design/ppr-shell-resume.md "The header
+ * doctrine".
  */
 export function assertCachedHeaderWriteAllowed(
   surface: string,
@@ -910,21 +918,37 @@ export function assertCachedHeaderWriteAllowed(
 ): void {
   const scope = RangoContext.getStore()?.cachedHeaderScope;
   if (!scope) return;
-  const insideLoader = isInsideAnyLoaderScope();
-  if (scope.kind === "cache" && insideLoader) return;
+  // Exempt DSL loaders (loaderScopeALS) ONLY. A registered loader re-runs on
+  // every cache HIT (fresh.ts runInsideLoaderScope -> cache-lookup.ts
+  // resolveLoadersOnly), so its header/cookie writes merge into every response
+  // with no MISS/HIT divergence. A handler-invoked loader body has
+  // loaderBodyScopeALS active but loaderScopeALS unset (loader-resolution.ts
+  // derives isDslLoader from isInsideLoaderScope()); on a HIT the handler is
+  // skipped so that loader never re-runs and its write would land only on the
+  // MISS — throw it. isInsideLoaderScope() (not isInsideAnyLoaderScope) is the
+  // discriminator; the DSL scope ALS survives nested ctx.use bodies, so a
+  // handler-invoked loader nested under a DSL loader stays exempt (its DSL
+  // parent re-invokes it on every HIT). This is the exempt fast path, so the
+  // broad predicate for the error label is deferred to the throw path below.
+  if (scope.kind === "cache" && isInsideLoaderScope()) return;
   // Everything below runs only on the throw path — `surfaceProp` exists so
   // callers pass constants and the success path allocates nothing (the full
-  // surface, e.g. "ctx.headers.set()", is assembled here).
+  // surface, e.g. "ctx.headers.set()", is assembled here). isInsideAnyLoaderScope
+  // (broad) labels a now-throwing handler-invoked loader body "loader".
   const fullSurface =
     surfaceProp === undefined ? surface : `${surface}.${String(surfaceProp)}()`;
-  const layer = insideLoader ? "loader" : "handler";
+  const layer = isInsideAnyLoaderScope() ? "loader" : "handler";
   const route = scope.routeKey ? ` (route "${scope.routeKey}")` : "";
   const where =
     scope.kind === "ppr"
       ? `on a ppr route${route} — the document shell is cached and replayed`
       : `inside a cache() boundary${route}`;
+  // ppr loader writes fail by physics (headers flush before loaders settle);
+  // every other throw — a handler, or a handler-invoked loader under cache() —
+  // fails because the handler is skipped on a HIT, so key the reason on the
+  // scope kind, not the layer.
   const why =
-    layer === "loader"
+    scope.kind === "ppr" && layer === "loader"
       ? "The response headers flush with the shell before loaders settle, so this write is dropped on cache hits."
       : "On a cache hit the handler is skipped, so this write would silently vanish.";
   throw new Error(