@nextrush/router 3.0.6 → 4.0.0-beta.0

package/src/__tests__/helpers/differential-corpus.ts

@@ -0,0 +1,316 @@
+/**
+ * @nextrush/router - Differential / characterization corpus
+ *
+ * Shared corpus + canonical serializer backing the golden-master regression
+ * harness for the `router-match-path-allocation-trim` change. The serializer
+ * reduces a `Router.match()` result to a stable, JSON-comparable shape so the
+ * pre-change matcher's output (captured once into `match-golden.json`) can be
+ * asserted byte-identical against the post-rewrite matcher across every trim.
+ *
+ * WHY a golden master rather than two live matchers: the trims land in-place on
+ * a single matcher, so the "old" implementation cannot coexist with the "new"
+ * one in the same process. Persisting the pre-change output as a committed
+ * fixture is the standard characterization technique for exactly this — the
+ * fixture IS the old matcher's behavior, frozen.
+ *
+ * Intentional-delta cases (null-prototype params, and `__proto__`/`constructor`/
+ * `prototype` param NAMES) are deliberately NOT in this corpus — they change
+ * observably by design (design.md D8) and are pinned by dedicated forward
+ * scenarios instead. This corpus covers only the behavior-PRESERVING contract:
+ * which route resolves, the own-enumerable param entries and their values, and
+ * whether an executor is present.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Context, RouteHandler } from '@nextrush/types';
+import { createRouter, Router } from '../../router';
+
+/** A tagged no-op handler so a match result's `handler` is identifiable. */
+function h(tag: string): RouteHandler {
+  const fn = (async (_ctx: Context) => {
+    /* no-op */
+  }) as RouteHandler & { tag: string };
+  fn.tag = tag;
+  return fn;
+}
+
+/** A single (method, path) probe against a named route set. */
+export interface Probe {
+  method: string;
+  path: string;
+}
+
+/** A named router plus the probes run against it. */
+export interface RouteSet {
+  name: string;
+  build: () => Router;
+  probes: Probe[];
+}
+
+/**
+ * Canonical, JSON-stable serialization of one match result.
+ *
+ * Deliberately excludes the params [[Prototype]] from the golden diff: the
+ * prototype flips from `Object.prototype` to `null` for populated params by
+ * design (D8), so it is asserted as a forward invariant elsewhere, not baked
+ * into the byte-identical golden. Own-enumerable key OWNERSHIP and VALUES —
+ * the real behavioral contract — ARE captured here.
+ */
+export interface SerializedMatch {
+  matched: boolean;
+  handlerTag: string | null;
+  params: Array<[string, string]>;
+  hasExecutor: boolean;
+}
+
+/** Run one probe against a built router and reduce it to the canonical shape. */
+export function serializeMatch(router: Router, method: string, path: string): SerializedMatch {
+  const result = router.match(method as never, path);
+  if (!result) {
+    return { matched: false, handlerTag: null, params: [], hasExecutor: false };
+  }
+  const handler = result.handler as (RouteHandler & { tag?: string }) | undefined;
+  const params = Object.keys(result.params)
+    .sort()
+    .map((k) => [k, result.params[k]] as [string, string]);
+  return {
+    matched: true,
+    handlerTag: handler?.tag ?? null,
+    params,
+    hasExecutor: typeof result.executor === 'function',
+  };
+}
+
+/**
+ * The default route set: exercises static, nested static, single/nested params,
+ * backtracking, static-over-param-over-wildcard precedence, wildcard (incl.
+ * empty capture), and param + trailing wildcard. Case-insensitive, non-strict,
+ * decode on (framework defaults).
+ */
+function buildDefault(): Router {
+  const r = createRouter();
+  r.get('/', h('root'));
+  r.get('/users', h('users'));
+  r.get('/users/me', h('users.me')); // static beats param
+  r.get('/users/:id', h('users.id'));
+  r.get('/a/b/c', h('a.b.c')); // nested static
+  r.get('/a/:x/c', h('a.x.c')); // backtracking target
+  r.get('/a/b/d', h('a.b.d'));
+  r.get('/a/:x/b/:y', h('a.x.b.y')); // nested params
+  r.get('/p/me', h('p.me')); // static > param > wildcard at one node
+  r.get('/p/:id', h('p.id'));
+  r.get('/p/*', h('p.star'));
+  r.get('/files/*', h('files.star')); // wildcard incl. empty capture
+  r.get('/g/:x/*', h('g.x.star')); // param + trailing wildcard
+  r.post('/users', h('users.post')); // method variety on a static path
+  return r;
+}
+
+function buildCaseSensitive(): Router {
+  const r = createRouter({ caseSensitive: true });
+  r.get('/Users/:id', h('cs.users.id'));
+  r.get('/Static', h('cs.static'));
+  return r;
+}
+
+function buildStrict(): Router {
+  const r = createRouter({ strict: true });
+  r.get('/strict', h('strict.static'));
+  r.get('/strict/:id', h('strict.id'));
+  return r;
+}
+
+function buildDecodeOff(): Router {
+  const r = createRouter({ decode: false });
+  r.get('/raw/:id', h('raw.id'));
+  r.get('/raw/*', h('raw.star'));
+  return r;
+}
+
+function buildAll(): Router {
+  const r = createRouter();
+  r.all('/any', h('any'));
+  return r;
+}
+
+function buildPrefix(): Router {
+  const r = createRouter({ prefix: '/api' });
+  r.get('/health', h('api.health'));
+  r.get('/items/:id', h('api.items.id'));
+  return r;
+}
+
+function buildMount(): Router {
+  const child = createRouter();
+  child.get('/x', h('mount.x'));
+  child.get('/:p', h('mount.p'));
+  const parent = createRouter();
+  parent.mount('/sub', child);
+  return parent;
+}
+
+function buildGroup(): Router {
+  const r = createRouter();
+  r.group('/g', (g) => {
+    g.get('/y', h('group.y'));
+    g.get('/:z', h('group.z'));
+  });
+  return r;
+}
+
+/**
+ * Backtracking-specific set. `/bt/:x/c` + `/bt/b/d` forces the walk to try the
+ * static `b` branch, fail at `c`, and fall back to the param branch. `/w/:x/deep`
+ * + `/w/*` is the stale-param guard: the param branch binds `:x`, fails deeper,
+ * backtracks, and the wildcard must match with NO leftover `x` binding.
+ */
+function buildBacktrack(): Router {
+  const r = createRouter();
+  r.get('/bt/:x/c', h('bt.x.c'));
+  r.get('/bt/b/d', h('bt.b.d'));
+  r.get('/w/:x/deep', h('w.x.deep'));
+  r.get('/w/*', h('w.star'));
+  return r;
+}
+
+/** Every route set + its probe corpus. */
+export const ROUTE_SETS: RouteSet[] = [
+  {
+    name: 'default',
+    build: buildDefault,
+    probes: [
+      { method: 'GET', path: '/' },
+      { method: 'GET', path: '/users' },
+      { method: 'GET', path: '/users/' }, // trailing slash (static, non-strict)
+      { method: 'GET', path: '/users/me' }, // static beats param
+      { method: 'GET', path: '/users/42' }, // param
+      { method: 'GET', path: '/users/42/' }, // trailing slash (param, non-strict)
+      { method: 'GET', path: '/Users/AbC' }, // non-ASCII-free cased; value keeps case
+      { method: 'GET', path: '/users/a%20b' }, // percent-decoded space
+      { method: 'GET', path: '/users/a%2Fb' }, // encoded slash stays in value
+      { method: 'GET', path: '/users/a%2Eb' }, // encoded dot stays in value
+      { method: 'GET', path: '/users/%zz' }, // malformed encoding → raw
+      { method: 'GET', path: '/users/%' }, // malformed → raw
+      { method: 'GET', path: '/users/%2' }, // truncated → raw
+      { method: 'GET', path: '/users/\u00dcrl' }, // non-ASCII uppercase param value
+      { method: 'GET', path: '/a/b/c' }, // nested static
+      { method: 'GET', path: '/a/b/c/' },
+      { method: 'GET', path: '/a/b/d' },
+      { method: 'GET', path: '/a/b/x' }, // backtrack: static b fails at x → param :x=b
+      { method: 'GET', path: '/a/1/b/2' }, // nested params
+      { method: 'GET', path: '/p/me' }, // static
+      { method: 'GET', path: '/p/other' }, // param
+      { method: 'GET', path: '/p/a/b/c' }, // wildcard
+      { method: 'GET', path: '/files/A/b/c' }, // wildcard original-case remainder
+      { method: 'GET', path: '/files' }, // wildcard empty capture
+      { method: 'GET', path: '/files/' }, // wildcard empty capture (trailing)
+      { method: 'GET', path: '/g/1/b/c' }, // param + trailing wildcard
+      { method: 'GET', path: '/users?q=1' }, // query stripped
+      { method: 'GET', path: '/users/42?x=y' }, // query stripped, param
+      { method: 'GET', path: '//a//b//c' }, // repeated-slash collapse
+      { method: 'GET', path: '///' }, // all-slash
+      { method: 'GET', path: '/nope' }, // miss
+      { method: 'POST', path: '/users' }, // method variety
+      { method: 'POST', path: '/users/me' }, // method-miss on known path
+      { method: 'DELETE', path: '/users/42' }, // method-miss on param path
+      { method: 'GET', path: `/deep/${Array.from({ length: 200 }, (_, i) => `s${i}`).join('/')}` }, // deep miss
+    ],
+  },
+  {
+    name: 'caseSensitive',
+    build: buildCaseSensitive,
+    probes: [
+      { method: 'GET', path: '/Users/AbC' },
+      { method: 'GET', path: '/users/abc' }, // lowercase miss (case-sensitive)
+      { method: 'GET', path: '/Static' },
+      { method: 'GET', path: '/static' }, // miss
+    ],
+  },
+  {
+    name: 'strict',
+    build: buildStrict,
+    probes: [
+      { method: 'GET', path: '/strict' },
+      { method: 'GET', path: '/strict/' }, // strict: trailing slash NOT stripped → behavior as today
+      { method: 'GET', path: '/strict/42' },
+      { method: 'GET', path: '/strict/42/' },
+    ],
+  },
+  {
+    name: 'decodeOff',
+    build: buildDecodeOff,
+    probes: [
+      { method: 'GET', path: '/raw/a%20b' }, // raw, not decoded
+      { method: 'GET', path: '/raw/a%2Fb' },
+      { method: 'GET', path: '/raw/x/y/z' }, // wildcard raw remainder
+    ],
+  },
+  {
+    name: 'all',
+    build: buildAll,
+    probes: [
+      { method: 'GET', path: '/any' },
+      { method: 'POST', path: '/any' },
+      { method: 'PUT', path: '/any' },
+      { method: 'DELETE', path: '/any' },
+      { method: 'PATCH', path: '/any' },
+      { method: 'HEAD', path: '/any' },
+      { method: 'OPTIONS', path: '/any' },
+    ],
+  },
+  {
+    name: 'prefix',
+    build: buildPrefix,
+    probes: [
+      { method: 'GET', path: '/api/health' },
+      { method: 'GET', path: '/health' }, // miss (no prefix)
+      { method: 'GET', path: '/api/items/7' },
+    ],
+  },
+  {
+    name: 'mount',
+    build: buildMount,
+    probes: [
+      { method: 'GET', path: '/sub/x' }, // copied static
+      { method: 'GET', path: '/sub/other' }, // copied param
+    ],
+  },
+  {
+    name: 'group',
+    build: buildGroup,
+    probes: [
+      { method: 'GET', path: '/g/y' }, // group static
+      { method: 'GET', path: '/g/other' }, // group param
+    ],
+  },
+  {
+    name: 'backtrack',
+    build: buildBacktrack,
+    probes: [
+      { method: 'GET', path: '/bt/b/c' }, // static b fails at c → param :x=b matches
+      { method: 'GET', path: '/bt/b/d' }, // static b/d
+      { method: 'GET', path: '/bt/z/c' }, // param directly (no static z)
+      { method: 'GET', path: '/w/foo/other' }, // param :x binds, fails, backtracks → wildcard, NO stale x
+      { method: 'GET', path: '/w/foo/deep' }, // param :x=foo matches deep
+      { method: 'GET', path: '/w/a/b/c' }, // wildcard multi-segment
+    ],
+  },
+];
+
+/**
+ * Compute the full golden map: `"<set> <METHOD> <path>" -> SerializedMatch`.
+ * Deterministic and side-effect-free (each route set is freshly built).
+ */
+export function computeGolden(): Record<string, SerializedMatch> {
+  const out: Record<string, SerializedMatch> = {};
+  for (const set of ROUTE_SETS) {
+    const router = set.build();
+    for (const probe of set.probes) {
+      const key = `${set.name} ${probe.method} ${probe.path}`;
+      out[key] = serializeMatch(router, probe.method, probe.path);
+    }
+  }
+  return out;
+}

package/src/__tests__/match-differential.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @nextrush/router - Differential / characterization harness
+ *
+ * Golden-master regression contract for `router-match-path-allocation-trim`.
+ * `match-golden.json` was captured from the PRE-CHANGE matcher; this asserts
+ * the current matcher reproduces it byte-for-byte across the broad corpus in
+ * `helpers/differential-corpus.ts`. Any behavioral drift on a preserved case
+ * (route resolution, own-param entries/values, executor presence) fails here.
+ *
+ * Regenerate intentionally (only when a delta is understood and approved):
+ *   GEN_GOLDEN=1 pnpm --filter @nextrush/router test match-differential
+ *
+ * Intentional deltas (null-prototype params; `__proto__`/`constructor`/
+ * `prototype` param names) are covered by dedicated forward scenarios, NOT by
+ * regenerating this golden — see `match-safety.test.ts`.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { computeGolden, type SerializedMatch } from './helpers/differential-corpus';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const GOLDEN_PATH = join(HERE, 'fixtures', 'match-golden.json');
+
+describe('Router match — differential / characterization harness', () => {
+  const computed = computeGolden();
+
+  if (process.env.GEN_GOLDEN) {
+    writeFileSync(GOLDEN_PATH, `${JSON.stringify(computed, null, 2)}\n`, 'utf-8');
+  }
+
+  const golden = JSON.parse(readFileSync(GOLDEN_PATH, 'utf-8')) as Record<string, SerializedMatch>;
+
+  it('reproduces the pre-change matcher output for every corpus probe', () => {
+    expect(computed).toEqual(golden);
+  });
+
+  it('covers the full corpus (no probe silently dropped)', () => {
+    const computedKeys = Object.keys(computed).sort();
+    const goldenKeys = Object.keys(golden).sort();
+    expect(computedKeys).toEqual(goldenKeys);
+    expect(computedKeys.length).toBeGreaterThan(50);
+  });
+});

package/src/__tests__/match-hotpath-guard.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @nextrush/router - HP-18 deopt-pattern regression guard
+ *
+ * Static source guard for OpenSpec change `router-context-final-cleanup` (HP-18).
+ * The P2 rewrite (`router-match-path-allocation-trim`) removed the two V8
+ * deopt/allocation patterns from the router match path:
+ *
+ *  - the eager-bind + backtrack `Reflect.deleteProperty(params, name)` used to
+ *    undo a stale param binding, and
+ *  - the `Object.keys(...)`-based post-match loop that materialized params.
+ *
+ * Both are gone today (params are bound via deferred parallel stacks and a
+ * bind-count loop). This guard fails if EITHER is reintroduced into the router
+ * match sources, so a future edit cannot silently regress the hot path.
+ *
+ * WHY a source scan rather than a behavioral spy: the invariant is "this
+ * mechanism never comes back", not "one probe doesn't trigger it". A spy
+ * (see `match-safety.test.ts`) proves a specific match doesn't call them; this
+ * proves the identifiers are absent from the source entirely — a stronger,
+ * edit-resistant contract. Comments are stripped first because the source prose
+ * deliberately NAMES these removed patterns to explain why they're gone.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = join(HERE, '..');
+
+/**
+ * The files that make up the router match path (design.md / proposal). `find-node.ts`
+ * holds the method-agnostic walk split out of `matching.ts` during the HP-17
+ * rewrite, so it is guarded alongside the two match sources.
+ */
+const MATCH_SOURCES = ['matching.ts', 'match-route.ts', 'find-node.ts'] as const;
+
+/**
+ * Remove block (`/* ... *\/`) and line (`// ...`) comments so the guard scans
+ * only executable code — the source comments intentionally reference the very
+ * patterns this guard forbids, to document that they were removed.
+ */
+function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+
+function readCode(file: string): string {
+  return stripComments(readFileSync(join(SRC, file), 'utf-8'));
+}
+
+describe('HP-18 — router match path stays free of the removed deopt patterns', () => {
+  it.each(MATCH_SOURCES)('%s contains no backtrack Reflect.deleteProperty', (file) => {
+    expect(readCode(file)).not.toContain('Reflect.deleteProperty');
+  });
+
+  it.each(MATCH_SOURCES)('%s contains no Object.keys post-match loop', (file) => {
+    expect(readCode(file)).not.toContain('Object.keys');
+  });
+
+  it('actually scanned real, non-empty match sources (guard is not vacuous)', () => {
+    for (const file of MATCH_SOURCES) {
+      const code = readCode(file);
+      // Sanity: the file exists, has real content, and the comment-stripper
+      // left the actual matcher code (so the negative assertions above are
+      // scanning something, not an empty string).
+      expect(code.length).toBeGreaterThan(200);
+      expect(code).toContain('export function');
+    }
+  });
+});

package/src/__tests__/match-normalize-fastpath.test.ts

@@ -0,0 +1,66 @@
+/**
+ * @nextrush/router - HP-12 unicode-correct case-normalization fast-path
+ *
+ * Pins design.md D3: `normalizePathForMatch` skips `toLowerCase()` only when the
+ * path is PROVABLY case-stable (all ASCII, no `A`–`Z`), folding on any non-ASCII
+ * or uppercase byte — so the result is byte-identical to always folding, and a
+ * non-ASCII uppercase path is never wrongly skipped. Also pins that a
+ * case-stable (lowercase-ASCII) request needs NO fold allocation and NO second
+ * original-case normalize pass, via a `String.prototype.toLowerCase` spy.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { normalizePathForMatch } from '../matching';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {
+  /* no-op */
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('HP-12 — unicode-correct case-normalization fast-path', () => {
+  it('does not call toLowerCase for a provably-lowercase ASCII path (case-insensitive)', () => {
+    const spy = vi.spyOn(String.prototype, 'toLowerCase');
+    const out = normalizePathForMatch('/users/abc', false, false);
+    expect(out).toBe('/users/abc');
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('still folds an ASCII-uppercase path byte-identically to toLowerCase()', () => {
+    expect(normalizePathForMatch('/Users/AbC', false, false)).toBe('/Users/AbC'.toLowerCase());
+  });
+
+  it('still folds a NON-ASCII uppercase path byte-identically (fast-path does not wrongly skip)', () => {
+    // '/ÜRL' contains non-ASCII uppercase; the fast-path must NOT skip folding.
+    expect(normalizePathForMatch('/\u00dcRL', false, false)).toBe('/\u00dcRL'.toLowerCase());
+    expect(normalizePathForMatch('/caf\u00c9', false, false)).toBe('/caf\u00c9'.toLowerCase());
+  });
+
+  it('collapses double slashes and strips a trailing slash identically after the fast-path', () => {
+    expect(normalizePathForMatch('//a//b/', false, false)).toBe('/a/b');
+    expect(normalizePathForMatch('//A//B/', false, false)).toBe('//A//B/'.toLowerCase().replace(/\/+/g, '/').replace(/\/$/, ''));
+  });
+
+  it('a case-stable param match resolves without ANY toLowerCase call (no second normalize pass)', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    // Warm registration is done; now spy only the match path.
+    const spy = vi.spyOn(String.prototype, 'toLowerCase');
+    const match = router.match('GET', '/users/42');
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({ id: '42' });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('a case-insensitive param match preserves original-case param values', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const match = router.match('GET', '/Users/AbC');
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({ id: 'AbC' });
+  });
+});

package/src/__tests__/match-safety.test.ts

@@ -0,0 +1,177 @@
+/**
+ * @nextrush/router - HP-11 safety & critical-flow contract (task 5.2)
+ *
+ * Forward-looking scenarios for the param-walk rewrite (design.md D4/D8/D9/D10):
+ * null-prototype params, `__proto__`-name binding without pollution,
+ * encoded-slash/dot never re-segmenting the path, concurrency isolation,
+ * deep-path DoS safety (iterative walk), the clean-null miss / 405 flow, the
+ * compiled-executor invariant, and the removal of the `Object.keys` post-loop
+ * and backtrack `Reflect.deleteProperty` (deterministic spies).
+ *
+ * The 5.1 core matching invariants (precedence, backtracking, casing, decode,
+ * wildcard, param+wildcard, empty-param, trailing-slash, param-less→EMPTY_PARAMS)
+ * are pinned by the 66-probe differential golden in `match-differential.test.ts`;
+ * this file adds only what the golden cannot express.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { EMPTY_PARAMS } from '../constants';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {
+  /* no-op */
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('HP-11 — null-prototype params (D8)', () => {
+  it('materializes a populated params object with a null prototype', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const match = router.match('GET', '/users/42');
+    expect(match?.params).toEqual({ id: '42' });
+    expect(Object.getPrototypeOf(match?.params)).toBeNull();
+  });
+
+  it('exposes no inherited Object.prototype members on params', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const params = router.match('GET', '/users/42')?.params as Record<string, unknown>;
+    expect(params['toString']).toBeUndefined();
+    expect(params['hasOwnProperty']).toBeUndefined();
+  });
+
+  it('binds a __proto__ param as an OWN key without polluting Object.prototype', () => {
+    const router = createRouter();
+    router.get('/:__proto__', noop);
+    const match = router.match('GET', '/danger');
+    expect(match).not.toBeNull();
+    expect(Object.prototype.hasOwnProperty.call(match?.params, '__proto__')).toBe(true);
+    expect((match?.params as Record<string, string>)['__proto__']).toBe('danger');
+    // No global prototype pollution.
+    expect(({} as Record<string, unknown>)['danger']).toBeUndefined();
+    expect((Object.prototype as Record<string, unknown>)['danger']).toBeUndefined();
+  });
+
+  it('binds a constructor param as an OWN string key', () => {
+    const router = createRouter();
+    router.get('/:constructor', noop);
+    const match = router.match('GET', '/boom');
+    expect(Object.prototype.hasOwnProperty.call(match?.params, 'constructor')).toBe(true);
+    expect((match?.params as Record<string, string>)['constructor']).toBe('boom');
+  });
+});
+
+describe('HP-11 — traversal-safe decode (D9): encoded slash/dot never re-segments', () => {
+  it('keeps an encoded slash inside a single param value and matches /files/:name (not a structural /files/a/b)', () => {
+    const router = createRouter();
+    router.get('/files/:name', noop);
+    router.get('/files/a/b', (async () => {}) as RouteHandler);
+    const match = router.match('GET', '/files/a%2Fb');
+    expect(match?.params).toEqual({ name: 'a/b' });
+  });
+
+  it('keeps encoded dots inside the value (no `..` traversal segments)', () => {
+    const router = createRouter();
+    router.get('/files/:name', noop);
+    const match = router.match('GET', '/files/%2E%2E');
+    expect(match?.params).toEqual({ name: '..' });
+  });
+});
+
+describe('HP-11 — concurrency isolation (D10)', () => {
+  it('gives each match its own params; no cross-contamination across many matches', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const results = Array.from({ length: 1000 }, (_, i) => router.match('GET', `/users/u${i}`));
+    results.forEach((m, i) => {
+      expect(m?.params).toEqual({ id: `u${i}` });
+    });
+    // Distinct param objects per match (no shared mutable scratch reused).
+    expect(results[0]?.params).not.toBe(results[1]?.params);
+  });
+
+  it('shares only the frozen EMPTY_PARAMS for param-less matches', () => {
+    const router = createRouter();
+    router.get('/a/*', noop); // wildcard keeps hasParamRoutes true; /health walks & binds nothing
+    router.get('/health', noop);
+    // A static-through-trie param-less match returns the shared sentinel.
+    const m1 = router.match('GET', '/health');
+    expect(m1?.params).toBe(EMPTY_PARAMS);
+  });
+});
+
+describe('HP-11 — deep-path DoS safety (iterative walk)', () => {
+  it('resolves a very deep matching path without a stack overflow', () => {
+    const depth = 60000;
+    const router = createRouter();
+    // A deep param chain forces the walk to descend `depth` levels.
+    router.get('/' + Array.from({ length: depth }, () => ':p').join('/'), noop);
+    const path = '/' + Array.from({ length: depth }, (_, i) => `x${i}`).join('/');
+    expect(() => router.match('GET', path)).not.toThrow();
+    expect(router.match('GET', path)).not.toBeNull();
+  });
+
+  it('misses a very deep non-matching path without a stack overflow', () => {
+    const depth = 60000;
+    const router = createRouter();
+    router.get('/short/:id', noop);
+    const path = '/' + Array.from({ length: depth }, (_, i) => `x${i}`).join('/');
+    expect(() => router.match('GET', path)).not.toThrow();
+    expect(router.match('GET', path)).toBeNull();
+  });
+});
+
+describe('HP-11 — miss / 405 / executor critical flow', () => {
+  it('returns null cleanly on a miss', () => {
+    const router = createRouter();
+    router.get('/x/:id', noop);
+    expect(router.match('GET', '/nope')).toBeNull();
+  });
+
+  it('returns null for a known path with an unregistered method (so allowedMethods can 405)', () => {
+    const router = createRouter();
+    router.get('/x/:id', noop);
+    expect(router.match('POST', '/x/42')).toBeNull();
+  });
+
+  it('returns null for a wildcard path requested with an unregistered method', () => {
+    const router = createRouter();
+    router.get('/w/*', noop);
+    // Wildcard child exists but has no POST handler → the walk pops the deferred
+    // '*' bind and backtracks to a clean null (not a spurious match).
+    expect(router.match('POST', '/w/a/b')).toBeNull();
+  });
+
+  it('returns the pre-compiled executor on a matched param route (not re-composed)', () => {
+    const router = createRouter();
+    router.get('/x/:id', noop);
+    const match = router.match('GET', '/x/42');
+    expect(typeof match?.executor).toBe('function');
+  });
+});
+
+describe('HP-11/HP-13 — allocation mechanism removed (deterministic spies)', () => {
+  it('does not call Object.keys on the param match path (HP-13 post-loop gone)', () => {
+    const router = createRouter();
+    router.get('/x/:id', noop);
+    const spy = vi.spyOn(Object, 'keys');
+    router.match('GET', '/x/42');
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('does not call Reflect.deleteProperty during a backtracking match (eager-bind/backtrack gone)', () => {
+    const router = createRouter();
+    router.get('/a/:x/c', noop);
+    router.get('/a/b/d', noop);
+    const spy = vi.spyOn(Reflect, 'deleteProperty');
+    // /a/b/c: static `b` tried, fails at `c`, backtracks to param :x — the exact
+    // path that used to call Reflect.deleteProperty on backtrack.
+    const match = router.match('GET', '/a/b/c');
+    expect(match?.params).toEqual({ x: 'b' });
+    expect(spy).not.toHaveBeenCalled();
+  });
+});