castrum 0.9.0 → 0.9.1

package/dist/index.d.ts

@@ -15,13 +15,14 @@ export interface SchemaError {
 export interface SchemaValidatorInstance {
 	/** Validate a single JSON document. */
 	validate(input: Uint8Array): boolean;
+	/** Opaque handle (bun:ffi fast path) — `castrum_schema_validator_validate`. */
+	innerPtr?(): bigint;
 	/** Validate a single JSON document, returning detailed errors (empty = valid). */
 	validateDetailed(input: Uint8Array): SchemaError[];
 	/** Validate a single JSON document, returning only the first error (null = valid). */
 	validateFirstError(input: Uint8Array): SchemaError | null;
 	validateBatchPackedCount(packed: Uint8Array): number;
 	validateBatchPackedBitset(packed: Uint8Array): Uint8Array;
-	validateBatchStreaming(batchBytes: Uint8Array): number;
 	/**
 	 * One-pass validate + extract: validate `input` against the schema and
 	 * capture scalar values / array lengths at `paths` during the same native
@@ -74,12 +75,13 @@ export interface MediaTypeResult {
 /** The native `MediaTypeParser` class instance. */
 export interface MediaTypeParserInstance {
 	parse(input: Uint8Array): MediaTypeResult;
-	/** Wildcard match: any/any, type/any, or exact type/subtype. */
-	matches(actual: Uint8Array, expected: Uint8Array): boolean;
 }
 /** The native `ConditionalRequest` class instance (per-resource 304 checks). */
 export interface ConditionalRequestInstance {
 	isNotModified(ifNoneMatch: Uint8Array | null, ifModifiedSince: Uint8Array | null): boolean;
+	/** Opaque handle to the precompiled state (present when the bun:ffi fast path
+	 * is active) — `castrum_conditional_is_not_modified` in rust/ffi.rs. */
+	innerPtr?(): bigint;
 }
 /** One parsed Accept-Encoding preference. */
 export interface EncodingPrefResult {
@@ -87,10 +89,15 @@ export interface EncodingPrefResult {
 	q: number;
 	order: number;
 }
-/** The native `AcceptNegotiator` class instance. */
+/**
+ * The native `AcceptNegotiator` class instance (supported encodings compiled
+ * once). Best supported encoding for a header, or `null` for identity.
+ */
 export interface AcceptNegotiatorInstance {
 	/** Best supported encoding for `header`, or null for identity. */
 	negotiate(header: Uint8Array): string | null;
+	/** Opaque handle (bun:ffi fast path) — `castrum_accept_negotiator_negotiate`. */
+	innerPtr?(): bigint;
 }
 /** The native `Base64Codec` class instance (config compiled once). */
 export interface Base64CodecInstance {
@@ -107,6 +114,8 @@ export interface RateCheckResult {
 export interface RateLimiterInstance {
 	check(key: string, nowMs: number): RateCheckResult;
 	checkKey(key: number, nowMs: number): RateCheckResult;
+	/** Opaque handle (bun:ffi fast path) — `castrum_rate_limiter_check*`. */
+	innerPtr?(): bigint;
 }
 /** The native `CookieSigner` class instance (HMAC key compiled once). */
 export interface CookieSignerInstance {
@@ -122,6 +131,9 @@ export interface CsrfProtectorInstance {
 /** The native `UrlBuilder` class instance (base parsed once). */
 export interface UrlBuilderInstance {
 	resolve(reference: Uint8Array): Uint8Array;
+	/** Opaque handle to the precompiled base (present when the bun:ffi fast path
+	 * is active) — `castrum_url_builder_resolve` in rust/ffi.rs. */
+	innerPtr?(): bigint;
 }
 /** Options for `passwordHash` (argon2id). */
 export interface PasswordHashOptions {
@@ -150,11 +162,15 @@ export interface TemplateRendererInstance {
 	renderBytes(contextJson: Uint8Array): Uint8Array;
 	/** Parallel batch render: packed contexts in → packed rendered out. */
 	renderBatchPacked(data: Uint8Array): Uint8Array;
+	/** Opaque handle (bun:ffi fast path) — `castrum_template_render`. */
+	innerPtr?(): bigint;
 }
 /** The native `MediaTypeMatcher` class instance (expected precompiled once). */
 export interface MediaTypeMatcherInstance {
 	/** Wildcard match against the precompiled expected type. */
 	matches(actual: Uint8Array): boolean;
+	/** Opaque handle (bun:ffi fast path) — `castrum_media_type_matcher_matches`. */
+	innerPtr?(): bigint;
 }
 /** The native `JwtSigner` class instance (HS256 key + ttl compiled once). */
 export interface JwtSignerInstance {
@@ -162,6 +178,8 @@ export interface JwtSignerInstance {
 	/** Sign from pre-serialized claim JSON bytes (no napi Value marshal). */
 	signBytes(claimsJson: Uint8Array, nowSeconds: number): Uint8Array;
 	verify(token: Uint8Array, nowSeconds: number): unknown;
+	/** Opaque handle (bun:ffi fast path) — `castrum_jwt_signer_*`. */
+	innerPtr?(): bigint;
 }
 /** The native `AeadCipher` class instance (algorithm + key compiled once). */
 export interface AeadCipherInstance {
@@ -173,63 +191,13 @@ export interface Argon2HasherInstance {
 	hash(password: Uint8Array, salt: Uint8Array): Uint8Array;
 	verify(password: Uint8Array, phc: Uint8Array): boolean;
 }
-/** Options accepted by `createRust` / `rust.configure`. */
-export interface RustOptions {
-	/**
-	 * Rayon thread pool size.
-	 *
-	 * The rayon pool is process-wide and initialized **once** (native
-	 * `OnceLock`) — the first initialization wins. Importing this module
-	 * initializes the pool with defaults, so this option only takes effect when
-	 * the pool has not yet been created. For reliable control set
-	 * `CASTRUM_RAYON_THREADS` / `RUST_RAYON_THREADS` before import.
-	 * Default: max(1, hardwareConcurrency - 1).
-	 */
-	rayonThreads?: number;
-	/** Cache MIME lookups keyed by normalized extension. Default: true. */
-	mimeCache?: boolean;
-	/** Reuse HMAC signers keyed by key-buffer identity. Default: true. */
-	hmacCache?: boolean;
-}
-/** String-oriented FFI namespace. */
-export interface RustText {
-	/**
-	 * Resolve a lowercase file extension to a MIME type string (e.g. `"html"` →
-	 * `"text/html"`). Unknown extensions return `"application/octet-stream"`.
-	 * @param ext the file extension WITHOUT a leading dot, case-insensitive.
-	 * @returns the MIME type for `ext`.
-	 */
-	mimeFromExtension(ext: string): string;
-	/**
-	 * RFC 3986 percent-encode a string (the `encodeURIComponent` unreserved
-	 * set). Under Bun this delegates to the native `encodeURIComponent` for
-	 * ~4x speed with byte-for-byte parity.
-	 * @param input the string to encode.
-	 * @returns the percent-encoded string.
-	 */
-	urlEncode(input: string): string;
-	/**
-	 * Percent-decode a string. Throws on malformed `%XX` or invalid UTF-8
-	 * output (parity with `decodeURIComponent`, which is used under Bun).
-	 * @param input the percent-encoded string to decode.
-	 * @returns the decoded string.
-	 */
-	urlDecode(input: string): string;
-	/**
-	 * Compute the RFC 6455 `Sec-WebSocket-Accept` value for a client key.
-	 * @param key the base64 `Sec-WebSocket-Key` header value.
-	 * @returns the 28-byte base64 accept value.
-	 */
-	wsAcceptKey(key: string): string;
-	/** @param input an email address. @returns whether it is RFC-valid. */
-	validateEmail(input: string): boolean;
-	/** @param input a UUID string. @returns whether it is a valid (v1-v8) UUID. */
-	validateUuid(input: string): boolean;
-	/** @param input an IPv4 address. @returns whether it is valid. */
-	validateIpv4(input: string): boolean;
-	/** @param input an IPv6 address. @returns whether it is valid. */
-	validateIpv6(input: string): boolean;
-}
+/** Parse a query string (`a=1&b=2`) into an object via the native parser. */
+export declare function parseQueryString(query: string): Record<string, string | string[]>;
+/** Parse a cookie header (`a=1; b=2`) into an object via the native parser. */
+export declare function parseCookieHeader(header: string): Record<string, string | string[]>;
+/** Parse an application/x-www-form-urlencoded body into a key/value object. */
+export declare function parseFormBody(body: Uint8Array): Record<string, string | string[]>;
+/** Native JSON-Schema validator handle (see `createSchemaValidator`). */
 export type SchemaValidator = SchemaValidatorInstance;
 /**
  * Unpack a packed u32 array: `[u32 count]{[u32 value]}` → `Uint32Array`.
@@ -252,18 +220,32 @@ export declare function unpackI64ArrayAsBigInt(bytes: Uint8Array): BigInt64Array
  * (zero-copy) — copy them if held beyond the buffer's lifetime.
  */
 export declare function unpackByteResults(bytes: Uint8Array): Uint8Array[];
+/** A decoded `[name, value]` pair from a packed buffer. */
 export type Pair = [
 	string,
 	string
 ];
+/**
+ * Decode a packed `[u32 count][u32 keyLen][key][u32 valLen][val]...` buffer
+ * into `[name, value]` string pairs (see `packPairs` for the layout).
+ */
 export declare function readPairsPacked(bytes: Uint8Array): Pair[];
+/**
+ * Fold `[name, value]` pairs into an object; repeated names collect into a
+ * string array (query-string/cookie semantics).
+ */
 export declare function pairsToObject(pairs: Pair[]): Record<string, string | string[]>;
+/** A decoded HTTP request from the native packed parser. */
 export interface ParsedHttpRequestPacked {
 	method: string;
 	path: string;
 	version: string;
 	headers: Record<string, string>;
 }
+/**
+ * Decode a native `httpParseRequestPacked` buffer into a plain request object
+ * (zero-alloc on the Rust side; this builds the JS strings once).
+ */
 export declare function readHttpPacked(bytes: Uint8Array): ParsedHttpRequestPacked;
 /**
  * Build a packed batch buffer. Returns an OWNED buffer (safe to hold across
@@ -271,410 +253,841 @@ export declare function readHttpPacked(bytes: Uint8Array): ParsedHttpRequestPack
  * guarantee synchronous consumption should use `withPackScratch` instead.
  */
 export declare function packBatch(items: Uint8Array[]): Uint8Array;
+/**
+ * Pack `[name, value]` string pairs into the native `[u32 count]...` layout
+ * that `readPairsPacked` / the batch validators consume.
+ */
 export declare function packPairs(pairs: Array<[
 	string,
 	string
 ]>): Uint8Array;
-export declare function parseQueryString(query: string): Record<string, string | string[]>;
-export declare function parseCookieHeader(header: string): Record<string, string | string[]>;
-/** Parse an application/x-www-form-urlencoded body into a key/value object. */
-export declare function parseFormBody(body: Uint8Array): Record<string, string | string[]>;
-/** Array-of-bytes FFI namespace. */
-export interface RustBatch {
-	jsonValid(items: Uint8Array[]): Uint8Array;
-	crc32(items: Uint8Array[]): Uint32Array;
-	validateEmail(items: Uint8Array[]): Uint8Array;
-	validateUuid(items: Uint8Array[]): Uint8Array;
-	validateIpv4(items: Uint8Array[]): Uint8Array;
-	validateIpv6(items: Uint8Array[]): Uint8Array;
-	jsonSumIds(items: Uint8Array[]): BigInt64Array;
-	queryParse(items: Uint8Array[]): Uint8Array[];
-	cookieParse(items: Uint8Array[]): Uint8Array[];
-	httpParseRequest(items: Uint8Array[]): Uint8Array[];
-	/** Apply N RFC 6902 patches (docs and patches zipped). Fail-fast on error. */
-	jsonPatch(docs: Uint8Array[], patches: Uint8Array[]): Uint8Array[];
-	/** Encode N items to lowercase hex (packed in → byte results). */
-	hexEncode(items: Uint8Array[]): Uint8Array[];
-	/** Decode N lowercase/uppercase hex strings to bytes. */
-	hexDecode(items: Uint8Array[]): Uint8Array[];
-	/** Base64-encode N items (standard by default; url-safe/padding configurable). */
-	base64Encode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[];
-	/** Base64-decode N items (standard by default; url-safe/padding configurable). */
-	base64Decode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[];
-	formParse(items: Uint8Array[]): Uint8Array[];
-	/** Sign N cookie values (packed → byte results). */
-	signCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array[];
-	/** Verify N signed cookies (bitset of valid). */
-	verifyCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array;
-	/** Verify N CSRF tokens (bitset of valid). */
-	csrfVerify(items: Uint8Array[], secret: Uint8Array): Uint8Array;
-	schemaValidate(validator: SchemaValidator, items: Uint8Array[]): Uint8Array;
-	schemaValidateCount(validator: SchemaValidator, items: Uint8Array[]): number;
-	/** Hash N items with FNV-1a 64 (packed → unsigned u64 array). */
-	fnv1a64(items: Uint8Array[]): BigUint64Array;
-	/** Generate N ETags (strong by default; weak flag applies to all items). */
-	etag(items: Uint8Array[], weak?: boolean | null): Uint8Array[];
-	urlEncode(items: Uint8Array[]): Uint8Array[];
-	/** Percent-decode N strings (UTF-8 validated; malformed items → empty). */
-	urlDecode(items: Uint8Array[]): Uint8Array[];
-	/** Strict percent-decode N strings (no UTF-8 validation). */
-	urlDecodeBytes(items: Uint8Array[]): Uint8Array[];
-	mimeFromExtension(items: Uint8Array[]): Uint8Array[];
-	wsAcceptKey(items: Uint8Array[]): Uint8Array[];
-	/** Base64url-encode N items (URL-safe, no padding). */
-	base64UrlEncode(items: Uint8Array[]): Uint8Array[];
-	/** Base64url-decode N items (URL-safe, no padding). */
-	base64UrlDecode(items: Uint8Array[]): Uint8Array[];
-	passwordHash(passwords: Uint8Array[], salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array[];
-	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, items: Uint8Array[], algorithm?: string | null): Uint8Array[];
-	aeadDecrypt(key: Uint8Array, nonce: Uint8Array, items: Uint8Array[], algorithm?: string | null): Uint8Array[];
-	gzipCompress(items: Uint8Array[], level?: number | null): Uint8Array[];
-	gzipDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[];
-	brotliCompress(items: Uint8Array[], quality?: number | null): Uint8Array[];
-	brotliDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[];
-	jwtVerify(tokens: Uint8Array[], secret: Uint8Array, nowSeconds: number): Uint8Array;
-	/** Sign N messages to lowercase-hex HMAC-SHA256 signatures (packed → byte results). */
-	hmacSha256(items: Uint8Array[], key: Uint8Array): Uint8Array[];
-	/** Verify N message + hex-signature pairs (two packed lists, zipped) → bitset of valid. */
-	hmacSha256Verify(items: Uint8Array[], sigs: Uint8Array[], key: Uint8Array): Uint8Array;
-	/** Verify N password+PHC pairs (two packed lists, zipped) → bitset of valid. */
-	passwordVerify(items: Uint8Array[], phcs: Uint8Array[]): Uint8Array;
-	/** Resolve N references against N bases (two packed lists, zipped). */
-	urlResolve(bases: Uint8Array[], references: Uint8Array[]): Uint8Array[];
-	/** Sign N JSON claim documents (packed → signed tokens). */
-	jwtSign(items: Uint8Array[], secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): Uint8Array[];
-	/** Encode N SSE events with shared event/id/retry. */
-	sseEncode(items: Uint8Array[], event?: string | null, id?: string | null, retry?: number | null): Uint8Array[];
-	/** Encode N frames (same opcode/mask/fin) from payloads. */
-	wsFrameEncode(items: Uint8Array[], opcode: number, mask: boolean, fin: boolean): Uint8Array[];
-	/** Decode N frames → payloads (opcodes/flags dropped; failed items → empty). */
-	wsFrameDecode(items: Uint8Array[]): Uint8Array[];
-	/** Parse N multipart bodies → array of parts per item (same boundary). */
-	multipartParse(items: Uint8Array[], boundary: Uint8Array): MultipartPart[][];
-	/**
-	 * @performance Template render: ~1.7x slower than the JS baseline (1/3 tasks failed) [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.7x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Promotion candidate: 2/3 benchmarks won in the latest run (static: not-competitive). [check:annotate]
-	 * @remarks The allocating render marshals the context via napi DOM (~1.5x loss). Use TemplateRenderer.renderBytes (JSON-bytes context) which avoids it and wins ~1.37x. [check:annotate]
-	 */
-	templateRender(source: string, contexts: Uint8Array[]): Uint8Array[];
-}
-/** Raw packed-wire FFI namespace. */
-export interface RustPacked {
-	crc32BatchPacked(input: Uint8Array): Uint8Array;
-	jsonValidBatchPacked(input: Uint8Array): Uint8Array;
-	validateEmailBatchPacked(input: Uint8Array): Uint8Array;
-	validateUuidBatchPacked(input: Uint8Array): Uint8Array;
-	validateIpv4BatchPacked(input: Uint8Array): Uint8Array;
-	validateIpv6BatchPacked(input: Uint8Array): Uint8Array;
-	jsonSumBatchPacked(input: Uint8Array): Uint8Array;
-	queryParseBatchPacked(input: Uint8Array): Uint8Array;
-	cookieParseBatchPacked(input: Uint8Array): Uint8Array;
-	httpParseRequestBatchPacked(input: Uint8Array): Uint8Array;
-	/** Batch RFC 6902 JSON Patch (two packed lists, zipped) → packed results. */
-	jsonPatchBatchPacked(docs: Uint8Array, patches: Uint8Array): Uint8Array;
-	/** Packed FNV-1a 64 batch (i64 per item). */
-	fnv1A64BatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed ETag batch (10 strong / 12 weak bytes per item). */
-	etagBatchPacked(input: Uint8Array, weak?: boolean | null): Uint8Array;
-	urlEncodeBatchPacked(input: Uint8Array): Uint8Array;
-	urlDecodeBatchPacked(input: Uint8Array): Uint8Array;
-	urlDecodeBytesBatchPacked(input: Uint8Array): Uint8Array;
-	mimeFromExtensionBatchPacked(input: Uint8Array): Uint8Array;
-	wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array;
-	jsonValidBatchCountPacked(input: Uint8Array): number;
-	validateEmailBatchCountPacked(input: Uint8Array): number;
-	validateUuidBatchCountPacked(input: Uint8Array): number;
-	validateIpv4BatchCountPacked(input: Uint8Array): number;
-	validateIpv6BatchCountPacked(input: Uint8Array): number;
-	jsonSumBatchTotalPacked(input: Uint8Array): number;
-	queryParseBatchTotalLenPacked(input: Uint8Array): number;
-	cookieParseBatchTotalLenPacked(input: Uint8Array): number;
-	httpParseRequestBatchTotalLenPacked(input: Uint8Array): number;
-	passwordHashBatchPacked(input: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array;
-	/** Packed password-verify batch (two packed lists, zipped) → bitset. */
-	passwordVerifyBatchPacked(passwords: Uint8Array, phcs: Uint8Array): Uint8Array;
-	/** Packed URL-resolve batch (two packed lists, zipped) → packed results. */
-	urlResolveBatchPacked(bases: Uint8Array, references: Uint8Array): Uint8Array;
-	aeadEncryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
-	aeadDecryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
-	gzipCompressBatchPacked(input: Uint8Array, level?: number | null): Uint8Array;
-	gzipDecompressBatchPacked(input: Uint8Array): Uint8Array;
-	brotliCompressBatchPacked(input: Uint8Array, quality?: number | null): Uint8Array;
-	brotliDecompressBatchPacked(input: Uint8Array): Uint8Array;
-	jwtSignBatchPacked(input: Uint8Array, secret: Uint8Array, ttlSeconds: number | null, nowSeconds: number): Uint8Array;
-	jwtVerifyBatchPacked(input: Uint8Array, secret: Uint8Array, nowSeconds: number): Uint8Array;
-	/** Batch HMAC-SHA256 sign (packed in → hex-signature byte results). */
-	hmacSha256BatchPacked(input: Uint8Array, key: Uint8Array): Uint8Array;
-	/** Batch HMAC-SHA256 verify (two packed lists: data + hex sigs, zipped) → bitset. */
-	hmacSha256VerifyBatchPacked(input: Uint8Array, sigs: Uint8Array, key: Uint8Array): Uint8Array;
-	multipartParseBatchPacked(input: Uint8Array, boundary: Uint8Array): Uint8Array;
-	templateRenderBatchPacked(input: Uint8Array, source: string): Uint8Array;
-	sseEncodeBatchPacked(input: Uint8Array, event: string | null, id: string | null, retry: number | null): Uint8Array;
-	wsFrameEncodeBatchPacked(input: Uint8Array, opcode: number, mask: boolean, fin: boolean): Uint8Array;
-	wsFrameDecodeBatchPacked(input: Uint8Array): Uint8Array;
+/** Bounds-checked section offsets for one ingress output buffer. */
+export interface PackedSectionLayout {
+	/** Cookie-JSON length clamped to the buffer (0 if none / out of range). */
+	safeCookiesLen: number;
+	/** Byte offset where the query-JSON section begins. */
+	queryStart: number;
+	/** Query-JSON length clamped to the buffer (0 if none / out of range). */
+	safeQueryLen: number;
+	/** Byte offset where the body-JSON section begins. */
+	bodyJsonStart: number;
+	/** Body-JSON length clamped to the buffer (0 if none / out of range). */
+	safeBodyJsonLen: number;
+	/** Whether any declared section length overran the buffer. */
+	truncated: boolean;
 }
-/** Scalar + factory + runtime methods of the Rust client. */
-export interface RustScalar {
+declare abstract class IngressResultBase {
+	/** Raw native verdict byte (0 = accepted). */
+	verdict: number;
+	/** Raw native error-code byte. */
+	errorCode: number;
+	/** Normalized HTTP status. */
+	status: number;
+	/** Header template variant byte emitted by the native core. */
+	headerVariant: number;
+	/** Remaining rate-limit budget (count). */
+	rateRemaining: number;
+	/** Rate-limit window reset (ms epoch). */
+	rateResetMs: number;
+	/** Retry-After value (ms). */
+	retryAfterMs: number;
+	/** True when the pipeline returned a terminal (error) verdict. */
+	terminal: boolean;
+	/** True when the pipeline accepted the request (verdict 0 + 2xx/3xx). */
+	ok: boolean;
+	/** True when the request was a CORS preflight. */
+	isPreflight: boolean;
+	/** True when the CORS engine allowed the request origin. */
+	corsAllowed: boolean;
+	/** True when the request was rate-limited. */
+	rateLimited: boolean;
+	/** True when the request came from a trusted proxy. */
+	trustedProxy: boolean;
+	/** True when the request body parsed as valid JSON. */
+	bodyValidJson: boolean;
+	/** True when the request body validated against the ingress schema. */
+	schemaValid: boolean;
+	/** True when a declared output section overran the buffer. */
+	bodyTruncated: boolean;
+	/** Request body bytes (may be an empty view). */
+	body: Uint8Array;
+	protected _buf: Uint8Array;
+	protected _bodyJsonStart: number;
+	protected _bodyJsonLen: number;
+	private _cookiesBuf;
+	private _queryBuf;
+	private _cookiesDecoded;
+	private _queryDecoded;
+	/** Reset the shared fields to their empty state (call from subclass `invalidate`). */
+	protected resetShared(): void;
+	/** Recompute `terminal`/`ok` from the (subclass-set) verdict + status. */
+	protected updateOkTerminal(): void;
 	/**
-	 * @performance CRC32: ~3.7x slower than the JS baseline (2/3 tasks failed) [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~3.7x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Sub-µs FFI-crossing bound vs the same-engine JS crc-32 loop (~0.23-0.44x across runs); use the packed crc32BatchPacked path which wins on larger inputs. [check:annotate]
+	 * Store the rate-limit window fields. Both decoders read the same OUT_*
+	 * slots and gate them on the same conditions (a positive budget OR the
+	 * rate-limited flag), so the read cannot drift between paths.
 	 */
-	crc32(input: Uint8Array): number;
+	protected setRateWindow(rateLimit: number, rateLimited: boolean, view: DataView): void;
 	/**
-	 * @performance FNV-1a 64: ~6.6x faster than the JS baseline [check:annotate]
+	 * Store the bounds-checked cookie/query/body JSON sections from `layout`.
+	 *
+	 * `bodyJsonLen` is the body-JSON length to trust for `bodyJson()`: the fast
+	 * path passes the RAW declared length (it re-checks bounds on read), the
+	 * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
+	 * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
 	 */
-	fnv1a64(input: Uint8Array): bigint;
-	/**
-	 * XXH3-64 over raw bytes (high-throughput non-cryptographic hash).
-	 * Compare against `Bun.hash.xxHash3` — see docs/bun-builtins-decision-matrix.md.
-	 */
-	xxh3(input: Uint8Array): bigint;
-	/**
-	 * @performance HMAC sign: ~1.1x faster than the JS baseline (2/3 tasks won) [check:annotate]
-	 */
-	hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
+	protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void;
+	/** Decoded cookies-JSON section, or `"{}"` when absent. */
+	cookiesJson(): string;
+	/** Decoded query-JSON section, or `"{}"` when absent. */
+	queryJson(): string;
+	/** Bounds-checked body-JSON slice (empty when absent / out of range). */
+	protected bodyJsonSlice(): Uint8Array;
+}
+/** Zero-alloc, reusable result decoder for the pre-baked handler path. */
+export declare class BakedIngressResult extends IngressResultBase {
+	refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void;
+	invalidate(): void;
+	setInternalError(): void;
+	bodyJson(copy: boolean): Uint8Array;
+}
+/** User-facing CORS configuration. */
+export interface CorsOptions {
+	allowOrigin?: string[];
+	allowMethods?: string[];
+	allowHeaders?: string[];
+	exposeHeaders?: string[];
+	allowCredentials?: boolean;
+	maxAge?: number;
+}
+/** Precomputed, immutable CORS policy strings. */
+export interface CorsStaticStrings {
+	readonly allowMethodsJoined: string;
+	readonly allowHeadersJoined: string;
+	readonly exposeHeadersJoined: string;
+	readonly maxAgeString: string | null;
+	readonly isWildcard: boolean;
+	readonly credentials: boolean;
+}
+/** User-facing security-headers configuration. */
+export interface SecurityHeadersOptions {
+	contentSecurityPolicy?: string;
+	hsts?: boolean;
+	hstsMaxAge?: number;
+	hstsIncludeSubdomains?: boolean;
+	hstsPreload?: boolean;
+	frameOptions?: string;
+	nosniff?: boolean;
+	referrerPolicy?: string;
+	coep?: string;
+	coop?: string;
+	corp?: string;
+	xssProtection?: string;
+}
+/** Zero-alloc, lazy-decoding view over a native Ingress output buffer. */
+export declare class FastIngressResult extends IngressResultBase {
+	status: number;
+	verdict: number;
+	errorCode: number;
+	flags: number;
+	https: boolean;
+	hasCookies: boolean;
+	hasQuery: boolean;
+	rateLimit: number;
+	requestId: string;
+	refresh(buf: Uint8Array, body: Uint8Array, requestId: string): void;
+	invalidate(): void;
+	setInternalError(requestId: string): void;
+	/** Bounds-checked body-JSON section, or an empty view when absent. */
+	bodyJson(): Uint8Array;
+}
+/** Options accepted by `createIngressFast` / `createIngress`. */
+export interface IngressFastOptions {
+	trustProxy?: boolean;
+	trustedProxies?: {
+		enabled?: boolean;
+		networks?: string[];
+	};
+	parseCookies?: boolean;
+	parseQuery?: boolean;
+	requireJsonBody?: boolean;
+	schema?: Uint8Array;
+	cors?: CorsOptions;
+	rateLimit?: {
+		limit?: number;
+		windowMs?: number;
+		maxEntries?: number;
+	};
 	/**
-	 * @performance HMAC verify: ~2.5x faster than the JS baseline [check:annotate]
+	 * Structured security-header options (CSP/HSTS) — honored by the fast/async
+	 * paths (`createIngressFast` throws on it; `createIngress` applies it via
+	 * `buildResponseContext`). The PRE-BAKED path (`createIngressHandler`)
+	 * instead takes raw `securityHeaders: [name, value][]` pairs. The two paths
+	 * intentionally use different option shapes (see docs/INGRESS.md).
 	 */
-	hmacSha256Verify(key: Uint8Array, data: Uint8Array, sig: Uint8Array): boolean;
+	security?: SecurityHeadersOptions;
+	https?: boolean;
+	maxBodyBytes?: number;
+	enableSecurityHeaders?: boolean;
+	enableRequestIds?: boolean;
+	enableBodySizeGuard?: boolean;
+	emitMetadataJson?: boolean;
+	readBody?: boolean;
+	outputBufferSize?: number;
 	/**
-	 * @performance JSON valid: ~3.2x faster than the JS baseline (8/8 tasks won) [check:annotate]
+	 * Overall deadline (ms) for reading a request body in the async
+	 * `createIngress` path. 0 disables. Default: `DEFAULT_BODY_TIMEOUT_MS` (30s).
+	 * Ignored by the sync `createIngressFast` (it does not read bodies).
 	 */
-	jsonValid(input: Uint8Array): boolean;
+	bodyTimeoutMs?: number;
 	/**
-	 * Parse JSON to a JS value (native sonic-rs DOM → napi). Throws on invalid JSON.
-	 * @performance JSON parse: ~5.0x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~5.0x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Bun's JSON.parse beats the native DOM + napi marshaling path (~5x). [check:annotate]
+	 * Invoked when the native pipeline throws (the request becomes a 500).
+	 * Native failures are otherwise silent in the fast path. Never throws.
 	 */
-	jsonParse(input: Uint8Array): unknown;
+	onError?: (error: Error) => void;
 	/**
-	 * @performance JSON sum: ~2.9x faster than the JS baseline (4/4 tasks won) [check:annotate]
+	 * When true, run one probe GET at construction so the `run()` closure,
+	 * packed pipeline and FFI ingress call are JIT-warmed before the first real
+	 * request (cuts cold-invocation tail latency in serverless-style
+	 * deployments). Opt-in; default false. Not forwarded to the native addon.
 	 */
-	jsonSumIds(input: Uint8Array): bigint;
+	warmOnCreate?: boolean;
+	limits?: {
+		maxUrlBytes?: number;
+		maxQueryBytes?: number;
+		maxCookieBytes?: number;
+		maxHeadersBytes?: number;
+		maxHeaders?: number;
+		maxPairs?: number;
+	};
+}
+/** The zero-alloc sync handler returned by `createIngressFast`. */
+export interface IngressFastHandler {
+	run<T>(req: Request, ip: string | undefined, body: Uint8Array | null, requestId: string, fn: (result: FastIngressResult) => T): T;
+}
+/**
+ * Options accepted by `createIngressHandler` (path 2).
+ *
+ * Same native option surface as the fast path, minus `onError` — path 2
+ * reports native failures through `BakedIngressRuntime.onError` instead of the
+ * options bag.
+ */
+export type IngressHandlerOptions = Omit<IngressFastOptions, "onError">;
+/** Public ingress options (extends the fast-path options). */
+export interface IngressOptions extends IngressFastOptions {
+	enableRequestIds?: boolean;
 	/**
-	 * @performance JSON Patch: ~1.2x faster than the JS baseline [check:annotate]
-	 * @remarks Modest but real win; swings ~0.9-1.5x run-to-run (DOM marshal dominated). [check:annotate]
+	 * Invoked before a request is processed (for tracing/context hooks).
+	 * Only used by the async `createIngress` path.
 	 */
-	jsonPatch(doc: Uint8Array, patch: Uint8Array): Uint8Array;
+	onRequest?: (req: Request, requestId: string, ip: string | undefined) => void;
 	/**
-	 * @performance MIME lookup: ≈ parity with the JS baseline [check:annotate]
-	 * @remarks Noisy sub-µs op: wins ~1.6x on good runs, loses on bad runs; phf table lookup. [check:annotate]
+	 * Invoked after a terminal context (and its `Response`) is produced, for
+	 * metrics/logging hooks. Only used by the async `createIngress` path.
 	 */
-	mimeFromExtension(ext: Uint8Array): Uint8Array;
+	onResponse?: (req: Request, result: IngressContext, status: number, requestId: string) => void;
+}
+/**
+ * Readonly structural view of a decoded ingress result.
+ *
+ * Note: the exported `FastIngressResult` class is the zero-alloc implementation;
+ * this interface is the readonly view used by the public sync/async handlers.
+ */
+export interface IngressResult {
+	readonly status: number;
+	readonly verdict: number;
+	readonly flags: number;
+	readonly errorCode: number;
+	readonly terminal: boolean;
+	readonly ok: boolean;
+	readonly https: boolean;
+	readonly trustedProxy: boolean;
+	readonly hasCookies: boolean;
+	readonly hasQuery: boolean;
+	readonly bodyValidJson: boolean;
+	readonly schemaValid: boolean;
+	readonly corsAllowed: boolean;
+	readonly isPreflight: boolean;
+	readonly rateLimited: boolean;
+	readonly rateLimit: number;
+	readonly rateRemaining: number;
+	readonly rateResetMs: number;
+	readonly retryAfterMs: number;
+	readonly body: Uint8Array;
+	readonly headerVariant: number;
+	readonly requestId: string;
+	readonly bodyTruncated: boolean;
+	cookiesJson(): string;
+	queryJson(): string;
+	bodyJson(): Uint8Array;
+}
+/** A result plus the terminal Response computed for it. */
+export interface IngressContext extends IngressResult {
+	response: Response | null;
+}
+/**
+ * Synchronous ingress handler.
+ *
+ * The callback runs on the zero-alloc result object and MUST be synchronous:
+ * returning a Promise (or any thenable) throws. The result is invalidated after
+ * `run()` returns, so capture the fields you need inside the callback (or use
+ * the async {@link IngressHandler} which snapshots for you).
+ */
+export interface SyncIngressHandler {
+	run<T>(req: Request, ip: string | undefined, body: Uint8Array | null, requestId: string, fn: (result: IngressResult) => T): T;
+}
+/** Async ingress handler (wraps {@link SyncIngressHandler} with body reading). */
+export type IngressHandler = (req: Request, ip?: string) => Promise<IngressContext>;
+/** Mutable per-request context threaded through the pre-baked handler run. */
+export interface BakedContext {
+	/** The request-id string (null when `emitRequestIdHeader` is off). */
+	requestIdHeader: string | null;
+	/** The `Origin` request header when CORS extraction is enabled. */
+	origin: string | null;
+}
+/**
+ * An optimized ingress handler. `run()` is the zero-alloc pipeline entry
+ * point; the response-builder methods are pre-baked and bound to this
+ * handler's configuration, so consumers can build custom routes without
+ * touching header templates or error bodies.
+ */
+export interface OptimizedIngressHandler {
+	run<T>(req: Request, ip: string | undefined, body: Uint8Array | null, fn: (result: BakedIngressResult, ctx: BakedContext) => T): T;
+	responseHeaders(variant: number, requestIdHeader: string | null, origin: string | null, rateRemaining?: number, rateResetSecs?: number, retryAfterSecs?: number): [
+		string,
+		string
+	][];
+	terminalHeaders(variant: number, ctx: BakedContext, result: BakedIngressResult | null): [
+		string,
+		string
+	][];
+	/** `req` is accepted for back-compat but unused by the baked terminal path. */
+	terminalResponse(req: Request | undefined, result: BakedIngressResult, ctx: BakedContext): Response | null;
+	/** `req` is accepted for back-compat but unused by the baked error path. */
+	errorResponse(req: Request | undefined, result: BakedIngressResult | null, status: number, code: string, message: string, ctx: BakedContext): Response;
+	internalErrorResponse(ctx: BakedContext, result?: BakedIngressResult): Response;
+	withContentType(headers: ReadonlyArray<[
+		string,
+		string
+	]>, contentType: string): [
+		string,
+		string
+	][];
 	/**
-	 * @performance Random token: ≈ parity with the JS baseline [check:annotate]
+	 * Build a zero-copy `Response` whose body is the request's pooled output
+	 * slice. The pooled buffer is returned to its pool once the body has been
+	 * consumed (stream closed) or the request aborted. Use when `copyBody` is
+	 * `false`; otherwise a copied body is released eagerly at the end of `run()`.
 	 */
-	randomToken(byteLen: number): Uint8Array;
+	zeroCopyResponse(result: BakedIngressResult, ctx: BakedContext, init: ResponseInit): Response;
+}
+/** Terminal (rejection) response envelope style for responder routes.
+ *  `"castrum"` (default) emits the pre-baked `ok:false`/`ratelimit-*` wire;
+ *  `"ignex"` emits the ignex framework envelope (`{error,status,code}` +
+ *  `x-frame-options`/`nosniff`/`referrer-policy` security headers). Additive —
+ *  castrum's own wire formats are untouched. */
+export type TerminalStyle = "castrum" | "ignex";
+/**
+ * Decoded request context handed to a {@link NativeResponder} after the native
+ * pipeline succeeded (non-terminal). The native pipeline owns parse/validate/
+ * CORS/rate-limit + terminal rejections; the responder builds the 2xx body
+ * (async OK). Fields are captured INSIDE the sync `run()` callback, so the
+ * pooled output buffer is never aliased after it is released.
+ */
+export interface NativeRequestContext {
+	readonly requestId: string;
+	readonly status: number;
+	readonly rateLimited: boolean;
+	readonly retryAfterMs: number;
+	/** Parsed query object (last-wins per key) — `{}` when `parseQuery` is off. */
+	readonly query: Record<string, string | string[]>;
+	/** Parsed cookie object (last-wins per key) — `{}` when `parseCookies` is off. */
+	readonly cookies: Record<string, string>;
+	/** Request body bytes when read for native validation, else empty. */
+	readonly body: Uint8Array;
+	readonly ip: string | undefined;
+	readonly req: Request;
+}
+/** A JS 2xx builder invoked after the native pipeline succeeds (async OK). */
+export type NativeResponder = (snap: NativeRequestContext) => Response | Promise<Response>;
+/** Options accepted by the pre-baked route factories. */
+export interface BakedHandlerOptions {
+	/** Resolve the client IP from the server object (e.g. `srv.requestIP`). */
+	getIp?: (req: Request, srv: unknown) => string | undefined;
+	/** Copy body slices instead of sharing the native buffer. Default: true (safe). */
+	copyBody?: boolean;
+	/** Maximum request body bytes for write/echo handlers. Default: 1 MiB. */
+	maxBodyBytes?: number;
 	/**
-	 * @performance URL encode: ~2.2x slower than the JS baseline (2/3 tasks failed) [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~2.2x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Loses ~2.8x on the shipped baseline release build (only wins in the LOCAL SIMD perf build). [check:annotate]
-	 */
-	urlEncode(input: Uint8Array): Uint8Array;
-	/**
-	 * @performance URL decode: ~2.2x slower than the JS baseline (2/3 tasks failed) [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~2.2x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Loses ~2.8x on the shipped baseline release build (only wins in the LOCAL SIMD perf build). [check:annotate]
-	 */
-	urlDecode(input: Uint8Array): Uint8Array;
-	/** Strict percent-decode without UTF-8 validation. */
-	urlDecodeBytes(input: Uint8Array): Uint8Array;
-	/** Reusable-output percent-encode; returns bytes written. */
-	urlEncodeInto(input: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output percent-decode; returns bytes written. */
-	urlDecodeInto(input: Uint8Array, output: Uint8Array): number;
-	/**
-	 * @performance Email validation: ~3.1x faster than the JS baseline (4/4 tasks won) [check:annotate]
-	 */
-	validateEmail(input: Uint8Array): boolean;
-	/**
-	 * @performance UUID validation: ≈ parity with the JS baseline (2/4 tasks won) [check:annotate]
-	 */
-	validateUuid(input: Uint8Array): boolean;
-	/**
-	 * @performance IPv4 validation: ≈ parity with the JS baseline (2/2 tasks won) [check:annotate]
-	 */
-	validateIpv4(input: Uint8Array): boolean;
-	/**
-	 * @performance IPv6 validation: ~1.9x faster than the JS baseline [check:annotate]
-	 */
-	validateIpv6(input: Uint8Array): boolean;
-	/**
-	 * @performance WebSocket accept: ~1.9x faster than the JS baseline (1/2 tasks won) [check:annotate]
-	 */
-	wsAcceptKey(key: Uint8Array): Uint8Array;
-	/**
-	 * @performance HTTP parse: ~5.3x faster than the JS baseline (6/6 tasks won) [check:annotate]
-	 */
-	httpParseRequestPacked(input: Uint8Array): Uint8Array;
-	/**
-	 * @performance Query parse: ~3.8x faster than the JS baseline (6/6 tasks won) [check:annotate]
-	 */
-	queryParsePacked(input: Uint8Array): Uint8Array;
-	/**
-	 * @performance Cookie parse: ~2.6x faster than the JS baseline (5/5 tasks won) [check:annotate]
-	 */
-	cookieParsePacked(input: Uint8Array): Uint8Array;
-	/** Reusable-output packed HTTP parse; returns bytes written. */
-	httpParseRequestPackedInto(input: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output packed query parse; returns bytes written. */
-	queryParsePackedInto(input: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output packed cookie parse; returns bytes written. */
-	cookieParsePackedInto(input: Uint8Array, output: Uint8Array): number;
-	/**
-	 * Parse an application/x-www-form-urlencoded body into packed pairs.
-	 * @performance Form parse: ~4.7x faster than the JS baseline (2/2 tasks won) [check:annotate]
-	 * @remarks Benchmarked via the FormParser instance (same parser core). [check:annotate]
-	 */
-	formParsePacked(input: Uint8Array): Uint8Array;
-	/**
-	 * Parse a Content-Type header into a structured media type.
-	 * @performance Media type parse: ~1.3x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.3x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Consistent ~0.71-0.81x (sub-µs FFI crossing vs the JS baseline); use MediaTypeMatcher (precompiled expected) for the zero-alloc match path. [check:annotate]
-	 */
-	parseMediaType(input: Uint8Array): MediaTypeResult;
-	/**
-	 * Generate a strong/weak ETag (crc32-based).
-	 * @performance ETag: ≈ parity with the JS baseline [check:annotate]
-	 */
-	etag(data: Uint8Array, weak?: boolean): Uint8Array;
-	/** Reusable-output etag; returns bytes written (10 strong / 12 weak). */
-	etagInto(data: Uint8Array, output: Uint8Array, weak?: boolean): number;
-	/**
-	 * Format a unix timestamp as an IMF-fixdate HTTP-date.
-	 * @performance HTTP date: ~1.5x slower than the JS baseline (2/2 tasks failed) [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.5x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Date.toUTCString() is native (~1.5-1.7x loss); pooled httpDateInto cuts it to ~1.3x. [check:annotate]
-	 */
-	httpDate(secs?: number): Uint8Array;
-	/** Reusable-output http-date; returns bytes written (29). Throws if `output` is too small or the year is out of the fixed-width range. */
-	httpDateInto(secs: number | undefined, output: Uint8Array): number;
-	/** Parse an IMF-fixdate HTTP-date back to unix seconds. */
-	parseHttpDate(input: Uint8Array): bigint | null;
-	/** Parse an Accept-Encoding header into ordered preferences. */
-	parseAcceptEncoding(input: Uint8Array): EncodingPrefResult[];
-	/**
-	 * Base64 encode (standard by default; url-safe/padding configurable).
-	 * @performance Base64 encode: ~1.6x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.6x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Bun Buffer base64 is SIMD; loses ~1.5x. [check:annotate]
-	 */
-	base64Encode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array;
-	/**
-	 * Base64 decode (standard); throws on invalid input.
-	 * @performance Base64 decode: ≈ parity with the JS baseline [check:annotate]
+	 * Overall deadline (ms) for reading the request body. Default: 30s
+	 * (`DEFAULT_BODY_TIMEOUT_MS`). Set `0` to disable. Protects against
+	 * slowloris / trickling bodies.
 	 */
-	base64Decode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array;
-	/** Reusable-output base64 encode; returns bytes written. */
-	base64EncodeInto(input: Uint8Array, output: Uint8Array, urlSafe?: boolean, padding?: boolean): number;
-	/** Reusable-output base64 decode; returns bytes written. Throws on invalid input. */
-	base64DecodeInto(input: Uint8Array, output: Uint8Array, urlSafe?: boolean, padding?: boolean): number;
-	base64UrlEncode(input: Uint8Array): Uint8Array;
-	base64UrlDecode(input: Uint8Array): Uint8Array;
+	bodyTimeoutMs?: number;
+	/** Fallback handler used for write error paths. Defaults to the write ingress. */
+	fallback?: OptimizedIngressHandler;
 	/**
-	 * Lowercase hex encode.
-	 * @performance Hex encode: ~1.4x slower than the JS baseline (1/2 tasks failed) [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.4x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Buffer.toString('hex') is native SIMD; pooled hexEncodeInto cuts the loss from ~2.2x to ~1.35x. [check:annotate]
+	 * When true, route the JSON-validity fallback check through the higher-order
+	 * loader (`loader("jsonValid")`) instead of the direct native call —
+	 * exercising the loader's dispatch + counters on the real request path.
+	 * Default: false (the direct call is marginally faster for a single request;
+	 * the loader pays off for same-tick bursts / bulk work, see src/integration/batch.ts).
 	 */
-	hexEncode(input: Uint8Array): Uint8Array;
+	enableLoader?: boolean;
+}
+/** A raw web-standard route handler (`Request` → `Response`), e.g. the
+ *  health/metrics probes (`livenessHandler`, `readinessHandler`,
+ *  `healthHandler`, `metricsHandler`). Accepted as `BakedRoute.read` and
+ *  served for GET directly, outside the ingress pipeline. The optional third
+ *  arg carries the matched dynamic path params (`:param`/`*`) on the Node
+ *  adapter (Bun's native router handles matching; the ingress pipeline does
+ *  not echo params in its response). */
+type RouteHandler = (req: Request, srv?: unknown, params?: Record<string, string>) => Response | Promise<Response>;
+/** Route spec for the Bun.serve builder. */
+export interface BakedRoute {
 	/**
-	 * Hex decode; throws on odd length or invalid digits.
-	 * @performance Hex decode: ≈ parity with the JS baseline [check:annotate]
-	 * @remarks Slightly slower than Buffer hex decode (~1.3x). [check:annotate]
+	 * Wires GET + HEAD read handlers. Accepts an optimized ingress handler OR a
+	 * raw `RouteHandler` function (health/metrics probes are raw — see
+	 * src/ingress/health.ts). A raw handler is served for GET only.
 	 */
-	hexDecode(input: Uint8Array): Uint8Array;
-	/** Reusable-output lowercase-hex encode; returns bytes written. */
-	hexEncodeInto(input: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output hex decode; returns bytes written. Throws on bad input. */
-	hexDecodeInto(input: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output HMAC-SHA256 hex (64 bytes); returns bytes written. Throws on too-small buffer. */
-	hmacSha256Into(key: Uint8Array, data: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output cookie sign (`value.<64-hex>`); returns bytes written. Throws on too-small buffer. */
-	signCookieInto(value: Uint8Array, secret: Uint8Array, output: Uint8Array): number;
-	/** Reusable-output AEAD encrypt (ct + 16-byte tag); returns bytes written. Throws on too-small buffer. */
-	aeadEncryptInto(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, output: Uint8Array, algorithm?: string | null): number;
-	/** Reusable-output WS frame encode; returns bytes written. Throws on too-small buffer. */
-	wsFrameEncodeInto(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean, output: Uint8Array): number;
-	/** Reusable-output gzip compress; returns bytes written. Throws on too-small buffer. */
-	gzipCompressInto(data: Uint8Array, output: Uint8Array, level?: number | null): number;
-	/** Reusable-output brotli compress; returns bytes written. Throws on too-small buffer. */
-	brotliCompressInto(data: Uint8Array, output: Uint8Array, quality?: number | null): number;
+	read?: OptimizedIngressHandler | RouteHandler;
+	/** Wires POST/PUT/PATCH JSON-write handlers (and OPTIONS fallback). */
+	write?: OptimizedIngressHandler;
+	/** Wires a POST echo handler. */
+	echo?: OptimizedIngressHandler;
+	/** Wires a GET read handler (cookies-style route). */
+	cookies?: OptimizedIngressHandler;
+	/** Wires a DELETE read-style handler. */
+	delete?: OptimizedIngressHandler;
 	/**
-	 * Sign a cookie value as `value.signature` (HMAC-SHA256 hex).
-	 * @performance Cookie sign: ~1.0x faster than the JS baseline [check:annotate]
-	 */
-	signCookie(value: Uint8Array, secret: Uint8Array): Uint8Array;
+	 * A JS responder route: the native pipeline owns parse/validate/CORS/
+	 * rate-limit + terminal rejections; the responder builds the 2xx body
+	 * (async OK). Wired for `methods` (default GET). Built by
+	 * `nativeResponderRoute` (src/ingress/routes/responder.ts).
+	 */
+	responder?: {
+		/** The route's compiled native `IngressInner`. */
+		ingress: OptimizedIngressHandler;
+		/** The JS 2xx builder. */
+		handler: NativeResponder;
+		/** HTTP methods to wire (default `['GET']`). */
+		methods?: ReadonlyArray<string>;
+		/** Terminal envelope style (`'castrum'` default / `'ignex'`). */
+		terminalStyle?: TerminalStyle;
+		/** Read the body for native validation (default false — framework owns it). */
+		readBody?: boolean;
+	};
+	/** Overrides `maxBodyBytes` for this route's write/echo handlers. */
+	maxBodyBytes?: number;
 	/**
-	 * Verify a signed cookie; returns the value or null.
-	 * @performance Cookie verify: ~9.5x faster than the JS baseline [check:annotate]
+	 * Overall deadline (ms) for reading the request body on this route's
+	 * write/echo handlers. Default: 30_000 (`DEFAULT_BODY_TIMEOUT_MS`).
+	 * Set 0 to disable.
 	 */
-	verifyCookie(signed: Uint8Array, secret: Uint8Array): Uint8Array | null;
+	bodyTimeoutMs?: number;
+}
+/** RFC 6455 handshake values returned by `CreateIngressServerOptions.upgrade`. */
+export interface NodeUpgradeHandshake {
+	/** `Sec-WebSocket-Accept` value (compute via `rust.text.wsAcceptKey`). */
+	accept: string;
+	/** Optional negotiated subprotocol (`Sec-WebSocket-Protocol`). */
+	protocol?: string;
+}
+/** Options for {@link createIngressServer}. */
+export interface CreateIngressServerOptions {
+	port: number;
+	hostname?: string;
+	idleTimeout?: number;
+	maxRequestBodySize?: number;
+	reusePort?: boolean;
+	copyBody?: boolean;
+	getIp?: (req: Request, srv: unknown) => string | undefined;
+	routes: Record<string, BakedRoute>;
+	fallback?: OptimizedIngressHandler;
 	/**
-	 * Create a CSRF token (32-byte random hex + HMAC signature).
-	 * @performance CSRF create: ~13.7x faster than the JS baseline [check:annotate]
+	 * Invoked when an unhandled error escapes a request handler (currently wired
+	 * on the Node adapter; the Bun path uses runtime.onResponse). Never throws —
+	 * hook failures are swallowed.
 	 */
-	csrfToken(secret: Uint8Array): Uint8Array;
+	onError?: (info: {
+		error: Error;
+		request?: Request;
+	}) => void;
+	/** Node adapter only: ms to receive the complete request (headers + body).
+	 *  Guards slowloris/trickling requests. Default: 30_000. */
+	requestTimeoutMs?: number;
+	/** Node adapter only: ms to receive the request headers. Default: 30_000. */
+	headersTimeoutMs?: number;
+	/** Node adapter only: max requests per keep-alive socket before Node forces
+	 *  a fresh connection (bounds long-lived socket reuse). Default: 1000. */
+	maxRequestsPerSocket?: number;
+	/** Node adapter only: optional WebSocket upgrade handler. Return the RFC 6455
+	 *  handshake values (see {@link NodeUpgradeHandshake}) to complete the
+	 *  handshake on the hijacked socket; return null/undefined to decline the
+	 *  upgrade. Ignored by the Bun server. (`createWebSocketUpgrade` is Bun-only
+	 *  — Node's Response cannot carry a 101.) */
+	upgrade?: (req: Request) => NodeUpgradeHandshake | null | undefined;
+	/** Node adapter only: called after a WebSocket upgrade handshake completes
+	 *  (the 101 response was accepted), with the hijacked socket so the caller
+	 *  can attach a frame codec/message loop (e.g. the `ws` library). Ignored by
+	 *  the Bun server. */
+	onUpgrade?: (socket: import("node:stream").Duplex, req: unknown, head: Buffer) => void;
+}
+/**
+ * Minimal surface of the running server that castrum relies on.
+ *
+ * This is intentionally NOT `ReturnType<typeof Bun.serve>` so that the public
+ * types stay runtime-agnostic — Node.js TypeScript consumers don't need
+ * `@types/bun` just to import castrum's types. Bun's server exposes far more
+ * fields; treat the handle as opaque.
+ */
+export interface ServerHandle {
+	/** The port the server is bound to, when known (Bun exposes it; Node's
+	 *  http.Server does not — use `BakedServer.port` instead). */
+	port?: number;
+	/** Force-stop the server. Bun semantics: `true` drops active connections. */
+	stop(force?: boolean): void;
+}
+/** A running server instance plus a stop helper. */
+export interface BakedServer {
+	server: ServerHandle;
+	stop(): void;
+	port: number;
+}
+/** Options for `gracefulShutdown` (drain grace period + signals). */
+export interface GracefulShutdownOptions {
+	/** Grace period (ms) to drain in-flight requests before force-closing. */
+	timeoutMs?: number;
+	/** Signals to listen for. Default: SIGTERM + SIGINT. */
+	signals?: NodeJS.Signals[];
+}
+/**
+ * Wire SIGTERM/SIGINT to a graceful shutdown: soft-stop (drain in-flight
+ * requests) then force-close after `timeoutMs`. Works with both the Bun and
+ * Node server handles (both expose `stop(force?)`).
+ *
+ * Returns a cleanup function that removes the signal listeners. Call it (or
+ * `process.exit`) to tear down without hanging.
+ */
+export declare function gracefulShutdown(handles: ReadonlyArray<ServerHandle>, options?: GracefulShutdownOptions): () => void;
+/** A matched dynamic route: the handler map + the extracted path params. */
+export interface PathMatch {
+	methods: Record<string, unknown>;
+	params: Record<string, string>;
+}
+/** Options for `createWebSocketUpgrade` (supported subprotocols). */ export interface WebSocketUpgradeOptions {
+	/** Subprotocols this server supports; the first client-requested match wins. */
+	protocols?: ReadonlyArray<string>;
+}
+/** The WebSocket upgrade handshake result (101 response + negotiation info). */
+export interface WebSocketUpgradeResult {
+	/** The 101 Switching Protocols response — return it from your fetch handler. */
+	readonly response: Response;
+	/** The client's `Sec-WebSocket-Key` (handy for connection logging). */
+	readonly key: string;
+	/** The negotiated subprotocol, if any. */
+	readonly protocol: string | null;
+}
+/**
+ * Build a WebSocket 101 upgrade handshake response for a request.
+ *
+ * Validates `Sec-WebSocket-Key` presence and computes the RFC 6455 accept key
+ * via the native `rust.wsAcceptKey`, optionally negotiates a subprotocol, and
+ * returns a ready-to-serve `Response`. Returns `null` when the request is not a
+ * valid upgrade (missing/empty key).
+ *
+ * This only produces the handshake — pair it with your framework's own
+ * WebSocket server (Bun.serve's `websocket` handler, or a WS library), which
+ * owns the subsequent frames:
+ *
+ * @example
+ * ```ts
+ * const srv = Bun.serve({
+ *   port: 3000,
+ *   fetch(req, server) {
+ *     const up = createWebSocketUpgrade(req, { protocols: ["chat"] });
+ *     if (up && server.upgrade(req, { data: { protocol: up.protocol } })) {
+ *       return up.response;
+ *     }
+ *     return new Response("Not a websocket", { status: 400 });
+ *   },
+ *   websocket: {
+ *     message(ws, msg) { ws.send(msg); },
+ *   },
+ * });
+ * ```
+ */
+export declare function createWebSocketUpgrade(req: Request, opts?: WebSocketUpgradeOptions): WebSocketUpgradeResult | null;
+/** Options accepted by `createRust` / `rust.configure`. */
+export interface RustOptions {
 	/**
-	 * Constant-time verify a CSRF token.
-	 * @performance CSRF verify: ~3.3x faster than the JS baseline [check:annotate]
+	 * Rayon thread pool size.
+	 *
+	 * The rayon pool is process-wide and initialized **once** (native
+	 * `OnceLock`) — the first initialization wins. Importing this module
+	 * initializes the pool with defaults, so this option only takes effect when
+	 * the pool has not yet been created. For reliable control set
+	 * `CASTRUM_RAYON_THREADS` / `RUST_RAYON_THREADS` before import.
+	 * Default: max(1, hardwareConcurrency - 1).
 	 */
-	csrfVerify(token: Uint8Array, secret: Uint8Array): boolean;
-	/**
-	 * Resolve a URL reference against a base (RFC 3986).
-	 * @performance URL resolve: ~1.8x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.8x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Auto-deprecated: 1/1 benchmarks failed in the latest run (static classification was parity). [check:annotate]
-	 * @remarks Noisy ~1.5µs op; swings 0.74-1.03x run-to-run. UrlBuilder reuses the parsed base. [check:annotate]
+	rayonThreads?: number;
+	/** Cache MIME lookups keyed by normalized extension. Default: true. */
+	mimeCache?: boolean;
+	/** Reuse HMAC signers keyed by key-buffer identity. Default: true. */
+	hmacCache?: boolean;
+}
+/**
+ * The `rust.batch.*` array-of-bytes batch surface: N items in → one packed
+ * native call → bitsets / typed arrays / byte arrays out. Separated from the
+ * implementation (`./build.ts`) so type-only consumers don't pull the native
+ * resolver.
+ */
+export interface RustBatch {
+	jsonValid(items: Uint8Array[]): Uint8Array;
+	crc32(items: Uint8Array[]): Uint32Array;
+	validateEmail(items: Uint8Array[]): Uint8Array;
+	validateUuid(items: Uint8Array[]): Uint8Array;
+	validateIpv4(items: Uint8Array[]): Uint8Array;
+	validateIpv6(items: Uint8Array[]): Uint8Array;
+	jsonSumIds(items: Uint8Array[]): BigInt64Array;
+	queryParse(items: Uint8Array[]): Uint8Array[];
+	cookieParse(items: Uint8Array[]): Uint8Array[];
+	httpParseRequest(items: Uint8Array[]): Uint8Array[];
+	jsonPatch(docs: Uint8Array[], patches: Uint8Array[]): Uint8Array[];
+	hexEncode(items: Uint8Array[]): Uint8Array[];
+	hexDecode(items: Uint8Array[]): Uint8Array[];
+	base64Encode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[];
+	base64Decode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[];
+	formParse(items: Uint8Array[]): Uint8Array[];
+	signCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array[];
+	verifyCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array;
+	csrfVerify(items: Uint8Array[], secret: Uint8Array): Uint8Array;
+	schemaValidate(validator: SchemaValidator, items: Uint8Array[]): Uint8Array;
+	schemaValidateCount(validator: SchemaValidator, items: Uint8Array[]): number;
+	fnv1a64(items: Uint8Array[]): BigUint64Array;
+	etag(items: Uint8Array[], weak?: boolean | null): Uint8Array[];
+	urlEncode(items: Uint8Array[]): Uint8Array[];
+	urlDecode(items: Uint8Array[]): Uint8Array[];
+	urlDecodeBytes(items: Uint8Array[]): Uint8Array[];
+	mimeFromExtension(items: Uint8Array[]): Uint8Array[];
+	wsAcceptKey(items: Uint8Array[]): Uint8Array[];
+	base64UrlEncode(items: Uint8Array[]): Uint8Array[];
+	base64UrlDecode(items: Uint8Array[]): Uint8Array[];
+	passwordHash(passwords: Uint8Array[], salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array[];
+	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, items: Uint8Array[], algorithm?: string | null): Uint8Array[];
+	aeadDecrypt(key: Uint8Array, nonce: Uint8Array, items: Uint8Array[], algorithm?: string | null): Uint8Array[];
+	gzipCompress(items: Uint8Array[], level?: number | null): Uint8Array[];
+	gzipDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[];
+	brotliCompress(items: Uint8Array[], quality?: number | null): Uint8Array[];
+	brotliDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[];
+	jwtVerify(tokens: Uint8Array[], secret: Uint8Array, nowSeconds: number): Uint8Array;
+	hmacSha256(items: Uint8Array[], key: Uint8Array): Uint8Array[];
+	hmacSha256Verify(items: Uint8Array[], sigs: Uint8Array[], key: Uint8Array): Uint8Array;
+	passwordVerify(items: Uint8Array[], phcs: Uint8Array[]): Uint8Array;
+	urlResolve(bases: Uint8Array[], references: Uint8Array[]): Uint8Array[];
+	jwtSign(items: Uint8Array[], secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): Uint8Array[];
+	sseEncode(items: Uint8Array[], event?: string | null, id?: string | null, retry?: number | null): Uint8Array[];
+	wsFrameEncode(items: Uint8Array[], opcode: number, mask: boolean, fin: boolean): Uint8Array[];
+	wsFrameDecode(items: Uint8Array[]): Uint8Array[];
+	multipartParse(items: Uint8Array[], boundary: Uint8Array): MultipartPart[][];
+	templateRender(source: string, contexts: Uint8Array[]): Uint8Array[];
+}
+/** Raw packed-wire FFI namespace. */
+export interface RustPacked {
+	crc32BatchPacked(input: Uint8Array): Uint8Array;
+	jsonValidBatchPacked(input: Uint8Array): Uint8Array;
+	validateEmailBatchPacked(input: Uint8Array): Uint8Array;
+	validateUuidBatchPacked(input: Uint8Array): Uint8Array;
+	validateIpv4BatchPacked(input: Uint8Array): Uint8Array;
+	validateIpv6BatchPacked(input: Uint8Array): Uint8Array;
+	jsonSumBatchPacked(input: Uint8Array): Uint8Array;
+	queryParseBatchPacked(input: Uint8Array): Uint8Array;
+	cookieParseBatchPacked(input: Uint8Array): Uint8Array;
+	httpParseRequestBatchPacked(input: Uint8Array): Uint8Array;
+	/** Batch RFC 6902 JSON Patch (two packed lists, zipped) → packed results. */
+	jsonPatchBatchPacked(docs: Uint8Array, patches: Uint8Array): Uint8Array;
+	/** Packed FNV-1a 64 batch (i64 per item). */
+	fnv1A64BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed ETag batch (10 strong / 12 weak bytes per item). */
+	etagBatchPacked(input: Uint8Array, weak?: boolean | null): Uint8Array;
+	urlEncodeBatchPacked(input: Uint8Array): Uint8Array;
+	urlDecodeBatchPacked(input: Uint8Array): Uint8Array;
+	urlDecodeBytesBatchPacked(input: Uint8Array): Uint8Array;
+	mimeFromExtensionBatchPacked(input: Uint8Array): Uint8Array;
+	wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array;
+	jsonValidBatchCountPacked(input: Uint8Array): number;
+	validateEmailBatchCountPacked(input: Uint8Array): number;
+	validateUuidBatchCountPacked(input: Uint8Array): number;
+	validateIpv4BatchCountPacked(input: Uint8Array): number;
+	validateIpv6BatchCountPacked(input: Uint8Array): number;
+	jsonSumBatchTotalPacked(input: Uint8Array): number;
+	queryParseBatchTotalLenPacked(input: Uint8Array): number;
+	cookieParseBatchTotalLenPacked(input: Uint8Array): number;
+	httpParseRequestBatchTotalLenPacked(input: Uint8Array): number;
+	passwordHashBatchPacked(input: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array;
+	/** Packed password-verify batch (two packed lists, zipped) → bitset. */
+	passwordVerifyBatchPacked(passwords: Uint8Array, phcs: Uint8Array): Uint8Array;
+	/** Packed URL-resolve batch (two packed lists, zipped) → packed results. */
+	urlResolveBatchPacked(bases: Uint8Array, references: Uint8Array): Uint8Array;
+	aeadEncryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
+	aeadDecryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
+	gzipCompressBatchPacked(input: Uint8Array, level?: number | null): Uint8Array;
+	gzipDecompressBatchPacked(input: Uint8Array): Uint8Array;
+	brotliCompressBatchPacked(input: Uint8Array, quality?: number | null): Uint8Array;
+	brotliDecompressBatchPacked(input: Uint8Array): Uint8Array;
+	jwtSignBatchPacked(input: Uint8Array, secret: Uint8Array, ttlSeconds: number | null, nowSeconds: number): Uint8Array;
+	jwtVerifyBatchPacked(input: Uint8Array, secret: Uint8Array, nowSeconds: number): Uint8Array;
+	/** Batch HMAC-SHA256 sign (packed in → hex-signature byte results). */
+	hmacSha256BatchPacked(input: Uint8Array, key: Uint8Array): Uint8Array;
+	/** Batch HMAC-SHA256 verify (two packed lists: data + hex sigs, zipped) → bitset. */
+	hmacSha256VerifyBatchPacked(input: Uint8Array, sigs: Uint8Array, key: Uint8Array): Uint8Array;
+	multipartParseBatchPacked(input: Uint8Array, boundary: Uint8Array): Uint8Array;
+	templateRenderBatchPacked(input: Uint8Array, source: string): Uint8Array;
+	sseEncodeBatchPacked(input: Uint8Array, event: string | null, id: string | null, retry: number | null): Uint8Array;
+	wsFrameEncodeBatchPacked(input: Uint8Array, opcode: number, mask: boolean, fin: boolean): Uint8Array;
+	wsFrameDecodeBatchPacked(input: Uint8Array): Uint8Array;
+}
+/**
+ * The flat `rust.*` scalar method surface: bytes in → normalized out. Built by
+ * the scalar builders from the native addon + Bun built-in delegations.
+ */
+export interface RustScalar {
+	crc32(input: Uint8Array): number;
+	fnv1a64(input: Uint8Array): bigint;
+	/**
+	 * XXH3-64 over raw bytes (high-throughput non-cryptographic hash).
+	 * Compare against `Bun.hash.xxHash3` — see docs/bun-builtins-decision-matrix.md.
 	 */
-	urlResolve(base: Uint8Array, reference: Uint8Array): Uint8Array;
+	xxh3(input: Uint8Array): bigint;
+	hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array | string;
+	hmacSha256Verify(key: Uint8Array, data: Uint8Array, sig: Uint8Array | string): boolean;
+	jsonValid(input: Uint8Array): boolean;
 	/**
-	 * Build a percent-encoded query string from params (sorted keys).
-	 * @performance URL query build: ~1.4x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.4x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks encodeURIComponent baseline wins (~1.2-1.35x). [check:annotate]
+	 * Parse JSON to a JS value (FFI packed structural parse on Bun — sonic-rs
+	 * parses ONCE, JS assembles from a token stream with no re-parse; napi
+	 * sonic-rs DOM fallback). Throws on invalid JSON.
+	 */
+	jsonParse(input: Uint8Array): unknown;
+	jsonSumIds(input: Uint8Array): bigint;
+	jsonPatch(doc: Uint8Array, patch: Uint8Array): Uint8Array | string;
+	mimeFromExtension(ext: Uint8Array): Uint8Array | string;
+	randomToken(byteLen: number): Uint8Array | string;
+	randomTokenInto(byteLen: number, output: Uint8Array): number;
+	urlEncode(input: Uint8Array): Uint8Array | string;
+	urlDecode(input: Uint8Array): Uint8Array;
+	/**
+	 * Strict percent-decode without UTF-8 validation.
+	 */
+	urlDecodeBytes(input: Uint8Array): Uint8Array;
+	urlEncodeInto(input: Uint8Array, output: Uint8Array): number;
+	urlDecodeInto(input: Uint8Array, output: Uint8Array): number;
+	validateEmail(input: Uint8Array): boolean;
+	validateUuid(input: Uint8Array): boolean;
+	validateIpv4(input: Uint8Array): boolean;
+	validateIpv6(input: Uint8Array): boolean;
+	wsAcceptKey(key: Uint8Array): Uint8Array | string;
+	wsAcceptKeyInto(key: Uint8Array, output: Uint8Array): number;
+	httpParseRequestPacked(input: Uint8Array): Uint8Array;
+	queryParsePacked(input: Uint8Array): Uint8Array;
+	cookieParsePacked(input: Uint8Array): Uint8Array;
+	httpParseRequestPackedInto(input: Uint8Array, output: Uint8Array): number;
+	queryParsePackedInto(input: Uint8Array, output: Uint8Array): number;
+	cookieParsePackedInto(input: Uint8Array, output: Uint8Array): number;
+	/**
+	 * Parse an application/x-www-form-urlencoded body into packed pairs.
+	 */
+	formParsePacked(input: Uint8Array): Uint8Array;
+	formParsePackedInto(input: Uint8Array, output: Uint8Array): number;
+	/**
+	 * Parse a Content-Type header into a structured media type.
+	 */
+	parseMediaType(input: Uint8Array): MediaTypeResult;
+	/**
+	 * Generate a strong/weak ETag (crc32-based).
+	 */
+	etag(data: Uint8Array, weak?: boolean): Uint8Array | string;
+	etagInto(data: Uint8Array, output: Uint8Array, weak?: boolean): number;
+	/**
+	 * Format a unix timestamp as an IMF-fixdate HTTP-date.
+	 */
+	httpDate(secs?: number): Uint8Array | string;
+	httpDateInto(secs: number | undefined, output: Uint8Array): number;
+	parseHttpDate(input: Uint8Array): bigint | null;
+	parseAcceptEncoding(input: Uint8Array): EncodingPrefResult[];
+	/**
+	 * Base64 encode (standard by default; url-safe/padding configurable).
+	 */
+	base64Encode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array | string;
+	/**
+	 * Base64 decode (standard); throws on invalid input.
+	 */
+	base64Decode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array;
+	base64EncodeInto(input: Uint8Array, output: Uint8Array, urlSafe?: boolean, padding?: boolean): number;
+	base64DecodeInto(input: Uint8Array, output: Uint8Array, urlSafe?: boolean, padding?: boolean): number;
+	base64UrlEncode(input: Uint8Array): Uint8Array | string;
+	base64UrlDecode(input: Uint8Array): Uint8Array;
+	/**
+	 * Lowercase hex encode.
+	 */
+	hexEncode(input: Uint8Array): Uint8Array | string;
+	/**
+	 * Hex decode; throws on odd length or invalid digits.
+	 */
+	hexDecode(input: Uint8Array): Uint8Array;
+	hexEncodeInto(input: Uint8Array, output: Uint8Array): number;
+	hexDecodeInto(input: Uint8Array, output: Uint8Array): number;
+	hmacSha256Into(key: Uint8Array, data: Uint8Array, output: Uint8Array): number;
+	signCookieInto(value: Uint8Array, secret: Uint8Array, output: Uint8Array): number;
+	verifyCookieInto(signed: Uint8Array, secret: Uint8Array, output: Uint8Array): number | null;
+	csrfTokenInto(secret: Uint8Array, output: Uint8Array): number;
+	aeadEncryptInto(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, output: Uint8Array, algorithm?: string | null): number;
+	wsFrameEncodeInto(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean, output: Uint8Array): number;
+	gzipCompressInto(data: Uint8Array, output: Uint8Array, level?: number | null): number;
+	brotliCompressInto(data: Uint8Array, output: Uint8Array, quality?: number | null): number;
+	/**
+	 * Sign a cookie value as `value.signature` (HMAC-SHA256 hex).
+	 */
+	signCookie(value: Uint8Array, secret: Uint8Array): Uint8Array | string;
+	/**
+	 * Verify a signed cookie; returns the value or null.
+	 */
+	verifyCookie(signed: Uint8Array, secret: Uint8Array): Uint8Array | string | null;
+	/**
+	 * Create a CSRF token (32-byte random hex + HMAC signature).
+	 */
+	csrfToken(secret: Uint8Array): Uint8Array | string;
+	/**
+	 * Constant-time verify a CSRF token.
+	 */
+	csrfVerify(token: Uint8Array, secret: Uint8Array): boolean;
+	/**
+	 * Resolve a URL reference against a base (RFC 3986).
 	 */
-	urlEncodeQuery(params: Record<string, string>): Uint8Array;
+	urlResolve(base: Uint8Array, reference: Uint8Array): Uint8Array | string;
 	/**
-	 * @performance JSON schema validate: ~1.7x faster than the JS baseline (2/2 tasks won) [check:annotate]
-	 * @remarks Zero-DOM fast path validates raw bytes for the common keyword subset (scalar ~1.2-2.4x, batch ~1.0-1.56x vs ajv); unsupported keywords fall back to the jsonschema crate. [check:annotate]
+	 * Build a percent-encoded query string from params (sorted keys).
 	 */
+	urlEncodeQuery(params: Record<string, string>): Uint8Array | string;
 	createSchemaValidator(schema: Uint8Array): SchemaValidatorInstance;
 	createHmacSigner(key: Uint8Array): HmacSignerInstance;
 	createTemplateRenderer(source: string): TemplateRendererInstance;
-	/** Higher-order form parser: owns a reusable output buffer (setup once). */
 	createFormParser(capacity?: number): FormParserInstance;
-	/** Higher-order media-type parser: reusable wildcard matcher. */
 	createMediaTypeParser(): MediaTypeParserInstance;
 	/**
 	 * Higher-order conditional-request check: per-resource 304 decision (setup once).
-	 * @performance Conditional request: ~1.7x faster than the JS baseline [check:annotate]
 	 */
 	createConditionalRequest(etagValue: Uint8Array, lastModifiedSecs?: number): ConditionalRequestInstance;
 	/**
 	 * Higher-order negotiator: precompiles supported encodings once.
-	 * @performance Accept-Encoding negotiate: ~4.2x faster than the JS baseline [check:annotate]
 	 */
 	createAcceptNegotiator(supported: string[]): AcceptNegotiatorInstance;
-	/** Higher-order codec: base64 config compiled once. */
 	createBase64Codec(urlSafe?: boolean, padding?: boolean): Base64CodecInstance;
-	/** Higher-order cookie signer: HMAC key compiled once. */
 	createCookieSigner(secret: Uint8Array): CookieSignerInstance;
-	/** Higher-order CSRF protector: HMAC key compiled once. */
 	createCsrfProtector(secret: Uint8Array): CsrfProtectorInstance;
-	/** Higher-order URL builder: base parsed once, reused. */
 	createUrlBuilder(base: Uint8Array): UrlBuilderInstance;
-	/** Higher-order JWT signer: HS256 key + ttl compiled once. */
 	createJwtSigner(secret: Uint8Array, ttlSeconds?: number): JwtSignerInstance;
-	/** Higher-order AEAD cipher: algorithm + key compiled once. */
 	createAeadCipher(key: Uint8Array, algorithm?: string): AeadCipherInstance;
-	/** Higher-order argon2id hasher: params compiled once. */
 	createArgon2Hasher(options?: PasswordHashOptions | null): Argon2HasherInstance;
-	/** Higher-order media-type matcher: expected precompiled once. */
 	createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance;
 	/**
 	 * Sharded fixed-window per-key rate limiter. `maxEntries` clamps internally
@@ -686,1106 +1099,364 @@ export interface RustScalar {
 	createRateLimiter(limit: number, windowMs: number, maxEntries?: number | null): RateLimiterInstance;
 	initThreadPool(rayonThreads?: number): void;
 	rayonNumThreads(): number;
-	/**
-	 * @performance JWT sign: ~1.1x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.1x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Base64 + claims DOM marshal overhead. Use jwtSignBytes (claims as JSON bytes) which skips the napi Value marshal and flips to a ~1.07x win. [check:annotate]
-	 */
 	jwtSign(claims: Record<string, unknown>, secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): Uint8Array;
 	/**
 	 * Sign a JWT from pre-serialized claim JSON bytes — skips the napi
 	 * `serde_json::Value` marshal of `jwtSign` for callers that already hold the
 	 * bytes (same injection semantics).
-	 * @performance JWT sign (bytes): ≈ parity with the JS baseline [check:annotate]
-	 * @remarks Byte-JSON claims overload avoids the napi serde_json::Value DOM marshal; flips jwtSign from a ~1.3x loss to ~1.07x (parity). [check:annotate]
-	 */
-	jwtSignBytes(claimsJson: Uint8Array, secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): Uint8Array;
-	/**
-	 * @performance JWT verify: ~1.7x faster than the JS baseline (2/2 tasks won) [check:annotate]
 	 */
+	jwtSignBytes(claimsJson: Uint8Array, secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): Uint8Array | string;
+	jwtSignBytesInto(claimsJson: Uint8Array, secret: Uint8Array, output: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number): number;
 	jwtVerify(token: Uint8Array, secret: Uint8Array, nowSeconds?: number): unknown;
+	passwordHash(password: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array | string;
+	passwordVerify(password: Uint8Array, phc: Uint8Array): boolean;
 	/**
-	 * @performance Password hash: ~18.2x faster than the JS baseline (2/2 tasks won) [check:annotate]
-	 * @remarks argon2id vs node:crypto scrypt. [check:annotate]
+	 * bcrypt password hash → `$2b$` PHC string (cost clamped 4..=31).
 	 */
-	passwordHash(password: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array;
-	passwordVerify(password: Uint8Array, phc: Uint8Array): boolean;
-	/** bcrypt password hash → `$2b$` PHC string (cost clamped 4..=31). */
 	passwordHashBcrypt(password: Uint8Array, cost: number): string;
-	/** Verify a password against a bcrypt `$2b$` PHC string. */
-	passwordVerifyBcrypt(password: Uint8Array, hash: string): boolean;
-	/** PBKDF2-HMAC-SHA256 key derivation (dkLen clamped to 1 MiB). */
-	pbkdf2Sha256(password: Uint8Array, salt: Uint8Array, rounds: number, dkLen: number): Uint8Array;
 	/**
-	 * @performance AEAD encrypt: ~1.3x faster than the JS baseline [check:annotate]
+	 * Verify a password against a bcrypt `$2b$` PHC string.
 	 */
-	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, algorithm?: string | null): Uint8Array;
+	passwordVerifyBcrypt(password: Uint8Array, hash: string): boolean;
 	/**
-	 * @performance AEAD decrypt: ~1.4x faster than the JS baseline [check:annotate]
+	 * PBKDF2-HMAC-SHA256 key derivation (dkLen clamped to 1 MiB).
 	 */
+	pbkdf2Sha256(password: Uint8Array, salt: Uint8Array, rounds: number, dkLen: number): Uint8Array;
+	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, algorithm?: string | null): Uint8Array;
 	aeadDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, algorithm?: string | null): Uint8Array | null;
-	/**
-	 * @performance Gzip compress: ≈ parity with the JS baseline (1/2 tasks won) [check:annotate]
-	 */
 	gzipCompress(data: Uint8Array, level?: number | null): Uint8Array;
 	/**
-	 * @performance Gzip decompress: ~1.0x faster than the JS baseline [check:annotate]
-	 * @remarks zlib-rs vs node zlib; swings 1.0-1.4x run-to-run. [check:annotate]
 	 * @param maxDecompressed Caps decompressed output (default 64 MiB) as a
 	 *   decompression-bomb guard; a larger value errors.
 	 */
 	gzipDecompress(data: Uint8Array, maxDecompressed?: number | null): Uint8Array;
 	/**
-	 * @performance Brotli compress: ~1.7x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.7x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks The native brotli baseline wins for small inputs. [check:annotate]
+	 * gzip-decompress into `output` (pooled — caller-owned buffer); returns bytes
+	 * written. Throws when `output` is too small (the exact required size is
+	 * reported) or the input is invalid / exceeds `maxDecompressed`.
+	 * @param maxDecompressed Caps decompressed output (default 64 MiB) as a
+	 *   decompression-bomb guard; a larger value errors.
 	 */
+	gzipDecompressInto(data: Uint8Array, output: Uint8Array, maxDecompressed?: number | null): number;
 	brotliCompress(data: Uint8Array, quality?: number | null): Uint8Array;
 	/**
-	 * @performance Brotli decompress: ~1.4x slower than the JS baseline [check:annotate]
-	 * @deprecated Slower than the native JS baseline (~1.4x) — prefer the JS/Bun baseline. [check:annotate]
-	 * @remarks Auto-deprecated: 1/1 benchmarks failed in the latest run (static classification was proven). [check:annotate]
 	 * @param maxDecompressed Caps decompressed output (default 64 MiB) as a
 	 *   decompression-bomb guard; a larger value errors.
 	 */
 	brotliDecompress(data: Uint8Array, maxDecompressed?: number | null): Uint8Array;
 	/**
-	 * @performance Multipart parse: ~1.9x faster than the JS baseline [check:annotate]
+	 * brotli-decompress into `output` (pooled — caller-owned buffer); returns
+	 * bytes written. Throws when `output` is too small (the exact required size
+	 * is reported) or the input is invalid / exceeds `maxDecompressed`.
+	 * @param maxDecompressed Caps decompressed output (default 64 MiB) as a
+	 *   decompression-bomb guard; a larger value errors.
 	 */
+	brotliDecompressInto(data: Uint8Array, output: Uint8Array, maxDecompressed?: number | null): number;
 	multipartParse(body: Uint8Array, boundary: Uint8Array): MultipartPart[];
-	/** Zero-copy packed sibling of `multipartParse` (packed parts layout). */
 	multipartParsePacked(body: Uint8Array, boundary: Uint8Array): Uint8Array;
-	/**
-	 * @performance WS frame encode: ~2.0x faster than the JS baseline [check:annotate]
-	 */
+	multipartParsePackedInto(body: Uint8Array, boundary: Uint8Array, output: Uint8Array): number;
 	wsFrameEncode(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean): Uint8Array;
-	/**
-	 * @performance WS frame decode: ~2.3x faster than the JS baseline [check:annotate]
-	 */
 	wsFrameDecode(data: Uint8Array): WsFrame | null;
-	/**
-	 * @performance SSE encode: ≈ parity with the JS baseline [check:annotate]
-	 */
+	wsFrameDecodePackedInto(data: Uint8Array, output: Uint8Array): number | null;
 	sseEncodeEvent(event: string | null, data: Uint8Array, id: string | null, retry: number | null): Uint8Array;
+	sseEncodeEventInto(event: string | null, data: Uint8Array, id: string | null, retry: number | null, output: Uint8Array): number;
 }
-/** The full Rust FFI client (scalar methods + namespaces + configuration). */
-export interface RustClient extends RustScalar {
-	text: RustText;
-	batch: RustBatch;
-	packed: RustPacked;
+/** String-oriented FFI namespace. */
+export interface RustText {
 	/**
-	 * Resolve the native transport in use on this runtime: `"ffi"` (bun:ffi —
-	 * the PRIMARY transport under Bun) or `"napi"` (Node, forced
-	 * `CASTRUM_FFI_MODE=napi`, or a failed ffi bind-time self-test).
+	 * Resolve a lowercase file extension to a MIME type string (e.g. `"html"` →
+	 * `"text/html"`). Unknown extensions return `"application/octet-stream"`.
+	 * @param ext the file extension WITHOUT a leading dot, case-insensitive.
+	 * @returns the MIME type for `ext`.
 	 */
-	transport(): "ffi" | "napi";
-	/** Whether the bun:ffi transport is live (equivalent to `transport() === "ffi"`). */
-	ffiActive(): boolean;
+	mimeFromExtension(ext: string): string;
 	/**
-	 * Update defaults on this instance. `mimeCache` / `hmacCache` apply
-	 * immediately (per-instance). `rayonThreads` is applied only if the
-	 * process-wide pool is not yet initialized (see {@link RustOptions}).
+	 * RFC 3986 percent-encode a string (the `encodeURIComponent` unreserved
+	 * set). Under Bun this delegates to the native `encodeURIComponent` for
+	 * ~4x speed with byte-for-byte parity.
+	 * @param input the string to encode.
+	 * @returns the percent-encoded string.
 	 */
-	configure(options: RustOptions): void;
-}
-/**
- * Create an isolated Rust client with the given defaults.
- *
- * `mimeCache` / `hmacCache` are per-instance. `rayonThreads` only applies
- * before the process-wide rayon pool is initialized (once per process — see
- * {@link RustOptions.rayonThreads}); the pool defaults to the env var or
- * `max(1, hardwareConcurrency - 1)` otherwise.
- */
-export declare function createRust(options?: RustOptions): RustClient;
-/**
- * The default, ready-to-use `RustClient` created with no options (resolves
- * rayon threads from the host automatically). Most consumers just do
- * `import { rust } from "castrum"` and call `rust.<fn>(...)` directly.
- */
-export declare const rust: RustClient;
-/** Recommended implementation for an operation. */
-export type OpImpl = "native" | "js";
-export interface OpDecision {
-	/** The recommended implementation when the addon is available. */
-	readonly impl: OpImpl;
-	/** Why this decision (measured ratio / rationale). */
-	readonly note?: string;
-}
-/**
- * The benchmark-driven native-vs-JS decision for `op` — runtime-aware.
- *
- * Returns `"native"` when the Rust addon is the recommended implementation,
- * `"js"` when a pure-JS (or Bun built-in) implementation wins, or `null` for
- * unknown ops (or when the addon is unavailable — with no addon there is no
- * "native" choice). Under Bun, ops in {@link BUN_WINS} resolve to `"js"` so the
- * consumer's JS path delegates to the faster Bun built-in.
- */
-export declare const opImpl: (op: string) => OpImpl | null;
-/** `true` when the Rust addon is the recommended impl for `op`. */
-export declare const isNativeOp: (op: string) => boolean;
-/** The decision record for `op`, or `null` when unknown. */
-export declare const opDecision: (op: string) => OpDecision | null;
-export type PerformanceStatus = "proven" | "parity" | "not-competitive" | "unmeasured";
-export interface ProvenEntry {
-	/** Public `rust.<name>` method key. */
-	name: string;
-	/** Benchmark comparison label (see src/bench/comparisons.ts). */
-	label: string;
-	/** Baseline task name in the CPU report. */
-	nativeTask: string;
-	/** Rust task name in the CPU report. */
-	rustTask: string;
-	status: PerformanceStatus;
-	/** Typical rust-vs-baseline ratio from release/perf builds (rust faster = >1). */
-	typicalRatio?: number;
-	/** Why this classification. */
-	note?: string;
-}
-/**
- * Curated registry. Classifications are based on release/perf-build results
- * (docs + prior runs); the audit script re-checks them against the latest
- * report. Borderline wins are kept as "parity" so the `proven` surface stays
- * honest.
- *
- * `as const satisfies` keeps the literal `name`/`status` types so the
- * `ProvenKey` type (below) can be derived at the type level.
- */
-export declare const PROVEN_SURFACE: readonly [
-	{
-		readonly name: "fnv1a64";
-		readonly label: "FNV-1a 64";
-		readonly nativeTask: "native:fnv1a64";
-		readonly rustTask: "rust:fnv1a64";
-		readonly status: "proven";
-		readonly typicalRatio: 11;
-	},
-	{
-		readonly name: "jsonValid";
-		readonly label: "JSON valid";
-		readonly nativeTask: "native:json_valid";
-		readonly rustTask: "rust:json_valid";
-		readonly status: "proven";
-		readonly typicalRatio: 3;
-	},
-	{
-		readonly name: "jsonSumIds";
-		readonly label: "JSON sum";
-		readonly nativeTask: "native:json_sum";
-		readonly rustTask: "rust:json_sum";
-		readonly status: "proven";
-		readonly typicalRatio: 3;
-	},
-	{
-		readonly name: "httpParseRequestPacked";
-		readonly label: "HTTP parse";
-		readonly nativeTask: "native:http_parse";
-		readonly rustTask: "rust:http_parse";
-		readonly status: "proven";
-		readonly typicalRatio: 4;
-	},
-	{
-		readonly name: "queryParsePacked";
-		readonly label: "Query parse";
-		readonly nativeTask: "native:query_parse";
-		readonly rustTask: "rust:query_parse";
-		readonly status: "proven";
-		readonly typicalRatio: 4;
-	},
-	{
-		readonly name: "cookieParsePacked";
-		readonly label: "Cookie parse";
-		readonly nativeTask: "native:cookie_parse";
-		readonly rustTask: "rust:cookie_parse";
-		readonly status: "proven";
-		readonly typicalRatio: 2.5;
-	},
-	{
-		readonly name: "wsAcceptKey";
-		readonly label: "WebSocket accept";
-		readonly nativeTask: "native:ws_accept_key";
-		readonly rustTask: "rust:ws_accept_key";
-		readonly status: "proven";
-		readonly typicalRatio: 1.6;
-	},
-	{
-		readonly name: "jsonPatch";
-		readonly label: "JSON Patch";
-		readonly nativeTask: "native:json_patch";
-		readonly rustTask: "rust:json_patch";
-		readonly status: "proven";
-		readonly typicalRatio: 1.2;
-		readonly note: "Modest but real win; swings ~0.9-1.5x run-to-run (DOM marshal dominated).";
-	},
-	{
-		readonly name: "hmacSha256";
-		readonly label: "HMAC sign";
-		readonly nativeTask: "native:hmac_sha256";
-		readonly rustTask: "rust:hmac_sha256";
-		readonly status: "proven";
-		readonly typicalRatio: 1.5;
-		readonly note: "Classification vs the node:crypto baseline. Under Bun the public rust.hmacSha256 delegates to Bun.CryptoHasher (BUN_WINS \u2014 hex re-encoded to the same contract); this row measures the raw addon (see src/bench/raw-native.ts).";
-	},
-	{
-		readonly name: "hmacSha256Verify";
-		readonly label: "HMAC verify";
-		readonly nativeTask: "native:hmac_verify";
-		readonly rustTask: "rust:hmac_verify";
-		readonly status: "proven";
-		readonly typicalRatio: 2.4;
-	},
-	{
-		readonly name: "validateEmail";
-		readonly label: "Email validation";
-		readonly nativeTask: "native:validate_email";
-		readonly rustTask: "rust:validate_email";
-		readonly status: "proven";
-		readonly typicalRatio: 3;
-	},
-	{
-		readonly name: "validateIpv6";
-		readonly label: "IPv6 validation";
-		readonly nativeTask: "native:validate_ipv6";
-		readonly rustTask: "rust:validate_ipv6";
-		readonly status: "proven";
-		readonly typicalRatio: 1.3;
-	},
-	{
-		readonly name: "urlEncode";
-		readonly label: "URL encode";
-		readonly nativeTask: "native:url_encode";
-		readonly rustTask: "rust:url_encode";
-		readonly status: "not-competitive";
-		readonly note: "Public rust.urlEncode delegates to encodeURIComponent under Bun (BUN_WINS \u2014 ~3-4x faster than the FFI crossing; skips the C-ABI call). The rust: column measures the RAW addon (src/bench/raw-native.ts): the small-input FFI crossing loses (~0.58x), but LARGE inputs win (rust:url_encode_large ~1.45x) \u2014 the honest report no longer self-compares the built-in. Rust addon remains the Node path. Byte parity pinned by test/unit/features/url.test.ts + test/unit/features/wiring.test.ts.";
-	},
-	{
-		readonly name: "urlDecode";
-		readonly label: "URL decode";
-		readonly nativeTask: "native:url_decode";
-		readonly rustTask: "rust:url_decode";
-		readonly status: "not-competitive";
-		readonly note: "Public rust.urlDecode delegates to decodeURIComponent under Bun (BUN_WINS \u2014 ~4-8x faster than the FFI crossing; strict UTF-8 semantics match: both throw on malformed/invalid). The rust: column measures the RAW addon (src/bench/raw-native.ts): the small-input FFI crossing loses (~0.55x), but LARGE inputs win (rust:url_decode_large ~3.45x) \u2014 the honest report no longer self-compares the built-in. Rust addon remains the Node path and the raw-bytes urlDecodeBytes stays native. Parity pinned by test/unit/features/url.test.ts + test/unit/features/wiring.test.ts.";
-	},
-	{
-		readonly name: "jwtVerify";
-		readonly label: "JWT verify";
-		readonly nativeTask: "native:jwt_verify";
-		readonly rustTask: "rust:jwt_verify";
-		readonly status: "proven";
-		readonly typicalRatio: 1.4;
-	},
-	{
-		readonly name: "passwordHash";
-		readonly label: "Password hash";
-		readonly nativeTask: "native:password_hash";
-		readonly rustTask: "rust:password_hash";
-		readonly status: "proven";
-		readonly typicalRatio: 19;
-		readonly note: "argon2id vs node:crypto scrypt.";
-	},
-	{
-		readonly name: "aeadEncrypt";
-		readonly label: "AEAD encrypt";
-		readonly nativeTask: "native:aead_encrypt";
-		readonly rustTask: "rust:aead_encrypt";
-		readonly status: "proven";
-		readonly typicalRatio: 1.6;
-	},
-	{
-		readonly name: "aeadDecrypt";
-		readonly label: "AEAD decrypt";
-		readonly nativeTask: "native:aead_decrypt";
-		readonly rustTask: "rust:aead_decrypt";
-		readonly status: "proven";
-		readonly typicalRatio: 2;
-	},
-	{
-		readonly name: "gzipDecompress";
-		readonly label: "Gzip decompress";
-		readonly nativeTask: "native:gzip_decompress";
-		readonly rustTask: "rust:gzip_decompress";
-		readonly status: "proven";
-		readonly typicalRatio: 1.4;
-		readonly note: "zlib-rs vs node zlib; swings 1.0-1.4x run-to-run. Deliberately NOT delegated to Bun.gunzipSync under Bun (NOT in BUN_WINS): Bun's decompressor has no output-size bound, and the native path keeps the 64 MiB decompression-bomb cap.";
-	},
-	{
-		readonly name: "brotliDecompress";
-		readonly label: "Brotli decompress";
-		readonly nativeTask: "native:brotli_decompress";
-		readonly rustTask: "rust:brotli_decompress";
-		readonly status: "proven";
-		readonly typicalRatio: 1.9;
-	},
-	{
-		readonly name: "multipartParse";
-		readonly label: "Multipart parse";
-		readonly nativeTask: "native:multipart_parse";
-		readonly rustTask: "rust:multipart_parse";
-		readonly status: "proven";
-		readonly typicalRatio: 2.3;
-	},
-	{
-		readonly name: "wsFrameEncode";
-		readonly label: "WS frame encode";
-		readonly nativeTask: "native:ws_frame_encode";
-		readonly rustTask: "rust:ws_frame_encode";
-		readonly status: "proven";
-		readonly typicalRatio: 1.8;
-	},
-	{
-		readonly name: "wsFrameDecode";
-		readonly label: "WS frame decode";
-		readonly nativeTask: "native:ws_frame_decode";
-		readonly rustTask: "rust:ws_frame_decode";
-		readonly status: "proven";
-		readonly typicalRatio: 2;
-	},
-	{
-		readonly name: "createSchemaValidator";
-		readonly label: "JSON schema validate";
-		readonly nativeTask: "native:json_schema_validate";
-		readonly rustTask: "rust:json_schema_validate";
-		readonly status: "proven";
-		readonly note: "Zero-DOM fast path validates raw bytes for the common keyword subset (scalar ~1.2-2.4x, batch ~1.0-1.56x vs ajv); unsupported keywords fall back to the jsonschema crate.";
-	},
-	{
-		readonly name: "crc32";
-		readonly label: "CRC32";
-		readonly nativeTask: "native:crc32";
-		readonly rustTask: "rust:crc32";
-		readonly status: "not-competitive";
-		readonly note: "Raw addon vs the same-engine JS crc-32 loop (~0.23-0.44x across runs). Under Bun the public rust.crc32 delegates to Bun.hash.crc32 (BUN_WINS, ~2.8-8.4x) \u2014 this row measures the raw addon (src/bench/raw-native.ts).";
-	},
-	{
-		readonly name: "xxh3";
-		readonly label: "XXH3-64";
-		readonly nativeTask: "diag:bun_hash_xxh3";
-		readonly rustTask: "diag:xxh3";
-		readonly status: "not-competitive";
-		readonly note: "Bun.hash.xxHash3 wins ~4x (in-process C++ beats the FFI crossing). The public rust.xxh3 now DELEGATES to Bun.hash.xxHash3 under Bun (BUN_WINS); the addon remains the Node/non-Bun fast path. See docs/bun-builtins-decision-matrix.md.";
-	},
-	{
-		readonly name: "randomToken";
-		readonly label: "Random token";
-		readonly nativeTask: "native:random_token";
-		readonly rustTask: "rust:random_token";
-		readonly status: "parity";
-		readonly typicalRatio: 1.1;
-		readonly note: "Raw addon vs crypto.getRandomValues baseline. Under Bun the public rust.randomToken delegates to crypto.getRandomValues + native hex (BUN_WINS, same 2n-hex format + 16 MiB guard) \u2014 this row measures the raw addon (src/bench/raw-native.ts).";
-	},
-	{
-		readonly name: "validateUuid";
-		readonly label: "UUID validation";
-		readonly nativeTask: "native:validate_uuid";
-		readonly rustTask: "rust:validate_uuid";
-		readonly status: "parity";
-		readonly typicalRatio: 1;
-	},
-	{
-		readonly name: "validateIpv4";
-		readonly label: "IPv4 validation";
-		readonly nativeTask: "native:validate_ipv4";
-		readonly rustTask: "rust:validate_ipv4";
-		readonly status: "parity";
-		readonly typicalRatio: 1.05;
-	},
-	{
-		readonly name: "mimeFromExtension";
-		readonly label: "MIME lookup";
-		readonly nativeTask: "native:mime";
-		readonly rustTask: "rust:mime";
-		readonly status: "parity";
-		readonly typicalRatio: 1.4;
-		readonly note: "Consistently ~1.38-1.44x rust after the 2026-08-12 marshal reduction (cachedMime no longer per-call slices; text.mimeFromExtension memoizes the decoded string). phf table lookup.";
-	},
-	{
-		readonly name: "gzipCompress";
-		readonly label: "Gzip compress";
-		readonly nativeTask: "native:gzip_compress";
-		readonly rustTask: "rust:gzip_compress";
-		readonly status: "parity";
-		readonly typicalRatio: 1;
-		readonly note: "Raw addon vs node zlib baseline. Under Bun the public rust.gzipCompress delegates to Bun.gzipSync (BUN_WINS, ~2x; decompression-parity with the addon \u2014 only the header OS byte differs) \u2014 this row measures the raw addon (src/bench/raw-native.ts).";
-	},
-	{
-		readonly name: "sseEncodeEvent";
-		readonly label: "SSE encode";
-		readonly nativeTask: "native:sse_encode";
-		readonly rustTask: "rust:sse_encode";
-		readonly status: "parity";
-		readonly typicalRatio: 1.1;
-	},
-	{
-		readonly name: "passwordHashBcrypt";
-		readonly label: "Password hash (bcrypt)";
-		readonly nativeTask: "diag:bun_password_bcrypt_hash";
-		readonly rustTask: "diag:bcrypt_hash";
-		readonly status: "parity";
-		readonly note: "Bun.password.bcrypt ~1.24x faster at cost 10 (noisy KDF); rust is self-contained and non-Bun. See docs/bun-builtins-decision-matrix.md.";
-	},
-	{
-		readonly name: "passwordVerifyBcrypt";
-		readonly label: "Password verify (bcrypt)";
-		readonly nativeTask: "diag:bun_password_bcrypt_verify";
-		readonly rustTask: "diag:bcrypt_verify";
-		readonly status: "parity";
-		readonly note: "Rust ~1.49x vs Bun.password.verify at cost 10; KDF timings noisy \u2014 parity for gate stability.";
-	},
-	{
-		readonly name: "pbkdf2Sha256";
-		readonly label: "PBKDF2-HMAC-SHA256";
-		readonly nativeTask: "diag:pbkdf2_sha256";
-		readonly rustTask: "diag:pbkdf2_sha256_rust";
-		readonly status: "parity";
-		readonly note: "~1.08x vs node:crypto pbkdf2Sync at 100k rounds (parity); Bun has no synchronous PBKDF2.";
-	},
-	{
-		readonly name: "jsonParse";
-		readonly label: "JSON parse";
-		readonly nativeTask: "native:json_parse";
-		readonly rustTask: "rust:json_parse";
-		readonly status: "not-competitive";
-		readonly note: "Bun's JSON.parse beats the native DOM + napi marshaling path (~5x).";
-	},
-	{
-		readonly name: "jwtSign";
-		readonly label: "JWT sign";
-		readonly nativeTask: "native:jwt_sign";
-		readonly rustTask: "rust:jwt_sign";
-		readonly status: "not-competitive";
-		readonly note: "Base64 + claims DOM marshal overhead. Use jwtSignBytes (claims as JSON bytes) which skips the napi Value marshal and flips to a ~1.07x win.";
-	},
-	{
-		readonly name: "jwtSignBytes";
-		readonly label: "JWT sign (bytes)";
-		readonly nativeTask: "native:jwt_sign";
-		readonly rustTask: "rust:jwt_sign_bytes";
-		readonly status: "parity";
-		readonly note: "Byte-JSON claims overload avoids the napi serde_json::Value DOM marshal; flips jwtSign from a ~1.3x loss to ~1.07x (parity).";
-	},
-	{
-		readonly name: "brotliCompress";
-		readonly label: "Brotli compress";
-		readonly nativeTask: "native:brotli_compress";
-		readonly rustTask: "rust:brotli_compress";
-		readonly status: "not-competitive";
-		readonly note: "The native brotli baseline wins for small inputs.";
-	},
-	{
-		readonly name: "templateRender";
-		readonly label: "Template render";
-		readonly nativeTask: "native:template_render";
-		readonly rustTask: "rust:template_render";
-		readonly status: "not-competitive";
-		readonly note: "The allocating render marshals the context via napi DOM (~1.5x loss). Use TemplateRenderer.renderBytes (JSON-bytes context) which avoids it and wins ~1.37x.";
-	},
-	{
-		readonly name: "formParsePacked";
-		readonly label: "Form parse";
-		readonly nativeTask: "native:form_parse";
-		readonly rustTask: "rust:form_parse";
-		readonly status: "proven";
-		readonly typicalRatio: 5.8;
-		readonly note: "Benchmarked via the FormParser instance (same parser core).";
-	},
-	{
-		readonly name: "parseMediaType";
-		readonly label: "Media type parse";
-		readonly nativeTask: "native:media_type_parse";
-		readonly rustTask: "rust:media_type_parse";
-		readonly status: "not-competitive";
-		readonly note: "Consistent ~0.71-0.81x (sub-\u00B5s FFI crossing vs the JS baseline); use MediaTypeMatcher (precompiled expected) for the zero-alloc match path.";
-	},
-	{
-		readonly name: "etag";
-		readonly label: "ETag";
-		readonly nativeTask: "native:etag";
-		readonly rustTask: "rust:etag";
-		readonly status: "parity";
-		readonly typicalRatio: 1.06;
-	},
-	{
-		readonly name: "httpDate";
-		readonly label: "HTTP date";
-		readonly nativeTask: "native:http_date";
-		readonly rustTask: "rust:http_date";
-		readonly status: "not-competitive";
-		readonly note: "Delegates to Date.toUTCString() under Bun (BUN_WINS \u2014 ~3.7x faster than the FFI crossing; byte-identical RFC 1123 for HTTP timestamps, incl. leap years/epoch). Rust addon remains the Node path; pooled httpDateInto stays native.";
-	},
-	{
-		readonly name: "createConditionalRequest";
-		readonly label: "Conditional request";
-		readonly nativeTask: "native:conditional";
-		readonly rustTask: "rust:conditional";
-		readonly status: "proven";
-		readonly typicalRatio: 1.4;
-	},
-	{
-		readonly name: "createAcceptNegotiator";
-		readonly label: "Accept-Encoding negotiate";
-		readonly nativeTask: "native:accept_negotiate";
-		readonly rustTask: "rust:accept_negotiate";
-		readonly status: "proven";
-		readonly typicalRatio: 4;
-	},
-	{
-		readonly name: "base64Encode";
-		readonly label: "Base64 encode";
-		readonly nativeTask: "native:base64_encode";
-		readonly rustTask: "rust:base64_encode";
-		readonly status: "not-competitive";
-		readonly note: "Delegates to Buffer base64 under Bun for the standard padded, non-url-safe case (BUN_WINS \u2014 ~2x faster than the FFI crossing); url-safe/unpadded falls through to native. Rust addon remains the Node path. Parity pinned by test/unit/features/encoding.test.ts.";
-	},
-	{
-		readonly name: "base64Decode";
-		readonly label: "Base64 decode";
-		readonly nativeTask: "native:base64_decode";
-		readonly rustTask: "rust:base64_decode";
-		readonly status: "parity";
-		readonly typicalRatio: 1.17;
-	},
-	{
-		readonly name: "hexEncode";
-		readonly label: "Hex encode";
-		readonly nativeTask: "native:hex_encode";
-		readonly rustTask: "rust:hex_encode";
-		readonly status: "not-competitive";
-		readonly note: "Buffer.toString('hex') is native SIMD; pooled hexEncodeInto cuts the loss from ~2.2x to ~1.35x.";
-	},
-	{
-		readonly name: "hexDecode";
-		readonly label: "Hex decode";
-		readonly nativeTask: "native:hex_decode";
-		readonly rustTask: "rust:hex_decode";
-		readonly status: "parity";
-		readonly typicalRatio: 0.78;
-		readonly note: "Slightly slower than Buffer hex decode (~1.3x).";
-	},
-	{
-		readonly name: "signCookie";
-		readonly label: "Cookie sign";
-		readonly nativeTask: "native:cookie_sign";
-		readonly rustTask: "rust:cookie_sign";
-		readonly status: "proven";
-		readonly typicalRatio: 9;
-	},
-	{
-		readonly name: "verifyCookie";
-		readonly label: "Cookie verify";
-		readonly nativeTask: "native:cookie_verify";
-		readonly rustTask: "rust:cookie_verify";
-		readonly status: "proven";
-		readonly typicalRatio: 2.1;
-	},
-	{
-		readonly name: "csrfToken";
-		readonly label: "CSRF create";
-		readonly nativeTask: "native:csrf_create";
-		readonly rustTask: "rust:csrf_create";
-		readonly status: "proven";
-		readonly typicalRatio: 13.8;
-	},
-	{
-		readonly name: "csrfVerify";
-		readonly label: "CSRF verify";
-		readonly nativeTask: "native:csrf_verify";
-		readonly rustTask: "rust:csrf_verify";
-		readonly status: "proven";
-		readonly typicalRatio: 2.7;
-	},
-	{
-		readonly name: "urlResolve";
-		readonly label: "URL resolve";
-		readonly nativeTask: "native:url_resolve";
-		readonly rustTask: "rust:url_resolve";
-		readonly status: "parity";
-		readonly typicalRatio: 1.11;
-		readonly note: "Noisy ~1.5\u00B5s op; swings 0.74-1.03x run-to-run. UrlBuilder reuses the parsed base.";
-	},
-	{
-		readonly name: "urlEncodeQuery";
-		readonly label: "URL query build";
-		readonly nativeTask: "native:url_encode_query";
-		readonly rustTask: "rust:url_encode_query";
-		readonly status: "not-competitive";
-		readonly note: "encodeURIComponent baseline wins (~1.2-1.35x).";
-	},
-	{
-		readonly name: "passwordVerify";
-		readonly label: "Password verify";
-		readonly nativeTask: "";
-		readonly rustTask: "";
-		readonly status: "unmeasured";
-		readonly note: "Depends on the hash cost; no standalone comparison.";
-	},
-	{
-		readonly name: "urlDecodeBytes";
-		readonly label: "URL decode (bytes)";
-		readonly nativeTask: "";
-		readonly rustTask: "";
-		readonly status: "unmeasured";
-	},
-	{
-		readonly name: "configure";
-		readonly label: "configure";
-		readonly nativeTask: "";
-		readonly rustTask: "";
-		readonly status: "unmeasured";
-		readonly note: "Config only.";
-	},
-	{
-		readonly name: "initThreadPool";
-		readonly label: "initThreadPool";
-		readonly nativeTask: "";
-		readonly rustTask: "";
-		readonly status: "unmeasured";
-		readonly note: "Runtime setup only.";
-	},
-	{
-		readonly name: "rayonNumThreads";
-		readonly label: "rayonNumThreads";
-		readonly nativeTask: "";
-		readonly rustTask: "";
-		readonly status: "unmeasured";
-		readonly note: "Introspection only.";
-	}
-];
-/** An entry of the registry with a specific status (type-level). */
-export type ProvenEntryOf<S extends PerformanceStatus> = Extract<(typeof PROVEN_SURFACE)[number], {
-	status: S;
-}>;
-/**
- * The `rust.<name>` keys whose status is "proven" — the only keys exposed on
- * the `proven` surface. Derived from the registry so the type can never drift
- * from the data.
- */
-export type ProvenKey = ProvenEntryOf<"proven">["name"];
-/** Look up the status of a public function by its `rust.<name>` key. */
-export declare function provenStatus(name: string): PerformanceStatus | undefined;
-/** Whether a function is part of the performance-proven surface. */
-export declare function isProven(name: string): boolean;
-/** The entries that are performance-proven (Rust clearly wins). */
-export declare function provenSurface(): ProvenEntry[];
-/** Aggregate summary of the registry (status → count). */
-export declare function provenSummary(): Record<PerformanceStatus, number>;
-/**
- * The performance-annotated client: the full {@link RustClient} surface.
- * Each exported function's JSDoc notes its measured performance vs the JS
- * baseline; functions slower than the baseline carry `@deprecated`.
- */
-export type ProvenClient = RustClient;
-/**
- * The full `rust.*` surface with benchmark-annotated JSDoc. Identical to
- * `rust` — the annotations and `@deprecated` markers are what communicate
- * performance now, not a curated subset.
- */
-export declare const proven: ProvenClient;
-/**
- * Shared TextEncoder instance for encoding strings to UTF-8 bytes.
- *
- * Reusing a single encoder avoids allocation overhead in hot paths.
- */
-export declare const encoder: TextEncoder;
-/**
- * Shared TextDecoder instance for decoding UTF-8 bytes to strings.
- *
- * Reusing a single decoder avoids allocation overhead in hot paths.
- */
-export declare const decoder: TextDecoder;
-export interface AdaptiveEstimateOptions {
-	/**
-	 * EWMA smoothing factor in (0, 1]. Higher reacts faster to new samples;
-	 * lower smooths more. Default: 0.25.
-	 */
-	alpha?: number;
-	/** Starting estimate. Default 0 (the first sample wins). */
-	initial?: number;
-	/** Clamp the estimate to at least this. Default 0. */
-	min?: number;
-	/** Clamp the estimate to at most this (bounds memory / resources). Default Infinity. */
-	max?: number;
-}
-/**
- * A bounded exponential-moving-average estimate of an observed quantity.
- *
- * `sample(x)` folds a new observation into the running estimate; `estimate`
- * reads the current value. The estimate is clamped to `[min, max]`, so it is
- * safe to drive resource sizing (buffer pools, batch thresholds) with it —
- * a single outlier cannot blow up the estimate, and it decays toward recent
- * observations.
- */
-export declare class AdaptiveEstimate {
-	private readonly alpha;
-	private readonly min;
-	private readonly max;
-	private readonly initial;
-	private value;
-	constructor(options?: AdaptiveEstimateOptions);
-	/** Fold a new observation into the running estimate. */
-	sample(x: number): void;
-	/** Current estimate (clamped to `[min, max]`). */
-	get estimate(): number;
-	/** Reset the estimate (back to `initial`). */
-	reset(): void;
-}
-/** Generate a UUIDv7 (time-ordered) string, preferring Bun's native built-in. */
-export declare function uuidv7(): string;
-/** Default histogram buckets (Prometheus-style, seconds). */
-export declare const DEFAULT_BUCKETS: readonly number[];
-export type Labels = Readonly<Record<string, string>>;
-/** A single labelled counter value. */
-export interface Counter {
-	/** Increment by 1 (or `by`). `labels` must match the label names exactly. */
-	inc(labels?: Labels, by?: number): void;
-}
-/** A single labelled gauge value (can go up and down). */
-export interface Gauge {
-	inc(labels?: Labels, by?: number): void;
-	dec(labels?: Labels, by?: number): void;
-	set(labels: Labels | undefined, value: number): void;
-}
-/** A single labelled histogram. */
-export interface Histogram {
-	/** Record one observation. `labels` must match the label names exactly. */
-	observe(value: number, labels?: Labels): void;
-}
-/** The metrics registry factory. */
-export interface MetricsRegistry {
-	/** Create (or fetch) a counter. `help` is only used on first creation. */
-	counter(name: string, help: string, labelNames?: readonly string[]): Counter;
-	/** Create (or fetch) a gauge. */
-	gauge(name: string, help: string, labelNames?: readonly string[]): Gauge;
-	/**
-	 * Create (or fetch) a histogram. `buckets`/`help` only apply on first
-	 * creation; later calls with the same name return the existing histogram.
-	 */
-	histogram(name: string, help: string, buckets?: readonly number[], labelNames?: readonly string[]): Histogram;
-	/** Render the Prometheus text exposition format. */
-	render(): string;
-	/** Reset all metrics (for tests / interval rotation). */
-	reset(): void;
-}
-/** Create a fresh metrics registry. */
-export declare function createMetrics(): MetricsRegistry;
-/** User-facing CORS configuration. */
-export interface CorsOptions {
-	allowOrigin?: string[];
-	allowMethods?: string[];
-	allowHeaders?: string[];
-	exposeHeaders?: string[];
-	allowCredentials?: boolean;
-	maxAge?: number;
-}
-/** Precomputed, immutable CORS policy strings. */
-export interface CorsStaticStrings {
-	readonly allowMethodsJoined: string;
-	readonly allowHeadersJoined: string;
-	readonly exposeHeadersJoined: string;
-	readonly maxAgeString: string | null;
-	readonly isWildcard: boolean;
-	readonly credentials: boolean;
-}
-/** User-facing security-headers configuration. */
-export interface SecurityHeadersOptions {
-	contentSecurityPolicy?: string;
-	hsts?: boolean;
-	hstsMaxAge?: number;
-	hstsIncludeSubdomains?: boolean;
-	hstsPreload?: boolean;
-	frameOptions?: string;
-	nosniff?: boolean;
-	referrerPolicy?: string;
-	coep?: string;
-	coop?: string;
-	corp?: string;
-	xssProtection?: string;
-}
-/** Bounds-checked section offsets for one ingress output buffer. */
-export interface PackedSectionLayout {
-	/** Cookie-JSON length clamped to the buffer (0 if none / out of range). */
-	safeCookiesLen: number;
-	/** Byte offset where the query-JSON section begins. */
-	queryStart: number;
-	/** Query-JSON length clamped to the buffer (0 if none / out of range). */
-	safeQueryLen: number;
-	/** Byte offset where the body-JSON section begins. */
-	bodyJsonStart: number;
-	/** Body-JSON length clamped to the buffer (0 if none / out of range). */
-	safeBodyJsonLen: number;
-	/** Whether any declared section length overran the buffer. */
-	truncated: boolean;
-}
-declare abstract class IngressResultBase {
-	/** Raw native verdict byte (0 = accepted). */
-	verdict: number;
-	/** Raw native error-code byte. */
-	errorCode: number;
-	/** Normalized HTTP status. */
-	status: number;
-	/** Header template variant byte emitted by the native core. */
-	headerVariant: number;
-	/** Remaining rate-limit budget (count). */
-	rateRemaining: number;
-	/** Rate-limit window reset (ms epoch). */
-	rateResetMs: number;
-	/** Retry-After value (ms). */
-	retryAfterMs: number;
-	/** True when the pipeline returned a terminal (error) verdict. */
-	terminal: boolean;
-	/** True when the pipeline accepted the request (verdict 0 + 2xx/3xx). */
-	ok: boolean;
-	/** True when the request was a CORS preflight. */
-	isPreflight: boolean;
-	/** True when the CORS engine allowed the request origin. */
-	corsAllowed: boolean;
-	/** True when the request was rate-limited. */
-	rateLimited: boolean;
-	/** True when the request came from a trusted proxy. */
-	trustedProxy: boolean;
-	/** True when the request body parsed as valid JSON. */
-	bodyValidJson: boolean;
-	/** True when the request body validated against the ingress schema. */
-	schemaValid: boolean;
-	/** True when a declared output section overran the buffer. */
-	bodyTruncated: boolean;
-	/** Request body bytes (may be an empty view). */
-	body: Uint8Array;
-	protected _buf: Uint8Array;
-	protected _bodyJsonStart: number;
-	protected _bodyJsonLen: number;
-	private _cookiesBuf;
-	private _queryBuf;
-	private _cookiesDecoded;
-	private _queryDecoded;
-	/** Reset the shared fields to their empty state (call from subclass `invalidate`). */
-	protected resetShared(): void;
-	/** Recompute `terminal`/`ok` from the (subclass-set) verdict + status. */
-	protected updateOkTerminal(): void;
-	/**
-	 * Store the rate-limit window fields. Both decoders read the same OUT_*
-	 * slots and gate them on the same conditions (a positive budget OR the
-	 * rate-limited flag), so the read cannot drift between paths.
-	 */
-	protected setRateWindow(rateLimit: number, rateLimited: boolean, view: DataView): void;
-	/**
-	 * Store the bounds-checked cookie/query/body JSON sections from `layout`.
-	 *
-	 * `bodyJsonLen` is the body-JSON length to trust for `bodyJson()`: the fast
-	 * path passes the RAW declared length (it re-checks bounds on read), the
-	 * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
-	 * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
-	 */
-	protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void;
-	/** Decoded cookies-JSON section, or `"{}"` when absent. */
-	cookiesJson(): string;
-	/** Decoded query-JSON section, or `"{}"` when absent. */
-	queryJson(): string;
-	/** Bounds-checked body-JSON slice (empty when absent / out of range). */
-	protected bodyJsonSlice(): Uint8Array;
-}
-/** Zero-alloc, lazy-decoding view over a native Ingress output buffer. */
-export declare class FastIngressResult extends IngressResultBase {
-	status: number;
-	verdict: number;
-	errorCode: number;
-	flags: number;
-	https: boolean;
-	hasCookies: boolean;
-	hasQuery: boolean;
-	rateLimit: number;
-	requestId: string;
-	refresh(buf: Uint8Array, body: Uint8Array, requestId: string): void;
-	invalidate(): void;
-	setInternalError(requestId: string): void;
-	/** Bounds-checked body-JSON section, or an empty view when absent. */
-	bodyJson(): Uint8Array;
-}
-/** Options accepted by `createIngressFast` / `createIngress`. */
-export interface IngressFastOptions {
-	trustProxy?: boolean;
-	trustedProxies?: {
-		enabled?: boolean;
-		networks?: string[];
-	};
-	parseCookies?: boolean;
-	parseQuery?: boolean;
-	requireJsonBody?: boolean;
-	schema?: Uint8Array;
-	cors?: CorsOptions;
-	rateLimit?: {
-		limit?: number;
-		windowMs?: number;
-		maxEntries?: number;
-	};
+	urlEncode(input: string): string;
 	/**
-	 * Structured security-header options (CSP/HSTS) — honored by the fast/async
-	 * paths (`createIngressFast` throws on it; `createIngress` applies it via
-	 * `buildResponseContext`). The PRE-BAKED path (`createIngressHandler`)
-	 * instead takes raw `securityHeaders: [name, value][]` pairs. The two paths
-	 * intentionally use different option shapes (see docs/INGRESS.md).
+	 * Percent-decode a string. Throws on malformed `%XX` or invalid UTF-8
+	 * output (parity with `decodeURIComponent`, which is used under Bun).
+	 * @param input the percent-encoded string to decode.
+	 * @returns the decoded string.
 	 */
-	security?: SecurityHeadersOptions;
-	https?: boolean;
-	maxBodyBytes?: number;
-	enableSecurityHeaders?: boolean;
-	enableRequestIds?: boolean;
-	enableBodySizeGuard?: boolean;
-	emitMetadataJson?: boolean;
-	readBody?: boolean;
-	outputBufferSize?: number;
+	urlDecode(input: string): string;
 	/**
-	 * Overall deadline (ms) for reading a request body in the async
-	 * `createIngress` path. 0 disables. Default: `DEFAULT_BODY_TIMEOUT_MS` (30s).
-	 * Ignored by the sync `createIngressFast` (it does not read bodies).
+	 * Compute the RFC 6455 `Sec-WebSocket-Accept` value for a client key.
+	 * @param key the base64 `Sec-WebSocket-Key` header value.
+	 * @returns the 28-byte base64 accept value.
 	 */
-	bodyTimeoutMs?: number;
+	wsAcceptKey(key: string): string;
+	/** @param input an email address. @returns whether it is RFC-valid. */
+	validateEmail(input: string): boolean;
+	/** @param input a UUID string. @returns whether it is a valid (v1-v8) UUID. */
+	validateUuid(input: string): boolean;
+	/** @param input an IPv4 address. @returns whether it is valid. */
+	validateIpv4(input: string): boolean;
+	/** @param input an IPv6 address. @returns whether it is valid. */
+	validateIpv6(input: string): boolean;
+}
+/** The full Rust FFI client (scalar methods + namespaces + configuration). */
+export interface RustClient extends RustScalar {
+	text: RustText;
+	batch: RustBatch;
+	packed: RustPacked;
 	/**
-	 * Invoked when the native pipeline throws (the request becomes a 500).
-	 * Native failures are otherwise silent in the fast path. Never throws.
+	 * Resolve the native transport in use on this runtime: `"ffi"` (bun:ffi —
+	 * the PRIMARY transport under Bun) or `"napi"` (Node, forced
+	 * `CASTRUM_FFI_MODE=napi`, or a failed ffi bind-time self-test).
 	 */
-	onError?: (error: Error) => void;
+	transport(): "ffi" | "napi";
+	/** Whether the bun:ffi transport is live (equivalent to `transport() === "ffi"`). */
+	ffiActive(): boolean;
 	/**
-	 * When true, run one probe GET at construction so the `run()` closure,
-	 * packed pipeline and FFI ingress call are JIT-warmed before the first real
-	 * request (cuts cold-invocation tail latency in serverless-style
-	 * deployments). Opt-in; default false. Not forwarded to the native addon.
+	 * Update defaults on this instance. `mimeCache` / `hmacCache` apply
+	 * immediately (per-instance). `rayonThreads` is applied only if the
+	 * process-wide pool is not yet initialized (see {@link RustOptions}).
 	 */
-	warmOnCreate?: boolean;
-	limits?: {
-		maxUrlBytes?: number;
-		maxQueryBytes?: number;
-		maxCookieBytes?: number;
-		maxHeadersBytes?: number;
-		maxHeaders?: number;
-		maxPairs?: number;
-	};
-}
-/** The zero-alloc sync handler returned by `createIngressFast`. */
-export interface IngressFastHandler {
-	run<T>(req: Request, ip: string | undefined, body: Uint8Array | null, requestId: string, fn: (result: FastIngressResult) => T): T;
+	configure(options: RustOptions): void;
 }
 /**
- * Options accepted by `createIngressHandler` (path 2).
+ * Create an isolated Rust client with the given defaults.
  *
- * Same native option surface as the fast path, minus `onError` — path 2
- * reports native failures through `BakedIngressRuntime.onError` instead of the
- * options bag.
+ * `mimeCache` / `hmacCache` are per-instance. `rayonThreads` only applies
+ * before the process-wide rayon pool is initialized (once per process — see
+ * {@link RustOptions.rayonThreads}); the pool defaults to the env var or
+ * `max(1, hardwareConcurrency - 1)` otherwise.
  */
-export type IngressHandlerOptions = Omit<IngressFastOptions, "onError">;
-/** Zero-alloc, reusable result decoder for the pre-baked handler path. */
-export declare class BakedIngressResult extends IngressResultBase {
-	refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void;
-	invalidate(): void;
-	setInternalError(): void;
-	bodyJson(copy: boolean): Uint8Array;
+export declare function createRust(options?: RustOptions): RustClient;
+/**
+ * The default, ready-to-use `RustClient` created with no options (resolves
+ * rayon threads from the host automatically). Most consumers just do
+ * `import { rust } from "castrum"` and call `rust.<fn>(...)` directly.
+ */
+export declare const rust: RustClient;
+/** The benchmark-proven default implementation for an op. */
+export type ProvenImpl = "native" | "js" | "bun";
+/** How decisive the baked winner is. */
+export type ProvenStatus = "proven" | "parity" | "unmeasured";
+/** One entry in the baked proven-selection registry. */
+export interface ProvenEntry {
+	/** Selection op name (matches `opImpl(op)` / `src/selection.json` keys). */
+	name: string;
+	/** The baked default implementation: the benchmark-proven winner. */
+	impl: ProvenImpl;
+	/** `proven` = decisive win, `parity` = borderline, `unmeasured` = pinned by policy. */
+	status: ProvenStatus;
+	/** Measured ratio behind the decision (see module doc for the axis). */
+	typicalRatio?: number;
+	/** Why this classification. */
+	note?: string;
 }
-/** Public ingress options (extends the fast-path options). */
-export interface IngressOptions extends IngressFastOptions {
-	enableRequestIds?: boolean;
-	/**
-	 * Invoked before a request is processed (for tracing/context hooks).
-	 * Only used by the async `createIngress` path.
-	 */
-	onRequest?: (req: Request, requestId: string, ip: string | undefined) => void;
+/**
+ * Baked proven-winner registry. Covering the FULL selection surface
+ * (`src/selection.json` ops + every Bun built-in delegation) so nothing can be
+ * silently dropped. Classifications are based on release/perf-build results;
+ * `test/unit/shared/proven.test.ts` re-checks them against the LIVE wiring.
+ */
+export declare const PROVEN_SELECTION: readonly ProvenEntry[];
+/**
+ * The baked {@link ProvenEntry} for `op`, or `undefined` for unknown ops.
+ * Pure data — never dlopens the addon.
+ */
+export declare function provenEntry(op: string): ProvenEntry | undefined;
+/** The baked default implementation for `op` (`native` / `js` / `bun`), or `null`. */
+export declare function provenImpl(op: string): ProvenImpl | null;
+/** The baked status for `op`, or `null` for unknown ops. */
+export declare function provenStatus(op: string): ProvenStatus | null;
+/** Whether the op's baked winner is a decisive (`proven`) win. */
+export declare function isProven(op: string): boolean;
+/** The full baked registry (same array as {@link PROVEN_SELECTION}). */
+export declare function provenSurface(): readonly ProvenEntry[];
+/** A one-line summary of the baked selection (counts per implementation). */
+export declare function provenSummary(): string;
+/** The full `rust.*` surface — identical to `rust`; the proven wiring is baked (see {@link ../shared/proven}). */
+export type ProvenClient = RustClient;
+/** The full `rust.*` surface, exposed for audit. Same object as `rust`. */
+export declare const proven: ProvenClient;
+/** Recommended implementation for an operation. */
+export type OpImpl = "native" | "js";
+/** A selection decision: recommended implementation + rationale note. */
+export interface OpDecision {
+	/** The recommended implementation when the addon is available. */
+	readonly impl: OpImpl;
+	/** Why this decision (measured ratio / rationale). */
+	readonly note?: string;
+}
+/**
+ * The benchmark-driven native-vs-JS decision for `op` — runtime-aware.
+ *
+ * Returns `"native"` when the Rust addon is the recommended implementation,
+ * `"js"` when a pure-JS (or Bun built-in) implementation wins, or `null` for
+ * unknown ops (or when the addon is unavailable — with no addon there is no
+ * "native" choice). Under Bun, ops in the adapter's builtins registry resolve
+ * to `"js"` so the consumer's JS path delegates to the faster Bun built-in.
+ *
+ * The default is the BAKED proven selection (`src/shared/proven.ts`):
+ * `native` / `js` directly, `bun` resolves to `"js"` via the builtins check
+ * above. Unknown ops (and `bun` entries on a non-Bun runtime, where no
+ * built-in exists) fall back to the addon's embedded decision
+ * (`rust/selection.rs` ← `src/selection.json`).
+ */
+export declare const opImpl: (op: string) => OpImpl | null;
+/** `true` when the Rust addon is the recommended impl for `op`. */
+export declare const isNativeOp: (op: string) => boolean;
+/** The decision record for `op`, or `null` when unknown. */
+export declare const opDecision: (op: string) => OpDecision | null;
+/**
+ * Shared UTF-8 encoder (encode / encodeInto), backed by the runtime-native
+ * codec (`src/shared/codec.ts`): on Bun the work is done by Bun's native
+ * transfer machinery (`Bun.ArrayBufferSink` / a zero-copy `Buffer` view
+ * write); under Node it falls back to `TextEncoder`. Reusing a single object
+ * avoids allocation overhead in hot paths.
+ *
+ * `encode` accepts the string-or-bytes union the text-returning `rust.*` ops
+ * surface (Bun returns strings, Node returns bytes) and normalizes to bytes —
+ * a string is UTF-8 encoded, bytes pass through unchanged.
+ */
+export declare const encoder: {
+	encode(s: Uint8Array | string): Uint8Array;
+	encodeInto(s: string, dest: Uint8Array): {
+		read: number;
+		written: number;
+	};
+};
+/**
+ * Shared UTF-8 decoder, backed by the runtime-native codec
+ * (`src/shared/codec.ts`): on Bun it uses `new CString(ptr, 0, len)` from
+ * `bun:ffi` (JSC-native, exact-length clone); under Node it falls back to
+ * `TextDecoder`. Reusing a single object avoids allocation overhead in hot
+ * paths.
+ *
+ * `decode` accepts the string-or-bytes union the text-returning `rust.*` ops
+ * surface and normalizes to a string — bytes are UTF-8 decoded, strings pass
+ * through unchanged.
+ */
+export declare const decoder: {
+	decode(bytes: Uint8Array | string): string;
+};
+/** Options for an `AdaptiveEstimate`: EWMA smoothing, bounds, starting value. */ export interface AdaptiveEstimateOptions {
 	/**
-	 * Invoked after a terminal context (and its `Response`) is produced, for
-	 * metrics/logging hooks. Only used by the async `createIngress` path.
+	 * EWMA smoothing factor in (0, 1]. Higher reacts faster to new samples;
+	 * lower smooths more. Default: 0.25.
 	 */
-	onResponse?: (req: Request, result: IngressContext, status: number, requestId: string) => void;
+	alpha?: number;
+	/** Starting estimate. Default 0 (the first sample wins). */
+	initial?: number;
+	/** Clamp the estimate to at least this. Default 0. */
+	min?: number;
+	/** Clamp the estimate to at most this (bounds memory / resources). Default Infinity. */
+	max?: number;
 }
 /**
- * Readonly structural view of a decoded ingress result.
+ * A bounded exponential-moving-average estimate of an observed quantity.
  *
- * Note: the exported `FastIngressResult` class is the zero-alloc implementation;
- * this interface is the readonly view used by the public sync/async handlers.
+ * `sample(x)` folds a new observation into the running estimate; `estimate`
+ * reads the current value. The estimate is clamped to `[min, max]`, so it is
+ * safe to drive resource sizing (buffer pools, batch thresholds) with it —
+ * a single outlier cannot blow up the estimate, and it decays toward recent
+ * observations.
  */
-export interface IngressResult {
-	readonly status: number;
-	readonly verdict: number;
-	readonly flags: number;
-	readonly errorCode: number;
-	readonly terminal: boolean;
-	readonly ok: boolean;
-	readonly https: boolean;
-	readonly trustedProxy: boolean;
-	readonly hasCookies: boolean;
-	readonly hasQuery: boolean;
-	readonly bodyValidJson: boolean;
-	readonly schemaValid: boolean;
-	readonly corsAllowed: boolean;
-	readonly isPreflight: boolean;
-	readonly rateLimited: boolean;
-	readonly rateLimit: number;
-	readonly rateRemaining: number;
-	readonly rateResetMs: number;
-	readonly retryAfterMs: number;
-	readonly body: Uint8Array;
-	readonly headerVariant: number;
-	readonly requestId: string;
-	readonly bodyTruncated: boolean;
-	cookiesJson(): string;
-	queryJson(): string;
-	bodyJson(): Uint8Array;
-}
-/** A result plus the terminal Response computed for it. */
-export interface IngressContext extends IngressResult {
-	response: Response | null;
+export declare class AdaptiveEstimate {
+	private readonly alpha;
+	private readonly min;
+	private readonly max;
+	private readonly initial;
+	private value;
+	constructor(options?: AdaptiveEstimateOptions);
+	/** Fold a new observation into the running estimate. */
+	sample(x: number): void;
+	/** Current estimate (clamped to `[min, max]`). */
+	get estimate(): number;
+	/** Reset the estimate (back to `initial`). */
+	reset(): void;
 }
 /**
- * Synchronous ingress handler.
+ * Generate a UUIDv7 (time-ordered) string, preferring Bun's native built-in.
+ * Under Node this falls back to `crypto.randomUUID` (v4).
  *
- * The callback runs on the zero-alloc result object and MUST be synchronous:
- * returning a Promise (or any thenable) throws. The result is invalidated after
- * `run()` returns, so capture the fields you need inside the callback (or use
- * the async {@link IngressHandler} which snapshots for you).
+ * @returns A UUID string.
  */
-export interface SyncIngressHandler {
-	run<T>(req: Request, ip: string | undefined, body: Uint8Array | null, requestId: string, fn: (result: IngressResult) => T): T;
+export declare const uuidv7: () => string;
+/** Default histogram buckets (Prometheus-style, seconds). */
+export declare const DEFAULT_BUCKETS: readonly number[];
+export type Labels = Readonly<Record<string, string>>;
+/** A single labelled counter value. */
+export interface Counter {
+	/** Increment by 1 (or `by`). `labels` must match the label names exactly. */
+	inc(labels?: Labels, by?: number): void;
 }
-/** Async ingress handler (wraps {@link SyncIngressHandler} with body reading). */
-export type IngressHandler = (req: Request, ip?: string) => Promise<IngressContext>;
-/** Mutable per-request context threaded through the pre-baked handler run. */
-export interface BakedContext {
-	/** The request-id string (null when `emitRequestIdHeader` is off). */
-	requestIdHeader: string | null;
-	/** The `Origin` request header when CORS extraction is enabled. */
-	origin: string | null;
+/** A single labelled gauge value (can go up and down). */
+export interface Gauge {
+	inc(labels?: Labels, by?: number): void;
+	dec(labels?: Labels, by?: number): void;
+	set(labels: Labels | undefined, value: number): void;
 }
-/**
- * An optimized ingress handler. `run()` is the zero-alloc pipeline entry
- * point; the response-builder methods are pre-baked and bound to this
- * handler's configuration, so consumers can build custom routes without
- * touching header templates or error bodies.
- */
-export interface OptimizedIngressHandler {
-	run<T>(req: Request, ip: string | undefined, body: Uint8Array | null, fn: (result: BakedIngressResult, ctx: BakedContext) => T): T;
-	responseHeaders(variant: number, requestIdHeader: string | null, origin: string | null, rateRemaining?: number, rateResetSecs?: number, retryAfterSecs?: number): [
-		string,
-		string
-	][];
-	terminalHeaders(variant: number, ctx: BakedContext, result: BakedIngressResult | null): [
-		string,
-		string
-	][];
-	/** `req` is accepted for back-compat but unused by the baked terminal path. */
-	terminalResponse(req: Request | undefined, result: BakedIngressResult, ctx: BakedContext): Response | null;
-	/** `req` is accepted for back-compat but unused by the baked error path. */
-	errorResponse(req: Request | undefined, result: BakedIngressResult | null, status: number, code: string, message: string, ctx: BakedContext): Response;
-	internalErrorResponse(ctx: BakedContext, result?: BakedIngressResult): Response;
-	withContentType(headers: ReadonlyArray<[
-		string,
-		string
-	]>, contentType: string): [
-		string,
-		string
-	][];
+/** A single labelled histogram. */
+export interface Histogram {
+	/** Record one observation. `labels` must match the label names exactly. */
+	observe(value: number, labels?: Labels): void;
+}
+/** The metrics registry factory. */
+export interface MetricsRegistry {
+	/** Create (or fetch) a counter. `help` is only used on first creation. */
+	counter(name: string, help: string, labelNames?: readonly string[]): Counter;
+	/** Create (or fetch) a gauge. */
+	gauge(name: string, help: string, labelNames?: readonly string[]): Gauge;
 	/**
-	 * Build a zero-copy `Response` whose body is the request's pooled output
-	 * slice. The pooled buffer is returned to its pool once the body has been
-	 * consumed (stream closed) or the request aborted. Use when `copyBody` is
-	 * `false`; otherwise a copied body is released eagerly at the end of `run()`.
+	 * Create (or fetch) a histogram. `buckets`/`help` only apply on first
+	 * creation; later calls with the same name return the existing histogram.
 	 */
-	zeroCopyResponse(result: BakedIngressResult, ctx: BakedContext, init: ResponseInit): Response;
+	histogram(name: string, help: string, buckets?: readonly number[], labelNames?: readonly string[]): Histogram;
+	/** Render the Prometheus text exposition format. */
+	render(): string;
+	/** Reset all metrics (for tests / interval rotation). */
+	reset(): void;
+}
+/** Create a fresh metrics registry. */
+export declare function createMetrics(): MetricsRegistry;
+/**
+ * Create the runtime-appropriate ingress server: `Bun.serve` on Bun, the
+ * `node:http` adapter on Node. Selected ONCE at module load — the branch
+ * never runs in the hot path.
+ */
+export declare function createIngressServer(options: CreateIngressServerOptions): BakedServer;
+/**
+ * Generate the next request ID as 16 lowercase hex bytes (zero-alloc).
+ *
+ * @returns A shared buffer aliased across calls — decode/copy before the next
+ *   `generateRequestId()` invocation.
+ */
+export declare function generateRequestId(): Uint8Array;
+/** A parsed W3C trace context (valid per the spec's length/hex rules). */
+export interface TraceContext {
+	/** Version, always `"00"` for accepted headers. */
+	version: string;
+	/** 32 hex chars — the trace id (shared across the whole trace). */
+	traceId: string;
+	/** 16 hex chars — the current span id. */
+	spanId: string;
+	/** The flags byte (bit 0 = sampled). */
+	flags: number;
+	/** True when the `sampled` (bit 0) flag is set. */
+	sampled: boolean;
 }
+/**
+ * Parse a `traceparent` header value into a {@link TraceContext}, or `null`
+ * when malformed (wrong version / length / non-hex). Invalid contexts are
+ * ignored per the spec — callers should generate a fresh trace then.
+ */
+export declare function parseTraceParent(header: string | null | undefined): TraceContext | null;
+/** Random 32-hex trace id (crypto-backed where available). */
+export declare function createTraceId(): string;
+/** Random 16-hex span id. */
+export declare function createSpanId(): string;
+/** Serialize a trace context back to a `traceparent` header value. */
+export declare function serializeTraceParent(ctx: TraceContext): string;
 /** Offset of the verdict byte (0 = accepted, nonzero = terminal error). */
 export declare const OUT_VERDICT: number;
 /** Offset of the error-code byte (see ERR_CODE_* below). */
@@ -1873,6 +1544,86 @@ export declare const ERR_CODE_INTERNAL: number;
  * numeric layout values come from the addon; this one is a JS-level error).
  */
 export declare const ERR_CODE_REQUEST_TIMEOUT: number;
+/** Map a native error code to its stable string name. */
+export declare function errorCodeName(code: number): string;
+/** Map a native error code (plus status context) to a human message. */
+export declare function errorMessage(status: number, code: number): string;
+/** A single precomputed header-variant template. */
+export interface HeaderTemplate {
+	readonly entries: ReadonlyArray<readonly [
+		string,
+		string
+	]>;
+	readonly needsOriginEcho: boolean;
+	readonly needsRateDynamic: boolean;
+	readonly needsRetryAfter: boolean;
+	readonly needsDynamicHsts: boolean;
+}
+/** Precomputed per-handler response context. */
+export interface ResponseBuildContext {
+	readonly templates: HeaderTemplate[];
+	readonly corsStatic: CorsStaticStrings | null;
+	readonly hstsValue: string | null;
+}
+/**
+ * Build the full response context (header templates + static CORS strings +
+ * HSTS value) for a handler configuration.
+ */
+export declare function buildResponseContext(options: {
+	cors?: CorsOptions;
+	security?: SecurityHeadersOptions;
+	https?: boolean;
+	enableSecurityHeaders?: boolean;
+	rateLimit?: {
+		limit?: number;
+	};
+}): ResponseBuildContext;
+/**
+ * Build the response headers for a decoded result, applying the dynamic parts
+ * (request-id, origin echo, rate-limit counters, retry-after, dynamic HSTS).
+ */
+export declare function headersForResult(ctx: ResponseBuildContext, r: {
+	readonly headerVariant: number;
+	readonly corsAllowed: boolean;
+	readonly rateRemaining: number;
+	readonly rateResetMs: number;
+	readonly retryAfterMs: number;
+	readonly https: boolean;
+}, req: Request, requestId: string): Headers;
+/**
+ * Build a terminal response for a result, or `null` when the result is not
+ * terminal (the caller should serve the body instead).
+ */
+export declare function buildTerminalResponse(ctx: ResponseBuildContext, r: {
+	readonly terminal: boolean;
+	readonly isPreflight: boolean;
+	readonly corsAllowed: boolean;
+	readonly errorCode: number;
+	readonly status: number;
+	readonly headerVariant: number;
+	readonly https: boolean;
+	readonly rateLimit: number;
+	readonly rateRemaining: number;
+	readonly rateResetMs: number;
+	readonly retryAfterMs: number;
+}, req: Request, requestId: string): Response | null;
+/** Default maximum request body size in bytes. */
+export declare const DEFAULT_MAX_BODY_BYTES = 1048576;
+/**
+ * Default overall deadline (ms) for reading a request body. Non-zero so the
+ * async `createIngress` / route handlers are protected against slowloris and
+ * trickling bodies by default. Set `bodyTimeoutMs: 0` to disable.
+ */
+export declare const DEFAULT_BODY_TIMEOUT_MS = 30000;
+/** Maps HTTP methods to the native Ingress method-kind enum. */
+export declare const METHOD_KIND: Record<string, number>;
+/** Which request headers to extract into the packed input. */
+export interface HeaderPlan {
+	cookie: boolean;
+	cors: boolean;
+	proxy: boolean;
+	proto: boolean;
+}
 /**
  * Whether a raw status is a legal HTTP response status for the ingress
  * pipeline (101 switch-protocol or any 2xx–5xx).
@@ -1898,10 +1649,18 @@ export declare function safeTerminalStatus(r: {
 	readonly isPreflight: boolean;
 	readonly corsAllowed: boolean;
 }): number;
-/** Map a native error code to its stable string name. */
-export declare function errorCodeName(code: number): string;
-/** Map a native error code (plus status context) to a human message. */
-export declare function errorMessage(status: number, code: number): string;
+/**
+ * Create a fast packed-input ingress handler (path 1).
+ *
+ * JS packs the request headers into a binary buffer (`IngressInputPacker`) and
+ * the native `Ingress.handleRequestPacked` decodes them. Responses use the
+ * `{"error":{...}}` wire format with `x-ratelimit-*` headers.
+ *
+ * Prefer this when you want the lowest-overhead pipeline and will call `run()`
+ * yourself with a **synchronous** callback. For ready-made route handlers and a
+ * server builder, use `createIngressHandler` (path 2).
+ */
+export declare function createIngressFast(options?: IngressFastOptions): IngressFastHandler;
 declare function createStructuredLogger(stream?: Pick<NodeJS.WritableStream, "write">, env?: NodeJS.ProcessEnv): {
 	/** Record one completed request. */
 	request(info: {
@@ -1922,172 +1681,67 @@ declare function createStructuredLogger(stream?: Pick<NodeJS.WritableStream, "wr
 };
 /** Pre-encoded static error bodies, keyed by error-code string name. */
 export declare const ERROR_BODIES: Record<string, Uint8Array>;
-/** Options accepted by the pre-baked route factories. */
-export interface BakedHandlerOptions {
-	/** Resolve the client IP from the server object (e.g. `srv.requestIP`). */
-	getIp?: (req: Request, srv: unknown) => string | undefined;
-	/** Copy body slices instead of sharing the native buffer. Default: true (safe). */
-	copyBody?: boolean;
-	/** Maximum request body bytes for write/echo handlers. Default: 1 MiB. */
-	maxBodyBytes?: number;
-	/**
-	 * Overall deadline (ms) for reading the request body. Default: 30s
-	 * (`DEFAULT_BODY_TIMEOUT_MS`). Set `0` to disable. Protects against
-	 * slowloris / trickling bodies.
-	 */
-	bodyTimeoutMs?: number;
-	/** Fallback handler used for write error paths. Defaults to the write ingress. */
-	fallback?: OptimizedIngressHandler;
-	/**
-	 * When true, route the JSON-validity fallback check through the higher-order
-	 * loader (`loader("jsonValid")`) instead of the direct native call —
-	 * exercising the loader's dispatch + counters on the real request path.
-	 * Default: false (the direct call is marginally faster for a single request;
-	 * the loader pays off for same-tick bursts / bulk work, see src/integration/batch.ts).
-	 */
-	enableLoader?: boolean;
-}
 /**
  * Pre-baked GET read handler: returns the ingress body JSON on success.
  */
 export declare function readHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Response;
 /**
- * Pre-baked HEAD read handler: headers only, no body.
- */
-export declare function headHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Response;
-/**
- * Pre-baked JSON-write handler (POST/PUT/PATCH): enforces Content-Type,
- * content-length/body-size limits, JSON validity and (optionally) schema
- * validation, then returns the ingress body JSON on success.
+ * Pre-baked DELETE handler: DELETE is a read-style method (no request body is
+ * read), so it shares the exact pipeline flow of {@link readHandler} — it
+ * returns the ingress body JSON on success and the terminal/error responses
+ * otherwise. Reusing the read factory keeps the two handlers byte-identical
+ * and avoids a copy-pasted variant.
+ *
+ * Wire it via the `delete` key of a `BakedRoute` (see `createIngressServer`).
  */
-export declare function jsonWriteHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Promise<Response>;
+export declare const deleteHandler: typeof readHandler;
 /**
  * Pre-baked echo handler: streams the request body back with the client's
  * Content-Type, bounded by `maxBodyBytes`.
  */
-export declare function echoHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Promise<Response>;
-/**
- * Pre-baked fallback handler: 404 for unmatched routes / OPTIONS.
- */
-export declare function fallbackHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Response;
-/** A raw web-standard route handler (`Request` → `Response`), e.g. the
- *  health/metrics probes (`livenessHandler`, `readinessHandler`,
- *  `healthHandler`, `metricsHandler`). Accepted as `BakedRoute.read` and
- *  served for GET directly, outside the ingress pipeline. The optional third
- *  arg carries the matched dynamic path params (`:param`/`*`) on the Node
- *  adapter (Bun's native router handles matching; the ingress pipeline does
- *  not echo params in its response). */
-type RouteHandler = (req: Request, srv?: unknown, params?: Record<string, string>) => Response | Promise<Response>;
-/** Route spec for the Bun.serve builder. */
-export interface BakedRoute {
-	/**
-	 * Wires GET + HEAD read handlers. Accepts an optimized ingress handler OR a
-	 * raw `RouteHandler` function (health/metrics probes are raw — see
-	 * src/ingress/health.ts). A raw handler is served for GET only.
-	 */
-	read?: OptimizedIngressHandler | RouteHandler;
-	/** Wires POST/PUT/PATCH JSON-write handlers (and OPTIONS fallback). */
-	write?: OptimizedIngressHandler;
-	/** Wires a POST echo handler. */
-	echo?: OptimizedIngressHandler;
-	/** Wires a GET read handler (cookies-style route). */
-	cookies?: OptimizedIngressHandler;
-	/** Wires a DELETE read-style handler. */
-	delete?: OptimizedIngressHandler;
-	/** Overrides `maxBodyBytes` for this route's write/echo handlers. */
-	maxBodyBytes?: number;
-	/**
-	 * Overall deadline (ms) for reading the request body on this route's
-	 * write/echo handlers. Default: 30_000 (`DEFAULT_BODY_TIMEOUT_MS`).
-	 * Set 0 to disable.
-	 */
-	bodyTimeoutMs?: number;
-}
-/** RFC 6455 handshake values returned by `CreateIngressServerOptions.upgrade`. */
-export interface NodeUpgradeHandshake {
-	/** `Sec-WebSocket-Accept` value (compute via `rust.text.wsAcceptKey`). */
-	accept: string;
-	/** Optional negotiated subprotocol (`Sec-WebSocket-Protocol`). */
-	protocol?: string;
-}
-/** Options for {@link createIngressServer}. */
-export interface CreateIngressServerOptions {
-	port: number;
-	hostname?: string;
-	idleTimeout?: number;
-	maxRequestBodySize?: number;
-	reusePort?: boolean;
-	copyBody?: boolean;
-	getIp?: (req: Request, srv: unknown) => string | undefined;
-	routes: Record<string, BakedRoute>;
-	fallback?: OptimizedIngressHandler;
-	/**
-	 * Invoked when an unhandled error escapes a request handler (currently wired
-	 * on the Node adapter; the Bun path uses runtime.onResponse). Never throws —
-	 * hook failures are swallowed.
-	 */
-	onError?: (info: {
-		error: Error;
-		request?: Request;
-	}) => void;
-	/** Node adapter only: ms to receive the complete request (headers + body).
-	 *  Guards slowloris/trickling requests. Default: 30_000. */
-	requestTimeoutMs?: number;
-	/** Node adapter only: ms to receive the request headers. Default: 30_000. */
-	headersTimeoutMs?: number;
-	/** Node adapter only: max requests per keep-alive socket before Node forces
-	 *  a fresh connection (bounds long-lived socket reuse). Default: 1000. */
-	maxRequestsPerSocket?: number;
-	/** Node adapter only: optional WebSocket upgrade handler. Return the RFC 6455
-	 *  handshake values (see {@link NodeUpgradeHandshake}) to complete the
-	 *  handshake on the hijacked socket; return null/undefined to decline the
-	 *  upgrade. Ignored by the Bun server. (`createWebSocketUpgrade` is Bun-only
-	 *  — Node's Response cannot carry a 101.) */
-	upgrade?: (req: Request) => NodeUpgradeHandshake | null | undefined;
-	/** Node adapter only: called after a WebSocket upgrade handshake completes
-	 *  (the 101 response was accepted), with the hijacked socket so the caller
-	 *  can attach a frame codec/message loop (e.g. the `ws` library). Ignored by
-	 *  the Bun server. */
-	onUpgrade?: (socket: import("node:stream").Duplex, req: unknown, head: Buffer) => void;
-}
+export declare function echoHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Promise<Response>;
 /**
- * Minimal surface of the running server that castrum relies on.
+ * Pre-baked fallback handler: 404 for unmatched routes / OPTIONS.
+ */
+export declare function fallbackHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Response;
+/**
+ * Pre-baked HEAD read handler: headers only, no body.
+ */
+export declare function headHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Response;
+/**
+ * Pre-baked JSON-write handler (POST/PUT/PATCH): enforces Content-Type,
+ * content-length/body-size limits, JSON validity and (optionally) schema
+ * validation, then returns the ingress body JSON on success.
+ */
+export declare function jsonWriteHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Promise<Response>;
+/**
+ * Pre-baked OPTIONS handler: serves the native pipeline's CORS preflight
+ * decision — 204 when the preflight is allowed, 403 (terminal) when denied —
+ * and a plain 204 for non-preflight OPTIONS.
  *
- * This is intentionally NOT `ReturnType<typeof Bun.serve>` so that the public
- * types stay runtime-agnostic — Node.js TypeScript consumers don't need
- * `@types/bun` just to import castrum's types. Bun's server exposes far more
- * fields; treat the handle as opaque.
+ * `createIngressServer` wires this for EVERY route that has a handler, so
+ * read-only routes also answer preflights (previously OPTIONS only reached the
+ * pipeline on write routes that also configured a fallback).
  */
-export interface ServerHandle {
-	/** The port the server is bound to, when known (Bun exposes it; Node's
-	 *  http.Server does not — use `BakedServer.port` instead). */
-	port?: number;
-	/** Force-stop the server. Bun semantics: `true` drops active connections. */
-	stop(force?: boolean): void;
-}
-/** A running server instance plus a stop helper. */
-export interface BakedServer {
-	server: ServerHandle;
-	stop(): void;
-	port: number;
-}
-export interface GracefulShutdownOptions {
-	/** Grace period (ms) to drain in-flight requests before force-closing. */
-	timeoutMs?: number;
-	/** Signals to listen for. Default: SIGTERM + SIGINT. */
-	signals?: NodeJS.Signals[];
+export declare function optionsHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Response;
+/** Options for {@link nativeResponderRoute}. */
+export interface ResponderRouteOptions extends BakedHandlerOptions {
+	/** Terminal envelope style. Default: `'castrum'` (the pre-baked wire). */
+	terminalStyle?: TerminalStyle;
+	/**
+	 * Read the request body and pass it to the native pipeline for validation
+	 * (`requireJsonBody`/schema). Default `false` — the framework owns the body
+	 * (the responder reads it via `ctx.body`); native only needs the bytes when
+	 * a body stage is enabled in the route's `IngressHandlerOptions`.
+	 */
+	readBody?: boolean;
 }
 /**
- * Wire SIGTERM/SIGINT to a graceful shutdown: soft-stop (drain in-flight
- * requests) then force-close after `timeoutMs`. Works with both the Bun and
- * Node server handles (both expose `stop(force?)`).
- *
- * Returns a cleanup function that removes the signal listeners. Call it (or
- * `process.exit`) to tear down without hanging.
+ * Build a responder route: native pipeline decides + rejects (terminal
+ * response in the chosen style); on success the JS `responder` builds the 2xx.
+ * Returns an async `RouteHandler` (`(req, srv?, params?) => Promise<Response>`).
  */
-export declare function gracefulShutdown(handles: ReadonlyArray<ServerHandle>, options?: GracefulShutdownOptions): () => void;
-/** Build a Bun.serve config from pre-baked route handlers. */
-export declare function createIngressServer(options: CreateIngressServerOptions): BakedServer;
+export declare function nativeResponderRoute(ingress: OptimizedIngressHandler, responder: NativeResponder, opts?: ResponderRouteOptions): RouteHandler;
 /** A Node.js ingress server: {@link BakedServer} plus an async ready signal. */
 export interface NodeIngressServer extends BakedServer {
 	/**
@@ -2108,6 +1762,7 @@ export interface NodeIngressServer extends BakedServer {
 export declare function createIngressServerNode(options: CreateIngressServerOptions): NodeIngressServer;
 /** Sentinel value used by Rust to mean "rate limiting disabled". */
 export declare const RATE_LIMIT_U32_MAX = 4294967295;
+/** Runtime configuration for the pre-baked handler path (`createIngressHandler`). */
 export interface BakedIngressRuntime {
 	/** Emit an `x-request-id` header on responses. Default: false. */
 	emitRequestIdHeader?: boolean;
@@ -2179,100 +1834,22 @@ export interface BakedIngressRuntime {
  */
 export declare function createIngressHandler(options?: IngressHandlerOptions, runtime?: BakedIngressRuntime): OptimizedIngressHandler;
 /**
- * Generate the next request ID as 16 lowercase hex bytes (zero-alloc).
- *
- * @returns A shared buffer aliased across calls — decode/copy before the next
- *   `generateRequestId()` invocation.
- */
-export declare function generateRequestId(): Uint8Array;
-/** A single precomputed header-variant template. */
-export interface HeaderTemplate {
-	readonly entries: ReadonlyArray<readonly [
-		string,
-		string
-	]>;
-	readonly needsOriginEcho: boolean;
-	readonly needsRateDynamic: boolean;
-	readonly needsRetryAfter: boolean;
-	readonly needsDynamicHsts: boolean;
-}
-/** Precomputed per-handler response context. */
-export interface ResponseBuildContext {
-	readonly templates: HeaderTemplate[];
-	readonly corsStatic: CorsStaticStrings | null;
-	readonly hstsValue: string | null;
-}
-/**
- * Build the full response context (header templates + static CORS strings +
- * HSTS value) for a handler configuration.
- */
-export declare function buildResponseContext(options: {
-	cors?: CorsOptions;
-	security?: SecurityHeadersOptions;
-	https?: boolean;
-	enableSecurityHeaders?: boolean;
-	rateLimit?: {
-		limit?: number;
-	};
-}): ResponseBuildContext;
-/**
- * Build the response headers for a decoded result, applying the dynamic parts
- * (request-id, origin echo, rate-limit counters, retry-after, dynamic HSTS).
- */
-export declare function headersForResult(ctx: ResponseBuildContext, r: {
-	readonly headerVariant: number;
-	readonly corsAllowed: boolean;
-	readonly rateRemaining: number;
-	readonly rateResetMs: number;
-	readonly retryAfterMs: number;
-	readonly https: boolean;
-}, req: Request, requestId: string): Headers;
-/**
- * Build a terminal response for a result, or `null` when the result is not
- * terminal (the caller should serve the body instead).
+ * Liveness probe: `200 {"status":"ok"}` as long as the process is alive.
+ * Never touches dependencies.
  */
-export declare function buildTerminalResponse(ctx: ResponseBuildContext, r: {
-	readonly terminal: boolean;
-	readonly isPreflight: boolean;
-	readonly corsAllowed: boolean;
-	readonly errorCode: number;
-	readonly status: number;
-	readonly headerVariant: number;
-	readonly https: boolean;
-	readonly rateLimit: number;
-	readonly rateRemaining: number;
-	readonly rateResetMs: number;
-	readonly retryAfterMs: number;
-}, req: Request, requestId: string): Response | null;
-/** Default maximum request body size in bytes. */
-export declare const DEFAULT_MAX_BODY_BYTES = 1048576;
+export declare function livenessHandler(): (_req: Request) => Response;
 /**
- * Default overall deadline (ms) for reading a request body. Non-zero so the
- * async `createIngress` / route handlers are protected against slowloris and
- * trickling bodies by default. Set `bodyTimeoutMs: 0` to disable.
+ * Readiness probe: runs the optional async `check` (dependency readiness).
+ * Returns `200 {"status":"ready"}` when the check passes (or no check is
+ * given), `503 {"status":"not_ready"}` when it throws or returns false.
  */
-export declare const DEFAULT_BODY_TIMEOUT_MS = 30000;
-/** Maps HTTP methods to the native Ingress method-kind enum. */
-export declare const METHOD_KIND: Record<string, number>;
-/** Which request headers to extract into the packed input. */
-export interface HeaderPlan {
-	cookie: boolean;
-	cors: boolean;
-	proxy: boolean;
-	proto: boolean;
-}
+export declare function readinessHandler(check?: () => boolean | Promise<boolean>): (_req: Request) => Promise<Response>;
 /**
- * Create a fast packed-input ingress handler (path 1).
- *
- * JS packs the request headers into a binary buffer (`IngressInputPacker`) and
- * the native `Ingress.handleRequestPacked` decodes them. Responses use the
- * `{"error":{...}}` wire format with `x-ratelimit-*` headers.
- *
- * Prefer this when you want the lowest-overhead pipeline and will call `run()`
- * yourself with a **synchronous** callback. For ready-made route handlers and a
- * server builder, use `createIngressHandler` (path 2).
+ * Combined health probe: liveness by default, plus an optional readiness
+ * `check`. When a `check` is provided the response is 503 on failure
+ * (readiness semantics), otherwise always 200.
  */
-export declare function createIngressFast(options?: IngressFastOptions): IngressFastHandler;
+export declare function healthHandler(check?: () => boolean | Promise<boolean>): ((_req: Request) => Response) | ((_req: Request) => Promise<Response>);
 /** The runtime hooks + registry for ingress metrics. */
 export interface IngressMetrics {
 	registry: MetricsRegistry;
@@ -2293,48 +1870,112 @@ export declare function createIngressMetrics(): IngressMetrics;
  *   createIngressServer({ routes: { "/metrics": { read: metricsHandler(m) } } })
  */
 export declare function metricsHandler(metrics: IngressMetrics): (_req: Request) => Response;
-/**
- * Liveness probe: `200 {"status":"ok"}` as long as the process is alive.
- * Never touches dependencies.
- */
-export declare function livenessHandler(): (_req: Request) => Response;
-/**
- * Readiness probe: runs the optional async `check` (dependency readiness).
- * Returns `200 {"status":"ready"}` when the check passes (or no check is
- * given), `503 {"status":"not_ready"}` when it throws or returns false.
- */
-export declare function readinessHandler(check?: () => boolean | Promise<boolean>): (_req: Request) => Promise<Response>;
-/**
- * Combined health probe: liveness by default, plus an optional readiness
- * `check`. When a `check` is provided the response is 503 on failure
- * (readiness semantics), otherwise always 200.
- */
-export declare function healthHandler(check?: () => boolean | Promise<boolean>): ((_req: Request) => Response) | ((_req: Request) => Promise<Response>);
-/** A parsed W3C trace context (valid per the spec's length/hex rules). */
-export interface TraceContext {
-	/** Version, always `"00"` for accepted headers. */
-	version: string;
-	/** 32 hex chars — the trace id (shared across the whole trace). */
-	traceId: string;
-	/** 16 hex chars — the current span id. */
-	spanId: string;
-	/** The flags byte (bit 0 = sampled). */
-	flags: number;
-	/** True when the `sampled` (bit 0) flag is set. */
-	sampled: boolean;
+/** Per-route spec for {@link createIngressRouter}. */
+export interface RouterRouteSpec {
+	/**
+	 * Per-route ingress options — compiled into a DEDICATED native `IngressInner`
+	 * for this route (parseCookies, parseQuery, schema, cors, rateLimit, limits,
+	 * requireJsonBody, ...). This is what makes the pipeline prune per route.
+	 */
+	options?: IngressHandlerOptions;
+	/** Wire GET + HEAD read handlers over this route's compiled handler. */
+	read?: boolean;
+	/** Wire POST/PUT/PATCH JSON-write handlers over this route's compiled handler. */
+	write?: boolean;
+	/** Wire a POST echo handler over this route's compiled handler. */
+	echo?: boolean;
+	/** Wire a GET read handler (cookies-style) over this route's compiled handler. */
+	cookies?: boolean;
+	/** Wire a DELETE read-style handler over this route's compiled handler. */
+	delete?: boolean;
+	/**
+	 * A JS responder route: the native pipeline decides + rejects (terminal
+	 * response in {@link terminalStyle}); on success the responder builds the
+	 * 2xx body (async OK) from a decoded snapshot. Wired for `methods`
+	 * (default `['GET']`). When set, the standard `read`/`write`/etc. flags for
+	 * this route are ignored.
+	 */
+	responder?: {
+		handler: NativeResponder;
+		/** HTTP methods to wire (default `['GET']`). */
+		methods?: ReadonlyArray<string>;
+		/** Read the body for native validation (default false — framework owns it). */
+		readBody?: boolean;
+	};
+	/** Terminal envelope style for this route's responder (default: router-level
+	 *  `terminalStyle` or `'castrum'`). */
+	terminalStyle?: TerminalStyle;
+	/**
+	 * A raw request→Response handler served directly for GET, OUTSIDE the
+	 * ingress pipeline (health/metrics probes, /metrics). When set, `read`/
+	 * `write`/etc. for this route are ignored.
+	 */
+	raw?: RouteHandler;
+	/** Overrides `maxBodyBytes` for this route's write/echo handlers. */
+	maxBodyBytes?: number;
+	/** Overrides `bodyTimeoutMs` for this route's write/echo handlers. */
+	bodyTimeoutMs?: number;
+}
+/** Options for {@link createIngressRouter}. */
+export interface CreateIngressRouterOptions {
+	/** Route table: path → per-route spec. */
+	routes: Record<string, RouterRouteSpec>;
+	/** Shared runtime hooks (onRequest/onResponse/onError, security headers,
+	 *  output buffer size) applied to EVERY compiled route handler. */
+	runtime?: BakedIngressRuntime;
+	/** Shared `getIp` resolver for route handlers. */
+	getIp?: (req: Request, srv: unknown) => string | undefined;
+	/** Shared `copyBody` default for route handlers. */
+	copyBody?: boolean;
+	/** Default terminal envelope style for responder routes (`'castrum'`). */
+	terminalStyle?: TerminalStyle;
+	/** Pre-warm every compiled route at construction (JIT the packed pipeline +
+	 *  the FFI ingress call before the first real request). Default: false. */
+	warmOnCreate?: boolean;
+}
+/** A compiled per-route router. */
+export interface IngressRouter {
+	/** The per-route compiled handlers keyed by path (for custom route wiring). */
+	routeHandlers: Record<string, OptimizedIngressHandler>;
+	/** The route → method → handler map (compatible with Bun.serve `routes` and
+	 *  `createIngressServerNode`). */
+	routes: Record<string, Record<string, unknown>>;
+	/** The path matcher (`:param`/`*` dynamic routes). */
+	match: (pathname: string) => PathMatch | undefined;
+	/** A fetch-style dispatcher: match path + method → the route's handler. */
+	fetch: (req: Request, srv?: unknown) => Response | Promise<Response>;
+	/** Pre-warm every compiled route (JIT the packed pipeline + FFI call). */
+	prewarm: () => void;
 }
 /**
- * Parse a `traceparent` header value into a {@link TraceContext}, or `null`
- * when malformed (wrong version / length / non-hex). Invalid contexts are
- * ignored per the spec — callers should generate a fresh trace then.
+ * Compile a route table into per-route native ingress instances.
+ *
+ * Each route with a pipeline-backed spec (`read`/`write`/`echo`/`cookies`/
+ * `delete`) compiles its OWN `createIngressHandler(options)` — a dedicated
+ * `IngressInner` pruned to that route's stages + a per-route header plan.
+ * Routes that need nothing (a bare `read` with no cookies/query/cors) therefore
+ * gather zero headers and run a near-empty native pipeline. All routes share
+ * the same wire format and the shared process-wide rate-limiter budgets.
+ *
+ * @example
+ * ```ts
+ * const router = createIngressRouter({
+ *   warmOnCreate: true,
+ *   runtime: ingressMetrics?.runtime,
+ *   routes: {
+ *     '/health': { read: true, options: { parseCookies: false, parseQuery: false } },
+ *     '/api/users': {
+ *       read: true,
+ *       write: true,
+ *       options: { parseCookies: true, parseQuery: true, schema: USER_SCHEMA_BYTES },
+ *     },
+ *     '/metrics': { raw: metricsHandler(ingressMetrics) },
+ *   },
+ * })
+ * const server = Bun.serve({ routes: router.routes }) // or router.fetch
+ * ```
  */
-export declare function parseTraceParent(header: string | null | undefined): TraceContext | null;
-/** Random 32-hex trace id (crypto-backed where available). */
-export declare function createTraceId(): string;
-/** Random 16-hex span id. */
-export declare function createSpanId(): string;
-/** Serialize a trace context back to a `traceparent` header value. */
-export declare function serializeTraceParent(ctx: TraceContext): string;
+export declare function createIngressRouter(options: CreateIngressRouterOptions): IngressRouter;
 /**
  * Synchronous convenience wrapper over `createIngressFast` (path 1).
  *
@@ -2373,6 +2014,7 @@ export interface PipelineContext {
 	/** Mutable per-request storage for middleware/user state. */
 	readonly locals: Map<string, unknown>;
 }
+/** Result of running `preprocess`: terminal short-circuit or pass-through. */
 export interface PreprocessOutcome {
 	/** True when the pipeline short-circuited (error/denied) — serve `response`. */
 	readonly terminal: boolean;
@@ -2380,6 +2022,7 @@ export interface PreprocessOutcome {
 	readonly result: PipelineResult | null;
 	readonly ctx: PipelineContext;
 }
+/** Options for `createPipeline`. */
 export interface CreatePipelineOptions {
 	/** Ingress options (same surface as `createIngressHandler`). */
 	options?: IngressHandlerOptions;
@@ -2400,6 +2043,7 @@ export interface CreatePipelineOptions {
 	 */
 	render?: (result: PipelineResult, ctx: PipelineContext) => Response | Promise<Response>;
 }
+/** The composed ingress pipeline: preprocess / handleRequest / readBody. */
 export interface IngressPipeline {
 	/** The underlying pre-baked handler (custom route factories / responses). */
 	readonly ingress: OptimizedIngressHandler;
@@ -2429,49 +2073,7 @@ export interface IngressPipeline {
  * ```
  */
 export declare function createPipeline(opts?: CreatePipelineOptions): IngressPipeline;
-export interface WebSocketUpgradeOptions {
-	/** Subprotocols this server supports; the first client-requested match wins. */
-	protocols?: ReadonlyArray<string>;
-}
-export interface WebSocketUpgradeResult {
-	/** The 101 Switching Protocols response — return it from your fetch handler. */
-	readonly response: Response;
-	/** The client's `Sec-WebSocket-Key` (handy for connection logging). */
-	readonly key: string;
-	/** The negotiated subprotocol, if any. */
-	readonly protocol: string | null;
-}
-/**
- * Build a WebSocket 101 upgrade handshake response for a request.
- *
- * Validates `Sec-WebSocket-Key` presence and computes the RFC 6455 accept key
- * via the native `rust.wsAcceptKey`, optionally negotiates a subprotocol, and
- * returns a ready-to-serve `Response`. Returns `null` when the request is not a
- * valid upgrade (missing/empty key).
- *
- * This only produces the handshake — pair it with your framework's own
- * WebSocket server (Bun.serve's `websocket` handler, or a WS library), which
- * owns the subsequent frames:
- *
- * @example
- * ```ts
- * const srv = Bun.serve({
- *   port: 3000,
- *   fetch(req, server) {
- *     const up = createWebSocketUpgrade(req, { protocols: ["chat"] });
- *     if (up && server.upgrade(req, { data: { protocol: up.protocol } })) {
- *       return up.response;
- *     }
- *     return new Response("Not a websocket", { status: 400 });
- *   },
- *   websocket: {
- *     message(ws, msg) { ws.send(msg); },
- *   },
- * });
- * ```
- */
-export declare function createWebSocketUpgrade(req: Request, opts?: WebSocketUpgradeOptions): WebSocketUpgradeResult | null;
-export interface SseEvent {
+/** One SSE event to frame via `sseResponse` (event/id/retry/data). */ export interface SseEvent {
 	/** Optional `event:` field. */
 	event?: string | null;
 	/** Optional `id:` field. */
@@ -2802,7 +2404,7 @@ export declare const LOADER_OPS: {
 	};
 	readonly hexEncode: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2814,7 +2416,7 @@ export declare const LOADER_OPS: {
 	};
 	readonly base64Encode: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array, urlSafe?: boolean, padding?: boolean) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, urlSafe?: boolean, padding?: boolean) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], urlSafe?: boolean, padding?: boolean) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2826,7 +2428,7 @@ export declare const LOADER_OPS: {
 	};
 	readonly base64UrlEncode: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2862,13 +2464,13 @@ export declare const LOADER_OPS: {
 	};
 	readonly etag: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array, weak?: boolean | null) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, weak?: boolean | null) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], weak?: boolean | null) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
 	readonly urlEncode: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2886,19 +2488,19 @@ export declare const LOADER_OPS: {
 	};
 	readonly wsAcceptKey: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
 	readonly mimeFromExtension: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
 	readonly signCookie: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array, secret: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, secret: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], secret: Uint8Array) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2916,7 +2518,7 @@ export declare const LOADER_OPS: {
 	};
 	readonly passwordHash: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, salt: Uint8Array, options?: PasswordHashOptions | null) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], salt: Uint8Array, options?: PasswordHashOptions | null) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2958,7 +2560,7 @@ export declare const LOADER_OPS: {
 		readonly pairedRest: [
 			0
 		];
-		readonly scalar: (i: Uint8Array, patch: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, patch: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], patches: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2967,7 +2569,7 @@ export declare const LOADER_OPS: {
 		readonly pairedRest: [
 			0
 		];
-		readonly scalar: (i: Uint8Array, base: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, base: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], bases: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};
@@ -2991,7 +2593,7 @@ export declare const LOADER_OPS: {
 	};
 	readonly hmacSha256: {
 		readonly kind: "bytes";
-		readonly scalar: (i: Uint8Array, key: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly scalar: (i: Uint8Array, key: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
 		readonly batch: (items: Uint8Array[], key: Uint8Array) => Uint8Array<ArrayBufferLike>[];
 		readonly element: typeof byteElem;
 	};