castrum 0.7.0 → 0.9.1

package/dist/index.d.ts

@@ -0,0 +1,2763 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/** A single JSON Schema validation error (fast path + DOM fallback). */
+export interface SchemaError {
+	/** RFC 6901 JSON pointer to the failing instance value ("" = root). */
+	instancePath: string;
+	/** JSON pointer into the schema at the failing keyword. */
+	schemaPath: string;
+	/** The failing keyword (e.g. "type", "pattern", "required"). */
+	keyword: string;
+	/** Human-readable failure message. */
+	message: string;
+}
+/** The native `SchemaValidator` class instance. */
+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;
+	/**
+	 * One-pass validate + extract: validate `input` against the schema and
+	 * capture scalar values / array lengths at `paths` during the same native
+	 * walk (no `JSON.parse`, no DOM). For "derive" routes (response built from a
+	 * handful of body fields) this replaces `JSON.parse` + Ajv on the happy path
+	 * and rejects invalid bodies with zero DOM/GC.
+	 *
+	 * `paths` are RFC 6901 JSON pointers of OBJECT KEYS; a trailing `/-`
+	 * captures the ARRAY LENGTH at that path (e.g. `"/totalCents"`,
+	 * `"/lineItems/-"`). Array-index steps are not supported.
+	 */
+	derive(input: Uint8Array, paths: string[]): JsonDeriveResult;
+}
+/** A single derived value captured during one-pass validation. */
+export interface JsonDeriveValue {
+	/** `"int" | "number" | "string" | "bool" | "null"`. */
+	kind: string;
+	int: number | null;
+	number: number | null;
+	text: string | null;
+	boolean: boolean | null;
+}
+/** Result of a one-pass `validate + derive`. */
+export interface JsonDeriveResult {
+	/** `true` when the document is schema-valid; `false` → caller rejects. */
+	ok: boolean;
+	/** One entry per requested path (`null` = path absent from the document). */
+	values: Array<JsonDeriveValue | null>;
+}
+/** The native `HmacSigner` class instance. */
+export interface HmacSignerInstance {
+	sign(data: Uint8Array): Uint8Array;
+	verify(data: Uint8Array, sig: Uint8Array): boolean;
+}
+/** The native `FormParser` class instance (reusable output buffer). */
+export interface FormParserInstance {
+	/** Parse an x-www-form-urlencoded body into packed pairs (reuses the buffer). */
+	parse(input: Uint8Array): Uint8Array;
+	/** Zero-alloc parse into a caller-provided output buffer. */
+	parseInto(input: Uint8Array, output: Uint8Array): number;
+}
+/** A parsed Content-Type / media type. */
+export interface MediaTypeResult {
+	/** Lowercased `type/subtype`. */
+	mediaType: string;
+	charset: string | null;
+	boundary: string | null;
+	params: Record<string, string>;
+}
+/** The native `MediaTypeParser` class instance. */
+export interface MediaTypeParserInstance {
+	parse(input: Uint8Array): MediaTypeResult;
+}
+/** 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 {
+	encoding: string;
+	q: number;
+	order: number;
+}
+/**
+ * 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 {
+	encode(input: Uint8Array): Uint8Array;
+	decode(input: Uint8Array): Uint8Array;
+}
+/** Result of a native rate-limit check for one key at a point in time. */
+export interface RateCheckResult {
+	allowed: boolean;
+	remaining: number;
+	resetMs: number;
+}
+/** The native `RateLimiter` class instance (sharded fixed-window state). */
+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 {
+	sign(value: Uint8Array): Uint8Array;
+	/** Returns the signed value without its signature, or null on invalid. */
+	verify(signed: Uint8Array): Uint8Array | null;
+}
+/** The native `CsrfProtector` class instance (HMAC key compiled once). */
+export interface CsrfProtectorInstance {
+	create(): Uint8Array;
+	verify(token: Uint8Array): boolean;
+}
+/** 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 {
+	mCost?: number;
+	tCost?: number;
+	pCost?: number;
+	outLen?: number;
+}
+/** A parsed multipart/form-data part. */
+export interface MultipartPart {
+	name: string;
+	filename: string | null;
+	contentType: string | null;
+	data: Uint8Array;
+}
+/** A decoded RFC 6455 websocket frame. */
+export interface WsFrame {
+	fin: boolean;
+	opcode: number;
+	payload: Uint8Array;
+}
+/** The native `TemplateRenderer` class instance. */
+export interface TemplateRendererInstance {
+	render(context: unknown): Uint8Array;
+	/** Render from pre-serialized JSON context bytes (no napi Value marshal). */
+	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 {
+	sign(claims: unknown, nowSeconds: number): Uint8Array;
+	/** 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 {
+	encrypt(nonce: Uint8Array, plaintext: Uint8Array): Uint8Array;
+	decrypt(nonce: Uint8Array, ciphertext: Uint8Array): Uint8Array | null;
+}
+/** The native `Argon2Hasher` class instance (params compiled once). */
+export interface Argon2HasherInstance {
+	hash(password: Uint8Array, salt: Uint8Array): Uint8Array;
+	verify(password: Uint8Array, phc: Uint8Array): 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`.
+ * @throws {RangeError} when the buffer is shorter than `count` × 4 bytes.
+ */
+export declare function unpackU32Array(bytes: Uint8Array): Uint32Array;
+/**
+ * Unpack a packed bitset: `[u32 count]{bit per item}` → one 0/1 byte per item.
+ * @throws {RangeError} when the buffer is shorter than `count` bits.
+ */
+export declare function unpackBitset(bytes: Uint8Array): Uint8Array;
+/**
+ * Unpack a packed i64 array as SIGNED `BigInt64Array`.
+ * @throws {RangeError} when the buffer is shorter than `count` × 8 bytes.
+ */
+export declare function unpackI64ArrayAsBigInt(bytes: Uint8Array): BigInt64Array;
+/**
+ * Unpack a packed byte-results buffer: `[u32 count]{[u32 len][bytes]}` → one
+ * `Uint8Array` slice per item. The slices reference `bytes`'s backing store
+ * (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
+ * later calls) — this is the public entry point. Hot internal paths that can
+ * 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;
+/** 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, 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;
+	};
+	/**
+	 * 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).
+	 */
+	security?: SecurityHeadersOptions;
+	https?: boolean;
+	maxBodyBytes?: number;
+	enableSecurityHeaders?: boolean;
+	enableRequestIds?: boolean;
+	enableBodySizeGuard?: boolean;
+	emitMetadataJson?: boolean;
+	readBody?: boolean;
+	outputBufferSize?: number;
+	/**
+	 * 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).
+	 */
+	bodyTimeoutMs?: number;
+	/**
+	 * Invoked when the native pipeline throws (the request becomes a 500).
+	 * Native failures are otherwise silent in the fast path. Never throws.
+	 */
+	onError?: (error: Error) => void;
+	/**
+	 * 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.
+	 */
+	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;
+	/**
+	 * 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;
+	/**
+	 * Invoked after a terminal context (and its `Response`) is produced, for
+	 * metrics/logging hooks. Only used by the async `createIngress` path.
+	 */
+	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
+	][];
+	/**
+	 * 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()`.
+	 */
+	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;
+	/**
+	 * 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;
+}
+/** 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;
+	/**
+	 * 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;
+	/**
+	 * 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;
+}
+/**
+ * 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 {
+	/**
+	 * 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;
+}
+/**
+ * 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.
+	 */
+	xxh3(input: Uint8Array): bigint;
+	hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array | string;
+	hmacSha256Verify(key: Uint8Array, data: Uint8Array, sig: Uint8Array | string): boolean;
+	jsonValid(input: Uint8Array): boolean;
+	/**
+	 * 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).
+	 */
+	urlResolve(base: Uint8Array, reference: Uint8Array): Uint8Array | string;
+	/**
+	 * 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;
+	createFormParser(capacity?: number): FormParserInstance;
+	createMediaTypeParser(): MediaTypeParserInstance;
+	/**
+	 * Higher-order conditional-request check: per-resource 304 decision (setup once).
+	 */
+	createConditionalRequest(etagValue: Uint8Array, lastModifiedSecs?: number): ConditionalRequestInstance;
+	/**
+	 * Higher-order negotiator: precompiles supported encodings once.
+	 */
+	createAcceptNegotiator(supported: string[]): AcceptNegotiatorInstance;
+	createBase64Codec(urlSafe?: boolean, padding?: boolean): Base64CodecInstance;
+	createCookieSigner(secret: Uint8Array): CookieSignerInstance;
+	createCsrfProtector(secret: Uint8Array): CsrfProtectorInstance;
+	createUrlBuilder(base: Uint8Array): UrlBuilderInstance;
+	createJwtSigner(secret: Uint8Array, ttlSeconds?: number): JwtSignerInstance;
+	createAeadCipher(key: Uint8Array, algorithm?: string): AeadCipherInstance;
+	createArgon2Hasher(options?: PasswordHashOptions | null): Argon2HasherInstance;
+	createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance;
+	/**
+	 * Sharded fixed-window per-key rate limiter. `maxEntries` clamps internally
+	 * (default 1,048,576). Each instance owns an independent budget.
+	 * @remarks Scalar per-check cost: ~3-14x SLOWER than the JS Map baseline —
+	 * prefer the ingress pipeline (one FFI for all stages) for native rate
+	 * limiting in a request path. [measured 2026-08]
+	 */
+	createRateLimiter(limit: number, windowMs: number, maxEntries?: number | null): RateLimiterInstance;
+	initThreadPool(rayonThreads?: number): void;
+	rayonNumThreads(): number;
+	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).
+	 */
+	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;
+	/**
+	 * 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;
+	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, algorithm?: string | null): Uint8Array;
+	aeadDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, algorithm?: string | null): Uint8Array | null;
+	gzipCompress(data: Uint8Array, level?: number | null): Uint8Array;
+	/**
+	 * @param maxDecompressed Caps decompressed output (default 64 MiB) as a
+	 *   decompression-bomb guard; a larger value errors.
+	 */
+	gzipDecompress(data: Uint8Array, maxDecompressed?: number | null): Uint8Array;
+	/**
+	 * 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;
+	/**
+	 * @param maxDecompressed Caps decompressed output (default 64 MiB) as a
+	 *   decompression-bomb guard; a larger value errors.
+	 */
+	brotliDecompress(data: Uint8Array, maxDecompressed?: number | null): Uint8Array;
+	/**
+	 * 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[];
+	multipartParsePacked(body: Uint8Array, boundary: Uint8Array): Uint8Array;
+	multipartParsePackedInto(body: Uint8Array, boundary: Uint8Array, output: Uint8Array): number;
+	wsFrameEncode(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean): Uint8Array;
+	wsFrameDecode(data: Uint8Array): WsFrame | null;
+	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;
+}
+/** 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;
+}
+/** The full Rust FFI client (scalar methods + namespaces + configuration). */
+export interface RustClient extends RustScalar {
+	text: RustText;
+	batch: RustBatch;
+	packed: RustPacked;
+	/**
+	 * 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).
+	 */
+	transport(): "ffi" | "napi";
+	/** Whether the bun:ffi transport is live (equivalent to `transport() === "ffi"`). */
+	ffiActive(): boolean;
+	/**
+	 * 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}).
+	 */
+	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;
+/** 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;
+}
+/**
+ * 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 {
+	/**
+	 * 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.
+ * Under Node this falls back to `crypto.randomUUID` (v4).
+ *
+ * @returns A UUID string.
+ */
+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;
+}
+/** 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;
+/**
+ * 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). */
+export declare const OUT_ERROR_CODE: number;
+/** Offset of the raw u16 status. */
+export declare const OUT_STATUS: number;
+/** Offset of the u32 flags word (see FLAG_* below). */
+export declare const OUT_FLAGS: number;
+/** Offset of the u32 rate-limit budget (U32_MAX = disabled). */
+export declare const OUT_RATE_LIMIT: number;
+/** Offset of the u32 rate-limit remaining count. */
+export declare const OUT_RATE_REMAINING: number;
+/** Offset of the u64 rate-limit window reset (ms epoch). */
+export declare const OUT_RATE_RESET: number;
+/** Offset of the u64 Retry-After value (ms). */
+export declare const OUT_RETRY_AFTER: number;
+/** Offset of the u32 cookies-JSON section length. */
+export declare const OUT_COOKIES_JSON_LEN: number;
+/** Offset of the u32 query-JSON section length. */
+export declare const OUT_QUERY_JSON_LEN: number;
+/** Offset of the header-template variant byte (see HV_* below). */
+export declare const OUT_HEADER_VARIANT: number;
+/** Offset of the u32 body-JSON section length. */
+export declare const OUT_BODY_JSON_LEN: number;
+/** Byte offset where the variable-length JSON sections begin. */
+export declare const OUT_DATA_START: number;
+/** Request carried a cookie header (cookie-JSON section present). */
+export declare const FLAG_HAS_COOKIES: number;
+/** Request carried a query string (query-JSON section present). */
+export declare const FLAG_HAS_QUERY: number;
+/** The request body parsed as valid JSON. */
+export declare const FLAG_BODY_VALID_JSON: number;
+/** The request body validated against the ingress schema. */
+export declare const FLAG_SCHEMA_VALID: number;
+/** The CORS engine allowed the request origin. */
+export declare const FLAG_CORS_ALLOWED: number;
+/** The request was a CORS preflight (OPTIONS + request-method). */
+export declare const FLAG_IS_PREFLIGHT: number;
+/** The request was rate-limited. */
+export declare const FLAG_RATE_LIMITED: number;
+/** The request arrived over HTTPS (trusted-proxy scheme). */
+export declare const FLAG_HTTPS: number;
+/** The request came from a trusted proxy (per the proxy config). */
+export declare const FLAG_TRUSTED_PROXY: number;
+/** A declared output section overran the buffer (truncated). */
+export declare const FLAG_BODY_TRUNCATED: number;
+/** Response body is JSON (`content-type: application/json`). */
+export declare const HV_JSON: number;
+/** CORS simple-request variant (Origin echoed + vary headers). */
+export declare const HV_CORS_SIMPLE: number;
+/** CORS preflight variant (allow-methods/headers/max-age). */
+export declare const HV_CORS_PREFLIGHT: number;
+/** Rate-limit active variant (`ratelimit-limit` header). */
+export declare const HV_RATE_ACTIVE: number;
+/** Rate-limited variant (Retry-After emitted). */
+export declare const HV_RATE_LIMITED: number;
+/** Total number of header-variant combinations (32). */
+export declare const HV_COUNT: number;
+/** No error (accepted). */
+export declare const ERR_CODE_NONE: number;
+/** CORS preflight rejected. */
+export declare const ERR_CODE_CORS_PREFLIGHT: number;
+/** Rate limit exceeded. */
+export declare const ERR_CODE_RATE_LIMITED: number;
+/** Request body exceeded the size guard. */
+export declare const ERR_CODE_BODY_TOO_LARGE: number;
+/** Request body is not valid JSON. */
+export declare const ERR_CODE_INVALID_JSON: number;
+/** Request body failed schema validation. */
+export declare const ERR_CODE_SCHEMA_VALIDATION: number;
+/** Malformed request (bad request line / headers). */
+export declare const ERR_CODE_BAD_REQUEST: number;
+/** Request headers/URL exceeded the configured limits. */
+export declare const ERR_CODE_REQUEST_TOO_LARGE: number;
+/** Internal pipeline failure (maps to 500). */
+export declare const ERR_CODE_INTERNAL: number;
+/**
+ * JS-only error-code sentinel for a request-body read timeout in the async
+ * `createIngress` path.
+ *
+ * The native pipeline never emits this value — it is a JS body-reader error
+ * (`REQUEST_TIMEOUT` from `readBodyWithLimit`) mapped onto the numeric
+ * error-code contract so the shared status/name/message helpers stay
+ * consistent. Deliberately not sourced from Rust (see the header comment:
+ * 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).
+ */
+export declare function isValidResponseStatus(status: number): boolean;
+/**
+ * Map a native ingress error code to the HTTP status that should be returned.
+ * A permitted CORS preflight always yields 204.
+ */
+export declare function statusForErrorCode(errorCode: number, isPreflightAllowed: boolean): number;
+/**
+ * Normalize a raw status to a legal response status, falling back to the
+ * error-code mapping when the raw status is not legal.
+ */
+export declare function normalizeResponseStatus(status: number, errorCode: number, isPreflightAllowed: boolean): number;
+/**
+ * Compute a safe terminal status for a result: a permitted CORS preflight
+ * yields 204, otherwise the normalized status (or the error-code mapping).
+ */
+export declare function safeTerminalStatus(r: {
+	readonly status: number;
+	readonly errorCode: number;
+	readonly isPreflight: boolean;
+	readonly corsAllowed: boolean;
+}): number;
+/**
+ * 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: {
+		requestId: string;
+		method: string;
+		path: string;
+		status: number;
+		durationMs: number;
+		ip?: string;
+	}): void;
+	error(info: {
+		requestId?: string;
+		method?: string;
+		path?: string;
+		code?: string;
+		message: string;
+	}): void;
+};
+/** Pre-encoded static error bodies, keyed by error-code string name. */
+export declare const ERROR_BODIES: Record<string, Uint8Array>;
+/**
+ * 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 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 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;
+/**
+ * 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.
+ *
+ * `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 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;
+}
+/**
+ * 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 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 {
+	/**
+	 * Resolves to the actually-bound port once the server is listening
+	 * (`node:http` binds asynchronously; useful when `port: 0`).
+	 */
+	ready: Promise<number>;
+}
+/**
+ * Start a Node.js `node:http` server serving the same pre-baked ingress route
+ * handlers as {@link createIngressServer}. Returns a {@link NodeIngressServer};
+ * `stop()` drains in-flight connections (graceful) before closing, and
+ * `ready` resolves to the bound port once listening.
+ *
+ * Requires Node.js >= 20.3 (N-API floor). Bun users should prefer
+ * {@link createIngressServer} (Bun.serve).
+ */
+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;
+	/** Enable security headers on responses. Default: true. */
+	enableSecurityHeaders?: boolean;
+	/**
+	 * Ordered `[name, value]` security headers (names are lowercased).
+	 * NOTE: this PRE-BAKED path takes RAW `[name, value]` pairs here; the
+	 * fast/async paths (`createIngressFast`/`createIngress`) instead take a
+	 * structured `security: SecurityHeadersOptions` object (CSP/HSTS builders).
+	 * The two paths intentionally use different option shapes (see
+	 * docs/INGRESS.md).
+	 */
+	securityHeaders?: ReadonlyArray<[
+		string,
+		string
+	]>;
+	/** Native output buffer size in bytes. Default: 131072. */
+	outputBufferSize?: number;
+	/** Invoked before a request is processed (for tracing/context hooks). */
+	onRequest?: (req: Request, requestId: string, ip: string | undefined) => void;
+	/** Invoked after a Response is produced (for metrics/logging hooks). */
+	onResponse?: (req: Request, result: BakedIngressResult, status: number, requestId: string) => void;
+	/**
+	 * Invoked when the native pipeline fails (the request becomes a 500).
+	 * Native failures are otherwise silent — wire this to your error tracker.
+	 */
+	onError?: (req: Request, requestId: string, error: Error) => void;
+	/**
+	 * Emit one structured JSON line per request/error via the built-in logger
+	 * (gated by `CASTRUM_LOG_LEVEL`). Default: false.
+	 */
+	structuredLog?: boolean;
+	/**
+	 * Custom structured logger (e.g. with a custom stream or extra fields).
+	 * When provided, request/error lines go here instead of the built-in stderr
+	 * logger and `structuredLog` is implicitly enabled.
+	 */
+	logger?: ReturnType<typeof createStructuredLogger>;
+	/**
+	 * Hard cap on concurrently borrowed output buffers (zero-copy responses not
+	 * yet consumed). Bounds memory when zero-copy responses are consumed
+	 * slowly; when exceeded, requests fail with a 500 (pool exhaustion) instead
+	 * of allocating unbounded temporaries. 0 (default) is unlimited — see
+	 * `BufferPool.maxInFlight`.
+	 */
+	maxInFlight?: number;
+	/**
+	 * Abandonment guard (ms) for zero-copy responses: if a response body is
+	 * neither pulled nor cancelled within this window, its pooled buffer is
+	 * released and the stream closed. Bounds memory under abandoned (unread)
+	 * zero-copy responses. 0 (default) disables it — see `pooledBodyResponse`.
+	 */
+	zeroCopyTimeoutMs?: number;
+}
+/**
+ * Create a pre-baked ingress handler (path 2).
+ *
+ * The request frame (url/ip/rid/headers) is packed in JS via `IngressInputPacker`
+ * + `gatherRawHeadersPacked` and driven through the same native core as the
+ * fast path (`Ingress.handleRequestPacked`), writing into a pooled output
+ * buffer (no per-request allocation). Responses use the benchmark wire format
+ * (`{"ok":false,"error":{...}}` + `ratelimit-*` headers) — see AGENTS.md for
+ * why this differs from `createIngressFast`.
+ *
+ * Returns an `OptimizedIngressHandler` whose response-builder methods are
+ * bound to this handler's configuration. Pair it with the route factories
+ * (`readHandler`, `jsonWriteHandler`, ...) or `createIngressServer`.
+ */
+export declare function createIngressHandler(options?: IngressHandlerOptions, runtime?: BakedIngressRuntime): OptimizedIngressHandler;
+/**
+ * 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>);
+/** The runtime hooks + registry for ingress metrics. */
+export interface IngressMetrics {
+	registry: MetricsRegistry;
+	/** Pass as the runtime to `createIngressHandler`. */
+	runtime: Pick<BakedIngressRuntime, "onRequest" | "onResponse" | "onError">;
+	/** Render the Prometheus exposition. */
+	render(): string;
+}
+/**
+ * Build ingress request/error/latency metrics wired to the pre-baked handler
+ * runtime hooks. Metric names follow the Prometheus `castrum_http_*` scheme.
+ */
+export declare function createIngressMetrics(): IngressMetrics;
+/**
+ * Route handler exposing the registry in Prometheus text format
+ * (`content-type: text/plain; version=0.0.4`). Serve it as a `read` route:
+ *
+ *   createIngressServer({ routes: { "/metrics": { read: metricsHandler(m) } } })
+ */
+export declare function metricsHandler(metrics: IngressMetrics): (_req: Request) => Response;
+/** 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;
+}
+/**
+ * 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 createIngressRouter(options: CreateIngressRouterOptions): IngressRouter;
+/**
+ * Synchronous convenience wrapper over `createIngressFast` (path 1).
+ *
+ * The callback runs on the fast-path result and MUST be synchronous. Use
+ * {@link createIngress} when you want automatic body reading + error contexts.
+ */
+export declare function createIngressSync(options?: IngressOptions): SyncIngressHandler;
+/**
+ * Async ingress factory: reads the request body (size guard + deadline) and
+ * returns a snapshot `IngressContext` with a terminal `Response`.
+ *
+ * Recommended default for serverless/edge-style `fetch` handlers. For maximum
+ * throughput use `createIngressFast` / `createIngressSync` directly.
+ */
+export declare function createIngress(options?: IngressOptions): IngressHandler;
+/** Readonly snapshot of the ingress decision, safe after `run()` returns. */
+export interface PipelineResult {
+	readonly ok: boolean;
+	readonly status: number;
+	readonly errorCode: number;
+	readonly terminal: boolean;
+	readonly rateLimited: boolean;
+	readonly bodyValidJson: boolean;
+	readonly schemaValid: boolean;
+	readonly bodyTruncated: boolean;
+	readonly requestId: string;
+	/** The raw request body the pipeline saw (read-only; aliases the request body). */
+	readonly body: Uint8Array;
+	/** The ingress metadata JSON body (when `emitMetadataJson` is on), else empty. */
+	readonly metadataJson: Uint8Array;
+}
+/** Per-request context threaded into the app's handler. */
+export interface PipelineContext {
+	readonly requestId: string;
+	readonly ip: string | undefined;
+	/** 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;
+	readonly response: Response | null;
+	readonly result: PipelineResult | null;
+	readonly ctx: PipelineContext;
+}
+/** Options for `createPipeline`. */
+export interface CreatePipelineOptions {
+	/** Ingress options (same surface as `createIngressHandler`). */
+	options?: IngressHandlerOptions;
+	/** Runtime hooks: onRequest/onResponse/onError, logging, pool sizing. */
+	runtime?: BakedIngressRuntime;
+	/** Body limit for `readBody`/`preprocess`. Default: 1 MiB. */
+	maxBodyBytes?: number;
+	/** Body-read deadline (ms) for `readBody`/`preprocess`. Default: 30s. */
+	bodyTimeoutMs?: number;
+	/**
+	 * When true (default), `preprocess` reads a request body (guarded) so the
+	 * result carries it. Set false when the app handler owns the body.
+	 */
+	readBody?: boolean;
+	/**
+	 * Optional renderer for the OK (non-terminal) case of `handleRequest`.
+	 * Defaults to a minimal `{"ok":true,"requestId":...}` JSON body.
+	 */
+	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;
+	/** Run the pipeline for a middleware/framework. */
+	preprocess(req: Request, ip?: string): Promise<PreprocessOutcome>;
+	/** Fetch-compatible handler: terminal response or the renderer's response. */
+	handleRequest(req: Request, ip?: string): Promise<Response>;
+	/** Stream-read a request body with the configured limits. */
+	readBody(req: Request, maxBytes?: number, timeoutMs?: number): Promise<Uint8Array>;
+}
+/**
+ * Create a framework-agnostic ingress pipeline.
+ *
+ * @example
+ * ```ts
+ * // Plain Bun.serve fetch handler
+ * const pipeline = createPipeline({ options: { parseCookies: true } });
+ * Bun.serve({ port: 3000, fetch: (req) => pipeline.handleRequest(req) });
+ *
+ * // Hono-style middleware: short-circuit on terminal, else handle the app route
+ * app.use("*", async (c, next) => {
+ *   const { terminal, response, ctx } = await pipeline.preprocess(c.req.raw);
+ *   if (terminal && response) return response;
+ *   c.set("ingress", ctx); // pass requestId / locals into the app handler
+ *   await next();
+ * });
+ * ```
+ */
+export declare function createPipeline(opts?: CreatePipelineOptions): IngressPipeline;
+/** One SSE event to frame via `sseResponse` (event/id/retry/data). */ export interface SseEvent {
+	/** Optional `event:` field. */
+	event?: string | null;
+	/** Optional `id:` field. */
+	id?: string | null;
+	/** Optional `retry:` field (ms). */
+	retry?: number | null;
+	/** Event data. */
+	data: string | Uint8Array;
+}
+/**
+ * Build a `text/event-stream` Response from an (async) iterable of events.
+ *
+ * Each event is framed with the native `rust.sseEncodeEvent` (zero-DOM, byte
+ * parity with the FFI primitive), so SSE stays on the fast path:
+ *
+ * @example
+ * ```ts
+ * async function* tick() {
+ *   for (let i = 0; i < 5; i++) {
+ *     await Bun.sleep(250);
+ *     yield { event: "tick", data: String(i) };
+ *   }
+ * }
+ * return sseResponse(tick(), { headers: { "x-request-id": rid } });
+ * ```
+ */
+export declare function sseResponse(events: AsyncIterable<SseEvent> | Iterable<SseEvent>, init?: ResponseInit): Response;
+/** Result kinds supported by the loader (mirrors the packed batch wire shapes). */
+export type LoaderResultKind = "boolean" | "number" | "bigint" | "bytes";
+/** Single-item (scalar) result type for a kind. */
+export type ScalarResult<K extends LoaderResultKind> = K extends "boolean" ? boolean : K extends "number" ? number : K extends "bigint" ? bigint : Uint8Array;
+/** Bulk (array-input) result type for a kind — same shape as `rust.batch.*`. */
+export type BulkResult<K extends LoaderResultKind> = K extends "boolean" ? Uint8Array : K extends "number" ? Uint32Array : K extends "bigint" ? BigInt64Array : Uint8Array[];
+/**
+ * Bulk-result type overrides per op. Bigint ops whose hashes can set the high
+ * bit (e.g. `fnv1a64`) return an UNSIGNED `BigUint64Array` to match the scalar
+ * `rust.<op>`; the default signed `BigInt64Array` stays for sum-style ops.
+ */
+export interface LoaderOpBulkOverride {
+	fnv1a64: BigUint64Array;
+}
+/** Bulk result type of a specific op (per-op override wins). */
+export type LoaderBulk<K extends LoaderOpName> = K extends keyof LoaderOpBulkOverride ? LoaderOpBulkOverride[K] : BulkResult<LoaderOpKind<K>>;
+/** Every op the loader can dispatch. */
+export type LoaderOpName = "crc32" | "fnv1a64" | "jsonValid" | "jsonSumIds" | "validateEmail" | "validateUuid" | "validateIpv4" | "validateIpv6" | "queryParse" | "cookieParse" | "formParse" | "httpParseRequest" | "hexEncode" | "hexDecode" | "base64Encode" | "base64Decode" | "base64UrlEncode" | "base64UrlDecode" | "gzipCompress" | "gzipDecompress" | "brotliCompress" | "brotliDecompress" | "etag" | "urlEncode" | "urlDecode" | "urlDecodeBytes" | "wsAcceptKey" | "mimeFromExtension" | "signCookie" | "verifyCookie" | "csrfVerify" | "passwordHash" | "passwordVerify" | "hmacSha256" | "hmacSha256Verify" | "aeadEncrypt" | "aeadDecrypt" | "jwtSign" | "jwtVerify" | "jsonPatch" | "urlResolve" | "wsFrameEncode" | "sseEncode" | "schemaValidate";
+/** Extra arguments (after the item/items) for each op — the SINGLE call shape. */
+export interface LoaderOpArgs {
+	crc32: [
+	];
+	fnv1a64: [
+	];
+	jsonValid: [
+	];
+	jsonSumIds: [
+	];
+	validateEmail: [
+	];
+	validateUuid: [
+	];
+	validateIpv4: [
+	];
+	validateIpv6: [
+	];
+	queryParse: [
+	];
+	cookieParse: [
+	];
+	formParse: [
+	];
+	httpParseRequest: [
+	];
+	hexEncode: [
+	];
+	hexDecode: [
+	];
+	base64Encode: [
+		urlSafe?: boolean,
+		padding?: boolean
+	];
+	base64Decode: [
+		urlSafe?: boolean,
+		padding?: boolean
+	];
+	base64UrlEncode: [
+	];
+	base64UrlDecode: [
+	];
+	gzipCompress: [
+		level?: number | null
+	];
+	gzipDecompress: [
+	];
+	brotliCompress: [
+		quality?: number | null
+	];
+	brotliDecompress: [
+	];
+	etag: [
+		weak?: boolean | null
+	];
+	urlEncode: [
+	];
+	urlDecode: [
+	];
+	urlDecodeBytes: [
+	];
+	wsAcceptKey: [
+	];
+	mimeFromExtension: [
+	];
+	signCookie: [
+		secret: Uint8Array
+	];
+	/** Boolean-validity op: returns valid/invalid (use `rust.verifyCookie` for the value). */
+	verifyCookie: [
+		secret: Uint8Array
+	];
+	csrfVerify: [
+		secret: Uint8Array
+	];
+	passwordHash: [
+		salt: Uint8Array,
+		options?: PasswordHashOptions | null
+	];
+	passwordVerify: [
+		phc: Uint8Array
+	];
+	hmacSha256: [
+		key: Uint8Array
+	];
+	hmacSha256Verify: [
+		key: Uint8Array,
+		sig: Uint8Array
+	];
+	aeadEncrypt: [
+		key: Uint8Array,
+		nonce: Uint8Array,
+		algorithm?: string | null
+	];
+	aeadDecrypt: [
+		key: Uint8Array,
+		nonce: Uint8Array,
+		algorithm?: string | null
+	];
+	jwtSign: [
+		secret: Uint8Array,
+		ttlSeconds?: number | null,
+		nowSeconds?: number
+	];
+	/** Boolean-validity op: returns valid/invalid (use `rust.jwtVerify` for the payload). */
+	jwtVerify: [
+		secret: Uint8Array,
+		nowSeconds?: number
+	];
+	jsonPatch: [
+		patch: Uint8Array
+	];
+	urlResolve: [
+		base: Uint8Array
+	];
+	wsFrameEncode: [
+		opcode: number,
+		mask: boolean,
+		fin: boolean
+	];
+	sseEncode: [
+		event?: string | null,
+		id?: string | null,
+		retry?: number | null
+	];
+	schemaValidate: [
+		validator: SchemaValidator
+	];
+}
+/**
+ * Extra arguments for the BULK call shape. Paired ops take a per-item
+ * companion ARRAY here; every other op inherits the scalar `LoaderOpArgs`
+ * shape (companions are shared across the batch).
+ */
+export interface LoaderOpBulkArgs {
+	jsonPatch: [
+		patches: Uint8Array[]
+	];
+	hmacSha256Verify: [
+		key: Uint8Array,
+		sigs: Uint8Array[]
+	];
+	passwordVerify: [
+		phcs: Uint8Array[]
+	];
+	urlResolve: [
+		bases: Uint8Array[]
+	];
+}
+/** Bulk call shape for any op (defaults to the scalar shape). */
+export type LoaderBulkArgs<K extends LoaderOpName> = K extends keyof LoaderOpBulkArgs ? LoaderOpBulkArgs[K] : LoaderOpArgs[K];
+declare function boolElem(bulk: unknown, index: number): boolean;
+declare function numElem(bulk: unknown, index: number): number;
+declare function bigElem(bulk: unknown, index: number): bigint;
+declare function byteElem(bulk: unknown, index: number): Uint8Array;
+declare function boolFast(_view: DataView, output: Uint8Array, index: number): boolean;
+declare function bitsetOutSize(count: number): number;
+declare function u32Fast(view: DataView, _output: Uint8Array, index: number): number;
+declare function u32OutSize(count: number): number;
+declare function i64Fast(view: DataView, _output: Uint8Array, index: number): bigint;
+declare function u64Fast(view: DataView, _output: Uint8Array, index: number): bigint;
+declare function i64OutSize(count: number): number;
+/**
+ * Registry — single source of truth for loader-op wiring. Every op must have
+ * a scalar variant and a packed batch variant; ops whose scalar returns
+ * something other than the bulk element (e.g. `jwtVerify` returning the
+ * decoded payload, `verifyCookie` returning the value) are deliberately
+ * EXCLUDED so single and bulk semantics stay identical.
+ */
+export declare const LOADER_OPS: {
+	readonly crc32: {
+		readonly kind: "number";
+		readonly scalar: (i: Uint8Array) => number;
+		readonly batch: (items: Uint8Array[]) => Uint32Array<ArrayBufferLike>;
+		readonly element: typeof numElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof u32Fast;
+			readonly outSize: typeof u32OutSize;
+		};
+	};
+	readonly fnv1a64: {
+		readonly kind: "bigint";
+		readonly unsigned: true;
+		readonly scalar: (i: Uint8Array) => bigint;
+		readonly batch: (items: Uint8Array[]) => BigUint64Array<ArrayBufferLike>;
+		readonly element: typeof bigElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof u64Fast;
+			readonly outSize: typeof i64OutSize;
+		};
+	};
+	readonly jsonValid: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof boolFast;
+			readonly outSize: typeof bitsetOutSize;
+		};
+	};
+	readonly jsonSumIds: {
+		readonly kind: "bigint";
+		readonly scalar: (i: Uint8Array) => bigint;
+		readonly batch: (items: Uint8Array[]) => BigInt64Array<ArrayBufferLike>;
+		readonly element: typeof bigElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof i64Fast;
+			readonly outSize: typeof i64OutSize;
+		};
+	};
+	readonly validateEmail: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof boolFast;
+			readonly outSize: typeof bitsetOutSize;
+		};
+	};
+	readonly validateUuid: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof boolFast;
+			readonly outSize: typeof bitsetOutSize;
+		};
+	};
+	readonly validateIpv4: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof boolFast;
+			readonly outSize: typeof bitsetOutSize;
+		};
+	};
+	readonly validateIpv6: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+		readonly fast: {
+			readonly batch: (packed: Uint8Array<ArrayBufferLike>, output: Uint8Array<ArrayBufferLike>) => number;
+			readonly element: typeof boolFast;
+			readonly outSize: typeof bitsetOutSize;
+		};
+	};
+	readonly queryParse: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly cookieParse: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly formParse: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly httpParseRequest: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly hexEncode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly hexDecode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly base64Encode: {
+		readonly kind: "bytes";
+		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;
+	};
+	readonly base64Decode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, urlSafe?: boolean, padding?: boolean) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], urlSafe?: boolean, padding?: boolean) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly base64UrlEncode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly base64UrlDecode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly gzipCompress: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, level?: number | null) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], level?: number | null) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly gzipDecompress: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly brotliCompress: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, quality?: number | null) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], quality?: number | null) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly brotliDecompress: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly etag: {
+		readonly kind: "bytes";
+		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) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly urlDecode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly urlDecodeBytes: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly wsAcceptKey: {
+		readonly kind: "bytes";
+		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) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly signCookie: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, secret: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], secret: Uint8Array) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly verifyCookie: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array, secret: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[], secret: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+	};
+	readonly csrfVerify: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array, secret: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[], secret: Uint8Array) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+	};
+	readonly passwordHash: {
+		readonly kind: "bytes";
+		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;
+	};
+	readonly passwordVerify: {
+		readonly kind: "boolean";
+		readonly pairedRest: [
+			0
+		];
+		readonly scalar: (i: Uint8Array, phc: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[], phcs: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+	};
+	readonly aeadEncrypt: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], key: Uint8Array, nonce: Uint8Array, algorithm?: string | null) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly aeadDecrypt: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], key: Uint8Array, nonce: Uint8Array, algorithm?: string | null) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly jwtSign: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], secret: Uint8Array, ttlSeconds?: number | null, nowSeconds?: number) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly jwtVerify: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array, secret: Uint8Array, nowSeconds?: number) => boolean;
+		readonly batch: (items: Uint8Array[], secret: Uint8Array, nowSeconds?: number) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+	};
+	readonly jsonPatch: {
+		readonly kind: "bytes";
+		readonly pairedRest: [
+			0
+		];
+		readonly scalar: (i: Uint8Array, patch: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], patches: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly urlResolve: {
+		readonly kind: "bytes";
+		readonly pairedRest: [
+			0
+		];
+		readonly scalar: (i: Uint8Array, base: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], bases: Uint8Array[]) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly wsFrameEncode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, opcode: number, mask: boolean, fin: boolean) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], opcode: number, mask: boolean, fin: boolean) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly sseEncode: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, event?: string | null, id?: string | null, retry?: number | null) => Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], event?: string | null, id?: string | null, retry?: number | null) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly schemaValidate: {
+		readonly kind: "boolean";
+		readonly scalar: (i: Uint8Array, validator: SchemaValidator) => boolean;
+		readonly batch: (items: Uint8Array[], validator: SchemaValidator) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+	};
+	readonly hmacSha256: {
+		readonly kind: "bytes";
+		readonly scalar: (i: Uint8Array, key: Uint8Array) => string | Uint8Array<ArrayBufferLike>;
+		readonly batch: (items: Uint8Array[], key: Uint8Array) => Uint8Array<ArrayBufferLike>[];
+		readonly element: typeof byteElem;
+	};
+	readonly hmacSha256Verify: {
+		readonly kind: "boolean";
+		readonly pairedRest: [
+			1
+		];
+		readonly scalar: (i: Uint8Array, key: Uint8Array, sig: Uint8Array) => boolean;
+		readonly batch: (items: Uint8Array[], key: Uint8Array, sigs: Uint8Array[]) => Uint8Array<ArrayBufferLike>;
+		readonly element: typeof boolElem;
+	};
+};
+/** Kind of a specific op. */
+export type LoaderOpKind<K extends LoaderOpName> = (typeof LOADER_OPS)[K]["kind"];
+/** Single-item result type of a specific op. */
+export type LoaderScalar<K extends LoaderOpName> = ScalarResult<LoaderOpKind<K>>;
+/** All op names, as a readonly array (for iteration). */
+export declare const LOADER_OP_NAMES: LoaderOpName[];
+/** Options for `createLoader()` / `loader.configure()`. */
+export interface LoaderOptions {
+	/** Let each op adapt `batchMin` from measured dispatch cost. Default true. */
+	adaptive?: boolean;
+	/** Initial batch threshold in [2, 8]. Default 2 (batch wins for n >= 2). */
+	batchMin?: number;
+	/** Max cached keys (bounded LRU). 0 disables caching. Default 256. */
+	maxCacheKeys?: number;
+	/** Default `cache` behavior for `load()`. Default true. */
+	caching?: boolean;
+	/** Sample timing every N dispatches (hot-path cost control). Default 32. */
+	sampleEvery?: number;
+	/**
+	 * `load()` dispatch strategy. `"auto"` (default) switches each op between
+	 * `"single"` (low load → direct scalar call, no coalescer) and
+	 * `"coalesce"` (rising load → one packed batch call) from observed load.
+	 */
+	loadStrategy?: LoadStrategy;
+}
+/** Options for `load()` / `opFn.load()`. */
+export interface LoadOptions {
+	/**
+	 * Explicit cache key. When omitted (and caching is on) the default key is
+	 * `fnv1a64(input)` — which costs one extra native call per load.
+	 */
+	key?: string;
+	/** Override the loader-wide caching toggle for this call. Default true. */
+	cache?: boolean;
+}
+/** Per-op counters exposed on `opFn.stats`. */
+export interface LoaderOpStats {
+	scalarCalls: number;
+	batchCalls: number;
+	itemsDispatched: number;
+	cachedHits: number;
+	/** Current learned batch threshold for this op. */
+	batchMin: number;
+	/** Current `load()` strategy: "single" (low load) or "coalesce" (bulk). */
+	mode: "single" | "coalesce";
+}
+/** Aggregate loader statistics. */
+export interface LoaderStats {
+	scalarCalls: number;
+	batchCalls: number;
+	itemsDispatched: number;
+	flushes: number;
+	cachedHits: number;
+	cacheSize: number;
+	cacheEvictions: number;
+}
+/** A specialized, pre-bound op function returned by `loader(op)`. */
+export interface LoaderOpFn<K extends LoaderOpName> {
+	/** Single item → scalar result. */
+	(input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>;
+	/** Bulk items → ONE packed batch call; same shape as `rust.batch.<op>`. */
+	(inputs: Uint8Array[], ...rest: LoaderBulkArgs<K>): LoaderBulk<K>;
+	readonly name: K;
+	readonly stats: LoaderOpStats;
+	clear(): void;
+	/** Sync cache peek (default key `fnv1a64(input)` unless `key` given). */
+	cache(input: Uint8Array, key?: string): LoaderScalar<K> | undefined;
+	/**
+	 * Coalesced, cache-aware load. Unavailable (`undefined`) on ops that require
+	 * extra arguments (e.g. `hmacSha256`, `signCookie`) — use `run` for those.
+	 */
+	load: K extends LoadableName ? LoaderLoadFn<K> : undefined;
+}
+export type LoaderLoadFn<K extends LoaderOpName> = (input: Uint8Array, opts?: LoadOptions) => Promise<LoaderScalar<K>>;
+/** Ops whose extra args are all optional/empty → they support `load()`. */
+export type LoadableName = {
+	[K in LoaderOpName]: LoaderOpArgs[K] extends [
+	] | [
+		unknown?
+	] | [
+		unknown?,
+		unknown?
+	] | [
+		unknown?,
+		unknown?,
+		unknown?
+	] ? K : never;
+}[LoaderOpName];
+/** A validator-bound helper returned by `loader.schema(validator)`. */
+export interface LoaderSchemaFn {
+	/** Single JSON document → valid? */
+	(input: Uint8Array): boolean;
+	/** Bulk JSON documents → bitset (1 per doc). */
+	(inputs: Uint8Array[]): Uint8Array;
+	/** Count how many bulk documents are valid. */
+	count(inputs: Uint8Array[]): number;
+}
+/** The global callable loader. */
+interface Loader$1 {
+	/** Higher-order function: `loader(op)` → specialized hot op function. */
+	<K extends LoaderOpName>(op: K): LoaderOpFn<K>;
+	/** Single-item dispatch. */
+	run<K extends LoaderOpName>(op: K, input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>;
+	/** Bulk dispatch (one packed batch call, or adaptive scalar loop). */
+	run<K extends LoaderOpName>(op: K, inputs: Uint8Array[], ...rest: LoaderBulkArgs<K>): LoaderBulk<K>;
+	/** Coalesced, cache-aware load (ops with required extra args throw). */
+	load<K extends LoadableName>(op: K, input: Uint8Array, opts?: LoadOptions): Promise<LoaderScalar<K>>;
+	/** Sync cache peek. */
+	cache<K extends LoaderOpName>(op: K, input: Uint8Array, key?: string): LoaderScalar<K> | undefined;
+	/**
+	 * Bind a `SchemaValidator` for repeated single/bulk JSON-schema validation
+	 * plus a whole-batch `count`. The returned callable uses the loader's normal
+	 * dispatch machinery (cost model + counters).
+	 */
+	schema(validator: SchemaValidator): LoaderSchemaFn;
+	/** Clear the shared cache (pending coalesced loads still flush). */
+	clear(): void;
+	/** Update options at runtime. */
+	configure(options: LoaderOptions): void;
+	readonly stats: LoaderStats;
+	readonly opNames: LoaderOpName[];
+}
+/** Load-dispatch strategy selector for `load()`. */
+export type LoadStrategy = "auto" | "single" | "coalesce";
+/** Create an isolated loader with the given defaults. */
+export declare function createLoader(options?: LoaderOptions): Loader$1;
+/**
+ * The global, ready-to-use loader. Most consumers just do
+ * `import { loader } from "castrum"` and either `loader("validateEmail")(…)`
+ * (higher-order function) or `loader.run("validateEmail", …)`.
+ */
+export declare const loader: Loader$1;
+/**
+ * Batch-validate JSON documents against a schema through the loader's bulk
+ * `schemaValidate` path. Returns a bitset — byte `i` is 1 when document `i`
+ * is valid (same shape as `rust.batch.schemaValidate`).
+ */
+export declare function validateMany(validator: SchemaValidator, docs: Uint8Array[]): Uint8Array;
+/** Count how many of `docs` validate against `validator` (one packed call). */
+export declare function validateCount(validator: SchemaValidator, docs: Uint8Array[]): number;
+/**
+ * Generic loader bulk dispatch: `loader.run(op, items, ...rest)` → one packed
+ * batch native call (or the adaptive scalar loop for tiny batches).
+ */
+export declare function runMany<K extends LoaderOpName>(op: K, items: Uint8Array[], ...rest: LoaderBulkArgs<K>): LoaderBulk<K>;
+/** Single-item loader dispatch — pairs with `runMany` for mixed workloads. */
+export declare function runOne<K extends LoaderOpName>(op: K, item: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>;
+
+export {
+	Loader$1 as Loader,
+	RouteHandler as IngressNodeRouteHandler,
+};
+
+export {};