@rangojs/router 0.19.0 → 0.19.1

package/dist/types/cache/cache-exec-scope.d.ts

@@ -30,6 +30,12 @@
  */
 export interface CacheExecScope {
     readonly parent?: CacheExecScope;
+    /**
+     * Loader values its chain read through an already-started execution, to
+     * their loader ids (cache-tag.ts readStartedLoaderValue), checked again
+     * before its write (#1011).
+     */
+    loaderReads?: Map<object, string>;
 }
 /**
  * Run a callback whose identity reads never reach a shared entry, so

package/dist/types/cache/cache-tag.d.ts

@@ -10,7 +10,8 @@
  * profile/DSL tags before storing.
  */
 import { type RequestContext } from "../server/request-context.js";
-import { type LoaderIdentityRead } from "../server/context.js";
+import { type LoaderIdentityRead, type LoaderRunIdentity } from "../server/context.js";
+import { type CacheExecScope } from "./cache-exec-scope.js";
 import type { ExecutionStart } from "./tag-invalidation.js";
 /**
  * Call `fn` outside any "use cache" tag scope: detached work a cached body
@@ -153,6 +154,28 @@ export declare function markIdentityRead(set: Set<string>, read: LoaderIdentityR
  * recorded, nearest first (breadth-first, so the execution's own read wins).
  */
 export declare function recordedIdentityRead(root: Set<string>): LoaderIdentityRead | undefined;
+/**
+ * `value` is the promise of the execution `run` records, started by the
+ * current execution (if any), which reads it. Both loader runners call it
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction).
+ */
+export declare function trackLoaderRun(value: object, run: LoaderRunIdentity): void;
+/**
+ * A ctx.use(Loader) or getRequestContext().use(Loader) read that returns an
+ * already-started value (the request memo, a loader cache() binding's value).
+ * The current loader execution, if any, links it (it reads the value).
+ * Inside a "use cache" body the value is refused when its execution read
+ * request identity, as a body entered there would have been
+ * (guardIdentityRead). The check runs once the value settles, so a read the
+ * body makes after an await counts. Each enclosing execution also notes the
+ * value, and checks it again after encoding its result
+ * (assertLoaderReadsClean): a read that settles after the value (a nested
+ * promise in it) then fails the write instead.
+ */
+export declare function readStartedLoaderValue<T>(value: Promise<T>, loaderId: string): Promise<T>;
+/** Throw when a loader value `scope` read carries an identity read. */
+export declare function assertLoaderReadsClean(scope: CacheExecScope): void;
 /** `root`'s tags plus those of every set it links to, transitively. */
 export declare function flattenRecordedTags(root: Set<string>): Set<string>;
 /** Record where the execution recording into `set` started. */

package/dist/types/server/context.d.ts

@@ -539,8 +539,44 @@ export interface LoaderIdentityRead {
  * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
  * Response directives do not record: a key cannot make a skipped body's side
  * effect reach a HIT.
+ *
+ * The read also lands on the execution's LoaderRunIdentity (#1011), which
+ * every execution has, from either loader runner (runInsideLoaderRun).
  */
 export declare function recordLoaderIdentityRead(surface: string, verb?: LoaderIdentityReadVerb): void;
+/**
+ * One loader execution's request-identity record (#1011): the first identity
+ * read its body made, and the executions whose values it read with
+ * ctx.use(Loader). Every execution has one; the recorded-tag sets that carry
+ * the same reads for a loader cache() fill (cache-tag.ts) exist only in a
+ * request that binds one.
+ *
+ * A "use cache" function that reads a loader's value through the request
+ * memo (a handler, the route's loader() binding or a parent layout's started
+ * it first) does not run the body, so guardIdentityRead never sees the read.
+ * Scar: the entry, keyed without the cookie, stored the first visitor's value
+ * and served it to the next. cache-tag.ts readStartedLoaderValue refuses such
+ * a value through this record.
+ */
+export interface LoaderRunIdentity {
+    readonly loaderId: string;
+    read?: LoaderIdentityRead;
+    reads?: Set<LoaderRunIdentity>;
+}
+/**
+ * Run a loader body with `run` as its identity record: both loader runners
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction) enter it around the loader function.
+ */
+export declare function runInsideLoaderRun<T>(run: LoaderRunIdentity, fn: () => T): T;
+/** The innermost loader execution's identity record (runInsideLoaderRun). */
+export declare function getLoaderRunIdentity(): LoaderRunIdentity | undefined;
+/**
+ * The error a "use cache" function's read of a loader value fails with when
+ * the loader's execution, or one whose value it read, made `read` (#1011).
+ * Worded like guardIdentityRead's "use cache" refusal, naming the loaders.
+ */
+export declare function useCacheLoaderIdentityError(read: LoaderIdentityRead, loaderId: string): Error;
 /** The error a loader cache() fill with no declared key fails with (#972). */
 export declare function loaderCacheIdentityError(read: LoaderIdentityRead, cachedLoaderId: string): Error;
 /**
@@ -632,7 +668,8 @@ export declare function runInsideLoaderScope<T>(fn: () => T): T;
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache() guard — a route cache() never stores loader values.
  * A "use cache" body the loader was entered in still refuses them
- * (guardIdentityRead).
+ * (guardIdentityRead); one that reads the value later refuses what the run
+ * recorded (runInsideLoaderRun, cache-tag.ts readStartedLoaderValue).
  */
 export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, tags?: Set<string>): T;
 /** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */

package/dist/vite/index.js

@@ -4578,7 +4578,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.19.0",
+  version: "0.19.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -6957,6 +6957,7 @@ var NON_CACHEABLE_READ = {
     ...requestReadCaptureFix("per-request variables")
   }
 };
+var loaderRunALS = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:loader-run-identity")] ??= new AsyncLocalStorage2();
 function getLoaderBodyTags() {
   return loaderBodyScopeALS.getStore()?.tags;
 }
@@ -9938,6 +9939,7 @@ globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:identity-read-recorder")]
   if (set === void 0 || identityReads.has(set)) return;
   identityReads.set(set, { surface, verb, bodyId: getCurrentLoaderBodyId() });
 };
+var loaderRuns = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:loader-runs")] ??= /* @__PURE__ */ new WeakMap();
 
 // src/router/router-context.ts
 import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -560,9 +560,9 @@ Loaders are exempt from the `cache()` guard because they run outside the cache
 scope and resolve fresh every request. A loader with its own `cache()` does not:
 its value is stored, so it falls under the loader `cache()` guard above. Nor
 does a loader awaited inside a `"use cache"` body: its value is part of what the
-function returns, so the same reads throw there when the cached function is
-the first to read it in the request (an already-started loader's value is
-stored unchecked).
+function returns, so the same reads throw there, whether the cached function
+starts the loader or reads a value a handler or a `loader()` binding already
+started.
 
 ## Loaders Are Always Fresh
 

package/skills/caching/SKILL.md

@@ -870,10 +870,10 @@ This is the **consumption-lane rule**, and it holds for every shared
 artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`): handler
 consumption = baked copy; client-side `useLoader` = live. The tiers differ on
 identity reads inside a handler-consumed loader: `cache()` permits them (the
-leak above); `"use cache"` throws when the cached function is the first to
-read the loader in the request, because the loader body then runs inside it
-and its value is part of the result (a loader already started elsewhere
-returns its value unchecked, and that value is stored); a PPR shell capture
+leak above); `"use cache"` throws, because the loader's value is part of the
+result: inside the loader body when the cached function starts it, and at
+`ctx.use()` when a handler or a `loader()` binding started it first and its
+run made such a read; a PPR shell capture
 refuses them and the route stays uncached. It is stated once in `/rango` → Invariants.
 
 ```typescript

package/skills/parallel/SKILL.md

@@ -280,7 +280,7 @@ layout(<AccountLayout />, () => [
 
 A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
 
-Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value freezes into the artifact. An identity read (`cookies()`, `headers()`, `ctx.request.headers`) inside the loader bakes too under `cache()`; inside `"use cache"` it throws when the cached function is the first to read the loader in the request (an already-started loader's value is stored unchecked); under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
+Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value freezes into the artifact. An identity read (`cookies()`, `headers()`, `ctx.request.headers`) inside the loader bakes too under `cache()`; inside `"use cache"` it throws, whichever code started the loader first; under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
 
 The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
 

package/skills/rango/SKILL.md

@@ -135,8 +135,8 @@ stated, greppable contract.
   `ctx.request.headers`, a `{ cache: false }` variable) inside that loader
   are permitted under a route `cache()` (a documented footgun; see
   `/caching` → "Cache purity & tainted objects"). They throw inside
-  `"use cache"` (when the cached function is the first to read the loader in
-  the request; an already-started loader's value is stored unchecked) and REFUSE a PPR capture: the route serves uncached until
+  `"use cache"` (whichever code started the loader first: a handler, a
+  `loader()` binding, or the cached function itself) and REFUSE a PPR capture: the route serves uncached until
   the read moves to a live loader. Client-side consumption
   (`useLoader` in a `"use client"` component) is the LIVE lane. DSL
   `loader()` segments follow their PPR lane (only `ssr: false` bakes; see

package/skills/use-cache/SKILL.md

@@ -283,11 +283,14 @@ is part of that body: its value is captured into the shared cache entry like
 any other computed data, so a `{ cache: false }` variable read there throws,
 exactly as `cookies()`, `headers()`, `ctx.request.headers` and a theme read do
 (one guard follows the
-cached body's whole async chain, loaders included). The check runs only when
-the loader body starts inside the cached function: a loader something else in
-the request already started (a handler's `ctx.use()`, a route `loader()`)
-returns its memoized value without it, and that value is still stored in the
-entry. Read the value outside and pass it in as an argument. Handler/cached-scope consumption = baked copy,
+cached body's whole async chain, loaders included). The order does not
+matter: a loader something else in the request already started (a handler's
+`ctx.use()`, the route's or a parent layout's `loader()`) returns its memoized
+value, and `ctx.use()` (or `getRequestContext().use()`) inside the cached function rejects with the same error
+when that run, or a loader it read, made such a read. A read the run makes
+after its value settled (a nested promise in the value) fails the entry's
+write instead: the caller gets its own value, nothing is stored, and `onError`
+reports it. Read the value outside and pass it in as an argument. Handler/cached-scope consumption = baked copy,
 client-side `useLoader` = live (the consumption-lane rule, `/rango` →
 Invariants). Under a route `cache()` a loader body's reads stay allowed (the
 route entry never stores a loader's value); during a PPR capture they refuse

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

@@ -34,6 +34,12 @@ import { _setCacheExecScopeProbe } from "./taint.js";
  */
 export interface CacheExecScope {
   readonly parent?: CacheExecScope;
+  /**
+   * Loader values its chain read through an already-started execution, to
+   * their loader ids (cache-tag.ts readStartedLoaderValue), checked again
+   * before its write (#1011).
+   */
+  loaderReads?: Map<object, string>;
 }
 
 const cacheExecStorage = new AsyncLocalStorage<CacheExecScope>();

package/src/cache/cache-runtime.ts

@@ -47,6 +47,7 @@ import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
+  assertLoaderReadsClean,
   normalizeTags,
   outsideCacheTagScope,
   recordRequestTags,
@@ -753,6 +754,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                       // An error row would replace the stale entry; the catch
                       // below reports it and the stale entry keeps serving.
                       if (flightErrors.length > 0) throw flightErrors[0];
+                      assertLoaderReadsClean(bgScope);
                       const freshTags = entryTags(scoped.tags);
                       // One of the refreshed value's tags was invalidated after
                       // the refresh started: written now, a value that may
@@ -972,6 +974,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         // promise in the result or a handle value, as an error row and
         // completes normally; stored, every hit would serve that error.
         if (flightErrors.length > 0) throw flightErrors[0];
+        // The encode awaited the result's nested promises: an identity read a
+        // loader value made after it settled is recorded now (#1011).
+        assertLoaderReadsClean(execScope);
       } catch (buildError) {
         // Serialize/handle-encode failed: no envelope for followers (they run
         // fresh) and nothing to write.

package/src/cache/cache-tag.ts

@@ -17,11 +17,19 @@ import {
 } from "../server/request-context.js";
 import {
   getCurrentLoaderBodyId,
+  getLoaderRunIdentity,
   getLoaderBodyTags,
   isInsideLoaderScope,
+  useCacheLoaderIdentityError,
   type LoaderIdentityRead,
   type LoaderIdentityReadVerb,
+  type LoaderRunIdentity,
 } from "../server/context.js";
+import {
+  getCacheExecScope,
+  isInsideIdentityExempt,
+  type CacheExecScope,
+} from "./cache-exec-scope.js";
 import type { ExecutionStart } from "./tag-invalidation.js";
 
 const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
@@ -481,6 +489,102 @@ export function recordedIdentityRead(
   return undefined;
 }
 
+/**
+ * Loader value identity (#1011). Each loader execution's value promise maps to
+ * its LoaderRunIdentity (server/context.ts); a loader-cache binding's value
+ * carries its reads on its recorded-tag set instead (tagLoaderValue,
+ * markIdentityRead). On globalThis like identityReads: the executor that
+ * tracks a value and the reader that checks it must share the map.
+ */
+const loaderRuns: WeakMap<object, LoaderRunIdentity> = ((globalThis as any)[
+  Symbol.for("rangojs-router:loader-runs")
+] ??= new WeakMap());
+
+/**
+ * `value` is the promise of the execution `run` records, started by the
+ * current execution (if any), which reads it. Both loader runners call it
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction).
+ */
+export function trackLoaderRun(value: object, run: LoaderRunIdentity): void {
+  loaderRuns.set(value, run);
+  linkLoaderRun(value);
+}
+
+/** The current loader execution reads `value`: its record links the value's. */
+function linkLoaderRun(value: object): void {
+  const reader = getLoaderRunIdentity();
+  const run = loaderRuns.get(value);
+  if (reader && run && reader !== run) (reader.reads ??= new Set()).add(run);
+}
+
+/**
+ * The identity read behind a loader value: its execution's or one it read
+ * (nearest first), or the one its recorded-tag set links to.
+ */
+function loaderValueIdentityRead(
+  value: object,
+): LoaderIdentityRead | undefined {
+  const root = loaderRuns.get(value);
+  if (root) {
+    const queue = [root];
+    const seen = new Set<LoaderRunIdentity>();
+    for (let i = 0; i < queue.length; i++) {
+      const run = queue[i]!;
+      if (seen.has(run)) continue;
+      seen.add(run);
+      if (run.read) return run.read;
+      for (const linked of run.reads ?? []) queue.push(linked);
+    }
+  }
+  const tags = loaderValueTags.get(value);
+  return tags && recordedIdentityRead(tags);
+}
+
+/**
+ * A ctx.use(Loader) or getRequestContext().use(Loader) read that returns an
+ * already-started value (the request memo, a loader cache() binding's value).
+ * The current loader execution, if any, links it (it reads the value).
+ * Inside a "use cache" body the value is refused when its execution read
+ * request identity, as a body entered there would have been
+ * (guardIdentityRead). The check runs once the value settles, so a read the
+ * body makes after an await counts. Each enclosing execution also notes the
+ * value, and checks it again after encoding its result
+ * (assertLoaderReadsClean): a read that settles after the value (a nested
+ * promise in it) then fails the write instead.
+ */
+export function readStartedLoaderValue<T>(
+  value: Promise<T>,
+  loaderId: string,
+): Promise<T> {
+  linkLoaderRun(value);
+  const scope = getCacheExecScope();
+  if (!scope || isInsideIdentityExempt()) return value;
+  for (let s: CacheExecScope | undefined = scope; s; s = s.parent) {
+    (s.loaderReads ??= new Map()).set(value, loaderId);
+  }
+  const checked = value.then((resolved) => {
+    assertLoaderValueClean(value, loaderId);
+    return resolved;
+  });
+  // A read the body never awaits must not crash the process as an unhandled
+  // rejection; the write check (assertLoaderReadsClean) still refuses it.
+  checked.catch(() => {});
+  return checked;
+}
+
+/** Throw when a loader value `scope` read carries an identity read. */
+export function assertLoaderReadsClean(scope: CacheExecScope): void {
+  for (const [value, loaderId] of scope.loaderReads ?? []) {
+    assertLoaderValueClean(value, loaderId);
+  }
+}
+
+function assertLoaderValueClean(value: object, loaderId: string): void {
+  const read = loaderValueIdentityRead(value);
+  if (read) throw useCacheLoaderIdentityError(read, loaderId);
+}
+
 /** `root` and every set it links to, transitively. */
 function linkedSets(root: Set<string>): Set<Set<string>> {
   const seen = new Set<Set<string>>();

package/src/router/loader-resolution.ts

@@ -15,8 +15,10 @@ import {
   linkValueTags,
   loaderTagSetsArmed,
   markTagSetStart,
+  readStartedLoaderValue,
   readValueTags,
   tagLoaderValue,
+  trackLoaderRun,
 } from "../cache/cache-tag.js";
 import { executionStart } from "../cache/tag-invalidation.js";
 import type {
@@ -57,8 +59,10 @@ import {
   assertNonCacheableReadAllowed,
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
+  runInsideLoaderRun,
   isInsidePushCallbackScope,
   runInsidePushCallbackScope,
+  type LoaderRunIdentity,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -479,7 +483,9 @@ function createLoaderExecutor<TEnv>(
     const memo = bound || loaderPromises.get(loader.$$id);
     if (memo) {
       if (recordTags) readValueTags(memo);
-      return memo;
+      // A "use cache" body reading it refuses an identity read the run made
+      // (#1011): the body ran outside the cached function, unguarded.
+      return readStartedLoaderValue(memo, loader.$$id);
     }
 
     // Get loader function - either from loader object or fetchable registry
@@ -724,8 +730,10 @@ function createLoaderExecutor<TEnv>(
     // BAKED copy in every shared artifact (cache(), "use cache", the PPR
     // shell). The cache() guard permits its identity reads; a "use cache"
     // body it was entered in and a PPR capture do not (server/context.ts
-    // guardIdentityRead).
+    // guardIdentityRead), and a "use cache" body that reads the value after
+    // another reader started it refuses what `identity` recorded (#1011).
 
+    const identity: LoaderRunIdentity = { loaderId: loader.$$id };
     const recordedTags = recordTags ? new Set<string>() : undefined;
     // A loader-cache write that stores or reads this value gates on the
     // earliest start behind it (#977, earliestRecordedStart).
@@ -736,7 +744,10 @@ function createLoaderExecutor<TEnv>(
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(
-          () => loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+          () =>
+            runInsideLoaderRun(identity, () =>
+              loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+            ),
           loader.$$id,
           recordedTags,
         ),
@@ -747,6 +758,7 @@ function createLoaderExecutor<TEnv>(
         runEndStore?.settleLoaderRun(loader.$$id);
       }),
     );
+    trackLoaderRun(promise, identity);
     if (recordedTags) {
       tagLoaderValue(promise, recordedTags);
       readValueTags(promise);

package/src/router/segment-resolution/loader-cache.ts

@@ -96,6 +96,7 @@ import {
   linkRecordedTags,
   markIdentityRead,
   markTagSetStart,
+  readStartedLoaderValue,
   readValueTags,
   recordedIdentityRead,
   recordLoaderTags,
@@ -591,7 +592,7 @@ function executeLoaderData<TEnv>(
         // useLoader.
         linkLoaderTags(item.$$id);
         readValueTags(cached);
-        return cached;
+        return readStartedLoaderValue(cached, item.$$id);
       }
       return originalUse(item);
     }) as typeof ctx.use;

package/src/server/context.ts

@@ -1131,18 +1131,91 @@ const IDENTITY_READ_RECORDER_KEY = Symbol.for(
  * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
  * Response directives do not record: a key cannot make a skipped body's side
  * effect reach a HIT.
+ *
+ * The read also lands on the execution's LoaderRunIdentity (#1011), which
+ * every execution has, from either loader runner (runInsideLoaderRun).
  */
 export function recordLoaderIdentityRead(
   surface: string,
   verb: LoaderIdentityReadVerb = "called",
 ): void {
   if (isInsideIdentityExempt()) return;
+  const run = loaderRunALS.getStore();
+  if (run && run.read === undefined) {
+    run.read = { surface, verb, bodyId: run.loaderId };
+  }
   const recorder = (globalThis as Record<symbol, unknown>)[
     IDENTITY_READ_RECORDER_KEY
   ] as ((surface: string, verb: LoaderIdentityReadVerb) => void) | undefined;
   recorder?.(surface, verb);
 }
 
+/**
+ * One loader execution's request-identity record (#1011): the first identity
+ * read its body made, and the executions whose values it read with
+ * ctx.use(Loader). Every execution has one; the recorded-tag sets that carry
+ * the same reads for a loader cache() fill (cache-tag.ts) exist only in a
+ * request that binds one.
+ *
+ * A "use cache" function that reads a loader's value through the request
+ * memo (a handler, the route's loader() binding or a parent layout's started
+ * it first) does not run the body, so guardIdentityRead never sees the read.
+ * Scar: the entry, keyed without the cookie, stored the first visitor's value
+ * and served it to the next. cache-tag.ts readStartedLoaderValue refuses such
+ * a value through this record.
+ */
+export interface LoaderRunIdentity {
+  readonly loaderId: string;
+  read?: LoaderIdentityRead;
+  reads?: Set<LoaderRunIdentity>;
+}
+
+// Its own scope, not a LoaderBodyScope field: the request-context runner
+// (request-context.ts createUseFunction) records reads too, but does not
+// enter a loader body scope, whose cache() exemption it never had.
+const loaderRunALS: AsyncLocalStorage<LoaderRunIdentity> = ((globalThis as any)[
+  Symbol.for("rangojs-router:loader-run-identity")
+] ??= new AsyncLocalStorage<LoaderRunIdentity>());
+
+/**
+ * Run a loader body with `run` as its identity record: both loader runners
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction) enter it around the loader function.
+ */
+export function runInsideLoaderRun<T>(run: LoaderRunIdentity, fn: () => T): T {
+  return loaderRunALS.run(run, fn);
+}
+
+/** The innermost loader execution's identity record (runInsideLoaderRun). */
+export function getLoaderRunIdentity(): LoaderRunIdentity | undefined {
+  return loaderRunALS.getStore();
+}
+
+/**
+ * The error a "use cache" function's read of a loader value fails with when
+ * the loader's execution, or one whose value it read, made `read` (#1011).
+ * Worded like guardIdentityRead's "use cache" refusal, naming the loaders.
+ */
+export function useCacheLoaderIdentityError(
+  read: LoaderIdentityRead,
+  loaderId: string,
+): Error {
+  const bodyId = read.bodyId ?? loaderId;
+  const source =
+    bodyId === loaderId
+      ? `Loader "${loaderId}" ${read.verb} it, and the cached function reads that loader's value`
+      : `Loader "${bodyId}" ${read.verb} it, and the cached function reads loader "${loaderId}", whose value is built from it`;
+  return new Error(
+    `${read.surface} cannot be ${read.verb} inside a "use cache" function. ` +
+      `${source}. The loader ran outside the function (a handler or a ` +
+      `loader() binding started it first), but its value becomes part of ` +
+      `what the function returns, and the cache key does not include it, so ` +
+      `the first caller's value would be stored and served to later callers. ` +
+      `Read the loader before calling the cached function and pass the value ` +
+      `in as an argument so it becomes part of the cache key.`,
+  );
+}
+
 /** The error a loader cache() fill with no declared key fails with (#972). */
 export function loaderCacheIdentityError(
   read: LoaderIdentityRead,
@@ -1344,7 +1417,8 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache() guard — a route cache() never stores loader values.
  * A "use cache" body the loader was entered in still refuses them
- * (guardIdentityRead).
+ * (guardIdentityRead); one that reads the value later refuses what the run
+ * recorded (runInsideLoaderRun, cache-tag.ts readStartedLoaderValue).
  */
 export function runInsideLoaderBodyScope<T>(
   fn: () => T,

package/src/server/request-context.ts

@@ -64,7 +64,10 @@ import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
   clearPprHeaderScope,
+  runInsideLoaderRun,
+  type LoaderRunIdentity,
 } from "./context.js";
+import { readStartedLoaderValue, trackLoaderRun } from "../cache/cache-tag.js";
 import {
   guardRawCookieRead,
   guardRequestHeaders,
@@ -1859,8 +1862,11 @@ export function createUseFunction<TEnv>(
 
     const loader = item as LoaderDefinition<any, any>;
 
-    if (loaderPromises.has(loader.$$id)) {
-      return loaderPromises.get(loader.$$id);
+    const memo = loaderPromises.get(loader.$$id);
+    if (memo) {
+      // Same refusal as the handler ctx.use memo hit (#1011): a "use cache"
+      // body reading a value whose run read request identity.
+      return readStartedLoaderValue(memo, loader.$$id);
     }
 
     let loaderFn = loader.fn;
@@ -1947,9 +1953,11 @@ export function createUseFunction<TEnv>(
     // (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 run: LoaderRunIdentity = { loaderId: loader.$$id };
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
-      Promise.resolve(loaderFn(loaderCtx)),
+      Promise.resolve(runInsideLoaderRun(run, () => loaderFn(loaderCtx))),
     );
+    trackLoaderRun(promise, run);
 
     loaderPromises.set(loader.$$id, promise);