@rangojs/router 0.20.0 → 0.22.0

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,53 +134,51 @@ 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;
+/**
+ * captureHandles and captureHandleOwners cut down to the handle arrays that
+ * hold an owned value, each whole (its unowned values too, in place), so
+ * restoreHandles rebuilds exactly those arrays over a store that already
+ * holds the rest. A prerender-served shell capture stores this: the
+ * prerender store restores the handler pushes on a HIT, and the loader
+ * pushes have no other record (shell-capture.ts captureAndStoreShell).
+ */
+export function captureOwnedHandles(handleStore: HandleStore): {
+  handles: HandleRecord;
+  owners?: HandleOwners;
+} {
+  const handles: HandleRecord = {};
+  let owners: HandleOwners | undefined;
+  for (const id of handleStore.getOwnedSegmentIds()) {
+    const segOwners = handleStore.getRecordOwners(id);
+    if (!segOwners) continue;
+    const kept = handleStore.getDataForSegment(id, true);
+    handles[id] = {};
+    for (const name in segOwners) handles[id][name] = kept[name] ?? [];
+    (owners ??= {})[id] = segOwners;
+  }
+  return { handles, owners };
 }
 
+/**
+ * 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.
  * Used when serving cached segments to replay their handle data: a route
  * 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 +186,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,29 +204,42 @@ 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);
         }
       }
     }
   }
 }
 
+/**
+ * Serve a doc record's handles: set its authority over the loaders' pushes
+ * (with or without a handles blob: a pinned loader whose capture pushed
+ * nothing has no copy, and its run must still add no settled push), then
+ * decode and restoreHandles. `keepIds` limits the restore to the segments a
+ * boundary-scoped scope serves. A decode failure skips the restore.
+ */
+export async function restoreRecordHandles(
+  handleStore: HandleStore,
+  record: { handles?: string; handleOwners?: HandleOwners },
+  owned: OwnedPushDelivery | undefined,
+  keepIds?: ReadonlySet<string>,
+): Promise<void> {
+  if (owned) handleStore.setRecordAuthority(owned);
+  if (!record.handles) return;
+  const decoded = await decodeHandles(record.handles);
+  if (!decoded) return;
+  if (keepIds) {
+    for (const id of Object.keys(decoded)) {
+      if (!keepIds.has(id)) delete decoded[id];
+    }
+  }
+  restoreHandles(decoded, handleStore, record.handleOwners, owned);
+}
+
 /**
  * Append recorded handle pushes to the store, in recorded order, via push()
  * so active captures and loader-scope tagging see them like live pushes. For
@@ -238,43 +247,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);
 }

package/src/cache/index.ts

@@ -1,5 +1,6 @@
 export type {
   SegmentCacheStore,
+  CacheStoreScope,
   CachedEntryData,
   CacheGetResult,
   CacheItemResult,
@@ -56,3 +57,7 @@ export {
 } from "./document-cache.js";
 
 export type { CacheErrorCategory } from "./cache-error.js";
+
+// For a custom persistent store: the versions the built-in stores key with.
+export { getCacheVersions } from "../server/build-version-table.js";
+export type { RouterVersions } from "../router-versions.js";

package/src/cache/invalidation-order.ts

@@ -43,6 +43,59 @@ export interface ExecutionStart {
   readonly at: number;
 }
 
+/**
+ * The `taggedAt` / `ta` stamp a store writes on a tagged data entry: the start
+ * of the execution that produced the value (`startedAt`), so a marker written
+ * while it ran rejects the entry on read (#1068). Write time when the writer
+ * knows no start. Never later than now: a start from a skewed clock must not
+ * stamp the future, which would make the entry look newer than every marker.
+ */
+export function entryStamp(startedAt: number | undefined): number {
+  const now = Date.now();
+  // 0 is "no start", not the epoch: no marker is older than it, so such an
+  // entry would never be rejected.
+  return typeof startedAt === "number" &&
+    Number.isFinite(startedAt) &&
+    startedAt > 0
+    ? Math.min(startedAt, now)
+    : now;
+}
+
+/** The stamp of a data entry: `entryStamp` for a tagged entry, none otherwise. */
+export function taggedStamp(
+  tags: readonly string[] | undefined,
+  startedAt: number | undefined,
+): number | undefined {
+  return Array.isArray(tags) && tags.length > 0
+    ? entryStamp(startedAt)
+    : undefined;
+}
+
+/**
+ * putResponse has no options object to carry the start and takes no new
+ * positional parameter, so the writer marks the Response it hands over.
+ * On globalThis like the order: a second evaluated copy of this module that
+ * wrote the mark must be read by the store's copy, else the stamp silently
+ * falls back to write time.
+ */
+const responseStarts: WeakMap<Response, number> = ((globalThis as any)[
+  Symbol.for("rangojs-router:response-execution-start")
+] ??= new WeakMap());
+
+/** Mark the execution start behind a Response handed to putResponse. */
+export function markResponseStart(
+  response: Response,
+  start: ExecutionStart,
+): Response {
+  responseStarts.set(response, start.at);
+  return response;
+}
+
+/** The start a writer marked on `response`, if any. */
+export function responseStartedAt(response: Response): number | undefined {
+  return responseStarts.get(response);
+}
+
 /** Record an execution's start, before it reads its data. */
 export function executionStart(): ExecutionStart {
   return { seq: order.seq, at: Date.now() };

package/src/cache/memory-segment-store.ts

@@ -6,6 +6,7 @@
  */
 
 import type {
+  CacheStoreScope,
   SegmentCacheStore,
   CachedEntryData,
   CacheDefaults,
@@ -23,6 +24,7 @@ import {
   DEFAULT_FUNCTION_TTL,
 } from "./cache-policy.js";
 import { reportCacheError } from "./cache-error.js";
+import { responseStartedAt } from "./invalidation-order.js";
 
 const CACHE_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
 const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
@@ -146,6 +148,26 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
    * ```
    */
   maxEntries?: number;
+
+  /**
+   * Where an entry this store writes can be read; what `router.prerender()`
+   * checks before warming a route. Defaults to `"local"`: the maps live in one
+   * process, and the router cannot tell one long-running server from several
+   * replicas or serverless instances, so a warm into it is refused in
+   * production. Set `"global"` only when exactly one process serves the app
+   * (a single Node server); a warm then reports `warmed`. Under the Vite dev
+   * server a `"local"` instance already counts as shared.
+   *
+   * Like `defaults` and `keyGenerator`, the scope is per instance: two
+   * instances with the same `name` share their maps but each declares its own
+   * scope. Keep them identical.
+   *
+   * @example
+   * ```typescript
+   * const store = new MemorySegmentCacheStore({ scope: "global" });
+   * ```
+   */
+  scope?: CacheStoreScope;
 }
 
 /** Default per-family entry cap for MemorySegmentCacheStore (FIFO eviction). */
@@ -188,6 +210,13 @@ const DEFAULT_MAX_ENTRIES = 1000;
 export class MemorySegmentCacheStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
+  /**
+   * SegmentCacheStore.scope: "local" unless `options.scope` says otherwise, so
+   * router.prerender() refuses to warm into these maps in production. Under
+   * the Vite dev server the gate counts a "local" instance as shared
+   * (store-scope.ts resolveWarmStoreScope).
+   */
+  readonly scope: CacheStoreScope;
   readonly supportsPassiveShellReads: true = true;
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
@@ -253,6 +282,7 @@ export class MemorySegmentCacheStore<
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
     this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.scope = options?.scope ?? "local";
   }
 
   /**
@@ -300,6 +330,7 @@ export class MemorySegmentCacheStore<
     ttl: number,
     _swr?: number,
   ): Promise<void> {
+    if (this.invalidatedAfter(data.tags, data.taggedAt)) return;
     const entry: CachedEntryData = {
       ...data,
       expiresAt: Date.now() + ttl * 1000,
@@ -358,6 +389,7 @@ export class MemorySegmentCacheStore<
     tags?: string[],
   ): Promise<void> {
     try {
+      const startedAt = responseStartedAt(response);
       const body = await response.clone().arrayBuffer();
       const headers: [string, string][] = [];
       response.headers.forEach((value, name) => {
@@ -368,6 +400,8 @@ export class MemorySegmentCacheStore<
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
 
+      // After the last await before the write.
+      if (this.invalidatedAfter(tags, startedAt)) return;
       const prefixedKey = `res:${key}`;
       this.unregisterTags(prefixedKey);
       this.evictIfNeeded(this.responseCache, key, "res");
@@ -415,6 +449,7 @@ export class MemorySegmentCacheStore<
     value: string,
     options?: CacheItemOptions,
   ): Promise<void> {
+    if (this.invalidatedAfter(options?.tags, options?.startedAt)) return;
     const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
@@ -486,7 +521,23 @@ export class MemorySegmentCacheStore<
     return this.tagsInvalidatedSince(tags, sinceMs);
   }
 
-  private tagsInvalidatedSince(tags: string[], sinceMs: number): boolean {
+  /**
+   * A tag invalidated in a millisecond after the write's execution started
+   * (#1068). Strictly after: the start's own millisecond is ambiguous, and
+   * invalidation-order.ts orders those exactly.
+   */
+  private invalidatedAfter(
+    tags: readonly string[] | undefined,
+    startedAt: number | undefined,
+  ): boolean {
+    if (!tags || tags.length === 0 || startedAt === undefined) return false;
+    return this.tagsInvalidatedSince(tags, startedAt + 1);
+  }
+
+  private tagsInvalidatedSince(
+    tags: readonly string[],
+    sinceMs: number,
+  ): boolean {
     for (const tag of tags) {
       const at = this.tagInvalidatedAt.get(tag);
       // >= so a same-millisecond invalidation wins (freshness over staleness),

package/src/cache/shell-snapshot.ts

@@ -18,7 +18,9 @@
  * the capture's copy of a value: it is dynamic or has its own cache. A
  * bake-lane loader body that runs on a HIT reads the store too; its pinned
  * container paths stay the pin's (overlayLoaderContainer), and its settled
- * pushes stay the record's (HandleStore.pushRestored).
+ * pushes stay the record's (HandleStore.pushRestored). The two go together:
+ * a loader whose pin the entry lost runs fresh, and the record's copies of
+ * its pushes give way to that run's (restoreHandles).
  */
 
 import type {
@@ -30,6 +32,7 @@ import type {
   ShellCacheEntry,
   ShellSnapshotRecord,
   ShellSnapshotLoaderValue,
+  ShellSnapshotHandlesValue,
   CacheReadError,
 } from "./types.js";
 import { settleGrowing } from "./background-task.js";
@@ -367,17 +370,40 @@ export interface ShellLoaderSeedEntry {
    * hole-free record: a hole-carrying one always runs.
    */
   runs: boolean;
+  /**
+   * The capture that wrote the pin recorded every settled push of the
+   * loader's run in the doc record (CachedEntryData.handleOwners): the pin
+   * carries the `runs` bit, which captures write since they record those
+   * pushes (v0.18). A replay then drops any other settled push of the loader
+   * (HandleStore RecordAuthority "pin"). False for an older pin, whose record
+   * may hold none and leaves them to the run.
+   */
+  complete: boolean;
 }
 
+/**
+ * A pin's loader. A pin is stored under its loader segment id,
+ * `${shortCode}D${index}.${loaderId}` (fresh.ts resolveLoaders), and a
+ * shortCode holds no "D" and no "." (server/context.ts getShortCode: M, L, P,
+ * R, C, I and digits), so the first `D<index>.` ends it. A loader id can hold
+ * both.
+ */
+const PIN_KEY_PREFIX = /^[^D.]*D\d+\./;
+
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane
- * container into a segment-key -> container Map, which serveShellHit assigns
- * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * container into a loader-id -> pin Map, which serveShellHit assigns to the
+ * tail context's `_shellLoaderSeed` (loader-cache.ts servedPins).
  * Lives here so every snapshot family is decoded in this module (the segment
  * family via {@link SeededShellStore}); the loader family is not a store
  * read, so it seeds the context instead of a store.
  *
+ * Keyed by loader, not by the segment a pin was stored under: a loader runs
+ * once per capture, so every segment that registers it pinned the same
+ * container, and the loader's value and its handle pushes are both looked up
+ * by loader. A key that does not parse pins nothing.
+ *
  * Deserializations run in parallel; a record that fails to decode is skipped
  * (that loader drifts — the pre-snapshot behavior — instead of failing the
  * HIT). Returns undefined when the snapshot carries no loader records, without
@@ -396,10 +422,14 @@ export async function buildShellLoaderSeed(
   const entries = await Promise.all(
     loaderRecords.map(
       async (rec): Promise<[string, ShellLoaderSeedEntry] | null> => {
+        const prefix = PIN_KEY_PREFIX.exec(rec.key);
+        if (!prefix) return null;
         try {
-          const stored = rec.value as ShellSnapshotLoaderValue;
+          // Typed as always carrying the bits; an older record lacks them.
+          const stored = rec.value as Partial<ShellSnapshotLoaderValue> &
+            Pick<ShellSnapshotLoaderValue, "value">;
           return [
-            rec.key,
+            rec.key.slice(prefix[0].length),
             {
               container: await deserializeResult(stored.value),
               // A record stored before the bits existed (v0.17) lacks the
@@ -407,6 +437,7 @@ export async function buildShellLoaderSeed(
               // so the loader body supplies them.
               holes: stored.holes !== 0,
               runs: stored.runs !== 0,
+              complete: stored.runs !== undefined,
             },
           ];
         } catch {
@@ -422,6 +453,22 @@ export async function buildShellLoaderSeed(
   return seed.size > 0 ? seed : undefined;
 }
 
+/** The key of a snapshot's one `handles` record (ShellSnapshotHandlesValue). */
+export const SHELL_HANDLES_RECORD_KEY = "handles";
+
+/**
+ * The `handles` record of a prerender-served entry, which a HIT tail restores
+ * after the prerender store's handles (cache-lookup.ts yieldFromStore), or
+ * undefined: an entry with a doc record, or one written before the record
+ * existed (v0.21), which serves as it did.
+ */
+export function shellPrerenderHandles(
+  snapshot: readonly ShellSnapshotRecord[],
+): ShellSnapshotHandlesValue | undefined {
+  const record = snapshot.find((r) => r?.family === "handles");
+  return record?.value as ShellSnapshotHandlesValue | undefined;
+}
+
 /**
  * The implicit doc scope's store on a HIT tail and on a partial replay: it
  * serves the snapshot's segment records, the doc record among them, and

package/src/cache/store-scope.ts

@@ -0,0 +1,36 @@
+/**
+ * The store scope `router.prerender()` gates a warm on
+ * (prerender/create-prerender-trigger.ts). See
+ * docs/design/prerender-every-route.md, "The store declaration".
+ */
+
+import type { CacheStoreScope, SegmentCacheStore } from "./types.js";
+import { MemorySegmentCacheStore } from "./memory-segment-store.js";
+
+/**
+ * True under the Vite dev server: only its routes-manifest virtual module sets
+ * the dev origin (vite/discovery/virtual-module-codegen.ts). A build, a preview
+ * server and a test runner answer false.
+ */
+export function isViteDevServer(): boolean {
+  return typeof globalThis.__PRERENDER_DEV_URL === "string";
+}
+
+/**
+ * The scope a warm treats `store` as having: its own declaration, with none
+ * or an unknown value being `"local"`.
+ *
+ * One exception: under the Vite dev server a MemorySegmentCacheStore answers
+ * `"global"`, because that one process serves every request. Production reads
+ * the class's own `scope` (`"local"`): changing that declaration is what
+ * would admit it there.
+ */
+export function resolveWarmStoreScope(
+  store: SegmentCacheStore<any>,
+  devServer: boolean = isViteDevServer(),
+): CacheStoreScope {
+  const declared = store.scope;
+  if (declared === "global" || declared === "regional") return declared;
+  if (devServer && store instanceof MemorySegmentCacheStore) return "global";
+  return "local";
+}

package/src/cache/tag-invalidation.ts

@@ -49,6 +49,7 @@ import {
 export {
   executionStart,
   invalidatedSince,
+  markResponseStart,
   type ExecutionStart,
 } from "./invalidation-order.js";
 
@@ -147,11 +148,12 @@ function markFreshReads(stores: SegmentCacheStore[]): void {
  * The write gate of every cache execution (#977): whether one of `tags` was
  * invalidated after the execution that produced the value started.
  *
- * Every built-in store stamps an entry when it is written (CFCacheStore's
- * `taggedAt`, VercelCacheStore's `ta`) or checks nothing on write
- * (MemorySegmentCacheStore), so a value read before an invalidation and
- * written after it would be served as newer than the invalidation until it
- * expires. Two answers, either one skips the write:
+ * A store stamps an entry with the execution's start (CFCacheStore's
+ * `taggedAt`, VercelCacheStore's `ta`, #1068), but only CFCacheStore with KV
+ * markers rejects it on a later request's read, and MemorySegmentCacheStore
+ * refuses the write. The gate saves the write everywhere and is the only
+ * guard where a read compares nothing. Two answers, either one skips the
+ * write:
  *
  * - this isolate's order (invalidatedSince), which sees every request's
  *   updateTag()/revalidateTag() here, the calling one included;