@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/__tests__/match-node-indexed-unpooled.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @nextrush/router - matchNodeIndexed's unpooled fallback stays correct
+ * (`reduce-router-match-allocations`)
+ *
+ * `Router` always supplies a `WalkPool` once it has any param/wildcard route
+ * (via `Router.addRoute`'s pool-rebuild hook), so the unpooled branch of
+ * `matchNodeIndexed` has no reachable caller through the public API today.
+ * It is kept as an explicit, documented fallback for any future direct caller
+ * that doesn't have a pool — this file is that caller, proving the fallback
+ * itself is still correct (same results as the pooled path) rather than
+ * leaving it as untested dead code.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { matchNodeIndexed } from '../matching';
+import { createNode, NodeType, type HandlerEntry } from '../segment-trie';
+import { compileExecutor } from '../segment-trie';
+
+const noop = async (): Promise<void> => {};
+
+function buildTrie() {
+  const root = createNode('');
+  const files = createNode('files');
+  root.children.set('files', files);
+  const executor = compileExecutor(noop, []);
+  const entry: HandlerEntry = { handler: noop, middleware: [], executor };
+
+  const idNode = createNode(':id', NodeType.PARAM);
+  idNode.paramName = 'id';
+  idNode.handlers.set('GET', entry);
+  files.paramChild = idNode;
+
+  const wildcard = createNode('*', NodeType.WILDCARD);
+  wildcard.handlers.set('GET', entry);
+  root.wildcardChild = wildcard;
+
+  return { root, entry };
+}
+
+describe('matchNodeIndexed — unpooled fallback (no WalkPool argument)', () => {
+  it('matches a param route without a pool', () => {
+    const { root, entry } = buildTrie();
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+    const result = matchNodeIndexed(root, '/files/42', 1, bindNames, bindValues, 'GET', true);
+    expect(result).toBe(entry);
+    expect(bindNames).toEqual(['id']);
+    expect(bindValues).toEqual(['42']);
+  });
+
+  it('returns the empty-segment terminal handler on a bare trailing slash', () => {
+    const root = createNode('');
+    const executor = compileExecutor(noop, []);
+    const entry: HandlerEntry = { handler: noop, middleware: [], executor };
+    root.handlers.set('GET', entry);
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+    // Position 1 on '/' lands on an empty segment at the root itself.
+    const result = matchNodeIndexed(root, '/', 1, bindNames, bindValues, 'GET', true);
+    expect(result).toBe(entry);
+  });
+
+  it('backtracks from a failed param branch to a wildcard without a pool', () => {
+    const { root, entry } = buildTrie();
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+    // No 'files' segment here — falls through directly to the root's own wildcard.
+    const result = matchNodeIndexed(root, '/anything/here', 1, bindNames, bindValues, 'GET', true);
+    expect(result).toBe(entry);
+    expect(bindNames).toEqual(['*']);
+    expect(bindValues).toEqual(['anything/here']);
+  });
+
+  it('returns null cleanly on a miss without a pool', () => {
+    const root = createNode('');
+    const bindNames: string[] = [];
+    const bindValues: string[] = [];
+    const result = matchNodeIndexed(root, '/nope', 1, bindNames, bindValues, 'GET', true);
+    expect(result).toBeNull();
+    expect(bindNames).toEqual([]);
+    expect(bindValues).toEqual([]);
+  });
+});

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

@@ -0,0 +1,64 @@
+/**
+ * @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 () => {};
+
+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-prenormalized.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @nextrush/router - F-10 preNormalized fast-path
+ *
+ * Pins the fix for F-10 (reconciliation report, Week 2): on the real HTTP
+ * dispatch path (`Router.routes()` -> `createRoutesMiddleware`), the request
+ * path is already canonicalized via `canonicalizePath()` before `match()` is
+ * ever called, so `matchRoute`'s own independent fold+collapse re-derivation
+ * (HP-12's `caseStable`/`isProvablyLowerAscii` decision) is pure repeated
+ * work on that path. `resolveMatch`/`matchRoute` gain a `preNormalized`
+ * parameter (default `false`) that, when `true`, trusts the input as already
+ * canonical and skips the fold+collapse re-derivation entirely. `Router.
+ * match()` — the public two-argument method used by tests and direct API
+ * callers, none of which canonicalize first — is unaffected: it still omits
+ * the argument and gets today's behavior exactly.
+ *
+ * Note: this test intentionally does not assert on path-parameter casing —
+ * a pre-existing, separate behavior (confirmed present before this change,
+ * unrelated to F-10) where `Router.routes()`'s dispatch path already
+ * publishes a case-folded `ctx.path` upstream of `match()` for a
+ * case-insensitive router, regardless of this fix. F-10 is about redundant
+ * computation, not about that param-casing question — out of this change's
+ * scope.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { resolveMatch, type MatchState } from '../match-route';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function buildState(overrides: Partial<MatchState> = {}): MatchState {
+  const router = createRouter();
+  router.get('/users/:id', noop);
+  const state = (router as unknown as { state: MatchState }).state;
+  return { ...state, ...overrides };
+}
+
+describe("F-10 — preNormalized skips matchRoute's redundant fold+collapse re-derivation", () => {
+  it('preNormalized: true skips the fold entirely, even on an uppercase path a fold would normally catch', () => {
+    const state = buildState();
+    const spy = vi.spyOn(String.prototype, 'toLowerCase');
+
+    // A caller passing preNormalized: true is asserting "I already
+    // canonicalized this" — matchRoute must trust that and never re-fold,
+    // even though '/USERS/ID' looks like it would otherwise trigger HP-12's
+    // fold branch. This is the direct, unambiguous proof the flag suppresses
+    // the fold step itself, independent of any caller's actual behavior.
+    resolveMatch(state, true, 'GET', '/USERS/ID', true);
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('preNormalized omitted (default false) behaves identically to today — still folds when needed', () => {
+    const state = buildState();
+    const match = resolveMatch(state, true, 'GET', '/Users/AbC');
+
+    expect(match).not.toBeNull();
+    expect(match?.params).toEqual({ id: 'AbC' });
+  });
+
+  it("Router.routes()'s internal dispatch wires preNormalized: true (no toLowerCase inside matchRoute for an already-canonical path)", async () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const middleware = router.routes();
+
+    const ctx = {
+      path: '/users/abc',
+      originalPath: '/users/abc',
+      method: 'GET',
+      params: {},
+      set: () => undefined,
+    } as unknown as import('@nextrush/types').Context;
+
+    const spy = vi.spyOn(String.prototype, 'toLowerCase');
+    await middleware(ctx, undefined);
+
+    // canonicalizePath's own upstream fold call (for ctx.path) is the only
+    // toLowerCase attributable to this dispatch — matchRoute must add none.
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(1);
+  });
+
+  it("Router.match() — the public two-argument method — is unaffected: still folds its own raw input", () => {
+    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,223 @@
+/**
+ * @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 () => {};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('HP-11 — params expose no Object.prototype (D8)', () => {
+  it('materializes a populated params object whose chain excludes Object.prototype', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const match = router.match('GET', '/users/42');
+    expect(match?.params).toEqual({ id: '42' });
+
+    // The requirement is that `Object.prototype` is unreachable, NOT that the
+    // immediate prototype is literally `null` — params are built on a shared
+    // null-prototype base so V8 keeps them in fast-property mode. Walk the whole
+    // chain: it must terminate, and never pass through `Object.prototype`.
+    let proto: unknown = Object.getPrototypeOf(match?.params);
+    let hops = 0;
+    while (proto !== null) {
+      expect(proto).not.toBe(Object.prototype);
+      proto = Object.getPrototypeOf(proto as object);
+      expect(++hops).toBeLessThan(10);
+    }
+    expect(match?.params instanceof Object).toBe(false);
+  });
+
+  it('keeps the params container in V8 fast-property mode', () => {
+    // %HasFastProperties needs --allow-natives-syntax, which vitest's threads
+    // pool cannot enable; the enforced gate is
+    // apps/benchmark/scripts/alloc/params-shape-gate.mjs. This asserts the
+    // structural precondition that gate depends on: params derive from a shared
+    // base object, not from `null`.
+    const router = createRouter();
+    router.get('/a/:x', noop);
+    router.get('/b/:y', noop);
+
+    const first = Object.getPrototypeOf(router.match('GET', '/a/1')?.params);
+    const second = Object.getPrototypeOf(router.match('GET', '/b/2')?.params);
+    expect(first).not.toBeNull();
+    expect(first).toBe(second);
+    expect(Object.getPrototypeOf(first as object)).toBeNull();
+    expect(Object.keys(first as object)).toHaveLength(0);
+  });
+
+  it('behaves identically to a plain object under every enumeration path', () => {
+    const router = createRouter();
+    router.get('/u/:id/:tab', noop);
+    const params = router.match('GET', '/u/42/profile')?.params as Record<string, string>;
+
+    expect(JSON.stringify(params)).toBe('{"id":"42","tab":"profile"}');
+    expect({ ...params }).toEqual({ id: '42', tab: 'profile' });
+    expect(Object.keys(params)).toEqual(['id', 'tab']);
+    expect(Object.entries(params)).toEqual([
+      ['id', '42'],
+      ['tab', 'profile'],
+    ]);
+    const seen: string[] = [];
+    for (const k in params) seen.push(k);
+    expect(seen).toEqual(['id', 'tab']);
+    expect(structuredClone(params)).toEqual({ id: '42', tab: 'profile' });
+    expect(Object.assign({}, params)).toEqual({ id: '42', tab: 'profile' });
+  });
+
+  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');
+    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();
+  });
+});

package/src/__tests__/match-single-alloc.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @nextrush/router - HP-10 single-allocation contract
+ *
+ * Pins design.md D1: a matched request produces ONE `RouteMatch` object with
+ * `middleware` attached, rather than a `matchRoute` result later wrapped by
+ * `resolveMatch`. Asserted at the `matchRoute` boundary — `matchRoute` now
+ * returns the full `RouteMatch` shape (incl. `middleware === routerMiddleware`)
+ * for both the static-map fast path and a param walk — plus at the public
+ * `Router.match()` boundary (shape unchanged, middleware attached once).
+ *
+ * The "exactly one object" claim itself is proven by the allocation micro-bench
+ * (`bench:alloc:router`); this file pins the observable single-object contract.
+ */
+
+import type { Middleware, RouteHandler } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { matchRoute } from '../match-route';
+import { compileExecutor, createNode, NodeType, type HandlerEntry, type StaticRouteMap } from '../segment-trie';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {};
+
+describe('HP-10 — single RouteMatch allocation', () => {
+  it('matchRoute attaches routerMiddleware to its own returned object (param walk)', () => {
+    const root = createNode('');
+    const users = createNode('users');
+    root.children.set('users', users);
+    const idNode = createNode(':id', NodeType.PARAM);
+    idNode.paramName = 'id';
+    users.paramChild = idNode;
+    const executor = compileExecutor(noop, []);
+    idNode.handlers.set('GET', { handler: noop, middleware: [], executor });
+
+    const routerMiddleware: Middleware[] = [async (_ctx, next) => next?.()];
+    const match = matchRoute(
+      'GET',
+      '/users/42',
+      root,
+      new Map() as StaticRouteMap,
+      true,
+      false,
+      false,
+      true,
+      routerMiddleware
+    );
+
+    expect(match).not.toBeNull();
+    expect(match?.handler).toBe(noop);
+    expect(match?.executor).toBe(executor);
+    expect(match?.params).toEqual({ id: '42' });
+    // The single-object contract: middleware lives on matchRoute's own return.
+    expect(match?.middleware).toBe(routerMiddleware);
+  });
+
+  it('matchRoute attaches routerMiddleware on the static fast path too', () => {
+    const root = createNode('');
+    const executor = compileExecutor(noop, []);
+    const staticRoutes: StaticRouteMap = new Map([
+      ['GET', new Map<string, HandlerEntry>([['/s', { handler: noop, middleware: [], executor }]])],
+    ]);
+    const routerMiddleware: Middleware[] = [async (_ctx, next) => next?.()];
+
+    const match = matchRoute('GET', '/s', root, staticRoutes, false, false, false, true, routerMiddleware);
+
+    expect(match?.handler).toBe(noop);
+    expect(match?.middleware).toBe(routerMiddleware);
+  });
+
+  it('Router.match attaches the SAME routerMiddleware array on every match (attached once, not rebuilt)', () => {
+    const mw: Middleware = async (_ctx, next) => next?.();
+    const router = createRouter();
+    router.use(mw);
+    router.get('/x', noop);
+    router.get('/y/:id', noop);
+
+    const m1 = router.match('GET', '/x');
+    const m2 = router.match('GET', '/y/7');
+
+    expect(m1?.middleware).toBe(m2?.middleware);
+    expect(m1?.middleware).toContain(mw);
+  });
+});

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

@@ -0,0 +1,103 @@
+/**
+ * @nextrush/router - reused walk-frame pool safety (`reduce-router-match-allocations`)
+ *
+ * `matchNodeIndexed`'s `WalkFrame[]` stack and `matchRoute`'s `bindNames`/
+ * `bindValues` arrays are pooled per-router-instance to avoid a fresh
+ * allocation on every call (F-02). Pinned here, per the new `router`
+ * capability requirement ("Reused internal walk state is never shared across
+ * concurrent in-flight matches"): pooling must never let one match observe or
+ * corrupt another's in-progress walk, and the walk must stay fully
+ * synchronous end-to-end for that guarantee to hold.
+ *
+ * `match-safety.test.ts`'s existing "concurrency isolation (D10)" describe
+ * block already proves the returned `params` object is never shared across
+ * matches — that stays true unchanged by this pool, since `params` is still
+ * materialized fresh via `Object.create(null)` regardless of pooling. This
+ * file adds the pool-specific contract the existing suite doesn't cover:
+ * sequential reuse safety and synchronous-only execution.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { createRouter } from '../router';
+
+const noop: RouteHandler = async () => {};
+
+describe('reused walk state — sequential matches reuse pooled scratch safely', () => {
+  it('a second match on the same router is unaffected by the first match’s path or params', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    router.get('/orgs/:orgId/teams/:teamId', noop);
+
+    const first = router.match('GET', '/orgs/42/teams/7');
+    const second = router.match('GET', '/users/99');
+
+    expect(first?.params).toEqual({ orgId: '42', teamId: '7' });
+    expect(second?.params).toEqual({ id: '99' });
+  });
+
+  it('a miss followed by a hit on the same router produces a clean, uncontaminated result', () => {
+    const router = createRouter();
+    router.get('/a/:x/c', noop);
+    router.get('/a/b/d', noop);
+
+    const miss = router.match('GET', '/a/zz/zz');
+    const hit = router.match('GET', '/a/b/c');
+
+    expect(miss).toBeNull();
+    expect(hit?.params).toEqual({ x: 'b' });
+  });
+
+  it('many interleaved matches at varying depth never bleed state into each other', () => {
+    const router = createRouter();
+    router.get('/x/:a', noop);
+    router.get('/y/:a/:b/:c', noop);
+    router.get('/z', noop);
+
+    const results = Array.from({ length: 500 }, (_, i) => {
+      const variant = i % 3;
+      if (variant === 0) return router.match('GET', `/x/v${i}`);
+      if (variant === 1) return router.match('GET', `/y/p${i}/q${i}/r${i}`);
+      return router.match('GET', '/z');
+    });
+
+    results.forEach((m, i) => {
+      const variant = i % 3;
+      if (variant === 0) expect(m?.params).toEqual({ a: `v${i}` });
+      else if (variant === 1) expect(m?.params).toEqual({ a: `p${i}`, b: `q${i}`, c: `r${i}` });
+      else expect(m).not.toBeNull();
+    });
+  });
+});
+
+describe('reused walk state — the walk never suspends mid-frame', () => {
+  it('router.match returns synchronously (never a Promise) for a hit', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const result = router.match('GET', '/users/1');
+    expect(result).not.toBeInstanceOf(Promise);
+  });
+
+  it('router.match returns synchronously (never a Promise) for a miss', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+    const result = router.match('GET', '/nope');
+    expect(result).not.toBeInstanceOf(Promise);
+  });
+
+  it('a deep param match completes entirely within one synchronous call (no microtask boundary)', () => {
+    const router = createRouter();
+    router.get('/' + Array.from({ length: 50 }, () => ':p').join('/'), noop);
+    const path = '/' + Array.from({ length: 50 }, (_, i) => `x${i}`).join('/');
+
+    let sawMicrotask = false;
+    queueMicrotask(() => {
+      sawMicrotask = true;
+    });
+    const result = router.match('GET', path);
+    // If the walk had suspended on a promise, the queued microtask above
+    // would have had a chance to run before match() returned.
+    expect(sawMicrotask).toBe(false);
+    expect(result).not.toBeNull();
+  });
+});