@rangojs/router 0.5.1 → 0.6.0

package/src/cache/cache-runtime.ts

@@ -51,6 +51,7 @@ import {
   recordRequestTags,
   runWithCacheTagScope,
 } from "./cache-tag.js";
+import { runWithCacheExecScope } from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
 import type { CacheItemResult } from "./types.js";
 
@@ -205,8 +206,63 @@ interface CacheEnvelope {
  * singleton), and cleared for a key as soon as the leader settles: a rejected
  * leader (function threw, or the result was not serializable) propagates to
  * current waiters, which then retry fresh.
+ *
+ * A leader that NEVER settles must not hang followers (scar tissue, autobarn
+ * pilot outage): a background shell capture's render became leader, awaited a
+ * tarpitting upstream fetch, and workerd killed the capture's waitUntil context
+ * — orphaning the leader promise as permanently pending, its map entry never
+ * cleared. Every later document render calling the same cached function (an
+ * isolate-global key for plain-args calls) awaited it forever before first
+ * byte: isolate-wide TTFB-0 until redeploy. Followers therefore trust an entry
+ * only for {@link IN_FLIGHT_LEADER_MAX_WAIT_MS} from registration; past it
+ * they evict the entry and run fresh — bounded duplicate upstream work instead
+ * of an unbounded hang. Eviction is age-based off `registeredAt`, so it also
+ * heals entries stranded by a killed context (no timer in that context needs
+ * to survive).
+ */
+interface InFlightExecution {
+  promise: Promise<CacheEnvelope>;
+  registeredAt: number;
+}
+
+const inFlightExecutions = new Map<string, InFlightExecution>();
+
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
  */
-const inFlightExecutions = new Map<string, Promise<CacheEnvelope>>();
+const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
+
+/** Distinguishes a leader timeout from a leader rejection in raceLeader. */
+const LEADER_TIMED_OUT = Symbol("leader-timed-out");
+
+/**
+ * Await a leader's envelope for at most `remainingMs`. Resolves with the
+ * envelope, `undefined` on leader rejection (the leader already cleared its
+ * entry — caller falls through to a fresh run), or {@link LEADER_TIMED_OUT}
+ * when the window expires first (caller must evict the entry itself).
+ */
+function raceLeader(
+  promise: Promise<CacheEnvelope>,
+  remainingMs: number,
+): Promise<CacheEnvelope | undefined | typeof LEADER_TIMED_OUT> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(LEADER_TIMED_OUT), remainingMs);
+    promise.then(
+      (envelope) => {
+        clearTimeout(timer);
+        resolve(envelope);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(undefined);
+      },
+    );
+  });
+}
 
 // ============================================================================
 // Core: registerCachedFunction
@@ -234,11 +290,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // cacheTag() call inside the function degrades to a no-op rather than
     // throwing "must be called inside a use cache function" - adopting cacheTag()
     // must not hard-fail in apps/tests without an item-capable cache configured.
-    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
-    // is intentionally NOT stamped here. It is a cached-path-only check; in the
-    // bypass the body actually executes, so the guarded side effects take effect
-    // and nothing is lost on a (non-existent) hit. Same applies to the
-    // non-serializable-args bypass below.
+    // Note: the cache-exec guards (cookies()/headers()/ctx.set() rejection —
+    // runWithCacheExecScope + the INSIDE_CACHE_EXEC arg stamp) are intentionally
+    // NOT active here. They are cached-path-only checks; in the bypass the body
+    // actually executes, so the guarded side effects take effect and nothing is
+    // lost on a (non-existent) hit. Same applies to the non-serializable-args
+    // bypass below.
     if (!store?.getItem) {
       // Test-ergonomics guard: under a test runner, a "use cache" function that
       // executes with no item-capable store seeded is exercising the UNCACHED
@@ -452,9 +509,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           // property stamped onto that SHARED object — so for the whole
           // revalidation window a concurrent foreground ctx.set() /
           // ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
-          // not stamped for the same reason. In-fn misuse is already caught
-          // by the miss path's stamps on the function's FIRST execution — the
-          // background re-runs the same function with the same request.
+          // never stamped anywhere for the same reason. In-body misuse IS
+          // still guarded here: runWithCacheExecScope below follows only this
+          // body's async chain, so a conditional cookies()/headers() read
+          // that fires only during revalidation throws instead of baking one
+          // user's value into the shared entry — with zero visibility to the
+          // concurrent foreground.
 
           try {
             // Re-establish the request-context ALS so a "use cache" body that
@@ -475,7 +535,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                 PHASES.background("use-cache-revalidation"),
                 async () => {
                   const scoped = runWithCacheTagScope(() =>
-                    fn.apply(this, args),
+                    runWithCacheExecScope(() => fn.apply(this, args)),
                   );
                   const freshResult = await scoped.result;
                   bgStopCapture?.();
@@ -541,20 +601,34 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // requests. The store write stays exactly once (the leader's).
     const existing = inFlightExecutions.get(cacheKey);
     if (existing) {
-      let envelope: CacheEnvelope | undefined;
-      try {
-        envelope = await existing;
-      } catch {
-        // Leader rejected (function threw or its result was not serializable);
-        // its map entry is already cleared, so fall through to a fresh run.
-        envelope = undefined;
-      }
-      if (envelope) {
+      const remainingMs =
+        IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
+      const raced =
+        remainingMs <= 0
+          ? LEADER_TIMED_OUT
+          : await raceLeader(existing.promise, remainingMs);
+      if (raced === LEADER_TIMED_OUT) {
+        // Wedged (or context-orphaned) leader: evict so this call and every
+        // later one run fresh. Guard the delete so a newer leader's entry is
+        // never removed; the stale leader's own clearSelf is identity-guarded
+        // the same way, so it can't evict our replacement if it settles late.
+        if (inFlightExecutions.get(cacheKey) === existing) {
+          inFlightExecutions.delete(cacheKey);
+        }
+        reportCacheError(
+          new Error(
+            `in-flight leader did not settle within ${IN_FLIGHT_LEADER_MAX_WAIT_MS}ms; evicted — executing fresh`,
+          ),
+          "cache-read",
+          `[use cache] "${id}" inflight-timeout`,
+        );
+        // Fall through to a fresh execution below (this call becomes leader).
+      } else if (raced) {
         try {
           return await serveCached({
-            value: envelope.serialized,
-            handles: envelope.handles,
-            tags: envelope.tags,
+            value: raced.serialized,
+            handles: raced.handles,
+            tags: raced.tags,
             shouldRevalidate: false,
           });
         } catch (error) {
@@ -566,6 +640,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           // Fall through to a fresh execution below.
         }
       }
+      // raced === undefined: leader rejected; its map entry is already
+      // cleared, so fall through to a fresh run.
     }
 
     // This call becomes the leader. Register a deferred envelope so concurrent
@@ -582,9 +658,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Followers attach their own catch; guard the map's own reference so a
     // rejected envelope with no waiter is not an unhandled rejection.
     envelopePromise.catch(() => {});
-    inFlightExecutions.set(cacheKey, envelopePromise);
+    inFlightExecutions.set(cacheKey, {
+      promise: envelopePromise,
+      registeredAt: Date.now(),
+    });
     const clearSelf = (): void => {
-      if (inFlightExecutions.get(cacheKey) === envelopePromise) {
+      if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
         inFlightExecutions.delete(cacheKey);
       }
     };
@@ -604,12 +683,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Uses ref-counted stamp/unstamp so overlapping executions
     // sharing the same ctx don't clear each other's guards.
     //
-    // LOAD-BEARING for the stale-revalidation path above: the background
-    // re-execution deliberately does NOT re-stamp (the objects are live
-    // foreground state mid-render), relying on THIS stamp having caught in-fn
-    // misuse on the function's first execution — an entry only becomes
-    // stale-revalidatable because a stamped miss ran clean and stored it. Do
-    // not create a "use cache" entry via any path that skips this stamp.
+    // The ambient guards (cookies()/headers() and getRequestContext()-reached
+    // ctx methods) ride runWithCacheExecScope below instead — an ALS scoped to
+    // the cached body's own async chain. The RequestContext itself is
+    // deliberately NOT stamped: a property on that SHARED object made every
+    // parallel read on the request throw for the cached body's whole
+    // execution window (a 2s cached fetch poisoned a sibling loader's
+    // cookies() — same hazard class as issue #684, plan 010).
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
       if (isTainted(arg)) {
@@ -617,17 +697,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         taintedArgs.push(arg);
       }
     }
-    // Always stamp the ALS RequestContext so cookies()/headers() guards fire
-    // even when the cached function receives no tainted args. The guard in
-    // cookie-store.ts checks RequestContext, not function args.
-    if (requestCtx) {
-      stampCacheExec(requestCtx as object);
-    }
 
     let result: any;
     let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
-      scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      scoped = runWithCacheTagScope(() =>
+        runWithCacheExecScope(() => fn.apply(this, args)),
+      );
       result = await scoped.result;
     } catch (execError) {
       // The function threw: drop the in-flight entry and reject any waiters so
@@ -640,9 +716,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       for (const arg of taintedArgs) {
         unstampCacheExec(arg as object);
       }
-      if (requestCtx) {
-        unstampCacheExec(requestCtx as object);
-      }
       // Remove this capture token (order-independent, safe for concurrent use)
       stopCapture?.();
     }

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

@@ -85,8 +85,15 @@ export const MAX_REVALIDATION_INTERVAL = 30;
  *
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
  */
-export const EDGE_LOOKUP_TIMEOUT_MS = 10;
+export const EDGE_LOOKUP_TIMEOUT_MS = 25;
 
 /**
  * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read

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

@@ -57,10 +57,13 @@ import { reportCacheError, reportingAsync } from "../cache-error.js";
 import type { CacheErrorCategory } from "../cache-error.js";
 import { bufferToBase64, base64ToBuffer } from "./cf-base64.js";
 import {
+  KV_KEY_PRESERVED_PREFIX_BYTES,
   KV_MAX_KEY_BYTES,
   KV_MIN_EXPIRATION_TTL,
   kvKeyByteLength,
+  kvKeyDigest,
   remainingCacheControl,
+  truncateToBytes,
 } from "./cf-kv-utils.js";
 import {
   TAG_MARKER_CACHE_PREFIX,
@@ -1325,7 +1328,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: delete from KV
       if (this.kv && this.waitUntil) {
-        const kvKey = this.toKVKey(key);
+        const kvKey = await this.toKVKey(key);
         this.waitUntil(() =>
           reportingAsync(
             () => this.kv!.delete(kvKey),
@@ -1559,7 +1562,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: persist to KV (KV requires expirationTtl >= 60s)
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = this.toDocKVKey(key);
+        const kvKey = await this.toDocKVKey(key);
         // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
         response.headers.forEach((v, k) => {
@@ -1848,7 +1851,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 = this.toKVKey(`fn:${key}`);
+        const kvKey = await this.toKVKey(`fn:${key}`);
         const expiresAt = staleAt + swrWindow * 1000;
         let envelopeJson = `{"v":${valueJson}`;
         if (handlesJson !== undefined) envelopeJson += `,"h":${handlesJson}`;
@@ -2073,20 +2076,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const taggedAt =
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
-      const kvKey = this.toKVKey(`shell:${key}`);
-      let writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
-      const kvKeyBytes = kvKeyByteLength(kvKey);
-      if (kvKeyBytes > KV_MAX_KEY_BYTES) {
-        reportCacheError(
-          new Error(
-            `shell cache key produces a ${kvKeyBytes}-byte KV key, over the ` +
-              `${KV_MAX_KEY_BYTES}-byte limit; the shell was not persisted to KV (L2).`,
-          ),
-          "cache-write",
-          "[CFCacheStore] putShell",
-        );
-        writeKv = false;
-      }
+      const kvKey = await this.toKVKey(`shell:${key}`);
+      const writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
@@ -2219,7 +2210,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
     try {
       const readStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const kvKey = this.toKVKey(`shell:${key}`);
+      const kvKey = await this.toKVKey(`shell:${key}`);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<CFShellEnvelope>(
           kvKey,
@@ -2330,11 +2321,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   /**
    * Convert string key to KV key string.
    * Uses same version prefix as Cache API for consistent invalidation.
+   *
+   * Single chokepoint for EVERY KV family (segments, items, shells, documents
+   * via toDocKVKey, tag markers via tagMarkerKey): a composed key over
+   * Cloudflare KV's 512-byte limit is normalized to a preserved readable
+   * prefix plus a SHA-256-derived 128-bit digest of the FULL key. Without
+   * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
+   * and the entry silently never reaches L2 (observed in production for
+   * "use cache" items whose serialized args — e.g. a CMS query object — blow
+   * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+   * normalization is semantics-preserving as long as distinct logical keys
+   * stay distinct: colliding requires an identical 400-byte prefix AND a
+   * 128-bit SHA-256 collision. Deterministic, so every family's read, write,
+   * and delete paths agree on the stored key.
    * @internal
    */
-  private toKVKey(key: string): string {
+  private async toKVKey(key: string): Promise<string> {
     const versionPath = this.version ? `v/${this.version}/` : "";
-    return `${versionPath}${key}`;
+    const composed = `${versionPath}${key}`;
+    if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
+    const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
+    return `${prefix}~${await kvKeyDigest(composed)}`;
   }
 
   /**
@@ -2364,7 +2371,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * document tier is the one with a request-host context here.
    * @internal
    */
-  private toDocKVKey(key: string): string {
+  private toDocKVKey(key: string): Promise<string> {
     return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
   }
 
@@ -2480,7 +2487,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // ============================================================================
 
   /** KV key for a tag's invalidation marker. */
-  private tagMarkerKey(tag: string): string {
+  private tagMarkerKey(tag: string): Promise<string> {
     return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`);
   }
 
@@ -2805,7 +2812,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // (reported cache-read), which also fails open. Either way one slow tag
     // never amplifies into a per-segment stall.
     const { value: raw, timedOut } = await this.readWithTimeout<string | null>(
-      () => this.kv!.get(this.tagMarkerKey(tag), { type: "text" }),
+      async () => this.kv!.get(await this.tagMarkerKey(tag), { type: "text" }),
       this.kvReadTimeoutMs,
       "tag marker KV read",
     );
@@ -3012,7 +3019,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    *
    * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
    * runs ONLY after that tag's KV marker write is confirmed. If any KV write
-   * fails (transient error, or an over-512-byte key), this rejects with the
+   * fails (transient error; over-limit keys are normalized by toKVKey rather
+   * than rejected), this rejects with the
    * failed tags so an awaiting updateTag() surfaces the failure instead of
    * silently reporting success while other requests/colos serve stale data. The
    * eager purge still fires for the whole batch first (it is additive).
@@ -3065,18 +3073,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
       await Promise.all(
         tags.map(async (tag) => {
-          const markerKey = this.tagMarkerKey(tag);
-          const markerKeyBytes = kvKeyByteLength(markerKey);
-          if (markerKeyBytes > KV_MAX_KEY_BYTES) {
-            failedTags.add(tag);
-            errors.push(
-              new Error(
-                `tag "${tag}" produces a ${markerKeyBytes}-byte KV ` +
-                  `marker key, over the ${KV_MAX_KEY_BYTES}-byte limit`,
-              ),
-            );
-            return;
-          }
+          // An over-limit tag no longer rejects: tagMarkerKey normalizes
+          // through toKVKey, and the marker read path derives the key the same
+          // way, so oversized tags invalidate correctly instead of erroring.
+          const markerKey = await this.tagMarkerKey(tag);
           try {
             await this.kv!.put(markerKey, String(invalidatedAt), {
               ...(this.tagInvalidationTtl
@@ -3200,7 +3200,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(key);
+      const kvKey = await this.toKVKey(key);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVSegmentEnvelope>(
           kvKey,
@@ -3294,29 +3294,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
-    const kvKey = this.toKVKey(key);
-
-    // Reject an oversized data-segment KV key the same way tag-marker keys are
-    // rejected in invalidateTags(). A key over KV_MAX_KEY_BYTES makes kv.put()
-    // fail, so the segment silently never lands in L2 (KV) and every cold-colo
-    // or TTL-expired read re-renders instead of serving stale. Segment keys can
-    // grow with user-controlled inputs (e.g. a route's search params), so report
-    // a clear, actionable error and skip the doomed write rather than letting it
-    // reject deep inside waitUntil as an opaque cache-write failure.
-    const kvKeyBytes = kvKeyByteLength(kvKey);
-    if (kvKeyBytes > KV_MAX_KEY_BYTES) {
-      reportCacheError(
-        new Error(
-          `cache segment key produces a ${kvKeyBytes}-byte KV key, over the ` +
-            `${KV_MAX_KEY_BYTES}-byte limit; the segment was not persisted to KV (L2). ` +
-            `Reduce the cache-key inputs (e.g. large search params on this route).`,
-        ),
-        "cache-write",
-        "[CFCacheStore] kvSetSegment",
-      );
-      return;
-    }
-
     const expiresAt = staleAt + swrWindow * 1000;
     // Same wire shape as JSON.stringify({ d, s, e }) — dataJson is already
     // valid JSON for CachedEntryData, so embedding it avoids re-walking the tree.
@@ -3324,8 +3301,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
     this.waitUntil(() =>
       reportingAsync(
-        () =>
-          this.kv!.put(kvKey, envelopeJson, {
+        async () =>
+          this.kv!.put(await this.toKVKey(key), envelopeJson, {
             expirationTtl: totalTtl,
           }),
         "cache-write",
@@ -3386,7 +3363,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(`fn:${key}`);
+      const kvKey = await this.toKVKey(`fn:${key}`);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVItemEnvelope>(
           kvKey,
@@ -3508,7 +3485,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toDocKVKey(key);
+      const kvKey = await this.toDocKVKey(key);
       // The document path is debug-silent (op is only get/getItem): a KV-read
       // timeout here is bounded for resilience parity (kvGetOrEvict applies the
       // budget) but emits no kv-timeout event, so its absence from the debug

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

@@ -333,7 +333,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * cannot stall the request; the read then falls through to its normal miss
    * path (L2/KV or render).
    *
-   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (25). Set to 0 (or any value
    * <= 0) to disable the budget and always await `match`.
    */
   edgeLookupTimeoutMs?: number;

package/src/cache/cf/cf-kv-utils.ts

@@ -26,6 +26,44 @@ export function kvKeyByteLength(key: string): number {
   return kvKeyEncoder.encode(key).length;
 }
 
+/**
+ * Bytes of a composed key preserved verbatim when an over-limit key is
+ * normalized (toKVKey). 400 leaves room for the `~` separator and the 32-hex
+ * digest inside KV_MAX_KEY_BYTES while keeping the version prefix and most of
+ * the logical key readable (and prefix-listable) in the KV dashboard.
+ */
+export const KV_KEY_PRESERVED_PREFIX_BYTES = 400;
+
+/**
+ * Truncate to at most `maxBytes` of UTF-8. A multibyte sequence split at the
+ * boundary decodes to U+FFFD, which is stripped — the result is deterministic
+ * for a given input, which is all key normalization needs.
+ */
+export function truncateToBytes(value: string, maxBytes: number): string {
+  const bytes = kvKeyEncoder.encode(value);
+  if (bytes.length <= maxBytes) return value;
+  return new TextDecoder()
+    .decode(bytes.subarray(0, maxBytes))
+    .replace(/�+$/, "");
+}
+
+/**
+ * 128-bit hex digest (SHA-256 truncated) of a composed KV key. WebCrypto is
+ * available on workerd and Node alike; SHA-256 (not a fast non-crypto hash)
+ * because cache keys embed user-influenced serialized args — an engineered
+ * collision between two normalized keys would serve one entry's payload for
+ * the other's.
+ */
+export async function kvKeyDigest(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    kvKeyEncoder.encode(value),
+  );
+  return Array.from(new Uint8Array(digest, 0, 16), (b) =>
+    b.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
 /**
  * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
  * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the

package/src/cache/segment-codec.ts

@@ -18,6 +18,12 @@ import {
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
+// Preserve embedded server references on a cache/prerender HIT so they
+// re-serialize to the client instead of resolving to a raw function React
+// refuses to pass to a Client Component. Shared across the deserialize sites so
+// the decode policy has a single owner.
+const PRESERVE_SERVER_REFS = { preserveServerReferences: true } as const;
+
 /**
  * Convert a ReadableStream to a string.
  */
@@ -81,7 +87,11 @@ export async function rscDeserialize<T>(
 
   const temporaryReferences = createTemporaryReferenceSet();
   const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+  return createFromReadableStream<T>(
+    stream,
+    { temporaryReferences },
+    PRESERVE_SERVER_REFS,
+  );
 }
 
 /**
@@ -116,7 +126,11 @@ export async function serializeResult(value: unknown): Promise<string | null> {
 export async function deserializeResult<T>(encoded: string): Promise<T> {
   const temporaryReferences = createTemporaryReferenceSet();
   const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+  return createFromReadableStream<T>(
+    stream,
+    { temporaryReferences },
+    PRESERVE_SERVER_REFS,
+  );
 }
 
 /**
@@ -271,9 +285,11 @@ export async function deserializeSegments(
 
       const [component, layout, loaderData, loaderDataPromise, loadingData] =
         await Promise.all([
-          createFromReadableStream(stringToStream(item.encoded), {
-            temporaryReferences,
-          }),
+          createFromReadableStream(
+            stringToStream(item.encoded),
+            { temporaryReferences },
+            PRESERVE_SERVER_REFS,
+          ),
           rscDeserialize(item.encodedLayout),
           rscDeserialize(item.encodedLoaderData),
           rscDeserialize(item.encodedLoaderDataPromise),

package/src/cache/taint.ts

@@ -21,14 +21,19 @@ export function isTainted(value: unknown): boolean {
 }
 
 /**
- * Symbol stamped on tainted ctx during "use cache" function execution.
- * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
- * throw if present — reads would cache per-request data under a shared key,
- * and side effects would be lost on cache hit.
+ * Symbol stamped on tainted ctx objects PASSED AS ARGUMENTS to a "use cache"
+ * function during its execution. ctx.set(), ctx.header(), etc. check this
+ * flag and throw if present — those side effects are lost on cache hit.
+ *
+ * Argument objects only. Ambient access (cookies()/headers() and ctx methods
+ * reached via getRequestContext()) is guarded by the AsyncLocalStorage scope
+ * in cache-exec-scope.ts instead: stamping the SHARED RequestContext made
+ * every parallel read on the request throw for the cached body's whole
+ * execution window (a 2s cached fetch poisoned a sibling loader's cookies()).
  *
  * The value is a numeric reference count, not a boolean. Multiple concurrent
- * cached functions sharing the same ctx/requestCtx each increment on entry
- * and decrement on exit. Guards fire when count > 0.
+ * cached functions sharing the same ctx each increment on entry and decrement
+ * on exit. Guards fire when count > 0.
  */
 export const INSIDE_CACHE_EXEC: unique symbol = Symbol.for(
   "rango:inside-cache-exec",
@@ -56,6 +61,20 @@ export function unstampCacheExec(obj: object): void {
   }
 }
 
+/**
+ * Probe for the AsyncLocalStorage-based "use cache" execution scope.
+ * Registered by cache-exec-scope.ts at module init; the default ("never
+ * inside") keeps this module free of node:async_hooks — taint.ts is reachable
+ * from browser-bundled DSL helpers. Covers AMBIENT ctx access inside a cached
+ * body (getRequestContext().set(...)) chain-scoped, where the object stamp
+ * below only covers ctx objects explicitly passed as arguments.
+ */
+let cacheExecScopeProbe: () => boolean = () => false;
+
+export function _setCacheExecScopeProbe(probe: () => boolean): void {
+  cacheExecScopeProbe = probe;
+}
+
 /**
  * Throw if ctx is inside a "use cache" execution.
  * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
@@ -64,12 +83,12 @@ export function assertNotInsideCacheExec(
   ctx: unknown,
   methodName: string,
 ): void {
-  if (
+  const argStamped =
     ctx !== null &&
     ctx !== undefined &&
     typeof ctx === "object" &&
-    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>)
-  ) {
+    (INSIDE_CACHE_EXEC as symbol) in (ctx as Record<symbol, unknown>);
+  if (argStamped || cacheExecScopeProbe()) {
     throw new Error(
       `ctx.${methodName}() cannot be called inside a "use cache" function. ` +
         `Side effects on the request context are lost on cache hit because ` +