@vinext/cloudflare 1.0.0-beta.6 → 1.0.0-beta.7

package/README.md

@@ -45,6 +45,9 @@ export default defineConfig({
   "cache": {
     "enabled": true,
   },
+  "version_metadata": {
+    "binding": "CF_VERSION_METADATA",
+  },
 }
 ```
 
@@ -54,6 +57,20 @@ import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
 vinext({ cache: { cdn: cdnAdapter() } });
 ```
 
+The version metadata binding lets staged warmup prove that every discovery,
+probe, and fill request reached the uploaded Worker version. Wrangler named
+environments do not inherit `version_metadata`; repeat the binding inside every
+`env.<name>` used with CDN warming.
+
+Use `--experimental-warm-cdn-cache` for the two-stage deploy. The default flow
+makes one final fill request per admitted identity. Add `--warm-cdn-certify`
+only when you want an opt-in second, header-only request that must prove every
+planned entry reusable before promotion.
+
+Do not configure a Cache Rule that ignores or normalizes query strings for
+these responses. The two-stage cacheability manifest authorizes the full
+pathname + query identity, but an edge HIT happens before Worker admission.
+
 ## Deploy
 
 Deploy Cloudflare Workers projects with the package CLI:

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

@@ -0,0 +1,22 @@
+//#region src/cache/cdn-adapter-config.d.ts
+type WranglerOutputConfig = {
+  version_metadata?: unknown;
+  [key: string]: unknown;
+};
+type VersionMetadataOptions = {
+  binding: string;
+  bindingIsExplicit: boolean;
+};
+declare function configureCdnVersionMetadata(config: WranglerOutputConfig, options: VersionMetadataOptions): WranglerOutputConfig;
+/**
+ * Add the CDN adapter's version metadata binding to the Cloudflare Vite
+ * plugin's primary generated deployment config.
+ */
+declare function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }: {
+  outDir: string;
+  isPrimaryServerOutput: boolean;
+  binding: string;
+  bindingIsExplicit: boolean;
+}): Promise<void>;
+//#endregion
+export { configureCdnVersionMetadata, finalizeCdnAdapterBuildOutput };

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

@@ -0,0 +1,47 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region src/cache/cdn-adapter-config.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function configureCdnVersionMetadata(config, options) {
+	if (!Object.hasOwn(config, "version_metadata")) return {
+		...config,
+		version_metadata: { binding: options.binding }
+	};
+	if (!isRecord(config.version_metadata)) throw new Error("[vinext] The generated Wrangler config has an invalid version_metadata value.");
+	const existingBinding = config.version_metadata.binding;
+	if (typeof existingBinding !== "string" || existingBinding.length === 0) throw new Error("[vinext] The generated Wrangler config has an invalid version_metadata.binding value.");
+	if (existingBinding === options.binding) return config;
+	if (!options.bindingIsExplicit) throw new Error(`[vinext] cdnAdapter() uses the default version metadata binding ${JSON.stringify(options.binding)}, but the generated Wrangler config already declares ${JSON.stringify(existingBinding)}. Align the Wrangler binding or configure cdnAdapter({ versionMetadataBinding: ${JSON.stringify(existingBinding)} }).`);
+	return {
+		...config,
+		version_metadata: { binding: options.binding }
+	};
+}
+/**
+* Add the CDN adapter's version metadata binding to the Cloudflare Vite
+* plugin's primary generated deployment config.
+*/
+async function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }) {
+	if (!isPrimaryServerOutput) return;
+	await configureGeneratedCdnVersionMetadata(path.resolve(outDir, "wrangler.json"), {
+		binding,
+		bindingIsExplicit
+	});
+}
+async function configureGeneratedCdnVersionMetadata(generatedConfigPath, options) {
+	let generatedConfig;
+	try {
+		const parsed = JSON.parse(await fs.readFile(generatedConfigPath, "utf8"));
+		if (!isRecord(parsed)) throw new TypeError("the root value must be an object");
+		generatedConfig = parsed;
+	} catch (cause) {
+		throw new Error(`[vinext] Could not read the generated Wrangler config at ${generatedConfigPath}.`, { cause });
+	}
+	const configured = configureCdnVersionMetadata(generatedConfig, options);
+	if (configured === generatedConfig) return;
+	await fs.writeFile(generatedConfigPath, `${JSON.stringify(configured, null, 2)}\n`);
+}
+//#endregion
+export { configureCdnVersionMetadata, finalizeCdnAdapterBuildOutput };

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

@@ -1,4 +1,10 @@
 //#region src/cache/cdn-adapter.d.ts
+declare const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+/** Options accepted by {@link cdnAdapter}, forwarded to the runtime factory. */
+type CdnAdapterOptions = {
+  /** Version metadata binding used to verify version-overridden requests. */
+  versionMetadataBinding?: string;
+};
 /**
  * Cloudflare CDN cache adapter - edge-managed page-level ISR backed by the
  * Cloudflare Workers Cache.
@@ -14,12 +20,37 @@
  *   "cache": {
  *     "enabled": true,
  *   },
+ *   "version_metadata": {
+ *     "binding": "CF_VERSION_METADATA"
+ *   }
  * }
  * ```
+ * Wrangler does not inherit `version_metadata` into named environments. Repeat
+ * the binding in every `env.<name>` used for CDN warmup.
+ *
+ * Cache Rules must preserve the full query string in the incoming cache key.
+ * Two-stage admission certifies exact pathname + search identities, while an
+ * edge HIT is served before the Worker can reject a differently keyed request.
  */
-declare function cdnAdapter(options?: Record<string, never>): {
+declare function cdnAdapter(options?: CdnAdapterOptions): {
   adapter: string;
-  options: Record<string, never> | undefined;
+  options: CdnAdapterOptions | undefined;
+  output: {
+    matchesBuild({ plugins }: {
+      plugins: readonly {
+        name?: string;
+      }[];
+    }): boolean;
+    finalizeBuildOutput({ outDir, isPrimaryServerOutput }: {
+      outDir: string;
+      isPrimaryServerOutput: boolean;
+    }): Promise<void>;
+  };
+  capabilities: {
+    buildIdentity: "response-header";
+    responseVary: "verbatim";
+    routeCacheability: "probe-manifest";
+  };
 };
 //#endregion
-export { cdnAdapter };
+export { CdnAdapterOptions, DEFAULT_CDN_VERSION_METADATA_BINDING, cdnAdapter };

package/dist/cache/cdn-adapter.js

@@ -1,5 +1,7 @@
+import { finalizeCdnAdapterBuildOutput } from "./cdn-adapter-config.js";
 import { fileURLToPath } from "node:url";
 //#region src/cache/cdn-adapter.ts
+const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
 /**
 * Cloudflare CDN cache adapter - edge-managed page-level ISR backed by the
 * Cloudflare Workers Cache.
@@ -15,14 +17,44 @@ import { fileURLToPath } from "node:url";
 *   "cache": {
 *     "enabled": true,
 *   },
+*   "version_metadata": {
+*     "binding": "CF_VERSION_METADATA"
+*   }
 * }
 * ```
+* Wrangler does not inherit `version_metadata` into named environments. Repeat
+* the binding in every `env.<name>` used for CDN warmup.
+*
+* Cache Rules must preserve the full query string in the incoming cache key.
+* Two-stage admission certifies exact pathname + search identities, while an
+* edge HIT is served before the Worker can reject a differently keyed request.
 */
 function cdnAdapter(options) {
+	if (options?.versionMetadataBinding !== void 0 && (typeof options.versionMetadataBinding !== "string" || options.versionMetadataBinding.length === 0)) throw new TypeError("[vinext] cdnAdapter({ versionMetadataBinding }) must be a non-empty string binding name.");
+	const versionMetadataBinding = options?.versionMetadataBinding ?? "CF_VERSION_METADATA";
+	const bindingIsExplicit = options?.versionMetadataBinding !== void 0;
 	return {
 		adapter: fileURLToPath(import.meta.resolve("./cdn-adapter.runtime.js")),
-		options
+		options,
+		output: {
+			matchesBuild({ plugins }) {
+				return plugins.some(({ name }) => name === "vite-plugin-cloudflare" || name?.startsWith("vite-plugin-cloudflare:"));
+			},
+			finalizeBuildOutput({ outDir, isPrimaryServerOutput }) {
+				return finalizeCdnAdapterBuildOutput({
+					outDir,
+					isPrimaryServerOutput,
+					binding: versionMetadataBinding,
+					bindingIsExplicit
+				});
+			}
+		},
+		capabilities: {
+			buildIdentity: "response-header",
+			responseVary: "verbatim",
+			routeCacheability: "probe-manifest"
+		}
 	};
 }
 //#endregion
-export { cdnAdapter };
+export { DEFAULT_CDN_VERSION_METADATA_BINDING, cdnAdapter };

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

@@ -1,7 +1,19 @@
 import { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders } from "vinext/shims/cdn-cache";
 import { CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache";
 //#region src/cache/cdn-adapter.runtime.d.ts
+type WorkerVersionMetadata = {
+  id: string;
+};
+type CdnAdapterOptions = {
+  versionMetadataBinding?: string;
+};
 declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
+  private readonly versionMetadata?;
+  private readonly versionMetadataBinding;
+  readonly requiresCompletedResponseAdmission = true;
+  readonly responseVary: "verbatim";
+  constructor(versionMetadata?: WorkerVersionMetadata | undefined, versionMetadataBinding?: string);
+  validateRequest(request: Request): Response | null;
   readonly ownsBackgroundRevalidation = false;
   /**
    * The origin keeps no page store — return null so the request renders fresh.
@@ -10,6 +22,7 @@ declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   get(): Promise<CacheHandlerValue | null>;
   /** No-op: the platform caches the response via its headers, not an origin store. */
   set(_key: string, _data: IncrementalCacheValue | null, _ctx?: Record<string, unknown>): Promise<void>;
+  buildResponseIdentityHeaders(): CdnResponseHeaders;
   buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
   hasExplicitNonCacheableResponsePolicy(headers: Headers): boolean;
   /** Purge edge-cached responses by tag via the request context's `cache.purge`. */
@@ -17,6 +30,9 @@ declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
     expire?: number;
   }): Promise<void>;
 }
-declare const createCloudflareCdnCacheAdapter: () => CdnCacheAdapter;
+declare const createCloudflareCdnCacheAdapter: ({ env, options }?: {
+  env?: Record<string, unknown>;
+  options?: CdnAdapterOptions;
+}) => CdnCacheAdapter;
 //#endregion
 export { CloudflareCdnCacheAdapter, createCloudflareCdnCacheAdapter as default };

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

@@ -1,11 +1,61 @@
+import { VINEXT_CDN_BUILD_ID_HEADER } from "./cdn-build-id.js";
+import { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "../version-headers.js";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/cdn-adapter.runtime.ts
-const NON_CACHEABLE_DIRECTIVE_RE = /\b(?:private|no-store|no-cache)\b/i;
+/**
+* Cloudflare CDN cache adapter — edge-managed page-level ISR backed by the
+* Cloudflare Workers Cache (`ctx.cache`).
+*
+* Unlike the origin-managed default adapter (which stores rendered artifacts in
+* the data cache and serves HIT/STALE itself), this adapter delegates serving
+* to Cloudflare's edge:
+*
+* - The origin never serves from a store — `get` returns `null`, so any
+*   request that reaches the Worker renders fresh. The edge absorbs HIT/STALE
+*   traffic and revalidates in the background (the `UPDATING` cache status).
+* - `set` is a no-op: the platform caches the *response* based on its
+*   cache headers, so there is nothing to persist at the origin.
+* - `buildResponseHeaders` emits the SWR policy as `CDN-Cache-Control`
+*   (`public, max-age=…, stale-while-revalidate=…`) so the edge caches and
+*   revalidates, while the browser-facing `Cache-Control` is
+*   `public, max-age=0, must-revalidate` so a browser never serves a stored copy
+*   without revalidating against the edge. A `Cache-Tag` header lets entries be
+*   purged by tag. Note the edge directive uses `max-age` (not `s-maxage`):
+*   the framework computes the policy with `s-maxage` for shared caches, but
+*   `CDN-Cache-Control` is already CDN-scoped so `max-age` is the correct knob
+*   for the edge to honor max-age + stale-while-revalidate.
+* - `revalidateTag` purges the edge via the request context's `cache.purge({ tags })`.
+*
+* Tag alignment: the tags emitted in `Cache-Tag` come from the page's render
+* tags (already canonicalised via `encodeCacheTag`), and the framework's
+* `revalidateTag` / `revalidatePath` pass the same canonical form to this
+* adapter's `revalidateTag`, so a purge targets exactly the responses that
+* carried the tag.
+*
+* The default export is the adapter factory the generated
+* `virtual:vinext-cache-adapters` registration imports; configure it from
+* vite.config via the {@link cdnAdapter} builder in `./cdn-adapter.ts` (which
+* `require.resolve`s this file).
+*/
+const DEFAULT_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+const WORKER_VERSION_OVERRIDE_HEADER = "Cloudflare-Workers-Version-Overrides";
+function versionValidationFailure(message, status = 500) {
+	return Response.json({ error: message }, {
+		status,
+		headers: { "Cache-Control": "no-store" }
+	});
+}
 const CACHEABLE_EDGE_DIRECTIVE_RE = /(?:^|,)\s*(?:s-maxage|max-age)\s*=/i;
 const EDGE_POLICY_HEADERS = ["CDN-Cache-Control", "Cloudflare-CDN-Cache-Control"];
+function getBuildIdentityResponseHeader() {
+	const buildId = process.env.__VINEXT_RSC_BUILD_IDENTITY ?? process.env.__VINEXT_BUILD_ID;
+	return buildId ? { [VINEXT_CDN_BUILD_ID_HEADER]: buildId } : {};
+}
 /** Remove every response header whose cache semantics are owned by Cloudflare. */
 function clearCloudflareCdnResponseHeaders(cacheControl) {
 	return {
+		...getBuildIdentityResponseHeader(),
 		"Cache-Control": cacheControl,
 		"CDN-Cache-Control": null,
 		"Cloudflare-CDN-Cache-Control": null,
@@ -15,10 +65,10 @@ function clearCloudflareCdnResponseHeaders(cacheControl) {
 /** Interpret Cloudflare's edge policy before core applies a replacement policy. */
 function hasExplicitCloudflareNonCacheableResponsePolicy(headers) {
 	const edgePolicies = EDGE_POLICY_HEADERS.map((name) => headers.get(name));
-	if (edgePolicies.some((value) => value && NON_CACHEABLE_DIRECTIVE_RE.test(value))) return true;
+	if (edgePolicies.some((value) => value && isNonCacheableCacheControl(value))) return true;
 	const hasCacheableEdgePolicy = edgePolicies.some((value) => value && CACHEABLE_EDGE_DIRECTIVE_RE.test(value));
 	const browserPolicy = headers.get("Cache-Control");
-	return Boolean(!hasCacheableEdgePolicy && browserPolicy && NON_CACHEABLE_DIRECTIVE_RE.test(browserPolicy));
+	return Boolean(!hasCacheableEdgePolicy && browserPolicy && isNonCacheableCacheControl(browserPolicy));
 }
 function getWorkersCache() {
 	const cache = getRequestExecutionContext()?.cache;
@@ -81,6 +131,22 @@ function formatCacheTag(tags) {
 	return parts.length > 0 ? parts.join(",") : null;
 }
 var CloudflareCdnCacheAdapter = class {
+	versionMetadata;
+	versionMetadataBinding;
+	requiresCompletedResponseAdmission = true;
+	responseVary = "verbatim";
+	constructor(versionMetadata, versionMetadataBinding = DEFAULT_VERSION_METADATA_BINDING) {
+		this.versionMetadata = versionMetadata;
+		this.versionMetadataBinding = versionMetadataBinding;
+	}
+	validateRequest(request) {
+		const expectedVersionId = request.headers.get(VINEXT_EXPECTED_WORKER_VERSION_HEADER);
+		if (expectedVersionId === null) return null;
+		if (!request.headers.has(WORKER_VERSION_OVERRIDE_HEADER)) return versionValidationFailure(`received ${VINEXT_EXPECTED_WORKER_VERSION_HEADER} without ${WORKER_VERSION_OVERRIDE_HEADER}.`);
+		if (!this.versionMetadata) return versionValidationFailure(`Cloudflare CDN prewarming requires the \`${this.versionMetadataBinding}\` version metadata binding. Add "version_metadata": { "binding": "${this.versionMetadataBinding}" } to the active Wrangler environment. Named environments do not inherit this binding from the top level.`);
+		if (expectedVersionId !== this.versionMetadata.id) return versionValidationFailure(`Cloudflare invoked Worker version ${this.versionMetadata.id}, but vinext warmup expected ${expectedVersionId}.`, 503);
+		return null;
+	}
 	ownsBackgroundRevalidation = false;
 	/**
 	* The origin keeps no page store — return null so the request renders fresh.
@@ -91,10 +157,15 @@ var CloudflareCdnCacheAdapter = class {
 	}
 	/** No-op: the platform caches the response via its headers, not an origin store. */
 	async set(_key, _data, _ctx) {}
+	buildResponseIdentityHeaders() {
+		return getBuildIdentityResponseHeader();
+	}
 	buildResponseHeaders(input) {
+		if (input.pendingDynamicCheck) return clearCloudflareCdnResponseHeaders(NO_STORE);
 		if (!input.cacheControl) return clearCloudflareCdnResponseHeaders(NO_STORE);
-		if (/\b(?:no-store|no-cache|private)\b/.test(input.cacheControl)) return clearCloudflareCdnResponseHeaders(input.cacheControl);
+		if (isNonCacheableCacheControl(input.cacheControl)) return clearCloudflareCdnResponseHeaders(input.cacheControl);
 		return {
+			...getBuildIdentityResponseHeader(),
 			"Cache-Control": BROWSER_REVALIDATE,
 			"CDN-Cache-Control": toEdgeCacheControl(input.cacheControl),
 			"Cloudflare-CDN-Cache-Control": null,
@@ -113,6 +184,10 @@ var CloudflareCdnCacheAdapter = class {
 		await cache.purge({ tags: tagList });
 	}
 };
-const createCloudflareCdnCacheAdapter = () => new CloudflareCdnCacheAdapter();
+const createCloudflareCdnCacheAdapter = ({ env, options } = {}) => {
+	const binding = options?.versionMetadataBinding ?? DEFAULT_VERSION_METADATA_BINDING;
+	const candidate = env?.[binding];
+	return new CloudflareCdnCacheAdapter(candidate && typeof candidate === "object" && "id" in candidate && typeof candidate.id === "string" ? { id: candidate.id } : void 0, binding);
+};
 //#endregion
 export { CloudflareCdnCacheAdapter, createCloudflareCdnCacheAdapter as default };

package/dist/cache/cdn-build-id.d.ts

@@ -0,0 +1,5 @@
+//#region src/cache/cdn-build-id.d.ts
+/** Build identity stamped by the Cloudflare CDN adapter on page responses. */
+declare const VINEXT_CDN_BUILD_ID_HEADER = "X-Vinext-Build-Id";
+//#endregion
+export { VINEXT_CDN_BUILD_ID_HEADER };

package/dist/cache/cdn-build-id.js

@@ -0,0 +1,5 @@
+//#region src/cache/cdn-build-id.ts
+/** Build identity stamped by the Cloudflare CDN adapter on page responses. */
+const VINEXT_CDN_BUILD_ID_HEADER = "X-Vinext-Build-Id";
+//#endregion
+export { VINEXT_CDN_BUILD_ID_HEADER };

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

@@ -1,7 +1,7 @@
 import { ENTRY_PREFIX, createKvKeySpace } from "./kv-key.js";
 import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
-import { getRequestExecutionContext } from "vinext/shims/request-context";
 import { Buffer } from "node:buffer";
+import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/kv-data-adapter.runtime.ts
 /**
 * Cloudflare KV data cache — implementation + runtime factory.

package/dist/cacheability-artifact.d.ts

@@ -0,0 +1,10 @@
+import { CacheabilityManifest } from "vinext/internal/server/cacheability-manifest";
+//#region src/cacheability-artifact.d.ts
+/**
+ * Write the version-specific manifest into the built Worker artifact.
+ * The application build already imports this stable module asset, so the
+ * completed dist directory remains the exact input to the final upload.
+ */
+declare function writeCacheabilityManifestArtifact(root: string, configuredPath: string | undefined, manifest: CacheabilityManifest): string;
+//#endregion
+export { writeCacheabilityManifestArtifact };

package/dist/cacheability-artifact.js

@@ -0,0 +1,165 @@
+import { cacheabilityManifestByteLimitError } from "./cacheability-manifest-limits.js";
+import fs from "node:fs";
+import path from "node:path";
+import { Buffer } from "node:buffer";
+import { CACHEABILITY_MANIFEST_MODULE } from "vinext/internal/server/cacheability-manifest";
+//#region src/cacheability-artifact.ts
+function tokenizeStaticImports(source) {
+	const tokens = [];
+	let index = 0;
+	const canStartRegularExpression = () => {
+		const previous = tokens.at(-1);
+		if (!previous) return true;
+		if (previous.kind === "punctuator" && "({[=,:;!?&|+-*%^~<>".includes(previous.value)) return true;
+		return previous.kind === "identifier" && /^(?:await|case|delete|do|else|in|instanceof|of|return|throw|typeof|void|yield)$/.test(previous.value);
+	};
+	while (index < source.length) {
+		const character = source[index];
+		if (/\s/.test(character)) {
+			index++;
+			continue;
+		}
+		if (character === "/" && source[index + 1] === "/") {
+			index = source.indexOf("\n", index + 2);
+			if (index === -1) break;
+			continue;
+		}
+		if (character === "/" && source[index + 1] === "*") {
+			const end = source.indexOf("*/", index + 2);
+			index = end === -1 ? source.length : end + 2;
+			continue;
+		}
+		if (character === "/" && canStartRegularExpression()) {
+			let inCharacterClass = false;
+			index++;
+			while (index < source.length) {
+				if (source[index] === "\\") {
+					index += 2;
+					continue;
+				}
+				if (source[index] === "[") inCharacterClass = true;
+				if (source[index] === "]") inCharacterClass = false;
+				if (source[index++] === "/" && !inCharacterClass) break;
+			}
+			while (index < source.length && /[A-Za-z]/.test(source[index])) index++;
+			continue;
+		}
+		if (character === "`") {
+			index++;
+			while (index < source.length) if (source[index] === "\\") index += 2;
+			else if (source[index++] === "`") break;
+			continue;
+		}
+		if (character === "\"" || character === "'") {
+			const quote = character;
+			const start = ++index;
+			while (index < source.length && source[index] !== quote) index += source[index] === "\\" ? 2 : 1;
+			tokens.push({
+				kind: "string",
+				value: source.slice(start, index)
+			});
+			index++;
+			continue;
+		}
+		if (/[A-Za-z_$]/.test(character)) {
+			const start = index++;
+			while (index < source.length && /[\w$]/.test(source[index])) index++;
+			tokens.push({
+				kind: "identifier",
+				value: source.slice(start, index)
+			});
+			continue;
+		}
+		tokens.push({
+			kind: "punctuator",
+			value: character
+		});
+		index++;
+	}
+	return tokens;
+}
+/**
+* Check only the generated entry module's static dependency declarations. This
+* deliberately avoids an AST parse or module-graph walk on the deploy path,
+* while rejecting comments, strings, templates, and dynamic imports that only
+* happen to mention the manifest filename.
+*/
+function hasStaticModuleSpecifier(source, expected) {
+	const tokens = tokenizeStaticImports(source);
+	let braceDepth = 0;
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index];
+		if (token.value === "{") {
+			braceDepth++;
+			continue;
+		}
+		if (token.value === "}") {
+			braceDepth = Math.max(0, braceDepth - 1);
+			continue;
+		}
+		if (braceDepth !== 0 || token.kind !== "identifier") continue;
+		if (token.value === "import") {
+			const next = tokens[index + 1];
+			if (next?.kind === "string" && next.value === expected) return true;
+			if (next?.value === "(" || next?.value === ".") continue;
+		} else if (token.value !== "export") continue;
+		for (let cursor = index + 1; cursor < tokens.length; cursor++) {
+			const candidate = tokens[cursor];
+			if (candidate.value === ";") break;
+			if (candidate.kind === "identifier" && candidate.value === "from") {
+				const specifier = tokens[cursor + 1];
+				if (specifier?.kind === "string" && specifier.value === expected) return true;
+				break;
+			}
+		}
+	}
+	return false;
+}
+function resolveGeneratedServerConfig(root, configuredPath) {
+	const distDirectory = path.join(root, "dist");
+	const configPath = path.resolve(root, configuredPath ?? "dist/server/wrangler.json");
+	const relativeConfigPath = path.relative(distDirectory, configPath);
+	if (relativeConfigPath.startsWith("..") || path.isAbsolute(relativeConfigPath)) throw new Error("Two-stage CDN warming requires a generated Wrangler config under dist/. Pass --config dist/server/wrangler.json (or another generated dist config).");
+	if (!fs.existsSync(configPath) || !fs.lstatSync(configPath).isFile()) throw new Error(`Two-stage CDN warming requires the generated Wrangler config at ${path.relative(root, configPath)}. Rebuild the app before deploying.`);
+	return configPath;
+}
+function assertManifestModuleReachable(configPath) {
+	const serverDirectory = path.dirname(configPath);
+	let config;
+	try {
+		config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+	} catch (cause) {
+		throw new Error("Two-stage CDN warming could not parse the generated Wrangler config.", { cause });
+	}
+	const main = config && typeof config === "object" && !Array.isArray(config) ? config.main : void 0;
+	if (typeof main !== "string" || main.length === 0) throw new Error("Two-stage CDN warming requires a generated Wrangler main module.");
+	const mainPath = path.resolve(serverDirectory, main);
+	if (!fs.existsSync(mainPath) || !fs.lstatSync(mainPath).isFile()) throw new Error("Two-stage CDN warming could not find the generated Wrangler main module.");
+	if (!hasStaticModuleSpecifier(fs.readFileSync(mainPath, "utf8"), `./${CACHEABILITY_MANIFEST_MODULE}`)) throw new Error(`Two-stage CDN warming requires the generated Worker main module to import ${CACHEABILITY_MANIFEST_MODULE}.`);
+}
+/**
+* Write the version-specific manifest into the built Worker artifact.
+* The application build already imports this stable module asset, so the
+* completed dist directory remains the exact input to the final upload.
+*/
+function writeCacheabilityManifestArtifact(root, configuredPath, manifest) {
+	const configPath = resolveGeneratedServerConfig(root, configuredPath);
+	assertManifestModuleReachable(configPath);
+	const serverDirectory = path.dirname(configPath);
+	const manifestPath = path.join(serverDirectory, CACHEABILITY_MANIFEST_MODULE);
+	if (!fs.existsSync(manifestPath) || !fs.lstatSync(manifestPath).isFile()) throw new Error(`Two-stage CDN warming requires ${CACHEABILITY_MANIFEST_MODULE} in the generated Worker artifact. Rebuild the app before deploying.`);
+	const serializedManifest = JSON.stringify(manifest);
+	const manifestBytes = Buffer.byteLength(serializedManifest);
+	if (manifestBytes > 2097152) throw cacheabilityManifestByteLimitError(manifestBytes);
+	const manifestSource = `export default ${JSON.stringify(serializedManifest)};\n`;
+	const pendingManifestPath = `${manifestPath}.${process.pid}.tmp`;
+	try {
+		fs.writeFileSync(pendingManifestPath, manifestSource, "utf8");
+		fs.renameSync(pendingManifestPath, manifestPath);
+	} finally {
+		if (fs.existsSync(pendingManifestPath)) fs.unlinkSync(pendingManifestPath);
+	}
+	return path.relative(root, configPath);
+}
+//#endregion
+export { writeCacheabilityManifestArtifact };

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

@@ -0,0 +1,5 @@
+//#region src/cacheability-manifest-limits.d.ts
+declare const MAX_CACHEABILITY_MANIFEST_BYTES: number;
+declare function cacheabilityManifestByteLimitError(manifestBytes: number, limit?: number): Error;
+//#endregion
+export { MAX_CACHEABILITY_MANIFEST_BYTES, cacheabilityManifestByteLimitError };

package/dist/cacheability-manifest-limits.js

@@ -0,0 +1,7 @@
+//#region src/cacheability-manifest-limits.ts
+const MAX_CACHEABILITY_MANIFEST_BYTES = 2 * 1024 * 1024;
+function cacheabilityManifestByteLimitError(manifestBytes, limit = MAX_CACHEABILITY_MANIFEST_BYTES) {
+	return /* @__PURE__ */ new Error(`Two-stage CDN warming produced a ${manifestBytes}-byte route-pattern cacheability manifest; the limit is ${limit} bytes. Reduce the number or length of route patterns, or split the deployment before retrying.`);
+}
+//#endregion
+export { MAX_CACHEABILITY_MANIFEST_BYTES, cacheabilityManifestByteLimitError };

package/dist/cacheability-probe.d.ts

@@ -0,0 +1,50 @@
+import { CdnWarmTarget } from "./cdn-warm.js";
+import { CacheabilityManifest } from "vinext/internal/server/cacheability-manifest";
+import { PrerenderRoutePattern } from "vinext/internal/build/prerender-paths";
+//#region src/cacheability-probe.d.ts
+declare const DEFAULT_CACHEABILITY_PROBE_PHASE_TIMEOUT_MS = 120000;
+declare const DEFAULT_CACHEABILITY_PROBE_RETRIES = 2;
+declare const DEFAULT_CACHEABILITY_PROBE_RETRY_DELAY_MS = 1000;
+type CacheabilityProbeProgress = {
+  completed: number;
+  dynamic: number;
+  failed: number;
+  probed: number;
+  skipped: number;
+  static: number;
+  total: number;
+};
+type CacheabilityProbeResult = {
+  cacheableTargets: CdnWarmTarget[];
+  classified: number;
+  dynamic: number;
+  failures: string[];
+  manifest: CacheabilityManifest;
+  probed: number;
+  skipped: number;
+  /** Paired representations admitted only if their own final warm render remains cacheable. */
+  speculativeTargets: CdnWarmTarget[];
+};
+declare function readPrerenderSecret(root: string): string;
+declare function probeStagedWorkerCacheability(options: {
+  buildId: string;
+  concurrency?: number;
+  expectedResponseBuildId?: string;
+  fallbackRoutePatterns?: readonly PrerenderRoutePattern[];
+  fetchImpl?: typeof fetch;
+  headers?: HeadersInit;
+  retries?: number;
+  retryDelayMs?: number;
+  root: string;
+  targets: readonly CdnWarmTarget[];
+  targetUrl: string;
+  timeoutMs?: number;
+  phaseTimeoutMs?: number;
+  onProgress?: (progress: CacheabilityProbeProgress) => void;
+  /** @internal Apply stricter artifact bounds for focused coordinator tests. */
+  manifestLimits?: {
+    maxBytes?: number;
+  };
+}): Promise<CacheabilityProbeResult>;
+//#endregion
+export { CacheabilityProbeProgress, CacheabilityProbeResult, DEFAULT_CACHEABILITY_PROBE_PHASE_TIMEOUT_MS, DEFAULT_CACHEABILITY_PROBE_RETRIES, DEFAULT_CACHEABILITY_PROBE_RETRY_DELAY_MS, probeStagedWorkerCacheability, readPrerenderSecret };