@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

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

@@ -38,6 +38,8 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
+  ShellCacheEntry,
+  ShellSnapshotRecord,
 } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
 import { isPerClientSignalHeader } from "../../browser/cookie-name.js";
@@ -48,6 +50,16 @@ import {
   DEFAULT_FUNCTION_TTL,
 } from "../cache-policy.js";
 import { reportCacheError, reportingAsync } from "../cache-error.js";
+import type { CacheErrorCategory } from "../cache-error.js";
+// Reuse the CF store's binary-safe base64 helpers. bufferToBase64 caps each
+// String.fromCharCode batch at 8192 and uses .apply (never a spread), so a large
+// Response/PPR-shell body cannot blow the JS argument-count ceiling (~65k) and
+// throw RangeError inside putResponse/putShell - which the outer try/catch would
+// swallow as a cache-write degrade, silently never caching the entry. Output is
+// byte-identical to a per-byte encoder (chunk size does not affect base64), so
+// this is a robustness fix, not a format change. Do NOT reintroduce a local
+// spread-based encoder or raise the chunk here; cf-base64.ts is import-pure.
+import { bufferToBase64, base64ToBuffer } from "../cf/cf-base64.js";
 
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
@@ -89,6 +101,19 @@ export const VERCEL_MAX_TAGS_PER_ITEM: number = 128;
 /** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
 export const VERCEL_MAX_TAG_BYTES: number = 256;
 
+/**
+ * URL metacharacters a tag must not contain. The official `@vercel/functions`
+ * client interpolates the tag straight into `revalidate?tags=${tag}` with NO
+ * URL-encoding (and also sends it in a request header), so a tag carrying one of
+ * these is stored intact on write but silently mangled server-side on
+ * invalidate: `&` starts a new query param, `?` a query, `#` truncates as a
+ * fragment, `%` is read as a (bad) percent-escape, `,` splits the tag list. The
+ * entry then never clears while `updateTag()`/`expireTag()` report success -
+ * the exact false-success the store's one deliberate throw exists to prevent.
+ * Such tags are dropped symmetrically on both the write and invalidate paths.
+ */
+const VERCEL_UNSAFE_TAG_CHARS = /[,&#%?]/;
+
 /**
  * Herd-dampening window (ms). On a stale read the store pushes the entry's
  * staleAt forward by this much and re-writes it, so other readers in the same
@@ -99,10 +124,10 @@ export const VERCEL_MAX_TAG_BYTES: number = 256;
  */
 const REVALIDATION_LOCK_MS = 30_000;
 
-/** Family prefixes that keep the three value tiers from colliding in the single
- *  Vercel keyspace. The router's own semantic prefixes (doc:/partial:/use-cache:)
- *  become the suffix; `rg:` namespaces every Rango entry. */
-type CacheFamily = "s" | "i" | "r";
+/** Family prefixes that keep the value tiers from colliding in the single Vercel
+ *  keyspace. The router's own semantic prefixes (doc:/partial:/use-cache:) become
+ *  the suffix; `rg:` namespaces every Rango entry. `h` is the PPR shell tier. */
+type CacheFamily = "s" | "i" | "r" | "h";
 
 /** Stored envelope for a segment-tree entry (get/set). */
 interface VercelSegmentEnvelope {
@@ -140,10 +165,34 @@ interface VercelResponseEnvelope {
   s: number;
   /** expiresAt (ms since epoch). */
   e: number;
-  /** Tags, preserved so a stale re-stamp keeps them. */
+  /** Tags, preserved so a background revalidation re-write keeps them. */
   t?: string[];
 }
 
+/** Stored envelope for a PPR shell entry (getShell/putShell). */
+interface VercelShellEnvelope {
+  /** base64-encoded prelude bytes. */
+  p: string;
+  /** postponed state JSON, or null (DATA variant). */
+  po: string | null;
+  /** React.version at capture. */
+  rv: string;
+  /** Build version at capture (ShellCacheEntry.buildVersion). */
+  bv?: string;
+  /** createdAt (ms since epoch). */
+  c: number;
+  /** staleAt (ms since epoch). */
+  s: number;
+  /** expiresAt (ms since epoch). */
+  e: number;
+  /** Tags, preserved so a background revalidation re-write keeps them. */
+  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[];
+}
+
 /** Read-path outcome for the debug sink. */
 export type VercelCacheReadOutcome =
   | "miss"
@@ -155,7 +204,7 @@ export type VercelCacheReadOutcome =
 
 /** Diagnostic event emitted on every read when `debug` is set. */
 export interface VercelCacheReadDebugEvent {
-  op: "get" | "getItem" | "getResponse";
+  op: "get" | "getItem" | "getResponse" | "getShell";
   key: string;
   outcome: VercelCacheReadOutcome;
   staleAt?: number;
@@ -188,9 +237,9 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
   cache: VercelRuntimeCache;
 
   /**
-   * `waitUntil` from `@vercel/functions`. Used only to run the stale-read
-   * re-stamp (herd dampening) off the response path - the router already
-   * backgrounds the actual writes. When omitted, the re-stamp runs detached
+   * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
+   * write (herd dampening) off the response path - the router already
+   * backgrounds the actual writes. When omitted, the lock write runs detached
    * (fire-and-forget) instead.
    */
   waitUntil?: (promise: Promise<unknown>) => void;
@@ -239,25 +288,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
-/** Encode binary body bytes to base64 in chunks (avoids call-stack blowups). */
-function bufferToBase64(buffer: ArrayBuffer): string {
-  const bytes = new Uint8Array(buffer);
-  let binary = "";
-  const CHUNK = 0x8000;
-  for (let i = 0; i < bytes.length; i += CHUNK) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
-  }
-  return btoa(binary);
-}
-
-/** Decode a base64 body back into bytes. */
-function base64ToBuffer(b64: string): ArrayBuffer {
-  const binary = atob(b64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes.buffer;
-}
-
 /**
  * Vercel Runtime Cache-backed segment cache store.
  *
@@ -276,6 +306,16 @@ function base64ToBuffer(b64: string): ArrayBuffer {
  * that propagates expireTag rejections does get the strict guarantee, which is
  * what the unit suite exercises.)
  *
+ * Key hashing / family isolation. The store namespaces its three value tiers as
+ * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * disjoint keyspaces. That separation is only as strong as the cache's
+ * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
+ * bits (8 hex chars), so at a large live-key count a collision can let one
+ * entry's body be served for another key (same-family) or be misread as corrupt
+ * (cross-family). For deployments with many cached keys, pass a wider hash so
+ * the family split is real isolation, e.g. `getCache({ keyHashFunction })` with
+ * a sha256-based function.
+ *
  * @example
  * ```ts
  * import { getCache, waitUntil } from "@vercel/functions";
@@ -284,7 +324,9 @@ function base64ToBuffer(b64: string): ArrayBuffer {
  * export const router = createRouter({
  *   cache: () => ({
  *     store: new VercelCacheStore({
- *       cache: getCache({ namespace: import.meta.env.VERCEL_DEPLOYMENT_ID }),
+ *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ *       // would be undefined here) so cross-deploy busting via `version` works.
+ *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
  *       waitUntil,
  *       defaults: { ttl: 60, swr: 300 },
  *     }),
@@ -343,7 +385,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "get", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asSegmentEnvelope(raw);
+    const env = this.asSegmentEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed segment envelope"),
@@ -370,35 +412,19 @@ export class VercelCacheStore<
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(
-        storeKey,
-        env,
-        env.d.tags,
-        "[VercelCacheStore] get",
-      );
-      this.emitDebug({
-        op: "get",
-        key,
-        outcome: "stale-revalidate",
-        shouldRevalidate: true,
-        staleAt: env.s,
-        expiresAt: env.e,
-        readMs,
-      });
-      return { data: env.d, shouldRevalidate: true };
-    }
-
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(storeKey, env.e, "[VercelCacheStore] get")
+      : false;
     this.emitDebug({
       op: "get",
       key,
-      outcome: "fresh",
-      shouldRevalidate: false,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
     });
-    return { data: env.d, shouldRevalidate: false };
+    return { data: env.d, shouldRevalidate };
   }
 
   async set(
@@ -410,12 +436,22 @@ export class VercelCacheStore<
     try {
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
-      const env: VercelSegmentEnvelope = { d: data, s: staleAt, e: expiresAt };
+      // Embed the CLAMPED tags, like putResponse/setItem: the segment family
+      // carries its tags inside `d`, and a raw list would resurface dropped
+      // tags into recordRequestTags on every hit.
+      const safeTags = this.clampTagsForWrite(
+        data.tags,
+        "[VercelCacheStore] set",
+      );
+      const d: CachedEntryData = data.tags
+        ? { ...data, tags: safeTags.length > 0 ? safeTags : undefined }
+        : data;
+      const env: VercelSegmentEnvelope = { d, s: staleAt, e: expiresAt };
       await this.write(
         this.toStoreKey(key, "s"),
         env,
         ttl + swrWindow,
-        data.tags,
+        safeTags,
         "[VercelCacheStore] set",
       );
     } catch (error) {
@@ -456,7 +492,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "getResponse", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asResponseEnvelope(raw);
+    const env = this.asResponseEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed response envelope"),
@@ -482,11 +518,11 @@ export class VercelCacheStore<
       return null;
     }
 
-    // Reconstruct the Response BEFORE marking revalidating. A corrupt body (e.g.
-    // invalid base64 from base64ToBuffer, or bad header entries) would otherwise
-    // throw out of getResponse — breaking the fail-open contract — and a stale
-    // re-stamp would re-persist the bad value. Treat a reconstruction failure as
-    // a corrupt entry: report, evict, and miss.
+    // Reconstruct the Response BEFORE claiming revalidation. A corrupt body
+    // (e.g. invalid base64 from base64ToBuffer, or bad header entries) would
+    // otherwise throw out of getResponse — breaking the fail-open contract — and
+    // a stale read would have written a lock for an entry it then evicts. Treat a
+    // reconstruction failure as a corrupt entry: report, evict, and miss.
     let response: Response;
     try {
       response = new Response(base64ToBuffer(env.b), {
@@ -505,24 +541,23 @@ export class VercelCacheStore<
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(
-        storeKey,
-        env,
-        env.t,
-        "[VercelCacheStore] getResponse",
-      );
-    }
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(
+          storeKey,
+          env.e,
+          "[VercelCacheStore] getResponse",
+        )
+      : false;
     this.emitDebug({
       op: "getResponse",
       key,
-      outcome: isStale ? "stale-revalidate" : "fresh",
-      shouldRevalidate: isStale,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
     });
-    return { response, shouldRevalidate: isStale };
+    return { response, shouldRevalidate };
   }
 
   async putResponse(
@@ -541,19 +576,28 @@ export class VercelCacheStore<
       });
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+      // Embed the CLAMPED tags in the envelope, not the raw list: tags dropped
+      // on write (unsafe/over-cap) would otherwise resurface on a hit and be
+      // merged into an upstream document's tag set, letting it claim a tag this
+      // entry can't actually be invalidated by. write() re-clamps (idempotent
+      // and silent on an already-clean list).
+      const safeTags = this.clampTagsForWrite(
+        tags,
+        "[VercelCacheStore] putResponse",
+      );
       const env: VercelResponseEnvelope = {
         b: bufferToBase64(body),
         st: response.status,
         hd: headers,
         s: staleAt,
         e: expiresAt,
-        t: tags,
+        t: safeTags.length > 0 ? safeTags : undefined,
       };
       await this.write(
         this.toStoreKey(key, "r"),
         env,
         ttl + swrWindow,
-        tags,
+        safeTags,
         "[VercelCacheStore] putResponse",
       );
     } catch (error) {
@@ -580,7 +624,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "getItem", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asItemEnvelope(raw);
+    const env = this.asItemEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed item envelope"),
@@ -595,19 +639,30 @@ export class VercelCacheStore<
     const now = Date.now();
     if (now > env.e) {
       void this.safeDelete(storeKey);
-      this.emitDebug({ op: "getItem", key, outcome: "expired", readMs });
+      this.emitDebug({
+        op: "getItem",
+        key,
+        outcome: "expired",
+        staleAt: env.s,
+        expiresAt: env.e,
+        readMs,
+      });
       return null;
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(storeKey, env, env.t, "[VercelCacheStore] getItem");
-    }
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(
+          storeKey,
+          env.e,
+          "[VercelCacheStore] getItem",
+        )
+      : false;
     this.emitDebug({
       op: "getItem",
       key,
-      outcome: isStale ? "stale-revalidate" : "fresh",
-      shouldRevalidate: isStale,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
@@ -615,7 +670,7 @@ export class VercelCacheStore<
     return {
       value: env.v,
       handles: env.h,
-      shouldRevalidate: isStale,
+      shouldRevalidate,
       tags: env.t,
     };
   }
@@ -629,18 +684,24 @@ export class VercelCacheStore<
       const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+      // Store the clamped tags (see putResponse) so dropped tags don't resurface
+      // on a hit; write() re-clamps idempotently.
+      const safeTags = this.clampTagsForWrite(
+        options?.tags,
+        "[VercelCacheStore] setItem",
+      );
       const env: VercelItemEnvelope = {
         v: value,
         h: options?.handles,
         s: staleAt,
         e: expiresAt,
-        t: options?.tags,
+        t: safeTags.length > 0 ? safeTags : undefined,
       };
       await this.write(
         this.toStoreKey(key, "i"),
         env,
         ttl + swrWindow,
-        options?.tags,
+        safeTags,
         "[VercelCacheStore] setItem",
       );
     } catch (error) {
@@ -648,12 +709,138 @@ export class VercelCacheStore<
     }
   }
 
+  // --- Shell family (PPR shell resume - getShell/putShell) ---
+
+  async getShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    const storeKey = this.toStoreKey(key, "h");
+    const started = Date.now();
+    let raw: unknown;
+    try {
+      raw = await this.cache.get(storeKey);
+    } catch (error) {
+      reportCacheError(error, "cache-read", "[VercelCacheStore] getShell");
+      this.emitDebug({ op: "getShell", key, outcome: "error" });
+      return null;
+    }
+    const readMs = Date.now() - started;
+
+    if (raw == null) {
+      this.emitDebug({ op: "getShell", key, outcome: "miss", readMs });
+      return null;
+    }
+    const env = this.asShellEnvelope(this.decodeRaw(raw));
+    if (!env) {
+      reportCacheError(
+        new Error("malformed shell envelope"),
+        "cache-corrupt",
+        "[VercelCacheStore] getShell",
+      );
+      void this.safeDelete(storeKey);
+      this.emitDebug({ op: "getShell", key, outcome: "corrupt", readMs });
+      return null;
+    }
+
+    const now = Date.now();
+    if (now > env.e) {
+      void this.safeDelete(storeKey);
+      this.emitDebug({
+        op: "getShell",
+        key,
+        outcome: "expired",
+        staleAt: env.s,
+        expiresAt: env.e,
+        readMs,
+      });
+      return null;
+    }
+
+    const isStale = env.s > 0 && now > env.s;
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(
+          storeKey,
+          env.e,
+          "[VercelCacheStore] getShell",
+        )
+      : false;
+    this.emitDebug({
+      op: "getShell",
+      key,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
+      staleAt: env.s,
+      expiresAt: env.e,
+      readMs,
+    });
+    return {
+      entry: {
+        prelude: env.p,
+        postponed: env.po,
+        reactVersion: env.rv,
+        buildVersion: env.bv,
+        initialTheme: env.i,
+        snapshot: env.sn,
+        createdAt: env.c,
+      },
+      shouldRevalidate,
+    };
+  }
+
+  async putShell(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void> {
+    try {
+      const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
+      const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
+      const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+      // Store the CLAMPED tags (see putResponse/setItem) so dropped tags don't
+      // resurface on a hit; write() re-clamps idempotently.
+      const safeTags = this.clampTagsForWrite(
+        tags,
+        "[VercelCacheStore] putShell",
+      );
+      const env: VercelShellEnvelope = {
+        p: entry.prelude,
+        po: entry.postponed,
+        rv: entry.reactVersion,
+        bv: entry.buildVersion,
+        c: entry.createdAt,
+        s: staleAt,
+        e: expiresAt,
+        t: safeTags.length > 0 ? safeTags : undefined,
+        i: entry.initialTheme,
+        sn: entry.snapshot,
+      };
+      // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
+      // oversized shell prelude is reported and skipped (fail-open to a full
+      // render), never silently no-op'd on the platform.
+      await this.write(
+        this.toStoreKey(key, "h"),
+        env,
+        ttl + swrWindow,
+        safeTags,
+        "[VercelCacheStore] putShell",
+      );
+    } catch (error) {
+      reportCacheError(error, "cache-write", "[VercelCacheStore] putShell");
+    }
+  }
+
   // --- Tags ---
 
   async invalidateTags(tags: string[]): Promise<void> {
     if (!tags || tags.length === 0) return;
     // No per-item cap here: an invalidation must reach every requested tag.
-    const safe = this.validateTags(tags, "[VercelCacheStore] invalidateTags");
+    const safe = this.validateTags(
+      tags,
+      "[VercelCacheStore] invalidateTags",
+      "cache-invalidate",
+    );
     if (safe.length === 0) return;
     try {
       await this.cache.expireTag(safe);
@@ -675,6 +862,12 @@ export class VercelCacheStore<
 
   // --- Internals ---
 
+  // The `rg:{family}:` prefix keeps the three value tiers in disjoint
+  // keyspaces, but the isolation is only as strong as the cache's
+  // keyHashFunction: djb2 (getCache's default) folds this to 32 bits, so at a
+  // large live-key count a same-family collision can serve the wrong body and a
+  // cross-family one reads as corrupt. See the class doc for passing a wider
+  // hash (sha256) when many keys are live.
   private toStoreKey(key: string, family: CacheFamily): string {
     const versionPrefix = this.version ? `v/${this.version}/` : "";
     return `${versionPrefix}rg:${family}:${key}`;
@@ -687,72 +880,135 @@ export class VercelCacheStore<
     tags: string[] | undefined,
     label: string,
   ): Promise<void> {
-    if (!this.withinSizeLimit(value, label)) return;
+    // Serialize the envelope exactly ONCE: the same string measures the entry
+    // against the size cap AND is what we hand the platform. The Vercel client
+    // JSON-serializes whatever value it is given, so passing the raw object here
+    // would walk and stringify the (potentially large) envelope a SECOND time.
+    // Entries written this way are JSON strings; the read path (decodeRaw)
+    // parses them back, and still accepts the legacy object shape written before
+    // this change.
+    let serialized: string | undefined;
+    try {
+      serialized = JSON.stringify(value);
+    } catch {
+      // Unserializable value: fall back to letting the platform serialize it
+      // (best-effort — matches the prior "cannot measure -> allow the write").
+      serialized = undefined;
+    }
+    if (serialized !== undefined && !this.withinSizeLimit(serialized, label)) {
+      return;
+    }
     const safeTags = this.clampTagsForWrite(tags, label);
     const options: { ttl: number; tags?: string[]; name?: string } = {
       ttl: Math.max(1, Math.ceil(totalTtlSeconds)),
     };
     if (safeTags.length > 0) options.tags = safeTags;
     if (this.name) options.name = this.name;
-    await this.cache.set(storeKey, value, options);
+    await this.cache.set(storeKey, serialized ?? value, options);
   }
 
   /**
-   * Stale-read herd dampening: push staleAt forward by REVALIDATION_LOCK_MS
-   * (clamped to the hard expiry) and re-write the same envelope under the
-   * remaining lifetime, so concurrent same-region readers see it as fresh while
-   * one revalidates. Best-effort and non-blocking; never throws.
+   * Normalize a value read back from the cache. Entries written by this store
+   * are pre-serialized JSON strings (see write()); legacy entries (written
+   * before that change, or by a client that deserializes for us) come back as
+   * objects. Parse strings, pass objects through, and treat a non-JSON string
+   * as corrupt (returns undefined, so the caller reports + evicts).
    */
-  private markRevalidating<E extends { s: number; e: number }>(
+  private decodeRaw(raw: unknown): unknown {
+    if (typeof raw !== "string") return raw;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Stale-read herd dampening via a tiny companion lock key. On a stale read,
+   * check `{storeKey}:lock`; if absent, claim it (write a short-TTL marker) and
+   * return true so THIS reader triggers revalidation. If present, another
+   * same-region reader already claimed it, so return false and serve the stale
+   * entry as fresh without piling on. Best-effort and non-blocking; never throws.
+   *
+   * Only the STALE path pays the extra lock read; the fresh-hit path takes no
+   * lock round trip. Unlike the prior whole-envelope re-stamp, a stale read now
+   * writes only the tiny lock, never the (potentially large) payload.
+   *
+   * Non-atomic (getCache has no compare-and-set): two readers can both find no
+   * lock and both revalidate. The window is REVALIDATION_LOCK_MS wide, after
+   * which the lock expires and the entry is re-claimed (or a fresh write has
+   * superseded it). A read-compare would not close the race without CAS.
+   */
+  private async claimRevalidation(
     storeKey: string,
-    env: E,
-    tags: string[] | undefined,
+    expiresAt: number,
     label: string,
-  ): void {
-    const now = Date.now();
-    const remainingSeconds = Math.ceil((env.e - now) / 1000);
-    if (remainingSeconds <= 0) return;
-    const locked: E = {
-      ...env,
-      s: Math.min(now + REVALIDATION_LOCK_MS, env.e),
-    };
+  ): Promise<boolean> {
+    const lockKey = `${storeKey}:lock`;
+    let lock: unknown;
+    try {
+      lock = await this.cache.get(lockKey);
+    } catch {
+      // A lock-read failure must not break the read path: treat as unlocked.
+      lock = null;
+    }
+    if (lock != null) return false;
+
+    const remainingSeconds = Math.ceil((expiresAt - Date.now()) / 1000);
+    const lockTtl = Math.max(
+      1,
+      Math.min(Math.ceil(REVALIDATION_LOCK_MS / 1000), remainingSeconds),
+    );
     const task = (): Promise<void> =>
-      this.write(storeKey, locked, remainingSeconds, tags, label);
+      this.cache.set(lockKey, 1, { ttl: lockTtl });
     if (this.waitUntil) {
       this.waitUntil(reportingAsync(task, "cache-write", label));
     } else {
       void reportingAsync(task, "cache-write", label);
     }
+    return true;
   }
 
-  private withinSizeLimit(value: unknown, label: string): boolean {
-    try {
-      const bytes = new TextEncoder().encode(JSON.stringify(value)).length;
-      if (bytes >= this.maxItemBytes) {
-        reportCacheError(
-          new Error(
-            `entry is ${bytes}B, at/above the ${this.maxItemBytes}B cap; not cached`,
-          ),
-          "cache-write",
-          label,
-        );
-        return false;
-      }
-    } catch {
-      // If the value cannot be measured, allow the write (best-effort).
+  /** Measure a pre-serialized entry against the per-item size cap (see write). */
+  private withinSizeLimit(serialized: string, label: string): boolean {
+    const bytes = new TextEncoder().encode(serialized).length;
+    if (bytes >= this.maxItemBytes) {
+      reportCacheError(
+        new Error(
+          `entry is ${bytes}B, at/above the ${this.maxItemBytes}B cap; not cached`,
+        ),
+        "cache-write",
+        label,
+      );
+      return false;
     }
     return true;
   }
 
-  /** Drop tags Vercel rejects (commas, over-length). Used by invalidateTags. */
-  private validateTags(tags: string[], label: string): string[] {
+  /**
+   * Drop tags Vercel cannot round-trip: over-length tags, and tags carrying a
+   * URL metacharacter the `@vercel/functions` client does not encode (see
+   * VERCEL_UNSAFE_TAG_CHARS). Runs on BOTH paths - the write path
+   * (clampTagsForWrite) and invalidateTags - so a tag that would silently fail
+   * invalidation is never stored in the first place. `category` reports the
+   * drop under the caller's real operation (write vs invalidate).
+   */
+  private validateTags(
+    tags: string[],
+    label: string,
+    category: CacheErrorCategory,
+  ): string[] {
     const encoder = new TextEncoder();
     const out: string[] = [];
     for (const tag of tags) {
-      if (tag.includes(",")) {
+      const unsafe = VERCEL_UNSAFE_TAG_CHARS.exec(tag);
+      if (unsafe) {
         reportCacheError(
-          new Error(`tag "${tag}" contains a comma; skipped`),
-          "cache-invalidate",
+          new Error(
+            `tag "${tag}" contains an unencodable URL character "${unsafe[0]}"; ` +
+              `skipped (it would not round-trip through Vercel tag invalidation)`,
+          ),
+          category,
           label,
         );
         continue;
@@ -760,7 +1016,7 @@ export class VercelCacheStore<
       if (encoder.encode(tag).length > VERCEL_MAX_TAG_BYTES) {
         reportCacheError(
           new Error(`tag exceeds ${VERCEL_MAX_TAG_BYTES} bytes; skipped`),
-          "cache-invalidate",
+          category,
           label,
         );
         continue;
@@ -776,7 +1032,7 @@ export class VercelCacheStore<
     label: string,
   ): string[] {
     if (!tags || tags.length === 0) return [];
-    const valid = this.validateTags(tags, label);
+    const valid = this.validateTags(tags, label, "cache-write");
     if (valid.length > VERCEL_MAX_TAGS_PER_ITEM) {
       reportCacheError(
         new Error(
@@ -837,6 +1093,27 @@ 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 } = raw;
+    if (typeof p !== "string" || typeof rv !== "string") return null;
+    if (po !== null && typeof po !== "string") return null;
+    if (typeof c !== "number") return null;
+    if (typeof s !== "number" || typeof e !== "number") return null;
+    return {
+      p,
+      po: po as string | null,
+      rv,
+      bv: typeof bv === "string" ? bv : undefined,
+      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,
+    };
+  }
+
   private asResponseEnvelope(raw: unknown): VercelResponseEnvelope | null {
     if (!isRecord(raw)) return null;
     const { b, st, hd, s, e, t } = raw;