fix(cache): SWR background revalidation under a derived context — no shared handle-store swap, no shared-arg stamping (#684 plan 010) - #689

Closes out the plan-010 investigate item of #684 (full trace + original repro in the issue comment).

Problem statement

On a stale "use cache" hit, the value is served immediately and the function re-runs in the background via waitUntil. Production waitUntil is Promise.resolve().then(fn) (request-context.ts), so the background prologue runs one microtask after scheduling — while the foreground is still rendering the rest of the page. That prologue swapped the shared requestCtx._handleStore in place (restored only in a finally, i.e. after the entire revalidation, including its origin I/O) and stamped INSIDE_CACHE_EXEC onto shared tainted args. For a consumer, during that window: breadcrumbs/metadata pushed by any handler rendering after the stale hit silently vanished from the live document AND were persisted into the revalidated cache entry (served to later visitors); and a plain ctx.set() / ctx.headers.set() in a downstream handler threw INSIDE_CACHE_EXEC — an error blaming code that isn't inside any cache function. The existing tests pinned the hazardous behavior behind queue-style waitUntil mocks that run the background only after the foreground finishes — the one ordering production never has.

Before vs. after

// Layout: stale "use cache" hit serves immediately, revalidation starts in background
const product = await getCachedProduct(ctx); // stale hit -> bg revalidation scheduled

// ...meanwhile, a sibling/downstream handler still rendering this SAME request:
ctx.use(Breadcrumbs)({ label: product.name }); // BEFORE: lost from the document
                                               //         AND baked into the revalidated entry
ctx.set(someVar, value);                       // BEFORE: throws INSIDE_CACHE_EXEC
                                               // AFTER: both just work

What changed

src/cache/cache-runtime.ts, stale-hit branch only:

• The background body now runs under a derived context — Object.create(requestCtx) with an own _handleStore (the established shell-capture isolation pattern, shell-capture.ts attemptCapture) — passed to the existing runWithRequestContext. Background pushes land in the isolated store and are captured/persisted with the entry exactly as before; the foreground's store is never touched; the restore step is gone because nothing shared is mutated.
• The background no longer stamps INSIDE_CACHE_EXEC onto shared args (or requestCtx). In-fn misuse is caught by the foreground miss path's stamps on the function's first execution — an entry only becomes stale-revalidatable because a stamped miss ran clean and stored it. That load-bearing invariant is now documented at the miss-path stamp itself (per the /simplify altitude review), so a future refactor of the stamp sees the coupling.

Semantics table

Test plan

• Red-before-green (cache-runtime-stale.test.ts): 2 failed | 18 passed on the old code → 20 passed with the fix.
  • Rewritten pin: "does NOT stamp INSIDE_CACHE_EXEC on shared tainted args during stale background revalidation" (previously asserted the stamp).
  • New: "background revalidation never mutates the shared context mid-render (production-faithful microtask scheduling)" — uses Promise.resolve().then(fn) scheduling and gates the background open to inspect the overlap window: shared store not swapped, no stamp, foreground push reaches the live store, revalidated entry carries only the background's push.
  • The mocked runWithRequestContext now threads its ctx (the old passthrough would hide the isolation under test).
• /simplify ran before push (4 agents): applied — collapsed the bgCtx/bgHandleStore double-ternary to one condition; removed the stale header comment ("completed store" / "same pattern as background-revalidation.ts" — both no longer true); added the invariant note at the miss-path stamp. Skipped — importing INSIDE_CACHE_EXEC from taint.js in the new test (the Symbol.for re-derivation is the file's existing idiom at four other sites). Efficiency/reuse angles came back clean.
• pnpm run typecheck 16/16; pnpm run test:unit:all all packages green (router 4983 + 6 todo); pnpm run lint 0/0; pnpm run format clean.
• No new e2e: the fix removes a mid-render race whose window is one microtask wide — a browser e2e cannot pin it deterministically; the production-faithful-scheduling unit test is the deterministic equivalent. Existing SWR value-semantics e2e (use-cache suites) are unaffected and cover the consumer-visible caching behavior in dev + production.

Notes

• The two remaining in-place _handleStore swaps (match-middleware/cache-store.ts, background-revalidation.ts) are safe by ordering — they swap only after the response is returned / the foreground drained. Verified during the /simplify altitude pass; no mid-render swap remains in src/cache/.
• Remaining Follow-ups: caching/PPR/render-pipeline audit (DRY consolidations, deferred coverage, held/investigate items) #684 items after this: plan 009 (capture barrier wiring), A4 diagnostics batch (blocked on PPR operability: snapshot size guard, capture diagnostics, and the silent missing-KV no-op #651/PPR capture pipeline hardening: narrow the write barrier, unify bounded drains, tame the backoff-vs-CI flake #652).