castrum 0.9.7 → 0.9.9

package/dist/index.d.ts

@@ -116,7 +116,11 @@ export interface NativeRoute {
 	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). */
+	/**
+	 * Free the native handle. Idempotent: a second call is a no-op. After it,
+	 * {@link runFrame}/{@link run} throw rather than pass a freed handle into the
+	 * native stack.
+	 */
 	destroy(): void;
 }
 /**
@@ -182,6 +186,13 @@ declare abstract class IngressResultBase {
 	/** Request body bytes (may be an empty view). */
 	body: Uint8Array;
 	protected _buf: Uint8Array;
+	/**
+	 * Valid byte length of `_buf` (the native `written` count). `_buf` may be the
+	 * WHOLE pooled output buffer (`outputBufferSize` bytes), so bounds checks must
+	 * use this, not `_buf.byteLength` — that lets `run()` skip a per-request
+	 * `buffer.subarray(0, written)` view.
+	 */
+	protected _len: number;
 	protected _bodyJsonStart: number;
 	protected _bodyJsonLen: number;
 	private _cookiesBuf;
@@ -206,7 +217,7 @@ declare abstract class IngressResultBase {
 	 * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
 	 * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
 	 */
-	protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void;
+	protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number, len?: number): void;
 	/** Decoded cookies-JSON section, or `"{}"` when absent. */
 	cookiesJson(): string;
 	/** Decoded query-JSON section, or `"{}"` when absent. */
@@ -216,7 +227,7 @@ declare abstract class IngressResultBase {
 }
 /** Zero-alloc, reusable result decoder for the pre-baked handler path. */
 export declare class BakedIngressResult extends IngressResultBase {
-	refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void;
+	refresh(buf: Uint8Array, body: Uint8Array, view: DataView, len?: number): void;
 	invalidate(): void;
 	setInternalError(): void;
 	bodyJson(copy: boolean): Uint8Array;
@@ -427,6 +438,14 @@ export interface OptimizedIngressHandler {
 		string,
 		string
 	][];
+	/**
+	 * Success-path headers as a ready `Headers` instance: the memoized base
+	 * (template + reflected origin) plus per-request rate/request-id extras,
+	 * without rebuilding `Headers` from an array on every response. Optional so
+	 * hand-rolled mocks need not provide it; callers fall back to
+	 * `memoizedHeaders(responseHeaders(...))`.
+	 */
+	successHeaders?(variant: number, requestIdHeader: string | null, origin: string | null, rateRemaining?: number, rateResetSecs?: number): Headers;
 	terminalHeaders(variant: number, ctx: BakedContext, result: BakedIngressResult | null): [
 		string,
 		string
@@ -534,8 +553,45 @@ export interface PathMatch {
  *  adapter (Bun's native router handles matching; the ingress pipeline does
  *  not echo params in its response). */
 type RouteHandler = (req: Request, srv?: unknown, params?: Record<string, string>) => Response | Promise<Response>;
+/**
+ * A prebuilt constant response for static route promotion.
+ *
+ * Either a bare `Response` or a factory that builds a FRESH `Response` per
+ * request. Behavior differs by runtime:
+ *
+ * - **Bun**: a bare `Response` is snapshotted into `Bun.serve`'s native route
+ *   table at bind time (verified on Bun 1.4.2 — the body is NOT consumed by the
+ *   first request) and served on every request without entering JS.
+ * - **Node** (`createIngressServerNode`): the adapter reads the bare `Response`
+ *   body ONCE and materializes a fresh `Response` per request (a web body is
+ *   one-shot).
+ *
+ * A factory is invoked by the runtime on every request, so it MUST return a new
+ * `Response` each call. Returning the SAME already-sent instance fails on the
+ * second request with `ERR_BODY_ALREADY_USED` (Bun) / a consumed stream
+ * (Node) — use a factory only when the response genuinely varies per request.
+ */
+export type StaticRoute = Response | (() => Response);
 /** Route spec for the Bun.serve builder. */
 export interface BakedRoute {
+	/**
+	 * A prebuilt constant response served for GET, bypassing the ingress
+	 * pipeline entirely. Takes precedence over `read`/`cookies` for GET (the
+	 * pipeline handler is never wired); other methods (`write`/`echo`/`delete`)
+	 * are unaffected. See {@link StaticRoute} for the one-shot-body contract.
+	 *
+	 * HEAD is intentionally NOT wired for `static` (a bare `Response` carries a
+	 * body; static responses are probes/constants served over GET). This matches
+	 * the raw-`read` probe behavior — but note that a route which previously
+	 * served HEAD via a native `read` now 405s (Node) on HEAD once `static` is
+	 * set. When `static` is combined with `write`/`echo`/`delete`, those dynamic
+	 * methods remain wired.
+	 *
+	 * Runtime note: `createIngressRouter` treats `static` differently — there,
+	 * like `raw`, it OWNS THE WHOLE SPEC (the router has no compiled ingress for
+	 * the other methods; see `RouterRouteSpec.static` in src/ingress/router.ts).
+	 */
+	static?: StaticRoute;
 	/**
 	 * Wires GET + HEAD read handlers. Accepts an optimized ingress handler OR a
 	 * raw `RouteHandler` function (health/metrics probes are raw — see
@@ -612,14 +668,20 @@ export interface CreateIngressServerOptions {
 	routes: Record<string, BakedRoute>;
 	fallback?: OptimizedIngressHandler;
 	/**
-	 * Invoked when an unhandled error escapes a request handler (currently wired
-	 * on the Node adapter; the Bun path uses runtime.onResponse). Never throws —
-	 * hook failures are swallowed.
+	 * Invoked when an unhandled error escapes a request handler (raw `read`
+	 * functions, `responder`/`native` responders, or the Bun/Node adapter
+	 * catch-all). The error is masked to a generic 500 on the wire. Never
+	 * throws — hook failures are swallowed.
 	 */
 	onError?: (info: {
 		error: Error;
 		request?: Request;
 	}) => void;
+	/**
+	 * Optional structured-log sink for escaped handler errors (one JSON line per
+	 * masked 500, message only). Never throws.
+	 */
+	logger?: (line: string) => void;
 	/** Node adapter only: ms to receive the complete request (headers + body).
 	 *  Guards slowloris/trickling requests. Default: 30_000. */
 	requestTimeoutMs?: number;
@@ -949,6 +1011,453 @@ export interface Argon2HasherInstance {
 	hash(password: Uint8Array, salt: Uint8Array): Uint8Array;
 	verify(password: Uint8Array, phc: Uint8Array): boolean;
 }
+/**
+ * The bound bun:ffi C-ABI surface. Each member is a dlopen'd `castrum_*`
+ * symbol wrapped so inputs are `(ptr,len)` byte slices and text outputs are
+ * returned as JS strings via JSC's native transfer (cstring clone) — zero
+ * `TextEncoder`/`TextDecoder` on the Bun path. `*Into` variants write into a
+ * caller buffer and return the byte count; variable-size ops return the exact
+ * required size on a too-small buffer so the transport grows once and retries
+ * exactly once.
+ */
+export interface BunFFI {
+	crc32(input: Uint8Array): number;
+	fnv1a64(input: Uint8Array): bigint;
+	xxh3(input: Uint8Array): bigint;
+	jsonValid(input: Uint8Array): boolean;
+	/** UTF-8 validity probe (native replacement for a fatal `TextDecoder`). */
+	utf8Valid(input: Uint8Array): boolean;
+	/** Lowercase-hex encode → string (native transfer, zero encode). */
+	hexEncode(input: Uint8Array): string;
+	/** Lowercase-hex encode into `output`; returns bytes written. */
+	hexEncodeInto(input: Uint8Array, output: Uint8Array): number;
+	/** RFC 3986 percent-encode → string. */
+	urlEncode(input: Uint8Array): string;
+	/** RFC 3986 percent-encode into `output`; returns bytes written. */
+	urlEncodeInto(input: Uint8Array, output: Uint8Array): number;
+	validateEmail(input: string): boolean;
+	validateUuid(input: string): boolean;
+	validateIpv4(input: string): boolean;
+	validateIpv6(input: string): boolean;
+	/** Byte-input sibling of {@link validateEmail} (`(ptr,len)` — no decode). */
+	validateEmailBytes(input: Uint8Array): boolean;
+	/** Byte-input sibling of {@link validateUuid} (`(ptr,len)` — no decode). */
+	validateUuidBytes(input: Uint8Array): boolean;
+	/** Byte-input sibling of {@link validateIpv4} (`(ptr,len)` — no decode). */
+	validateIpv4Bytes(input: Uint8Array): boolean;
+	/** Byte-input sibling of {@link validateIpv6} (`(ptr,len)` — no decode). */
+	validateIpv6Bytes(input: Uint8Array): boolean;
+	/** Sum of `id` fields across a JSON array → bigint (throws on non-array input). */
+	jsonSumIds(input: Uint8Array): bigint;
+	hmacSha256Verify(key: Uint8Array, data: Uint8Array, signature: Uint8Array): boolean;
+	csrfVerify(token: Uint8Array, secret: Uint8Array): boolean;
+	passwordVerify(password: Uint8Array, phc: Uint8Array): boolean;
+	/** `phc` is a `cstring` ARG (the engine transcodes the JS PHC string in-engine). */
+	passwordVerifyBcrypt(password: Uint8Array, phc: string): boolean;
+	/** Hex-decode into a fresh buffer (size `input.length / 2`). */
+	hexDecode(input: Uint8Array): Uint8Array;
+	/** Hex-decode into `output`; returns bytes written (throws if too small). */
+	hexDecodeInto(input: Uint8Array, output: Uint8Array): number;
+	/** Percent-decode into a fresh buffer (size `input.length`). */
+	urlDecode(input: Uint8Array): Uint8Array;
+	/** Percent-decode into `output`; returns bytes written (throws if too small). */
+	urlDecodeInto(input: Uint8Array, output: Uint8Array): number;
+	/** base64-decode into a fresh buffer (size `ceil(len/4)*3`). */
+	base64Decode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array;
+	/** base64-decode into `output`; returns bytes written (throws if too small). */
+	base64DecodeInto(input: Uint8Array, output: Uint8Array, urlSafe?: boolean, padding?: boolean): number;
+	/** RFC 6455 Sec-WebSocket-Accept → string (cstring return; `key` is a `cstring` ARG). */
+	wsAcceptKey(key: string): string;
+	/** RFC 6455 Sec-WebSocket-Accept into `output`; returns bytes written. */
+	wsAcceptKeyInto(key: Uint8Array, output: Uint8Array): number;
+	/** crc32 ETag → string (10 strong / 12 weak chars, cstring return). */
+	etag(data: Uint8Array, weak?: boolean): string;
+	/** crc32 ETag into `output`; returns bytes written. */
+	etagInto(data: Uint8Array, output: Uint8Array, weak?: boolean): number;
+	/** Evaluate a precompiled `ConditionalRequest` (opaque `inner` handle from its
+	 * napi `inner_ptr()`) — true → 304. `null` header args = absent (flags encode
+	 * presence so a present-but-empty header is distinct). A null (0) handle → false. */
+	conditionalIsNotModified(inner: number, ifNoneMatch: Uint8Array | null, ifModifiedSince: Uint8Array | null): boolean;
+	/** Precompiled `MediaTypeMatcher` wildcard match (opaque `inner` handle). */
+	mediaTypeMatcherMatches(inner: number, actual: Uint8Array): boolean;
+	/** Precompiled `AcceptNegotiator` → best supported encoding (opaque `inner`
+	 * handle); `null` = identity. */
+	acceptNegotiatorNegotiate(inner: number, header: Uint8Array): string | null;
+	/** Precompiled `AcceptNegotiator` → best supported encoding with SERVER-
+	 * preference tie-breaking (RFC 7231 server semantics, opaque `inner` handle);
+	 * `null` = identity. */
+	acceptNegotiatorNegotiateServer(inner: number, header: Uint8Array): string | null;
+	/** Precompiled `JwtSigner` → compact token from pre-serialized claim JSON
+	 * (opaque `inner` handle); throws on invalid claims / null handle. */
+	jwtSignerSign(inner: number, claimsJson: Uint8Array, nowSeconds: number): Uint8Array;
+	/** Precompiled `JwtSigner` → claims JSON bytes (opaque `inner` handle);
+	 * `null` = invalid signature / expired / malformed. */
+	jwtSignerVerify(inner: number, token: Uint8Array, nowSeconds: number): Uint8Array | null;
+	/** Ed25519 keypair generation → `{ privateKey, publicKey }` (PKCS#8 v1 DER
+	 * private + SPKI DER public bytes); throws on CSPRNG failure. */
+	ed25519GenerateKeypair(): {
+		privateKey: Uint8Array;
+		publicKey: Uint8Array;
+	};
+	/** Ed25519 sign → 64-byte signature; throws on invalid private key. */
+	ed25519Sign(msg: Uint8Array, privateKey: Uint8Array): Uint8Array;
+	/** Ed25519 verify → whether `signature` is valid for `msg` under `publicKey`. */
+	ed25519Verify(msg: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean;
+	/** EdDSA (Ed25519) JWT sign → compact token; `null` = invalid claims/private
+	 * key. `ttl <= 0` = no `iat`/`exp` injection. */
+	jwtEdDSASign(claimsJson: Uint8Array, privateKey: Uint8Array, ttl: number, nowSeconds: number): string | null;
+	/** EdDSA (Ed25519) JWT verify → claims JSON string; `null` = invalid. */
+	jwtEdDSAVerify(token: Uint8Array, publicKey: Uint8Array, nowSeconds: number): string | null;
+	/** Compiled `TemplateRenderer` → UTF-8 bytes from a pre-serialized JSON
+	 * context (opaque `inner` handle); throws on invalid context / render error. */
+	templateRender(inner: number, contextJson: Uint8Array): Uint8Array;
+	/** Compiled `SchemaValidator` → whether a document is valid (opaque `inner` handle). */
+	schemaValidatorValidate(inner: number, doc: Uint8Array): boolean;
+	/** `RateLimiter` string-key check → { allowed, remaining, resetMs } (opaque
+	 * `inner` handle; `key` is a `cstring` ARG); throws on a null handle. */
+	rateLimiterCheck(inner: number, key: string, nowMs: number): RateLimiterVerdict;
+	/** `RateLimiter` pre-hashed key check → { allowed, remaining, resetMs }. */
+	rateLimiterCheckKey(inner: number, key: number, nowMs: number): RateLimiterVerdict;
+	/** `byteLen` random bytes → `byteLen * 2` hex-char string (cstring return). */
+	randomToken(byteLen: number): string;
+	/** base64-encode → string. */
+	base64Encode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): string;
+	/** base64-encode into `output`; returns bytes written. */
+	base64EncodeInto(input: Uint8Array, output: Uint8Array, urlSafe?: boolean, padding?: boolean): number;
+	/** HMAC-SHA256 → 64-char lowercase-hex string. */
+	hmacSha256(key: Uint8Array, data: Uint8Array): string;
+	/** HMAC-SHA256 hex into `output`; returns bytes written (throws if too small). */
+	hmacSha256Into(key: Uint8Array, data: Uint8Array, output: Uint8Array): number;
+	/** Sign cookie `value` as `value.<64-hex>` → string (cstring return). */
+	signCookie(value: Uint8Array, secret: Uint8Array): string;
+	/** Sign cookie into `output`; returns bytes written (throws if too small). */
+	signCookieInto(value: Uint8Array, secret: Uint8Array, output: Uint8Array): number;
+	/** Verify a signed cookie → value string, or `null` on bad signature. */
+	verifyCookie(signed: Uint8Array, secret: Uint8Array): string | null;
+	/** Verify a signed cookie into `output`; returns value length or `null` on bad signature. */
+	verifyCookieInto(signed: Uint8Array, secret: Uint8Array, output: Uint8Array): number | null;
+	/** CSRF token (129 chars: 64 rnd-hex + '.' + 64 sig-hex) → string. */
+	csrfToken(secret: Uint8Array): string;
+	/** CSRF token into `output`; returns bytes written (throws if too small). */
+	csrfTokenInto(secret: Uint8Array, output: Uint8Array): number;
+	/** Argon2id PHC hash → string (m/t/p/out_len params). */
+	passwordHash(password: Uint8Array, salt: Uint8Array, mCost: number, tCost: number, pCost: number, outLen: number): string;
+	/** bcrypt `$2b$` PHC → string (cost clamped 4..=31). */
+	passwordHashBcrypt(password: Uint8Array, cost: number): string;
+	/** PBKDF2-HMAC-SHA256 → `dkLen` bytes (rounds, dkLen clamped). */
+	pbkdf2Sha256(password: Uint8Array, salt: Uint8Array, rounds: number, dkLen: number): Uint8Array;
+	/** AEAD encrypt (0 = AES-256-GCM, 1 = ChaCha20-Poly1305) → ct+tag. */
+	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, algorithm?: number): Uint8Array;
+	/** AEAD encrypt into `output` (ct + 16-byte tag); returns bytes written. */
+	aeadEncryptInto(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, output: Uint8Array, algorithm?: number): number;
+	/** AEAD decrypt → plaintext, or `null` on auth failure. */
+	aeadDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, algorithm?: number): Uint8Array | null;
+	/** RFC 6455 frame encode into a fresh buffer. */
+	wsFrameEncode(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean): Uint8Array;
+	/** RFC 6455 frame encode into `output`; returns bytes written (throws if too small). */
+	wsFrameEncodeInto(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean, output: Uint8Array): number;
+	/** RFC 6902 JSON patch → JSON text string. */
+	jsonPatch(doc: Uint8Array, patch: Uint8Array): string;
+	/** gzip-compress into a fresh buffer (level clamped 0..=9, default 6). */
+	gzipCompress(data: Uint8Array, level?: number): Uint8Array;
+	/** gzip-compress into `output`; returns bytes written (throws if too small). */
+	gzipCompressInto(data: Uint8Array, output: Uint8Array, level?: number): number;
+	/** gzip-decompress into a fresh buffer (capped by `maxDecompressed`). */
+	gzipDecompress(data: Uint8Array, maxDecompressed?: number): Uint8Array;
+	/** gzip-decompress into `output`; returns bytes written (throws if too small). */
+	gzipDecompressInto(data: Uint8Array, output: Uint8Array, maxDecompressed?: number): number;
+	/**
+	 * gzip ISIZE trailer probe → the uncompressed size for a single-member gzip
+	 * stream, or `0` when unknown (invalid stream / multi-member). Used to
+	 * PRE-SIZE a destination buffer for the zero-copy task path.
+	 */
+	gzipIsize(data: Uint8Array): number;
+	/** brotli-compress into a fresh buffer (quality clamped 0..=11, default 5). */
+	brotliCompress(data: Uint8Array, quality?: number): Uint8Array;
+	/** brotli-compress into `output`; returns bytes written (throws if too small). */
+	brotliCompressInto(data: Uint8Array, output: Uint8Array, quality?: number): number;
+	/** brotli-decompress into a fresh buffer (capped by `maxDecompressed`). */
+	brotliDecompress(data: Uint8Array, maxDecompressed?: number): Uint8Array;
+	/** brotli-decompress into `output`; returns bytes written (throws if too small). */
+	brotliDecompressInto(data: Uint8Array, output: Uint8Array, maxDecompressed?: number): number;
+	/** HTTP request parse → packed output into `output`; returns bytes written. */
+	httpParseRequestPackedInto(input: Uint8Array, output: Uint8Array): number;
+	/** Query string parse → packed output into `output`; returns bytes written. */
+	queryParsePackedInto(input: Uint8Array, output: Uint8Array): number;
+	/** Cookie header parse → packed output into `output`; returns bytes written. */
+	cookieParsePackedInto(input: Uint8Array, output: Uint8Array): number;
+	/** Sign JWT (HS256) from pre-serialized claim JSON (ttl<=0 → no iat/exp) → string. */
+	jwtSignBytes(claimsJson: Uint8Array, secret: Uint8Array, ttl: number, now: number): string;
+	/** Sign JWT into `output`; returns bytes written (throws if too small). */
+	jwtSignBytesInto(claimsJson: Uint8Array, secret: Uint8Array, ttl: number, now: number, output: Uint8Array): number;
+	/** Decode a WS frame into packed `[flags][opcode][u32 len][payload]`; null on malformed. */
+	wsFrameDecodePacked(data: Uint8Array): Uint8Array | null;
+	/**
+	 * Decode a WS frame into `output` (sized ≥ `data.length + 6`); returns bytes
+	 * written, null on malformed. Pooled sibling of `wsFrameDecodePacked`.
+	 */
+	wsFrameDecodePackedInto(data: Uint8Array, output: Uint8Array): number | null;
+	/** Parse multipart/form-data into the packed parts layout. */
+	multipartParsePacked(body: Uint8Array, boundary: Uint8Array): Uint8Array;
+	/** Parse multipart/form-data into `output`; returns bytes written (throws if too small). */
+	multipartParsePackedInto(body: Uint8Array, boundary: Uint8Array, output: Uint8Array): number;
+	/** Parse x-www-form-urlencoded into packed pairs into `output`. */
+	formParsePackedInto(input: Uint8Array, output: Uint8Array): number;
+	/**
+	 * Verify an HS256 JWT → claims JSON text (cstring return; `null` on invalid
+	 * signature / expired / malformed). `nowSeconds` is an i64 C arg.
+	 */
+	jwtVerify(token: Uint8Array, secret: Uint8Array, nowSeconds: number): string | null;
+	/**
+	 * Parse JSON → packed token stream bytes (structural, no re-parse). Layout:
+	 * `[u32 strCount]{[u32 len][utf8]}... [u32 treeLen][tree]` — a deduplicated
+	 * string table followed by a start/end-marker value tree:
+	 * `0=null 1=false 2=true 3=number(f64 LE) 4=string(u32 table idx)
+	 * 5=array start 6=object start 7=array end 8=object end
+	 * 9=object key(u32 table idx)` (object body `6,(9,keyIdx,value)*,8`).
+	 * Throws on invalid JSON / too-small output. The scalar wrapper decodes the
+	 * table once and assembles the value — no second parse.
+	 */
+	jsonParsePacked(input: Uint8Array): Uint8Array;
+	/**
+	 * Parse a Content-Type header → packed verdict bytes:
+	 * `[u32 mediaTypeLen][mediaType][u32 charsetLen (0xFFFFFFFF = none)][charset]
+	 * [u32 boundaryLen][boundary][u32 paramCount]{[u32 keyLen][key][u32 valLen][val]}`.
+	 * Throws on invalid media type / too-small output.
+	 */
+	parseMediaType(input: Uint8Array): Uint8Array;
+	/** Parse an IMF-fixdate → unix seconds, or `null` on malformed (packed
+	 * `[u8 ok][i64 secs LE]` output, decoded here). */
+	parseHttpDate(input: Uint8Array): bigint | null;
+	/**
+	 * Parse an Accept-Encoding header → packed verdict bytes:
+	 * `[u32 count]{[u32 encLen][enc][f32 q][u32 order]}` (empty header → count 0).
+	 * Throws on too-small output.
+	 */
+	parseAcceptEncoding(input: Uint8Array): Uint8Array;
+	/** Percent-encode a query from packed pairs (the `packPairs` layout) → string,
+	 * keys SORTED (matches napi `BTreeMap` ordering); `null` on malformed input. */
+	urlEncodeQuery(input: Uint8Array): string | null;
+	/** RFC 3986 URL resolution (base + reference) → string; `null` on non-UTF-8. */
+	urlResolve(base: Uint8Array, reference: Uint8Array): string | null;
+	/** Resolve a reference against a `UrlBuilder`'s PRECOMPILED base (opaque
+	 * `inner` handle from its napi `inner_ptr()`) → bytes; throws on a null
+	 * handle / non-UTF-8 reference / too-small output. */
+	urlBuilderResolve(inner: number, reference: Uint8Array): Uint8Array;
+	/** Extension → MIME type → string (unknown → `application/octet-stream`; `ext` is a `cstring` ARG). */
+	mimeFromExtension(ext: string): string | null;
+	/**
+	 * 29-byte HTTP-date (`Sun, 06 Nov 1994 08:49:37 GMT`) into `output`; returns
+	 * bytes written (throws on too-small / out-of-range year). FFI sibling of the
+	 * napi `httpDateInto` — kills the napi crossing on the hot path.
+	 */
+	httpDateInto(secs: number, output: Uint8Array): number;
+	/** 29-byte HTTP-date → string (allocating sibling of httpDateInto). */
+	httpDate(secs?: number): string;
+	/**
+	 * Encode one SSE event → bytes (fresh buffer). event/id null = line omitted
+	 * (a present-but-empty string emits the line, matching napi `Option`).
+	 * NOTE: event/id stay `(ptr,len)` byte args — a cstring-ARG conversion was
+	 * attempted and reverted (2026-08-23); see docs/FFI_BUN_GUIDE.md §14 before
+	 * touching this signature.
+	 * FFI sibling of the napi `sse_encode_event`.
+	 */
+	sseEncodeEvent(event: string | null, data: Uint8Array, id: string | null, retry: number | null): Uint8Array;
+	/**
+	 * Encode one SSE event into `output` (sized ≥ `data.length + 64`); returns
+	 * bytes written (throws if too small / invalid UTF-8). Pooled sibling of
+	 * `sseEncodeEvent` — removes the per-call output-buffer alloc.
+	 */
+	sseEncodeEventInto(event: string | null, data: Uint8Array, id: string | null, retry: number | null, output: Uint8Array): number;
+	/** Random hex token into `output`; returns bytes written (throws if too small). */
+	randomTokenInto(byteLen: number, output: Uint8Array): number;
+	/**
+	 * Run the ingress pipeline on a packed frame via the opaque inner handle from
+	 * `Ingress.ingressInnerPtr()` (valid only while the instance is alive — the
+	 * caller must hold it). Returns bytes written; throws on error / too-small.
+	 */
+	ingressHandlePacked(inner: number, input: Uint8Array, body: Uint8Array | null, output: Uint8Array): number;
+	/**
+	 * Run the ingress pipeline from raw request components via the opaque inner
+	 * handle (valid only while the instance is alive). `url`/`ip` are JS strings
+	 * passed as `bun:ffi` `cstring` ARGs — the engine transcodes them to
+	 * call-scoped NUL-terminated UTF-8 buffers in-engine, so the JS side skips
+	 * the frame assembly + `Buffer.write` encode for the URL/IP. `rid`/`headers`
+	 * are the packed byte slices; `body` is the request body (or null); `output`
+	 * receives the packed decision. Same wire format as {@link ingressHandlePacked}.
+	 * Returns bytes written; throws on error / too-small.
+	 */
+	ingressHandleComponents(inner: number, methodKind: number, url: string, ip: string, rid: Uint8Array, headers: Uint8Array, body: Uint8Array | null, output: Uint8Array): number;
+	/**
+	 * Write the ingress binary-layout constants (38 × u32 LE — `rust/ffi.rs`
+	 * `IngressLayout`, numeric source `rust/ingress/output.rs`) into `output`;
+	 * returns bytes written. Lets `src/ingress/constants.ts` read the layout via
+	 * bun:ffi on Bun so importing the package does NOT dlopen the napi addon.
+	 */
+	ingressLayout(out: Uint8Array): number;
+	/**
+	 * Compile a route descriptor (the `@ignex/native` route-wire v3 format:
+	 * magic `ROUT`, version 3, limits, stage tags, draft-07 body schema) into an
+	 * opaque handle. Returns the handle (`0` = invalid descriptor / compile
+	 * failure / panic — throws). The handle is owned by the caller and must be
+	 * released with {@link routeDestroy}.
+	 */
+	routeCompile(descriptor: Uint8Array): number;
+	/**
+	 * Run a compiled route on one request frame, writing the packed verdict
+	 * (`[flags u32][errorCode u32]` + optional query/cookie pair sections) into
+	 * `output`. Returns bytes written (`0` = real error — throws; `> output.length`
+	 * = the EXACT required size — the caller allocates once and retries, per the
+	 * growExact convention).
+	 */
+	routeRun(handle: number, frame: Uint8Array, output: Uint8Array): number;
+	/** Destroy a compiled route handle (frees the native `Box<NativeRoute>`). */
+	routeDestroy(handle: number): void;
+	/** Create an empty metrics registry → a caller-owned opaque handle. */
+	metricsCreate(): number;
+	/**
+	 * Declare a counter family → its `u32` series id (`0xFFFFFFFF` = error).
+	 * `name` and `labelKeys` are `cstring` ARGs; label keys are
+	 * `\u001f`-separated (empty string = no labels).
+	 */
+	metricsCounter(handle: number, name: string, labelKeys: string): number;
+	/** Declare a gauge family → its series id. Same ABI as {@link metricsCounter}. */
+	metricsGauge(handle: number, name: string, labelKeys: string): number;
+	/**
+	 * Declare a histogram family → its series id. `bucketsCsv` is a
+	 * comma-separated finite positive list (empty string = default buckets).
+	 */
+	metricsHistogram(handle: number, name: string, labelKeys: string, bucketsCsv: string): number;
+	/**
+	 * Counter/gauge `+= amount`, or histogram observe `amount`. `values` is the
+	 * packed `\u001f`-separated label values. Returns true on success.
+	 */
+	metricsRecord(handle: number, series: number, values: Uint8Array, amount: number): boolean;
+	/** Gauge assignment (`= value`). Returns true on success. */
+	metricsGaugeSet(handle: number, series: number, values: Uint8Array, value: number): boolean;
+	/**
+	 * Zero-encode sibling of {@link metricsRecord}: `values` is the JOINED
+	 * `\u001f`-separated JS string — the engine transcodes it in-engine.
+	 */
+	metricsRecordStr(handle: number, series: number, values: string, amount: number): boolean;
+	/** Zero-encode sibling of {@link metricsGaugeSet} (joined string values). */
+	metricsGaugeSetStr(handle: number, series: number, values: string, value: number): boolean;
+	/**
+	 * Render the Prometheus text format into `output`; returns bytes written
+	 * (`0` = null handle / error; `> output.length` = exact required size).
+	 */
+	metricsRender(handle: number, output: Uint8Array): number;
+	/**
+	 * Dump the packed v1 series snapshot into `output`; returns bytes written
+	 * (`0` = null handle / error; `> output.length` = exact required size).
+	 */
+	metricsSnapshot(handle: number, output: Uint8Array): number;
+	/** Destroy a registry handle (frees the native `Box<MetricsRegistry>`). */
+	metricsDestroy(handle: number): void;
+	/**
+	 * Record a BATCH of events in one crossing. Packed layout:
+	 * `[u32 n]{[u32 series][u32 valsLen][vals][f64 amount]}`; returns true when
+	 * all entries applied.
+	 */
+	metricsRecordBatch(handle: number, packed: Uint8Array): boolean;
+	/**
+	 * Fused wire-level validation: RAW query string → JSON → draft-07 validate
+	 * against the compiled schema (`inner` from `SchemaValidator.innerPtr()`).
+	 */
+	queryValidate(inner: number, qs: string): boolean;
+	/** Fused cookie-header variant of {@link queryValidate}. */
+	cookieValidate(inner: number, header: string): boolean;
+	/**
+	 * Seal a session envelope natively: builds
+	 * `{"id":"…","data":<dataJson>,"exp":exp}` and HMAC-signs it →
+	 * `payload.<hex>` token string (`null` = failure).
+	 */
+	sessionSeal(id: string, dataJson: string, expSecs: number, secret: string): string | null;
+	/**
+	 * Open a sealed session token: verify + extract in one crossing into
+	 * `output` as `[u8 ok][i64 exp][u32 idLen][id][u32 dataLen][dataJson]`.
+	 * Returns bytes written (`0` = bad signature / error; `> output.length` =
+	 * exact required size).
+	 */
+	sessionOpen(token: string, secret: string, output: Uint8Array): number;
+	/**
+	 * Byte-arg `{@link sessionSeal}`: same envelope + wire format, inputs as
+	 * bytes. Preferred for user-derived `id`/`dataJson`, because a `cstring` ARG
+	 * is engine-transcoded (a per-arg cost) and SILENTLY TRUNCATES at an
+	 * embedded `U+0000` before Rust sees it. `null` = failure.
+	 */
+	sessionSealBytes(id: Uint8Array, dataJson: Uint8Array, expSecs: number, secret: Uint8Array): string | null;
+	/**
+	 * Byte-arg `{@link sessionOpen}`: same output layout and needed-size
+	 * convention, `token`/`secret` as bytes (exact length, no transcode).
+	 */
+	sessionOpenBytes(token: Uint8Array, secret: Uint8Array, output: Uint8Array): number;
+	/**
+	 * Validate NEWLINE-separated lines as fixed-width hex into `output`
+	 * (one verdict byte per line); returns bytes written (`0` = bad width /
+	 * error; `> output.length` = exact required size).
+	 */
+	hexValidateBatchInto(input: Uint8Array, width: number, output: Uint8Array): number;
+	/**
+	 * String-input sibling of {@link hexValidateBatchInto}: the NEWLINE-
+	 * separated ids cross as a `cstring` ARG (engine-transcoded — no encode).
+	 */
+	hexValidateBatchStr(ids: string, width: number, output: Uint8Array): number;
+	/**
+	 * Escape JS-RegExp metacharacters into `output`; returns bytes written
+	 * (`0` = error; `> output.length` = exact required size).
+	 */
+	regexEscapeInto(input: Uint8Array, output: Uint8Array): number;
+	/**
+	 * Zero-copy text sibling of {@link regexEscapeInto}: cstring ARG in,
+	 * cstring return out (engine-cloned — zero JS decode). `null` = failure.
+	 */
+	regexEscapeStr(input: string): string | null;
+	/** Start the shared native task pool; 0 = started, 1 = already running. */
+	taskInit(threads: number): number;
+	/**
+	 * Submit a task op with packed `args` under `taskId`. Returns `1` accepted,
+	 * `2` overloaded (bounded queue full), `0` invalid args.
+	 */
+	taskSubmit(op: number, args: Uint8Array, taskId: number): number;
+	/**
+	 * Zero-copy submit: the op writes its result DIRECTLY into `output` on the
+	 * pool thread. `output` must be a stable, caller-owned buffer that stays
+	 * alive (and untouched) until the completion is drained — the runtime holds
+	 * the reference. The completion body is the 8-byte LE written length.
+	 * Returns `1` accepted, `2` overloaded, `0` invalid args.
+	 */
+	taskSubmitOut(op: number, args: Uint8Array, taskId: number, output: Uint8Array): number;
+	/**
+	 * Zero-copy INPUT: only `hdr` is copied; `data` is read in place by the pool
+	 * thread, so the caller must keep it alive (and untouched) until completion.
+	 * Returns `1` accepted, `2` overloaded, `0` invalid args.
+	 */
+	taskSubmitSlice(op: number, hdr: Uint8Array, data: Uint8Array, taskId: number): number;
+	/**
+	 * Drain finished tasks into `output` (packed `[u32 count][entry…]`).
+	 * Returns bytes written, `0` when nothing is pending, or the EXACT required
+	 * size when `output` is too small (nothing is consumed in that case).
+	 */
+	taskDrain(output: Uint8Array): number;
+	/** Finished-but-undrained completion count. */
+	taskPending(): number;
+	/** Mark a task cancelled; 1 = newly marked, 0 = unknown/already finished. */
+	taskCancel(taskId: number): number;
+	/** Register the thread-safe doorbell trampoline address (`0` disables it). */
+	taskSetDoorbell(ptr: number): number;
+	/** Stop the task pool and drop pending completions. */
+	taskShutdown(): number;
+	/** Configured task-pool worker count (0 before the pool starts). */
+	taskThreads(): number;
+}
+/** Unpacked rate-limit verdict (from the packed
+ * `[u8 allowed][u32 remaining LE][i64 reset_ms LE]` C-ABI output). */
+export interface RateLimiterVerdict {
+	allowed: boolean;
+	remaining: number;
+	resetMs: number;
+}
 /**
  * Create the runtime-appropriate ingress server: `Bun.serve` on Bun, the
  * `node:http` adapter on Node. Selected ONCE at module load — the branch
@@ -987,6 +1496,41 @@ export declare function createTraceId(): string;
 export declare function createSpanId(): string;
 /** Serialize a trace context back to a `traceparent` header value. */
 export declare function serializeTraceParent(ctx: TraceContext): string;
+/**
+ * The `err.code` value a body read carries when it is rejected because the
+ * client disconnected (`Request.signal` aborted).
+ */
+export declare const ABORT_CODE = "REQUEST_ABORTED";
+/**
+ * Whether a thrown value is the cancellation error produced when `req.signal`
+ * aborts during a body read (see `readBodyWithLimit` in `./body`).
+ *
+ * @param err - The caught value.
+ * @returns `true` when `err.code === 'REQUEST_ABORTED'`.
+ * @example
+ * ```ts
+ * try {
+ *   await readBodyWithLimit(req, 1 << 20, true)
+ * } catch (err) {
+ *   if (isAbortError(err)) return abortResponse()
+ *   throw err
+ * }
+ * ```
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Build the cancelled-client response: status **499** ("Client Closed
+ * Request", a de-facto nginx status) with no body. This is the only new
+ * outcome added by cancellation — it never replaces an existing success or
+ * error status.
+ *
+ * @returns A bodyless `Response` with status 499.
+ * @example
+ * ```ts
+ * if (req.signal?.aborted) return abortResponse()
+ * ```
+ */
+export declare function abortResponse(): Response;
 /** Offset of the verdict byte (0 = accepted, nonzero = terminal error). */
 export declare const OUT_VERDICT: number;
 /** Offset of the error-code byte (see ERR_CODE_* below). */
@@ -1227,7 +1771,7 @@ export declare function readHandler(ingress: OptimizedIngressHandler, opts?: Bak
 export declare const deleteHandler: typeof readHandler;
 /**
  * Pre-baked echo handler: streams the request body back with the client's
- * Content-Type, bounded by `maxBodyBytes`.
+ * Content-Type (coerced to a non-active type), bounded by `maxBodyBytes`.
  */
 export declare function echoHandler(ingress: OptimizedIngressHandler, opts?: BakedHandlerOptions): (req: Request, srv?: unknown) => Promise<Response>;
 /**
@@ -1368,6 +1912,20 @@ export declare function createIngressHandler(options?: IngressHandlerOptions, ru
  * Never touches dependencies.
  */
 export declare function livenessHandler(): (_req: Request) => Response;
+/**
+ * Liveness probe as a PREBUILT `Response`, for static route promotion.
+ *
+ * Wire it as `{ static: staticLiveness() }` so `Bun.serve` snapshots the
+ * constant body into its native route table and serves `/livez` without
+ * entering the JavaScript ingress pipeline at all (see `BakedRoute.static` in
+ * src/ingress/server.ts). On the node:http adapter the bare `Response` is
+ * re-materialized per request from cached body bytes, so the one-shot body is
+ * never replayed. Unlike {@link readinessHandler}, it never runs a dependency
+ * check.
+ *
+ * @returns A fresh 200 `{"status":"ok"}` `Response`.
+ */
+export declare function staticLiveness(): Response;
 /**
  * Readiness probe: runs the optional async `check` (dependency readiness).
  * Returns `200 {"status":"ready"}` when the check passes (or no check is
@@ -1494,6 +2052,20 @@ export interface RouterRouteSpec {
 	/** Terminal envelope style for this route's responder (default: router-level
 	 *  `terminalStyle` or `'castrum'`). */
 	terminalStyle?: TerminalStyle;
+	/**
+	 * A prebuilt constant response served directly for GET, OUTSIDE the ingress
+	 * pipeline (static route promotion). Like `raw`, it OWNS THE WHOLE SPEC: the
+	 * router compiles no `IngressInner` for a `static` route, so `read`/`write`/
+	 * `echo`/etc. on the same spec are ignored.
+	 *
+	 * This differs from `BakedRoute.static` in src/ingress/server.ts, where
+	 * `static` only takes GET precedence and leaves `write`/`echo`/`delete`
+	 * wired — the router cannot mirror that because a `static`-only spec has no
+	 * compiled ingress to hand those methods. Do not unify the two semantics.
+	 *
+	 * See `BakedRoute.static` for the one-shot-body contract.
+	 */
+	static?: StaticRoute;
 	/**
 	 * A raw request→Response handler served directly for GET, OUTSIDE the
 	 * ingress pipeline (health/metrics probes, /metrics). When set, `read`/
@@ -1586,6 +2158,23 @@ export declare function createIngressSync(options?: IngressOptions): SyncIngress
  * @returns an async handler returning a snapshot context
  */
 export declare function createIngress(options?: IngressOptions): IngressHandler;
+/**
+ * Synchronous ingress writers backed by castrum's process-lifetime FFI binding.
+ * Handles MUST originate from addonPath and remain owned/alive while in use.
+ * Writers throw on native failure; a return larger than output.byteLength is
+ * the exact required capacity, not a completed write. No buffer is retained.
+ */
+export type IngressBinding = Pick<BunFFI, "ingressHandleComponents" | "ingressHandlePacked" | "ingressLayout"> & {
+	readonly addonPath: string;
+};
+/**
+ * Share castrum's self-tested ingress writers without a second dlopen/map.
+ * @returns The binding and actual binary path, or null when FFI is unavailable.
+ * @example
+ * const binding = getIngressBinding()
+ * // Verify binding.addonPath matches the addon that owns your ingress handle.
+ */
+export declare function getIngressBinding(): IngressBinding | null;
 /** 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. */
@@ -2513,8 +3102,23 @@ export interface RustBatch {
 	wsAcceptKey(items: Uint8Array[]): Uint8Array[];
 	base64UrlEncode(items: Uint8Array[]): Uint8Array[];
 	base64UrlDecode(items: Uint8Array[]): Uint8Array[];
+	/**
+	 * Parallel password hashing. WARNING: the SAME `salt` is applied to every
+	 * item. Reusing one salt across real user passwords enables a single
+	 * precomputation to attack them all — generate a unique salt per password in
+	 * production (this batch form is for precomputed/benchmark workloads).
+	 */
 	passwordHash(passwords: Uint8Array[], salt: Uint8Array, options?: PasswordHashOptions | null): Uint8Array[];
+	/**
+	 * Parallel AEAD encrypt. `nonce` MUST be exactly 12 bytes and MUST be fresh
+	 * for every batch call with the same key: a unique per-item nonce is derived
+	 * by XOR-ing the item index into the low 8 bytes, so reusing a base nonce
+	 * across calls reuses keystream/tag material for colliding indices
+	 * (catastrophic for AES-GCM / ChaCha20-Poly1305). A non-12-byte nonce is
+	 * rejected with an error.
+	 */
 	aeadEncrypt(key: Uint8Array, nonce: Uint8Array, items: Uint8Array[], algorithm?: string | null): Uint8Array[];
+	/** Parallel AEAD decrypt. Pass the SAME base nonce and item order as the encrypt call. */
 	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[];
@@ -2781,7 +3385,10 @@ export interface RustScalar {
 	createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance;
 	/**
 	 * Sharded fixed-window per-key rate limiter. `maxEntries` clamps internally
-	 * (default 1,048,576). Each instance owns an independent budget.
+	 * (default 1,048,576) and has an effective floor of 16,384
+	 * (`max_per_shard = max(maxEntries / 256, 64)` × 256 shards) — values below
+	 * that are silently raised, so don't rely on it to bound a tiny key space.
+	 * 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]
@@ -2796,6 +3403,20 @@ export interface RustScalar {
 	createMetricsRegistry(): MetricsRegistryInstance;
 	initThreadPool(rayonThreads?: number): void;
 	rayonNumThreads(): number;
+	/**
+	 * Drop the process-wide compiled request-body schema cache. Identical schema
+	 * bytes are compiled once and shared across `Ingress` / `NativeRoute`
+	 * instances; this releases those compiled validators (already-constructed
+	 * instances keep their own shared reference and are unaffected). Idempotent,
+	 * and a safe no-op when the native addon is absent or predates the symbol
+	 * (the public `flushMemory()` relies on that).
+	 *
+	 * Maintenance-only escape hatch — NOT a benchmarked op, so it is intentionally
+	 * exempt from `PROVEN_SELECTION` / `selection.json` (there is no native-vs-JS
+	 * winner to classify). `test/unit/contract/proven.test.ts` only requires
+	 * registry coverage for selection.json ops + Bun built-ins.
+	 */
+	clearSchemaCache(): void;
 	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
@@ -3198,6 +3819,41 @@ export declare const encoder: {
 export declare const decoder: {
 	decode(bytes: Uint8Array | string): string;
 };
+/** Options for {@link flushMemory}. */
+export interface FlushMemoryOptions {
+	/**
+	 * When true (the default), also request a full garbage collection from the
+	 * runtime: `Bun.gc(true)` on Bun, `globalThis.gc?.()` on Node when the
+	 * process runs with `--expose-gc`. Set false to flush caches only.
+	 */
+	gc?: boolean;
+}
+/**
+ * Flush process-level caches and (by default) request a full GC. Intended for
+ * explicit memory-pressure handling — e.g. after a burst or before a snapshot.
+ *
+ * Clears:
+ * - the global loader LRU cache (`loader.clear()`),
+ * - the process-wide MIME caches (`clearMimeCaches()`),
+ * - the native compiled-schema cache (`rust.clearSchemaCache()`).
+ *
+ * The metrics registry is intentionally left untouched.
+ *
+ * Idempotent, and safe to call before the native addon has ever been loaded
+ * (every cache starts empty, the loader cache is a plain Map, and the native
+ * schema-cache clear is a defensive no-op when the addon/symbol is absent).
+ *
+ * @param options - `gc: false` skips the runtime GC request. Defaults to `{}`
+ *   (GC requested).
+ * @example
+ * ```ts
+ * import { flushMemory } from 'castrum'
+ *
+ * flushMemory()            // drop caches + request GC
+ * flushMemory({ gc: false }) // drop caches only
+ * ```
+ */
+export declare function flushMemory(options?: FlushMemoryOptions): void;
 /**
  * Generate a UUIDv7 (time-ordered) string, preferring Bun's native built-in.
  * Under Node this falls back to `crypto.randomUUID` (v4).