ingenium 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,4262 @@
+import { Buffer as Buffer$1 } from 'node:buffer';
+import * as node_http from 'node:http';
+import { IncomingHttpHeaders, Server as Server$1 } from 'node:http';
+import { Readable } from 'node:stream';
+import { KeyObject } from 'node:crypto';
+import { WebSocket as WebSocket$1 } from 'ws';
+
+/**
+ * Trust-proxy resolution for `X-Forwarded-*` headers.
+ *
+ * Mirrors Express's `app.set('trust proxy', ...)` semantics:
+ * - `false` (default): never trust XFF — `ctx.ip` always reflects the immediate
+ *   socket peer.
+ * - `true`: trust the entire `X-Forwarded-For` chain — last entry wins.
+ * - `number n`: trust `n` upstream hops — return chain entry `n` from the right.
+ * - `string` (single CIDR/IP/keyword) or `string[]` (list): trust connections
+ *   from these addresses; walk the chain skipping trusted IPs.
+ * - `(ip, hopIdx) => boolean`: custom predicate, called per chain entry.
+ *
+ * Supported keywords: `'loopback'` (127.0.0.0/8, ::1), `'linklocal'`
+ * (169.254.0.0/16, fe80::/10), `'uniquelocal'` (10/8, 172.16/12, 192.168/16,
+ * fc00::/7). CIDRs accepted in IPv4 dotted (`10.0.0.0/8`) and IPv6
+ * (`fc00::/7`) form. Single addresses without `/` match exactly.
+ */
+type TrustProxy = boolean | number | string | string[] | ((ip: string, hopIdx: number) => boolean);
+interface ForwardedInfo {
+    /** The resolved client IP after walking the trusted hop chain. */
+    ip: string;
+    /** Full forwarded chain, left-to-right (closest to client first), plus the immediate peer at the end. */
+    ips: readonly string[];
+    /** Best-effort protocol: `http` or `https`. */
+    protocol: 'http' | 'https';
+    /** Best-effort hostname (no port). */
+    hostname: string;
+}
+/**
+ * Resolve forwarded info from raw headers + the immediate socket peer.
+ *
+ * @param trust          The `trustProxy` configuration.
+ * @param remoteAddress  The socket-level peer address (always present).
+ * @param headers        Lowercased request headers (Node convention).
+ * @param defaultProtocol The protocol of the underlying transport (`http` for `node:http`,
+ *                        `https` for TLS, `http` for h2c, `https` for h2/TLS).
+ */
+declare function resolveForwarded(trust: TrustProxy, remoteAddress: string, headers: Readonly<Record<string, string | string[] | undefined>>, defaultProtocol?: 'http' | 'https'): ForwardedInfo;
+
+/**
+ * Background-job type surface for Ingenium.
+ *
+ * The core abstraction is a {@link QueueStore} — a pluggable persistence layer
+ * for FIFO jobs with retries and a dead-letter list. The default implementation
+ * ({@link MemoryQueueStore}) keeps everything in process; a Redis adapter can
+ * land later by simply implementing this interface.
+ *
+ * A {@link IngeniumQueue} wraps a store with a worker pool, retry policy, and
+ * pause/resume/drain controls; a {@link QueueRegistry} (held by `IngeniumApp`)
+ * indexes named queues so route handlers can enqueue from any code path.
+ */
+/**
+ * Worker function for a registered queue. Throwing causes a retry per the
+ * configured {@link RetryPolicy}; resolving means the job is `ack`'d.
+ */
+type QueueWorker<TData> = (job: {
+    /** Stable id assigned by the store at enqueue time. */
+    id: string;
+    /** Job payload (the value passed to `add`). */
+    data: TData;
+    /**
+     * 1-indexed attempt counter. `1` on first delivery; incremented before each
+     * retry. Use this in the worker to back off external calls or short-circuit
+     * non-recoverable failures.
+     */
+    attempt: number;
+}) => unknown | Promise<unknown>;
+/**
+ * Retry policy. The first attempt is included in the count: `attempts: 3`
+ * means one initial try + two retries.
+ */
+interface RetryPolicy {
+    /** Total tries including the first delivery. Must be `>= 1`. */
+    attempts: number;
+    /**
+     * Delay (ms) before the NEXT attempt, given the attempt that just failed
+     * (1-indexed). E.g. for `attempts: 3`, this is called with `1` then `2`.
+     */
+    backoffMs: (attempt: number) => number;
+}
+/**
+ * Options for {@link IngeniumApp.queue}. All fields optional.
+ *
+ * @typeParam TData - shape of job payloads enqueued onto this queue
+ */
+interface QueueOptions<TData> {
+    /**
+     * Max concurrent jobs processed in parallel by this queue's worker pool.
+     * Default `1` (strict FIFO). Bump this for I/O-bound work.
+     */
+    concurrency?: number;
+    /**
+     * Retry policy on worker throw. Numeric shorthand `n` is equivalent to
+     * `{ attempts: n, backoffMs: exponential }`. Default: 3 attempts at
+     * 100ms / 400ms / 1.6s.
+     */
+    retries?: number | RetryPolicy;
+    /**
+     * Custom store. Default {@link MemoryQueueStore}. Implement this to back
+     * the queue with Redis / Postgres / SQS / etc.
+     */
+    store?: QueueStore<TData>;
+    /**
+     * Called once retries are exhausted, just before the job is moved to the
+     * dead-letter list. Throwing here is logged and swallowed — the job is
+     * still moved to the DLQ.
+     */
+    onFailed?: (job: FailedJob<TData>) => void | Promise<void>;
+}
+/**
+ * Pluggable persistence layer. The default {@link MemoryQueueStore} keeps
+ * pending and failed jobs in arrays + an in-flight map. A Redis adapter
+ * would map this onto LPUSH / BRPOPLPUSH / a processing list / a DLQ list.
+ *
+ * Implementations MUST guarantee at-least-once delivery (a `next()`-ed
+ * job that is neither `ack`'d nor `retry`'d nor `fail`'d is considered
+ * stuck and may be re-delivered by the store on its own schedule).
+ */
+interface QueueStore<TData> {
+    /** Append a job to the tail. Returns the assigned id. */
+    enqueue(data: TData): Promise<{
+        id: string;
+    }>;
+    /**
+     * Pop the next pending job and move it to the in-flight set. Returns
+     * `null` when the queue is empty. The returned `attempt` reflects how
+     * many times this job has been delivered (1 on first delivery).
+     */
+    next(): Promise<{
+        id: string;
+        data: TData;
+        attempt: number;
+    } | null>;
+    /** Mark an in-flight job as completed. Removes it from the store. */
+    ack(id: string): Promise<void>;
+    /**
+     * Re-enqueue the in-flight job for another attempt after `delayMs`.
+     * The store MUST increment its internal attempt counter so the next
+     * `next()` returns it with the bumped count.
+     */
+    retry(id: string, delayMs: number): Promise<void>;
+    /** Move the in-flight job to the dead-letter list. */
+    fail(id: string): Promise<void>;
+    /** Number of pending (not in-flight, not failed) jobs. */
+    size(): Promise<number>;
+    /** Number of jobs in the dead-letter list. */
+    failedCount(): Promise<number>;
+}
+/** Payload passed to {@link QueueOptions.onFailed} when retries are exhausted. */
+interface FailedJob<TData> {
+    id: string;
+    data: TData;
+    /** Final attempt number (== `retries.attempts`). */
+    attempt: number;
+    /** Whatever the worker threw on its last attempt. */
+    lastError: unknown;
+}
+/** Per-request handle returned by `ctx.queue(name)`. */
+interface JobHandle<TData = unknown> {
+    /** Enqueue `data`. Resolves to the assigned job id. */
+    add(data: TData): Promise<{
+        id: string;
+    }>;
+}
+/**
+ * Bookkeeping wrapper a {@link QueueRegistry} keeps for every registered
+ * queue. Mostly useful for introspection / tests.
+ */
+interface RegisteredQueue<TData = unknown> {
+    name: string;
+    options: Required<Pick<QueueOptions<TData>, 'concurrency'>> & {
+        retries: RetryPolicy;
+        onFailed: ((job: FailedJob<TData>) => void | Promise<void>) | undefined;
+    };
+}
+
+/**
+ * Options for `IngeniumBody.multipart()`.
+ *
+ * All limits are validated mid-parse — exceeding any of them throws before
+ * the full body is fully decoded so memory usage stays bounded.
+ */
+interface MultipartOptions {
+    /** Total request body cap. Default 100,000 bytes (matches Express's body-parser default). */
+    maxBytes?: number;
+    /** Per-file size cap. Default 10 * 1024 * 1024 (10 MiB). */
+    maxFileSize?: number;
+    /** Maximum number of file parts in one request. Default 20. */
+    maxFiles?: number;
+    /** Maximum number of plain (non-file) field parts. Default 100. */
+    maxFields?: number;
+    /** Allowed MIME prefixes (e.g. ['image/']). File rejected if no prefix matches. Default: any. */
+    allowedMimePrefixes?: string[];
+}
+/** A single uploaded file part, fully buffered. */
+interface MultipartFile {
+    /** Original filename as supplied by the client. */
+    filename: string;
+    /** MIME type from the part's `Content-Type` header (defaults to `application/octet-stream`). */
+    mimeType: string;
+    /** Byte length of `data`. */
+    size: number;
+    /** Raw file bytes — fully buffered. For very large uploads, prefer `ctx.body.stream()`. */
+    data: Buffer$1;
+}
+/** Result of parsing a `multipart/form-data` body. */
+interface MultipartResult {
+    /** Plain-text form fields keyed by name. Repeated names collapse into an array. */
+    fields: Record<string, string | string[]>;
+    /** File parts keyed by name. Repeated names collapse into an array. */
+    files: Record<string, MultipartFile | MultipartFile[]>;
+}
+
+/**
+ * Local, zero-dependency type definitions for the
+ * [Standard Schema](https://standardschema.dev) v1 spec.
+ *
+ * Ingenium detects schemas implementing this contract on
+ * `IngeniumBody.json(schema)` and runs their `validate` function, mapping
+ * `issues` into a `IngeniumValidationError` with field-level messages.
+ *
+ * We intentionally do NOT import `@standard-schema/spec` to keep the
+ * core dependency-free. These types mirror the spec exactly.
+ */
+/** A successful validation result: parsed/transformed value. */
+interface StandardSuccessResult<TOut> {
+    readonly value: TOut;
+    readonly issues?: undefined;
+}
+/** A single issue describing why validation failed at a particular path. */
+interface StandardIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | StandardPathSegment> | undefined;
+}
+/** A path segment may be a bare key OR an object with a `key` property. */
+interface StandardPathSegment {
+    readonly key: PropertyKey;
+}
+/** A failed validation result: one or more issues. */
+interface StandardFailureResult {
+    readonly issues: ReadonlyArray<StandardIssue>;
+    readonly value?: undefined;
+}
+/** Standard Schema validation result: success XOR failure. */
+type StandardResult<TOut> = StandardSuccessResult<TOut> | StandardFailureResult;
+/** The properties living under the `~standard` key. */
+interface StandardSchemaV1Props<TIn = unknown, TOut = TIn> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (input: unknown) => StandardResult<TOut> | Promise<StandardResult<TOut>>;
+    readonly types?: {
+        readonly input: TIn;
+        readonly output: TOut;
+    } | undefined;
+}
+/** The Standard Schema v1 interface — anything with a `~standard` property. */
+interface StandardSchemaV1<TIn = unknown, TOut = TIn> {
+    readonly '~standard': StandardSchemaV1Props<TIn, TOut>;
+}
+/**
+ * Type guard: is `x` a Standard Schema v1?
+ *
+ * Checks for the `~standard` property and that its `version` is `1` and
+ * `validate` is a function. Cheap enough to call on every body.json() call.
+ */
+declare function isStandardSchema(x: unknown): x is StandardSchemaV1;
+
+/** Minimal duck-type for any validation library that accepts unknown and returns a typed value. */
+interface ParseSchema<T> {
+    parse(input: unknown): T;
+}
+/** Optional Zod-like schema: success/failure object output (used internally for friendlier errors). */
+interface SafeParseSchema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: ZodLikeIssue[];
+        };
+    };
+}
+interface ZodLikeIssue {
+    path: ReadonlyArray<string | number>;
+    message: string;
+}
+/**
+ * Lazy body accessor. Bytes are not read until one of the consume methods
+ * (`json`, `text`, `urlencoded`, `buffer`, `stream`) is called.
+ *
+ * One instance is allocated per `IngeniumContext` (pool-bound), so per-request
+ * cost is just a `reset()`.
+ */
+declare class IngeniumBody {
+    /** @internal */ _source: Readable | null;
+    /** @internal */ _consumed: boolean;
+    /** @internal */ _contentType: string | undefined;
+    /** @internal */ _contentLength: number | undefined;
+    /**
+     * @internal
+     * Parse cache. Stores the raw body bytes after the first successful
+     * `buffer()` (or `text()` / `json()` / `urlencoded()`, which all go
+     * through `buffer()`). Subsequent buffer-producing consumers reuse
+     * these bytes instead of throwing "already consumed".
+     *
+     * Caches the RAW Buffer (not parsed objects) so different callers can
+     * apply different schemas / decoders against the same bytes — a
+     * common pattern when an audit middleware reads the body before the
+     * handler does. Re-parsing JSON from a cached buffer is cheap; mixing
+     * schemas against a cached parsed object would be incorrect.
+     *
+     * `stream()` opts out (it hands the caller ownership of the raw
+     * Readable) and `multipart()` opts out (its result is bespoke and
+     * re-parsing with different options would be ambiguous).
+     *
+     * Checked with `!== null` rather than truthiness so an empty body
+     * (`Buffer.alloc(0)`) still hits the cache on subsequent reads.
+     */
+    /** @internal */ _cached: Buffer$1 | null;
+    /** @internal Adapter calls this on each request before dispatch. */
+    _attach(source: Readable | null, contentType: string | undefined, contentLength: number | undefined): void;
+    /** @internal Pool reset. */
+    _reset(): void;
+    /**
+     * Returns the raw request body stream. Throws if already consumed OR
+     * if the body has already been buffered (cached) — once we hold the
+     * bytes, we can't hand the caller back a fresh Readable to own.
+     */
+    stream(): Readable;
+    /**
+     * Buffers the entire body into a `Buffer`. Honors `maxBytes` (default 100KB).
+     *
+     * If the body has already been buffered once (by any prior `buffer()`,
+     * `text()`, `json()`, or `urlencoded()` call), returns the cached bytes
+     * — `maxBytes` is still enforced against `cached.length`, so a caller
+     * passing a tighter cap than the original still gets a 413.
+     */
+    buffer(maxBytes?: number): Promise<Buffer$1>;
+    /** Buffers the body and decodes as UTF-8 text. */
+    text(maxBytes?: number): Promise<string>;
+    /**
+     * Parses the body as JSON. If a schema is provided, the parsed value is
+     * validated. Detection order:
+     *
+     *   1. Standard Schema v1 (`["~standard"]`) — async-aware, multi-issue
+     *   2. Zod-like `safeParse(input)` — multi-issue
+     *   3. Plain `parse(input): T` — throws on failure
+     *
+     * Validation failures are normalized into `IngeniumValidationError` with a
+     * field-level `fields` map (dot-joined paths; empty path → `_`).
+     */
+    json<T = unknown>(schema?: StandardSchemaV1<unknown, T> | SafeParseSchema<T> | ParseSchema<T>, maxBytes?: number): Promise<T>;
+    /** Parses the body as `application/x-www-form-urlencoded`. */
+    urlencoded(maxBytes?: number): Promise<Record<string, string>>;
+    /**
+     * Parses the body as `multipart/form-data` (RFC 7578).
+     *
+     * Returns plain-text fields and fully buffered file parts. For very large
+     * uploads prefer `stream()` and parse manually — this method holds every
+     * file in memory.
+     *
+     * Failure modes:
+     * - Body exceeds `maxBytes` → `IngeniumPayloadTooLargeError`
+     * - Single file exceeds `maxFileSize` → `IngeniumPayloadTooLargeError`
+     * - Too many files / fields → `IngeniumBadRequestError`
+     * - Disallowed mime type → `IngeniumBadRequestError`
+     * - Content-Type isn't `multipart/form-data` or boundary missing → `IngeniumBadRequestError`
+     * - Malformed body → `IngeniumBadRequestError`
+     */
+    multipart(opts?: MultipartOptions): Promise<MultipartResult>;
+}
+
+/**
+ * Options accepted by {@link IngeniumCookies.set}. Maps 1:1 to RFC 6265 cookie
+ * attributes plus a few modern extensions (`Priority`, `Partitioned`).
+ *
+ * `sameSite: true` is normalized to `'strict'` (Express compatibility);
+ * `sameSite: false` omits the attribute entirely so the browser falls back
+ * to its default policy.
+ */
+interface CookieSetOptions {
+    /** `Domain=` attribute. Omitted when undefined. */
+    domain?: string;
+    /** `Path=` attribute. Defaults to `'/'`. */
+    path?: string;
+    /** `Expires=` attribute. Serialized via `Date.toUTCString()`. */
+    expires?: Date;
+    /** `Max-Age=` (seconds). Floored to an integer. */
+    maxAge?: number;
+    /** `HttpOnly` flag. */
+    httpOnly?: boolean;
+    /** `Secure` flag. */
+    secure?: boolean;
+    /** `SameSite=` attribute. `true` → `'strict'`; `false`/omitted → no attr. */
+    sameSite?: 'strict' | 'lax' | 'none' | true | false;
+    /** `Priority=` attribute (CHIPS / RFC 9220). Capitalized on the wire. */
+    priority?: 'low' | 'medium' | 'high';
+    /** `Partitioned` flag (CHIPS). */
+    partitioned?: boolean;
+    /**
+     * When `true`, the cookie value is HMAC-SHA-256 signed with the app's
+     * `cookieSecrets[0]`. On the wire: `name=value.signature`. Throws
+     * `IngeniumError(500, 'COOKIE_SECRET_MISSING')` if no secrets are configured.
+     */
+    signed?: boolean;
+}
+/** Options accepted by {@link IngeniumCookies.get}. */
+interface CookieGetOptions {
+    /**
+     * When `true`, the cookie value is treated as `value.signature` and the
+     * HMAC is verified against every configured secret (rotation-safe).
+     * Returns `null` on tamper, missing signature, or no configured secrets.
+     */
+    signed?: boolean;
+}
+/**
+ * First-class cookie API exposed via `ctx.cookies`. Pool-bound and lazy —
+ * the holder is allocated on first access and dropped to `null` on context
+ * reset, so routes that never touch cookies pay zero overhead.
+ *
+ * Read side parses `ctx.headers.cookie` once and caches the resulting record.
+ * Write side appends to the response `set-cookie` header, preserving prior
+ * values (a single response may carry multiple `Set-Cookie` headers).
+ */
+interface IngeniumCookies {
+    /**
+     * Read a cookie by name. With `{ signed: true }`, verifies the HMAC
+     * suffix and returns `null` on mismatch. Returns `null` when the cookie
+     * is absent.
+     */
+    get(name: string, opts?: CookieGetOptions): string | null;
+    /**
+     * Snapshot of all parsed cookies. Signed cookies appear with their raw
+     * `value.signature` suffix — call `.get(name, { signed: true })` to verify.
+     */
+    all(): Record<string, string>;
+    /**
+     * Write a `Set-Cookie` header. Multiple calls accumulate (the response
+     * carries one `Set-Cookie` header per call). With `{ signed: true }`,
+     * the value is HMAC-SHA-256 signed.
+     */
+    set(name: string, value: string, opts?: CookieSetOptions): void;
+    /**
+     * Expire a cookie. Emits `Max-Age=0` plus an `Expires` in the past, and
+     * mirrors `path` / `domain` so the browser actually removes the right
+     * cookie (a `Set-Cookie` only matches the existing cookie on those attrs).
+     */
+    clear(name: string, opts?: Pick<CookieSetOptions, 'domain' | 'path'>): void;
+}
+
+/** HTTP methods supported by the router. */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+declare const HTTP_METHODS: readonly HttpMethod[];
+/**
+ * Recursively extracts named params from a path string at the type level.
+ *
+ * - `:name`           → required string
+ * - `:name?`          → optional string (becomes `string | undefined`)
+ * - `:name(regex)`    → required string. The regex is type-stripped here, but
+ *                       the constraint IS enforced at runtime by the trie
+ *                       (`RouterTrie.find` tests the segment against the
+ *                       compiled, fully-anchored pattern), so the `string`
+ *                       type is honest about the matched shape.
+ *                       Note: number-narrowing (typing `:id(\d+)` as `number`)
+ *                       remains deferred — constrained params stay `string`.
+ * - `*name`           → required string (greedy wildcard tail)
+ *
+ * @example
+ * type P = ExtractParams<'/users/:id(\\d+)/posts/:slug?'>
+ * // { id: string; slug?: string | undefined }
+ */
+type ExtractParams<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}` ? ParamRecord<Param> & ExtractParams<`/${Rest}`> : Path extends `${string}:${infer Param}` ? ParamRecord<Param> : Path extends `${string}*${infer Wild}` ? {
+    [K in Wild]: string;
+} : EmptyParams;
+type EmptyParams = Record<string, never>;
+/**
+ * Drop a single parenthesized constraint group from a param name.
+ * `id(\\d+)`   → `id`
+ * `id(\\d+)?`  → `id?`  (optionality marker preserved for ParamRecord)
+ * `id`         → `id`   (no-op when no constraint present)
+ */
+type StripConstraint<P extends string> = P extends `${infer Head}(${string})${infer Tail}` ? `${Head}${Tail}` : P;
+type ParamRecord<P extends string> = StripConstraint<P> extends `${infer Name}?` ? {
+    [K in Name]?: string;
+} : {
+    [K in StripConstraint<P>]: string;
+};
+
+/**
+ * Higher-level `accepts*` helpers, parameterized over a context-like object
+ * with a `headers` map. Kept context-agnostic so they're trivially testable
+ * with a plain `{ headers: {...} }` stub.
+ */
+
+/** Minimal shape we depend on — `IngeniumContext` satisfies it. */
+interface NegotiableCtx {
+    headers: IncomingHttpHeaders;
+}
+/**
+ * `accepts(ctx)` → list of accepted media types in preference order
+ * (after expanding shorthand inputs is a no-op here — it returns the raw
+ * mime strings the client sent).
+ *
+ * `accepts(ctx, ...types)` → best matching offered type, or `false`.
+ * Each `type` may be a shorthand (`'json'`, `'html'`) or full mime
+ * (`'application/json'`).
+ */
+declare function accepts(ctx: NegotiableCtx): string[];
+declare function accepts(ctx: NegotiableCtx, ...types: string[]): string | false;
+/**
+ * `acceptsCharsets(ctx)` → all charsets in preference order.
+ * `acceptsCharsets(ctx, ...charsets)` → best match or `false`.
+ */
+declare function acceptsCharsets(ctx: NegotiableCtx): string[];
+declare function acceptsCharsets(ctx: NegotiableCtx, ...charsets: string[]): string | false;
+/**
+ * `acceptsLanguages(ctx)` → all languages in preference order.
+ * `acceptsLanguages(ctx, ...langs)` → best match or `false`.
+ *
+ * Language matching is treated like opaque tokens with `*` as wildcard;
+ * partial-tag matching (e.g. `en` matching `en-US`) is **not** performed —
+ * use exact tags for predictable behavior, mirroring Express's default.
+ */
+declare function acceptsLanguages(ctx: NegotiableCtx): string[];
+declare function acceptsLanguages(ctx: NegotiableCtx, ...langs: string[]): string | false;
+/**
+ * `acceptsEncodings(ctx)` → all encodings in preference order.
+ * `acceptsEncodings(ctx, ...encodings)` → best match or `false`.
+ *
+ * Per RFC 9110 §12.5.4, when `Accept-Encoding` is absent, the server
+ * MAY assume the client accepts any encoding — we follow Express and
+ * return the first offered.
+ */
+declare function acceptsEncodings(ctx: NegotiableCtx): string[];
+declare function acceptsEncodings(ctx: NegotiableCtx, ...encodings: string[]): string | false;
+
+/**
+ * `formatResponse(ctx, handlers)` — Express's `res.format` for Ingenium.
+ *
+ * Picks the best handler key against the request `Accept` header, runs it,
+ * sets `Content-Type` to the matched key, and writes the result as the
+ * response body. If no handler matches and no `default` key is provided,
+ * throws a `IngeniumError(406, 'NOT_ACCEPTABLE')`.
+ *
+ * Handlers may be sync or async — `formatResponse` always awaits.
+ */
+
+/** Minimal context shape required by `formatResponse` — narrower than full `IngeniumContext`. */
+interface FormattableCtx extends NegotiableCtx {
+    set(name: string, value: string | string[]): unknown;
+    json(body: unknown, status?: number): void;
+    send(body: Buffer$1 | string, status?: number): void;
+}
+/** Map of `mime → handler`. The reserved key `default` is the no-match fallback. */
+type FormatHandlers = Record<string, () => unknown | Promise<unknown>>;
+/**
+ * Pick the best handler key for `Accept` and run it.
+ *
+ * - JSON-shaped result objects are written via `ctx.json`.
+ * - String / Buffer results are written via `ctx.send` with the matched
+ *   content-type preserved (instead of `send`'s default text/plain inference).
+ * - `default` handler is used when no explicit key matches.
+ * - No match + no default → throws `IngeniumError(406, 'NOT_ACCEPTABLE')`.
+ */
+declare function formatResponse(ctx: FormattableCtx, handlers: FormatHandlers): Promise<void>;
+
+/**
+ * `respondJsonWithEtag(ctx, body, opts)` — JSON response with auto ETag and
+ * 304 short-circuit when `If-None-Match` matches.
+ *
+ * Behavior:
+ *   1. Stringify `body` to JSON exactly once.
+ *   2. Compute weak ETag (default) over the stringified bytes.
+ *   3. If `If-None-Match` (after weak normalization) matches → set 304,
+ *      clear body, mark written. Skip writing the JSON.
+ *   4. Otherwise: set `ETag` + `Content-Type` headers, write the body via
+ *      the same internal shape `ctx.json` uses, and mark written.
+ *
+ * Uses the lower-level shape from `IngeniumContext` directly (rather than
+ * calling `ctx.json`) so the JSON.stringify result can be reused without
+ * a second pass.
+ */
+
+/** Options for `respondJsonWithEtag`. */
+interface JsonEtagOptions {
+    /** Prefix the ETag with `W/`. Defaults to `true`. */
+    weak?: boolean;
+    /** HTTP status to use for the success path. Defaults to `200`. */
+    status?: number;
+}
+/**
+ * Minimal context shape required by `respondJsonWithEtag` — keeps the
+ * helper testable with a plain stub and avoids a hard import cycle on
+ * the full `IngeniumContext` class.
+ */
+interface JsonEtagCtx {
+    headers: IncomingHttpHeaders;
+    _statusCode: number;
+    _headers: Record<string, string | string[]>;
+    _body: ResponseBody;
+    _written: boolean;
+}
+declare function respondJsonWithEtag(ctx: JsonEtagCtx, body: unknown, opts?: JsonEtagOptions): void;
+
+/**
+ * `URLSearchParams` augmented with a `parse(schema)` method that runs the
+ * query through the same schema-detection pipeline as `ctx.body.json(schema)`.
+ *
+ * The shape passed to the schema is a **shallow array-aware** object:
+ *
+ *   `?id=42&tag=a&tag=b&active=true`
+ *     → `{ id: '42', tag: ['a','b'], active: 'true' }`
+ *
+ * Single-occurrence keys → `string`. Repeated keys → `string[]`. Everything is
+ * a string on the wire, so the user's schema is responsible for coercing
+ * numbers/booleans (Zod: use `z.coerce.number()`; ArkType: use `'string.numeric.parse'`).
+ *
+ * Rationale for picking THIS coercion over alternatives:
+ *   - "raw strings only" loses repeated-key fidelity (qs/Express-style arrays)
+ *   - "pre-coerced booleans/numbers" surprises users when "12foo" silently
+ *     becomes a string or "true" becomes a boolean against their schema
+ *   - Shallow-array matches `Object.fromEntries` semantics PLUS the most
+ *     common ergonomic ask (tag=a&tag=b → tag: string[])
+ */
+interface IngeniumQuery extends URLSearchParams {
+    parse<T = unknown>(schema: StandardSchemaV1<unknown, T> | SafeParseSchema<T> | ParseSchema<T>): T;
+}
+/** Internal response body shape — adapter writes one of these to the wire. */
+type ResponseBody = {
+    kind: 'none';
+} | {
+    kind: 'buffer';
+    data: Buffer$1;
+} | {
+    kind: 'string';
+    data: string;
+} | {
+    kind: 'stream';
+    data: Readable;
+};
+/**
+ * Per-request context. Pool-bound: one instance per pool slot, reused
+ * across thousands of requests. All mutable fields are reset between uses.
+ *
+ * The `Params` generic is a phantom — it narrows `ctx.params` for typed
+ * route handlers but is `Record<string, string>` at runtime.
+ */
+declare class IngeniumContext<Params = Record<string, string>> {
+    /** HTTP method, uppercase. */
+    method: HttpMethod;
+    /** Full request URL including query string (e.g. `/users/42?expand=posts`). */
+    url: string;
+    /** Path portion of the URL (no query string). Set by the adapter. */
+    path: string;
+    /** Raw query string (no leading `?`). Use `query` for parsed access. */
+    rawQuery: string;
+    /** Route params, written at trie-match time. */
+    params: Params;
+    /** Lowercased request headers (Node convention). */
+    headers: IncomingHttpHeaders;
+    /** Lazy body accessor. */
+    readonly body: IngeniumBody;
+    /** Free-form per-request state for plugins/middleware (e.g. `ctx.user = ...`). */
+    state: Record<string, unknown>;
+    /**
+     * Per-request handle to enqueue background jobs onto a registered queue.
+     * Wired by `IngeniumApp` as a lazy decorator (declared with `!` because the
+     * runtime value is installed by the decorator registry, not the class
+     * initializer). Throws if the named queue isn't registered.
+     *
+     * @example
+     *   await ctx.queue<{ to: string }>('emails').add({ to: 'a@b.com' })
+     */
+    queue: <TData = unknown>(name: string) => JobHandle<TData>;
+    /** Lazy-parsed query. First access caches the URLSearchParams. */
+    private _query;
+    get query(): IngeniumQuery;
+    /**
+     * @internal Lazy cookie holder. `null` until first read of `ctx.cookies`.
+     * Reset to `null` in `reset()` so a context returned to the pool drops the
+     * parsed-cookie cache (and any closed-over write state — though writes go
+     * straight to `_headers`, which is itself reset by reassignment).
+     */
+    _cookies: IngeniumCookies | null;
+    /**
+     * First-class cookie API. Lazy: the holder is allocated on first access so
+     * apps that never touch cookies pay zero per-request overhead. See
+     * `cookies.ts` for the read/write contract and signing rules.
+     *
+     * @example
+     *   const sid = ctx.cookies.get('sid', { signed: true })
+     *   ctx.cookies.set('theme', 'dark', { httpOnly: true, sameSite: 'lax' })
+     *   ctx.cookies.clear('legacy')
+     */
+    get cookies(): IngeniumCookies;
+    /**
+     * @internal App-wide cookie-signing secrets. Stamped by `IngeniumApp.handle`
+     * on dispatch entry when configured (mirrors `_trustProxy`). First secret
+     * signs new cookies; all entries verify reads (supports rotation). Empty
+     * means signed cookies will throw `IngeniumError(500, 'COOKIE_SECRET_MISSING')`.
+     *
+     * NOT cleared in `reset()` — this is app-wide config, not per-request state,
+     * and the cost of re-stamping every request is wasteful when the value is
+     * stable across the app's lifetime. The first call to `handle()` after a
+     * compose sets it; subsequent requests reuse the same array reference.
+     */
+    _cookieSecrets: readonly string[];
+    /** Immediate socket peer address — populated by the adapter. */
+    remoteAddress: string;
+    /** Underlying transport protocol — populated by the adapter (http for node:http, https for TLS). */
+    baseProtocol: 'http' | 'https';
+    /** @internal `trustProxy` config carried in from the app. */ _trustProxy: TrustProxy;
+    /** @internal Cached forwarded resolution; computed lazily from headers. */
+    private _forwarded;
+    private resolveForwarded;
+    /**
+     * Best-effort client IP. With `trustProxy: false` this is the immediate
+     * socket peer; with trust-proxy enabled the X-Forwarded-For chain is
+     * walked according to the configured trust policy.
+     */
+    get ip(): string;
+    /** Full forwarded chain (left-to-right, immediate peer last). */
+    get ips(): readonly string[];
+    /** Best-effort protocol — honors `X-Forwarded-Proto` when trust-proxy is enabled. */
+    get protocol(): 'http' | 'https';
+    /** Convenience: `protocol === 'https'`. */
+    get secure(): boolean;
+    /** Best-effort hostname (no port) — honors `X-Forwarded-Host` when trust-proxy is enabled. */
+    get hostname(): string;
+    /** @internal */ _statusCode: number;
+    /** @internal */ _headers: Record<string, string | string[]>;
+    /** @internal */ _body: ResponseBody;
+    /** @internal Whether a response helper has been called. */
+    _written: boolean;
+    /**
+     * @internal Per-request generation counter. Incremented every time the
+     * pool resets this context (and also bumped by `IngeniumApp.handle` when a
+     * request times out, so writes from the orphaned handler can be detected
+     * as stale). Compared against `_dispatchEpoch` by every response writer.
+     */
+    _epoch: number;
+    /**
+     * @internal Last `_epoch` value captured by `IngeniumApp.withEpochGuard`.
+     * Set on dispatch entry; the per-dispatch wrappers installed around the
+     * response writers close over this value to detect late writes from an
+     * orphaned (timed-out) handler. The wrappers compare `_epoch` against
+     * the captured value at call time — mismatch ⇒ orphan ⇒ swallow.
+     *
+     * `0` means no guard is active (no `requestTimeoutMs` configured, or
+     * the dispatch already resolved naturally).
+     */
+    _dispatchEpoch: number;
+    /**
+     * @internal Dev-only — emit `IngeniumDoubleWriteWarning` when a writer is
+     * called after `_written` is already true. No-op in production: V8
+     * eliminates the branch body behind the `IS_DEV` gate.
+     */
+    private _warnDoubleWrite;
+    /** Set the HTTP status code. Returns `this` for chaining. */
+    status(code: number): this;
+    /**
+     * Set a response header (case-insensitive). Returns `this` for chaining.
+     *
+     * Throws `IngeniumHeaderInjectionError` if `name` or `value` contains CR
+     * or LF — these would otherwise enable header-injection / response-
+     * splitting attacks if a caller forwards untrusted user input directly.
+     */
+    set(name: string, value: string | string[]): this;
+    /** Alias for `set` — matches Express's `res.setHeader`. */
+    setHeader(name: string, value: string | string[]): this;
+    /** Get a previously-set response header (lowercase lookup). */
+    getHeader(name: string): string | string[] | undefined;
+    /**
+     * Send a JSON response.
+     *
+     * Throws `IngeniumUnserializableError` if `body` cannot be encoded
+     * (circular structure, `BigInt`, etc.) — surfaces a clean 500 from the
+     * framework error boundary instead of a deep `TypeError`.
+     */
+    json(body: unknown, status?: number): void;
+    /** Send a `text/plain` response. */
+    text(body: string, status?: number): void;
+    /** Send a `text/html` response. */
+    html(body: string, status?: number): void;
+    /** Send a redirect (default 302). */
+    redirect(location: string, status?: number): void;
+    /** Stream a `Readable` to the client. Sets content-type if not already set. */
+    stream(readable: Readable, contentType?: string): void;
+    /**
+     * Sinatra-style short-circuit. Throws `IngeniumHaltError(status, body?)`
+     * — the framework error boundary catches it and serializes per `bodyShape`:
+     *
+     * - `ctx.halt(401)` → 401 with default JSON `{ error, code: 'HALT' }`.
+     * - `ctx.halt(404, 'Not Found')` → 404 `text/plain` body verbatim.
+     * - `ctx.halt(422, { fields })` → 422 `application/json` body verbatim.
+     *
+     * The TypeScript `never` return type lets `if (!found) ctx.halt(404)`
+     * narrow the rest of the function — code after the call is unreachable.
+     *
+     * To bypass the error boundary entirely (write the response without
+     * throwing) call `ctx.json(body, status)` and `return` from the handler.
+     *
+     * @example
+     *   if (!authorized(ctx)) ctx.halt(401, 'Unauthorized')
+     *   if (!user)            ctx.halt(404, { error: 'Not Found', id })
+     */
+    halt(status: number, body?: string | Record<string, unknown>): never;
+    /** Send a `Buffer` body verbatim. */
+    send(body: Buffer$1 | string, status?: number): void;
+    /**
+     * Return the best mime type the client accepts from the offered list, or
+     * `false` if none are acceptable. With no arguments, returns the parsed
+     * preference-ordered list of accepted types from `Accept`.
+     *
+     * Each `type` may be a shorthand (`'json'`, `'html'`, `'csv'`, …) or a full
+     * mime (`'application/json'`). Quality factors are honored.
+     *
+     * @example
+     *   if (ctx.accepts('json')) ctx.json({ ok: true })
+     *   else ctx.status(406).text('Not Acceptable')
+     */
+    accepts(): string[];
+    accepts(...types: string[]): string | false;
+    /** Best matching charset from the offered list against `Accept-Charset`. */
+    acceptsCharsets(): string[];
+    acceptsCharsets(...charsets: string[]): string | false;
+    /** Best matching language against `Accept-Language` (exact-tag match only). */
+    acceptsLanguages(): string[];
+    acceptsLanguages(...langs: string[]): string | false;
+    /** Best matching encoding against `Accept-Encoding` (first offered when header absent). */
+    acceptsEncodings(): string[];
+    acceptsEncodings(...encodings: string[]): string | false;
+    /**
+     * Run the handler whose key best matches the request `Accept` header. The
+     * matched key is set as `Content-Type`. If no key matches and no `default`
+     * handler is provided, throws `IngeniumError(406, 'NOT_ACCEPTABLE')`.
+     */
+    format(handlers: FormatHandlers): Promise<void>;
+    /**
+     * `true` when the client's `If-None-Match` matches the response `ETag`,
+     * or `If-Modified-Since` is at-or-after the response `Last-Modified`.
+     * Reads from `_headers` so handlers can set ETag / Last-Modified before checking.
+     */
+    get fresh(): boolean;
+    /** `!fresh`. */
+    get stale(): boolean;
+    /**
+     * Send a JSON body with an auto-computed weak ETag. If the request's
+     * `If-None-Match` matches the computed tag, short-circuits to 304.
+     */
+    jsonWithEtag(body: unknown, opts?: JsonEtagOptions): void;
+    /**
+     * Reset all per-request state. Called by the pool before returning the
+     * context to the free list. Reassignments preserve the V8 hidden class
+     * so subsequent allocations stay monomorphic.
+     */
+    reset(): void;
+}
+
+/**
+ * A function that runs as part of the middleware chain. Call `next()` to
+ * continue to the next middleware; omit it to short-circuit.
+ *
+ * @example
+ * const logger: IngeniumMiddleware = async (ctx, next) => {
+ *   const start = Date.now()
+ *   await next()
+ *   ctx.logger?.info(`${ctx.method} ${ctx.path} ${Date.now() - start}ms`)
+ * }
+ */
+type IngeniumMiddleware = (ctx: IngeniumContext, next: () => Promise<void>) => unknown | Promise<unknown>;
+/**
+ * A composed middleware chain plus terminal handler. Returned by `compose()`.
+ * Internally cached on each trie leaf.
+ */
+type ComposedHandler = (ctx: IngeniumContext) => Promise<void>;
+/**
+ * A user-facing route handler. Its return value is reflected to the wire by
+ * the response-helper dispatcher (see `response/helpers.ts`):
+ *
+ * - `undefined` → 204 (unless `ctx.json/...` was already called)
+ * - `string`    → 200 text/plain (or text/html if it starts with `<`)
+ * - object      → 200 application/json
+ * - `Buffer`/`Uint8Array` → 200 application/octet-stream
+ * - `Readable`  → streamed response
+ *
+ * For full control, call `ctx.json/text/html/stream/redirect` and return
+ * `void` (or any value — return value is ignored once a helper has run).
+ */
+type IngeniumHandler<Params = Record<string, string>> = (ctx: IngeniumContext<Params>) => unknown | Promise<unknown>;
+
+/** A journal entry — replayed against the trie when the app composes. */
+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[];
+};
+/**
+ * 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.
+ */
+declare 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;
+    get<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    get<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    post<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    post<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    put<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    put<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    patch<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    patch<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    delete<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    delete<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    head<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    head<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    options<P extends string>(path: P, handler: IngeniumHandler<ExtractParams<P>>): this;
+    options<P extends string>(path: P, ...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    /**
+     * 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>;
+    /**
+     * 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;
+}
+/**
+ * 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.
+ */
+declare class RouteBuilder<P extends string> {
+    private readonly emit;
+    constructor(emit: (method: HttpMethod, args: unknown[]) => void);
+    get(handler: IngeniumHandler<ExtractParams<P>>): this;
+    get(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    post(handler: IngeniumHandler<ExtractParams<P>>): this;
+    post(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    put(handler: IngeniumHandler<ExtractParams<P>>): this;
+    put(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    patch(handler: IngeniumHandler<ExtractParams<P>>): this;
+    patch(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    delete(handler: IngeniumHandler<ExtractParams<P>>): this;
+    delete(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    head(handler: IngeniumHandler<ExtractParams<P>>): this;
+    head(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    options(handler: IngeniumHandler<ExtractParams<P>>): this;
+    options(...args: [...IngeniumMiddleware[], IngeniumHandler<ExtractParams<P>>]): this;
+    /** Register the same handler for all common HTTP methods (GET, POST, PUT, PATCH, DELETE). */
+    all(handler: IngeniumHandler<ExtractParams<P>>): this;
+}
+
+/**
+ * Payload fired to `onRoute` hooks each time a route is registered into the
+ * trie during composition. Plugins can observe — they MUST NOT mutate.
+ */
+interface RegistrationEvent {
+    /** HTTP method (uppercase). */
+    readonly method: HttpMethod;
+    /** Final composed route path (after all prefixes). */
+    readonly path: string;
+}
+/**
+ * The shape a plugin can rely on regardless of whether it's registered onto
+ * the root `IngeniumApp` or onto a `ScopedApp` (via `app.scope(...).register(...)`).
+ *
+ * Both root and scoped registration targets implement this interface. Plugins
+ * that previously took `(app: IngeniumApp, opts)` are source-compatible:
+ * `IngeniumApp` implements every member of `PluginTarget`. The only practical
+ * difference at the call site is that `target.scope(...)`, `target.use(mw)`,
+ * and the verb methods become prefix-relative when `target` is a `ScopedApp`.
+ *
+ * # Scoping semantics for plugin authors
+ *
+ * - `target.use(mw)` / `target.use(subprefix, mw)` — middleware is scoped to
+ *   the target's prefix at compose time. On the root, this is "global". In a
+ *   scope, it's "applies only to paths under the scope's prefix".
+ * - `target.get/post/...` and `target.method(...)` — paths are prefix-
+ *   relative; the scope prepends its absolute prefix at registration time.
+ * - `target.register(plugin, opts)` — runs the plugin against the SAME
+ *   target. Nested scopes compose as expected.
+ * - `target.hooks` — lifecycle hooks are GLOBAL even when called inside a
+ *   scope. Hooks fire per request, before route dispatch; making them
+ *   scope-aware would require runtime path-prefix checks on every request.
+ *   If a plugin needs scope-aware behavior, it should inspect `ctx.path`
+ *   inside the hook body.
+ * - `target.decorate(...)` / `target.decorateRequest(...)` — decorators are
+ *   GLOBAL even when called inside a scope (see {@link IngeniumPlugin} JSDoc
+ *   for the rationale). `ScopedApp.decorate` emits a one-shot
+ *   `process.emitWarning` in non-production environments to surface this
+ *   footgun.
+ */
+interface PluginTarget {
+    /** Lifecycle hooks (global — see interface JSDoc). */
+    readonly hooks: Hooks;
+    /** Add middleware that runs for every request below this target. */
+    use(mw: IngeniumMiddleware): this;
+    /** Mount middleware or a sub-router at a path prefix (relative to this target). */
+    use(prefix: string, mw: IngeniumMiddleware | Router): this;
+    /** Register a route under any HTTP method (path is relative to this target). */
+    method(method: HttpMethod, path: string, handler: IngeniumHandler): this;
+    method(method: HttpMethod, path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    /**
+     * Chainable per-path builder. Same path-joining rules as the bare verbs —
+     * inside a `ScopedApp`, the builder's emitted routes are prefix-relative.
+     */
+    route<P extends string>(path: P): RouteBuilder<P>;
+    /** Convenience verb shortcuts (paths are relative to this target). */
+    get(path: string, handler: IngeniumHandler): this;
+    get(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    post(path: string, handler: IngeniumHandler): this;
+    post(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    put(path: string, handler: IngeniumHandler): this;
+    put(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    patch(path: string, handler: IngeniumHandler): this;
+    patch(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    delete(path: string, handler: IngeniumHandler): this;
+    delete(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    head(path: string, handler: IngeniumHandler): this;
+    head(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    options(path: string, handler: IngeniumHandler): this;
+    options(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    /**
+     * Pre-handler / post-handler middleware (paths are relative to this target).
+     * Inside a `ScopedApp` these are confined to the scope prefix — `s.before(h)`
+     * only fires for requests under the scope, mirroring `s.use`.
+     */
+    before(handler: IngeniumMiddleware): this;
+    before(pattern: string, handler: IngeniumMiddleware): this;
+    after(handler: IngeniumMiddleware): this;
+    after(pattern: string, handler: IngeniumMiddleware): this;
+    /** Decorator registration. NOTE: GLOBAL even when called inside a scope. */
+    decorate<T>(name: string, factory: LazyDecorator<T>): this;
+    decorateRequest<T>(name: string, factory: EagerDecorator<T>): this;
+    /**
+     * Register a plugin against this target. Plugins may be async and the
+     * caller should `await` the returned promise.
+     */
+    register<O>(plugin: IngeniumPlugin<O>, opts: O): Promise<this>;
+    register(plugin: IngeniumPlugin<void>): Promise<this>;
+    /**
+     * Open a nested registration scope. All registrations inside `registrar`
+     * are prefix-relative to `prefix` (and inherit any outer scope prefix).
+     */
+    scope(prefix: string, registrar: (scope: PluginTarget) => void): this | Promise<this>;
+}
+/**
+ * A plugin is a function that mutates a registration target: it can register
+ * routes, middleware, decorators, and hook handlers. Plugins are registered
+ * before `compose()` runs; they may be async.
+ *
+ * The `target` parameter is `PluginTarget` — implemented by both `IngeniumApp`
+ * (the root) and `ScopedApp` (created by `app.scope(prefix, ...)`). When a
+ * plugin is registered inside a scope, its `target.use(...)` / `target.get(...)`
+ * are automatically prefix-scoped at compose time.
+ *
+ * # Scoped-decorator caveat (V1)
+ *
+ * Decorators (`target.decorate`, `target.decorateRequest`) install onto the
+ * pooled `IngeniumContext` at request start; the registry is per-app, not
+ * per-path. That means a plugin registered inside `app.scope('/api', ...)`
+ * that calls `target.decorate('user', ...)` will decorate EVERY request,
+ * not just `/api/*` requests. The first such call inside a scope emits a
+ * `process.emitWarning` in non-production environments. Plugin authors who
+ * want per-scope decorator behavior should make the decorator's factory
+ * inspect `ctx.path` and return a sentinel for out-of-scope requests.
+ *
+ * @example
+ * const myPlugin: IngeniumPlugin<{ secret: string }> = async (target, opts) => {
+ *   target.hooks.onRequest((ctx) => { ... })
+ *   target.use((ctx, next) => next())          // scoped if target is a ScopedApp
+ *   target.get('/whoami', (ctx) => ...)        // path is relative to scope
+ * }
+ *
+ * await app.register(myPlugin, { secret: 'shh' })
+ * app.scope('/api', (s) => s.register(myPlugin, { secret: 'shh' }))
+ */
+type IngeniumPlugin<O = void> = (target: PluginTarget, opts: O) => void | Promise<void>;
+/** Fires once per route as the trie is built (during `compose()`). */
+type OnRouteHook = (registration: RegistrationEvent) => void;
+/** Fires before composition runs. May be async. */
+type OnComposeHook = () => void | Promise<void>;
+/** Fires at the start of every request, before middleware dispatch. */
+type OnRequestHook = (ctx: IngeniumContext) => void | Promise<void>;
+/** Fires after the handler resolves successfully. */
+type OnResponseHook = (ctx: IngeniumContext) => void | Promise<void>;
+/**
+ * Fires when the handler chain throws. OBSERVATION ONLY — the framework's
+ * error boundary still owns the response. Throwing inside an `onError` hook
+ * is swallowed; this is by design so observers can't mask the original error.
+ */
+type OnErrorHook = (err: unknown, ctx: IngeniumContext) => void | Promise<void>;
+/**
+ * Public hooks API exposed on `app.hooks`. Each method appends a listener;
+ * listeners are invoked in registration order, sequentially (`await`-ed in
+ * a loop) for predictable ordering.
+ */
+interface Hooks {
+    onRoute(fn: OnRouteHook): void;
+    onCompose(fn: OnComposeHook): void;
+    onRequest(fn: OnRequestHook): void;
+    onResponse(fn: OnResponseHook): void;
+    onError(fn: OnErrorHook): void;
+}
+/** Lazy decorator — computed on first access, then cached on the ctx. */
+type LazyDecorator<T = unknown> = (ctx: IngeniumContext) => T;
+/** Eager decorator — evaluated at request start, value assigned directly. */
+type EagerDecorator<T = unknown> = (ctx: IngeniumContext) => T;
+/** Generic decorator factory shape (covers both lazy and eager). */
+type Decorator<T = unknown> = (ctx: IngeniumContext) => T;
+
+/** A function the framework hands to the transport — call it per request. */
+type TransportDispatch = (ctx: IngeniumContext) => Promise<void>;
+/** A function the transport calls to acquire a context from the pool. */
+type TransportAcquire = () => IngeniumContext;
+/** A function the transport calls to release a context back to the pool. */
+type TransportRelease = (ctx: IngeniumContext) => void;
+/**
+ * The hooks a transport uses to interact with the framework. The transport
+ * owns the request/response objects from its underlying server (node:http,
+ * Bun.serve, etc.), populates a `IngeniumContext` from each request, awaits the
+ * `dispatch` callback, then writes the context's response state to the wire.
+ */
+interface TransportHooks {
+    acquire: TransportAcquire;
+    release: TransportRelease;
+    dispatch: TransportDispatch;
+    /**
+     * Hard ceiling (bytes) on the total request body. Adapters SHOULD wrap the
+     * inbound body stream in `createByteLimit(maxRequestBytes)` before handing
+     * it to `ctx.body._attach(...)`, AND reject with a 413 immediately when
+     * the request advertises a `Content-Length` greater than this value (no
+     * need to read the body). `Number.POSITIVE_INFINITY` disables the cap.
+     *
+     * Optional for backward compatibility with adapters / test fixtures that
+     * predate this hook. The framework's `app.listen()` always populates the
+     * field (default 2 MiB); consumers that read it should treat `undefined`
+     * as "no cap" (`Number.POSITIVE_INFINITY`).
+     */
+    maxRequestBytes?: number;
+}
+/** Options accepted by {@link ListeningServer.close}. */
+interface CloseOptions {
+    /**
+     * Maximum time (ms) to wait for keep-alive sockets to drain naturally
+     * before they are forcibly destroyed. When omitted (or undefined), no
+     * force-close occurs and `close()` waits indefinitely for sockets to
+     * finish — this matches the historical Node `server.close()` behavior.
+     */
+    gracefulTimeoutMs?: number;
+}
+/** A transport-agnostic listening server handle. */
+interface ListeningServer {
+    /** Bound port (resolved if `port: 0` was passed). */
+    port: number;
+    /** The bound host. */
+    host: string;
+    /**
+     * Stop accepting new connections; resolves when in-flight requests
+     * finish. If `gracefulTimeoutMs` is provided, idle keep-alive sockets
+     * still open after that many milliseconds are forcibly destroyed.
+     */
+    close(opts?: CloseOptions): Promise<void>;
+}
+/**
+ * A transport binds the Ingenium dispatch loop to a concrete server
+ * runtime (Node's `node:http`, Bun.serve, etc).
+ */
+interface Transport {
+    /** Wire up the transport with framework-side hooks. Called once by `app.listen()`. */
+    attach(hooks: TransportHooks): void;
+    /** Bind to a port and start accepting requests. */
+    listen(port: number, host?: string): Promise<ListeningServer>;
+}
+
+/**
+ * Minimal OpenAPI 3.1 type surface — just enough for what Ingenium
+ * generates today. Not a full mirror of the spec; we keep it intentionally
+ * narrow so the generator's outputs typecheck without dragging in a
+ * 4000-line ambient module.
+ *
+ * Spec reference: https://spec.openapis.org/oas/v3.1.0
+ *
+ * Intentional gaps (out of scope for v0.0.1, document-as-TODO):
+ * - `callbacks`, `links`, `webhooks` — none of these have a registration
+ *   surface in Ingenium yet.
+ * - `discriminator` / `xml` — schema is passed through verbatim, so callers
+ *   can include these themselves if they want to.
+ * - `pathItems` under `components` — we only emit operations under `paths`.
+ */
+/** Permissive `$ref`-or-inline union used in many slots. */
+type Ref<T> = T | {
+    $ref: string;
+};
+/** A JSON Schema fragment (per OpenAPI 3.1 = full JSON Schema 2020-12). */
+type Schema = Record<string, unknown>;
+/** Where a parameter lives. Ingenium only emits `path` from route syntax. */
+type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
+interface Parameter {
+    name: string;
+    in: ParameterLocation;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: Schema;
+    example?: unknown;
+    examples?: Record<string, Example>;
+    /** Free-form passthrough so callers can stamp `x-*` extensions. */
+    [extension: `x-${string}`]: unknown;
+}
+interface Example {
+    summary?: string;
+    description?: string;
+    value?: unknown;
+    externalValue?: string;
+}
+interface MediaType {
+    schema?: Schema;
+    example?: unknown;
+    examples?: Record<string, Example>;
+}
+interface RequestBody {
+    description?: string;
+    required?: boolean;
+    content: Record<string, MediaType>;
+}
+interface Response {
+    description: string;
+    headers?: Record<string, Ref<Header>>;
+    content?: Record<string, MediaType>;
+}
+interface Header {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: Schema;
+}
+interface SecurityRequirement {
+    [name: string]: string[];
+}
+interface Operation {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    parameters?: Parameter[];
+    requestBody?: RequestBody;
+    responses?: Record<string, Response>;
+    deprecated?: boolean;
+    security?: SecurityRequirement[];
+    /** Free-form passthrough so callers can stamp `x-*` extensions. */
+    [extension: `x-${string}`]: unknown;
+}
+type PathItem = Partial<Record<'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options' | 'trace', Operation>> & {
+    summary?: string;
+    description?: string;
+    parameters?: Parameter[];
+};
+interface Server {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        enum?: string[];
+        description?: string;
+    }>;
+}
+interface Tag {
+    name: string;
+    description?: string;
+}
+interface Info {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+        identifier?: string;
+    };
+    summary?: string;
+}
+interface Components {
+    schemas?: Record<string, Schema>;
+    responses?: Record<string, Response>;
+    parameters?: Record<string, Parameter>;
+    examples?: Record<string, Example>;
+    requestBodies?: Record<string, RequestBody>;
+    headers?: Record<string, Header>;
+    securitySchemes?: Record<string, SecurityScheme>;
+}
+/**
+ * Loose security-scheme type — we do not interpret this, we pass it through
+ * verbatim to `components.securitySchemes`. Use the OpenAPI spec's full
+ * shape (apiKey / http / oauth2 / openIdConnect / mutualTLS).
+ */
+type SecurityScheme = Record<string, unknown>;
+interface OpenApiSpec {
+    openapi: '3.1.0';
+    info: Info;
+    servers?: Server[];
+    paths: Record<string, PathItem>;
+    components?: Components;
+    security?: SecurityRequirement[];
+    tags?: Tag[];
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+}
+
+/**
+ * Per-route metadata supplied via `app.describe('METHOD', '/path', meta)`.
+ * Merged into the generated Operation by `generateOpenApi`.
+ *
+ * Anything you put here ends up on the operation object verbatim, except:
+ * - `hidden: true` skips the route entirely (won't appear in the spec).
+ * - `parameters` are *appended* to the path-param parameters extracted from
+ *   the route syntax, so you typically only put `query`, `header`, or
+ *   `cookie` parameters here.
+ */
+interface RouteDescriptor {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    hidden?: boolean;
+    parameters?: Parameter[];
+    requestBody?: RequestBody;
+    responses?: Record<string | number, Response>;
+    security?: SecurityRequirement[];
+    /** Extension passthrough — anything starting with `x-` is preserved. */
+    [extension: `x-${string}`]: unknown;
+}
+
+/**
+ * A single named background queue. Wraps a {@link QueueStore} with a worker
+ * pool, retry/backoff logic, pause/resume controls, and a `drain()` for
+ * graceful shutdown.
+ *
+ * The pool is event-driven: when a slot frees up, the queue immediately
+ * tries to pull another job; if none is ready (empty or all delayed), the
+ * pool sleeps until either:
+ *   - a new `add()` call wakes it, or
+ *   - the earliest delayed job's `notBefore` elapses (timer-based wake).
+ *
+ * All timers are `unref()`'d so the queue alone never keeps the event loop alive.
+ */
+declare class IngeniumQueue<TData = unknown> {
+    readonly name: string;
+    private readonly store;
+    private readonly worker;
+    private readonly retries;
+    private readonly concurrency;
+    private readonly onFailed;
+    /** Active worker slot count. When `< concurrency`, pull more work. */
+    private active;
+    /** Whether `pause()` has been called and `resume()` not yet. */
+    private paused;
+    /** Whether `drain()`/close has been called. No new jobs accepted. */
+    private closed;
+    /** Timer for waking the pool when a delayed retry becomes due. */
+    private wakeTimer;
+    /** Resolvers waiting for `active` to hit 0 (used by `drain()`). */
+    private idleWaiters;
+    /** Set when the pool is started — protects against double-start. */
+    private started;
+    constructor(name: string, opts: QueueOptions<TData>, worker: QueueWorker<TData>);
+    /**
+     * Start the worker pool. Idempotent — safe to call multiple times. The
+     * pool is also implicitly started by the first `add()` call so direct
+     * invocation is optional.
+     */
+    start(): void;
+    /** Enqueue a job. Returns the assigned id. */
+    add(data: TData): Promise<{
+        id: string;
+    }>;
+    /** Approximate number of pending jobs. */
+    size(): Promise<number>;
+    /** Number of jobs in the dead-letter list. */
+    failedCount(): Promise<number>;
+    /**
+     * Empty the dead-letter list. Only effective when the underlying store
+     * is the default {@link MemoryQueueStore}; custom stores should provide
+     * their own clearing surface.
+     */
+    clearFailed(): void;
+    /**
+     * Stop pulling new jobs from the store. In-flight jobs continue to run
+     * until they complete. Idempotent.
+     */
+    pause(): void;
+    /** Resume pulling jobs. Wakes the pool. */
+    resume(): void;
+    /**
+     * Wait for all in-flight jobs to complete, then stop accepting new ones.
+     * If `timeoutMs` elapses first, resolve anyway — the orphaned jobs keep
+     * running until they naturally finish (JS can't cancel a Promise), but
+     * the framework stops waiting.
+     *
+     * Returns `true` if the queue drained cleanly; `false` on timeout.
+     */
+    drain(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Pump the pool: while we have free slots and we're not paused, pull jobs
+     * and dispatch them. No-op when paused / saturated. Re-entrant: every
+     * job completion calls `pump()` again to fill the slot.
+     */
+    private pump;
+    /**
+     * Attempts to take one job from the store and run it. Returns `false` if
+     * the store is empty (or all-delayed) so the caller stops looping.
+     *
+     * NOTE: we increment `active` BEFORE the async `next()` resolves so a
+     * burst of synchronous `pump()` calls doesn't over-subscribe the pool.
+     * We decrement on the `null` path.
+     */
+    private tryFillSlot;
+    private runOne;
+    private safeFail;
+    /**
+     * If the store has only delayed entries (e.g. just-retried jobs whose
+     * backoff hasn't elapsed), schedule a one-shot wake when the earliest
+     * delay fires so we don't spin or sleep forever.
+     *
+     * Only the default in-memory store exposes `earliestPendingAt`; for
+     * custom stores we don't poll — we rely on the next `add()` to wake us.
+     */
+    private scheduleDelayedWake;
+    private clearWakeTimer;
+    private checkIdle;
+}
+
+/**
+ * Maps queue names → {@link IngeniumQueue} instances. Held by `IngeniumApp`,
+ * mirroring the shape of {@link CronRegistry}.
+ *
+ * Lookup is O(1). Names must be unique within an app — re-registering the
+ * same name throws (mirrors how `app.get('/users')` would conflict if you
+ * registered the same path twice with the same method).
+ */
+declare class QueueRegistry {
+    private readonly queues;
+    /**
+     * Register a new queue. Returns the created instance. Throws if a queue
+     * with `name` is already registered.
+     */
+    register<TData>(name: string, opts: QueueOptions<TData>, worker: QueueWorker<TData>): IngeniumQueue<TData>;
+    /** Look up a queue. Throws if not registered (typos surface immediately). */
+    get<TData = unknown>(name: string): IngeniumQueue<TData>;
+    /** Has a queue with this name been registered? */
+    has(name: string): boolean;
+    /** Number of registered queues. */
+    count(): number;
+    /** All registered queue names (insertion order). */
+    names(): string[];
+    /**
+     * Start the worker pool of every registered queue. Called by the app's
+     * composition step so workers don't process jobs before the app is ready.
+     */
+    startAll(): void;
+    /**
+     * Drain every queue concurrently. Resolves when all queues either finish
+     * their in-flight work or hit `timeoutMs`. The returned object reports
+     * which queues drained cleanly vs timed out — useful for shutdown logs.
+     */
+    drainAll(timeoutMs?: number): Promise<{
+        clean: string[];
+        timedOut: string[];
+    }>;
+}
+
+/**
+ * Handler signature for `app.cron(...)` jobs. Receives the scheduled fire
+ * time AND a fresh `now` so handlers can detect drift / late starts.
+ */
+type CronHandler = (ctx: {
+    now: Date;
+    firedAt: Date;
+}) => unknown | Promise<unknown>;
+/** Options for {@link IngeniumCronJob}. */
+interface CronOptions {
+    /** IANA timezone for the spec. Default `'UTC'`. */
+    timezone?: string;
+    /**
+     * If `true`, fire once at `start()` BEFORE waiting for the next scheduled
+     * slot. The synthetic `firedAt` for this immediate run is `now`. Default `false`.
+     */
+    runOnStart?: boolean;
+    /**
+     * Behavior when a previous run is still in flight at the next fire time.
+     *   - `'skip'`  → drop the new tick (default).
+     *   - `'queue'` → queue ONE pending run; subsequent ticks during the same
+     *      pile-up still drop. (We don't do unbounded queuing; that's an
+     *      anti-pattern that hides bugs.)
+     */
+    overlap?: 'skip' | 'queue';
+    /** Optional name for logs / introspection. Defaults to the original spec. */
+    name?: string;
+}
+/**
+ * A single scheduled cron job. Owns its parsed spec, a `setTimeout`-based
+ * one-shot rescheduler, and bookkeeping for in-flight runs.
+ *
+ * Lifecycle: `start()` arms the first timer; `stop()` cancels it. The
+ * timer is `unref()`'d so a registered cron alone never keeps the event
+ * loop alive — production apps that have an HTTP listener will keep
+ * running normally; standalone scripts will exit when other work finishes.
+ */
+declare class IngeniumCronJob {
+    readonly name: string;
+    readonly spec: string;
+    readonly timezone: string;
+    readonly overlap: 'skip' | 'queue';
+    private readonly match;
+    private readonly handler;
+    private readonly runOnStart;
+    private timer;
+    private inFlight;
+    private queuedRun;
+    private nextAt;
+    private started;
+    private stopped;
+    constructor(spec: string, opts: CronOptions, handler: CronHandler);
+    /** Arm the scheduler. Idempotent. */
+    start(): void;
+    /** Cancel the scheduler. In-flight runs continue until they naturally finish. */
+    stop(): void;
+    /** Next scheduled fire time, or `null` if not started / stopped. */
+    nextRunAt(): Date | null;
+    /** Are there currently any in-flight invocations of the handler? */
+    isRunning(): boolean;
+    /** @internal Test helper — does this job have its wake timer armed? */
+    hasArmedTimer(): boolean;
+    private scheduleNext;
+    private dispatch;
+    private runOnce;
+}
+
+/**
+ * Holds every registered {@link IngeniumCronJob} for an app. Mirrors the shape
+ * of `QueueRegistry` so the integration in `IngeniumApp` is symmetric.
+ *
+ * Cron jobs are NOT auto-started on registration — `startAll()` runs at
+ * compose time so handlers don't fire before the app is ready (e.g. before
+ * `app.decorate()` plugins have wired up `ctx`-style state the handler may
+ * inspect via the registry from another code path).
+ */
+declare class CronRegistry {
+    private readonly jobs;
+    private started;
+    /** Register a new cron job. Returns the job for advanced introspection. */
+    register(spec: string, opts: CronOptions, handler: CronHandler): IngeniumCronJob;
+    /** Number of registered jobs. */
+    count(): number;
+    /** All registered job names (insertion order). */
+    names(): string[];
+    /** Start every registered job. Idempotent. */
+    startAll(): void;
+    /** Stop every registered job. In-flight handlers continue until they finish. */
+    stopAll(): void;
+}
+
+/** Options accepted by `ingenium(...)` and `new IngeniumApp(...)`. */
+interface IngeniumAppOptions {
+    /** Max number of pooled `IngeniumContext` instances kept in the free list. Default 1024. */
+    poolSize?: number;
+    /** Inject a custom transport (e.g. for tests). Default: `NodeAdapter`. */
+    transport?: Transport;
+    /**
+     * Trust-proxy configuration — controls whether `X-Forwarded-For`,
+     * `X-Forwarded-Proto`, `X-Forwarded-Host` are honored when computing
+     * `ctx.ip`, `ctx.protocol`, `ctx.hostname`. Mirrors Express's
+     * `app.set('trust proxy', ...)` semantics. Default `false` (never trust).
+     * See `proxy/trust.ts` for the full type. Set to `true` only when running
+     * behind a reverse proxy you control.
+     */
+    trustProxy?: TrustProxy;
+    /**
+     * Maximum wall-clock time (ms) for a single request to complete from
+     * dispatch to response. When exceeded, throws `IngeniumTimeoutError(503)`
+     * and the response becomes 503 Service Unavailable.
+     *
+     * The handler that timed out is NOT cancelled — JavaScript can't safely
+     * cancel a Promise. The framework just stops waiting for it; the in-flight
+     * work continues until it naturally completes or the process exits. This
+     * means a slow handler can still leak compute (but not connections or
+     * pool slots, since the response is sent and the context is released).
+     *
+     * Scoped to HTTP request handling only — does NOT apply to upgraded
+     * connections (WebSocket, SSE) which are explicitly long-lived.
+     *
+     * Default: undefined (no timeout). Production deploys SHOULD set this.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Hard ceiling (bytes) on the total request body, enforced at the
+     * transport layer — applies regardless of which `ctx.body.*` consumer
+     * reads the body, including `ctx.body.stream()`. Defaults to **2 MiB**
+     * (2_097_152) — high enough for typical JSON / form payloads,
+     * low enough that an unauthenticated attacker can't exhaust memory.
+     *
+     * Per-call limits on `ctx.body.json(schema, maxBytes)` etc. are still
+     * honored and apply WITHIN this ceiling. To allow larger uploads on a
+     * specific route, raise this AND use `ctx.body.stream()` with your own
+     * size accounting.
+     *
+     * Set to `Infinity` to disable (NOT recommended outside controlled deploys).
+     */
+    maxRequestBytes?: number;
+    /**
+     * Default queue-drain timeout (ms) used when the listener closes. Per-queue
+     * timeouts can also be passed to `app.queues.drainAll(timeoutMs)`. Default
+     * `10_000`ms — matches `gracefulShutdown`'s default `gracefulTimeoutMs`.
+     */
+    queueDrainTimeoutMs?: number;
+    /**
+     * Secret(s) used to HMAC-sign cookies written via
+     * `ctx.cookies.set(name, value, { signed: true })`.
+     *
+     * Accepts a single string or an array — the FIRST entry signs new cookies,
+     * ALL entries verify reads (so rotating a secret is: prepend the new key,
+     * keep the old key, deploy; remove the old key on the next deploy once all
+     * outstanding signed cookies have expired).
+     *
+     * If omitted, calling `ctx.cookies.set(..., { signed: true })` or
+     * `ctx.cookies.get(..., { signed: true })` throws
+     * `IngeniumError(500, 'COOKIE_SECRET_MISSING')`. The unsigned cookie API
+     * still works without any secrets configured.
+     */
+    cookieSecrets?: string | string[];
+}
+/** A user-supplied error handler. Return a non-error or call a `ctx` writer to recover. */
+type IngeniumErrorHandler = (err: unknown, ctx: IngeniumContext) => unknown | Promise<unknown>;
+/**
+ * Options for {@link IngeniumApp.inject} — the in-process test client. Mirrors
+ * the shape a real request would carry, minus a socket. `url` is the only
+ * required field; everything else defaults to a bare GET.
+ */
+interface InjectRequest {
+    /** HTTP method. Defaults to `GET`. */
+    method?: HttpMethod;
+    /** Request URL including any query string (e.g. `/users/42?expand=posts`). */
+    url: string;
+    /**
+     * Request headers. Names are lowercased before they reach the handler so
+     * `ctx.headers['x-custom']` works regardless of the casing passed here
+     * (matching node:http's lowercasing of inbound headers).
+     */
+    headers?: Record<string, string | string[]>;
+    /**
+     * Request body. A `string` / `Buffer` / `Uint8Array` is sent verbatim; a
+     * plain object is JSON-serialized and (unless the caller set a
+     * `content-type`) tagged `application/json`.
+     */
+    body?: string | Buffer$1 | Uint8Array | Record<string, unknown> | unknown[];
+    /** Socket peer address surfaced as `ctx.remoteAddress`. Defaults to `127.0.0.1`. */
+    remoteAddress?: string;
+}
+/**
+ * Result of {@link IngeniumApp.inject}. A fully-materialized snapshot of the
+ * response — captured BEFORE the pooled context is released, so reading any
+ * field is safe even though the underlying context has been recycled.
+ */
+interface InjectResponse {
+    /** Final HTTP status code. */
+    status: number;
+    /**
+     * Response headers, lowercased. A deep-ish copy of the context's header bag
+     * (the array values are cloned) so sequential `inject()` calls never share
+     * or bleed header state.
+     */
+    headers: Record<string, string | string[]>;
+    /**
+     * Response body decoded as a UTF-8 string. Stream responses are drained to
+     * completion first; a bodyless response (`{ kind: 'none' }`) yields `''`.
+     */
+    body: string;
+    /** Parse {@link InjectResponse.body} as JSON. Throws on invalid JSON, like `JSON.parse`. */
+    json<T = unknown>(): T;
+}
+/**
+ * Per-route options object accepted as the second positional arg to a verb
+ * registration (`app.get(path, { auth: ['admin'] }, handler)`). Each key must
+ * match a registered declarator (see `app.declare(...)`); the value is passed
+ * to the declarator's factory at REGISTRATION time and the resulting
+ * middleware is prepended to the route's chain.
+ */
+type RouteOptions = Record<string, unknown>;
+/**
+ * The Ingenium application. Combines a `Router` (registration journal),
+ * a `RouterTrie` (matched at request time), a context pool, and a
+ * transport. Composition is lazy: the trie's composed handlers are built
+ * on first request (or when `compose()` is called explicitly), and a dirty
+ * bit triggers recomposition if registrations are added later.
+ */
+declare class IngeniumApp implements PluginTarget {
+    private readonly pool;
+    private readonly transport;
+    private readonly router;
+    private trie;
+    private dirty;
+    private errorHandler;
+    private readonly _hooks;
+    private readonly _decorators;
+    /** @internal Per-route OpenAPI metadata. Keyed by `${method} ${path}`. */
+    private readonly _routeDescriptors;
+    /** @internal Bumped on every `describe()` call so the OpenAPI handler's cache invalidates. */
+    private _routeDescriptorVersion;
+    /** @internal Carried onto each `IngeniumContext` so its `ip`/`protocol`/`hostname` getters can resolve. */
+    private readonly _trustProxy;
+    /** @internal Wall-clock per-request ceiling. `undefined` disables the race entirely. */
+    private readonly _requestTimeoutMs;
+    /**
+     * @internal Hard transport-layer ceiling on request body bytes. Passed to
+     * the transport via `TransportHooks.maxRequestBytes`. `Infinity` disables.
+     */
+    private readonly _maxRequestBytes;
+    /** @internal Background job registry. Workers start at compose() / first request. */
+    private readonly _queues;
+    /** @internal Cron job registry. Timers start at compose() / first request. */
+    private readonly _crons;
+    /** @internal Default queue-drain timeout used when the listener closes. */
+    private readonly _queueDrainTimeoutMs;
+    /**
+     * @internal Frozen list of cookie-signing secrets, normalized from the
+     * scalar/array input. Empty array when not configured. Stamped onto each
+     * dispatched context only when non-empty (per-request field write avoided
+     * for the common case of "no cookie secrets configured").
+     */
+    private readonly _cookieSecrets;
+    /** @internal Whether `cookieSecrets` was configured — caches the truthy check. */
+    private readonly _hasCookieSecrets;
+    /**
+     * @internal Per-request dispatch booleans, recomputed at every `compose()`.
+     * Cached because their underlying `.hasAny()` / `.hasOnXxx()` calls walk
+     * arrays and we don't want to pay that on every request — the registries
+     * are frozen between composes.
+     *
+     * `_handleFast` is the hot-path closure: when ALL of these are off
+     * (`!_hasHooks && !_hasDecorators && !_hasTimeout && !_hasTrustProxy`)
+     * we route through a stripped dispatch that skips every conditional.
+     */
+    private _hasHooks;
+    private _hasOnRequest;
+    private _hasOnResponse;
+    private _hasOnError;
+    private _hasDecorators;
+    private readonly _hasTimeout;
+    private readonly _hasTrustProxy;
+    private _useFastPath;
+    /**
+     * @internal Whether `listen()` has bound a server that hasn't been closed
+     * yet. Guards against the double-listen footgun: a second `listen()` on the
+     * same app would silently bind a second server (two ports dispatching to one
+     * pool), almost always a copy-paste mistake. Cleared when the returned
+     * handle's `close()` resolves, so re-listening after a clean shutdown works.
+     */
+    private _listening;
+    constructor(options?: IngeniumAppOptions);
+    /**
+     * @internal Recompute the cached dispatch booleans. Called at the end of
+     * `compose()` (and `composeAsync()`) so per-request reads are O(1) field
+     * loads instead of `.hasAny()` array scans.
+     *
+     * The fast path is taken when an app uses zero opt-in features beyond the
+     * router itself: no plugins, no decorators, no request timeout, no
+     * trust-proxy. That's the typical "Sinatra-shape" / "Express-shape"
+     * register-routes-and-go app — the case we want to be the absolute fastest.
+     * Note `ctx.queue` registers a decorator at construction, so any app that
+     * uses background jobs is OFF the fast path. That's the correct semantics:
+     * if you want the queue ergonomic, you accept the per-request decorator
+     * apply cost.
+     */
+    private _recomputeDispatchFlags;
+    /** Lifecycle hooks API — plugins call `app.hooks.onRequest(...)` etc. */
+    get hooks(): Hooks;
+    /**
+     * Register a plugin. Plugins are invoked immediately and may be async;
+     * callers should `await app.register(...)` if the plugin returns a Promise.
+     * Plugins must be registered BEFORE `compose()` runs (i.e. before the
+     * first request); registering a plugin sets the dirty bit so the next
+     * request will recompose.
+     */
+    register<O>(plugin: IngeniumPlugin<O>, opts: O): Promise<this>;
+    register(plugin: IngeniumPlugin<void>): Promise<this>;
+    /**
+     * Open a registration scope rooted at `prefix`. Routes, middleware, and
+     * sub-plugins registered through the `scope` parameter inside `registrar`
+     * are automatically prefix-qualified, so a plugin's `use(mw)` only applies
+     * to requests under `prefix` — not the whole app.
+     *
+     * This is the killer feature for sub-app affinity: today, plugins registered
+     * via `app.register(...)` decorate the WHOLE app (their `app.use(mw)` calls
+     * become global). Wrapping a `register(...)` call inside `app.scope(...)`
+     * confines the plugin's middleware to the scope's subtree, without forcing
+     * the user to manually prefix every route.
+     *
+     * The actual prefix-matching happens at compose time: scope translates
+     * `s.use(mw)` into `app.use(prefix, mw)` on the underlying router, which
+     * the existing `flattenRouter` / `RouterTrie` machinery already handles.
+     * Per-request dispatch sees no new work.
+     *
+     * @example
+     * app.scope('/api/v2', (s) => {
+     *   s.use(authPlugin)          // only runs for /api/v2/*
+     *   s.get('/users', listUsers) // registers at /api/v2/users
+     * })
+     *
+     * Nested scopes compose:
+     *
+     * @example
+     * app.scope('/api', (s) => {
+     *   s.scope('/v2', (s2) => {
+     *     s2.get('/users', listUsers) // /api/v2/users
+     *   })
+     * })
+     *
+     * # Caveat — decorators (V1)
+     *
+     * `scope.decorate(...)` decorates EVERY request, not just requests under
+     * `prefix`. Decorators install onto the pooled context at request start,
+     * before the route is matched. The first call from inside any scope emits
+     * a `process.emitWarning` in non-production environments to surface this.
+     * See `ScopedApp` for details.
+     *
+     * @returns `this` for chaining. If `registrar` is async, the returned
+     * promise is NOT awaited — callers who need async plugin registration
+     * inside a scope should await the `registrar` themselves (or use
+     * `scope.register(asyncPlugin)`, which returns a Promise).
+     */
+    scope(prefix: string, registrar: (scope: PluginTarget) => void): this;
+    /**
+     * @internal Mark the compose-cache dirty. Used by `ScopedApp` to invalidate
+     * after registering routes/middleware/plugins inside a scope. External
+     * callers should not depend on this — it's a friend-access seam for the
+     * scope facade.
+     */
+    _markDirty(): void;
+    /**
+     * Add a lazy decorator. The factory is invoked the first time `ctx[name]`
+     * is read; the result is cached on the context for the rest of the request.
+     *
+     * @example
+     * app.decorate('user', async (ctx) => loadUser(ctx.headers.authorization))
+     */
+    decorate<T>(name: string, factory: LazyDecorator<T>): this;
+    /**
+     * Add an eager decorator. The factory runs at the start of every request,
+     * and the value is assigned directly to the context.
+     *
+     * @example
+     * app.decorateRequest('startedAt', () => Date.now())
+     */
+    decorateRequest<T>(name: string, factory: EagerDecorator<T>): this;
+    use(mw: IngeniumMiddleware): this;
+    use(prefix: string, mw: IngeniumMiddleware | Router): this;
+    get(path: string, handler: IngeniumHandler): this;
+    get(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    post(path: string, handler: IngeniumHandler): this;
+    post(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    put(path: string, handler: IngeniumHandler): this;
+    put(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    patch(path: string, handler: IngeniumHandler): this;
+    patch(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    delete(path: string, handler: IngeniumHandler): this;
+    delete(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    head(path: string, handler: IngeniumHandler): this;
+    head(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    options(path: string, handler: IngeniumHandler): this;
+    options(path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    /**
+     * Chainable per-path registration. Returns a `RouteBuilder` that stacks
+     * verb registrations on the same path without retyping it:
+     *
+     * @example
+     *   app
+     *     .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 `app.method(...)`, so
+     * declarative options, inline middleware, and typed params via
+     * `ExtractParams<P>` work exactly as they do on the bare verb form.
+     */
+    route<P extends string>(path: P): RouteBuilder<P>;
+    /**
+     * Register a route under any HTTP method. Accepts the variadic shape with
+     * an optional declarative-options object as the first arg (after `path`).
+     */
+    method(method: HttpMethod, path: string, handler: IngeniumHandler): this;
+    method(method: HttpMethod, path: string, optsOrFirst: RouteOptions | IngeniumMiddleware, ...rest: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    /**
+     * @internal Registry of declarators. Looked up at REGISTRATION time, not
+     * request time — so unknown-declarator errors fire eagerly and the per-
+     * request hot path stays clean.
+     */
+    private readonly _declarators;
+    /**
+     * Register a declarator: a name → middleware-factory mapping. When a route
+     * registration includes an options object with that name as a key, the value
+     * is passed to the factory and the resulting middleware is composed into
+     * the route's chain (in the same position as positional inline middleware,
+     * but BEFORE any positional middleware on the same call).
+     *
+     * Declarators are global to the app and survive across all subsequent route
+     * registrations until overridden by a second `declare(name, ...)` call.
+     * Lookup is REGISTRATION-time: a route registered before the matching
+     * `declare(...)` call throws at registration with a clear hint, not at
+     * request time. This trades flexibility for debuggability — the error is
+     * caught at boot, not under load.
+     *
+     * @example
+     *   app.declare('auth', (roles: string[]) => requireRoles(roles))
+     *   app.declare('rateLimit', (spec: string) => parseRateLimitSpec(spec))
+     *   app.get('/admin', { auth: ['admin'], rateLimit: '10/min' }, handler)
+     */
+    declare<O>(name: string, factory: (opts: O) => IngeniumMiddleware): this;
+    /**
+     * @internal Resolve a route's options object into a list of middleware by
+     * looking up each key in the declarator registry. Iterates keys in object
+     * insertion order (ES2015+ guarantee for string keys). Throws at REG TIME
+     * with a contextual message when a key has no registered declarator.
+     */
+    private translateRouteOptions;
+    /** Register a global error handler. Re-throw to delegate to the default boundary. */
+    onError(handler: IngeniumErrorHandler): this;
+    /**
+     * Register a `before` filter — runs BEFORE the route handler resolves.
+     * The user writes only the body; `await next()` is called automatically
+     * after it returns. If the body writes a response (e.g. `ctx.json(...)`)
+     * the chain short-circuits and the route handler does not run.
+     *
+     * - `before(handler)` — runs for every request (global).
+     * - `before(pattern, handler)` — boundary-respecting prefix match
+     *   (`/admin/*` and `/admin` both match `/admin` and `/admin/x`, neither
+     *   matches `/administrator`). See `sinatra/filters.ts` for details.
+     */
+    before(handler: IngeniumMiddleware): this;
+    before(pattern: string, handler: IngeniumMiddleware): this;
+    /**
+     * Register an `after` filter — runs AFTER the route handler resolves but
+     * BEFORE the adapter writes the response to the wire. The filter sees the
+     * final ctx state (status, headers, body buffer) and may inspect or
+     * augment it. Errors thrown by the filter propagate to the error boundary.
+     *
+     * - `after(handler)` — runs for every request (global).
+     * - `after(pattern, handler)` — same prefix semantics as `before`.
+     */
+    after(handler: IngeniumMiddleware): this;
+    after(pattern: string, handler: IngeniumMiddleware): this;
+    /**
+     * Attach OpenAPI metadata to a route. The route must be registered separately
+     * via `app.get/post/...`. Multiple calls MERGE shallowly onto the existing
+     * descriptor for the same `(method, path)` pair — later keys overwrite
+     * earlier ones, but keys absent from `meta` are preserved. This is what lets
+     * the inline-options form (`app.get(p, { tags: [...] }, h)`) coexist with a
+     * later explicit `app.describe(method, p, { summary })` without one wiping
+     * the other. Reads via `generateOpenApi(app)`.
+     */
+    describe(method: HttpMethod, path: string, meta: RouteDescriptor): this;
+    /** @internal Read-only view of route descriptors — used by the OpenAPI generator. */
+    get routeDescriptors(): ReadonlyMap<string, RouteDescriptor>;
+    /** @internal Bumps on every `describe()` call so the OpenAPI handler can cache-bust. */
+    get routeDescriptorVersion(): number;
+    /** @internal Read-only view of the registration journal — used by the OpenAPI generator. */
+    get routerJournal(): Router;
+    /**
+     * Register a background queue with a worker. The worker pool starts when
+     * the app is composed (first request, `app.compose()`, or `app.listen()`).
+     *
+     * @example
+     * app.queue<{ to: string; body: string }>('emails',
+     *   { concurrency: 4, retries: 5 },
+     *   async (job) => sendEmail(job.data),
+     * )
+     *
+     * // From a route handler:
+     * app.post('/signup', async (ctx) => {
+     *   const u = await createUser(await ctx.body.json())
+     *   await ctx.queue('emails').add({ to: u.email, body: 'Welcome!' })
+     *   return { ok: true }
+     * })
+     */
+    queue<TData>(name: string, opts: QueueOptions<TData>, worker: QueueWorker<TData>): this;
+    queue<TData>(name: string, worker: QueueWorker<TData>): this;
+    /**
+     * Register a cron job. Spec is a 5-field crontab string. See
+     * `src/cron/parser.ts` for the supported grammar.
+     *
+     * @example
+     * app.cron('0 *\/15 * * *', () => refreshCaches())   // every 15 min
+     * app.cron('0 0 * * 0', { timezone: 'America/Los_Angeles' }, weeklyReport)
+     */
+    cron(spec: string, handler: CronHandler): this;
+    cron(spec: string, opts: CronOptions, handler: CronHandler): this;
+    /** @internal Read-only access to the queue registry for ops/test introspection. */
+    get queues(): QueueRegistry;
+    /** @internal Read-only access to the cron registry for ops/test introspection. */
+    get crons(): CronRegistry;
+    /**
+     * Walk the registration journal and rebuild the trie with composed
+     * handlers at every leaf. Auto-runs on first request; safe to call
+     * explicitly to pre-warm.
+     */
+    /** Cached flat registrations — used to build the on-miss fallback chain. */
+    private _flat;
+    compose(): void;
+    /**
+     * Async composition entry — runs `onCompose` hooks first, then composes.
+     * Used by `handle()` and `listen()` when there are async pre-compose
+     * listeners. Sync-only composition still works via `compose()` above.
+     */
+    private composeAsync;
+    /**
+     * Dispatch a single context through the framework. Handles route lookup,
+     * 404/405 generation, and the error boundary. The transport is responsible
+     * for populating the request side of the context and writing the response
+     * side after this resolves.
+     */
+    handle(ctx: IngeniumContext): Promise<void>;
+    /**
+     * Run global + path-matching scoped middleware as a fallback chain when the
+     * trie has no matching route. The terminal handler re-throws the original
+     * trie miss so the error boundary still produces 404/405 if no middleware
+     * wrote the response. Composed per-request — misses are exceptional.
+     */
+    private runFallback;
+    private handleError;
+    /**
+     * Dispatch a synthetic request through the SAME path as the wire — no
+     * socket, no transport. Acquires a pooled context, populates it exactly as
+     * the Node adapter would from an `IncomingMessage`, runs `handle()` (so
+     * routing, 404/405, middleware, hooks, and the error boundary all behave
+     * identically), then materializes the response into a plain {@link InjectResponse}.
+     *
+     * Crucially the context is extracted FULLY and only THEN released back to
+     * the pool: releasing bumps `_epoch` and reassigns `_headers`/`_body`, so
+     * reading them after release would surface the next request's state (or
+     * empty). The returned object holds copies, so it survives the recycle and
+     * sequential `inject()` calls never bleed header/body state into each other.
+     *
+     * @example
+     *   const res = await app.inject({ method: 'POST', url: '/users', body: { name: 'a' } })
+     *   expect(res.status).toBe(201)
+     *   expect(res.json<{ id: string }>().id).toBeDefined()
+     */
+    inject(opts: InjectRequest): Promise<InjectResponse>;
+    /** Bind a port and accept requests. Returns a handle for graceful shutdown. */
+    listen(port: number, host?: string): Promise<ListeningServer>;
+}
+/**
+ * Factory function. Mirrors the `express()` ergonomics — `ingenium(...)` returns
+ * a new app, and the function carries the body-parser middleware factories
+ * plus a `Router` constructor as static properties.
+ */
+interface IngeniumFactory {
+    (options?: IngeniumAppOptions): IngeniumApp;
+    Router: () => Router;
+}
+
+/**
+ * Express compatibility shim. In Ingenium, body parsing is lazy via
+ * `ctx.body.json()` / `ctx.body.urlencoded()` / `ctx.body.text()` — there is
+ * no parse-on-every-request middleware to register. This factory exists so
+ * existing `app.use(express.json())` migration patterns keep compiling and
+ * reading naturally; the returned middleware is a zero-cost no-op.
+ *
+ * If you need to enforce a default `maxBytes` across all body access, set it
+ * via the `limit` option here and read it inside your handlers when calling
+ * `ctx.body.json({ limit })` — Ingenium doesn't store it implicitly.
+ *
+ * @returns a no-op middleware
+ */
+declare function jsonMiddleware(_opts?: {
+    limit?: number;
+}): IngeniumMiddleware;
+/**
+ * See `jsonMiddleware` — same rationale. URL-encoded parsing is lazy via
+ * `ctx.body.urlencoded()`.
+ */
+declare function urlencodedMiddleware(_opts?: {
+    limit?: number;
+}): IngeniumMiddleware;
+
+/**
+ * Options for the `ingenium.static` middleware.
+ */
+interface StaticOptions {
+    /**
+     * The file to serve when a directory is requested. Set to `false` to
+     * disable directory-index resolution. Default: `'index.html'`.
+     */
+    index?: string | false;
+    /**
+     * `Cache-Control: max-age=<seconds>` to set on served files, in
+     * MILLISECONDS (Express convention). Default: `0` (no caching).
+     */
+    maxAge?: number;
+    /**
+     * Extensions to try (in order) when the requested path doesn't exist.
+     * For example, `['html']` lets `/about` resolve to `/about.html`.
+     * Default: `[]` (off).
+     */
+    extensions?: string[];
+    /**
+     * How to treat files / directories whose name starts with `.`:
+     * - `'allow'`  — serve normally
+     * - `'deny'`   — respond with 403
+     * - `'ignore'` — call `next()` (let routes 404 it). DEFAULT.
+     */
+    dotfiles?: 'allow' | 'deny' | 'ignore';
+}
+
+/**
+ * Static-file middleware. Serves files from `root`, supporting directory
+ * indexes, weak ETags, `If-None-Match`, byte-range requests, and basic
+ * dotfile policy. Misses (file not found) call `next()` — they do NOT
+ * write 404 themselves, so downstream routes still get a chance.
+ *
+ * @example
+ *   app.use(ingenium.static('./public', { maxAge: 60_000 }))
+ */
+declare function staticMiddleware(root: string, opts?: StaticOptions): IngeniumMiddleware;
+
+/**
+ * Function form of the `origin` option. Receives the request's `Origin`
+ * header value (always a string — never called when no `Origin` is present)
+ * and the active `IngeniumContext`. May return:
+ *
+ * - `true`  — allow the request, reflect the request's `Origin` back.
+ * - `false` — deny the request (no `Access-Control-Allow-Origin` header set).
+ * - `string` — allow the request, use this exact value as the
+ *   `Access-Control-Allow-Origin` header (use `'*'` for the wildcard).
+ *
+ * May be sync or async.
+ */
+type CorsOriginFn = (origin: string, ctx: IngeniumContext) => boolean | string | Promise<boolean | string>;
+/**
+ * Spec for the `origin` option.
+ *
+ * - `boolean` — `true` reflects any request `Origin`; `false` disables CORS.
+ * - `'*'` — wildcard: `Access-Control-Allow-Origin: *`.
+ * - any other `string` — exact match against the request's `Origin`.
+ * - `string[]` — allowlist; matched exactly.
+ * - `RegExp` — tested against the request's `Origin`.
+ * - `CorsOriginFn` — fully custom predicate (see above).
+ */
+type CorsOrigin = boolean | string | string[] | RegExp | CorsOriginFn;
+/**
+ * Options for `ingenium.cors`. All fields are optional. See README for details.
+ */
+interface CorsOptions {
+    /** Origin policy. Default: `'*'`. */
+    origin?: CorsOrigin;
+    /**
+     * Methods advertised on `Access-Control-Allow-Methods` for preflight.
+     * Default: `['GET','HEAD','PUT','PATCH','POST','DELETE']`.
+     */
+    methods?: string[];
+    /**
+     * Headers advertised on `Access-Control-Allow-Headers` for preflight.
+     * If `undefined`, the value of `Access-Control-Request-Headers` from the
+     * preflight request is mirrored back. Default: `undefined`.
+     */
+    allowedHeaders?: string[];
+    /**
+     * Headers advertised on `Access-Control-Expose-Headers` for simple
+     * responses. Default: `undefined` (header omitted).
+     */
+    exposedHeaders?: string[];
+    /**
+     * If `true`, sets `Access-Control-Allow-Credentials: true`.
+     * Incompatible with `origin: '*'` — throws at construction time.
+     * Default: `false`.
+     */
+    credentials?: boolean;
+    /**
+     * `Access-Control-Max-Age` (seconds). Default: `undefined` (header omitted).
+     */
+    maxAge?: number;
+    /**
+     * Status code for successful preflight responses. Default: `204`.
+     */
+    optionsSuccessStatus?: number;
+}
+
+/**
+ * CORS middleware. Implements the standard CORS protocol (Fetch spec
+ * §3.2.4) for both simple requests and preflight (`OPTIONS` +
+ * `Access-Control-Request-Method`).
+ *
+ * @example
+ *   app.use(ingenium.cors())
+ *   app.use(ingenium.cors({ origin: ['https://app.example.com'], credentials: true }))
+ */
+declare function corsMiddleware(opts?: CorsOptions): IngeniumMiddleware;
+
+/**
+ * A single Server-Sent Event. The `data` field is required; if you pass an
+ * object, it's `JSON.stringify`'d before being written. All other fields are
+ * optional and serialized per the EventSource specification.
+ *
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html
+ */
+interface SseEvent {
+    /** Payload. Strings are written verbatim; objects are JSON-encoded. */
+    data: string | object;
+    /** Optional event name — populates `event:` field. */
+    event?: string;
+    /** Optional event id — populates `id:` field. */
+    id?: string;
+    /** Optional retry hint in milliseconds — populates `retry:` field. */
+    retry?: number;
+}
+/**
+ * Handle for an open SSE connection. Returned by {@link sse}. Use `send()`
+ * to push events, `comment()` for keep-alive frames, and `close()` to end
+ * the response stream cleanly.
+ */
+interface SseStream {
+    /**
+     * Send a single event. A bare string is treated as `{ data: <string> }`.
+     */
+    send(event: SseEvent | string): void;
+    /** Write a comment line (`: <text>`). Useful for heartbeats / keep-alive. */
+    comment(text: string): void;
+    /** End the response stream. Subsequent calls are no-ops. */
+    close(): void;
+    /** Whether the underlying stream has been closed (locally or by the client). */
+    readonly closed: boolean;
+}
+/**
+ * Open a Server-Sent Events response on the given context. Sets the
+ * appropriate headers (`Content-Type: text/event-stream`, no caching, no
+ * proxy buffering) and wires a `PassThrough` into `ctx.stream()`.
+ *
+ * @example
+ *   app.get('/events', (ctx) => {
+ *     const stream = sse(ctx)
+ *     stream.send({ event: 'hello', data: { msg: 'world' } })
+ *     setTimeout(() => stream.close(), 1000)
+ *   })
+ */
+declare function sse(ctx: IngeniumContext): SseStream;
+
+/**
+ * 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.
+ */
+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}.
+ */
+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;
+}
+
+/**
+ * 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 }))
+ */
+declare function rateLimit(opts?: RateLimitOptions): IngeniumMiddleware;
+
+/**
+ * Base error class for all framework-emitted errors. Errors that extend
+ * `IngeniumError` are caught by the global error boundary and serialized to the
+ * client according to their `statusCode` and `code`.
+ */
+declare class IngeniumError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    /**
+     * @param statusCode HTTP status code to send to the client.
+     * @param code Machine-readable error code (UPPER_SNAKE_CASE convention).
+     * @param message Human-readable error message.
+     * @param cause Optional underlying error.
+     */
+    constructor(statusCode: number, code: string, message: string, cause?: unknown | undefined);
+}
+/** 404 — no route matched. */
+declare class IngeniumNotFoundError extends IngeniumError {
+    constructor(message?: string);
+}
+/** 401 — authentication required or invalid. */
+declare class IngeniumUnauthorizedError extends IngeniumError {
+    constructor(message?: string);
+}
+/**
+ * 405 — path matched but method did not. Includes the list of allowed methods,
+ * which the framework writes into the `Allow` response header automatically.
+ */
+declare class IngeniumMethodNotAllowedError extends IngeniumError {
+    readonly allowed: readonly string[];
+    constructor(allowed: readonly string[], message?: string);
+}
+/** 413 — request body exceeded the configured `maxBytes` limit. */
+declare class IngeniumPayloadTooLargeError extends IngeniumError {
+    constructor(message?: string);
+}
+/**
+ * 422 — request body parsed successfully but failed validation. The `fields`
+ * map is serialized into the response body so clients can render field-level
+ * error messages.
+ */
+declare class IngeniumValidationError extends IngeniumError {
+    readonly fields: Record<string, string>;
+    constructor(fields: Record<string, string>, message?: string);
+}
+/** 400 — request was malformed (bad JSON, invalid content-type, etc). */
+declare class IngeniumBadRequestError extends IngeniumError {
+    constructor(message?: string, cause?: unknown);
+}
+/**
+ * 500 — caller attempted to write a header name or value containing CR or
+ * LF. Node would eventually reject these at the wire level, but the late
+ * throw produces a useless stack — we fail fast at the call site so the
+ * offending header (and the route that set it) shows up in the trace.
+ */
+declare class IngeniumHeaderInjectionError extends IngeniumError {
+    constructor(message?: string);
+}
+/**
+ * 500 — `ctx.json` (or `respondJsonWithEtag`) was handed a value that
+ * `JSON.stringify` cannot serialize: a circular structure, a `BigInt`, or
+ * any other unsupported shape. The original `TypeError` is attached as
+ * `cause` and emitted via `process.emitWarning` for diagnostics.
+ */
+declare class IngeniumUnserializableError extends IngeniumError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Sinatra-style `halt` short-circuit. Thrown by `ctx.halt(status, body?)`;
+ * caught by the default error boundary and serialized according to `bodyShape`:
+ *
+ * - `'none'`  → boundary uses default `{ error, code: 'HALT' }` JSON shape.
+ * - `'text'`  → boundary writes `body` as `text/plain` verbatim.
+ * - `'json'`  → boundary writes `body` as `application/json`.
+ *
+ * The body shape is decided at the call site (string ⇒ text, object ⇒ json,
+ * undefined ⇒ none) so the boundary can branch without re-inspecting types.
+ * Custom `app.onError` handlers still receive the error and can override it
+ * (e.g. add a header, reshape the body) by writing the response themselves.
+ */
+declare class IngeniumHaltError extends IngeniumError {
+    /** What the default error boundary should do with `body`. */
+    readonly bodyShape: 'none' | 'text' | 'json';
+    /** The body argument from `ctx.halt(status, body?)`. */
+    readonly body: string | Record<string, unknown> | undefined;
+    constructor(statusCode: number, body?: string | Record<string, unknown>);
+}
+/**
+ * 503 — handler exceeded the configured `requestTimeoutMs` ceiling. The
+ * orphaned handler is NOT cancelled (JavaScript can't safely cancel a
+ * Promise); the framework just stops waiting for it. Late writes from the
+ * orphaned handler are guarded by the per-request epoch counter on the
+ * context and discarded with a `process.emitWarning`.
+ */
+declare class IngeniumTimeoutError extends IngeniumError {
+    constructor(timeoutMs: number, message?: string);
+}
+
+/**
+ * Where the CSRF token lives between requests.
+ *
+ * - `'cookie'` (default): double-submit cookie pattern. Token is generated
+ *   on safe requests, written to a non-HttpOnly cookie, and the client must
+ *   echo it back via a header on unsafe requests. No session required.
+ * - `'session'`: synchronizer pattern. Token is stored on `ctx.session`
+ *   and validated against the submitted token on unsafe requests. Requires
+ *   `sessionMiddleware` to run before this middleware.
+ */
+type CsrfStorage = 'cookie' | 'session';
+/** How to extract the submitted token from an incoming request. */
+type CsrfValueReader = (ctx: IngeniumContext) => string | undefined | Promise<string | undefined>;
+interface CsrfCookieOptions {
+    /** Cookie name. Default `ingenium.csrf`. */
+    name?: string;
+    /** Restrict cookie to a single subpath. Default `/`. */
+    path?: string;
+    /** Restrict cookie to a domain. Default unset. */
+    domain?: string;
+    /** SameSite policy. Default `'lax'`. */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Mark cookie Secure. Default `false`; set `true` behind TLS. */
+    secure?: boolean;
+    /**
+     * Mark cookie HttpOnly. **Default `false`** — clients must read the cookie
+     * to copy the value into the request header. Setting `true` would break the
+     * double-submit pattern; only enable with a custom value reader that pulls
+     * the token from elsewhere.
+     */
+    httpOnly?: boolean;
+    /** Cookie max-age (seconds). Default 7 days. */
+    maxAgeSeconds?: number;
+}
+interface CsrfOptions {
+    /**
+     * HMAC secret used to sign the token. Required for the cookie storage
+     * mode (signed double-submit). For session storage the secret is optional
+     * — the session id already authenticates the binding.
+     */
+    secret?: string | string[];
+    /** Token storage strategy. Default `'cookie'`. */
+    storage?: CsrfStorage;
+    /** Cookie options when `storage === 'cookie'`. */
+    cookie?: CsrfCookieOptions;
+    /** Methods that bypass validation. Default `['GET', 'HEAD', 'OPTIONS', 'TRACE']`. */
+    ignoreMethods?: readonly string[];
+    /**
+     * How to extract the submitted token. Default reads (in order):
+     *   1. `X-CSRF-Token` header
+     *   2. `X-XSRF-Token` header (Angular convention)
+     *   3. `_csrf` query string parameter
+     */
+    value?: CsrfValueReader;
+    /**
+     * Per-request opt-out. Return `true` to skip validation entirely for
+     * this request (and skip token issuance).
+     */
+    skip?: (ctx: IngeniumContext) => boolean | Promise<boolean>;
+}
+
+/** 403 Forbidden — CSRF token missing or mismatched. */
+declare class IngeniumCsrfError extends IngeniumError {
+    constructor(message?: string);
+}
+/**
+ * CSRF protection middleware. Two modes:
+ *
+ * - `storage: 'cookie'` (default) — double-submit cookie pattern. A
+ *   randomly-generated token is HMAC-signed, written to a non-HttpOnly
+ *   cookie on safe requests, and the client must echo the cookie value
+ *   back in a header (`X-CSRF-Token`) on unsafe requests. The signature
+ *   prevents client-side forgery; the same-origin policy prevents
+ *   cross-origin sites from reading the cookie.
+ *
+ * - `storage: 'session'` — synchronizer pattern. The token is stored on
+ *   `ctx.session` and matched against the submitted token. Requires
+ *   `sessionMiddleware` to run before this middleware.
+ *
+ * Use `ctx.state.csrfToken` (or call `(ctx as IngeniumContext & { csrfToken(): string }).csrfToken()`)
+ * to read the current token to embed in HTML forms or send to a JS client.
+ */
+declare function csrfMiddleware(opts?: CsrfOptions): IngeniumMiddleware;
+
+/**
+ * RFC 7807 Problem Details for HTTP APIs.
+ *
+ * The five standard members are reserved by the spec; arbitrary additional
+ * extension members are permitted via the index signature. See
+ * https://datatracker.ietf.org/doc/html/rfc7807#section-3.1.
+ */
+interface ProblemDetails {
+    /**
+     * A URI reference that identifies the problem type. When dereferenced it
+     * SHOULD provide human-readable documentation. Default per spec is
+     * `'about:blank'`, indicating that no specific problem-type URL exists
+     * (in which case `title` is conventionally the HTTP status reason phrase).
+     */
+    type: string;
+    /**
+     * A short, human-readable summary of the problem type. SHOULD NOT change
+     * from occurrence to occurrence (use `detail` for instance-specific info).
+     */
+    title: string;
+    /** HTTP status code generated by the origin server. */
+    status: number;
+    /** Human-readable explanation specific to this occurrence of the problem. */
+    detail?: string;
+    /** A URI reference identifying the specific occurrence of the problem. */
+    instance?: string;
+    /** RFC 7807 permits arbitrary extension members. */
+    [key: string]: unknown;
+}
+/** Options accepted by `ingenium.problemDetails(...)`. */
+interface ProblemDetailsOptions {
+    /**
+     * Prefix used when constructing the `type` URI from an error's `code`.
+     * Example: `'https://api.example.com/errors/'` + `NOT_FOUND` →
+     * `'https://api.example.com/errors/not-found'`.
+     *
+     * Default `'about:blank'` (per spec — no problem-specific docs URL).
+     */
+    typeBaseUrl?: string;
+    /**
+     * If true, attaches the error's `stack` as an extension member. Useful in
+     * development; never enable in production — stack traces leak source paths
+     * and internal structure. Default `false`.
+     */
+    includeStack?: boolean;
+    /**
+     * Override how the `instance` URI is derived. Default returns `ctx.path`.
+     * Return `undefined` to omit the field entirely.
+     */
+    instance?: (ctx: IngeniumContext) => string | undefined;
+}
+/** Options after defaults have been applied. Internal use. */
+interface ResolvedProblemDetailsOptions {
+    typeBaseUrl: string;
+    includeStack: boolean;
+    instance: (ctx: IngeniumContext) => string | undefined;
+}
+
+/**
+ * RFC 7807 Problem Details middleware. Wraps downstream handlers in a
+ * try/catch and serializes any `IngeniumError` (or unknown error) as
+ * `application/problem+json` instead of the framework's default
+ * `{ error, code, fields? }` shape.
+ *
+ * Composition notes:
+ * - This sits as a regular middleware in front of user handlers, NOT in
+ *   place of `app.onError`. If `app.onError` is configured AND it re-throws
+ *   (or the user handler throws past the onError), this middleware catches
+ *   the error before it reaches the default boundary.
+ * - Composes cleanly with other middleware (e.g. idempotency) — the
+ *   try/catch is the only thing it does on the way out.
+ *
+ * @example
+ *   app.use(ingenium.problemDetails({
+ *     typeBaseUrl: 'https://api.example.com/errors/',
+ *     includeStack: process.env.NODE_ENV !== 'production',
+ *   }))
+ */
+declare function problemDetailsMiddleware(opts?: ProblemDetailsOptions): IngeniumMiddleware;
+
+/**
+ * A frozen snapshot of an outgoing response. Captured AFTER the handler
+ * runs and stored in the idempotency cache for replay on retry.
+ *
+ * `body` is `null` only for empty responses (e.g. 204).
+ */
+interface CachedResponse {
+    /** HTTP status code from the original response. */
+    statusCode: number;
+    /** Plain header bag (lowercased keys), copied from `ctx._headers`. */
+    headers: Record<string, string | string[]>;
+    /** Serialized body. `null` when the original response had no body. */
+    body: string | Buffer$1 | null;
+}
+/**
+ * Pluggable storage for the idempotency cache. Default impl is in-memory;
+ * swap for Redis/etc. when running multiple replicas.
+ */
+interface IdempotencyStore {
+    /** Returns the cached response for `key` or `null` if missing/expired. */
+    get(key: string): Promise<CachedResponse | null>;
+    /** Persist `value` under `key` for `ttlMs` milliseconds. */
+    set(key: string, value: CachedResponse, ttlMs: number): Promise<void>;
+    /** Remove `key`. Idempotent — does nothing if absent. */
+    delete(key: string): Promise<void>;
+}
+/** Options accepted by `ingenium.idempotency(...)`. */
+interface IdempotencyOptions {
+    /**
+     * Header name carrying the idempotency key. Comparison is
+     * case-insensitive (Node lowercases header names automatically).
+     * Default `'Idempotency-Key'`.
+     */
+    header?: string;
+    /** Backing cache. Default: an in-process `IdempotencyMemoryStore`. */
+    store?: IdempotencyStore;
+    /**
+     * Time-to-live for cached responses, in seconds. After this elapses, the
+     * same key replays nothing and the handler runs again. Default `86400`
+     * (24h) — matches Stripe's documented behavior.
+     */
+    ttlSeconds?: number;
+    /**
+     * Namespace function — distinguishes keys belonging to different callers
+     * so two clients can independently use the same idempotency-key string.
+     * Default uses the `Authorization` header (or `'anon'` when absent).
+     */
+    scope?: (ctx: IngeniumContext) => string;
+    /**
+     * HTTP methods eligible for idempotency caching. Default: `['POST',
+     * 'PATCH', 'DELETE']` — only mutating methods. Safe methods (GET/HEAD/
+     * OPTIONS) and idempotent-by-spec PUT are skipped by default; opt in by
+     * extending this list if you need PUT semantics cached too.
+     */
+    methods?: readonly HttpMethod[];
+    /**
+     * Predicate deciding which response status codes are cacheable. Default:
+     * `(s) => s >= 200 && s < 500` — caches 2xx/3xx/4xx but NOT 5xx, matching
+     * Stripe's documented behavior. The intent: a transient 500 (DB blip,
+     * deploy race) must NOT be cached for the entire TTL — every retry would
+     * replay the same failure and the user would be permanently broken until
+     * the cache expires. Validation errors (4xx) are deterministic and worth
+     * caching. Override to opt in to 5xx caching or tighten further.
+     */
+    cacheable?: (statusCode: number) => boolean;
+}
+
+/**
+ * Idempotency-Key middleware (per Stripe / IETF idempotency-key draft).
+ *
+ * Behavior:
+ * - Non-mutating method or missing header → pass through.
+ * - Mutating method WITH header:
+ *   1. Build cache key: `<scope>:<method>:<path>:<idempotency-key>`.
+ *   2. Cache hit → replay the cached (status, headers, body) and set
+ *      `Idempotent-Replayed: true`. Handler does NOT run.
+ *   3. Cache miss → run handler. If the response is cacheable (i.e. not a
+ *      stream and something was written), persist it under the key with
+ *      the configured TTL.
+ *   4. Concurrent in-flight requests for the same key are coordinated via
+ *      an in-process Promise map: the second request awaits the first and
+ *      replays its result.
+ *
+ * Note: the cache key intentionally does NOT include the request body —
+ * the spec assumes the client guarantees byte-for-byte identical retries,
+ * and reading the body at middleware-entry time would defeat lazy parsing.
+ *
+ * @example
+ *   app.use(ingenium.idempotency({
+ *     store: new IdempotencyMemoryStore(),
+ *     ttlSeconds: 86_400,
+ *   }))
+ */
+declare function idempotencyMiddleware(opts?: IdempotencyOptions): IngeniumMiddleware;
+
+/**
+ * Supported JWT signing algorithms.
+ *
+ * - `HSxxx` — HMAC with the supplied shared secret.
+ * - `RSxxx` — RSASSA-PKCS1-v1_5 with the supplied RSA public key (PEM / JWK / KeyObject).
+ * - `PSxxx` — RSASSA-PSS (MGF1, salt length = digest length).
+ * - `ESxxx` — ECDSA on P-256 / P-384 / P-521 (raw r||s, NOT DER — per the JWT spec).
+ *
+ * `alg: 'none'` is intentionally absent from this union and is hard-rejected
+ * at the verifier — never accept unsigned tokens, even with an empty allowlist.
+ */
+type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512';
+/** Decoded JWT header. The `alg` field is required by the spec. */
+interface JwtHeader {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [k: string]: unknown;
+}
+/**
+ * A successfully verified JWT. `payload` carries the typed claims object,
+ * `header` carries the decoded protected header, and `raw` is the original
+ * compact-serialization string the client sent (useful for re-emitting).
+ */
+interface JwtVerified<T = Record<string, unknown>> {
+    header: JwtHeader;
+    payload: T;
+    raw: string;
+}
+/** Internal — verifier failure mode. Public surface only ever sees `'Invalid token'`. */
+type JwtVerifyError = {
+    error: 'malformed';
+} | {
+    error: 'unsupported_alg';
+} | {
+    error: 'bad_signature';
+} | {
+    error: 'expired';
+} | {
+    error: 'not_yet_valid';
+} | {
+    error: 'too_old';
+} | {
+    error: 'aud_mismatch';
+} | {
+    error: 'iss_mismatch';
+} | {
+    error: 'kid_unknown';
+} | {
+    error: 'jwks_fetch_failed';
+};
+/**
+ * A single signing/verification key. For HMAC algorithms (HSxxx) this is the
+ * shared secret as a string; for asymmetric algorithms it's the PUBLIC key in
+ * PEM (string / Buffer) or as a pre-built `KeyObject`.
+ *
+ * Wrapping with `{ kid, key }` enables header-based key selection — the
+ * verifier picks the entry whose `kid` matches `header.kid`.
+ */
+type JwtKey = string | Buffer$1 | KeyObject | {
+    kid: string;
+    key: string | Buffer$1 | KeyObject;
+};
+/**
+ * Resolve a per-request key. Receives the decoded JWT header so callers can
+ * implement `kid`-based JWKS-style routing without parsing the token themselves.
+ */
+type JwtSecretResolver<_T = Record<string, unknown>> = (header: JwtHeader) => JwtKey | Promise<JwtKey>;
+/** All ways `secret` can be supplied. */
+type JwtSecret<T = Record<string, unknown>> = JwtKey | JwtKey[] | JwtSecretResolver<T>;
+/** Signature for pulling the raw compact-serialization out of the request. */
+type JwtTokenReader = (ctx: IngeniumContext) => string | undefined | Promise<string | undefined>;
+/** Optional structured logger for redacted verification diagnostics. */
+type JwtLogger = (event: {
+    reason: string;
+    alg?: string;
+}) => void;
+interface JwtOptions<T = Record<string, unknown>> {
+    /**
+     * Verification key material. Accepts:
+     * - A single key (string secret, PEM, Buffer, or `KeyObject`).
+     * - `{ kid, key }` for explicit key-id tagging.
+     * - An array of any of the above (rotation / multi-key — the verifier
+     *   picks by `kid` if present, else tries each in order).
+     * - A function `(header) => key | Promise<key>` for fully custom routing.
+     */
+    secret: JwtSecret<T>;
+    /** Allowed signing algorithms. Default `['HS256']`. */
+    algorithms?: readonly JwtAlgorithm[];
+    /** Required `aud` claim. Token's `aud` must match (or include) one of these. */
+    audience?: string | readonly string[];
+    /** Required `iss` claim. */
+    issuer?: string | readonly string[];
+    /** Reject tokens whose `iat` is older than N seconds. */
+    maxAgeSeconds?: number;
+    /** Leeway for `nbf` / `exp` checks, in seconds. Default `5`. */
+    clockSkewSeconds?: number;
+    /**
+     * If `true` (default), missing tokens raise `IngeniumUnauthorizedError`.
+     * If `false`, missing tokens just call `next()` with no `ctx.jwt`.
+     */
+    required?: boolean;
+    /**
+     * Custom token reader. Default reads `Authorization: Bearer <token>`.
+     * Return `undefined` to indicate "no token in this request".
+     */
+    getToken?: JwtTokenReader;
+    /**
+     * Optional sink for redacted verification failure reasons. Useful for
+     * observability without leaking the failure type to the wire (which would
+     * be an oracle for attackers).
+     */
+    logger?: JwtLogger;
+    /**
+     * Optional JWKS endpoint URL. When set, the middleware fetches the keys
+     * from this URL on demand and looks them up by `header.kid`. Cached for
+     * `jwksCacheMs` (default 10 minutes) per URL with a single in-flight
+     * request coalesced across concurrent callers.
+     */
+    jwksUrl?: string;
+    /** JWKS cache TTL in milliseconds. Default `600_000` (10 minutes). */
+    jwksCacheMs?: number;
+    /** Phantom — narrows `ctx.jwt.payload` for typed handlers. */
+    _payload?: T;
+}
+
+/**
+ * Bearer-token JWT verification middleware.
+ *
+ * Attaches the verified token at `ctx.jwt`. Callers should module-augment
+ * `IngeniumContext` for typed access (the framework purposely doesn't ship a
+ * baked-in `jwt` field — payload shape is application-specific).
+ *
+ * @example
+ * ```ts
+ * declare module 'ingenium' {
+ *   interface IngeniumContext {
+ *     jwt?: import('ingenium').JwtVerified<{ sub: string; roles: string[] }>
+ *   }
+ * }
+ *
+ * import { ingenium } from 'ingenium'
+ * const app = ingenium()
+ * // HMAC
+ * app.use(ingenium.jwt({ secret: process.env.JWT_SECRET! }))
+ * // RSA via JWKS (Auth0, Okta, Cognito, Clerk, Supabase, ...)
+ * app.use(ingenium.jwt({
+ *   secret: [],
+ *   algorithms: ['RS256'],
+ *   jwksUrl: 'https://example.auth0.com/.well-known/jwks.json',
+ *   issuer: 'https://example.auth0.com/',
+ *   audience: 'https://api.example.com',
+ * }))
+ * ```
+ *
+ * Security choices:
+ * - Default leeway (`clockSkewSeconds`) is **5 seconds** — enough for typical
+ *   multi-host clock drift, small enough that an expired token does not stay
+ *   usable for long.
+ * - HMAC signature comparison uses `crypto.timingSafeEqual` after an explicit
+ *   length check inside {@link verifyJwt}; asymmetric verification uses
+ *   `crypto.verify` (constant-time within OpenSSL).
+ * - The algorithm allowlist is enforced at verify time. Even if an attacker
+ *   crafts `alg: 'RS256'` and we have a matching JWKS key, verification fails
+ *   unless `RS256` appears in `algorithms`. This is the canonical defence
+ *   against algorithm-confusion attacks.
+ * - `'none'` is rejected unconditionally, regardless of the allowlist.
+ * - The wire-facing error is always `IngeniumUnauthorizedError('Invalid token')`
+ *   regardless of which check failed (signature vs exp vs aud) — this avoids
+ *   handing attackers an oracle. Detailed reasons go to `opts.logger` (or
+ *   `process.emitWarning` if no logger is supplied).
+ */
+declare function jwtMiddleware<T = Record<string, unknown>>(opts: JwtOptions<T>): IngeniumMiddleware;
+
+/** Result of a custom API-key validator. */
+type ApiKeyValidator = (key: string, ctx: IngeniumContext) => boolean | Promise<boolean>;
+/** Optional logger for redacted failure reasons. */
+type ApiKeyLogger = (event: {
+    reason: string;
+}) => void;
+interface ApiKeyOptions {
+    /**
+     * Either an allow-list of valid keys (compared with `timingSafeEqual`) or a
+     * custom validator. Functions get the candidate key and the request ctx.
+     */
+    keys: readonly string[] | ApiKeyValidator;
+    /** Header to read the key from. Default `'x-api-key'`. */
+    header?: string;
+    /**
+     * Optional fallback query-string parameter, e.g. `'api_key'`. When set,
+     * the middleware checks `?api_key=...` if no header / scheme key matched.
+     */
+    query?: string;
+    /**
+     * Optional `Authorization` scheme to accept, e.g. `'ApiKey'`. When set,
+     * the middleware accepts `Authorization: ApiKey <key>`.
+     */
+    scheme?: string;
+    /**
+     * If `true` (default), missing keys raise `IngeniumUnauthorizedError`. If
+     * `false`, missing keys just call `next()` with no `ctx.apiKey`.
+     */
+    required?: boolean;
+    /** Optional sink for redacted failure reasons. Defaults to `process.emitWarning`. */
+    logger?: ApiKeyLogger;
+}
+
+/**
+ * API-key authentication middleware.
+ *
+ * Attaches the validated key string at `ctx.apiKey`. Callers should
+ * module-augment `IngeniumContext` for typed access:
+ *
+ * @example
+ * ```ts
+ * declare module 'ingenium' {
+ *   interface IngeniumContext { apiKey?: string }
+ * }
+ *
+ * import { ingenium } from 'ingenium'
+ * const app = ingenium()
+ * app.use(ingenium.apiKey({
+ *   keys: process.env.API_KEYS!.split(','),
+ *   scheme: 'ApiKey',
+ *   query: 'api_key',
+ * }))
+ * ```
+ *
+ * Security choices:
+ * - Allow-list comparisons go through `crypto.timingSafeEqual` after an
+ *   explicit length check, so neither equality nor length leaks via timing.
+ * - The wire-facing error is always `IngeniumUnauthorizedError('Invalid API key')`
+ *   regardless of which lookup failed (header vs scheme vs query) — no
+ *   oracle for which transport surface the legit key uses.
+ * - Custom validators get the candidate key + ctx; their boolean result is
+ *   trusted as-is. Validators should be constant-time when comparing keys.
+ */
+declare function apiKeyMiddleware(opts: ApiKeyOptions): IngeniumMiddleware;
+
+/** Public options for `generateOpenApi(app, opts)`. */
+interface GenerateOpenApiOptions {
+    info: Info;
+    servers?: Server[];
+    tags?: Tag[];
+    security?: SecurityRequirement[];
+    /**
+     * Auto-tag generated operations by path prefix. The longest matching
+     * prefix wins. Routes that already have `tags` in their descriptor are
+     * left alone.
+     *
+     * @example { '/users': 'users', '/auth': 'auth' }
+     */
+    tagsByPrefix?: Record<string, string>;
+    /**
+     * Hide routes whose path matches any entry. Strings match exactly,
+     * RegExps are tested against the full path.
+     */
+    excludePaths?: (string | RegExp)[];
+    /** Pass-through `components.securitySchemes`. */
+    securitySchemes?: Record<string, SecurityScheme>;
+    /**
+     * Optional additional schemas to merge into `components.schemas`. Useful
+     * when you reference shared models via `$ref: '#/components/schemas/X'`.
+     */
+    componentSchemas?: Record<string, Schema>;
+}
+/**
+ * Generate an OpenAPI 3.1 spec from a composed (or uncomposed) IngeniumApp.
+ * Walks the registration journal — does not require `compose()` to have run.
+ *
+ * Schema-conversion strategy (in priority order):
+ *   1. If a request/response schema has a `toJsonSchema()` method (Zod 3.24+,
+ *      ArkType, Effect Schema, etc.), call it.
+ *   2. If it looks like a Standard Schema (has `~standard`), emit `{}` plus
+ *      `x-schema-source: '<vendor>-untranslated'` as a TODO marker.
+ *   3. Otherwise, pass the value through unchanged (assumed JSON Schema).
+ */
+declare function generateOpenApi(app: IngeniumApp, opts: GenerateOpenApiOptions): OpenApiSpec;
+
+/**
+ * Build a route handler that serves the generated OpenAPI spec as JSON.
+ *
+ * The spec is generated lazily on the first request that hits this handler
+ * and cached on the app under a private symbol. The cache invalidates when
+ * the registration journal length changes — i.e. when new routes are added —
+ * so live-registered routes are reflected on the next request.
+ *
+ * @example
+ * app.get('/openapi.json', ingenium.openapiHandler({
+ *   info: { title: 'My API', version: '1.0.0' },
+ * }))
+ */
+declare function openapiHandler(opts: GenerateOpenApiOptions): IngeniumHandler;
+
+/**
+ * A bounded free-list of `IngeniumContext` objects. Acquire on each request,
+ * release back when the response has been written. If the pool is empty,
+ * a fresh context is allocated; if the pool is full on release, the
+ * context is discarded (GC handles it). Never blocks.
+ */
+declare class IngeniumContextPool {
+    private readonly pool;
+    private readonly max;
+    constructor(maxSize?: number);
+    /** Acquire a context. Caller must call `release()` when done. */
+    acquire(): IngeniumContext;
+    /** Reset and return the context to the free list (or discard if full). */
+    release(ctx: IngeniumContext): void;
+    /** Current free-list size. Useful for tests and metrics. */
+    get size(): number;
+}
+
+/**
+ * Compose an array of middleware into a single async function. Composition
+ * runs ONCE at registration / first-request time; the returned function has
+ * no per-request `bind`, no index variable, and no `stack[n]` lookups.
+ *
+ * The dispatcher chain is pre-built bottom-up: `dispatchers[i]` runs
+ * `stack[i]` with a `next` that invokes `dispatchers[i + 1]`. Each
+ * middleware-level invocation still allocates one closure to capture `ctx`
+ * (unavoidable without dropping concurrency safety).
+ *
+ * Double-`next()` calls are detected only when `process.env.REX_DEBUG` is
+ * truthy, to keep the production hot path free of per-call guard variables.
+ */
+declare function compose(stack: readonly IngeniumMiddleware[]): ComposedHandler;
+/**
+ * Compose middleware then append a terminal handler that does not receive a
+ * `next` (so a route handler can be the leaf of the chain). The handler's
+ * return value is reflected to the response per the contract in
+ * `response/reflect.ts` — unless the handler called a `ctx.json/...` helper,
+ * in which case the return value is ignored.
+ *
+ * Hot-path optimization: when there are no middleware, we skip the
+ * dispatcher chain entirely and return a thin wrapper that calls the
+ * handler directly. We also detect synchronous handler return values
+ * (non-thenable) and avoid the `await` microtask in that case — measurable
+ * on JSON-returning routes that don't touch the body.
+ */
+declare function composeWithHandler(middleware: readonly IngeniumMiddleware[], handler: (ctx: IngeniumContext) => unknown | Promise<unknown>): ComposedHandler;
+
+/**
+ * One node in the radix trie. Static segments win over `:param`, which wins
+ * over `*wild`. Method-specific composed handlers live at the leaf.
+ */
+declare class TrieNode {
+    staticChildren: Map<string, TrieNode>;
+    paramChild: TrieNode | null;
+    paramName: string | null;
+    wildcardChild: TrieNode | null;
+    wildcardName: string | null;
+    /**
+     * Compiled inline constraint for this node *as a param child*, or `null`
+     * when the param is unconstrained. Set at insert time when the registered
+     * segment carries a `(regex)` group (e.g. `:id(\d+)`). The `find()` hot
+     * path loads this field and only runs `.test()` when it is non-null, so
+     * unconstrained routes pay zero extra cost. Lives on the param node itself
+     * (the child) so the matcher can test it the instant it descends.
+     */
+    paramConstraint: RegExp | null;
+    /** Per-method composed handlers, populated by `RouteRegistry` after compose. */
+    handlers: Partial<Record<HttpMethod, ComposedHandler>>;
+    /**
+     * Param names accumulated from root → this node, in order. Cached so
+     * matching can fill the params object in O(k) without re-walking parents.
+     */
+    paramNames: readonly string[];
+}
+/** Result of a trie lookup. `params` may be empty if the route had none. */
+interface MatchResult {
+    handler: ComposedHandler;
+    params: Record<string, string>;
+    /** Methods registered at this leaf — used to populate `Allow` on 405. */
+    allowed: readonly HttpMethod[];
+}
+/** Why a lookup failed. */
+type MatchMiss = {
+    kind: 'not-found';
+} | {
+    kind: 'method-not-allowed';
+    allowed: readonly HttpMethod[];
+};
+/**
+ * Radix trie router. `insert()` is called at registration; `find()` runs on
+ * every request and is the single hottest piece of code in the framework.
+ */
+declare class RouterTrie {
+    readonly root: TrieNode;
+    /**
+     * Walks/creates trie nodes for the path. Returns the leaf where handlers
+     * should be attached. Path must start with `/`.
+     */
+    insert(path: string): TrieNode;
+    /**
+     * Look up a route. Iterative with single-level wildcard backtrack — if the
+     * static/param walk dead-ends and an ancestor had a `*wildcard` child, we
+     * retry from the wildcard with the remaining segments. Backtrack frames
+     * are tracked in a small stack (one per wildcard ancestor encountered).
+     */
+    find(method: HttpMethod, path: string): MatchResult | MatchMiss;
+}
+
+/**
+ * `safeJsonStringify(value, opts?)` — a lenient `JSON.stringify` that never
+ * throws on circular references or `BigInt` values.
+ *
+ * Behavior:
+ * - Circular references → replaced with the string `'[Circular]'`.
+ * - `BigInt` values     → serialized as a JSON string (e.g. `1n` → `"1"`).
+ *   This preserves precision and is reversible by the caller; if you need a
+ *   different convention, pass your own `replacer`.
+ * - Symbol values       → omitted (matches `JSON.stringify` default).
+ * - Functions           → omitted (matches `JSON.stringify` default).
+ *
+ * Intended for opt-in use by callers who want lenient behavior — the
+ * default `ctx.json()` path remains strict and surfaces a
+ * `IngeniumUnserializableError` so the bug is visible.
+ *
+ * @example
+ *   import { safeJsonStringify } from 'ingenium'
+ *   ctx.send(safeJsonStringify(value), 200)
+ *   ctx.set('content-type', 'application/json; charset=utf-8')
+ */
+/** Options for `safeJsonStringify`. */
+interface SafeJsonStringifyOptions {
+    /**
+     * Pass-through to `JSON.stringify`'s third argument — number of spaces or
+     * indent string for pretty-printing. Defaults to no indentation.
+     */
+    space?: string | number;
+    /**
+     * Optional user replacer applied AFTER the cycle/BigInt sanitization. If
+     * provided, behaves like `JSON.stringify`'s second argument.
+     */
+    replacer?: (key: string, value: unknown) => unknown;
+}
+/**
+ * Stringify `value` without throwing on circular structures or `BigInt`s.
+ * See module doc for the exact substitution rules.
+ */
+declare function safeJsonStringify(value: unknown, opts?: SafeJsonStringifyOptions): string;
+
+/**
+ * Node.js `node:http` transport. Owns a single `http.Server`; on each
+ * request, populates a pooled `IngeniumContext` directly from the
+ * `IncomingMessage` (no WinterCG translation), awaits dispatch, then writes
+ * the context's response state to the `ServerResponse`.
+ */
+declare class NodeAdapter implements Transport {
+    private hooks;
+    attach(hooks: TransportHooks): void;
+    listen(port: number, host?: string): Promise<ListeningServer>;
+}
+
+/** TLS options accepted by the h2 (secure) adapter. */
+interface Http2AdapterOptions {
+    /** TLS certificate (PEM). */
+    cert: Buffer | string;
+    /** TLS private key (PEM). */
+    key: Buffer | string;
+    /**
+     * If true, the secure server also accepts HTTP/1.1 connections via ALPN
+     * fallback. Inbound HTTP/1 requests are dispatched through the same path
+     * used by `NodeAdapter`. Default: false (HTTP/2 only).
+     */
+    allowHttp1?: boolean;
+}
+/**
+ * HTTP/2-over-TLS (`h2`) transport. Uses Node's built-in `http2.createSecureServer`.
+ * Browsers REQUIRE TLS for HTTP/2 — there is no cleartext HTTP/2 negotiation
+ * over the open web. For local testing without certs, use {@link Http2cAdapter}.
+ *
+ * Per-request: on `'stream'`, populates a pooled `IngeniumContext` from pseudo-headers,
+ * awaits dispatch, then writes the response via `stream.respond()` + `stream.end()`
+ * (or pipes for `Readable` bodies).
+ */
+declare class Http2Adapter implements Transport {
+    private readonly options;
+    private hooks;
+    constructor(options: Http2AdapterOptions);
+    attach(hooks: TransportHooks): void;
+    listen(port: number, host?: string): Promise<ListeningServer>;
+}
+/**
+ * HTTP/2 cleartext (`h2c`) transport. Uses Node's `http2.createServer` — no TLS,
+ * so this is intended for local development, internal service-to-service calls
+ * behind an L7 proxy that handles TLS termination, or test suites. Browsers do
+ * not speak h2c; use {@link Http2Adapter} for browser traffic.
+ *
+ * Constructor takes no required arguments.
+ */
+declare class Http2cAdapter implements Transport {
+    private hooks;
+    constructor(_options?: {});
+    attach(hooks: TransportHooks): void;
+    listen(port: number, host?: string): Promise<ListeningServer>;
+}
+
+/**
+ * Graceful shutdown helper. Wires POSIX signal handlers to drain a
+ * {@link ListeningServer}, run a user cleanup hook, then exit.
+ *
+ * Most production deployments (Kubernetes, systemd, PM2, ECS, Fly, …) send
+ * SIGTERM when they want a process to stop. By default Node simply dies on
+ * SIGTERM, which kills in-flight requests and leaves keep-alive sockets
+ * dangling. Calling {@link gracefulShutdown} after `app.listen()` opts the
+ * process into a clean drain instead.
+ */
+
+/** Options for {@link gracefulShutdown}. */
+interface ShutdownOptions {
+    /**
+     * Maximum time (ms) to wait for sockets to drain before they are forcibly
+     * destroyed. Defaults to `10_000` (10s) — matches Kubernetes' default
+     * `terminationGracePeriodSeconds` headroom.
+     */
+    gracefulTimeoutMs?: number;
+    /**
+     * Signals to listen for. Defaults to `['SIGTERM', 'SIGINT']`.
+     */
+    signals?: NodeJS.Signals[];
+    /**
+     * User cleanup hook — runs AFTER the server stops accepting new
+     * connections but BEFORE the process exits. Use for closing DB pools,
+     * flushing logs, etc. Awaited; throwing exits with code 1.
+     */
+    onShutdown?: () => void | Promise<void>;
+    /** Logger used to announce shutdown lifecycle events. Defaults to `console.log`. */
+    logger?: (msg: string) => void;
+}
+/**
+ * Wire signal handlers that gracefully shut down `server` on SIGTERM/SIGINT
+ * (or whichever signals you pass). Returns an unsubscribe function that
+ * removes the listeners — mostly useful for tests.
+ *
+ * @example
+ *   const server = await app.listen(3000)
+ *   gracefulShutdown(server, { onShutdown: async () => db.close() })
+ */
+declare function gracefulShutdown(server: ListeningServer, opts?: ShutdownOptions): () => void;
+
+/**
+ * Send a `:keepalive` comment to the given SSE stream every `intervalMs`
+ * milliseconds. Returns a cancellation function.
+ *
+ * The interval is automatically cancelled when the stream closes — but
+ * callers should still hold onto the cancel function for explicit cleanup
+ * (e.g. on a separate teardown signal).
+ *
+ * The internal timer is `unref()`'d so it won't keep the Node event loop
+ * alive on its own.
+ *
+ * @example
+ *   const stream = sse(ctx)
+ *   const cancel = startKeepAlive(stream, 15_000)
+ *   ctx.req.on('close', cancel) // optional
+ */
+declare function startKeepAlive(stream: SseStream, intervalMs?: number): () => void;
+
+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.**
+ */
+declare class MemoryStore$1 implements RateLimitStore {
+    private readonly map;
+    private sweeper;
+    private sweepIntervalMs;
+    private readonly maxEntries;
+    constructor(opts?: MemoryStoreOptions);
+    hit(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+    /**
+     * 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;
+    /** @internal Current entry count — exposed for ops/tests. */
+    get size(): number;
+    private ensureSweeper;
+    private sweep;
+}
+
+/**
+ * Pure parsers and matchers for HTTP `Accept`-family headers.
+ *
+ * Implemented from scratch — no `negotiator` / `accepts` runtime dep.
+ * Used by `negotiate.ts`, `format.ts`, and downstream context helpers.
+ *
+ * Spec references:
+ *   - RFC 9110 §12.5.1 (Accept), §12.5.2 (Accept-Charset),
+ *     §12.5.4 (Accept-Encoding), §12.5.5 (Accept-Language).
+ */
+/** A single parsed media-range entry from an `Accept` header. */
+interface ParsedAccept {
+    /** The full media-range string (lowercased), e.g. `text/html`, `text/\*`, `\*\/\*`. */
+    type: string;
+    /** Quality factor from `;q=N`, default `1`. Out-of-range values are clamped. */
+    quality: number;
+    /** Any other extension parameters (e.g. `level=1`). */
+    params: Record<string, string>;
+}
+/** Resolve a shorthand (`'json'`) to its canonical mime, or pass through. */
+declare function expandShorthand(token: string): string;
+/**
+ * Parse a comma-separated `Accept`-family header into a list of entries.
+ * Empty / undefined input returns an empty array. Malformed entries are
+ * silently dropped (lenient parsing — same as Express).
+ *
+ * Result is **not** sorted; pass to `sortByPreference` if you need ordering.
+ */
+declare function parseAcceptHeader(header: string | undefined): ParsedAccept[];
+/**
+ * Stable sort by RFC preference: highest q first, then most-specific first.
+ * Returns a NEW array; does not mutate input.
+ */
+declare function sortByPreference(entries: readonly ParsedAccept[]): ParsedAccept[];
+/**
+ * Return the best match for `offered` against `acceptHeader`, or `false`.
+ *
+ * Matching algorithm:
+ *   1. If `acceptHeader` is missing/empty → first offered wins (Express behavior).
+ *   2. Walk parsed entries sorted by quality + specificity.
+ *   3. For each entry (in preference order), pick the first offered that matches.
+ *      Among ties at the same Accept entry, the offered's listed order wins.
+ *   4. Entries with `q=0` reject — never match.
+ */
+declare function selectBest(acceptHeader: string | undefined, offered: readonly string[]): string | false;
+
+/**
+ * `isFresh(reqHeaders, resHeaders)` — RFC 7232 conditional-request evaluator.
+ *
+ * Returns `true` when the response can be considered fresh relative to the
+ * client's cached copy, i.e. a `304 Not Modified` is appropriate. This is
+ * the engine behind `ctx.fresh` / `ctx.stale`.
+ *
+ * Decision matrix:
+ *   - `If-None-Match` present → compare against response `ETag`. Wildcard
+ *     `*` matches any current representation. Strong/weak prefixes are
+ *     normalized away (per RFC 7232 §2.3.2 weak-comparison rules).
+ *   - Else if `If-Modified-Since` present → compare against response
+ *     `Last-Modified` (or fall back to `Date`). Fresh when the resource has
+ *     not been modified since.
+ *   - Otherwise → not fresh (no precondition to evaluate).
+ *
+ * Methods other than GET/HEAD are not handled here — callers should gate
+ * on method themselves (Express does the same in `req.fresh`).
+ */
+/** Header bag shape — accepts both incoming-request and stored-response styles. */
+type HeaderBag = Record<string, string | string[] | undefined>;
+/**
+ * Returns `true` when the response is fresh w.r.t. the client's preconditions.
+ */
+declare function isFresh(reqHeaders: HeaderBag, resHeaders: HeaderBag): boolean;
+
+/**
+ * `computeEtag(body, weak?)` — sha1-based entity tag for response bodies.
+ *
+ * Format: `W/"<sha1-base64-without-padding>"` (weak) or `"<sha1-base64-without-padding>"`.
+ * Weak is the default — fine for JSON where serialization may legitimately vary
+ * (key order, whitespace) without representing a different resource.
+ *
+ * The empty-body ETag is special-cased to a fixed constant so two empty
+ * bodies always compare equal without pumping through the hash.
+ */
+
+/**
+ * Compute an ETag for the given body. Strings are treated as UTF-8.
+ * @param body  Response body — usually `JSON.stringify(...)` or a `Buffer`.
+ * @param weak  Prefix the tag with `W/`. Defaults to `true` for JSON safety.
+ */
+declare function computeEtag(body: string | Buffer$1, weak?: boolean): string;
+
+/**
+ * Convert a thrown value into an RFC 7807 ProblemDetails object. Handles
+ * `IngeniumError` and its subclasses with rich extensions; unknown errors are
+ * reported as a generic 500 with `type: 'about:blank'`.
+ *
+ * Side effect: for `IngeniumMethodNotAllowedError`, the `Allow` header is set
+ * on the response so it matches the framework's default boundary behavior.
+ */
+declare function toProblemDetails(err: unknown, opts: ResolvedProblemDetailsOptions, ctx: IngeniumContext): ProblemDetails;
+
+/**
+ * In-process idempotency cache. Suitable for single-replica deployments and
+ * tests; back with Redis when running multiple replicas behind a load
+ * balancer (responses cached on one replica won't replay on another).
+ *
+ * A periodic sweep removes expired entries 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.
+ */
+declare class IdempotencyMemoryStore implements IdempotencyStore {
+    private readonly map;
+    private sweeper;
+    private sweepIntervalMs;
+    get(key: string): Promise<CachedResponse | null>;
+    set(key: string, value: CachedResponse, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * 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;
+    private ensureSweeper;
+    private sweep;
+}
+
+/**
+ * A verification key as supplied by the caller (post-resolution).
+ * - `string` / `Buffer` for HMAC secrets and PEM blobs.
+ * - `KeyObject` for pre-built node:crypto keys (and JWKS-derived keys).
+ */
+type VerifyKeyMaterial = string | Buffer$1 | KeyObject;
+/** Optional kid-tagged variant — what middleware passes after kid resolution. */
+interface KidTaggedKey {
+    kid?: string;
+    key: VerifyKeyMaterial;
+}
+/** Options accepted by {@link verifyJwt}. Mirrors the relevant subset of `JwtOptions`. */
+interface VerifyOptions {
+    algorithms: readonly JwtAlgorithm[];
+    audience?: string | readonly string[];
+    issuer?: string | readonly string[];
+    maxAgeSeconds?: number;
+    clockSkewSeconds?: number;
+    /** Override "now" for deterministic tests. Returns seconds since epoch. */
+    nowSeconds?: () => number;
+}
+/**
+ * Pure JWT verifier. No I/O, no logging — returns either a `JwtVerified` or
+ * a tagged failure object. The middleware layer is responsible for collapsing
+ * every failure into the same `IngeniumUnauthorizedError('Invalid token')` so
+ * the wire never reveals which check tripped.
+ *
+ * `keys` is a flat array because key-resolution (rotation, kid-lookup, JWKS)
+ * is the caller's responsibility; this function just tries them in order.
+ * Each entry may carry an optional `kid` — when present AND `header.kid` is
+ * set, only matching entries are considered. Without a `header.kid`, every
+ * entry is tried.
+ *
+ * `alg: 'none'` is rejected unconditionally, even if for some reason the
+ * allowlist were extended to include it. Defence in depth.
+ */
+declare function verifyJwt<T = Record<string, unknown>>(token: string, keys: readonly (VerifyKeyMaterial | KidTaggedKey)[], opts: VerifyOptions): JwtVerified<T> | JwtVerifyError;
+
+/**
+ * Fetch + cache a JWKS. Returns a `Map<kid, KeyObject>`.
+ *
+ * Concurrency: if a fetch is already in flight for `url` we await the same
+ * promise, ensuring a thundering-herd of requests collapses to one upstream
+ * call. After the fetch resolves, all waiters get the same keys.
+ *
+ * Failure mode: any thrown error (network, JSON parse, malformed JWK, empty
+ * keyset) bubbles as a generic `Error('jwks_fetch_failed')` — the caller is
+ * responsible for translating to a wire-safe `IngeniumUnauthorizedError`. We
+ * deliberately do NOT serve a stale cache on failure: stale public keys can
+ * mean accepting tokens that the IdP has rotated away from.
+ */
+declare function fetchJwks(url: string, ttlMs: number): Promise<Map<string, KeyObject>>;
+/** Reset the in-process cache. Tests use this; production code shouldn't need it. */
+declare function clearJwksCache(): void;
+
+/**
+ * In-process FIFO queue store. Backs {@link IngeniumQueue} when no custom
+ * store is supplied. Suitable for single-instance deployments and tests.
+ *
+ * Layout:
+ *   - `pending`: ordered list of jobs ready to be picked up. Delayed jobs
+ *      (post-retry backoff) sit here too — `next()` skips entries whose
+ *      `notBefore` hasn't elapsed yet, so callers should poll on a timer.
+ *   - `inFlight`: jobs that have been `next()`-ed but not yet `ack`/`retry`/`fail`-ed.
+ *   - `failed`: dead-letter list. Persists until `clearFailed()` is called.
+ *
+ * No background timers — purely event-driven via the queue worker pool.
+ */
+declare class MemoryQueueStore<TData> implements QueueStore<TData> {
+    private readonly pending;
+    private readonly inFlight;
+    private readonly failed;
+    private nextId;
+    enqueue(data: TData): Promise<{
+        id: string;
+    }>;
+    next(): Promise<{
+        id: string;
+        data: TData;
+        attempt: number;
+    } | null>;
+    ack(id: string): Promise<void>;
+    retry(id: string, delayMs: number): Promise<void>;
+    fail(id: string): Promise<void>;
+    size(): Promise<number>;
+    failedCount(): Promise<number>;
+    /** @internal Used by `IngeniumQueue.clearFailed()`. */
+    clearFailed(): void;
+    /** @internal Used by `IngeniumQueue.drain()` to know if work is outstanding. */
+    inFlightCount(): number;
+    /** @internal Earliest `notBefore` of any pending entry, or `null` if none. */
+    earliestPendingAt(): number | null;
+}
+
+/**
+ * 5-field crontab parser + "next fire time" calculator.
+ *
+ * Grammar (per field):
+ *   - `*`              every value
+ *   - `N`              literal
+ *   - `N-M`            inclusive range
+ *   - `* / S` or `N-M / S`  step
+ *   - `A,B,C`          list (each entry can be any of the above)
+ *
+ * Supported field ranges:
+ *   minute  0-59
+ *   hour    0-23
+ *   dom     1-31
+ *   month   1-12, or 3-letter names jan|feb|...|dec
+ *   dow     0-6  (sunday=0), or 3-letter names sun|mon|...|sat
+ *
+ * Explicitly NOT supported (would need a different parser):
+ *   - 6-field syntax with seconds
+ *   - L (last day-of-month), W (weekday), # (nth-of-month)
+ *   - Predefined macros (@hourly, @daily, ...)
+ *
+ * Day-of-month vs day-of-week conflict resolution: when BOTH `dom` and
+ * `dow` are restricted (i.e. neither is `*`), the cron fires when EITHER
+ * matches (this is the historical Vixie-cron behavior). When only one is
+ * restricted, only that one matters. This is what every other production
+ * cron implementation does and what users expect.
+ */
+/** Parsed match-set. `Set<number>` of all valid integers per field. */
+interface CronMatch {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    /** Was the original `dom` field `*`? Used for dom/dow conflict resolution. */
+    domIsWild: boolean;
+    /** Was the original `dow` field `*`? */
+    dowIsWild: boolean;
+}
+/**
+ * Parse a 5-field crontab spec into a {@link CronMatch}. Throws on any
+ * malformed input — out-of-range, wrong field count, garbage characters.
+ */
+declare function parseCronSpec(spec: string): CronMatch;
+/**
+ * Given a parsed {@link CronMatch}, find the next moment >= `from` that
+ * matches the spec, in the given IANA timezone. Returns `null` if none
+ * within ~5 years (defensive against pathological specs).
+ *
+ * Algorithm: walk forward minute-by-minute with smart skipping. We start
+ * one minute past `from` (cron fires at the START of each minute and we
+ * never want to re-fire the same slot back-to-back).
+ *
+ * Timezone handling:
+ *   - For `'UTC'` we use direct UTC accessors — fast path.
+ *   - For other zones we call `Intl.DateTimeFormat` to get the wall-clock
+ *     fields in that zone for each candidate. This relies on Node's bundled
+ *     ICU data; full-icu Node ships with a complete tz database.
+ *
+ * DST: by walking minute-by-minute on the UTC timeline and reading the
+ * wall-clock fields per-step, we naturally skip the "spring forward" gap
+ * (those minutes simply don't exist in the local clock so they can't match
+ * the user's local-time spec) and double-fire on "fall back" (the wall
+ * clock visits 1:30am twice; we fire each time). The latter matches Vixie
+ * cron's documented behavior — users wanting strict once-per-day semantics
+ * should pin their spec to UTC.
+ */
+declare function nextFireFrom(match: CronMatch, from: Date, timezone?: string): Date | null;
+
+/**
+ * Session middleware types.
+ *
+ * @see ./middleware.ts for the {@link sessionMiddleware} factory and the
+ * module-augmentation pattern users opt into for typed `ctx.session`.
+ */
+/** Cookie attribute overrides. */
+interface SessionCookieOptions {
+    /** Cookie `Domain` attribute. Omitted when undefined. */
+    domain?: string;
+    /** Cookie `Path` attribute. @default '/' */
+    path?: string;
+    /** Cookie `HttpOnly` attribute. @default true */
+    httpOnly?: boolean;
+    /** Cookie `SameSite` attribute. @default 'lax' */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Cookie `Secure` attribute. @default false */
+    secure?: boolean;
+}
+/** Options accepted by {@link sessionMiddleware}. */
+interface SessionOptions {
+    /**
+     * HMAC secret(s) for signing the session-id cookie.
+     *
+     * - Single string: used for both signing and verification.
+     * - Array: index `0` is the active signing key; ALL entries are accepted
+     *   for verification, enabling key rotation. Cookies signed with an older
+     *   key are re-signed with the active key on the next response.
+     */
+    secret: string | string[];
+    /** Name of the session cookie. @default 'ingenium.sid' */
+    cookieName?: string;
+    /** Cookie / store TTL in seconds. @default 604800 (7 days) */
+    maxAgeSeconds?: number;
+    /**
+     * If true, the cookie expiry and store TTL are refreshed on every request,
+     * even when the session data did not change. @default false
+     */
+    rolling?: boolean;
+    /** Cookie attribute overrides. */
+    cookie?: SessionCookieOptions;
+    /**
+     * Backing store. Defaults to an in-process {@link MemoryStore} which is
+     * NOT suitable for clustered deployments — supply your own for Redis,
+     * Postgres, etc.
+     */
+    store?: SessionStore;
+}
+/**
+ * Per-request session handle attached as `ctx.session`.
+ *
+ * Mutations (`set`, `delete`, `destroy`, `regenerate`) mark the session as
+ * dirty so the middleware persists changes after the handler returns.
+ */
+interface Session {
+    /** Stable, opaque session id (rotated by {@link Session.regenerate}). */
+    readonly id: string;
+    /** Frozen view of the session data. */
+    readonly data: Readonly<Record<string, unknown>>;
+    /** Read a value from the session. */
+    get<T = unknown>(key: string): T | undefined;
+    /** Write a value into the session. Marks the session dirty. */
+    set(key: string, value: unknown): void;
+    /** Remove a key from the session. Marks the session dirty. */
+    delete(key: string): void;
+    /** Drop the session: remove from store + clear the cookie. */
+    destroy(): Promise<void>;
+    /**
+     * Issue a new session id while preserving the current data. The old id is
+     * removed from the store. Use after privilege changes (e.g. login) to
+     * mitigate session-fixation attacks.
+     */
+    regenerate(): Promise<void>;
+}
+/**
+ * Pluggable session storage. Implementations must be safe to call
+ * concurrently for distinct ids; per-id ordering is the caller's concern.
+ */
+interface SessionStore {
+    /** Look up a session by id. Returns `null` for unknown / expired ids. */
+    get(id: string): Promise<Record<string, unknown> | null>;
+    /** Persist `data` under `id` with the given TTL (seconds). */
+    set(id: string, data: Record<string, unknown>, ttlSeconds: number): Promise<void>;
+    /** Remove a session entirely. No-op if it does not exist. */
+    destroy(id: string): Promise<void>;
+    /**
+     * OPTIONAL: extend an existing session's TTL without rewriting its data.
+     * Used by `rolling` sessions on requests that did not mutate state.
+     */
+    touch?(id: string, ttlSeconds: number): Promise<void>;
+}
+
+/**
+ * Cookie-backed session middleware.
+ *
+ * The middleware attaches a {@link Session} instance at `ctx.session`. To
+ * make this typesafe in user code, augment the `IngeniumContext` interface in
+ * your own project:
+ *
+ * @example
+ * ```ts
+ * declare module 'ingenium' {
+ *   interface IngeniumContext { session: import('ingenium').Session }
+ * }
+ *
+ * import { ingenium, sessionMiddleware } from 'ingenium'
+ * const app = ingenium()
+ * app.use(sessionMiddleware({ secret: process.env.SESSION_SECRET! }))
+ *
+ * app.get('/me', (ctx) => ({ user: ctx.session.get('user') }))
+ * app.post('/login', async (ctx) => {
+ *   ctx.session.set('user', { id: 1 })
+ *   await ctx.session.regenerate() // mitigate session fixation
+ * })
+ * ```
+ *
+ * Security choices:
+ * - HMAC-SHA-256 over the session id, base64url-encoded; verified with
+ *   `timingSafeEqual`.
+ * - 144-bit (18-byte) random ids.
+ * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. Set `secure: true`
+ *   behind TLS to enable `Secure`.
+ * - Tampered or unknown cookies silently issue a fresh session — never an
+ *   error response, since this is an attacker-influenced surface.
+ */
+declare function sessionMiddleware(opts: SessionOptions): IngeniumMiddleware;
+
+/**
+ * In-process session store backed by a `Map`. Suitable for development and
+ * single-instance deployments. NOT shared across workers/replicas.
+ *
+ * Expired entries are evicted lazily on access AND periodically by a
+ * background sweep. The sweep timer is `unref()`'d so it never keeps the
+ * Node process alive on its own.
+ */
+declare class MemoryStore implements SessionStore {
+    private readonly map;
+    private readonly sweep;
+    /**
+     * @param sweepIntervalMs How often to scan the map for expired entries.
+     * Defaults to 60s. Pass `0` to disable the timer entirely (tests).
+     */
+    constructor(sweepIntervalMs?: number);
+    get(id: string): Promise<Record<string, unknown> | null>;
+    set(id: string, data: Record<string, unknown>, ttlSeconds: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+    touch(id: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Stop the background sweep timer. Useful in tests / graceful shutdown.
+     * After this call the store still works but expired entries are only
+     * evicted on access.
+     */
+    stop(): void;
+    /** @internal Test helper: number of live (non-expired) entries. */
+    size(): number;
+    private purge;
+}
+
+/** Re-export the underlying `ws` `WebSocket` type for convenience. */
+type WebSocket = WebSocket$1;
+/**
+ * Handler invoked when a client successfully upgrades to a WebSocket.
+ *
+ * `socket` is the `ws.WebSocket` instance. `ctx` is a minimal `IngeniumContext`
+ * populated from the upgrade `IncomingMessage` — the body / response writers
+ * are not meaningful for WS handlers (the upgrade has already happened).
+ */
+type WebSocketHandler = (socket: WebSocket$1, ctx: IngeniumContext) => void | Promise<void>;
+/** Per-handler options forwarded to `WebSocketServer({ noServer: true, ... })`. */
+interface WebSocketHandlerOptions {
+    /** Max payload size (bytes) for incoming frames. */
+    maxPayload?: number;
+    /** Enable permessage-deflate. Defaults to false (matches `ws` default). */
+    perMessageDeflate?: boolean;
+}
+/** Bag passed to integrators (advanced). */
+interface WsIntegrator {
+    (httpServer: node_http.Server): void;
+}
+/** Shape of the per-app registrar exposed to `enableWebSockets`. */
+interface WsRegistrar {
+    add(path: string, handler: WebSocketHandler, options?: WebSocketHandlerOptions): void;
+    attach(httpServer: node_http.Server): void;
+    close(): Promise<void>;
+}
+
+/**
+ * WebSocket registrar — the small piece of state that holds path → handler
+ * mappings and knows how to wire `'upgrade'` on a Node `http.Server`.
+ *
+ * Design: the `ws` package is loaded lazily via dynamic `import('ws')` so
+ * apps that never use WebSockets pay no cost (no module load, no peer-dep
+ * requirement). The first call to `attach()` resolves the import.
+ */
+
+/**
+ * Attempt to detect whether `ws` is installed. Used by the test suite to
+ * `describe.skipIf` the WS suite when the optional peer dep is missing.
+ */
+declare function peerHasWs(): Promise<boolean>;
+/**
+ * Build a registrar bound to an app. The registrar is intentionally
+ * decoupled from `IngeniumApp` — the app calls `add()` from `app.ws()`, and
+ * `enableWebSockets()` (or the app's `listen()` integration) calls `attach()`
+ * once the underlying `http.Server` is created.
+ */
+declare function createWebSocketRegistrar(): WsRegistrar;
+
+/**
+ * WebSocket-aware variant of `NodeAdapter`. Mirrors the behavior of
+ * `transport/node.ts` (request handling, socket tracking, graceful close)
+ * but exposes the underlying `http.Server` via an `onServerReady` callback
+ * so the WS registrar can `.on('upgrade', …)` it.
+ *
+ * We did not modify the core `NodeAdapter` because the core has no awareness
+ * of WebSockets; this adapter is opt-in via `enableWebSockets()`.
+ */
+
+type OnServerReady = (httpServer: Server$1) => void;
+declare class WsNodeAdapter implements Transport {
+    private hooks;
+    private readonly onServerReady;
+    constructor(onServerReady: OnServerReady);
+    attach(hooks: TransportHooks): void;
+    listen(port: number, host?: string): Promise<ListeningServer>;
+}
+
+/**
+ * WebSocket adapter for Ingenium (optional `ws` peer dependency).
+ *
+ * # Usage
+ * ```ts
+ * import { ingenium } from 'ingenium'
+ * import { enableWebSockets } from 'ingenium/ws'
+ *
+ * const app = ingenium()
+ * enableWebSockets(app)
+ * app.ws('/echo', (sock) => {
+ *   sock.on('message', (m) => sock.send(m))
+ * })
+ * await app.listen(3000)
+ * ```
+ *
+ * # Why a monkey-patch?
+ * `enableWebSockets(app)` augments the app instance with `app.ws()` and
+ * wraps `app.listen()` so the registrar gets attached to the underlying
+ * `http.Server` once it's bound. We chose this over extending `IngeniumApp` to
+ * avoid pulling `./ws/middleware.ts` into the core import graph (which would
+ * create a soft dep on `ws` types from every `app.ts` consumer). This is a
+ * known pattern in WS-extending frameworks (e.g. `express-ws`).
+ *
+ * The trade-off: TypeScript can't statically see `app.ws` unless the
+ * augmentation below is loaded. Importing this module both registers the
+ * runtime patch AND adds the type augmentation to the global `IngeniumApp`.
+ */
+
+declare module '../app.ts' {
+    interface IngeniumApp {
+        ws(path: string, handler: WebSocketHandler, options?: WebSocketHandlerOptions): IngeniumApp;
+        upgradeWith(integrator: WsIntegrator): IngeniumApp;
+    }
+}
+/** Options for `enableWebSockets`. Reserved for future use. */
+interface EnableWebSocketsOptions {
+    /**
+     * When `true`, eagerly probes for the `ws` peer dependency at install
+     * time and prints a warning if it is missing. Default: `false` (we wait
+     * until the first upgrade attempt).
+     */
+    warnOnMissingPeer?: boolean;
+}
+/**
+ * Augment a `IngeniumApp` with WebSocket support. Idempotent — calling more than
+ * once on the same app is a no-op.
+ */
+declare function enableWebSockets(app: IngeniumApp, opts?: EnableWebSocketsOptions): void;
+
+/**
+ * Registry for the framework's lifecycle hooks. Implements the `Hooks`
+ * interface that plugins call into via `app.hooks`.
+ *
+ * # Execution model
+ *
+ * `runOn*` methods invoke listeners **sequentially** in registration order,
+ * awaiting each one before invoking the next. This is intentional:
+ *
+ *   - Predictable ordering: a hook registered first ALWAYS observes state
+ *     before a hook registered later. Plugins can rely on this.
+ *   - Backpressure: an async hook (e.g. fetching a session) blocks
+ *     subsequent hooks, ensuring downstream hooks see decorated state.
+ *   - Errors short-circuit `runOnRequest`/`runOnResponse`/`runOnCompose` —
+ *     they propagate to the caller (the request enters the error boundary).
+ *
+ * `runOnError` is the exception: it wraps each listener in a try/catch and
+ * swallows throws, because observers must not mask the original error.
+ *
+ * # Reading order
+ *
+ * Within a single `run*` call, listeners run in the order they were added.
+ * Across hook types within one request, the order is fixed by `app.handle`:
+ *
+ *   onRequest -> (decorators applied) -> dispatch -> onResponse
+ *                                                 \-> onError (on throw)
+ *
+ * # Hot-path note
+ *
+ * Each `runOn*` returns immediately if no listeners are registered. Callers
+ * should additionally check `hasAny()` (or the per-hook `has*()` helpers) to
+ * skip the `await` entirely on the zero-plugin path.
+ */
+declare class HooksRegistry implements Hooks {
+    private readonly _onRoute;
+    private readonly _onCompose;
+    private readonly _onRequest;
+    private readonly _onResponse;
+    private readonly _onError;
+    onRoute(fn: OnRouteHook): void;
+    onCompose(fn: OnComposeHook): void;
+    onRequest(fn: OnRequestHook): void;
+    onResponse(fn: OnResponseHook): void;
+    onError(fn: OnErrorHook): void;
+    /** True when any request-time hook is registered. */
+    hasAny(): boolean;
+    hasOnRequest(): boolean;
+    hasOnResponse(): boolean;
+    hasOnError(): boolean;
+    hasOnRoute(): boolean;
+    hasOnCompose(): boolean;
+    /** Synchronous — `onRoute` is invoked during composition for each route. */
+    runOnRoute(event: RegistrationEvent): void;
+    runOnCompose(): Promise<void>;
+    runOnRequest(ctx: IngeniumContext): Promise<void>;
+    runOnResponse(ctx: IngeniumContext): Promise<void>;
+    /** Observation only. Throws inside listeners are swallowed. */
+    runOnError(err: unknown, ctx: IngeniumContext): Promise<void>;
+}
+
+/**
+ * Per-app registry of decorators. Decorators are NOT installed onto
+ * `IngeniumContext.prototype` — that would mutate a shared class and leak across
+ * apps in the same process. Instead, `applyTo(ctx)` writes them onto each
+ * pooled context instance at request start.
+ *
+ * # Lazy vs eager — perf trade-off
+ *
+ * - **Lazy** (`decorate`): installed via `Object.defineProperty` with a
+ *   getter. The getter computes on first access, then redefines itself as
+ *   a plain data property holding the resolved value (define-self pattern).
+ *   Subsequent reads cost a normal property access — no getter call. Use
+ *   this for values that may not be needed (e.g. `ctx.user` on public
+ *   routes), and for values whose computation is non-trivial (DB lookups,
+ *   token decoding).
+ *
+ * - **Eager** (`decorateRequest`): factory is invoked at request start,
+ *   value assigned directly. Use this for cheap values that virtually every
+ *   handler will read (e.g. `ctx.startedAt = Date.now()`). Avoids the
+ *   per-property getter-redefinition overhead.
+ *
+ * # Pool reuse
+ *
+ * Pooled contexts are reset between requests; the `IngeniumContext.reset()`
+ * method does not know about decorator names, so each request re-applies
+ * via `applyTo(ctx)`. Lazy `defineProperty` overwrites the previous slot
+ * configuration cleanly; eager assignment overwrites the previous value.
+ * No leakage between requests.
+ */
+declare class DecoratorRegistry {
+    private readonly lazy;
+    private readonly eager;
+    /** Register a lazy decorator. Computed on first access; cached thereafter. */
+    decorate<T>(name: string, factory: LazyDecorator<T>): void;
+    /** Register an eager decorator. Factory runs at the start of every request. */
+    decorateRequest<T>(name: string, factory: EagerDecorator<T>): void;
+    /** True when any decorator is registered (lets the hot path skip work). */
+    hasAny(): boolean;
+    /**
+     * Install all registered decorators onto a single context instance.
+     * Called by `app.handle` after `onRequest` hooks and before dispatch.
+     */
+    applyTo(ctx: IngeniumContext): void;
+}
+
+/**
+ * `ScopedApp` — registration facade returned to the callback of
+ * `app.scope(prefix, registrar)`. Translates every registration call into a
+ * prefix-qualified registration on the underlying `IngeniumApp`, leveraging
+ * the existing Router scoping primitives (`use-prefix`, prefix-prepended
+ * paths) so the COMPOSE-TIME machinery does all the heavy lifting and the
+ * per-request hot path stays untouched.
+ *
+ * # Design
+ *
+ * - Holds a reference to the root `IngeniumApp` plus the ABSOLUTE prefix
+ *   (already includes any outer scope prefix). Nested scopes just construct
+ *   a new `ScopedApp` with `parent.prefix + sub`.
+ * - `scope.use(mw)` becomes `app.use(absolutePrefix, mw)` — the existing
+ *   `Router.use(prefix, mw)` plumbing produces a `use-prefix` registration,
+ *   and `flattenRouter` emits a `scopedMiddleware` entry that `app.compose()`
+ *   intersects against route paths via `pathStartsWith`.
+ * - `scope.get(path, handler)` becomes `app.method('GET', absolutePrefix + path, handler)`.
+ * - `scope.register(plugin, opts)` invokes the plugin with `this` as the
+ *   target. Any `target.use(...)` inside the plugin body is therefore
+ *   scope-prefixed; the plugin can't accidentally leak global middleware.
+ * - `scope.scope(sub, fn)` constructs a child `ScopedApp` and runs `fn`
+ *   against it.
+ *
+ * # Out of scope for V1 (documented footguns)
+ *
+ * - **Decorators**: `scope.decorate(...)` / `scope.decorateRequest(...)`
+ *   forward to the root app and decorate EVERY request, not just requests
+ *   under the scope's prefix. The reason is structural: decorators install
+ *   onto pooled `IngeniumContext` instances at request start, BEFORE the
+ *   route is matched — there's no path information available at that point
+ *   without re-shaping the dispatch path. Per-scope decorators would require
+ *   either (a) a runtime path check on every property access, or (b) a
+ *   separate decorator registry per scope keyed by matched route — both of
+ *   which move work onto the hot path and complicate the pool. For V1 we
+ *   accept the footgun and emit a one-shot `process.emitWarning` in
+ *   non-production environments to surface it.
+ * - **Hooks**: `scope.hooks` returns the SAME registry the root app uses.
+ *   Hook registration is global. A plugin that wants scope-aware hook
+ *   behavior should inspect `ctx.path` inside the hook body.
+ */
+
+/**
+ * @internal Friend-access surface a `ScopedApp` needs from its parent
+ * `IngeniumApp`. Kept narrow so refactors don't accidentally widen the
+ * coupling. The methods are implemented on `IngeniumApp` itself.
+ */
+interface ScopeHost {
+    use(mw: IngeniumMiddleware): IngeniumApp;
+    use(prefix: string, mw: IngeniumMiddleware | Router): IngeniumApp;
+    method(method: HttpMethod, path: string, handler: IngeniumHandler): IngeniumApp;
+    method(method: HttpMethod, path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): IngeniumApp;
+    decorate<T>(name: string, factory: LazyDecorator<T>): IngeniumApp;
+    decorateRequest<T>(name: string, factory: EagerDecorator<T>): IngeniumApp;
+    readonly hooks: Hooks;
+    /** @internal Marks the app's compose-cache dirty. */
+    _markDirty(): void;
+}
+/**
+ * A `ScopedApp` is the registration target passed to the `app.scope(prefix, registrar)`
+ * callback. It exposes the registration surface a plugin needs (`use`, verbs,
+ * `register`, `decorate`, `before`/`after`, nested `scope`) but NOT the
+ * dispatch surface (`compose`, `handle`, `listen`) — those still belong to
+ * the root app.
+ *
+ * Instances are cheap: a couple of fields and method-call forwarding. Do not
+ * cache them across recompose boundaries — they hold a reference to the
+ * `IngeniumApp` and rely on its mutable router journal.
+ */
+declare class ScopedApp implements PluginTarget {
+    /** @internal The root app this scope translates registrations onto. */
+    private readonly _app;
+    /** @internal Absolute prefix (already includes any outer scope's prefix). */
+    private readonly _prefix;
+    /** @internal Construct via `app.scope(...)`; not meant to be `new`'d directly. */
+    constructor(app: ScopeHost, prefix: string);
+    /** Absolute prefix this scope rewrites against (for debugging / introspection). */
+    get prefix(): string;
+    /** Lifecycle hooks. SHARED with the root app — hooks are global by design. */
+    get hooks(): Hooks;
+    use(mw: IngeniumMiddleware): this;
+    use(subPrefix: string, mw: IngeniumMiddleware | Router): this;
+    get(path: string, handler: IngeniumHandler): this;
+    get(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    post(path: string, handler: IngeniumHandler): this;
+    post(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    put(path: string, handler: IngeniumHandler): this;
+    put(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    patch(path: string, handler: IngeniumHandler): this;
+    patch(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    delete(path: string, handler: IngeniumHandler): this;
+    delete(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    head(path: string, handler: IngeniumHandler): this;
+    head(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    options(path: string, handler: IngeniumHandler): this;
+    options(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    method(method: HttpMethod, path: string, handler: IngeniumHandler): this;
+    method(method: HttpMethod, path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this;
+    /**
+     * Chainable per-path builder. The builder closes over `this.method`, which
+     * already does the scope-prefix join — so the same builder works identically
+     * on the root app and inside a scope. Typed params via `ExtractParams<P>`
+     * narrow against the RELATIVE path the user wrote, matching what the bare
+     * verb form does.
+     */
+    route<P extends string>(path: P): RouteBuilder<P>;
+    /**
+     * Register a lazy decorator. **WARNING:** decorators are GLOBAL even when
+     * registered inside a scope — they apply to every request regardless of
+     * the scope's prefix. The first call from inside any scope in a process
+     * emits a `process.emitWarning` (non-production only). See file header.
+     */
+    decorate<T>(name: string, factory: LazyDecorator<T>): this;
+    /**
+     * Register an eager decorator. **WARNING:** see {@link ScopedApp.decorate}.
+     */
+    decorateRequest<T>(name: string, factory: EagerDecorator<T>): this;
+    /**
+     * Register a plugin against THIS scope. The plugin receives the `ScopedApp`
+     * as its `target`, so any `target.use(...)` inside the plugin body is
+     * automatically prefix-scoped.
+     */
+    register<O>(plugin: IngeniumPlugin<O>, opts: O): Promise<this>;
+    register(plugin: IngeniumPlugin<void>): Promise<this>;
+    /**
+     * Open a nested scope. `subPrefix` is relative to this scope's prefix.
+     * The registrar may be async; the call returns a Promise that resolves
+     * once the registrar finishes if it returned one, otherwise resolves
+     * synchronously to `this`. We type-erase to `this` to match the
+     * `PluginTarget` interface, which can't express the sync-or-async return
+     * without polluting every caller.
+     */
+    scope(subPrefix: string, registrar: (scope: PluginTarget) => void): this;
+    /**
+     * Register a `before` filter scoped to this scope's prefix. If a pattern
+     * is given it's appended to the scope's prefix (so `scope('/api').before('/users', h)`
+     * matches `/api/users` and below). If omitted, the filter applies to the
+     * scope's full subtree.
+     */
+    before(handler: IngeniumMiddleware): this;
+    before(pattern: string, handler: IngeniumMiddleware): this;
+    /** Register an `after` filter scoped to this scope's prefix. See {@link ScopedApp.before}. */
+    after(handler: IngeniumMiddleware): this;
+    after(pattern: string, handler: IngeniumMiddleware): this;
+}
+
+/**
+ * Sinatra-style top-level shorthand.
+ *
+ * Lets users skip the app object entirely:
+ *
+ * ```ts
+ * import { get, post, listen } from 'ingenium'
+ *
+ * get('/', () => 'hi')
+ * get('/users/:id', (ctx) => ({ id: ctx.params.id }))
+ * post('/echo', async (ctx) => ctx.body.json())
+ *
+ * await listen(3000)
+ * ```
+ *
+ * All exported verbs route to a lazy singleton `IngeniumApp` created on first
+ * call. The instance is retained for the lifetime of the process; tests can
+ * call `_resetDefaultApp()` to drop it (this throws in production).
+ */
+
+/**
+ * Get the lazy default app. Created on first call, retained for the
+ * lifetime of the process (or until `_resetDefaultApp()` is invoked).
+ *
+ * The same instance is returned on every subsequent call, so all
+ * top-level verb functions and `listen()` operate on a single coherent
+ * registration journal.
+ */
+declare function defaultApp(): IngeniumApp;
+/**
+ * Reset the default app — for tests only. The next call to any top-level
+ * function will lazily create a fresh `IngeniumApp`. Throws when
+ * `NODE_ENV === 'production'` so accidental production calls are loud.
+ */
+declare function _resetDefaultApp(): void;
+declare function get(path: string, handler: IngeniumHandler): IngeniumApp;
+declare function post(path: string, handler: IngeniumHandler): IngeniumApp;
+declare function put(path: string, handler: IngeniumHandler): IngeniumApp;
+declare function patch(path: string, handler: IngeniumHandler): IngeniumApp;
+/**
+ * Default-app shorthand for `app.delete(path, handler)`.
+ * Exported as `del` because `delete` is a reserved word in JavaScript and
+ * cannot be used as a top-level identifier. `index.ts` re-exports this as
+ * `{ del as delete }` so the public name is `delete`.
+ */
+declare function del(path: string, handler: IngeniumHandler): IngeniumApp;
+declare function head(path: string, handler: IngeniumHandler): IngeniumApp;
+declare function options(path: string, handler: IngeniumHandler): IngeniumApp;
+/**
+ * Mount middleware on the default app. Same overload set as `app.use`:
+ *   - `use(mw)` — global
+ *   - `use(prefix, mw | Router)` — prefix-scoped
+ */
+declare function use(mw: IngeniumMiddleware): IngeniumApp;
+declare function use(prefix: string, mw: IngeniumMiddleware | Router): IngeniumApp;
+/** Default-app shorthand for `app.onError(handler)`. */
+declare function onError(handler: IngeniumErrorHandler): IngeniumApp;
+/**
+ * Bind the default app to a port. Returns a `ListeningServer` whose
+ * `.close()` shuts down the underlying transport. Pass `0` for an
+ * ephemeral port (useful in tests).
+ */
+declare function listen(port: number, host?: string): Promise<ListeningServer>;
+declare function before(handler: IngeniumMiddleware): IngeniumApp;
+declare function before(pattern: string, handler: IngeniumMiddleware): IngeniumApp;
+declare function after(handler: IngeniumMiddleware): IngeniumApp;
+declare function after(pattern: string, handler: IngeniumMiddleware): IngeniumApp;
+
+/**
+ * Ingenium — Express DX, Hono/Fastify throughput.
+ *
+ * @packageDocumentation
+ */
+
+declare const ingenium: IngeniumFactory & {
+    json: typeof jsonMiddleware;
+    urlencoded: typeof urlencodedMiddleware;
+    static: typeof staticMiddleware;
+    cors: typeof corsMiddleware;
+    csrf: typeof csrfMiddleware;
+    sse: typeof sse;
+    rateLimit: typeof rateLimit;
+    problemDetails: typeof problemDetailsMiddleware;
+    idempotency: typeof idempotencyMiddleware;
+    jwt: typeof jwtMiddleware;
+    apiKey: typeof apiKeyMiddleware;
+    openapiHandler: typeof openapiHandler;
+};
+
+export { type ApiKeyLogger, type ApiKeyOptions, type ApiKeyValidator, type CachedResponse, type CloseOptions, type ComposedHandler, type CookieGetOptions, type CookieSetOptions, type CorsOptions, type CorsOrigin, type CorsOriginFn, type CronHandler, type CronMatch, type CronOptions, CronRegistry, type CsrfCookieOptions, type CsrfOptions, type CsrfStorage, type CsrfValueReader, type Decorator, DecoratorRegistry, type EagerDecorator, type EnableWebSocketsOptions, type ExtractParams, type FailedJob, type FormatHandlers, type FormattableCtx, type ForwardedInfo, type GenerateOpenApiOptions, HTTP_METHODS, type HeaderBag, type Hooks, HooksRegistry, Http2Adapter, type Http2AdapterOptions, Http2cAdapter, type HttpMethod, IdempotencyMemoryStore, type IdempotencyOptions, type IdempotencyStore, IngeniumApp, type IngeniumAppOptions, IngeniumBadRequestError, IngeniumBody, IngeniumContext, IngeniumContextPool, type IngeniumCookies, IngeniumCronJob, IngeniumCsrfError, IngeniumError, type IngeniumErrorHandler, IngeniumHaltError, type IngeniumHandler, IngeniumHeaderInjectionError, IngeniumMethodNotAllowedError, type IngeniumMiddleware, IngeniumNotFoundError, IngeniumPayloadTooLargeError, type IngeniumPlugin, type IngeniumQuery, IngeniumQueue, IngeniumTimeoutError, IngeniumUnauthorizedError, IngeniumUnserializableError, IngeniumValidationError, type InjectRequest, type InjectResponse, type JobHandle, type JsonEtagCtx, type JsonEtagOptions, type JwtAlgorithm, type JwtHeader, type JwtKey, type JwtLogger, type JwtOptions, type JwtSecret, type JwtSecretResolver, type JwtTokenReader, type JwtVerified, type LazyDecorator, type ListeningServer, type MatchMiss, type MatchResult, MemoryQueueStore, type MultipartFile, type MultipartOptions, type MultipartResult, type NegotiableCtx, NodeAdapter, type OnComposeHook, type OnErrorHook, type OnRequestHook, type OnResponseHook, type OnRouteHook, type Components as OpenApiComponents, type Info as OpenApiInfo, type Response as OpenApiResponse, type Schema as OpenApiSchema, type SecurityRequirement as OpenApiSecurityRequirement, type SecurityScheme as OpenApiSecurityScheme, type Server as OpenApiServer, type OpenApiSpec, type Tag as OpenApiTag, type Operation, type Parameter, type ParseSchema, type ParsedAccept, type PathItem, type PluginTarget, type ProblemDetails, type ProblemDetailsOptions, type QueueOptions, QueueRegistry, type QueueStore, type QueueWorker, MemoryStore$1 as RateLimitMemoryStore, type RateLimitOptions, type RateLimitStore, type RegisteredQueue, type RegistrationEvent, type RequestBody, type ResponseBody, type RetryPolicy, RouteBuilder, type RouteDescriptor, type RouteOptions, Router, RouterTrie, type SafeJsonStringifyOptions, type SafeParseSchema, ScopedApp, type Session, type SessionCookieOptions, MemoryStore as SessionMemoryStore, type SessionOptions, type SessionStore, type ShutdownOptions, type SseEvent, type SseStream, type StandardFailureResult, type StandardIssue, type StandardPathSegment, type StandardResult, type StandardSchemaV1, type StandardSchemaV1Props, type StandardSuccessResult, type StaticOptions, type Transport, type TransportHooks, TrieNode, type TrustProxy, type WebSocket, type WebSocketHandler, type WebSocketHandlerOptions, type WsIntegrator, WsNodeAdapter, type WsRegistrar, _resetDefaultApp, accepts, acceptsCharsets, acceptsEncodings, acceptsLanguages, after, apiKeyMiddleware, before, clearJwksCache, compose, composeWithHandler, computeEtag, corsMiddleware as cors_, createWebSocketRegistrar, csrfMiddleware, ingenium as default, defaultApp, del as delete, enableWebSockets, expandShorthand, fetchJwks, formatResponse, generateOpenApi, get, gracefulShutdown, head, idempotencyMiddleware, ingenium, isFresh, isStandardSchema, jwtMiddleware, listen, nextFireFrom, onError, openapiHandler, options, parseAcceptHeader, parseCronSpec, patch, peerHasWs, post, problemDetailsMiddleware, put, rateLimit, resolveForwarded, respondJsonWithEtag, safeJsonStringify, selectBest, sessionMiddleware, sortByPreference, sse, startKeepAlive, staticMiddleware as static_, toProblemDetails, use, verifyJwt };