@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

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

@@ -0,0 +1,368 @@
+/**
+ * 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 { observePhase, PHASES } from "../instrument.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)) {
+    // Capture lane, per LOADER (not per entry):
+    //
+    // - `ssr: false` (awaitBeforeFlush) — the BAKE lane. The flag's
+    //   document promise is "this loader's data is in the HTML before first
+    //   flush"; under ppr the pre-flush HTML IS the frozen prelude, so the
+    //   loader executes at capture and its SETTLED return bakes into the
+    //   shell. Nested-promise SHAPE stays the liveness declaration: nested
+    //   thenables are masked so their subtrees postpone as holes (per-request
+    //   material must be promise-shaped — the #692 cross-session scar). The
+    //   masked container registers on _shellCaptureLoaderRecords: it holds
+    //   the capture gate (bounded by ppr.captureTimeout) and pins into the
+    //   shell snapshot, so a HIT tail replays the baked value and the
+    //   hydration payload matches the frozen prelude byte-for-byte.
+    // - Every other loader — LIVE unconditionally: masked with a
+    //   never-resolving promise, postponed at its boundary (loading() or an
+    //   inline Suspense), streamed fresh per request. A masked reader with NO
+    //   boundary above it root-postpones and the <body> sanity gate refuses
+    //   the shell (eternal-MISS warning) — the degrade for boundary-less ppr
+    //   routes. A route whose loaders are ALL flagged therefore needs no
+    //   loading() at all: nothing masks, the shell captures complete.
+    if (loaderEntry.awaitBeforeFlush && bakeSegmentKey) {
+      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(() => {});
+      const maskedPromise = containerPromise.then((container: unknown) =>
+        maskNestedContainerThenables(container),
+      );
+      maskedPromise.catch(() => {});
+      reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+      return maskedPromise;
+    }
+    return createMaskedLoaderPromise();
+  }
+
+  if (bakeSegmentKey) {
+    const seed = reqCtx?._shellLoaderSeed;
+    if (seed && seed.has(bakeSegmentKey)) {
+      const recorded = seed.get(bakeSegmentKey)!;
+      if (!recorded.holes) {
+        // Pin-first (hole-free record): the pinned container is what the
+        // payload serves either way (recorded paths win wholesale), so
+        // resolve it immediately instead of gating on the fresh run's
+        // latency — a slow bake-lane loader body otherwise stalls the HIT
+        // tail for values that get discarded. The fresh run still executes
+        // for its side effects and cache read-through writes, lifetime-
+        // extended so the runtime cannot cancel it when the stream closes
+        // first; its rejection is swallowed here (the payload already
+        // matches the prelude, which a fresh error value never could).
+        //
+        // CONTRACT (deliberate divergence from the gated overlay's
+        // fresh-only-keys passthrough): a hole-free pin serves the pinned
+        // SHAPE wholesale — a key the fresh run adds mid-TTL is dropped.
+        // It could never render server-side anyway: no hole was postponed
+        // for it at capture, so the prelude froze the without-that-field
+        // branch and the resume pass has nothing to fill; passing it
+        // through only made the hydration payload disagree with the frozen
+        // prelude (client-side mismatch repair — the divergence class the
+        // snapshot exists to prevent). A field that is per-request must be
+        // promise-shaped at capture (masked -> hole marker -> holes: 1 ->
+        // the gated path below, which preserves fresh-only passthrough) or
+        // live behind loading(). Anything else is uncached nondeterminism
+        // in shell material — the documented drift residual.
+        const fresh = executeLoaderData(loaderEntry, ctx, pathname);
+        fresh.catch(() => {});
+        reqCtx?.executionContext?.waitUntil?.(fresh);
+        return Promise.resolve(
+          overlayLoaderContainer(undefined, recorded.container),
+        );
+      }
+      // Hole-carrying record: 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.container),
+      );
+    }
+  }
+
+  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),
+      // The rango.background span (kind=loader-revalidation) wraps the WHOLE
+      // stale revalidation — the re-execution AND the serialize/setItem write
+      // (read-through-swr routes the full task through wrapBackground) — so
+      // the loader's rango.loader span, its fetch/KV platform spans, and the
+      // store write all nest under one explanatory parent instead of dangling
+      // under the ended foreground phases. Inside runWithRequestContext so
+      // observePhase can read tracing on workerd (ALS detaches in waitUntil).
+      wrapBackground: (run) =>
+        runWithRequestContext(requestCtxForExecute, () =>
+          observePhase(PHASES.background("loader-revalidation"), 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;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * PPR shell-capture loader masking.
+ *
+ * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
+ * route loaders are the "live lane": they must NOT execute — no side effects, no
+ * cost, no cache round-trips. Instead every loader segment's value slot receives
+ * a never-resolving promise, so the loader-consuming Suspense subtree stays
+ * pending and React's static `prerender` marks it as a postponed hole. The frozen
+ * shell (prelude) captures only the fallback; the resumed serve pass runs the
+ * loaders fresh through the unchanged execution path and streams their output
+ * into the holes.
+ *
+ * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
+ * the derived request context of the background capture task (shell-capture.ts) —
+ * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
+ * capture is wanted" and must not change behavior. This module is the single home
+ * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * `resolveLoaderData`, fresh.ts `resolveLoaders`).
+ */
+
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
+
+/**
+ * True when the current render is the active PPR shell capture and route loaders
+ * must be masked rather than executed. Reads `_shellCaptureRun` off the ALS
+ * request context (the capture task re-establishes its derived context via
+ * runWithRequestContext), so it is accurate at the loader resolution sites, which
+ * run synchronously inside the pipeline's context frame.
+ */
+export function isShellCaptureActive(
+  reqCtx: RequestContext<any> | undefined = _getRequestContext(),
+): boolean {
+  return reqCtx?._shellCaptureRun === true;
+}
+
+// createMaskedLoaderPromise moved to the leaf module mask-nested.ts (shared
+// with the handle-push funnel in request-context, which cannot import THIS
+// module without a cycle). Re-exported to keep the mask API in one place.
+export { createMaskedLoaderPromise } from "./mask-nested.js";
+
+/**
+ * Entry-level lane input for an entry's loaders under PPR (the loading()
+ * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
+ * is per LOADER in loader-cache.ts: an `ssr: false`
+ * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
+ * flag's document promise ("data in the HTML before first flush") maps to
+ * the frozen prelude — while every other loader is LIVE (masked at capture,
+ * fresh on every serve), postponing at loading() or an inline Suspense.
+ * This helper still gates which entries pass a bake segment key for the
+ * legacy loading()-less shape and the HIT-tail seed overlay.
+ *
+ * Mirrors segment-system's isRenderableLoading so the mask decision and the
+ * tree's boundary placement can never disagree.
+ */
+export function entryLoadingMasksLoaders(loading: unknown): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}

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

@@ -0,0 +1,259 @@
+/**
+ * Loader-family capture snapshot: elide + overlay for bake-lane loader
+ * containers (docs/design/loader-container-bake.md).
+ *
+ * A loader on an entry with NO renderable loading() executes during shell
+ * capture; its settled container bakes into the prelude while every promise
+ * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
+ * payload byte-identical to that frozen prelude, the capture pins the container
+ * in the shell snapshot:
+ *
+ *   - elide:   deep-walk the settled container; a PENDING nested promise is a
+ *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
+ *              loader-cache masks every nested thenable at capture
+ *              ({@link maskNestedContainerThenables}), nested promises are
+ *              ALWAYS pending here for new captures. The SETTLED-marker branch
+ *              below is legacy: it fires only if a settled thenable reaches
+ *              elide anyway, and the overlay keeps decoding SETTLED markers
+ *              from pre-mask snapshots. The result is promise-free and
+ *              Flight-serializable.
+ *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
+ *              the live nested promises), then the recorded container is laid
+ *              over it: recorded paths win (they are what the prelude froze),
+ *              hole-marker paths take the fresh run's value (the live hole),
+ *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
+ *              wrote use(data.x) against a promise-shaped container, and
+ *              handing them the raw value throws React #438 on every HIT (the
+ *              storefront PDP regression) — and fresh-only paths pass through
+ *              (they cannot contradict prelude bytes that never rendered them).
+ */
+
+import { isThenable } from "../../handles/is-thenable.js";
+
+// Capture-side nested-thenable masking lives in the LEAF module mask-nested.ts
+// (request-context also needs it for handle pushes and cannot import through
+// loader-mask without a cycle). Re-exported here so loader-cache and the unit
+// tests keep one import site for the snapshot family.
+export { maskNestedContainerThenables } from "./mask-nested.js";
+
+/**
+ * Marker object standing in for a pending nested promise in a recorded loader
+ * container. Shape-checked (not identity-checked) because the record round-trips
+ * through Flight serialization and a JSON-embedding store envelope.
+ */
+export const LOADER_HOLE_KEY = "$rangoLoaderHole" as const;
+
+export interface LoaderHoleMarker {
+  [LOADER_HOLE_KEY]: 1;
+}
+
+export function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_HOLE_KEY] === 1
+  );
+}
+
+/**
+ * Marker wrapping the inlined value of a NESTED promise that settled during
+ * capture. The value baked (physics), but the container key was a promise —
+ * the overlay must hand consumers a Promise.resolve(value), not the raw value,
+ * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
+ * container is never wrapped: loader-cache overlays against the awaited fresh
+ * container value.
+ */
+export const LOADER_SETTLED_KEY = "$rangoLoaderSettled" as const;
+
+export interface LoaderSettledMarker {
+  [LOADER_SETTLED_KEY]: 1;
+  value: unknown;
+  /**
+   * Present when the pinned subtree contains hole markers. Computed once at
+   * capture (elide already visits every node) so the per-HIT overlay never
+   * rescans the pinned structure to pick its rehydration path.
+   */
+  holes?: 1;
+}
+
+export function isLoaderSettledMarker(
+  value: unknown,
+): value is LoaderSettledMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_SETTLED_KEY] === 1
+  );
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Probe whether a promise is already settled without waiting for it: races it
+ * against an immediately-resolved sentinel across two microtask hops (then
+ * chaining means a resolved inner value needs one extra hop to surface).
+ * Returns the settled state, or "pending" if it has not settled by then.
+ */
+async function probeSettled(
+  p: PromiseLike<unknown>,
+): Promise<
+  | { state: "fulfilled"; value: unknown }
+  | { state: "rejected" }
+  | { state: "pending" }
+> {
+  const PENDING = Symbol("pending");
+  // Two sentinel hops: Promise.resolve(p) adoption costs a microtask, so a
+  // single-hop sentinel would misreport an already-fulfilled promise as pending.
+  const sentinel = Promise.resolve()
+    .then(() => undefined)
+    .then(() => PENDING as unknown);
+  try {
+    const raced = await Promise.race([Promise.resolve(p), sentinel]);
+    if (raced === PENDING) return { state: "pending" };
+    return { state: "fulfilled", value: raced };
+  } catch {
+    return { state: "rejected" };
+  }
+}
+
+export type ElideResult =
+  | { state: "ok"; value: unknown; hasHole: boolean }
+  | { state: "rejected" };
+
+/**
+ * Deep-elide a settled bake-lane container for recording. Settled nested
+ * promises pin their value behind a settled marker (they baked, but consumers
+ * hold a promise-shaped key); pending ones become hole markers; a REJECTED
+ * nested promise poisons the record (error UI must never bake into a shared
+ * shell) — the caller refuses the capture. Only plain objects/arrays are
+ * traversed; anything else (Date, Map, class instance) is a pinned leaf.
+ * Cycles are cut as pinned references (best effort — Flight rejects true
+ * cycles later regardless).
+ *
+ * The ROOT container promise-chain unwraps with NO marker: loader-cache
+ * overlays against the AWAITED fresh container, so the recorded root must be
+ * the unwrapped structure. Everything below it goes through elideNested.
+ */
+export async function elideLoaderContainer(
+  value: unknown,
+  seen: Set<object> = new Set(),
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    return elideLoaderContainer(probed.value, seen);
+  }
+  return elideNested(value, seen);
+}
+
+async function elideNested(
+  value: unknown,
+  seen: Set<object>,
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    const inner = await elideNested(probed.value, seen);
+    if (inner.state === "rejected") return inner;
+    const marker: LoaderSettledMarker = inner.hasHole
+      ? { [LOADER_SETTLED_KEY]: 1, value: inner.value, holes: 1 }
+      : { [LOADER_SETTLED_KEY]: 1, value: inner.value };
+    return { state: "ok", value: marker, hasHole: inner.hasHole };
+  }
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
+    seen.add(value);
+    const out: unknown[] = new Array(value.length);
+    let hasHole = false;
+    for (let i = 0; i < value.length; i++) {
+      const r = await elideNested(value[i], seen);
+      if (r.state === "rejected") return r;
+      out[i] = r.value;
+      hasHole ||= r.hasHole;
+    }
+    return { state: "ok", value: out, hasHole };
+  }
+
+  if (isPlainObject(value)) {
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    let hasHole = false;
+    for (const key of Object.keys(value)) {
+      const r = await elideNested(value[key], seen);
+      if (r.state === "rejected") return r;
+      out[key] = r.value;
+      hasHole ||= r.hasHole;
+    }
+    return { state: "ok", value: out, hasHole };
+  }
+
+  return { state: "ok", value, hasHole: false };
+}
+
+/**
+ * Overlay a recorded (elided) container onto the fresh run's container for a
+ * shell HIT. Recorded wins per path; hole markers take the fresh value (the
+ * live nested promise); fresh-only object keys pass through. Where the shapes
+ * disagree structurally, recorded wins wholesale — it is what the prelude
+ * froze, and parity beats freshness inside the shell.
+ */
+export function overlayLoaderContainer(
+  fresh: unknown,
+  recorded: unknown,
+): unknown {
+  if (isLoaderHoleMarker(recorded)) return fresh;
+
+  if (isLoaderSettledMarker(recorded)) {
+    const pinned = recorded.value;
+    // Deep holes inside a settled container (capture-computed `holes` bit)
+    // need the fresh promise's resolved value to fill them; a fully-pinned
+    // container resolves immediately (the prelude already shows it — never
+    // gate it on fresh latency). A rejecting fresh run degrades holes to
+    // undefined instead of poisoning the pin.
+    if (recorded.holes === 1) {
+      return Promise.resolve(fresh).then(
+        (freshValue) => overlayLoaderContainer(freshValue, pinned),
+        () => overlayLoaderContainer(undefined, pinned),
+      );
+    }
+    return Promise.resolve(overlayLoaderContainer(undefined, pinned));
+  }
+
+  if (Array.isArray(recorded)) {
+    const freshArr = Array.isArray(fresh) ? fresh : [];
+    return recorded.map((item, i) => overlayLoaderContainer(freshArr[i], item));
+  }
+
+  if (isPlainObject(recorded)) {
+    if (!isPlainObject(fresh)) {
+      // Shape drift: still honor markers (holes fall back to undefined).
+      const out: Record<string, unknown> = {};
+      for (const key of Object.keys(recorded)) {
+        out[key] = overlayLoaderContainer(undefined, recorded[key]);
+      }
+      return out;
+    }
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(recorded)) {
+      out[key] = overlayLoaderContainer(fresh[key], recorded[key]);
+    }
+    for (const key of Object.keys(fresh)) {
+      if (!(key in out)) out[key] = fresh[key];
+    }
+    return out;
+  }
+
+  return recorded;
+}