@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.147

package/src/prerender/shell-manifest-key.ts

@@ -0,0 +1,20 @@
+/**
+ * Build shell manifest key, shared by the producer (the build's shell
+ * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
+ * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
+ * cannot drift. Dependency-free: the producer runs node-side in the plugin,
+ * the consumer in the RSC runtime.
+ *
+ * PATHNAME-ONLY by design. Host-free because the build knows no request
+ * host. Router-free because the router id ($$id) is a hash of
+ * filePath:lineNumber of the TRANSFORMED source, which differs between the
+ * discovery temp server's dev-style transform chain and the main build's —
+ * a temp-realm router id can never be looked up by the shipped worker. The
+ * producer instead detects pathname collisions across routers at build time
+ * and declines both entries (loudly), keeping the key unambiguous. This is
+ * a manifest namespace, never a store keyspace: the runtime shell key
+ * (host + pathname + search + ":shell") stays untouched.
+ */
+export function buildShellManifestKey(pathname: string): string {
+  return pathname;
+}

package/src/prerender/store.ts

@@ -73,7 +73,16 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
       if (isIntercept) url += "&intercept=1";
       if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
-        const res = await fetch(url);
+        // Bounded: this fetch also runs inside the PPR shell capture (a
+        // workerd waitUntil task), where an unsettled fetch does not reject —
+        // it pends until the task is torn down. Unbounded, one pending fetch
+        // wedged the per-isolate capture queue on GH runners (rotating dev
+        // capture failures; endpoint instrumentation showed 3-4ms memo HITs,
+        // so latency was never the issue — settlement was). On timeout the
+        // catch degrades to a store miss and the pipeline falls through to
+        // the live handler render (the documented dev fall-through), so the
+        // capture still lands with live content.
+        const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
         if (!res.ok) return null;
         return res.json();
       } catch {

package/src/router/match-middleware/cache-lookup.ts

@@ -112,6 +112,9 @@ let prerenderStoreInstance: PrerenderStore | null | undefined;
 let _deserializeSegments:
   | typeof import("../../cache/segment-codec.js").deserializeSegments
   | undefined;
+let _fragmentSegments:
+  | typeof import("../../cache/segment-codec.js").fragmentSegments
+  | undefined;
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
@@ -135,6 +138,7 @@ async function ensurePrerenderDeps() {
       import("../../prerender/store.js"),
     ]);
     _deserializeSegments = codec.deserializeSegments;
+    _fragmentSegments = codec.fragmentSegments;
     _restoreHandles = snapshot.restoreHandles;
     _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
@@ -237,6 +241,7 @@ async function* yieldFromStore<TEnv>(
 
   if (
     !_deserializeSegments ||
+    !_fragmentSegments ||
     !_restoreHandles ||
     !_decodeHandles ||
     !_hashParams ||
@@ -245,7 +250,13 @@ async function* yieldFromStore<TEnv>(
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
 
-  const segments = await _deserializeSegments(entry.segments);
+  // Shell-HIT tail (issue #700): a Prerender+ppr route's tail serves from THIS
+  // store (the prerender lookup runs before the cache scope), so the fragment
+  // splice must apply here too — otherwise producer B entries re-serialize the
+  // whole tree per request while producer A entries do not.
+  const segments = _getRequestContext()?._shellFragmentPayload
+    ? await _fragmentSegments(entry.segments)
+    : await _deserializeSegments(entry.segments);
 
   // Replay handle data (same as runtime cache hit path). entry.handles is a
   // Flight-encoded string ("" when none) — decode before restore so

package/src/router/prerender-match.ts

@@ -21,6 +21,7 @@ import type { RouterContext } from "./router-context.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
 import { runWithRouterContext } from "./router-context.js";
 import type { EntryData, InterceptEntry } from "../server/context";
+import type { PartialPrerenderProps } from "../urls/pattern-types.js";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -74,6 +75,13 @@ export async function matchForPrerender<TEnv = any>(
    *  the sinks store it as-is (no longer merge raw records). */
   interceptHandles?: string;
   passthrough?: true;
+  /**
+   * The matched route entry's `ppr` path option, surfaced so the build
+   * collection can flag Prerender+ppr routes as build-time shell candidates
+   * (issue #699 producer B). Runtime-only today; the build otherwise never
+   * sees the option (it lives on EntryData, not the trie).
+   */
+  ppr?: boolean | PartialPrerenderProps;
 } | null> {
   // 1. Find the matching route entry
   const matched = await deps.findMatch(pathname);
@@ -306,6 +314,18 @@ export async function matchForPrerender<TEnv = any>(
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
 
+      // Surface the matched route entry's ppr option for the build collection
+      // (leaf-first: the deepest type:"route" entry in the ancestor chain is
+      // the matched page route; ancestors are layouts/includes).
+      let routePpr: boolean | PartialPrerenderProps | undefined;
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i]!;
+        if (e.type === "route") {
+          routePpr = e.ppr;
+          break;
+        }
+      }
+
       // 14. Resolve intercept segments for this route (if any ancestor defines
       //     an intercept targeting this route). At build time we skip when()
       //     evaluation -- we pre-render all intercepts unconditionally and let
@@ -420,6 +440,7 @@ export async function matchForPrerender<TEnv = any>(
         params: matchedParams,
         interceptSegments,
         interceptHandles,
+        ppr: routePpr,
       };
     });
   });

package/src/rsc/capture-queue.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-isolate shell-capture serialization.
+ *
+ * Captures are CPU-bound background renders whose quiet detection is
+ * task-quantized (FLIGHT_QUIET_HOPS macrotask hops with zero new bytes). Two
+ * captures running concurrently starve each other: one grinding capture —
+ * e.g. a prerender+ppr route whose capture round-trips the dev
+ * /__rsc_prerender endpoint, whose per-request module re-import can peg a
+ * slow CI runner for seconds — keeps the sibling's render byte-silent past
+ * its abort budget, so the sibling freezes a trivial prelude and stores
+ * nothing. Observed on GH runners as ROTATING eternal-MISS victims (the
+ * warmup on one shard, a composition probe, then /ppr-shell?probe=stream once
+ * the first was quieted) while every local run passed.
+ *
+ * Serializing capture execution removes the cross-talk: each capture's quiet
+ * window observes only its own work. Captures are TTL-scale background work,
+ * so queueing costs latency-to-HIT only — never a served response. On workerd
+ * a queued capture rides the scheduling request's waitUntil, whose lifetime
+ * is bounded; a capture killed mid-queue by that bound simply recaptures on a
+ * later request (the existing best-effort contract).
+ *
+ * The chain link resolves in `finally` and the prior link is awaited with a
+ * swallow, so one rejected capture can never wedge every later one.
+ */
+let captureQueue: Promise<void> = Promise.resolve();
+
+/**
+ * Upper bound on how long one queue link may hold the queue. A capture task
+ * normally settles well inside this (attempt + in-place retry + writes), but
+ * a task wedged on never-settling I/O — a workerd waitUntil fetch that pends
+ * instead of rejecting (seen on GH runners with the dev prerender store
+ * before its fetch was time-bounded) — must not block every later capture in
+ * the isolate. At the cap the QUEUE is released; the wedged task itself stays
+ * detached (its own per-key guards clean up when/if it settles).
+ */
+const QUEUE_LINK_CAP_MS = 60_000;
+
+/**
+ * Run `task` after every previously enqueued capture has settled. Returns a
+ * promise for THIS task's completion (rejections propagate to the caller —
+ * the queue itself is insulated).
+ */
+export function enqueueSerializedCapture(
+  task: () => Promise<void>,
+): Promise<void> {
+  const prior = captureQueue;
+  let releaseQueue!: () => void;
+  captureQueue = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  return (async () => {
+    await prior.catch(() => {});
+    let capTimer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        task(),
+        new Promise<void>((resolve) => {
+          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+          (capTimer as { unref?: () => void }).unref?.();
+        }),
+      ]);
+    } finally {
+      if (capTimer) clearTimeout(capTimer);
+      releaseQueue();
+    }
+  })();
+}

package/src/rsc/rsc-rendering.ts

@@ -44,6 +44,7 @@ import {
   warnShellStoreMissingOnce,
   warnPprNonceActiveOnce,
 } from "./shell-serve.js";
+import { lookupBuildShell } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
 import {
   resolveSameOriginRedirect,
@@ -172,6 +173,36 @@ async function handleRscRenderingInner<TEnv>(
             store,
             debug: INTERNAL_RANGO_DEBUG,
           };
+          // One serve funnel for BOTH entry sources (runtime store hit below,
+          // build-manifest hit further down): schedule the background
+          // recapture when asked, then commit the composed response.
+          const serveHit = (
+            entry: ShellCacheEntry,
+            revalidate: boolean | undefined,
+          ): Response => {
+            if (revalidate) {
+              scheduleShellCapture(
+                ctx,
+                request,
+                env,
+                url,
+                reqCtx,
+                ssrModule,
+                descriptor,
+              );
+            }
+            return serveShellHit(
+              ctx,
+              request,
+              env,
+              url,
+              reqCtx,
+              handleStore,
+              ssrModule,
+              entry,
+              descriptor,
+            );
+          };
           let cached: Awaited<ReturnType<typeof store.getShell>> = null;
           try {
             cached = await store.getShell(key);
@@ -196,30 +227,43 @@ async function handleRscRenderingInner<TEnv>(
             } else {
               // Stale (SWR) hit: serve the stale shell now, recapture in the
               // background (stampede-guarded + backoff inside scheduleShellCapture).
-              if (cached.shouldRevalidate) {
-                scheduleShellCapture(
-                  ctx,
-                  request,
-                  env,
-                  url,
-                  reqCtx,
-                  ssrModule,
-                  descriptor,
-                );
-              }
-              return serveShellHit(
-                ctx,
-                request,
-                env,
-                url,
-                reqCtx,
-                handleStore,
-                ssrModule,
-                cached.entry,
-                descriptor,
-              );
+              return serveHit(cached.entry, cached.shouldRevalidate);
             }
           }
+          // Build-time shell read-through (producer B, #699): on a runtime
+          // store MISS (or an invalid/corrupt runtime entry), a Prerender+ppr
+          // route's shell was already produced at `vite build` — serve it
+          // through the SAME serveShellHit, so the first-ever request after a
+          // deploy is a HIT with zero runtime capture. lookupBuildShell owns
+          // every gate (search-less request, versions, integrity, tag
+          // markers) and fails to null — the ordinary MISS path below takes
+          // over. Past ppr.ttl the baked entry still serves but a runtime
+          // recapture is scheduled: SWR is the UPGRADE path from build entry
+          // to fresher runtime entry (the runtime store read above wins once
+          // the capture lands).
+          const buildHit = await lookupBuildShell(
+            url,
+            ctx.version,
+            store,
+            // Dev: no build manifest exists; producer B runs on demand via
+            // the dev server's /__rsc_shell endpoint for PRERENDERED routes
+            // only (production's exact candidate set). Folded away in
+            // production builds (NODE_ENV is a compile-time constant).
+            process.env.NODE_ENV !== "production"
+              ? {
+                  isPrerenderRoute:
+                    reqCtx._classifiedRoute?.matched?.pr === true,
+                  routeName: reqCtx._classifiedRoute?.routeKey,
+                  ttl: pprConfig.ttl,
+                  swr: pprConfig.swr,
+                  tags: pprConfig.tags,
+                }
+              : undefined,
+          );
+          if (buildHit) {
+            // Past ppr.ttl: still serve the baked entry, recapture upgrades it.
+            return serveHit(buildHit.entry, buildHit.stale);
+          }
           // MISS (no entry, invalid reactVersion, or store read failure): axis 1
           // + a background capture scheduled once the response is known servable.
           pprMiss = { descriptor, ssrModule };
@@ -609,9 +653,24 @@ function serveShellHit(
           `[Server][ppr] shell HIT: fast path declined — handler-live holes; tail re-runs handlers (abs ${Math.round(performance.now())})`,
         );
       }
+      // Fragment splice (issue #700): cache/prerender-store hits inside THIS
+      // tail render emit their stored segment fragments verbatim into the
+      // payload; the SSR resume pass and browser hydration expand them
+      // (segment-fragments.ts). Tail-only: the flag lives on the derived
+      // context so it can never leak into a capture render (which serializes
+      // segments and must see real elements).
+      seededCtx._shellFragmentPayload = true;
       return runWithRequestContext(seededCtx, () => renderTail(seededCtx));
     }
-    return renderTail(reqCtx);
+    // No snapshot (e.g. a producer B entry whose capture hit only the
+    // prerender store): still a shell-HIT tail, so arm the fragment splice on
+    // a derived context — the tail's prerender-store/cache hits (if any) then
+    // splice; a route with neither serves exactly as before. Derived, never
+    // the shared reqCtx: scheduleShellCapture derives the capture context from
+    // reqCtx and the flag must not be inherited there.
+    const fragmentCtx: RequestContext<any> = Object.create(reqCtx);
+    fragmentCtx._shellFragmentPayload = true;
+    return runWithRequestContext(fragmentCtx, () => renderTail(fragmentCtx));
   })();
   // The stream below is the only consumer; pre-attach a no-op catch so a tail
   // failure before the stream is pulled never surfaces as an unhandled rejection.

package/src/rsc/shell-build-manifest.ts

@@ -0,0 +1,244 @@
+/**
+ * Build-time shell entry read-through (producer B, issue #699).
+ *
+ * The build stages one ShellCacheEntry per Prerender+ppr URL as a lazy
+ * manifest module injected into the RSC bundle
+ * (`globalThis.__loadShellManifestModule`, mirroring the prerender payload
+ * manifest — the worker handles every request; nothing is served from
+ * assets). The serve path consults this on a runtime shell-store MISS, so the
+ * FIRST request after a deploy is already a shell HIT with zero runtime
+ * capture. The worker cannot tell where an entry came from: a build hit is
+ * served through the same serveShellHit as a captured one.
+ *
+ * Lifecycle:
+ * - No expiry until the next deploy — the buildVersion gate retires entries
+ *   the moment a new build ships (a new manifest replaces them anyway).
+ * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
+ *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
+ *   from build entry to fresher runtime entry, not the bootstrap path. The
+ *   runtime store is consulted first, so a captured entry supersedes the
+ *   build entry as soon as it lands.
+ * - `updateTag()` evicts build entries like runtime ones: the read-through
+ *   validates the entry's baked tag union against the store's tag
+ *   invalidation markers (isTagsInvalidatedSince) with the entry's createdAt
+ *   as the reference instant. No tombstones — the manifest is immutable; the
+ *   markers say whether it is still current.
+ */
+
+import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+import { hasIntactShellPayload, isValidShellHit } from "./shell-serve.js";
+import { buildShellManifestKey } from "../prerender/shell-manifest-key.js";
+
+/** One baked manifest record (the __ps asset module's default export). */
+export interface BuildShellEntry {
+  entry: ShellCacheEntry;
+  /** Resolved ppr ttl (seconds) — drives staleness/recapture, never expiry. */
+  ttl: number;
+  swr?: number;
+  /** The putShell-barrier tag union baked at build (static + recorded). */
+  tags?: string[];
+  routeName: string;
+}
+
+interface ShellManifestModule {
+  /** Manifest key (pathname — see shell-manifest-key.ts) -> asset specifier. */
+  default: Record<string, string>;
+  loadShellAsset: (spec: string) => Promise<{ default: BuildShellEntry }>;
+}
+
+declare global {
+  // Injected into the built RSC entry by the shell prerender phase
+  // (vite/discovery/shell-prerender-phase.ts): lazy loader for the shell
+  // manifest module.
+  // eslint-disable-next-line no-var
+  var __loadShellManifestModule:
+    | (() => Promise<ShellManifestModule>)
+    | undefined;
+}
+
+let manifestPromise: Promise<ShellManifestModule | null> | null = null;
+
+function loadManifest(): Promise<ShellManifestModule | null> {
+  if (!manifestPromise) {
+    const loader = globalThis.__loadShellManifestModule;
+    if (!loader) return Promise.resolve(null);
+    // A failing import is memoized as absent: the module is a build artifact,
+    // so the failure is deterministic — retrying per request only re-pays it.
+    manifestPromise = loader().catch(() => null);
+  }
+  return manifestPromise;
+}
+
+/**
+ * Per-spec verdict memo for the version + integrity gates. A manifest record
+ * is immutable for the process lifetime (content-hashed asset module), so its
+ * gate verdict is constant — without this, EVERY request to a baked ppr route
+ * re-decodes the full prelude base64 (hasIntactShellPayload) on the hot path:
+ * a fresh build hit never populates the runtime store, so the store MISS +
+ * read-through is the steady state, not a warm-up. Only the per-request
+ * gates (tag markers, staleness) stay outside the memo. `null` memoizes a
+ * failed verdict — deterministically invalid, don't re-pay the decode.
+ * Spec-only keying is sound because buildVersion is process-constant on the
+ * manifest path (folded into the shipped worker; dev never loads a manifest).
+ */
+const validatedSpecs = new Map<string, BuildShellEntry | null>();
+
+async function validatedManifestRecord(
+  mod: ShellManifestModule,
+  spec: string,
+  buildVersion: string,
+): Promise<BuildShellEntry | undefined> {
+  let verdict = validatedSpecs.get(spec);
+  if (verdict === undefined) {
+    const record = (await mod.loadShellAsset(spec)).default;
+    verdict =
+      isValidShellHit(record.entry, buildVersion) &&
+      hasIntactShellPayload(record.entry)
+        ? record
+        : null;
+    validatedSpecs.set(spec, verdict);
+  }
+  return verdict ?? undefined;
+}
+
+/** Reset the memoized manifest (unit tests swap the global loader). */
+export function resetBuildShellManifestForTests(): void {
+  manifestPromise = null;
+  validatedSpecs.clear();
+}
+
+/** Keys already warned about a tag-check-incapable store (once per key). */
+const warnedTagCheckUnsupported = new Set<string>();
+
+export interface BuildShellHit {
+  entry: ShellCacheEntry;
+  /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
+  stale: boolean;
+}
+
+/**
+ * Dev-mode lookup context: there is no build manifest in dev, so producer B
+ * runs ON DEMAND through the Vite dev server's /__rsc_shell endpoint
+ * (memoized per router HMR generation), mirroring the dev prerender store's
+ * /__rsc_prerender flow. Only armed for PRERENDERED routes (matched.pr) —
+ * exactly production's candidate set; everything else keeps runtime capture.
+ */
+export interface DevShellLookup {
+  /** True when the classified route is trie-flagged pr (Prerender-backed). */
+  isPrerenderRoute: boolean;
+  /** Canonical route key of the classified route (endpoint verification). */
+  routeName: string | undefined;
+  /** Resolved ppr policy from the serve gate (the endpoint is policy-free). */
+  ttl: number;
+  swr?: number;
+  tags?: string[];
+}
+
+/**
+ * Bound like the dev prerender store fetch (see #697): inside a workerd
+ * waitUntil an unsettled fetch pends forever instead of rejecting; on
+ * timeout this degrades to a MISS and the runtime capture path takes over.
+ * 20s (not the store fetch's 10s): the endpoint's response IS an inline
+ * capture — up to ~5s attempt + 400ms + ~5s cold-graph retry — and this
+ * fetch blocks a foreground document request, so it must outlast a full
+ * cold capture cycle rather than abort into a MISS at 10s.
+ */
+const DEV_SHELL_FETCH_TIMEOUT_MS = 20_000;
+
+async function fetchDevShellEntry(
+  pathname: string,
+  buildVersion: string,
+  dev: DevShellLookup,
+): Promise<BuildShellEntry | undefined> {
+  if (!dev.isPrerenderRoute || !dev.routeName) return undefined;
+  const devUrl = globalThis.__PRERENDER_DEV_URL;
+  if (!devUrl) return undefined;
+  const params = new URLSearchParams({
+    pathname,
+    routeName: dev.routeName,
+    ttl: String(dev.ttl),
+    version: buildVersion,
+  });
+  if (dev.swr !== undefined) params.set("swr", String(dev.swr));
+  if (dev.tags && dev.tags.length > 0) params.set("tags", dev.tags.join(","));
+  try {
+    const res = await fetch(`${devUrl}/__rsc_shell?${params}`, {
+      signal: AbortSignal.timeout(DEV_SHELL_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return undefined;
+    return (await res.json()) as BuildShellEntry;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Look up the baked shell entry for a request, applying every serve gate:
+ * search-less requests only (the build captured the bare pathname; a
+ * search-bearing URL has its own shell identity owned by runtime capture),
+ * version validity, payload integrity, and tag-invalidation markers. Returns
+ * null on any gate failure — the caller degrades to the ordinary MISS path
+ * (axis 1 + runtime capture), never a broken serve.
+ */
+export async function lookupBuildShell(
+  url: URL,
+  buildVersion: string,
+  store: SegmentCacheStore,
+  dev?: DevShellLookup,
+): Promise<BuildShellHit | null> {
+  try {
+    // Source-presence first: with no manifest and no dev context this is the
+    // steady-state MISS shape for every non-baked ppr route — return before
+    // the searchParams sort/allocation below.
+    const hasManifest = globalThis.__loadShellManifestModule !== undefined;
+    if (!hasManifest && !dev) return null;
+    if (sortedSearchString(url.searchParams) !== "") return null;
+    let record: BuildShellEntry | undefined;
+    if (hasManifest) {
+      const mod = await loadManifest();
+      if (!mod) return null;
+      const spec = mod.default[buildShellManifestKey(url.pathname)];
+      if (!spec) return null;
+      record = await validatedManifestRecord(mod, spec, buildVersion);
+    } else if (dev) {
+      const fetched = await fetchDevShellEntry(url.pathname, buildVersion, dev);
+      record =
+        fetched !== undefined &&
+        isValidShellHit(fetched.entry, buildVersion) &&
+        hasIntactShellPayload(fetched.entry)
+          ? fetched
+          : undefined;
+    }
+    if (!record) return null;
+    const entry = record.entry;
+    if (record.tags && record.tags.length > 0) {
+      const check = store.isTagsInvalidatedSince;
+      if (typeof check !== "function") {
+        // A tagged build entry on a store that cannot answer "was this tag
+        // invalidated since the build" must not serve: updateTag() could
+        // never evict it. Declared intent that cannot be honored deserves a
+        // diagnostic; the route keeps runtime-capture semantics.
+        const key = buildShellManifestKey(url.pathname);
+        if (!warnedTagCheckUnsupported.has(key)) {
+          warnedTagCheckUnsupported.add(key);
+          console.warn(
+            `[rango] Build-time shell for "${url.pathname}" carries cache tags, but ` +
+              "the app cache store does not implement isTagsInvalidatedSince(), so " +
+              "updateTag() could not evict it. The entry is not served; the route " +
+              "keeps runtime shell capture. Use MemorySegmentCacheStore, CFCacheStore, " +
+              "or VercelCacheStore (or add the method to your custom store).",
+          );
+        }
+        return null;
+      }
+      if (await check.call(store, record.tags, entry.createdAt)) return null;
+    }
+    const stale = Date.now() >= entry.createdAt + record.ttl * 1000;
+    return { entry, stale };
+  } catch {
+    // Any read-through fault is a MISS, never a 500 — the ordinary axis-1 +
+    // runtime-capture path takes over.
+    return null;
+  }
+}