vinext 1.0.0-beta.8 → 1.0.0

package/dist/server/cache-control.js

@@ -1,4 +1,5 @@
-import { getCdnCacheAdapter } from "../shims/cdn-cache.js";
+import { getCdnCacheAdapter, isNonCacheableCacheControl } from "../shims/cdn-cache.js";
+import { recordRouteCacheabilityCdnTags } from "../shims/cacheability-classification.js";
 //#region src/server/cache-control.ts
 const NEVER_CACHE_CONTROL = "private, no-cache, no-store, max-age=0, must-revalidate";
 const BROWSER_REVALIDATE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
@@ -6,7 +7,6 @@ const STATIC_CACHE_CONTROL = "s-maxage=31536000, stale-while-revalidate";
 const STALE_REVALIDATE_CACHE_CONTROL = "s-maxage=0, stale-while-revalidate";
 const NO_STORE_CACHE_CONTROL = "no-store, must-revalidate";
 const SHARED_CACHE_DIRECTIVE_RE = /(?:^|,)\s*s-maxage\s*=/i;
-const NON_CACHEABLE_DIRECTIVE_RE = /(?:private|no-store|no-cache)/i;
 function shouldUseNextDeployCacheControl() {
 	return process.env.VINEXT_NEXT_DEPLOY_CACHE_CONTROL === "1";
 }
@@ -18,11 +18,52 @@ function isSharedCacheControl(cacheControl) {
 * inspect the provider-specific policy headers they own; the generic fallback
 * only understands the framework-owned `Cache-Control` header.
 */
-function hasExplicitNonCacheableResponsePolicy(headers) {
-	const adapter = getCdnCacheAdapter();
-	if (adapter.hasExplicitNonCacheableResponsePolicy) return adapter.hasExplicitNonCacheableResponsePolicy(headers);
+function hasExplicitNonCacheableResponsePolicy(headers, baseline) {
+	const policy = getCdnCacheAdapter().responsePolicy;
+	if (policy) return policy.hasExplicitNonCacheablePolicy(headers, baseline);
 	const cacheControl = headers.get("Cache-Control");
-	return Boolean(cacheControl && NON_CACHEABLE_DIRECTIVE_RE.test(cacheControl));
+	return Boolean(cacheControl && cacheControl !== baseline?.get("Cache-Control") && isNonCacheableCacheControl(cacheControl));
+}
+/** Whether a response header controls core or the active CDN adapter. */
+function isCdnResponsePolicyHeader(name) {
+	return name.toLowerCase() === "cache-control" || getCdnCacheAdapter().responsePolicy?.isHeader(name) === true;
+}
+/** Whether a response declares any core- or adapter-owned cache policy. */
+function hasCdnResponsePolicy(headers) {
+	return [...headers.keys()].some(isCdnResponsePolicyHeader);
+}
+/** Read the effective shared-cache policy without interpreting provider headers in core. */
+function readCdnResponseCacheControl(headers) {
+	if (!headers) return null;
+	const policy = getCdnCacheAdapter().responsePolicy;
+	return policy ? policy.readCacheControl(headers) : headers.get("Cache-Control");
+}
+/** Name the lowercased policy header whose value `readCdnResponseCacheControl` read. */
+function readCdnResponsePolicyHeaderName(headers) {
+	const policy = getCdnCacheAdapter().responsePolicy;
+	if (!policy) return headers.has("Cache-Control") ? "cache-control" : null;
+	return policy.readCacheControlHeaderName?.(headers)?.toLowerCase() ?? null;
+}
+/** Ask the active adapter whether one policy header explicitly disables storage. */
+function isNonCacheableCdnResponsePolicy(name, value) {
+	if (name.toLowerCase() === "cache-control") return isNonCacheableCacheControl(value);
+	return hasExplicitNonCacheableResponsePolicy(new Headers({ [name]: value }));
+}
+/** Capture only cache-policy provenance from an outer composition stage. */
+function captureCdnResponsePolicyHeaders(headers) {
+	const policy = new Headers();
+	for (const [name, value] of headers) if (isCdnResponsePolicyHeader(name)) policy.set(name, value);
+	return policy;
+}
+/** Capture policy values that were added above an already-transported baseline. */
+function captureCdnResponsePolicyOverrides(headers, baseline) {
+	const overrides = captureCdnResponsePolicyHeaders(headers);
+	for (const [name, value] of overrides) if (baseline.get(name) === value) overrides.delete(name);
+	return overrides;
+}
+/** Delegate provider-specific request routing validation to the CDN adapter. */
+async function validateCdnRequest(request) {
+	return await getCdnCacheAdapter().validateRequest?.(request) ?? null;
 }
 /**
 * Route a cacheable response's headers through the active CDN cache adapter and
@@ -35,6 +76,7 @@ function hasExplicitNonCacheableResponsePolicy(headers) {
 * owns before applying that map.
 */
 function applyCdnResponseHeaders(headers, input) {
+	recordRouteCacheabilityCdnTags(input.tags);
 	headers.delete("Cache-Control");
 	const useNextDeployPolicy = shouldUseNextDeployCacheControl() && isSharedCacheControl(input.cacheControl);
 	const map = getCdnCacheAdapter().buildResponseHeaders(useNextDeployPolicy ? {
@@ -52,6 +94,61 @@ function applyCdnResponseHeaders(headers, input) {
 	if (useNextDeployPolicy) headers.set("Cache-Control", BROWSER_REVALIDATE_CACHE_CONTROL);
 }
 /**
+* Reconcile request-stage policy composed above a reusable response artifact.
+* A newly applied private policy must clear any cacheable provider headers that
+* belonged to the inner artifact before the final response leaves the gateway.
+* `outerPolicyHeaders` contains only policy set by the uncached request stage,
+* so an identical inner value cannot hide explicit outer provenance.
+*/
+function reconcileCdnResponseHeadersAfterOuterPolicy(headers, outerPolicyHeaders) {
+	if (headers.has("set-cookie")) {
+		applyCdnResponseHeaders(headers, { cacheControl: NO_STORE_CACHE_CONTROL });
+		return;
+	}
+	const cacheControl = outerPolicyHeaders.get("cache-control");
+	if (cacheControl !== null) {
+		applyCdnResponseHeaders(headers, { cacheControl });
+		for (const [name, value] of outerPolicyHeaders) {
+			if (name === "cache-control") continue;
+			if (isCdnResponsePolicyHeader(name)) headers.set(name, value);
+		}
+		return;
+	}
+	for (const [name, value] of outerPolicyHeaders) if (isCdnResponsePolicyHeader(name) && isNonCacheableCdnResponsePolicy(name, value)) {
+		applyCdnResponseHeaders(headers, { cacheControl: NO_STORE_CACHE_CONTROL });
+		return;
+	}
+	if (hasExplicitNonCacheableResponsePolicy(outerPolicyHeaders)) applyCdnResponseHeaders(headers, { cacheControl: NO_STORE_CACHE_CONTROL });
+}
+/** Apply adapter-owned build identity to an HTML or RSC page response. */
+function applyCdnResponseIdentityHeaders(response, request) {
+	const accept = request.headers.get("Accept")?.toLowerCase() ?? "";
+	const isPagesDataRequest = /(?:^|\/)_next\/data\/[^/]+\/.+\.json$/.test(new URL(request.url).pathname);
+	if (request.headers.get("RSC") !== "1" && !accept.includes("text/html") && !isPagesDataRequest) return response;
+	return applyCdnResponseBuildIdentityHeaders(response);
+}
+/** Apply adapter-owned build identity to an already-classified response. */
+function applyCdnResponseBuildIdentityHeaders(response) {
+	const map = getCdnCacheAdapter().buildResponseIdentityHeaders?.();
+	if (!map || Object.keys(map).length === 0) return response;
+	try {
+		applyResponseHeaderMap(response.headers, map);
+		return response;
+	} catch {
+		const headers = new Headers(response.headers);
+		applyResponseHeaderMap(headers, map);
+		return new Response(response.body, {
+			headers,
+			status: response.status,
+			statusText: response.statusText
+		});
+	}
+}
+function applyResponseHeaderMap(headers, map) {
+	for (const [name, value] of Object.entries(map)) if (value === null) headers.delete(name);
+	else headers.set(name, value);
+}
+/**
 * Matches Next.js's `getCacheControlHeader` stale window semantics while
 * preserving vinext's legacy unbounded SWR header when no expire ceiling is
 * available yet.
@@ -78,4 +175,4 @@ function buildCachedRevalidateCacheControl(cacheState, revalidateSeconds, expire
 	return buildRevalidateCacheControl(revalidateSeconds, expireSeconds);
 }
 //#endregion
-export { BROWSER_REVALIDATE_CACHE_CONTROL, NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, applyCdnResponseHeaders, buildCachedRevalidateCacheControl, buildRevalidateCacheControl, hasExplicitNonCacheableResponsePolicy, shouldUseNextDeployCacheControl };
+export { BROWSER_REVALIDATE_CACHE_CONTROL, NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, applyCdnResponseBuildIdentityHeaders, applyCdnResponseHeaders, applyCdnResponseIdentityHeaders, buildCachedRevalidateCacheControl, buildRevalidateCacheControl, captureCdnResponsePolicyHeaders, captureCdnResponsePolicyOverrides, hasCdnResponsePolicy, hasExplicitNonCacheableResponsePolicy, isCdnResponsePolicyHeader, isNonCacheableCacheControl, isNonCacheableCdnResponsePolicy, readCdnResponseCacheControl, readCdnResponsePolicyHeaderName, reconcileCdnResponseHeadersAfterOuterPolicy, shouldUseNextDeployCacheControl, validateCdnRequest };

package/dist/server/cache-headers.d.ts

@@ -1,6 +1,5 @@
 //#region src/server/cache-headers.d.ts
 type VinextCacheState = "HIT" | "MISS" | "STALE" | "STATIC";
-declare function setCacheStateHeaders(headers: Headers, cacheState: VinextCacheState): void;
-declare function buildCacheStateHeaders(cacheState: VinextCacheState): Record<string, string>;
-//#endregion
-export { buildCacheStateHeaders, setCacheStateHeaders };
+export declare function setCacheStateHeaders(headers: Headers, cacheState: VinextCacheState): void;
+export declare function buildCacheStateHeaders(cacheState: VinextCacheState): Record<string, string>;
+//#endregion

package/dist/server/cache-proof.d.ts

@@ -1,23 +1,23 @@
 import { AppRouteSemanticIds } from "../routing/app-route-graph.js";
 import { ArtifactCompatibilityEnvelope, ArtifactCompatibilityEvaluationOptions } from "./artifact-compatibility.js";
 //#region src/server/cache-proof.d.ts
-declare const CACHE_PROOF_MODEL_SCHEMA_VERSION = 1;
-type CacheProofModelSchemaVersion = 1;
-type CacheProofRejectionCode = "CP_CACHE_ENTRY_PROOF_MISSING" | "CP_MODEL_DISABLED" | "CP_ARTIFACT_COMPATIBILITY_INCOMPATIBLE" | "CP_ARTIFACT_COMPATIBILITY_UNKNOWN" | "CP_DIMENSION_COUNT_EXCEEDED" | "CP_DIMENSION_NAME_MISSING" | "CP_DIMENSION_NAME_TOO_LONG" | "CP_DIMENSION_VALUE_COUNT_EXCEEDED" | "CP_DIMENSION_VALUE_TOO_LONG" | "CP_DIMENSION_VALUES_MISSING" | "CP_ENCODED_VARIANT_TOO_LONG" | "CP_INVALID_VARIANT_BUDGET" | "CP_ROUTE_VARIANT_BUDGET_ROUTE_MISMATCH" | "CP_ROUTE_VARIANT_CEILING_EXCEEDED" | "CP_UNSAFE_PUBLIC_DIMENSION" | "CP_BOUNDARY_OUTCOME_MISMATCH" | "CP_BOUNDARY_OUTCOME_UNKNOWN" | "CP_PRIVATE_DYNAMIC_DOWNGRADE" | "CP_STATIC_LAYOUT_CANDIDATE_OUTPUT_KIND" | "CP_STATIC_LAYOUT_CURRENT_OUTPUT_KIND" | "CP_STATIC_LAYOUT_ID_MISMATCH" | "CP_STATIC_LAYOUT_OBSERVATION_OUTPUT_KIND" | "CP_STATIC_LAYOUT_OBSERVATION_OUTPUT_MISMATCH" | "CP_STATIC_LAYOUT_PRIVATE_DYNAMIC_DOWNGRADE" | "CP_STATIC_LAYOUT_REQUEST_API_OBSERVED" | "CP_STATIC_LAYOUT_REQUEST_API_UNKNOWN" | "CP_STATIC_LAYOUT_ROOT_BOUNDARY_MISMATCH" | "CP_STATIC_LAYOUT_ROOT_BOUNDARY_UNKNOWN" | "CP_STATIC_LAYOUT_VARIANT_DIMENSION_UNPROVEN";
-type CacheProofAcceptanceCode = "CP_STATIC_LAYOUT_REUSE_PROVEN";
-type CacheProofTraceCode = CacheProofAcceptanceCode | CacheProofRejectionCode;
-type CacheProofTraceFieldValue = string | number | boolean | null | readonly string[];
-type CacheProofTraceFields = Readonly<Record<string, CacheProofTraceFieldValue>>;
-type CacheProofBreakerFallbackMode = "renderFresh" | "privateUncacheable";
-type CacheProofFallbackScope = "affectedOutput" | "route";
-type CacheProofBreakerFallback = Readonly<{
+export declare const CACHE_PROOF_MODEL_SCHEMA_VERSION = 1;
+export type CacheProofModelSchemaVersion = 1;
+export type CacheProofRejectionCode = "CP_CACHE_ENTRY_PROOF_MISSING" | "CP_MODEL_DISABLED" | "CP_ARTIFACT_COMPATIBILITY_INCOMPATIBLE" | "CP_ARTIFACT_COMPATIBILITY_UNKNOWN" | "CP_DIMENSION_COUNT_EXCEEDED" | "CP_DIMENSION_NAME_MISSING" | "CP_DIMENSION_NAME_TOO_LONG" | "CP_DIMENSION_VALUE_COUNT_EXCEEDED" | "CP_DIMENSION_VALUE_TOO_LONG" | "CP_DIMENSION_VALUES_MISSING" | "CP_ENCODED_VARIANT_TOO_LONG" | "CP_INVALID_VARIANT_BUDGET" | "CP_ROUTE_VARIANT_BUDGET_ROUTE_MISMATCH" | "CP_ROUTE_VARIANT_CEILING_EXCEEDED" | "CP_UNSAFE_PUBLIC_DIMENSION" | "CP_BOUNDARY_OUTCOME_MISMATCH" | "CP_BOUNDARY_OUTCOME_UNKNOWN" | "CP_PRIVATE_DYNAMIC_DOWNGRADE" | "CP_STATIC_LAYOUT_CANDIDATE_OUTPUT_KIND" | "CP_STATIC_LAYOUT_CURRENT_OUTPUT_KIND" | "CP_STATIC_LAYOUT_ID_MISMATCH" | "CP_STATIC_LAYOUT_OBSERVATION_OUTPUT_KIND" | "CP_STATIC_LAYOUT_OBSERVATION_OUTPUT_MISMATCH" | "CP_STATIC_LAYOUT_PRIVATE_DYNAMIC_DOWNGRADE" | "CP_STATIC_LAYOUT_REQUEST_API_OBSERVED" | "CP_STATIC_LAYOUT_REQUEST_API_UNKNOWN" | "CP_STATIC_LAYOUT_ROOT_BOUNDARY_MISMATCH" | "CP_STATIC_LAYOUT_ROOT_BOUNDARY_UNKNOWN" | "CP_STATIC_LAYOUT_VARIANT_DIMENSION_UNPROVEN";
+export type CacheProofAcceptanceCode = "CP_STATIC_LAYOUT_REUSE_PROVEN";
+export type CacheProofTraceCode = CacheProofAcceptanceCode | CacheProofRejectionCode;
+export type CacheProofTraceFieldValue = string | number | boolean | null | readonly string[];
+export type CacheProofTraceFields = Readonly<Record<string, CacheProofTraceFieldValue>>;
+export type CacheProofBreakerFallbackMode = "renderFresh" | "privateUncacheable";
+export type CacheProofFallbackScope = "affectedOutput" | "route";
+export type CacheProofBreakerFallback = Readonly<{
   kind: "breakerFallback";
   code: CacheProofRejectionCode;
   mode: CacheProofBreakerFallbackMode;
   scope: CacheProofFallbackScope;
   fields: CacheProofTraceFields;
 }>;
-type CacheVariantBudget = Readonly<{
+export type CacheVariantBudget = Readonly<{
   maxDimensionCount: number;
   maxDimensionNameLength: number;
   maxDimensionValueLength: number;
@@ -25,7 +25,7 @@ type CacheVariantBudget = Readonly<{
   maxValuesPerDimension: number;
   maxVariantsPerRoute: number;
 }>;
-declare const DEFAULT_CACHE_VARIANT_BUDGET: {
+export declare const DEFAULT_CACHE_VARIANT_BUDGET: {
   maxDimensionCount: number;
   maxDimensionNameLength: number;
   maxDimensionValueLength: number;
@@ -33,15 +33,15 @@ declare const DEFAULT_CACHE_VARIANT_BUDGET: {
   maxValuesPerDimension: number;
   maxVariantsPerRoute: number;
 };
-type CacheVariantDimensionSource = "auth" | "cookie" | "custom" | "draft-mode" | "header" | "interception" | "mounted-slots" | "params" | "route" | "search" | "session";
-type CacheVariantDimensionPrivacy = "internal" | "private" | "public";
-type CacheVariantDimensionInput = Readonly<{
+export type CacheVariantDimensionSource = "auth" | "cookie" | "custom" | "draft-mode" | "header" | "interception" | "mounted-slots" | "params" | "route" | "search" | "session";
+export type CacheVariantDimensionPrivacy = "internal" | "private" | "public";
+export type CacheVariantDimensionInput = Readonly<{
   name: string;
   privacy: CacheVariantDimensionPrivacy;
   source: CacheVariantDimensionSource;
   values: readonly string[];
 }>;
-type CacheVariantDimension = Readonly<{
+export type CacheVariantDimension = Readonly<{
   encoded: string;
   name: string;
   privacy: CacheVariantDimensionPrivacy;
@@ -49,7 +49,7 @@ type CacheVariantDimension = Readonly<{
   valueCount: number;
   valueHashes: readonly string[];
 }>;
-type CacheProofOutputScope = Readonly<{
+export type CacheProofOutputScope = Readonly<{
   kind: "app-html";
   renderEpoch: string | null;
   rootBoundaryId: string | null;
@@ -85,10 +85,10 @@ type CacheProofOutputScope = Readonly<{
   routeId: string;
   templateId: string;
 }>;
-type StaticLayoutCacheProofOutputScope = Extract<CacheProofOutputScope, {
+export type StaticLayoutCacheProofOutputScope = Extract<CacheProofOutputScope, {
   kind: "layout";
 }>;
-type CacheVariant = Readonly<{
+export type CacheVariant = Readonly<{
   budget: CacheVariantBudget;
   cacheKey: string;
   dimensions: readonly CacheVariantDimension[];
@@ -96,23 +96,23 @@ type CacheVariant = Readonly<{
   output: CacheProofOutputScope;
   schemaVersion: CacheProofModelSchemaVersion;
 }>;
-type BuildCacheVariantInput = Readonly<{
+export type BuildCacheVariantInput = Readonly<{
   budget: CacheVariantBudget;
   dimensions: readonly CacheVariantDimensionInput[];
   output: CacheProofOutputScope;
 }>;
-type BuildCacheVariantResult = Readonly<{
+export type BuildCacheVariantResult = Readonly<{
   kind: "variant";
   variant: CacheVariant;
 }> | Readonly<{
   kind: "breakerFallback";
   fallback: CacheProofBreakerFallback;
 }>;
-type CacheVariantRouteBudget = Readonly<{
+export type CacheVariantRouteBudget = Readonly<{
   routeId: string;
   variantCacheKeys: readonly string[];
 }>;
-type CacheVariantRouteBudgetAdmission = Readonly<{
+export type CacheVariantRouteBudgetAdmission = Readonly<{
   didConsumeRouteVariantBudget: boolean;
   kind: "variant";
   routeBudget: CacheVariantRouteBudget;
@@ -122,14 +122,14 @@ type CacheVariantRouteBudgetAdmission = Readonly<{
   kind: "breakerFallback";
   routeBudget: CacheVariantRouteBudget | null;
 }>;
-type BuildCacheVariantWithRouteBudgetInput = BuildCacheVariantInput & Readonly<{
+export type BuildCacheVariantWithRouteBudgetInput = BuildCacheVariantInput & Readonly<{
   routeBudget: CacheVariantRouteBudget | null;
 }>;
-type BuildCacheVariantWithRouteBudgetResult = CacheVariantRouteBudgetAdmission;
-type AppRouteCacheProofGraphScopeInput = Readonly<{
+export type BuildCacheVariantWithRouteBudgetResult = CacheVariantRouteBudgetAdmission;
+export type AppRouteCacheProofGraphScopeInput = Readonly<{
   ids: AppRouteSemanticIds;
 }>;
-type AppRouteCacheProofGraphScope = Readonly<{
+export type AppRouteCacheProofGraphScope = Readonly<{
   layoutIds: readonly string[];
   pageId: string | null;
   routeHandlerId: string | null;
@@ -137,7 +137,7 @@ type AppRouteCacheProofGraphScope = Readonly<{
   slotIds: readonly string[];
   templateIds: readonly string[];
 }>;
-type BoundaryOutcome = Readonly<{
+export type BoundaryOutcome = Readonly<{
   kind: "error";
   digest?: string;
 }> | Readonly<{
@@ -158,7 +158,7 @@ type BoundaryOutcome = Readonly<{
 }> | Readonly<{
   kind: "unknown";
 }>;
-type BoundaryOutcomeCompatibility = Readonly<{
+export type BoundaryOutcomeCompatibility = Readonly<{
   kind: "compatible";
   outcome: BoundaryOutcome;
   reason: "CP_BOUNDARY_OUTCOME_MATCH";
@@ -168,17 +168,17 @@ type BoundaryOutcomeCompatibility = Readonly<{
   fallback: CacheProofBreakerFallback;
   kind: "incompatible";
 }>;
-type RenderObservationCompleteness = "complete" | "partial" | "unknown";
-type RenderCacheability = "private" | "public" | "uncacheable" | "unknown";
-type RenderRequestApiKind = "connection" | "cookies" | "draftMode" | "headers" | "params" | "searchParams";
-type RenderRequestApiStatus = "notObserved" | "observed" | "unknown";
-declare const ALL_RENDER_REQUEST_API_KINDS: readonly RenderRequestApiKind[];
-type RenderRequestApiObservation = Readonly<{
+export type RenderObservationCompleteness = "complete" | "partial" | "unknown";
+export type RenderCacheability = "private" | "public" | "uncacheable" | "unknown";
+export type RenderRequestApiKind = "connection" | "cookies" | "draftMode" | "headers" | "params" | "searchParams";
+export type RenderRequestApiStatus = "notObserved" | "observed" | "unknown";
+export declare const ALL_RENDER_REQUEST_API_KINDS: readonly RenderRequestApiKind[];
+export type RenderRequestApiObservation = Readonly<{
   kind: RenderRequestApiKind;
   status: RenderRequestApiStatus;
 }>;
-type CacheProofDowngradeTarget = "freshRender" | "private" | "privateUncacheable" | "public" | "publicVariant";
-type CacheProofDowngradeReason = Readonly<{
+export type CacheProofDowngradeTarget = "freshRender" | "private" | "privateUncacheable" | "public" | "publicVariant";
+export type CacheProofDowngradeReason = Readonly<{
   code: "CP_DOWNGRADE_CACHEABILITY_PRIVATE";
   target: "private";
 }> | Readonly<{
@@ -221,20 +221,20 @@ type CacheProofDowngradeReason = Readonly<{
   requestApi: RenderRequestApiKind;
   target: "freshRender";
 }>;
-type CacheProofDowngradeClassification = Readonly<{
+export type CacheProofDowngradeClassification = Readonly<{
   fallback: CacheProofBreakerFallback | null;
   isPublicCacheCandidate: boolean;
   reasons: readonly CacheProofDowngradeReason[];
   target: CacheProofDowngradeTarget;
 }>;
-type ClassifyRenderObservationDowngradeInput = Readonly<{
+export type ClassifyRenderObservationDowngradeInput = Readonly<{
   cacheability: RenderCacheability;
   completeness: RenderObservationCompleteness;
   dynamicFetches: readonly string[];
   requestApis: readonly RenderRequestApiObservation[];
 }>;
-type ClassifyCacheVariantDimensionDowngradeInput = Pick<CacheVariantDimensionInput, "source">;
-type RenderObservation = Readonly<{
+export type ClassifyCacheVariantDimensionDowngradeInput = Pick<CacheVariantDimensionInput, "source">;
+export type RenderObservation = Readonly<{
   boundaryOutcome: BoundaryOutcome;
   cacheTags: readonly string[];
   cacheability: RenderCacheability;
@@ -246,7 +246,7 @@ type RenderObservation = Readonly<{
   requestApis: readonly RenderRequestApiObservation[];
   schemaVersion: CacheProofModelSchemaVersion;
 }>;
-type StaticLayoutReuseProof = Readonly<{
+export type StaticLayoutReuseProof = Readonly<{
   authorizesRuntimeReuse: true;
   candidateOutput: StaticLayoutCacheProofOutputScope;
   code: "CP_STATIC_LAYOUT_REUSE_PROVEN";
@@ -257,28 +257,28 @@ type StaticLayoutReuseProof = Readonly<{
   reuseClass: "static-layout";
   variant: CacheVariant;
 }>;
-type StaticLayoutArtifactReuseProof = StaticLayoutReuseProof & Readonly<{
+export type StaticLayoutArtifactReuseProof = StaticLayoutReuseProof & Readonly<{
   candidateArtifactCompatibility: ArtifactCompatibilityEnvelope;
 }>;
-type BuildStaticLayoutReuseProofInput = Readonly<{
+export type BuildStaticLayoutReuseProofInput = Readonly<{
   candidateObservation: RenderObservation;
   candidateVariant: CacheVariant;
   currentOutput: CacheProofOutputScope;
 }>;
-type BuildStaticLayoutReuseProofResult = Readonly<{
+export type BuildStaticLayoutReuseProofResult = Readonly<{
   kind: "proof";
   proof: StaticLayoutReuseProof;
 }> | Readonly<{
   kind: "rejected";
   fallback: CacheProofBreakerFallback;
 }>;
-type CacheProofHotPathMetric = Readonly<{
+export type CacheProofHotPathMetric = Readonly<{
   code: CacheProofTraceCode;
   fields: CacheProofTraceFields;
   name: "vinext.cache.static_layout_artifact_reuse";
   outcome: "fallback" | "reuse";
 }>;
-type StaticLayoutArtifactReuseDecision = Readonly<{
+export type StaticLayoutArtifactReuseDecision = Readonly<{
   canReuse: true;
   kind: "reuse";
   metric: CacheProofHotPathMetric;
@@ -289,7 +289,7 @@ type StaticLayoutArtifactReuseDecision = Readonly<{
   kind: "fallback";
   metric: CacheProofHotPathMetric;
 }>;
-type CacheEntryReuseDecision = Readonly<{
+export type CacheEntryReuseDecision = Readonly<{
   canReuse: true;
   code: CacheProofAcceptanceCode;
   kind: "reuse";
@@ -301,18 +301,18 @@ type CacheEntryReuseDecision = Readonly<{
   mode: CacheProofBreakerFallbackMode;
   scope: CacheProofFallbackScope;
 }>;
-type CacheEntryReuseProof = Readonly<{
+export type CacheEntryReuseProof = Readonly<{
   decision: CacheEntryReuseDecision | null;
   kind: "runtime-cache-entry";
 }>;
-type CreateStaticLayoutArtifactReuseDecisionInput = Readonly<{
+export type CreateStaticLayoutArtifactReuseDecisionInput = Readonly<{
   candidateArtifactCompatibility: ArtifactCompatibilityEnvelope;
   candidateObservation: RenderObservation;
   candidateVariant: BuildCacheVariantWithRouteBudgetResult;
   currentArtifactCompatibility: ArtifactCompatibilityEnvelope;
   currentOutput: CacheProofOutputScope;
 }> & ArtifactCompatibilityEvaluationOptions;
-type BuildRenderObservationInput = Readonly<{
+export type BuildRenderObservationInput = Readonly<{
   boundaryOutcome: BoundaryOutcome;
   cacheTags: readonly string[];
   cacheability: RenderCacheability;
@@ -322,11 +322,11 @@ type BuildRenderObservationInput = Readonly<{
   pathTags: readonly string[];
   requestApis: readonly RenderRequestApiObservation[];
 }>;
-type BuildRenderRequestApiObservationsInput = Readonly<{
+export type BuildRenderRequestApiObservationsInput = Readonly<{
   completeness: RenderObservationCompleteness;
   observed: readonly RenderRequestApiKind[];
 }>;
-type DisabledCacheProofDecision = Readonly<{
+export type DisabledCacheProofDecision = Readonly<{
   canReuse: false;
   fallback: CacheProofBreakerFallback;
   kind: "disabled";
@@ -334,30 +334,35 @@ type DisabledCacheProofDecision = Readonly<{
   staticLayoutProof?: StaticLayoutReuseProof;
   variant: CacheVariant;
 }>;
-type CreateDisabledCacheProofDecisionInput = Readonly<{
+export type CreateDisabledCacheProofDecisionInput = Readonly<{
   observation: RenderObservation;
   staticLayoutProof?: StaticLayoutReuseProof;
   variant: CacheVariant;
 }>;
-declare function createAppRouteCacheProofGraphScope(route: AppRouteCacheProofGraphScopeInput): AppRouteCacheProofGraphScope;
-declare function buildCacheVariant(input: BuildCacheVariantInput): BuildCacheVariantResult;
-declare function enforceCacheVariantRouteBudget(input: {
+export declare function createAppRouteCacheProofGraphScope(route: AppRouteCacheProofGraphScopeInput): AppRouteCacheProofGraphScope;
+export declare function buildCacheVariant(input: BuildCacheVariantInput): BuildCacheVariantResult;
+export declare function enforceCacheVariantRouteBudget(input: {
   routeBudget: CacheVariantRouteBudget | null;
   variant: CacheVariant;
 }): CacheVariantRouteBudgetAdmission;
-declare function buildCacheVariantWithRouteBudget(input: BuildCacheVariantWithRouteBudgetInput): BuildCacheVariantWithRouteBudgetResult;
-declare function buildBoundaryOutcomeCompatibility(input: {
+export declare function buildCacheVariantWithRouteBudget(input: BuildCacheVariantWithRouteBudgetInput): BuildCacheVariantWithRouteBudgetResult;
+export declare function buildBoundaryOutcomeCompatibility(input: {
   candidate: BoundaryOutcome;
   expected: BoundaryOutcome;
 }): BoundaryOutcomeCompatibility;
-declare function classifyCacheVariantDimensionDowngrade(input: ClassifyCacheVariantDimensionDowngradeInput): CacheProofDowngradeReason | null;
-declare function classifyRenderObservationDowngrade(input: ClassifyRenderObservationDowngradeInput): CacheProofDowngradeClassification;
-declare function buildRenderRequestApiObservations(input: BuildRenderRequestApiObservationsInput): RenderRequestApiObservation[];
-declare function buildRenderObservation(input: BuildRenderObservationInput): RenderObservation;
-declare function hasCompleteNegativeRequestApiProof(observation: RenderObservation, requiredApis: readonly RenderRequestApiKind[]): boolean;
-declare function buildStaticLayoutReuseProof(input: BuildStaticLayoutReuseProofInput): BuildStaticLayoutReuseProofResult;
-declare function createStaticLayoutArtifactReuseDecision(input: CreateStaticLayoutArtifactReuseDecisionInput): StaticLayoutArtifactReuseDecision;
-declare function createCacheEntryReuseProof(decision: StaticLayoutArtifactReuseDecision | null): CacheEntryReuseProof;
-declare function createDisabledCacheProofDecision(input: CreateDisabledCacheProofDecisionInput): DisabledCacheProofDecision;
-//#endregion
-export { ALL_RENDER_REQUEST_API_KINDS, AppRouteCacheProofGraphScope, AppRouteCacheProofGraphScopeInput, BoundaryOutcome, BoundaryOutcomeCompatibility, BuildCacheVariantInput, BuildCacheVariantResult, BuildCacheVariantWithRouteBudgetInput, BuildCacheVariantWithRouteBudgetResult, BuildRenderObservationInput, BuildRenderRequestApiObservationsInput, BuildStaticLayoutReuseProofInput, BuildStaticLayoutReuseProofResult, CACHE_PROOF_MODEL_SCHEMA_VERSION, CacheEntryReuseDecision, CacheEntryReuseProof, CacheProofAcceptanceCode, CacheProofBreakerFallback, CacheProofBreakerFallbackMode, CacheProofDowngradeClassification, CacheProofDowngradeReason, CacheProofDowngradeTarget, CacheProofFallbackScope, CacheProofHotPathMetric, CacheProofModelSchemaVersion, CacheProofOutputScope, CacheProofRejectionCode, CacheProofTraceCode, CacheProofTraceFieldValue, CacheProofTraceFields, CacheVariant, CacheVariantBudget, CacheVariantDimension, CacheVariantDimensionInput, CacheVariantDimensionPrivacy, CacheVariantDimensionSource, CacheVariantRouteBudget, CacheVariantRouteBudgetAdmission, ClassifyCacheVariantDimensionDowngradeInput, ClassifyRenderObservationDowngradeInput, CreateDisabledCacheProofDecisionInput, CreateStaticLayoutArtifactReuseDecisionInput, DEFAULT_CACHE_VARIANT_BUDGET, DisabledCacheProofDecision, RenderCacheability, RenderObservation, RenderObservationCompleteness, RenderRequestApiKind, RenderRequestApiObservation, RenderRequestApiStatus, StaticLayoutArtifactReuseDecision, StaticLayoutArtifactReuseProof, StaticLayoutCacheProofOutputScope, StaticLayoutReuseProof, buildBoundaryOutcomeCompatibility, buildCacheVariant, buildCacheVariantWithRouteBudget, buildRenderObservation, buildRenderRequestApiObservations, buildStaticLayoutReuseProof, classifyCacheVariantDimensionDowngrade, classifyRenderObservationDowngrade, createAppRouteCacheProofGraphScope, createCacheEntryReuseProof, createDisabledCacheProofDecision, createStaticLayoutArtifactReuseDecision, enforceCacheVariantRouteBudget, hasCompleteNegativeRequestApiProof };
+export declare function classifyCacheVariantDimensionDowngrade(input: ClassifyCacheVariantDimensionDowngradeInput): CacheProofDowngradeReason | null;
+export declare function classifyRenderObservationDowngrade(input: ClassifyRenderObservationDowngradeInput): CacheProofDowngradeClassification;
+export declare function buildRenderRequestApiObservations(input: BuildRenderRequestApiObservationsInput): RenderRequestApiObservation[];
+export declare function buildRenderObservation(input: BuildRenderObservationInput): RenderObservation;
+export declare function hasCompleteNegativeRequestApiProof(observation: RenderObservation, requiredApis: readonly RenderRequestApiKind[]): boolean;
+/**
+ * Whether a stored App page's render is proven not to have read the request's
+ * query, so one entry may serve every query. Core only writes and reads
+ * entries with this proof.
+ */
+export declare function hasQueryInvariantRenderProof(observation: RenderObservation | undefined): boolean;
+export declare function buildStaticLayoutReuseProof(input: BuildStaticLayoutReuseProofInput): BuildStaticLayoutReuseProofResult;
+export declare function createStaticLayoutArtifactReuseDecision(input: CreateStaticLayoutArtifactReuseDecisionInput): StaticLayoutArtifactReuseDecision;
+export declare function createCacheEntryReuseProof(decision: StaticLayoutArtifactReuseDecision | null): CacheEntryReuseProof;
+export declare function createDisabledCacheProofDecision(input: CreateDisabledCacheProofDecisionInput): DisabledCacheProofDecision;
+//#endregion

package/dist/server/cache-proof.js

@@ -594,6 +594,14 @@ function hasCompleteNegativeRequestApiProof(observation, requiredApis) {
 	for (const api of requiredApis) if (statuses.get(api) !== "notObserved") return false;
 	return true;
 }
+/**
+* Whether a stored App page's render is proven not to have read the request's
+* query, so one entry may serve every query. Core only writes and reads
+* entries with this proof.
+*/
+function hasQueryInvariantRenderProof(observation) {
+	return observation !== void 0 && hasCompleteNegativeRequestApiProof(observation, ["searchParams"]);
+}
 function isStaticLayoutOutputScope(output) {
 	return output.kind === "layout";
 }
@@ -791,4 +799,4 @@ function createDisabledCacheProofDecision(input) {
 	};
 }
 //#endregion
-export { ALL_RENDER_REQUEST_API_KINDS, CACHE_PROOF_MODEL_SCHEMA_VERSION, DEFAULT_CACHE_VARIANT_BUDGET, buildBoundaryOutcomeCompatibility, buildCacheVariant, buildCacheVariantWithRouteBudget, buildRenderObservation, buildRenderRequestApiObservations, buildStaticLayoutReuseProof, classifyCacheVariantDimensionDowngrade, classifyRenderObservationDowngrade, createAppRouteCacheProofGraphScope, createCacheEntryReuseProof, createDisabledCacheProofDecision, createStaticLayoutArtifactReuseDecision, enforceCacheVariantRouteBudget, hasCompleteNegativeRequestApiProof };
+export { ALL_RENDER_REQUEST_API_KINDS, CACHE_PROOF_MODEL_SCHEMA_VERSION, DEFAULT_CACHE_VARIANT_BUDGET, buildBoundaryOutcomeCompatibility, buildCacheVariant, buildCacheVariantWithRouteBudget, buildRenderObservation, buildRenderRequestApiObservations, buildStaticLayoutReuseProof, classifyCacheVariantDimensionDowngrade, classifyRenderObservationDowngrade, createAppRouteCacheProofGraphScope, createCacheEntryReuseProof, createDisabledCacheProofDecision, createStaticLayoutArtifactReuseDecision, enforceCacheVariantRouteBudget, hasCompleteNegativeRequestApiProof, hasQueryInvariantRenderProof };

package/dist/server/cacheability-limits.d.ts

@@ -0,0 +1,8 @@
+//#region src/server/cacheability-limits.d.ts
+/** Maximum completed response retained before CDN admission. */
+export declare const CACHEABILITY_ADMISSION_RESPONSE_BODY_LIMIT: number;
+/** Maximum completed-response capture retained across concurrent isolate requests. */
+export declare const CACHEABILITY_ADMISSION_ISOLATE_BODY_LIMIT: number;
+/** Leave headroom below the deploy-side request timeout for a fail-closed envelope. */
+export declare const CACHEABILITY_PROBE_TIMEOUT_MS = 20000;
+//#endregion

package/dist/server/cacheability-limits.js

@@ -0,0 +1,9 @@
+//#region src/server/cacheability-limits.ts
+/** Maximum completed response retained before CDN admission. */
+const CACHEABILITY_ADMISSION_RESPONSE_BODY_LIMIT = 16777216;
+/** Maximum completed-response capture retained across concurrent isolate requests. */
+const CACHEABILITY_ADMISSION_ISOLATE_BODY_LIMIT = 33554432;
+/** Leave headroom below the deploy-side request timeout for a fail-closed envelope. */
+const CACHEABILITY_PROBE_TIMEOUT_MS = 2e4;
+//#endregion
+export { CACHEABILITY_ADMISSION_ISOLATE_BODY_LIMIT, CACHEABILITY_ADMISSION_RESPONSE_BODY_LIMIT, CACHEABILITY_PROBE_TIMEOUT_MS };

package/dist/server/cacheability-manifest.d.ts

@@ -0,0 +1,68 @@
+//#region src/server/cacheability-manifest.d.ts
+export declare const CACHEABILITY_MANIFEST_MODULE = "__vinext_cacheability_manifest.js";
+/** Request-stage projection of the manifest: the App page routes that can admit a query-free entry. */
+export declare const CACHEABILITY_REQUEST_PROJECTION_MODULE = "__vinext_cacheability_request_projection.js";
+export type CacheabilityRouteKind = "app-page" | "app-route" | "pages-page";
+export type CacheabilityRepresentation = "app-route" | "html" | "pages-data" | "rsc-full" | "rsc-loading-shell";
+export type CacheabilityManifestRouteState = "static-candidate" | "runtime-check";
+export type CacheabilityManifestRoute = {
+  kind: CacheabilityRouteKind;
+  pattern: string;
+  /** Default completed-render policy for authorized non-static representations. */
+  state: CacheabilityManifestRouteState;
+  /** Permit completed-render admission for paths not observed during probing. */
+  allowUnknown?: boolean;
+  /** Next.js fallback classification for paths not observed during probing. */
+  unknownState?: CacheabilityManifestRouteState;
+  /** Common prefix omitted from every exact path below. */
+  pathPrefix?: string;
+  /** Runtime-checked representation authorized for every path in a pattern. */
+  runtimeRepresentation?: CacheabilityRepresentation;
+  /** Static representation for a literal route that needs no exact path list. */
+  staticRepresentation?: CacheabilityRepresentation;
+  /** Exact dynamic paths observed in a mixed or pattern-dynamic route. */
+  runtimePaths?: string[];
+  /** Exact paths runtime-checked only in the listed representation. */
+  runtimeRepresentationPaths?: Partial<Record<CacheabilityRepresentation, string[]>>;
+  /** Exact paths statically certified per representation. A path may appear in several lists. */
+  staticPaths?: Partial<Record<CacheabilityRepresentation, string[]>>;
+};
+export type CacheabilityManifest = {
+  buildId: string;
+  routes: Record<string, CacheabilityManifestRoute>;
+  version: 1;
+};
+export declare function cacheabilityManifestRouteKey(kind: CacheabilityManifestRoute["kind"], pattern: string): string;
+export declare function parseCacheabilityManifest(value: string | null | undefined, expectedBuildId: string | null | undefined): CacheabilityManifest | null;
+export declare function cacheabilityRequestIdentity(request: Request, trustedRepresentation?: CacheabilityRepresentation): {
+  representation: CacheabilityRepresentation;
+  requestKey: string;
+} | null;
+export declare function normalizeCacheabilityRoutePathname(pathname: string): string;
+export declare function cacheabilityRoutePathname(pathname: string, representation: CacheabilityRepresentation): string;
+export declare function cacheabilityManifestRouteState(route: CacheabilityManifestRoute, routePathname: string, representation?: CacheabilityRepresentation): CacheabilityManifestRouteState | null;
+export declare function findCacheabilityManifestRoute(manifest: CacheabilityManifest, kind: CacheabilityRouteKind, pattern: string): CacheabilityManifestRoute | null;
+export declare function resolveCacheabilityRepresentation(representation: CacheabilityRepresentation, routeKind: "app-page" | "app-route" | "pages-api" | "pages-page"): CacheabilityRepresentation;
+/** Whether completed-response admission can store a page route under this representation. */
+export declare function cacheabilityRepresentationMatchesPageRoute(routeKind: "app-page" | "pages-page", representation: CacheabilityRepresentation): boolean;
+/**
+ * The manifest state completed-response admission gives a page request, or
+ * null when admission refuses it. `requestRepresentation` is the request
+ * identity's, and `routePathname` is built from the resolved pathname with
+ * `cacheabilityRoutePathname`, as admission builds it. The Workers Cache
+ * request stage decides its query-free dispatch with this same function, so
+ * the dispatch and admission always see the same state.
+ */
+export declare function cacheabilityManifestPageState(manifest: CacheabilityManifest, route: {
+  kind: "app-page" | "pages-page";
+  pattern: string;
+}, requestRepresentation: CacheabilityRepresentation, routePathname: string): CacheabilityManifestRouteState | null;
+/**
+ * Project the manifest onto the Workers Cache request stage, which strips the
+ * query from App page dispatches whose manifest state is `static-candidate`.
+ * The projection keeps every App page route record that can resolve to that
+ * state, unchanged, so a lookup against it returns `static-candidate` exactly
+ * when the full manifest does. Every other route is left out.
+ */
+export declare function projectCacheabilityManifestForRequestStage(manifest: CacheabilityManifest): CacheabilityManifest;
+//#endregion