@rangojs/router 0.20.0 → 0.22.0

package/src/build/generate-manifest.ts

@@ -61,6 +61,8 @@ export interface GeneratedManifest {
   prerenderRoutes?: string[];
   /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
   passthroughRoutes?: string[];
+  /** Route names opted into on-demand prerender (Prerender(..., { onDemand })) */
+  onDemandRoutes?: string[];
   /** Route name → response type for non-RSC routes */
   responseTypeRoutes?: Record<string, string>;
   /** Route name -> search schema descriptor for typed URL helpers */
@@ -172,6 +174,7 @@ async function buildPrefixTreeNode(
   prerenderRoutes?: string[],
   prerenderDefs?: Record<string, any>,
   passthroughRoutes?: string[],
+  onDemandRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
   routerId?: string,
@@ -264,6 +267,13 @@ async function buildPrefixTreeNode(
             passthroughRoutes.push(name);
           }
         }
+        if (
+          onDemandRoutes &&
+          entry.type === "route" &&
+          entry.isOnDemand === true
+        ) {
+          onDemandRoutes.push(name);
+        }
       }
     }
 
@@ -289,6 +299,7 @@ async function buildPrefixTreeNode(
         prerenderRoutes,
         prerenderDefs,
         passthroughRoutes,
+        onDemandRoutes,
         responseTypeRoutes,
         routeSearchSchemas,
         routerId,
@@ -455,6 +466,7 @@ export async function generateManifestFull<TEnv>(
   const prerenderRoutes: string[] = [];
   const prerenderDefs: Record<string, any> = {};
   const passthroughRoutes: string[] = [];
+  const onDemandRoutes: string[] = [];
   const responseTypeRoutes: Record<string, string> = {};
   for (const [name, entry] of manifest) {
     if (entry.type === "route" && entry.isPrerender) {
@@ -465,6 +477,9 @@ export async function generateManifestFull<TEnv>(
       if (entry.isPassthrough === true) {
         passthroughRoutes.push(name);
       }
+      if (entry.isOnDemand === true) {
+        onDemandRoutes.push(name);
+      }
     }
     if (entry.type === "route" && entry.responseType) {
       responseTypeRoutes[name] = entry.responseType;
@@ -485,6 +500,7 @@ export async function generateManifestFull<TEnv>(
       prerenderRoutes,
       prerenderDefs,
       passthroughRoutes,
+      onDemandRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
       options?.routerId,
@@ -502,6 +518,7 @@ export async function generateManifestFull<TEnv>(
     prerenderRoutes: prerenderRoutes.length > 0 ? prerenderRoutes : undefined,
     passthroughRoutes:
       passthroughRoutes.length > 0 ? passthroughRoutes : undefined,
+    onDemandRoutes: onDemandRoutes.length > 0 ? onDemandRoutes : undefined,
     responseTypeRoutes:
       Object.keys(responseTypeRoutes).length > 0
         ? responseTypeRoutes

package/src/build/merge-full-manifests.ts

@@ -136,6 +136,11 @@ export function mergeFullManifests(
         manifest.passthroughRoutes,
         overwrittenRoutes,
       ),
+      onDemandRoutes: mergeRouteList(
+        merged.onDemandRoutes,
+        manifest.onDemandRoutes,
+        overwrittenRoutes,
+      ),
       responseTypeRoutes: mergeRouteRecord(
         merged.responseTypeRoutes,
         manifest.responseTypeRoutes,

package/src/build/route-trie.ts

@@ -50,5 +50,6 @@ export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
       ? new Set(manifest.passthroughRoutes)
       : undefined,
     manifest.responseTypeRoutes,
+    manifest.onDemandRoutes ? new Set(manifest.onDemandRoutes) : undefined,
   );
 }

package/src/cache/background-task.ts

@@ -7,6 +7,8 @@
  * skipping.
  */
 
+import type { ExecutionContext } from "../types/request-scope.js";
+
 interface WaitUntilHost {
   waitUntil?: (fn: () => Promise<void>) => void;
 }
@@ -85,3 +87,62 @@ export async function settleGrowing(
   }
   return true;
 }
+
+/** Macrotask turns `awaitLaterMillisecond` waits at most. */
+export const LATER_MILLISECOND_MAX_TURNS = 10;
+
+/**
+ * Yield until `Date.now()` passes `since`, so a store's whole-millisecond tag
+ * gate (putShell vs an invalidation made just before) sees a later
+ * millisecond. Bounded: on Cloudflare the clock stands still between I/O
+ * events, so an unbounded wait could hang. At the bound the caller proceeds
+ * and a store may refuse the write, which its result reports.
+ */
+export async function awaitLaterMillisecond(
+  since: number,
+  maxTurns: number = LATER_MILLISECOND_MAX_TURNS,
+): Promise<void> {
+  for (let turn = 0; turn < maxTurns && Date.now() === since; turn++) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+/** An ExecutionContext that keeps every promise handed to `waitUntil`. */
+export interface CollectingExecutionContext extends ExecutionContext {
+  readonly tasks: Promise<unknown>[];
+}
+
+/**
+ * Wrap the caller's ExecutionContext (or none) so a caller can wait for the
+ * request's background work: the deferred cache writes, the shell capture, a
+ * store's own writes. Every other member reads through to `inner`, bound to
+ * it (workerd's methods reject a foreign `this`).
+ */
+export function createCollectingExecutionContext(
+  inner?: ExecutionContext,
+): CollectingExecutionContext {
+  const tasks: Promise<unknown>[] = [];
+  const own: CollectingExecutionContext = {
+    tasks,
+    waitUntil(promise) {
+      const task = Promise.resolve(promise);
+      // The list only waits; the host (or the log below) owns the failure.
+      tasks.push(task.catch(() => {}));
+      if (inner) inner.waitUntil(task);
+      else {
+        task.catch((error) =>
+          console.error("[waitUntil] Background task failed:", error),
+        );
+      }
+    },
+    passThroughOnException() {},
+  };
+  if (!inner) return own;
+  return new Proxy(own, {
+    get(target, prop) {
+      if (prop in target) return target[prop as keyof typeof target];
+      const value = (inner as unknown as Record<PropertyKey, unknown>)[prop];
+      return typeof value === "function" ? value.bind(inner) : value;
+    },
+  });
+}

package/src/cache/cache-key-utils.ts

@@ -22,7 +22,7 @@ import type { SearchParamsFilter } from "./search-params-filter.js";
  */
 const RESERVED_SEARCH_PARAMS = new Set(["__no_cache", "__rsc", "__html"]);
 
-function isReservedSearchParam(key: string): boolean {
+export function isReservedSearchParam(key: string): boolean {
   return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
 }
 
@@ -65,20 +65,37 @@ export function sortedRouteParams(
 }
 
 /**
- * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ * THE ROUTER RULE (#1065). A key that names one router's output for a host
+ * and path starts with the router part, `{encodeURIComponent(routerId)}@`. A
+ * key that names a function and its arguments, or a tag, does not.
  *
- * The ONE composition of the host-namespacing rule, shared by the segment tier
- * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
- * drift between them. Host prefixing matters because VercelCacheStore /
- * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
- * internally) -- on a single function serving multiple domains an
- * un-namespaced key bleeds tenant A's cached response to tenant B.
+ * - With the part: PPR shells and the build-shell manifest (buildShellKey,
+ *   buildShellManifestKey); route cache() records, the document cache and
+ *   response routes (cacheKeyBase); a loader's own cache() entry; a
+ *   `"use cache"` entry of a call that takes a ctx (a ctx is one router's:
+ *   its variables, env and reverse() map).
+ * - Without: a `"use cache"` entry of plain arguments or a bare Request
+ *   (requestArgKey); tag markers; a key the app builds itself
+ *   (`cache({ key })`, a `keyGenerator`).
  *
- * Output is BYTE-STABLE by contract: changing the composition silently
- * invalidates every persisted cache entry on upgrade. Callers append their own
- * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ * Why: a host and path do not name a router. A `hostOverride` cookie picks
+ * the router and forwards the request unmodified, and a `router.prerender()`
+ * warm requests whatever origin it resolved, so two routers on one store
+ * built one key and read each other's entry.
+ *
+ * The id (router.ts) has to be the same in every isolate and in build-time
+ * discovery: an explicit `id` and the injected `$$id` are, the `router_{n}`
+ * fallback is for a single router only (discover-routers.ts warns about
+ * more). Encoded, the id holds no `@` or `/`, and a host holds no `@`, so a
+ * key has a router part exactly when its first `@` comes before its first
+ * `/`: no id can be chosen to spell another router's key.
  */
-export function cacheKeyBase(
+export function routerKeyPrefix(routerId: string): string {
+  return `${encodeURIComponent(routerId)}@`;
+}
+
+/** `{host}{pathname}[:params][?search]`: what follows the router part. */
+function hostPathKey(
   host: string,
   pathname: string,
   searchParams?: URLSearchParams,
@@ -96,6 +113,68 @@ export function cacheKeyBase(
   return key;
 }
 
+/**
+ * Key base of one router's output (the router rule, routerKeyPrefix):
+ * `${routerId}@${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the namespacing rule, shared by the segment tier
+ * (cache-scope.ts), the document tier (document-cache.ts), the response tier
+ * (rsc/response-cache-serve.ts) and the loader cache so the rule cannot drift
+ * between them. Host prefixing matters because VercelCacheStore /
+ * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
+ * internally) -- on a single function serving multiple domains an
+ * un-namespaced key bleeds tenant A's cached response to tenant B.
+ *
+ * Output is BYTE-STABLE by contract: changing the composition silently
+ * invalidates every persisted cache entry on upgrade. Callers append their own
+ * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ */
+export function cacheKeyBase(
+  routerId: string,
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+  filter?: SearchParamsFilter,
+): string {
+  return `${routerKeyPrefix(routerId)}${hostPathKey(host, pathname, searchParams, params, filter)}`;
+}
+
+/**
+ * cacheKeyBase for the request context `ctx`. rsc/handler.ts sets `_routerId`
+ * before the request scope opens and derived contexts inherit it, so a served
+ * request always has one. Only a hand-built context has none (a unit test,
+ * the runLoader / renderHandler primitives): its key has no router part,
+ * which no router's key equals (routerKeyPrefix).
+ */
+export function requestKeyBase(
+  ctx: { readonly _routerId?: string } | null | undefined,
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+  filter?: SearchParamsFilter,
+): string {
+  const routerId = ctx?._routerId;
+  return routerId === undefined
+    ? hostPathKey(host, pathname, searchParams, params, filter)
+    : cacheKeyBase(routerId, host, pathname, searchParams, params, filter);
+}
+
+/**
+ * The `"use cache"` key part of a bare Request argument: its URL, with no
+ * router part (the router rule, routerKeyPrefix).
+ */
+export function requestArgKey(url: URL, filter?: SearchParamsFilter): string {
+  return hostPathKey(
+    url.host,
+    url.pathname,
+    url.searchParams,
+    undefined,
+    filter,
+  );
+}
+
 /**
  * The prefix of a `key()` result's part in a record key (#975), and of a
  * loader's own `key()` result after its `loader:<id>:` namespace (#1009,

package/src/cache/cache-policy.ts

@@ -13,6 +13,15 @@ import type { RequestContext } from "../server/request-context.js";
 import { normalizeTags } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
 
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
+ */
+export const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
+
 /**
  * Default TTL for route-level cache() DSL and loader cache.
  * Applied when neither the cache options nor the store defaults specify a TTL.
@@ -184,8 +193,8 @@ export function resolveTagsOption<TEnv>(
  * and on CFCacheStore would also cost a wasted KV marker read per request.
  * Returns undefined when nothing usable remains, keeping the entry header-free.
  */
-function normalizeTagList(tags: string[]): string[] | undefined {
-  const out = normalizeTags(tags);
+export function normalizeTagList(tags: string[]): string[] | undefined {
+  const out = [...new Set(normalizeTags(tags))];
   return out.length > 0 ? out : undefined;
 }
 

package/src/cache/cache-runtime.ts

@@ -42,7 +42,11 @@ import {
 } from "./handle-snapshot.js";
 import { startHandleCapture, useCacheRecordKey } from "./handle-capture.js";
 import { isHandle } from "../handle.js";
-import { cacheKeyBase, sortedSearchString } from "./cache-key-utils.js";
+import {
+  requestArgKey,
+  requestKeyBase,
+  sortedSearchString,
+} from "./cache-key-utils.js";
 import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -60,6 +64,8 @@ import {
   type CacheExecScope,
 } from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
+import { IN_FLIGHT_LEADER_MAX_WAIT_MS } from "./cache-policy.js";
+import { isWarmReplace, noteWarmWrite } from "../prerender/warm-request.js";
 import {
   executionStart,
   invalidatedSince,
@@ -314,15 +320,6 @@ interface InFlightExecution {
 
 const inFlightExecutions = new Map<string, InFlightExecution>();
 
-/**
- * How long a follower trusts an in-flight leader before evicting it and
- * running fresh. High enough that a slow-but-healthy upstream never triggers
- * duplicate work (a legitimate cached call taking >15s is already pathological);
- * low enough to bound the blast radius of a wedged leader to seconds, not the
- * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
- */
-const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
-
 /** Distinguishes a leader timeout from a leader rejection in raceLeader. */
 const LEADER_TIMED_OUT = Symbol("leader-timed-out");
 
@@ -499,9 +496,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         }
         if (ctx.params && typeof ctx.params === "object") {
           // Include host to prevent cross-host cache collisions (same
-          // pattern as route-level cache-scope.ts key generation).
+          // pattern as route-level cache-scope.ts key generation), led by the
+          // router part: a ctx is one router's (cache-key-utils.ts, the
+          // router rule).
           if (ctx.url?.host) {
-            keyArgs.push(ctx.url.host);
+            keyArgs.push(requestKeyBase(requestCtx, ctx.url.host, ""));
           }
           // Include route name to prevent collisions when the same cached
           // function is reused across routes with identical pathname/params
@@ -529,15 +528,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       } else if (arg instanceof Request) {
         // A raw Request (ctx.request) is request-scoped like ctx: fold in its
         // URL with the same host-namespacing and search normalization.
-        const url = new URL(arg.url);
         keyArgs.push(
-          cacheKeyBase(
-            url.host,
-            url.pathname,
-            url.searchParams,
-            undefined,
-            requestCtx?._searchParamsFilter,
-          ),
+          requestArgKey(new URL(arg.url), requestCtx?._searchParamsFilter),
         );
       } else if (arg != null && arg === requestCtx?.env) {
         // The request's env is left out: constant per deployment, and its
@@ -617,8 +609,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       return result;
     }
 
-    // Cache lookup
-    const cached = await store.getItem(cacheKey);
+    // Cache lookup. A router.prerender() warm reads a miss and leads its own
+    // execution below: a leader that started before the warm was called may
+    // be reading data from before the change the warm publishes, and a
+    // follower writes nothing of its own.
+    const warmReplace = isWarmReplace(requestCtx);
+    const cached = warmReplace ? null : await store.getItem(cacheKey);
 
     // Serve a cached entry on the hit path: deserialize the stored value,
     // replay handle data (gated on tainted args), and surface the entry's tags
@@ -767,7 +763,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                         ttl: profile.ttl,
                         swr: profile.swr,
                         tags: freshTags.length > 0 ? freshTags : undefined,
+                        startedAt: start.at,
                       });
+                      noteWarmWrite(requestCtx, "item");
                     }
                   },
                 ),
@@ -806,7 +804,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // against its OWN handle store (gated on ITS hasTaintedArgs), and records
     // tags into its OWN request — no deserialized result is shared across
     // requests. The store write stays exactly once (the leader's).
-    let existing = inFlightExecutions.get(cacheKey);
+    let existing = warmReplace ? undefined : inFlightExecutions.get(cacheKey);
     while (existing) {
       const remainingMs =
         IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
@@ -1022,7 +1020,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           ttl: profile.ttl,
           swr: profile.swr,
           tags: tags.length > 0 ? tags : undefined,
+          startedAt: start.at,
         });
+        noteWarmWrite(requestCtx, "item");
       } catch (writeError) {
         requestCtx?._reportBackgroundError?.(writeError, "cache-write");
       }

package/src/cache/cache-scope.ts

@@ -38,12 +38,11 @@ import {
 import {
   captureHandles,
   captureHandleOwners,
-  restoreHandles,
+  restoreRecordHandles,
   type OwnedPushDelivery,
   encodeHandles,
-  decodeHandles,
 } from "./handle-snapshot.js";
-import { cacheKeyBase, composeCacheKeys } from "./cache-key-utils.js";
+import { composeCacheKeys, requestKeyBase } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
   isFiniteNonNegativeSeconds,
@@ -53,6 +52,7 @@ import {
 } from "./cache-policy.js";
 import type { RequestContext } from "../server/request-context.js";
 import { runIdentityExempt } from "./cache-exec-scope.js";
+import { isWarmReplace, noteWarmWrite } from "../prerender/warm-request.js";
 
 /**
  * Narrow the request's route-record window (RequestContext._routeRecordWindow)
@@ -138,7 +138,7 @@ function getDefaultRouteCacheKey(
     ? "intercept"
     : (prefixOverride ?? (isPartial ? "partial" : "doc"));
 
-  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
+  return `${prefix}:${requestKeyBase(ctx, host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
 }
 
 // ============================================================================
@@ -735,15 +735,14 @@ export class CacheScope {
    * @param pathname - URL pathname for cache key generation
    * @param params - Route params for cache key generation
    * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
-   * @param ownedPushes - How restoreHandles delivers the record's
-   *   loader-owned values (withCacheLookup: the handler context's
-   *   _claimLoaderPushes, and on a document HIT tail the owners it restores)
+   * @param ownedPushes - What the record is to each loader's handle pushes
+   *   (withCacheLookup: loader-cache.ts loaderPins), called on a hit
    */
   async lookupRoute(
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
-    ownedPushes?: OwnedPushDelivery,
+    ownedPushes?: () => OwnedPushDelivery,
   ): Promise<{
     segments: ResolvedSegment[];
     shouldRevalidate: boolean;
@@ -779,7 +778,7 @@ export class CacheScope {
     pathname: string,
     params: Record<string, string>,
     isIntercept?: boolean,
-    ownedPushes?: OwnedPushDelivery,
+    ownedPushes?: () => OwnedPushDelivery,
   ): Promise<CacheRouteLookupOutcome> {
     if (!this.enabled) return { status: "bypass" };
     if (!this.conditionAllows("read")) return { status: "bypass" };
@@ -787,6 +786,12 @@ export class CacheScope {
     const store = this.getStore();
     if (!store) return { status: "bypass" };
 
+    // A router.prerender() warm renders as on a cold cache: the opt-outs
+    // above still answer `bypass`, and the miss lets the write path replace
+    // the record under the key it resolves (cacheRoute).
+    const ambientContext = _getRequestContext();
+    if (isWarmReplace(ambientContext)) return { status: "miss" };
+
     // Resolve cache key INSIDE the try so a throwing consumer key() (or a
     // store.keyGenerator) degrades to a cache miss (return null -> render
     // uncached) instead of crashing the foreground render. resolveCacheKey
@@ -827,7 +832,6 @@ export class CacheScope {
       // seeded record, which a document tail turns into the degrade
       // (ShellRecordUnavailableError).
       let segments: ResolvedSegment[];
-      const ambientContext = _getRequestContext();
       try {
         const codec = await import("./segment-codec.js");
         segments = ambientContext?._shellFragmentPayload
@@ -870,27 +874,24 @@ export class CacheScope {
         cached.tags,
       );
 
-      // Replay handle data. An empty string means the route pushed no handles —
-      // skip the decode entirely (the common case). Otherwise decode the
-      // Flight-encoded blob; a decode failure skips handle restore but keeps the
-      // valid cached segments.
+      // Before the handle replay: the implicit doc scope's marker arms the
+      // loader pins of a navigation replay here (matchPartialWithPprReplay),
+      // and `ownedPushes` reads them to decide which loader-owned values
+      // stand. The segments decoded, so the record serves from here on.
+      await this.onHit?.();
+
       const handleStore = _getRequestContext()?._handleStore;
-      if (handleStore && cached.handles) {
-        const handlesRecord = await decodeHandles(cached.handles);
-        if (handlesRecord) {
-          if (this.boundary !== undefined) {
-            const kept = new Set(segments.map((s) => s.id));
-            for (const id of Object.keys(handlesRecord)) {
-              if (!kept.has(id)) delete handlesRecord[id];
-            }
-          }
-          restoreHandles(
-            handlesRecord,
-            handleStore,
-            cached.handleOwners,
-            ownedPushes,
-          );
-        }
+      // An empty handles string means the route pushed none (the common
+      // case); a decode failure skips the restore but keeps the segments.
+      if (handleStore) {
+        await restoreRecordHandles(
+          handleStore,
+          cached,
+          ownedPushes?.(),
+          this.boundary !== undefined
+            ? new Set(segments.map((s) => s.id))
+            : undefined,
+        );
       }
 
       if (INTERNAL_RANGO_DEBUG) {
@@ -905,7 +906,6 @@ export class CacheScope {
       if (ambientContext)
         this.noteRecordWindow(ambientContext, cached.expiresAt, false);
 
-      await this.onHit?.();
       return { status: "hit", result: { segments, shouldRevalidate } };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
@@ -1105,15 +1105,25 @@ export class CacheScope {
         // the tree) or a rejected handle value as an error row and completes
         // normally; stored, every HIT would render that error until expiry.
         if (flightErrors.length > 0) throw flightErrors[0];
+        // A streamed handler recovered into its boundary fallback resolves, so
+        // Flight reports nothing; refuse like a Flight error row.
+        const recovered = requestCtx._recoveredHandlerErrors;
+        if (recovered?.size) {
+          const failed = nonLoaderSegments.find((s) => recovered.has(s.id));
+          if (failed) throw recovered.get(failed.id);
+        }
 
+        const recordTags = collectRecordTags(requestCtx, tags, [
+          ...nonLoaderSegments.map((s) => s.id),
+          handlesOwnerId,
+        ]);
         const data: CachedEntryData = {
           segments: serializedSegments,
           handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
-          tags: collectRecordTags(requestCtx, tags, [
-            ...nonLoaderSegments.map((s) => s.id),
-            handlesOwnerId,
-          ]),
+          tags: recordTags,
+          // The stamp is the render's start, not the write's (#1068).
+          ...(start && recordTags?.length ? { taggedAt: start.at } : {}),
         };
         if (handleOwners && encodedHandles) data.handleOwners = handleOwners;
 
@@ -1127,6 +1137,8 @@ export class CacheScope {
         }
 
         await store.set(key, data, ttl, swr);
+        // The implicit doc scope's record lives in the shell entry only.
+        if (!this.isShellImplicitDocScope) noteWarmWrite(requestCtx, "record");
 
         if (INTERNAL_RANGO_DEBUG) {
           const segmentTypes = nonLoaderSegments.map((s) =>
@@ -1175,7 +1187,7 @@ function collectRecordTags(
  * enclosing scopes on another store (#974) and of a scope without its own
  * `key()` (#970)); with none, the app store's keyGenerator result
  * given the document default key. Undefined (synchronously, with no work)
- * when neither applies: the shell key stays host + path + filtered search.
+ * when neither applies: the shell key stays unpartitioned (buildShellKey).
  * Resolves to null when the partition is the default key itself (a
  * keyGenerator that returns it unchanged): that partitions nothing, so the
  * shell stays unpartitioned and keeps its build shell. The shell's key, its