castrum 0.9.0 → 0.9.2

package/src/native/ffi.ts

@@ -1,271 +1,58 @@
-// src/native/ffi.ts — Bun-only C-ABI fast path via `bun:ffi`.
+// src/native/ffi.ts — Bun-only C-ABI fast path via `bun:ffi` (transport core).
 //
 // Bun JIT-compiles `bun:ffi` calls down to direct native calls (~10-20ns
 // crossing), versus ~100-350ns for a Node-API call. The same cdylib that Node
-// loads through napi-rs ALSO exports `extern "C"` symbols (`rust/ffi.rs`), so
-// under Bun we can `dlopen` it and call the hot scalar functions directly —
-// skipping the N-API marshaling that dominates the sub-µs operations.
+// loads through napi-rs ALSO exports `extern "C"` symbols (`rust/ffi/`), so
+// under Bun we can `dlopen` it and call the hot scalar functions directly.
+//
+// Structure: this file is the transport CORE (transport selection + probe +
+// dlopen + symbol binding + bind-time self-test gating). The per-call wrapper
+// surface lives in `build.ts` (delegating to `build/{codecs,compress,parse,
+// instances}.ts`), and the pure pieces beside it: `ffi/types.ts` (BunFFI /
+// FfiMode / Raw signatures), `ffi/constants.ts` (caps + sizing + self-test
+// vectors), `ffi/selftest.ts` (the bind-time self-test). This file re-exports
+// `getBunFFI` + `BunFFI` so existing importers keep working unchanged.
 //
 // Safety / correctness strategy:
 //   - Lazily bound (no addon/ffi work until first use).
-//   - A one-time SELF-TEST runs at bind time: every bound function is checked
-//     against known-good vectors. If ANY check fails (ABI mismatch, platform
-//     quirk, a future Bun regression), the whole ffi layer is disabled and the
-//     caller falls back to the napi addon — the public API never sees a wrong
-//     result. `bun:ffi` is experimental; this is the safety net.
-//   - Decoders that can fail (hexDecode / urlDecode / base64Decode) ARE exposed
-//     here with parity error semantics: a `0` write on non-empty input throws
-//     (the napi decoders throw rather than return a short buffer). The only
-//     unavoidable divergence is decompressing a stream that yields exactly 0
-//     bytes, which the C ABI can't distinguish from "too small" (napi returns
-//     an empty buffer; ffi throws) — degenerate and not exercised by tests.
+//   - A one-time SELF-TEST runs at bind time (ffi/selftest.ts); any failure
+//     disables ffi and falls back to the napi addon.
+//   - Decoders that can fail ARE exposed with parity error semantics: a `0`
+//     write on non-empty input throws (the napi decoders throw rather than
+//     return a short buffer).
 //   - Never called under Node (falls back to napi immediately).
 //
 // Buffer ABI: input/out pointers are `(ptr, len)` pairs; the JS wrapper passes
 // `(view, view.length)` and bun:ffi converts the TypedArray to its pointer.
 
-// Type-only: erased at compile time (no runtime import of `bun:ffi` — that
-// stays lazy inside `bind()`). `FFITypeOrString` is the dlopen ABI-string union.
 import type { FFITypeOrString } from 'bun:ffi'
 import { resolveEnvVar } from '../shared/env'
 import { isBun } from '../shared/runtime'
+import { build } from './ffi/build'
+import { selfTest } from './ffi/selftest'
+import type { BunFFI, FfiMode } from './ffi/types'
 // Static import: loader.ts has no side effects (path resolution only — no
 // dlopen), so this adds zero import-time cost while letting `bind()` reuse the
 // exact same resolved `.node` path the napi fallback uses (the shared seam).
 import { getAddonPath } from './loader'
 
-const encoder = new TextEncoder()
-
-/** The set of C-ABI functions this layer can accelerate on Bun. */
-export interface BunFFI {
-  crc32(input: Uint8Array): number
-  fnv1a64(input: Uint8Array): bigint
-  xxh3(input: Uint8Array): bigint
-  jsonValid(input: Uint8Array): boolean
-  /** Lowercase-hex encode into a fresh `Uint8Array` (size `input.length * 2`). */
-  hexEncode(input: Uint8Array): Uint8Array
-  /** Lowercase-hex encode into `output`; returns bytes written. */
-  hexEncodeInto(input: Uint8Array, output: Uint8Array): number
-  /** RFC 3986 percent-encode into a fresh buffer (size `input.length * 3`). */
-  urlEncode(input: Uint8Array): Uint8Array
-  /** RFC 3986 percent-encode into `output`; returns bytes written. */
-  urlEncodeInto(input: Uint8Array, output: Uint8Array): number
-
-  // ── Validators (u8 → boolean) ─────────────────────────────────────
-  validateEmail(input: Uint8Array): boolean
-  validateUuid(input: Uint8Array): boolean
-  validateIpv4(input: Uint8Array): boolean
-  validateIpv6(input: Uint8Array): boolean
-  /** Sum of `id` fields across a JSON array → bigint (throws on non-array input). */
-  jsonSumIds(input: Uint8Array): bigint
-
-  // ── Constant-time verify (u8 → boolean) ───────────────────────────
-  hmacSha256Verify(key: Uint8Array, data: Uint8Array, signature: Uint8Array): boolean
-  csrfVerify(token: Uint8Array, secret: Uint8Array): boolean
-  passwordVerify(password: Uint8Array, phc: Uint8Array): boolean
-  passwordVerifyBcrypt(password: Uint8Array, phc: Uint8Array): boolean
-
-  // ── Decoders (throw on malformed input — napi `Result` parity) ──
-  /** 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
-
-  // ── Fixed-size output writers ─────────────────────────────────────
-  /** RFC 6455 Sec-WebSocket-Accept (28 bytes) into a fresh buffer. */
-  wsAcceptKey(key: Uint8Array): Uint8Array
-  /** crc32 ETag (10 strong / 12 weak bytes) into a fresh buffer. */
-  etag(data: Uint8Array, weak?: boolean): Uint8Array
-  /** crc32 ETag into `output`; returns bytes written. */
-  etagInto(data: Uint8Array, output: Uint8Array, weak?: boolean): number
-  /** `byteLen` random bytes → `byteLen * 2` hex chars. */
-  randomToken(byteLen: number): Uint8Array
-  /** base64-encode into a fresh buffer (size `ceil(len/3)*4`). */
-  base64Encode(input: Uint8Array, urlSafe?: boolean, padding?: boolean): Uint8Array
-  /** base64-encode into `output`; returns bytes written. */
-  base64EncodeInto(
-    input: Uint8Array,
-    output: Uint8Array,
-    urlSafe?: boolean,
-    padding?: boolean,
-  ): number
-  /** HMAC-SHA256 hex (64 chars) into a fresh buffer. */
-  hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array
-  /** 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>` into a fresh buffer. */
-  signCookie(value: Uint8Array, secret: Uint8Array): Uint8Array
-  /** Sign cookie into `output`; returns bytes written (throws if too small). */
-  signCookieInto(value: Uint8Array, secret: Uint8Array, output: Uint8Array): number
-  /** Verify a signed cookie → value bytes, or `null` on bad signature. */
-  verifyCookie(signed: Uint8Array, secret: Uint8Array): Uint8Array | null
-  /** CSRF token (129 bytes: 64 rnd-hex + '.' + 64 sig-hex). */
-  csrfToken(secret: Uint8Array): Uint8Array
-  /** Argon2id PHC hash bytes (m/t/p/out_len params). */
-  passwordHash(
-    password: Uint8Array,
-    salt: Uint8Array,
-    mCost: number,
-    tCost: number,
-    pCost: number,
-    outLen: number,
-  ): Uint8Array
-  /** bcrypt `$2b$` PHC string bytes (cost clamped 4..=31). */
-  passwordHashBcrypt(password: Uint8Array, cost: number): Uint8Array
-  /** 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
-
-  // ── Frame / patch / compression (variable-size → grow-retry) ─────
-  /** 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 into a fresh buffer. */
-  jsonPatch(doc: Uint8Array, patch: Uint8Array): Uint8Array
-  /** 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
-  /** 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
-
-  // ── Packed parsers (into caller buffers) ─────────────────────────
-  /** 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
-
-  // ── Excluded-surface additions (packed / opaque-handle) ─────────
-  /** Sign JWT (HS256) from pre-serialized claim JSON (ttl<=0 → no iat/exp). */
-  jwtSignBytes(claimsJson: Uint8Array, secret: Uint8Array, ttl: number, now: number): Uint8Array
-  /** Decode a WS frame into packed `[flags][opcode][u32 len][payload]`; null on malformed. */
-  wsFrameDecodePacked(data: Uint8Array): Uint8Array | null
-  /** Parse multipart/form-data into the packed parts layout. */
-  multipartParsePacked(body: Uint8Array, boundary: Uint8Array): Uint8Array
-  /** Parse x-www-form-urlencoded into packed pairs into `output`. */
-  formParsePackedInto(input: Uint8Array, 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
-  /**
-   * 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
-}
-
-// ── Caps mirrored from the Rust napi layer ────────────────────────
-// rust/payload/compress.rs DEFAULT_MAX_DECOMPRESSED (64 MiB decompression bomb
-// guard — must stay in sync; do not raise without benchmarking).
-const MAX_DECOMPRESSED = 64 * 1024 * 1024
-// rust/json/json_patch_ops.rs MAX_JSON_PATCH_OUTPUT (128 MiB).
-const MAX_JSON_PATCH_OUTPUT = 128 * 1024 * 1024
-
-// ── Output-buffer sizing heuristics (measured) ─────────────────────
-// These are ALLOCATION caps only, not correctness bounds: `growExact` covers
-// any residual miss with at most one exact-size retry (no re-run loop), so a
-// guess that is too small costs one extra native pass, never a wrong result.
-//
-// Compress: a 75 KiB input compresses to <1 KiB, so a 16 KiB initial is
-// plenty and single-pass; the 1 MiB ceiling bounds incompressible data.
-const COMPRESS_INITIAL_CAP = 16 * 1024
-const COMPRESS_MAX_CAP = 1024 * 1024
-const COMPRESS_HEADROOM = 64 // small-input slack above `data.length`
-// Decompress (no trailer / expensive trailer): typical JSON/text ratios.
-const DECOMPRESS_GUESS_MULTIPLIER_GZIP = 16
-const DECOMPRESS_GUESS_MULTIPLIER_BROTLI = 32
-const DECOMPRESS_FALLBACK_CAP = 4 * 1024 * 1024 // 4 MiB over-alloc bound
-const DECOMPRESS_MIN_INITIAL = 1024
-// JWT: token ≈ header(~36) + payload(≈4/3× claims) + sig(~43) + 2 dots. The
-// old `claims.length + 128` under-sized a typical token (measured 168 B for a
-// 30 B claim → grow-retry double-run, making ffi slower than napi). 2×+128
-// with a 256-byte floor covers typical claims in one pass.
-const JWT_INITIAL_MULTIPLIER = 2
-const JWT_INITIAL_EXTRA = 128
-const JWT_INITIAL_FLOOR = 256
-
-// ── Known-good vectors for the bind-time self-test ───────────────
-// These mirror the Rust `#[cfg(test)]` vectors in rust/ffi.rs.
-const SELFTEST_HEX = encoder.encode('hello') // -> 68656c6c6f
-const SELFTEST_JSON = encoder.encode('{"a":1}')
-
-// Empty view for `null` body slots in (ptr, len) pairs — the C side treats
-// len 0 as "no body" regardless of the pointer value.
-const EMPTY_VIEW = new Uint8Array(0)
+// Re-export the type surface so `import type { BunFFI } from '../native/ffi'`
+// keeps working (existing call sites).
+export type { BunFFI, FfiMode } from './ffi/types'
 
 let cached: BunFFI | null | undefined
+/**
+ * Resolved buffer ABI mode, set once by `bind()`. `null` = ffi unavailable
+ * (Node / `CASTRUM_FFI_MODE=napi` / failed self-test), `'buffer-pair'` = the
+ * engine-native `buffer`/`buffer_length` pair is live, `'ptr-len'` = the
+ * explicit `(ptr, usize)` fallback.
+ */
+let bufferAbiMode: 'buffer-pair' | 'ptr-len' | null = null
 
 // ── Transport selection (CASTRUM_FFI_MODE) ───────────────────────
-// auto  (default): use bun:ffi on Bun, silently fall back to napi when the
-//                  bind or self-test fails (and always on Node).
-// ffi   : force bun:ffi on Bun — throw a clear error if it can't bind or the
-//                  self-test fails (use in benches/CI that MUST run ffi).
-// napi  : never bind — every call goes through the napi addon (the fallback;
-//                  useful for exercising the fallback path on Bun).
-// The legacy alias `RUST_FFI_MODE` is accepted too (see src/shared/env.ts).
-export type FfiMode = 'auto' | 'ffi' | 'napi'
 
 function resolveFfiMode(): FfiMode {
-  const raw = resolveEnvVar('CASTRUM_FFI_MODE', ['RUST_FFI_MODE'])
+  const raw = resolveEnvVar('CASTRUM_FFI_MODE')
   switch (raw) {
     case 'ffi':
       return 'ffi'
@@ -292,6 +79,23 @@ export function getBunFFI(): BunFFI | null {
   return cached
 }
 
+/**
+ * Which buffer ABI the live `bun:ffi` binding uses, or `null` when the
+ * transport is unavailable (Node, `CASTRUM_FFI_MODE=napi`, or a failed
+ * self-test). `'buffer-pair'` = the engine-native `buffer`/`buffer_length`
+ * pair (atomic ptr+byteLength snapshot) is in use; `'ptr-len'` = the explicit
+ * `(ptr, usize)` fallback (older Bun / probe failure). Lazy — triggers the
+ * same one-time bind as {@link getBunFFI}. Under `CASTRUM_FFI_MODE=ffi` on Bun
+ * this is guaranteed non-null; a bind/self-test failure THROWS, matching
+ * `getBunFFI`.
+ */
+export function ffiBufferMode(): 'buffer-pair' | 'ptr-len' | null {
+  if (cached === undefined) {
+    getBunFFI()
+  }
+  return bufferAbiMode
+}
+
 /**
  * Probe whether this Bun build accepts the `buffer`/`buffer_length` ABI pair in
  * `dlopen`. Bun's docs list `buffer_length` as engine-native (dlopen-supported),
@@ -324,6 +128,7 @@ function probeBufferLength(dlopen: typeof import('bun:ffi')['dlopen'], path: str
 }
 
 function bind(): BunFFI | null {
+  bufferAbiMode = null // reset — the mode below is only valid for a live bind
   const mode = resolveFfiMode()
   if (!isBun()) {
     if (mode === 'ffi') {
@@ -349,125 +154,319 @@ function bind(): BunFFI | null {
     // TypedArray at call time — an atomic snapshot) once; when supported we use
     // it for the input-only hot fns (one JS arg instead of two), else `(ptr,len)`.
     const useBufferLength = probeBufferLength(dlopen, path)
+    bufferAbiMode = useBufferLength ? 'buffer-pair' : 'ptr-len'
 
     // String ABI specs ("ptr"/"usize"/"u32"...): accepted by bun:ffi and typed
     // via `FFITypeOrString` in bun-types. usize == uint64 on the host ABI.
     // Symbol keys must be the exact `#[no_mangle] extern "C"` names in
-    // rust/ffi.rs. Every `(ptr,len)` pair is passed as `(view, view.length)`.
+    // rust/ffi/. Every `(ptr,len)` pair is passed as `(view, view.length)`.
     // The 8 input-only single-buffer fns use `inputAbi`; everything else keeps
     // `(ptr,len)` because the output length is the caller's write cap.
     const inputAbi: readonly FFITypeOrString[] = useBufferLength
       ? (['buffer', 'buffer_length'] as unknown as readonly FFITypeOrString[])
       : ['ptr', 'usize']
+    // Phase 1.1: extend `buffer`/`buffer_length` to EVERY `(ptr,len)` pair, not
+    // just the input-only fns. The engine reads ptr + byteLength off the SAME
+    // view at call time (atomic snapshot), so call sites pass the view twice
+    // (see `lenOrView` below). Conversion is POSITIONAL and pair-aware: each
+    // `ptr` consumes its following `usize` as a length. Scalar args that happen
+    // to be `usize` (the opaque `inner` handle of `castrum_ingress_handle_packed`
+    // and the `max` param of gzip/brotli decompress) are passed through
+    // unchanged — a blind `usize`→`buffer_length` map would corrupt them.
+    const abi = (shape: readonly string[]): readonly FFITypeOrString[] => {
+      if (!useBufferLength) return shape as readonly FFITypeOrString[]
+      const out: FFITypeOrString[] = []
+      for (let i = 0; i < shape.length; i++) {
+        const t = shape[i]
+        if (t === 'ptr') {
+          out.push('buffer' as unknown as FFITypeOrString)
+          out.push('buffer_length' as unknown as FFITypeOrString)
+          i++ // consume the paired `usize`
+        } else {
+          out.push(t as FFITypeOrString)
+        }
+      }
+      return out
+    }
+    // `u64_fast` returns a plain `number` when the value fits (< 2^53) instead
+    // of a BigInt — bun-types lacks the literal, so bind it via a typed const
+    // (same cast pattern as the `buffer_length` probe above). Every bytes-written
+    // return fits in a double, so this removes the per-call BigInt boxing on the
+    // hot scalar / `*_into` / packed-parser / ingress calls.
+    const U64_FAST = 'u64_fast' as unknown as FFITypeOrString
     const { symbols } = dlopen(path, {
       castrum_crc32: { args: inputAbi, returns: 'u32' },
       castrum_fnv1a64: { args: inputAbi, returns: 'u64' },
       castrum_xxh3: { args: inputAbi, returns: 'u64' },
       castrum_json_valid: { args: inputAbi, returns: 'u8' },
-      castrum_hex_encode: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
-      castrum_hex_decode: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
-      castrum_url_encode: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
-      castrum_url_decode: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
-      castrum_validate_email: { args: inputAbi, returns: 'u8' },
-      castrum_validate_uuid: { args: inputAbi, returns: 'u8' },
-      castrum_validate_ipv4: { args: inputAbi, returns: 'u8' },
-      castrum_validate_ipv6: { args: inputAbi, returns: 'u8' },
-      castrum_json_sum_ids: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
+      castrum_utf8_valid: { args: inputAbi, returns: 'u8' },
+      castrum_hex_encode: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
+      castrum_hex_decode: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
+      castrum_url_encode: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
+      castrum_url_decode: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
+      // String-input validators: `cstring` ARG (the engine transcodes the JS
+      // string in-engine — no JS-side encode; Rust borrows via CStr::from_ptr).
+      castrum_validate_email: { args: ['cstring'], returns: 'u8' },
+      castrum_validate_uuid: { args: ['cstring'], returns: 'u8' },
+      castrum_validate_ipv4: { args: ['cstring'], returns: 'u8' },
+      castrum_validate_ipv6: { args: ['cstring'], returns: 'u8' },
+      castrum_json_sum_ids: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
       castrum_hmac_sha256_verify: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: 'u8',
+      },
+      castrum_csrf_verify: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: 'u8' },
+      castrum_password_verify: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: 'u8' },
+      castrum_password_verify_bcrypt: {
+        // `phc` crosses as a `cstring` ARG; `password` stays a `(ptr,len)` pair.
+        args: abi(['ptr', 'usize', 'cstring']),
         returns: 'u8',
       },
-      castrum_csrf_verify: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'u8' },
-      castrum_password_verify: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'u8' },
-      castrum_password_verify_bcrypt: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'u8' },
-      castrum_ws_accept_key: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
-      castrum_etag: { args: ['ptr', 'usize', 'ptr', 'usize', 'u8'], returns: 'usize' },
-      castrum_random_token: { args: ['u32', 'ptr', 'usize'], returns: 'usize' },
+      castrum_ws_accept_key: { args: ['cstring'], returns: 'cstring' },
+      castrum_ws_accept_key_into: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_etag: { args: abi(['ptr', 'usize', 'u8']), returns: 'cstring' },
+      castrum_etag_into: { args: abi(['ptr', 'usize', 'u8', 'ptr', 'usize']), returns: U64_FAST },
+      castrum_conditional_is_not_modified: {
+        args: abi(['usize', 'ptr', 'usize', 'ptr', 'usize', 'u8']),
+        returns: 'u8',
+      },
+      castrum_media_type_matcher_matches: {
+        args: abi(['usize', 'ptr', 'usize']),
+        returns: 'u8',
+      },
+      castrum_accept_negotiator_negotiate: {
+        args: abi(['usize', 'ptr', 'usize']),
+        returns: 'cstring',
+      },
+      // Server-preference sibling (RFC 7231 server semantics): `header` is a
+      // `cstring` ARG — the engine transcodes the JS header string in-engine.
+      castrum_accept_negotiator_negotiate_server: {
+        args: ['usize', 'cstring'],
+        returns: 'cstring',
+      },
+      castrum_jwt_signer_sign: {
+        args: abi(['usize', 'ptr', 'usize', 'i64', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_jwt_signer_verify: {
+        args: abi(['usize', 'ptr', 'usize', 'i64', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_template_render: {
+        args: abi(['usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_schema_validator_validate: {
+        args: abi(['usize', 'ptr', 'usize']),
+        returns: 'u8',
+      },
+      castrum_rate_limiter_check: {
+        // `key` crosses as a `cstring` ARG (text, no NUL in the intended use).
+        args: abi(['usize', 'cstring', 'i64', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_rate_limiter_check_key: {
+        args: abi(['usize', 'i64', 'i64', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_random_token: { args: ['u32'], returns: 'cstring' },
+      castrum_random_token_into: { args: ['u32', ...abi(['ptr', 'usize'])], returns: U64_FAST },
       castrum_base64_encode: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'u8', 'u8'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'u8', 'u8']),
+        returns: U64_FAST,
       },
       castrum_base64_decode: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'u8', 'u8'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'u8', 'u8']),
+        returns: U64_FAST,
       },
       castrum_hmac_sha256: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_sign_cookie: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+      castrum_sign_cookie: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: 'cstring' },
+      castrum_sign_cookie_into: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_verify_cookie: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+      castrum_verify_cookie: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: 'cstring' },
+      castrum_verify_cookie_into: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_csrf_token: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
+      castrum_csrf_token: { args: abi(['ptr', 'usize']), returns: 'cstring' },
+      castrum_csrf_token_into: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
       castrum_password_hash: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'u32', 'u32', 'u32', 'u32', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'u32', 'u32', 'u32', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_password_hash_bcrypt: {
-        args: ['ptr', 'usize', 'u32', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_pbkdf2_sha256: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'u32', 'u32', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'u32', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_aead_encrypt: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize', 'u8', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize', 'u8', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_aead_decrypt: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize', 'u8', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize', 'u8', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_ws_frame_encode: {
-        args: ['u8', 'ptr', 'usize', 'u8', 'u8', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['u8', 'ptr', 'usize', 'u8', 'u8', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_json_patch: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_gzip_compress: {
+        args: abi(['ptr', 'usize', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_gzip_compress: { args: ['ptr', 'usize', 'u32', 'ptr', 'usize'], returns: 'usize' },
       castrum_gzip_decompress: {
-        args: ['ptr', 'usize', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_brotli_compress: {
+        args: abi(['ptr', 'usize', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_brotli_compress: { args: ['ptr', 'usize', 'u32', 'ptr', 'usize'], returns: 'usize' },
       castrum_brotli_decompress: {
-        args: ['ptr', 'usize', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_gzip_isize: { args: ['ptr', 'usize'], returns: 'u32' },
+      castrum_gzip_isize: { args: abi(['ptr', 'usize']), returns: 'u32' },
       castrum_http_parse_request_packed: {
-        args: ['ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_query_parse_packed: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_cookie_parse_packed: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_http_date_into: { args: ['f64', ...abi(['ptr', 'usize'])], returns: U64_FAST },
+      castrum_sse_encode_into: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize', 'u8', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_query_parse_packed: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
-      castrum_cookie_parse_packed: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
       // ── Excluded-surface additions ──
       castrum_jwt_sign_bytes: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'i64', 'i64', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64', 'i64']),
+        returns: 'cstring',
+      },
+      castrum_jwt_sign_bytes_into: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64', 'i64', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      // ── Ed25519 / EdDSA JWT (RBAC auth) — bound + self-tested; the public
+      //    surface is deferred to the auth-module consumer ────────────────
+      castrum_ed25519_generate_keypair: {
+        args: abi(['ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_ed25519_sign: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_ed25519_verify: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: 'u32',
+      },
+      castrum_jwt_eddsa_sign: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64', 'i64']),
+        returns: 'cstring',
+      },
+      castrum_jwt_eddsa_verify: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64']),
+        returns: 'cstring',
       },
       castrum_ws_frame_decode_packed: {
-        args: ['ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
       castrum_multipart_parse_packed: {
-        args: ['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_form_parse_packed: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
+      // ── Phase 3 — stateless napi-only scalars (now FFI) ──────────
+      // Structural parse: parses ONCE, emits a packed token stream with a
+      // deduped string table so JS assembles the value with NO second parse.
+      castrum_json_parse_packed: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_parse_media_type: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_parse_http_date: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_parse_accept_encoding: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_url_encode_query: { args: abi(['ptr', 'usize']), returns: 'cstring' },
+      castrum_url_resolve: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize']),
+        returns: 'cstring',
+      },
+      castrum_url_builder_resolve: {
+        args: abi(['usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_mime_from_extension: { args: ['cstring'], returns: 'cstring' },
+      castrum_jwt_verify: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64']),
+        returns: 'cstring',
       },
-      castrum_form_parse_packed: { args: ['ptr', 'usize', 'ptr', 'usize'], returns: 'usize' },
       castrum_ingress_handle_packed: {
-        args: ['usize', 'ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize'],
-        returns: 'usize',
+        args: abi(['usize', 'ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      // Raw-components sibling of `castrum_ingress_handle_packed`: `url`/`ip`
+      // are `cstring` ARGs (Bun transcodes the JS strings to call-scoped
+      // NUL-terminated buffers in-engine — no JS-side Buffer.write encode);
+      // rid/headers/body are `(ptr,len)` byte slices; out is `(ptr,len)`.
+      castrum_ingress_handle_components: {
+        args: abi([
+          'usize',
+          'u8',
+          'cstring',
+          'cstring',
+          'ptr',
+          'usize',
+          'ptr',
+          'usize',
+          'ptr',
+          'usize',
+          'ptr',
+          'usize',
+        ]),
+        returns: U64_FAST,
+      },
+      castrum_ingress_layout: { args: abi(['ptr', 'usize']), returns: U64_FAST },
+      // Per-route native stack (`@ignex/native` also dlopens these exact names
+      // itself; castrum binds them for the bind-time self-test + parity guard).
+      castrum_route_compile: { args: abi(['ptr', 'usize']), returns: U64_FAST },
+      castrum_route_run: {
+        args: abi(['usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
       },
-      castrum_ingress_layout: { args: ['ptr', 'usize'], returns: 'usize' },
+      castrum_route_destroy: { args: ['usize'], returns: 'void' },
     })
 
     const bindings = build(symbols as Record<string, (...a: unknown[]) => unknown>, useBufferLength)
@@ -490,1052 +489,3 @@ function bind(): BunFFI | null {
     return null
   }
 }
-
-// Types for the raw dlopen'd functions (bun:ffi converts Uint8Array -> ptr for
-// `ptr` args; `usize`/`u64`/`i64` returns surface as BigInt).
-type Raw2 = (a: unknown, b: unknown) => number | bigint
-type Raw3 = (a: unknown, b: unknown, c: unknown) => number | bigint
-type Raw4 = (a: unknown, b: unknown, c: unknown, d: unknown) => number | bigint
-type Raw5 = (a: unknown, b: unknown, c: unknown, d: unknown, e: unknown) => number | bigint
-type Raw6 = (
-  a: unknown,
-  b: unknown,
-  c: unknown,
-  d: unknown,
-  e: unknown,
-  f: unknown,
-) => number | bigint
-type Raw7 = (
-  a: unknown,
-  b: unknown,
-  c: unknown,
-  d: unknown,
-  e: unknown,
-  f: unknown,
-  g: unknown,
-) => number | bigint
-type Raw8 = (
-  a: unknown,
-  b: unknown,
-  c: unknown,
-  d: unknown,
-  e: unknown,
-  f: unknown,
-  g: unknown,
-  h: unknown,
-) => number | bigint
-type Raw9 = (
-  a: unknown,
-  b: unknown,
-  c: unknown,
-  d: unknown,
-  e: unknown,
-  f: unknown,
-  g: unknown,
-  h: unknown,
-  i: unknown,
-) => number | bigint
-type Raw10 = (
-  a: unknown,
-  b: unknown,
-  c: unknown,
-  d: unknown,
-  e: unknown,
-  f: unknown,
-  g: unknown,
-  h: unknown,
-  i: unknown,
-  j: unknown,
-) => number | bigint
-
-const flag = (v?: boolean): number => (v ? 1 : 0)
-
-/**
- * Write with the C ABI's "needed" convention. The C side returns the EXACT
- * total bytes the result requires: `0` = real error (throw immediately — no
- * re-run, no grow-to-max allocation storm on invalid input), `w > out.length`
- * = buffer too small with `w` the exact required size (allocate once, retry),
- * else `w` is the written count. A miss therefore costs at most ONE retry with
- * an exact buffer — never a doubling loop that re-runs the whole native op
- * (which is what made FFI gzip/brotli/jsonPatch slower than napi).
- */
-function growExact(
-  write: (out: Uint8Array) => number,
-  initial: number,
-  max: number,
-  error: string,
-): Uint8Array {
-  let cap = Math.min(Math.max(initial, 16), max)
-  for (;;) {
-    const out = new Uint8Array(cap)
-    const w = Number(write(out))
-    if (w === 0) throw new Error(error)
-    if (w <= out.length) return out.subarray(0, w)
-    if (w > max) throw new Error(error)
-    cap = Math.min(w, max)
-  }
-}
-
-/** Decoder parity: a `0` write on non-empty input throws (napi `Result`). */
-function writeOrThrow(w: number, inputLen: number, label: string): number {
-  if (w === 0 && inputLen !== 0) {
-    throw new Error(`${label}: invalid input or output buffer too small`)
-  }
-  return w
-}
-
-/** base64 (no-pad) length of `n` bytes. */
-const b64Len = (n: number): number => (n === 0 ? 0 : Math.ceil(n / 3) * 4 - ((3 - (n % 3)) % 3))
-
-/**
- * Exact length of an argon2id PHC string for the given params (m/t/p/out_len).
- * Format: `$argon2id$v=19$m=<m>,t=<t>,p=<p>$<22-char salt b64>$<hash b64>`.
- * The salt is always 16 bytes → 22 base64 chars (SaltString::encode_b64).
- * Pre-sizing exactly makes `passwordHash` a single native pass instead of a
- * grow-retry (which would re-run the whole ~tens-of-ms hash on a miss).
- */
-function argon2PhcLength(m: number, t: number, p: number, outLen: number): number {
-  return (
-    15 + // "$argon2id$v=19$"
-    2 + // "m="
-    String(m).length +
-    3 + // ",t="
-    String(t).length +
-    3 + // ",p="
-    String(p).length +
-    1 + // "$" before the salt
-    22 + // salt b64 (16 bytes)
-    1 + // "$" before the hash
-    b64Len(outLen)
-  )
-}
-
-function build(
-  sym: Record<string, (...a: unknown[]) => unknown>,
-  useBufferLength: boolean,
-): BunFFI {
-  const crc32 = sym.castrum_crc32 as (...a: unknown[]) => number | bigint
-  const fnv = sym.castrum_fnv1a64 as (...a: unknown[]) => number | bigint
-  const xxh = sym.castrum_xxh3 as (...a: unknown[]) => number | bigint
-  const jsonValid = sym.castrum_json_valid as (...a: unknown[]) => number | bigint
-  const hexEncode = sym.castrum_hex_encode as Raw4
-  const hexDecode = sym.castrum_hex_decode as Raw4
-  const urlEncode = sym.castrum_url_encode as Raw4
-  const urlDecode = sym.castrum_url_decode as Raw4
-  const validateEmail = sym.castrum_validate_email as (...a: unknown[]) => number | bigint
-  const validateUuid = sym.castrum_validate_uuid as (...a: unknown[]) => number | bigint
-  const validateIpv4 = sym.castrum_validate_ipv4 as (...a: unknown[]) => number | bigint
-  const validateIpv6 = sym.castrum_validate_ipv6 as (...a: unknown[]) => number | bigint
-  const jsonSumRaw = sym.castrum_json_sum_ids as Raw4
-
-  // Single-buffer input fns: with the probe-gated `buffer/buffer_length` ABI the
-  // engine reads ptr + byteLength off the SAME TypedArray at call time (an
-  // atomic snapshot — pass the view twice, per Bun's docs); with `(ptr,len)` we
-  // pass the length explicitly. The branch is on a bind-time constant, so the
-  // JIT folds it away at the call site.
-  const oneArg = (raw: (...a: unknown[]) => number | bigint, v: Uint8Array): number | bigint =>
-    useBufferLength ? raw(v, v) : raw(v, v.length)
-  const hmacVerify = sym.castrum_hmac_sha256_verify as Raw6
-  const csrfVerify = sym.castrum_csrf_verify as Raw4
-  const passwordVerify = sym.castrum_password_verify as Raw4
-  const passwordVerifyBcrypt = sym.castrum_password_verify_bcrypt as Raw4
-  const wsAcceptKey = sym.castrum_ws_accept_key as Raw4
-  const etag = sym.castrum_etag as Raw5
-  const randomToken = sym.castrum_random_token as Raw3
-  const base64Encode = sym.castrum_base64_encode as Raw6
-  const base64Decode = sym.castrum_base64_decode as Raw6
-  const hmacSha256 = sym.castrum_hmac_sha256 as Raw6
-  const signCookie = sym.castrum_sign_cookie as Raw6
-  const verifyCookie = sym.castrum_verify_cookie as Raw6
-  const csrfToken = sym.castrum_csrf_token as Raw4
-  const passwordHash = sym.castrum_password_hash as Raw10
-  const passwordHashBcrypt = sym.castrum_password_hash_bcrypt as Raw5
-  const pbkdf2 = sym.castrum_pbkdf2_sha256 as Raw8
-  const aeadEncrypt = sym.castrum_aead_encrypt as Raw9
-  const aeadDecrypt = sym.castrum_aead_decrypt as Raw9
-  const wsFrameEncode = sym.castrum_ws_frame_encode as Raw7
-  const jsonPatch = sym.castrum_json_patch as Raw6
-  const gzipCompress = sym.castrum_gzip_compress as Raw5
-  const gzipDecompress = sym.castrum_gzip_decompress as Raw5
-  const brotliCompress = sym.castrum_brotli_compress as Raw5
-  const brotliDecompress = sym.castrum_brotli_decompress as Raw5
-  const gzipIsize = sym.castrum_gzip_isize as Raw2
-  const httpParsePacked = sym.castrum_http_parse_request_packed as Raw4
-  const queryParsePacked = sym.castrum_query_parse_packed as Raw4
-  const cookieParsePacked = sym.castrum_cookie_parse_packed as Raw4
-  const jwtSignBytes = sym.castrum_jwt_sign_bytes as Raw8
-  const wsFrameDecodePacked = sym.castrum_ws_frame_decode_packed as Raw4
-  const multipartParsePacked = sym.castrum_multipart_parse_packed as Raw6
-  const formParsePacked = sym.castrum_form_parse_packed as Raw4
-  const ingressHandlePacked = sym.castrum_ingress_handle_packed as Raw7
-  const ingressLayoutSym = sym.castrum_ingress_layout as Raw2
-
-  // ── Encoder / decoder `Into` helpers ──────────────────────────────
-  const hexEncodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    // Mirror napi error semantics: a too-small buffer throws, not returns 0.
-    // Hex encode always writes exactly `input.length * 2` bytes on success.
-    if (output.length < input.length * 2) {
-      throw new Error('hex encode: output buffer too small')
-    }
-    return Number(hexEncode(input, input.length, output, output.length))
-  }
-
-  const urlEncodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    const w = Number(urlEncode(input, input.length, output, output.length))
-    // Every input byte encodes to >= 1 output byte, so a 0 write on non-empty
-    // input means the buffer was too small (napi throws there too). Empty
-    // input legitimately writes 0.
-    if (w === 0 && input.length !== 0) {
-      throw new Error('url encode: output buffer too small')
-    }
-    return w
-  }
-
-  const hexDecodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    const w = Number(hexDecode(input, input.length, output, output.length))
-    return writeOrThrow(w, input.length, 'hex decode')
-  }
-
-  const urlDecodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    const w = Number(urlDecode(input, input.length, output, output.length))
-    return writeOrThrow(w, input.length, 'url decode')
-  }
-
-  const base64DecodeInto = (
-    input: Uint8Array,
-    output: Uint8Array,
-    urlSafe?: boolean,
-    padding?: boolean,
-  ): number => {
-    // napi defaults: urlSafe=false, padding=true (rust/crypto/base64.rs).
-    const w = Number(
-      base64Decode(
-        input,
-        input.length,
-        output,
-        output.length,
-        flag(urlSafe),
-        flag(padding ?? true),
-      ),
-    )
-    return writeOrThrow(w, input.length, 'base64 decode')
-  }
-
-  const base64EncodeInto = (
-    input: Uint8Array,
-    output: Uint8Array,
-    urlSafe?: boolean,
-    padding?: boolean,
-  ): number => {
-    // napi defaults: urlSafe=false, padding=true.
-    const w = Number(
-      base64Encode(
-        input,
-        input.length,
-        output,
-        output.length,
-        flag(urlSafe),
-        flag(padding ?? true),
-      ),
-    )
-    // Empty input legitimately writes 0 bytes — only a 0 write on NON-empty
-    // input is a real error (same convention as the decode/etag paths).
-    return writeOrThrow(w, input.length, 'base64 encode')
-  }
-
-  const etagInto = (data: Uint8Array, output: Uint8Array, weak?: boolean): number => {
-    const w = Number(etag(data, data.length, output, output.length, flag(weak)))
-    if (w === 0 && data.length !== 0) {
-      throw new Error('etag: output buffer too small')
-    }
-    return w
-  }
-
-  return {
-    crc32: (input) => Number(oneArg(crc32, input)) >>> 0,
-    fnv1a64: (input) => BigInt(oneArg(fnv, input)),
-    xxh3: (input) => BigInt(oneArg(xxh, input)),
-    jsonValid: (input) => Number(oneArg(jsonValid, input)) === 1,
-    hexEncode(input) {
-      const out = new Uint8Array(input.length * 2)
-      const w = hexEncodeInto(input, out)
-      return w === input.length * 2 ? out : out.subarray(0, w)
-    },
-    hexEncodeInto,
-    urlEncode(input) {
-      // RFC 3986 worst case is 3 bytes per input byte (`%XX`).
-      const out = new Uint8Array(input.length * 3)
-      const w = urlEncodeInto(input, out)
-      return out.subarray(0, w)
-    },
-    urlEncodeInto,
-
-    validateEmail: (input) => Number(oneArg(validateEmail, input)) === 1,
-    validateUuid: (input) => Number(oneArg(validateUuid, input)) === 1,
-    validateIpv4: (input) => Number(oneArg(validateIpv4, input)) === 1,
-    validateIpv6: (input) => Number(oneArg(validateIpv6, input)) === 1,
-    jsonSumIds: (input) => {
-      // Packed [u8 ok][i64 sum LE] output (9 B): ok=1 → valid array (the sum
-      // may be 0); ok=0 → invalid input. Bytes written: 9/1/0 (0 = real error).
-      const out = new Uint8Array(9)
-      const w = Number(jsonSumRaw(input, input.length, out, out.length))
-      if (w === 0) {
-        throw new Error('json sum ids: output buffer too small')
-      }
-      if (out[0] === 0) {
-        // Mirrors the napi error phrasing (serde: "expected an array of objects
-        // with numeric ids") so both transports throw the same message.
-        throw new Error('json sum ids: expected an array of objects with numeric ids')
-      }
-      return new DataView(out.buffer, out.byteOffset, out.byteLength).getBigInt64(1, true)
-    },
-    hmacSha256Verify: (key, data, signature) =>
-      Number(hmacVerify(key, key.length, data, data.length, signature, signature.length)) === 1,
-    csrfVerify: (token, secret) =>
-      Number(csrfVerify(token, token.length, secret, secret.length)) === 1,
-    passwordVerify: (password, phc) =>
-      Number(passwordVerify(password, password.length, phc, phc.length)) === 1,
-    passwordVerifyBcrypt: (password, phc) =>
-      Number(passwordVerifyBcrypt(password, password.length, phc, phc.length)) === 1,
-
-    hexDecode(input) {
-      const out = new Uint8Array(Math.floor(input.length / 2))
-      const w = hexDecodeInto(input, out)
-      return out.subarray(0, w)
-    },
-    hexDecodeInto,
-    urlDecode(input) {
-      const out = new Uint8Array(input.length)
-      const w = urlDecodeInto(input, out)
-      return out.subarray(0, w)
-    },
-    urlDecodeInto,
-    base64Decode(input, urlSafe, padding) {
-      const out = new Uint8Array(Math.ceil((input.length * 3) / 4))
-      const w = base64DecodeInto(input, out, urlSafe, padding)
-      return out.subarray(0, w)
-    },
-    base64DecodeInto,
-
-    wsAcceptKey(key) {
-      const out = new Uint8Array(28)
-      const w = Number(wsAcceptKey(key, key.length, out, out.length))
-      if (w === 0) {
-        throw new Error('ws accept key: bad key or output buffer too small')
-      }
-      return out.subarray(0, w)
-    },
-    etag(data, weak) {
-      const out = new Uint8Array(12)
-      const w = etagInto(data, out, weak)
-      return out.subarray(0, w)
-    },
-    etagInto,
-    randomToken(byteLen) {
-      const out = new Uint8Array(byteLen * 2)
-      const w = Number(randomToken(byteLen, out, out.length))
-      // byteLen 0 legitimately yields an empty token (napi returns empty too);
-      // any other 0 is a real error (buffer too small / random source failed).
-      if (w === 0 && byteLen !== 0) {
-        throw new Error('random token: output buffer too small or random source failed')
-      }
-      return out.subarray(0, w)
-    },
-    base64Encode(input, urlSafe, padding) {
-      const out = new Uint8Array(Math.ceil(input.length / 3) * 4)
-      const w = base64EncodeInto(input, out, urlSafe, padding)
-      return out.subarray(0, w)
-    },
-    base64EncodeInto,
-    hmacSha256(key, data) {
-      const out = new Uint8Array(64)
-      const w = Number(hmacSha256(key, key.length, data, data.length, out, out.length))
-      if (w === 0) {
-        throw new Error('hmac sha256: output buffer too small')
-      }
-      return out.subarray(0, w)
-    },
-    hmacSha256Into(key, data, output) {
-      if (output.length < 64) {
-        throw new Error('hmac sha256: output buffer too small')
-      }
-      const w = Number(hmacSha256(key, key.length, data, data.length, output, output.length))
-      if (w === 0) {
-        throw new Error('hmac sha256: output buffer too small')
-      }
-      return w
-    },
-    signCookie(value, secret) {
-      // `value.<64-hex>` → value.length + 1 + 64.
-      const out = new Uint8Array(value.length + 65)
-      const w = Number(signCookie(value, value.length, secret, secret.length, out, out.length))
-      if (w === 0) {
-        throw new Error('sign cookie: output buffer too small')
-      }
-      return out.subarray(0, w)
-    },
-    signCookieInto(value, secret, output) {
-      const need = value.length + 65
-      if (output.length < need) {
-        throw new Error('sign cookie: output buffer too small')
-      }
-      const w = Number(
-        signCookie(value, value.length, secret, secret.length, output, output.length),
-      )
-      if (w === 0) {
-        throw new Error('sign cookie: output buffer too small')
-      }
-      return w
-    },
-    verifyCookie(signed, secret) {
-      const out = new Uint8Array(signed.length)
-      const w = Number(verifyCookie(signed, signed.length, secret, secret.length, out, out.length))
-      return w === 0 ? null : out.subarray(0, w)
-    },
-    csrfToken(secret) {
-      const out = new Uint8Array(129)
-      const w = Number(csrfToken(secret, secret.length, out, out.length))
-      if (w === 0) {
-        throw new Error('csrf token: output buffer too small or random source failed')
-      }
-      return out.subarray(0, w)
-    },
-    passwordHash(password, salt, mCost, tCost, pCost, outLen) {
-      // Pre-size with the EXACT PHC string length (computable from the params),
-      // so the hash runs once — a grow-retry would re-run the whole argon2
-      // hash on a miss. growExact remains the safety net.
-      return growExact(
-        (out) =>
-          Number(
-            passwordHash(
-              password,
-              password.length,
-              salt,
-              salt.length,
-              mCost,
-              tCost,
-              pCost,
-              outLen,
-              out,
-              out.length,
-            ),
-          ),
-        argon2PhcLength(mCost, tCost, pCost, outLen),
-        2 * 1024 * 1024,
-        'password hash: output buffer too small',
-      )
-    },
-    passwordHashBcrypt(password, cost) {
-      // `$2b$CC$` + 22 salt chars + 31 hash chars = 60 chars.
-      const out = new Uint8Array(64)
-      const w = Number(passwordHashBcrypt(password, password.length, cost, out, out.length))
-      if (w === 0) {
-        throw new Error('password hash bcrypt: output buffer too small')
-      }
-      return out.subarray(0, w)
-    },
-    pbkdf2Sha256(password, salt, rounds, dkLen) {
-      // Rust clamps dkLen to [1, 1MiB] (PBKDF2_MIN_LEN/MAX_LEN) AFTER sizing its
-      // own buffer — so pre-clamp here so dkLen 0 still yields a 1-byte result.
-      const dk = Math.min(Math.max(dkLen, 1), 1024 * 1024)
-      const out = new Uint8Array(dk)
-      const w = Number(
-        pbkdf2(password, password.length, salt, salt.length, rounds, dkLen, out, out.length),
-      )
-      if (w === 0) {
-        throw new Error('pbkdf2: output buffer too small')
-      }
-      return out.subarray(0, w)
-    },
-    aeadEncrypt(key, nonce, plaintext, algorithm = 0) {
-      // ciphertext + 16-byte auth tag.
-      const out = new Uint8Array(plaintext.length + 16)
-      const w = Number(
-        aeadEncrypt(
-          key,
-          key.length,
-          nonce,
-          nonce.length,
-          plaintext,
-          plaintext.length,
-          algorithm,
-          out,
-          out.length,
-        ),
-      )
-      if (w === 0) {
-        throw new Error('aead encrypt: output buffer too small or bad parameters')
-      }
-      return out.subarray(0, w)
-    },
-    aeadEncryptInto(key, nonce, plaintext, output, algorithm = 0) {
-      const need = plaintext.length + 16
-      if (output.length < need) {
-        throw new Error('aead encrypt: output buffer too small')
-      }
-      const w = Number(
-        aeadEncrypt(
-          key,
-          key.length,
-          nonce,
-          nonce.length,
-          plaintext,
-          plaintext.length,
-          algorithm,
-          output,
-          output.length,
-        ),
-      )
-      if (w === 0) {
-        throw new Error('aead encrypt: output buffer too small or bad parameters')
-      }
-      return w
-    },
-    aeadDecrypt(key, nonce, ciphertext, algorithm = 0) {
-      const out = new Uint8Array(ciphertext.length)
-      const w = Number(
-        aeadDecrypt(
-          key,
-          key.length,
-          nonce,
-          nonce.length,
-          ciphertext,
-          ciphertext.length,
-          algorithm,
-          out,
-          out.length,
-        ),
-      )
-      return w === 0 ? null : out.subarray(0, w)
-    },
-
-    wsFrameEncode(opcode, payload, mask, fin) {
-      // Header (max 10) + payload + mask key (4).
-      const out = new Uint8Array(payload.length + 14)
-      const w = Number(
-        wsFrameEncode(opcode, payload, payload.length, flag(mask), flag(fin), out, out.length),
-      )
-      if (w === 0) {
-        throw new Error('ws frame encode: output buffer too small')
-      }
-      return out.subarray(0, w)
-    },
-    wsFrameEncodeInto(opcode, payload, mask, fin, output) {
-      // Header (max 10) + payload + mask key (4).
-      const need = payload.length + 14
-      if (output.length < need) {
-        throw new Error('ws frame encode: output buffer too small')
-      }
-      const w = Number(
-        wsFrameEncode(
-          opcode,
-          payload,
-          payload.length,
-          flag(mask),
-          flag(fin),
-          output,
-          output.length,
-        ),
-      )
-      if (w === 0) {
-        throw new Error('ws frame encode: output buffer too small')
-      }
-      return w
-    },
-    jsonPatch(doc, patch) {
-      return growExact(
-        (out) => Number(jsonPatch(doc, doc.length, patch, patch.length, out, out.length)),
-        Math.min(Math.max(doc.length, patch.length) + 16, 64 * 1024),
-        MAX_JSON_PATCH_OUTPUT,
-        'json patch: output buffer too small or patch inapplicable',
-      )
-    },
-    gzipCompress(data, level = 6) {
-      // The C ABI streams the compressed output directly into `out` (no internal
-      // Vec — see rust/payload/compress.rs gzip_compress_into). Cap the initial
-      // so large compressible inputs don't pay a full-size allocation (measured:
-      // a 75 KiB input compressed to <1 KiB — COMPRESS_INITIAL_CAP is plenty and
-      // single-pass). growExact handles incompressible data with at most one
-      // exact retry (no re-run loop).
-      return growExact(
-        (out) => Number(gzipCompress(data, data.length, Math.min(level, 9), out, out.length)),
-        Math.min(data.length + COMPRESS_HEADROOM, COMPRESS_INITIAL_CAP),
-        Math.max(data.length * 2 + COMPRESS_HEADROOM, COMPRESS_MAX_CAP),
-        'gzip compress: output buffer too small',
-      )
-    },
-    gzipCompressInto(data, output, level = 6) {
-      const w = Number(gzipCompress(data, data.length, Math.min(level, 9), output, output.length))
-      // Needed-size convention: w > output.length = too small; w === 0 = real error.
-      if (w === 0) {
-        throw new Error('gzip compress: invalid input')
-      }
-      if (w > output.length) {
-        throw new Error('gzip compress: output buffer too small')
-      }
-      return w
-    },
-    gzipDecompress(data, maxDecompressed) {
-      const max = maxDecompressed ?? MAX_DECOMPRESSED
-      // Pre-size from the gzip ISIZE trailer via the C probe (exact for
-      // single-member streams) so the happy path is a single native pass; fall
-      // back to a multiplier guess. growExact handles any residual miss with
-      // one exact retry, and invalid input throws immediately (no 64 MiB
-      // grow-to-max allocation storm).
-      const isize = Number(gzipIsize(data, data.length))
-      const initial =
-        isize !== 0
-          ? Math.min(isize, max)
-          : Math.min(data.length * DECOMPRESS_GUESS_MULTIPLIER_GZIP, DECOMPRESS_FALLBACK_CAP)
-      return growExact(
-        (out) => Number(gzipDecompress(data, data.length, max, out, out.length)),
-        initial,
-        max,
-        'gzip decompress: invalid stream or exceeded max decompressed size',
-      )
-    },
-    brotliCompress(data, quality = 5) {
-      // Same cap rationale as gzipCompress (streaming core); growExact for
-      // incompressible data.
-      return growExact(
-        (out) => Number(brotliCompress(data, data.length, Math.min(quality, 11), out, out.length)),
-        Math.min(data.length + COMPRESS_HEADROOM, COMPRESS_INITIAL_CAP),
-        Math.max(data.length * 2 + COMPRESS_HEADROOM, COMPRESS_MAX_CAP),
-        'brotli compress: output buffer too small',
-      )
-    },
-    brotliCompressInto(data, output, quality = 5) {
-      const w = Number(
-        brotliCompress(data, data.length, Math.min(quality, 11), output, output.length),
-      )
-      // Needed-size convention: w > output.length = too small; w === 0 = real error.
-      if (w === 0) {
-        throw new Error('brotli compress: invalid input')
-      }
-      if (w > output.length) {
-        throw new Error('brotli compress: output buffer too small')
-      }
-      return w
-    },
-    brotliDecompress(data, maxDecompressed) {
-      const max = maxDecompressed ?? MAX_DECOMPRESSED
-      // Brotli has no cheap trailer size: DECOMPRESS_GUESS_MULTIPLIER_BROTLI×
-      // initial covers typical JSON/text ratios (~10-30x) while the fallback
-      // cap bounds over-allocation on large streams; growExact handles
-      // higher-ratio streams with one exact retry.
-      return growExact(
-        (out) => Number(brotliDecompress(data, data.length, max, out, out.length)),
-        Math.min(
-          Math.max(data.length * DECOMPRESS_GUESS_MULTIPLIER_BROTLI, DECOMPRESS_MIN_INITIAL),
-          DECOMPRESS_FALLBACK_CAP,
-        ),
-        max,
-        'brotli decompress: invalid stream or exceeded max decompressed size',
-      )
-    },
-
-    httpParseRequestPackedInto(input, output) {
-      const w = Number(httpParsePacked(input, input.length, output, output.length))
-      if (w === 0 && input.length !== 0) {
-        throw new Error('http parse: output buffer too small or malformed request')
-      }
-      return w
-    },
-    queryParsePackedInto(input, output) {
-      const w = Number(queryParsePacked(input, input.length, output, output.length))
-      if (w === 0 && input.length !== 0) {
-        throw new Error('query parse: output buffer too small')
-      }
-      return w
-    },
-    cookieParsePackedInto(input, output) {
-      const w = Number(cookieParsePacked(input, input.length, output, output.length))
-      if (w === 0 && input.length !== 0) {
-        throw new Error('cookie parse: output buffer too small')
-      }
-      return w
-    },
-
-    // ── Excluded-surface additions ──────────────────────────────────
-    jwtSignBytes(claimsJson, secret, ttl, now) {
-      // Token = header(~36) + payload (claims + iat/exp, base64url ≈ 4/3×) +
-      // signature (~43) + 2 dots. The old `claims.length + 128` under-sized a
-      // typical token (measured 168 B for a 30 B claim → grow-retry double-run,
-      // which made ffi slower than napi). 2×+128 with a 256-byte floor covers
-      // typical claims in one pass; growExact handles huge claims with one
-      // exact retry (no re-run loop).
-      return growExact(
-        (out) =>
-          Number(
-            jwtSignBytes(
-              claimsJson,
-              claimsJson.length,
-              secret,
-              secret.length,
-              ttl,
-              now,
-              out,
-              out.length,
-            ),
-          ),
-        Math.min(
-          Math.max(
-            claimsJson.length * JWT_INITIAL_MULTIPLIER + JWT_INITIAL_EXTRA,
-            JWT_INITIAL_FLOOR,
-          ),
-          1024 * 1024,
-        ),
-        1024 * 1024,
-        'jwt sign: output buffer too small',
-      )
-    },
-    wsFrameDecodePacked(data) {
-      // Max packed output = 6-byte header + payload.
-      const out = new Uint8Array(data.length + 6)
-      const w = Number(wsFrameDecodePacked(data, data.length, out, out.length))
-      return w === 0 ? null : out.subarray(0, w)
-    },
-    multipartParsePacked(body, boundary) {
-      return growExact(
-        (out) =>
-          Number(
-            multipartParsePacked(body, body.length, boundary, boundary.length, out, out.length),
-          ),
-        Math.min(body.length + boundary.length + 64, 64 * 1024),
-        128 * 1024 * 1024,
-        'multipart parse: output buffer too small',
-      )
-    },
-    formParsePackedInto(input, output) {
-      const w = Number(formParsePacked(input, input.length, output, output.length))
-      if (w === 0 && input.length !== 0) {
-        throw new Error('form parse: output buffer too small')
-      }
-      return w
-    },
-    ingressHandlePacked(inner, input, body, output) {
-      const w = Number(
-        ingressHandlePacked(
-          inner,
-          input,
-          input.length,
-          body ?? EMPTY_VIEW,
-          body?.length ?? 0,
-          output,
-          output.length,
-        ),
-      )
-      if (w === 0) {
-        throw new Error('ingress handle: output buffer too small or pipeline error')
-      }
-      return w
-    },
-    ingressLayout(out) {
-      const w = Number(ingressLayoutSym(out, out.length))
-      if (w !== out.length) {
-        throw new Error('ingress layout: output buffer too small')
-      }
-      return w
-    },
-  }
-}
-
-/** Verify every bound function against known-good results; false disables ffi. */
-function selfTest(b: BunFFI): boolean {
-  const dec = new TextDecoder()
-  const enc = encoder
-
-  if (b.crc32(enc.encode('123456789')) !== 0xcbf4_3926) {
-    return false
-  }
-  if (b.fnv1a64(enc.encode('foobar')) !== 0x8594_4171_f739_67e8n) {
-    return false
-  }
-  // XXH3-64 of empty input = 0x2d06800538d394c2 (standard reference vector).
-  if (b.xxh3(new Uint8Array(0)) !== 0x2d06800538d394c2n) {
-    return false
-  }
-  if (b.jsonValid(SELFTEST_JSON) !== true || b.jsonValid(enc.encode('{not json')) !== false) {
-    return false
-  }
-  const hexOut = new Uint8Array(SELFTEST_HEX.length * 2)
-  if (b.hexEncodeInto(SELFTEST_HEX, hexOut) !== 10 || dec.decode(hexOut) !== '68656c6c6f') {
-    return false
-  }
-  const urlInput = enc.encode('a b/c')
-  const urlOut = new Uint8Array(9)
-  if (b.urlEncodeInto(urlInput, urlOut) !== 9 || dec.decode(urlOut) !== 'a%20b%2Fc') {
-    return false
-  }
-
-  // Ingress layout blob (38 × u32 LE). The pinned values catch a reordered
-  // `#[repr(C)] IngressLayout` (drift → self-test fails → napi fallback); the
-  // Rust unit test `ingress_layout_c_abi_matches_output_source` pins every
-  // field against output.rs. Slot order mirrors the struct field order.
-  const layoutBuf = new Uint8Array(38 * 4)
-  b.ingressLayout(layoutBuf)
-  const layoutView = new DataView(layoutBuf.buffer, layoutBuf.byteOffset, layoutBuf.byteLength)
-  if (
-    layoutView.getUint32(0, true) !== 0 || // OUT_VERDICT
-    layoutView.getUint32(2 * 4, true) !== 2 || // OUT_STATUS
-    layoutView.getUint32(12 * 4, true) !== 48 || // OUT_DATA_START
-    layoutView.getUint32(13 * 4, true) !== 1 || // FLAG_HAS_COOKIES
-    layoutView.getUint32(28 * 4, true) !== 32 || // HV_COUNT
-    layoutView.getUint32(37 * 4, true) !== 8 // ERR_INTERNAL
-  ) {
-    return false
-  }
-
-  // Ingress pipeline C-ABI: with a null (0) inner handle the Rust side returns
-  // 0 immediately and the wrapper throws. This exercises the symbol's ABI (arg
-  // count/types/return) at bind time — a signature drift would surface here
-  // instead of crashing under load. Real frame→output parity is covered by
-  // ffi.test.ts against a live napi instance.
-  try {
-    b.ingressHandlePacked(0, enc.encode('/'), null, new Uint8Array(64))
-    return false // a null handle must throw, not return
-  } catch {
-    // expected: null inner handle → 0 → throw
-  }
-
-  // ── New bindings ───────────────────────────────────────────────────
-  const a = enc.encode('a@b.com')
-  const uuid = enc.encode('550e8400-e29b-41d4-a716-446655440000')
-  if (
-    !b.validateEmail(a) ||
-    !b.validateUuid(uuid) ||
-    !b.validateIpv4(enc.encode('192.168.0.1')) ||
-    !b.validateIpv6(enc.encode('2001:db8::1')) ||
-    b.validateEmail(enc.encode('not-an-email')) ||
-    b.validateUuid(enc.encode('not-a-uuid'))
-  ) {
-    return false
-  }
-  if (b.jsonSumIds(enc.encode(`[{"id":1},{"id":2}]`)) !== 3n) {
-    return false
-  }
-  // The packed [u8 ok][i64 sum LE] ABI: a legit zero-sum is ok, invalid input throws.
-  if (b.jsonSumIds(enc.encode(`[{"id":0},{"id":0}]`)) !== 0n) {
-    return false
-  }
-  let sumInvalidThrew = false
-  try {
-    b.jsonSumIds(enc.encode('nope'))
-  } catch {
-    sumInvalidThrew = true
-  }
-  if (!sumInvalidThrew) {
-    return false
-  }
-
-  // HMAC RFC 4231 test case 1 (0x0b × 20 key, "Hi There" data).
-  const hmacKey = new Uint8Array(20).fill(0x0b)
-  const hmacData = enc.encode('Hi There')
-  const hmacSig = enc.encode('b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7')
-  const hmacHex = b.hmacSha256(hmacKey, hmacData)
-  if (dec.decode(hmacHex) !== 'b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7') {
-    return false
-  }
-  if (!b.hmacSha256Verify(hmacKey, hmacData, hmacSig)) {
-    return false
-  }
-
-  // Decoders round-trip.
-  const decoded = b.hexDecode(enc.encode('68656c6c6f'))
-  if (
-    dec.decode(decoded) !== 'hello' ||
-    dec.decode(b.urlDecode(enc.encode('a%20b%2Fc'))) !== 'a b/c'
-  ) {
-    return false
-  }
-
-  // WebSocket accept key (RFC 6455 sample).
-  if (
-    dec.decode(b.wsAcceptKey(enc.encode('dGhlIHNhbXBsZSBub25jZQ=='))) !==
-    's3pPLMBiTxaQ9kYGzzhZRbK+xOo='
-  ) {
-    return false
-  }
-
-  // ETag: strong = 10 bytes, weak = 12 bytes.
-  if (b.etag(SELFTEST_HEX).length !== 10 || b.etag(SELFTEST_HEX, true).length !== 12) {
-    return false
-  }
-
-  // base64.
-  if (dec.decode(b.base64Encode(SELFTEST_HEX)) !== 'aGVsbG8=') {
-    return false
-  }
-  if (dec.decode(b.base64Decode(enc.encode('aGVsbG8='))) !== 'hello') {
-    return false
-  }
-
-  // Signed cookie round-trip.
-  const secret = enc.encode('s3cr3t-secret')
-  const signed = b.signCookie(SELFTEST_HEX, secret)
-  const verified = b.verifyCookie(signed, secret)
-  if (verified === null || dec.decode(verified) !== 'hello') {
-    return false
-  }
-  if (b.verifyCookie(enc.encode('tampered.0000'), secret) !== null) {
-    return false
-  }
-
-  // CSRF token round-trip (issued token verifies against the same secret).
-  const csrfTokenBytes = b.csrfToken(secret)
-  if (csrfTokenBytes.length !== 129 || !b.csrfVerify(csrfTokenBytes, secret)) {
-    return false
-  }
-
-  // Argon2id round-trip at minimum cost (fast) — full defaults would take ~50ms.
-  const pw = enc.encode('correct horse battery staple')
-  const salt = enc.encode('salty-salt-16b')
-  const phc = b.passwordHash(pw, salt, 8, 1, 1, 16)
-  if (phc.length === 0 || !b.passwordVerify(pw, phc)) {
-    return false
-  }
-
-  // bcrypt round-trip at minimum cost (fast).
-  const bcryptPhc = b.passwordHashBcrypt(pw, 4)
-  if (bcryptPhc.length === 0 || !b.passwordVerifyBcrypt(pw, bcryptPhc)) {
-    return false
-  }
-
-  // PBKDF2-HMAC-SHA256: password="password", salt="salt", c=1, dkLen=32.
-  // The C ABI writes the RAW derived key; hex-encode before comparing.
-  const dk = b.pbkdf2Sha256(enc.encode('password'), enc.encode('salt'), 1, 32)
-  if (
-    dec.decode(b.hexEncode(dk)) !==
-    '120fb6cffcf8b32c43e7225256c4f837a86548c92ccc35480805987cb70be17b'
-  ) {
-    return false
-  }
-
-  // AEAD AES-256-GCM round-trip (key 32B, nonce 12B).
-  const aeadKey = new Uint8Array(32).fill(0x42)
-  const nonce = new Uint8Array(12).fill(0x07)
-  const ct = b.aeadEncrypt(aeadKey, nonce, SELFTEST_HEX, 0)
-  const pt = b.aeadDecrypt(aeadKey, nonce, ct, 0)
-  if (pt === null || dec.decode(pt) !== 'hello') {
-    return false
-  }
-
-  // WebSocket frame: text frame, FIN, no mask → first byte 0x81.
-  const frame = b.wsFrameEncode(1, SELFTEST_HEX, false, true)
-  if (frame.length === 0 || frame[0] !== 0x81) {
-    return false
-  }
-
-  // JSON patch: add a key.
-  const patched = b.jsonPatch(
-    enc.encode(`{"a":"b"}`),
-    enc.encode(`[{"op":"add","path":"/c","value":"d"}]`),
-  )
-  if (!dec.decode(patched).includes(`"c":"d"`)) {
-    return false
-  }
-
-  // gzip / brotli round-trips.
-  const gz = b.gzipCompress(SELFTEST_HEX)
-  if (dec.decode(b.gzipDecompress(gz)) !== 'hello') {
-    return false
-  }
-  const br = b.brotliCompress(SELFTEST_HEX)
-  if (dec.decode(b.brotliDecompress(br)) !== 'hello') {
-    return false
-  }
-
-  // Needed-size convention: invalid compressed input throws IMMEDIATELY (the C
-  // ABI returns 0 = real error, so the JS wrapper does NOT grow-retry re-runs
-  // or allocate up to the 64 MiB decompression cap per bad input).
-  let decompressThrew = false
-  try {
-    b.gzipDecompress(enc.encode('not-a-gzip-stream'))
-  } catch {
-    decompressThrew = true
-  }
-  if (!decompressThrew) {
-    return false
-  }
-  decompressThrew = false
-  try {
-    b.brotliDecompress(enc.encode('not-brotli-stream'))
-  } catch {
-    decompressThrew = true
-  }
-  if (!decompressThrew) {
-    return false
-  }
-
-  // Packed parsers (non-empty output). Packed output is LARGER than input (each
-  // component gets a u32 length prefix), so size with the Rust allocator's
-  // conservative upper bound (`input.len() * 9 + 16` in query_parser.rs).
-  const req = enc.encode('GET /a?b=1 HTTP/1.1\r\nHost: example.com\r\n\r\n')
-  const reqOut = new Uint8Array(req.length * 9 + 16)
-  if (b.httpParseRequestPackedInto(req, reqOut) === 0) {
-    return false
-  }
-  const qIn = enc.encode('a=1&b=2')
-  const qOut = new Uint8Array(qIn.length * 9 + 16)
-  if (b.queryParsePackedInto(qIn, qOut) === 0) {
-    return false
-  }
-  const cIn = enc.encode('a=1; b=2')
-  const cOut = new Uint8Array(cIn.length * 9 + 16)
-  if (b.cookieParsePackedInto(cIn, cOut) === 0) {
-    return false
-  }
-
-  // ── Excluded-surface additions ────────────────────────────────────
-  // form parse shares the query core → 2 pairs.
-  const fIn = enc.encode('a=1&b=2')
-  const fOut = new Uint8Array(fIn.length * 9 + 16)
-  if (b.formParsePackedInto(fIn, fOut) === 0 || fOut[0] !== 2) {
-    return false
-  }
-
-  // multipart parse → 1 part named "field".
-  const boundary = enc.encode('----boundary')
-  // Wire format is `--{boundary}` — boundary is `----boundary`, so the body
-  // must open with `------boundary`.
-  const mBody = enc.encode(
-    '------boundary\r\nContent-Disposition: form-data; name="field"\r\n\r\nvalue\r\n------boundary--',
-  )
-  const mOut = b.multipartParsePacked(mBody, boundary)
-  if (mOut[0] !== 1) {
-    return false
-  }
-  // Packed layout: [u32 count][u32 name_len][name]... → name_len at offset 4.
-  const mNameLen = (mOut[4] ?? 0) | ((mOut[5] ?? 0) << 8) | ((mOut[6] ?? 0) << 16) | ((mOut[7] ?? 0) << 24)
-  if (dec.decode(mOut.subarray(8, 8 + mNameLen)) !== 'field') {
-    return false
-  }
-
-  // WS frame decode: encode("hello") → decode → fin=1, opcode=1, payload="hello".
-  const wf = b.wsFrameEncode(1, SELFTEST_HEX, true, true)
-  const wd = b.wsFrameDecodePacked(wf)
-  if (wd === null || wd[0] !== 1 || wd[1] !== 1 || dec.decode(wd.subarray(6)) !== 'hello') {
-    return false
-  }
-  if (b.wsFrameDecodePacked(enc.encode('\x80')) !== null) {
-    return false
-  }
-
-  // JWT sign with ttl=0 (deterministic — no iat/exp), then verify the
-  // signature with the FFI HMAC to prove the binding is real.
-  const jwtSecret = enc.encode('my-secret')
-  const jwt = b.jwtSignBytes(enc.encode('{"sub":"user-1"}'), jwtSecret, 0, 0)
-  const jwtStr = dec.decode(jwt)
-  const segs = jwtStr.split('.')
-  if (segs.length !== 3 || segs[0] === '' || segs[1] === '' || segs[2] === '') {
-    return false
-  }
-  const signingInput = enc.encode(`${segs[0]}.${segs[1]}`)
-  const sigHex = dec.decode(b.hmacSha256(jwtSecret, signingInput))
-  const sigBytes = b.base64Decode(enc.encode(segs[2]), true, false)
-  if (sigBytes === null || dec.decode(b.hexEncode(sigBytes)) !== sigHex) {
-    return false
-  }
-
-  return true
-}