@vinext/cloudflare 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -91,6 +91,15 @@ npx @vinext/cloudflare deploy
 `vinext-cloudflare deploy` never creates, rewrites, or deploys the Response
 Store Worker.
 
+Metadata sharding is opt-in and works in either deployment mode:
+
+```ts
+vinext({ cache: responseStoreAdapter({ shards: 16 }) });
+```
+
+Keys remain pinned to one shard while tag/path mutations fan out across every
+shard. Omit `shards` to retain the original single metadata Durable Object.
+
 To deploy storage and cache entrypoints with the application instead, select
 self-contained mode:
 

package/dist/cache/cdn-adapter.worker.d.ts

@@ -1,4 +1,5 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
+import "vinext/internal/server/cloudflare-workers-tracing";
 import { VinextAssetFetcher } from "vinext/server/multi-stage";
 //#region src/cache/cdn-adapter.worker.d.ts
 type CloudflareStageContext = {

package/dist/cache/cdn-adapter.worker.js

@@ -2,8 +2,10 @@ import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-bui
 import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER, VINEXT_PRERENDER_READINESS_PATH, VINEXT_RSC_VARY_HEADER } from "vinext/internal/server/headers";
 import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { WorkerEntrypoint } from "cloudflare:workers";
+import "vinext/internal/server/cloudflare-workers-tracing";
 import { loadVinextRequestStage } from "vinext/server/request-stage";
 import { loadVinextResponseStage } from "vinext/server/response-stage";
+import { traceCachedResponseStart } from "vinext/internal/server/response-start-tracing";
 //#region src/cache/cdn-adapter.worker.ts
 const CACHED_RESPONSE_STAGE_EXPORT = "VinextCachedResponse";
 const UNCACHED_RESPONSE_STAGE_EXPORT = "VinextUncachedResponse";
@@ -197,15 +199,15 @@ function preventResponseCaching(response) {
 * the outer gateway never forwards an inner shared-cache policy after adding
 * request-specific middleware or routing headers.
 */
-function markSharedResponseStage(response, provenanceToken, exposeEntrypointCacheStatus = false) {
+function markSharedResponseStage(response, provenanceToken, responseStageProps, exposeEntrypointCacheStatus = false) {
 	const headers = new Headers(response.headers);
 	const cacheStatus = exposeEntrypointCacheStatus ? headers.get("CF-Cache-Status") : null;
 	headers.set(SHARED_RESPONSE_STAGE_HEADER, cacheStatus ? `${provenanceToken}:${encodeURIComponent(cacheStatus)}` : provenanceToken);
-	return new Response(response.body, {
+	return traceCachedResponseStart(new Response(response.body, {
 		headers,
 		status: response.status,
 		statusText: response.statusText
-	});
+	}), cacheStatus, responseStageProps);
 }
 function finalizeGatewayResponse(response, provenanceToken) {
 	const provenance = response.headers.get(SHARED_RESPONSE_STAGE_HEADER);
@@ -358,7 +360,7 @@ var cdn_adapter_worker_default = { async fetch(request, env, context) {
 			if (!binding) return responseStageUnavailable();
 			const entrypointRequest = usesSharedCache ? await createCacheFacingRequest(stageRequest, serializedInvocation) : stageRequest;
 			const response = validateResponseStageBuildIdentity(await binding.fetch(entrypointRequest));
-			return usesSharedCache ? markSharedResponseStage(response, sharedResponseStageProvenance, true) : response;
+			return usesSharedCache ? markSharedResponseStage(response, sharedResponseStageProvenance, props, true) : response;
 		} catch (error) {
 			if (isResponseStageReadinessRequest(stageRequest)) return responseStageUnavailable();
 			throw error;

package/dist/cache/kv-data-adapter.d.ts

@@ -44,5 +44,9 @@ export type KvDataAdapterOptions = {
 export declare function kvDataAdapter(options?: KvDataAdapterOptions): {
   adapter: string;
   options: KvDataAdapterOptions | undefined;
+  capabilities: {
+    buildIdentity: "response-header";
+    warmup: "data-cache";
+  };
 };
 //#endregion

package/dist/cache/kv-data-adapter.js

@@ -18,7 +18,11 @@ function kvDataAdapter(options) {
 	if (options?.binding !== void 0 && typeof options.binding !== "string") throw new TypeError("[vinext] kvDataAdapter({ binding }) must be a string KV binding name.");
 	return {
 		adapter: fileURLToPath(import.meta.resolve("./kv-data-adapter.runtime.js")),
-		options
+		options,
+		capabilities: {
+			buildIdentity: "response-header",
+			warmup: "data-cache"
+		}
 	};
 }
 //#endregion

package/dist/cache/response-store-adapter.d.ts

@@ -1,6 +1,8 @@
 //#region src/cache/response-store-adapter.d.ts
 export type ResponseStoreAdapterOptions = {
   mode?: "self-contained" | "service-binding";
+  /** Split version-scoped metadata across this many Durable Objects. */
+  shards?: number;
 };
 /**
  * Use Workers Response Store for both vinext response-stage and data caching.
@@ -9,6 +11,31 @@ export type ResponseStoreAdapterOptions = {
  */
 export declare function responseStoreAdapter(options?: ResponseStoreAdapterOptions): {
   cdn: {
+    options?: undefined;
+    adapter: string;
+    output: {
+      entry: string;
+      matchesBuild({ plugins }: {
+        plugins: readonly {
+          name?: string;
+        }[];
+      }): boolean;
+      transformHostEntry({ code, id }: {
+        code: string;
+        id: string;
+      }): string | null;
+      type: "multi-stage";
+    };
+    capabilities: {
+      buildIdentity: "response-header";
+      isResponsePolicyHeader: (name: string) => boolean;
+      requestRouting: "uncached-stage";
+      warmup: "response-store";
+    };
+  } | {
+    options: {
+      shards: number;
+    };
     adapter: string;
     output: {
       entry: string;
@@ -31,6 +58,12 @@ export declare function responseStoreAdapter(options?: ResponseStoreAdapterOptio
     };
   };
   data: {
+    options?: undefined;
+    adapter: string;
+  } | {
+    options: {
+      shards: number;
+    };
     adapter: string;
   };
 };

package/dist/cache/response-store-adapter.js

@@ -9,11 +9,14 @@ const CLOUDFLARE_WORKER_ENTRY_ID = "virtual:cloudflare/worker-entry";
 function responseStoreAdapter(options = {}) {
 	const mode = options.mode ?? "service-binding";
 	if (mode !== "service-binding" && mode !== "self-contained") throw new Error(`Unknown Workers Response Store mode: ${String(mode)}`);
+	if (options.shards !== void 0 && (!Number.isSafeInteger(options.shards) || options.shards <= 1)) throw new TypeError("Workers Response Store shards must be an integer greater than 1");
+	const runtimeOptions = options.shards === void 0 ? {} : { options: { shards: options.shards } };
 	const workerEntry = fileURLToPath(import.meta.resolve(mode === "self-contained" ? "./response-store-adapter.self-contained.worker.js" : "./response-store-adapter.service-binding.worker.js"));
 	const entrypoints = mode === "self-contained" ? "CacheMetadata, ResponseStoreBinding, ResponseStoreRevalidator" : "ResponseStoreClient, ResponseStoreRevalidator";
 	return {
 		cdn: {
 			adapter: fileURLToPath(import.meta.resolve("./response-store-cdn.runtime.js")),
+			...runtimeOptions,
 			output: {
 				entry: workerEntry,
 				matchesBuild({ plugins }) {
@@ -32,7 +35,10 @@ function responseStoreAdapter(options = {}) {
 				warmup: "response-store"
 			}
 		},
-		data: { adapter: fileURLToPath(import.meta.resolve("./response-store-data.runtime.js")) }
+		data: {
+			adapter: fileURLToPath(import.meta.resolve("./response-store-data.runtime.js")),
+			...runtimeOptions
+		}
 	};
 }
 //#endregion

package/dist/cache/response-store-adapter.self-contained.worker.d.ts

@@ -1,4 +1,5 @@
 import { VinextResponseStoreEnv } from "./response-store-adapter.worker.js";
+import "vinext/internal/server/cloudflare-workers-tracing";
 import { ResponseStoreRevalidatorEntrypoint, WorkersResponseStoreEnv } from "@cloudflare/workers-response-store";
 import { CacheMetadata as CacheMetadata$1, ResponseStoreBinding as ResponseStoreBinding$1 } from "@cloudflare/workers-response-store/service";
 //#region src/cache/response-store-adapter.self-contained.worker.d.ts

package/dist/cache/response-store-adapter.self-contained.worker.js

@@ -1,7 +1,9 @@
 import { createVinextResponseStoreHandler, createVinextResponseStoreOptions } from "./response-store-adapter.worker.js";
+import "vinext/internal/server/cloudflare-workers-tracing";
 import { createWorkersResponseStore } from "@cloudflare/workers-response-store";
+import { configuredCdnCacheAdapterOptions } from "virtual:vinext-cdn-cache-adapter";
 //#region src/cache/response-store-adapter.self-contained.worker.ts
-const responseStore = createWorkersResponseStore(createVinextResponseStoreOptions());
+const responseStore = createWorkersResponseStore(createVinextResponseStoreOptions(configuredCdnCacheAdapterOptions));
 const CacheMetadata = responseStore.entrypoints.CacheMetadata;
 const ResponseStoreBinding = responseStore.entrypoints.ResponseStoreBinding;
 const ResponseStoreRevalidator = responseStore.entrypoints.ResponseStoreRevalidator;

package/dist/cache/response-store-adapter.service-binding.worker.d.ts

@@ -1,4 +1,5 @@
 import { VinextResponseStoreEnv } from "./response-store-adapter.worker.js";
+import "vinext/internal/server/cloudflare-workers-tracing";
 import { ResponseStoreClientEntrypoint, ResponseStoreRevalidatorEntrypoint, WorkersResponseStoreClientEnv } from "@cloudflare/workers-response-store";
 //#region src/cache/response-store-adapter.service-binding.worker.d.ts
 export declare const ResponseStoreClient: ResponseStoreClientEntrypoint;

package/dist/cache/response-store-adapter.service-binding.worker.js

@@ -1,7 +1,9 @@
 import { createVinextResponseStoreHandler, createVinextResponseStoreOptions } from "./response-store-adapter.worker.js";
+import "vinext/internal/server/cloudflare-workers-tracing";
 import { createWorkersResponseStoreClient } from "@cloudflare/workers-response-store";
+import { configuredCdnCacheAdapterOptions } from "virtual:vinext-cdn-cache-adapter";
 //#region src/cache/response-store-adapter.service-binding.worker.ts
-const responseStore = createWorkersResponseStoreClient(createVinextResponseStoreOptions());
+const responseStore = createWorkersResponseStoreClient(createVinextResponseStoreOptions(configuredCdnCacheAdapterOptions));
 const ResponseStoreClient = responseStore.entrypoints.ResponseStoreClient;
 const ResponseStoreRevalidator = responseStore.entrypoints.ResponseStoreRevalidator;
 var response_store_adapter_service_binding_worker_default = createVinextResponseStoreHandler(responseStore);

package/dist/cache/response-store-adapter.worker.d.ts

@@ -7,7 +7,7 @@ type WorkerExecutionContext = {
   waitUntil(promise: Promise<unknown>): void;
 };
 export type VinextResponseStoreEnv = WorkersResponseStoreClientEnv | WorkersResponseStoreEnv;
-export declare function createVinextResponseStoreOptions<Env extends VinextResponseStoreEnv>(): WorkersResponseStoreOptions<Env>;
+export declare function createVinextResponseStoreOptions<Env extends VinextResponseStoreEnv>(configuration?: Record<string, unknown>): WorkersResponseStoreOptions<Env>;
 export declare function createVinextResponseStoreHandler(store: WorkersResponseStore): {
   fetch(request: Request, env: VinextResponseStoreEnv, ctx: WorkerExecutionContext): Promise<Response>;
 };

package/dist/cache/response-store-adapter.worker.js

@@ -3,12 +3,14 @@ import { VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER, applyRscCompatibilityI
 import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { loadVinextRequestStage } from "vinext/server/request-stage";
 import { loadVinextResponseStage } from "vinext/server/response-stage";
+import { traceCachedResponseStart } from "vinext/internal/server/response-start-tracing";
 //#region src/cache/response-store-adapter.worker.ts
 const ROUTE_REVALIDATOR_ID = "vinext:response";
-const RESPONSE_STORE_KEY_PARAM = "__vinext_response_store";
+const RESPONSE_STORE_KEY_PARAM = "__workers_response_store";
 const AGE_BASIS_HEADER = "X-Workers-Response-Store-Age-Basis";
 const WARMUP_USER_AGENT = "vinext-cloudflare-cdn-warm";
 const REPLAY_REQUEST_HEADERS = VINEXT_RSC_VARY_HEADER.split(",").map((name) => name.trim().toLowerCase());
+const CACHE_REQUEST_VARY_HEADERS = REPLAY_REQUEST_HEADERS.map((name) => [name, "vinext-keyed"]);
 function stageContext(ctx, env) {
 	const assets = Reflect.get(env, "ASSETS");
 	return Object.assign(Object.create(Object.getPrototypeOf(ctx)), ctx, {
@@ -73,34 +75,39 @@ async function invokeResponseStage(request, props, env, ctx, cache, capture) {
 	const serialized = serializeInvocation(request, props);
 	return runWithResponseStoreInvocation(serialized, isReplayableInvocation(request, props), () => handleResponseStage(request, env, context, props, dispatchRequestStage, { cache }), capture);
 }
-function createVinextResponseStoreOptions() {
-	return { async regenerate(input, { env, ctx }) {
-		if (input.id === ROUTE_REVALIDATOR_ID) {
-			const invocation = parseInvocation(input.args.at(-1));
-			const response = await invokeResponseStage(restoreRequest(invocation), invocation.props, env, ctx, "shared");
-			if (!isCacheable(response)) {
-				await response.body?.cancel().catch(() => {});
-				throw new Error("Vinext response-stage regeneration was not cacheable");
+function createVinextResponseStoreOptions(configuration) {
+	const shards = configuration?.shards;
+	if (shards !== void 0 && typeof shards !== "number") throw new TypeError("Workers Response Store shards must be a number");
+	return {
+		...shards === void 0 ? {} : { shards },
+		async regenerate(input, { env, ctx }) {
+			if (input.id === ROUTE_REVALIDATOR_ID) {
+				const invocation = parseInvocation(input.args.at(-1));
+				const response = await invokeResponseStage(restoreRequest(invocation), invocation.props, env, ctx, "shared");
+				if (!isCacheable(response)) {
+					await response.body?.cancel().catch(() => {});
+					throw new Error("Vinext response-stage regeneration was not cacheable");
+				}
+				return response;
 			}
-			return response;
-		}
-		if (input.id === "vinext:cache-function" && typeof input.args[0] === "string" && typeof input.args[1] === "string") {
-			const invocation = JSON.parse(input.args[1]);
-			if (!invocation || typeof invocation.referenceId !== "string" || typeof invocation.encryptedArgs !== "string" || !invocation.rootParams || typeof invocation.rootParams !== "object" || !Array.isArray(invocation.softTags)) throw new TypeError("Invalid vinext cache function invocation");
-			return captureResponseStoreDataRegeneration(input.args[0], async () => {
-				const responseStage = await loadVinextResponseStage();
-				if (!responseStage.invokeCacheFunction) throw new Error("The vinext response stage cannot invoke cache functions");
-				await responseStage.invokeCacheFunction(invocation, env, stageContext(ctx, env), (request) => invokeRequestStage(request, env, ctx));
-			});
-		}
-		if (input.id === "vinext:data" && typeof input.args[0] === "string") {
-			const invocation = parseInvocation(input.args.at(-1));
-			return captureResponseStoreDataRegeneration(input.args[0], async () => {
-				await (await invokeResponseStage(restoreRequest(invocation), invocation.props, env, ctx, "bypass")).body?.pipeTo(new WritableStream());
-			});
+			if (input.id === "vinext:cache-function" && typeof input.args[0] === "string" && typeof input.args[1] === "string") {
+				const invocation = JSON.parse(input.args[1]);
+				if (!invocation || typeof invocation.referenceId !== "string" || typeof invocation.encryptedArgs !== "string" || !invocation.rootParams || typeof invocation.rootParams !== "object" || !Array.isArray(invocation.softTags)) throw new TypeError("Invalid vinext cache function invocation");
+				return captureResponseStoreDataRegeneration(input.args[0], async () => {
+					const responseStage = await loadVinextResponseStage();
+					if (!responseStage.invokeCacheFunction) throw new Error("The vinext response stage cannot invoke cache functions");
+					await responseStage.invokeCacheFunction(invocation, env, stageContext(ctx, env), (request) => invokeRequestStage(request, env, ctx));
+				});
+			}
+			if (input.id === "vinext:data" && typeof input.args[0] === "string") {
+				const invocation = parseInvocation(input.args.at(-1));
+				return captureResponseStoreDataRegeneration(input.args[0], async () => {
+					await (await invokeResponseStage(restoreRequest(invocation), invocation.props, env, ctx, "bypass")).body?.pipeTo(new WritableStream());
+				});
+			}
+			throw new Error(`Unknown vinext response-store revalidator ${input.id}`);
 		}
-		throw new Error(`Unknown vinext response-store revalidator ${input.id}`);
-	} };
+	};
 }
 async function cacheRequest(request, props) {
 	const identity = JSON.stringify([
@@ -111,8 +118,11 @@ async function cacheRequest(request, props) {
 	]);
 	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(identity)));
 	const url = new URL(request.url);
-	url.searchParams.set(RESPONSE_STORE_KEY_PARAM, [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join(""));
-	return new Request(url, { method: "GET" });
+	url.searchParams.set(RESPONSE_STORE_KEY_PARAM, `v1.${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`);
+	return new Request(url, {
+		headers: CACHE_REQUEST_VARY_HEADERS,
+		method: "GET"
+	});
 }
 function isCacheable(response) {
 	const policy = response.headers.get("Cloudflare-CDN-Cache-Control") ?? response.headers.get("CDN-Cache-Control") ?? response.headers.get("Cache-Control");
@@ -121,7 +131,7 @@ function isCacheable(response) {
 function isResponseStoreMiss(response) {
 	return response.status === 404 && response.headers.get("X-Workers-Response-Store") === "MISS";
 }
-function publicResponse(response, cacheStatus) {
+function publicResponse(response, cacheStatus, responseStageProps) {
 	const headers = new Headers(response.headers);
 	const publicCacheStatus = cacheStatus === "HIT" && headers.get("CF-Cache-Status") === "UPDATING" ? "UPDATING" : cacheStatus;
 	const ageBasis = /^(\d+):(\d+)$/.exec(headers.get(AGE_BASIS_HEADER) ?? "");
@@ -145,11 +155,11 @@ function publicResponse(response, cacheStatus) {
 	}
 	const cacheControl = headers.get("Cache-Control");
 	if (!cacheControl || !isNonCacheableCacheControl(cacheControl)) headers.set("Cache-Control", "private, max-age=0, must-revalidate");
-	return new Response(response.body, {
+	return traceCachedResponseStart(new Response(response.body, {
 		headers,
 		status: response.status,
 		statusText: response.statusText
-	});
+	}), publicCacheStatus ?? null, responseStageProps);
 }
 let responseStore;
 function createVinextResponseStoreHandler(store) {
@@ -161,7 +171,7 @@ const handler = { async fetch(request, env, ctx) {
 	const context = stageContext(ctx, env);
 	const dispatchResponseStage = async (stageRequest, props, options) => {
 		const invocation = serializeInvocation(stageRequest, props);
-		if (options.cache === "bypass" || stageRequest.method !== "GET" && stageRequest.method !== "HEAD") return publicResponse(await invokeResponseStage(stageRequest, props, env, ctx, "bypass"), "BYPASS");
+		if (options.cache === "bypass" || stageRequest.method !== "GET" && stageRequest.method !== "HEAD") return publicResponse(await invokeResponseStage(stageRequest, props, env, ctx, "bypass"), "BYPASS", props);
 		const isWarmup = request.headers.get("user-agent") === WARMUP_USER_AGENT;
 		const rscSeed = isWarmup && props !== null && typeof props === "object" && Reflect.get(props, "kind") === "app-page" && Reflect.get(props, "isRscRequest") === false && Reflect.get(props, "matchKind") === "request" && Reflect.get(props, "interceptionContext") === null && Reflect.get(props, "interceptionId") === null && Reflect.get(props, "mountedSlotsHeader") === null ? {
 			props: {
@@ -175,11 +185,11 @@ const handler = { async fetch(request, env, ctx) {
 		const key = await cacheRequest(stageRequest, props);
 		const stored = await responseStore.fetch(key);
 		if (!isResponseStoreMiss(stored)) {
-			if (!rscKey) return publicResponse(stored, "HIT");
+			if (!rscKey) return publicResponse(stored, "HIT", props);
 			const storedRsc = await responseStore.fetch(rscKey);
 			if (!isResponseStoreMiss(storedRsc)) {
 				await storedRsc.body?.cancel();
-				return publicResponse(stored, "HIT");
+				return publicResponse(stored, "HIT", props);
 			}
 			await Promise.all([stored.body?.cancel(), storedRsc.body?.cancel()]);
 		}
@@ -204,11 +214,11 @@ const handler = { async fetch(request, env, ctx) {
 					error: error instanceof Error ? error.message : String(error)
 				}));
 			}));
-			return publicResponse(rendered, "MISS");
+			return publicResponse(rendered, "MISS", props);
 		}
 		if (!isCacheable(rendered)) {
 			capture?.rscData?.catch(() => {});
-			return publicResponse(rendered, "BYPASS");
+			return publicResponse(rendered, "BYPASS", props);
 		}
 		if (rscSeed && !capture?.rscData) {
 			await rendered.body?.cancel();
@@ -245,7 +255,7 @@ const handler = { async fetch(request, env, ctx) {
 				}
 			});
 		}
-		return publicResponse(new Response(foreground, rendered), "MISS");
+		return publicResponse(new Response(foreground, rendered), "MISS", props);
 	};
 	const { handleRequestStage } = await loadVinextRequestStage();
 	return handleRequestStage(request, env, context, dispatchResponseStage);

package/dist/cdn-warm.d.ts

@@ -33,7 +33,7 @@ export type CdnWarmOptions = {
   requireCacheHit?: boolean;
   strict?: boolean;
   /** Cache-admission signal exposed by the deployed adapter. */
-  statusSource?: "cloudflare" | "vinext";
+  statusSource?: "cloudflare" | "data-cache" | "vinext";
   fetchImpl?: typeof fetch;
 };
 export declare const DEFAULT_CDN_WARM_CONCURRENCY = 25;

package/dist/cdn-warm.js

@@ -365,6 +365,7 @@ const REUSABLE_CF_CACHE_STATUSES = /* @__PURE__ */ new Set([
 	"REVALIDATED",
 	"UPDATING"
 ]);
+const TRANSITIONAL_VINEXT_CACHE_STATUSES = /* @__PURE__ */ new Set(["MISS", "UPDATING"]);
 const NON_CACHEABLE_CF_CACHE_STATUSES = /* @__PURE__ */ new Set(["BYPASS"]);
 const CDN_CACHE_POLICY_HEADERS = [
 	"Cloudflare-CDN-Cache-Control",
@@ -445,20 +446,29 @@ function validateCachePolicy(response, requireCacheStatus, requireCacheHit = fal
 		error: `CF-Cache-Status is ${cacheStatus}`
 	};
 }
-function validateVinextCacheStatus(response) {
+function validateVinextCacheStatus(response, missingStatus = "failed", requireCacheHit = false) {
 	const status = response.headers.get(VINEXT_CACHE_HEADER)?.trim().toUpperCase();
+	if (requireCacheHit && status !== "HIT") return {
+		outcome: "failed",
+		error: `${VINEXT_CACHE_HEADER} is ${status ?? "missing"}; the cache fill is not reusable`
+	};
 	if (status === "MISS" || status === "HIT" || status === "UPDATING") return { outcome: "warmed" };
 	if (status === "BYPASS" || status === "DYNAMIC") return {
 		outcome: "skipped",
 		reason: `${VINEXT_CACHE_HEADER} is ${status}`
 	};
-	return {
+	return missingStatus === "skipped" ? {
+		outcome: "skipped",
+		reason: `response is missing ${VINEXT_CACHE_HEADER}`
+	} : {
 		outcome: "failed",
 		error: `response is missing ${VINEXT_CACHE_HEADER}`
 	};
 }
 function validateWarmAdmission(response, statusSource, requireCacheHit) {
-	return statusSource === "vinext" ? validateVinextCacheStatus(response) : validateCachePolicy(response, true, requireCacheHit);
+	if (statusSource === "vinext") return validateVinextCacheStatus(response, "failed", requireCacheHit);
+	if (statusSource === "data-cache") return validateVinextCacheStatus(response, "skipped", requireCacheHit);
+	return validateCachePolicy(response, true, requireCacheHit);
 }
 function validateBuildIdentity(response, expectedBuildId) {
 	if (expectedBuildId !== void 0 && response.headers.get("X-Vinext-Build-Id") !== expectedBuildId) {
@@ -645,6 +655,14 @@ function shouldRetryValidationFailure(response, target, options) {
 	if (expectedIdentities.some((matches) => !matches)) return true;
 	return isRetryableStatus(response.status, options.retryNotFound);
 }
+function isRetryableCertificationFailure(response, statusSource, retryPropagationFailures) {
+	if (statusSource === "cloudflare") {
+		const status = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
+		return !REUSABLE_CF_CACHE_STATUSES.has(status ?? "") && (retryPropagationFailures || ADMITTED_CF_CACHE_STATUSES.has(status ?? ""));
+	}
+	const status = response.headers.get(VINEXT_CACHE_HEADER)?.trim().toUpperCase();
+	return TRANSITIONAL_VINEXT_CACHE_STATUSES.has(status ?? "");
+}
 async function warmOnePath(target, options) {
 	const url = buildWarmupUrl(options.targetUrl, target.pathname);
 	let lastError = "request failed before the first attempt";
@@ -707,8 +725,7 @@ async function warmOnePath(target, options) {
 				}
 				lastSkippedReason = null;
 				lastError = validation.error;
-				const cacheStatus = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
-				lastRetryable = options.requireCacheHit && ADMITTED_CF_CACHE_STATUSES.has(cacheStatus ?? "") && !REUSABLE_CF_CACHE_STATUSES.has(cacheStatus ?? "") || shouldRetryValidationFailure(response, target, options);
+				lastRetryable = options.requireCacheHit && isRetryableCertificationFailure(response, options.statusSource, options.retryPropagationFailures) || shouldRetryValidationFailure(response, target, options);
 				if (!lastRetryable) break;
 				if (!canRetry(attempt)) break;
 				if (!await waitBeforeRetry()) return {
@@ -745,8 +762,7 @@ async function warmOnePath(target, options) {
 			}
 			lastSkippedReason = null;
 			lastError = validation.error;
-			const cacheStatus = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
-			lastRetryable = options.requireCacheHit && ADMITTED_CF_CACHE_STATUSES.has(cacheStatus ?? "") && !REUSABLE_CF_CACHE_STATUSES.has(cacheStatus ?? "") || shouldRetryValidationFailure(response, target, options);
+			lastRetryable = options.requireCacheHit && isRetryableCertificationFailure(response, options.statusSource, options.retryPropagationFailures) || shouldRetryValidationFailure(response, target, options);
 			if (!lastRetryable) break;
 		} catch (error) {
 			lastSkippedReason = null;

package/dist/deploy-help.js

@@ -19,6 +19,8 @@ function formatDeployHelp() {
     --skip-build             Skip the build step (use existing dist/)
     --dry-run                Validate setup without building or deploying
     --verbose                Print raw output from internal Wrangler commands
+    --no-promote             Do not promote the uploaded Worker version to 100%
+                             traffic
     --prerender-all          Pre-render discovered routes after building (future
                              releases will auto-populate the remote cache)
     --prerender-concurrency <count>
@@ -60,8 +62,6 @@ function formatDeployHelp() {
     --dangerously-promote-on-cdn-warm-error
                              Promote even when ordinary staged warmup cannot be
                              verified (never bypasses --warm-cdn-certify)
-    --warm-cdn-no-promote    Leave the warmed Worker version staged at 0% traffic;
-                             production triggers are still applied before warming
     --warm-cdn-promotion-delay <ms>
                              Delay before promotion after warmup (default: 15000)
     --warm-cdn-include-fallbacks
@@ -69,16 +69,18 @@ function formatDeployHelp() {
     -h, --help               Show this help
 
   Experimental:
-    --experimental-tpr               Enable Traffic-aware Pre-Rendering
-    --tpr-coverage <pct>             Traffic coverage target, 0-100 (default: 90)
-    --tpr-limit <count>              Hard cap on pages to pre-render (default: 1000)
-    --tpr-window <hours>             Analytics lookback window in hours (default: 24)
+    --experimental-traffic-aware-warm-cache
+                                     Select CDN pre-warm routes from traffic
+    --traffic-aware-coverage <pct>   Traffic coverage target, 0-100 (default: 90)
+    --traffic-aware-limit <count>    Hard cap on selected routes (default: 1000)
+    --traffic-aware-window <hours>   Analytics lookback window in hours (default: 24)
 
-  TPR (Traffic-aware Pre-Rendering) uses Cloudflare zone analytics to determine
-  which pages get the most traffic and pre-renders them into KV cache during
-  deploy. This feature is experimental and must be explicitly enabled. Requires
-  a custom domain (zone analytics are unavailable on *.workers.dev) and the
-  CLOUDFLARE_API_TOKEN environment variable with Zone.Analytics read permission.
+  Traffic-aware warming uses Cloudflare zone analytics to select the
+  highest-traffic routes, then feeds those routes into the same staged CDN
+  pre-warming flow used by --experimental-warm-cdn-cache. It requires a custom
+  domain and a CLOUDFLARE_API_TOKEN with Zone Analytics read permission.
+
+  Legacy --experimental-tpr and --tpr-* aliases remain supported.
 
   Workers Cache automatically uses tiered caching. Warmed entries can therefore
   be reused outside the data center reached by the warmup request after cache
@@ -93,12 +95,16 @@ function formatDeployHelp() {
     vinext-cloudflare deploy --config dist/server/wrangler.json        Deploy using a generated Wrangler config
     vinext-cloudflare deploy --dry-run                                 Validate setup without building or deploying
     vinext-cloudflare deploy --name my-app                             Deploy with a custom Worker name
+    vinext-cloudflare deploy --no-promote                              Upload a version without changing deployment traffic
     vinext-cloudflare deploy --experimental-warm-cdn-cache              Warm build-discovered paths during version deploy (experimental)
     vinext-cloudflare deploy --experimental-warm-cdn-cache --warm-cdn-target https://example.com
                                                                           Warm an explicit production origin
-    vinext-cloudflare deploy --experimental-tpr                        Enable TPR during deploy
-    vinext-cloudflare deploy --experimental-tpr --tpr-coverage 95      Cover 95% of traffic
-    vinext-cloudflare deploy --experimental-tpr --tpr-limit 500        Cap at 500 pages
+    vinext-cloudflare deploy --experimental-traffic-aware-warm-cache
+                                                                          Enable traffic-aware warming
+    vinext-cloudflare deploy --experimental-traffic-aware-warm-cache --traffic-aware-coverage 95
+                                                                          Cover 95% of traffic
+    vinext-cloudflare deploy --experimental-traffic-aware-warm-cache --traffic-aware-limit 500
+                                                                          Cap at 500 routes
 `;
 }
 function printDeployHelp() {

package/dist/deploy.d.ts

@@ -1,5 +1,6 @@
 import { CdnWarmOptions, CdnWarmRequestPlan, PrerenderWarmPlan } from "./cdn-warm.js";
-import { parseWranglerConfig } from "./tpr.js";
+import { parseWranglerConfig } from "./wrangler-config.js";
+import { TrafficEntry } from "./tpr.js";
 import { WranglerDeploymentStatus, WranglerVersionTraffic } from "./version-deploy.js";
 import { KVBulkPair } from "./prerender-kv-populate.js";
 import { spawn } from "node:child_process";
@@ -58,17 +59,17 @@ export type DeployOptions = {
   warmCdnReadinessProbeDelay?: number;
   /** Promote even when staged CDN warmup cannot be completed */
   dangerouslyPromoteOnCdnWarmError?: boolean;
-  /** Promote the warmed Worker version to 100% traffic (default: true) */
+  /** Promote the uploaded Worker version to 100% traffic (default: true) */
   warmCdnPromote?: boolean;
   /** Delay between successful warmup and promotion in milliseconds */
   warmCdnPromotionDelay?: number;
   /** Include PPR fallback-shell placeholder paths during CDN warmup */
   warmCdnIncludeFallbacks?: boolean;
-  /** Enable experimental TPR (Traffic-aware Pre-Rendering) */
+  /** Select CDN pre-warm routes using traffic analytics */
   experimentalTPR?: boolean;
   /** TPR: traffic coverage percentage target (0–100, default: 90) */
   tprCoverage?: number;
-  /** TPR: hard cap on number of pages to pre-render (default: 1000) */
+  /** TPR: hard cap on selected routes (default: 1000) */
   tprLimit?: number;
   /** TPR: analytics lookback window in hours (default: 24) */
   tprWindow?: number;
@@ -157,18 +158,25 @@ export declare function runWranglerKVBulkPut(root: string, options: {
   pairs: KVBulkPair[];
   tempDir?: string;
 }, execute?: typeof spawn, nodeExecutable?: string): Promise<void>;
-export declare function runWranglerDeploy(root: string, options: Pick<DeployOptions, "preview" | "env" | "name" | "config">, execute?: typeof spawn): Promise<string>;
+export declare function runWranglerDeploy(root: string, options: Pick<DeployOptions, "preview" | "env" | "name" | "config" | "verbose"> & {
+  promote?: boolean;
+}, execute?: typeof spawn): Promise<string>;
 export declare function hasCdnWarmRequests(plan: Omit<CdnWarmRequestPlan, "pagesDataPaths"> & {
   pagesDataPaths?: readonly string[];
 }): boolean;
+export declare function selectTPRWarmPlan(plan: PrerenderWarmPlan, traffic: readonly TrafficEntry[], coverage: number, limit: number): PrerenderWarmPlan;
 export declare function projectRequiresRouteCacheabilityProbeManifest(project: Pick<ProjectInfo, "isAppRouter" | "isPagesRouter">, cacheConfig: VinextCacheConfig | null): boolean;
 type CdnWarmDeployOptions = Pick<DeployOptions, "preview" | "env" | "name" | "config" | "verbose" | "warmCdnTarget" | "warmCdnConcurrency" | "warmCdnTimeout" | "warmCdnRetries" | "warmCdnDiscoveryTimeout" | "warmCdnDiscoveryRetries" | "warmCdnProbeTimeout" | "warmCdnProbeRetries" | "warmCdnCertify" | "warmCdnReadinessTimeout" | "warmCdnReadinessRetries" | "warmCdnReadinessProbes" | "warmCdnReadinessProbeDelay" | "dangerouslyPromoteOnCdnWarmError" | "warmCdnPromote" | "warmCdnPromotionDelay"> & Pick<CdnWarmOptions, "deploymentId" | "expectedBuildId" | "expectedRscBuildId" | "loadingShellPaths" | "pagesDataPaths" | "routeHandlerPaths" | "routePatterns" | "rscPaths" | "statusSource"> & {
+  /** Allow optional route selection to discover no warmable requests. */
+  allowEmptyWarmPlan?: boolean;
   /** Probe a staged Worker and upload the resulting manifest as a second version. */
   cacheabilityProbe?: boolean;
   discoverWarmPlan?: (target: {
     headers?: HeadersInit;
     targetUrl: string;
   }) => Promise<PrerenderWarmPlan>;
+  /** Narrow the final warm requests without changing discovery or probe metadata. */
+  selectWarmPlan?: (plan: PrerenderWarmPlan) => PrerenderWarmPlan;
 };
 export declare function deployWithCdnWarmup(root: string, paths: readonly string[], options: CdnWarmDeployOptions): Promise<string>;
 export declare function resolveCdnWarmupTargetUrl(root: string, deployedUrl: string | null): string | null;