test(cache): verify dev "use cache" parity for cacheMaxMemorySize: 0 and custom handlers (#2110)

[Divkix]

Summary

Closes #2110.

Issue #2110 is a nextjs-tracking parity item asking whether vinext needs Next.js PR #94784's dev-only TieredCacheHandler. That PR fixes warm next dev reloads being treated as cold cache misses under Cache Components when cacheMaxMemorySize: 0 installs a no-op stub or a custom cache handler's get is slow/remote.

Finding: vinext is immune by design and needs no TieredCacheHandler. Next.js's bug is that dev reads the configured cache handler during a staged render, and a read that doesn't resolve in a microtask is counted as a miss. vinext's dev "use cache" path never reads the handler — registerCachedFunction short-circuits in dev (packages/vinext/src/shims/cache-runtime.ts, the if (isDev) return executeWithContext(...) branch) and re-executes the function so HMR edits are reflected immediately. Therefore:

• cacheMaxMemorySize: 0 only configures the production/ISR MemoryCacheHandler; it is never on the dev "use cache" read path.
• A slow or remote custom data handler is never consulted by dev "use cache", so its latency cannot surface as a cold miss.
• "use cache: private" uses a per-request Map, never sized from cacheMaxMemorySize, so it cannot degrade to a no-op stub (the dev-private sub-case Next.js also fixed).

Porting TieredCacheHandler as-is would be inert dead code, so per the repo's "no speculative/dead code" guidance this PR verifies, documents, and locks in the divergence with regression tests. No runtime behavior change.

Changes

• tests/shims.test.ts — new dev cache parity describe block in the "use cache" runtime suite:
  • dev cacheMaxMemorySize: 0 still returns the real value (no cold miss)
  • dev never consults a slow/remote custom handler's get/set
  • dev "use cache: private" still caches per-request under size-0
  • dev revalidateTag still reaches the configured handler under size-0
  • production parity guard: size-0 caches nothing → re-executes
• packages/vinext/src/shims/cache-runtime.ts — expand the if (isDev) comment to explain the immunity and reference Dev cache parity: make cacheMaxMemorySize: 0 and custom cache handlers fast in dev (TieredCacheHandler) #2110 / Next.js #94784.
• AGENTS.md — new "Architecture & Gotchas" subsection documenting this deliberate, verified divergence.

Testing

vp test run tests/shims.test.ts -t "use cache"   # 48 passed
vp check tests/shims.test.ts packages/vinext/src/shims/cache-runtime.ts   # clean

Upstream references

• Next.js PR: Make cacheMaxMemorySize: 0 and custom cache handlers fast in dev vercel/next.js#94784
• Next.js commit: vercel/next.js@96e9a8e

[pkg-pr-new]

Open in StackBlitz

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

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

commit: b49ff59

[github-actions]

Performance benchmarks

Compared b49ff59 against base 42f8700.

0 improved · 4 regressed · 2 within ±1.5%

Scenario	Framework	Baseline	Current	Change
Client bundle size (gzip)	Next.js	185.6 KB	185.6 KB	⚫ 0.0%
Client bundle size (gzip)	vinext	129.9 KB	129.9 KB	⚫ -0.0%
Dev server cold start	Next.js	2.26 s	2.54 s	🔴 +12.1%
Dev server cold start	vinext	2.44 s	2.69 s	🔴 +10.2%
Production build time	Next.js	3.98 s	4.59 s	🔴 +15.3%
Production build time	vinext	2.66 s	3.09 s	🔴 +16.4%

View detailed results and traces

_{🟢 improvement · 🔴 regression · ⚫ change below 1.5%}