@nextrush/router 4.0.0-beta.0 → 4.0.0-beta.1

package/src/__tests__/walk-pool-sizing.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @nextrush/router - walk pool sizing tracks maxDepth (`reduce-router-match-allocations`)
+ *
+ * `Router.addRoute` rebuilds `state.walkPool` whenever a newly registered
+ * route's depth exceeds the current pool's size, so the pool is never too
+ * small for the deepest route actually registered — never guessed, never
+ * left stale after a deeper route is added later.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {};
+
+describe('walk pool sizing follows registered route depth', () => {
+  it('has no pool for a router with only static routes', () => {
+    const router = createRouter();
+    router.get('/a', noop);
+    router.get('/b', noop);
+    // No param/wildcard route registered — matches still work via the static
+    // fast path, and there is nothing for a pool to help with.
+    expect(router.match('GET', '/a')?.handler).toBe(noop);
+  });
+
+  it('matches correctly immediately after the first param route is registered', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const match = router.match('GET', '/users/42');
+    expect(match?.params).toEqual({ id: '42' });
+  });
+
+  it('matches correctly after a deeper route is registered later, growing the pool', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    // First match at the shallower depth, pool sized to depth 2.
+    expect(router.match('GET', '/users/1')?.params).toEqual({ id: '1' });
+
+    // Register a much deeper route — the pool must grow to cover it.
+    router.get('/orgs/:o/teams/:t/members/:m/roles/:r', noop);
+    const deep = router.match('GET', '/orgs/1/teams/2/members/3/roles/4');
+    expect(deep?.params).toEqual({ o: '1', t: '2', m: '3', r: '4' });
+
+    // The original shallow route still matches correctly after the pool grew.
+    expect(router.match('GET', '/users/2')?.params).toEqual({ id: '2' });
+  });
+
+  it('a router built with all routes registered up front matches every depth correctly', () => {
+    const router = createRouter();
+    router.get('/a/:x', noop);
+    router.get('/a/:x/b/:y', noop);
+    router.get('/a/:x/b/:y/c/:z', noop);
+
+    expect(router.match('GET', '/a/1')?.params).toEqual({ x: '1' });
+    expect(router.match('GET', '/a/1/b/2')?.params).toEqual({ x: '1', y: '2' });
+    expect(router.match('GET', '/a/1/b/2/c/3')?.params).toEqual({ x: '1', y: '2', z: '3' });
+  });
+
+  it('reset() clears pooled state so a shallower re-registration still matches correctly', () => {
+    const router = createRouter();
+    router.get('/orgs/:o/teams/:t/members/:m', noop);
+    expect(router.match('GET', '/orgs/1/teams/2/members/3')?.params).toEqual({
+      o: '1',
+      t: '2',
+      m: '3',
+    });
+
+    router.reset();
+    router.get('/x/:id', noop);
+    expect(router.match('GET', '/x/9')?.params).toEqual({ id: '9' });
+  });
+});

package/src/__tests__/walk-pool-undersized-guard.test.ts

@@ -0,0 +1,59 @@
+/**
+ * @nextrush/router - walk-pool fail-closed guard when undersized
+ * (`reduce-router-match-allocations`)
+ *
+ * `matchNodeIndexedPooled` defensively fails closed (treats the walk as a
+ * miss, never writes past the array) if a caller ever supplies a `WalkPool`
+ * smaller than the path actually being walked needs. `createWalkPool` sizes
+ * correctly today (`maxDepth + 1`), so this should be unreachable through the
+ * public API — this file proves the guard itself is correct if that
+ * invariant is ever violated by a future change, rather than leaving an
+ * untested "should be unreachable" comment as the only evidence.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { matchNodeIndexed } from '../matching';
+import { createWalkPool } from '../walk-pool';
+import { createNode, NodeType, type HandlerEntry } from '../segment-trie';
+import { compileExecutor } from '../segment-trie';
+
+const noop = async (): Promise<void> => {};
+
+describe('walk pool — fails closed when undersized (defense-in-depth)', () => {
+  it('a static-descent pool undersized by one frame misses cleanly instead of writing past the array', () => {
+    const root = createNode('');
+    const a = createNode('a');
+    root.children.set('a', a);
+    const executor = compileExecutor(noop, []);
+    const entry: HandlerEntry = { handler: noop, middleware: [], executor };
+    a.handlers.set('GET', entry);
+
+    // Correctly sized for depth 0 only (createWalkPool(0) -> 1 frame) — one
+    // fewer frame than the descent into 'a' (depth 1) actually needs.
+    const undersizedPool = createWalkPool(0);
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+
+    const result = matchNodeIndexed(root, '/a', 1, bindNames, bindValues, 'GET', true, undefined, undersizedPool);
+    expect(result).toBeNull();
+  });
+
+  it('a param-descent pool undersized by one frame misses cleanly and leaves no dangling bind', () => {
+    const root = createNode('');
+    const idNode = createNode(':id', NodeType.PARAM);
+    idNode.paramName = 'id';
+    root.paramChild = idNode;
+    const executor = compileExecutor(noop, []);
+    idNode.handlers.set('GET', { handler: noop, middleware: [], executor });
+
+    const undersizedPool = createWalkPool(0);
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+
+    const result = matchNodeIndexed(root, '/42', 1, bindNames, bindValues, 'GET', true, undefined, undersizedPool);
+    expect(result).toBeNull();
+    // The guard pops its own speculative bind before failing closed — no leak.
+    expect(bindNames).toEqual([]);
+    expect(bindValues).toEqual([]);
+  });
+});

package/src/canonicalize.ts

@@ -0,0 +1,137 @@
+/**
+ * @nextrush/router - Canonical Request Path
+ *
+ * The single normalization owner (RFC-029): every consumer that needs to know
+ * "what path does the router treat this request as" — the router's own match,
+ * a mounted-router prefix test, a CSRF exclude-path match, an adapter's
+ * published `ctx.path` — calls {@link canonicalizePath} instead of hand-rolling
+ * its own fold/collapse/strip, so there is exactly one definition of "the same
+ * path" across the framework (SEC-02, SEC-09, SEC-15).
+ *
+ * @see docs/RFC/request-data/029-canonical-request-path.md
+ * @packageDocumentation
+ */
+
+import { collapseAndStrip, isProvablyLowerAscii } from './matching';
+
+/** Result of {@link canonicalizePath}. */
+export interface CanonicalPathResult {
+  /**
+   * `true` when the path contains a `.`/`..` path segment. A dot segment is
+   * rejected outright (400), never resolved — resolving it locally would
+   * diverge from how a front-end proxy already resolved (or didn't resolve)
+   * the same segment before forwarding, reopening the desync this RFC closes.
+   */
+  readonly rejected: boolean;
+  /**
+   * The canonical path: query-stripped, dot-segment-free, case-folded (unless
+   * `caseSensitive`), slash-collapsed, trailing-slash-stripped per `strict`.
+   * Meaningless when {@link rejected} is `true`.
+   */
+  readonly path: string;
+}
+
+const DOT = 0x2e; // '.'
+const SLASH = 0x2f; // '/'
+
+/**
+ * True when `path` (already query-stripped) contains a `.` or `..` segment —
+ * a component that is exactly `.` or `..` between slash boundaries (or at the
+ * start/end of the string). A single linear scan, no backtracking regex
+ * (task 3.5): each character is visited at most once, so a pathological input
+ * cannot degrade to worse than O(n).
+ *
+ * A dot as filename content (`archive.tar.gz`, `..hidden.txt`) is NOT a dot
+ * segment — only a component whose entire text between slashes is `.` or `..`
+ * counts.
+ */
+export function hasDotSegment(path: string): boolean {
+  const len = path.length;
+  let segStart = 0;
+
+  for (let i = 0; i <= len; i++) {
+    const atBoundary = i === len || path.charCodeAt(i) === SLASH;
+    if (!atBoundary) continue;
+
+    const segLen = i - segStart;
+    if (segLen === 1 && path.charCodeAt(segStart) === DOT) return true;
+    if (segLen === 2 && path.charCodeAt(segStart) === DOT && path.charCodeAt(segStart + 1) === DOT) {
+      return true;
+    }
+    segStart = i + 1;
+  }
+
+  return false;
+}
+
+/**
+ * Single-entry memo for {@link canonicalizePath}.
+ *
+ * Exists because a request falling through N prefix mounts asks for the
+ * canonical form of the *same* path N times, once per mount — the O(mounts)
+ * term that made a 10-module app spend most of its dispatch time deciding which
+ * mount to enter. Each call also allocated its own result object, so the memo
+ * removes an allocation as well as three string scans.
+ *
+ * Safe to share the result across callers: {@link CanonicalPathResult} declares
+ * both fields `readonly`, and no caller mutates it (verified across all three
+ * call sites — the mount test, the router's own dispatch, and the adapter).
+ * Keyed on all three inputs, so two routers with different `caseSensitive` or
+ * `strict` options can never read each other's answer. A single entry means
+ * interleaved requests simply miss rather than getting a wrong answer.
+ *
+ * This is a pure-function memo, not shared state: it cannot make
+ * `canonicalizePath` return anything other than what recomputing would return.
+ */
+let memoTarget: string | undefined = undefined;
+let memoCaseSensitive = false;
+let memoStrict = false;
+let memoResult: CanonicalPathResult = { rejected: false, path: '/' };
+
+/**
+ * Canonicalize a raw request target into the one path value every consumer
+ * (router match, mount-prefix test, CSRF exclude match, published `ctx.path`)
+ * treats as "this request's path" (RFC-029).
+ *
+ * Order: strip the query string, reject a dot segment before any further
+ * normalization (a dot segment is a request-shape violation, not something to
+ * fold case on first), then fold case (unless `caseSensitive`) and collapse
+ * structure exactly as {@link import('./matching').normalizePathForMatch} does
+ * — this function IS that normalization, extended with dot-segment rejection
+ * and made a public, adapter-facing entry point.
+ *
+ * The most recent result is memoized; see the note above the memo fields for
+ * why that is sound. Treat the returned object as immutable.
+ *
+ * @param rawTarget - The raw request target, may include a query string.
+ * @param caseSensitive - Router case-sensitivity option.
+ * @param strict - Router strict-trailing-slash option.
+ */
+export function canonicalizePath(
+  rawTarget: string,
+  caseSensitive: boolean,
+  strict: boolean
+): CanonicalPathResult {
+  if (rawTarget === memoTarget && caseSensitive === memoCaseSensitive && strict === memoStrict) {
+    return memoResult;
+  }
+
+  const queryIdx = rawTarget.indexOf('?');
+  const path = queryIdx === -1 ? rawTarget : rawTarget.slice(0, queryIdx);
+
+  const result: CanonicalPathResult = hasDotSegment(path)
+    ? { rejected: true, path }
+    : {
+        rejected: false,
+        path: collapseAndStrip(
+          caseSensitive || isProvablyLowerAscii(path) ? path : path.toLowerCase(),
+          strict
+        ),
+      };
+
+  memoTarget = rawTarget;
+  memoCaseSensitive = caseSensitive;
+  memoStrict = strict;
+  memoResult = result;
+  return result;
+}

package/src/composition.ts

@@ -43,6 +43,10 @@ export function copyRoutes(
 ): void {
   // Copy handlers at this node
   for (const [method, entry] of node.handlers) {
+    // A derived HEAD entry is not copied — the parent re-derives it from the
+    // GET registration below, which keeps the parent's own explicit-HEAD
+    // precedence and introspection rows correct.
+    if (entry.autoHead) continue;
     const path = prefix + '/' + segments.join('/');
     // Prepend sub-router middleware so it runs before the route's own middleware
     const combined =

package/src/constants.ts

@@ -12,14 +12,32 @@
  */
 
 /**
- * Frozen, null-prototype empty params object for matches with no path
- * parameters (static-map hits and successful walks that bound no `:param`/`*`).
+ * Prototype for every per-request key/value bag the router hands to
+ * application code (`ctx.params`).
+ *
+ * Built once at module load, so instances are created with
+ * `Object.create(NULL_PROTO)` rather than `Object.create(null)`. Both satisfy
+ * the security requirement — `Object.prototype` stays unreachable, so a param
+ * named `__proto__`/`constructor`/`prototype` binds as an own key and no
+ * inherited member is visible — but `Object.create(null)` additionally puts the
+ * object into V8 DICTIONARY mode, where property loads cannot be inline-cached.
+ * That cost is paid by every `ctx.params.id` read in every handler, forever.
+ * Deriving from a null-prototype object instead keeps FAST properties.
+ *
+ * @see docs/adr/ADR-0021-fast-property-request-containers.md
+ */
+export const NULL_PROTO: object = Object.create(null) as object;
+
+/**
+ * Frozen empty params object for matches with no path parameters (static-map
+ * hits and successful walks that bound no `:param`/`*`).
  *
  * Shared as a single instance to avoid allocating a fresh object per request on
- * the hot path. Null-prototype so callers can never read an inherited
- * `Object.prototype` key as if it were a route param; frozen so the shared
- * instance can never be mutated by a handler.
+ * the hot path. Frozen so the shared instance can never be mutated by a
+ * handler. Built on {@link NULL_PROTO} because it is *read* on every
+ * static-route request — a dictionary-mode miss-read (`ctx.params.id` on a
+ * route with no params) measured 2.2x slower than a fast-property one.
  */
 export const EMPTY_PARAMS: Record<string, string> = Object.freeze(
-  Object.create(null) as Record<string, string>
+  Object.create(NULL_PROTO) as Record<string, string>
 );

package/src/dispatch.ts

@@ -21,6 +21,7 @@
 import type { Context, HttpMethod, Middleware, RouteMatch } from '@nextrush/types';
 import { NOOP_NEXT, type TrieNode } from './segment-trie';
 import { findAllowedMethods } from './find-node';
+import { canonicalizePath } from './canonicalize';
 
 /**
  * Shared resolved promise for the no-`next` miss path (NF-1). Reused rather than
@@ -32,19 +33,46 @@ const RESOLVED: Promise<void> = Promise.resolve();
 /**
  * Build the router's primary dispatch middleware.
  *
- * On each request it resolves the route via the injected `match` function,
- * sets `ctx.params`, and runs the pre-compiled executor (which already bakes
- * in any router-level middleware). A miss sets `ctx.status = 404` and yields
- * to the next middleware so `allowedMethods()`/a 404 handler can act.
+ * On each request it canonicalizes the path (RFC-029): a dot segment
+ * (`.`/`..`) is rejected with 400 before any route match or path-based
+ * middleware runs — resolving it locally would diverge from how a front-end
+ * proxy already handled the same segment, so it is never resolved, only
+ * rejected. Otherwise it resolves the route via the injected `match`
+ * function, publishes the canonical path onto `ctx.path` (preserving the raw
+ * target as `ctx.originalPath`), sets `ctx.params`, and runs the
+ * pre-compiled executor (which already bakes in any router-level
+ * middleware). A miss sets `ctx.status = 404` and yields to the next
+ * middleware so `allowedMethods()`/a 404 handler can act.
  *
  * @param match - Route resolver, supplied by `Router.match` so this factory
  *   never touches `Router` internals directly.
+ * @param caseSensitive - Router case-sensitivity option, forwarded to
+ *   canonicalization so the published `ctx.path` matches what `match` used.
+ * @param strict - Router strict-trailing-slash option, forwarded likewise.
  */
 export function createRoutesMiddleware(
-  match: (method: HttpMethod, path: string) => RouteMatch | null
+  match: (method: HttpMethod, path: string) => RouteMatch | null,
+  caseSensitive: boolean,
+  strict: boolean
 ): Middleware {
   return (ctx: Context, next?: () => Promise<void>): Promise<void> => {
-    const routeMatch = match(ctx.method, ctx.path);
+    const originalPath = ctx.path;
+    const canonical = canonicalizePath(originalPath, caseSensitive, strict);
+
+    if (canonical.rejected) {
+      // A dot segment is a request-shape violation, not a 404 — it stops the
+      // chain outright rather than falling through to a 404/allowedMethods
+      // handler, which would still leak information about the un-normalized
+      // target via ctx.path.
+      ctx.status = 400;
+      (ctx as { originalPath: string }).originalPath = originalPath;
+      return RESOLVED;
+    }
+
+    (ctx as { path: string }).path = canonical.path;
+    (ctx as { originalPath: string }).originalPath = originalPath;
+
+    const routeMatch = match(ctx.method, canonical.path);
 
     if (!routeMatch) {
       // No route matched — set 404 so allowedMethods()/notFoundHandler() can act,

package/src/index.ts

@@ -15,6 +15,12 @@
 // Router
 export { createRouter, endpoint, Router } from './router';
 
+// Canonical request path (RFC-029) — the single normalization owner shared by
+// the router's own match, mounted-router prefix tests, and any consumer that
+// needs to know "what path does the router treat this request as".
+export { canonicalizePath, hasDotSegment } from './canonicalize';
+export type { CanonicalPathResult } from './canonicalize';
+
 // Route groups
 export type { RouteGroup } from './group-router';
 

package/src/match-route.ts

@@ -14,8 +14,9 @@
  */
 
 import type { HttpMethod, Middleware, RouteMatch } from '@nextrush/types';
-import { EMPTY_PARAMS } from './constants';
+import { EMPTY_PARAMS, NULL_PROTO } from './constants';
 import { matchNodeIndexed, collapseAndStrip, isProvablyLowerAscii } from './matching';
+import type { WalkPool } from './walk-pool';
 import type { StaticRouteMap, TrieNode } from './segment-trie';
 
 /**
@@ -43,7 +44,25 @@ export function matchRoute(
   caseSensitive: boolean,
   strict: boolean,
   decode: boolean,
-  routerMiddleware: Middleware[]
+  routerMiddleware: Middleware[],
+  /**
+   * When `true`, `rawPath` is trusted as already the output of
+   * `canonicalizePath()` (same `caseSensitive`/`strict` options) — the fold
+   * and structural-collapse steps below are skipped entirely rather than
+   * re-derived. Only valid when the caller has actually run
+   * `canonicalizePath()` on this exact input first (F-10); the router's own
+   * `routes()` dispatch path is the only caller that does. Defaults to
+   * `false`, preserving every other caller's existing behavior — including
+   * `Router.match()`, which never canonicalizes first.
+   */
+  preNormalized = false,
+  /**
+   * When supplied, the param walk reuses this router instance's pooled
+   * `WalkFrame[]`/binding-array scratch space instead of allocating fresh
+   * arrays on this call (F-02, `reduce-router-match-allocations`). Omitted,
+   * `matchRoute` behaves exactly as before.
+   */
+  walkPool?: WalkPool
 ): RouteMatch | null {
   let path = rawPath;
   // Query string must not affect path matching (RFC 3986 §3.4). Strip it here,
@@ -51,16 +70,30 @@ export function matchRoute(
   // exclude it. This strip is caller-specific: `findAllowedMethods` receives an
   // already query-free `ctx.path`, so the shared `normalizePathForMatch` does
   // not strip — only `matchRoute` does.
-  const queryIdx = path.indexOf('?');
-  if (queryIdx !== -1) path = path.slice(0, queryIdx);
+  if (!preNormalized) {
+    const queryIdx = path.indexOf('?');
+    if (queryIdx !== -1) path = path.slice(0, queryIdx);
+  }
 
   // HP-12: decide case-stability ONCE. When the path is provably case-stable
   // (case-sensitive router, or an all-lowercase-ASCII path), folding is a no-op
   // and the original-case path equals the normalized one — so we skip both the
   // `toLowerCase()` allocation and the second original-case normalize pass.
-  const caseStable = caseSensitive || isProvablyLowerAscii(path);
-  const folded = caseStable ? path : path.toLowerCase();
-  const normalized = collapseAndStrip(folded, strict);
+  //
+  // F-10: when `preNormalized` is true, the caller already ran this exact
+  // fold+collapse via `canonicalizePath()` — trust `path` as both the
+  // normalized AND original-case string, skipping the fold+collapse
+  // re-derivation entirely rather than repeating work already done upstream.
+  let normalized: string;
+  let caseStable: boolean;
+  if (preNormalized) {
+    normalized = path;
+    caseStable = true;
+  } else {
+    caseStable = caseSensitive || isProvablyLowerAscii(path);
+    const folded = caseStable ? path : path.toLowerCase();
+    normalized = collapseAndStrip(folded, strict);
+  }
 
   // FAST PATH: O(1) static route lookup (no tree traversal). Method-nested map
   // (HP-9): select the inner map by method, then probe by the normalized path —
@@ -94,9 +127,19 @@ export function matchRoute(
   // Deferred param binding (HP-11): the walk records the accepted path's
   // `:param`/`*` bindings onto these parallel stacks (pushed on descent, popped
   // on backtrack) so params are materialized ONCE here on the accepted terminal
-  // — no eager bind + backtrack `Reflect.deleteProperty`.
-  const bindNames: string[] = [];
-  const bindValues: string[] = [];
+  // — no eager bind + backtrack `Reflect.deleteProperty`. Reused from the
+  // router's pool when supplied (F-02) instead of allocated fresh.
+  const bindNames: string[] = walkPool ? walkPool.bindNames : [];
+  const bindValues: string[] = walkPool ? walkPool.bindValues : [];
+  // A pooled bindNames/bindValues array persists across calls — clear any
+  // leftover entries from a prior match before this walk starts (the walk
+  // itself pops everything it pushes on a clean miss or match, but a defensive
+  // clear here costs nothing on the common empty case and closes any future
+  // edit that might leave a stale entry behind).
+  if (walkPool) {
+    bindNames.length = 0;
+    bindValues.length = 0;
+  }
 
   const entry = matchNodeIndexed(
     root,
@@ -106,21 +149,25 @@ export function matchRoute(
     bindValues,
     method,
     decode,
-    originalPath
+    originalPath,
+    walkPool
   );
   if (!entry) return null;
 
-  // Materialize params once on a null-prototype object (design.md D8): a param
-  // named `__proto__`/`constructor`/`prototype` binds as an OWN key with no
-  // prototype mutation, and no inherited member is visible on `ctx.params`. The
-  // bind count replaces the former `Object.keys` post-loop (HP-13); zero binds
-  // returns the shared frozen `EMPTY_PARAMS`.
+  // Materialize params once on a bag whose prototype chain excludes
+  // `Object.prototype` (design.md D8): a param named
+  // `__proto__`/`constructor`/`prototype` binds as an OWN key with no prototype
+  // mutation, and no inherited member is visible on `ctx.params`. Derived from
+  // `NULL_PROTO` rather than `Object.create(null)` so the object keeps V8 fast
+  // properties and handler reads stay inline-cacheable. The bind count replaces
+  // the former `Object.keys` post-loop (HP-13); zero binds returns the shared
+  // frozen `EMPTY_PARAMS`.
   const count = bindNames.length;
   let params: Record<string, string>;
   if (count === 0) {
     params = EMPTY_PARAMS;
   } else {
-    params = Object.create(null) as Record<string, string>;
+    params = Object.create(NULL_PROTO) as Record<string, string>;
     for (let i = 0; i < count; i++) {
       const name = bindNames[i];
       const value = bindValues[i];
@@ -140,6 +187,14 @@ export function matchRoute(
  * Stable router state `resolveMatch` reads on every request. All fields are
  * fixed references for the router's lifetime, so the caller memoizes this once
  * rather than rebuilding it per request.
+ *
+ * `walkPool` is the one field that is itself mutable (its contents, not the
+ * reference) — the reused `WalkFrame[]`/binding-array scratch space (F-02,
+ * `reduce-router-match-allocations`). It is `undefined` until the router has
+ * at least one param/wildcard route (no pool needed for a static-only router,
+ * per `createWalkPool(0)` never being called) and is rebuilt whenever the
+ * router's `maxDepth` grows past what the current pool was sized for — see
+ * `Router`'s own wiring, not this interface, for when that rebuild happens.
  */
 export interface MatchState {
   readonly root: TrieNode;
@@ -148,6 +203,7 @@ export interface MatchState {
   readonly strict: boolean;
   readonly decode: boolean;
   readonly routerMiddleware: Middleware[];
+  walkPool?: WalkPool;
 }
 
 /**
@@ -162,7 +218,12 @@ export function resolveMatch(
   state: MatchState,
   hasParamRoutes: boolean,
   method: HttpMethod,
-  path: string
+  path: string,
+  /**
+   * Forwarded to {@link matchRoute} — see its own doc comment for the
+   * caller contract. Defaults to `false`.
+   */
+  preNormalized = false
 ): RouteMatch | null {
   return matchRoute(
     method,
@@ -173,6 +234,8 @@ export function resolveMatch(
     state.caseSensitive,
     state.strict,
     state.decode,
-    state.routerMiddleware
+    state.routerMiddleware,
+    preNormalized,
+    state.walkPool
   );
 }

package/src/matching.ts

@@ -13,6 +13,10 @@
 
 import type { HttpMethod } from '@nextrush/types';
 import type { HandlerEntry, TrieNode } from './segment-trie';
+import { matchNodeIndexedPooled, type WalkFrame, type WalkPool } from './walk-pool';
+
+export type { WalkFrame, WalkPool } from './walk-pool';
+export { createWalkPool } from './walk-pool';
 
 /**
  * Percent-decode an extracted param/wildcard value when `decode` is enabled.
@@ -113,20 +117,10 @@ export function normalizePathForMatch(
 }
 
 /**
- * One node in the iterative walk's explicit stack. `stage` is a small state
- * machine (0 = extract + try static, 1 = try param, 2 = try wildcard/backtrack)
- * so a single frame can be revisited on backtrack without recursion. `bound`
- * records whether this frame pushed a deferred param binding, so backtracking
- * can pop it without an object-property delete.
+ * One node in the iterative walk's explicit stack — see the full doc comment
+ * on {@link WalkFrame} in `walk-pool.ts` (re-exported here for callers that
+ * only import from `matching.ts`).
  */
-interface WalkFrame {
-  node: TrieNode;
-  pos: number;
-  stage: 0 | 1 | 2;
-  seg: string;
-  next: number;
-  bound: boolean;
-}
 
 /**
  * Iterative, index-based segment-trie match (HP-11 / HP-13, design.md D4).
@@ -156,8 +150,20 @@ export function matchNodeIndexed(
   bindValues: string[],
   method: HttpMethod,
   decode: boolean,
-  originalPath?: string
+  originalPath?: string,
+  /**
+   * When provided, the walk indexes into `pool.frames` by depth (reusing
+   * each pre-allocated frame object in place) instead of `push`/`pop`-ing
+   * fresh frame literals onto a fresh array — see `walk-pool.ts`'s
+   * `matchNodeIndexedPooled`. Omitted, the walk behaves exactly as before (a
+   * fresh `stack: WalkFrame[]`) — every other caller of `matchNodeIndexed`
+   * keeps its current behavior unchanged.
+   */
+  pool?: WalkPool
 ): HandlerEntry | null {
+  if (pool) {
+    return matchNodeIndexedPooled(root, path, startPos, bindNames, bindValues, method, decode, pool, originalPath);
+  }
   const stack: WalkFrame[] = [
     { node: root, pos: startPos, stage: 0, seg: '', next: 0, bound: false },
   ];