@nifrajs/core 2.1.0 → 2.3.0

package/src/index.ts

@@ -1,16 +1,16 @@
 /**
- * `@nifrajs/core` — Nifra's lean HTTP server API.
+ * `@nifrajs/core` - Nifra's lean HTTP server API.
  *
  * Nifra 2.0 keeps the package root intentionally lean. Optional systems live at documented
  * subpaths so importing the root cannot activate unrelated runtimes.
  */
 
 /**
- * Current package version. A hardcoded literal on purpose — core runs on the edge (no fs), so it can't
+ * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.1.0" as const
+export const VERSION = "2.3.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/brand.ts

@@ -3,7 +3,7 @@
  *
  * Every developer-facing string (error prefixes, the default OpenAPI title, the
  * logger tag) pulls from here, so renaming the brand is a one-line change. The
- * npm scope (`@nifrajs/*`) is the other naming axis — `scripts/rename.ts` flips
+ * npm scope (`@nifrajs/*`) is the other naming axis - `scripts/rename.ts` flips
  * both at once.
  */
 export const FRAMEWORK_NAME = "Nifra" as const

package/src/internal/route-catalog.ts

@@ -0,0 +1,94 @@
+/**
+ * The app's route table: one canonical fact per registered route, and the router built over them.
+ *
+ * ## Why this is not in the server kernel
+ *
+ * Nothing here knows what a `Server` is. It owns matching, reflection, assurance and native-compilation
+ * input, and the kernel holds one instance - which is the whole relationship. The reason it lived in
+ * `server.ts` is that `RouteEntry` used to be declared there, and until that vocabulary moved to
+ * `internal/` this could not be split out without exporting the engine's internals as public types.
+ *
+ * ## Why this costs the request path nothing
+ *
+ * Per-request code calls `this.catalog.find(...)`: a property load and a method call on an instance.
+ * Which module DECLARED the class does not enter into that. The only cross-module operation is the
+ * `new RouteCatalog()` in the server's constructor, once per server; every other method here runs at
+ * registration.
+ */
+import type { CompiledRoutePattern } from "../router/pattern.ts"
+import { type Method, Router, type RouterMatch } from "../router/router.ts"
+import type { RouteDescriptor } from "../server/server-types.ts"
+import type { AssuranceDeclaration } from "./route-assurance.ts"
+import type { RouteEntry } from "./route-execution.ts"
+
+/** One canonical runtime route fact. The catalog owns matching, reflection, assurance, tool metadata,
+ * replay, and native compilation input so batch registration has one commit point. */
+export interface CatalogRoute {
+  readonly method: Method
+  readonly path: string
+  readonly pattern: CompiledRoutePattern
+  readonly entry: RouteEntry
+  readonly descriptor: RouteDescriptor
+  readonly assurance: readonly AssuranceDeclaration[]
+}
+
+/**
+ * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
+ * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
+ * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
+ * reflection unchanged.
+ *
+ * Coverage note: this file reports 90% functions with every method exercised. `bun test --coverage`
+ * (1.3.14) counts one synthetic function per class that it never marks hit - a one-method class with a
+ * passing test for that method reports 50%. So 90 is this file's ceiling, not a missing test; do not go
+ * looking for the tenth function.
+ */
+export class RouteCatalog {
+  private matcher = new Router<RouteEntry>()
+  private records: CatalogRoute[] = []
+  /** Allocation-free reflection view for the common no-assurance case. Derived only at commit time. */
+  private descriptors: RouteDescriptor[] = []
+  private assurancePresent = false
+
+  add(route: CatalogRoute): void {
+    this.matcher.add(route.method, route.pattern, route.entry)
+    this.records.push(route)
+    this.descriptors.push(route.descriptor)
+    if (route.assurance.length > 0) this.assurancePresent = true
+  }
+
+  addBatch(routes: readonly CatalogRoute[]): void {
+    if (routes.length === 0) return
+    const nextRecords = this.records.concat(routes)
+    const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor))
+    const nextAssurancePresent =
+      this.assurancePresent || routes.some((route) => route.assurance.length > 0)
+    const staged = new Router<RouteEntry>()
+    for (const route of this.records) staged.add(route.method, route.pattern, route.entry)
+    for (const route of routes) staged.add(route.method, route.pattern, route.entry)
+    this.matcher = staged
+    this.records = nextRecords
+    this.descriptors = nextDescriptors
+    this.assurancePresent = nextAssurancePresent
+  }
+
+  find(method: string, path: string): RouterMatch<RouteEntry> {
+    return this.matcher.find(method, path)
+  }
+
+  entries(): readonly CatalogRoute[] {
+    return this.records
+  }
+
+  routeDescriptors(): ReadonlyArray<RouteDescriptor> {
+    return this.descriptors
+  }
+
+  lastDescriptor(): RouteDescriptor | undefined {
+    return this.records[this.records.length - 1]?.descriptor
+  }
+
+  hasAssurance(): boolean {
+    return this.assurancePresent
+  }
+}

package/src/internal/route-execution.ts

@@ -0,0 +1,106 @@
+/**
+ * What a compiled route IS, and the registration-time decision that produces it.
+ *
+ * ## Why this is not in the server kernel
+ *
+ * `compileExecutionPlan` is BOOT work: it runs from `register`/`registerBatch`, both gated by
+ * `assertConfigurable`, so nothing here is reachable once the server is serving. Moving it costs the
+ * request path nothing - per-request code still calls the same frozen `run` closure it always did.
+ *
+ * ## Why `internal/`
+ *
+ * These types are the engine's vocabulary, not the package's API. They lived in `server.ts`, which IS
+ * published as `./server`, so every attempt to split the kernel had the same choice: export the engine's
+ * internals as public types, or not split. `internal/` is not a published subpath, so this moves the
+ * vocabulary somewhere it can be shared without becoming API. That is the step that unblocks the rest.
+ *
+ * The `Server` import is type-only and erased, so there is no runtime cycle back into the kernel.
+ */
+import type { RequestBudget } from "../budget.ts"
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { Platform, RouteSchema } from "../server/context.ts"
+import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
+import type { ResolvedEffectLedger } from "../server/ledger-lane.ts"
+import type { Registry } from "../server/registry.ts"
+import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import type { HandlerResult } from "../server/runtime-core.ts"
+import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
+
+export type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
+
+/** A `derive` computes per-request context extensions; stored path-erased. */
+export type RawDerive = (ctx: RawContext) => MaybePromise<object>
+export type RawBeforeHandle = (ctx: RawContext) => MaybePromise<unknown>
+export type RawAfterHandle = (result: unknown, ctx: RawContext) => MaybePromise<unknown>
+export type RawErrorHandler = (error: unknown, ctx: RawContext) => MaybePromise<unknown>
+export type RawAround = <T>(ctx: RawContext, next: () => MaybePromise<T>) => MaybePromise<T>
+
+export type RouteExecutionRunner = <T, R extends Registry, Ctx>(
+  runtime: Server<R, Ctx>,
+  entry: RouteEntry,
+  source: RequestSource,
+  params: Record<string, string>,
+  search: string | undefined,
+  signal: AbortSignal,
+  budget: RequestBudget,
+  platform: Platform | undefined,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response) => T,
+) => MaybePromise<T>
+
+export type ContextRouteRunner = <T, R extends Registry, Ctx>(
+  runtime: Server<R, Ctx>,
+  entry: RouteEntry,
+  source: RequestSource,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet) => T,
+  wrapResponse: (response: Response) => T,
+) => MaybePromise<T>
+
+/** Registration-compiled route behavior. Every adapter invokes the same runner; the optional fused
+ * renderer is only a response-format specialization of that same selected route semantics. */
+export interface RouteExecutionPlan {
+  readonly run: RouteExecutionRunner
+  readonly fusedWeb: FusedWebRunner | undefined
+}
+
+export interface RouteEntry {
+  readonly handler: InternalHandler
+  readonly schema: RouteSchema | undefined
+  /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
+  readonly idempotent: ResolvedIdempotency | undefined
+  /** Resolved effect-ledger wiring; `undefined` = off (no per-request ledger, no settle step). */
+  readonly ledgered: ResolvedEffectLedger | undefined
+  /** The installed response-contract runtime paired with this route's declared schema, resolved once
+   * at registration; `undefined` = not checked (the default, and the only state in which the route can
+   * still take the fused/native lanes). */
+  readonly responseContract:
+    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | undefined
+  /** Per-request context extensions captured at registration (order-scoped). */
+  readonly derives: ReadonlyArray<RawDerive>
+  /** Static context extensions captured at registration. */
+  readonly decorations: Record<PropertyKey, unknown>
+  /** Whether {@link decorations} has any keys - precomputed so the hot path skips a no-op
+   * `Object.assign` on the (common) no-decoration route. */
+  readonly hasDecorations: boolean
+  /** Lifecycle hooks captured at registration (order-scoped). */
+  readonly beforeHandle: ReadonlyArray<RawBeforeHandle>
+  readonly afterHandle: ReadonlyArray<RawAfterHandle>
+  readonly onError: ReadonlyArray<RawErrorHandler>
+  /** Wraps the matched route lifecycle. Empty for the common no-around path. */
+  readonly around: ReadonlyArray<RawAround>
+  /** The single immutable execution decision consumed by portable, Node-direct, and Bun-native paths. */
+  readonly execution: RouteExecutionPlan
+}
+
+/** The fused Web lane: same inputs `routeAndRun` would hand the generic path, a `Response` out. */
+export type FusedWebRunner = (
+  source: RequestSource,
+  params: Record<string, string>,
+  search: string | undefined,
+  signal: AbortSignal,
+  budget: RequestBudget,
+  platform: Platform | undefined,
+  nativeContext: boolean,
+) => MaybePromise<Response>

package/src/internal/same-origin.ts

@@ -0,0 +1,43 @@
+/**
+ * The same-origin test every browser-facing endpoint in Nifra uses.
+ *
+ * One owner, because there are two of these seams - the WebSocket handshake's CSWSH default and the
+ * server-function mount - and they answered differently for the same request. A browser that could
+ * open a socket was told its POST was cross-origin.
+ */
+
+/**
+ * True when `origin` is the request's own origin, as observed from inside a possibly-proxied server.
+ *
+ * The host must match exactly. The scheme must be equal or STRONGER on the Origin side, never weaker:
+ *
+ *   - `https://app` page → `http://app` request URL: accepted. This is what every TLS-terminating
+ *     proxy looks like from the origin server - Cloudflare, a tunnel, an ingress. The socket is plain
+ *     HTTP, so `request.url` says `http:` while the browser correctly reports an `https:` page.
+ *   - `http://app` page → `https://app` request URL: rejected. Nifra terminated TLS itself here, so a
+ *     plaintext page on the same host is the downgrade an attacker would need and buys nothing real.
+ *
+ * Comparing full origins instead is not the stricter option, it is an outage: measured, it rejects
+ * every server-function POST behind a terminating proxy, while the cross-origin attacker it aims at
+ * was already rejected by the host comparison. Nifra deliberately does not read `X-Forwarded-Proto` -
+ * a forwarded header is attacker-controlled unless something upstream is proven to overwrite it - so
+ * the scheme in `request.url` is the socket's, not the browser's, and this asymmetry is how the two
+ * are reconciled without trusting a header.
+ *
+ * An unparseable Origin is not same-origin.
+ */
+export function isSameOriginRequest(origin: string, request: Request): boolean {
+  try {
+    const from = new URL(origin)
+    const own = new URL(request.url)
+    if (from.host !== own.host) return false
+    // Written out rather than ranked through a lookup table: a table is a shipped object, and there
+    // are exactly two schemes to order. Any other scheme on either side falls through to `false`,
+    // which is what refuses `Origin: null`, `file:` and webview schemes.
+    if (from.protocol === "https:") return own.protocol === "https:" || own.protocol === "http:"
+    if (from.protocol === "http:") return own.protocol === "http:"
+    return false
+  } catch {
+    return false
+  }
+}

package/src/internal/secret.ts

@@ -7,7 +7,7 @@ const MIN_SECRET_BYTES = 32
 const SECRET_ENCODER = new TextEncoder()
 
 /**
- * Boot-time guard: reject an HMAC secret under 256 bits, loudly, at construction — never at the
+ * Boot-time guard: reject an HMAC secret under 256 bits, loudly, at construction - never at the
  * first request. UTF-8 byte length (not char count), so a multibyte secret is measured honestly.
  * The single source of truth for the framework's secret-strength floor; every HMAC entry point
  * (signed cookies, `@nifrajs/auth` sessions, webhook verification, signed upload/image URLs) routes

package/src/ledger.ts

@@ -4,7 +4,7 @@
  * Every owned effect seam (a repository write, an external call, an email send) records one entry via
  * the `useCapability` beacon. The entry type is deliberately **token-only**: capability ids, phase,
  * an adapter/resource token, dimensionless cost counters, an optional keyed digest, and an error code.
- * There is no free-form payload field — request bodies, rows, and values cannot enter the ledger, so
+ * There is no free-form payload field - request bodies, rows, and values cannot enter the ledger, so
  * redaction holds by construction rather than by filtering. The sealed ledger carries the **route
  * pattern** (`/users/:id`), never the concrete URL, so path parameters cannot leak either.
  *
@@ -29,7 +29,7 @@ export type EffectCost = Readonly<Record<string, number>>
 
 /** Token-only caller metadata shared by an effect intent and outcome. */
 export interface EffectMetadata {
-  /** Adapter/resource token (`repo:orders`, `provider:payments`). A token — never a value or a row. */
+  /** Adapter/resource token (`repo:orders`, `provider:payments`). A token - never a value or a row. */
   readonly target?: string
   /** Dimensionless counters; see {@link EffectCost}. At most {@link MAX_COST_AXES} axes. */
   readonly cost?: EffectCost
@@ -45,7 +45,7 @@ export interface EffectEntryInput extends EffectMetadata {
   readonly capability: string
   /** Default `"intent"`. Record `committed`/`failed`/`compensated` only after the outcome is known. */
   readonly phase?: EffectPhase
-  /** Outcome error as a bounded token code — never a message, never a stack. */
+  /** Outcome error as a bounded token code - never a message, never a stack. */
   readonly error?: { readonly code: string }
 }
 
@@ -75,10 +75,10 @@ export interface EffectChain {
 /** The immutable result of sealing a request's ledger. Token-only; safe to hand to any sink. */
 export interface SealedEffectLedger {
   readonly method: string
-  /** The registered route pattern (`/users/:id`) — never the concrete request URL. */
+  /** The registered route pattern (`/users/:id`) - never the concrete request URL. */
   readonly path: string
   readonly entries: readonly EffectEntry[]
-  /** The route's declared capability tokens — the runtime-enforcement view: recorded ⊆ declared is
+  /** The route's declared capability tokens - the runtime-enforcement view: recorded ⊆ declared is
    * guaranteed by the beacon, and `declared` minus the recorded ids is the unused declaration set. */
   readonly declared: readonly string[]
   /** Present when the ledger was created with `chain: true`. */
@@ -99,7 +99,7 @@ export class EffectLedgerOverflowError extends Error {
   }
 }
 
-/** Thrown by `append` after `seal()` — e.g. an effect attempted while streaming a response body. */
+/** Thrown by `append` after `seal()` - e.g. an effect attempted while streaming a response body. */
 export class EffectLedgerSealedError extends Error {
   constructor() {
     super("effect ledger is sealed: effects cannot be recorded after the response settles")
@@ -115,14 +115,14 @@ export interface RequestLedger {
   entries(): readonly EffectEntry[]
   readonly size: number
   readonly sealed: boolean
-  /** Finalize the ledger (computing the chain when enabled). Idempotent — always the same result. */
+  /** Finalize the ledger (computing the chain when enabled). Idempotent - always the same result. */
   seal(): Promise<SealedEffectLedger>
 }
 
 export interface CreateRequestLedgerOptions {
   /** HTTP method of the matched route. */
   readonly method: string
-  /** The registered route pattern — callers must never pass the concrete request URL. */
+  /** The registered route pattern - callers must never pass the concrete request URL. */
   readonly path: string
   /** The route's declared capability tokens, surfaced verbatim on the sealed ledger. Default `[]`. */
   readonly declared?: readonly string[]
@@ -255,7 +255,7 @@ class BoundedRequestLedger implements RequestLedger {
     if (input.error !== undefined && !ERROR_CODE.test(input.error.code)) {
       throw new TypeError("effect ledger: error code must be a bounded lowercase token")
     }
-    // Only the known token fields are copied — a stray `payload`-like property never survives append.
+    // Only the known token fields are copied - a stray `payload`-like property never survives append.
     const at = this.clock()
     if (!Number.isFinite(at) || at < 0) {
       throw new TypeError("effect ledger: clock must return a finite non-negative number")
@@ -315,7 +315,7 @@ export function createRequestLedger(options: CreateRequestLedgerOptions): Reques
   return new BoundedRequestLedger(options)
 }
 
-/** Canonical, key-ordered serialization of one entry — the hash-chain input. */
+/** Canonical, key-ordered serialization of one entry - the hash-chain input. */
 function canonicalEntry(entry: EffectEntry): string {
   const cost =
     entry.cost === undefined
@@ -382,7 +382,7 @@ export function createMemoryLedgerSink(options: MemoryLedgerSinkOptions = {}): M
 /** Minimum digest key material. A short key would make the keyed digest brute-forceable. */
 export const MIN_DIGEST_KEY_BYTES = 16
 
-/** Fresh random digest key (32 bytes). Per-process by default — persist one externally to correlate across restarts. */
+/** Fresh random digest key (32 bytes). Per-process by default - persist one externally to correlate across restarts. */
 export function randomEffectDigestKey(): Uint8Array {
   const bytes = new Uint8Array(32)
   crypto.getRandomValues(bytes)

package/src/reflection.ts

@@ -40,7 +40,7 @@ export interface SchemaReflection {
 export interface ReflectedRouteSchema {
   readonly body?: SchemaReflection
   readonly query?: SchemaReflection
-  /** Path-params schema — constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
+  /** Path-params schema - constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
   readonly params?: SchemaReflection
   readonly response?: SchemaReflection
   readonly errors?: Readonly<Record<string, SchemaReflection>>

package/src/router/pattern.ts

@@ -8,6 +8,13 @@ export type RoutePatternSegment =
   | { readonly kind: "static"; readonly value: string }
   | { readonly kind: "param"; readonly name: string }
   | { readonly kind: "wildcard"; readonly name: string }
+  /** A segment that is part literal, part parameter: `:key.txt`, `feed.:format`, `v:major.:minor`. */
+  | { readonly kind: "mixed"; readonly parts: readonly MixedPart[] }
+
+/** One piece of a {@link RoutePatternSegment} of kind `mixed`, in left-to-right order. */
+export type MixedPart =
+  | { readonly t: "lit"; readonly v: string }
+  | { readonly t: "param"; readonly name: string }
 
 /**
  * Compiled route grammar shared by runtime routers, browser navigation, mocks, and adapters.
@@ -45,7 +52,9 @@ function regexOf(compiled: CompiledRoutePattern): RegExp {
         ? escapeRegex(segment.value)
         : segment.kind === "param"
           ? "([^/]+)"
-          : "(.+)",
+          : segment.kind === "mixed"
+            ? mixedSegmentSource(segment.parts)
+            : "(.+)",
     )
     regex = new RegExp(parts.length === 0 ? "^/$" : `^/${parts.join("/")}$`)
     REGEX_CACHE.set(compiled, regex)
@@ -57,10 +66,93 @@ function validParamName(name: string): boolean {
   return PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name)
 }
 
+/**
+ * Explain WHY a parameter name was rejected, in the terms the author was thinking in.
+ *
+ * The grammar is per-segment: a segment is wholly static or wholly a parameter, so everything after
+ * the colon is the name. `/v/:id.json` therefore asks for a parameter literally named `id.json`,
+ * which is not what anyone means by it - but the bare "invalid parameter" that produces reads as a
+ * typo rather than as a rule, leaving the author to guess whether the dot, the length, or the casing
+ * was the problem. Naming the actual limitation and showing the two ways out is the difference
+ * between a five-second fix and a trip to the source.
+ */
+function paramNameHint(name: string): string {
+  if (RESERVED_PARAM_NAMES.has(name)) return ` - "${name}" is reserved (prototype key)`
+  if (name.length === 0) return ` - ":" needs a name after it`
+  // No "a segment is wholly static or wholly a parameter" case here any more: mixed segments made
+  // that message obsolete. `:id.json` was the shape it explained, and `:id.json` now compiles.
+  return ` - a name must match ${PARAM_NAME.source}`
+}
+
 function escapeRegex(value: string): string {
   return value.replace(/[.*+?^()|[\]\\{}$]/g, "\\$&")
 }
 
+/**
+ * Split a segment containing `:` into literal and parameter parts.
+ *
+ * The param name is the LONGEST run matching {@link PARAM_NAME}'s body after each `:`; everything
+ * else in the segment is literal. So `:key.txt` is `[param key][lit ".txt"]`. Choosing a greedy scan
+ * on the existing sigil rather than a new `{key}.txt` syntax is a safety argument, not a taste one:
+ * every segment this newly accepts currently THROWS `INVALID_PARAM_NAME`, so no pattern that compiles
+ * today can change meaning.
+ *
+ * Returns `undefined` when the segment holds no parameter at all, so a literal colon
+ * (`/v1/things:batchGet` - legal in a URL path) stays a plain static segment.
+ */
+function splitMixed(value: string): MixedPart[] | undefined {
+  const parts: MixedPart[] = []
+  let literal = ""
+  let sawParam = false
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] !== ":") {
+      literal += value[i]
+      continue
+    }
+    const rest = value.slice(i + 1)
+    const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest)?.[0]
+    // A `:` not followed by a valid name start is literal text, not a malformed parameter.
+    if (name === undefined) {
+      literal += ":"
+      continue
+    }
+    const paramEnd = i + 1 + name.length
+    const previous = i > 0 ? value[i - 1] : undefined
+    const precededByBoundary = previous === undefined || !/[A-Za-z0-9_]/.test(previous)
+    // Preserve established RPC-style literals such as `things:batchGet`. A colon embedded after an
+    // identifier and running to the end is literal; mixed params remain unambiguous at segment start,
+    // after punctuation (`post-:id`), or when followed by a literal suffix (`v:major.json`).
+    if (!precededByBoundary && paramEnd === value.length) {
+      literal += `:${name}`
+      i += name.length
+      continue
+    }
+    if (literal !== "") {
+      parts.push({ t: "lit", v: literal })
+      literal = ""
+    }
+    parts.push({ t: "param", name })
+    sawParam = true
+    i += name.length
+  }
+  if (!sawParam) return undefined
+  if (literal !== "") parts.push({ t: "lit", v: literal })
+  return parts
+}
+
+/** The regex source matching one segment's worth of a mixed pattern, with a capture per parameter. */
+export function mixedSegmentSource(parts: readonly MixedPart[]): string {
+  let source = ""
+  for (const part of parts) {
+    // LAZY (`+?`), not greedy. A greedy capture swallows the trailing literal, so `/:key.txt` against
+    // `/abc.txt` would capture `abc.txt` and then fail to match `\.txt`. With `^…$` anchoring, the
+    // lazy form still yields `abc.txt` for `/abc.txt.txt` - the anchor forces the LAST `.txt` to be
+    // the literal. `+?` and not `*?`: an empty capture must not match (see the empty-segment rule).
+    source += part.t === "lit" ? escapeRegex(part.v) : "([^/]+?)"
+  }
+  return source
+}
+
 /** Parse and validate Nifra's strict route grammar once. Trailing slashes remain significant. */
 export function compileRoutePattern(pattern: string): CompiledRoutePattern {
   if (pattern.length === 0 || pattern.charCodeAt(0) !== 47 /* / */) {
@@ -71,14 +163,20 @@ export function compileRoutePattern(pattern: string): CompiledRoutePattern {
   const paramNames: string[] = []
   for (let i = 0; i < raw.length; i++) {
     const value = raw[i]!
-    if (value.charCodeAt(0) === 58 /* : */) {
-      const name = value.slice(1)
-      if (!validParamName(name)) {
+    // A leading `:` whose name run spans the WHOLE segment is a plain parameter - the untouched fast
+    // path. When it does not (`:key.txt`), the segment is mixed and is handled below; but a leading
+    // `:` that yields no usable name at all (`:9lives`, `:`) was clearly meant as a parameter, so it
+    // still fails here rather than being silently reinterpreted as literal text.
+    if (value.charCodeAt(0) === 58 /* : */ && !validParamName(value.slice(1))) {
+      if (splitMixed(value) === undefined) {
+        const name = value.slice(1)
         throw new RouteConfigError(
           "INVALID_PARAM_NAME",
-          `invalid parameter ":${name}" in "${pattern}"`,
+          `invalid parameter ":${name}" in "${pattern}"${paramNameHint(name)}`,
         )
       }
+    } else if (value.charCodeAt(0) === 58 /* : */) {
+      const name = value.slice(1)
       if (paramNames.includes(name)) {
         throw new RouteConfigError(
           "DUPLICATE_PARAM",
@@ -113,6 +211,32 @@ export function compileRoutePattern(pattern: string): CompiledRoutePattern {
       segments.push(Object.freeze({ kind: "wildcard", name }))
       continue
     }
+    // A segment holding a `:` anywhere other than the front is part literal, part parameter. Checked
+    // last so the wholly-static and wholly-param fast paths above are untouched.
+    const mixed = value.includes(":") ? splitMixed(value) : undefined
+    if (mixed !== undefined) {
+      for (const part of mixed) {
+        if (part.t !== "param") continue
+        if (!validParamName(part.name)) {
+          throw new RouteConfigError(
+            "INVALID_PARAM_NAME",
+            `invalid parameter ":${part.name}" in "${pattern}"${paramNameHint(part.name)}`,
+          )
+        }
+        // Duplicates must be rejected WITHIN a segment (`/:a.:a`) as well as across segments,
+        // or two captures would race for one params key.
+        if (paramNames.includes(part.name)) {
+          throw new RouteConfigError(
+            "DUPLICATE_PARAM",
+            `duplicate parameter ":${part.name}" in "${pattern}"`,
+          )
+        }
+        // Pushed left-to-right so `paramNames` stays aligned with regex capture order.
+        paramNames.push(part.name)
+      }
+      segments.push(Object.freeze({ kind: "mixed", parts: Object.freeze(mixed) }))
+      continue
+    }
     segments.push(Object.freeze({ kind: "static", value }))
   }
   const compiled = Object.freeze({
@@ -124,7 +248,50 @@ export function compileRoutePattern(pattern: string): CompiledRoutePattern {
   return compiled
 }
 
-/** Core precedence: static > param > wildcard at the first differing segment, independent of order. */
+/** Weight for {@link compareRoutePatternSpecificity}. A mixed segment constrains more than a bare
+ * param (it pins literal text) and less than a fully static one, so it sits between them. */
+const SPECIFICITY: Readonly<Record<RoutePatternSegment["kind"], number>> = {
+  static: 4,
+  mixed: 3,
+  param: 2,
+  wildcard: 1,
+}
+
+/**
+ * Total ordering for mixed segment shapes, shared by the trie and regex-based routers.
+ *
+ * Code-unit comparison, never `localeCompare`: this exists so the server and the browser agree on which
+ * of two equally-weighted patterns wins, and `localeCompare` answers by the RUNTIME's locale - a server
+ * and a visitor in different locales would order the same pair differently, which is the divergence
+ * being prevented.
+ */
+export function compareMixedPartsSpecificity(
+  left: readonly MixedPart[],
+  right: readonly MixedPart[],
+): number {
+  const literalWeight = (parts: readonly MixedPart[]): number =>
+    parts.reduce((sum, part) => (part.t === "lit" ? sum + part.v.length : sum), 0)
+  const order = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0)
+
+  const weightDifference = literalWeight(right) - literalWeight(left)
+  if (weightDifference !== 0) return weightDifference
+
+  const length = Math.max(left.length, right.length)
+  for (let i = 0; i < length; i++) {
+    const a = left[i]
+    const b = right[i]
+    if (a === undefined || b === undefined) return b === undefined ? -1 : 1
+    if (a.t !== b.t) return a.t === "lit" ? -1 : 1
+    if (a.t === "lit" && b.t === "lit" && a.v !== b.v) {
+      return a.v.length === b.v.length ? order(a.v, b.v) : b.v.length - a.v.length
+    }
+  }
+
+  return order(mixedSegmentSource(left), mixedSegmentSource(right))
+}
+
+/** Core precedence: static > mixed > param > wildcard at the first differing segment, independent of
+ * registration order. */
 export function compareRoutePatternSpecificity(
   left: CompiledRoutePattern,
   right: CompiledRoutePattern,
@@ -134,9 +301,13 @@ export function compareRoutePatternSpecificity(
     const a = left.segments[i]
     const b = right.segments[i]
     if (a === undefined || b === undefined) return b === undefined ? -1 : 1
-    const aWeight = a.kind === "static" ? 3 : a.kind === "param" ? 2 : 1
-    const bWeight = b.kind === "static" ? 3 : b.kind === "param" ? 2 : 1
+    const aWeight = SPECIFICITY[a.kind]
+    const bWeight = SPECIFICITY[b.kind]
     if (aWeight !== bWeight) return bWeight - aWeight
+    if (a.kind === "mixed" && b.kind === "mixed") {
+      const mixed = compareMixedPartsSpecificity(a.parts, b.parts)
+      if (mixed !== 0) return mixed
+    }
   }
   return 0
 }