@orkestrel/middleware 0.0.18 → 0.0.19

package/dist/src/server/index.d.cts

@@ -1,12 +1,13 @@
 import { Encoding } from '@orkestrel/server';
 import { FileHandle } from 'node:fs/promises';
+import { HTTPError } from '@orkestrel/server';
 import { MiddlewareHandler } from '@orkestrel/server';
 import { MultipartBody } from '@orkestrel/middleware';
 import { MultipartFile } from '@orkestrel/middleware';
 import { MultipartState } from '@orkestrel/middleware';
 
 /**
- * One in-memory asset representation returned by an {@link AssetSourceInterface}.
+ * Describes one in-memory asset representation returned by an {@link AssetSourceInterface}.
  *
  * @remarks
  * - `body` — the representation bytes. `createAssets` copies them before use.
@@ -19,26 +20,32 @@ export declare interface Asset {
 }
 
 /**
- * Options for `createAssets` — in-memory identity/Brotli asset serving.
+ * Configures `createAssets` — in-memory identity/Brotli asset serving.
  *
- * @param options - See fields below
  * @remarks
- * - `source` — the required in-memory asset reader.
+ * - `source` — the required in-memory asset reader. It MUST answer a bounded
+ *   key set and return `undefined` for every key outside it, because
+ *   `createAssets` retains every successful result for the factory's lifetime
+ *   and evicts nothing. A `source` that synthesizes a representation for an
+ *   arbitrary key therefore grows that cache without limit under request
+ *   pressure.
  */
 export declare interface AssetOptions {
     readonly source: AssetSourceInterface;
 }
 
 /**
- * Read in-memory assets by decoded, browser-build-relative path.
+ * Reads in-memory assets by decoded, browser-build-relative path.
  *
  * @remarks
  * A successful result is cached by `createAssets`; later source changes do
  * not alter that path's response. A miss may be read again on a later request.
+ * `read` therefore owes a BOUNDED key set: that cache retains every
+ * successful result for the factory's lifetime and evicts nothing.
  */
 export declare interface AssetSourceInterface {
     /**
-     * Read one asset representation.
+     * Reads one asset representation.
      *
      * @param path - The validated relative asset path
      * @returns The asset, or `undefined` when the path is absent
@@ -47,7 +54,24 @@ export declare interface AssetSourceInterface {
 }
 
 /**
- * Compress response bytes with Node's guaranteed zlib gzip/deflate codecs.
+ * Describes one inclusive byte range over a file — `streamFile`'s optional
+ * `range` argument and the shape `createStatic` builds for a satisfiable
+ * `Range` request.
+ *
+ * @remarks
+ * - `start` — the first byte offset served.
+ * - `end` — the last byte offset served.
+ *
+ * Both bounds are 0-indexed and inclusive, matching `node:fs`'s
+ * `createReadStream` options.
+ */
+export declare interface ByteRange {
+    readonly start: number;
+    readonly end: number;
+}
+
+/**
+ * Compresses response bytes with Node's guaranteed zlib gzip/deflate codecs.
  *
  * @param bytes - The uncompressed response bytes
  * @param encoding - The negotiated actionable coding
@@ -62,7 +86,7 @@ export declare interface AssetSourceInterface {
 export declare function compressNodeBytes(bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>): Promise<Uint8Array<ArrayBuffer>>;
 
 /**
- * Compute a static file's weak ETag from its size and modification time.
+ * Computes a static file's weak ETag from its size and modification time.
  *
  * @param size - The file's byte size
  * @param mtimeMs - The file's modification time in milliseconds
@@ -76,7 +100,7 @@ export declare function compressNodeBytes(bytes: Uint8Array<ArrayBuffer>, encodi
 export declare function computeFileETag(size: number, mtimeMs: number): string;
 
 /**
- * Serve validated in-memory assets with identity/Brotli negotiation.
+ * Serves validated in-memory assets with identity/Brotli negotiation.
  *
  * @remarks
  * Only `GET` and `HEAD` are served. `/` resolves to `index.html`. Every other
@@ -112,20 +136,19 @@ export declare function computeFileETag(size: number, mtimeMs: number): string;
 export declare function createAssets<TState>(options: AssetOptions): MiddlewareHandler<TState>;
 
 /**
- * Compress response bodies via `node:zlib` — the node-bound sibling of the
- * core face's `CompressionStream`-feature-detected `createCompression`,
+ * Compresses response bodies through `node:zlib` — the node-bound sibling of
+ * the core face's `CompressionStream`-feature-detected `createCompression`,
  * guaranteed available on any Node runtime rather than dependent on the
- * WHATWG `CompressionStream` global (PROPOSAL §4.3, ruling J). Ships as a
- * SEPARATE package entry point (`@orkestrel/middleware/server`) from the core
- * face's `createCompression`, so the shared name is unambiguous per
- * consumer import path (ruling H).
+ * WHATWG `CompressionStream` global. Ships as a SEPARATE package entry point
+ * (`@orkestrel/middleware/server`) from the core face's `createCompression`,
+ * so the shared name is unambiguous per consumer import path.
  *
  * @remarks
- * Peer-type limitation (same one U1 recorded on the core face): the shipped
+ * Peer-type limitation, the same one the core face carries: the shipped
  * `@orkestrel/server` `Encoding` union is `'gzip' | 'deflate' | 'identity'`
  * — it does not include `'br'`, so this battery cannot honestly type or
  * negotiate a guaranteed brotli coding despite `node:zlib` shipping
- * `brotliCompress`. It guarantees `gzip`/`deflate` via `node:zlib` (never
+ * `brotliCompress`. It guarantees `gzip`/`deflate` through `node:zlib` (never
  * feature-detected — always available) and negotiates only those.
  *
  * @typeParam TState - The consumer's opaque per-request state type
@@ -144,9 +167,9 @@ export declare function createAssets<TState>(options: AssetOptions): MiddlewareH
 export declare function createCompression<TState>(options?: NodeCompressionOptions): MiddlewareHandler<TState>;
 
 /**
- * Parse a streamed `multipart/form-data` request body and stash its
+ * Parses a streamed `multipart/form-data` request body and stashes its
  * {@link MultipartBody} on `context.state.multipart` — the node-bound
- * streaming multipart battery (PROPOSAL §4.15, ruling C).
+ * streaming multipart battery.
  *
  * @remarks
  * A non-multipart request passes through untouched. Consumes `request.body`
@@ -177,8 +200,8 @@ export declare function createCompression<TState>(options?: NodeCompressionOptio
 export declare function createMultipart<TState extends MultipartState>(options?: MultipartOptions): MiddlewareHandler<TState>;
 
 /**
- * Serve static files from `options.root` over `node:fs` — the node-bound
- * static-file battery (PROPOSAL §4.14).
+ * Serves static files from `options.root` over `node:fs` — the node-bound
+ * static-file battery.
  *
  * @remarks
  * Containment is enforced on CANONICAL paths, not merely the lexically
@@ -193,7 +216,7 @@ export declare function createMultipart<TState extends MultipartState>(options?:
  * that carries a file body), the open `FileHandle` is owned by the
  * `Response` body and is released only once that body is fully read or
  * cancelled — Node HTTP servers do this automatically when sending the
- * response, but a caller that holds an unread `Response` (e.g. in a test)
+ * response, but a caller that holds an unread `Response` (for example in a test)
  * must cancel its body to release the handle promptly.
  *
  * @typeParam TState - The consumer's opaque per-request state type
@@ -211,47 +234,56 @@ export declare function createMultipart<TState extends MultipartState>(options?:
 export declare function createStatic<TState>(options: StaticOptions): MiddlewareHandler<TState>;
 
 /**
- * Build a frozen {@link UploadedFileInterface} record.
+ * Builds a frozen {@link UploadedFile} record.
  *
  * @param input - Every field of the record
- * @returns A frozen {@link UploadedFileInterface}
+ * @returns A frozen {@link UploadedFile}
  *
  * @example
  * ```ts
  * createUploadedFile({ field: 'avatar', name: 'a.png', size: 1024, mime: 'image/png', validated: true, status: 'staged', path: '/tmp/x' })
  * ```
  */
-export declare function createUploadedFile(input: UploadedFileInput): UploadedFileInterface;
+export declare function createUploadedFile(input: UploadedFile): UploadedFile;
 
-/** The MIME type served when a file extension has no known mapping. */
+/** Names the MIME type served when a file extension has no known mapping. */
 export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
 
-/** `createMultipart`'s default per-field byte-size cap. */
-export declare const DEFAULT_MULTIPART_FIELD = 65536;
+/** Holds `createMultipart`'s default maximum field-part count. */
+export declare const DEFAULT_MULTIPART_FIELD_COUNT = 100;
 
-/** `createMultipart`'s default maximum field-part count. */
-export declare const DEFAULT_MULTIPART_FIELDS = 100;
+/** Holds `createMultipart`'s default per-field byte-size cap. */
+export declare const DEFAULT_MULTIPART_FIELD_SIZE = 65536;
 
-/** `createMultipart`'s default per-file byte-size cap. */
-export declare const DEFAULT_MULTIPART_FILE = 10485760;
+/** Holds `createMultipart`'s default maximum file-part count. */
+export declare const DEFAULT_MULTIPART_FILE_COUNT = 10;
 
-/** `createMultipart`'s default maximum file-part count. */
-export declare const DEFAULT_MULTIPART_FILES = 10;
+/** Holds `createMultipart`'s default per-file byte-size cap. */
+export declare const DEFAULT_MULTIPART_FILE_SIZE = 10485760;
 
-/** `createMultipart`'s default combined request-body byte-size cap. */
+/** Holds `createMultipart`'s default combined request-body byte-size cap. */
 export declare const DEFAULT_MULTIPART_TOTAL = 52428800;
 
-/** `createStatic`'s `fallback: true` default excluded path prefix. */
+/** Names `createStatic`'s default policy for a path carrying a dotfile segment. */
+export declare const DEFAULT_STATIC_DOTFILES: NonNullable<StaticOptions['dotfiles']>;
+
+/** Names `createStatic`'s `fallback: true` default excluded path prefix. */
 export declare const DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
 
-/** `createStatic`'s default directory-index filename. */
+/** Names `createStatic`'s default directory-index filename. */
 export declare const DEFAULT_STATIC_INDEX = "index.html";
 
 /**
- * Sniff a MIME type from a file's leading bytes against a small magic-byte
- * table (jpeg, png, gif87a/89a, webp, pdf, zip) — the SNIFF-AUTHORITATIVE
- * signal `createMultipart`'s type validation rests on, never the declared
- * `Content-Type`.
+ * Sniffs a MIME type from a file's leading bytes against a small magic-byte
+ * table (jpeg, png, gif87a/89a, webp, pdf, zip).
+ *
+ * @remarks
+ * `createMultipart`'s `allowed` check reads this signal alone and never the
+ * declared `Content-Type`, so a file whose bytes match no signature can never
+ * be placed on an `allowed` list. The record's `mime` field is a different
+ * question: it falls back to the declared `Content-Type` (then to
+ * {@link DEFAULT_CONTENT_TYPE}) when nothing sniffs, and its `validated` flag
+ * reports whether the sniffed and declared types agreed.
  *
  * @param head - The file's first bytes (16 is sufficient for every signature)
  * @returns The detected MIME type, or `undefined` when no signature matches
@@ -263,11 +295,27 @@ export declare const DEFAULT_STATIC_INDEX = "index.html";
  */
 export declare function detectMIME(head: Uint8Array): string | undefined;
 
-/** File-extension (lowercase, with leading `.`) → MIME type lookup table for static serving. */
+/** Holds the file-extension (lowercase, with leading `.`) → MIME type lookup table for static serving. */
 export declare const EXTENSION_TYPES: Readonly<Record<string, string>>;
 
 /**
- * Whether `child` is `parent` itself or lies inside it on-disk — the
+ * Extracts the `boundary` parameter from a `Content-Type` header, or
+ * `undefined` when the request is not `multipart/form-data`.
+ *
+ * @param contentType - The request's `Content-Type` header value, if present
+ * @returns The multipart boundary token, or `undefined` for a non-multipart
+ * (or malformed/boundary-less) content type
+ *
+ * @example
+ * ```ts
+ * extractMultipartBoundary('multipart/form-data; boundary=abc123') // 'abc123'
+ * extractMultipartBoundary('application/json') // undefined
+ * ```
+ */
+export declare function extractMultipartBoundary(contentType: string | null): string | undefined;
+
+/**
+ * Checks whether `child` is `parent` itself or lies inside it on-disk — the
  * FILESYSTEM containment predicate `createStatic` applies to `fs.realpath`
  * output (never to a URL pathname — that is {@link isUnderPath}'s job).
  *
@@ -281,7 +329,7 @@ export declare const EXTENSION_TYPES: Readonly<Record<string, string>>;
  *
  * @param child - The absolute on-disk path to test
  * @param parent - The absolute on-disk directory it must lie under
- * @returns `true` when `child` equals `parent` or resolves inside it
+ * @returns True if `child` equals `parent` or resolves inside it; false otherwise
  *
  * @example
  * ```ts
@@ -292,11 +340,11 @@ export declare const EXTENSION_TYPES: Readonly<Record<string, string>>;
 export declare function isContainedPath(child: string, parent: string): boolean;
 
 /**
- * Whether a relative path (already resolved under a static root) has any
+ * Checks whether a relative path (already resolved under a static root) has any
  * segment starting with `.` — a dotfile or dot-directory.
  *
  * @param relativePath - A path relative to the static root
- * @returns `true` when any segment starts with `.`
+ * @returns True if any segment starts with `.`; false otherwise
  *
  * @example
  * ```ts
@@ -307,16 +355,16 @@ export declare function isContainedPath(child: string, parent: string): boolean;
 export declare function isDotfilePath(relativePath: string): boolean;
 
 /**
- * Narrow an unknown caught value to a {@link MultipartError}.
+ * Narrows an unknown caught value to a {@link MultipartError}.
  *
  * @remarks
  * Structural, not `instanceof` — tests that `value` is a non-null object
- * carrying the module-scope brand, a numeric `status`, and a `reason` in the
- * parser's set of reason strings (`'limit' | 'malformed' | 'rejected'`).
+ * carrying {@link MULTIPART_ERROR_BRAND}, a numeric `status`, and a `code`
+ * in the parser's {@link MultipartErrorCode} set (`'limit' | 'malformed' | 'rejected'`).
  * Total: never throws, returns `false` for any off-shape input.
  *
  * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is a {@link MultipartError}
+ * @returns True if `value` is a {@link MultipartError}; false otherwise
  *
  * @example
  * ```ts
@@ -325,14 +373,14 @@ export declare function isDotfilePath(relativePath: string): boolean;
  * try {
  * 	await parse(request)
  * } catch (error) {
- * 	if (isMultipartError(error)) console.log(error.status, error.reason)
+ * 	if (isMultipartError(error)) console.log(error.status, error.code)
  * }
  * ```
  */
 export declare function isMultipartError(value: unknown): value is MultipartError;
 
 /**
- * Whether a path segment is a Windows reserved device name (CVE-2025-27210).
+ * Checks whether a path segment is a Windows reserved device name (CVE-2025-27210).
  *
  * @remarks
  * Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
@@ -342,7 +390,7 @@ export declare function isMultipartError(value: unknown): value is MultipartErro
  * `console.js` and `nullable.css` are never flagged.
  *
  * @param segment - One path segment (no separators)
- * @returns `true` when `segment` names a reserved device
+ * @returns True if `segment` names a reserved device; false otherwise
  *
  * @example
  * ```ts
@@ -354,14 +402,14 @@ export declare function isMultipartError(value: unknown): value is MultipartErro
 export declare function isReservedDeviceName(segment: string): boolean;
 
 /**
- * Whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+ * Checks whether `pathname` is `prefix` itself or lies under it on a SEGMENT
  * boundary — the shared under-path test `resolveStaticPath`'s prefix strip
  * and `createStatic`'s SPA-fallback `exclude` both apply, so `exclude:
  * '/api'` matches `/api` and `/api/x` but never `/apifoo`.
  *
  * @param pathname - The request pathname to test
  * @param prefix - The path prefix to test against
- * @returns `true` when `pathname` equals `prefix` or starts with `prefix` + `/`
+ * @returns True if `pathname` equals `prefix` or starts with `prefix` + `/`; false otherwise
  *
  * @example
  * ```ts
@@ -372,7 +420,7 @@ export declare function isReservedDeviceName(segment: string): boolean;
 export declare function isUnderPath(pathname: string, prefix: string): boolean;
 
 /**
- * Look up the MIME type for a static file path by its extension.
+ * Looks up the MIME type for a static file path by its extension.
  *
  * @param pathname - The file's path (only its extension is read)
  * @returns The mapped MIME type, or {@link DEFAULT_CONTENT_TYPE} when unknown
@@ -385,12 +433,12 @@ export declare function isUnderPath(pathname: string, prefix: string): boolean;
 export declare function lookupContentType(pathname: string): string;
 
 /**
- * Whether `bytes` contains `signature` at the requested offset.
+ * Checks whether `bytes` contains `signature` at the requested offset.
  *
  * @param bytes - The bytes to inspect
  * @param signature - The exact byte sequence to match
  * @param offset - The starting byte offset, defaulting to zero
- * @returns `true` when the complete signature matches
+ * @returns True if the complete signature matches; false otherwise
  *
  * @example
  * ```ts
@@ -400,59 +448,56 @@ export declare function lookupContentType(pathname: string): string;
 export declare function matchesBytes(bytes: Uint8Array, signature: readonly number[], offset?: number): boolean;
 
 /**
- * Move a staged uploaded file to its final `destination`.
+ * Moves a staged uploaded file to its final `destination`.
  *
  * @remarks
  * Attempts a `rename` first; on a cross-device error (`EXDEV`) falls back to
  * `copyFile` + `unlink`. Returns a new frozen record with `status: 'moved'`
- * and `path: destination` — the input record is never mutated.
+ * and `path: destination` — the input record is never mutated. The suite
+ * drives the `EXDEV` fallback only on a host whose device probe finds a
+ * second filesystem, so a single-device host leaves that branch unproven.
  *
- * @param file - The {@link UploadedFileInterface} record to move
+ * @param file - The {@link UploadedFile} record to move
  * @param destination - The final on-disk path
- * @returns A new {@link UploadedFileInterface} record reflecting the move
+ * @returns A new {@link UploadedFile} record reflecting the move
  *
  * @example
  * ```ts
  * const moved = await moveUploadedFile(file, '/var/uploads/final.png')
  * ```
  */
-export declare function moveUploadedFile(file: UploadedFileInterface, destination: string): Promise<UploadedFileInterface>;
+export declare function moveUploadedFile(file: UploadedFile, destination: string): Promise<UploadedFile>;
 
-/** The maximum bytes a single multipart part's header block may occupy before it is malformed. */
+/**
+ * Holds the `Symbol.for` brand {@link MultipartError} carries so
+ * {@link isMultipartError} recognizes an instance across duplicate copies of
+ * this package — a registry symbol rather than a module-local `Symbol()`,
+ * which would mint an unequal symbol per copy.
+ */
+export declare const MULTIPART_ERROR_BRAND: unique symbol;
+
+/** Holds the maximum bytes a single multipart part's header block may occupy before it is malformed. */
 export declare const MULTIPART_MAX_HEADER_BLOCK = 16384;
 
-/** The maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+/** Holds the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
 export declare const MULTIPART_MAX_PREAMBLE = 65536;
 
-/** The HTTP status `createMultipart` renders for each {@link MultipartReason}. */
-export declare const MULTIPART_REASON_STATUS: Readonly<Record<MultipartReason, number>>;
-
-/**
- * Extract the `boundary` parameter from a `Content-Type` header, or
- * `undefined` when the request is not `multipart/form-data`.
- *
- * @param contentType - The request's `Content-Type` header value, if present
- * @returns The multipart boundary token, or `undefined` for a non-multipart
- * (or malformed/boundary-less) content type
- *
- * @example
- * ```ts
- * multipartBoundary('multipart/form-data; boundary=abc123') // 'abc123'
- * multipartBoundary('application/json') // undefined
- * ```
- */
-export declare function multipartBoundary(contentType: string | null): string | undefined;
+/** Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}. */
+export declare const MULTIPART_STATUS: Readonly<Record<MultipartErrorCode, number>>;
 
 /**
- * An error `createMultipart` throws when a streamed multipart request fails
+ * Represents an error `createMultipart` throws when a streamed multipart request fails
  * a mid-stream limit, is structurally malformed, or has a file whose sniffed
  * bytes are rejected by the configured `allowed` MIME list.
  *
  * @remarks
- * Carries the HTTP `status` derived from `reason` (limit → 413, malformed →
- * 400, rejected → 415) and an optional `context` record. Rendered by
- * `createBoundary` like any other `HTTPError`-shaped throw. Narrow a caught
- * value with {@link isMultipartError}.
+ * Extends the peer `HTTPError`, which already publishes the `status`,
+ * `context`, and brand members every fleet error of this shape carries, and
+ * adds the machine-readable `code` axis a caller narrows on. `status` is
+ * derived from `code` through {@link MULTIPART_STATUS} (limit → 413, malformed →
+ * 400, rejected → 415), so `createBoundary` — or any other `isHTTPError`-aware
+ * renderer — maps it without knowing this face's error type. Narrow a caught
+ * value to the richer type with {@link isMultipartError}.
  *
  * @example
  * ```ts
@@ -461,43 +506,76 @@ export declare function multipartBoundary(contentType: string | null): string |
  * throw new MultipartError('limit', 'too many files')
  * ```
  */
-export declare class MultipartError extends Error {
-    readonly status: number;
-    readonly reason: MultipartReason;
-    readonly context?: Readonly<Record<string, unknown>>;
-    constructor(reason: MultipartReason, message: string, context?: Readonly<Record<string, unknown>>);
+export declare class MultipartError extends HTTPError {
+    readonly code: MultipartErrorCode;
+    readonly [MULTIPART_ERROR_BRAND] = true;
+    constructor(code: MultipartErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * Per-category size/count caps `createMultipart` enforces MID-STREAM.
+ * Names the reason `createMultipart` rejected a request — the machine-readable code
+ * {@link MultipartError} carries and maps onto its HTTP status: `'limit'` →
+ * 413, `'malformed'` → 400, `'rejected'` → 415.
+ */
+export declare type MultipartErrorCode = 'limit' | 'malformed' | 'rejected';
+
+/**
+ * Describes the per-category size/count caps `createMultipart` enforces MID-STREAM — the
+ * effective limits, every documented default already applied.
  *
  * @remarks
- * - `file` — the maximum size in bytes of one uploaded file; defaults to
- *   {@link DEFAULT_MULTIPART_FILE}.
- * - `files` — the maximum number of file parts; defaults to
- *   {@link DEFAULT_MULTIPART_FILES}.
- * - `field` — the maximum size in bytes of one text field; defaults to
- *   {@link DEFAULT_MULTIPART_FIELD}.
- * - `fields` — the maximum number of text field parts; defaults to
- *   {@link DEFAULT_MULTIPART_FIELDS}.
+ * - `file.size` — the maximum size in bytes of one uploaded file; defaults to
+ *   {@link DEFAULT_MULTIPART_FILE_SIZE}.
+ * - `file.count` — the maximum number of file parts; defaults to
+ *   {@link DEFAULT_MULTIPART_FILE_COUNT}.
+ * - `field.size` — the maximum size in bytes of one text field; defaults to
+ *   {@link DEFAULT_MULTIPART_FIELD_SIZE}.
+ * - `field.count` — the maximum number of text field parts; defaults to
+ *   {@link DEFAULT_MULTIPART_FIELD_COUNT}.
  * - `total` — the maximum combined byte size of the whole request body;
  *   defaults to {@link DEFAULT_MULTIPART_TOTAL}.
  */
 export declare interface MultipartLimits {
-    readonly file?: number;
-    readonly files?: number;
-    readonly field?: number;
-    readonly fields?: number;
+    readonly file: {
+        readonly size: number;
+        readonly count: number;
+    };
+    readonly field: {
+        readonly size: number;
+        readonly count: number;
+    };
+    readonly total: number;
+}
+
+/**
+ * Describes the caller's partial {@link MultipartLimits} — `createMultipart`'s `limits`
+ * option, with every member optional.
+ *
+ * @remarks
+ * `resolveMultipartLimits` applies each documented default to an omitted leaf,
+ * so a caller states only the caps it wants to move.
+ * - `file` — the per-file caps: `size` in bytes, `count` of file parts.
+ * - `field` — the per-field caps: `size` in bytes, `count` of text field parts.
+ * - `total` — the maximum combined byte size of the whole request body.
+ */
+export declare interface MultipartLimitsInput {
+    readonly file?: {
+        readonly size?: number;
+        readonly count?: number;
+    };
+    readonly field?: {
+        readonly size?: number;
+        readonly count?: number;
+    };
     readonly total?: number;
 }
 
 /**
- * Options for `createMultipart` — node `fs`/`os`/`crypto`-backed streaming
+ * Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming
  * multipart upload parsing.
  *
- * @param options - See fields below
  * @remarks
- * - `limits` — see {@link MultipartLimits}.
+ * - `limits` — see {@link MultipartLimitsInput}.
  * - `allowed` — a MIME allow-list validated against SNIFFED (not merely
  *   declared) bytes; an empty array allows nothing. Omitted ⇒ no type
  *   rejection.
@@ -505,30 +583,30 @@ export declare interface MultipartLimits {
  *   `os.tmpdir()`.
  */
 export declare interface MultipartOptions {
-    readonly limits?: MultipartLimits;
+    readonly limits?: MultipartLimitsInput;
     readonly allowed?: readonly string[];
     readonly directory?: string;
 }
 
 /**
- * Why `createMultipart` rejected a request — the axis {@link MultipartError}
- * maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400,
- * `'rejected'` → 415.
+ * Lists the content-codings the node face's `createCompression` offers — the two
+ * `node:zlib` guarantees on every Node runtime, so this face never
+ * feature-detects.
  */
-export declare type MultipartReason = 'limit' | 'malformed' | 'rejected';
+export declare const NODE_COMPRESSION_ENCODINGS: readonly Encoding[];
 
 /**
- * Options for the node face's `createCompression` — `node:zlib`-backed
+ * Configures the node face's `createCompression` — `node:zlib`-backed
  * response compression.
  *
- * @param options - See fields below
  * @remarks
  * - `threshold` — the minimum buffered body size (bytes) worth compressing;
  *   defaults to {@link DEFAULT_COMPRESSION_THRESHOLD}.
  * - `filter` — an additional predicate a response must pass before
- *   compression is attempted; defaults to always-allow. `encodings` is fixed
- *   to `['gzip', 'deflate']` and is not configurable (see the peer `Encoding`
- *   type limitation documented on `createCompression`).
+ *   compression is attempted; defaults to always-allow. The offered codings
+ *   are fixed to {@link NODE_COMPRESSION_ENCODINGS} and are not configurable
+ *   (see the peer `Encoding` type limitation documented on
+ *   `createCompression`).
  */
 export declare interface NodeCompressionOptions {
     readonly threshold?: number;
@@ -536,14 +614,14 @@ export declare interface NodeCompressionOptions {
 }
 
 /**
- * Stream-parse a `multipart/form-data` request into its files and fields —
- * the mid-stream state machine `createMultipart` drives (PROPOSAL §4.15).
+ * Stream-parses a `multipart/form-data` request into its files and fields —
+ * the mid-stream state machine `createMultipart` drives.
  *
  * @remarks
- * Reads `request.body` chunk by chunk via its `ReadableStream` reader —
+ * Reads `request.body` chunk by chunk through its `ReadableStream` reader —
  * NEVER buffers the whole body — enforcing every {@link MultipartLimits} cap
  * the instant it is exceeded (reading stops, every already-staged temp file
- * is deleted, throws {@link MultipartError} with reason `'limit'`). Each file
+ * is deleted, throws {@link MultipartError} with code `'limit'`). Each file
  * part streams to `join(directory, randomUUID())` — the client's declared
  * filename is METADATA ONLY, never a path component. A field OR file part
  * named `__proto__` / `constructor` / `prototype` is silently skipped and
@@ -552,18 +630,22 @@ export declare interface NodeCompressionOptions {
  * referenced). A file part with an empty declared filename (`filename=""`)
  * AND a zero-byte body — the browser convention for an unselected optional
  * `<input type="file">` — is a silent no-op: its temp file is unlinked, it is
- * never counted against the `files` limit, and it never runs the `allowed`
- * check. A malformed
+ * never counted against the `file.count` limit, and it never runs the
+ * `allowed` check. A malformed
  * structure (missing/unterminated boundary, nameless part, an oversized
  * header block, or a preamble exceeding {@link MULTIPART_MAX_PREAMBLE} before
- * the first boundary) throws with reason `'malformed'`. A file is accepted
+ * the first boundary) throws with code `'malformed'`. A file is accepted
  * against the configured `allowed` MIME list iff its SNIFFED bytes detect a
  * type present in the list — sniff-authoritative, independent of whether the
  * declared `Content-Type` matches (that agreement is exposed separately as
- * `validated`); otherwise throws with reason `'rejected'`. A
+ * `validated`); otherwise throws with code `'rejected'`. A
  * request abort mid-upload triggers the same fail-closed cleanup as a limit
  * breach. Returns `undefined` for a non-multipart request (untouched).
  *
+ * Staging defaults to a process-owned directory created ONCE (lazily,
+ * memoized across calls) with `mkdtemp` under `os.tmpdir()` and locked to
+ * mode `0o700`; `options.directory` overrides it.
+ *
  * @param request - The incoming multipart request
  * @param options - See {@link MultipartOptions}
  * @returns The parsed {@link MultipartBody}, or `undefined` when the request
@@ -579,41 +661,41 @@ export declare interface NodeCompressionOptions {
 export declare function parseMultipartRequest(request: Request, options?: MultipartOptions): Promise<MultipartBody | undefined>;
 
 /**
- * Parse one multipart part's raw header block into its `name` (from
+ * Parses one multipart part's raw header block into its `name` (from
  * `Content-Disposition`), optional `filename`, and optional `Content-Type`.
  *
  * @param block - The raw header block for one multipart part (before the
  * terminating blank line)
- * @returns The parsed `name`, `filename`, and `contentType` (each
- * `undefined` when absent)
+ * @returns The parsed `name`, `filename`, and `mime` (each `undefined` when
+ * absent)
  *
  * @example
  * ```ts
  * parsePartHeaders('Content-Disposition: form-data; name="title"')
- * // { name: 'title', filename: undefined, contentType: undefined }
+ * // { name: 'title', filename: undefined, mime: undefined }
  * ```
  */
 export declare function parsePartHeaders(block: string): PartHeaders;
 
 /**
- * One multipart part's parsed header block — `parsePartHeaders`'s return
+ * Describes one multipart part's parsed header block — `parsePartHeaders`'s return
  * shape.
  *
  * @remarks
  * - `name` — the `Content-Disposition` `name` parameter, or `undefined` when absent.
  * - `filename` — the `Content-Disposition` `filename` parameter, or `undefined` when absent.
- * - `contentType` — the part's declared `Content-Type` header value, or `undefined` when absent.
+ * - `mime` — the part's declared `Content-Type` header value, or `undefined` when absent.
  */
 export declare interface PartHeaders {
     readonly name: string | undefined;
     readonly filename: string | undefined;
-    readonly contentType: string | undefined;
+    readonly mime: string | undefined;
 }
 
 /**
- * Read a staged/moved uploaded file's full contents into memory.
+ * Reads a staged/moved uploaded file's full contents into memory.
  *
- * @param file - The {@link UploadedFileInterface} record to read
+ * @param file - The {@link UploadedFile} record to read
  * @returns The file's bytes
  *
  * @example
@@ -621,46 +703,65 @@ export declare interface PartHeaders {
  * const bytes = await readUploadedFile(file)
  * ```
  */
-export declare function readUploadedFile(file: UploadedFileInterface): Promise<Uint8Array>;
+export declare function readUploadedFile(file: UploadedFile): Promise<Uint8Array>;
 
 /**
- * Windows reserved device-name stems (CVE-2025-27210) — matched
+ * Lists the Windows reserved device-name stems (CVE-2025-27210) — matched
  * case-insensitively against the segment's stem (before its first `.`).
  */
 export declare const RESERVED_DEVICE_NAMES: ReadonlySet<string>;
 
 /**
- * Resolve `parseMultipartRequest`'s default staging directory when the
- * caller did not configure one — a process-owned directory created ONCE
- * (lazily, memoized across calls) via `mkdtemp` under `os.tmpdir()` and
- * locked to mode `0o700`.
+ * Canonicalizes `candidate` and returns it only when it lies inside `rootReal`
+ * — the shared realpath-then-contain step `createStatic` applies to a
+ * directory index and to its SPA shell.
  *
- * @returns The absolute path of the process-owned staging directory
+ * @remarks
+ * Total: a `realpath` failure (a dangling symlink, a missing file, a
+ * permission refusal) and an escape from `rootReal` both resolve `undefined`,
+ * so a caller that treats those two outcomes identically needs no `try`. A
+ * caller that must tell them apart keeps its own explicit branch instead.
+ *
+ * @param candidate - The on-disk path to canonicalize
+ * @param rootReal - The already-canonical root the result must lie under
+ * @returns The canonical path inside `rootReal`, or `undefined`
  *
  * @example
  * ```ts
- * const directory = await resolveDefaultDirectory()
+ * await resolveContainedRealPath('/srv/public/index.html', '/srv/public')
+ * // '/srv/public/index.html'
  * ```
  */
-export declare function resolveDefaultDirectory(): Promise<string>;
+export declare function resolveContainedRealPath(candidate: string, rootReal: string): Promise<string | undefined>;
 
 /**
- * Resolve `createMultipart`'s effective {@link MultipartLimits}, applying
- * every documented default.
+ * Resolves `createMultipart`'s effective {@link MultipartLimits}, applying
+ * every documented default to an omitted leaf.
  *
  * @param limits - The caller's partial limits
  * @returns The fully-resolved limits
+ *
+ * @example
+ * ```ts
+ * resolveMultipartLimits({ file: { size: 1_048_576 } })
+ * ```
  */
-export declare function resolveMultipartLimits(limits: MultipartLimits | undefined): Required<MultipartLimits>;
+export declare function resolveMultipartLimits(limits: MultipartLimitsInput | undefined): MultipartLimits;
 
 /**
- * Resolve the fixed SPA shell path when a static-file miss is eligible for
+ * Resolves the fixed SPA shell path when a static-file miss is eligible for
  * fallback.
  *
+ * @remarks
+ * `GET` and `HEAD` are both eligible, and resolve the SAME shell: `HEAD` is
+ * defined as `GET` without a body (RFC 9110 §9.3.2), so a navigation probe
+ * that answered `404` while its `GET` answered `200` would report a resource
+ * the very next request serves.
+ *
  * @param root - The configured static root
  * @param index - The configured shell filename
  * @param exclude - The URL prefix excluded from fallback
- * @param method - The request method
+ * @param method - The request method; only `GET` and `HEAD` are eligible
  * @param pathname - The request pathname
  * @param accept - The request's `Accept` header value
  * @returns The fixed shell path, or `undefined` when fallback is ineligible
@@ -674,9 +775,9 @@ export declare function resolveMultipartLimits(limits: MultipartLimits | undefin
 export declare function resolveStaticFallbackPath(root: string, index: string, exclude: string, method: string, pathname: string, accept: string): string | undefined;
 
 /**
- * Resolve a request pathname to an on-disk path UNDER `root`, or `undefined`
- * when it cannot — the traversal guard, EXACT algorithm and order (PROPOSAL
- * §4.14): strip `prefix` on a segment boundary → `decodeURIComponent` (a
+ * Resolves a request pathname to an on-disk path UNDER `root`, or `undefined`
+ * when it cannot — the traversal guard, whose algorithm and order are exact:
+ * strip `prefix` on a segment boundary → `decodeURIComponent` (a
  * malformed escape refuses, never throws) → reject a NUL byte → strip the
  * leading path separator FIRST (so a leading `..` survives `normalize` as a
  * genuine climbing segment) → `normalize` → refuse any Windows reserved-
@@ -698,24 +799,29 @@ export declare function resolveStaticFallbackPath(root: string, index: string, e
 export declare function resolveStaticPath(root: string, prefix: string | undefined, pathname: string): string | undefined;
 
 /**
- * Options for `createStatic` — node `fs`-backed static file serving.
+ * Configures `createStatic` — node `fs`-backed static file serving.
  *
- * @param options - See fields below
  * @remarks
  * - `root` — the directory every request resolves under, resolved once at
  *   construction. REQUIRED.
  * - `prefix` — a URL path prefix stripped (on a segment boundary) before
  *   resolving under `root`.
- * - `index` — the filename served for a directory hit; defaults to
- *   {@link DEFAULT_STATIC_INDEX}.
+ * - `index` — the filename served for a directory hit and by the SPA
+ *   fallback; defaults to {@link DEFAULT_STATIC_INDEX}. The fallback serves
+ *   it whatever `dotfiles` is set to, because this path is operator-
+ *   configured rather than request-derived.
  * - `dotfiles` — the policy for a path with a dotfile segment: `'ignore'`
- *   (default, falls through to `next()`), `'deny'` (403), or `'allow'`
- *   (serves it).
+ *   (falls through to `next()`), `'deny'` (403), or `'allow'` (serves it);
+ *   defaults to {@link DEFAULT_STATIC_DOTFILES}.
  * - `cache` — `Cache-Control: max-age=<cache>` in seconds, when set.
  * - `etag` — whether to compute and honor a weak file `ETag`; defaults to `true`.
  * - `fallback` — SPA fallback: `false` (default, off), `true` (on, excluding
  *   {@link DEFAULT_STATIC_FALLBACK_EXCLUDE}), or `{ exclude }` for a custom
- *   excluded prefix.
+ *   excluded prefix. An eligible `GET` or `HEAD` navigation miss answers with
+ *   `index` through the SAME handle-`fstat` header block a directly requested
+ *   file answers through, so `cache`, `etag`, conditional revalidation,
+ *   `HEAD`, and ranges are identical on both routes; `index` reaches the
+ *   client through this route whatever `dotfiles` is set to.
  */
 export declare interface StaticOptions {
     readonly root: string;
@@ -730,7 +836,7 @@ export declare interface StaticOptions {
 }
 
 /**
- * Adapt a `node:fs` read stream over `path` (or an already-open
+ * Adapts a `node:fs` read stream over a file path (or an already-open
  * `FileHandle`) into a DOM-compatible `ReadableStream<Uint8Array>` — the
  * single shared node↔web stream bridge every static-file and uploaded-file
  * response body routes through.
@@ -741,24 +847,23 @@ export declare interface StaticOptions {
  * the web `ReadableStream` invokes exactly when its internal queue has room
  * for more data. Exactly one disk chunk is read and enqueued per `pull` —
  * never more — so a slow or stalled consumer (a stalled HTTP connection)
- * simply stops triggering `pull` calls and the source stops reading ahead;
+ * stops triggering `pull` calls and the source stops reading ahead;
  * this is genuine consumer backpressure, not the "naturally backpressured"
  * `for await`/`enqueue` pattern (which does not block on a slow consumer at
- * all, since `enqueue` returns synchronously). The controller is closed on
+ * all, because `enqueue` returns synchronously). The controller is closed on
  * iterator completion and errored (never thrown into the process) on a
- * mid-stream read failure. Cancelling the returned `ReadableStream` (e.g. the
- * consumer aborts the response) calls the iterator's `return()`, which
+ * mid-stream read failure. Cancelling the returned `ReadableStream` (for
+ * example the consumer aborts the response) calls the iterator's `return()`, which
  * destroys the underlying node read stream so the file descriptor is
- * released. When `path` is a `FileHandle`, `FileHandle.createReadStream`'s
+ * released. When `source` is a `FileHandle`, `FileHandle.createReadStream`'s
  * default `autoClose` closes the handle on every terminal path (end, error,
- * or `destroy()` via the iterator's `return()`) — the caller never needs a
- * separate `handle.close()` for a handle passed here.
+ * or `destroy()` through the iterator's `return()`) — the caller never needs a
+ * separate `handle.close()` for a `FileHandle` passed as `source`.
  *
  * @param source - The absolute on-disk file path to stream, or an already-open
- * `FileHandle` (e.g. one already `fstat`'d so the served bytes match the
+ * `FileHandle` (for example one already `fstat`'d so the served bytes match the
  * headers computed from that same `fstat`)
- * @param range - An optional inclusive byte range (`start`/`end`, both
- * 0-indexed and inclusive, matching `node:fs`'s `createReadStream` options)
+ * @param range - An optional inclusive byte range; see {@link ByteRange}
  * @returns A `ReadableStream<Uint8Array>` valid as a fetch `BodyInit`
  *
  * @example
@@ -766,15 +871,12 @@ export declare interface StaticOptions {
  * new Response(streamFile('/srv/public/index.html'))
  * ```
  */
-export declare function streamFile(source: string | FileHandle, range?: {
-    readonly start: number;
-    readonly end: number;
-}): ReadableStream<Uint8Array>;
+export declare function streamFile(source: string | FileHandle, range?: ByteRange): ReadableStream<Uint8Array>;
 
 /**
- * Open a staged/moved uploaded file as a web `ReadableStream`.
+ * Opens a staged/moved uploaded file as a web `ReadableStream`.
  *
- * @param file - The {@link UploadedFileInterface} record to stream
+ * @param file - The {@link UploadedFile} record to stream
  * @returns A `ReadableStream<Uint8Array>` over the file's current on-disk path
  *
  * @example
@@ -782,10 +884,10 @@ export declare function streamFile(source: string | FileHandle, range?: {
  * new Response(streamUploadedFile(file))
  * ```
  */
-export declare function streamUploadedFile(file: UploadedFileInterface): ReadableStream<Uint8Array>;
+export declare function streamUploadedFile(file: UploadedFile): ReadableStream<Uint8Array>;
 
 /**
- * Best-effort unlink every still-`'staged'` file in a parsed
+ * Attempts to unlink every still-`'staged'` file in a parsed
  * {@link MultipartBody} — the fail-closed cleanup `createMultipart` runs when
  * its downstream handler throws, mirroring `parseMultipartRequest`'s own
  * cleanup pattern (a missing file is already gone; failures are swallowed).
@@ -801,30 +903,7 @@ export declare function streamUploadedFile(file: UploadedFileInterface): Readabl
 export declare function unlinkStagedFiles(body: MultipartBody): Promise<void>;
 
 /**
- * The full field set `createUploadedFile` needs to build an
- * {@link UploadedFileInterface} record.
- *
- * @remarks
- * - `field` — the multipart field name the file was submitted under.
- * - `name` — the client-declared filename (metadata only).
- * - `size` — the file's byte size.
- * - `mime` — the sniffed MIME type.
- * - `validated` — `true` when the sniffed type matches the declared `Content-Type`.
- * - `status` — see {@link UploadStatus}.
- * - `path` — the file's current on-disk path.
- */
-export declare interface UploadedFileInput {
-    readonly field: string;
-    readonly name: string;
-    readonly size: number;
-    readonly mime: string;
-    readonly validated: boolean;
-    readonly status: UploadStatus;
-    readonly path: string;
-}
-
-/**
- * One uploaded file's post-parse record — the node-bound, richer sibling of
+ * Describes one uploaded file's post-parse record — the node-bound, richer sibling of
  * the pure core's {@link MultipartFile} (identical fields, `status` narrowed
  * to {@link UploadStatus}). Structurally assignable into {@link MultipartFile}
  * so a `createMultipart`-built {@link MultipartBody} satisfies the shared
@@ -835,18 +914,21 @@ export declare interface UploadedFileInput {
  * - `name` — the client-declared filename (METADATA ONLY — never used to
  *   build a filesystem path).
  * - `size` — the file's byte size.
- * - `mime` — the SNIFFED (magic-byte-detected) MIME type.
- * - `validated` — `true` when the sniffed type matches the declared
- *   `Content-Type`.
+ * - `mime` — the SNIFFED (magic-byte-detected) MIME type when a signature
+ *   matches; otherwise the part's declared `Content-Type`; otherwise
+ *   {@link DEFAULT_CONTENT_TYPE}. Read `validated` to tell which.
+ * - `validated` — `true` when a signature matched AND the sniffed type equals
+ *   the declared `Content-Type`, so `mime` is the sniffed fact. `false` means
+ *   `mime` may be the client-declared value.
  * - `status` — see {@link UploadStatus}.
  * - `path` — the file's current on-disk path.
  */
-export declare interface UploadedFileInterface extends Omit<MultipartFile, 'status'> {
+export declare interface UploadedFile extends Omit<MultipartFile, 'status'> {
     readonly status: UploadStatus;
 }
 
 /**
- * The lifecycle stage of one staged upload's temp file.
+ * Names the lifecycle stage of one staged upload's temp file.
  *
  * @remarks
  * `'staged'` — written to the configured temp directory under a random name,