fix(router): drop shared-staticPrefix precomputed shortcut (C19) + R3 warn + e2e parity - #544

Problem

If two include()s resolve to the same static prefix — which happens whenever a dynamic param eats their literal prefix (e.g. /shop/:category and /shop/:brand both reduce to "/shop") — and at least one of them is discovered lazily (nested inside another include), a request to one of those routes returns an opaque 500 (RouteNotFoundError) on a route that genuinely exists. The failure is identical in dev and production and is permanent for the isolate once triggered. From the consumer's seat: a valid URL that should render simply 500s, with no hint that two includes "collided."

Mechanically: the precomputed match shortcut was built as new Map(entries.map(e => [e.staticPrefix, e.routes])). A JS Map is last-wins on duplicate keys, so one include's routes were silently dropped and the survivor's routes were mis-assigned to whichever lazy entry evaluated first. The existing prefixIsShared guard counts only already-spliced route entries, so it is blind to a nested sibling that hasn't been discovered yet — leaving a window where the shortcut fires with the wrong routes. findMatch then selects the wrong include's entry (its corrupted routes contain the sibling's key), loadManifest runs the wrong handler, and the Store.manifest.has(routeKey) invariant fails.

This branch had zero coverage — every test passed getPrecomputedByPrefix: () => null, so the collapse path was never exercised.

Before vs. after (consumer)

// urls.ts (root)
export default urls(({ include }) => [
  include("/shop/:category", () => import("./category")), // staticPrefix "/shop"
  include("", () => import("./storefront")),              // root-scoped feature
]);

// storefront.ts — nested include, discovered lazily on first hit
export default urls(({ include }) => [
  include("/shop/:brand", () => import("./brand")),       // ALSO staticPrefix "/shop"
]);

// category.ts →  path("/page", CategoryPage, { name: "page" })  →  /shop/:category/page
// brand.ts    →  path("/list", BrandList,    { name: "list" })  →  /shop/:brand/list

What a consumer does differently

Nothing. This is a pure correctness fix — no API change, no migration. Consumers who never hit a shared-static-prefix + lazy-nested combination are unaffected; consumers who did were getting a 500 and now get the correct route.

Why this fix shape

Two distinct includes under one static prefix cannot be collapsed to a single routes object (last-wins drops data) and must not be merged (assigning a merged set to the first matching entry makes findMatch pick the wrong handler — the exact failure here). So buildPrecomputedByPrefix omits any static prefix owned by more than one leaf include from the shortcut. Those includes fall through to the handler path — the ground truth, identical to behavior before the shortcut existed.

Because the shortcut is purely an optimization, dropping a prefix can only ever cost a handler run; it can never change a result. The fix lives at the single point where the array becomes a Map (router.ts); the precomputed array shape (asserted by per-router-manifest.test.ts) is untouched.

- precomputedByPrefix = current
-   ? new Map(current.map((e) => [e.staticPrefix, e.routes]))
-   : null;
+ // shared staticPrefix -> omitted (resolve via handler path) instead of last-wins collapse
+ precomputedByPrefix = current ? buildPrecomputedByPrefix(current) : null;

The timing-blind prefixIsShared check in lazy-includes.ts is kept as defense-in-depth, with a comment recording that the load-bearing protection now lives upstream.

Bonus: R3 dev-warning false positive

The dev-only "route resolved via the regex fallback even though the trie was present — please report this" warning fired on the first request to a 2+-level nested lazy include (the trie matched, but its entry hadn't been spliced yet, so resolution fell to the regex path). That is the supported lazy-splicing flow, not a trie gap. The warning is now suppressed when the trie did match (trieMatched); genuine trie gaps still warn. This stops the router from manufacturing false bug reports.

Why the C19 repro is an integration test, not a live HTTP e2e

The corruption only fires when the top-level entry is evaluated while its nested sibling is not yet spliced — i.e. a /shop request must be the very first handler-triggering request to a cold isolate, before any sp:"" request splices the sibling. A shared Playwright worker/dev-server isolate (plus build-time route discovery, which also evaluates handlers) cannot guarantee that ordering, so an HTTP e2e would pass regardless of the fix — false assurance.

Instead, the repro drives the real createFindMatch → evaluateLazyEntry → loadManifest chain in the exact evaluate-alone → splice → request sequence. Verified by toggling the fix: old collapse routes the brand request to the wrong include and loadManifest throws (the 500); the fix routes it to the right include and it renders.

Code-change summary

• src/build/prefix-tree-utils.ts — new pure buildPrecomputedByPrefix(entries); omits shared static prefixes.
• src/router.ts — getPrecomputedByPrefix uses it instead of the last-wins Map.
• src/router/lazy-includes.ts — prefixIsShared comment updated (protection moved upstream; live-count is timing-blind defense-in-depth).
• src/router/find-match.ts — track trieMatched; suppress the R3 warning on lazy-splicing lag.
• docs/internal/matching-stability-review.md — Pass 2 section documenting C19.

Test plan

• Unit — precomputed-prefix-collision.test.ts (new): real config emits duplicate-staticPrefix leaves; naive collapse loses routes vs. buildPrecomputedByPrefix omits the shared prefix and keeps unshared ones; evaluateLazyEntry no longer mis-assigns; request-path integration test (real findMatch → loadManifest, old collapse 500s, fix renders).
• Unit — find-match.test.ts: R3 suppress-on-lazy-lag and warn-on-genuine-gap.
• E2e (dev + production) — cloudflare-basic/e2e/trie-routing.test.ts converted to a dev + (production) factory; new /files/* route + C1 bare-prefix empty-splat assertion (/files → "", /files/a/b → a/b) verified in both modes. router.named-routes.gen.ts updated for filesWildcard.
• typecheck clean · unit 3383 pass / 6 todo · lint clean · format clean · e2e-bucketing guard OK.

Notes

• No deprecation / no migration — pure correctness fix; existing behavior for distinct-prefix and all-live-sibling cases is unchanged.
• The deferred lazy-include perf items (LP1/LP3/LP4) were independently re-audited during this work and confirmed correctness-neutral (run-count only); they remain tracked as it.todo + the matching-stability doc. This PR does not touch them.