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

package/src/server/context.ts

@@ -10,7 +10,7 @@ import type {
   ShouldRevalidateFn,
   TransitionConfig,
 } from "../types";
-import { invariant } from "../errors";
+import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 
 // ============================================================================
@@ -27,6 +27,7 @@ export interface PerformanceMetric {
   duration: number; // milliseconds
   startTime: number; // relative to request start
   depth?: number; // nesting level for hierarchical display (0 = top-level)
+  desc?: string; // free-form outcome detail, emitted as Server-Timing desc="..."
 }
 
 /**
@@ -40,7 +41,7 @@ export interface MetricsStore {
   metrics: PerformanceMetric[];
 }
 // ============================================================================
-//  RSC Router Context
+//  Rango Context
 // ============================================================================
 
 /**
@@ -71,6 +72,10 @@ export type EntryPropCommon = {
 };
 
 /**
+ * Attachments resolved by walking the parent chain, not owned by the entry:
+ * middleware composes downward; revalidate and the error/notFound boundaries are
+ * resolved by nearest-ancestor lookup. Inherited, not a single execution chain.
+ *
  * @internal This type is an implementation detail and may change without notice.
  */
 export type EntryPropDatas = {
@@ -80,6 +85,16 @@ export type EntryPropDatas = {
   notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
 };
 
+/**
+ * Render-time presentation fields shared by every entry variant.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropRender = {
+  loading?: ReactNode | false;
+  transition?: TransitionConfig;
+};
+
 /**
  * Loader entry stored in EntryData
  * Contains the loader definition and its revalidation rules
@@ -136,6 +151,19 @@ export type InterceptWhenFn<TEnv = any> = (
   ctx: InterceptSelectorContext<TEnv>,
 ) => boolean;
 
+/**
+ * Config object passed to intercept() (its 4th argument). `when` gates whether
+ * the intercept activates on a soft navigation — a single match-time selector or
+ * an array of them (ALL must return true; omit to always activate). This is the
+ * intercept counterpart to transition({ when }); both express conditional
+ * behavior as a config field rather than a separate DSL helper.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface InterceptConfig<TEnv = any> {
+  when?: InterceptWhenFn<TEnv> | InterceptWhenFn<TEnv>[];
+}
+
 /**
  * Intercept entry stored in EntryData
  * Contains the slot name, route to intercept, and handler
@@ -158,11 +186,9 @@ export type InterceptEntry = {
 };
 
 export interface ParallelEntryData
-  extends EntryPropCommon, EntryPropDatas, EntryPropSegments {
+  extends EntryPropCommon, EntryPropDatas, EntryPropSegments, EntryPropRender {
   type: "parallel";
   handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
-  loading?: ReactNode | false;
-  transition?: TransitionConfig;
   /** Set when any parallel slot is a Static definition */
   isStaticPrerender?: true;
   /** Per-slot static handler $$ids for build-time store lookup */
@@ -171,6 +197,13 @@ export interface ParallelEntryData
 
 export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
 
+/**
+ * This entry's own structural children plus its owned loaders. `loader` lives
+ * here (not in EntryPropDatas) because loaders are owned by the entry, not
+ * inherited from ancestors.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
 export type EntryPropSegments = {
   loader: LoaderEntry[];
   layout: EntryData[];
@@ -182,8 +215,6 @@ export type EntryData =
   | ({
       type: "route";
       handler: Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
       /** URL pattern for this route (used by path() in urls()) */
       pattern?: string;
       /** Set when handler is a Prerender definition */
@@ -203,31 +234,37 @@ export type EntryData =
       staticHandlerId?: string;
       /** Response type for non-RSC routes (json, text, image, any) */
       responseType?: string;
+      /**
+       * PPR (partial pre-rendering) opt-in from the path() `ppr` option. A
+       * document-level property of the page route: `true` uses the default
+       * shell policy, an object carries ttl/swr/tags. Read by the integrated
+       * PPR serve path (rsc/shell-serve.ts resolvePprConfig).
+       */
+      ppr?: boolean | import("../urls/pattern-types.js").PartialPrerenderProps;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments)
+      EntryPropSegments &
+      EntryPropRender)
   | ({
       type: "layout";
       handler: ReactNode | Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
       /** Set when handler is a Static definition (build-time only) */
       isStaticPrerender?: true;
       /** Static handler $$id for build-time store lookup */
       staticHandlerId?: string;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments)
+      EntryPropSegments &
+      EntryPropRender)
   | ParallelEntryData
   | ({
       type: "cache";
       /** Cache entries create cache boundaries and render like layouts (with Outlet) */
       handler: ReactNode | Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments);
+      EntryPropSegments &
+      EntryPropRender);
 
 /**
  * Tracked include info for build-time manifest generation
@@ -240,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
  */
@@ -250,6 +298,10 @@ interface HelperContext {
   counters: Record<string, number>;
   forRoute?: string;
   mountIndex?: number;
+  /** Owning router id, when known (threaded by generateManifestFull). Scopes
+   *  the search-schema/root-scope registries so same-named routes in
+   *  different routers don't clobber each other (route-map-builder.ts). */
+  routerId?: string;
   metrics?: MetricsStore;
   /** True when rendering for SSR (document requests) */
   isSSR?: boolean;
@@ -280,6 +332,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.
    *
@@ -303,10 +362,28 @@ interface HelperContext {
 // hold references to the old instance — causing getStore() to return
 // undefined even inside a run() callback.
 const RSC_CONTEXT_KEY = Symbol.for("rangojs-router:rsc-context");
-export const RSCRouterContext: AsyncLocalStorage<HelperContext> = ((
+export const RangoContext: AsyncLocalStorage<HelperContext> = ((
   globalThis as any
 )[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage<HelperContext>());
 
+/** shortCode prefix letter per entry type (e.g. "L0", "R2", "M1C0"). */
+const SHORT_CODE_PREFIX: Record<
+  "layout" | "parallel" | "route" | "loader" | "cache",
+  string
+> = {
+  layout: "L",
+  parallel: "P",
+  route: "R",
+  loader: "D",
+  cache: "C",
+};
+
+/** Post-increment a named per-store counter, returning the prior value. */
+function bumpCounter(store: HelperContext, key: string): number {
+  store.counters[key] ??= 0;
+  return store.counters[key]++;
+}
+
 export const getContext = (): {
   context: AsyncLocalStorage<HelperContext>;
   getStore: () => HelperContext;
@@ -330,12 +407,12 @@ export const getContext = (): {
     callback: (...args: any[]) => T,
   ) => T;
 } => {
-  const context = RSCRouterContext;
+  const context = RangoContext;
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
-      let store = RSCRouterContext.getStore();
+      let store = RangoContext.getStore();
       if (!store) {
         store = {
           manifest: new Map<string, EntryData>(),
@@ -355,7 +432,7 @@ export const getContext = (): {
       const store = context.getStore();
       if (!store) {
         throw new Error(
-          "RSC Router context store is not available. Make sure to run within RSC Router context.",
+          "Rango context store is not available. Make sure to run within Rango context.",
         );
       }
       return store;
@@ -372,29 +449,17 @@ export const getContext = (): {
       type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
-      store.counters[type] ??= 0;
-      const index = store.counters[type];
-      store.counters[type] = index + 1;
-      return `$${type}.${index}`;
+      invariant(store, "No context RangoContext available");
+      return `$${type}.${bumpCounter(store, type)}`;
     },
     getShortCode: (
       type: "layout" | "parallel" | "route" | "loader" | "cache",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
+      invariant(store, "No context RangoContext available");
 
       const parent = store.parent;
-      const prefix =
-        type === "layout"
-          ? "L"
-          : type === "parallel"
-            ? "P"
-            : type === "loader"
-              ? "D"
-              : type === "cache"
-                ? "C"
-                : "R";
+      const prefix = SHORT_CODE_PREFIX[type];
       const mountPrefix =
         store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
 
@@ -405,10 +470,7 @@ export const getContext = (): {
         const counterKey = mountPrefix
           ? `${mountPrefix}_root_${type}`
           : `root_${type}`;
-        store.counters[counterKey] ??= 0;
-        const index = store.counters[counterKey];
-        store.counters[counterKey] = index + 1;
-        return `${mountPrefix}${prefix}${index}`;
+        return `${mountPrefix}${prefix}${bumpCounter(store, counterKey)}`;
       } else {
         // Child entry: use parent-scoped counter with includeScope appended.
         // When we're evaluating a lazy include's direct children, includeScope
@@ -416,10 +478,7 @@ export const getContext = (): {
         // parent's counter namespace so routes inside one include cannot
         // collide with siblings declared outside it.
         const counterKey = `${parent.shortCode}${includeScope}_${type}`;
-        store.counters[counterKey] ??= 0;
-        const index = store.counters[counterKey];
-        store.counters[counterKey] = index + 1;
-        return `${parent.shortCode}${includeScope}${prefix}${index}`;
+        return `${parent.shortCode}${includeScope}${prefix}${bumpCounter(store, counterKey)}`;
       }
     },
     runWithStore: <T>(
@@ -436,6 +495,7 @@ export const getContext = (): {
           counters: store.counters,
           forRoute: store.forRoute,
           mountIndex: store.mountIndex,
+          routerId: store.routerId,
           metrics: store.metrics,
           isSSR: store.isSSR,
           patterns: store.patterns,
@@ -447,6 +507,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,
       );
@@ -475,6 +538,7 @@ export const getContext = (): {
           counters,
           forRoute: store?.forRoute,
           mountIndex: store?.mountIndex,
+          routerId: store?.routerId,
           metrics: store?.metrics,
           isSSR: store?.isSSR,
           patterns,
@@ -493,6 +557,31 @@ export const getContext = (): {
   };
 };
 
+/**
+ * Acquire the active DSL build context, throwing `message` if a helper was
+ * called outside a urls()/map() builder. Returns the store API and the live
+ * HelperContext so callers avoid a second getContext() lookup.
+ */
+export function requireDslContext(message: string): {
+  store: ReturnType<typeof getContext>;
+  ctx: HelperContext;
+} {
+  const store = getContext();
+  const ctx = store.context.getStore();
+  if (!ctx) {
+    // The only reason the store is absent here is that a route-definition helper
+    // ran with no active RangoContext — i.e. outside a urls()/map() builder.
+    // Record that as the cause so the throw is self-explanatory, not a bare
+    // "must be called inside urls()" with no indication of the mechanism.
+    throw new DslContextError(message, {
+      cause:
+        "RangoContext store is undefined: a route-definition helper was called " +
+        "outside an active urls()/map() builder.",
+    });
+  }
+  return { store, ctx };
+}
+
 /**
  * Run a callback with specific URL and name prefixes
  * Used by include() to apply prefixes to nested patterns
@@ -502,7 +591,7 @@ export function runWithPrefixes<T>(
   namePrefix: string | undefined,
   callback: () => T,
 ): T {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   if (!store) {
     throw new Error("runWithPrefixes must be called within router context");
   }
@@ -547,7 +636,7 @@ export function runWithPrefixes<T>(
         ? (store.rootScoped ?? false)
         : store.rootScoped;
 
-  return RSCRouterContext.run(
+  return RangoContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
@@ -562,7 +651,7 @@ export function runWithPrefixes<T>(
  * Get current URL prefix from context
  */
 export function getUrlPrefix(): string {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.urlPrefix || "";
 }
 
@@ -570,7 +659,7 @@ export function getUrlPrefix(): string {
  * Get current name prefix from context
  */
 export function getNamePrefix(): string | undefined {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.namePrefix;
 }
 
@@ -579,10 +668,32 @@ export function getNamePrefix(): string | undefined {
  * Returns true at root or inside { name: "" } includes, false inside named includes.
  */
 export function getRootScoped(): boolean {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.rootScoped ?? true;
 }
 
+/**
+ * Stamp build-time scope identity onto a Static() definition at mount time.
+ * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
+ * evaluation scope and used to iterate the registry first-non-null, so these
+ * are the ONLY reliable carriers of the def's owning router, root-scope, and
+ * full route name — a name-keyed registry lookup at bake time reproduces the
+ * cross-router collision #757/#762 fixed (and the collector's historical
+ * `$$routePrefix` argument is a name PREFIX, which the root-scope registry
+ * never contains, silently degrading to the dot-heuristic).
+ * A definition mounted more than once is stamped each time; the last mount wins.
+ */
+export function stampStaticDefScope(
+  handler: unknown,
+  routeName?: string,
+): void {
+  const store = RangoContext.getStore();
+  const def = handler as Record<string, unknown>;
+  if (routeName !== undefined) def.$$routeName = routeName;
+  def.$$rootScoped = getRootScoped();
+  if (store?.routerId !== undefined) def.$$routerId = store.routerId;
+}
+
 // Export HelperContext type for use in other modules
 export type { HelperContext };
 
@@ -676,7 +787,7 @@ export function getParallelSlotCount(
  * ```
  */
 export function track(label: string, depth?: number): () => void {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
   if (!store?.metrics?.enabled) {
@@ -699,25 +810,50 @@ export function track(label: string, depth?: number): () => void {
 
 /**
  * Separate ALS for tracking loader execution scope.
- * Uses a dedicated ALS (not RSCRouterContext) to avoid issues with
- * nested RSCRouterContext.run() calls in Vite's module runner.
+ * Uses a dedicated ALS (not RangoContext) to avoid issues with
+ * nested RangoContext.run() calls in Vite's module runner.
  */
 const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
 const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
   globalThis as any
 )[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
 
+// Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
+// of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
+// invoked via ctx.use). Consulted by isInsideCacheScope() to exempt
+// request-scoped reads, by getCurrentLoaderBodyId() for guard-warning
+// attribution, and by isInsideHandlerInvokedLoaderBody() for the
+// consumption-lane rule (the shell-capture guard exemption). It deliberately
+// does NOT affect isInsideLoaderScope(), so rendered()/barrier/deadlock
+// gating (which must distinguish DSL from handler-invoked loaders) is
+// unchanged.
+const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
+const loaderBodyScopeALS: AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}> = ((globalThis as any)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}>());
+
 /**
  * Check if the current execution is inside a cache() DSL boundary.
  * Returns false inside loader execution — loaders are always fresh
  * (never cached), so non-cacheable reads are safe.
  */
 export function isInsideCacheScope(): boolean {
-  if (RSCRouterContext.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;
+  if (RangoContext.getStore()?.insideCacheScope !== true) return false;
+  // 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;
 }
 
@@ -730,6 +866,159 @@ 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 };
+  }
+}
+
+/**
+ * Clear the ppr header-write latch for the remainder of this render (issue
+ * #735). Called by ctx.dynamic(): a dynamic() render opts off the SHELL axis
+ * (rsc-rendering.ts skips both the HIT commit and the MISS capture on
+ * `_dynamic`), so it is ALWAYS live — every request re-runs the handler and its
+ * header write lands identically each time. The guard's reason to forbid it
+ * (MISS/HIT divergence) evaporates, so the write is re-permitted.
+ *
+ * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
+ * axis. Two cases:
+ * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
+ * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
+ *   funnel top (first-wins), which MASKS the positional cache() latch, but the
+ *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
+ *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
+ *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
+ *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ *
+ * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
+ * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the
+ * field is undefined again once cleared). No-op when there is no funnel store or
+ * no ppr latch (dynamic() from middleware runs outside the funnel Store.run
+ * scope, so nothing is latched — the middleware exemption is unchanged).
+ */
+export function clearPprHeaderScope(): void {
+  const store = RangoContext.getStore();
+  if (store?.cachedHeaderScope?.kind !== "ppr") return;
+  store.cachedHeaderScope = store.insideCacheScope
+    ? { kind: "cache", routeKey: store.cachedHeaderScope.routeKey }
+    : undefined;
+}
+
+/**
+ * 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 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).
+ * A ctx.dynamic() render clears the ppr latch (clearPprHeaderScope, #735) so
+ * its always-live handler header writes are re-permitted. 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;
+  // 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). isInsideAnyLoaderScope
+  // (broad) labels a now-throwing handler-invoked loader body "loader".
+  const fullSurface =
+    surfaceProp === undefined ? surface : `${surface}.${String(surfaceProp)}()`;
+  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 =
+    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(
+    `${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
@@ -738,3 +1027,75 @@ export function isInsideLoaderScope(): boolean {
 export function runInsideLoaderScope<T>(fn: () => T): T {
   return loaderScopeALS.run({ active: true }, fn);
 }
+
+/**
+ * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
+ * cache-purity guard only (isInsideCacheScope), WITHOUT affecting
+ * isInsideLoaderScope()/rendered() gating. Applied to every loader body (DSL
+ * and handler-invoked via ctx.use) so request-scoped reads inside a loader
+ * never trip the cache-scope guards — loaders always run fresh.
+ */
+export function runInsideLoaderBodyScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  handlerInvoked?: boolean,
+): T {
+  return loaderBodyScopeALS.run({ active: true, loaderId, handlerInvoked }, fn);
+}
+
+/**
+ * The $$id of the loader whose body is currently executing, or undefined
+ * outside any loader body. Used by the shell-capture identity guard
+ * (cookie-store.ts) so its refusal warning can name the loader that read
+ * cookies()/headers() instead of blaming a lane it cannot see — the old
+ * hardcoded "bake-lane loader" text misled a live-lane debugging session
+ * (issue #672, secondary).
+ */
+export function getCurrentLoaderBodyId(): string | undefined {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
+
+/**
+ * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
+ * handler, not the DSL segment funnel) is executing. The consumption-lane
+ * rule keys off this: handler consumption yields a BAKED copy in every shared
+ * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
+ * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
+ * like the cache-purity guards do. DSL segment loaders (live lane masked at
+ * capture, bake lane guarded) never set the flag.
+ */
+export function isInsideHandlerInvokedLoaderBody(): boolean {
+  return loaderBodyScopeALS.getStore()?.handlerInvoked === true;
+}
+
+// Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).
+// A push callback's value is stored as-is; if it is a promise it is NOT tracked
+// by handleStore.settled and does not block segment resolution, so a
+// ctx.use(loader) made from inside such a callback can never form a rendered()
+// deadlock. This is an ALS (not a plain boolean) so the exemption survives the
+// callback's own awaits — an async push callback that resumes after `await`
+// still reads as "inside a push callback" and stays out of the deadlock guard.
+const PUSH_CALLBACK_SCOPE_KEY = Symbol.for(
+  "rangojs-router:push-callback-scope",
+);
+const pushCallbackScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+
+/**
+ * Check if the current execution is inside a handle push callback (sync or an
+ * async callback's continuation). Used by the handler-to-loader deadlock guard
+ * to exempt push-callback continuations.
+ */
+export function isInsidePushCallbackScope(): boolean {
+  return pushCallbackScopeALS.getStore()?.active === true;
+}
+
+/**
+ * Run `fn` inside a push-callback scope. Wraps the invocation of a handle push
+ * callback so that any ctx.use(loader) it makes — including after one of its own
+ * awaits — is exempt from the deadlock guard.
+ */
+export function runInsidePushCallbackScope<T>(fn: () => T): T {
+  return pushCallbackScopeALS.run({ active: true }, fn);
+}