@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/router/segment-resolution/helpers.ts

@@ -0,0 +1,348 @@
+/**
+ * Shared Helpers for Segment Resolution
+ *
+ * Common utilities used by both fresh and revalidation resolution paths:
+ * - Handler result processing (Response vs ReactNode)
+ * - Static handler interception (build-time pre-rendered components)
+ * - Layout handler resolution with static fallback
+ * - Error boundary segment creation
+ */
+
+import { createElement, type ReactNode } from "react";
+import { DataNotFoundError } from "../../errors";
+import {
+  createErrorInfo,
+  createErrorSegment,
+  createNotFoundInfo,
+  createNotFoundSegment,
+} from "../error-handling.js";
+import { getRequestContext } from "../../server/request-context.js";
+import { DefaultErrorFallback } from "../../default-error-boundary.js";
+import type { EntryData } from "../../server/context";
+import type {
+  ResolvedSegment,
+  ErrorInfo,
+  HandlerContext,
+  InternalHandlerContext,
+} from "../../types";
+import type { SegmentResolutionDeps } from "../types.js";
+import { debugLog } from "../logging.js";
+import { tryStaticLookup } from "./static-store.js";
+import { observeHandler } from "../instrument.js";
+import type { TelemetrySink } from "../telemetry.js";
+import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
+
+/** The errorContext shape wrapLoaderPromise expects as its 5th argument. */
+type LoaderErrorContext<TEnv> = NonNullable<
+  Parameters<SegmentResolutionDeps<TEnv>["wrapLoaderPromise"]>[4]
+>;
+
+/**
+ * Build the errorContext passed to wrapLoaderPromise so a throwing DSL loader
+ * fires createRouter({ onError }) (phase "loader") and emits the loader.error
+ * telemetry event. wrapLoaderPromise only wires the onError/telemetry path when
+ * this 5th argument is present; every real call site previously omitted it, so
+ * loaders were the one phase whose failures were silently dropped (handlers,
+ * actions, routing, rendering, and fetchable loaders all reported correctly).
+ *
+ * The fields come off the handler context, which already carries the request,
+ * url, params, env, and (on the internal shape) the matched route name.
+ */
+export function buildLoaderErrorContext<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+): LoaderErrorContext<TEnv> {
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  return {
+    request: ctx.request,
+    url: ctx.url,
+    routeKey: internal._routeName,
+    params: ctx.params as Record<string, string>,
+    env: ctx.env,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Handler result processing
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle Response returns from handlers.
+ * When a handler returns a Response (e.g., redirect), throw it to trigger
+ * the short-circuit mechanism. Otherwise return the ReactNode.
+ */
+export function handleHandlerResult(
+  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+): ReactNode {
+  if (result instanceof Response) {
+    throw result;
+  }
+  if (result instanceof Promise) {
+    return result.then((resolved) => {
+      if (resolved instanceof Response) {
+        throw resolved;
+      }
+      return resolved;
+    }) as ReactNode;
+  }
+  return result;
+}
+
+/**
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
+ * rejects with a Response (e.g. redirect()).
+ *
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
+ * redirect. But when the route declares loading(), the handler result is
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
+ * only during RSC serialization and is rendered into the stream instead of
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
+ * a loader, or a synchronous handler return instead. Compiled out in production.
+ */
+export function warnOnStreamedResponse(
+  result: Promise<unknown>,
+  entryId: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+  // A Response can surface either as a rejection (handleHandlerResult rethrows a
+  // resolved Response) or as a resolved value (the raw parallel-slot handler is
+  // not run through handleHandlerResult). Check both so every streamed path is
+  // covered. Each handler is an independent observer; it does not consume the
+  // rejection for the trackHandler/observeStreamedHandler chains.
+  const check = (value: unknown) => {
+    if (value instanceof Response) {
+      console.warn(
+        `[rango] Handler for "${entryId}" returned a Response (e.g. ` +
+          `redirect()), but it declares loading(): the Response is rendered ` +
+          `into the RSC stream, NOT sent as an HTTP redirect. Issue redirects ` +
+          `from middleware, a loader, or a synchronous handler return.`,
+      );
+    }
+  };
+  result.then(check, check);
+}
+
+// ---------------------------------------------------------------------------
+// Static handler interception
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to resolve a component from the build-time static store.
+ * Returns undefined synchronously when the entry is not a static prerender,
+ * avoiding unnecessary promise wrapping on the hot path.
+ */
+export function tryStaticHandler(
+  entry: EntryData,
+  segmentId: string,
+): Promise<ReactNode | undefined> | undefined {
+  const entryAny = entry as any;
+  if (entryAny.isStaticPrerender && entryAny.staticHandlerId) {
+    return tryStaticLookup(entryAny.staticHandlerId, segmentId);
+  }
+  return undefined;
+}
+
+/**
+ * Try to resolve a parallel slot component from the build-time static store.
+ * Returns undefined synchronously when no static handler ID exists for the slot.
+ */
+export function tryStaticSlot(
+  parallelEntry: EntryData,
+  slot: string,
+  segmentId: string,
+): Promise<ReactNode | undefined> | undefined {
+  const slotStaticId = (parallelEntry as any).staticHandlerIds?.[slot];
+  if (slotStaticId) {
+    return tryStaticLookup(slotStaticId, segmentId);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a layout or cache entry's handler component.
+ * Checks build-time static store first, then invokes the handler.
+ */
+export async function resolveLayoutComponent<TEnv>(
+  entry: EntryData,
+  context: HandlerContext<any, TEnv>,
+): Promise<ReactNode> {
+  // Static/prerender hit: no handler runs, so emit no rango.handler span.
+  const staticComponent = await tryStaticHandler(entry, entry.shortCode);
+  if (staticComponent !== undefined) return staticComponent;
+  const handler = entry.handler;
+  if (typeof handler !== "function") return handler as ReactNode;
+  // Wrap ONLY the handler call in the rango.handler span (the perf metric is owned
+  // by track("handler:<id>") at the call site). handleHandlerResult stays OUTSIDE
+  // the span so a handler that returns a Response (redirect control flow, which it
+  // rethrows) is not recorded as a span error — mirrors the route-handler sites.
+  return handleHandlerResult(await observeHandler(entry.id, handler, context));
+}
+
+// ---------------------------------------------------------------------------
+// Error boundary segment creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Context for error reporting in segment resolution.
+ * When provided, callOnError is invoked with this context.
+ */
+export interface ErrorReportContext {
+  request?: Request;
+  url?: URL;
+  routeKey?: string;
+  env?: any;
+  isPartial?: boolean;
+  requestStartTime?: number;
+  telemetry?: TelemetrySink;
+}
+
+/**
+ * Handle a caught error during segment resolution by creating an
+ * error or not-found segment with the nearest boundary.
+ *
+ * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ */
+export function catchSegmentError<TEnv>(
+  error: unknown,
+  entry: EntryData,
+  params: Record<string, string>,
+  deps: SegmentResolutionDeps<TEnv>,
+  report?: ErrorReportContext,
+  pathname?: string,
+): ResolvedSegment {
+  const reportError = (
+    handledByBoundary: boolean,
+    metadata?: Record<string, unknown>,
+  ) => {
+    if (!report) return;
+    deps.callOnError(error, "handler", {
+      request: report.request as Request,
+      url: report.url,
+      routeKey: report.routeKey,
+      params,
+      segmentId: entry.shortCode,
+      segmentType: entry.type as any,
+      env: report.env,
+      isPartial: report.isPartial,
+      handledByBoundary,
+      metadata,
+      requestStartTime: report.requestStartTime,
+    });
+    if (report.telemetry) {
+      const errorObj =
+        error instanceof Error ? error : new Error(String(error));
+      safeEmit(resolveSink(report.telemetry), {
+        type: "handler.error",
+        timestamp: performance.now(),
+        requestId: report.request ? getRequestId(report.request) : undefined,
+        segmentId: entry.shortCode,
+        segmentType: entry.type,
+        error: errorObj,
+        handledByBoundary,
+        pathname,
+        routeKey: report.routeKey,
+        params,
+      });
+    }
+  };
+
+  const setResponseStatus = (status: number) => {
+    const reqCtx = getRequestContext();
+    if (reqCtx) {
+      reqCtx._setStatus(status);
+    }
+  };
+
+  if (error instanceof DataNotFoundError) {
+    const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+    // Fall back to router's notFound component, then a plain default
+    const notFoundOption = deps.notFoundComponent;
+    const defaultFallback =
+      typeof notFoundOption === "function"
+        ? notFoundOption({ pathname: pathname ?? "" })
+        : (notFoundOption ?? createElement("h1", null, "Not Found"));
+    const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
+
+    const notFoundInfo = createNotFoundInfo(
+      error,
+      entry.shortCode,
+      entry.type,
+      pathname,
+    );
+
+    reportError(true, {
+      notFound: true,
+      message: notFoundInfo.message,
+    });
+
+    debugLog("segment", "notFound boundary handled error", {
+      segmentId: entry.shortCode,
+      message: notFoundInfo.message,
+    });
+
+    setResponseStatus(404);
+
+    return createNotFoundSegment(
+      notFoundInfo,
+      effectiveNotFoundFallback,
+      entry,
+      params,
+    );
+  }
+
+  const fallback = deps.findNearestErrorBoundary(entry);
+  const segmentType: ErrorInfo["segmentType"] = entry.type;
+  const errorInfo = createErrorInfo(error, entry.shortCode, segmentType);
+  const effectiveFallback = fallback ?? DefaultErrorFallback;
+
+  reportError(!!effectiveFallback);
+
+  debugLog("segment", "error boundary handled error", {
+    segmentId: entry.shortCode,
+    boundary: fallback ? "custom" : "default",
+    message: errorInfo.message,
+  });
+
+  setResponseStatus(500);
+
+  return createErrorSegment(errorInfo, effectiveFallback, entry, params);
+}
+
+/**
+ * Generic error boundary wrapper for segment resolution.
+ * Catches non-Response errors and produces an error/notFound segment
+ * via catchSegmentError. Response throws (e.g. redirects) are re-thrown.
+ *
+ * The caller provides a `wrapError` callback to shape the error segment
+ * into the expected return type (e.g. ResolvedSegment[] for the fresh
+ * path, or SegmentRevalidationResult for the revalidation path).
+ */
+export async function resolveWithErrorBoundary<TEnv, TResult>(
+  entry: EntryData,
+  params: Record<string, string>,
+  resolveFn: () => Promise<TResult>,
+  wrapError: (segment: ResolvedSegment) => TResult,
+  deps: SegmentResolutionDeps<TEnv>,
+  report?: ErrorReportContext,
+  pathname?: string,
+  throwOnError?: boolean,
+): Promise<TResult> {
+  try {
+    return await resolveFn();
+  } catch (error) {
+    if (error instanceof Response) throw error;
+    // Pre-render surfaces render failures to the build instead of baking the
+    // error boundary as a frozen 200 (issue #587). A `throw new Skip()` in a
+    // render fn also propagates here so the build can skip that URL rather than
+    // bake its error page. The live request path leaves throwOnError unset.
+    if (throwOnError) throw error;
+    const segment = catchSegmentError(
+      error,
+      entry,
+      params,
+      deps,
+      report,
+      pathname,
+    );
+    return wrapError(segment);
+  }
+}

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

@@ -0,0 +1,315 @@
+/**
+ * Loader-Level Caching
+ *
+ * When a LoaderEntry has a cache config (set via loader(Fn, () => [cache({...})])),
+ * this module wraps the loader execution with cache lookup/store using the
+ * getItem()/setItem() methods on SegmentCacheStore.
+ *
+ * Cache key resolution (3-tier, matching CacheScope.resolveKey):
+ *   1. options.key(requestCtx) — full override
+ *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
+ *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
+ *
+ * Values are serialized via RSC Flight (serializeResult/deserializeResult),
+ * supporting ReactNode, Promises, null, and all RSC-serializable types.
+ *
+ * On hit: returns cached data directly, skips loader execution.
+ * On stale hit (SWR): returns stale data, schedules background revalidation.
+ * On miss: executes loader, schedules non-blocking cache write.
+ */
+
+import type { LoaderEntry } from "../../server/context.js";
+import type { HandlerContext, InternalHandlerContext } from "../../types.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import {
+  getRequestContext,
+  _getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
+import { sortedRouteParams } from "../../cache/cache-key-utils.js";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  resolveCacheKey,
+  resolveCacheStore,
+  resolveTagsOption,
+  DEFAULT_ROUTE_TTL,
+} from "../../cache/cache-policy.js";
+import { readThroughItem } from "../../cache/read-through-swr.js";
+import {
+  maskNestedContainerThenables,
+  overlayLoaderContainer,
+} from "./loader-snapshot.js";
+import { recordRequestTags } from "../../cache/cache-tag.js";
+import {
+  isShellCaptureActive,
+  createMaskedLoaderPromise,
+} from "./loader-mask.js";
+// Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
+// import segment-resolution but never use loader caching.
+let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
+let _deserializeResult: typeof import("../../cache/segment-codec.js").deserializeResult;
+async function getCodec() {
+  if (!_serializeResult) {
+    const mod = await import("../../cache/segment-codec.js");
+    _serializeResult = mod.serializeResult;
+    _deserializeResult = mod.deserializeResult;
+  }
+  return {
+    serializeResult: _serializeResult,
+    deserializeResult: _deserializeResult,
+  };
+}
+
+function debugLoaderCacheLog(message: string): void {
+  if (INTERNAL_RANGO_DEBUG) {
+    console.log(message);
+  }
+}
+
+function getDefaultLoaderCacheKey(
+  loaderId: string,
+  host: string,
+  pathname: string,
+  params: Record<string, string>,
+): string {
+  const paramStr = sortedRouteParams(params);
+  const base = paramStr ? `${pathname}:${paramStr}` : pathname;
+  return `loader:${loaderId}:${host}${base}`;
+}
+
+/**
+ * Resolve cache key using the shared 3-tier priority.
+ */
+async function resolveLoaderKey(
+  loaderEntry: LoaderEntry,
+  store: import("../../cache/types.js").SegmentCacheStore,
+  loaderId: string,
+  pathname: string,
+  params: Record<string, string>,
+): Promise<string> {
+  const options = loaderEntry.cache!.options;
+  // The host is part of the loader cache identity, matching the route-level
+  // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
+  // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
+  // serving the same pathname for different hosts would leak one host's cached
+  // loader data to another.
+  const host = getRequestContext()?.url?.host ?? "localhost";
+  const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
+  if (options === false) return defaultKey;
+  return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
+}
+
+/**
+ * Resolve tags from cache options (static array or function).
+ * Fails open: a thrown tag callback falls back to no tags rather than
+ * aborting the request. Tags are additive metadata (not identity), so
+ * a missing tag does not cause cache collisions.
+ */
+function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
+  const options = loaderEntry.cache?.options;
+  if (!options) return undefined;
+  return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
+}
+
+function getLoaderStore(
+  loaderEntry: LoaderEntry,
+): import("../../cache/types.js").SegmentCacheStore | null {
+  const cacheConfig = loaderEntry.cache;
+  if (!cacheConfig || cacheConfig.options === false) return null;
+  return resolveCacheStore(cacheConfig.options.store);
+}
+
+/**
+ * Resolve loader data with optional caching.
+ *
+ * When the LoaderEntry has no cache config, delegates directly to ctx.use(loader).
+ * When cached, checks store first and stores on miss via waitUntil.
+ *
+ * Loader metering is NOT done here — it lives at the ctx.use execution funnel
+ * (observePhase; see instrument.ts). A cache HIT returns without calling ctx.use,
+ * so it emits no loader phase (the loader did not execute; the hit is only a
+ * LoaderCache debug log).
+ */
+export function resolveLoaderData<TEnv>(
+  loaderEntry: LoaderEntry,
+  ctx: HandlerContext<any, TEnv>,
+  pathname: string,
+  bakeSegmentKey?: string | null,
+): Promise<any> {
+  // One ALS read serves the capture check, the record registration, and the
+  // seed lookup — this runs for every loader on every request.
+  const reqCtx = _getRequestContext();
+  // PPR shell capture policy — gated here, the single funnel every loader
+  // segment path routes through (fresh resolveLoaders, cache-hit
+  // resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation).
+  //
+  // Two lanes (docs/design/loader-container-bake.md):
+  // - LIVE lane (entry has renderable loading(); no `bakeSegmentKey`): never
+  //   execute during capture. The slot gets a never-resolving promise so the
+  //   LoaderBoundary postpones (a hole). See loader-mask.ts.
+  // - BAKE lane (no renderable loading(); callers pass `bakeSegmentKey`):
+  //   execute during capture exactly like axis 1 — the settled container bakes
+  //   into the prelude, nested pending promises postpone at the consumer's own
+  //   Suspense. The container promise is registered on the derived context so
+  //   captureAndStoreShell pins it into the snapshot's loader family; on a
+  //   shell HIT the recorded container is overlaid onto the fresh run so the
+  //   payload matches the frozen prelude byte-for-byte.
+  if (isShellCaptureActive(reqCtx)) {
+    if (!bakeSegmentKey) {
+      return createMaskedLoaderPromise();
+    }
+    const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
+    // Pre-attach a no-op catch: a bake-lane rejection during capture must
+    // surface through the drain's refusal (and the wrapper's error boundary),
+    // never as an unhandled rejection that can kill the worker before the
+    // drain probes this record.
+    containerPromise.catch(() => {});
+    // Nested-promise SHAPE is the liveness declaration: mask nested thenables
+    // in the capture's copy of the container so the consuming subtree
+    // postpones as a hole no matter when the promise settles, elide records a
+    // HOLE marker, and every HIT streams the fresh value. Without this, a
+    // nested promise that settled before the quiet window baked its value into
+    // the SHARED shell and the snapshot pinned it for every visitor
+    // (per-request basket data served cross-session, found live). The raw
+    // container is untouched: handler-side ctx.use consumption (the
+    // consumption-lane rule, semantic-matrix PPR3) keeps real values.
+    const maskedPromise = containerPromise.then((container: unknown) =>
+      maskNestedContainerThenables(container),
+    );
+    maskedPromise.catch(() => {});
+    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+    return maskedPromise;
+  }
+
+  if (bakeSegmentKey) {
+    const seed = reqCtx?._shellLoaderSeed;
+    if (seed && seed.has(bakeSegmentKey)) {
+      const recorded = seed.get(bakeSegmentKey);
+      // HIT tail: run fresh (only the loader body can mint the live nested
+      // promises), then pin the recorded paths over it. A fresh REJECTION here
+      // skips the overlay and flows to the per-loader error boundary — the
+      // payload then diverges from the prelude (same residual class as uncached
+      // nondeterminism in shell material).
+      return executeLoaderData(loaderEntry, ctx, pathname).then(
+        (fresh: unknown) => overlayLoaderContainer(fresh, recorded),
+      );
+    }
+  }
+
+  return executeLoaderData(loaderEntry, ctx, pathname);
+}
+
+/** The pre-policy loader execution: cache read-through or plain ctx.use. */
+function executeLoaderData<TEnv>(
+  loaderEntry: LoaderEntry,
+  ctx: HandlerContext<any, TEnv>,
+  pathname: string,
+): Promise<any> {
+  const cacheConfig = loaderEntry.cache;
+
+  // No cache config or disabled — run fresh (zero overhead path)
+  if (!cacheConfig || cacheConfig.options === false) {
+    return ctx.use(loaderEntry.loader);
+  }
+
+  const store = getLoaderStore(loaderEntry);
+  if (!store?.getItem || !store?.setItem) {
+    return ctx.use(loaderEntry.loader);
+  }
+
+  // Evaluate runtime condition if provided
+  const options = cacheConfig.options;
+  if (options.condition) {
+    const requestCtx = getRequestContext();
+    if (requestCtx && !options.condition(requestCtx)) {
+      return ctx.use(loaderEntry.loader);
+    }
+  }
+
+  const loaderId = loaderEntry.loader.$$id;
+
+  // A handler that later awaits this same loader via ctx.use(loader) must get
+  // THIS memoized promise, not a fresh execution. Rather than rebind ctx.use
+  // once per cached loader (O(N) chained wrappers + a synchronous
+  // capture-before-overwrite invariant), install a single stable interceptor on
+  // the first cached loader that consults a per-ctx override table, then just
+  // prime the table for each subsequent cached loader. The captured pre-
+  // interceptor `originalUse` (whatever setup mode installed it) runs the
+  // cache-miss execute, so a loader never awaits its own in-flight promise.
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  let overrides = internal._loaderCacheOverrides;
+  if (!overrides) {
+    overrides = internal._loaderCacheOverrides = new Map();
+    const originalUse = ctx.use;
+    internal._loaderCacheOriginalUse = originalUse;
+    ctx.use = ((item: any) => {
+      const cached = overrides!.get(item?.$$id);
+      if (cached) return cached;
+      return originalUse(item);
+    }) as typeof ctx.use;
+  }
+  const runMiss = internal._loaderCacheOriginalUse!;
+
+  // Dedup the cache read-through across repeated resolutions of the SAME
+  // loaderId in one request. An orphan layout with parallel slots inherits its
+  // parent route's loaders, so resolveOrphanLayout (fresh.ts) re-resolves the
+  // parent's loaders under a different shortCode — calling resolveLoaderData
+  // again for the same loaderId. The cache key (loader:{loaderId}:{host}
+  // {pathname}:{sortedParams}) does not include the shortCode and ctx/params
+  // are identical, so both resolutions produce the same data. Reuse the already
+  // in-flight dataPromise instead of issuing a second getItem/setItem (e.g. a
+  // second KV round-trip) for one logical cached loader. The shortCode only
+  // affects the emitted segmentId in resolveLoaders, not the cached value.
+  const existing = overrides.get(loaderId);
+  if (existing) return existing;
+
+  // Compute ttl/swr/tags only AFTER the dedup short-circuit: a deduped second
+  // resolution of the same loaderId (the orphan-layout inheritance path) must
+  // not re-run the user tags() callback. These values are only consumed inside
+  // the read-through below, so they belong here, past the dedup gate.
+  const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
+  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
+  const swr = swrWindow || undefined;
+  const tags = resolveTags(loaderEntry);
+  recordRequestTags(tags);
+
+  const dataPromise = (async () => {
+    const codec = await getCodec();
+    const key = await resolveLoaderKey(
+      loaderEntry,
+      store,
+      loaderId,
+      pathname,
+      ctx.params,
+    );
+
+    // Capture the request context up front (foreground, ALS present) so the
+    // background stale revalidation can re-establish it. On workerd a waitUntil
+    // task runs detached from the request's I/O context, so a loader body that
+    // reads the ambient getRequestContext() would otherwise throw "called
+    // outside of a request context" and the revalidation would fail silently.
+    // The wrap is applied via wrapBackground (background path only); the
+    // foreground miss runs execute() directly since its context is present.
+    const requestCtxForExecute = getRequestContext();
+    return readThroughItem({
+      getItem: (k) => store.getItem!(k),
+      setItem: (k, v, o) => store.setItem!(k, v, o),
+      key,
+      execute: () => runMiss(loaderEntry.loader),
+      wrapBackground: (run) => runWithRequestContext(requestCtxForExecute, run),
+      serialize: (d) => codec.serializeResult(d),
+      deserialize: (v) => codec.deserializeResult(v),
+      storeOptions: { ttl, swr, tags },
+      onHit: () => debugLoaderCacheLog(`[LoaderCache] HIT: ${key}`),
+      onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
+      onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
+      onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
+      host: requestCtxForExecute,
+    });
+  })();
+
+  overrides.set(loaderId, dataPromise);
+
+  return dataPromise;
+}