@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/cache/cache-runtime.ts

@@ -20,7 +20,11 @@ import {
   encodeReply,
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../server/request-context.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
   CACHED_FN_SYMBOL,
@@ -32,20 +36,232 @@ import {
 export { isCachedFunction };
 import { serializeResult, deserializeResult } from "./segment-codec.js";
 import { createHandleStore } from "../server/handle-store.js";
-import { restoreHandles } from "./handle-snapshot.js";
+import {
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
+import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import {
+  normalizeTags,
+  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";
+
+/**
+ * DJB2 hash returning an 8-char hex string. Deterministic across runtimes
+ * (no crypto import — cache-runtime runs on the edge). Mirrors prerender's
+ * param-hash djb2Hex so binary key parts hash consistently.
+ */
+function djb2HexBytes(bytes: Uint8Array): string {
+  let hash = 5381;
+  for (let i = 0; i < bytes.length; i++) {
+    hash = ((hash << 5) + hash + bytes[i]!) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
 
 /**
  * Convert encodeReply result to a stable string key.
- * encodeReply may return string or FormData — normalize to string.
+ *
+ * encodeReply may return a string or FormData. A plain string is already
+ * deterministic for a given arg set, so return it verbatim. FormData (emitted
+ * whenever a key arg is a typed array / Blob / File / a large object React
+ * lazily chunks) carries a per-call RANDOM multipart boundary
+ * (`formdata-undici-<random>`); stringifying the whole body via
+ * `new Response(formData).text()` would therefore produce a DIFFERENT key on
+ * every call, so the cached function would always miss and the store would
+ * accumulate one duplicate entry per call (unbounded growth).
+ *
+ * Instead derive the key from the entries themselves, independent of the
+ * boundary: iterate in sorted-key order and, for each value, emit a
+ * boundary-free token — `s:<value>` for strings, `b:<size>:<type>:<name>:<hash>`
+ * for Blob/File (bytes folded via djb2 so distinct payloads of equal
+ * size/type/name still differ). Strings carry an `s:` type tag so a string whose
+ * value happens to equal a blob token (e.g. the literal `b:4::a:b:<hash>`) cannot
+ * collide with an actual Blob/File entry under the same FormData key. The
+ * user-controlled `type`/`name` are percent-encoded before joining so an embedded
+ * `:` cannot shift the field boundaries and collide two distinct files (e.g.
+ * {name:"a:b",type:""} vs {name:"b",type:":a"}). The result is stable across
+ * identical arg sets.
  */
-async function replyToCacheKey(encoded: string | FormData): Promise<string> {
+export async function replyToCacheKey(
+  encoded: string | FormData,
+): Promise<string> {
   if (typeof encoded === "string") return encoded;
-  // FormData: convert to Response body, then to string for deterministic key
-  const text = await new Response(encoded).text();
-  return text;
+
+  // Snapshot entries synchronously (forEach avoids relying on FormData's
+  // iterator typings), then fold any Blob/File bytes asynchronously.
+  const raw: [string, FormDataEntryValue][] = [];
+  encoded.forEach((value, key) => {
+    raw.push([key, value]);
+  });
+  const pairs: [string, string][] = [];
+  for (const [key, value] of raw) {
+    if (typeof value === "string") {
+      // Type-tag strings with `s:` so a string equal to a blob token (e.g.
+      // `b:4::a:b:<hash>`) cannot collide with a Blob/File entry under the same
+      // key (which carries the `b:` tag below).
+      pairs.push([key, "s:" + value]);
+    } else {
+      // Blob/File: fold the bytes into a deterministic, boundary-free token.
+      // Percent-encode the user-controlled type/name so an embedded `:` cannot
+      // shift the `:`-delimited field boundaries and collide distinct files.
+      const buf = await value.arrayBuffer();
+      const hash = djb2HexBytes(new Uint8Array(buf));
+      const name = "name" in value ? value.name : "";
+      const encType = encodeURIComponent(value.type);
+      const encName = encodeURIComponent(name);
+      pairs.push([key, `b:${value.size}:${encType}:${encName}:${hash}`]);
+    }
+  }
+  return encodeKV(pairs, { sort: true });
+}
+
+// Cached-fn ids already warned about running uncached under a test runner, so
+// the test-ergonomics warning fires once per fn rather than once per call.
+const warnedUncachedUnderTest = new Set<string>();
+
+/**
+ * Fast-path cache-key builder for JSON-safe key args. Returns a deterministic
+ * string (object keys recursively sorted so insertion order can't change the
+ * key) when EVERY part is a primitive or a plain object/array of the same, and
+ * `undefined` otherwise so the caller falls back to the Flight reply encoder.
+ *
+ * Strings are always quoted via JSON.stringify, so they can never collide with
+ * the bareword encodings of null/true/false/undefined/numbers. Anything the
+ * reply encoder must handle instead — functions, symbols, bigint, non-finite
+ * numbers, Dates, Maps, class instances, promises, and React elements (whose
+ * `$$typeof` symbol value trips the symbol reject) — yields `undefined`.
+ */
+function jsonSafeKeyPart(value: unknown): string | undefined {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string":
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      return Number.isFinite(value) ? String(value) : undefined;
+    case "undefined":
+      return "undefined";
+    case "object": {
+      if (Array.isArray(value)) {
+        const parts: string[] = [];
+        for (const item of value) {
+          const encoded = jsonSafeKeyPart(item);
+          if (encoded === undefined) return undefined;
+          parts.push(encoded);
+        }
+        return `[${parts.join(",")}]`;
+      }
+      // Only plain objects (Object.prototype or null proto) are fast-path safe.
+      // Dates, Maps, class instances, promises, etc. carry a different prototype
+      // and fall back to the encoder.
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return undefined;
+      const obj = value as Record<string, unknown>;
+      const parts: string[] = [];
+      for (const key of Object.keys(obj).sort()) {
+        const encoded = jsonSafeKeyPart(obj[key]);
+        if (encoded === undefined) return undefined;
+        parts.push(`${JSON.stringify(key)}:${encoded}`);
+      }
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      // bigint, symbol, function
+      return undefined;
+  }
+}
+
+/**
+ * The serialized product of one "use cache" execution: exactly what the store
+ * write persists. Followers that dedup onto an in-flight execution (see
+ * inFlightExecutions) await this and serve it as a synthetic cache hit — each
+ * deserializing its OWN copy of `serialized` and replaying `handles`/`tags`
+ * against its OWN request. A deserialized result object is never shared.
+ */
+interface CacheEnvelope {
+  /** RSC-serialized return value (never null — a null serialize rejects). */
+  serialized: string;
+  /** Merged profile/DSL + runtime cacheTag() tags. */
+  tags: string[];
+  /** RSC-encoded handle blob captured during execution, if any. */
+  handles?: string;
+}
+
+/**
+ * In-flight "use cache" executions keyed by cache key. When N concurrent calls
+ * miss on the same key, only the first (the leader) runs the function; the rest
+ * await its {@link CacheEnvelope} and serve it as a synthetic hit rather than
+ * re-running the function and re-writing the store. Isolate-scoped (module
+ * 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 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);
+      },
+    );
+  });
 }
 
 // ============================================================================
@@ -70,9 +286,39 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const store = requestCtx?._cacheStore;
     const resolvedProfileName = profileName || "default";
 
-    // Bypass: no store or no getItem support
+    // Bypass: no store or no getItem support. Still run inside a tag scope so a
+    // 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 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) {
-      return fn.apply(this, args);
+      // Test-ergonomics guard: under a test runner, a "use cache" function that
+      // executes with no item-capable store seeded is exercising the UNCACHED
+      // path — a green test that proves nothing about caching. Warn once per fn
+      // id so the author knows to seed a cacheStore. Advisory (never throws), so
+      // a test that DELIBERATELY runs uncached is unaffected. Gated on the test
+      // runner (process.env.VITEST, not folded) so production never evaluates it.
+      if (isUnderTestRunner() && !warnedUncachedUnderTest.has(id)) {
+        warnedUncachedUnderTest.add(id);
+        console.warn(
+          `[rango] "use cache" function "${id}" executed but no cacheStore was ` +
+            `seeded; the cached path is NOT under test (it ran uncached). Pass ` +
+            `{ cacheStore, cacheProfiles } to runLoader/runMiddleware/renderHandler/` +
+            `runInRequestContext (or configure createRouter({ cache }) for dispatch) ` +
+            `to exercise it.`,
+        );
+      }
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      // Still record the runtime tags into the request set so a cacheTag() in an
+      // uncached function tags the document, even with no item-capable store.
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Resolve profile strictly from request-scoped config (set by the
@@ -114,9 +360,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           if (ctx._responseType) {
             keyArgs.push(ctx._responseType);
           }
-          // Include user-facing search params (exclude internal _rsc*/__ params)
+          // Include user-facing search params (exclude internal _rsc*/__
+          // params, plus the request's cache.searchParams filter -- same
+          // normalization as the URL-keyed tiers).
           if (ctx.searchParams instanceof URLSearchParams) {
-            const normalized = sortedSearchString(ctx.searchParams);
+            const normalized = sortedSearchString(
+              ctx.searchParams,
+              requestCtx?._searchParamsFilter,
+            );
             if (normalized) {
               keyArgs.push(normalized);
             }
@@ -145,67 +396,105 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     let cacheKey: string;
     try {
       if (keyArgs.length > 0) {
-        const tempRefs = createClientTemporaryReferenceSet();
-        const encoded = await encodeReply(keyArgs as unknown[], {
-          temporaryReferences: tempRefs,
-        });
-        const argsKey = await replyToCacheKey(encoded);
-        cacheKey = `use-cache:${id}:${argsKey}`;
+        // Fast path: when every key arg is JSON-safe, build the key with a
+        // deterministic stable-stringify and skip encodeReply (the Flight reply
+        // encoder runs on EVERY call, including hits). The `:j:` namespace keeps
+        // these keys disjoint from the encoder path so the two can never collide
+        // for one fn id. Entries cached under the old encoder key for JSON-safe
+        // args cold-start once after this upgrade.
+        const fastKey = jsonSafeKeyPart(keyArgs);
+        if (fastKey !== undefined) {
+          cacheKey = `use-cache:${id}:j:${fastKey}`;
+        } else {
+          const tempRefs = createClientTemporaryReferenceSet();
+          const encoded = await encodeReply(keyArgs as unknown[], {
+            temporaryReferences: tempRefs,
+          });
+          const argsKey = await replyToCacheKey(encoded);
+          cacheKey = `use-cache:${id}:${argsKey}`;
+        }
       } else {
         cacheKey = `use-cache:${id}`;
       }
     } catch {
-      // Non-serializable args: run uncached
-      return fn.apply(this, args);
+      // Non-serializable args: run uncached (within a tag scope so cacheTag()
+      // still does not throw). Record runtime tags so the document union still
+      // sees them even though this call is not itself cached.
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Cache lookup
     const cached = await store.getItem(cacheKey);
 
+    // Serve a cached entry on the hit path: deserialize the stored value,
+    // replay handle data (gated on tainted args), and surface the entry's tags
+    // to the request set (the function did not re-run, so its runtime cacheTag()
+    // tags are only available from the stored entry). Shared by the fresh-hit
+    // and stale-hit branches; the only divergence is the stale branch scheduling
+    // background revalidation, which it does after this returns.
+    const serveCached = async (entry: CacheItemResult): Promise<any> => {
+      const result = await deserializeResult(entry.value);
+      if (entry.handles && hasTaintedArgs) {
+        const handleStore = requestCtx?._handleStore;
+        if (handleStore) {
+          const r = await decodeHandles(entry.handles);
+          if (r) restoreHandles(r, handleStore);
+        }
+      }
+      recordRequestTags(entry.tags, requestCtx);
+      return result;
+    };
+
     if (cached && !cached.shouldRevalidate) {
       // Fresh hit: deserialize and return
       try {
-        const result = await deserializeResult(cached.value);
-        // Restore handle data if present
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
-          }
-        }
-        return result;
-      } catch {
-        // Deserialization failed, fall through to fresh execution
+        return await serveCached(cached);
+      } catch (error) {
+        // The stored value is corrupt/partial (failed RSC deserialize). Report
+        // it, then fall through to fresh execution - the miss path below re-runs
+        // and setItem() overwrites the faulty entry under the same key (self-heal).
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" fresh-hit`,
+        );
       }
     }
 
-    if (cached?.shouldRevalidate) {
+    // foregroundOnAction (opt-in; see CacheProfile.foregroundOnAction): during an
+    // action's revalidation render, a stale entry falls through to the foreground
+    // miss path below instead of SWR. The flag is set by revalidateAfterAction.
+    const foregroundOnActionRevalidation =
+      requestCtx?._inActionRevalidation === true &&
+      profile.foregroundOnAction === true;
+    if (cached?.shouldRevalidate && !foregroundOnActionRevalidation) {
       // Stale hit: return stale value, revalidate in background
       try {
-        const result = await deserializeResult(cached.value);
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
-          }
-        }
+        const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
-        // Use an isolated handle store so background pushes don't pollute the
-        // live response or throw LateHandlePushError on the completed store.
-        // Same isolation pattern as route-level background-revalidation.ts.
         runBackground(requestCtx, async () => {
-          // Reuse closure-captured requestCtx instead of calling
-          // getRequestContext() — ALS context may be gone inside waitUntil.
-          let originalHandleStore:
-            | ReturnType<typeof createHandleStore>
-            | undefined;
-          if (hasTaintedArgs && requestCtx) {
-            originalHandleStore = requestCtx._handleStore;
-            requestCtx._handleStore = createHandleStore();
-          }
-          const bgHandleStore = hasTaintedArgs
-            ? requestCtx?._handleStore
-            : undefined;
+          // The background body runs under a DERIVED context with an OWN
+          // _handleStore (the shell-capture isolation pattern —
+          // shell-capture.ts attemptCapture): its handle pushes land in the
+          // isolated store (captured below, persisted with the entry) while
+          // the foreground keeps pushing into the ORIGINAL store, untouched.
+          // Derivation matters because the foreground is STILL RENDERING here
+          // — runBackground/waitUntil starts the task on the next microtask,
+          // not after the response. The previous shape swapped
+          // requestCtx._handleStore in place (restore in finally), which
+          // routed the whole overlap window's foreground pushes into the
+          // background store: lost from the live document AND persisted into
+          // the revalidated entry (issue #684, plan 010).
+          const bgHandleStore =
+            hasTaintedArgs && requestCtx ? createHandleStore() : undefined;
+          const bgCtx: typeof requestCtx = bgHandleStore
+            ? Object.assign(Object.create(requestCtx), {
+                _handleStore: bgHandleStore,
+              })
+            : requestCtx;
           let bgCapture: HandleCapture | undefined;
           let bgStopCapture: (() => void) | undefined;
           if (bgHandleStore) {
@@ -214,57 +503,172 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted args and RequestContext so request-scoped
-          // reads (cookies, headers) and side effects (ctx.set, etc.)
-          // throw inside background revalidation, same as the miss path.
-          // Uses ref-counted stamp/unstamp so overlapping executions
-          // sharing the same ctx don't clear each other's guards.
-          const bgTaintedArgs: unknown[] = [];
-          for (const arg of args) {
-            if (isTainted(arg)) {
-              stampCacheExec(arg as object);
-              bgTaintedArgs.push(arg);
-            }
-          }
-          if (requestCtx) {
-            stampCacheExec(requestCtx as object);
-          }
+          // Tainted args are NOT stamped here, in contrast to the foreground
+          // miss path below. The args include the live HandlerContext the
+          // still-rendering foreground holds, and INSIDE_CACHE_EXEC is a
+          // 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
+          // 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 {
-            const freshResult = await fn.apply(this, args);
-            bgStopCapture?.();
-            const serialized = await serializeResult(freshResult);
-            if (serialized !== null) {
-              await store.setItem!(cacheKey, serialized, {
-                handles: bgCapture?.data,
-                ttl: profile.ttl,
-                swr: profile.swr,
-                tags: profile.tags,
-              });
-            }
+            // Re-establish the request-context ALS so a "use cache" body that
+            // reads the ambient getRequestContext() (e.g.
+            // getRequestContext().env.ApiKey) resolves during the background
+            // revalidation instead of throwing "called outside of a request
+            // context". runWithRequestContext sets the store for fn's
+            // synchronous kickoff; its async continuations inherit it. The
+            // DERIVED context goes in, so ambient _handleStore reads inside
+            // the body resolve to the isolated store.
+            //
+            // The span opens inside the request ALS and wraps the WHOLE task —
+            // fn kickoff through the store write — so its platform spans nest
+            // under rango.background and a slow or failing setItem is part of
+            // the traced revalidation, not an untraced tail.
+            await runWithRequestContext(bgCtx, () =>
+              observePhase(
+                PHASES.background("use-cache-revalidation"),
+                async () => {
+                  const scoped = runWithCacheTagScope(() =>
+                    runWithCacheExecScope(() => fn.apply(this, args)),
+                  );
+                  const freshResult = await scoped.result;
+                  bgStopCapture?.();
+                  // Merge profile/DSL tags with runtime cacheTag() tags, read
+                  // after awaiting so post-await cacheTag() calls are included.
+                  // Normalize (drops empty profile tags, matching the
+                  // invalidate path) + dedupe.
+                  const freshTags = [
+                    ...new Set(
+                      normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+                    ),
+                  ];
+                  recordRequestTags(freshTags, requestCtx);
+                  const serialized = await serializeResult(freshResult);
+                  if (serialized !== null) {
+                    const encodedHandles = bgCapture?.data
+                      ? await encodeHandles(bgCapture.data)
+                      : undefined;
+                    await store.setItem!(cacheKey, serialized, {
+                      handles: encodedHandles,
+                      ttl: profile.ttl,
+                      swr: profile.swr,
+                      tags: freshTags.length > 0 ? freshTags : undefined,
+                    });
+                  }
+                },
+              ),
+            );
           } catch (bgError) {
             bgStopCapture?.();
-            requestCtx?._reportBackgroundError?.(bgError, "stale-revalidation");
-          } finally {
-            for (const arg of bgTaintedArgs) {
-              unstampCacheExec(arg as object);
-            }
-            if (requestCtx) {
-              unstampCacheExec(requestCtx as object);
-            }
-            // Restore original handle store
-            if (originalHandleStore && requestCtx) {
-              requestCtx._handleStore = originalHandleStore;
-            }
+            // Pass requestCtx explicitly: this runs in a detached background
+            // task where the ALS context is gone, so onError can only fire if
+            // we hand it the context captured up front.
+            reportCacheError(
+              bgError,
+              "stale-revalidation",
+              "[use cache] background revalidation failed",
+              requestCtx,
+            );
           }
+          // No finally: nothing shared was mutated — the derived context and
+          // its handle store are garbage after the task settles.
         });
         return result;
-      } catch {
-        // Deserialization of stale value failed, fall through
+      } catch (error) {
+        // Stale value is corrupt/partial; report and fall through to a fresh
+        // execution, which overwrites the faulty entry under the same key.
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" stale-hit`,
+        );
+      }
+    }
+
+    // Cache miss.
+    //
+    // In-flight dedup: if a concurrent call for this key is already executing,
+    // await its envelope and serve it as a synthetic hit rather than re-running
+    // the function. Each follower deserializes its OWN copy, replays handles
+    // against its OWN handle store (gated on ITS hasTaintedArgs), and records
+    // tags into its OWN request — no deserialized result is shared across
+    // requests. The store write stays exactly once (the leader's).
+    const existing = inFlightExecutions.get(cacheKey);
+    if (existing) {
+      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: raced.serialized,
+            handles: raced.handles,
+            tags: raced.tags,
+            shouldRevalidate: false,
+          });
+        } catch (error) {
+          reportCacheError(
+            error,
+            "cache-corrupt",
+            `[use cache] "${id}" inflight-hit`,
+          );
+          // Fall through to a fresh execution below.
+        }
       }
+      // raced === undefined: leader rejected; its map entry is already
+      // cleared, so fall through to a fresh run.
     }
 
-    // Cache miss: execute, serialize, store
+    // This call becomes the leader. Register a deferred envelope so concurrent
+    // callers dedup onto it; it is resolved/rejected exactly once below (or on a
+    // function throw). clearSelf only deletes the map slot if it still holds
+    // THIS promise, so a fall-through retry (rare rejected-leader path) can't
+    // evict a newer leader's entry.
+    let resolveEnvelope!: (env: CacheEnvelope) => void;
+    let rejectEnvelope!: (err: unknown) => void;
+    const envelopePromise = new Promise<CacheEnvelope>((res, rej) => {
+      resolveEnvelope = res;
+      rejectEnvelope = rej;
+    });
+    // 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, {
+      promise: envelopePromise,
+      registeredAt: Date.now(),
+    });
+    const clearSelf = (): void => {
+      if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
+        inFlightExecutions.delete(cacheKey);
+      }
+    };
+
+    // execute, serialize, store
     const handleStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
     let capture: HandleCapture | undefined;
     let stopCapture: (() => void) | undefined;
@@ -278,6 +682,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // inside the cached function body (those side effects are lost on hit).
     // Uses ref-counted stamp/unstamp so overlapping executions
     // sharing the same ctx don't clear each other's guards.
+    //
+    // 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)) {
@@ -285,47 +697,84 @@ 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 {
-      result = await 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
+      // they retry fresh, then propagate to this caller.
+      clearSelf();
+      rejectEnvelope(execError);
+      throw execError;
     } finally {
       // Decrement ref count; symbol is deleted when it reaches zero
       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?.();
     }
 
-    // Serialize and store — fully non-blocking when waitUntil is available.
-    // The response does not need to wait for serialization or the store write.
-    const cacheWrite = async () => {
+    // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
+    // after awaiting result so post-await cacheTag() calls are included.
+    // Normalize (drops empty profile tags, matching the invalidate path) + dedupe.
+    const allTags = [
+      ...new Set(normalizeTags([...(profile.tags ?? []), ...scoped!.tags])),
+    ];
+    recordRequestTags(allTags, requestCtx);
+
+    // Serialize + encode handles ONCE, resolve the in-flight envelope so any
+    // concurrent followers can serve a synthetic hit, then persist to the store.
+    // Fully non-blocking when waitUntil is available — the leader's response
+    // waits on neither serialization nor the store write.
+    const finalizeAndWrite = async (): Promise<void> => {
+      let serialized: string | null;
+      let encodedHandles: string | undefined;
       try {
-        const serialized = await serializeResult(result);
-        if (serialized !== null) {
-          await store.setItem!(cacheKey, serialized, {
-            handles: capture?.data,
-            ttl: profile.ttl,
-            swr: profile.swr,
-            tags: profile.tags,
-          });
-        }
+        serialized = await serializeResult(result);
+        encodedHandles = capture?.data
+          ? await encodeHandles(capture.data)
+          : undefined;
+      } catch (buildError) {
+        // Serialize/handle-encode failed: no envelope for followers (they run
+        // fresh) and nothing to write.
+        clearSelf();
+        rejectEnvelope(buildError);
+        requestCtx?._reportBackgroundError?.(buildError, "cache-write");
+        return;
+      }
+      clearSelf();
+      if (serialized === null) {
+        // Non-serializable result: no store write (matches the prior silent
+        // skip); reject so any waiter falls through to a fresh execution.
+        rejectEnvelope(
+          new Error(
+            `[use cache] "${id}" result is not serializable; not cached`,
+          ),
+        );
+        return;
+      }
+      // Hand followers the envelope before the store write so a slow/failed
+      // write never stalls them.
+      resolveEnvelope({ serialized, tags: allTags, handles: encodedHandles });
+      try {
+        await store.setItem!(cacheKey, serialized, {
+          handles: encodedHandles,
+          ttl: profile.ttl,
+          swr: profile.swr,
+          tags: allTags.length > 0 ? allTags : undefined,
+        });
       } catch (writeError) {
         requestCtx?._reportBackgroundError?.(writeError, "cache-write");
       }
     };
 
-    await runBackground(requestCtx, cacheWrite, true);
+    await runBackground(requestCtx, finalizeAndWrite, true);
 
     return result;
   };