perf(router): benchmark lazy-include double-run; record LP3 deferral with data - #545

What & why

No behavior change. This adds the lazy-eval / loadManifest / cold-start timing benchmark that docs/internal/matching-stability-review.md explicitly asked for, and uses it to turn the vague LP3 "needs-design" item into a measured decision to defer.

LP3 is the match-time + render-time double handler execution for a non-leaf include — a module with path() routes alongside a nested include(), so it is never precomputed and runs its handler once in evaluateLazyEntry (match) and again in loadManifest (render).

The numbers (vitest bench lazy-include-cost)

Reading: the redundant run is ~0.75 µs/route and ~50% of the manifest-build cost — but manifest-build is itself microseconds, and a real RSC first request (render + Flight + SSR) is milliseconds, so the waste is < 0.5% of a cold first request. It's paid once per route per isolate and amortizes to ~0 (warm cache hit ~0.8–1.8 µs).

Decision: defer LP3

• Common case is already 1 run — leaf includes are precomputed (C8/LP2); only the render run executes. The residual double-run is a non-leaf include's direct routes.
• Removing it is entangled with LP4. The match-time tree is built in a throwaway "lazy" namespace without isSSR (which isn't even known at match time), so reusing it for render requires splitting isSSR-dependent state out of the cached tree — the LP4 refactor, touching shortCodes and the semantic matrix.
• Risk ≫ reward for a sub-µs-per-route, amortizes-to-zero cold-start cost. Deferred as a documented decision, not planned work. LP4 is the gate for ever revisiting it.

Changes

• src/router/__tests__/lazy-include-cost.bench.ts (new) — vitest bench: construct / match (LP3 waste) / render-cold / warm across 5- and 50-route non-leaf includes. .bench.ts, so excluded from the default vitest run.
• lazy-include-perf.test.ts — clarify the Part B 2 sentinel simulates the pre-C8 (shortcut-disabled) path and is expected to stay 2; rewrite the LP3 it.todo with the measured numbers + deferral rationale.
• docs/internal/matching-stability-review.md — LP3 section rewritten as MEASURED / DEFERRED with the numbers and the LP4 entanglement; Follow-up updated (benchmark done; LP4 gates any LP3 revisit).

Test plan

• typecheck clean (covers the .bench.ts)
• unit 3383 pass / 6 todo — bench correctly excluded from the run (185 files, unchanged)
• lint + format clean; pre-commit (lint/format/e2e-bucketing) green
• bench runs: vitest bench lazy-include-cost produces the table above
• no behavior change → no new e2e; existing suites unaffected

Notes

• Sibling of the just-merged fix(router): drop shared-staticPrefix precomputed shortcut (C19) + R3 warn + e2e parity #544 (C19); built on the same investigation. LP1 and LP4 remain deferred and unchanged.