@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/server/request-context.ts

@@ -11,7 +11,15 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import { parseCookiesFromHeader } from "./cookie-parse.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
+import {
+  KEEP_CACHE_HEADER,
+  getRawCookieValue,
+  mintStateValue,
+  serializeStateCookie,
+} from "../browser/cookie-name.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type {
@@ -33,24 +41,54 @@ import {
   type HandleData,
 } from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track, type MetricsStore } from "./context.js";
+import { withDefer } from "../defer.js";
+import { type MetricsStore } from "./context.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
-import { fireAndForgetWaitUntil } from "../types/request-scope.js";
-import { THEME_COOKIE } from "../theme/constants.js";
+import type { TransitionWhenFn } from "../types/segments.js";
+import type { ResolvedTracing } from "../router/tracing.js";
+import type { RenderMode, RenderPhase } from "../router/timeout.js";
+import {
+  THEME_COOKIE,
+  isValidTheme,
+  warnInvalidTheme,
+} from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RoutineTrace } from "../rsc/routine-plan.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
-import { isInsideCacheScope } from "./context.js";
+import {
+  assertCachedHeaderWriteAllowed,
+  clearPprHeaderScope,
+  isInsideCacheScope,
+} from "./context.js";
 import {
   createReverseFunction,
   stripInternalParams,
 } from "../router/handler-context.js";
-import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
+import {
+  getGlobalRouteMap,
+  isRouteRootScoped,
+  getSearchSchema,
+} from "../route-map-builder.js";
+import { parseSearchParams } from "../search-params.js";
 import { invariant } from "../errors.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
+export interface RenderForegroundCursor {
+  mode: RenderMode;
+  phase: RenderPhase;
+  state: "paused" | "running";
+  completed: number;
+  total: number;
+  pipelineStartedAt: number;
+  phaseStartedAt?: number;
+  routeKey?: string;
+  actionId?: string;
+}
+
 /**
  * Unified request context available via getRequestContext()
  *
@@ -85,6 +123,27 @@ export interface RequestContext<
   /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
   readonly res: Response;
 
+  /**
+   * True for build-time render/capture requests. Live requests use false.
+   * Build-time shell capture sets this while replaying middleware so apps can
+   * skip side-effectful runtime work.
+   */
+  readonly build: boolean;
+
+  /**
+   * Opt this request out of PPR shell serving/capture.
+   * Runtime middleware can call this before the PPR commit point; handlers can
+   * call it on a MISS to prevent the follow-up capture.
+   *
+   * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+   * (Prerender/Static) serving, and it is inert in the prerender-collect /
+   * static-render contexts (no live shell decision to influence there).
+   */
+  dynamic(): void;
+
+  /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
+  _dynamic?: boolean;
+
   /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
   cookie(name: string): string | undefined;
   /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
@@ -102,6 +161,10 @@ export interface RequestContext<
   setStatus(status: number): void;
   /** @internal Set status bypassing cache-exec guard (for framework error handling) */
   _setStatus(status: number): void;
+  /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
+  _rotateStateCookie(): void;
+  /** @internal Set the keepClientCache() directive header on the response. */
+  _setKeepCacheDirective(): void;
 
   /**
    * Access loader data or push handle data.
@@ -137,9 +200,234 @@ export interface RequestContext<
   /** @internal Handle store for tracking handle data across segments */
   _handleStore: HandleStore;
 
+  /**
+   * @internal transition({ when }) predicates for segments matched this request,
+   * keyed by segment id. Collected during resolution (the function is stripped
+   * from the serialized segment config), then evaluated post-handler in
+   * rsc-rendering — outside any cache scope — to drop the transition of any
+   * segment whose predicate returns false.
+   */
+  _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
+
+  /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+  _pprTransitionDecisions?: Map<string, boolean>;
+
+  /**
+   * @internal Post-match serve-source truth for the PPR replay reporter.
+   * Stamped from the match context as `intercept`, then overwritten as
+   * `prerender-store` if that lookup actually serves. The latter wins because
+   * it identifies the response source. matchPartialWithPprReplay reads this
+   * AFTER matching to reclassify its pre-match guess and suppress pointless
+   * heal captures.
+   */
+  _pprReplayPostMatchReason?: "prerender-store" | "intercept";
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Compiled `cache.searchParams` filter for default cache-key
+   * generation (undefined = "all", the byte-stable unfiltered format). Set
+   * once per request by handler.ts; every URL-keyed tier (segment, document,
+   * response, shell, "use cache") reads it so the tiers cannot drift.
+   */
+  _searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
+
+  /**
+   * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
+   * capture task's derived request context (built by shell-capture.ts). This is
+   * the switch every capture-specific behavior reads: loader masking
+   * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
+   * cookies()/headers() capture guard (cookie-store.ts
+   * assertNotInsideShellCapture). The foreground render never sets it, so the
+   * served response is byte-identical to axis 1. The capture descriptor itself
+   * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
+   * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
+   * locally and passes it to scheduleShellCapture directly.
+   */
+  _shellCaptureRun?: boolean;
+
+  /**
+   * @internal Bake-lane loader containers collected DURING a shell capture:
+   * segment-key -> the loader's (pre-wrap) result promise. Populated by
+   * resolveLoaderData for loaders on entries with no renderable loading() (the
+   * bake lane — they execute at capture instead of being masked; see
+   * docs/design/loader-container-bake.md). Drained by captureAndStoreShell
+   * after the shell quiesces: settled containers are promise-elided,
+   * Flight-serialized, and pinned into the snapshot's loader family; a
+   * REJECTED container refuses the capture (error UI must never bake into the
+   * shared shell). Own property of the capture's derived context only.
+   */
+  _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+
+  /**
+   * @internal Loader-family snapshot seed for a shell HIT's tail render:
+   * segment-key -> the capture's elided container (already Flight-deserialized
+   * by serveShellHit) plus its capture-computed hole bit. resolveLoaderData
+   * overlays it onto the fresh run's container (recorded paths pinned,
+   * hole-marker paths keep the fresh nested promises) so the payload's baked
+   * bytes match the frozen prelude; a hole-free entry resolves pin-first
+   * without gating on the fresh run. Own property of the HIT tail's derived
+   * context only.
+   */
+  _shellLoaderSeed?: Map<
+    string,
+    import("../cache/shell-snapshot.js").ShellLoaderSeedEntry
+  >;
+
+  /**
+   * @internal Shell fast-path marker: makes the next eligible match treat the
+   * whole matched route as an implicit doc-level cache() boundary (see
+   * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
+   * (a) the capture's derived context — with a record-only store so the
+   * capture's cacheRoute write lands in the snapshot, never the real store —
+   * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
+   * replay, where `store` is a request-local segment overlay. Handler-live holes
+   * and conditional transitions decline replay.
+   * Routes with their own cache() config are never overridden — their scope's
+   * store/key/ttl/swr/condition semantics stay authoritative. On the
+   * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
+   * such a scope instead of being ignored: the seeded doc record supplies the match
+   * only when the explicit tier misses (withCacheLookup). cache(false) and a
+   * false condition() stay absolute opt-outs — replay bypasses before any
+   * shell read (`cache-disabled`).
+   */
+  _shellImplicitCache?: {
+    ttl?: number;
+    swr?: number;
+    store?: SegmentCacheStore;
+    /**
+     * @internal Override the implicit scope's default cache namespace. Shell
+     * captures and navigation replay both consume the canonical document
+     * segment record even when the triggering request is partial.
+     */
+    keyPrefix?: "doc";
+    /** @internal Called only after the implicit cache hit decodes successfully. */
+    onHit?: () => void;
+    /**
+     * @internal Called when the seeded document record fails server-side
+     * deserialization. Partial replay uses it to replace the enclosing shell
+     * snapshot after serving the fresh fallback.
+     */
+    onCorrupt?: () => void;
+    /**
+     * @internal The resolved key of the canonical document segment record.
+     * Written during a CAPTURE render by CacheScope.cacheRoute when a
+     * doc-namespaced scope records the matched segments; captureAndStoreShell
+     * stamps it onto the ShellCacheEntry (`docKey`) so replay eligibility can
+     * require the exact consumable record instead of "any segment record".
+     */
+    docKey?: string;
+    /**
+     * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
+     * serve path. Its presence arms the explicit-scope composition in
+     * withCacheLookup: a route-derived cache() scope stays authoritative, and
+     * only when its lookup MISSes does the seeded doc record supply the match.
+     * A capture render must never set this (its match must re-run handlers so
+     * SWR recapture stays fresh), which is why the fallback keys off this
+     * field and not off the marker itself. Fired when the route-derived
+     * scope's own lookup supplied the match — the header then reports
+     * `BYPASS; reason=explicit-cache-hit`, never a false replay HIT.
+     */
+    onExplicitHit?: () => void;
+    /**
+     * @internal Companion to onExplicitHit, same lifecycle: fired when the
+     * route-derived scope's lookup REFUSED the read (`bypass` outcome — a
+     * false condition() or no store). The gate only pre-decides the static
+     * cache(false) case; a predicate refusal is known only at lookup time and
+     * reports `BYPASS; reason=cache-disabled` post-match.
+     */
+    onExplicitBypass?: () => void;
+  };
+
+  /**
+   * @internal Fragment-passthrough marker: cache/prerender-store hits during
+   * THIS render emit stored segment fragments VERBATIM into the payload
+   * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
+   * per request; the payload consumers (SSR resume, browser hydration, and
+   * the client partial-navigation decode chokepoints) expand them
+   * (segment-fragments.ts, issue #700). Partial requests arm only after the
+   * browser advertises `X-Rango-Fragment-Passthrough: 1`; a decode failure
+   * retries without it so CacheScope can evict the bad record. Two arming sites,
+   * both scoped to a
+   * render/match window: serveShellHit's derived tail context (document
+   * HIT), and matchPartialWithPprReplay's mutate-restore around the partial
+   * match (matchPartialForReplay). It must never be visible to a capture
+   * render: the capture SSR-prerenders the payload AND serializes segments
+   * into records (cacheRoute), and an envelope reaching serializeSegments
+   * would store a double-encoded fragment — deriveShellCaptureContext resets
+   * it as an own property for exactly that reason.
+   */
+  _shellFragmentPayload?: boolean;
+
+  /**
+   * @internal Handler-layer liveness observed DURING a shell capture, from
+   * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
+   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
+   * (masked to a never-filling hole); (b) still-pending top-level handler
+   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
+   * executing during the capture (loader-resolution.ts — its consumption-lane
+   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
+   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
+   * property of the capture's derived context only.
+   */
+  _shellCaptureHandleLiveness?: {
+    holes: boolean;
+    pendingPushes: number;
+    handlerInvokedLoader: boolean;
+  };
+
+  /**
+   * @internal Handle values pushed from a DSL loader scope DURING a shell
+   * capture (identity set; populated by the capture push wrapper in
+   * shell-capture.ts). cacheRoute threads it into captureHandles so those
+   * values stay out of cache-write handle records — loaders re-run fresh on
+   * every HIT, so replaying their captured (masked) values would duplicate
+   * the fresh push and stall the Flight handle encode. Own property of the
+   * capture's derived context only; render-time handle consumers are
+   * unaffected (the exclusion applies only at the captureHandles call site).
+   */
+  _shellCaptureLoaderHandleValues?: WeakSet<object>;
+
+  /**
+   * @internal Set (to the offending fn name) by the cookies()/headers()
+   * capture guard when it throws DURING a capture render. Load-bearing for the
+   * bake lane: a guard throw inside an executing loader is swallowed by
+   * wrapLoaderPromise into per-loader error UI, which would otherwise bake
+   * silently into the shared shell — the capture checks this flag after the
+   * render and refuses instead. Deterministic, so the capture does not retry.
+   */
+  _shellCaptureGuardTripped?: string;
+
+  /**
+   * @internal The loader $$id whose BODY was executing when the capture guard
+   * tripped (read off the loader-body ALS scope at trip time), or undefined
+   * when the read came from handler/render code. Only used to make the
+   * once-per-key refusal warning name the real source — the old text
+   * hardcoded "a bake-lane loader", which misattributed handler-land reads
+   * and sent users debugging the wrong lane (issue #672, secondary).
+   */
+  _shellCaptureGuardTrippedLoaderId?: string;
+
+  /**
+   * @internal Handler-owned registry of explicit per-scope stores from
+   * cache({ store }). Created once per createRSCHandler() and threaded into
+   * every request context, so it accumulates every explicit store the handler
+   * resolves. updateTag()/revalidateTag() iterate this set plus _cacheStore to
+   * reach every store that may hold tagged entries. The app-level store is not
+   * added here (it is always reachable via _cacheStore).
+   */
+  _explicitTaggedStores?: Set<SegmentCacheStore>;
+
+  /**
+   * @internal Union of every cache tag resolved while producing this request's
+   * response (from cache({ tags }), runtime cacheTag(), and loader cache tags).
+   * Populated at the tag-resolution sites via recordRequestTags(). Read by the
+   * document cache middleware so a full-page entry is tagged with everything its
+   * content used and can therefore be invalidated by updateTag()/revalidateTag().
+   */
+  _requestTags: Set<string>;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
@@ -168,6 +456,19 @@ export interface RequestContext<
   /** @internal Registered onResponse callbacks */
   _onResponseCallbacks: Array<(response: Response) => Response>;
 
+  /**
+   * @internal Promises of the background tasks scheduled via this context's
+   * waitUntil (deferred cache writes, revalidations, consumer tasks). The PPR
+   * shell capture drains this list BEFORE its match/render as an ORDERING EDGE:
+   * every foreground deferred cache write is scheduled here before the capture
+   * task is, so settling the list first guarantees the capture's cache reads
+   * observe the foreground's generation instead of racing it (see
+   * shell-capture.ts). Tasks whose scheduling fn carries
+   * UNTRACKED_BACKGROUND_TASK are not tracked (the capture task itself —
+   * tracking it would make that drain await its own promise).
+   */
+  _pendingBackgroundTasks?: Array<Promise<unknown>>;
+
   /**
    * Current theme setting (only available when theme is enabled in router config)
    *
@@ -249,6 +550,30 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
+  /**
+   * @internal Navigation/action source data the transition({ when }) gate reads
+   * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
+   * come from the navigation snapshot (set at match time); action* are stashed
+   * at the action-bearing gate call sites. All undefined when there is no source
+   * (initial full load) or no action (plain navigation).
+   */
+  _gateCurrentUrl?: URL;
+  _gateCurrentParams?: Record<string, string>;
+  _gateActionId?: string;
+  _gateActionUrl?: URL;
+  _gateActionResult?: unknown;
+  _gateFormData?: FormData;
+
+  /**
+   * @internal True while the post-action revalidation render is running (set by
+   * revalidateAfterAction). The "use cache" runtime reads this to prefer
+   * freshness over a fast stale response during an action: a stale entry
+   * re-executes in the foreground (so the action response reflects the refreshed
+   * value) with only the store write deferred, instead of serving stale and
+   * revalidating in the background. A plain navigation (flag unset) keeps SWR.
+   */
+  _inActionRevalidation?: boolean;
+
   /**
    * @internal Render barrier for experimental `rendered()` API.
    * Resolves when all non-loader segments have settled and handle data
@@ -273,7 +598,9 @@ export interface RequestContext<
 
   /**
    * @internal Set to true when the matched entry tree contains any `loading()`
-   * entries (streaming). Used by rendered() to fail fast.
+   * entries (streaming). On a streaming tree rendered() waits for the streaming
+   * handlers to settle (via handleStore.settled) before resolving, and the
+   * deadlock guard state is kept live until that wait completes.
    */
   _treeHasStreaming?: boolean;
 
@@ -297,6 +624,18 @@ export interface RequestContext<
    */
   _renderBarrierHandleSnapshot?: HandleData;
 
+  /**
+   * @internal The deadlock guard window is closed (no further handler-awaits-
+   * loader cycle is possible). For non-streaming trees this is set when the
+   * barrier resolves. For streaming trees the window stays open until
+   * handleStore.settled — rendered() keeps waiting past the barrier and a
+   * loading() handler can still resume and await a still-waiting loader — so it
+   * is set only after settled. The guard (loader-resolution `setupLoaderAccess`)
+   * reads this instead of `_renderBarrierSegmentOrder` so it does not go blind
+   * during the streaming settle wait.
+   */
+  _renderBarrierGuardClosed?: boolean;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -304,9 +643,13 @@ export interface RequestContext<
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
    * creation. Cache-runtime and other subsystems call this to surface
-   * errors without failing the response.
+   * errors without failing the response. `category` is surfaced to consumers as
+   * `metadata.category` on the onError context (phase `cache`).
    */
-  _reportBackgroundError?: (error: unknown, category: string) => void;
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
 
   /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
   _debugPerformance?: boolean;
@@ -314,14 +657,59 @@ export interface RequestContext<
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
 
+  /**
+   * @internal Foreground response-construction cursor. It reports only the
+   * generator driver's current Flight/HTML/response operation; concurrent
+   * loaders and post-commit stream work have separate lifetimes.
+   */
+  _renderForeground?: RenderForegroundCursor;
+
+  /** @internal Request routine currently executing, used by timeout diagnostics. */
+  _activeRoutine?: RoutineTrace;
+
+  /** @internal Keep the render cursor active for timeout support. */
+  _renderDiagnosticsEnabled?: boolean;
+
+  /**
+   * @internal True request entry timestamp (performance.now() at handler entry).
+   * Set once at request-context creation (rsc/handler.ts) so a metrics store
+   * created MID-request — ctx.debugPerformance() or the getMetricsStore wrapper —
+   * anchors its timeline to the real request start instead of the opt-in moment,
+   * keeping phases that began before the opt-in at their true (non-negative) offset.
+   */
+  _handlerStart?: number;
+
+  /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
+  _tracing?: ResolvedTracing;
+
   /** @internal Router basename for this request (used by redirect()) */
   _basename?: string;
 
+  /** @internal Owning router id; scopes the search-schema/root-scope registry
+   *  lookups per router (route-map-builder.ts) */
+  _routerId?: string;
+
   /**
    * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @internal Classified request mode from classifyRequest, read by the
+   * rango.response span tail (rsc/handler.ts) for the rango.response.mode
+   * attribute. Unset when middleware short-circuits before core execution.
+   */
+  _requestMode?: import("../router/request-classification.js").RequestPlan["mode"];
+
+  /**
+   * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+   * header. Populated by match/matchPartial only when the debug cache signal
+   * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+   * the response-finalization path (createResponseWithMergedHeaders). Undefined
+   * when the gate is off, so no header is emitted.
+   */
+  _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
 /**
@@ -340,13 +728,36 @@ export type PublicRequestContext<
   | "setCookie"
   | "deleteCookie"
   | "_handleStore"
+  | "_transitionWhen"
+  | "_pprTransitionDecisions"
+  | "_pprReplayPostMatchReason"
   | "_cacheStore"
+  | "_searchParamsFilter"
+  | "_shellCaptureRun"
+  | "_shellImplicitCache"
+  | "_shellLoaderSeed"
+  | "_shellCaptureLoaderRecords"
+  | "_shellCaptureHandleLiveness"
+  | "_shellCaptureLoaderHandleValues"
+  | "_shellFragmentPayload"
+  | "_shellCaptureGuardTripped"
+  | "_shellCaptureGuardTrippedLoaderId"
+  | "_explicitTaggedStores"
+  | "_requestTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
+  | "_pendingBackgroundTasks"
   | "_themeConfig"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
+  | "_gateCurrentUrl"
+  | "_gateCurrentParams"
+  | "_gateActionId"
+  | "_gateActionUrl"
+  | "_gateActionResult"
+  | "_gateFormData"
+  | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
@@ -355,16 +766,39 @@ export type PublicRequestContext<
   | "_renderBarrierWaiters"
   | "_handlerLoaderDeps"
   | "_renderBarrierHandleSnapshot"
+  | "_renderBarrierGuardClosed"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_renderForeground"
+  | "_activeRoutine"
+  | "_renderDiagnosticsEnabled"
+  | "_handlerStart"
+  | "_tracing"
   | "_basename"
+  | "_routerId"
   | "_setStatus"
+  | "_rotateStateCookie"
+  | "_setKeepCacheDirective"
   | "_variables"
   | "_classifiedRoute"
+  | "_requestMode"
+  | "_cacheSignal"
+  | "_dynamic"
   | "res"
 >;
 
+/**
+ * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
+ * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
+ * the capture's pre-render write barrier settles that list, so tracking the
+ * capture itself would make the drain wait on its own (still-running) promise.
+ * @internal
+ */
+export const UNTRACKED_BACKGROUND_TASK: unique symbol = Symbol.for(
+  "rango.untrackedBackgroundTask",
+);
+
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
@@ -413,6 +847,7 @@ export function _getRequestContext<TEnv = DefaultEnv>():
 export function setRequestContextParams(
   params: Record<string, string>,
   routeName?: string,
+  routeMap?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
   if (ctx) {
@@ -425,12 +860,16 @@ export function setRequestContextParams(
           : undefined
       ) as DefaultRouteName | undefined;
     }
-    // Update reverse with scoped resolution now that route is known
+    // Update reverse with scoped resolution now that route is known. Production
+    // omits routeMap and uses the global map (routes are registered globally);
+    // the testing primitives (renderToFlightString/renderServerTree) pass a
+    // scoped routeMap so `ctx.reverse` is not order-dependent on whatever router
+    // registered last.
     ctx.reverse = createReverseFunction(
-      getGlobalRouteMap(),
+      routeMap ?? getGlobalRouteMap(),
       routeName,
       params,
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      routeName ? isRouteRootScoped(routeName, ctx._routerId) : undefined,
     );
   }
 }
@@ -443,11 +882,17 @@ export function setRequestContextParams(
  */
 export function setRequestContextPrevRouteKey(
   prevRouteKey: string | undefined,
+  currentUrl?: URL,
+  currentParams?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
-  if (ctx && prevRouteKey !== undefined) {
-    ctx._prevRouteKey = prevRouteKey;
-  }
+  if (!ctx) return;
+  if (prevRouteKey !== undefined) ctx._prevRouteKey = prevRouteKey;
+  // Source URL/params for the transition({ when }) gate (effectiveFromUrl /
+  // effectiveFromMatch.params from the navigation snapshot). Same write point as
+  // _prevRouteKey, which doubles as fromRouteName.
+  if (currentUrl !== undefined) ctx._gateCurrentUrl = currentUrl;
+  if (currentParams !== undefined) ctx._gateCurrentParams = currentParams;
 }
 
 /**
@@ -461,16 +906,6 @@ export function getLocationState(): LocationStateEntry[] | undefined {
   return ctx?._locationState;
 }
 
-/**
- * Get the current request context, throwing if not available
- * @deprecated Use getRequestContext() directly — it now throws if outside context
- */
-export function requireRequestContext<
-  TEnv = DefaultEnv,
->(): RequestContext<TEnv> {
-  return getRequestContext<TEnv>();
-}
-
 export type { ExecutionContext };
 
 /**
@@ -485,6 +920,16 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Compiled `cache.searchParams` filter from the resolved handler cache
+   * config (handler.ts). Stored as _searchParamsFilter.
+   */
+  searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
+  /**
+   * Handler-owned registry of explicit per-scope stores for cross-store tag
+   * invalidation. Created once per handler, reused across requests.
+   */
+  explicitTaggedStores?: Set<SegmentCacheStore>;
   /** Optional cache profiles for "use cache" resolution (per-router) */
   cacheProfiles?: Record<
     string,
@@ -492,8 +937,14 @@ export interface CreateRequestContextOptions<TEnv> {
   >;
   /** Optional Cloudflare execution context for waitUntil support */
   executionContext?: ExecutionContext;
+  /** Build-time render/capture request marker. Defaults to false. */
+  build?: boolean;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
   themeConfig?: ResolvedThemeConfig | null;
+  /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
+  stateCookieName?: string;
+  /** Build version, used as the prefix of a server-rotated rango state value. */
+  version?: string;
 }
 
 /**
@@ -514,15 +965,19 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    searchParamsFilter,
+    explicitTaggedStores,
     cacheProfiles,
     executionContext,
+    build = false,
     themeConfig,
+    stateCookieName,
+    version: stateVersion,
   } = options;
   const cookieHeader = request.headers.get("Cookie");
+  let rangoStateRotated = false;
   let parsedCookies: Record<string, string> | null = null;
 
-  // Create stub response for collecting headers/cookies.
-  // All cookie/header mutations go here; cookie reads derive from it.
   let stubResponse = initialResponse
     ? new Response(null, {
         status: initialResponse.status,
@@ -531,11 +986,53 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
-  // Create handle store and loader memoization for this request
+  // 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>>();
 
-  // Lazy parse cookies from the original Cookie header
   const getParsedCookies = (): Record<string, string> => {
     if (!parsedCookies) {
       parsedCookies = parseCookiesFromHeader(cookieHeader);
@@ -543,7 +1040,6 @@ export function createRequestContext<TEnv>(
     return parsedCookies;
   };
 
-  // Cached response cookie mutations — invalidated on setCookie/deleteCookie/setTheme
   let responseCookieCache: Map<string, string | null> | null = null;
   const getResponseCookies = (): Map<string, string | null> => {
     if (!responseCookieCache) {
@@ -555,20 +1051,15 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
-  // Guard: throw if a response-level side effect is called inside a cache() scope.
-  // Uses ALS to detect the scope (set during segment resolution).
-  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);
   }
 
-  // Effective cookie read: response stub Set-Cookie wins, then original header.
-  // The stub IS the source of truth for same-request mutations.
+  // Response stub Set-Cookie wins, then original header (source of truth for mutations).
   const effectiveCookie = (name: string): string | undefined => {
     const mutations = getResponseCookies();
     if (mutations.has(name)) {
@@ -578,14 +1069,11 @@ export function createRequestContext<TEnv>(
     return getParsedCookies()[name];
   };
 
-  // Theme helpers (only used when themeConfig is provided)
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
-    // Use overlay-aware read so setTheme() in the same request is reflected
     const stored = effectiveCookie(themeConfig.storageKey);
     if (stored) {
-      // Validate stored value
       if (stored === "system" && themeConfig.enableSystem) {
         return "system";
       }
@@ -599,15 +1087,15 @@ export function createRequestContext<TEnv>(
   const setTheme = (theme: Theme): void => {
     if (!themeConfig) return;
 
-    // Validate theme value
-    if (theme !== "system" && !themeConfig.themes.includes(theme)) {
-      console.warn(
-        `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
-      );
+    // Shared guard (isValidTheme): reject any value not in the configured theme
+    // set, AND reject "system" when system detection is off — a cookie of
+    // theme=system with enableSystem:false would re-apply a bogus class="system"
+    // on the next SSR.
+    if (!isValidTheme(theme, themeConfig)) {
+      warnInvalidTheme(theme, themeConfig);
       return;
     }
 
-    // Write to stub — effectiveCookie() will pick it up on next read
     stubResponse.headers.append(
       "Set-Cookie",
       serializeCookieValue(themeConfig.storageKey, theme, {
@@ -619,10 +1107,8 @@ export function createRequestContext<TEnv>(
     invalidateResponseCookieCache();
   };
 
-  // Strip internal _rsc* params so userland sees a clean URL.
   const cleanUrl = stripInternalParams(url);
 
-  // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
@@ -631,6 +1117,16 @@ export function createRequestContext<TEnv>(
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
     _variables: variables,
+    build,
+    dynamic(): void {
+      ctx._dynamic = true;
+      // A dynamic() render is always live (never a shell HIT), so its handler
+      // header writes are deterministic — clear the ppr latch to re-permit them
+      // (#735). No-op from middleware (outside the funnel scope) or on non-ppr
+      // routes; cache() latches are left alone.
+      clearPprHeaderScope();
+    },
+    _dynamic: false,
     get: ((keyOrVar: any) => {
       if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
         throw new Error(
@@ -681,7 +1177,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),
@@ -694,7 +1189,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 }),
@@ -704,54 +1198,113 @@ export function createRequestContext<TEnv>(
 
     header(name: string, value: string): void {
       assertNotInsideCacheExec(ctx, "header");
-      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
+    // Rotate the rango state cookie for the responding client (the server seat
+    // of invalidateClientCache). Writes ONE Set-Cookie per request with the
+    // value {version}:{timestamp}; the `:` stays raw (the cookie-name.ts
+    // serializer), not the URL-encoded form serializeCookieValue would produce.
+    // The timestamp is strictly greater than the client's current one (inbound
+    // X-Rango-State), so a same-millisecond server rotation still differs from
+    // the client value and the divergence observer fires.
+    _rotateStateCookie(): void {
+      if (rangoStateRotated) return;
+      rangoStateRotated = true;
+      if (!stateCookieName) return;
+      // The client's current value, for the monotonic guard: prefer the
+      // X-Rango-State header (router navigation/prefetch fetches send it), but
+      // fall back to the request's rango state cookie — action POSTs / plain
+      // app fetch()s carry no router header yet DO send the cookie. Without the
+      // fallback, prevTs stays 0 and a same-ms mint can equal the client value,
+      // leaving the divergence observer silent. `|| null` so an empty header
+      // ('' from proxy normalization) falls through instead of short-circuiting.
+      // getRawCookieValue reads the cookie undecoded (the wire value
+      // decodeStateValue decodes exactly once) AND is the same parser the client
+      // mirror uses, so both seats read the same jar entry.
+      const prevRaw =
+        (request.headers.get("x-rango-state") || null) ??
+        getRawCookieValue(cookieHeader, stateCookieName);
+      const value = mintStateValue(stateVersion ?? "0", prevRaw);
+      // 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:"),
+      );
+      invalidateResponseCookieCache();
+    },
+
+    // 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). rawStubHeaders:
+    // guard-exempt internal writer.
+    _setKeepCacheDirective(): void {
+      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);
     },
 
-    // Placeholder - will be replaced below
     use: null as any,
 
     method: request.method,
 
     _handleStore: handleStore,
+    _transitionWhen: [],
     _cacheStore: cacheStore,
+    _searchParamsFilter: searchParamsFilter,
+    _explicitTaggedStores: explicitTaggedStores,
+    _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
+      if (ctx.build) return;
+      // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
+      // non-async callback becomes a rejected promise handed to the host's
+      // waitUntil (logged as a background failure), instead of escaping into
+      // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
+      const task = Promise.resolve().then(fn);
+      // Track the task promise so the PPR shell capture can settle the
+      // foreground's deferred cache writes before its own match/render (the
+      // ordering edge; see _pendingBackgroundTasks). The capture task itself
+      // opts out via the marker — the drain must never await its own promise.
+      if (
+        !(fn as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
+          UNTRACKED_BACKGROUND_TASK
+        ]
+      ) {
+        ctx._pendingBackgroundTasks?.push(task);
+      }
       if (executionContext?.waitUntil) {
-        executionContext.waitUntil(fn());
+        executionContext.waitUntil(task);
       } else {
-        fireAndForgetWaitUntil(fn);
+        // Node/dev fallback: fire-and-forget with error logging (the same
+        // policy fireAndForgetWaitUntil applies).
+        task.catch((err) =>
+          console.error("[waitUntil] Background task failed:", err),
+        );
       }
     },
 
     executionContext,
 
     _onResponseCallbacks: [],
+    _pendingBackgroundTasks: [],
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
-      assertNotInsideCacheScopeALS("onResponse");
+      assertResponseWriteAllowed("onResponse");
       this._onResponseCallbacks.push(callback);
     },
 
-    // Theme properties (only set when themeConfig is provided)
     get theme() {
       return themeConfig ? getTheme() : undefined;
     },
@@ -774,20 +1327,68 @@ export function createRequestContext<TEnv>(
 
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
+    _renderForeground: undefined,
+    _activeRoutine: undefined,
+    _renderDiagnosticsEnabled: undefined,
+    _handlerStart: undefined,
 
-    // Render barrier: deferred promise resolved after non-loader segments settle.
-    _renderBarrier: null as any, // set below
-    _resolveRenderBarrier: null as any, // set below
+    _renderBarrier: null as any,
+    _resolveRenderBarrier: null as any,
     _renderBarrierSegmentOrder: undefined,
 
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Lazy render barrier: only allocate the Promise when a loader actually
-  // calls rendered(). Requests that don't use rendered() pay zero cost.
+  wireRenderBarrier(ctx, handleStore);
+
+  ctx.use = createUseFunction({
+    handleStore,
+    loaderPromises,
+    getContext: () => ctx,
+  });
+
+  (ctx as any)[NOCACHE_SYMBOL] = true;
+  return ctx;
+}
+
+/**
+ * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
+ * handle store. Called by createRequestContext for every fresh context, and by
+ * deriveShellCaptureContext (rsc/shell-capture.ts) for the PPR capture's
+ * derived context.
+ *
+ * The derived-context call is load-bearing (issue #684, plan 009): the capture
+ * context is `Object.create(reqCtx)`, so without its own wiring every
+ * `_renderBarrier*` read fell through the prototype to the FOREGROUND
+ * request's barrier — whose getter and resolver are closure-bound to the
+ * foreground ctx and its handle store, and whose resolver no-ops once
+ * resolved. A bake-lane loader's `await ctx.rendered()` during capture then
+ * resolved instantly against the foreground's barrier and `ctx.use(handle)`
+ * read the foreground's handle snapshot; the capture's fresh `_handleStore`
+ * was invisible, so foreground per-request handle data could bake into the
+ * shared shell.
+ */
+export function wireRenderBarrier(
+  ctx: RequestContext<any, any>,
+  handleStore: HandleStore,
+): void {
+  // Reset the whole barrier family as OWN properties. No-op for a fresh
+  // context; for the derived capture context this shadows the foreground's
+  // resolved state so the capture runs its own barrier lifecycle. In
+  // particular _treeHasStreaming must be recomputed for the CAPTURE's tree
+  // (cache-lookup/segment-resolution only set it when undefined): an
+  // inherited `true` made a capture-lane rendered() seal the capture's fresh
+  // store at loader start and pair it with the foreground's segment order.
+  ctx._renderBarrierSegmentOrder = undefined;
+  ctx._renderBarrierWaiters = undefined;
+  ctx._renderBarrierHandleSnapshot = undefined;
+  ctx._renderBarrierGuardClosed = undefined;
+  ctx._handlerLoaderDeps = undefined;
+  ctx._treeHasStreaming = undefined;
+
+  // Lazy allocation: only create the Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any; // lazy — created on first access
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -797,21 +1398,29 @@ export function createRequestContext<TEnv>(
       .filter((s) => s.type !== "loader")
       .map((s) => s.id);
     ctx._renderBarrierSegmentOrder = segOrder;
-    // Build and cache handle snapshot so loader ctx.use(handle) calls
-    // don't rebuild it on every invocation.
-    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
-      handleStore,
-      segOrder,
-    );
-    ctx._renderBarrierWaiters = undefined;
-    ctx._handlerLoaderDeps = undefined;
+
+    const closeGuard = () => {
+      ctx._renderBarrierWaiters = undefined;
+      ctx._handlerLoaderDeps = undefined;
+      ctx._renderBarrierGuardClosed = true;
+    };
+
+    if (ctx._treeHasStreaming) {
+      handleStore.settled.then(closeGuard);
+    } else {
+      ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+        handleStore,
+        segOrder,
+      );
+      closeGuard();
+    }
     if (resolveBarrier) resolveBarrier();
   };
+  // defineProperty, not assignment: on a derived context the prototype's
+  // _renderBarrier may already be a non-writable data property (the getter
+  // pins it after first access), which would reject a plain assignment.
   Object.defineProperty(ctx, "_renderBarrier", {
     get() {
-      // Barrier already resolved (cache/prerender hit) or first lazy access.
-      // Either way, replace the getter with a concrete value to avoid
-      // repeated Promise.resolve() allocations on subsequent reads.
       const p = barrierResolved
         ? Promise.resolve()
         : new Promise<void>((resolve) => {
@@ -826,33 +1435,25 @@ export function createRequestContext<TEnv>(
     },
     configurable: true,
   });
+}
 
-  // Now create use() with access to ctx
-  ctx.use = createUseFunction({
-    handleStore,
-    loaderPromises,
-    getContext: () => ctx,
-  });
+// Capture the Max-Age value so it can be parsed numerically. A leading zero
+// (Max-Age=05) is a non-zero lifetime, not a deletion; only a value that parses
+// to <= 0 marks a cookie for deletion. Pattern-matching a leading "0" misread
+// zero-prefixed values like 05 / 010 as deletions.
+const MAX_AGE_RE = /;\s*Max-Age\s*=\s*(-?\d+)/i;
 
-  // Brand with taint symbol so "use cache" excludes ctx from cache keys
-  (ctx as any)[NOCACHE_SYMBOL] = true;
-  return ctx;
+function isCookieDeletion(header: string): boolean {
+  const m = MAX_AGE_RE.exec(header);
+  if (!m) return false;
+  return Number(m[1]) <= 0;
 }
 
-/**
- * Parse Set-Cookie headers from a response into effective cookie state.
- * Returns a map of cookie name -> value (string) or name -> null (deleted).
- * Last-write-wins: later Set-Cookie entries for the same name overwrite earlier ones.
- * Max-Age=0 is treated as a delete.
- */
-const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
-
 function parseResponseCookies(response: Response): Map<string, string | null> {
   const result = new Map<string, string | null>();
   const setCookies = response.headers.getSetCookie();
 
   for (const header of setCookies) {
-    // First segment before ';' is the name=value pair
     const semiIdx = header.indexOf(";");
     const pair = semiIdx === -1 ? header : header.substring(0, semiIdx);
     const eqIdx = pair.indexOf("=");
@@ -864,62 +1465,78 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
       name = decodeURIComponent(pair.substring(0, eqIdx).trim());
       value = decodeURIComponent(pair.substring(eqIdx + 1).trim());
     } catch {
-      // Malformed encoding — skip this entry
       continue;
     }
 
-    // Max-Age=0 means the cookie is being deleted
-    const isDeleted = MAX_AGE_ZERO_RE.test(header);
+    const isDeleted = isCookieDeletion(header);
     result.set(name, isDeleted ? null : value);
   }
 
   return result;
 }
 
-/**
- * Parse cookies from Cookie header
- */
-function parseCookiesFromHeader(
-  cookieHeader: string | null,
-): Record<string, string> {
-  if (!cookieHeader) return {};
-
-  const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(";");
-
-  for (const pair of pairs) {
-    const [name, ...rest] = pair.trim().split("=");
-    if (name) {
-      const raw = rest.join("=");
-      try {
-        cookies[name] = decodeURIComponent(raw);
-      } catch {
-        // Malformed percent-encoded value (e.g. %zz, %2) - fall back to raw value
-        cookies[name] = raw;
-      }
+// Re-exported for unit tests and the existing import path. The implementation
+// lives in the dependency-free ./cookie-parse leaf so consumers (e.g. the host
+// dispatcher) can share it without pulling this module's request-context graph.
+export { parseCookiesFromHeader };
+
+/** Reject CR/LF/;/,/whitespace/control so raw attribute interpolation cannot inject. */
+function assertSafeCookieAttribute(
+  value: string,
+  label: "domain" | "path",
+): void {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f || value[i] === ";" || value[i] === ",") {
+      throw new Error(
+        label === "domain" ? "invalid cookie domain" : "invalid cookie path",
+      );
     }
   }
-
-  return cookies;
 }
 
-/**
- * Serialize a cookie for Set-Cookie header
- */
-function serializeCookieValue(
+export function serializeCookieValue(
   name: string,
   value: string,
   options: CookieOptions = {},
 ): string {
   let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
 
-  if (options.domain) cookie += `; Domain=${options.domain}`;
-  if (options.path) cookie += `; Path=${options.path}`;
-  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options.domain) {
+    assertSafeCookieAttribute(options.domain, "domain");
+    cookie += `; Domain=${options.domain}`;
+  }
+  if (options.path) {
+    if (!options.path.startsWith("/")) {
+      throw new Error("invalid cookie path");
+    }
+    assertSafeCookieAttribute(options.path, "path");
+    cookie += `; Path=${options.path}`;
+  }
+  if (options.maxAge !== undefined) {
+    // Safe integer: Number.isInteger(1e21) is true but stringifies as "1e+21",
+    // which is invalid Max-Age wire syntax. Number.isSafeInteger rejects that.
+    if (
+      typeof options.maxAge !== "number" ||
+      !Number.isSafeInteger(options.maxAge)
+    ) {
+      throw new Error("invalid cookie maxAge");
+    }
+    cookie += `; Max-Age=${options.maxAge}`;
+  }
   if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
   if (options.httpOnly) cookie += "; HttpOnly";
   if (options.secure) cookie += "; Secure";
-  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+  if (options.sameSite) {
+    if (
+      options.sameSite !== "strict" &&
+      options.sameSite !== "lax" &&
+      options.sameSite !== "none"
+    ) {
+      throw new Error("invalid cookie sameSite");
+    }
+    cookie += `; SameSite=${options.sameSite}`;
+  }
 
   return cookie;
 }
@@ -933,20 +1550,12 @@ export interface CreateUseFunctionOptions<TEnv> {
   getContext: () => RequestContext<TEnv>;
 }
 
-/**
- * Create the use() function for loader and handle composition.
- *
- * This is the unified implementation used by both RequestContext and HandlerContext.
- * - For loaders: executes and memoizes loader functions
- * - For handles: returns a push function to add handle data
- */
 export function createUseFunction<TEnv>(
   options: CreateUseFunctionOptions<TEnv>,
 ): RequestContext["use"] {
   const { handleStore, loaderPromises, getContext } = options;
 
   return ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
-    // Handle case: return a push function
     if (isHandle(item)) {
       const handle = item;
       const ctx = getContext();
@@ -959,30 +1568,24 @@ export function createUseFunction<TEnv>(
         );
       }
 
-      // Return a push function bound to this handle and segment
-      return (
-        dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
-      ) => {
-        // If it's a function, call it immediately to get the promise
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
-
-        // Push directly - promises will be serialized by RSC and streamed
-        handleStore.push(handle.$$id, segmentId, valueOrPromise);
-      };
+      return withDefer(
+        (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+          const valueOrPromise =
+            typeof dataOrFn === "function"
+              ? (dataOrFn as () => Promise<unknown>)()
+              : dataOrFn;
+
+          handleStore.push(handle.$$id, segmentId, valueOrPromise);
+        },
+      );
     }
 
-    // Loader case
     const loader = item as LoaderDefinition<any, any>;
 
-    // Return cached promise if already started
     if (loaderPromises.has(loader.$$id)) {
       return loaderPromises.get(loader.$$id);
     }
 
-    // Get loader function - either from loader object or fetchable registry
     let loaderFn = loader.fn;
     if (!loaderFn) {
       const fetchable = getFetchableLoader(loader.$$id);
@@ -999,33 +1602,56 @@ export function createUseFunction<TEnv>(
 
     const ctx = getContext();
 
-    // Create loader context with recursive use() support
+    // Build the typed ctx.search the same way the render path
+    // (createHandlerContext) and the fetchable-loader path (loader-fetch.ts) do:
+    // parse the route's search schema over the cleaned searchParams. The base
+    // RequestContext carries no `search` field, so reading `(ctx as any).search`
+    // here always yielded {} — dropping typed search for action/dispatch loaders.
+    const searchSchema = ctx._routeName
+      ? getSearchSchema(ctx._routeName, ctx._routerId)
+      : undefined;
+    const loaderSearch = searchSchema
+      ? parseSearchParams(ctx.searchParams, searchSchema)
+      : {};
+
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
-      search: (ctx as any).search ?? {},
+      search: loaderSearch,
       pathname: ctx.pathname,
       url: ctx.url,
       originalUrl: ctx.originalUrl,
       env: ctx.env as any,
       waitUntil: ctx.waitUntil.bind(ctx),
       executionContext: ctx.executionContext,
-      get: ctx.get as any,
-      use: (<TDep, TDepParams = any>(
-        dep: LoaderDefinition<TDep, TDepParams>,
-      ): Promise<TDep> => {
-        // Recursive call - will start dep loader if not already started
-        return ctx.use(dep);
-      }) as LoaderContext["use"],
+      get: ((keyOrVar: any) => {
+        // Handle READS need the rendered() barrier, which this lane
+        // (action/dispatch-invoked loaders) does not run. Fail with guidance
+        // instead of returning a misleading empty collect.
+        if (isHandle(keyOrVar)) {
+          throw new Error(
+            `ctx.get(handle) is only available in DSL loaders after ` +
+              `"await ctx.rendered()". It cannot be used from request-context ` +
+              `loaders or server actions.`,
+          );
+        }
+        return (ctx.get as any)(keyOrVar);
+      }) as any,
+      // Pass items through: loaders delegate to the request ctx's loader
+      // executor; a handle yields the ctx's push function (write parity —
+      // ctx.use(Meta)({...}) works in this lane exactly like in a handler).
+      use: ((item: any) => ctx.use(item)) as LoaderContext["use"],
       method: "GET",
       body: undefined,
       reverse: createReverseFunction(
         getGlobalRouteMap(),
         ctx._routeName,
         ctx.params as Record<string, string>,
-        ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
+        ctx._routeName
+          ? isRouteRootScoped(ctx._routeName, ctx._routerId)
+          : undefined,
       ),
       rendered: () => {
         throw new Error(
@@ -1035,12 +1661,14 @@ export function createUseFunction<TEnv>(
       },
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`, 2);
-    const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
-      doneLoader();
-    });
+    // Meter through the same unified phase API as the loader-resolution funnel
+    // (observePhase), so a loader resolved via this base request-context ctx.use
+    // co-emits the "loader:<id>" perf metric AND the "rango.loader" span — no
+    // drift between the two ctx.use implementations.
+    const promise = observePhase(PHASES.loader(loader.$$id), () =>
+      Promise.resolve(loaderFn(loaderCtx)),
+    );
 
-    // Memoize for subsequent calls
     loaderPromises.set(loader.$$id, promise);
 
     return promise;