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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextrush/router",
-  "version": "4.0.0-beta.0",
+  "version": "4.0.0-beta.1",
   "description": "High-performance segment trie router for NextRush",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,15 +18,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@nextrush/types": "4.0.0-beta.0"
+    "@nextrush/types": "4.0.0-beta.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@nextrush/core": "4.0.0-beta.0"
+    "@nextrush/core": "4.0.0-beta.1"
   },
   "peerDependencies": {
-    "@nextrush/core": "4.0.0-beta.0"
+    "@nextrush/core": "4.0.0-beta.1"
   },
   "peerDependenciesMeta": {
     "@nextrush/core": {

package/src/__tests__/allowed-methods.test.ts

@@ -93,7 +93,7 @@ describe('allowedMethods() middleware — end-to-end characterization', () => {
     await middleware(ctx, async () => {});
 
     expect(ctx.status).toBe(200);
-    expect(ctx.set).toHaveBeenCalledWith('Allow', 'GET');
+    expect(ctx.set).toHaveBeenCalledWith('Allow', 'GET, HEAD');
   });
 
   it('resolves a wildcard route via findNode (wildcardChild branch)', async () => {
@@ -104,7 +104,7 @@ describe('allowedMethods() middleware — end-to-end characterization', () => {
     await middleware(ctx, async () => {});
 
     expect(ctx.status).toBe(200);
-    expect(ctx.set).toHaveBeenCalledWith('Allow', 'GET');
+    expect(ctx.set).toHaveBeenCalledWith('Allow', 'GET, HEAD');
   });
 
   it('resolves a static-child branch deeper than one segment (findNode recursion)', async () => {

package/src/__tests__/audit-fixes.test.ts

@@ -9,10 +9,6 @@ import type { Context } from '@nextrush/types';
 import { describe, expect, it, vi } from 'vitest';
 import { createRouter } from '../router';
 
-// ---------------------------------------------------------------------------
-// RT-1 — reset() must also clear routeDefinitions (getRoutes introspection)
-// ---------------------------------------------------------------------------
-
 describe('RT-1: reset() clears the introspection registry', () => {
   it('getRoutes() is empty after reset()', () => {
     const router = createRouter();
@@ -25,10 +21,6 @@ describe('RT-1: reset() clears the introspection registry', () => {
   });
 });
 
-// ---------------------------------------------------------------------------
-// RT-5 — conflicting param names at the same position must throw, not warn
-// ---------------------------------------------------------------------------
-
 describe('RT-5: param-name conflict throws at registration', () => {
   it('throws when the same position uses two different param names', () => {
     const router = createRouter();
@@ -43,10 +35,6 @@ describe('RT-5: param-name conflict throws at registration', () => {
   });
 });
 
-// ---------------------------------------------------------------------------
-// RT-7 — routes() called twice must not seal router middleware twice
-// ---------------------------------------------------------------------------
-
 describe('RT-7: routes() is idempotent w.r.t. router middleware sealing', () => {
   it('runs router-level middleware exactly once even if routes() is called twice', async () => {
     const router = createRouter();

package/src/__tests__/canonical-path-security.test.ts

@@ -0,0 +1,198 @@
+/**
+ * @nextrush/router - SEC-02 / SEC-09 canonical-path security regression suite
+ *
+ * RED tests (tasks 3.1-3.3) for RFC-029: the router folds case and collapses
+ * structure for its own lookup, but never publishes that decision, and never
+ * rejects a dot segment. A path-based policy comparing raw `ctx.path` (the
+ * idiomatic prefix-guard pattern shown in this framework's own README) sees a
+ * different string than the one the router matched on.
+ *
+ * @see docs/RFC/request-data/029-canonical-request-path.md
+ */
+
+import type { Context, RouteHandler } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, Router } from '../router';
+
+function createMockContext(overrides: Partial<Context> = {}): Context {
+  return {
+    method: 'GET',
+    path: '/',
+    params: {},
+    query: {},
+    body: undefined,
+    headers: {},
+    status: 200,
+    state: {},
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    next: vi.fn(),
+    raw: {
+      req: {} as never,
+      res: {} as never,
+    },
+    ...overrides,
+  } as Context;
+}
+
+describe('SEC-02: case-fold path-prefix authorization bypass (P1)', () => {
+  let router: Router;
+  let handler: RouteHandler;
+
+  beforeEach(() => {
+    router = createRouter();
+    handler = vi.fn();
+    router.get('/admin/users', handler);
+  });
+
+  it('3.1: dispatches a mixed-case request while a naive raw-ctx.path prefix guard never fires', () => {
+    // The exact PoC from report/security-review.md SEC-02: a policy comparing
+    // ctx.path.startsWith('/admin') against the RAW request target, guarding a
+    // route the router matches after folding.
+    const rawPath = '/ADMIN/users';
+    const guardWouldFire = rawPath.startsWith('/admin');
+
+    const match = router.match('GET', rawPath);
+
+    expect(guardWouldFire).toBe(false); // the guard never runs
+    expect(match).not.toBeNull(); // the router dispatches anyway
+    expect(match?.handler).toBe(handler);
+  });
+
+  it('3.1: a trailing-slash variant also dispatches while failing a naive equality guard', () => {
+    const rawPath = '/admin/users/';
+    const guardWouldFire = rawPath === '/admin/users';
+
+    const match = router.match('GET', rawPath);
+
+    expect(guardWouldFire).toBe(false);
+    expect(match).not.toBeNull();
+  });
+
+  it('3.1: a repeated-slash variant also dispatches while failing a naive equality guard', () => {
+    const rawPath = '//admin//users';
+    const guardWouldFire = rawPath === '/admin/users';
+
+    const match = router.match('GET', rawPath);
+
+    expect(guardWouldFire).toBe(false);
+    expect(match).not.toBeNull();
+  });
+});
+
+describe('SEC-09: no dot-segment normalization (P2)', () => {
+  let router: Router;
+
+  beforeEach(() => {
+    router = createRouter();
+    router.get('/api/webhooks/handler', vi.fn());
+    router.get('/admin', vi.fn());
+    router.get('/users/:id', vi.fn());
+    router.get('/files/*', vi.fn());
+  });
+
+  it.each([
+    ['/api/webhooks/../admin', 'literal dot segment'],
+    ['/api/./users', 'single-dot segment'],
+    ['/../..', 'leading dot segments past root'],
+  ])(
+    '3.2: %s (%s) is never rejected — it either 404s or resolves past its own directory, both unsafe for a canonical-path contract',
+    (path) => {
+      // TODAY: the router has no dot-segment concept at all — a dot segment is
+      // just an opaque path component. This test documents the RED state: no
+      // 400 is ever produced, because nothing in matching.ts/match-route.ts
+      // inspects segments for `.`/`..`. Once RFC-029 P0 lands, dot-segment
+      // paths must be rejected with 400 before reaching match() at all — this
+      // test's premise (the router matches or 404s, never rejects) must flip.
+      const match = router.match('GET', path);
+
+      // Current behavior: no route happens to be registered at the resolved
+      // literal segments, so this 404s (null) today — proving the absence of
+      // any dot-segment handling, not proving safety. A registered route at
+      // the resolved target would dispatch silently instead.
+      expect(match).toBeNull();
+    }
+  );
+
+  it('3.2: a percent-encoded double-dot segment is likewise passed through as an opaque literal segment', () => {
+    // %2e%2e is never decoded by matchRoute for structural purposes — only
+    // param VALUES are percent-decoded (decodeParam), and only after a param
+    // slot in the trie already matched. A dot segment used for traversal
+    // purposes is a static path segment, so it is compared literally as
+    // `%2e%2e`, which matches nothing today.
+    const match = router.match('GET', '/api/%2e%2e/admin');
+    expect(match).toBeNull();
+  });
+
+  it('3.2: a two-character segment starting with a dot but not a double-dot is not flagged as a traversal segment', () => {
+    router.get('/files/.x', vi.fn());
+    const match = router.match('GET', '/files/.x');
+    expect(match).not.toBeNull();
+  });
+
+  it('3.2: a dot as filename content (not a traversal segment) is accepted and dispatches normally', () => {
+    router.get('/files/archive.tar.gz', vi.fn());
+    const match = router.match('GET', '/files/archive.tar.gz');
+    expect(match).not.toBeNull();
+  });
+});
+
+describe('3.3: published-path contract (ctx.path / ctx.originalPath)', () => {
+  it('3.3: the router publishes the canonical path onto ctx.path and preserves the raw target on ctx.originalPath', async () => {
+    const router = createRouter();
+    let seenPath = '';
+    let seenOriginal: string | undefined;
+    router.get('/admin/users', (ctx) => {
+      seenPath = ctx.path;
+      seenOriginal = ctx.originalPath;
+    });
+
+    const ctx = createMockContext({ path: '/ADMIN/users?x=1' });
+    const middleware = router.routes();
+    await middleware(ctx, async () => {});
+
+    expect(seenPath).toBe('/admin/users');
+    expect(seenOriginal).toBe('/ADMIN/users?x=1');
+    expect(seenPath).not.toContain('?');
+  });
+
+  it('3.3: both ctx.path and ctx.originalPath are populated on a 404 (no route matched)', async () => {
+    const router = createRouter();
+    router.get('/users', () => undefined);
+
+    const ctx = createMockContext({ path: '/USERS/999' });
+    const middleware = router.routes();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(404);
+    expect(ctx.path).toBe('/users/999');
+    expect((ctx as unknown as { originalPath?: string }).originalPath).toBe('/USERS/999');
+  });
+
+  it('a mocked ctx not yet touched by router dispatch has no originalPath — optional field, absent by default', () => {
+    const ctx = createMockContext({ path: '/ADMIN/users' });
+    expect((ctx as unknown as { originalPath?: string }).originalPath).toBeUndefined();
+  });
+
+  it('3.3: a dot-segment request rejected by dispatch sets 400 and still populates ctx.originalPath', async () => {
+    const router = createRouter();
+    router.get('/admin', vi.fn());
+
+    const ctx = createMockContext({ path: '/../admin' });
+    const middleware = router.routes();
+    let nextCalled = false;
+    await middleware(ctx, async () => {
+      nextCalled = true;
+    });
+
+    expect(ctx.status).toBe(400);
+    expect((ctx as unknown as { originalPath?: string }).originalPath).toBe('/../admin');
+    // A dot-segment rejection stops the chain outright — it never falls
+    // through to a 404/allowedMethods handler the way a plain miss does.
+    expect(nextCalled).toBe(false);
+  });
+});

package/src/__tests__/canonicalize-memo.test.ts

@@ -0,0 +1,108 @@
+/**
+ * @nextrush/router - Canonicalization memo correctness
+ *
+ * `canonicalizePath` memoizes its most recent result, and `matchesMountPrefix`
+ * memoizes the canonical form of its (registration-fixed) prefix. Both exist to
+ * remove the O(mounts) canonicalization cost a request paid falling through
+ * prefix mounts — measured at ~557 ns per mounted router before, ~190 ns after.
+ *
+ * A memo is only sound if it can never return an answer that differs from
+ * recomputing. The hazard is options: `caseSensitive` and `strict` change the
+ * result for the same input string, and two routers with different options can
+ * be mounted in the same application. These tests pin that.
+ *
+ * @see reports/investigations/post-audit-invariant-erosion-review.md F-1
+ */
+
+import { describe, expect, it } from 'vitest';
+import { canonicalizePath } from '../canonicalize';
+import { createRouter } from '../router';
+
+describe('canonicalizePath memo cannot leak across option combinations', () => {
+  it('returns the folded path for caseSensitive=false and the raw path for true', () => {
+    // Same input, alternating options — a memo keyed only on the string would
+    // return the first answer for both.
+    for (let i = 0; i < 3; i++) {
+      expect(canonicalizePath('/Users/List', false, false).path).toBe('/users/list');
+      expect(canonicalizePath('/Users/List', true, false).path).toBe('/Users/List');
+    }
+  });
+
+  it('respects strict for the same input string', () => {
+    for (let i = 0; i < 3; i++) {
+      expect(canonicalizePath('/users/', false, false).path).toBe('/users');
+      expect(canonicalizePath('/users/', false, true).path).toBe('/users/');
+    }
+  });
+
+  it('still rejects a dot segment after a non-rejected call for another path', () => {
+    expect(canonicalizePath('/safe/path', false, false).rejected).toBe(false);
+    expect(canonicalizePath('/a/../b', false, false).rejected).toBe(true);
+    expect(canonicalizePath('/safe/path', false, false).rejected).toBe(false);
+    expect(canonicalizePath('/a/./b', false, false).rejected).toBe(true);
+  });
+
+  it('is stable under repetition and equal to a first-call result', () => {
+    const first = canonicalizePath('/A//b/', false, false);
+    canonicalizePath('/something/else', true, true);
+    const again = canonicalizePath('/A//b/', false, false);
+    expect(again.path).toBe(first.path);
+    expect(again.rejected).toBe(first.rejected);
+    expect(again.path).toBe('/a/b');
+  });
+
+  it('strips the query string consistently whether memoized or not', () => {
+    expect(canonicalizePath('/users?a=1', false, false).path).toBe('/users');
+    expect(canonicalizePath('/users?a=1', false, false).path).toBe('/users');
+    expect(canonicalizePath('/users?b=2', false, false).path).toBe('/users');
+  });
+});
+
+describe('matchesMountPrefix prefix memo', () => {
+  it('returns the correct remainder repeatedly for one prefix', () => {
+    const router = createRouter();
+    for (let i = 0; i < 3; i++) {
+      expect(router.matchesMountPrefix('/api/v1/users/42', '/api/v1')).toBe('/users/42');
+    }
+  });
+
+  it('handles a router tested against two different prefixes (memo miss path)', () => {
+    const router = createRouter();
+    expect(router.matchesMountPrefix('/api/users', '/api')).toBe('/users');
+    expect(router.matchesMountPrefix('/admin/users', '/admin')).toBe('/users');
+    expect(router.matchesMountPrefix('/api/users', '/api')).toBe('/users');
+    // A prefix that does not match must still miss after the memo warmed.
+    expect(router.matchesMountPrefix('/api/users', '/admin')).toBeUndefined();
+  });
+
+  it('folds the prefix per the router own caseSensitive option', () => {
+    const insensitive = createRouter();
+    expect(insensitive.matchesMountPrefix('/ADMIN/Users', '/admin')).toBe('/users');
+
+    const sensitive = createRouter({ caseSensitive: true });
+    expect(sensitive.matchesMountPrefix('/ADMIN/Users', '/admin')).toBeUndefined();
+    expect(sensitive.matchesMountPrefix('/admin/Users', '/admin')).toBe('/Users');
+  });
+
+  it('enforces the segment boundary rather than a bare string prefix', () => {
+    const router = createRouter();
+    expect(router.matchesMountPrefix('/apifoo/bar', '/api')).toBeUndefined();
+    expect(router.matchesMountPrefix('/api/bar', '/api')).toBe('/bar');
+    expect(router.matchesMountPrefix('/api', '/api')).toBe('/');
+  });
+
+  it('rejects a dot-segment path', () => {
+    const router = createRouter();
+    expect(router.matchesMountPrefix('/api/../secret', '/api')).toBeUndefined();
+  });
+
+  it('gives two routers with different options independent answers', () => {
+    const a = createRouter({ caseSensitive: false });
+    const b = createRouter({ caseSensitive: true });
+    // Interleaved, so a shared memo keyed only on the string would cross over.
+    for (let i = 0; i < 3; i++) {
+      expect(a.matchesMountPrefix('/API/x', '/api')).toBe('/x');
+      expect(b.matchesMountPrefix('/API/x', '/api')).toBeUndefined();
+    }
+  });
+});

package/src/__tests__/dispatch-deasync.test.ts

@@ -68,10 +68,6 @@ const run = (router: Router, ctx: Context): Promise<void> =>
 /** Settle a promise into its resolution or rejection reason without throwing. */
 const settle = (p: Promise<unknown>): Promise<unknown> => p.then((v) => v, (e) => e);
 
-// ===========================================================================
-// §2.1 — no extra async frame (structural identity probes, RED before change)
-// ===========================================================================
-
 describe('NF-1 §2.1: dispatch forwards without an extra async frame', () => {
   it('createRoutesMiddleware returns the executor promise directly (identity)', () => {
     const sentinel = Promise.resolve();
@@ -113,10 +109,6 @@ describe('NF-1 §2.1: dispatch forwards without an extra async frame', () => {
   });
 });
 
-// ===========================================================================
-// §2.2–§2.5 — error / return-shape propagation (behavior contracts)
-// ===========================================================================
-
 describe('NF-1 §2.2: a synchronous throw becomes a rejected promise', () => {
   it('the executor never throws synchronously out of dispatch', async () => {
     const exec = compileExecutor((() => {
@@ -196,10 +188,6 @@ describe('NF-1 §2.5: a non-Error throw is wrapped as Error(String(thrown))', ()
   });
 });
 
-// ===========================================================================
-// §2.6 — miss → 404 → next() fall-through (allowedMethods 405)
-// ===========================================================================
-
 describe('NF-1 §2.6: a miss sets 404 and forwards next()', () => {
   it('a known-path/unregistered-method miss becomes 405 with Allow via allowedMethods', async () => {
     const router = createRouter();
@@ -223,10 +211,6 @@ describe('NF-1 §2.6: a miss sets 404 and forwards next()', () => {
   });
 });
 
-// ===========================================================================
-// §2.7 — load-bearing setNext(NOOP_NEXT) chain termination (NF-4a KEPT)
-// ===========================================================================
-
 describe('NF-1 §2.7: setNext(NOOP_NEXT) terminates the chain at the handler', () => {
   it('a route handler calling ctx.next() does NOT advance into app middleware after the router', async () => {
     const router = createRouter();
@@ -252,10 +236,6 @@ describe('NF-1 §2.7: setNext(NOOP_NEXT) terminates the chain at the handler', (
   });
 });
 
-// ===========================================================================
-// §2.8 — the len >= 1 per-route middleware chain is unchanged
-// ===========================================================================
-
 describe('NF-1 §2.8: the len >= 1 executor path is unchanged', () => {
   it('preserves onion ordering across a 5-layer ctx.next() chain', async () => {
     const router = createRouter();

package/src/__tests__/find-node-differential.test.ts

@@ -27,9 +27,7 @@ import { normalizePathForMatch } from '../matching';
 import { addRoute, type RegistrationState } from '../registration';
 import { createNode, type TrieNode } from '../segment-trie';
 
-const noop: RouteHandler = async () => {
-  /* no-op */
-};
+const noop: RouteHandler = async () => {};
 
 /** Build a bare trie root from a route list, mirroring how `Router` inserts. */
 function buildRoot(
@@ -42,6 +40,7 @@ function buildRoot(
     caseSensitive,
     staticRoutes: new Map(),
     routeDefinitions: [],
+    maxDepth: 0,
   };
   for (const [method, path] of routes) {
     addRoute(method, path, [noop], [], state);
@@ -166,8 +165,9 @@ describe('HP-17 — findNode iterative rewrite: differential parity with recursi
       ['GET', '/p/:id'],
       ['GET', '/p/*'],
     ]);
-    // Static wins.
-    expect(findAllowedMethods('/p/me', r, false, false)).toEqual(['GET']);
+    // Static wins. HEAD is present because a GET registration derives it
+    // (RFC 9110 §9.3.2) — the assertion here is about precedence, not the method set.
+    expect(findAllowedMethods('/p/me', r, false, false)).toEqual(['GET', 'HEAD']);
     // Param wins over wildcard for a single leftover segment.
     const paramNode = prodNode('/p/other', r, false, false);
     expect(paramNode).toBe(refNode('/p/other', r, false, false));
@@ -203,7 +203,7 @@ describe('HP-17 — deep-path 405/OPTIONS safety (RED before the iterative rewri
     const root = buildRoot([['GET', '/' + Array.from({ length: depth }, () => ':p').join('/')]]);
     const deepPath = '/' + Array.from({ length: depth }, (_, i) => `x${i}`).join('/');
     expect(() => findAllowedMethods(deepPath, root, false, false)).not.toThrow();
-    expect(findAllowedMethods(deepPath, root, false, false)).toEqual(['GET']);
+    expect(findAllowedMethods(deepPath, root, false, false)).toEqual(['GET', 'HEAD']);
   });
 
   it('misses a deep-but-overshooting path without a stack overflow', () => {

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();
+  });
+});