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

package/README.md

@@ -7,7 +7,13 @@ This package provides Cloudflare-specific cache and image backends for vinext:
 
 - **`kvDataAdapter()`** (`@vinext/cloudflare/cache/kv-data-adapter`) — backs the
   data cache (`fetch`, `"use cache"`, `unstable_cache`) with a Workers KV
-  namespace. Also used for ISR in the absence of a CDN adapter.
+  namespace.
+- **`cdnAdapter()`** (`@vinext/cloudflare/cache/cdn-adapter`) — delegates
+  page-level ISR serving and revalidation to Cloudflare Workers Cache through
+  an automatically generated cache-enabled response entrypoint.
+- **`responseStoreAdapter()`** (`@vinext/cloudflare/cache/response-store-adapter`) —
+  uses Workers Response Store for both response and data caching, either in a
+  separate cache Worker or inside the application Worker.
 - **`imagesOptimizer()`** (`@vinext/cloudflare/images/images-optimizer`) — backs
   `next/image` transformations with a Cloudflare Images binding.
 
@@ -32,6 +38,93 @@ export default defineConfig({
 });
 ```
 
+### Workers Cache
+
+`cdnAdapter()` is optional. Configuring it asks the Cloudflare build for two
+Worker entrypoints: the default entrypoint runs middleware and request-time
+routing with caching disabled, while `VinextCachedResponse` lazily loads the
+render stage with Workers Cache enabled. These settings are written to the
+generated `dist/server/wrangler.json`; do not enable Workers Cache on the
+default entrypoint in your source config. The generated config also declares
+the version metadata binding used for staged warmup.
+
+```ts
+import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+
+vinext({ cache: { cdn: cdnAdapter() } });
+```
+
+The generated version metadata binding lets staged warmup prove that every
+discovery, probe, and fill request reached the uploaded Worker version. Pass
+`versionMetadataBinding` to `cdnAdapter()` only when the deployment needs a
+custom binding name.
+
+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.
+
+The response entrypoint hashes the complete transport identity into its
+Workers Cache URL, independently of zone Cache Rules, so distinct query and
+representation variants cannot collide.
+
+### Workers Response Store
+
+`responseStoreAdapter()` replaces both `cdnAdapter()` and `kvDataAdapter()`.
+It defaults to a separate cache Worker reached through the `RESPONSE_STORE`
+service binding. `vinext init` writes two collocated source configs:
+`wrangler.jsonc` for the application and `wrangler.response-store.jsonc` for the
+cache Worker. The latter points directly at the installed
+`@cloudflare/workers-response-store` implementation and owns its R2 bucket,
+SQLite Durable Object, Worker name, and cache settings. Edit those configs to
+choose or reuse names, keeping the application service binding aligned with the
+cache Worker name.
+
+The two Workers are deliberately deployed separately. Deploy the Response Store
+when its package or config changes, then deploy the application normally:
+
+```sh
+npx wrangler deploy --config wrangler.response-store.jsonc
+npx @vinext/cloudflare deploy
+```
+
+`vinext-cloudflare deploy` never creates, rewrites, or deploys the Response
+Store Worker.
+
+Metadata sharding is opt-in and works in either deployment mode:
+
+```ts
+vinext({ cache: responseStoreAdapter({ shards: 16 }) });
+```
+
+Keys remain pinned to one shard while tag/path mutations fan out across every
+shard. Omit `shards` to retain the original single metadata Durable Object.
+
+To place newly created metadata Durable Objects near a stable traffic and R2
+region, pass a Cloudflare location hint:
+
+```ts
+vinext({ cache: responseStoreAdapter({ locationHint: "weur" }) });
+```
+
+The hint works in both deployment modes, is best-effort, and only affects each
+Durable Object's first creation. Changing it does not relocate existing
+objects; treat the change as a cache-cold deployment and align it with the R2
+bucket's location.
+
+To deploy storage and cache entrypoints with the application instead, select
+self-contained mode:
+
+```ts
+import { responseStoreAdapter } from "@vinext/cloudflare/cache/response-store-adapter";
+
+vinext({ cache: responseStoreAdapter({ mode: "self-contained" }) });
+```
+
+In this mode `vinext init` places the required R2, SQLite Durable Object,
+Workers Cache entrypoint, and version-metadata configuration in
+`wrangler.jsonc`; no second Wrangler config is required.
+
 ## Deploy
 
 Deploy Cloudflare Workers projects with the package CLI:

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

@@ -0,0 +1,30 @@
+//#region src/cache/cdn-adapter-config.d.ts
+type WranglerWorkerExport = {
+  cache?: {
+    enabled: boolean;
+  };
+  type?: string;
+  [key: string]: unknown;
+};
+type WranglerOutputConfig = {
+  compatibility_date?: string;
+  compatibility_flags?: string[];
+  exports?: Record<string, WranglerWorkerExport>;
+  version_metadata?: unknown;
+  [key: string]: unknown;
+};
+type VersionMetadataOptions = {
+  binding: string;
+  bindingIsExplicit: boolean;
+};
+export declare function configureCdnVersionMetadata(config: WranglerOutputConfig, options: VersionMetadataOptions): WranglerOutputConfig;
+/** Add the per-entrypoint Workers Cache policy to an emitted Wrangler config. */
+export declare function configureWorkersCacheEntrypoints(config: WranglerOutputConfig): WranglerOutputConfig;
+/** Apply the complete CDN adapter policy to the primary generated config. */
+export declare function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }: {
+  outDir: string;
+  isPrimaryServerOutput: boolean;
+  binding: string;
+  bindingIsExplicit: boolean;
+}): Promise<void>;
+//#endregion

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

@@ -0,0 +1,87 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region src/cache/cdn-adapter-config.ts
+const CACHED_RESPONSE_STAGE_EXPORT = "VinextCachedResponse";
+const UNCACHED_RESPONSE_STAGE_EXPORT = "VinextUncachedResponse";
+const CTX_EXPORTS_DEFAULT_DATE = "2025-11-17";
+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 per-entrypoint Workers Cache policy to an emitted Wrangler config. */
+function configureWorkersCacheEntrypoints(config) {
+	const configuredExports = config.exports ?? {};
+	const compatibilityFlags = config.compatibility_flags ?? [];
+	if (compatibilityFlags.includes("disable_ctx_exports")) throw new Error("[vinext] cdnAdapter() requires ctx.exports, but the generated Wrangler config explicitly disables it with disable_ctx_exports.");
+	const configuredCompatibilityFlags = config.compatibility_date === void 0 || config.compatibility_date < CTX_EXPORTS_DEFAULT_DATE ? compatibilityFlags.includes("enable_ctx_exports") ? compatibilityFlags : [...compatibilityFlags, "enable_ctx_exports"] : compatibilityFlags.filter((flag) => flag !== "enable_ctx_exports");
+	for (const name of [
+		"default",
+		CACHED_RESPONSE_STAGE_EXPORT,
+		UNCACHED_RESPONSE_STAGE_EXPORT
+	]) {
+		const existing = configuredExports[name];
+		if (existing?.type !== void 0 && existing.type !== "worker") throw new Error(`[vinext] cdnAdapter() cannot configure the reserved Worker export ${JSON.stringify(name)} because it is already declared as ${JSON.stringify(existing.type)}.`);
+	}
+	return {
+		...config,
+		compatibility_flags: configuredCompatibilityFlags,
+		exports: {
+			...configuredExports,
+			default: {
+				...configuredExports.default,
+				type: "worker",
+				cache: { enabled: false }
+			},
+			[CACHED_RESPONSE_STAGE_EXPORT]: {
+				...configuredExports[CACHED_RESPONSE_STAGE_EXPORT],
+				type: "worker",
+				cache: { enabled: true }
+			},
+			[UNCACHED_RESPONSE_STAGE_EXPORT]: {
+				...configuredExports[UNCACHED_RESPONSE_STAGE_EXPORT],
+				type: "worker",
+				cache: { enabled: false }
+			}
+		}
+	};
+}
+async function readGeneratedConfig(generatedConfigPath, allowMissing) {
+	try {
+		const parsed = JSON.parse(await fs.readFile(generatedConfigPath, "utf8"));
+		if (!isRecord(parsed)) throw new TypeError("the root value must be an object");
+		return parsed;
+	} catch (cause) {
+		if (allowMissing && cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") return null;
+		throw new Error(`[vinext] Could not read the generated Wrangler config at ${generatedConfigPath}.`, { cause });
+	}
+}
+async function writeGeneratedConfig(generatedConfigPath, config) {
+	await fs.writeFile(generatedConfigPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+/** Apply the complete CDN adapter policy to the primary generated config. */
+async function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }) {
+	if (!isPrimaryServerOutput) return;
+	const generatedConfigPath = path.resolve(outDir, "wrangler.json");
+	const generatedConfig = await readGeneratedConfig(generatedConfigPath, false);
+	if (!generatedConfig) return;
+	await writeGeneratedConfig(generatedConfigPath, configureWorkersCacheEntrypoints(configureCdnVersionMetadata(generatedConfig, {
+		binding,
+		bindingIsExplicit
+	})));
+}
+//#endregion
+export { configureCdnVersionMetadata, configureWorkersCacheEntrypoints, finalizeCdnAdapterBuildOutput };

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

@@ -1,25 +1,57 @@
 //#region src/cache/cdn-adapter.d.ts
+export declare const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+/** Options accepted by {@link cdnAdapter}, forwarded to the runtime factory. */
+export 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.
  *
  * Unlike the data adapter (which stores cache entries in a durable store and
- * serves HIT/STALE itself), this adapter delegates serving to Cloudflare's
- * edge cache.
+ * serves HIT/STALE itself), this adapter delegates serving to Workers Cache on
+ * a named Worker entrypoint. The default entrypoint always runs middleware and
+ * request-time routing before dispatching to cached or uncached response-stage
+ * entrypoints.
+ *
+ * The emitted Wrangler configuration enables Workers Cache only for that
+ * response-stage export, so cache hits do not start the application stage.
+ * The generated deployment config automatically enables Workers Cache for the
+ * cached response entrypoint and adds the version metadata binding used by
+ * warmup. The uncached response entrypoint keeps bypass and probe renders out
+ * of the gateway without enabling Workers Cache for them.
  *
- * Workers Cache must be enabled in your Wrangler config for this to work.
- * ```jsonc
- * // wrangler.jsonc
- * {
- *   "cache": {
- *     "enabled": true,
- *   },
- * }
- * ```
+ * The adapter adds a transport-only URL digest so distinct response-stage
+ * identities cannot collide. Workers Cache owns this key independently of
+ * zone Cache Rules.
  */
-declare function cdnAdapter(options?: Record<string, never>): {
+export declare function cdnAdapter(options?: CdnAdapterOptions): {
   adapter: string;
-  options: Record<string, never> | undefined;
+  options: CdnAdapterOptions | undefined;
+  output: {
+    entry: string;
+    matchesBuild({ plugins }: {
+      plugins: readonly {
+        name?: string;
+      }[];
+    }): boolean;
+    transformHostEntry({ code, id }: {
+      code: string;
+      id: string;
+    }): string | null;
+    finalizeBuildOutput({ outDir, isPrimaryServerOutput }: {
+      outDir: string;
+      isPrimaryServerOutput: boolean;
+    }): Promise<void>;
+    type: "multi-stage";
+  };
+  capabilities: {
+    buildIdentity: "response-header";
+    isResponsePolicyHeader: (name: string) => boolean;
+    requestRouting: "uncached-stage";
+    responseVary: "verbatim";
+    routeCacheability: "probe-manifest";
+  };
 };
-//#endregion
-export { cdnAdapter };
+//#endregion

package/dist/cache/cdn-adapter.js

@@ -1,28 +1,64 @@
+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";
+const CLOUDFLARE_WORKER_ENTRY_ID = "virtual:cloudflare/worker-entry";
 /**
 * Cloudflare CDN cache adapter - edge-managed page-level ISR backed by the
 * Cloudflare Workers Cache.
 *
 * Unlike the data adapter (which stores cache entries in a durable store and
-* serves HIT/STALE itself), this adapter delegates serving to Cloudflare's
-* edge cache.
+* serves HIT/STALE itself), this adapter delegates serving to Workers Cache on
+* a named Worker entrypoint. The default entrypoint always runs middleware and
+* request-time routing before dispatching to cached or uncached response-stage
+* entrypoints.
 *
-* Workers Cache must be enabled in your Wrangler config for this to work.
-* ```jsonc
-* // wrangler.jsonc
-* {
-*   "cache": {
-*     "enabled": true,
-*   },
-* }
-* ```
+* The emitted Wrangler configuration enables Workers Cache only for that
+* response-stage export, so cache hits do not start the application stage.
+* The generated deployment config automatically enables Workers Cache for the
+* cached response entrypoint and adds the version metadata binding used by
+* warmup. The uncached response entrypoint keeps bypass and probe renders out
+* of the gateway without enabling Workers Cache for them.
+*
+* The adapter adds a transport-only URL digest so distinct response-stage
+* identities cannot collide. Workers Cache owns this key independently of
+* zone Cache Rules.
 */
 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;
+	const workerEntry = fileURLToPath(import.meta.resolve("./cdn-adapter.worker.js"));
 	return {
 		adapter: fileURLToPath(import.meta.resolve("./cdn-adapter.runtime.js")),
-		options
+		options,
+		output: {
+			entry: workerEntry,
+			matchesBuild({ plugins }) {
+				return plugins.some(({ name }) => name === "vite-plugin-cloudflare" || name?.startsWith("vite-plugin-cloudflare:"));
+			},
+			transformHostEntry({ code, id }) {
+				if ((id.charCodeAt(0) === 0 ? id.slice(1) : id) !== CLOUDFLARE_WORKER_ENTRY_ID) return null;
+				return `${code}\nexport { VinextCachedResponse, VinextUncachedResponse } from ${JSON.stringify(workerEntry)};\n`;
+			},
+			finalizeBuildOutput({ outDir, isPrimaryServerOutput }) {
+				return finalizeCdnAdapterBuildOutput({
+					outDir,
+					isPrimaryServerOutput,
+					binding: versionMetadataBinding,
+					bindingIsExplicit
+				});
+			},
+			type: "multi-stage"
+		},
+		capabilities: {
+			buildIdentity: "response-header",
+			isResponsePolicyHeader: (name) => name.toLowerCase() === "cdn-cache-control" || name.toLowerCase() === "cloudflare-cdn-cache-control",
+			requestRouting: "uncached-stage",
+			responseVary: "verbatim",
+			routeCacheability: "probe-manifest"
+		}
 	};
 }
 //#endregion
-export { cdnAdapter };
+export { DEFAULT_CDN_VERSION_METADATA_BINDING, cdnAdapter };

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

@@ -1,8 +1,26 @@
 import { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders } from "vinext/shims/cdn-cache";
 import { CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache";
-
 //#region src/cache/cdn-adapter.runtime.d.ts
-declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
+type WorkerVersionMetadata = {
+  id: string;
+};
+type CdnAdapterOptions = {
+  versionMetadataBinding?: string;
+};
+/** Encode a case-sensitive Next.js tag into a fixed Workers Cache tag. */
+export declare function encodeCloudflareCacheTag(tag: string): string;
+export declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
+  private readonly versionMetadata?;
+  private readonly versionMetadataBinding;
+  readonly requiresCompletedResponseAdmission = true;
+  readonly responseVary: "verbatim";
+  readonly responsePolicy: {
+    isHeader(name: string): boolean;
+    readCacheControl(headers: Headers): string | null;
+    hasExplicitNonCacheablePolicy(headers: Headers, baseline?: Headers): boolean;
+  };
+  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.
@@ -11,12 +29,16 @@ 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;
   /** Purge edge-cached responses by tag via the request context's `cache.purge`. */
   revalidateTag(tags: string | string[], _durations?: {
     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 };
+export { createCloudflareCdnCacheAdapter as default };

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

@@ -1,5 +1,80 @@
+import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-build-id.js";
+import { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "../version-headers.js";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
+import { fnv1a64 } from "vinext/internal/utils/hash";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
 //#region src/cache/cdn-adapter.runtime.ts
+/**
+* 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 `Cloudflare-CDN-Cache-Control`
+*   (`public, max-age=…, stale-while-revalidate=…`) so the edge caches and
+*   revalidates. The inner response's `Cache-Control` is
+*   `public, max-age=0, must-revalidate` so a browser never serves a stored copy
+*   without revalidating against the edge; the uncached gateway changes that to
+*   `private, max-age=0, must-revalidate` before public egress so personalized
+*   request-stage headers cannot enter another shared cache. 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
+*   `Cloudflare-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 })`.
+*
+* Tags use fixed-size lowercase digests before emission and purge because
+* Workers Cache tags are case-insensitive printable ASCII, while Next.js tags
+* are case-sensitive arbitrary strings.
+*
+* 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 = getVinextCdnBuildIdentity();
+	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,
+		"Cache-Tag": null
+	};
+}
+/** 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 && 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 && isNonCacheableCacheControl(browserPolicy));
+}
+function readCloudflareResponseCacheControl(headers) {
+	return headers.get("Cloudflare-CDN-Cache-Control") ?? headers.get("CDN-Cache-Control") ?? headers.get("Cache-Control");
+}
 function getWorkersCache() {
 	const cache = getRequestExecutionContext()?.cache;
 	if (cache && typeof cache.purge === "function") return cache;
@@ -28,7 +103,7 @@ const UNBOUNDED_SWR_SECONDS = 31536e3;
 /**
 * Convert the framework's shared-cache policy into a CDN-scoped one:
 * `s-maxage=…` → `max-age=…` (the edge honors `max-age` inside
-* `CDN-Cache-Control`), give a value-less `stale-while-revalidate` an explicit
+* `Cloudflare-CDN-Cache-Control`), give a value-less `stale-while-revalidate` an explicit
 * seconds value (Cloudflare ignores the bare directive), and ensure a leading
 * `public`.
 */
@@ -37,30 +112,61 @@ function toEdgeCacheControl(cacheControl) {
 	return /\bpublic\b/.test(withMaxAge) ? withMaxAge : `public, ${withMaxAge}`;
 }
 /**
-* Cloudflare's `Cache-Tag` header budget is 16 KB total with each tag capped at
-* 1024 bytes. Keep a conservative ceiling so a page with a large tag set never
-* produces an oversized (silently-dropped) header.
+* Cloudflare's `Cache-Tag` header budget is 16 KB total. Fixed-size digests let
+* the full Next.js tag set fit without dropping valid long or Unicode tags.
 */
-const MAX_CACHE_TAG_BYTES = 8 * 1024;
-const MAX_SINGLE_TAG_BYTES = 1024;
+const MAX_CACHE_TAG_BYTES = 16384;
+const CACHE_TAG_PREFIX = "vinext-";
+/** Encode a case-sensitive Next.js tag into a fixed Workers Cache tag. */
+function encodeCloudflareCacheTag(tag) {
+	return `${CACHE_TAG_PREFIX}${fnv1a64(`0:${tag}`)}${fnv1a64(`1:${tag}`)}`;
+}
 /**
-* Build a `Cache-Tag` header value from canonicalised tags. Tags containing a
-* comma (the header separator) or exceeding the per-tag size are skipped, and
-* the whole value is bounded to stay within Cloudflare's limit.
+* Build a complete `Cache-Tag` header value from canonicalised tags. Returning
+* null makes the response uncacheable rather than caching with incomplete
+* invalidation metadata.
 */
 function formatCacheTag(tags) {
-	const parts = [];
-	let total = 0;
-	for (const tag of tags) {
-		if (!tag || tag.includes(",") || tag.length > MAX_SINGLE_TAG_BYTES) continue;
-		const next = total + tag.length + (parts.length > 0 ? 1 : 0);
-		if (next > MAX_CACHE_TAG_BYTES) break;
-		parts.push(tag);
-		total = next;
-	}
-	return parts.length > 0 ? parts.join(",") : null;
+	const value = tags.map(encodeCloudflareCacheTag).join(",");
+	return value && value.length <= MAX_CACHE_TAG_BYTES ? value : null;
 }
 var CloudflareCdnCacheAdapter = class {
+	versionMetadata;
+	versionMetadataBinding;
+	requiresCompletedResponseAdmission = true;
+	responseVary = "verbatim";
+	responsePolicy = {
+		isHeader(name) {
+			const normalized = name.toLowerCase();
+			return EDGE_POLICY_HEADERS.some((header) => header.toLowerCase() === normalized);
+		},
+		readCacheControl(headers) {
+			return readCloudflareResponseCacheControl(headers);
+		},
+		hasExplicitNonCacheablePolicy(headers, baseline) {
+			if (baseline) {
+				for (const name of EDGE_POLICY_HEADERS) {
+					const value = headers.get(name);
+					if (value !== baseline.get(name) && value !== null && isNonCacheableCacheControl(value)) return true;
+				}
+				const browserPolicy = headers.get("Cache-Control");
+				return Boolean(browserPolicy !== baseline.get("Cache-Control") && browserPolicy && isNonCacheableCacheControl(browserPolicy));
+			}
+			return hasExplicitCloudflareNonCacheableResponsePolicy(headers);
+		}
+	};
+	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.
@@ -71,33 +177,40 @@ 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.cacheControl) return { "Cache-Control": NO_STORE };
-		if (/\b(?:no-store|no-cache|private)\b/.test(input.cacheControl)) return {
-			"Cache-Control": input.cacheControl,
-			"CDN-Cache-Control": null,
-			"Cloudflare-CDN-Cache-Control": null,
-			"Cache-Tag": null
-		};
-		const headers = {
+		if (input.pendingDynamicCheck) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		if (!input.cacheControl) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		if (isNonCacheableCacheControl(input.cacheControl)) return clearCloudflareCdnResponseHeaders(input.cacheControl);
+		const cacheTag = input.tags?.length ? formatCacheTag(input.tags) : null;
+		if (input.tags?.length && !cacheTag) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		return {
+			...getBuildIdentityResponseHeader(),
 			"Cache-Control": BROWSER_REVALIDATE,
-			"CDN-Cache-Control": toEdgeCacheControl(input.cacheControl)
+			"CDN-Cache-Control": null,
+			"Cloudflare-CDN-Cache-Control": toEdgeCacheControl(input.cacheControl),
+			"Cache-Tag": cacheTag
 		};
-		if (input.tags && input.tags.length > 0) {
-			const cacheTag = formatCacheTag(input.tags);
-			if (cacheTag) headers["Cache-Tag"] = cacheTag;
-		}
-		return headers;
 	}
 	/** Purge edge-cached responses by tag via the request context's `cache.purge`. */
 	async revalidateTag(tags, _durations) {
 		const cache = getWorkersCache();
 		if (!cache) return;
-		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string" && t.length > 0);
+		const tagList = (Array.isArray(tags) ? tags : [tags]).filter((t) => typeof t === "string");
 		if (tagList.length === 0) return;
-		await cache.purge({ tags: tagList });
+		const result = await cache.purge({ tags: tagList.map(encodeCloudflareCacheTag) });
+		if (result?.success === false) {
+			const errors = result.errors.map(({ code, message }) => `${code}: ${message}`).join(", ");
+			throw new Error(`[vinext] Workers Cache purge failed${errors ? `: ${errors}` : ""}`);
+		}
 	}
 };
-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 };
+export { CloudflareCdnCacheAdapter, createCloudflareCdnCacheAdapter as default, encodeCloudflareCacheTag };