@vinext/cloudflare 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/deploy.js

@@ -1,13 +1,21 @@
-import { readPrerenderWarmPaths, warmCdnCache } from "./cdn-warm.js";
-import { parseWranglerConfig, runTPR } from "./tpr.js";
-import { formatImageOptimizationHint, formatMissingCacheAdapterError, resolveKvDataAdapterConfig, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
-import { parseWorkersDevUrl } from "./workers-dev-url.js";
+import { writeCacheabilityManifestArtifact } from "./cacheability-artifact.js";
+import { DEFAULT_CACHEABILITY_PROBE_RETRY_DELAY_MS, probeStagedWorkerCacheability, readPrerenderSecret } from "./cacheability-probe.js";
+import { CdnOperationProgress, createCdnWarmTargets, createPrerenderWarmPlan, waitForCdnWarmTargetReadiness, warmCdnCache } from "./cdn-warm.js";
+import { parseWranglerConfig } from "./wrangler-config.js";
+import { resolveTPRRoutes, selectRoutes } from "./tpr.js";
+import { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "./version-headers.js";
+import { formatImageOptimizationHint, formatMissingCacheAdapterError, resolveCdnAdapterConfig, resolveKvDataAdapterConfig, viteConfigHasCacheAdapter, viteConfigHasCloudflarePlugin, viteConfigHasImageAdapter, workerEntryHasCacheHandler } from "./deploy-config.js";
+import { assertCdnVersionMetadataConfig } from "./wrangler-version-metadata.js";
+import { parseWorkerDeploymentUrl } from "./worker-deployment-url.js";
 import { runWranglerDeploymentStatus, runWranglerTriggersDeploy, runWranglerVersionDeploy, runWranglerVersionUpload } from "./version-deploy.js";
 import { buildPrerenderKVPairs } from "./prerender-kv-populate.js";
 import { createRequire } from "node:module";
-import path from "node:path";
 import fs from "node:fs";
-import { emitPrerenderPathManifest } from "vinext/internal/build/prerender-paths";
+import path from "node:path";
+import { cacheabilityRoutePathname } from "vinext/internal/server/cacheability-manifest";
+import { setTimeout } from "node:timers/promises";
+import { DEFAULT_REMOTE_PATH_DISCOVERY_PHASE_TIMEOUT_MS, DEFAULT_REMOTE_PATH_DISCOVERY_RETRY_DELAY_MS, discoverPrerenderPathManifest, emitPrerenderPathManifest } from "vinext/internal/build/prerender-paths";
+import { normalizePathTrailingSlash } from "vinext/shims/url-utils";
 import os from "node:os";
 import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
@@ -15,7 +23,7 @@ import { pathToFileURL } from "node:url";
 import { runPrerender } from "vinext/internal/build/run-prerender";
 import { loadDotenv } from "vinext/internal/config/dotenv";
 import { findVinextNextConfigInPlugins, loadNextConfig, resolveNextConfig, resolveNextConfigInput } from "vinext/internal/config/next-config";
-import { findVinextCacheConfigInPlugins, findVinextPrerenderConfigInPlugins, findVinextRouteRootConfigInPlugins, formatVinextPrerenderLabel, resolveVinextPrerenderDecision } from "vinext/internal/config/prerender";
+import { cacheWarmupStatusSource, findVinextCacheConfigInPlugins, findVinextPrerenderConfigInPlugins, findVinextRouteRootConfigInPlugins, formatVinextPrerenderLabel, hasBuildIdentityResponseHeader, hasUncachedRequestRouting, hasVerbatimResponseVary, isConfiguredCdnResponsePolicyHeader, requiresRouteCacheabilityProbeManifest, resolveVinextPrerenderDecision, supportsCanonicalRscWarmup } from "vinext/internal/config/prerender";
 import { detectProject, findInNodeModules, formatMissingCloudflarePluginError, getMissingDeps } from "vinext/internal/utils/project";
 import { PHASE_PRODUCTION_BUILD } from "vinext/shims/constants";
 //#region src/deploy.ts
@@ -28,6 +36,7 @@ import { PHASE_PRODUCTION_BUILD } from "vinext/shims/constants";
 *   2. Runs the Vite build
 *   3. Deploys to Cloudflare Workers via Wrangler
 */
+const DEFAULT_CDN_WARM_PROMOTION_DELAY_MS = 15e3;
 function parsePositiveIntegerArg(raw, flag) {
 	if (raw === "") throw new Error(`${flag} requires a value, but none was provided.`);
 	const parsed = Number(raw);
@@ -40,10 +49,31 @@ function parseNonNegativeIntegerArg(raw, flag) {
 	if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} expects a non-negative integer, but got "${raw}".`);
 	return parsed;
 }
+const MAX_NODE_TIMER_DELAY_MS = 2147483647;
+function validateTimerDelay(value, flag, raw = String(value)) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`${flag} expects a non-negative integer, but got "${raw}".`);
+	if (value > MAX_NODE_TIMER_DELAY_MS) throw new Error(`${flag} must not exceed ${MAX_NODE_TIMER_DELAY_MS} milliseconds, but got "${raw}".`);
+	return value;
+}
+function validatePromotionDelay(value, raw = String(value)) {
+	return validateTimerDelay(value, "--warm-cdn-promotion-delay", raw);
+}
+function validateCdnWarmTarget(raw) {
+	const value = raw.trim();
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`--warm-cdn-target expects an HTTPS origin, but got "${raw}".`);
+	}
+	if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "") throw new Error(`--warm-cdn-target expects an HTTPS origin without a path, query, credentials, or port, but got "${raw}".`);
+	return url.origin;
+}
 function formatUnknownError(error) {
 	if (error instanceof Error && error.message) return error.message;
 	return String(error);
 }
+var StagedWarmupError = class extends Error {};
 /** Deploy command flag definitions for util.parseArgs. */
 const deployArgOptions = {
 	help: {
@@ -66,6 +96,10 @@ const deployArgOptions = {
 		type: "boolean",
 		default: false
 	},
+	verbose: {
+		type: "boolean",
+		default: false
+	},
 	"prerender-all": {
 		type: "boolean",
 		default: false
@@ -75,17 +109,46 @@ const deployArgOptions = {
 		type: "boolean",
 		default: false
 	},
+	"warm-cdn-target": { type: "string" },
 	"warm-cdn-concurrency": { type: "string" },
 	"warm-cdn-timeout": { type: "string" },
 	"warm-cdn-retries": { type: "string" },
-	"warm-cdn-strict": {
+	"warm-cdn-discovery-timeout": { type: "string" },
+	"warm-cdn-discovery-retries": { type: "string" },
+	"warm-cdn-probe-timeout": { type: "string" },
+	"warm-cdn-probe-retries": { type: "string" },
+	"warm-cdn-certify": {
+		type: "boolean",
+		default: false
+	},
+	"warm-cdn-readiness-timeout": { type: "string" },
+	"warm-cdn-readiness-retries": { type: "string" },
+	"warm-cdn-readiness-probes": { type: "string" },
+	"warm-cdn-readiness-probe-delay": { type: "string" },
+	"dangerously-promote-on-cdn-warm-error": {
+		type: "boolean",
+		default: false
+	},
+	"no-promote": {
 		type: "boolean",
 		default: false
 	},
+	"warm-cdn-no-promote": {
+		type: "boolean",
+		default: false
+	},
+	"warm-cdn-promotion-delay": { type: "string" },
 	"warm-cdn-include-fallbacks": {
 		type: "boolean",
 		default: false
 	},
+	"experimental-traffic-aware-warm-cache": {
+		type: "boolean",
+		default: false
+	},
+	"traffic-aware-coverage": { type: "string" },
+	"traffic-aware-limit": { type: "string" },
+	"traffic-aware-window": { type: "string" },
 	"experimental-tpr": {
 		type: "boolean",
 		default: false
@@ -100,6 +163,8 @@ function parseDeployArgs(args) {
 		options: deployArgOptions,
 		strict: true
 	});
+	if (values["warm-cdn-certify"] && !values["experimental-warm-cdn-cache"]) throw new Error("--warm-cdn-certify requires --experimental-warm-cdn-cache.");
+	if (values["warm-cdn-target"] && !values["experimental-warm-cdn-cache"]) throw new Error("--warm-cdn-target requires --experimental-warm-cdn-cache.");
 	function parseIntArg(name, raw) {
 		if (!raw) return void 0;
 		const n = parseInt(raw, 10);
@@ -117,18 +182,31 @@ function parseDeployArgs(args) {
 		config: values.config?.trim() || void 0,
 		skipBuild: values["skip-build"],
 		dryRun: values["dry-run"],
+		verbose: values.verbose,
 		prerenderAll: values["prerender-all"],
 		prerenderConcurrency: values["prerender-concurrency"] === void 0 ? void 0 : parsePositiveIntegerArg(values["prerender-concurrency"], "--prerender-concurrency"),
 		warmCdnCache: values["experimental-warm-cdn-cache"],
+		warmCdnTarget: values["warm-cdn-target"] === void 0 ? void 0 : validateCdnWarmTarget(values["warm-cdn-target"]),
 		warmCdnConcurrency: values["warm-cdn-concurrency"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-concurrency"], "--warm-cdn-concurrency"),
 		warmCdnTimeout: values["warm-cdn-timeout"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-timeout"], "--warm-cdn-timeout"),
 		warmCdnRetries: values["warm-cdn-retries"] === void 0 ? void 0 : parseNonNegativeIntegerArg(values["warm-cdn-retries"], "--warm-cdn-retries"),
-		warmCdnStrict: values["warm-cdn-strict"],
+		warmCdnDiscoveryTimeout: values["warm-cdn-discovery-timeout"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-discovery-timeout"], "--warm-cdn-discovery-timeout"),
+		warmCdnDiscoveryRetries: values["warm-cdn-discovery-retries"] === void 0 ? void 0 : parseNonNegativeIntegerArg(values["warm-cdn-discovery-retries"], "--warm-cdn-discovery-retries"),
+		warmCdnProbeTimeout: values["warm-cdn-probe-timeout"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-probe-timeout"], "--warm-cdn-probe-timeout"),
+		warmCdnProbeRetries: values["warm-cdn-probe-retries"] === void 0 ? void 0 : parseNonNegativeIntegerArg(values["warm-cdn-probe-retries"], "--warm-cdn-probe-retries"),
+		warmCdnCertify: values["warm-cdn-certify"],
+		warmCdnReadinessTimeout: values["warm-cdn-readiness-timeout"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-readiness-timeout"], "--warm-cdn-readiness-timeout"),
+		warmCdnReadinessRetries: values["warm-cdn-readiness-retries"] === void 0 ? void 0 : parseNonNegativeIntegerArg(values["warm-cdn-readiness-retries"], "--warm-cdn-readiness-retries"),
+		warmCdnReadinessProbes: values["warm-cdn-readiness-probes"] === void 0 ? void 0 : parsePositiveIntegerArg(values["warm-cdn-readiness-probes"], "--warm-cdn-readiness-probes"),
+		warmCdnReadinessProbeDelay: values["warm-cdn-readiness-probe-delay"] === void 0 ? void 0 : validateTimerDelay(parseNonNegativeIntegerArg(values["warm-cdn-readiness-probe-delay"], "--warm-cdn-readiness-probe-delay"), "--warm-cdn-readiness-probe-delay", values["warm-cdn-readiness-probe-delay"]),
+		dangerouslyPromoteOnCdnWarmError: values["dangerously-promote-on-cdn-warm-error"],
+		warmCdnPromote: !values["no-promote"] && !values["warm-cdn-no-promote"],
+		warmCdnPromotionDelay: values["warm-cdn-promotion-delay"] === void 0 ? void 0 : validatePromotionDelay(parseNonNegativeIntegerArg(values["warm-cdn-promotion-delay"], "--warm-cdn-promotion-delay"), values["warm-cdn-promotion-delay"]),
 		warmCdnIncludeFallbacks: values["warm-cdn-include-fallbacks"],
-		experimentalTPR: values["experimental-tpr"],
-		tprCoverage: parseIntArg("tpr-coverage", values["tpr-coverage"]),
-		tprLimit: parseIntArg("tpr-limit", values["tpr-limit"]),
-		tprWindow: parseIntArg("tpr-window", values["tpr-window"])
+		experimentalTPR: values["experimental-traffic-aware-warm-cache"] || values["experimental-tpr"],
+		tprCoverage: parseIntArg("traffic-aware-coverage", values["traffic-aware-coverage"] ?? values["tpr-coverage"]),
+		tprLimit: parseIntArg("traffic-aware-limit", values["traffic-aware-limit"] ?? values["tpr-limit"]),
+		tprWindow: parseIntArg("traffic-aware-window", values["traffic-aware-window"] ?? values["tpr-window"])
 	};
 }
 /**
@@ -164,13 +242,27 @@ async function loadProjectViteApi(root) {
 	}
 	return await (vitePath === "vite" ? import(vitePath) : import(pathToFileURL(vitePath).href));
 }
+async function loadProjectWranglerApi(root) {
+	const req = createRequire(path.join(root, "package.json"));
+	let wranglerPath;
+	try {
+		wranglerPath = req.resolve("wrangler");
+	} catch {
+		const cloudflarePluginPath = req.resolve("@cloudflare/vite-plugin");
+		wranglerPath = createRequire(cloudflarePluginPath).resolve("wrangler");
+	}
+	return await import(
+		/* @vite-ignore */
+		pathToFileURL(wranglerPath).href
+);
+}
 async function loadDeployViteConfigMetadata(root) {
 	const plugins = (await (await loadProjectViteApi(root)).loadConfigFromFile({
 		command: "build",
 		mode: "production"
 	}, void 0, root))?.config.plugins;
 	return {
-		cacheConfig: viteConfigHasCacheAdapter(root) ? await findVinextCacheConfigInPlugins(plugins) : null,
+		cacheConfig: await findVinextCacheConfigInPlugins(plugins),
 		nextConfig: await findVinextNextConfigInPlugins(plugins),
 		prerenderConfig: await findVinextPrerenderConfigInPlugins(plugins),
 		routeRootConfig: await findVinextRouteRootConfigInPlugins(plugins)
@@ -309,6 +401,7 @@ async function runWranglerKVBulkPut(root, options, execute = spawn, nodeExecutab
 	}
 }
 async function runWranglerDeploy(root, options, execute = spawn) {
+	if (options.promote === false) return runWranglerVersionUpload(root, options).previewUrl ?? "(Preview URL not detected in wrangler output)";
 	const spawnOptions = {
 		cwd: root,
 		stdio: [
@@ -344,90 +437,548 @@ async function runWranglerDeploy(root, options, execute = spawn) {
 			reject(/* @__PURE__ */ new Error(`Wrangler deploy failed with ${exitReason}.`));
 		});
 	});
-	return parseWorkersDevUrl(output) ?? "(URL not detected in wrangler output)";
+	return parseWorkerDeploymentUrl(output) ?? "(URL not detected in wrangler output)";
+}
+function hasCdnWarmRequests(plan) {
+	return plan.paths.length + (plan.pagesDataPaths?.length ?? 0) + (plan.routeHandlerPaths?.length ?? 0) + plan.rscPaths.length + plan.loadingShellPaths.length > 0;
+}
+function selectTPRWarmPlan(plan, traffic, coverage, limit) {
+	const canonical = (pathname) => normalizePathTrailingSlash(pathname, false);
+	const resolved = new Set(Object.entries(plan.routePatterns ?? {}).map(([pathname, route]) => canonical(route.cacheabilityProbe?.concretePathname ?? pathname)));
+	const requestsByPath = /* @__PURE__ */ new Map();
+	for (const { path, requests } of traffic) {
+		const pathname = canonical(path);
+		if (!resolved.has(pathname)) continue;
+		requestsByPath.set(pathname, (requestsByPath.get(pathname) ?? 0) + requests);
+	}
+	const selected = new Set(selectRoutes(Array.from(requestsByPath, ([path, requests]) => ({
+		path,
+		requests
+	})).sort((a, b) => b.requests - a.requests), coverage, limit).routes.map(({ path }) => path));
+	const includes = (pathname) => selected.has(canonical(plan.routePatterns?.[pathname]?.cacheabilityProbe?.concretePathname ?? pathname));
+	const filter = (pathnames) => pathnames?.filter(includes);
+	return {
+		...plan,
+		appPaths: filter(plan.appPaths),
+		loadingShellPaths: filter(plan.loadingShellPaths) ?? [],
+		pagesDataPaths: filter(plan.pagesDataPaths),
+		pagesPaths: filter(plan.pagesPaths),
+		paths: filter(plan.paths) ?? [],
+		routeHandlerPaths: filter(plan.routeHandlerPaths),
+		routePatterns: plan.routePatterns ? Object.fromEntries(Object.entries(plan.routePatterns).filter(([pathname]) => includes(pathname))) : void 0,
+		rscPaths: filter(plan.rscPaths) ?? []
+	};
+}
+function projectRequiresRouteCacheabilityProbeManifest(project, cacheConfig) {
+	return (project.isAppRouter || project.isPagesRouter) && requiresRouteCacheabilityProbeManifest(cacheConfig);
+}
+function cdnWarmTargetKey(target) {
+	return `${target.kind}\0${target.sourcePathname}`;
+}
+function requiredCdnWarmTargetKeys(plan, optionalTargetKeys) {
+	const keys = /* @__PURE__ */ new Set([
+		...plan.paths.map((pathname) => `html\0${pathname}`),
+		...plan.pagesDataPaths.map((pathname) => `pages-data\0${pathname}`),
+		...(plan.routeHandlerPaths ?? []).map((pathname) => `app-route\0${pathname}`),
+		...plan.rscPaths.map((pathname) => `rsc-full\0${pathname}`),
+		...plan.loadingShellPaths.map((pathname) => `rsc-loading-shell\0${pathname}`)
+	]);
+	if (optionalTargetKeys) for (const key of optionalTargetKeys) keys.delete(key);
+	return keys;
 }
 async function deployWithCdnWarmup(root, paths, options) {
-	const upload = runWranglerVersionUpload(root, options);
+	if (options.warmCdnTarget !== void 0) options = {
+		...options,
+		warmCdnTarget: validateCdnWarmTarget(options.warmCdnTarget)
+	};
+	if (options.warmCdnDiscoveryTimeout !== void 0) parsePositiveIntegerArg(String(options.warmCdnDiscoveryTimeout), "--warm-cdn-discovery-timeout");
+	if (options.warmCdnDiscoveryRetries !== void 0) parseNonNegativeIntegerArg(String(options.warmCdnDiscoveryRetries), "--warm-cdn-discovery-retries");
+	if (options.warmCdnProbeTimeout !== void 0) parsePositiveIntegerArg(String(options.warmCdnProbeTimeout), "--warm-cdn-probe-timeout");
+	if (options.warmCdnProbeRetries !== void 0) parseNonNegativeIntegerArg(String(options.warmCdnProbeRetries), "--warm-cdn-probe-retries");
+	if (options.warmCdnReadinessTimeout !== void 0) parsePositiveIntegerArg(String(options.warmCdnReadinessTimeout), "--warm-cdn-readiness-timeout");
+	if (options.warmCdnReadinessRetries !== void 0) parseNonNegativeIntegerArg(String(options.warmCdnReadinessRetries), "--warm-cdn-readiness-retries");
+	if (options.warmCdnReadinessProbes !== void 0) parsePositiveIntegerArg(String(options.warmCdnReadinessProbes), "--warm-cdn-readiness-probes");
+	if (options.warmCdnReadinessProbeDelay !== void 0) validateTimerDelay(options.warmCdnReadinessProbeDelay, "--warm-cdn-readiness-probe-delay");
+	if (options.warmCdnPromotionDelay !== void 0) validatePromotionDelay(options.warmCdnPromotionDelay);
+	if (options.cacheabilityProbe) return deployWithCacheabilityProbe(root, options);
+	return deployUploadedVersionWithCdnWarmup(root, paths, options);
+}
+async function deployUploadedVersionWithCdnWarmup(root, paths, options) {
+	const allowUnverifiedPromotion = options.dangerouslyPromoteOnCdnWarmError === true && options.warmCdnCertify !== true;
+	let deploymentId = options.deploymentId;
+	let expectedBuildId = options.expectedBuildId;
+	let expectedRscBuildId = options.expectedRscBuildId;
+	const hasPreparedWarmPlan = options.uploadedVersion !== void 0;
+	let warmPlanDiscovered = hasPreparedWarmPlan || options.discoverWarmPlan === void 0;
+	let remainingWarmPlan = {
+		loadingShellPaths: [...options.loadingShellPaths ?? []],
+		pagesDataPaths: [...options.pagesDataPaths ?? []],
+		paths: [...paths],
+		routeHandlerPaths: [...options.routeHandlerPaths ?? []],
+		routePatterns: options.routePatterns ? { ...options.routePatterns } : void 0,
+		rscPaths: [...options.rscPaths ?? []]
+	};
+	let discoveredWarmRequests = remainingWarmPlan.paths.length + remainingWarmPlan.pagesDataPaths.length + (remainingWarmPlan.routeHandlerPaths?.length ?? 0) + remainingWarmPlan.rscPaths.length + remainingWarmPlan.loadingShellPaths.length;
+	const prepareWarmPlan = (plan) => {
+		if (plan.paths.length === 0 && plan.pagesDataPaths.length === 0 && (plan.routeHandlerPaths?.length ?? 0) === 0 || expectedBuildId !== void 0) return plan;
+		if (!allowUnverifiedPromotion) {
+			const warmupKind = plan.paths.length > 0 ? "CDN HTML warmup" : plan.pagesDataPaths.length > 0 ? "CDN Pages data warmup" : "CDN Route Handler warmup";
+			throw new Error(`${warmupKind} requires a CDN adapter that declares build-identity response headers. Configure that adapter capability or deploy without --experimental-warm-cdn-cache.`);
+		}
+		console.warn(`  CDN warmup: skipping ${plan.paths.length} HTML, ${plan.pagesDataPaths.length} Pages data, and ${plan.routeHandlerPaths?.length ?? 0} Route Handler request(s) because the CDN adapter does not declare build-identity response headers.`);
+		return {
+			...plan,
+			pagesDataPaths: [],
+			paths: [],
+			routeHandlerPaths: []
+		};
+	};
+	const discoverWarmPlan = async (targetUrl, headers) => {
+		if (!options.discoverWarmPlan) return;
+		const discovered = await options.discoverWarmPlan({
+			headers,
+			targetUrl
+		});
+		const plan = options.selectWarmPlan?.(discovered) ?? discovered;
+		deploymentId = plan.deploymentId;
+		expectedBuildId = plan.buildIdentity;
+		expectedRscBuildId = plan.rscBuildId;
+		remainingWarmPlan = {
+			loadingShellPaths: [...plan.loadingShellPaths],
+			pagesDataPaths: [...plan.pagesDataPaths ?? []],
+			paths: [...plan.paths],
+			routeHandlerPaths: [...plan.routeHandlerPaths ?? []],
+			routePatterns: plan.routePatterns ? { ...plan.routePatterns } : void 0,
+			rscPaths: [...plan.rscPaths]
+		};
+		discoveredWarmRequests = remainingWarmPlan.paths.length + remainingWarmPlan.pagesDataPaths.length + (remainingWarmPlan.routeHandlerPaths?.length ?? 0) + remainingWarmPlan.rscPaths.length + remainingWarmPlan.loadingShellPaths.length;
+		warmPlanDiscovered = true;
+	};
+	if (!options.discoverWarmPlan || hasPreparedWarmPlan) remainingWarmPlan = prepareWarmPlan(remainingWarmPlan);
+	const upload = options.uploadedVersion ?? runWranglerVersionUpload(root, options);
+	const warmUploadedVersion = (targetUrl, headers, propagatingTarget = false, plan = {
+		loadingShellPaths: remainingWarmPlan.loadingShellPaths,
+		pagesDataPaths: remainingWarmPlan.pagesDataPaths,
+		paths: remainingWarmPlan.paths,
+		routeHandlerPaths: remainingWarmPlan.routeHandlerPaths,
+		routePatterns: remainingWarmPlan.routePatterns,
+		rscPaths: remainingWarmPlan.rscPaths
+	}, requireCacheHit = false) => warmCdnCache({
+		targetUrl,
+		paths: plan.paths,
+		headers,
+		propagatingTarget,
+		deploymentId,
+		expectedBuildId,
+		expectedRscBuildId,
+		loadingShellPaths: plan.loadingShellPaths,
+		pagesDataPaths: plan.pagesDataPaths,
+		routeHandlerPaths: plan.routeHandlerPaths,
+		routePatterns: plan.routePatterns,
+		rscPaths: plan.rscPaths,
+		concurrency: options.warmCdnConcurrency,
+		timeoutMs: options.warmCdnTimeout,
+		retries: options.warmCdnRetries,
+		retrySkippedTargetKeys: propagatingTarget && hasPreparedWarmPlan ? requiredCdnWarmTargetKeys(plan, options.optionalWarmTargetKeys) : void 0,
+		requireCacheHit,
+		strict: requireCacheHit || !allowUnverifiedPromotion,
+		statusSource: options.statusSource
+	});
 	const wranglerConfig = parseWranglerConfig(root, options.config);
-	const stagingTraffic = getZeroPercentStagingTraffic(readWranglerDeploymentStatus(root, options), upload.versionId);
+	let deploymentStatus;
+	try {
+		deploymentStatus = runWranglerDeploymentStatus(root, options);
+	} catch (error) {
+		if (!hasPreparedWarmPlan) throw error;
+		throw new StagedWarmupError(formatUnknownError(error), { cause: error });
+	}
+	if (options.expectedDeploymentState && !deploymentStateEquals(deploymentStatus, options.expectedDeploymentState)) throw new StagedWarmupError("Two-stage CDN warming stopped because Worker deployment traffic or deployment identity changed before the final version could be staged. No final version was promoted.");
+	const stagingTraffic = getZeroPercentStagingTraffic(deploymentStatus, upload.versionId);
+	if (hasPreparedWarmPlan && !stagingTraffic) throw new StagedWarmupError("Two-stage CDN warming stopped because Worker deployment traffic changed before the final version could be staged. No final version was promoted.");
 	let staged = null;
-	let triggersDeployedUrl = null;
-	let warmedBeforePromotion = false;
-	let triggersApplied = false;
+	let triggersDeployedUrl = options.triggersDeployedUrl ?? null;
+	let stagedCacheFilled = false;
+	let stagedDeploymentState = null;
+	const initialWarmRequests = options.discoverWarmPlan === void 0 || hasPreparedWarmPlan ? remainingWarmPlan.paths.length + remainingWarmPlan.pagesDataPaths.length + (remainingWarmPlan.routeHandlerPaths?.length ?? 0) + remainingWarmPlan.rscPaths.length + remainingWarmPlan.loadingShellPaths.length : 1;
+	let triggersApplied = options.triggersAlreadyApplied === true;
 	function applyTriggers() {
 		if (triggersApplied) return;
 		triggersDeployedUrl = runWranglerTriggersDeploy(root, options).deployedUrl;
 		triggersApplied = true;
 	}
 	if (stagingTraffic) {
-		staged = runWranglerVersionDeploy(root, stagingTraffic, options, "stage");
 		try {
+			staged = runWranglerVersionDeploy(root, stagingTraffic, options, "stage");
+		} catch (error) {
+			throw reconcileVersionDeployFailure(root, options, error, {
+				desiredTraffic: stagingTraffic,
+				desiredDescription: "The uploaded version is staged at 0% with the previous version still serving 100% traffic; Worker triggers/routes were not changed.",
+				priorState: deploymentStatus,
+				priorDescription: "Worker deployment traffic was not changed and Worker triggers/routes were not changed."
+			});
+		}
+		try {
+			if (hasPreparedWarmPlan) {
+				stagedDeploymentState = runWranglerDeploymentStatus(root, options);
+				if (!deploymentTrafficEquals(stagedDeploymentState.versions, stagingTraffic)) throw new Error("Two-stage CDN warming stopped because Worker deployment traffic changed before production triggers could be applied. No final version was promoted.");
+			}
 			applyTriggers();
 		} catch (error) {
 			throw withStagedVersionCleanupNote(error);
 		}
-		const targetUrl = resolveCdnWarmupTargetUrl(root, staged.deployedUrl ?? triggersDeployedUrl, options);
-		const headers = buildVersionOverrideHeaders(resolveWorkerNameForVersionOverride(wranglerConfig, options), upload.versionId);
-		if (targetUrl && headers) {
-			try {
-				await warmCdnCache({
+		const targetUrl = resolveCdnWarmupTargetUrl(root, triggersDeployedUrl, options) ?? staged.deployedUrl;
+		const headers = buildVersionOverrideHeaders(options.name ?? upload.workerName ?? resolveWorkerNameForVersionOverride(wranglerConfig, options), upload.versionId);
+		if (targetUrl && headers) try {
+			if (!warmPlanDiscovered) {
+				console.log("  CDN warmup: discovering paths from the staged Worker version...");
+				await discoverWarmPlan(targetUrl, headers);
+				remainingWarmPlan = prepareWarmPlan(remainingWarmPlan);
+				console.log(`  CDN warmup: discovered ${remainingWarmPlan.paths.length} HTML, ${remainingWarmPlan.pagesDataPaths.length} Pages data, ${remainingWarmPlan.routeHandlerPaths?.length ?? 0} Route Handler, ${remainingWarmPlan.rscPaths.length} RSC, and ${remainingWarmPlan.loadingShellPaths.length} loading-shell request(s).`);
+			}
+			const stagedWarmPlan = {
+				loadingShellPaths: remainingWarmPlan.loadingShellPaths,
+				pagesDataPaths: remainingWarmPlan.pagesDataPaths,
+				paths: remainingWarmPlan.paths,
+				routeHandlerPaths: remainingWarmPlan.routeHandlerPaths,
+				routePatterns: remainingWarmPlan.routePatterns,
+				rscPaths: remainingWarmPlan.rscPaths
+			};
+			const stagedWarmRequests = stagedWarmPlan.paths.length + stagedWarmPlan.pagesDataPaths.length + (stagedWarmPlan.routeHandlerPaths?.length ?? 0) + stagedWarmPlan.rscPaths.length + stagedWarmPlan.loadingShellPaths.length;
+			if (stagedWarmRequests > 0) {
+				console.log("  CDN warmup: waiting for the staged Worker version to become stable...");
+				const readiness = await waitForCdnWarmTargetReadiness({
 					targetUrl,
-					paths,
 					headers,
-					concurrency: options.warmCdnConcurrency,
-					timeoutMs: options.warmCdnTimeout,
-					retries: options.warmCdnRetries,
-					strict: options.warmCdnStrict
+					plan: stagedWarmPlan,
+					prerenderSecret: options.prerenderSecret,
+					deploymentId,
+					expectedBuildId,
+					expectedRscBuildId,
+					phaseTimeoutMs: options.warmCdnReadinessTimeout,
+					probeIntervalMs: options.warmCdnReadinessProbeDelay,
+					requiredConsecutiveSuccesses: options.warmCdnReadinessProbes,
+					retries: options.warmCdnReadinessRetries ?? options.warmCdnRetries,
+					timeoutMs: options.warmCdnTimeout
 				});
+				if (!readiness.ready) {
+					const message = `CDN warmup could not verify staged Worker readiness: ${readiness.error}.`;
+					const noPromoteNote = options.warmCdnPromote === false ? " CDN warmup cannot continue because promotion is disabled and the staged version was not warmed." : "";
+					if (!allowUnverifiedPromotion || options.warmCdnPromote === false) throw new Error(`${message}${noPromoteNote}`);
+					console.warn(`  ${message} Promoting because the dangerous override is enabled.`);
+				} else {
+					console.log("  CDN warmup: staged Worker version is stable.");
+					const warmResult = await warmUploadedVersion(targetUrl, headers, true, stagedWarmPlan);
+					const optionalSkipped = options.optionalWarmTargetKeys ? warmResult.skippedTargets.filter((target) => options.optionalWarmTargetKeys.has(cdnWarmTargetKey(target))).length : 0;
+					if (hasPreparedWarmPlan && options.warmCdnCertify) {
+						if (warmResult.warmed + optionalSkipped !== stagedWarmRequests) throw new Error(`CDN warmup cannot certify the staged cache because only ${warmResult.warmed}/${stagedWarmRequests - optionalSkipped} cacheable entries completed their initial fill.`);
+					}
+					const requiredSkipped = warmResult.skipped - optionalSkipped;
+					if (hasPreparedWarmPlan && requiredSkipped > 0) {
+						const message = `Two-stage CDN warming could not fill ${requiredSkipped}/${warmResult.total} planned cache entries because Cloudflare refused cache admission.`;
+						if (!allowUnverifiedPromotion) throw new Error(message);
+						console.warn(`  ${message} Promoting because the dangerous override is enabled.`);
+					}
+					if (optionalSkipped > 0) console.log(`  CDN warmup: ${optionalSkipped} paired representation${optionalSkipped === 1 ? " remained" : "s remained"} private after ${optionalSkipped === 1 ? "its" : "their"} final render and will not be cached.`);
+					remainingWarmPlan = {
+						loadingShellPaths: warmResult.retryPlan.loadingShellPaths,
+						pagesDataPaths: warmResult.retryPlan.pagesDataPaths,
+						paths: warmResult.retryPlan.paths,
+						routeHandlerPaths: warmResult.retryPlan.routeHandlerPaths,
+						rscPaths: warmResult.retryPlan.rscPaths
+					};
+					if (options.warmCdnCertify && warmResult.warmed > 0) {
+						console.log(`  CDN warmup: certifying ${warmResult.warmed} staged cache entr${warmResult.warmed === 1 ? "y" : "ies"} before promotion...`);
+						const certification = await warmUploadedVersion(targetUrl, headers, true, warmResult.warmedPlan, true);
+						if (certification.warmed !== warmResult.warmed) throw new Error(`CDN warmup certified ${certification.warmed}/${warmResult.warmed} staged cache entries as reusable.`);
+						stagedCacheFilled = true;
+					} else stagedCacheFilled = warmResult.warmed > 0;
+				}
+			}
+		} catch (error) {
+			throw withStagedVersionCleanupNote(error);
+		}
+		else if (initialWarmRequests > 0) {
+			const message = "CDN warmup failed: pre-traffic warmup needs a production URL and Worker name for version overrides. Configure a route/custom domain and Worker name, or deploy without --experimental-warm-cdn-cache.";
+			if (!allowUnverifiedPromotion) throw new StagedWarmupError(`${message} ${getStagedVersionCleanupNote()}`);
+			console.warn(`  ${message} Promoting because the dangerous override is enabled.`);
+		}
+	} else {
+		if (initialWarmRequests > 0) {
+			const message = "CDN warmup cannot stage the uploaded Worker at 0% because the current deployment is not exactly one version serving 100% traffic.";
+			if (!allowUnverifiedPromotion) throw new Error(`${message} No traffic or triggers were changed.`);
+			console.warn(`  ${message} Promoting because the dangerous override is enabled.`);
+		}
+		console.warn("  CDN warmup: pre-traffic version override skipped because the current deployment is not one version serving 100% traffic.");
+	}
+	const countRemainingWarmRequests = () => remainingWarmPlan.paths.length + remainingWarmPlan.pagesDataPaths.length + (remainingWarmPlan.routeHandlerPaths?.length ?? 0) + remainingWarmPlan.rscPaths.length + remainingWarmPlan.loadingShellPaths.length;
+	if (options.warmCdnPromote === false) {
+		if (!staged) throw new Error("CDN warmup cannot skip promotion because the uploaded Worker version could not be staged at 0% traffic. The current deployment must have exactly one version serving 100% traffic.");
+		const remainingWarmRequests = countRemainingWarmRequests();
+		if (!options.allowEmptyWarmPlan && !hasPreparedWarmPlan && options.discoverWarmPlan && discoveredWarmRequests === 0) throw withStagedVersionCleanupNote(/* @__PURE__ */ new Error("CDN warmup cannot skip promotion because no build-discovered requests were found to warm."));
+		if (remainingWarmRequests > 0) throw withStagedVersionCleanupNote(/* @__PURE__ */ new Error(`CDN warmup cannot skip promotion because ${remainingWarmRequests} request(s) remain unwarmed.`));
+		if (hasPreparedWarmPlan && stagedDeploymentState) {
+			let currentDeployment;
+			try {
+				currentDeployment = runWranglerDeploymentStatus(root, options);
 			} catch (error) {
-				throw withStagedVersionCleanupNote(error);
+				throw new StagedWarmupError(`${error instanceof Error ? error.message : String(error)} CDN warmup cannot confirm that the uploaded Worker remains staged at 0% traffic; production Worker triggers/routes remain applied. Inspect \`wrangler deployments status\` before continuing.`, { cause: error });
 			}
-			warmedBeforePromotion = true;
-		} else if (options.warmCdnStrict) throw new Error("CDN warmup failed: pre-traffic warmup needs a production URL and Worker name for version overrides. Configure a route/custom domain and Worker name, or rerun without --warm-cdn-strict. " + getStagedVersionCleanupNote());
-	} else console.warn("  CDN warmup: pre-traffic version override skipped because the current deployment is not a single 100% version.");
-	const deployed = runWranglerVersionDeploy(root, [{
+			if (!deploymentStateEquals(currentDeployment, stagedDeploymentState)) throw new StagedWarmupError("Two-stage CDN warming stopped because Worker deployment traffic or deployment identity changed before the no-promote handoff. The uploaded Worker is not confirmed staged at 0% traffic; production Worker triggers/routes remain applied.");
+		}
+		console.log(`  CDN warmup: promotion disabled; uploaded Worker version ${upload.versionId} remains staged at 0% traffic and production Worker triggers/routes remain applied.`);
+		return staged.deployedUrl ?? triggersDeployedUrl ?? upload.previewUrl ?? "(URL not detected in wrangler output)";
+	}
+	let deployed;
+	let prePromotionState = null;
+	const promotionTraffic = [{
 		versionId: upload.versionId,
 		percentage: 100
-	}], options, warmedBeforePromotion ? "promote-warmed" : "promote-uploaded");
-	if (!warmedBeforePromotion) {
-		try {
-			applyTriggers();
-		} catch (error) {
-			throw withPromotedVersionTriggerNote(error);
+	}];
+	let promotionAttempted = false;
+	try {
+		if (stagedCacheFilled && options.statusSource !== "vinext") {
+			const promotionDelay = options.warmCdnPromotionDelay ?? 15e3;
+			if (promotionDelay > 0) {
+				console.log(`  CDN warmup: waiting ${promotionDelay / 1e3} seconds for cache propagation before promotion...`);
+				await setTimeout(promotionDelay);
+			}
+		}
+		if (hasPreparedWarmPlan && stagingTraffic) {
+			prePromotionState = runWranglerDeploymentStatus(root, options);
+			if (!deploymentTrafficEquals(prePromotionState.versions, stagingTraffic) || stagedDeploymentState && !deploymentStateEquals(prePromotionState, stagedDeploymentState)) throw new Error("Two-stage CDN warming stopped because Worker deployment traffic or deployment identity changed before the final version could be promoted. No final version was promoted.");
 		}
-		const targetUrl = resolveCdnWarmupTargetUrl(root, deployed.deployedUrl ?? triggersDeployedUrl, options);
-		if (targetUrl) await warmCdnCache({
-			targetUrl,
-			paths,
-			concurrency: options.warmCdnConcurrency,
-			timeoutMs: options.warmCdnTimeout,
-			retries: options.warmCdnRetries,
-			strict: options.warmCdnStrict
+		promotionAttempted = true;
+		deployed = runWranglerVersionDeploy(root, promotionTraffic, options, stagedCacheFilled ? "promote-warmed" : "promote-uploaded");
+	} catch (error) {
+		if (promotionAttempted) throw reconcileVersionDeployFailure(root, options, error, {
+			desiredTraffic: promotionTraffic,
+			desiredDescription: "The uploaded version is already promoted to 100%; Worker triggers/routes may already have changed.",
+			priorState: prePromotionState ?? (stagingTraffic ? {
+				deploymentId: null,
+				output: "",
+				versions: stagingTraffic
+			} : deploymentStatus),
+			priorDescription: "The uploaded version remains staged at 0% with the previous version still serving 100% traffic; Worker triggers/routes may already have changed."
 		});
-		else if (options.warmCdnStrict) throw new Error("CDN warmup failed: no production URL could be inferred from wrangler config or output. Configure a route/custom domain, ensure Wrangler prints a workers.dev URL, or rerun without --warm-cdn-strict.");
-		else console.warn("  CDN warmup skipped: no production URL could be inferred from wrangler config or output.");
+		throw staged ? withStagedVersionCleanupNote(error) : error;
+	}
+	try {
+		applyTriggers();
+	} catch (error) {
+		throw withPromotedVersionTriggerNote(error);
+	}
+	let postPromotionTargetUrl = resolveCdnWarmupTargetUrl(root, triggersDeployedUrl, options) ?? deployed.deployedUrl;
+	if (!warmPlanDiscovered && postPromotionTargetUrl) try {
+		console.log("  CDN warmup: discovering paths from the promoted Worker version...");
+		await discoverWarmPlan(postPromotionTargetUrl);
+		remainingWarmPlan = prepareWarmPlan(remainingWarmPlan);
+	} catch (error) {
+		throw withPromotedVersionWarmupNote(error);
+	}
+	if (countRemainingWarmRequests() > 0) {
+		const targetUrl = postPromotionTargetUrl;
+		if (targetUrl) try {
+			await warmUploadedVersion(targetUrl, void 0, true, remainingWarmPlan);
+		} catch (error) {
+			throw withPromotedVersionWarmupNote(error);
+		}
+		else if (!allowUnverifiedPromotion) throw withPromotedVersionWarmupNote(/* @__PURE__ */ new Error("CDN warmup failed: no production URL could be inferred from wrangler config or output. Configure a route/custom domain, ensure Wrangler prints a workers.dev URL, or deploy without --experimental-warm-cdn-cache."));
+		else console.warn("  CDN warmup skipped: no production URL could be inferred after promotion; the dangerous override was enabled.");
 	}
 	return deployed.deployedUrl ?? triggersDeployedUrl ?? staged?.deployedUrl ?? upload.previewUrl ?? "(URL not detected in wrangler output)";
 }
-function resolveCdnWarmupTargetUrl(root, deployedUrl, options) {
-	const config = parseWranglerConfig(root, options?.config);
-	const env = getWranglerTargetEnv(options ?? {});
-	const customDomain = (env ? config?.env?.[env]?.customDomain : void 0) ?? config?.customDomain;
-	if (customDomain) return `https://${customDomain}`;
-	return deployedUrl;
+function deploymentTrafficEquals(actual, expected) {
+	const normalize = (traffic) => [...traffic].sort((a, b) => a.versionId.localeCompare(b.versionId));
+	const normalizedActual = normalize(actual);
+	const normalizedExpected = normalize(expected);
+	return normalizedActual.length === normalizedExpected.length && normalizedActual.every((version, index) => version.versionId === normalizedExpected[index]?.versionId && version.percentage === normalizedExpected[index]?.percentage);
+}
+function deploymentStateEquals(actual, expected) {
+	if (expected.deploymentId !== null && actual.deploymentId !== expected.deploymentId) return false;
+	return deploymentTrafficEquals(actual.versions, expected.versions);
 }
-function readWranglerDeploymentStatus(root, options) {
+function reconcileVersionDeployFailure(root, options, error, expected) {
+	const message = error instanceof Error ? error.message : String(error);
+	let reconciliation;
+	let mayNeedCleanup = true;
 	try {
-		return runWranglerDeploymentStatus(root, options);
-	} catch {
-		return null;
+		const current = runWranglerDeploymentStatus(root, options);
+		if (deploymentTrafficEquals(current.versions, expected.desiredTraffic)) reconciliation = expected.desiredDescription;
+		else if (deploymentStateEquals(current, expected.priorState)) {
+			reconciliation = expected.priorDescription;
+			mayNeedCleanup = false;
+		} else reconciliation = "Worker deployment state differs from both the requested and prior state, so the deployment outcome is unknown or another deployment changed it.";
+	} catch (reconciliationError) {
+		reconciliation = `Worker deployment status could not be read after the command failed, so the deployment outcome is unknown (${reconciliationError instanceof Error ? reconciliationError.message : String(reconciliationError)}).`;
 	}
+	const detail = `${message} ${reconciliation}`;
+	return mayNeedCleanup ? new StagedWarmupError(detail, { cause: error }) : new Error(detail, { cause: error });
+}
+function assertDeploymentStateUnchanged(root, options, expected, message) {
+	if (!deploymentStateEquals(runWranglerDeploymentStatus(root, options), expected)) throw new Error(message);
+}
+async function deployWithCacheabilityProbe(root, options) {
+	if (!options.discoverWarmPlan) throw new Error("Two-stage CDN warming requires staged Worker route discovery before cacheability probing.");
+	const prerenderSecret = readPrerenderSecret(root);
+	const probeUpload = runWranglerVersionUpload(root, options);
+	const initialDeployment = runWranglerDeploymentStatus(root, options);
+	const probeTraffic = getZeroPercentStagingTraffic(initialDeployment, probeUpload.versionId);
+	if (!probeTraffic) throw new Error("Two-stage CDN warming cannot stage the probe Worker at 0% because the current deployment is not exactly one version serving 100% traffic. No traffic or triggers were changed.");
+	let stagedProbe;
+	try {
+		stagedProbe = runWranglerVersionDeploy(root, probeTraffic, options, "stage");
+	} catch (error) {
+		throw reconcileVersionDeployFailure(root, options, error, {
+			desiredTraffic: probeTraffic,
+			desiredDescription: "The probe version is staged at 0% with the previous version still serving 100% traffic; production Worker triggers/routes were not changed.",
+			priorState: initialDeployment,
+			priorDescription: "Worker deployment traffic was not changed and production Worker triggers/routes were not changed."
+		});
+	}
+	let stagedProbeDeployment;
+	try {
+		stagedProbeDeployment = runWranglerDeploymentStatus(root, options);
+		if (!deploymentTrafficEquals(stagedProbeDeployment.versions, probeTraffic)) throw new Error("Two-stage CDN warming stopped because Worker deployment traffic changed immediately after the probe version was staged.");
+	} catch (error) {
+		throw new StagedWarmupError(`${error instanceof Error ? error.message : String(error)} The probe staging command completed, but its current deployment state could not be confirmed; production Worker triggers/routes were not changed. Inspect \`wrangler deployments status\` and remove the staged probe version if necessary.`, { cause: error });
+	}
+	let prepared;
+	try {
+		const targetUrl = resolveCdnWarmupTargetUrl(root, stagedProbe.deployedUrl ?? probeUpload.previewUrl, options);
+		const wranglerConfig = parseWranglerConfig(root, options.config);
+		const headers = buildVersionOverrideHeaders(options.name ?? probeUpload.workerName ?? resolveWorkerNameForVersionOverride(wranglerConfig, options), probeUpload.versionId);
+		if (!targetUrl || !headers) throw new Error("Two-stage CDN warming needs a production URL and Worker name for version-overridden cacheability probes.");
+		console.log("  CDN warmup: discovering paths from the staged probe Worker...");
+		const discovered = await options.discoverWarmPlan({
+			headers,
+			targetUrl
+		});
+		if (!discovered.buildId) throw new Error("Two-stage CDN warming requires the staged discovery result to match dist/server/BUILD_ID.");
+		if (!discovered.buildIdentity) throw new Error("Two-stage CDN warming requires a CDN adapter that exposes the application build identity.");
+		const plan = {
+			...discovered,
+			appPaths: discovered.appPaths ? [...discovered.appPaths] : void 0,
+			fallbackRoutePatterns: discovered.fallbackRoutePatterns ? [...discovered.fallbackRoutePatterns] : void 0,
+			loadingShellPaths: [...discovered.loadingShellPaths],
+			pagesDataPaths: [...discovered.pagesDataPaths ?? []],
+			pagesPaths: discovered.pagesPaths ? [...discovered.pagesPaths] : void 0,
+			paths: [...discovered.paths],
+			routeHandlerPaths: [...discovered.routeHandlerPaths ?? []],
+			routePatterns: discovered.routePatterns ? { ...discovered.routePatterns } : void 0,
+			rscPaths: [...discovered.rscPaths]
+		};
+		if (!plan.appPaths && !plan.pagesPaths) throw new Error("Two-stage CDN warming requires staged discovery to report App or Pages route ownership.");
+		const ownedHtmlPaths = /* @__PURE__ */ new Set([...plan.appPaths ?? [], ...plan.pagesPaths ?? []]);
+		plan.paths = plan.paths.filter((pathname) => ownedHtmlPaths.has(pathname));
+		const targets = await createCdnWarmTargets({
+			deploymentId: plan.deploymentId,
+			headers,
+			loadingShellPaths: plan.loadingShellPaths,
+			pagesDataPaths: plan.pagesDataPaths,
+			paths: plan.paths,
+			routeHandlerPaths: plan.routeHandlerPaths,
+			routePatterns: plan.routePatterns,
+			rscPaths: plan.rscPaths
+		});
+		const routePatternCount = new Set(targets.flatMap((target) => target.route ? [`${target.route.kind}\0${target.route.pattern}`] : [])).size;
+		const concreteRoutePathCount = new Set(targets.flatMap((target) => target.route ? [`${target.route.kind}\0${target.route.pattern}\0${target.route.cacheabilityProbe?.concretePathname ?? cacheabilityRoutePathname(target.pathname, target.kind)}`] : [])).size;
+		if (targets.length > 0) {
+			console.log("  CDN warmup: waiting for the staged probe Worker to become stable...");
+			const readiness = await waitForCdnWarmTargetReadiness({
+				targetUrl,
+				headers,
+				plan,
+				prerenderSecret,
+				deploymentId: plan.deploymentId,
+				expectedBuildId: plan.buildIdentity,
+				expectedRscBuildId: plan.rscBuildId,
+				phaseTimeoutMs: options.warmCdnReadinessTimeout,
+				probeIntervalMs: options.warmCdnReadinessProbeDelay,
+				requiredConsecutiveSuccesses: options.warmCdnReadinessProbes,
+				retries: options.warmCdnReadinessRetries ?? options.warmCdnRetries,
+				timeoutMs: options.warmCdnTimeout
+			});
+			if (!readiness.ready) throw new Error(`Two-stage CDN warming could not verify staged probe Worker readiness: ${readiness.error}.`);
+			console.log(`  CDN warmup: probing ${concreteRoutePathCount} concrete route path${concreteRoutePathCount === 1 ? "" : "s"} once across ${routePatternCount} pattern${routePatternCount === 1 ? "" : "s"}; filtering ${targets.length} candidate warm request identit${targets.length === 1 ? "y" : "ies"}...`);
+		} else {
+			const fallbackPatternCount = plan.fallbackRoutePatterns?.length ?? 0;
+			console.log(fallbackPatternCount > 0 ? `  CDN warmup: embedding ${fallbackPatternCount} on-demand static route pattern${fallbackPatternCount === 1 ? "" : "s"} without a speculative render.` : "  CDN warmup: no page request identities were discovered; embedding an empty fail-closed cacheability manifest.");
+		}
+		const probeProgress = new CdnOperationProgress();
+		let probe;
+		try {
+			probe = await probeStagedWorkerCacheability({
+				buildId: discovered.buildId,
+				concurrency: options.warmCdnConcurrency,
+				expectedResponseBuildId: plan.buildIdentity,
+				fallbackRoutePatterns: plan.fallbackRoutePatterns,
+				phaseTimeoutMs: options.warmCdnProbeTimeout ?? 12e4,
+				retries: options.warmCdnProbeRetries ?? options.warmCdnRetries ?? 2,
+				retryDelayMs: DEFAULT_CACHEABILITY_PROBE_RETRY_DELAY_MS,
+				root,
+				targets,
+				targetUrl,
+				timeoutMs: options.warmCdnTimeout,
+				onProgress(progress) {
+					probeProgress.update(progress.completed, progress.total, `${progress.static} static, ${progress.dynamic} dynamic, ${progress.skipped} skipped`, "Probing route cacheability");
+				}
+			});
+		} finally {
+			probeProgress.finish();
+		}
+		console.log(`  CDN warmup: classified ${probe.classified} route pattern${probe.classified === 1 ? "" : "s"} with ${probe.probed} render probe${probe.probed === 1 ? "" : "s"}; ${probe.dynamic} observed dynamic and ${probe.skipped} excluded by pattern-wide proof.`);
+		if (probe.failures.length > 0) throw new Error(`Two-stage CDN warming failed to classify ${probe.failures.length}/${concreteRoutePathCount} concrete route paths after ${probe.probed} render probe(s). First failure: ${probe.failures[0]}`);
+		const finalPlan = {
+			...plan,
+			loadingShellPaths: probe.cacheableTargets.filter((target) => target.kind === "rsc-loading-shell").map((target) => target.sourcePathname),
+			pagesDataPaths: probe.cacheableTargets.filter((target) => target.kind === "pages-data").map((target) => target.sourcePathname),
+			paths: probe.cacheableTargets.filter((target) => target.kind === "html").map((target) => target.sourcePathname),
+			routeHandlerPaths: probe.cacheableTargets.filter((target) => target.kind === "app-route").map((target) => target.sourcePathname),
+			rscPaths: probe.cacheableTargets.filter((target) => target.kind === "rsc-full").map((target) => target.sourcePathname)
+		};
+		const selectedFinalPlan = options.selectWarmPlan?.(finalPlan) ?? finalPlan;
+		assertDeploymentStateUnchanged(root, options, stagedProbeDeployment, "Two-stage CDN warming stopped because Worker deployment traffic or deployment identity changed while cacheability was being probed. No final version was promoted.");
+		const finalConfig = writeCacheabilityManifestArtifact(root, options.config, probe.manifest);
+		const finalUpload = runWranglerVersionUpload(root, {
+			config: finalConfig,
+			env: options.env,
+			name: options.name,
+			preview: options.preview,
+			verbose: options.verbose
+		});
+		prepared = {
+			optionalWarmTargetKeys: new Set(probe.speculativeTargets.map(cdnWarmTargetKey)),
+			prerenderSecret,
+			plan: selectedFinalPlan,
+			upload: finalUpload
+		};
+	} catch (error) {
+		throw withStagedProbeVersionCleanupNote(error);
+	}
+	return deployUploadedVersionWithCdnWarmup(root, prepared.plan.paths, {
+		...options,
+		deploymentId: prepared.plan.deploymentId,
+		expectedBuildId: prepared.plan.buildIdentity,
+		expectedRscBuildId: prepared.plan.rscBuildId,
+		expectedDeploymentState: stagedProbeDeployment,
+		loadingShellPaths: prepared.plan.loadingShellPaths,
+		optionalWarmTargetKeys: prepared.optionalWarmTargetKeys,
+		pagesDataPaths: prepared.plan.pagesDataPaths,
+		prerenderSecret: prepared.prerenderSecret,
+		routeHandlerPaths: prepared.plan.routeHandlerPaths,
+		routePatterns: prepared.plan.routePatterns,
+		rscPaths: prepared.plan.rscPaths,
+		uploadedVersion: prepared.upload
+	});
+}
+function resolveCdnWarmupTargetUrl(_root, deployedUrl, options) {
+	return options?.warmCdnTarget ?? deployedUrl;
 }
 function getZeroPercentStagingTraffic(deployment, versionId) {
-	const current = deployment?.versions ?? [];
-	if (current.length !== 1 || current[0].percentage !== 100) return null;
-	if (current[0].versionId === versionId) return null;
-	return [current[0], {
+	const serving = (deployment?.versions ?? []).filter((version) => version.percentage > 0);
+	if (serving.length !== 1 || serving[0].percentage !== 100) return null;
+	if (serving[0].versionId === versionId) return null;
+	return [serving[0], {
 		versionId,
 		percentage: 0
 	}];
@@ -447,20 +998,31 @@ function quoteStructuredHeaderString(value) {
 }
 function buildVersionOverrideHeaders(workerName, versionId) {
 	if (!workerName) return void 0;
-	return { "Cloudflare-Workers-Version-Overrides": `${workerName}=${quoteStructuredHeaderString(versionId)}` };
+	return {
+		"Cloudflare-Workers-Version-Overrides": `${workerName}=${quoteStructuredHeaderString(versionId)}`,
+		[VINEXT_EXPECTED_WORKER_VERSION_HEADER]: versionId
+	};
 }
 function withStagedVersionCleanupNote(error) {
-	const message = error instanceof Error ? error.message : String(error);
-	return new Error(`${message} ${getStagedVersionCleanupNote()}`, { cause: error });
+	return new StagedWarmupError(`${error instanceof Error ? error.message : String(error)} ${getStagedVersionCleanupNote()}`, { cause: error });
+}
+function withStagedProbeVersionCleanupNote(error) {
+	return new StagedWarmupError(`${error instanceof Error ? error.message : String(error)} The probe version may remain staged at 0% with the previous version still serving 100% traffic; production Worker triggers/routes were not changed.`, { cause: error });
 }
 function getStagedVersionCleanupNote() {
-	return "The uploaded version may remain staged at 0% with the previous version still serving 100% traffic; rerun deploy to promote it or use `wrangler versions deploy` to choose the desired version split.";
+	return "The uploaded version may remain staged at 0% with the previous version still serving 100% traffic; Worker triggers/routes may also have changed because trigger deployment runs before warming. Rerun deploy to promote it or use `wrangler versions deploy` to choose the desired version split.";
 }
 function withPromotedVersionTriggerNote(error) {
 	const message = error instanceof Error ? error.message : String(error);
 	return new Error(`${message} The uploaded version may already be promoted to 100%, but Worker triggers/routes may not be updated; rerun deploy or \`wrangler triggers deploy\` after fixing the trigger error.`, { cause: error });
 }
+function withPromotedVersionWarmupNote(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(`${message} The uploaded version is already promoted to 100% and its Worker triggers/routes were updated; rerun deploy to retry cache warming or roll back with \`wrangler versions deploy\`.`, { cause: error });
+}
 async function deploy(options) {
+	if (options.warmCdnTarget !== void 0 && !options.warmCdnCache) throw new Error("--warm-cdn-target requires --experimental-warm-cdn-cache.");
+	const warmCdnTarget = options.warmCdnTarget === void 0 ? void 0 : validateCdnWarmTarget(options.warmCdnTarget);
 	const deployEnv = validateWranglerEnvName(options.env || (options.preview ? "preview" : "production"));
 	const root = path.resolve(options.root);
 	loadDotenv({
@@ -495,9 +1057,11 @@ async function deploy(options) {
 	}
 	const buildEnv = deployEnv === "production" && !options.env ? void 0 : deployEnv;
 	const viteConfigMetadata = await withCloudflareEnv(buildEnv, () => loadDeployViteConfigMetadata(info.root));
+	const cdnAdapterConfig = resolveCdnAdapterConfig(viteConfigMetadata.cacheConfig);
 	const nextConfig = await withCloudflareEnv(buildEnv, async () => {
 		const inlineNextConfig = viteConfigMetadata.nextConfig;
-		return resolveNextConfig(inlineNextConfig ? await resolveNextConfigInput(inlineNextConfig, PHASE_PRODUCTION_BUILD) : await loadNextConfig(info.root, PHASE_PRODUCTION_BUILD), info.root);
+		const rawNextConfig = inlineNextConfig ? await resolveNextConfigInput(inlineNextConfig, PHASE_PRODUCTION_BUILD) : await loadNextConfig(info.root, PHASE_PRODUCTION_BUILD);
+		return resolveNextConfig(rawNextConfig, info.root);
 	});
 	const vinextPrerenderConfig = !options.prerenderAll && nextConfig.output !== "export" ? viteConfigMetadata.prerenderConfig : null;
 	const prerenderDecision = resolveVinextPrerenderDecision({
@@ -505,16 +1069,79 @@ async function deploy(options) {
 		vinextPrerenderConfig,
 		nextOutput: nextConfig.output
 	});
-	const shouldEmitPrerenderPathManifest = options.warmCdnCache || !options.skipBuild && prerenderDecision;
+	const hasStrictResponseVary = hasVerbatimResponseVary(viteConfigMetadata.cacheConfig);
+	const warmupStatusSource = cacheWarmupStatusSource(viteConfigMetadata.cacheConfig);
+	const hasStagedRequestRouting = hasUncachedRequestRouting(viteConfigMetadata.cacheConfig) || warmupStatusSource === "data-cache";
+	const hasBuildIdentityHeader = hasBuildIdentityResponseHeader(viteConfigMetadata.cacheConfig);
+	const hasCanonicalRscWarmup = supportsCanonicalRscWarmup(viteConfigMetadata.cacheConfig);
+	const needsCacheabilityProbeManifest = projectRequiresRouteCacheabilityProbeManifest(info, viteConfigMetadata.cacheConfig);
+	const shouldEmitPrerenderPathManifest = !options.skipBuild && prerenderDecision;
 	if (!options.skipBuild) await runBuild(info, buildEnv);
 	else console.log("\n  Skipping build (--skip-build)");
+	const canWarmTpr = options.experimentalTPR && !prerenderDecision && hasBuildIdentityHeader;
+	if (options.experimentalTPR && prerenderDecision) console.log("  TPR: Skipping route selection (all-route prerendering configured)");
+	else if (options.experimentalTPR && !hasBuildIdentityHeader) console.log(workerEntryHasCacheHandler(root) ? "  TPR: Skipping pre-warm (legacy imperative cache handlers must migrate to declarative vinext({ cache }) for standard warming)" : "  TPR: Skipping pre-warm (configured cache does not expose build identity)");
+	const tpr = canWarmTpr ? await resolveTPRRoutes({
+		root,
+		config: options.config,
+		env: buildEnv,
+		hostname: warmCdnTarget ? new URL(warmCdnTarget).hostname : void 0,
+		window: Math.max(1, options.tprWindow ?? 24)
+	}) : null;
+	if (tpr?.skipped) console.log(`  TPR: Skipped (${tpr.skipped})`);
+	const tprRoutes = tpr?.routes ?? [];
+	const wranglerOptions = {
+		env: deployEnv === "production" && !options.env ? void 0 : deployEnv,
+		name: options.name,
+		config: options.config,
+		verbose: options.verbose
+	};
+	let shouldWarmTpr = tprRoutes.length > 0;
+	if (shouldWarmTpr && !options.warmCdnCache) {
+		try {
+			shouldWarmTpr = getZeroPercentStagingTraffic(runWranglerDeploymentStatus(root, wranglerOptions), "tpr-preflight") !== null;
+		} catch {
+			shouldWarmTpr = false;
+		}
+		if (!shouldWarmTpr) console.log("  TPR: Skipping pre-warm (current deployment cannot be staged safely)");
+	}
+	const shouldWarmCdnCache = options.warmCdnCache || shouldWarmTpr;
+	const shouldSelectTpr = shouldWarmTpr && !options.warmCdnCache;
+	const candidatePathsOnly = shouldSelectTpr && !needsCacheabilityProbeManifest;
+	const shouldPrerenderLocally = prerenderDecision && (!shouldWarmCdnCache || prerenderDecision.reason === "next-export");
+	if (shouldWarmCdnCache && cdnAdapterConfig) {
+		const wrangler = await loadProjectWranglerApi(info.root);
+		const previousCwd = process.cwd();
+		try {
+			process.chdir(info.root);
+			const config = wrangler.unstable_readConfig({
+				config: options.config,
+				env: buildEnv
+			}, {
+				hideWarnings: true,
+				preserveOriginalMain: true,
+				useRedirectIfAvailable: true
+			});
+			assertCdnVersionMetadataConfig({
+				binding: cdnAdapterConfig.versionMetadataBinding,
+				configuredBinding: config.version_metadata?.binding,
+				configPath: config.configPath
+			});
+		} finally {
+			process.chdir(previousCwd);
+		}
+	}
 	if (shouldEmitPrerenderPathManifest) await emitPrerenderPathManifest({
 		root: info.root,
 		nextConfig,
+		buildIdentity: hasBuildIdentityHeader ? "response-header" : void 0,
+		requestRouting: hasStagedRequestRouting ? "uncached-stage" : void 0,
+		responseVary: hasStrictResponseVary ? "verbatim" : void 0,
+		isResponsePolicyHeader: (name) => isConfiguredCdnResponsePolicyHeader(viteConfigMetadata.cacheConfig, name),
 		routeRootConfig: viteConfigMetadata.routeRootConfig
 	});
 	let ranPrerender = false;
-	if (prerenderDecision) {
+	if (shouldPrerenderLocally) {
 		console.log(`\n  ${formatVinextPrerenderLabel(prerenderDecision)}`);
 		if (nextConfig.enablePrerenderSourceMaps) {
 			process.setSourceMapsEnabled(true);
@@ -523,7 +1150,8 @@ async function deploy(options) {
 		await runPrerender({
 			root: info.root,
 			concurrency: options.prerenderConcurrency,
-			nextConfig
+			nextConfig,
+			routeRootConfig: viteConfigMetadata.routeRootConfig
 		});
 		ranPrerender = true;
 	}
@@ -532,43 +1160,73 @@ async function deploy(options) {
 	} catch (error) {
 		console.log(`  KV cache: Skipping prerender upload (${formatUnknownError(error)}). Continuing with deploy.`);
 	}
-	if (options.experimentalTPR) {
-		console.log();
-		const tprResult = await runTPR({
-			root,
-			config: options.config,
-			coverage: Math.max(1, Math.min(100, options.tprCoverage ?? 90)),
-			limit: Math.max(1, options.tprLimit ?? 1e3),
-			window: Math.max(1, options.tprWindow ?? 24)
-		});
-		if (tprResult.skipped) console.log(`  TPR: Skipped (${tprResult.skipped})`);
-	}
-	const wranglerOptions = {
-		env: deployEnv === "production" && !options.env ? void 0 : deployEnv,
-		name: options.name,
-		config: options.config
-	};
 	let url;
-	if (options.warmCdnCache) {
-		const warmPaths = readPrerenderWarmPaths(root, {
-			includeFallbackShells: options.warmCdnIncludeFallbacks,
-			strict: options.warmCdnStrict
-		});
-		if (warmPaths.length > 0) url = await deployWithCdnWarmup(root, warmPaths, {
+	if (shouldWarmCdnCache) try {
+		url = await deployWithCdnWarmup(root, [], {
 			...wranglerOptions,
+			allowEmptyWarmPlan: tprRoutes.length > 0 && !options.warmCdnCache,
+			cacheabilityProbe: needsCacheabilityProbeManifest,
+			discoverWarmPlan: async ({ headers, targetUrl }) => {
+				const discovery = await discoverPrerenderPathManifest({
+					root: info.root,
+					candidatePaths: tprRoutes.map(({ path }) => path),
+					candidatePathsOnly,
+					nextConfig,
+					buildIdentity: hasBuildIdentityHeader ? "response-header" : void 0,
+					includeCanonicalRsc: hasCanonicalRscWarmup,
+					requestRouting: hasStagedRequestRouting ? "uncached-stage" : void 0,
+					responseVary: hasStrictResponseVary ? "verbatim" : void 0,
+					isResponsePolicyHeader: (name) => isConfiguredCdnResponsePolicyHeader(viteConfigMetadata.cacheConfig, name),
+					routeRootConfig: viteConfigMetadata.routeRootConfig,
+					pathDiscoveryTarget: {
+						baseUrl: targetUrl,
+						headers,
+						phaseTimeoutMs: options.warmCdnDiscoveryTimeout ?? DEFAULT_REMOTE_PATH_DISCOVERY_PHASE_TIMEOUT_MS,
+						retries: options.warmCdnDiscoveryRetries,
+						retryDelayMs: DEFAULT_REMOTE_PATH_DISCOVERY_RETRY_DELAY_MS
+					}
+				});
+				if (!discovery) return {
+					loadingShellPaths: [],
+					paths: [],
+					rscPaths: []
+				};
+				return createPrerenderWarmPlan(root, discovery, {
+					includeCanonicalRsc: hasCanonicalRscWarmup,
+					includeFallbackShells: options.warmCdnIncludeFallbacks,
+					strict: options.warmCdnCertify === true || !options.dangerouslyPromoteOnCdnWarmError
+				});
+			},
+			selectWarmPlan: shouldSelectTpr ? (plan) => selectTPRWarmPlan(plan, tprRoutes, Math.max(1, Math.min(100, options.tprCoverage ?? 90)), Math.max(1, options.tprLimit ?? 1e3)) : void 0,
+			statusSource: warmupStatusSource,
 			warmCdnConcurrency: options.warmCdnConcurrency,
+			warmCdnTarget,
 			warmCdnTimeout: options.warmCdnTimeout,
 			warmCdnRetries: options.warmCdnRetries,
-			warmCdnStrict: options.warmCdnStrict
+			warmCdnDiscoveryTimeout: options.warmCdnDiscoveryTimeout,
+			warmCdnDiscoveryRetries: options.warmCdnDiscoveryRetries,
+			warmCdnProbeTimeout: options.warmCdnProbeTimeout,
+			warmCdnProbeRetries: options.warmCdnProbeRetries,
+			warmCdnCertify: options.warmCdnCertify,
+			warmCdnReadinessTimeout: options.warmCdnReadinessTimeout,
+			warmCdnReadinessRetries: options.warmCdnReadinessRetries,
+			warmCdnReadinessProbes: options.warmCdnReadinessProbes,
+			warmCdnReadinessProbeDelay: options.warmCdnReadinessProbeDelay,
+			dangerouslyPromoteOnCdnWarmError: options.dangerouslyPromoteOnCdnWarmError,
+			warmCdnPromote: options.warmCdnPromote,
+			warmCdnPromotionDelay: options.warmCdnPromotionDelay
 		});
-		else {
-			console.log("\n  CDN warmup skipped: no build-discovered paths found.");
-			url = await runWranglerDeploy(root, wranglerOptions);
-		}
-	} else url = await runWranglerDeploy(root, wranglerOptions);
+	} catch (error) {
+		if (options.warmCdnCache || options.warmCdnPromote === false && error instanceof StagedWarmupError) throw error;
+		console.log(`  TPR: Skipping pre-warm (${formatUnknownError(error)}). Continuing with deploy.`);
+	}
+	if (url === void 0) url = await runWranglerDeploy(root, {
+		...wranglerOptions,
+		promote: options.warmCdnPromote
+	});
 	console.log("\n  ─────────────────────────────────────────");
-	console.log(`  Deployed to: ${url}`);
+	console.log(`  ${options.warmCdnPromote === false ? "Version URL" : "Deployed to"}: ${url}`);
 	console.log("  ─────────────────────────────────────────\n");
 }
 //#endregion
-export { buildNodeCliInvocation, buildVersionOverrideHeaders, buildWranglerDeployArgs, buildWranglerInvocation, buildWranglerKVBulkPutArgs, deploy, deployWithCdnWarmup, getZeroPercentStagingTraffic, parseDeployArgs, resolveCdnWarmupTargetUrl, resolveWorkerNameForVersionOverride, resolveWranglerBin, runWranglerDeploy, runWranglerKVBulkPut, validateWranglerEnvName, withCloudflareEnv };
+export { DEFAULT_CDN_WARM_PROMOTION_DELAY_MS, buildNodeCliInvocation, buildVersionOverrideHeaders, buildWranglerDeployArgs, buildWranglerInvocation, buildWranglerKVBulkPutArgs, deploy, deployWithCdnWarmup, getZeroPercentStagingTraffic, hasCdnWarmRequests, parseDeployArgs, projectRequiresRouteCacheabilityProbeManifest, resolveCdnWarmupTargetUrl, resolveWorkerNameForVersionOverride, resolveWranglerBin, runWranglerDeploy, runWranglerKVBulkPut, selectTPRWarmPlan, validateWranglerEnvName, withCloudflareEnv };