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

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

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

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

@@ -1428,7 +1428,7 @@ export function createAppRscHandler<TRoute extends AppRscHandlerRoute>(
     const requestContext = createRequestContext({
       headersContext,
       executionContext,
-      unstableCacheRevalidation: "background",
+      cacheRevalidationMode: "background",
     });
 
     const responsePromise = runWithRequestContext(requestContext, () =>

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

@@ -41,7 +41,12 @@ export function getRegisteredCacheContext(): CacheContextLike | null {
   return getCacheContext?.() ?? null;
 }
 
-export type UnstableCacheRevalidationMode = "foreground" | "background";
+/**
+ * Controls stale function/data-cache reads. Patched fetch response caching has
+ * a separate policy because it owns response streams and refetch timeouts.
+ */
+export type CacheRevalidationMode = "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 +62,7 @@ export type CacheState = {
   pendingRevalidations: Set<Promise<void>>;
   requestScopedCacheLife: CacheLifeConfig | null;
   unstableCacheObservations: Map<string, UnstableCacheObservation>;
-  unstableCacheRevalidation: UnstableCacheRevalidationMode;
+  cacheRevalidationMode: CacheRevalidationMode;
 };
 
 const FALLBACK_KEY = Symbol.for("vinext.cache.fallback");
@@ -74,7 +79,7 @@ const fallbackState = (globalState[FALLBACK_KEY] ??= {
   pendingRevalidations: new Set<Promise<void>>(),
   requestScopedCacheLife: null,
   unstableCacheObservations: new Map<string, UnstableCacheObservation>(),
-  unstableCacheRevalidation: "foreground",
+  cacheRevalidationMode: "foreground",
 } satisfies CacheState) as CacheState;
 
 function getCacheState(): CacheState {
@@ -92,7 +97,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.cacheRevalidationMode = "foreground";
     }, fn);
   }
   const state: CacheState = {
@@ -101,7 +106,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",
+    cacheRevalidationMode: "foreground",
   };
   return cacheAls.run(state, fn);
 }
@@ -245,6 +250,22 @@ export function _peekUnstableCacheObservations(): UnstableCacheObservation[] {
   );
 }
 
-export function shouldServeStaleUnstableCacheEntry(): boolean {
-  return getCacheState().unstableCacheRevalidation === "background";
+export function getCacheRevalidationMode(): CacheRevalidationMode {
+  return getCacheState().cacheRevalidationMode;
+}
+
+/**
+ * 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: CacheRevalidationMode,
+): CacheReadAction {
+  if (cacheState === undefined) return "serve";
+  if (cacheState === "stale") {
+    return mode === "background" ? "serve-and-revalidate" : "revalidate";
+  }
+  return "revalidate";
 }