fix(caching/ppr): audit remediation — redirect guard, host key, base64 bound, SSR capture hardening, +docs/diagnostics - #685

Problem statement

An audit of the caching / cache-tags / revalidation, PPR + render-pipeline, and PPR×action subsystems surfaced a set of correctness, robustness, and coverage gaps. This PR lands the eight that were safe to fix now; each is independent and file-disjoint. Deferred/held items (a loader-HIT optimization that proved unsafe as a skip, two investigate-first hypotheses, and DRY consolidations) are tracked in #684.

Every finding was adversarially re-verified against the current code before a fix was written, and the one behavior-sensitive claim (SSR abort discrimination) was confirmed empirically against real react-dom/static.edge.

What's included

Before vs. after (representative — the two consumer-facing ones)

Render-callable cacheTag() — the docs now show the shipped form:

// A plain server component makes the PPR shell tag-invalidatable with NO
// "use cache" in its tree — the tag rides ctx._requestTags onto the shell entry.
function CampaignBanner() {
  cacheTag("campaign:spring");
  return <aside>Spring sale</aside>;
}
// revalidateTag("campaign:spring") then evicts that shell.

Multi-tenant document cache — before, getResponse("/pricing:html") collided across hosts; after, the default key is a.example/pricing:html vs b.example/pricing:html. A consumer supplying a custom keyGenerator still owns their own namespacing (JSDoc warns to include host).

Semantics table (behavior that branches)

Test plan

• pnpm run typecheck (turbo, 16/16 packages) — exit 0
• pnpm run test:unit:all (unit + rsc, every package incl. cloudflare-basic / vite-rsc-demo dogfood suites) — all pass; router package 319 files / 4979 tests
• pnpm run lint (oxlint --deny-warnings) — 0/0
• pnpm run format — clean
• pnpm check:e2e-bucketing — OK (lefthook-verified on every commit)
• Navigation-loading (production) project — 10/10 pass locally
• New tests pin each fix (all proven red-before-green):
  • shell-hit-redirect-guard.test.ts — cross-origin→root, protocol-relative→off-host, same-origin passthrough (reverting the helper → 4 failed)
  • document-cache.test.ts — cross-host isolation MISS (reverting the host prefix → served the wrong tenant's body)
  • vercel-cache-store.test.ts — >32 KB high-byte body round-trips without overflow
  • cf-cache-store-tags.test.ts — warns exactly once per namespace; no warn when TTL set
  • shell-capture-untagged-bake.test.ts — warn once per key; no warn when tagged / ppr.tags / hole-only / production
  • shell-handlers.test.tsx — a genuine AbortError-named throw propagates (was masked); hung bootstrap degrades bounded

Notes

• SSR abort discrimination was validated against real react-dom/static.edge: our own controller.abort(reason) resolves (holes postpone / trivial prelude → sanity gate), and a genuine fatal throw rejects with the thrown error (!== abortReason → propagates). The modified abort itself rejects fake exercises a defensive branch; the load-bearing red→green is the genuine-throw propagation.
• Document-cache and CF no-TTL are the only two with an operational footprint: the host-key change cold-starts document-cache entries once on deploy; the CF warning is diagnostic-only.
• Follow-ups (DRY consolidations, the deferred shell-redirect e2e, held loader-HIT redesign, two investigate plans, SSR-03/04) are tracked in Follow-ups: caching/PPR/render-pipeline audit (DRY consolidations, deferred coverage, held/investigate items) #684.
• Held out of this PR: the hole-free loader-HIT skip (unsafe — executeLoaderData has unconditional telemetry/tag/interceptor side effects the HIT path relies on; needs a capture-time-replay redesign).