castrum 0.9.0 → 0.9.1

package/src/native/ffi.ts

@@ -1,271 +1,82 @@
-// 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.
+// under Bun we can `dlopen` it and call the hot scalar functions directly.
+//
+// Structure: this file is the transport CORE (dlopen + symbol binding +
+// per-call wrappers). The pure pieces live 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 { decodeUtf8, encodeUtf8 } from '../shared/codec'
 import { resolveEnvVar } from '../shared/env'
 import { isBun } from '../shared/runtime'
+import {
+  COMPRESS_HEADROOM,
+  COMPRESS_INITIAL_CAP,
+  COMPRESS_MAX_CAP,
+  DECOMPRESS_FALLBACK_CAP,
+  DECOMPRESS_GUESS_MULTIPLIER_BROTLI,
+  DECOMPRESS_GUESS_MULTIPLIER_GZIP,
+  DECOMPRESS_MIN_INITIAL,
+  EMPTY_VIEW,
+  MAX_DECOMPRESSED,
+  MAX_JSON_PATCH_OUTPUT,
+} from './ffi/constants'
+import { selfTest } from './ffi/selftest'
+import type {
+  BunFFI,
+  FfiMode,
+  Raw2,
+  Raw3,
+  Raw4,
+  Raw5,
+  Raw6,
+  Raw7,
+  Raw8,
+  Raw9,
+  Raw10,
+  Raw12,
+  RawCStr,
+} 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 +103,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 +152,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,6 +178,7 @@ 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.
@@ -359,115 +189,280 @@ function bind(): BunFFI | null {
     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_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_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_accept_negotiator_negotiate: {
+        args: abi(['usize', 'ptr', 'usize']),
+        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,
       },
       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: ['ptr', 'usize'], returns: 'usize' },
+      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_route_destroy: { args: ['usize'], returns: 'void' },
     })
 
     const bindings = build(symbols as Record<string, (...a: unknown[]) => unknown>, useBufferLength)
@@ -493,60 +488,6 @@ function bind(): BunFFI | 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)
 
@@ -584,17 +525,37 @@ function writeOrThrow(w: number, inputLen: number, label: string): number {
   return w
 }
 
+/** Unpack the packed rate-limit verdict `[u8 allowed][u32 remaining LE][i64 reset_ms LE]`. */
+function unpackRateCheck(
+  out: Uint8Array,
+  view: DataView,
+): {
+  allowed: boolean
+  remaining: number
+  resetMs: number
+} {
+  return {
+    allowed: out[0] === 1,
+    remaining: view.getUint32(1, true),
+    resetMs: Number(view.getBigInt64(5, true)),
+  }
+}
+
 /** 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).
+ * Exact length of an argon2id PHC string for the given params
+ * (m/t/p/salt_len/out_len).
+ * Format: `$argon2id$v=19$m=<m>,t=<t>,p=<p>$<salt b64>$<hash b64>`.
+ * The salt b64 length is base64-no-pad of the CALLER's salt byte length
+ * (`SaltString::encode_b64`) — NOT a fixed 16 bytes. Hardcoding 22
+ * under-counts salts >16 bytes (e.g. the 18-byte "salty-salt-16bytes" →
+ * 24 chars) and growExact would re-run the whole ~tens-of-ms hash on the
+ * retry (measured 2× slowdown). Pre-sizing exactly keeps `passwordHash` a
+ * single native pass.
  */
-function argon2PhcLength(m: number, t: number, p: number, outLen: number): number {
+function argon2PhcLength(m: number, t: number, p: number, saltLen: number, outLen: number): number {
   return (
     15 + // "$argon2id$v=19$"
     2 + // "m="
@@ -604,7 +565,7 @@ function argon2PhcLength(m: number, t: number, p: number, outLen: number): numbe
     3 + // ",p="
     String(p).length +
     1 + // "$" before the salt
-    22 + // salt b64 (16 bytes)
+    b64Len(saltLen) + // salt b64 (no-pad — depends on the caller's salt length)
     1 + // "$" before the hash
     b64Len(outLen)
   )
@@ -618,6 +579,7 @@ function build(
   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 utf8Valid = sym.castrum_utf8_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
@@ -635,19 +597,39 @@ function build(
   // 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)
+  // Phase 1.1: under `buffer`/`buffer_length` the engine reads ptr + byteLength
+  // off the SAME view, so every `(ptr,len)` pair passes the view itself for the
+  // length slot (atomic snapshot, one JS arg fewer); under `(ptr,usize)` it's
+  // the explicit length. The branch is a bind-time constant → JIT folds it.
+  const lenOrView = (v: Uint8Array): Uint8Array | number => (useBufferLength ? 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 passwordVerifyBcrypt = sym.castrum_password_verify_bcrypt as Raw3
+  const wsAcceptKey = sym.castrum_ws_accept_key as RawCStr
+  const wsAcceptKeyInto = sym.castrum_ws_accept_key_into as Raw4
+  const etagCStr = sym.castrum_etag as RawCStr
+  const etagIntoRaw = sym.castrum_etag_into as Raw5
+  const conditionalIsNotModifiedRaw = sym.castrum_conditional_is_not_modified as Raw6
+  const mediaTypeMatcherMatchesRaw = sym.castrum_media_type_matcher_matches as Raw3
+  const acceptNegotiatorNegotiateRaw = sym.castrum_accept_negotiator_negotiate as RawCStr
+  const jwtSignerSignRaw = sym.castrum_jwt_signer_sign as Raw6
+  const jwtSignerVerifyRaw = sym.castrum_jwt_signer_verify as Raw6
+  const templateRenderRaw = sym.castrum_template_render as Raw5
+  const schemaValidatorValidateRaw = sym.castrum_schema_validator_validate as Raw3
+  const rateLimiterCheckRaw = sym.castrum_rate_limiter_check as Raw5
+  const rateLimiterCheckKeyRaw = sym.castrum_rate_limiter_check_key as Raw5
+  const randomToken = sym.castrum_random_token as RawCStr
+  const randomTokenInto = sym.castrum_random_token_into 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 signCookie = sym.castrum_sign_cookie as RawCStr
+  const signCookieInto = sym.castrum_sign_cookie_into as Raw6
+  const verifyCookie = sym.castrum_verify_cookie as RawCStr
+  const verifyCookieInto = sym.castrum_verify_cookie_into as Raw6
+  const csrfToken = sym.castrum_csrf_token as RawCStr
+  const csrfTokenInto = sym.castrum_csrf_token_into 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
@@ -663,12 +645,29 @@ function build(
   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 httpDateIntoRaw = sym.castrum_http_date_into as Raw3
+  const sseEncodeIntoRaw = sym.castrum_sse_encode_into as Raw10
+  const jwtSignBytes = sym.castrum_jwt_sign_bytes as RawCStr
+  const jsonParsePackedSym = sym.castrum_json_parse_packed as Raw4
+  const jwtSignBytesInto = sym.castrum_jwt_sign_bytes_into 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
+  // Phase 3 — stateless napi-only scalars.
+  const parseMediaTypeSym = sym.castrum_parse_media_type as Raw4
+  const parseHttpDateSym = sym.castrum_parse_http_date as Raw4
+  const parseAcceptEncodingSym = sym.castrum_parse_accept_encoding as Raw4
+  const urlEncodeQuerySym = sym.castrum_url_encode_query as (...a: unknown[]) => string | null
+  const urlResolveSym = sym.castrum_url_resolve as (...a: unknown[]) => string | null
+  const urlBuilderResolveRaw = sym.castrum_url_builder_resolve as Raw5
+  const mimeFromExtensionSym = sym.castrum_mime_from_extension as (...a: unknown[]) => string | null
+  const jwtVerifySym = sym.castrum_jwt_verify as (...a: unknown[]) => string | null
   const ingressHandlePacked = sym.castrum_ingress_handle_packed as Raw7
+  const ingressHandleComponentsSym = sym.castrum_ingress_handle_components as Raw12
   const ingressLayoutSym = sym.castrum_ingress_layout as Raw2
+  const routeCompileSym = sym.castrum_route_compile as Raw2
+  const routeRunSym = sym.castrum_route_run as Raw5
+  const routeDestroySym = sym.castrum_route_destroy as (a: unknown) => void
 
   // ── Encoder / decoder `Into` helpers ──────────────────────────────
   const hexEncodeInto = (input: Uint8Array, output: Uint8Array): number => {
@@ -677,11 +676,11 @@ function build(
     if (output.length < input.length * 2) {
       throw new Error('hex encode: output buffer too small')
     }
-    return Number(hexEncode(input, input.length, output, output.length))
+    return Number(hexEncode(input, lenOrView(input), output, lenOrView(output)))
   }
 
   const urlEncodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    const w = Number(urlEncode(input, input.length, output, output.length))
+    const w = Number(urlEncode(input, lenOrView(input), output, lenOrView(output)))
     // 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.
@@ -692,12 +691,12 @@ function build(
   }
 
   const hexDecodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    const w = Number(hexDecode(input, input.length, output, output.length))
+    const w = Number(hexDecode(input, lenOrView(input), output, lenOrView(output)))
     return writeOrThrow(w, input.length, 'hex decode')
   }
 
   const urlDecodeInto = (input: Uint8Array, output: Uint8Array): number => {
-    const w = Number(urlDecode(input, input.length, output, output.length))
+    const w = Number(urlDecode(input, lenOrView(input), output, lenOrView(output)))
     return writeOrThrow(w, input.length, 'url decode')
   }
 
@@ -711,9 +710,9 @@ function build(
     const w = Number(
       base64Decode(
         input,
-        input.length,
+        lenOrView(input),
         output,
-        output.length,
+        lenOrView(output),
         flag(urlSafe),
         flag(padding ?? true),
       ),
@@ -731,9 +730,9 @@ function build(
     const w = Number(
       base64Encode(
         input,
-        input.length,
+        lenOrView(input),
         output,
-        output.length,
+        lenOrView(output),
         flag(urlSafe),
         flag(padding ?? true),
       ),
@@ -743,60 +742,110 @@ function build(
     return writeOrThrow(w, input.length, 'base64 encode')
   }
 
+  // cstring-return (the engine clones the NUL-terminated string at call time)
+  // → the JS string directly (native transfer — zero encode); a `null` return
+  // is the C failure sentinel → throw.
+  const cstr = (s: string | null, label: string): string => {
+    if (s === null) throw new Error(label)
+    return s
+  }
+
   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) {
+    // Native pooled `_into`: writes 10/12 bytes directly into the caller
+    // buffer (no cstring round-trip). Needed-size convention: a write larger
+    // than `output.length` reports the exact required size → throw.
+    const w = Number(etagIntoRaw(data, lenOrView(data), flag(weak), output, lenOrView(output)))
+    if (w === 0) {
+      throw new Error('etag: invalid input')
+    }
+    if (w > output.length) {
       throw new Error('etag: output buffer too small')
     }
     return w
   }
 
+  // Pooled 9-byte scratch for jsonSumIds (the packed `[u8 ok][i64 sum LE]`
+  // output). The wrapper returns the BigInt VALUE (no byte aliasing escapes),
+  // so a single reused buffer + cached DataView is safe — removes the per-call
+  // Uint8Array + DataView allocs (measured ~400ns of the FFI wrapper cost).
+  const jsonSumOut = new Uint8Array(9)
+  const jsonSumView = new DataView(jsonSumOut.buffer)
+
+  // ── Reusable scratch for the STRING-returning encode wrappers ────────
+  // Each wrapper writes its result and decodes it into an immutable JS string
+  // (or primitive) SYNCHRONOUSLY before the next call reuses the buffer — the
+  // same safety rationale as `jsonSumOut` / `generateRequestId`. Per-Worker
+  // module state (single-threaded event loop); never shared across Workers.
+  // NOT used for byte-returning ops (hexDecode/urlDecode/base64Decode/aead/
+  // wsFrame/packed parsers): their returned `Uint8Array` aliases the buffer
+  // and escapes to the caller — those stay on `*Into` (caller-owned).
+  let encodeScratch = new Uint8Array(0)
+  const scratchFor = (size: number): Uint8Array => {
+    if (encodeScratch.byteLength < size) encodeScratch = new Uint8Array(size)
+    return encodeScratch
+  }
+  // Fixed-size packed-verdict scratch + cached DataViews (parseHttpDate 9 B,
+  // rate-limit check 13 B) — same pooled pattern as `jsonSumView`. Kept
+  // separate from the growable `encodeScratch` so the cached DataViews are
+  // never invalidated by a buffer replacement.
+  const dateScratch = new Uint8Array(9)
+  const dateScratchView = new DataView(dateScratch.buffer)
+  const rateScratch = new Uint8Array(13)
+  const rateScratchView = new DataView(rateScratch.buffer)
+
   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,
+    utf8Valid: (input) => Number(oneArg(utf8Valid, input)) === 1,
     hexEncode(input) {
-      const out = new Uint8Array(input.length * 2)
+      // Pooled scratch — decoded synchronously to an immutable string (safe;
+      // removes the per-call `new Uint8Array(len*2)`). ALWAYS decode the
+      // written subarray: the shared scratch may be larger than `w` (grown by
+      // an earlier op), so decoding the whole buffer would read stale bytes.
+      const out = scratchFor(input.length * 2)
       const w = hexEncodeInto(input, out)
-      return w === input.length * 2 ? out : out.subarray(0, w)
+      return decodeUtf8(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)
+      // RFC 3986 worst case is 3 bytes per input byte (`%XX`). Pooled scratch
+      // (decoded synchronously — safe).
+      const out = scratchFor(input.length * 3)
       const w = urlEncodeInto(input, out)
-      return out.subarray(0, w)
+      return decodeUtf8(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,
+    validateEmail: (input) => Number(validateEmail(input)) === 1,
+    validateUuid: (input) => Number(validateUuid(input)) === 1,
+    validateIpv4: (input) => Number(validateIpv4(input)) === 1,
+    validateIpv6: (input) => Number(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))
+      const w = Number(jsonSumRaw(input, lenOrView(input), jsonSumOut, lenOrView(jsonSumOut)))
       if (w === 0) {
         throw new Error('json sum ids: output buffer too small')
       }
-      if (out[0] === 0) {
+      if (jsonSumOut[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)
+      return jsonSumView.getBigInt64(1, true)
     },
     hmacSha256Verify: (key, data, signature) =>
-      Number(hmacVerify(key, key.length, data, data.length, signature, signature.length)) === 1,
+      Number(
+        hmacVerify(key, lenOrView(key), data, lenOrView(data), signature, lenOrView(signature)),
+      ) === 1,
     csrfVerify: (token, secret) =>
-      Number(csrfVerify(token, token.length, secret, secret.length)) === 1,
+      Number(csrfVerify(token, lenOrView(token), secret, lenOrView(secret))) === 1,
     passwordVerify: (password, phc) =>
-      Number(passwordVerify(password, password.length, phc, phc.length)) === 1,
+      Number(passwordVerify(password, lenOrView(password), phc, lenOrView(phc))) === 1,
     passwordVerifyBcrypt: (password, phc) =>
-      Number(passwordVerifyBcrypt(password, password.length, phc, phc.length)) === 1,
+      Number(passwordVerifyBcrypt(password, lenOrView(password), phc)) === 1,
 
     hexDecode(input) {
       const out = new Uint8Array(Math.floor(input.length / 2))
@@ -818,121 +867,291 @@ function build(
     base64DecodeInto,
 
     wsAcceptKey(key) {
-      const out = new Uint8Array(28)
-      const w = Number(wsAcceptKey(key, key.length, out, out.length))
+      return cstr(wsAcceptKey(key), 'ws accept key: bad key')
+    },
+    wsAcceptKeyInto(key, output) {
+      // Native pooled `_into`: writes the 28-byte accept key directly into the
+      // caller buffer (no cstring round-trip). Needed-size convention.
+      const w = Number(wsAcceptKeyInto(key, lenOrView(key), output, lenOrView(output)))
       if (w === 0) {
-        throw new Error('ws accept key: bad key or output buffer too small')
+        throw new Error('ws accept key: bad key')
       }
-      return out.subarray(0, w)
+      if (w > output.length) {
+        throw new Error('ws accept key: output buffer too small')
+      }
+      return w
     },
     etag(data, weak) {
-      const out = new Uint8Array(12)
-      const w = etagInto(data, out, weak)
-      return out.subarray(0, w)
+      // cstring return (10 strong / 12 weak chars) — zero encode.
+      return cstr(etagCStr(data, lenOrView(data), flag(weak)), 'etag: invalid input')
     },
     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')
+    conditionalIsNotModified(inner, ifNoneMatch, ifModifiedSince) {
+      // Opaque-handle eval of the precompiled `ConditionalRequest` state.
+      // flags bit0 = If-None-Match present, bit1 = If-Modified-Since present
+      // (present-but-empty is distinct from absent — napi Option parity). A
+      // null handle (0) → 0 (never dereferences freed state).
+      const flags = (ifNoneMatch === null ? 0 : 1) | (ifModifiedSince === null ? 0 : 2)
+      const inm = ifNoneMatch ?? EMPTY_VIEW
+      const ims = ifModifiedSince ?? EMPTY_VIEW
+      return (
+        Number(
+          conditionalIsNotModifiedRaw(inner, inm, lenOrView(inm), ims, lenOrView(ims), flags),
+        ) === 1
+      )
+    },
+    mediaTypeMatcherMatches(inner, actual) {
+      // Precompiled expected-type match → u8.
+      return Number(mediaTypeMatcherMatchesRaw(inner, actual, lenOrView(actual))) === 1
+    },
+    acceptNegotiatorNegotiate(inner, header) {
+      // cstring best-supported encoding; `null` = identity (napi Option parity).
+      return acceptNegotiatorNegotiateRaw(inner, header, lenOrView(header))
+    },
+    jwtSignerSign(inner, claimsJson, nowSeconds) {
+      // Precompiled key + ttl → compact token. 0 = invalid claims JSON (real
+      // error → growExact throws); w > output.length = exact needed size.
+      return growExact(
+        (out) =>
+          Number(
+            jwtSignerSignRaw(
+              inner,
+              claimsJson,
+              lenOrView(claimsJson),
+              BigInt(nowSeconds),
+              out,
+              lenOrView(out),
+            ),
+          ),
+        Math.min(claimsJson.length + 128, 64 * 1024),
+        1024 * 1024,
+        'jwt signer: invalid claims JSON or output buffer too small',
+      )
+    },
+    jwtSignerVerify(inner, token, nowSeconds) {
+      // Precompiled key → claims JSON bytes; 0 = invalid / expired → null.
+      const out = new Uint8Array(Math.min(token.length + 256, 64 * 1024))
+      const w = Number(
+        jwtSignerVerifyRaw(inner, token, lenOrView(token), BigInt(nowSeconds), out, lenOrView(out)),
+      )
+      if (w === 0) return null
+      if (w > out.length) {
+        const out2 = new Uint8Array(w)
+        const w2 = Number(
+          jwtSignerVerifyRaw(
+            inner,
+            token,
+            lenOrView(token),
+            BigInt(nowSeconds),
+            out2,
+            lenOrView(out2),
+          ),
+        )
+        return w2 === 0 ? null : out2.subarray(0, w2)
       }
       return out.subarray(0, w)
     },
+    templateRender(inner, contextJson) {
+      // Compiled template + pre-serialized JSON context → UTF-8 bytes. 0 =
+      // invalid context / render error (real error → growExact throws).
+      return growExact(
+        (out) =>
+          Number(
+            templateRenderRaw(inner, contextJson, lenOrView(contextJson), out, lenOrView(out)),
+          ),
+        Math.min(contextJson.length + 128, 64 * 1024),
+        1024 * 1024,
+        'template render: invalid context JSON or render failed',
+      )
+    },
+    schemaValidatorValidate(inner, doc) {
+      return Number(schemaValidatorValidateRaw(inner, doc, lenOrView(doc))) === 1
+    },
+    rateLimiterCheck(inner, key, nowMs) {
+      // Packed [u8 allowed][u32 remaining LE][i64 reset_ms LE] (13 bytes).
+      // Reused scratch + cached DataView (no per-call allocs). `key` is a
+      // `cstring` ARG (the engine transcodes the JS string in-engine).
+      const out = rateScratch
+      const w = Number(
+        rateLimiterCheckRaw(inner, key, BigInt(Math.trunc(nowMs)), out, lenOrView(out)),
+      )
+      if (w === 0) throw new Error('rate limiter check: null handle')
+      return unpackRateCheck(out, rateScratchView)
+    },
+    rateLimiterCheckKey(inner, key, nowMs) {
+      // Packed [u8 allowed][u32 remaining LE][i64 reset_ms LE] (13 bytes).
+      // Reused scratch + cached DataView (no per-call allocs).
+      const out = rateScratch
+      const w = Number(
+        rateLimiterCheckKeyRaw(inner, BigInt(key), BigInt(Math.trunc(nowMs)), out, lenOrView(out)),
+      )
+      if (w === 0) throw new Error('rate limiter check: null handle')
+      return unpackRateCheck(out, rateScratchView)
+    },
+    randomToken(byteLen) {
+      // cstring return of `byteLen*2` hex chars; byteLen 0 → empty string → empty
+      // Uint8Array (napi returns empty too). null = random source failed / >16MiB.
+      return cstr(
+        randomToken(byteLen),
+        'random token: output buffer too small or random source failed',
+      )
+    },
+    randomTokenInto(byteLen, output) {
+      // Pooled sibling: native writes `byteLen*2` hex chars directly into the
+      // caller buffer (no cstring round-trip). Needed-size convention: a write
+      // larger than `output.length` reports the exact required size → throw
+      // (the caller owns the buffer); 0 = real error (cap / RNG).
+      const w = Number(randomTokenInto(byteLen, output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('random token: random source failed or byteLen exceeds 16 MiB')
+      }
+      if (w > output.length) {
+        throw new Error('random token: output buffer too small')
+      }
+      return w
+    },
     base64Encode(input, urlSafe, padding) {
-      const out = new Uint8Array(Math.ceil(input.length / 3) * 4)
+      // Pooled scratch — decoded synchronously to an immutable string (safe).
+      const out = scratchFor(Math.ceil(input.length / 3) * 4)
       const w = base64EncodeInto(input, out, urlSafe, padding)
-      return out.subarray(0, w)
+      return decodeUtf8(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))
+      // Pooled 64-byte scratch — decoded synchronously (safe).
+      const out = scratchFor(64)
+      const w = Number(hmacSha256(key, lenOrView(key), data, lenOrView(data), out, lenOrView(out)))
       if (w === 0) {
         throw new Error('hmac sha256: output buffer too small')
       }
-      return out.subarray(0, w)
+      return decodeUtf8(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))
+      const w = Number(
+        hmacSha256(key, lenOrView(key), data, lenOrView(data), output, lenOrView(output)),
+      )
       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)
+      // `value.<64-hex>` returned as a cstring (value.length + 1 + 64 chars).
+      return cstr(
+        signCookie(value, lenOrView(value), secret, lenOrView(secret)),
+        'sign cookie: invalid input',
+      )
     },
     signCookieInto(value, secret, output) {
-      const need = value.length + 65
-      if (output.length < need) {
-        throw new Error('sign cookie: output buffer too small')
-      }
+      // Native pooled `_into`: writes `value.<64-hex>` directly into the caller
+      // buffer (no cstring round-trip — this is why pooled sign_cookie was
+      // previously a REGRESSION vs allocating). Needed-size convention.
       const w = Number(
-        signCookie(value, value.length, secret, secret.length, output, output.length),
+        signCookieInto(
+          value,
+          lenOrView(value),
+          secret,
+          lenOrView(secret),
+          output,
+          lenOrView(output),
+        ),
       )
       if (w === 0) {
+        throw new Error('sign cookie: invalid input')
+      }
+      if (w > output.length) {
         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)
+      // cstring return; `null` = invalid signature / malformed → null (napi parity).
+      // CAVEAT (refactor): the engine clones a UTF-8 string, so a cookie VALUE
+      // containing non-UTF-8 bytes or NUL cannot round-trip byte-faithfully on
+      // the FFI path (napi still does). Signed values are ASCII in practice.
+      const s = verifyCookie(signed, lenOrView(signed), secret, lenOrView(secret))
+      return s === null ? null : s
+    },
+    verifyCookieInto(signed, secret, output) {
+      // Native pooled `_into`: writes the verified value directly into the
+      // caller buffer. 0 = invalid signature / malformed → null (napi parity,
+      // like the allocating `verifyCookie`); a write larger than `output.length`
+      // reports the exact required size → throw.
+      const w = Number(
+        verifyCookieInto(
+          signed,
+          lenOrView(signed),
+          secret,
+          lenOrView(secret),
+          output,
+          lenOrView(output),
+        ),
+      )
+      if (w === 0) {
+        return null
+      }
+      if (w > output.length) {
+        throw new Error('verify cookie: output buffer too small')
+      }
+      return w
     },
     csrfToken(secret) {
-      const out = new Uint8Array(129)
-      const w = Number(csrfToken(secret, secret.length, out, out.length))
+      // 129-char `hex.hex` cstring return.
+      return cstr(
+        csrfToken(secret, lenOrView(secret)),
+        'csrf token: output buffer too small or random source failed',
+      )
+    },
+    csrfTokenInto(secret, output) {
+      // Native pooled `_into`: writes the 129-char `hex.hex` token directly
+      // into the caller buffer (no cstring round-trip). Needed-size convention.
+      const w = Number(csrfTokenInto(secret, lenOrView(secret), output, lenOrView(output)))
       if (w === 0) {
-        throw new Error('csrf token: output buffer too small or random source failed')
+        throw new Error('csrf token: random source failed')
       }
-      return out.subarray(0, w)
+      if (w > output.length) {
+        throw new Error('csrf token: output buffer too small')
+      }
+      return 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,
+      return decodeUtf8(
+        growExact(
+          (out) =>
+            Number(
+              passwordHash(
+                password,
+                lenOrView(password),
+                salt,
+                lenOrView(salt),
+                mCost,
+                tCost,
+                pCost,
+                outLen,
+                out,
+                lenOrView(out),
+              ),
             ),
-          ),
-        argon2PhcLength(mCost, tCost, pCost, outLen),
-        2 * 1024 * 1024,
-        'password hash: output buffer too small',
+          argon2PhcLength(mCost, tCost, pCost, salt.length, 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))
+      const w = Number(passwordHashBcrypt(password, lenOrView(password), cost, out, lenOrView(out)))
       if (w === 0) {
         throw new Error('password hash bcrypt: output buffer too small')
       }
-      return out.subarray(0, w)
+      return decodeUtf8(out.subarray(0, w))
     },
     pbkdf2Sha256(password, salt, rounds, dkLen) {
       // Rust clamps dkLen to [1, 1MiB] (PBKDF2_MIN_LEN/MAX_LEN) AFTER sizing its
@@ -940,7 +1159,16 @@ function build(
       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),
+        pbkdf2(
+          password,
+          lenOrView(password),
+          salt,
+          lenOrView(salt),
+          rounds,
+          dkLen,
+          out,
+          lenOrView(out),
+        ),
       )
       if (w === 0) {
         throw new Error('pbkdf2: output buffer too small')
@@ -953,14 +1181,14 @@ function build(
       const w = Number(
         aeadEncrypt(
           key,
-          key.length,
+          lenOrView(key),
           nonce,
-          nonce.length,
+          lenOrView(nonce),
           plaintext,
-          plaintext.length,
+          lenOrView(plaintext),
           algorithm,
           out,
-          out.length,
+          lenOrView(out),
         ),
       )
       if (w === 0) {
@@ -976,14 +1204,14 @@ function build(
       const w = Number(
         aeadEncrypt(
           key,
-          key.length,
+          lenOrView(key),
           nonce,
-          nonce.length,
+          lenOrView(nonce),
           plaintext,
-          plaintext.length,
+          lenOrView(plaintext),
           algorithm,
           output,
-          output.length,
+          lenOrView(output),
         ),
       )
       if (w === 0) {
@@ -996,14 +1224,14 @@ function build(
       const w = Number(
         aeadDecrypt(
           key,
-          key.length,
+          lenOrView(key),
           nonce,
-          nonce.length,
+          lenOrView(nonce),
           ciphertext,
-          ciphertext.length,
+          lenOrView(ciphertext),
           algorithm,
           out,
-          out.length,
+          lenOrView(out),
         ),
       )
       return w === 0 ? null : out.subarray(0, w)
@@ -1013,7 +1241,15 @@ function build(
       // 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),
+        wsFrameEncode(
+          opcode,
+          payload,
+          lenOrView(payload),
+          flag(mask),
+          flag(fin),
+          out,
+          lenOrView(out),
+        ),
       )
       if (w === 0) {
         throw new Error('ws frame encode: output buffer too small')
@@ -1030,11 +1266,11 @@ function build(
         wsFrameEncode(
           opcode,
           payload,
-          payload.length,
+          lenOrView(payload),
           flag(mask),
           flag(fin),
           output,
-          output.length,
+          lenOrView(output),
         ),
       )
       if (w === 0) {
@@ -1043,11 +1279,14 @@ function build(
       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',
+      return decodeUtf8(
+        growExact(
+          (out) =>
+            Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out))),
+          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) {
@@ -1058,14 +1297,17 @@ function build(
       // 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)),
+        (out) =>
+          Number(gzipCompress(data, lenOrView(data), Math.min(level, 9), out, lenOrView(out))),
         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))
+      const w = Number(
+        gzipCompress(data, lenOrView(data), Math.min(level, 9), output, lenOrView(output)),
+      )
       // Needed-size convention: w > output.length = too small; w === 0 = real error.
       if (w === 0) {
         throw new Error('gzip compress: invalid input')
@@ -1082,23 +1324,40 @@ function build(
       // 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 isize = Number(gzipIsize(data, lenOrView(data)))
       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)),
+        (out) => Number(gzipDecompress(data, lenOrView(data), max, out, lenOrView(out))),
         initial,
         max,
         'gzip decompress: invalid stream or exceeded max decompressed size',
       )
     },
+    gzipDecompressInto(data, output, maxDecompressed) {
+      // Pooled sibling — the C ABI streams the decompressed output directly
+      // into the caller buffer via the `_into` core (no internal Vec), keeping
+      // the 64 MiB decompression-bomb cap. Needed-size convention: w === 0 =
+      // real error (invalid stream / cap exceeded); w > output.length = exact
+      // required size → throw (nothing to grow — the caller owns the buffer).
+      const max = maxDecompressed ?? MAX_DECOMPRESSED
+      const w = Number(gzipDecompress(data, lenOrView(data), max, output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('gzip decompress: invalid stream or exceeded max decompressed size')
+      }
+      if (w > output.length) {
+        throw new Error('gzip decompress: output buffer too small')
+      }
+      return w
+    },
     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)),
+        (out) =>
+          Number(brotliCompress(data, lenOrView(data), Math.min(quality, 11), out, lenOrView(out))),
         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',
@@ -1106,7 +1365,7 @@ function build(
     },
     brotliCompressInto(data, output, quality = 5) {
       const w = Number(
-        brotliCompress(data, data.length, Math.min(quality, 11), output, output.length),
+        brotliCompress(data, lenOrView(data), Math.min(quality, 11), output, lenOrView(output)),
       )
       // Needed-size convention: w > output.length = too small; w === 0 = real error.
       if (w === 0) {
@@ -1124,7 +1383,7 @@ function build(
       // 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)),
+        (out) => Number(brotliDecompress(data, lenOrView(data), max, out, lenOrView(out))),
         Math.min(
           Math.max(data.length * DECOMPRESS_GUESS_MULTIPLIER_BROTLI, DECOMPRESS_MIN_INITIAL),
           DECOMPRESS_FALLBACK_CAP,
@@ -1133,24 +1392,41 @@ function build(
         'brotli decompress: invalid stream or exceeded max decompressed size',
       )
     },
+    brotliDecompressInto(data, output, maxDecompressed) {
+      // Pooled sibling — streams into the caller buffer, keeps the 64 MiB cap
+      // (same convention as gzipDecompressInto above).
+      const max = maxDecompressed ?? MAX_DECOMPRESSED
+      const w = Number(brotliDecompress(data, lenOrView(data), max, output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('brotli decompress: invalid stream or exceeded max decompressed size')
+      }
+      if (w > output.length) {
+        throw new Error('brotli decompress: output buffer too small')
+      }
+      return w
+    },
 
     httpParseRequestPackedInto(input, output) {
-      const w = Number(httpParsePacked(input, input.length, output, output.length))
+      const w = Number(httpParsePacked(input, lenOrView(input), output, lenOrView(output)))
       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) {
+      const w = Number(queryParsePacked(input, lenOrView(input), output, lenOrView(output)))
+      // Needed-size convention: w > output.length = exact required size →
+      // too-small (throw — the caller owns the buffer, nothing to grow);
+      // w === 0 = real error (malformed %XX).
+      if (w === 0 || w > output.length) {
         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) {
+      const w = Number(cookieParsePacked(input, lenOrView(input), output, lenOrView(output)))
+      // Needed-size convention (same as queryParsePackedInto).
+      if (w === 0 || w > output.length) {
         throw new Error('cookie parse: output buffer too small')
       }
       return w
@@ -1158,71 +1434,283 @@ function build(
 
     // ── 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,
+      // Compact HS256 token returned as a cstring (engine-cloned) — the Rust
+      // side builds the whole token and the JS pays zero decode. ttl<=0 = no
+      // iat/exp (napi Option<i64> sentinel). i64 args must be BigInt.
+      return cstr(
+        jwtSignBytes(
+          claimsJson,
+          lenOrView(claimsJson),
+          secret,
+          lenOrView(secret),
+          BigInt(ttl),
+          BigInt(now),
+        ),
+        'jwt sign: invalid claims JSON',
+      )
+    },
+    jwtSignBytesInto(claimsJson, secret, ttl, now, output) {
+      // Native pooled `_into`: writes the compact token directly into the
+      // caller buffer (no cstring round-trip). Needed-size convention: a write
+      // larger than `output.length` reports the exact required size → throw;
+      // 0 = invalid claims JSON.
+      const w = Number(
+        jwtSignBytesInto(
+          claimsJson,
+          lenOrView(claimsJson),
+          secret,
+          lenOrView(secret),
+          BigInt(ttl),
+          BigInt(now),
+          output,
+          lenOrView(output),
         ),
-        1024 * 1024,
-        'jwt sign: output buffer too small',
       )
+      if (w === 0) {
+        throw new Error('jwt sign: invalid claims JSON')
+      }
+      if (w > output.length) {
+        throw new Error('jwt sign: output buffer too small')
+      }
+      return w
     },
     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))
+      const w = Number(wsFrameDecodePacked(data, lenOrView(data), out, lenOrView(out)))
       return w === 0 ? null : out.subarray(0, w)
     },
+    wsFrameDecodePackedInto(data, output) {
+      // Pooled sibling: the caller provides the output buffer, sized to at
+      // least `data.length + 6` (6-byte header + payload — the Rust core
+      // returns 0 for BOTH too-small and malformed, so the caller must size
+      // to the max; the allocating path always does). 0 = malformed → null,
+      // mirroring the allocating path's return contract.
+      const w = Number(wsFrameDecodePacked(data, lenOrView(data), output, lenOrView(output)))
+      return w === 0 ? null : w
+    },
     multipartParsePacked(body, boundary) {
       return growExact(
         (out) =>
           Number(
-            multipartParsePacked(body, body.length, boundary, boundary.length, out, out.length),
+            multipartParsePacked(
+              body,
+              lenOrView(body),
+              boundary,
+              lenOrView(boundary),
+              out,
+              lenOrView(out),
+            ),
           ),
         Math.min(body.length + boundary.length + 64, 64 * 1024),
         128 * 1024 * 1024,
         'multipart parse: output buffer too small',
       )
     },
+    multipartParsePackedInto(body, boundary, output) {
+      // Pooled sibling: the caller provides the output buffer. Needed-size
+      // convention (same as queryParsePackedInto): w > output.length = exact
+      // required size → throw; w === 0 = real error (malformed).
+      const w = Number(
+        multipartParsePacked(
+          body,
+          lenOrView(body),
+          boundary,
+          lenOrView(boundary),
+          output,
+          lenOrView(output),
+        ),
+      )
+      if (w === 0 || w > output.length) {
+        throw new Error('multipart parse: output buffer too small or malformed body')
+      }
+      return w
+    },
     formParsePackedInto(input, output) {
-      const w = Number(formParsePacked(input, input.length, output, output.length))
-      if (w === 0 && input.length !== 0) {
+      const w = Number(formParsePacked(input, lenOrView(input), output, lenOrView(output)))
+      // Needed-size convention (form aliases the query core — same convention).
+      if (w === 0 || w > output.length) {
         throw new Error('form parse: output buffer too small')
       }
       return w
     },
+
+    // ── Wired WIP surface (JWT verify, task group) ──
+    jsonParsePacked(input) {
+      // Packed token stream (deduped string table + typed value tree) — the
+      // scalar wrapper assembles the JS value from the tokens with NO second
+      // JSON text parse. `0` = invalid JSON (real error → growExact throws);
+      // `w > out.length` = exact required size (one exact retry).
+      return growExact(
+        (out) => Number(jsonParsePackedSym(input, lenOrView(input), out, lenOrView(out))),
+        Math.min(input.length + (input.length >> 1), 16 * 1024 * 1024),
+        Math.max(1024 * 1024, input.length * 16),
+        'json parse packed: invalid JSON or output buffer too small',
+      )
+    },
+    parseMediaType(input) {
+      // Packed verdict: [u32 mediaTypeLen][mediaType][u32 charsetLen
+      // (0xFFFFFFFF = none)][charset][u32 boundaryLen][boundary]
+      // [u32 paramCount]{[u32 keyLen][key][u32 valLen][val]}. 0 = invalid media
+      // type (real error → growExact throws); w > output.length = exact needed
+      // size (one exact retry).
+      return growExact(
+        (out) => Number(parseMediaTypeSym(input, lenOrView(input), out, lenOrView(out))),
+        Math.min(input.length + 64, 64 * 1024),
+        1024 * 1024,
+        'media type parse: invalid media type or output buffer too small',
+      )
+    },
+    parseHttpDate(input) {
+      // Packed [u8 ok][i64 secs LE] (9 B) / 1 B (ok=0). A too-small buffer is
+      // never a 0 here — the Rust side reports the exact size (9/1) — so a 9-byte
+      // buffer always succeeds. Reused scratch + cached DataView (no per-call
+      // allocs).
+      const out = dateScratch
+      const w = Number(parseHttpDateSym(input, lenOrView(input), out, lenOrView(out)))
+      if (w === 0) {
+        throw new Error('http date parse: output buffer too small')
+      }
+      if (out[0] === 0) return null
+      return dateScratchView.getBigInt64(1, true)
+    },
+    parseAcceptEncoding(input) {
+      // Packed: [u32 count]{[u32 encLen][enc][f32 q][u32 order]} (empty header →
+      // count 0, 4 bytes). 0 = too small (real error → growExact throws).
+      return growExact(
+        (out) => Number(parseAcceptEncodingSym(input, lenOrView(input), out, lenOrView(out))),
+        Math.min(input.length + 64, 64 * 1024),
+        1024 * 1024,
+        'accept encoding parse: output buffer too small',
+      )
+    },
+    urlEncodeQuery(input) {
+      // Packed pairs `[u32 count]{[u32 keyLen][key][u32 valLen][val]}` (the JS
+      // `packPairs` layout) → percent-encoded query TEXT as a cstring, keys
+      // SORTED (matches the napi BTreeMap ordering). `null` = malformed packed
+      // input / non-UTF-8 (napi parity: throws).
+      return urlEncodeQuerySym(input, lenOrView(input))
+    },
+    urlResolve(base, reference) {
+      // RFC 3986 resolution → cstring; `null` = non-UTF-8 input (napi parity).
+      return urlResolveSym(base, lenOrView(base), reference, lenOrView(reference))
+    },
+    urlBuilderResolve(inner, reference) {
+      // Opaque-handle resolve against a `UrlBuilder`'s PRECOMPILED base. 0 =
+      // null handle / non-UTF-8 reference (real error → growExact throws);
+      // w > output.length = exact needed size (one exact retry).
+      return growExact(
+        (out) =>
+          Number(urlBuilderResolveRaw(inner, reference, lenOrView(reference), out, lenOrView(out))),
+        Math.min(reference.length * 2 + 128, 64 * 1024),
+        1024 * 1024,
+        'url builder resolve: invalid reference or output buffer too small',
+      )
+    },
+    mimeFromExtension(ext) {
+      // Extension → MIME → cstring (cstring ARG: the engine transcodes the JS
+      // extension in-engine); unknown → `application/octet-stream` (never null).
+      return mimeFromExtensionSym(ext)
+    },
+    jwtVerify(token, secret, nowSeconds) {
+      // Verify an HS256 JWT → claims as a JSON cstring; `null` = invalid
+      // signature / expired / malformed (napi Option parity). `now` is an i64
+      // C arg → must be passed as BigInt.
+      return jwtVerifySym(token, lenOrView(token), secret, lenOrView(secret), BigInt(nowSeconds))
+    },
+
+    // ── Napi-only hot ops, now FFI (kills the napi crossing) ──────
+    httpDateInto(secs, output) {
+      // 29-byte HTTP-date into the caller buffer. 0 = too-small buffer or
+      // out-of-range year (napi httpDateInto throws on both).
+      const w = Number(httpDateIntoRaw(secs, output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('http date: output buffer too small or year out of range')
+      }
+      return w
+    },
+    httpDate(secs) {
+      // Allocating sibling — 32-byte buffer always fits the 29-byte date, so
+      // the only 0 case is an out-of-range year (napi falls back to the
+      // allocating format! there — mirror with Date.toUTCString). Pooled
+      // scratch (decoded synchronously — safe).
+      const out = scratchFor(32)
+      const w = Number(httpDateIntoRaw(secs ?? 0, out, lenOrView(out)))
+      if (w !== 0) return decodeUtf8(out.subarray(0, w))
+      return new Date((secs ?? 0) * 1000).toUTCString()
+    },
+    sseEncodeEvent(event, data, id, retry) {
+      // One SSE event → bytes. event/id are encoded to UTF-8 only when
+      // non-null (flag bits 1/2/4 = present) so a present-but-empty string is
+      // distinct from absent (napi Option parity). growExact with the needed-size
+      // convention; `data.length + 64` covers the common single-line case.
+      const ev = event === null ? EMPTY_VIEW : encodeUtf8(event)
+      const idv = id === null ? EMPTY_VIEW : encodeUtf8(id)
+      const flags = (event === null ? 0 : 1) | (id === null ? 0 : 2) | (retry === null ? 0 : 4)
+      return growExact(
+        (out) =>
+          Number(
+            sseEncodeIntoRaw(
+              ev,
+              lenOrView(ev),
+              data,
+              lenOrView(data),
+              idv,
+              lenOrView(idv),
+              flags,
+              retry ?? 0,
+              out,
+              lenOrView(out),
+            ),
+          ),
+        data.length + 64,
+        1 << 20,
+        'sse encode: output buffer too small',
+      )
+    },
+    sseEncodeEventInto(event, data, id, retry, output) {
+      // Pooled sibling — caller-owned output buffer (sized ≥ `data.length + 64`
+      // for the common single-line case). Needed-size convention: w > output.length
+      // = exact required size → throw; w === 0 = real error (invalid UTF-8).
+      const ev = event === null ? EMPTY_VIEW : encodeUtf8(event)
+      const idv = id === null ? EMPTY_VIEW : encodeUtf8(id)
+      const flags = (event === null ? 0 : 1) | (id === null ? 0 : 2) | (retry === null ? 0 : 4)
+      const w = Number(
+        sseEncodeIntoRaw(
+          ev,
+          lenOrView(ev),
+          data,
+          lenOrView(data),
+          idv,
+          lenOrView(idv),
+          flags,
+          retry ?? 0,
+          output,
+          lenOrView(output),
+        ),
+      )
+      if (w === 0) {
+        throw new Error('sse encode: invalid UTF-8 in event/id')
+      }
+      if (w > output.length) {
+        throw new Error('sse encode: output buffer too small')
+      }
+      return w
+    },
+
     ingressHandlePacked(inner, input, body, output) {
       const w = Number(
         ingressHandlePacked(
           inner,
           input,
-          input.length,
+          lenOrView(input),
           body ?? EMPTY_VIEW,
-          body?.length ?? 0,
+          // Under `buffer_length` the length slot must be a view (the engine
+          // reads byteLength off it) — `EMPTY_VIEW` has byteLength 0, matching
+          // a null body; under `(ptr,usize)` it's the explicit length 0.
+          body ? lenOrView(body) : lenOrView(EMPTY_VIEW),
           output,
-          output.length,
+          lenOrView(output),
         ),
       )
       if (w === 0) {
@@ -1230,312 +1718,58 @@ function build(
       }
       return w
     },
+    ingressHandleComponents(inner, methodKind, url, ip, rid, headers, body, output) {
+      // `url`/`ip` are passed as JS strings to `cstring` args — the engine
+      // transcodes them to call-scoped NUL-terminated UTF-8 buffers in-engine
+      // (no JS-side `Buffer.write` encode, no frame assembly for URL/IP).
+      const w = Number(
+        ingressHandleComponentsSym(
+          inner,
+          methodKind,
+          url,
+          ip,
+          rid,
+          lenOrView(rid),
+          headers,
+          lenOrView(headers),
+          body ?? EMPTY_VIEW,
+          body ? lenOrView(body) : lenOrView(EMPTY_VIEW),
+          output,
+          lenOrView(output),
+        ),
+      )
+      if (w === 0) {
+        throw new Error('ingress components: output buffer too small or pipeline error')
+      }
+      return w
+    },
     ingressLayout(out) {
-      const w = Number(ingressLayoutSym(out, out.length))
+      const w = Number(ingressLayoutSym(out, lenOrView(out)))
       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
+    routeCompile(descriptor) {
+      const handle = Number(routeCompileSym(descriptor, lenOrView(descriptor)))
+      if (handle === 0) {
+        throw new Error('route compile: invalid route descriptor')
+      }
+      return handle
+    },
+    routeRun(handle, frame, output) {
+      // Needed-size convention: `0` = real error (malformed frame / panic); a
+      // write larger than `output.length` is the EXACT required size (caller
+      // allocates once and retries) — only a `0` write throws here.
+      const w = Number(routeRunSym(handle, frame, lenOrView(frame), output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('route run: malformed frame or pipeline error')
+      }
+      return w
+    },
+    routeDestroy(handle) {
+      routeDestroySym(handle)
+    },
   }
-
-  return true
 }