@rangojs/router 0.18.0 → 0.19.0

package/src/cache/tag-invalidation.ts

@@ -30,22 +30,27 @@
  * Invariant: the mask only turns the invalidating request's hits into misses.
  * If the durable write then fails, that request paid extra misses, never a
  * stale read, and other requests read the durable state. Both also record
- * the tags on the request (markInvalidated), so a "use cache" execution or
- * stale refresh this request started before one of its own tags was
- * invalidated is neither joined nor written (cache-runtime.ts). Its own tags
- * only: a nested "use cache" function's tags do not reach the enclosing
- * entry (#980), for this gate as for eviction. Not covered (#977): such an
- * execution in another request, or a loader cache() write, still lands, and
- * the store accepts it (docs/design/caching.md "Read-your-own-writes").
+ * the tags in the isolate's invalidation order (markInvalidated), so a cache
+ * execution that started before one of its tags was invalidated, in any
+ * request, is neither joined nor written (#973, #977): see
+ * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
 
-import {
-  _getRequestContext,
-  type RequestContext,
-} from "../server/request-context.js";
+import { _getRequestContext } from "../server/request-context.js";
 import { reportingAsync } from "./cache-error.js";
 import { normalizeTags } from "./cache-tag.js";
 import type { SegmentCacheStore } from "./types.js";
+import {
+  invalidatedSince,
+  markInvalidated,
+  type ExecutionStart,
+} from "./invalidation-order.js";
+
+export {
+  executionStart,
+  invalidatedSince,
+  type ExecutionStart,
+} from "./invalidation-order.js";
 
 /**
  * Collect every store that may hold entries tagged for this request's handler:
@@ -139,48 +144,49 @@ function markFreshReads(stores: SegmentCacheStore[]): void {
 }
 
 /**
- * The isolate's order of tag invalidations and "use cache" execution starts
- * (#973). A counter, not Date.now(): Workers advance the clock only on I/O,
- * so an execution started right after an invalidation would share its
- * millisecond and read as older.
- */
-let cacheSeq = 0;
-
-/** The current position in that order; an execution records it at start. */
-export function currentCacheSeq(): number {
-  return cacheSeq;
-}
-
-/**
- * Whether the request invalidated any of `tags` after `since` (a
- * currentCacheSeq() value an execution recorded when it started): its value
- * may predate the invalidation, so the request neither joins nor writes it.
+ * 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:
+ *
+ * - this isolate's order (invalidatedSince), which sees every request's
+ *   updateTag()/revalidateTag() here, the calling one included;
+ * - the store's markers (isTagsInvalidatedSince), for another isolate's
+ *   invalidation, as far as the store can tell: KV markers on CFCacheStore
+ *   (KV-less, only this request's own), `tm` markers on VercelCacheStore,
+ *   the process markers on MemorySegmentCacheStore. Asked about the
+ *   milliseconds after the start's: this isolate's own invalidation that
+ *   preceded the start usually shares its millisecond (Workers freeze
+ *   Date.now() between I/O), and `>=` would skip every write started right
+ *   after it. Another isolate's invalidation in the start's own millisecond
+ *   is not caught. Asked fail-closed: a marker the store cannot read
+ *   counts as an invalidation.
+ *
+ * The order is read again once the store answers: its read can be in flight
+ * while this isolate invalidates (an action awaits a "use cache" miss, whose
+ * write waits on the read, then runs updateTag()), and it then answers with
+ * the markers from before. markInvalidated is synchronous, so this second
+ * look sees every invalidation made before the answer.
+ *
+ * Invariant: a skipped write only costs a later miss, never a stale read.
+ * The caller still returns the value it computed.
  */
-export function invalidatedSince(
-  ctx: RequestContext<any, any> | undefined,
+export async function predatesInvalidation(
+  store: SegmentCacheStore,
   tags: readonly string[] | undefined,
-  since: number,
-): boolean {
-  const record = (ctx?._requestRoot ?? ctx)?._tagInvalidations;
-  if (!record || !tags) return false;
-  for (const tag of tags) {
-    const at = record.get(tag);
-    if (at !== undefined && at > since) return true;
-  }
-  return false;
-}
-
-/**
- * Record the invalidation on the request (RequestContext._tagInvalidations,
- * on the root so derived contexts share it), before any store sees it.
- */
-function markInvalidated(tags: readonly string[]): void {
-  const ctx = _getRequestContext();
-  if (!ctx) return;
-  const root = ctx._requestRoot ?? ctx;
-  const at = ++cacheSeq;
-  const record = (root._tagInvalidations ??= new Map());
-  for (const tag of tags) record.set(tag, at);
+  start: ExecutionStart,
+): Promise<boolean> {
+  if (!tags || tags.length === 0) return false;
+  if (invalidatedSince(tags, start.seq)) return true;
+  if (!store.isTagsInvalidatedSince) return false;
+  const marked = await store.isTagsInvalidatedSince([...tags], start.at + 1, {
+    failClosed: true,
+  });
+  return marked || invalidatedSince(tags, start.seq);
 }
 
 async function invalidateAcross(

package/src/cache/types.ts

@@ -75,6 +75,12 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * 2. Store-level `keyGenerator` (modifies default key)
    * 3. Default key generation (prefix:pathname:params)
    *
+   * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
+   * string is not a key: where the result partitions a nested cache() on
+   * another store, or a ppr shell, it fails key resolution, so the request
+   * renders uncached (as when the keyGenerator throws), and the router warns
+   * once naming the store.
+   *
    * @example Using headers for cache segmentation
    * ```typescript
    * keyGenerator: (ctx, defaultKey) => {
@@ -327,12 +333,27 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * freshness). Consulted by build-shell read-through and runtime shell stores:
    * "was it evicted" is answered by tag markers against the entry's createdAt,
    * including when invalidation races a capture that has not been written yet.
+   * Also the store's half of every cache write's gate (#977,
+   * tag-invalidation.ts predatesInvalidation): a "use cache", loader cache(),
+   * route cache() or document-cache write whose execution started before an
+   * invalidation another isolate made is skipped when this answers true, so
+   * it must reflect invalidations made after this request started reading
+   * (not a value memoized earlier in the request).
    * Optional: without it, TAGGED build entries are not served (untagged ones
-   * are unaffected — they are evictable only by deploy/buildVersion anyway).
+   * are unaffected — they are evictable only by deploy/buildVersion anyway),
+   * and writes are gated by this isolate's invalidations only.
    * Fail open to `false` on marker-read errors: a transient store fault must
    * degrade to "still valid", the same posture as the envelope tag checks.
-   */
-  isTagsInvalidatedSince?(tags: string[], sinceMs: number): Promise<boolean>;
+   * The write gate passes `{ failClosed: true }` instead: a marker it cannot
+   * read (an error, a timed-out read) answers `true`, since a skipped write
+   * only costs a later miss. A store that ignores the option still works;
+   * its fault then lets that write through.
+   */
+  isTagsInvalidatedSince?(
+    tags: string[],
+    sinceMs: number,
+    options?: { failClosed?: boolean },
+  ): Promise<boolean>;
 }
 
 /**
@@ -399,11 +420,10 @@ export interface ShellCacheEntry {
    * on dev RSC-module edits). The second read-time gate: a persistent shared
    * store (KV/runtime-cache) survives deploys, and an app-code change that
    * keeps the same React version would otherwise leave a stale-build
-   * prelude+postponed live under the same key. Optional only for entries
-   * stored before the field existed — those are treated as a miss and the
-   * recapture re-stamps them (pre-release, no compat shim).
+   * prelude+postponed live under the same key. A custom store returns it as
+   * putShell received it.
    */
-  buildVersion?: string;
+  buildVersion: string;
   /**
    * The initialTheme the CAPTURE render was built with: the no-cookie default
    * (payloadInitialTheme, rsc/full-payload.ts), never the capturing visitor's
@@ -418,22 +438,20 @@ export interface ShellCacheEntry {
    */
   initialTheme?: string;
   /**
-   * The CAPTURE DATA SNAPSHOT: every cache-store read-hit and write the capture
-   * render performed, in stored/serialized form. Replaying these on a HIT (via
-   * the SeededShellStore overlay, for the tail render only) reproduces the
-   * shell's cached content byte-identically, so the freshly rendered hydration
-   * payload matches the frozen prelude even after the underlying cache entries
-   * have drifted (expired, been recomputed, or been tag-invalidated).
-   *
-   * Optional: an entry captured before this field existed simply has no
-   * snapshot and keeps the pre-snapshot behavior (the tail reads live, so any
-   * shell-baked cached value that drifted mismatches the prelude). Recapture
-   * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
+   * The CAPTURE DATA SNAPSHOT, in stored/serialized form: the doc segment
+   * record every HIT replays the handler layer from (`docKey`) and the
+   * bake-lane loader pins (pruned to what a HIT reads, issue #941). Replaying
+   * them on a HIT keeps the freshly rendered hydration payload equal to the
+   * frozen prelude after the underlying cache entries have drifted; every
+   * other read on a HIT, a hole's included, reads the store. Empty when the capture
+   * recorded nothing (a prerender-served capture without bake-lane loaders,
+   * a tombstone). A custom store returns it as putShell received it. See
+   * docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
-  snapshot?: ShellSnapshotRecord[];
+  snapshot: ShellSnapshotRecord[];
   /**
    * Records the capture dropped from `snapshot` because no reader of this
-   * entry consumes them, by family (`item:4/response:1`). Diagnostic only: the
+   * entry consumes them, by family (`loader:1`). Diagnostic only: the
    * HIT tail timing reports it next to the kept records. See
    * docs/design/shell-entry-layout.md ("Record only what a HIT reads").
    */
@@ -459,6 +477,13 @@ export interface ShellCacheEntry {
   createdAt: number;
 }
 
+/**
+ * @internal A shell entry without its prelude and snapshot: what a
+ * prelude-first read (SegmentCacheStore.readShellDocument) resolves with
+ * before the snapshot bytes arrive.
+ */
+export type ShellEntryHead = Omit<ShellCacheEntry, "prelude" | "snapshot">;
+
 /**
  * A shell entry whose document half is present — what the document HIT path
  * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
@@ -493,7 +518,7 @@ export type ShellSnapshotFailure = "unavailable" | "corrupt";
  */
 export interface ShellDocumentRead {
   /** The entry without its prelude and snapshot (delivered separately). */
-  entry: ShellCacheEntry;
+  entry: ShellEntryHead;
   /** Raw prelude bytes (empty for a navigationOnly entry). */
   prelude: Uint8Array;
   shouldRevalidate?: boolean;
@@ -580,14 +605,13 @@ export interface ShellReadStats {
 }
 
 /**
- * The families a shell snapshot pins. The item/segment/response families are
- * cache-store reads/writes (recorded by RecordingShellStore); the loader family
- * pins the settled CONTAINER of a bake-lane loader (lane rule: see
- * resolveLoaderData, loader-cache.ts). Excludes the shell family itself
- * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
- * it would be self-referential.
+ * The families a shell snapshot pins: the doc segment record (recorded by
+ * RecordingShellStore) and the settled CONTAINER of each bake-lane loader
+ * (lane rule: see resolveLoaderData, loader-cache.ts). No cache read is
+ * pinned: a HIT's holes, and a bake-lane loader body that runs on the HIT,
+ * read the store.
  */
-export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
+export type ShellSnapshotFamily = "segment" | "loader";
 
 /**
  * The stored form of a loader-family snapshot value: the bake-lane loader's
@@ -604,57 +628,35 @@ export interface ShellSnapshotLoaderValue {
    * container carries hole markers, so a HIT must gate the overlay on the
    * fresh run (only the loader body can mint the live nested promises);
    * 0 = fully pinned, so a HIT resolves the payload promise immediately from
-   * the pin and does not run the loader body (unless `runs`). Absent on
-   * pre-bit snapshots, which keep the gated path.
+   * the pin and does not run the loader body (unless `runs`).
    */
-  holes?: 0 | 1;
+  holes: 0 | 1;
   /**
    * 1 when the capture saw a loader push it could not record (a deferred
    * push, one with masked nested promises, or one made outside any loader
    * body): a HIT then still runs the loader body in the background
    * (pin-first) so those pushes reach the page. 0: a hole-free record is
-   * served from the pin alone and its body does not run on a HIT. Absent (a
-   * snapshot written before the bit, which lacks the loader-owned pushes)
-   * reads as 1, so the body supplies them.
+   * served from the pin alone and its body does not run on a HIT.
+   *
+   * Both bits are always written. A record stored before they existed (v0.17)
+   * reads each missing bit as 1 (buildShellLoaderSeed): its snapshot lacks
+   * the loader-owned pushes, so the body supplies them.
    */
-  runs?: 0 | 1;
-}
-
-/** A serialized cached Response for the response family of a shell snapshot. */
-export interface ShellSnapshotResponseValue {
-  status: number;
-  /** Client-facing header pairs (per-client signal headers excluded at record). */
-  headers: [string, string][];
-  /** base64-encoded response body (binary-safe, JSON-serializable). */
-  body: string;
-}
-
-/** The stored form of an item-family (use cache / loader cache) snapshot value. */
-export interface ShellSnapshotItemValue {
-  /** RSC-serialized return value. */
-  value: string;
-  /** RSC-encoded handle data, if any. */
-  handles?: string;
-  /** The entry's cache tags. */
-  tags?: string[];
+  runs: 0 | 1;
 }
 
 /**
- * One recorded cache-store read-hit or write from the capture render. `value`
- * carries the entry in its stored/serialized shape so it round-trips through a
- * JSON-serializing store (KV, CF, Vercel) with the rest of the ShellCacheEntry:
- * - `item`    -> {@link ShellSnapshotItemValue}
+ * One snapshot record: the doc segment record or a bake-lane loader pin.
+ * `value` carries it in its stored/serialized shape so it round-trips
+ * through a JSON-serializing store (KV, CF, Vercel) with the rest of the
+ * ShellCacheEntry:
  * - `segment` -> {@link CachedEntryData} (already JSON-able)
- * - `response`-> {@link ShellSnapshotResponseValue}
+ * - `loader`  -> {@link ShellSnapshotLoaderValue}
  */
 export interface ShellSnapshotRecord {
   family: ShellSnapshotFamily;
   key: string;
-  value:
-    | ShellSnapshotItemValue
-    | CachedEntryData
-    | ShellSnapshotResponseValue
-    | ShellSnapshotLoaderValue;
+  value: CachedEntryData | ShellSnapshotLoaderValue;
 }
 
 /**
@@ -759,8 +761,10 @@ export type SegmentHandleData = Record<string, unknown[]>;
  * index (null: not owned). Only a PPR shell capture writes owners: the
  * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
  * the loaders it awaits, and its own cache() replays), which the record keeps
- * because the prelude rendered them. restoreHandles replays an owned value
- * through HandleStore.pushReplayed, so a loader that does run on the HIT
- * replaces it with its live push.
+ * because the prelude rendered them. A document HIT restores a bake-lane
+ * owner's value through HandleStore.pushRestored, and it stands against a run
+ * of its loader there; a live-lane owner's (a hole), and every owner's on
+ * any other replay of the record (a client navigation), go through
+ * pushReplayed, so a run of the loader replaces it with its live push.
  */
 export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

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

@@ -6,8 +6,9 @@
  * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
  * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
  * L1/L2 tiering or per-tier timeout budgets are needed here - the platform does
- * that work. Tag markers exist only for the shell family (`tm`, see
- * isTagsInvalidatedSince), and only PPR shell reads memoize them. What this
+ * that work. Tag markers (`tm`, see isTagsInvalidatedSince) gate shell reads
+ * and writes and every cache write that started before an invalidation
+ * (#977); only PPR shell reads memoize them. What this
  * store adds on top of the raw primitive is the parts Vercel does NOT give us:
  *
  *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
@@ -76,9 +77,10 @@ import {
   base64ToBytes,
 } from "../cf/cf-base64.js";
 import {
-  perRequestStoreValue,
-  type PerRequestStoreMap,
-} from "../cf/cf-tag-marker-memo.js";
+  gateMarkerRead,
+  maskRequestTags,
+  maskedForRequest,
+} from "../request-tag-mask.js";
 import {
   ShellMemo,
   freshReadsWindowMs,
@@ -170,8 +172,9 @@ type CacheFamily = "s" | "i" | "r" | "h" | "tm";
 
 /**
  * TTL for tag-invalidation marker entries ("tm" family), written by
- * invalidateTags for the build-shell read-through's isTagsInvalidatedSince
- * gate. The platform's expireTag() DELETES tagged entries (no queryable
+ * invalidateTags for isTagsInvalidatedSince (the build-shell read-through,
+ * the shell write gate, and the write gate of cache executions, #977).
+ * The platform's expireTag() DELETES tagged entries (no queryable
  * history), so the markers are rango's own record of "tag X was invalidated
  * at T". One year: runtime tagged-shell retention is capped to this lifetime,
  * while buildVersion retires build shells on the next deploy. An expired marker
@@ -237,7 +240,7 @@ interface VercelShellEnvelope {
   /** React.version at capture. */
   rv: string;
   /** Build version at capture (ShellCacheEntry.buildVersion). */
-  bv?: string;
+  bv: string;
   /** Capture-generation start time, used by tag marker checks. */
   c: number;
   /** staleAt (ms since epoch). */
@@ -248,8 +251,8 @@ interface VercelShellEnvelope {
   t?: string[];
   /** initialTheme the capture render was built with (resume theme fidelity). */
   i?: string;
-  /** Capture data snapshot: recorded cache-store hits/writes for HIT parity. */
-  sn?: ShellSnapshotRecord[];
+  /** Capture data snapshot (ShellCacheEntry.snapshot). */
+  sn: ShellSnapshotRecord[];
   /**
    * ShellCacheEntry.docKey. Must round-trip: navigation-replay eligibility
    * requires the exact canonical doc segment record named here — dropping the
@@ -417,18 +420,6 @@ function handleMemos(cache: VercelRuntimeCache): VercelHandleMemos {
   return memos;
 }
 
-/**
- * The tags a request invalidated through a store, with their invalidatedAt:
- * request root context (RequestContext._requestRoot, so contexts derived
- * from the request share it) -> store -> tag -> ms (#973). invalidateTags()
- * writes it before its first await, and every read in that request treats an entry
- * carrying one of the tags, written at or before that time, as invalidated.
- * The platform's expireTag() and the tm marker writes are what other
- * requests see, and revalidateTag() does not wait for them.
- */
-const requestInvalidations: PerRequestStoreMap<Map<string, number>> =
-  new WeakMap();
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
@@ -1217,8 +1208,10 @@ export class VercelCacheStore<
    * fresh values are used as is, stale ones are used and refreshed in the
    * background, older ones block on the runtime-cache read. A request
    * carrying the fresh-reads cookie skips the memo. A failed read rejects and
-   * is never memoized. The shell write gate and build shells
-   * (isTagsInvalidatedSince) read the runtime cache every time.
+   * is never memoized. The shell write gate, build shells and the data
+   * write gates (isTagsInvalidatedSince) read the runtime cache each time
+   * they ask; gates of a request asking while a read is in flight share it
+   * (gateMarkerRead), and nothing is kept once it settles.
    */
   private async readTagMarker(
     tag: string,
@@ -1314,16 +1307,38 @@ export class VercelCacheStore<
   // --- Tags ---
 
   /**
-   * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
-   * expireTag() keeps no queryable history, so invalidateTags() writes "tm"
-   * markers for runtime capture races and immutable build shells. Marker >=
-   * generation start wins; read errors fail open like the CF marker check.
+   * SegmentCacheStore.isTagsInvalidatedSince. expireTag() keeps no queryable
+   * history, so invalidateTags() writes "tm" markers for runtime capture
+   * races, immutable build shells and data writes that started before an
+   * invalidation (#977, tag-invalidation.ts predatesInvalidation). Marker >=
+   * generation start wins. Read errors fail open like the CF marker check,
+   * except for the write gate (`failClosed`), which counts them as an
+   * invalidation. Each tag's marker is read through gateMarkerRead
+   * (request-tag-mask.ts): gates asking while a read is in flight share it.
    */
   async isTagsInvalidatedSince(
     tags: string[],
     sinceMs: number,
+    options?: { failClosed?: boolean },
   ): Promise<boolean> {
-    return this.tagsInvalidatedSince(tags, sinceMs, false);
+    if (this.maskedForRequest(tags, sinceMs)) return true;
+    const ctx = _getRequestContext();
+    const reads = new Map(
+      tags.map((tag) => [
+        tag,
+        gateMarkerRead(ctx, this, tag, sinceMs, () =>
+          this.readTagMarker(tag, false),
+        ),
+      ]),
+    );
+    return this.tagsInvalidatedSince(
+      tags,
+      sinceMs,
+      false,
+      reads,
+      undefined,
+      options?.failClosed === true,
+    );
   }
 
   private async tagsInvalidatedSince(
@@ -1332,6 +1347,8 @@ export class VercelCacheStore<
     isolateMemo: boolean,
     prefetched?: Map<string, Promise<number | null>>,
     outcomes?: Map<string, MarkerMemoOutcome>,
+    /** What a failed marker read answers: true for the write gate (#977). */
+    failClosed = false,
   ): Promise<boolean> {
     if (this.maskedForRequest(tags, sinceMs)) return true;
     try {
@@ -1342,6 +1359,9 @@ export class VercelCacheStore<
             this.readTagMarker(tag, isolateMemo, outcomes),
         ),
       );
+      // A read in flight when this request invalidated one of the tags
+      // resolved to the marker before it.
+      if (this.maskedForRequest(tags, sinceMs)) return true;
       for (const at of markers) {
         if (at !== null && at >= sinceMs) return true;
       }
@@ -1352,7 +1372,7 @@ export class VercelCacheStore<
         "cache-read",
         "[VercelCacheStore] tag invalidation check",
       );
-      return false;
+      return failClosed;
     }
   }
 
@@ -1408,42 +1428,24 @@ export class VercelCacheStore<
 
   /**
    * The request-local half of invalidateTags(), run before its first await
-   * (#973): see requestInvalidations. revalidateTag() waits for nothing
-   * after it.
+   * (#973): the request masks the tags (request-tag-mask.ts). The platform's
+   * expireTag() and the tm marker writes are what other requests see, and
+   * revalidateTag() does not wait for them.
    */
   private maskTagsForRequest(tags: string[], at: number): void {
     const ctx = _getRequestContext();
-    if (!ctx) return;
-    const mask = perRequestStoreValue(
-      requestInvalidations,
-      ctx._requestRoot ?? ctx,
-      this,
-      () => new Map<string, number>(),
-    );
-    for (const tag of tags) mask.set(tag, at);
+    if (ctx) maskRequestTags(ctx, this, tags, at);
   }
 
   /**
-   * Whether this request invalidated one of `tags` through this store at or
-   * after `taggedAt`. `>=`, as the marker check: an entry written in the
-   * invalidation's millisecond may hold a value computed before it, so it
-   * misses (a false miss, never a stale read). An entry without a stamp was
-   * written before the stamp existed and counts as older.
+   * Whether this request masked one of `tags` through this store at or after
+   * `taggedAt`. An entry without a stamp counts as older than any mask.
    */
   private maskedForRequest(
     tags: string[] | undefined,
     taggedAt: number | undefined,
   ): boolean {
-    if (!tags?.length) return false;
-    const ctx = _getRequestContext();
-    const mask =
-      ctx && requestInvalidations.get(ctx._requestRoot ?? ctx)?.get(this);
-    if (!mask) return false;
-    for (const tag of tags) {
-      const at = mask.get(tag);
-      if (at !== undefined && at >= (taggedAt ?? 0)) return true;
-    }
-    return false;
+    return maskedForRequest(_getRequestContext(), this, tags, taggedAt ?? 0);
   }
 
   /** A data read's mask check: reports the miss and returns true when masked. */
@@ -1700,7 +1702,7 @@ export class VercelCacheStore<
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
     const { p, po, rv, bv, c, s, e, t, i, sn, dk, pr, no } = raw;
-    if (typeof rv !== "string") return null;
+    if (typeof rv !== "string" || typeof bv !== "string") return null;
     // Document half: required unless navigationOnly (`no`), which stores
     // neither field. Tolerate a legacy navigationOnly envelope that still
     // carries them.
@@ -1716,13 +1718,14 @@ export class VercelCacheStore<
       ...(typeof p === "string" ? { p } : {}),
       ...(po !== undefined ? { po: po as string | null } : {}),
       rv,
-      bv: typeof bv === "string" ? bv : undefined,
+      bv,
       c,
       s,
       e,
       t: Array.isArray(t) ? (t as string[]) : undefined,
       i: typeof i === "string" ? i : undefined,
-      sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
+      // A non-array field reads as no records.
+      sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : [],
       dk: typeof dk === "string" ? dk : undefined,
       pr: typeof pr === "string" ? pr : undefined,
       no: no === true ? true : undefined,

package/src/client-urls/client-root.tsx

@@ -125,8 +125,9 @@ export function ClientUrlsRoot({
   const mount = useMount();
   const [intent, setIntent] = useState<ClientUrlNavigationIntent | null>(null);
   useEffect(
-    () => registerClientUrlGroup(definition, mount, namePrefix, setIntent),
-    [definition, mount, namePrefix],
+    () =>
+      registerClientUrlGroup(definition, mount, namePrefix, setIntent, routeId),
+    [definition, mount, namePrefix, routeId],
   );
 
   // Optimistic destination (design: docs/design/client-urls-optimistic-destination.md).
@@ -136,9 +137,12 @@ export function ClientUrlsRoot({
   // own keeps the previous content visible (React's transition hold — the
   // pre-existing contract for routes without loading()), one with loading()
   // or inline <Suspense> at its reads presents immediately. Same-route intents
-  // never swap: held data + transition() own that case.
+  // never swap: held data + transition() own that case. A navigation its
+  // transition({ when }) gated off at the swap presents urgently: no hold,
+  // no view transition, the destination's loading() streams.
   const pending = intent !== null;
-  const presented = useDeferredValue(intent);
+  const deferred = useDeferredValue(intent);
+  const presented = intent?.transitionGatedOff ? intent : deferred;
   const optimisticRoute =
     presented && presented.routeId !== routeId
       ? findRoute(definition, presented.routeId)

package/src/client-urls/client-urls.ts

@@ -29,6 +29,7 @@ const TRANSITION_CONFIG_KEYS = new Set<PropertyKey>([
   "default",
   "name",
   "viewTransition",
+  "when",
 ]);
 
 const PPR_NUMBER_KEYS = new Set<PropertyKey>([
@@ -431,12 +432,6 @@ function createHelpers(): ClientUrlHelpers {
       );
     }
     for (const key of Reflect.ownKeys(config)) {
-      if (key === "when") {
-        throw new Error(
-          "clientUrls() transition() does not support `when` — the gate is a " +
-            "server-executed predicate; declare it with a server-tree transition()",
-        );
-      }
       if (!TRANSITION_CONFIG_KEYS.has(key)) {
         throw new Error(
           `clientUrls() transition() option ${JSON.stringify(String(key))} is not supported`,
@@ -446,6 +441,13 @@ function createHelpers(): ClientUrlHelpers {
     if (config.name !== undefined && typeof config.name !== "string") {
       throw new Error("clientUrls() transition() name must be a string");
     }
+    if (config.when !== undefined && typeof config.when !== "function") {
+      throw new TypeError(
+        process.env.NODE_ENV !== "production"
+          ? `clientUrls() transition() when must be a function (it runs in the browser), got ${config.when === null ? "null" : typeof config.when}`
+          : "clientUrls() transition() when must be a function",
+      );
+    }
     if (
       config.viewTransition !== undefined &&
       config.viewTransition !== "auto" &&