@rangojs/router 0.17.0 → 0.19.0

package/src/browser/transition-when.ts

@@ -0,0 +1,205 @@
+/**
+ * Browser-side transition({ when }) decisions.
+ *
+ * A navigation is decided ONCE, at the first commit that presents its
+ * destination: the canonical commit for a server route, the optimistic swap
+ * for a clientUrls() cross-route navigation (the canonical commit then reuses
+ * the decision carried on its transaction), the history-cache restore or
+ * refetch commit for back/forward, the action commit (error lane included).
+ *
+ * The decision is navigation-wide: every distinct predicate (by function
+ * identity) declared by a committed segment, kept or re-sent (#989), runs, and
+ * any false gates the whole navigation off. It never changes the rendered
+ * tree's shape: every segment keeps its key and its <ViewTransition> element
+ * (segment-system.tsx renders each class "none"), and the commit is urgent
+ * instead of held (partial-update.ts). That is what keeps component state
+ * across when true -> false -> true (#995). A response carries no decision,
+ * so a reused prefetch is decided against the real source.
+ */
+
+import type {
+  ResolvedSegment,
+  RouteLocation,
+  TransitionWhenContext,
+  TransitionWhenFn,
+  TransitionWhenKind,
+} from "../types/segments.js";
+import { resolveTransitionWhen } from "../transition-when-ref.js";
+import { makeIsAction } from "../router/is-action.js";
+import { isInterceptSegment } from "./intercept-utils.js";
+import type { NavigationStore } from "./types.js";
+
+/** One side of the navigation before it is frozen into a RouteLocation. */
+export interface RouteLocationInput {
+  url: string | URL;
+  params?: Readonly<Record<string, string>>;
+  routeName?: string;
+  state?: unknown;
+}
+
+/** The action fields of a `kind: "action"` context. */
+export interface TransitionWhenActionInput {
+  id?: string;
+  formData?: FormData;
+  result?: unknown;
+  error?: unknown;
+}
+
+export interface TransitionDecisionInput {
+  kind: TransitionWhenKind;
+  from: RouteLocationInput;
+  /** The destination; ignored for "action" and "revalidate" (`to` is `from`). */
+  to?: RouteLocationInput;
+  action?: TransitionWhenActionInput;
+}
+
+const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({});
+
+function createRouteLocation(input: RouteLocationInput): RouteLocation {
+  return Object.freeze({
+    // A fresh URL: a predicate may not mutate the store's or the caller's.
+    url: new URL(
+      String(input.url),
+      typeof window !== "undefined"
+        ? window.location.href
+        : "http://localhost/",
+    ),
+    params: input.params ? Object.freeze({ ...input.params }) : EMPTY_PARAMS,
+    routeName: input.routeName,
+    state: input.state,
+  });
+}
+
+export function createTransitionWhenContext(
+  input: TransitionDecisionInput,
+): TransitionWhenContext {
+  const from = createRouteLocation(input.from);
+  const inAction = input.kind === "action";
+  const { id, formData, result, error } = input.action ?? {};
+  return Object.freeze({
+    kind: input.kind,
+    from,
+    to:
+      inAction || input.kind === "revalidate" || !input.to
+        ? from
+        : createRouteLocation(input.to),
+    isAction: makeIsAction(id, inAction),
+    ...(inAction && { action: Object.freeze({ id, formData, result, error }) }),
+  });
+}
+
+/**
+ * Run one predicate. A throw counts as false (the navigation does not hold)
+ * and is logged; it never fails the navigation.
+ */
+export function evaluateTransitionWhen(
+  fn: TransitionWhenFn,
+  ctx: TransitionWhenContext,
+): boolean {
+  try {
+    return fn(ctx) !== false;
+  } catch (error) {
+    console.error(
+      "[rango] transition({ when }) threw; the navigation does not hold.",
+      error,
+    );
+    return false;
+  }
+}
+
+/** Distinct predicates of the segments that declare one, in segment order. */
+export function collectTransitionWhens(
+  segments: readonly ResolvedSegment[],
+): Set<TransitionWhenFn> {
+  const fns = new Set<TransitionWhenFn>();
+  for (const segment of segments) {
+    const fn = resolveTransitionWhen(segment.transition?.when);
+    if (fn) fns.add(fn);
+  }
+  return fns;
+}
+
+/**
+ * Decide a commit: true when the navigation is gated off (some predicate
+ * returned false or threw). The context is built only when a predicate runs.
+ * An intercept commit is not evaluated: it never holds or animates
+ * (partial-update.ts shouldStartViewTransition). `extra` is a predicate not on
+ * a segment yet (the optimistic clientUrls() destination).
+ */
+export function decideTransitionGatedOff(
+  segments: readonly ResolvedSegment[],
+  input: () => TransitionDecisionInput,
+  extra?: TransitionWhenFn,
+): boolean {
+  if (segments.some(isInterceptSegment)) return false;
+  const fns = collectTransitionWhens(segments);
+  if (extra) fns.add(extra);
+  if (fns.size === 0) return false;
+  const ctx = createTransitionWhenContext(input());
+  for (const fn of fns) if (!evaluateTransitionWhen(fn, ctx)) return true;
+  return false;
+}
+
+/** Merge route params the way popstate restores them (per-segment params). */
+export function mergeSegmentParams(
+  segments: readonly ResolvedSegment[],
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  for (const s of segments) if (s.params) Object.assign(params, s.params);
+  return params;
+}
+
+export interface CommitDecision {
+  /** Newer params / route name for the committed location (an action response's). */
+  from?: { params?: Record<string, string>; routeName?: string };
+  /** The destination, from the committed location; omit for "action" / "revalidate". */
+  to?: (from: RouteLocationInput) => RouteLocationInput;
+  action?: TransitionWhenActionInput;
+  extra?: TransitionWhenFn;
+}
+
+/**
+ * decideTransitionGatedOff with `from` read from the store: call it before
+ * the commit moves the store. `state` is the live history.state, except for
+ * back/forward: at popstate history.state already belongs to the destination,
+ * so the entry being left comes from the store's per-entry memory (undefined
+ * after a reload, never guessed).
+ */
+export function decideCommitGatedOff(
+  store: NavigationStore,
+  segments: readonly ResolvedSegment[],
+  kind: TransitionWhenKind,
+  decision: CommitDecision = {},
+): boolean {
+  return decideTransitionGatedOff(
+    segments,
+    () => {
+      const memory = store.getHistoryEntryMemory();
+      const from: RouteLocationInput = {
+        url: store.getSegmentState().currentUrl || window.location.href,
+        params:
+          decision.from?.params ??
+          mergeSegmentParams(
+            store.getCachedSegments(store.getHistoryKey())?.segments ?? [],
+          ),
+        routeName: decision.from?.routeName ?? memory?.routeName,
+        state: kind === "pop" ? memory?.state : window.history.state,
+      };
+      return {
+        kind,
+        from,
+        to: decision.to?.(from),
+        action: decision.action,
+      };
+    },
+    decision.extra,
+  );
+}
+
+/** The FormData argument a server action was called with, if any. */
+export function findActionFormData(
+  args: readonly unknown[],
+): FormData | undefined {
+  if (typeof FormData === "undefined") return undefined;
+  return args.find((arg): arg is FormData => arg instanceof FormData);
+}

package/src/browser/types.ts

@@ -48,6 +48,12 @@ export interface RscMetadata {
   resolvedIds?: string[];
   /** Merged route params from the matched route */
   params?: Record<string, string>;
+  /**
+   * The matched route's name (include name prefix applied), when the route is
+   * named. The browser keeps it per history entry for transition({ when })'s
+   * `from.routeName` / `to.routeName` (browser/transition-when.ts).
+   */
+  routeName?: string;
   /**
    * State of named slots for this route match
    * Key is slot name (e.g., "@modal"), value is slot state
@@ -276,6 +282,18 @@ export interface SegmentState {
   currentSegmentIds: string[];
 }
 
+/**
+ * What the router remembers about one history entry for transition({ when })
+ * (NavigationStore.rememberDisplayedEntry).
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface HistoryEntryMemory {
+  readonly routeName: string | undefined;
+  /** The entry's `history.state` as last recorded. */
+  readonly state: unknown;
+}
+
 /**
  * Navigation update emitted when UI should re-render
  *
@@ -296,13 +314,67 @@ export interface NavigationUpdate {
 }
 
 /**
- * State value for navigate/Link
- * - LocationStateEntry[]: Type-safe state entries (recommended)
- * - unknown: Plain state format (object or getter function)
+ * Plain object accepted as {@link PlainHistoryState}. The `any` string index
+ * admits interface-typed values (an `unknown` index would reject interfaces,
+ * which carry no implicit index signature). The `never` members reject:
+ * - a single typed entry (`GridState(value)` without the array) — its
+ *   `__rsc_ls_*` fields would be spread onto history.state and
+ *   `useLocationState(GridState)` would read `undefined`;
+ * - functions, including a location-state definition passed uncalled
+ *   (`Symbol.hasInstance` comes from `Function.prototype`), which throw
+ *   `DataCloneError`;
+ * - arrays and other iterables (`Symbol.iterator`), so an array must match the
+ *   typed-entry or plain-array member instead;
+ * - built-ins tagged with `Symbol.toStringTag` (`Promise`, `WeakMap`,
+ *   `WeakSet`), which throw `DataCloneError`. The cloneable tagged ones
+ *   (`Map`, `Set`, `ArrayBuffer`, typed arrays) have their own members.
+ *
+ * Members are not checked: a function, symbol, or React element inside a
+ * plain object still compiles, as does a top-level `ReactElement` or DOM node
+ * (an object with none of the keys above).
+ */
+export interface PlainHistoryObject {
+  readonly [key: string]: any;
+  readonly __rsc_ls_key?: never;
+  readonly __rsc_ls_value?: never;
+  readonly __rsc_ls_lazy?: never;
+  readonly [Symbol.iterator]?: never;
+  readonly [Symbol.hasInstance]?: never;
+  readonly [Symbol.toStringTag]?: never;
+}
+
+/**
+ * Plain (untyped) navigation state, stored under `history.state.state` and
+ * read with `useLocationState<T>()`. A structured-clone-safe value: primitives,
+ * arrays, `Map`/`Set`, `ArrayBuffer`, typed arrays, and plain objects. Excludes
+ * functions, symbols, `Promise`/`WeakMap`/`WeakSet`, and objects carrying
+ * `__rsc_ls_*` keys (a typed entry passed without its array). Arrays, `Map`,
+ * and `Set` are checked element by element; plain object members are not
+ * checked (see {@link PlainHistoryObject}).
+ */
+export type PlainHistoryState =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | readonly PlainHistoryState[]
+  | ReadonlyMap<PlainHistoryState, PlainHistoryState>
+  | ReadonlySet<PlainHistoryState>
+  | ArrayBuffer
+  | ArrayBufferView
+  | PlainHistoryObject;
+
+/**
+ * State value for `router.push()` / `router.replace()` / `<Link state>`.
+ * - `readonly LocationStateEntry[]`: typed entries from `createLocationState()`
+ *   definitions, e.g. `[GridState({ count: 3 })]` (recommended)
+ * - {@link PlainHistoryState}: plain structured-clone-safe state
  */
 export type HistoryState =
-  | import("./react/location-state-shared.js").LocationStateEntry[]
-  | unknown;
+  | readonly import("./react/location-state-shared.js").LocationStateEntry[]
+  | PlainHistoryState;
 
 /**
  * Options for navigation operations
@@ -329,6 +401,22 @@ export interface NavigateOptions {
    * ```
    */
   revalidate?: boolean;
+  /**
+   * Set to `false` to present this navigation without a transition: the
+   * commit is urgent and every `<ViewTransition>` class resolves to `"none"`,
+   * the same result as a `transition({ when })` predicate returning `false`.
+   * No `when` predicate is called. Back/forward, action and revalidation
+   * commits are unaffected (they are not started by this call).
+   *
+   * @default true (the route's transition config applies)
+   *
+   * @example
+   * ```tsx
+   * router.push("/photos/2", { transition: false });
+   * <Link to="/photos/2" transition={false}>Next</Link>
+   * ```
+   */
+  transition?: boolean;
   /**
    * State to pass to history.pushState/replaceState
    * Accessible via useLocationState() hook.
@@ -350,15 +438,25 @@ export interface NavigateOptions {
    * // Plain static state
    * navigate("/product", { state: { from: "list" } });
    *
-   * // Plain just-in-time state
-   * navigate("/product", { state: () => ({ from: window.location.pathname }) });
+   * // Compile errors (and a dev-mode runtime error for untyped callers):
+   * navigate("/product", { state: ProductState(p) }); // entry without the array
+   * navigate("/product", { state: [ProductState] }); // definition not called
    * ```
    */
   state?: HistoryState;
 }
 
-/** @internal Extended options used only within the navigation bridge */
-export interface NavigateOptionsInternal extends NavigateOptions {
+/**
+ * @internal Extended options used only within the navigation bridge. `state`
+ * is widened to `unknown`: the redirect lanes pass state already resolved to
+ * a flat `history.state` record, and in dev Link passes an uncalled
+ * definition through to resolveNavigationState's check.
+ */
+export interface NavigateOptionsInternal extends Omit<
+  NavigateOptions,
+  "state"
+> {
+  state?: unknown;
   /** Skip segment cache (used by redirect-with-state to force re-render) */
   _skipCache?: boolean;
 }
@@ -465,6 +563,22 @@ export interface NavigationStore {
   // History-based segment cache (for back/forward navigation and partial merging)
   getHistoryKey(): string;
   setHistoryKey(key: string): void;
+
+  /**
+   * Per-history-entry memory for transition({ when }) sources: record the
+   * entry on screen (keyed by its `history.state.key`) with its current
+   * `history.state` and, when given, its route name (kept from the last
+   * record otherwise; every push/replace creates a new key, so a stale name
+   * never carries to another entry). Called after every commit, restore and
+   * state merge.
+   */
+  rememberDisplayedEntry(routeName?: string): void;
+  /**
+   * The memory of the entry on screen, or of `entryKey`. At popstate
+   * history.state already belongs to the destination, so back/forward reads
+   * the entry being LEFT from here. In-memory only: empty after a reload.
+   */
+  getHistoryEntryMemory(entryKey?: string): HistoryEntryMemory | undefined;
   /** Monotonic token of the most recently committed navigation. */
   getNavInstance(): number;
   cacheSegmentsForHistory(
@@ -631,7 +745,7 @@ export interface ServerActionBridgeConfig {
  * Navigation bridge for handling client-side navigation
  */
 export interface NavigationBridge {
-  navigate(url: string, options?: NavigateOptions): Promise<void>;
+  navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;

package/src/build/generate-manifest.ts

@@ -11,12 +11,20 @@
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems } from "../route-types.js";
 import { extractStaticPrefix } from "../router/pattern-matching.js";
-import { RangoContext, runWithPrefixes } from "../server/context.js";
+import {
+  getParallelSlotEntries,
+  RangoContext,
+  runWithPrefixes,
+} from "../server/context.js";
 import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
 import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
+import {
+  createTransitionWhenError,
+  transitionWhenProblem,
+} from "../transition-when-ref.js";
 import {
   isIncludeProvider,
   resolveIncludeModule,
@@ -59,6 +67,57 @@ export interface GeneratedManifest {
   routeSearchSchemas?: Record<string, Record<string, string>>;
 }
 
+/**
+ * Fail discovery on an invalid transition({ when }) anywhere in the entry
+ * chains of the evaluated routes: the route itself, its ancestors, their
+ * orphan layouts, parallel slots and intercepts. Strict: a plain function is
+ * rejected, because discovery evaluates the tree in the react-server graph
+ * where a "use client" import is a client reference (transition-when-ref.ts).
+ * The error names the first route found through the entry.
+ */
+function validateTransitionWhens(
+  manifest: Map<string, EntryData>,
+  patterns: Map<string, string>,
+): void {
+  const seen = new Set<object>();
+  for (const [routeName, routeEntry] of manifest) {
+    const route = {
+      routeName,
+      pattern:
+        patterns.get(routeName) ??
+        (routeEntry.type === "route" ? routeEntry.pattern : undefined),
+    };
+    const check = (when: unknown, entryType: string): void => {
+      const problem = transitionWhenProblem(when, true);
+      if (problem) {
+        throw createTransitionWhenError(when, problem, {
+          ...route,
+          entryType,
+        });
+      }
+    };
+    const visit = (entry: EntryData): void => {
+      if (seen.has(entry)) return;
+      seen.add(entry);
+      check(entry.transition?.when, entry.type);
+      for (const orphan of entry.layout) visit(orphan);
+      for (const { entry: slot } of getParallelSlotEntries(entry.parallel)) {
+        visit(slot);
+      }
+      for (const intercept of entry.intercept) {
+        check(intercept.transition?.when, "intercept");
+      }
+    };
+    for (
+      let entry: EntryData | null | undefined = routeEntry;
+      entry;
+      entry = entry.parent ?? entry.orphanOwner
+    ) {
+      visit(entry);
+    }
+  }
+}
+
 /**
  * Build prefix tree node by running the patterns with proper context.
  * Uses a visited set to detect circular includes and prevent infinite recursion.
@@ -116,6 +175,7 @@ async function buildPrefixTreeNode(
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
   routerId?: string,
+  validateTransitionWhen?: boolean,
 ): Promise<PrefixTreeNode> {
   // Resolve an async include provider (`() => import("./routes")`) so its routes
   // are walked into the build-time manifest/types/href. Runtime matching still
@@ -174,6 +234,8 @@ async function buildPrefixTreeNode(
       },
     );
 
+    if (validateTransitionWhen) validateTransitionWhens(manifest, patternsMap);
+
     // Collect route names defined in this include (routes have prefixes applied)
     const routes = [...patternsMap.keys()];
     Object.assign(routeManifest, Object.fromEntries(patternsMap));
@@ -230,6 +292,7 @@ async function buildPrefixTreeNode(
         responseTypeRoutes,
         routeSearchSchemas,
         routerId,
+        validateTransitionWhen,
       ),
     );
 
@@ -313,6 +376,14 @@ export async function generateManifestFull<TEnv>(
      * EntryData map built below is local; this is the only seam that surfaces it.
      */
     collectClientFallbackRef?: (refKey: string) => void;
+    /**
+     * Fail on an invalid transition({ when }): a non-function, or a plain
+     * (server) function where a client reference is required. Only the Vite
+     * plugin's discovery passes it: it evaluates the tree in the react-server
+     * graph, the one place a "use client" import is told apart from a server
+     * function (transition-when-ref.ts).
+     */
+    validateTransitionWhen?: boolean;
   },
 ): Promise<FullManifest> {
   const routeManifest: Record<string, string> = {};
@@ -351,6 +422,10 @@ export async function generateManifestFull<TEnv>(
     },
   );
 
+  if (options?.validateTransitionWhen) {
+    validateTransitionWhens(manifest, patternsMap);
+  }
+
   // Surface the "use client" components registered as error/notFound fallbacks
   // (route-tree errorBoundary()/notFoundBoundary() helpers, stored on EntryData).
   // The boundary may be a handler function and/or wrap the client boundary in
@@ -413,6 +488,7 @@ export async function generateManifestFull<TEnv>(
       responseTypeRoutes,
       routeSearchSchemas,
       options?.routerId,
+      options?.validateTransitionWhen,
     ),
   );
 

package/src/cache/background-task.ts

@@ -1,8 +1,10 @@
 /**
  * Background Task Runner
  *
- * Unified helper for scheduling async work via waitUntil.
- * When waitUntil is unavailable, falls back to blocking or skipping.
+ * Unified helper for scheduling async work via waitUntil, and the two bounded
+ * waits the PPR shell capture puts on background work (raceDeadline,
+ * settleGrowing). When waitUntil is unavailable, falls back to blocking or
+ * skipping.
  */
 
 interface WaitUntilHost {
@@ -32,3 +34,54 @@ export function runBackground(
     return task();
   }
 }
+
+/**
+ * Race `work` against an absolute deadline (epoch ms), keeping its value. The
+ * losing work is not cancelled (a router match has no abort signal) and its
+ * late rejection is swallowed. The timer is unref'd, so a pending deadline
+ * never keeps a Node dev process alive.
+ */
+export async function raceDeadline<T>(
+  work: Promise<T>,
+  deadline: number,
+): Promise<{ done: true; value: T } | { done: false }> {
+  work.catch(() => {});
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<{ done: false }>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ done: false }),
+      Math.max(0, deadline - Date.now()),
+    );
+    (timer as { unref?: () => void }).unref?.();
+  });
+  try {
+    return await Promise.race([
+      work.then((value) => ({ done: true as const, value })),
+      expired,
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Wait until every promise in `list` has settled, including ones appended
+ * while waiting (a settled write can schedule a nested one: cacheRoute
+ * schedules its store.set in a second waitUntil), or until `deadline` (epoch
+ * ms). Resolves true when the list drained, false at the deadline. Never
+ * mutates `list`: a later call waits for what is still pending.
+ */
+export async function settleGrowing(
+  list: readonly Promise<unknown>[],
+  deadline: number,
+): Promise<boolean> {
+  let seen = 0;
+  while (list.length > seen) {
+    if (Date.now() >= deadline) return false;
+    const batch = list.slice(seen);
+    seen = list.length;
+    const settled = await raceDeadline(Promise.allSettled(batch), deadline);
+    if (!settled.done) return false;
+  }
+  return true;
+}

package/src/cache/cache-exec-scope.ts

@@ -38,6 +38,53 @@ export interface CacheExecScope {
 
 const cacheExecStorage = new AsyncLocalStorage<CacheExecScope>();
 
+// Global key: the value must survive HMR re-evaluation of this module, like
+// the other request-scoped ALS instances (server/context.ts RangoContext).
+const IDENTITY_EXEMPT_KEY = Symbol.for("rangojs-router:identity-exempt");
+const identityExemptStorage: AsyncLocalStorage<boolean> = ((globalThis as any)[
+  IDENTITY_EXEMPT_KEY
+] ??= new AsyncLocalStorage<boolean>());
+
+/**
+ * Run a callback whose identity reads never reach a shared entry, so
+ * guardIdentityRead (server/context.ts) lets them through and records
+ * nothing (#976):
+ *
+ * - a cache's own decisions and metadata: a `key()`, a store `keyGenerator`
+ *   (cache-policy.ts resolveCacheKey), a `condition()` (cache-scope.ts
+ *   conditionAllows, loader-cache.ts) and a `tags()` function
+ *   (cache-policy.ts resolveTagsOption). The value picks the entry, whether
+ *   one is used, or how it is invalidated; it is never rendered. Reading the
+ *   request there is the documented way to partition an entry;
+ * - the router's `onError` (router/error-handling.ts invokeOnError): it
+ *   observes, and a render error can reach it inside a capture or a cached
+ *   scope.
+ *
+ * Scar: a ppr capture resolves its doc record key, and the record's tags,
+ * again under the capture context; once `ctx.request.headers` was guarded, a
+ * keyGenerator or tags() reading it refused every capture of the route.
+ *
+ * The exemption is async-local, so it would follow everything the callback
+ * starts. A "use cache" body (runWithCacheExecScope), a loader body
+ * (server/context.ts runInsideLoaderBodyScope) and a segment funnel
+ * (getContext().runWithStore) end it on entry (endIdentityExempt). Scar: a
+ * key() that awaited a "use cache" function reading cookies() stored the
+ * first visitor's cookie and served it to the next.
+ */
+export function runIdentityExempt<T>(fn: () => T): T {
+  return identityExemptStorage.run(true, fn);
+}
+
+/** True inside runIdentityExempt, and not in a scope started from it. */
+export function isInsideIdentityExempt(): boolean {
+  return identityExemptStorage.getStore() === true;
+}
+
+/** Run `fn` with the identity exemption ended (see runIdentityExempt). */
+export function endIdentityExempt<T>(fn: () => T): T {
+  return isInsideIdentityExempt() ? identityExemptStorage.run(false, fn) : fn();
+}
+
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.
@@ -48,7 +95,7 @@ export function runWithCacheExecScope<T>(
   fn: () => T,
   scope: CacheExecScope = createCacheExecScope(),
 ): T {
-  return cacheExecStorage.run(scope, fn);
+  return endIdentityExempt(() => cacheExecStorage.run(scope, fn));
 }
 
 /** A scope nested in the calling chain's current one, if any. */