vinext 1.0.0-beta.8 → 1.0.0

package/dist/shims/cache.js

@@ -1,15 +1,16 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope } from "./unified-request-context.js";
 import { getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
-import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
+import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { getCdnCacheAdapter } from "./cdn-cache.js";
+import { isStagedCacheabilityProbeActive } from "./cacheability-classification.js";
 import { fnv1a64 } from "../utils/hash.js";
+import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
 import { getHeadersAccessPhase, isDraftModeEnabled, markDynamicUsage } from "./headers.js";
 import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
-import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 //#region src/shims/cache.ts
 /**
 * next/cache shim
@@ -28,8 +29,7 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 *   vinext({ cache: { data: kvDataAdapter({ binding: 'VINEXT_KV_CACHE' }) } })
 *
 * The imperative `setCacheHandler` / `setDataCacheHandler` setters are
-* deprecated for consumers and retained only as the internal registration
-* target used by the generated cache-adapter module.
+* deprecated for consumers and retained for backwards compatibility.
 */
 const _g = globalThis;
 function scheduleRevalidation(promise) {
@@ -54,6 +54,10 @@ function scheduleRevalidation(promise) {
 * @param profile - cacheLife profile name (e.g. 'max', 'hours') or inline { expire: number }
 */
 function revalidateTag(tag, profile) {
+	if (isStagedCacheabilityProbeActive()) {
+		markDynamicUsage();
+		return;
+	}
 	let durations;
 	if (typeof profile === "string") {
 		const resolved = cacheLifeProfiles[profile];
@@ -93,9 +97,14 @@ async function _invalidateEncodedTag(encoded, durations) {
 * layout/page hierarchy tags, so only no-type invalidation applies there.
 */
 function revalidatePath(path, type) {
+	if (isStagedCacheabilityProbeActive()) {
+		markDynamicUsage();
+		return;
+	}
 	markActionRevalidation(1);
 	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
-	const encodedTag = encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`);
+	const tag = type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`;
+	const encodedTag = encodeCacheTag(tag);
 	_markPendingRevalidatedTag(encodedTag);
 	return scheduleRevalidation(_invalidateEncodedTag(encodedTag));
 }
@@ -304,6 +313,7 @@ function unstable_cacheTag(...tags) {
 	}
 	return cacheTag(...tags);
 }
+const UNSTABLE_CACHE_KEY_PREFIX = "unstable_cache:v2";
 /**
 * AsyncLocalStorage to track whether we're inside an unstable_cache() callback.
 * Stored on globalThis via Symbol so headers.ts can detect the scope without
@@ -389,7 +399,7 @@ function unstable_cache(fn, keyParts, options) {
 	const revalidateSeconds = options?.revalidate;
 	const cachedFn = async (...args) => {
 		const argsKey = JSON.stringify(args);
-		const cacheKey = `unstable_cache:${baseKey}:${argsKey}`;
+		const cacheKey = `${UNSTABLE_CACHE_KEY_PREFIX}:${baseKey}:${argsKey}`;
 		addCollectedRequestTags(tags);
 		recordUnstableCacheObservation({
 			kind: "unstable_cache",
@@ -408,12 +418,14 @@ function unstable_cache(fn, keyParts, options) {
 			});
 			if (existing?.value && existing.value.kind === "FETCH") {
 				const cached = tryDeserializeUnstableCacheResult(existing.value.data.body);
-				if (cached.ok) if (existing.cacheState === "stale") {
-					if (shouldServeStaleUnstableCacheEntry()) {
-						scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds));
-						return cached.value;
-					}
-				} else return cached.value;
+				if (cached.ok) {
+					if (existing.cacheState === "stale") {
+						if (shouldServeStaleUnstableCacheEntry()) {
+							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds));
+							return cached.value;
+						}
+					} else return cached.value;
+				}
 			}
 		}
 		if (isDraftMode) return await _unstableCacheAls.run(true, () => fn(...args));
@@ -422,4 +434,4 @@ function unstable_cache(fn, keyParts, options) {
 	return cachedFn;
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, registerDataCacheHandler, registerLazyDataCacheHandler, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/cacheability-classification.d.ts

@@ -0,0 +1,106 @@
+//#region src/shims/cacheability-classification.d.ts
+export declare const CACHEABILITY_REQUEST_STATE: unique symbol;
+export type RouteCacheabilityOutcome = {
+  cacheControl?: string;
+  cacheable: boolean;
+  classificationFailure?: boolean;
+  dynamicUsage?: boolean;
+  reason?: string;
+  /** App pages: the render proved it left searchParams unread, so its response holds for every query. */
+  searchParamsUnread?: true;
+  /** A transient classification failure that may succeed on another bounded attempt. */
+  retryable?: true;
+  tags?: readonly string[];
+};
+export type RouteCacheabilityState = {
+  admission?: {
+    manifest?: unknown;
+    policy: "deny" | "manifest" | "runtime";
+    representation?: string;
+    requestKey?: string;
+    routePathname?: string;
+  };
+  /** Optional admission budget override used by focused runtime tests. */
+  captureBudget?: {
+    maxBytes: number;
+    reservedBytes: number;
+  };
+  captureDeadlineAt: number;
+  complete?: (outcome: RouteCacheabilityOutcome) => void;
+  completion?: Promise<RouteCacheabilityOutcome>;
+  /** Canonical framework tags most recently handed to the active CDN adapter. */
+  cdnCacheTags?: readonly string[];
+  /** Private marker surrounding this render's injected client trace metadata. */
+  clientTraceMetadataMarker?: string;
+  completedResponseBody?: boolean;
+  /** Whether admission must translate a completed response through the active adapter. */
+  applyCompletedResponsePolicy?: boolean;
+  /** Core- or adapter-owned cache policy headers set by next.config, by lowercased name. */
+  configCdnCachePolicy?: Map<string, string>;
+  explicitConfigCachePolicy?: boolean;
+  explicitResponseCachePolicy?: boolean;
+  finalResponseVetoReason?: string;
+  forcedDynamicReason?: string;
+  /** A route-config decision that applies to every concrete identity for this pattern. */
+  patternDynamicReason?: string;
+  frameworkResponseCachePolicy?: Headers;
+  mode: "admit" | "identity" | "probe";
+  outcome?: RouteCacheabilityOutcome;
+  preserveResponseCachePolicy?: boolean;
+  /** Whether an API request carried credentials that must not enter shared caching. */
+  credentialedRequest?: boolean;
+  /** Cache-key behavior declared by the active CDN adapter. */
+  responseVary?: "verbatim";
+  /** Concrete pathname resolved by the trusted request stage before rendering. */
+  resolvedRoutePathname?: string;
+  probeBailout?: {
+    kind: "private-cache";
+    outcome: RouteCacheabilityOutcome;
+  };
+  route?: {
+    kind: "app-page" | "app-route" | "pages-api" | "pages-page";
+    pattern: string;
+  };
+};
+/** Retain canonical tags across completed-response admission and adapter header shaping. */
+export declare function recordRouteCacheabilityCdnTags(tags: readonly string[] | undefined): void;
+/** Retain the exact trace metadata marker for completed shared-response admission. */
+export declare function recordRouteCacheabilityClientTraceMetadataMarker(marker: string): void;
+/** Preserve the existing policy when hybrid routing hands the request to Pages Router. */
+export declare function preserveRouteCacheabilityResponsePolicy(): void;
+export declare function readRouteCacheabilityState(): RouteCacheabilityState | null;
+export declare function beginRouteCacheability(kind: "app-page" | "app-route" | "pages-api" | "pages-page", pattern: string): boolean;
+/** Prevent shared caching when request processing before route dispatch was request-specific. */
+export declare function markRouteCacheabilityDynamic(reason: string): void;
+/** Mark an effective route configuration that makes the whole pattern dynamic. */
+export declare function markRouteCacheabilityPatternDynamic(reason: string): void;
+/** Read a request-specific routing veto without making the route globally dynamic. */
+export declare function getRouteCacheabilityDynamicReason(): string | null;
+/** Reuse the active request's bounded response-capture envelope when available. */
+export declare function getRouteCacheabilityCaptureOptions(): Pick<RouteCacheabilityState, "captureBudget" | "captureDeadlineAt"> | null;
+/** Keep a completed response private without treating it as static-to-dynamic. */
+export declare function markRouteCacheabilityFinalResponseUncacheable(reason: string): void;
+/** Record that next.config explicitly owns the final response cache policy. */
+export declare function markRouteCacheabilityExplicitConfigPolicy(): void;
+/** Record a cache policy header, not just Vary, that a next.config rule set. */
+export declare function markRouteCacheabilityConfigCdnCachePolicy(name: string, value: string): void;
+/** Record a next.config cache policy header with the value a response carries. */
+export declare function recordConfigCdnCachePolicyHeader(state: RouteCacheabilityState, name: string, value: string): void;
+/** Record a public cache policy supplied by the Route Handler itself. */
+export declare function markRouteCacheabilityExplicitResponsePolicy(): void;
+/** Record that the response body reached clean EOF and is now a replay stream. */
+export declare function markRouteCacheabilityResponseBodyComplete(): void;
+/** Record framework-owned policy so admission can identify policy added later. */
+export declare function captureRouteCacheabilityResponsePolicy(headers: Headers): void;
+/** True only for an authenticated probe that must render the matched App Page. */
+export declare function isRouteCacheabilityProbe(): boolean;
+/** True when the outer Worker must decide cache admission after clean EOF. */
+export declare function isRouteCacheabilityEvaluation(): boolean;
+/** True for the authenticated routing pass that must not evaluate user components. */
+export declare function isRouteCacheabilityIdentityProbe(): boolean;
+/** True for every side-effect-free staged Worker observation request. */
+export declare function isStagedCacheabilityProbeActive(): boolean;
+export declare function deferRouteCacheability(): ((outcome: RouteCacheabilityOutcome) => void) | null;
+export declare function recordRouteCacheability(outcome: RouteCacheabilityOutcome): void;
+export declare function recordRouteCacheabilityProbeBailout(kind: "private-cache", outcome: RouteCacheabilityOutcome): void;
+//#endregion

package/dist/shims/cacheability-classification.js

@@ -0,0 +1,161 @@
+import { getRequestExecutionContext } from "./request-context.js";
+//#region src/shims/cacheability-classification.ts
+const CACHEABILITY_REQUEST_STATE = Symbol.for("vinext.cacheabilityRequestState");
+/** Retain canonical tags across completed-response admission and adapter header shaping. */
+function recordRouteCacheabilityCdnTags(tags) {
+	if (tags === void 0) return;
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "admit") return;
+	state.cdnCacheTags = [...tags];
+}
+/** Retain the exact trace metadata marker for completed shared-response admission. */
+function recordRouteCacheabilityClientTraceMetadataMarker(marker) {
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "admit") return;
+	state.clientTraceMetadataMarker = marker;
+}
+/** Preserve the existing policy when hybrid routing hands the request to Pages Router. */
+function preserveRouteCacheabilityResponsePolicy() {
+	const state = readRouteCacheabilityState();
+	if (!state || state.mode !== "admit") return;
+	if (state.route?.kind === "pages-page") return;
+	state.preserveResponseCachePolicy = true;
+}
+function readRouteCacheabilityState() {
+	const context = getRequestExecutionContext();
+	if (!context) return null;
+	return Reflect.get(context, CACHEABILITY_REQUEST_STATE) ?? null;
+}
+function beginRouteCacheability(kind, pattern) {
+	const state = readRouteCacheabilityState();
+	if (!state) return false;
+	state.route = {
+		kind,
+		pattern
+	};
+	if (kind === "pages-page") state.preserveResponseCachePolicy = false;
+	return true;
+}
+/** Prevent shared caching when request processing before route dispatch was request-specific. */
+function markRouteCacheabilityDynamic(reason) {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	state.forcedDynamicReason = reason;
+}
+/** Mark an effective route configuration that makes the whole pattern dynamic. */
+function markRouteCacheabilityPatternDynamic(reason) {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	state.patternDynamicReason = reason;
+}
+/** Read a request-specific routing veto without making the route globally dynamic. */
+function getRouteCacheabilityDynamicReason() {
+	return readRouteCacheabilityState()?.forcedDynamicReason ?? null;
+}
+/** Reuse the active request's bounded response-capture envelope when available. */
+function getRouteCacheabilityCaptureOptions() {
+	const state = readRouteCacheabilityState();
+	return state ? {
+		captureBudget: state.captureBudget,
+		captureDeadlineAt: state.captureDeadlineAt
+	} : null;
+}
+/** Keep a completed response private without treating it as static-to-dynamic. */
+function markRouteCacheabilityFinalResponseUncacheable(reason) {
+	const state = readRouteCacheabilityState();
+	if (!state || state.mode !== "admit") return;
+	state.finalResponseVetoReason ??= reason;
+}
+/** Record that next.config explicitly owns the final response cache policy. */
+function markRouteCacheabilityExplicitConfigPolicy() {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	state.explicitConfigCachePolicy = true;
+}
+/** Record a cache policy header, not just Vary, that a next.config rule set. */
+function markRouteCacheabilityConfigCdnCachePolicy(name, value) {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	recordConfigCdnCachePolicyHeader(state, name, value);
+}
+/** Record a next.config cache policy header with the value a response carries. */
+function recordConfigCdnCachePolicyHeader(state, name, value) {
+	state.explicitConfigCachePolicy = true;
+	const applied = new Headers([[name, value]]).get(name) ?? value;
+	(state.configCdnCachePolicy ??= /* @__PURE__ */ new Map()).set(name.toLowerCase(), applied);
+}
+/** Record a public cache policy supplied by the Route Handler itself. */
+function markRouteCacheabilityExplicitResponsePolicy() {
+	const state = readRouteCacheabilityState();
+	if (!state || state.mode !== "admit") return;
+	state.explicitResponseCachePolicy = true;
+}
+/** Record that the response body reached clean EOF and is now a replay stream. */
+function markRouteCacheabilityResponseBodyComplete() {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	state.completedResponseBody = true;
+}
+/** Record framework-owned policy so admission can identify policy added later. */
+function captureRouteCacheabilityResponsePolicy(headers) {
+	const state = readRouteCacheabilityState();
+	if (!state || state.mode !== "admit") return;
+	state.frameworkResponseCachePolicy = new Headers(headers);
+}
+/** True only for an authenticated probe that must render the matched App Page. */
+function isRouteCacheabilityProbe() {
+	return readRouteCacheabilityState()?.mode === "probe";
+}
+/** True when the outer Worker must decide cache admission after clean EOF. */
+function isRouteCacheabilityEvaluation() {
+	const mode = readRouteCacheabilityState()?.mode;
+	return mode === "probe" || mode === "admit";
+}
+/** True for the authenticated routing pass that must not evaluate user components. */
+function isRouteCacheabilityIdentityProbe() {
+	return readRouteCacheabilityState()?.mode === "identity";
+}
+/** True for every side-effect-free staged Worker observation request. */
+function isStagedCacheabilityProbeActive() {
+	const mode = readRouteCacheabilityState()?.mode;
+	return mode === "probe" || mode === "identity";
+}
+function deferRouteCacheability() {
+	const state = readRouteCacheabilityState();
+	if (!state?.route || state.completion) return null;
+	state.completion = new Promise((resolve) => {
+		state.complete = (outcome) => {
+			const resolvedOutcome = state.forcedDynamicReason ? {
+				cacheable: false,
+				dynamicUsage: true,
+				reason: state.forcedDynamicReason
+			} : outcome;
+			state.outcome = resolvedOutcome;
+			resolve(resolvedOutcome);
+		};
+	});
+	return (outcome) => state.complete?.(outcome);
+}
+function recordRouteCacheability(outcome) {
+	const state = readRouteCacheabilityState();
+	if (!state?.route) return;
+	const resolvedOutcome = state.forcedDynamicReason ? {
+		cacheable: false,
+		dynamicUsage: true,
+		reason: state.forcedDynamicReason
+	} : outcome;
+	state.outcome = resolvedOutcome;
+	state.complete?.(resolvedOutcome);
+}
+function recordRouteCacheabilityProbeBailout(kind, outcome) {
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "probe" || !state.route) return;
+	state.probeBailout = {
+		kind,
+		outcome
+	};
+	state.outcome = outcome;
+	state.complete?.(outcome);
+}
+//#endregion
+export { CACHEABILITY_REQUEST_STATE, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityConfigCdnCachePolicy, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordConfigCdnCachePolicyHeader, recordRouteCacheability, recordRouteCacheabilityCdnTags, recordRouteCacheabilityClientTraceMetadataMarker, recordRouteCacheabilityProbeBailout };

package/dist/shims/cdn-cache-state.d.ts

@@ -0,0 +1,13 @@
+import { CdnCacheAdapter } from "./cdn-cache.js";
+//#region src/shims/cdn-cache-state.d.ts
+/** Register an adapter without loading the origin cache implementation. */
+export declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
+/**
+ * Lazily keep the first declaratively configured adapter shared across
+ * duplicated stage modules. Failed factories remain retryable so a later
+ * entrypoint with the required runtime bindings can register successfully.
+ */
+export declare function registerCdnCacheAdapter(factory: () => CdnCacheAdapter): void;
+/** Read only an explicitly registered adapter; defaults belong to cdn-cache. */
+export declare function getExplicitCdnCacheAdapter(): CdnCacheAdapter | null;
+//#endregion

package/dist/shims/cdn-cache-state.js

@@ -0,0 +1,23 @@
+//#region src/shims/cdn-cache-state.ts
+const CDN_CACHE_ADAPTER_KEY = Symbol.for("vinext.cdnCacheAdapter");
+const globals = globalThis;
+/** Register an adapter without loading the origin cache implementation. */
+function setCdnCacheAdapter(adapter) {
+	globals[CDN_CACHE_ADAPTER_KEY] = adapter;
+}
+/**
+* Lazily keep the first declaratively configured adapter shared across
+* duplicated stage modules. Failed factories remain retryable so a later
+* entrypoint with the required runtime bindings can register successfully.
+*/
+function registerCdnCacheAdapter(factory) {
+	if (globals[CDN_CACHE_ADAPTER_KEY] !== void 0) return;
+	const adapter = factory();
+	if (globals[CDN_CACHE_ADAPTER_KEY] === void 0) globals[CDN_CACHE_ADAPTER_KEY] = adapter;
+}
+/** Read only an explicitly registered adapter; defaults belong to cdn-cache. */
+function getExplicitCdnCacheAdapter() {
+	return globals[CDN_CACHE_ADAPTER_KEY] ?? null;
+}
+//#endregion
+export { getExplicitCdnCacheAdapter, registerCdnCacheAdapter, setCdnCacheAdapter };

package/dist/shims/cdn-cache.d.ts

@@ -1,8 +1,9 @@
 import { CacheHandlerValue, IncrementalCacheValue } from "./cache-handler.js";
+import { setCdnCacheAdapter } from "./cdn-cache-state.js";
 //#region src/shims/cdn-cache.d.ts
 /** A map of response header name -> value the adapter wants applied or removed. */
-type CdnResponseHeaders = Record<string, string | null>;
-type CdnCacheableHeaderInput = {
+export type CdnResponseHeaders = Record<string, string | null>;
+export type CdnCacheableHeaderInput = {
   /**
    * The cacheable `Cache-Control` value the framework computed for shared
    * caches (e.g. `s-maxage=60, stale-while-revalidate`). May be an empty string
@@ -28,11 +29,69 @@ type CdnCacheableHeaderInput = {
    */
   tags?: readonly string[];
 };
+export type CdnResponsePolicy = {
+  /** Whether a provider-specific response header controls shared caching. */
+  isHeader(name: string): boolean;
+  /**
+   * Read the effective shared-cache policy from a response. The returned value
+   * uses Cache-Control syntax so core can apply the framework's cacheability
+   * rules without knowing which provider header carried it.
+   */
+  readCacheControl(headers: Headers): string | null;
+  /**
+   * Name the response header `readCacheControl` interpreted, or `null` when
+   * none did. Core uses it to tell which stage owns the effective policy;
+   * without it, core cannot attribute that policy to next.config.
+   */
+  readCacheControlHeaderName?(headers: Headers): string | null;
+  /** Whether provider policy explicitly opts out of storage. */
+  hasExplicitNonCacheablePolicy(headers: Headers, baseline?: Headers): boolean;
+};
+/** Whether a Cache-Control value contains an exact non-cacheable directive. */
+export declare function isNonCacheableCacheControl(cacheControl: string): boolean;
 /**
  * The serving strategy for page-level ISR. Implement this to delegate
  * page/route/image caching to a CDN edge instead of the origin store.
  */
-type CdnCacheAdapter = {
+export type CdnCacheAdapter = {
+  /**
+   * The shared cache selects response variants using every request header
+   * named by `Vary`, comparing values verbatim.
+   */
+  readonly responseVary?: "verbatim";
+  /** Provider-specific response-policy interpretation, when the adapter has one. */
+  readonly responsePolicy?: CdnResponsePolicy;
+  /**
+   * Fresh App Page responses must reach clean EOF before this adapter may emit
+   * shared-cache headers. Used by edge adapters whose cache sits in front of
+   * the Worker; origin-managed adapters can stream privately and persist only
+   * the completed artifact.
+   */
+  readonly requiresCompletedResponseAdmission?: boolean;
+  /**
+   * This adapter's response-stage transport keys shared App page dispatches by
+   * `VinextResponseStageDispatchOptions.cacheIdentity` when core supplies one.
+   * Core supplies it only when completed-response admission is also required,
+   * because that admission is what makes a query-free identity safe.
+   */
+  readonly responseStageCacheIdentity?: "query-free";
+  /**
+   * Optionally return a foreground page response while completed-response
+   * admission continues on an independent body branch. Returning `null` keeps
+   * the normal blocking admission path. API responses are never passed here.
+   */
+  deferCompletedPageResponseAdmission?(response: Response, complete: (response: Response) => Promise<Response>): Response | null;
+  /** Capture the full-route RSC side stream while admitting a completed HTML response. */
+  captureAppPageRscData?(rscData: Promise<ArrayBuffer>): void;
+  /**
+   * Validate provider-specific request routing before the application handles
+   * the request. Returning a response short-circuits the request pipeline;
+   * returning `null` continues normally.
+   *
+   * Core deliberately passes the untouched request and does not interpret any
+   * provider headers or bindings itself.
+   */
+  validateRequest?(request: Request): Response | null | Promise<Response | null>;
   /**
    * Read a page-level artifact. Returning a value lets the origin serve it
    * (HIT/STALE); returning `null` makes the origin render fresh.
@@ -57,13 +116,11 @@ type CdnCacheAdapter = {
    */
   buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
   /**
-   * Whether existing response headers explicitly opt out of storage. Adapters
-   * that split browser and provider cache policy should implement this so they
-   * can interpret the provider-specific headers they own.
-   *
-   * When omitted, core inspects only the generic `Cache-Control` header.
+   * Build adapter-owned headers that identify the deployed application build.
+   * Core applies these at the outer page-response boundary, including response
+   * paths that do not pass through cache-policy finalization.
    */
-  hasExplicitNonCacheableResponsePolicy?(headers: Headers): boolean;
+  buildResponseIdentityHeaders?(): CdnResponseHeaders;
   /**
    * Whether the **origin** runs in-process background regeneration when a stale
    * entry is served. Edge adapters set this to `false` because the CDN
@@ -89,11 +146,14 @@ type CdnCacheAdapter = {
  * response headers alone. Deployments where provider headers carry cache
  * semantics must configure the adapter that owns those headers.
  */
-declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
+export declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
+  private readonly buildIdentity?;
   readonly ownsBackgroundRevalidation = true;
+  constructor(buildIdentity?: string | undefined);
   get(key: string, ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
   set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
   buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
+  buildResponseIdentityHeaders(): CdnResponseHeaders;
   revalidateTag(_tags: string | string[], _durations?: {
     expire?: number;
   }): Promise<void>;
@@ -109,23 +169,21 @@ declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
  *
  * ```ts
  * import { vinext } from "vinext";
- * import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+ * import { workersCacheCdnAdapter } from "@vinext/cloudflare/cache/workers-cache-cdn-adapter";
  *
  * export default defineConfig({
- *   plugins: [vinext({ cache: { cdn: cdnAdapter() } })],
+ *   plugins: [vinext({ cache: { cdn: workersCacheCdnAdapter() } })],
  * });
  * ```
  *
  * The plugin registers the adapter across every runtime/router entry, so you
- * don't have to call this from a worker entry. This setter remains as the
- * internal registration target and for backwards compatibility, but is not the
- * recommended consumer API.
+ * don't have to call this from a worker entry. This setter remains for
+ * backwards compatibility, but is not the recommended consumer API.
  */
-declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
 /**
  * Get the active CDN cache adapter. An explicitly configured adapter wins;
  * otherwise the origin-managed {@link DefaultCdnCacheAdapter} is used.
  */
-declare function getCdnCacheAdapter(): CdnCacheAdapter;
+export declare function getCdnCacheAdapter(): CdnCacheAdapter;
 //#endregion
-export { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders, DefaultCdnCacheAdapter, getCdnCacheAdapter, setCdnCacheAdapter };
+export { setCdnCacheAdapter };