castrum 0.9.2 → 0.9.4

package/dist/index.d.ts

@@ -1,285 +1,150 @@
 // 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;
+/** Route descriptor magic (`"ROUT"` LE). Must match `ROUTE_DESC_MAGIC` in Rust. */
+export declare const ROUTE_DESC_MAGIC = 1380930900;
+/** Wire version — bump on ANY descriptor/frame/result layout change. */
+export declare const ROUTE_DESC_VERSION = 3;
+/** Descriptor stage tags (the ordered pipeline a route instance runs). */
+export declare const ROUTE_STAGE: {
+	readonly parseQuery: 0;
+	readonly parseCookies: 1;
+	readonly validateQuery: 2;
+	readonly validateCookies: 3;
+	readonly validateBody: 4;
+	readonly requireJsonBody: 5;
+};
+/** A descriptor stage tag (`ROUTE_STAGE` values, must match Rust). */
+export type RouteStageTag = (typeof ROUTE_STAGE)[keyof typeof ROUTE_STAGE];
+/** Descriptor part tags (`RoutePartKind`): the schema-bearing request parts. */
+export declare const ROUTE_PART: {
+	readonly body: 3;
+};
+/** Result flag bits (`ROUTE_RESULT_FLAG_*` in Rust). */
+export declare const ROUTE_FLAG: {
+	readonly OK: number;
+	readonly BODY_VALID_JSON: number;
+	readonly QUERY_VALID: number;
+	readonly COOKIE_VALID: number;
+	readonly BODY_VALID: number;
+};
+/** Frame flag: the body section is present (bit 0 of the frame flags word). */
+export declare const ROUTE_FRAME_FLAG_HAS_BODY: number;
+/** Size limits a route descriptor carries. */
+export interface RouteWireLimits {
+	maxBodyBytes: number;
+	maxQueryBytes: number;
+	maxCookieBytes: number;
+	maxPairs: number;
 }
-/** One parsed Accept-Encoding preference. */
-export interface EncodingPrefResult {
-	encoding: string;
-	q: number;
-	order: number;
+/** A schema part carried by the descriptor (part tag + draft-07 JSON bytes). */
+export interface RouteWireSchema {
+	part: number;
+	bytes: Uint8Array;
 }
 /**
- * The native `AcceptNegotiator` class instance (supported encodings compiled
- * once). Best supported encoding for a header, or `null` for identity.
+ * Encode a route plan into the descriptor wire.
+ *
+ * Layout: `[magic u32][version u32][maxBody u32][maxQuery u32][maxCookie u32]
+ * [maxPairs u32][stageCount u32][stages u8…][schemaCount u32]
+ * { [part u8][len u32][schema] }…`
  */
-export interface AcceptNegotiatorInstance {
-	/** Best supported encoding for `header`, or null for identity. */
-	negotiate(header: Uint8Array): string | null;
-	/** Best supported encoding for `header` with SERVER-preference tie-breaking
-	 * (RFC 7231 server semantics — the supported list's order breaks q-value
-	 * ties), or null for identity. On the napi fallback this is the projected
-	 * `negotiate_server_preference` method. */
-	negotiateServerPreference(header: Uint8Array): string | null;
-	/** Opaque handle (bun:ffi fast path) — `castrum_accept_negotiator_negotiate`. */
-	innerPtr?(): bigint;
+export declare function encodeRouteDescriptor(pipeline: readonly RouteStageTag[], schemas: readonly RouteWireSchema[], limits: RouteWireLimits): Uint8Array;
+/**
+ * Encode a request frame: `[flags u32][qLen][query][cLen][cookie]([bLen][body])`.
+ * The `flags` word currently only carries `ROUTE_FRAME_FLAG_HAS_BODY`.
+ */
+export declare function packRouteFrame(query: string, cookie: string, body: Uint8Array | null): Uint8Array;
+/** A decoded `[name, value]` pair from a result section. */
+export type RouteWirePair = [
+	string,
+	string
+];
+/** The decoded route result: the verdict header + optional pair sections. */
+export interface RouteWireResult {
+	/** `ROUTE_FLAG_*` bits from the result header. */
+	flags: number;
+	/** `0` = ok; `400` = not-JSON under requireJsonBody; `422` = schema fail. */
+	errorCode: number;
+	/** Decoded query pairs (present iff the plan compiled `parseQuery`). */
+	query: RouteWirePair[];
+	/** Decoded cookie pairs (present iff the plan compiled `parseCookies`). */
+	cookie: RouteWirePair[];
 }
-/** The native `Base64Codec` class instance (config compiled once). */
-export interface Base64CodecInstance {
-	encode(input: Uint8Array): Uint8Array;
-	decode(input: Uint8Array): Uint8Array;
+/**
+ * Decode the result wire: `[flags u32][errorCode u32]` + a query pair section
+ * iff `query` and a cookie pair section iff `cookie` (the caller knows its own
+ * plan). Sections are `[count u32] { [nameLen u32][name][valueLen u32][value] }`.
+ */
+export declare function decodeRouteResult(buf: Uint8Array, opts: {
+	query: boolean;
+	cookie: boolean;
+}): RouteWireResult;
+/** Plan for a compiled native route (the stage/limit/schema surface). */
+export interface NativeRoutePlan {
+	/** Parse + lenient-decode the query string into pairs (stage 0). */
+	parseQuery?: boolean;
+	/** Parse + lenient-decode the Cookie header into pairs (stage 1). */
+	parseCookies?: boolean;
+	/** Reject a missing / non-JSON body with 400 (stage 5, first-failure-wins). */
+	requireJsonBody?: boolean;
+	/** Validate the body against `schema` with 422 on failure (stage 4). */
+	validateBody?: boolean;
+	/** Draft-07 JSON schema bytes for the body (`validateBody`). */
+	schema?: Uint8Array;
+	/** Max body bytes before `requireJsonBody`/`validateBody` fail (default 2 MiB). */
+	maxBodyBytes?: number;
+	/** Max query bytes before the parse VALID bit clears (default 8192). */
+	maxQueryBytes?: number;
+	/** Max cookie bytes before the parse VALID bit clears (default 8192). */
+	maxCookieBytes?: number;
+	/** Max pairs per section (0 = unlimited; default 0). */
+	maxPairs?: number;
 }
-/** Result of a native rate-limit check for one key at a point in time. */
-export interface RateCheckResult {
-	allowed: boolean;
-	remaining: number;
-	resetMs: number;
+/** A compiled per-route native stack (route-wire v3). */
+export interface NativeRoute {
+	/** Whether the plan compiled `parseQuery` (the result carries a query section). */
+	readonly parseQuery: boolean;
+	/** Whether the plan compiled `parseCookies` (the result carries a cookie section). */
+	readonly parseCookies: boolean;
+	/**
+	 * Run one request frame through the compiled stack and return the decoded
+	 * verdict. The frame is `[flags u32][qLen][query][cLen][cookie]([bLen][body])`
+	 * — build it with {@link packRouteFrame}. Reuses one growable output buffer
+	 * (the needed-size convention: `0` = real error → throws; `> out.length` =
+	 * exact required size → retry once).
+	 */
+	runFrame(frame: Uint8Array): RouteWireResult;
+	/** Convenience: pack a `(query, cookie, body)` frame then {@link runFrame}. */
+	run(query: string, cookie: string, body: Uint8Array | null): RouteWireResult;
+	/** Free the native handle (idempotent; safe to call once at shutdown). */
+	destroy(): void;
 }
-/** 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;
+/**
+ * Compile a per-route native stack from a plan. Returns a compiled route whose
+ * `run`/`runFrame` perform the parse + verdict in ONE native call.
+ *
+ * @example
+ * ```ts
+ * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
+ * const result = route.run('page=1&limit=20', 'session=abc', null)
+ * // result.flags & ROUTE_FLAG.OK → parse succeeded; result.query = [['page','1'],…]
+ * ```
+ */
+export declare function createNativeRoute(plan?: NativeRoutePlan): NativeRoute;
+/** 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). */
@@ -356,6 +221,23 @@ export declare class BakedIngressResult extends IngressResultBase {
 	setInternalError(): void;
 	bodyJson(copy: boolean): Uint8Array;
 }
+/** Zero-alloc, lazy-decoding view over a native Ingress output buffer. */
+export declare class FastIngressResult extends IngressResultBase {
+	status: number;
+	verdict: number;
+	errorCode: number;
+	flags: number;
+	https: boolean;
+	hasCookies: boolean;
+	hasQuery: boolean;
+	rateLimit: number;
+	requestId: string;
+	refresh(buf: Uint8Array, body: Uint8Array, requestId: string): void;
+	invalidate(): void;
+	setInternalError(requestId: string): void;
+	/** Bounds-checked body-JSON section, or an empty view when absent. */
+	bodyJson(): Uint8Array;
+}
 /** User-facing CORS configuration. */
 export interface CorsOptions {
 	allowOrigin?: string[];
@@ -389,23 +271,6 @@ export interface SecurityHeadersOptions {
 	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;
@@ -656,141 +521,10 @@ export interface BakedHandlerOptions {
 	 */
 	enableLoader?: boolean;
 }
-/** Route descriptor magic (`"ROUT"` LE). Must match `ROUTE_DESC_MAGIC` in Rust. */
-export declare const ROUTE_DESC_MAGIC = 1380930900;
-/** Wire version — bump on ANY descriptor/frame/result layout change. */
-export declare const ROUTE_DESC_VERSION = 3;
-/** Descriptor stage tags (the ordered pipeline a route instance runs). */
-export declare const ROUTE_STAGE: {
-	readonly parseQuery: 0;
-	readonly parseCookies: 1;
-	readonly validateQuery: 2;
-	readonly validateCookies: 3;
-	readonly validateBody: 4;
-	readonly requireJsonBody: 5;
-};
-/** A descriptor stage tag (`ROUTE_STAGE` values, must match Rust). */
-export type RouteStageTag = (typeof ROUTE_STAGE)[keyof typeof ROUTE_STAGE];
-/** Descriptor part tags (`RoutePartKind`): the schema-bearing request parts. */
-export declare const ROUTE_PART: {
-	readonly body: 3;
-};
-/** Result flag bits (`ROUTE_RESULT_FLAG_*` in Rust). */
-export declare const ROUTE_FLAG: {
-	readonly OK: number;
-	readonly BODY_VALID_JSON: number;
-	readonly QUERY_VALID: number;
-	readonly COOKIE_VALID: number;
-	readonly BODY_VALID: number;
-};
-/** Frame flag: the body section is present (bit 0 of the frame flags word). */
-export declare const ROUTE_FRAME_FLAG_HAS_BODY: number;
-/** Size limits a route descriptor carries. */
-export interface RouteWireLimits {
-	maxBodyBytes: number;
-	maxQueryBytes: number;
-	maxCookieBytes: number;
-	maxPairs: number;
-}
-/** A schema part carried by the descriptor (part tag + draft-07 JSON bytes). */
-export interface RouteWireSchema {
-	part: number;
-	bytes: Uint8Array;
-}
-/**
- * Encode a route plan into the descriptor wire.
- *
- * Layout: `[magic u32][version u32][maxBody u32][maxQuery u32][maxCookie u32]
- * [maxPairs u32][stageCount u32][stages u8…][schemaCount u32]
- * { [part u8][len u32][schema] }…`
- */
-export declare function encodeRouteDescriptor(pipeline: readonly RouteStageTag[], schemas: readonly RouteWireSchema[], limits: RouteWireLimits): Uint8Array;
-/**
- * Encode a request frame: `[flags u32][qLen][query][cLen][cookie]([bLen][body])`.
- * The `flags` word currently only carries `ROUTE_FRAME_FLAG_HAS_BODY`.
- */
-export declare function packRouteFrame(query: string, cookie: string, body: Uint8Array | null): Uint8Array;
-/** A decoded `[name, value]` pair from a result section. */
-export type RouteWirePair = [
-	string,
-	string
-];
-/** The decoded route result: the verdict header + optional pair sections. */
-export interface RouteWireResult {
-	/** `ROUTE_FLAG_*` bits from the result header. */
-	flags: number;
-	/** `0` = ok; `400` = not-JSON under requireJsonBody; `422` = schema fail. */
-	errorCode: number;
-	/** Decoded query pairs (present iff the plan compiled `parseQuery`). */
-	query: RouteWirePair[];
-	/** Decoded cookie pairs (present iff the plan compiled `parseCookies`). */
-	cookie: RouteWirePair[];
-}
-/**
- * Decode the result wire: `[flags u32][errorCode u32]` + a query pair section
- * iff `query` and a cookie pair section iff `cookie` (the caller knows its own
- * plan). Sections are `[count u32] { [nameLen u32][name][valueLen u32][value] }`.
- */
-export declare function decodeRouteResult(buf: Uint8Array, opts: {
-	query: boolean;
-	cookie: boolean;
-}): RouteWireResult;
-/** Plan for a compiled native route (the stage/limit/schema surface). */
-export interface NativeRoutePlan {
-	/** Parse + lenient-decode the query string into pairs (stage 0). */
-	parseQuery?: boolean;
-	/** Parse + lenient-decode the Cookie header into pairs (stage 1). */
-	parseCookies?: boolean;
-	/** Reject a missing / non-JSON body with 400 (stage 5, first-failure-wins). */
-	requireJsonBody?: boolean;
-	/** Validate the body against `schema` with 422 on failure (stage 4). */
-	validateBody?: boolean;
-	/** Draft-07 JSON schema bytes for the body (`validateBody`). */
-	schema?: Uint8Array;
-	/** Max body bytes before `requireJsonBody`/`validateBody` fail (default 2 MiB). */
-	maxBodyBytes?: number;
-	/** Max query bytes before the parse VALID bit clears (default 8192). */
-	maxQueryBytes?: number;
-	/** Max cookie bytes before the parse VALID bit clears (default 8192). */
-	maxCookieBytes?: number;
-	/** Max pairs per section (0 = unlimited; default 0). */
-	maxPairs?: number;
-}
-/** A compiled per-route native stack (route-wire v3). */
-export interface NativeRoute {
-	/** Whether the plan compiled `parseQuery` (the result carries a query section). */
-	readonly parseQuery: boolean;
-	/** Whether the plan compiled `parseCookies` (the result carries a cookie section). */
-	readonly parseCookies: boolean;
-	/**
-	 * Run one request frame through the compiled stack and return the decoded
-	 * verdict. The frame is `[flags u32][qLen][query][cLen][cookie]([bLen][body])`
-	 * — build it with {@link packRouteFrame}. Reuses one growable output buffer
-	 * (the needed-size convention: `0` = real error → throws; `> out.length` =
-	 * exact required size → retry once).
-	 */
-	runFrame(frame: Uint8Array): RouteWireResult;
-	/** Convenience: pack a `(query, cookie, body)` frame then {@link runFrame}. */
-	run(query: string, cookie: string, body: Uint8Array | null): RouteWireResult;
-	/** Free the native handle (idempotent; safe to call once at shutdown). */
-	destroy(): void;
-}
-/**
- * Compile a per-route native stack from a plan. Returns a compiled route whose
- * `run`/`runFrame` perform the parse + verdict in ONE native call.
- *
- * @example
- * ```ts
- * const route = createNativeRoute({ parseQuery: true, parseCookies: true })
- * const result = route.run('page=1&limit=20', 'session=abc', null)
- * // result.flags & ROUTE_FLAG.OK → parse succeeded; result.query = [['page','1'],…]
- * ```
- */
-export declare function createNativeRoute(plan?: NativeRoutePlan): NativeRoute;
-/** A matched dynamic route: the handler map + the extracted path params. */
-export interface PathMatch {
-	methods: Record<string, unknown>;
-	params: Record<string, string>;
+/** A matched dynamic route: the handler map + the extracted path params. */
+export interface PathMatch {
+	methods: Record<string, unknown>;
+	params: Record<string, string>;
 }
 /** A raw web-standard route handler (`Request` → `Response`), e.g. the
  *  health/metrics probes (`livenessHandler`, `readinessHandler`,
@@ -986,675 +720,265 @@ export interface WebSocketUpgradeResult {
  * ```
  */
 export declare function createWebSocketUpgrade(req: Request, opts?: WebSocketUpgradeOptions): WebSocketUpgradeResult | null;
-/** Options accepted by `createRust` / `rust.configure`. */
-export interface RustOptions {
+/**
+ * The native `MetricsRegistry` class instance — sharded counters / gauges /
+ * histograms with a Prometheus text-format render. Series are declared once
+ * (`counter`/`gauge`/`histogram` return a reusable id); per-event updates
+ * take the id + the label values for that event.
+ */
+export interface MetricsRegistryInstance {
+	/** Declare a counter family → its series id (idempotent per shape). */
+	counter(name: string, labelKeys?: string[]): number;
+	/** Declare a gauge family → its series id (idempotent per shape). */
+	gauge(name: string, labelKeys?: string[]): number;
+	/**
+	 * Declare a histogram family → its series id. Omitted/empty `buckets`
+	 * selects the default latency buckets.
+	 */
+	histogram(name: string, labelKeys?: string[], buckets?: number[]): number;
+	/** Counter/gauge `+= amount`, or histogram observe `amount`. */
+	record(series: number, values?: string[], amount?: number): void;
+	/** Gauge assignment (`= value`). */
+	gaugeSet(series: number, values: string[] | undefined, value: number): void;
+	/** Render the Prometheus text exposition format (deterministic order). */
+	render(): string;
 	/**
-	 * Rayon thread pool size.
+	 * Packed v1 series snapshot bytes (families then series — see the Rust
+	 * registry docs). bun:ffi-backed wrappers only; napi exposes
+	 * `MetricsRegistry.snapshot()` directly.
+	 */
+	snapshot?(): Uint8Array;
+	/** Number of live series (tests / introspection; napi transport only). */
+	seriesCount?(): number;
+	/** Free the native handle (bun:ffi-backed wrappers only). */
+	destroy?(): void;
+}
+/** 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.
 	 *
-	 * 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).
+	 * `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.
 	 */
-	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;
+	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 `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.
+ * The native `AcceptNegotiator` class instance (supported encodings compiled
+ * once). Best supported encoding for a header, or `null` for identity.
  */
-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[];
+export interface AcceptNegotiatorInstance {
+	/** Best supported encoding for `header`, or null for identity. */
+	negotiate(header: Uint8Array): string | null;
+	/** Best supported encoding for `header` with SERVER-preference tie-breaking
+	 * (RFC 7231 server semantics — the supported list's order breaks q-value
+	 * ties), or null for identity. On the napi fallback this is the projected
+	 * `negotiate_server_preference` method. */
+	negotiateServerPreference(header: Uint8Array): string | null;
+	/** Opaque handle (bun:ffi fast path) — `castrum_accept_negotiator_negotiate`. */
+	innerPtr?(): bigint;
 }
-/** Raw packed-wire FFI namespace. */
-export interface RustPacked {
-	/** Packed CRC32 batch: packed `[u8[]]` items → packed u32 results. */
-	crc32BatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed JSON-validity batch: packed `[u8[]]` items → packed 0/1 bitset. */
-	jsonValidBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed email-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
-	validateEmailBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed UUID-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
-	validateUuidBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed IPv4-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
-	validateIpv4BatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed IPv6-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
-	validateIpv6BatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed JSON-sum batch: packed `[{id}]` docs → packed `[ok u8][sum i64 LE]`. */
-	jsonSumBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed query-string parser batch: packed `[u8[]]` queries → packed pair lists. */
-	queryParseBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed cookie-header parser batch: packed `[u8[]]` headers → packed pair lists. */
-	cookieParseBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed HTTP-request parser batch: packed `[u8[]]` requests → packed request sections. */
-	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;
-	/** Packed percent-encoding batch: packed `[u8[]]` items → packed hex-percent bytes. */
-	urlEncodeBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed percent-decoding batch: packed `[u8[]]` items → packed decoded bytes (string-safe). */
-	urlDecodeBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed percent-decoding batch returning raw bytes (`%FF` preserved). */
-	urlDecodeBytesBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed MIME-lookup batch: packed `[u8[]]` extensions → packed media-type strings. */
-	mimeFromExtensionBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed WebSocket accept-key batch: packed `[u8[]]` keys → packed base64 SHA-1 results. */
-	wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array;
-	/** Valid JSON count in a packed JSON batch (0..n; invalid items not counted). */
-	jsonValidBatchCountPacked(input: Uint8Array): number;
-	/** Valid-email count in a packed email batch. */
-	validateEmailBatchCountPacked(input: Uint8Array): number;
-	/** Valid-UUID count in a packed UUID batch. */
-	validateUuidBatchCountPacked(input: Uint8Array): number;
-	/** Valid-IPv4 count in a packed IPv4 batch. */
-	validateIpv4BatchCountPacked(input: Uint8Array): number;
-	/** Valid-IPv6 count in a packed IPv6 batch. */
-	validateIpv6BatchCountPacked(input: Uint8Array): number;
-	/** Total `id` sum across a packed JSON batch (valid items only). */
-	jsonSumBatchTotalPacked(input: Uint8Array): number;
-	/** Total packed-output length (bytes) a query batch will produce. */
-	queryParseBatchTotalLenPacked(input: Uint8Array): number;
-	/** Total packed-output length (bytes) a cookie batch will produce. */
-	cookieParseBatchTotalLenPacked(input: Uint8Array): number;
-	/** Total packed-output length (bytes) an HTTP-request batch will produce. */
-	httpParseRequestBatchTotalLenPacked(input: Uint8Array): number;
-	/** Packed Argon2id-hash batch: packed `[u8[]]` passwords + shared salt → packed PHC strings. */
-	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;
-	/** Packed AEAD-encrypt batch (packed inputs + shared key/nonce) → packed ciphertexts. */
-	aeadEncryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
-	/** Packed AEAD-decrypt batch (packed inputs + shared key/nonce) → packed plaintexts. */
-	aeadDecryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
-	/** Packed gzip-compress batch: packed `[u8[]]` items → packed gzip streams. */
-	gzipCompressBatchPacked(input: Uint8Array, level?: number | null): Uint8Array;
-	/** Packed gzip-decompress batch (64 MiB cap per item) → packed plaintexts. */
-	gzipDecompressBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed brotli-compress batch: packed `[u8[]]` items → packed brotli streams. */
-	brotliCompressBatchPacked(input: Uint8Array, quality?: number | null): Uint8Array;
-	/** Packed brotli-decompress batch (64 MiB cap per item) → packed plaintexts. */
-	brotliDecompressBatchPacked(input: Uint8Array): Uint8Array;
-	/** Packed HS256 JWT-sign batch (packed claims + shared secret) → packed tokens. */
-	jwtSignBatchPacked(input: Uint8Array, secret: Uint8Array, ttlSeconds: number | null, nowSeconds: number): Uint8Array;
-	/** Packed HS256 JWT-verify batch (packed tokens + shared secret) → packed claims/validity. */
-	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;
-	/** Packed multipart/form-data parser batch (packed bodies + shared boundary) → packed parts. */
-	multipartParseBatchPacked(input: Uint8Array, boundary: Uint8Array): Uint8Array;
-	/** Packed minijinja template batch: packed contexts + shared source → packed renders. */
-	templateRenderBatchPacked(input: Uint8Array, source: string): Uint8Array;
-	/** Packed SSE-frame batch: packed data + shared event/id/retry → packed frames. */
-	sseEncodeBatchPacked(input: Uint8Array, event: string | null, id: string | null, retry: number | null): Uint8Array;
-	/** Packed WebSocket-frame encode batch: packed payloads + shared opcode/mask/fin → packed frames. */
-	wsFrameEncodeBatchPacked(input: Uint8Array, opcode: number, mask: boolean, fin: boolean): Uint8Array;
-	/** Packed WebSocket-frame decode batch: packed frames → packed (fin, opcode, payload) results. */
-	wsFrameDecodeBatchPacked(input: Uint8Array): Uint8Array;
+/** 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;
 }
 /**
- * The flat `rust.*` scalar method surface: bytes in → normalized out. Built by
- * the scalar builders from the native addon + Bun built-in delegations.
+ * 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 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;
-}
+export declare function createIngressServer(options: CreateIngressServerOptions): BakedServer;
 /**
- * Create an isolated Rust client with the given defaults.
+ * Generate the next request ID as 16 lowercase hex bytes (zero-alloc).
  *
- * `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.
+ * @returns A shared buffer aliased across calls — decode/copy before the next
+ *   `generateRequestId()` invocation.
  */
-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;
+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;
 }
 /**
- * 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.
+ * 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). */
@@ -2056,6 +1380,43 @@ export declare function readinessHandler(check?: () => boolean | Promise<boolean
  * (readiness semantics), otherwise always 200.
  */
 export declare function healthHandler(check?: () => boolean | Promise<boolean>): ((_req: Request) => Response) | ((_req: Request) => Promise<Response>);
+/** 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;
 /** The runtime hooks + registry for ingress metrics. */
 export interface IngressMetrics {
 	registry: MetricsRegistry;
@@ -2225,116 +1586,76 @@ export declare function createIngressSync(options?: IngressOptions): SyncIngress
  * @returns an async handler returning a snapshot context
  */
 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>;
-}
+/** 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;
 /**
- * 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();
- * });
- * ```
+ * Unpack a packed u32 array: `[u32 count]{[u32 value]}` → `Uint32Array`.
+ * @throws {RangeError} when the buffer is shorter than `count` × 4 bytes.
  */
-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;
+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>;
 }
 /**
- * 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 } });
- * ```
+ * 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 sseResponse(events: AsyncIterable<SseEvent> | Iterable<SseEvent>, init?: ResponseInit): Response;
+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;
 /** 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. */
@@ -2860,134 +2181,866 @@ export interface LoaderOptions {
 	/** 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.
+	 * `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>;
+/** 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;
+/** 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;
+/** 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 {
+	/** Packed CRC32 batch: packed `[u8[]]` items → packed u32 results. */
+	crc32BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed JSON-validity batch: packed `[u8[]]` items → packed 0/1 bitset. */
+	jsonValidBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed email-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
+	validateEmailBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed UUID-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
+	validateUuidBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed IPv4-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
+	validateIpv4BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed IPv6-validator batch: packed `[u8[]]` items → packed 0/1 bitset. */
+	validateIpv6BatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed JSON-sum batch: packed `[{id}]` docs → packed `[ok u8][sum i64 LE]`. */
+	jsonSumBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed query-string parser batch: packed `[u8[]]` queries → packed pair lists. */
+	queryParseBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed cookie-header parser batch: packed `[u8[]]` headers → packed pair lists. */
+	cookieParseBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed HTTP-request parser batch: packed `[u8[]]` requests → packed request sections. */
+	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;
+	/** Packed percent-encoding batch: packed `[u8[]]` items → packed hex-percent bytes. */
+	urlEncodeBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed percent-decoding batch: packed `[u8[]]` items → packed decoded bytes (string-safe). */
+	urlDecodeBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed percent-decoding batch returning raw bytes (`%FF` preserved). */
+	urlDecodeBytesBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed MIME-lookup batch: packed `[u8[]]` extensions → packed media-type strings. */
+	mimeFromExtensionBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed WebSocket accept-key batch: packed `[u8[]]` keys → packed base64 SHA-1 results. */
+	wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array;
+	/** Valid JSON count in a packed JSON batch (0..n; invalid items not counted). */
+	jsonValidBatchCountPacked(input: Uint8Array): number;
+	/** Valid-email count in a packed email batch. */
+	validateEmailBatchCountPacked(input: Uint8Array): number;
+	/** Valid-UUID count in a packed UUID batch. */
+	validateUuidBatchCountPacked(input: Uint8Array): number;
+	/** Valid-IPv4 count in a packed IPv4 batch. */
+	validateIpv4BatchCountPacked(input: Uint8Array): number;
+	/** Valid-IPv6 count in a packed IPv6 batch. */
+	validateIpv6BatchCountPacked(input: Uint8Array): number;
+	/** Total `id` sum across a packed JSON batch (valid items only). */
+	jsonSumBatchTotalPacked(input: Uint8Array): number;
+	/** Total packed-output length (bytes) a query batch will produce. */
+	queryParseBatchTotalLenPacked(input: Uint8Array): number;
+	/** Total packed-output length (bytes) a cookie batch will produce. */
+	cookieParseBatchTotalLenPacked(input: Uint8Array): number;
+	/** Total packed-output length (bytes) an HTTP-request batch will produce. */
+	httpParseRequestBatchTotalLenPacked(input: Uint8Array): number;
+	/** Packed Argon2id-hash batch: packed `[u8[]]` passwords + shared salt → packed PHC strings. */
+	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;
+	/** Packed AEAD-encrypt batch (packed inputs + shared key/nonce) → packed ciphertexts. */
+	aeadEncryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
+	/** Packed AEAD-decrypt batch (packed inputs + shared key/nonce) → packed plaintexts. */
+	aeadDecryptBatchPacked(input: Uint8Array, key: Uint8Array, nonce: Uint8Array, algorithm?: string | null): Uint8Array;
+	/** Packed gzip-compress batch: packed `[u8[]]` items → packed gzip streams. */
+	gzipCompressBatchPacked(input: Uint8Array, level?: number | null): Uint8Array;
+	/** Packed gzip-decompress batch (64 MiB cap per item) → packed plaintexts. */
+	gzipDecompressBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed brotli-compress batch: packed `[u8[]]` items → packed brotli streams. */
+	brotliCompressBatchPacked(input: Uint8Array, quality?: number | null): Uint8Array;
+	/** Packed brotli-decompress batch (64 MiB cap per item) → packed plaintexts. */
+	brotliDecompressBatchPacked(input: Uint8Array): Uint8Array;
+	/** Packed HS256 JWT-sign batch (packed claims + shared secret) → packed tokens. */
+	jwtSignBatchPacked(input: Uint8Array, secret: Uint8Array, ttlSeconds: number | null, nowSeconds: number): Uint8Array;
+	/** Packed HS256 JWT-verify batch (packed tokens + shared secret) → packed claims/validity. */
+	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;
+	/** Packed multipart/form-data parser batch (packed bodies + shared boundary) → packed parts. */
+	multipartParseBatchPacked(input: Uint8Array, boundary: Uint8Array): Uint8Array;
+	/** Packed minijinja template batch: packed contexts + shared source → packed renders. */
+	templateRenderBatchPacked(input: Uint8Array, source: string): Uint8Array;
+	/** Packed SSE-frame batch: packed data + shared event/id/retry → packed frames. */
+	sseEncodeBatchPacked(input: Uint8Array, event: string | null, id: string | null, retry: number | null): Uint8Array;
+	/** Packed WebSocket-frame encode batch: packed payloads + shared opcode/mask/fin → packed frames. */
+	wsFrameEncodeBatchPacked(input: Uint8Array, opcode: number, mask: boolean, fin: boolean): Uint8Array;
+	/** Packed WebSocket-frame decode batch: packed frames → packed (fin, opcode, payload) results. */
+	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;
+	/**
+	 * Batch fixed-width hex validation: NEWLINE-separated lines in → one
+	 * verdict byte (1/0) per line. One native call replaces per-item
+	 * `/^[0-9a-f]{width}$/` regex loops (ObjectIds = width 24). Accepts bytes,
+	 * a joined string, or an array of id strings (joined internally).
+	 */
+	hexValidateBatch(input: Uint8Array | readonly string[], width: number): Uint8Array;
+	/**
+	 * Escape JS-RegExp metacharacters so `new RegExp(escaped, flags)` matches
+	 * the input literally — the safe literal-substring-search primitive.
+	 */
+	regexEscape(input: Uint8Array | string): string;
+	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;
+	/**
+	 * Create a sharded metrics registry (counters / gauges / histograms +
+	 * Prometheus render). Fully C-ABI-backed on Bun (caller-owned native
+	 * handle); the napi class on Node. Call `destroy()` on ffi-backed
+	 * registries at shutdown.
+	 */
+	createMetricsRegistry(): MetricsRegistryInstance;
+	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.
 	 */
-	loadStrategy?: LoadStrategy;
-}
-/** Options for `load()` / `opFn.load()`. */
-export interface LoadOptions {
+	urlDecode(input: string): string;
 	/**
-	 * Explicit cache key. When omitted (and caching is on) the default key is
-	 * `fnv1a64(input)` — which costs one extra native call per load.
+	 * 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.
 	 */
-	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;
+	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;
 }
-/** 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;
+/** The full Rust FFI client (scalar methods + namespaces + configuration). */
+export interface RustClient extends RustScalar {
+	text: RustText;
+	batch: RustBatch;
+	packed: RustPacked;
 	/**
-	 * Coalesced, cache-aware load. Unavailable (`undefined`) on ops that require
-	 * extra arguments (e.g. `hmacSha256`, `signCookie`) — use `run` for those.
+	 * 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).
 	 */
-	load: K extends LoadableName ? LoaderLoadFn<K> : undefined;
+	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;
 }
-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;
+/**
+ * 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 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 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;
+/**
+ * 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;
+/** Options for an `AdaptiveEstimate`: EWMA smoothing, bounds, starting value. */ export interface AdaptiveEstimateOptions {
 	/**
-	 * 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).
+	 * EWMA smoothing factor in (0, 1]. Higher reacts faster to new samples;
+	 * lower smooths more. Default: 0.25.
 	 */
-	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[];
+	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;
 }
-/** 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", …)`.
+ * 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 const loader: Loader$1;
+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;
+}
 /**
- * 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`).
+ * Shared UTF-8 encoder (encode / encodeInto), backed by the runtime-native
+ * codec (`src/shared/codec.ts`): a shared native `TextEncoder` singleton on
+ * both runtimes (on Bun 1.4 the engine-native implementation measures ~3x
+ * faster than the old `Bun.ArrayBufferSink` path) plus a zero-copy `Buffer`
+ * view write for `encodeInto`. 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 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;
+export declare const encoder: {
+	encode(s: Uint8Array | string): Uint8Array;
+	encodeInto(s: string, dest: Uint8Array): {
+		read: number;
+		written: number;
+	};
+};
 /**
- * Generic loader bulk dispatch: `loader.run(op, items, ...rest)` → one packed
- * batch native call (or the adaptive scalar loop for tiny batches).
+ * 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 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 declare const decoder: {
+	decode(bytes: Uint8Array | string): string;
+};
+/**
+ * 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;
 
 export {
 	Loader$1 as Loader,