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

package/dist/vite/index.js

@@ -2520,7 +2520,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.149",
+  version: "0.0.0-experimental.150",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4673,6 +4673,21 @@ import { pathToFileURL as pathToFileURL2 } from "node:url";
 
 // src/rsc/shell-serve.ts
 import React from "react";
+
+// src/server/context.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var RSC_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:rsc-context");
+var RangoContext = globalThis[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage();
+var LOADER_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-scope");
+var loaderScopeALS = globalThis[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage();
+var LOADER_BODY_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-body-scope");
+var loaderBodyScopeALS = globalThis[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage();
+var PUSH_CALLBACK_SCOPE_KEY = /* @__PURE__ */ Symbol.for(
+  "rangojs-router:push-callback-scope"
+);
+var pushCallbackScopeALS = globalThis[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage();
+
+// src/rsc/shell-serve.ts
 var DEV_SHELL_PROBE_TIMEOUT_MS = 1e4;
 function normalizeCaptureTimeout(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 1 ? value : void 0;
@@ -4997,13 +5012,13 @@ function checkSelfGenWrite(state, filePath, consume) {
 }
 
 // src/router/logging.ts
-import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
 // src/internal-debug.ts
 var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
 
 // src/router/logging.ts
-var routerLogContext = new AsyncLocalStorage();
+var routerLogContext = new AsyncLocalStorage2();
 
 // src/router/url-params.ts
 var PATH_SAFE_ESCAPES = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.149",
+  "version": "0.0.0-experimental.150",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/ppr/SKILL.md

@@ -318,8 +318,19 @@ The lane is decided PER TREE NODE, at the entry that REGISTERS the loaders —
 `loading()` on a CHILD route does not change a parent layout's lane, and
 `loading()` IS valid on layout and parallel entries, not just routes.
 
-Three hard edges (each e2e/unit-pinned):
-
+Four hard edges (each e2e/unit-pinned):
+
+- **Header writes throw (issue #713).** ppr is a document-scoped `cache()`:
+  in any cached scenario ONLY MIDDLEWARE writes response headers. A handler
+  or loader on a ppr route calling `ctx.headers.set()`, `cookies().set()`,
+  `ctx.header()`, `ctx.setTheme()`, or `setStatus()` throws on EVERY render —
+  dev and prod,
+  first render, same guard family as the `cache()` boundary guard. Handlers
+  are replayed on HITs (the write would silently differ between MISS and
+  HIT); loaders are live but settle AFTER the response headers flushed with
+  the shell (dead letters). Move the write into route middleware — it runs
+  on every request, including HITs, and its headers/cookies merge into every
+  response.
 - **Identity refuses.** `cookies()`/`headers()` inside a bake-lane loader
   throws during capture and the capture REFUSES (deterministic, once-per-key
   warned) — identity can never bake into the shared shell. Give that loader's

package/src/router/handler-context.ts

@@ -14,7 +14,10 @@ import {
   isNonCacheable,
   type ContextSetOptions,
 } from "../context-var.js";
-import { isInsideCacheScope } from "../server/context.js";
+import {
+  assertCachedHeaderWriteAllowed,
+  isInsideCacheScope,
+} from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
@@ -214,7 +217,9 @@ export function createHandlerContext<TEnv>(
   const stubResponse =
     requestContext?.res ?? new Response(null, { status: 200 });
 
-  // Guard mutating Headers methods so they throw inside "use cache" or cache() scope.
+  // Guard mutating Headers methods so they throw inside "use cache" scope or
+  // cached header-write territory (cache() boundary / ppr route render —
+  // assertCachedHeaderWriteAllowed, the unified #713 guard).
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
   // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
@@ -226,13 +231,7 @@ export function createHandlerContext<TEnv>(
         if (MUTATING_HEADERS_METHODS.has(prop as string)) {
           return (...args: any[]) => {
             assertNotInsideCacheExec(ctx, "headers");
-            if (isInsideCacheScope()) {
-              throw new Error(
-                `ctx.headers.${String(prop)}() cannot be called inside a cache() boundary. ` +
-                  `On cache hit the handler is skipped, so this side effect would be lost. ` +
-                  `Move header mutations to a middleware or layout outside the cache() scope.`,
-              );
-            }
+            assertCachedHeaderWriteAllowed("ctx.headers", prop);
             return value.apply(target, args);
           };
         }

package/src/router/intercept-resolution.ts

@@ -28,7 +28,32 @@ import {
 } from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
-import { runInsideLoaderScope } from "../server/context.js";
+import {
+  RangoContext,
+  latchPprHeaderScopeForEntries,
+  runInsideLoaderScope,
+} from "../server/context.js";
+
+/**
+ * Header-guard latch for the intercept funnels (issue #713). ppr and
+ * intercepts do not compose on the shell path — shells are captured/served
+ * only for document requests and withInterceptResolution skips intercepts on
+ * full matches — so this is defense in depth: a partial nav CAN render an
+ * intercept over a ppr-declared target route, in its own store scope where
+ * the main funnel's latch does not apply. Latch by declaration, off the
+ * target route's manifest entry (same leaf input as the segment funnels).
+ * Called AFTER intercept middleware runs — middleware stays the live lane.
+ */
+function latchPprHeaderScopeForInterceptTarget(
+  interceptEntry: InterceptEntry,
+): void {
+  const targetEntry = RangoContext.getStore()?.manifest.get(
+    interceptEntry.routeName,
+  );
+  if (targetEntry) {
+    latchPprHeaderScopeForEntries([targetEntry], interceptEntry.routeName);
+  }
+}
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -150,6 +175,8 @@ export async function resolveInterceptEntry<TEnv>(
     if (middlewareResponse) throw middlewareResponse;
   }
 
+  latchPprHeaderScopeForInterceptTarget(interceptEntry);
+
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 
@@ -328,6 +355,8 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     return null;
   }
 
+  latchPprHeaderScopeForInterceptTarget(interceptEntry);
+
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 

package/src/router/segment-resolution/fresh.ts

@@ -40,6 +40,8 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
@@ -650,6 +652,12 @@ export async function resolveAllSegments<TEnv>(
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // ppr routes are document-scoped cached territory: the whole chain (root
+  // layout down to the page) bakes into the shared shell, so the header-write
+  // guard latches BEFORE any entry resolves (unlike the positional cache()
+  // latch below). See assertCachedHeaderWriteAllowed (server/context.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   // Safe request access: during build-time prerendering, context.request
   // is a throwing getter. Use undefined when unavailable.
   let safeRequest: Request | undefined;
@@ -665,11 +673,13 @@ export async function resolveAllSegments<TEnv>(
 
   for (const entry of entries) {
     // Set ALS flag when entering a cache() boundary so that ctx.get()
-    // can guard non-cacheable variable reads. Also guards response-level
-    // side effects (headers.set). Persists for all descendant entries.
+    // can guard non-cacheable variable reads. Also latch the header-write
+    // scope (response-level side effects — headers/cookies/status).
+    // Persists for all descendant entries.
     if (entry.type === "cache") {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
@@ -718,6 +728,15 @@ export async function resolveLoadersOnly<TEnv>(
   const loaderSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // Loader-only serves (cached non-loader segments) still run loaders live —
+  // on a ppr route their header writes are dead letters (headers flushed with
+  // the shell), so the guard latches here too. cache() needs no latch: loader
+  // writes are exempt under cache() (see assertCachedHeaderWriteAllowed).
+  latchPprHeaderScopeForEntries(
+    entries,
+    (context as InternalHandlerContext<any, TEnv>)._routeName,
+  );
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,

package/src/router/segment-resolution/revalidation.ts

@@ -50,6 +50,8 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
 /**
@@ -250,6 +252,9 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
   const allMatchedIds: string[] = [];
   const seenIds = new Set<string>();
 
+  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,
@@ -1260,6 +1265,9 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   const seenSegIds = new Set<string>();
   const seenMatchIds = new Set<string>();
 
+  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   const telemetry = getRouterContext()?.telemetry;
 
   for (const entry of entries) {
@@ -1283,6 +1291,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     if (entry.type === "cache") {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(

package/src/rsc/shell-serve.ts

@@ -17,7 +17,7 @@
  */
 
 import React from "react";
-import type { EntryData } from "../server/context.js";
+import { isPprEntry, type EntryData } from "../server/context.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 
@@ -90,9 +90,10 @@ export function normalizeCaptureTimeout(value: unknown): number | undefined {
 export function resolvePprConfig(
   entry: EntryData | undefined | null,
 ): ResolvedPprConfig | null {
-  if (!entry || entry.type !== "route") return null;
+  // isPprEntry (server/context.ts) is the ONE opt-in predicate — shared with
+  // the header-write latch so serve and guard can never drift.
+  if (!entry || !isPprEntry(entry)) return null;
   const ppr = entry.ppr;
-  if (ppr === undefined || ppr === false) return null;
   if (ppr === true) return { ttl: DEFAULT_PPR_TTL_SECONDS };
   return {
     ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,

package/src/server/context.ts

@@ -277,6 +277,17 @@ export interface TrackedInclude {
   lazy: boolean;
 }
 
+/**
+ * Cached response-header write scope (issue #713). `kind` selects the error
+ * wording; `routeKey` names the route in the error.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type CachedHeaderScope = {
+  kind: "cache" | "ppr";
+  routeKey?: string;
+};
+
 /**
  * Context stored in AsyncLocalStorage
  */
@@ -317,6 +328,13 @@ interface HelperContext {
   /** True when resolving handlers inside a cache() DSL boundary.
    *  Read by ctx.get() to guard non-cacheable variable reads. */
   insideCacheScope?: boolean;
+  /**
+   * RULE (issue #713): in any cached scenario ONLY MIDDLEWARE writes response
+   * headers. Latched by the segment funnels, consulted by
+   * assertCachedHeaderWriteAllowed(); full doctrine in
+   * docs/design/ppr-shell-resume.md "The header doctrine".
+   */
+  cachedHeaderScope?: CachedHeaderScope;
   /**
    * Include scope string applied to direct-descendant shortCodes.
    *
@@ -484,6 +502,9 @@ export const getContext = (): {
           trackedIncludes: store.trackedIncludes,
           cacheProfiles: store.cacheProfiles,
           includeScope: store.includeScope,
+          // cachedHeaderScope (and insideCacheScope) deliberately NOT copied —
+          // the header guard's middleware exemption depends on the latch dying
+          // with the funnel scope (see assertCachedHeaderWriteAllowed).
         },
         callback,
       );
@@ -797,13 +818,9 @@ 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. Skip the guard when running
-  // inside a loader.
-  if (loaderScopeALS.getStore()?.active) return false;
-  // Also exempt handler-invoked loaders: their bodies run in a loader-body
-  // scope (not the DSL loader scope above), so request-scoped reads inside any
-  // loader — however invoked — are safe (loaders always re-run fresh).
-  if (loaderBodyScopeALS.getStore()?.active) return false;
+  // function re-executes on every request (DSL loaders AND handler-invoked
+  // loader bodies alike), so request-scoped reads inside any loader are safe.
+  if (isInsideAnyLoaderScope()) return false;
   return true;
 }
 
@@ -816,6 +833,107 @@ export function isInsideLoaderScope(): boolean {
   return loaderScopeALS.getStore()?.active === true;
 }
 
+/**
+ * Latch the cached header-write scope for the current request. First latch
+ * wins: a ppr route latched at the funnel top is not downgraded by a nested
+ * cache() entry (the document-scoped wording is the more useful one).
+ * Takes scalars so the already-latched path allocates nothing.
+ */
+export function latchCachedHeaderScope(
+  kind: CachedHeaderScope["kind"],
+  routeKey?: string,
+): void {
+  const store = RangoContext.getStore();
+  if (store && !store.cachedHeaderScope) {
+    store.cachedHeaderScope = { kind, routeKey };
+  }
+}
+
+/** True inside ANY loader execution — DSL loader scope or a loader body
+ *  (however invoked). The "loaders always re-run fresh" exemptions key off
+ *  this. */
+function isInsideAnyLoaderScope(): boolean {
+  return (
+    loaderScopeALS.getStore()?.active === true ||
+    loaderBodyScopeALS.getStore()?.active === true
+  );
+}
+
+/**
+ * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
+ * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
+ * the two layers can never drift on what counts as a ppr route.
+ */
+export function isPprEntry(entry: EntryData): entry is EntryData & {
+  type: "route";
+  ppr: true | import("../urls/pattern-types.js").PartialPrerenderProps;
+} {
+  return (
+    entry.type === "route" && entry.ppr !== undefined && entry.ppr !== false
+  );
+}
+
+/**
+ * Latch the ppr header-write scope when the entry chain about to resolve is a
+ * `ppr` page route's. Called at the TOP of every segment funnel — unlike
+ * cache() (positional: ancestors before the boundary stay writable), ppr is
+ * document-scoped: the root layout down to the page bakes into the shared
+ * shell, so the whole funnel is cached territory.
+ *
+ * Checks the LEAF entry only: `entries` is the traverseBack chain
+ * [root, ..., manifestEntry], and the serve path reads `ppr` off the same
+ * leaf (rsc-rendering.ts: resolvePprConfig(manifestEntry)) — guard and serve
+ * share the predicate (isPprEntry) AND the input, so they cannot drift.
+ */
+export function latchPprHeaderScopeForEntries(
+  entries: EntryData[],
+  routeKey?: string,
+): void {
+  const store = RangoContext.getStore();
+  if (!store || store.cachedHeaderScope) return;
+  const leaf = entries[entries.length - 1];
+  if (leaf !== undefined && isPprEntry(leaf)) {
+    store.cachedHeaderScope = { kind: "ppr", routeKey };
+  }
+}
+
+/**
+ * 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".
+ */
+export function assertCachedHeaderWriteAllowed(
+  surface: string,
+  surfaceProp?: string | symbol,
+): void {
+  const scope = RangoContext.getStore()?.cachedHeaderScope;
+  if (!scope) return;
+  const insideLoader = isInsideAnyLoaderScope();
+  if (scope.kind === "cache" && insideLoader) 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).
+  const fullSurface =
+    surfaceProp === undefined ? surface : `${surface}.${String(surfaceProp)}()`;
+  const layer = insideLoader ? "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}`;
+  const why =
+    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(
+    `${fullSurface} cannot be called from a ${layer} ${where}. ${why} ` +
+      "Set response headers in route middleware instead — middleware runs " +
+      "on every request, including cache hits.",
+  );
+}
+
 /**
  * Run `fn` inside a loader scope. While active, cache-scope guards
  * are bypassed because loaders are always fresh (never cached) and

package/src/server/request-context.ts

@@ -57,7 +57,10 @@ import {
 } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
-import { isInsideCacheScope } from "./context.js";
+import {
+  assertCachedHeaderWriteAllowed,
+  isInsideCacheScope,
+} from "./context.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -817,6 +820,50 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
+  // The #713 choke point: `rawStubHeaders` is the stub's REAL Headers; the
+  // proxy below is the only view reachable from consumer code, and its
+  // mutating methods consult the cached-scope guard first. shadowStubHeaders
+  // shadows `headers` on the stub Response INSTANCE (a real Response, not a
+  // facade — safe to hand to the platform), so every surface that ends in a
+  // stub-header mutation — ctx.header/setCookie/deleteCookie, ctx.setTheme,
+  // the handler ctx.headers proxy, and raw `ctx.res.headers.set(...)` — is
+  // guarded at the mutation itself, not per enumerated wrapper. Guard-exempt
+  // internal writers (_rotateStateCookie, _setKeepCacheDirective — serve
+  // machinery, documented callable from loaders/during capture) write to
+  // rawStubHeaders directly. The serve/commit path's stub reads and its
+  // Set-Cookie drain (rsc/helpers.ts) run outside any latched funnel scope,
+  // where assertCachedHeaderWriteAllowed is a no-op.
+  let rawStubHeaders = stubResponse.headers;
+  const guardedStubHeaders: Headers = new Proxy(new Headers(), {
+    get(_target, prop) {
+      const raw = rawStubHeaders;
+      const value = Reflect.get(raw, prop) as unknown;
+      if (typeof value !== "function") return value;
+      if (prop === "set" || prop === "append" || prop === "delete") {
+        return (...args: unknown[]) => {
+          assertCachedHeaderWriteAllowed("response headers", prop);
+          return (value as (...a: unknown[]) => unknown).apply(raw, args);
+        };
+      }
+      return (value as (...a: unknown[]) => unknown).bind(raw);
+    },
+  });
+  const shadowStubHeaders = (res: Response): void => {
+    Object.defineProperty(res, "headers", {
+      value: guardedStubHeaders,
+      enumerable: true,
+      configurable: true,
+    });
+  };
+  shadowStubHeaders(stubResponse);
+  // Rebuild the stub with a new status, re-shadowing the fresh instance
+  // (the Response constructor copies rawStubHeaders into new raw Headers).
+  const replaceStubStatus = (status: number): void => {
+    stubResponse = new Response(null, { status, headers: rawStubHeaders });
+    rawStubHeaders = stubResponse.headers;
+    shadowStubHeaders(stubResponse);
+  };
+
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
 
@@ -838,14 +885,12 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
-  function assertNotInsideCacheScopeALS(methodName: string): void {
-    if (isInsideCacheScope()) {
-      throw new Error(
-        `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
-          `On cache hit the handler is skipped, so this side effect would be lost. ` +
-          `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
-      );
-    }
+  // Guard for the two response-write surfaces that are NOT Headers mutations
+  // (setStatus rebuilds the stub Response, onResponse registers a callback) —
+  // these can't ride the guarded-headers choke point above, so they stay
+  // enumerated. Same unified #713 guard, same message family.
+  function assertResponseWriteAllowed(methodName: string): void {
+    assertCachedHeaderWriteAllowed("ctx", methodName);
   }
 
   // Response stub Set-Cookie wins, then original header (source of truth for mutations).
@@ -956,7 +1001,6 @@ export function createRequestContext<TEnv>(
 
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
-      assertNotInsideCacheScopeALS("setCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, value, options),
@@ -969,7 +1013,6 @@ export function createRequestContext<TEnv>(
       options?: Pick<CookieOptions, "domain" | "path">,
     ): void {
       assertNotInsideCacheExec(ctx, "deleteCookie");
-      assertNotInsideCacheScopeALS("deleteCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, "", { ...options, maxAge: 0 }),
@@ -979,7 +1022,6 @@ export function createRequestContext<TEnv>(
 
     header(name: string, value: string): void {
       assertNotInsideCacheExec(ctx, "header");
-      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
@@ -1008,7 +1050,9 @@ export function createRequestContext<TEnv>(
         (request.headers.get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
       const value = mintStateValue(stateVersion ?? "0", prevRaw);
-      stubResponse.headers.append(
+      // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
+      // is documented callable from loaders and during shell capture.
+      rawStubHeaders.append(
         "Set-Cookie",
         serializeStateCookie(stateCookieName, value, url.protocol === "https:"),
       );
@@ -1017,25 +1061,20 @@ export function createRequestContext<TEnv>(
 
     // Set the keepClientCache() directive header. The action bridge reads it on
     // the response and suppresses its automatic invalidation. `.set` makes this
-    // idempotent (one header regardless of call count).
+    // idempotent (one header regardless of call count). rawStubHeaders:
+    // guard-exempt internal writer.
     _setKeepCacheDirective(): void {
-      stubResponse.headers.set(KEEP_CACHE_HEADER, "1");
+      rawStubHeaders.set(KEEP_CACHE_HEADER, "1");
     },
 
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
-      assertNotInsideCacheScopeALS("setStatus");
-      stubResponse = new Response(null, {
-        status,
-        headers: stubResponse.headers,
-      });
+      assertResponseWriteAllowed("setStatus");
+      replaceStubStatus(status);
     },
 
     _setStatus(status: number): void {
-      stubResponse = new Response(null, {
-        status,
-        headers: stubResponse.headers,
-      });
+      replaceStubStatus(status);
     },
 
     use: null as any,
@@ -1084,7 +1123,7 @@ export function createRequestContext<TEnv>(
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
-      assertNotInsideCacheScopeALS("onResponse");
+      assertResponseWriteAllowed("onResponse");
       this._onResponseCallbacks.push(callback);
     },