fix(cache): certify staged cache fills before promotion

[james-elicx]

Capability stack 7/9. Exact head: de0d12e4f27aa266418e5e1daa3a2044324da7cb. Base: #3093.

Full chain: #3108 → #3090 → #3091 → #3092 → #3103 → #3093 → #3094 → #3098 → #3113.

Summary

Add an optional header-only certification pass for successfully warmed cache keys before promotion.

The default two-stage flow issues one cache-fill request per identity. Certification is enabled only with --warm-cdn-certify; it then re-requests each warmed identity and accepts only HIT, REVALIDATED, or UPDATING as proof that the entry is reusable. Cached response bodies are cancelled rather than downloaded again, and promotion aborts if deployment traffic changes. The dangerous warmup override cannot bypass an enabled certification pass. --warm-cdn-certify is rejected unless --experimental-warm-cdn-cache is also supplied, and every planned initial fill must succeed before certification or promotion.

The deployed Cloudflare E2E also purges a warmed App Page and asserts MISS → HIT, proving that embedded classification continues to admit safe cold fills after cache loss.

Why opt-in

Certification gives stronger deployment-time evidence, but doubles requests for warmed identities. Keeping it behind a CLI flag preserves the performance benefit of normal cache warming while allowing stricter deployments to choose the extra verification.

Review guide

1. packages/cloudflare/src/cdn-warm.ts performs header-only cache certification and defines accepted cache states.
2. packages/cloudflare/src/deploy.ts gates certification on warmCdnCertify and relies on feat(cache): deploy probed manifests in two stages #3093's traffic checks before promotion.
3. packages/cloudflare/src/cli.ts and deploy-help.ts expose --warm-cdn-certify.
4. tests/cloudflare-cdn-warm.test.ts covers accepted/rejected cache states without consuming bodies.
5. The Cloudflare README documents the required version_metadata binding, including repetition in named Wrangler environments.
6. tests/cloudflare-cdn-warm-deploy.test.ts proves one request by default, rejects invalid flag combinations, and requires complete initial-fill success before opt-in certification.
7. tests/e2e/cloudflare-workers/rsc-prewarm.spec.ts proves warmed reuse and post-purge admission on the real CDN.

Review size

Layer-only diff against this PR's base: 10 files, +525/-29.

Validation

• default-flow regression proves one final fill request per identity
• certification adds a second, header-only request only with --warm-cdn-certify
• current full-stack cumulative changed-file suites — 2,864/2,864
• current full-stack PPR probe/admission/Pages built-workerd E2E — 8/8
• current full-stack vp check and git diff --check
• layer exact-head CI and deploy previews are green

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@vinext/cloudflare@3094

npm i https://pkg.pr.new/create-vinext-app@3094

npm i https://pkg.pr.new/@vinext/types@3094

npm i https://pkg.pr.new/vinext@3094

commit: de0d12e

[github-actions]

Performance benchmarks

Compared de0d12e against base 03d5e5e using alternating same-runner rounds. Next.js was unchanged and skipped.

0 improved · 0 regressed · 6 within ±1.5%

Scenario	Framework	Baseline	Current	Change
Client bundle size (gzip)	vinext	142.3 KB	142.3 KB	⚫ +0.0%
Client entry size (gzip)	vinext	129.6 KB	129.6 KB	⚫ +0.0%
Dev server cold start	vinext	3.38 s	3.40 s	⚫ +0.6%
Production build time	vinext	3.78 s	3.77 s	⚫ -0.4%
RSC entry closure size (gzip)	vinext	118.9 KB	118.9 KB	⚫ -0.0%
Server bundle size (gzip)	vinext	202.3 KB	202.3 KB	⚫ -0.0%

View detailed results and traces

_{🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head}

[github-actions]

Example	Preview	Production	Original
app-router-cloudflare	preview	production
pages-router-cloudflare	preview	production
app-router-playground	preview	production	original
realworld-api-rest	preview	production
nextra-docs-template	preview	production
benchmarks	preview	production
hackernews	preview	production	original
workers-cache	preview	production
static-export	preview	production
web	preview	production