@nifrajs/core 3.3.0 → 4.0.0

package/src/manifest.ts

@@ -12,10 +12,9 @@ import {
   diffRouteSnapshots,
   type RouteChange,
   type RouteSnapshotSchema,
-  snapshotRoutes,
 } from "./diff.ts"
-import type { ProjectEvidenceSnapshot } from "./evidence.ts"
-import { reflectRoutes } from "./reflection.ts"
+import { type ProjectEvidenceSnapshot, snapshotProjectEvidence } from "./evidence.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 
 export interface NifraManifestAssurance {
   readonly rule?: string
@@ -190,25 +189,28 @@ export async function buildNifraManifest(input: BuildNifraManifestInput): Promis
   if (input.evidence?.capabilities !== undefined && !input.evidence.capabilities.ok) {
     throw new Error("nifra manifest: refusing to emit failing capability assurance")
   }
+  const evidence =
+    input.evidence ??
+    snapshotProjectEvidence(input.source, {
+      ...(input.assurance === undefined ? {} : { assurance: input.assurance }),
+      ...(input.capabilities === undefined ? {} : { capabilities: input.capabilities }),
+    })
   const reflected = new Map(
-    (input.evidence?.routes ?? reflectRoutes(input.source)).map((route) => [
-      routeKey(route.method, route.path),
-      route,
-    ]),
+    evidence.routes.map((route) => [routeKey(route.method, route.path), route]),
   )
   const assured = new Map(
-    (input.evidence?.assurance?.routes ?? input.assurance?.routes ?? []).map((route) => [
+    (evidence.assurance?.routes ?? input.assurance?.routes ?? []).map((route) => [
       routeKey(route.method, route.path),
       route,
     ]),
   )
   const capable = new Map(
-    (input.evidence?.capabilities?.routes ?? input.capabilities?.routes ?? []).map((route) => [
+    (evidence.capabilities?.routes ?? input.capabilities?.routes ?? []).map((route) => [
       routeKey(route.method, route.path),
       route,
     ]),
   )
-  const routes = (input.evidence?.routes ?? snapshotRoutes(input.source))
+  const routes = evidence.routes
     .map((route): NifraManifestRoute => {
       const key = routeKey(route.method, route.path)
       const reflection = reflected.get(key)
@@ -225,7 +227,7 @@ export async function buildNifraManifest(input: BuildNifraManifestInput): Promis
                 evidence: Object.freeze(
                   [...assurance.evidence]
                     .map((item) => ({ id: item.id, source: item.source }))
-                    .sort((a, b) => a.id.localeCompare(b.id) || a.source.localeCompare(b.source)),
+                    .sort((a, b) => codeUnitOrder(a.id, b.id) || codeUnitOrder(a.source, b.source)),
                 ),
               },
             }
@@ -245,7 +247,7 @@ export async function buildNifraManifest(input: BuildNifraManifestInput): Promis
           : {}),
       }
     })
-    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    .sort((a, b) => codeUnitOrder(a.path, b.path) || codeUnitOrder(a.method, b.method))
   const body = Object.freeze({ manifestVersion: 1 as const, routes: Object.freeze(routes) })
   return Object.freeze({ ...body, contentHash: await sha256Hex(canonicalManifest(body)) })
 }
@@ -461,44 +463,48 @@ export function diffNifraManifests(before: NifraManifest, after: NifraManifest):
     before.routes.map((route) => [routeKey(route.method, route.path), route]),
   )
   for (const route of after.routes) {
-    const old = previous.get(routeKey(route.method, route.path))
-    if (old === undefined) continue
+    const existing = previous.get(routeKey(route.method, route.path))
     const base = { method: route.method, path: route.path } as const
 
-    const oldRule = old.assurance?.rule
-    const newRule = route.assurance?.rule
-    if (oldRule !== newRule) {
-      changes.push({
-        ...base,
-        section: "assurance",
-        severity: "breaking",
-        message: `assurance rule changed from ${oldRule ?? "unclassified"} to ${newRule ?? "unclassified"}`,
-      })
-    }
-    const oldEvidence = (old.assurance?.evidence ?? [])
-      .map((item) => `${item.id}@${item.source}`)
-      .sort()
-    const newEvidence = (route.assurance?.evidence ?? [])
-      .map((item) => `${item.id}@${item.source}`)
-      .sort()
-    const assuranceDelta = listChanges(oldEvidence, newEvidence)
-    for (const value of assuranceDelta.added) {
-      changes.push({
-        ...base,
-        section: "assurance",
-        severity: "compatible",
-        message: `assurance evidence added ${value}`,
-      })
-    }
-    for (const value of assuranceDelta.removed) {
-      changes.push({
-        ...base,
-        section: "assurance",
-        severity: "breaking",
-        message: `assurance evidence removed ${value}`,
-      })
+    if (existing !== undefined) {
+      const oldRule = existing.assurance?.rule
+      const newRule = route.assurance?.rule
+      if (oldRule !== newRule) {
+        changes.push({
+          ...base,
+          section: "assurance",
+          severity: "breaking",
+          message: `assurance rule changed from ${oldRule ?? "unclassified"} to ${newRule ?? "unclassified"}`,
+        })
+      }
+      const oldEvidence = (existing.assurance?.evidence ?? [])
+        .map((item) => `${item.id}@${item.source}`)
+        .sort()
+      const newEvidence = (route.assurance?.evidence ?? [])
+        .map((item) => `${item.id}@${item.source}`)
+        .sort()
+      const assuranceDelta = listChanges(oldEvidence, newEvidence)
+      for (const value of assuranceDelta.added) {
+        changes.push({
+          ...base,
+          section: "assurance",
+          severity: "compatible",
+          message: `assurance evidence added ${value}`,
+        })
+      }
+      for (const value of assuranceDelta.removed) {
+        changes.push({
+          ...base,
+          section: "assurance",
+          severity: "breaking",
+          message: `assurance evidence removed ${value}`,
+        })
+      }
     }
 
+    // A new route is diffed against an empty one: the capabilities it declares and the data it returns
+    // expand risk as surely as the same change to a route that already existed.
+    const old: Partial<NifraManifestRoute> = existing ?? {}
     for (const field of ["declared", "evidenced", "unproven"] as const) {
       const delta = listChanges(old.capabilities?.[field] ?? [], route.capabilities?.[field] ?? [])
       for (const value of delta.added) {

package/src/mount.ts

@@ -7,18 +7,80 @@
  * in-process mount.
  */
 
+import type { ProjectEvidenceSnapshot } from "./evidence.ts"
 import type { Platform } from "./server/context.ts"
+import type { WebSocketUpgradeOutcome } from "./server/websocket.ts"
 
 /** Global symbol so independently bundled copies of core/client/web still agree on the mount seam. */
 export const NIFRA_BACKEND_MOUNT = Symbol.for("@nifrajs/backend-mount")
 
+/** Optional symbol-keyed upgrade seam carried by an in-process client mount. */
+export const NIFRA_BACKEND_WS_MOUNT = Symbol.for("@nifrajs/backend-ws-mount")
+
+/** Internal runtime-provider seam used when an in-process WebSocket backend is mounted in Bun. */
+export const NIFRA_BACKEND_WS_RUNTIME = Symbol.for("@nifrajs/backend-ws-runtime")
+
+/** Optional offline assurance/evidence seam for composed applications. */
+export const NIFRA_BACKEND_EVIDENCE = Symbol.for("@nifrajs/backend-evidence")
+
+/**
+ * Optional request-scoping seam carried by an in-process typed client. Called with one request's
+ * {@link Platform}, it returns a view of the same typed client whose calls dispatch with that platform,
+ * so a backend reached from an SSR loader sees the page visitor's `c.clientIp`, `c.env` and
+ * `c.waitUntil`. The view carries platform fields only - never the page request's headers.
+ */
+export const NIFRA_BACKEND_BIND_PLATFORM = Symbol.for("@nifrajs/backend-bind-platform")
+
+export { NIFRA_PLATFORM_CLIENT_IP_DERIVED } from "./server/client-ip.ts"
+
 /** Dispatch one already-materialized request into a backend with its outer runtime platform context. */
 export type BackendMountHandler<Env = unknown> = (
   request: Request,
   platform?: Platform<Env>,
 ) => Response | Promise<Response>
 
+/** Adapter-neutral WebSocket upgrade resolver for a mounted backend. */
+export type BackendWebSocketMountHandler<Env = unknown> = (
+  request: Request,
+  platform?: Platform<Env>,
+) => WebSocketUpgradeOutcome | Promise<WebSocketUpgradeOutcome>
+
+/** Opaque provider kept structural so public mount types do not expose the WS runtime internals. */
+export type BackendWebSocketRuntimeProvider = () => unknown
+
+/** Returns a view of an in-process typed client bound to one request's platform. */
+export type BackendPlatformBinder<Env = unknown> = (platform: Platform<Env>) => unknown
+
+/** Produces token-only route/evidence facts; it is never called from request dispatch. */
+export type BackendEvidenceProvider = () =>
+  | ProjectEvidenceSnapshot
+  | Promise<ProjectEvidenceSnapshot>
+
+/**
+ * The path of every pre-route `mount()` on a nifra server, as the server matches it (`"/"` for a root
+ * mount). Such a mount answers every request under its path before the app's own routes run, and
+ * `fallbackOn: 404` only moves on to the next mount, so a route the app declares there is unreachable.
+ * Reads the server's own mount table, as `reflectMounts` does; a value that is not a nifra server
+ * yields `[]`. Never called from request dispatch.
+ */
+export function preRouteMountPaths(app: unknown): readonly string[] {
+  const mounts = (app as { readonly fetchMounts?: unknown } | null | undefined)?.fetchMounts
+  if (!Array.isArray(mounts)) return []
+  const paths: string[] = []
+  for (const mount of mounts as ReadonlyArray<{
+    readonly path?: unknown
+    readonly beforeRoutes?: unknown
+  } | null>) {
+    if (mount?.beforeRoutes === true && typeof mount.path === "string") paths.push(mount.path)
+  }
+  return paths
+}
+
 /** Structural mount capability exposed by an in-process typed client. */
 export interface BackendMount<Env = unknown> {
   readonly [NIFRA_BACKEND_MOUNT]: BackendMountHandler<Env>
+  readonly [NIFRA_BACKEND_WS_MOUNT]?: BackendWebSocketMountHandler<Env>
+  readonly [NIFRA_BACKEND_WS_RUNTIME]?: BackendWebSocketRuntimeProvider
+  readonly [NIFRA_BACKEND_EVIDENCE]?: BackendEvidenceProvider
+  readonly [NIFRA_BACKEND_BIND_PLATFORM]?: BackendPlatformBinder<Env>
 }

package/src/reflection.ts

@@ -18,6 +18,7 @@ import {
   evidenceProvenance,
   validEvidence,
 } from "./internal/route-assurance.ts"
+import { NIFRA_BACKEND_EVIDENCE } from "./mount.ts"
 import type { StandardSchemaV1 } from "./schema/standard.ts"
 import type { ToolAnnotations } from "./server/server.ts"
 
@@ -39,14 +40,25 @@ export interface SchemaReflection {
   readonly jsonSchema: JsonSchema | undefined
   /** Top-level object fields, or `undefined` when the JSON Schema is absent/non-object. */
   readonly fields: readonly ReflectedSchemaField[] | undefined
+  /**
+   * The media types a body schema reads through a parser of its own (`bodyParser`), beyond the
+   * JSON and urlencoded bodies every body schema reads. Absent when it declares none.
+   */
+  readonly mediaTypes?: readonly string[]
 }
 
 export interface ReflectedRouteSchema {
+  /** Explicit external-protocol mode; the handler owns raw request parsing. */
+  readonly wire?: "raw"
+  /** Validation/authentication ordering selected for this route. */
+  readonly validationOrder?: "validate-before-auth" | "auth-before-validation"
   /** Effective transport body policy; surfaced so upload/streaming exemptions are auditable. */
   readonly bodyLimit?: number | "unlimited"
   readonly bodyLimitReason?: string
   /** Request-header schema; names are normalized to lower-case at runtime. */
   readonly headers?: SchemaReflection
+  /** Request-cookie schema, validated against the parsed `Cookie` header. */
+  readonly cookies?: SchemaReflection
   readonly body?: SchemaReflection
   readonly query?: SchemaReflection
   /** Path-params schema - constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
@@ -61,6 +73,8 @@ export interface ReflectedRoute {
   readonly method: string
   readonly path: string
   readonly schema?: ReflectedRouteSchema
+  /** Runtime response-contract mode, when a response-contract plugin covered the route. */
+  readonly responseContract?: "warn" | "enforce"
   readonly assurance?: readonly AssuranceEvidence[]
   readonly capabilities?: readonly string[]
   /** Set when the route is a declared dynamic route family (a runtime-resolved template like
@@ -146,6 +160,24 @@ const fieldsOf = (schema: JsonSchema | undefined): readonly ReflectedSchemaField
   return fields
 }
 
+// The brand a body schema carries its own reader under. Spelled here rather than imported so that
+// reflection does not pull the body lane into a bundle that only describes routes.
+const BODY_READER = Symbol.for("nifra.body.schemaReader")
+
+const mediaTypesOf = (value: unknown): readonly string[] | undefined => {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return undefined
+  try {
+    const reader = (value as Record<symbol, unknown>)[BODY_READER]
+    if (typeof reader !== "function") return undefined
+    const declared = (reader as { readonly mediaTypes?: unknown }).mediaTypes
+    if (!Array.isArray(declared)) return undefined
+    const types = declared.filter((type): type is string => typeof type === "string")
+    return types.length > 0 ? Object.freeze(types) : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Reflect a Standard Schema, Nifra/TypeBox schema carrier, or raw JSON Schema. Never throws.
  * Validation-only schemas have `standard` but no `jsonSchema`; raw JSON Schema has the reverse.
@@ -153,7 +185,13 @@ const fieldsOf = (schema: JsonSchema | undefined): readonly ReflectedSchemaField
 export function reflectSchema(value: unknown): SchemaReflection {
   const standard = standardOf(value)
   const jsonSchema = jsonSchemaOf(value, standard)
-  return { standard, jsonSchema, fields: fieldsOf(jsonSchema) }
+  const mediaTypes = mediaTypesOf(value)
+  return {
+    standard,
+    jsonSchema,
+    fields: fieldsOf(jsonSchema),
+    ...(mediaTypes !== undefined ? { mediaTypes } : {}),
+  }
 }
 
 const routeCandidates = (source: unknown): readonly unknown[] => {
@@ -179,6 +217,11 @@ const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined
     }
   }
   return {
+    ...(schema.wire === "raw" ? { wire: "raw" as const } : {}),
+    ...(schema.validationOrder === "auth-before-validation" ||
+    schema.validationOrder === "validate-before-auth"
+      ? { validationOrder: schema.validationOrder }
+      : {}),
     ...(schema.bodyLimit === "unlimited" || typeof schema.bodyLimit === "number"
       ? { bodyLimit: schema.bodyLimit }
       : {}),
@@ -186,6 +229,7 @@ const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined
       ? { bodyLimitReason: schema.bodyLimitReason }
       : {}),
     ...(schema.headers !== undefined ? { headers: reflectSchema(schema.headers) } : {}),
+    ...(schema.cookies !== undefined ? { cookies: reflectSchema(schema.cookies) } : {}),
     ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
     ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
     ...(schema.params !== undefined ? { params: reflectSchema(schema.params) } : {}),
@@ -242,6 +286,9 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
       method: route.method.toUpperCase(),
       path: route.path,
       ...(schema !== undefined ? { schema } : {}),
+      ...(route.responseContract === "warn" || route.responseContract === "enforce"
+        ? { responseContract: route.responseContract }
+        : {}),
       ...(assurance !== undefined ? { assurance } : {}),
       ...(capabilities.length > 0 ? { capabilities } : {}),
       ...(route.family === true ? { family: true } : {}),
@@ -251,3 +298,39 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
   }
   return reflected
 }
+
+/** A mounted child (`mount()`, `mountFetch()`) whose routes route reflection cannot see. */
+export interface ReflectedMount {
+  /** The mount prefix with `/*`: the child serves every path under it. */
+  readonly path: string
+  /** Why the child is not analyzed, as declared by `opaque` on the mount. */
+  readonly opaque?: string
+}
+
+/**
+ * The mounts on an app that route reflection cannot see into, sorted by path. A mount whose app
+ * publishes composed evidence (the API `createWebApp` mounts) is left out: its routes reach
+ * reflection through that evidence. Anything that is not a nifra server yields an empty list.
+ */
+export function reflectMounts(source: unknown): readonly ReflectedMount[] {
+  // `fetchMounts` is the server's own mount table, read here rather than exposed through a method so
+  // apps that never reflect pay nothing for it.
+  const mounts = recordOf(source)?.fetchMounts
+  if (!Array.isArray(mounts)) return []
+  const reflected: ReflectedMount[] = []
+  for (const candidate of mounts) {
+    const mount = recordOf(candidate)
+    if (typeof mount?.path !== "string") continue
+    const app = mount.app as { readonly [NIFRA_BACKEND_EVIDENCE]?: unknown } | undefined
+    if (typeof app?.[NIFRA_BACKEND_EVIDENCE] === "function") continue
+    // Checked here, at analysis time, so serving pays nothing: a blank reason is no reason.
+    const opaque = typeof mount.opaque === "string" ? mount.opaque.trim() || undefined : undefined
+    reflected.push(
+      Object.freeze({
+        path: mount.path === "/" ? "/*" : `${mount.path}/*`,
+        ...(opaque !== undefined ? { opaque } : {}),
+      }),
+    )
+  }
+  return reflected.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}

package/src/response-observer.ts

@@ -6,6 +6,7 @@ import {
 import type { AnyServer } from "./server/server.ts"
 
 export type {
+  NodeResponseBodyHook,
   ResponseBodyHook,
   ResponseHeadersHook,
   ResponseObserverMethods,

package/src/router/overlap.ts

@@ -0,0 +1,258 @@
+import {
+  type CompiledRoutePattern,
+  compileRoutePattern,
+  expandOptionalParams,
+  type MixedPart,
+  type ParamConstraint,
+} from "./pattern.ts"
+
+type Token =
+  | { readonly kind: "char"; readonly value: string }
+  | { readonly kind: "param"; readonly c?: ParamConstraint }
+  | { readonly kind: "wildcard" }
+
+interface State {
+  readonly index: number
+  readonly active?: "param" | "wildcard"
+  /**
+   * Inside a parameter constrained to a character class: how many characters it has taken. Once the
+   * class has no upper bound the count stops at the lower one, where it no longer changes anything.
+   */
+  readonly taken?: number
+  /** Inside a parameter constrained to a list of values: what is left of each value still possible. */
+  readonly live?: readonly string[]
+}
+
+interface ProductNode {
+  readonly left: State
+  readonly right: State
+  readonly previous?: string
+  readonly character?: string
+}
+
+/** Hard budget for the offline route-language intersection. Never use this on the request path. */
+export const ROUTE_PATTERN_OVERLAP_MAX_STATES = 100_000
+const ROUTE_PATTERN_OVERLAP_MAX_LENGTH = 16_384
+
+export class RoutePatternOverlapLimitError extends Error {
+  readonly code = "ROUTE_OVERLAP_LIMIT"
+
+  constructor() {
+    super("route overlap analysis exceeded its safety budget")
+    this.name = "RoutePatternOverlapLimitError"
+  }
+}
+
+const stateKey = (state: State): string =>
+  `${state.index}:${state.active ?? "none"}:${state.taken ?? ""}:${state.live?.join("|") ?? ""}`
+const productKey = (left: State, right: State): string => `${stateKey(left)}|${stateKey(right)}`
+
+function pushLiteral(tokens: Token[], value: string): void {
+  for (const character of value) tokens.push({ kind: "char", value: character })
+}
+
+function pushMixed(tokens: Token[], parts: readonly MixedPart[]): void {
+  for (const part of parts) {
+    if (part.t === "lit") pushLiteral(tokens, part.v)
+    else tokens.push(part.c === undefined ? { kind: "param" } : { kind: "param", c: part.c })
+  }
+}
+
+function tokensOf(pattern: CompiledRoutePattern): readonly Token[] {
+  const tokens: Token[] = [{ kind: "char", value: "/" }]
+  pattern.segments.forEach((segment, index) => {
+    if (index > 0) tokens.push({ kind: "char", value: "/" })
+    if (segment.kind === "static") pushLiteral(tokens, segment.value)
+    else if (segment.kind === "param") tokens.push({ kind: "param" })
+    else if (segment.kind === "wildcard") tokens.push({ kind: "wildcard" })
+    else pushMixed(tokens, segment.parts)
+  })
+  return tokens
+}
+
+function epsilon(state: State, tokens: readonly Token[]): State | undefined {
+  if (state.active === undefined) return undefined
+  // A constrained parameter ends only where its constraint is met: a whole value from the list, or
+  // at least the class's lower bound of characters.
+  if (state.live?.includes("") === false) return undefined
+  const token = tokens[state.index]
+  if (state.taken !== undefined && token?.kind === "param" && state.taken < token.c!.min) {
+    return undefined
+  }
+  return { index: state.index + 1 }
+}
+
+function advance(state: State, character: string, tokens: readonly Token[]): State | undefined {
+  if (state.active === "wildcard") return state
+  const token = tokens[state.index]
+  if (token === undefined) return undefined
+  if (token.kind === "char") {
+    return token.value === character ? { index: state.index + 1 } : undefined
+  }
+  if (token.kind === "wildcard") return { index: state.index, active: "wildcard" }
+  if (character === "/") return undefined
+  const constraint = token.c
+  if (constraint === undefined) {
+    return state.active === "param" ? state : { index: state.index, active: "param" }
+  }
+  if (constraint.oneOf !== undefined) {
+    const live = (state.live ?? constraint.oneOf)
+      .filter((value) => value[0] === character)
+      .map((value) => value.slice(1))
+    return live.length === 0 ? undefined : { index: state.index, active: "param", live }
+  }
+  const taken = state.taken ?? 0
+  const code = character.charCodeAt(0)
+  if (taken >= constraint.max || constraint.mask.charCodeAt(code) !== 49 /* 1 */) return undefined
+  return {
+    index: state.index,
+    active: "param",
+    taken: constraint.max === Infinity ? Math.min(taken + 1, constraint.min) : taken + 1,
+  }
+}
+
+/** The exact characters that can advance `state`, or `undefined` when it accepts a character class. */
+function exactCharacters(state: State, tokens: readonly Token[]): readonly string[] | undefined {
+  if (state.active === "wildcard") return undefined
+  const token = tokens[state.index]
+  if (token === undefined) return []
+  if (token.kind === "char") return [token.value]
+  if (token.kind === "wildcard") return undefined
+  const values = state.live ?? token.c?.oneOf
+  return values === undefined
+    ? undefined
+    : [...new Set(values.flatMap((value) => (value === "" ? [] : [value[0]!])))]
+}
+
+// "a" first, so an unconstrained parameter is still witnessed by the letter it always was.
+const CLASS_REPRESENTATIVES = ["a"]
+for (let code = 33; code < 127; code++) {
+  if (code !== 47 /* / */ && code !== 97 /* a */) {
+    CLASS_REPRESENTATIVES.push(String.fromCharCode(code))
+  }
+}
+
+/**
+ * Return the finite representative alphabet for this product state. A global alphabet makes a
+ * route containing many literal characters quadratic in the number of states. At each state only
+ * the exact characters one side asks for can affect the next state, or - when both sides take a
+ * class of characters - one character that both classes hold: where a class leads does not depend on
+ * which of its characters was taken. Slash is additionally needed only when both sides are
+ * wildcards because it can move through a segment boundary that no parameter may consume.
+ */
+function transitionCharacters(
+  left: State,
+  right: State,
+  leftTokens: readonly Token[],
+  rightTokens: readonly Token[],
+): readonly string[] {
+  const exact = exactCharacters(left, leftTokens) ?? exactCharacters(right, rightTokens)
+  if (exact !== undefined) return exact
+  const both = (character: string): boolean =>
+    advance(left, character, leftTokens) !== undefined &&
+    advance(right, character, rightTokens) !== undefined
+  const shared = CLASS_REPRESENTATIVES.find(both)
+  const characters = shared === undefined ? [] : [shared]
+  if (both("/")) characters.push("/")
+  return characters
+}
+
+function accepted(state: State, tokens: readonly Token[]): boolean {
+  return state.active === undefined && state.index === tokens.length
+}
+
+function witnessOf(nodes: ReadonlyMap<string, ProductNode>, key: string): string {
+  const characters: string[] = []
+  let current = key
+  while (true) {
+    const node = nodes.get(current)
+    if (node === undefined || node.previous === undefined) break
+    if (node.character !== undefined) characters.push(node.character)
+    current = node.previous
+  }
+  characters.reverse()
+  return characters.join("")
+}
+
+/**
+ * Return a deterministic path accepted by both patterns, or `undefined` when their path languages are
+ * disjoint. A pattern ending in optional params is every concrete path it serves, so `/users/:id?`
+ * overlaps `/users` as well as `/users/me`.
+ *
+ * This is a build/check-time NFA product, never a request-time operation. Route literals are the only
+ * input alphabet needed: a literal character is tried verbatim, while `a` is a representative for
+ * the unrestricted non-slash character class. No user route text is compiled as a regular expression.
+ *
+ * A constrained parameter is modelled as its constraint: a value from its list, or a run of its
+ * class within its bounds. In a segment that has several parameters the router is stricter than
+ * that - it places the literals first and tests the values afterwards - so for such a segment the
+ * answer errs towards reporting an overlap that no request can reach, never towards missing one.
+ * The state budget is one budget for the whole call, however many concrete paths the two sides have.
+ */
+export function routePatternOverlap(left: string, right: string): string | undefined {
+  if (
+    left.length > ROUTE_PATTERN_OVERLAP_MAX_LENGTH ||
+    right.length > ROUTE_PATTERN_OVERLAP_MAX_LENGTH
+  )
+    throw new RoutePatternOverlapLimitError()
+  const rights = expandOptionalParams(right).map((form) => tokensOf(compileRoutePattern(form)))
+  const budget = { states: ROUTE_PATTERN_OVERLAP_MAX_STATES }
+  for (const form of expandOptionalParams(left)) {
+    const leftTokens = tokensOf(compileRoutePattern(form))
+    for (const rightTokens of rights) {
+      const witness = tokenOverlap(leftTokens, rightTokens, budget)
+      if (witness !== undefined) return witness
+    }
+  }
+  return undefined
+}
+
+function tokenOverlap(
+  leftTokens: readonly Token[],
+  rightTokens: readonly Token[],
+  budget: { states: number },
+): string | undefined {
+  const startLeft: State = { index: 0 }
+  const startRight: State = { index: 0 }
+  const start = productKey(startLeft, startRight)
+  if (budget.states-- <= 0) throw new RoutePatternOverlapLimitError()
+  const nodes = new Map<string, ProductNode>([[start, { left: startLeft, right: startRight }]])
+  const queue: string[] = [start]
+  let head = 0
+
+  const enqueue = (next: string, node: ProductNode): void => {
+    if (nodes.has(next)) return
+    if (budget.states-- <= 0) throw new RoutePatternOverlapLimitError()
+    nodes.set(next, node)
+    queue.push(next)
+  }
+
+  while (head < queue.length) {
+    const key = queue[head++]!
+    const node = nodes.get(key)!
+    if (accepted(node.left, leftTokens) && accepted(node.right, rightTokens)) {
+      return witnessOf(nodes, key)
+    }
+
+    const transitions: Array<{ readonly left: State; readonly right: State }> = []
+    const leftEpsilon = epsilon(node.left, leftTokens)
+    const rightEpsilon = epsilon(node.right, rightTokens)
+    if (leftEpsilon !== undefined) transitions.push({ left: leftEpsilon, right: node.right })
+    if (rightEpsilon !== undefined) transitions.push({ left: node.left, right: rightEpsilon })
+
+    for (const transition of transitions) {
+      const next = productKey(transition.left, transition.right)
+      enqueue(next, { ...transition, previous: key })
+    }
+
+    for (const character of transitionCharacters(node.left, node.right, leftTokens, rightTokens)) {
+      const nextLeft = advance(node.left, character, leftTokens)
+      const nextRight = advance(node.right, character, rightTokens)
+      if (nextLeft === undefined || nextRight === undefined) continue
+      const next = productKey(nextLeft, nextRight)
+      enqueue(next, { left: nextLeft, right: nextRight, previous: key, character })
+    }
+  }
+
+  return undefined
+}