castrum 0.9.7 → 0.9.8

package/Cargo.lock

@@ -233,7 +233,7 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "castrum"
-version = "0.9.7"
+version = "0.9.8"
 dependencies = [
  "argon2",
  "aws-lc-rs",

package/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "castrum"
 # Keep in sync with package.json "version" (single source of truth: the npm package).
-version = "0.9.7"
+version = "0.9.8"
 edition = "2021"
 # Keep in sync with package.json "license" (cargo-deny rejects a crate with no
 # license expression).

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
@@ -949,6 +968,448 @@ 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`; 1 = accepted. */
+	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.
+	 */
+	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.
+	 */
+	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
@@ -1227,7 +1688,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>;
 /**
@@ -1586,6 +2047,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 +2991,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 +3274,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]