fix: reject ambiguous module routes

A module can register both `GET /events/:id` and `GET /events/new`. Driven
through the pinned router, `/events/new` reached the parameter handler under
`demo.events.read` when the parameter route registered first, and the static
handler under `demo.events.create` when it registered second. Nothing rejected
the pair, so declaration order decided which permission guarded the path. That
is a permission policy, not a routing preference, and it must not be inferred
from array position.

Two routes of one module now overlap when they share a method and a segment
count and, at every position, either both segments are the same static literal
or at least one is a parameter. Under this grammar — static literals or `:name`
parameters, no wildcard, regex, optional, or catch-all — that is exactly "some
concrete request path matches both". `moduleRoutesOverlap` implements it in the
contracts package, where path semantics already live and Hono cannot reach.

Core checks it during staged registration, after the existing duplicate check,
so identical shapes (including paths differing only in parameter name) keep
returning MODULE_ROUTE_DUPLICATE and a genuine intersection returns the new
MODULE_ROUTE_OVERLAP. The rejected module publishes none of its staged routes or
capabilities, no start hook runs, and no listener binds. Rejection rather than a
specificity rule: ranking static above parameter would still silently pick which
permission applies. Disjoint routes keep their order; different methods,
different segment counts, and the same local path in two different modules
(each has its own platform-owned mount prefix) all remain legal.

The same requests also pinned down what handlers actually receive. Route
declarations are validated; route *parameters* are not, and the two are
unrelated. A single encoded segment arrives decoded as `/../admin`, `a\b`, an
embedded NUL, CR/LF, `1; drop`, or non-ASCII text — none of which any declared
path could contain. The contract now says so explicitly: decoded values are
untrusted, module-owned input that a handler must validate against its own exact
domain grammar before any database, filesystem, command, or identifier use, and
re-encoding is not a substitute. No generic validator, path-normalization layer,
or route field was added, because module parameters are module-owned domain
types and one platform-wide pattern would either reject legitimate values or
approve meaningless ones.

Co-Authored-By: Claude Opus 5 <[email protected]>

packages/contracts/tests/module-http.test.ts

@@ -6,6 +6,7 @@ import {
   type ModuleRouteDefinitionInput,
   moduleRoutePathSchema,
   moduleRouteShapeKey,
+  moduleRoutesOverlap,
   parseModuleRouteDefinition,
   parseModuleRoutePath,
   safeParseModuleRouteDefinition,
@@ -294,3 +295,42 @@ describe("parseModuleRouteDefinition", () => {
     }
   });
 });
+
+describe("moduleRoutesOverlap", () => {
+  const route = (method: "GET" | "POST", path: string) => ({
+    method,
+    path: parseModuleRoutePath(path),
+  });
+
+  it.each([
+    ["a parameter against a static literal", "/events/:id", "/events/new"],
+    ["a later position", "/events/:id/edit", "/events/new/:action"],
+    ["parameters on both sides at different positions", "/a/:left/c", "/a/b/:right"],
+    ["identical parameter shapes with different names", "/events/:id", "/events/:eventId"],
+    ["identical static paths", "/events/new", "/events/new"],
+    ["root against root", "/", "/"],
+  ])("reports an overlap for %s", (_label, first, second) => {
+    expect(moduleRoutesOverlap(route("GET", first), route("GET", second))).toBe(true);
+    // The relation is symmetric, so registration order cannot change the verdict.
+    expect(moduleRoutesOverlap(route("GET", second), route("GET", first))).toBe(true);
+  });
+
+  it.each([
+    ["two different static literals", "/events/new", "/events/archive"],
+    ["different segment counts", "/events/:id", "/events/:id/edit"],
+    ["a static prefix that differs earlier", "/events/:id", "/people/:id"],
+    ["root against a one-segment path", "/", "/events"],
+  ])("reports no overlap for %s", (_label, first, second) => {
+    expect(moduleRoutesOverlap(route("GET", first), route("GET", second))).toBe(false);
+    expect(moduleRoutesOverlap(route("GET", second), route("GET", first))).toBe(false);
+  });
+
+  it("never reports an overlap across different methods", () => {
+    expect(moduleRoutesOverlap(route("GET", "/events/:id"), route("POST", "/events/new"))).toBe(
+      false,
+    );
+    expect(moduleRoutesOverlap(route("GET", "/events/new"), route("POST", "/events/new"))).toBe(
+      false,
+    );
+  });
+});