fix(cache): serve stale use cache entries during refresh

packages/vinext/src/server/app-page-dispatch.ts

@@ -571,7 +571,7 @@ async function runAppPageRevalidationContext<
     currentFetchCacheMode: options.currentFetchCacheMode ?? null,
     currentForceDynamicFetchDefault: options.dynamicConfig === "force-dynamic",
     executionContext: getRequestExecutionContext(),
-    unstableCacheRevalidation: "foreground",
+    functionCacheRevalidationMode: "foreground",
   });
 
   const revalidation = runWithRequestContext(requestContext, async () => {

packages/vinext/src/server/app-route-handler-dispatch.ts

@@ -132,7 +132,7 @@ async function runInRouteHandlerRevalidationContext(
   const requestContext = createRequestContext({
     headersContext,
     executionContext: getRequestExecutionContext(),
-    unstableCacheRevalidation: "foreground",
+    functionCacheRevalidationMode: "foreground",
   });
 
   const revalidation = runWithRequestContext(requestContext, async () => {

packages/vinext/src/server/app-rsc-handler.ts

@@ -1432,7 +1432,14 @@ export function createAppRscHandler<TRoute extends AppRscHandlerRoute>(
     const requestContext = createRequestContext({
       headersContext,
       executionContext,
-      unstableCacheRevalidation: "background",
+      // Ordinary runtime requests serve stale `use cache` data and refresh in
+      // the background. A build/prerender request (VINEXT_PRERENDER=1) instead
+      // bakes the response into a static artifact, so it must await the refresh
+      // in the foreground — otherwise a stale persistent entry would be written
+      // into the generated artifact. Matches the static-generation dispatch
+      // paths, which also force foreground during prerendering.
+      functionCacheRevalidationMode:
+        process.env.VINEXT_PRERENDER === "1" ? "foreground" : "background",
     });
 
     const responsePromise = runWithRequestContext(requestContext, () =>

packages/vinext/src/shims/cache-request-state.ts

@@ -41,7 +41,20 @@ export function getRegisteredCacheContext(): CacheContextLike | null {
   return getCacheContext?.() ?? null;
 }
 
-export type UnstableCacheRevalidationMode = "foreground" | "background";
+/**
+ * Controls stale reads for the function caches ("use cache" and
+ * unstable_cache) only. Patched fetch response caching deliberately keeps its
+ * own `refreshStaleFetchesInForeground` flag (fetch-cache.ts) for now: its
+ * default is fail-open (serve stale, background refetch) across every request
+ * path, while this mode's default is fail-closed, so folding fetch into this
+ * field would need an audit of Pages Router and fallback-scope requests first.
+ * Converging both onto one request-level freshness policy is tracked in
+ * https://github.com/cloudflare/vinext/issues/2685; until then this field is
+ * intentionally named narrowly so it does not read as the authoritative
+ * policy for all persistent caches.
+ */
+export type FunctionCacheRevalidationMode = "foreground" | "background";
+export type CacheReadAction = "serve" | "serve-and-revalidate" | "revalidate";
 export type ActionRevalidationKind = 0 | 1 | 2;
 export type UnstableCacheObservation = Readonly<{
   kind: "unstable_cache";
@@ -57,7 +70,7 @@ export type CacheState = {
   pendingRevalidations: Set<Promise<void>>;
   requestScopedCacheLife: CacheLifeConfig | null;
   unstableCacheObservations: Map<string, UnstableCacheObservation>;
-  unstableCacheRevalidation: UnstableCacheRevalidationMode;
+  functionCacheRevalidationMode: FunctionCacheRevalidationMode;
 };
 
 const FALLBACK_KEY = Symbol.for("vinext.cache.fallback");
@@ -74,7 +87,7 @@ const fallbackState = (globalState[FALLBACK_KEY] ??= {
   pendingRevalidations: new Set<Promise<void>>(),
   requestScopedCacheLife: null,
   unstableCacheObservations: new Map<string, UnstableCacheObservation>(),
-  unstableCacheRevalidation: "foreground",
+  functionCacheRevalidationMode: "foreground",
 } satisfies CacheState) as CacheState;
 
 function getCacheState(): CacheState {
@@ -92,7 +105,7 @@ export function _runWithCacheState<T>(fn: () => T | Promise<T>): T | Promise<T>
       context.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
       context.requestScopedCacheLife = null;
       context.unstableCacheObservations = new Map<string, UnstableCacheObservation>();
-      context.unstableCacheRevalidation = "foreground";
+      context.functionCacheRevalidationMode = "foreground";
     }, fn);
   }
   const state: CacheState = {
@@ -101,7 +114,7 @@ export function _runWithCacheState<T>(fn: () => T | Promise<T>): T | Promise<T>
     pendingRevalidations: new Set<Promise<void>>(),
     requestScopedCacheLife: null,
     unstableCacheObservations: new Map<string, UnstableCacheObservation>(),
-    unstableCacheRevalidation: "foreground",
+    functionCacheRevalidationMode: "foreground",
   };
   return cacheAls.run(state, fn);
 }
@@ -245,6 +258,22 @@ export function _peekUnstableCacheObservations(): UnstableCacheObservation[] {
   );
 }
 
-export function shouldServeStaleUnstableCacheEntry(): boolean {
-  return getCacheState().unstableCacheRevalidation === "background";
+export function getFunctionCacheRevalidationMode(): FunctionCacheRevalidationMode {
+  return getCacheState().functionCacheRevalidationMode;
+}
+
+/**
+ * Decide whether a function/data-cache value can satisfy the current read.
+ * An absent state is a fresh value. Stale values are policy-dependent, while
+ * expired or unrecognized states must be regenerated before use.
+ */
+export function decideCacheRead(
+  cacheState: string | undefined,
+  mode: FunctionCacheRevalidationMode,
+): CacheReadAction {
+  if (cacheState === undefined) return "serve";
+  if (cacheState === "stale") {
+    return mode === "background" ? "serve-and-revalidate" : "revalidate";
+  }
+  return "revalidate";
 }