@rangojs/router 0.20.0 → 0.21.0

package/src/cache/cache-scope.ts

@@ -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" };
@@ -870,11 +869,23 @@ export class CacheScope {
         cached.tags,
       );
 
+      // 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;
+      // With or without a handles blob: a pinned loader whose capture pushed
+      // nothing has no copy in the record, and its run on this request must
+      // still add no settled push (HandleStore.setRecordAuthority).
+      const owned = handleStore ? ownedPushes?.() : undefined;
+      if (owned) handleStore?.setRecordAuthority(owned);
+
       // 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.
-      const handleStore = _getRequestContext()?._handleStore;
       if (handleStore && cached.handles) {
         const handlesRecord = await decodeHandles(cached.handles);
         if (handlesRecord) {
@@ -888,7 +899,7 @@ export class CacheScope {
             handlesRecord,
             handleStore,
             cached.handleOwners,
-            ownedPushes,
+            owned,
           );
         }
       }
@@ -905,7 +916,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

package/src/cache/cf/cf-cache-store.ts

@@ -1,5 +1,3 @@
-/// <reference path="../../vite/plugins/version.d.ts" />
-
 // Extend CacheStorage with Cloudflare's default cache property
 declare global {
   interface CacheStorage {
@@ -50,7 +48,10 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
-import { VERSION } from "@rangojs/router:version";
+import {
+  versionKeyPrefix,
+  type KeyVersion,
+} from "../../server/build-version-table.js";
 import {
   isPerClientSignalHeader,
   stripPerClientSignals,
@@ -314,10 +315,9 @@ interface KVItemEnvelope {
 
 /**
  * Key namespace of the shell family. `shell2:` holds the prelude-first frame
- * (cf-shell-frame.ts); `shell:` held the JSON envelope. Every deploy retires
- * the old entries anyway (buildVersion gate); the new namespace also keeps
- * new code from reporting an old body as corrupt and a rollback from parsing
- * a frame. Old keys age out by their TTL.
+ * (cf-shell-frame.ts); `shell:` held the JSON envelope. The separate
+ * namespace keeps new code from reporting an old body as corrupt and a
+ * rollback from parsing a frame. Old keys age out by their TTL.
  */
 const SHELL_KEY_PREFIX = "shell2:";
 
@@ -494,7 +494,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly namespace?: string;
   private readonly explicitBaseUrl?: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
-  private readonly version?: string;
+  /** The `version` option: used for every versioned family when set. */
+  private readonly explicitVersion?: string;
   private readonly edgeLookupTimeoutMs: number;
   private readonly edgeReadTimeoutMs: number;
   private readonly kvReadTimeoutMs: number;
@@ -540,7 +541,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // the internal host. Only the explicit override can be captured eagerly.
     this.explicitBaseUrl = options.baseUrl;
     this.defaults = options.defaults;
-    this.version = options.version ?? VERSION;
+    this.explicitVersion = options.version;
     // Coalesce only finite numbers to the override; a non-finite value (NaN from
     // `Number(env.UNSET)`, or Infinity) would otherwise sail past `?? DEFAULT`
     // (which only replaces null/undefined) into setTimeout, where NaN/Infinity
@@ -1134,7 +1135,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.isReservedSegmentKey(key, "cache-read")) return null;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(key);
+      const request = this.keyToRequest(key, "data");
       const matchStart = Date.now();
       const {
         response,
@@ -1381,7 +1382,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.skipUncacheableTagSet(data.tags)) return;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(key);
+      const request = this.keyToRequest(key, "data");
 
       // Extended TTL covers SWR window
       const swrWindow = resolveSwrWindow(swr, this.defaults);
@@ -1457,11 +1458,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.isReservedSegmentKey(key, "cache-delete")) return false;
     try {
       const cache = await this.getCache();
-      const result = await cache.delete(this.keyToRequest(key));
+      const result = await cache.delete(this.keyToRequest(key, "data"));
 
       // L2: delete from KV
       if (this.kv && this.waitUntil) {
-        const kvKey = await this.toKVKey(key);
+        const kvKey = await this.toKVKey(key, "data");
         this.waitUntil(() =>
           reportingAsync(
             () => this.kv!.delete(kvKey),
@@ -1492,7 +1493,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`doc:${key}`);
+      const request = this.keyToRequest(`doc:${key}`, "document");
       // The document path is outside the debug surface (op is only get/getItem),
       // so the match-timeout flag is not surfaced as an event here -- though
       // matchWithTimeout still warns on a slow match. A miss or timeout falls
@@ -1633,7 +1634,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.skipUncacheableTagSet(tags)) return;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`doc:${key}`);
+      const request = this.keyToRequest(`doc:${key}`, "document");
 
       // Extended TTL covers SWR window
       const swrWindow = resolveSwrWindow(swr, this.defaults);
@@ -1747,7 +1748,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   async getItem(key: string): Promise<CacheItemResult | null> {
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`fn:${key}`);
+      const request = this.keyToRequest(`fn:${key}`, "data");
       const matchStart = Date.now();
       const {
         response,
@@ -1932,7 +1933,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (this.skipUncacheableTagSet(options?.tags)) return;
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`fn:${key}`);
+      const request = this.keyToRequest(`fn:${key}`, "data");
 
       const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
@@ -1984,7 +1985,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // JSON.stringify(KVItemEnvelope); field names differ from L1 so we assemble
       // from the pre-escaped value/handles pieces rather than re-stringifying.
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = await this.toKVKey(`fn:${key}`);
+        const kvKey = await this.toKVKey(`fn:${key}`, "data");
         const expiresAt = staleAt + swrWindow * 1000;
         let envelopeJson = `{"v":${valueJson}`;
         if (handlesJson !== undefined) envelopeJson += `,"h":${handlesJson}`;
@@ -2154,7 +2155,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
     try {
       const cache = await this.getCache();
-      const request = this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`);
+      const request = this.shellRequest(key);
       const matchStartedAt = stats ? performance.now() : 0;
       const {
         response,
@@ -2297,14 +2298,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
-  /** The isolate marker memo's key for a tag: markers are per namespace and version. */
+  /**
+   * The isolate marker memo's key for a tag: markers are per namespace, and
+   * shared by every version (tagMarkerKey).
+   */
   private markerMemoKey(tag: string): string {
-    return `${this.namespace ?? ""}\u0000${this.version ?? ""}\u0000${tag}`;
+    return `${this.namespace ?? ""}\u0000${tag}`;
   }
 
-  /** The memo key: one per namespace, build version, base URL, and shell key. */
+  /** The memo key: one per namespace, document version, base URL, and shell key. */
   private shellMemoKey(key: string): string {
-    return `${this.namespace ?? ""}\u0000${this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`).url}`;
+    return `${this.namespace ?? ""}\u0000${this.shellRequest(key).url}`;
   }
 
   /**
@@ -2571,15 +2575,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const evict = async (): Promise<void> => {
       const cache = await this.getCache();
       await reportingAsync(
-        () => cache.delete(this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`)),
+        () => cache.delete(this.shellRequest(key)),
         "cache-delete",
         "[CFCacheStore] getShell: evict corrupt L1",
       );
       if (this.kv) {
-        await this.evictKvKey(
-          await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`),
-          "getShell",
-        );
+        await this.evictKvKey(await this.shellKVKey(key), "getShell");
       }
     };
     if (this.waitUntil) this.waitUntil(evict);
@@ -2641,9 +2642,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
       const writeKv = !!this.kv && retentionTtl > 0;
-      const kvKey = writeKv
-        ? await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`)
-        : null;
+      const kvKey = writeKv ? await this.shellKVKey(key) : null;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
@@ -2684,7 +2683,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             try {
               const cache = await this.getCache();
               await cache.put(
-                this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`),
+                this.shellRequest(key),
                 this.shellFrameResponse(frame, head),
               );
               this.debugShell(key, "l1-stored", { expiresAt: head.e });
@@ -2781,7 +2780,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // One kvReadTimeoutMs budget covers opening the value and reading its
       // head and prelude; the remainder after the open bounds the frame read.
       const deadline = Date.now() + this.kvReadTimeoutMs;
-      const kvKey = await this.toKVKey(`${SHELL_KEY_PREFIX}${key}`);
+      const kvKey = await this.shellKVKey(key);
       // A transient read REJECTION propagates to the catch below (reported
       // cache-read, the entry left intact); only a malformed frame on a body
       // that WAS read is corruption that evicts.
@@ -2884,7 +2883,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           if (Date.now() > head.e) return;
           const cache = await this.getCache();
           await cache.put(
-            this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`),
+            this.shellRequest(key),
             this.shellFrameResponse(
               encodeShellFrame(head, prelude, snapshotBytes),
               head,
@@ -2905,18 +2904,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // Key Helpers
   // ============================================================================
 
+  private shellRequest(key: string): Request {
+    return this.keyToRequest(`${SHELL_KEY_PREFIX}${key}`, "document");
+  }
+
+  private shellKVKey(key: string): Promise<string> {
+    return this.toKVKey(`${SHELL_KEY_PREFIX}${key}`, "document");
+  }
+
   /**
    * Convert string key to Request object for CF Cache API.
-   * Includes version in URL if specified (for cache invalidation on code changes).
+   *
+   * `family` picks the version in the URL path, so a version change misses:
+   * `"data"` for segment entries and `fn:` items (cached RSC data, valid while
+   * the router's server code is unchanged), `"document"` for `doc:` responses
+   * and `shell2:` shells (their bytes carry asset URLs and the handler
+   * version), `null` for tag markers, which apply to every version.
    * @internal
    */
-  private keyToRequest(key: string): Request {
+  private keyToRequest(key: string, family: KeyVersion): Request {
     const encodedKey = encodeURIComponent(key);
-    // Include version in URL path to invalidate cache when version changes
-    const versionPath = this.version ? `v/${this.version}/` : "";
-    return new Request(`${this.resolveBaseUrl()}${versionPath}${encodedKey}`, {
-      method: "GET",
-    });
+    return new Request(
+      `${this.resolveBaseUrl()}${versionKeyPrefix(this.explicitVersion, family)}${encodedKey}`,
+      { method: "GET" },
+    );
   }
 
   /**
@@ -2937,9 +2948,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * and delete paths agree on the stored key.
    * @internal
    */
-  private async toKVKey(key: string): Promise<string> {
-    const versionPath = this.version ? `v/${this.version}/` : "";
-    const composed = `${versionPath}${key}`;
+  private async toKVKey(key: string, family: KeyVersion): Promise<string> {
+    const composed = `${versionKeyPrefix(this.explicitVersion, family)}${key}`;
     if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
     const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
     return `${prefix}~${await kvKeyDigest(composed)}`;
@@ -2973,7 +2983,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * @internal
    */
   private toDocKVKey(key: string): Promise<string> {
-    return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
+    return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`, "document");
   }
 
   /**
@@ -3087,9 +3097,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // Tag Invalidation (single-store: markers live in this.kv)
   // ============================================================================
 
-  /** KV key for a tag's invalidation marker. */
+  /**
+   * KV key for a tag's invalidation marker. Unversioned: a content-hash
+   * version can come back (deploy A, deploy B, roll back to A), and a marker
+   * written while B was live has to be visible to A's entries. The staleness
+   * check compares the marker time with the entry's taggedAt and nothing else
+   * (isGloballyInvalidated), so one marker per tag serves every version.
+   */
   private tagMarkerKey(tag: string): Promise<string> {
-    return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`);
+    return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`, null);
   }
 
   /**
@@ -3320,9 +3336,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return false;
   }
 
-  /** Synthetic Cache API request for a tag's L1-cached invalidation marker. */
+  /**
+   * Synthetic Cache API request for a tag's L1-cached invalidation marker.
+   * Unversioned for the same reason as tagMarkerKey; the cache namespace
+   * (getCache) still scopes it.
+   */
   private tagMarkerRequest(tag: string): Request {
-    return this.keyToRequest(`${TAG_MARKER_CACHE_PREFIX}${tag}`);
+    return this.keyToRequest(`${TAG_MARKER_CACHE_PREFIX}${tag}`, null);
   }
 
   /**
@@ -3974,7 +3994,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = await this.toKVKey(key);
+      const kvKey = await this.toKVKey(key, "data");
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVSegmentEnvelope>(
           kvKey,
@@ -4076,7 +4096,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.waitUntil(() =>
       reportingAsync(
         async () =>
-          this.kv!.put(await this.toKVKey(key), envelopeJson, {
+          this.kv!.put(await this.toKVKey(key, "data"), envelopeJson, {
             expirationTtl: totalTtl,
           }),
         "cache-write",
@@ -4101,7 +4121,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             Math.floor((envelope.e - now) / 1000),
           );
           const cache = await this.getCache();
-          const request = this.keyToRequest(key);
+          const request = this.keyToRequest(key, "data");
 
           const response = new Response(JSON.stringify(envelope.d), {
             headers: {
@@ -4137,7 +4157,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = await this.toKVKey(`fn:${key}`);
+      const kvKey = await this.toKVKey(`fn:${key}`, "data");
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVItemEnvelope>(
           kvKey,
@@ -4221,7 +4241,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             Math.floor((envelope.e - now) / 1000),
           );
           const cache = await this.getCache();
-          const request = this.keyToRequest(`fn:${key}`);
+          const request = this.keyToRequest(`fn:${key}`, "data");
 
           const body = JSON.stringify({
             value: envelope.v,
@@ -4355,7 +4375,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             Math.floor((envelope.e - now) / 1000),
           );
           const cache = await this.getCache();
-          const request = this.keyToRequest(`doc:${key}`);
+          const request = this.keyToRequest(`doc:${key}`, "document");
 
           const headers = new Headers(envelope.hd);
           const originalCacheControl = headers.get("Cache-Control");

package/src/cache/cf/cf-cache-types.ts

@@ -320,11 +320,19 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
   tagCacheTtl?: number;
 
   /**
-   * Cache version string override. When this changes, all cached entries are
-   * effectively invalidated (new keys won't match old entries).
+   * Cache version string override. When set, this exact value prefixes every
+   * versioned key the store writes (`v/{version}/...`), for cached data and
+   * stored HTML alike; changing it makes every earlier entry unreachable.
    *
-   * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
+   * Leave it unset for the default: the store keys with the versions of the
+   * router serving the request. Segment entries and `"use cache"` items use
+   * the router's data version; document responses and PPR shells use its
+   * document version (see `createRouter({ version })`). Those are computed
+   * from the router's built code, so a deploy that does not change the router
+   * keeps its entries.
+   *
+   * Tag invalidation markers are never versioned: an invalidation applies to
+   * the entries of every version, including one that comes back in a rollback.
    */
   version?: string;
 

package/src/cache/handle-snapshot.ts

@@ -8,7 +8,7 @@
 
 import { replayLoaderPush } from "./handle-capture.js";
 import type { ResolvedSegment } from "../types.js";
-import type { HandleStore } from "../server/handle-store.js";
+import type { HandleStore, RecordAuthority } from "../server/handle-store.js";
 import type { HandleOwners, SegmentHandleData } from "./types.js";
 // segment-codec eagerly pulls @vitejs/plugin-rsc (a virtual: module unresolvable
 // in plain node/vitest). It is imported LAZILY inside the two async encode/decode
@@ -134,28 +134,13 @@ export function captureHandleOwners(
   return owners;
 }
 
-/** How restoreHandles delivers a record's loader-owned values. */
-export interface OwnedPushDelivery {
-  /**
-   * Asked once per owner delivered through pushReplayed
-   * (setupLoaderAccess _claimLoaderPushes); an owner it refuses is skipped.
-   */
-  claim?: (loaderId: string) => boolean;
-  /**
-   * A PPR shell's record (capture, document HIT tail, navigation replay): the
-   * loaders the route runs on the live lane (liveLaneLoaderIds), marked on
-   * the store (HandleStore.markLiveLane). A hole's values are replayed
-   * unclaimed, so its own cache() HIT redelivers its entry's pushes in their
-   * place (HandleStore.redeliverReplays), and its run ending without a push
-   * drops them (HandleStore.settleLoaderRun).
-   */
-  liveLane?: ReadonlySet<string>;
-  /**
-   * A document HIT tail: every owner outside `liveLane` goes through
-   * pushRestored and stands, unclaimed.
-   */
-  restore?: boolean;
-}
+/**
+ * What the record being restored is to each loader's handle pushes on this
+ * request (HandleStore RecordAuthority). Built by loaderPins (loader-cache.ts)
+ * over the pins resolveLoaderData serves a loader's value from, so a value
+ * and its record copies get one answer.
+ */
+export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
 
 /**
  * Restore handle data from a cached snapshot into the handle store.
@@ -163,24 +148,12 @@ export interface OwnedPushDelivery {
  * cache() record owns its segments' arrays, so it REPLACES them.
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
- * recorded order, an owned value through pushReplayed: if the owning loader
- * runs (a client navigation replaying a ppr route's cache() record runs its
- * `ssr: false` loaders), its live pushes replace the recorded ones in place
- * instead of appending a second copy. `owned.claim` is asked once per
- * owner, so the loader's own cache() HIT does not replay its pushes a second
- * time (loader-cache.ts replayLoaderHandles). A record without owners
- * restores as a plain replay.
- *
- * `owned.restore`: a document HIT tail restoring the shell's doc record
- * (withCacheLookup). A bake-lane owner's values are the prelude's, so they go
- * through pushRestored and stand: a run of that loader on the HIT (a
- * promise-carrying `ssr: false` loader, one whose record asks for a run)
- * reads the store, and its settled pushes are dropped, not swapped in.
- * Nothing is claimed, so the loader's own cache() HIT still replays the
- * pushes the record could not keep (the thenable ones pushRestored lets
- * through). A loader the route also runs on the live lane is a hole: its
- * values keep pushReplayed, unclaimed, and its live run replaces them
- * (#936), even inside a restored loader's body (`owned.liveLane`).
+ * recorded order. A loader-owned value stands (pushRestored) where `owned`
+ * says the record supplies that loader's value too ("pin", "copies"), and is
+ * a placeholder (pushPlaceholder) everywhere else: without `owned`, every
+ * owner. Neither claims its loader, so the loader's own cache() HIT still
+ * delivers (the thenable pushes a restored copy lets through, or its entry's
+ * pushes in a placeholder's place).
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,
@@ -188,8 +161,6 @@ export function restoreHandles(
   owners?: HandleOwners,
   owned?: OwnedPushDelivery,
 ): void {
-  let delivers: Map<string, boolean> | undefined;
-  if (owned?.liveLane) handleStore.markLiveLane(owned.liveLane);
   for (const [segId, segHandles] of Object.entries(handles)) {
     if (Object.keys(segHandles).length === 0) continue;
     const segOwners = owners?.[segId];
@@ -208,23 +179,11 @@ export function restoreHandles(
           handleStore.push(handleName, segId, values[i]);
           continue;
         }
-        const hole = owned?.liveLane?.has(owner) === true;
-        if (owned?.restore && !hole) {
+        const authority = owned?.(owner);
+        if (authority === "pin" || authority === "copies") {
           handleStore.pushRestored(handleName, segId, values[i], owner);
-          continue;
-        }
-        if (hole) {
-          handleStore.pushReplayed(handleName, segId, values[i], owner);
-          continue;
-        }
-        delivers ??= new Map();
-        let deliver = delivers.get(owner);
-        if (deliver === undefined) {
-          deliver = owned?.claim ? owned.claim(owner) : true;
-          delivers.set(owner, deliver);
-        }
-        if (deliver) {
-          handleStore.pushReplayed(handleName, segId, values[i], owner);
+        } else {
+          handleStore.pushPlaceholder(handleName, segId, values[i], owner);
         }
       }
     }
@@ -238,43 +197,66 @@ export function restoreHandles(
  * restoreHandles would wipe those. `segmentId` redirects every value to one
  * segment (the caller's).
  *
- * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
- * pushes, which reach the page once per request: `claim` (setupLoaderAccess
- * _claimLoaderPushes) skips a loader that already ran or was replayed in this
- * request, and a claimed loader that runs later replaces its replayed values
- * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
- * A key without ":" is a segment id (records written before owner keys) and
- * replays unchanged. A loader's own cache() replays through loader-cache.ts
- * replayLoaderHandles.
+ * The replay of every cached unit that records by owner: a "use cache"
+ * function (useCacheRecordKey) and a loader's own cache() (loader-cache.ts
+ * recordOwnerKey, with `unitLoader` the cached loader).
+ *
+ * A `${seq}:${loaderId}` group is that loader's pushes, which reach the page
+ * once per request: `claim` (setupLoaderAccess _claimLoaderPushes) is asked
+ * once per loader and skips one that already ran or was replayed in this
+ * request; a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). A group without an owner (`${seq}:`, or a key
+ * without ":" from a record written before owner keys, which is a segment
+ * id) is the unit's own: `unitLoader`'s, or no loader's for a function,
+ * whose pushes are plain.
+ *
+ * The claimed loaders' placeholders give way to this delivery
+ * (HandleStore.replacePlaceholders), `unitLoader`'s even when the entry
+ * recorded no push for it: the entry stands for that loader's run.
+ *
+ * No `claim` means the caller's pushes are diverted off the page (a stale
+ * refresh: cache-runtime.ts refreshView, setupLoaderAccess
+ * _runLoaderIsolated): every group is delivered, into the diverting capture,
+ * and the page's placeholders stay, or the page would lose the push.
  */
 export function appendHandles(
   handles: Record<string, SegmentHandleData>,
   handleStore: HandleStore,
-  segmentId?: string,
-  claim?: (loaderId: string) => boolean,
+  segmentId: string | undefined,
+  claim: ((loaderId: string) => boolean) | undefined,
+  unitLoader?: string,
 ): void {
-  let claims: Map<string, boolean> | undefined;
-  for (const [key, segHandles] of Object.entries(handles)) {
+  const ownerOf = (key: string): string | undefined => {
     const colon = key.indexOf(":");
-    const owner = colon < 0 ? "" : key.slice(colon + 1);
-    if (owner) {
-      claims ??= new Map();
-      let deliver = claims.get(owner);
-      if (deliver === undefined) {
-        deliver = claim ? claim(owner) : true;
-        claims.set(owner, deliver);
-      }
-      if (!deliver) continue;
+    return (colon < 0 ? "" : key.slice(colon + 1)) || unitLoader;
+  };
+  const claims = new Map<string, boolean>();
+  const ask = (owner: string | undefined): void => {
+    if (owner !== undefined && !claims.has(owner)) {
+      claims.set(owner, claim ? claim(owner) : true);
     }
-    const target = segmentId ?? key;
-    for (const [handleName, values] of Object.entries(segHandles)) {
-      for (const value of values) {
-        if (owner) {
-          replayLoaderPush(handleStore, handleName, target, value, owner);
-        } else {
-          handleStore.push(handleName, target, value);
+  };
+  ask(unitLoader);
+  for (const key in handles) ask(ownerOf(key));
+  const deliver = (): void => {
+    for (const [key, segHandles] of Object.entries(handles)) {
+      const owner = ownerOf(key);
+      if (owner !== undefined && !claims.get(owner)) continue;
+      const target = segmentId ?? key;
+      for (const [handleName, values] of Object.entries(segHandles)) {
+        for (const value of values) {
+          if (owner !== undefined) {
+            replayLoaderPush(handleStore, handleName, target, value, owner);
+          } else {
+            handleStore.push(handleName, target, value);
+          }
         }
       }
     }
+  };
+  const granted: string[] = [];
+  if (claim) {
+    for (const [owner, given] of claims) if (given) granted.push(owner);
   }
+  handleStore.replacePlaceholders(granted, deliver);
 }