@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/server/request-context.ts

@@ -11,8 +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 {
@@ -34,13 +41,20 @@ 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 type { ResolvedTracing } from "../router/tracing.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
-import { THEME_COOKIE } from "../theme/constants.js";
+import {
+  THEME_COOKIE,
+  isValidTheme,
+  warnInvalidTheme,
+} from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isInsideCacheScope } from "./context.js";
@@ -48,7 +62,12 @@ 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";
 
@@ -103,6 +122,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.
@@ -293,7 +316,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;
 
@@ -317,6 +342,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>;
 
@@ -338,6 +375,9 @@ export interface RequestContext<
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
 
+  /** @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;
 
@@ -346,6 +386,15 @@ export interface RequestContext<
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @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[];
 }
 
 /**
@@ -381,13 +430,17 @@ export type PublicRequestContext<
   | "_renderBarrierWaiters"
   | "_handlerLoaderDeps"
   | "_renderBarrierHandleSnapshot"
+  | "_renderBarrierGuardClosed"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
   | "_basename"
   | "_setStatus"
+  | "_rotateStateCookie"
+  | "_setKeepCacheDirective"
   | "_variables"
   | "_classifiedRoute"
+  | "_cacheSignal"
   | "res"
 >;
 
@@ -439,6 +492,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) {
@@ -451,9 +505,13 @@ 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,
@@ -487,16 +545,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 };
 
 /**
@@ -525,6 +573,10 @@ export interface CreateRequestContextOptions<TEnv> {
   executionContext?: ExecutionContext;
   /** 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;
 }
 
 /**
@@ -549,12 +601,13 @@ export function createRequestContext<TEnv>(
     cacheProfiles,
     executionContext,
     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,
@@ -563,11 +616,9 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
-  // Create handle store and loader memoization for this request
   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);
@@ -575,7 +626,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) {
@@ -587,8 +637,6 @@ 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(
@@ -599,8 +647,7 @@ export function createRequestContext<TEnv>(
     }
   }
 
-  // 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)) {
@@ -610,14 +657,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";
       }
@@ -631,15 +675,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, {
@@ -651,10 +695,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,
@@ -740,6 +782,45 @@ export function createRequestContext<TEnv>(
       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);
+      stubResponse.headers.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).
+    _setKeepCacheDirective(): void {
+      stubResponse.headers.set(KEEP_CACHE_HEADER, "1");
+    },
+
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
       assertNotInsideCacheScopeALS("setStatus");
@@ -756,7 +837,6 @@ export function createRequestContext<TEnv>(
       });
     },
 
-    // Placeholder - will be replaced below
     use: null as any,
 
     method: request.method,
@@ -769,7 +849,11 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        executionContext.waitUntil(fn());
+        // 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.
+        executionContext.waitUntil(Promise.resolve().then(fn));
       } else {
         fireAndForgetWaitUntil(fn);
       }
@@ -785,7 +869,6 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    // Theme properties (only set when themeConfig is provided)
     get theme() {
       return themeConfig ? getTheme() : undefined;
     },
@@ -809,19 +892,17 @@ export function createRequestContext<TEnv>(
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: 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.
+  // Lazy allocation: only create Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._renderBarrier = null as any;
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -831,21 +912,26 @@ 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();
   };
   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) => {
@@ -861,32 +947,33 @@ export function createRequestContext<TEnv>(
     configurable: true,
   });
 
-  // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
     loaderPromises,
     getContext: () => ctx,
   });
 
-  // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }
 
-/**
- * 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;
+// 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;
+
+function isCookieDeletion(header: string): boolean {
+  const m = MAX_AGE_RE.exec(header);
+  if (!m) return false;
+  return Number(m[1]) <= 0;
+}
 
 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("=");
@@ -898,49 +985,22 @@ 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;
-      }
-    }
-  }
-
-  return cookies;
-}
+// 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 };
 
-/**
- * Serialize a cookie for Set-Cookie header
- */
-function serializeCookieValue(
+export function serializeCookieValue(
   name: string,
   value: string,
   options: CookieOptions = {},
@@ -967,20 +1027,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();
@@ -993,30 +1045,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);
@@ -1033,13 +1079,24 @@ 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)
+      : 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,
@@ -1050,7 +1107,6 @@ export function createUseFunction<TEnv>(
       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"],
       method: "GET",
@@ -1069,12 +1125,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;