ingenium 0.0.1

package/src/rate-limit/middleware.ts

@@ -0,0 +1,72 @@
+import type { IngeniumContext } from '../context/context.ts'
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import { MemoryStore } from './store.ts'
+import type { RateLimitOptions } from './types.ts'
+
+/** Default key generator — see RateLimitOptions.keyGenerator JSDoc. */
+function defaultKeyGenerator(ctx: IngeniumContext): string {
+  const xff = ctx.headers['x-forwarded-for']
+  if (typeof xff === 'string' && xff.length > 0) {
+    const first = xff.split(',')[0]
+    const trimmed = first?.trim()
+    if (trimmed && trimmed.length > 0) return trimmed
+  }
+  const xri = ctx.headers['x-real-ip']
+  if (typeof xri === 'string' && xri.length > 0) return xri
+  return 'unknown'
+}
+
+/**
+ * Fixed-window rate-limiting middleware. Each key is allowed at most `max`
+ * requests per `windowMs`. Over-limit requests get a `429 Too Many
+ * Requests` response with `Retry-After` and a JSON body.
+ *
+ * Every passing response carries `X-RateLimit-Limit`,
+ * `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix seconds).
+ *
+ * @example
+ *   app.use(rateLimit({ max: 100, windowMs: 60_000 }))
+ *   app.use('/auth', rateLimit({ max: 5, windowMs: 60_000 }))
+ */
+export function rateLimit(opts: RateLimitOptions = {}): IngeniumMiddleware {
+  const windowMs = opts.windowMs ?? 60_000
+  const max = opts.max ?? 100
+  const keyGenerator = opts.keyGenerator ?? defaultKeyGenerator
+  const skip = opts.skip
+  const store = opts.store ?? new MemoryStore()
+
+  if (windowMs <= 0) throw new Error('rateLimit: windowMs must be > 0')
+  if (max <= 0) throw new Error('rateLimit: max must be > 0')
+
+  return async (ctx, next) => {
+    if (skip && skip(ctx)) {
+      return next()
+    }
+
+    const key = keyGenerator(ctx)
+    const { count, resetAt } = await store.hit(key, windowMs)
+
+    const remaining = Math.max(0, max - count)
+    const resetSeconds = Math.ceil(resetAt / 1000)
+
+    ctx.set('x-ratelimit-limit', String(max))
+    ctx.set('x-ratelimit-remaining', String(remaining))
+    ctx.set('x-ratelimit-reset', String(resetSeconds))
+
+    if (count > max) {
+      const retryAfter = Math.max(1, Math.ceil((resetAt - Date.now()) / 1000))
+      ctx.set('retry-after', String(retryAfter))
+      ctx.json(
+        {
+          error: 'Too Many Requests',
+          code: 'RATE_LIMITED',
+          retryAfter,
+        },
+        429,
+      )
+      return
+    }
+
+    return next()
+  }
+}

package/src/rate-limit/store.ts

@@ -0,0 +1,129 @@
+import type { RateLimitStore } from './types.ts'
+
+interface Entry {
+  count: number
+  resetAt: number
+}
+
+/** Default cap on the number of distinct keys held in the in-memory store. */
+const DEFAULT_MAX_ENTRIES = 100_000
+
+export interface MemoryStoreOptions {
+  /**
+   * Hard ceiling on the number of distinct keys retained. When exceeded, the
+   * **least-recently-touched** entry is evicted to make room. Default
+   * `100_000`.
+   *
+   * The cap exists to bound memory under adversarial conditions: an attacker
+   * generating one request per unique IP would otherwise grow the map without
+   * bound. With the cap, the worst case is a fixed memory footprint and
+   * attackers' counters get evicted (which means they bypass rate-limiting
+   * for the exact endpoint they're hammering — a real trade-off, but better
+   * than OOM).
+   *
+   * For genuinely high-cardinality production workloads (millions of distinct
+   * users), prefer a Redis-backed store so eviction isn't required.
+   */
+  maxEntries?: number
+}
+
+/**
+ * In-process fixed-window counter store. Suitable for single-replica
+ * deployments and tests; swap for a Redis-backed store when running
+ * multiple replicas behind a load balancer.
+ *
+ * A periodic sweep removes expired entries every `windowMs` so long-lived
+ * processes don't leak memory across forgotten keys. The sweep timer is
+ * `.unref()`'d, so it never keeps the Node event loop alive.
+ *
+ * The `Map` itself is bounded by `maxEntries` (default 100k). When the cap
+ * is reached, the least-recently-touched entry is evicted before the new
+ * entry is inserted. We rely on the JS `Map` insertion-order guarantee:
+ * delete-then-set on an existing key moves it to the end, so the first
+ * iteration step always returns the genuine LRU. **This is intentional
+ * defense against scanner attacks that would otherwise OOM the process by
+ * generating unique keys.**
+ */
+export class MemoryStore implements RateLimitStore {
+  private readonly map: Map<string, Entry> = new Map()
+  private sweeper: NodeJS.Timeout | null = null
+  private sweepIntervalMs = 0
+  private readonly maxEntries: number
+
+  constructor(opts: MemoryStoreOptions = {}) {
+    this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES
+    if (!Number.isInteger(this.maxEntries) || this.maxEntries < 1) {
+      throw new RangeError(
+        `MemoryStore: maxEntries must be a positive integer, got ${String(opts.maxEntries)}`,
+      )
+    }
+  }
+
+  hit(key: string, windowMs: number): Promise<{ count: number; resetAt: number }> {
+    const now = Date.now()
+    const existing = this.map.get(key)
+
+    let entry: Entry
+    if (!existing || now >= existing.resetAt) {
+      // New (or expired) key — may need to evict before inserting.
+      if (!existing && this.map.size >= this.maxEntries) {
+        // Evict the LRU: Map preserves insertion order, so the first key in
+        // iteration is the oldest-touched (touch = delete+set on every hit).
+        const oldestKey = this.map.keys().next().value
+        if (oldestKey !== undefined) this.map.delete(oldestKey)
+      }
+      entry = { count: 1, resetAt: now + windowMs }
+      // Re-insert order: existing-but-expired keys also need delete+set so
+      // their order moves to the end (preserves LRU semantics).
+      if (existing) this.map.delete(key)
+      this.map.set(key, entry)
+    } else {
+      // Touch — move to end of insertion order so it's NOT the LRU candidate.
+      existing.count += 1
+      entry = existing
+      this.map.delete(key)
+      this.map.set(key, entry)
+    }
+
+    this.ensureSweeper(windowMs)
+    return Promise.resolve({ count: entry.count, resetAt: entry.resetAt })
+  }
+
+  reset(key: string): Promise<void> {
+    this.map.delete(key)
+    return Promise.resolve()
+  }
+
+  /**
+   * Stop the cleanup interval. Safe to call multiple times. Mostly useful
+   * in tests; production usage doesn't need this because the timer is
+   * already unref'd.
+   */
+  destroy(): void {
+    if (this.sweeper) {
+      clearInterval(this.sweeper)
+      this.sweeper = null
+    }
+    this.map.clear()
+  }
+
+  /** @internal Current entry count — exposed for ops/tests. */
+  get size(): number {
+    return this.map.size
+  }
+
+  private ensureSweeper(windowMs: number): void {
+    if (this.sweeper && this.sweepIntervalMs === windowMs) return
+    if (this.sweeper) clearInterval(this.sweeper)
+    this.sweepIntervalMs = windowMs
+    this.sweeper = setInterval(() => this.sweep(), windowMs)
+    if (typeof this.sweeper.unref === 'function') this.sweeper.unref()
+  }
+
+  private sweep(): void {
+    const now = Date.now()
+    for (const [key, entry] of this.map) {
+      if (now >= entry.resetAt) this.map.delete(key)
+    }
+  }
+}

package/src/rate-limit/types.ts

@@ -0,0 +1,60 @@
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * Pluggable backing store for the rate-limit middleware. The default
+ * in-memory implementation is sync internally but exposes a Promise-based
+ * surface so a Redis (or other distributed) store can drop in unchanged.
+ */
+export interface RateLimitStore {
+  /**
+   * Record a hit for `key`. Returns the new count and the unix-millis
+   * timestamp at which the current window expires.
+   *
+   * Implementations MUST roll the window over when `Date.now() >= resetAt`,
+   * resetting the count to 1.
+   */
+  hit(key: string, windowMs: number): Promise<{ count: number; resetAt: number }>
+
+  /** Clear the counter for `key`. Used by tests and by ops tooling. */
+  reset(key: string): Promise<void>
+}
+
+/**
+ * Options for {@link rateLimit}.
+ */
+export interface RateLimitOptions {
+  /**
+   * Window length in milliseconds. Default: `60_000` (one minute).
+   *
+   * Each key is allowed at most `max` requests per window. Counts reset
+   * sharply at window boundaries (fixed-window algorithm).
+   */
+  windowMs?: number
+
+  /** Max requests per `windowMs` per key. Default: `100`. */
+  max?: number
+
+  /**
+   * Build the limiter key for a request. Default uses `X-Forwarded-For`
+   * (first hop), then `X-Real-IP`, then the literal string `'unknown'`.
+   *
+   * **Security**: the default trusts `X-Forwarded-For` blindly. Without
+   * an upstream that strips client-supplied values, this header is
+   * forgeable. Production deployments behind a proxy should validate the
+   * proxy chain or supply a custom `keyGenerator`.
+   */
+  keyGenerator?: (ctx: IngeniumContext) => string
+
+  /**
+   * Skip rate-limiting for a given request. When this returns `true`, no
+   * counter hit is recorded and no `X-RateLimit-*` headers are written.
+   * Default: never skip.
+   */
+  skip?: (ctx: IngeniumContext) => boolean
+
+  /**
+   * Backing store. Default: an in-process {@link MemoryStore}. Swap in a
+   * shared store (Redis etc.) when running multiple replicas.
+   */
+  store?: RateLimitStore
+}

package/src/response/reflect.ts

@@ -0,0 +1,93 @@
+import { Buffer } from 'node:buffer'
+import { Readable } from 'node:stream'
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * Dev-mode gate. Captured ONCE at module load; in production V8 dead-code-
+ * eliminates the branch bodies behind `if (IS_DEV)`. Every dev diagnostic
+ * MUST check this first so it pays nothing on the hot path.
+ */
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
+/**
+ * @internal Once-per-process flag for the fetch-style `Response` warning.
+ * Exposed via `_resetReflectFootgunWarnings()` for tests.
+ */
+let _responseObjectWarned = false
+
+/** @internal Test-only — clear the once-flag for the fetch-Response warning. */
+export function _resetReflectFootgunWarnings(): void {
+  _responseObjectWarned = false
+}
+
+/**
+ * Reflect a handler's return value to the response per the contract:
+ *
+ * | return type            | wire output                       |
+ * |------------------------|-----------------------------------|
+ * | `undefined` / `null`   | 204 (unless ctx wrote)            |
+ * | string starting w/ `<` | 200 text/html                     |
+ * | other string           | 200 text/plain                    |
+ * | `Buffer` / `Uint8Array`| 200 application/octet-stream      |
+ * | `Readable`             | 200 streamed                      |
+ * | any object/array       | 200 application/json              |
+ *
+ * If a `ctx.json/text/html/stream/redirect/send` helper has already been
+ * called, the return value is ignored.
+ */
+export function reflectReturn(ctx: IngeniumContext, value: unknown): void {
+  if (ctx._written) return
+
+  if (value === undefined || value === null) {
+    ctx.status(204)
+    return
+  }
+
+  // Dev-only — catch the common mistake of returning a fetch-style `Response`
+  // object (e.g. `return new Response('hi')`). Ingenium handlers return plain
+  // values; interop with the Fetch Response shape is intentionally not
+  // supported. Warn once, then fall through to the 204 path so the framework
+  // doesn't accidentally JSON-serialize the Response object's enumerable bag.
+  if (IS_DEV && typeof Response !== 'undefined' && value instanceof Response) {
+    if (!_responseObjectWarned) {
+      _responseObjectWarned = true
+      try {
+        process.emitWarning(
+          'Handler returned a fetch-style Response object. Ingenium handlers return plain values or call ctx.json/text/etc. The Response was ignored.',
+          { type: 'IngeniumResponseObjectWarning' },
+        )
+      } catch {
+        // process.emitWarning can throw in unusual runtimes (workers); swallow.
+      }
+    }
+    ctx.status(204)
+    return
+  }
+
+  if (typeof value === 'string') {
+    if (value.length > 0 && value.charCodeAt(0) === 60 /* '<' */) {
+      ctx.html(value)
+    } else {
+      ctx.text(value)
+    }
+    return
+  }
+
+  if (Buffer.isBuffer(value)) {
+    ctx.send(value)
+    return
+  }
+
+  if (value instanceof Uint8Array) {
+    ctx.send(Buffer.from(value))
+    return
+  }
+
+  if (value instanceof Readable) {
+    ctx.stream(value)
+    return
+  }
+
+  // Default: JSON-serialize anything else (objects, arrays, numbers, booleans).
+  ctx.json(value)
+}

package/src/router/router.ts

@@ -0,0 +1,284 @@
+import type { IngeniumHandler, IngeniumMiddleware } from '../middleware/types.ts'
+import type { ExtractParams, HttpMethod } from './types.ts'
+
+/** A journal entry — replayed against the trie when the app composes. */
+export type Registration =
+  | { kind: 'use-global'; mw: IngeniumMiddleware }
+  | { kind: 'use-prefix'; prefix: string; mw: IngeniumMiddleware }
+  | { kind: 'use-router'; prefix: string; router: Router }
+  | {
+      kind: 'route'
+      method: HttpMethod
+      path: string
+      handler: IngeniumHandler
+      /**
+       * Inline middleware passed positionally to `app.get(path, mw1, mw2, handler)`
+       * (and the equivalent declarative-options form on `IngeniumApp`). Spliced into
+       * the composed chain AFTER global + scoped middleware AND BEFORE the handler.
+       * `undefined` for the back-compat single-arg form.
+       */
+      inlineMiddleware?: IngeniumMiddleware[]
+    }
+
+/**
+ * Variadic route-arg shape: zero or more middleware followed by exactly one
+ * handler at the tail. The TypeScript trick `[...IngeniumMiddleware[], IngeniumHandler]`
+ * forces the tail position to be the handler while everything before it is
+ * middleware — preserves Express's `app.get(path, ...mw, handler)` ergonomics.
+ */
+export type RouteArgs<P = Record<string, string>> =
+  | [IngeniumHandler<P>]
+  | [...IngeniumMiddleware[], IngeniumHandler<P>]
+
+/**
+ * A mountable router. Registrations are journaled, not eagerly composed —
+ * mounting via `app.use('/api', router)` replays this journal into the
+ * parent's trie with the prefix prepended.
+ */
+export class Router {
+  /** @internal */ readonly journal: Registration[] = []
+
+  /** Add middleware that runs for every request below this router. */
+  use(mw: IngeniumMiddleware): this
+  /** Mount middleware or a sub-router at a path prefix. */
+  use(prefix: string, mw: IngeniumMiddleware | Router): this
+  use(arg1: string | IngeniumMiddleware, arg2?: IngeniumMiddleware | Router): this {
+    if (typeof arg1 === 'string') {
+      const prefix = normalizePrefix(arg1)
+      if (arg2 instanceof Router) {
+        this.journal.push({ kind: 'use-router', prefix, router: arg2 })
+      } else if (typeof arg2 === 'function') {
+        this.journal.push({ kind: 'use-prefix', prefix, mw: arg2 })
+      } else {
+        throw new TypeError(`Router.use(prefix, value): value must be a middleware function or a Router`)
+      }
+    } else if (typeof arg1 === 'function') {
+      this.journal.push({ kind: 'use-global', mw: arg1 })
+    } else {
+      throw new TypeError(`Router.use(): first argument must be a path string or middleware function`)
+    }
+    return this
+  }
+
+  // ───── Verb registration ──────────────────────────────────────────────
+  // Each verb supports the back-compat `(path, handler)` shape AND the
+  // variadic `(path, ...inlineMiddleware, handler)` shape Express uses. The
+  // overloads keep TypeScript happy with the "handler is always last" rule.
+
+  get<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  get<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  get<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('GET', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+  post<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  post<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  post<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('POST', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+  put<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  put<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  put<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('PUT', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+  patch<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  patch<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  patch<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('PATCH', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+  delete<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  delete<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  delete<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('DELETE', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+  head<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  head<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  head<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('HEAD', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+  options<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this
+  options<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  options<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this {
+    return this.method('OPTIONS', path, ...(args as [...IngeniumMiddleware[], IngeniumHandler]))
+  }
+
+  /**
+   * Chainable per-path registration. Returns a builder that holds the path
+   * and lets you stack verbs on it without retyping:
+   *
+   * @example
+   *   router
+   *     .route('/users/:id')
+   *     .get((ctx) => loadUser(ctx.params.id))
+   *     .put(requireAdmin, (ctx) => updateUser(ctx))
+   *     .delete(requireAdmin, (ctx) => deleteUser(ctx))
+   *
+   * Pure registration sugar — every call delegates to `router.method(...)`,
+   * so all features (inline middleware, declarative options, typed params
+   * via `ExtractParams<P>`) work identically.
+   */
+  route<P extends string>(path: P): RouteBuilder<P> {
+    return new RouteBuilder<P>((method, args) =>
+      (this.method as (m: HttpMethod, p: string, ...a: unknown[]) => unknown)(method, path, ...args),
+    )
+  }
+
+  /**
+   * Internal — register a route under any HTTP method. Accepts the variadic
+   * `(...inlineMiddleware, handler)` tail; the LAST positional arg is always
+   * the handler.
+   */
+  method(method: HttpMethod, path: string, handler: IngeniumHandler): this
+  method(method: HttpMethod, path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  method(method: HttpMethod, path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this {
+    if (args.length === 0) {
+      throw new TypeError(`Router.${method.toLowerCase()}('${path}'): handler is required`)
+    }
+    const handler = args[args.length - 1] as IngeniumHandler
+    if (typeof handler !== 'function') {
+      throw new TypeError(
+        `Router.${method.toLowerCase()}('${path}'): last argument must be a handler function`,
+      )
+    }
+    const inline = args.slice(0, -1) as IngeniumMiddleware[]
+    for (let i = 0; i < inline.length; i++) {
+      if (typeof inline[i] !== 'function') {
+        throw new TypeError(
+          `Router.${method.toLowerCase()}('${path}'): inline middleware at position ${i} is not a function`,
+        )
+      }
+    }
+    const entry: Registration = {
+      kind: 'route',
+      method,
+      path: normalizePath(path),
+      handler,
+    }
+    if (inline.length > 0) entry.inlineMiddleware = inline
+    this.journal.push(entry)
+    return this
+  }
+}
+
+/**
+ * Per-path chainable builder returned by `app.route(path)` and
+ * `router.route(path)`. Holds the path and an "emit" callback that registers
+ * a route on the underlying host (an `IngeniumApp` or a `Router`); the
+ * builder itself is just sugar — no per-request cost, no separate dispatch
+ * path. The host's verb method does all the validation, dirty-bit flipping,
+ * and journal writes.
+ *
+ * The generic `P` flows `ExtractParams<P>` into every handler signature so
+ * `app.route('/users/:id').get(ctx => ctx.params.id)` narrows `ctx.params`
+ * exactly like the bare verb form does.
+ */
+export class RouteBuilder<P extends string> {
+  constructor(private readonly emit: (method: HttpMethod, args: unknown[]) => void) {}
+
+  get(handler: IngeniumHandler<ExtractParams<P>>): this
+  get(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  get(...args: unknown[]): this { this.emit('GET', args); return this }
+
+  post(handler: IngeniumHandler<ExtractParams<P>>): this
+  post(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  post(...args: unknown[]): this { this.emit('POST', args); return this }
+
+  put(handler: IngeniumHandler<ExtractParams<P>>): this
+  put(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  put(...args: unknown[]): this { this.emit('PUT', args); return this }
+
+  patch(handler: IngeniumHandler<ExtractParams<P>>): this
+  patch(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  patch(...args: unknown[]): this { this.emit('PATCH', args); return this }
+
+  delete(handler: IngeniumHandler<ExtractParams<P>>): this
+  delete(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  delete(...args: unknown[]): this { this.emit('DELETE', args); return this }
+
+  head(handler: IngeniumHandler<ExtractParams<P>>): this
+  head(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  head(...args: unknown[]): this { this.emit('HEAD', args); return this }
+
+  options(handler: IngeniumHandler<ExtractParams<P>>): this
+  options(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this
+  options(...args: unknown[]): this { this.emit('OPTIONS', args); return this }
+
+  /** Register the same handler for all common HTTP methods (GET, POST, PUT, PATCH, DELETE). */
+  all(handler: IngeniumHandler<ExtractParams<P>>): this {
+    for (const m of ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const) this.emit(m, [handler])
+    return this
+  }
+}
+
+/** Strip trailing slash; ensure leading slash. Empty string is allowed (means "no prefix"). */
+function normalizePrefix(p: string): string {
+  if (p === '' || p === '/') return ''
+  let out = p
+  if (out[0] !== '/') out = '/' + out
+  if (out.length > 1 && out[out.length - 1] === '/') out = out.slice(0, -1)
+  return out
+}
+
+function normalizePath(p: string): string {
+  if (!p) return '/'
+  if (p[0] !== '/') return '/' + p
+  return p
+}
+
+/**
+ * Flatten a router's journal into resolved registrations against the parent,
+ * applying the given prefix and inheriting any router-scoped middleware.
+ *
+ * Returns:
+ *   - global middleware to apply to ALL routes inside the prefix
+ *   - prefix-scoped middleware (with its own sub-prefix relative to root)
+ *   - routes with their final composed paths
+ *
+ * Used by the App at compose time.
+ */
+export interface FlatRegistrations {
+  globalMiddleware: IngeniumMiddleware[]              // unscoped (matches every request)
+  scopedMiddleware: { prefix: string; mw: IngeniumMiddleware }[]
+  routes: {
+    method: HttpMethod
+    path: string
+    handler: IngeniumHandler
+    /** Inline middleware survives the flatten so app.compose() can splice it in. */
+    inlineMiddleware?: IngeniumMiddleware[]
+  }[]
+}
+
+export function flattenRouter(router: Router, prefix: string = ''): FlatRegistrations {
+  const out: FlatRegistrations = { globalMiddleware: [], scopedMiddleware: [], routes: [] }
+  flattenInto(router, prefix, out)
+  return out
+}
+
+function flattenInto(router: Router, prefix: string, out: FlatRegistrations): void {
+  for (const entry of router.journal) {
+    switch (entry.kind) {
+      case 'use-global':
+        // A "global" registration inside a mounted router is actually scoped to the mount prefix.
+        if (prefix === '') out.globalMiddleware.push(entry.mw)
+        else out.scopedMiddleware.push({ prefix, mw: entry.mw })
+        break
+      case 'use-prefix':
+        out.scopedMiddleware.push({ prefix: prefix + entry.prefix, mw: entry.mw })
+        break
+      case 'use-router':
+        flattenInto(entry.router, prefix + entry.prefix, out)
+        break
+      case 'route': {
+        const route: FlatRegistrations['routes'][number] = {
+          method: entry.method,
+          path: prefix + entry.path,
+          handler: entry.handler,
+        }
+        if (entry.inlineMiddleware && entry.inlineMiddleware.length > 0) {
+          route.inlineMiddleware = entry.inlineMiddleware
+        }
+        out.routes.push(route)
+        break
+      }
+    }
+  }
+}