Phase 2/2: Finalize ALS rollout with parity tests, cleanup, and docs #478
Description
Why This Issue Exists
Phase 1 (#451 / PR #450) already landed the core unified request-context rollout, including the main Pages Router entry points. The remaining work is follow-up validation, cleanup, and documentation rather than another large implementation pass.
This issue is an umbrella follow-up for the ALS rollout and may span more than one PR.
Recommended Execution Order
First follow-up PR (required)
Focus on correctness, parity validation, and documentation:
- Add Pages Router integration tests for concurrent SSR isolation in dev and prod
- Verify
<Head>elements do not leak between concurrent requests - Verify router SSR context does not leak between concurrent requests
- Validate the production Pages Router path, which currently reaches the unified scope through
renderPage()rather than a separate wrapper inprod-server.ts - Document the decision for per-call ALS scopes:
cacheContextStorageincache-runtime.ts_unstableCacheAlsincache.ts
- Add ALS architecture documentation
Later cleanup PR (optional / conditional)
Only remove standalone fallback ALS paths if the parity tests and production validation show they are truly unnecessary. If they still serve SSR, entry-wrapper, or test compatibility needs, defer deletion and record the rationale here.
Scope
1. Pages Router parity and coverage
- Add Pages Router integration tests for concurrent SSR isolation in dev and prod
- Verify
<Head>elements do not leak between concurrent requests - Verify router SSR context does not leak between concurrent requests
- Validate the production Pages Router path, which currently reaches the unified scope through
renderPage()rather than a separate wrapper inprod-server.ts
2. Per-call ALS evaluation
Evaluate and document whether these should remain separate from the unified request scope:
cacheContextStorageincache-runtime.ts_unstableCacheAlsincache.ts
Expected default: keep them separate unless benchmarking or correctness findings show otherwise, since they are semantically per-call rather than per-request.
3. Dual-path fallback cleanup
Once parity tests are in place and the rollout has had time to bake, remove standalone fallback ALS code only where it is clearly unnecessary:
headers.tsnavigation-state.tscache.tscache-runtime.ts(fallback/private-cache path only)fetch-cache.tsrequest-context.tsonly if validation proves the standalone behavior is no longer needed for outer entry-wrapper flowsrouter-state.tshead-state.ts
If some fallback paths still serve SSR, test, or entry-wrapper compatibility, keep them and document that decision instead of forcing deletion.
4. Documentation
- Add an ALS architecture document explaining the final split between unified request scope and per-call cache scopes
- Document contributor guidance for adding new request-scoped state
Acceptance Criteria
- Pages Router dev concurrency tests added
- Pages Router prod concurrency tests added
- Head and router SSR isolation verified under concurrent requests
- Production Pages Router unified path validated
- Decision documented for
cacheContextStorageand_unstableCacheAls - ALS architecture documented
- Fallback cleanup completed, or explicitly deferred with rationale
- Typecheck, lint, format, and targeted tests are clean