@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/__tests__/head-auto-registration.test.ts

@@ -0,0 +1,197 @@
+/**
+ * @nextrush/router - HEAD-on-GET auto-registration (RFC 9110 §9.3.2)
+ *
+ * A `GET` route must also answer `HEAD`. Fastify, Express, Koa and Hono all do
+ * this; before this suite NextRush returned 404 for `HEAD` on every `GET` route,
+ * making conditional-request revalidation, CDN HEAD probes and HEAD-configured
+ * health checks fail.
+ *
+ * @see reports/investigations/2026-07-31-measured-floor-params-compliance/04-http-compliance-head.md
+ */
+
+import type { HttpMethod } from '@nextrush/types';
+import { describe, expect, it } from 'vitest';
+import { createRouter, Router } from '../router';
+
+const noop = (): void => {};
+
+describe('HEAD auto-registration for GET routes', () => {
+  it('matches HEAD on a static GET route', () => {
+    const router = createRouter();
+    router.get('/health', noop);
+
+    expect(router.match('GET', '/health')).not.toBeNull();
+    expect(router.match('HEAD', '/health')).not.toBeNull();
+  });
+
+  it('matches HEAD on a param GET route and extracts the same params', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+
+    const get = router.match('GET', '/users/42');
+    const head = router.match('HEAD', '/users/42');
+
+    expect(head).not.toBeNull();
+    expect(head?.params).toEqual({ id: '42' });
+    expect(head?.params).toEqual(get?.params);
+  });
+
+  it('matches HEAD on a wildcard GET route', () => {
+    const router = createRouter();
+    router.get('/static/*', noop);
+
+    const head = router.match('HEAD', '/static/a/b.txt');
+    expect(head).not.toBeNull();
+    expect(head?.params['*']).toBe('a/b.txt');
+  });
+
+  it('reuses the GET handler and executor rather than compiling a second one', () => {
+    const router = createRouter();
+    router.get('/x', noop);
+
+    const get = router.match('GET', '/x');
+    const head = router.match('HEAD', '/x');
+
+    expect(head?.handler).toBe(get?.handler);
+    expect(head?.executor).toBe(get?.executor);
+  });
+
+  it('does not auto-register HEAD for non-GET methods', () => {
+    const router = createRouter();
+    router.post('/submit', noop);
+    router.put('/replace', noop);
+
+    expect(router.match('HEAD', '/submit')).toBeNull();
+    expect(router.match('HEAD', '/replace')).toBeNull();
+  });
+
+  describe('an explicit router.head() always wins', () => {
+    it('when registered AFTER the GET route', () => {
+      const router = createRouter();
+      const getHandler = (): void => {};
+      const headHandler = (): void => {};
+
+      router.get('/x', getHandler);
+      expect(() => router.head('/x', headHandler)).not.toThrow();
+
+      expect(router.match('HEAD', '/x')?.handler).toBe(headHandler);
+      expect(router.match('GET', '/x')?.handler).toBe(getHandler);
+    });
+
+    it('when registered BEFORE the GET route', () => {
+      const router = createRouter();
+      const getHandler = (): void => {};
+      const headHandler = (): void => {};
+
+      router.head('/x', headHandler);
+      expect(() => router.get('/x', getHandler)).not.toThrow();
+
+      expect(router.match('HEAD', '/x')?.handler).toBe(headHandler);
+      expect(router.match('GET', '/x')?.handler).toBe(getHandler);
+    });
+  });
+
+  it('still rejects a genuine duplicate HEAD registration', () => {
+    const router = createRouter();
+    router.head('/x', noop);
+    expect(() => router.head('/x', noop)).toThrow(/already registered/);
+  });
+
+  it('still rejects a genuine duplicate GET registration', () => {
+    const router = createRouter();
+    router.get('/x', noop);
+    expect(() => router.get('/x', noop)).toThrow(/already registered/);
+  });
+
+  it('does not emit a duplicate introspection row for the derived HEAD', () => {
+    const router = createRouter();
+    router.get('/users/:id', noop);
+
+    const rows = router.getRoutes();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.method).toBe('GET');
+    expect(rows.some((r) => r.method === 'HEAD')).toBe(false);
+  });
+
+  it('emits exactly one introspection row when HEAD is registered explicitly', () => {
+    const router = createRouter();
+    router.get('/x', noop);
+    router.head('/x', noop);
+
+    const rows = router.getRoutes();
+    expect(rows.filter((r) => r.method === 'HEAD')).toHaveLength(1);
+    expect(rows.filter((r) => r.method === 'GET')).toHaveLength(1);
+  });
+
+  it('leaves router.all() working (its own HEAD registration must not conflict)', () => {
+    const router = createRouter();
+    expect(() => router.all('/any', noop)).not.toThrow();
+
+    const methods: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+    for (const method of methods) {
+      expect(router.match(method, '/any'), `expected ${method} to match`).not.toBeNull();
+    }
+    // .all() still consolidates to a single introspection row
+    expect(router.getRoutes()).toHaveLength(1);
+  });
+
+  it('leaves redirect() working (it registers GET and HEAD itself)', () => {
+    const router = createRouter();
+    expect(() => router.redirect('/old', '/new')).not.toThrow();
+
+    expect(router.match('GET', '/old')).not.toBeNull();
+    expect(router.match('HEAD', '/old')).not.toBeNull();
+  });
+
+  it('survives a mounted sub-router without a route conflict or duplicate rows', () => {
+    const sub = createRouter();
+    sub.get('/list', noop);
+    sub.get('/:id', noop);
+
+    const parent = createRouter();
+    expect(() => parent.mount('/users', sub)).not.toThrow();
+
+    expect(parent.match('GET', '/users/list')).not.toBeNull();
+    expect(parent.match('HEAD', '/users/list')).not.toBeNull();
+    expect(parent.match('HEAD', '/users/7')).not.toBeNull();
+
+    // one row per copied GET route, no HEAD rows
+    const rows = parent.getRoutes();
+    expect(rows.filter((r) => r.method === 'HEAD')).toHaveLength(0);
+    expect(rows.filter((r) => r.method === 'GET')).toHaveLength(2);
+  });
+
+  it('reports HEAD in the Allow set for a GET-only route', () => {
+    const router = createRouter();
+    router.get('/only-get', noop);
+
+    // allowedMethods() walks the trie; HEAD is now a registered method there.
+    const middleware = router.allowedMethods();
+    expect(typeof middleware).toBe('function');
+
+    // Direct trie assertion via match(), which is the observable contract.
+    expect(router.match('HEAD', '/only-get')).not.toBeNull();
+  });
+
+  it('clears derived HEAD entries on reset()', () => {
+    const router = new Router();
+    router.get('/x', noop);
+    expect(router.match('HEAD', '/x')).not.toBeNull();
+
+    router.reset();
+    expect(router.match('GET', '/x')).toBeNull();
+    expect(router.match('HEAD', '/x')).toBeNull();
+
+    // re-registering after reset must not report a conflict
+    expect(() => router.get('/x', noop)).not.toThrow();
+    expect(router.match('HEAD', '/x')).not.toBeNull();
+  });
+
+  it('honours a case-insensitive static route for HEAD too', () => {
+    const router = createRouter();
+    router.get('/Health', noop);
+
+    expect(router.match('HEAD', '/health')).not.toBeNull();
+    expect(router.match('HEAD', '/HEALTH')).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,314 @@
+/**
+ * @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) => {}) 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');
+    }
+  });
+});