fix(cache): trust framework admission policy

Author: james-elicx

packages/vinext/src/server/app-rsc-response-finalizer.ts

@@ -13,6 +13,7 @@ import { hasBasePath, stripBasePath } from "../utils/base-path.js";
 import { normalizeDefaultLocalePathname } from "./pages-i18n.js";
 import { sanitizeMethodNotAllowedHeaders } from "./http-error-responses.js";
 import { hasPostConfigLinkHeaders } from "./app-response-header-provenance.js";
+import { captureRouteCacheabilityResponsePolicy } from "vinext/shims/cacheability-classification";
 
 type FinalizeAppRscResponseOptions = {
   basePath: string;
@@ -123,6 +124,11 @@ export async function finalizeAppRscResponse(
   // already applied. Redirects are already skipped above.
   if (!response.headers.has("Cache-Control")) {
     applyCdnResponseHeaders(response.headers, { cacheControl: "" });
+    // This is the adapter's fail-closed provisional policy, not an
+    // application opt-out. Admission may replace it only after the body has
+    // completed and the render has proved reusable. Capture before config
+    // headers run so any later private/no-store override still vetoes.
+    captureRouteCacheabilityResponsePolicy(response.headers);
   }
 
   if (configHeadersAlreadyApplied.has(response)) {

packages/vinext/src/server/cacheability-request.ts

@@ -413,7 +413,7 @@ function hasStrictFinalResponseVeto(response: Response, state: RouteCacheability
     const value = response.headers.get(name);
     if (
       value !== null &&
-      value !== state.initialResponseCachePolicy?.[name] &&
+      value !== state.frameworkResponseCachePolicy?.[name] &&
       isNonCacheableCacheControl(value)
     ) {
       return true;

packages/vinext/src/shims/cacheability-classification.ts

@@ -33,7 +33,7 @@ export type RouteCacheabilityState = {
   completion?: Promise<RouteCacheabilityOutcome>;
   finalResponseVetoReason?: string;
   forcedDynamicReason?: string;
-  initialResponseCachePolicy?: Partial<Record<CacheabilityPolicyHeader, string>>;
+  frameworkResponseCachePolicy?: Partial<Record<CacheabilityPolicyHeader, string>>;
   mode: "admit" | "identity" | "probe";
   outcome?: RouteCacheabilityOutcome;
   route?: {
@@ -71,17 +71,23 @@ export function markRouteCacheabilityFinalResponseUncacheable(reason: string): v
   state.finalResponseVetoReason ??= reason;
 }
 
-/** Record renderer-owned policy so admission can identify policy added later. */
+/** Record framework-owned policy so admission can identify policy added later. */
 export function captureRouteCacheabilityResponsePolicy(headers: Headers): void {
   const state = readRouteCacheabilityState();
-  if (!state || state.mode !== "admit" || state.initialResponseCachePolicy) return;
+  if (!state || state.mode !== "admit") return;
 
   const policy: Partial<Record<CacheabilityPolicyHeader, string>> = {};
   for (const name of CACHEABILITY_POLICY_HEADERS) {
     const value = headers.get(name);
     if (value !== null) policy[name] = value;
   }
-  state.initialResponseCachePolicy = policy;
+  // Framework response shaping has more than one trusted phase. In
+  // particular, the App Page renderer can leave Cache-Control absent before
+  // the outer response finalizer applies the adapter's provisional no-store
+  // default. Keep the latest trusted snapshot; configurable response headers
+  // run after the final capture and remain visible to the strict admission
+  // comparison below.
+  state.frameworkResponseCachePolicy = policy;
 }
 
 /** True only for an authenticated probe that must render the matched App Page. */

tests/app-rsc-response-finalizer.test.ts

@@ -16,6 +16,12 @@ import {
   type CdnResponseHeaders,
 } from "../packages/vinext/src/shims/cdn-cache.js";
 import { createStaticFileSignal } from "../packages/vinext/src/server/request-pipeline.js";
+import { createWorkerCacheabilityAdmissionContext } from "../packages/vinext/src/server/cacheability-request.js";
+import {
+  CACHEABILITY_REQUEST_STATE,
+  type RouteCacheabilityState,
+} from "../packages/vinext/src/shims/cacheability-classification.js";
+import { runWithExecutionContext } from "../packages/vinext/src/shims/request-context.js";
 
 afterEach(() => setCdnCacheAdapter(new DefaultCdnCacheAdapter()));
 
@@ -94,6 +100,55 @@ describe("finalizeAppRscResponse — config header application", () => {
     expect(response.headers.get("x-example-edge-policy")).toBeNull();
   });
 
+  it("records the adapter's provisional policy before config headers run", async () => {
+    const adapter: CdnCacheAdapter = {
+      ownsBackgroundRevalidation: true,
+      async get() {
+        return null;
+      },
+      async set() {},
+      buildResponseHeaders({ cacheControl }): CdnResponseHeaders {
+        return { "Cache-Control": cacheControl || "no-store" };
+      },
+      hasExplicitNonCacheableResponsePolicy(headers) {
+        return headers.get("Cache-Control")?.includes("no-store") === true;
+      },
+      async revalidateTag() {},
+    };
+    setCdnCacheAdapter(adapter);
+    const request = new Request("http://example.com/about", {
+      headers: { Accept: "text/html" },
+    });
+    const executionContext = createWorkerCacheabilityAdmissionContext(
+      { waitUntil() {} },
+      request,
+      null,
+      "build-a",
+      true,
+    );
+
+    await runWithExecutionContext(executionContext, () =>
+      finalizeAppRscResponse(new Response("body"), request, {
+        basePath: "",
+        configHeaders: [
+          {
+            source: "/about",
+            headers: [{ key: "Cache-Control", value: "private, no-store" }],
+          },
+        ],
+        i18nConfig: null,
+        requestContext: makeRequestContext(),
+      }),
+    );
+
+    const state = Reflect.get(
+      executionContext,
+      CACHEABILITY_REQUEST_STATE,
+    ) as RouteCacheabilityState;
+    expect(state.frameworkResponseCachePolicy).toEqual({ "cache-control": "no-store" });
+    expect(state.finalResponseVetoReason).toContain("next.config headers set a non-cacheable");
+  });
+
   it("applies a matching config header to a 200 response", async () => {
     // Behavior: /about page response gets x-added header from next.config.js headers[].
     // Regression: expected null to be "config"

tests/cacheability-admission.test.ts

@@ -126,7 +126,7 @@ describe("single-request cacheability admission", () => {
       cacheable: true,
       cacheControl: "s-maxage=60, stale-while-revalidate=540",
     };
-    state.initialResponseCachePolicy = { "cache-control": "no-store" };
+    state.frameworkResponseCachePolicy = { "cache-control": "no-store" };
 
     const response = await finalizeWorkerCacheabilityResponse(
       new Response("static", { headers: { "Cache-Control": "no-store" } }),
@@ -225,7 +225,7 @@ describe("single-request cacheability admission", () => {
 
   const lateFinalPolicyCases: Array<{
     finalHeaders: Record<string, string>;
-    initialPolicy: NonNullable<RouteCacheabilityState["initialResponseCachePolicy"]>;
+    initialPolicy: NonNullable<RouteCacheabilityState["frameworkResponseCachePolicy"]>;
     name: string;
   }> = [
     {
@@ -262,7 +262,7 @@ describe("single-request cacheability admission", () => {
       );
       const state = cacheabilityState(context);
       state.route = { kind: "app-page", pattern: "/page" };
-      state.initialResponseCachePolicy = testCase.initialPolicy;
+      state.frameworkResponseCachePolicy = testCase.initialPolicy;
       state.outcome = {
         cacheable: true,
         cacheControl: "s-maxage=60, stale-while-revalidate=540",