perf(router): cold-start at route scale — manifest sharding per prefix, or a documented warmup pattern #665

Problem

At 26,363 routes the deployed worker's very first request costs ~646ms vs a ~23ms warm floor (BENCHMARK-2026-07-04-edge-26k.md, n=1 post-deploy, CF-reported isolate startup 78ms). The cost concentrates in first-request work:

• the routes-manifest chunk (5.7MB raw at this scale) is JSON.parsed once on the first request via the lazy manifest loader (src/vite/discovery/virtual-module-codegen.ts registerRouterManifestLoader);
• the named-routes chunk (1.15MB) is statically imported by the worker entry, so it is inside the 78ms startup;
• each include group then pays chunk eval on its own first hit, scaling with routes-per-chunk: 188ms for the ~9k-route group, 137ms for ~5k, ~75ms for a 240-route group.

Per-request matching is flat (trie), so cold start is where route count now costs — and it is paid by one unlucky user per isolate.

Directions (independent levers)

1. Manifest sharding per include prefix: emit the precomputed trie/entries per group so the first request parses root + the target group only, not the whole table. Biggest structural win; interacts with the bundle-hygiene rule that generated route data lives in exactly one (lazy) chunk — sharding means one lazy chunk per group instead.
2. Lazy-parse trie subtrees: keep one chunk but defer JSON.parse of per-group subtrees until first touch.
3. Short-term, docs-only: document a post-deploy warmup ping pattern (hit each include prefix once after deploy) in the deployment-facing skills. The stress app's bench harness already does exactly this sequence (bench/scenarios.ts coldStartPaths).

Evidence

tests/cloudflare-stress-demo/BENCHMARK-2026-07-04-edge-26k.md — cold table (646ms first request; per-chunk first-hit costs) and methodology (bench/run.ts --url right after wrangler deploy).