castrum 0.9.0 → 0.9.1

package/src/rust-ffi/scalar/json-packed.ts

@@ -0,0 +1,175 @@
+// src/rust-ffi/scalar/json-packed.ts — packed JSON token-stream decoder.
+//
+// Decodes the output of `castrum_json_parse_packed` (layout documented in
+// `src/native/ffi/types.ts`) into a JS value. The C side parses ONCE with
+// sonic-rs and emits a typed token stream with a DEDUPLICATED string table, so
+// the JS side never re-parses JSON text and decodes each unique string exactly
+// once (no per-occurrence decode — a per-occurrence blob + JS `slice` was ~10x
+// worse due to rope strings). This is what makes `rust.jsonParse` competitive
+// with Bun's own `JSON.parse` (the old FFI cstring path re-serialized the whole
+// doc to text and re-parsed it — measured ~3.92x slower on the 5k-row fixture).
+
+import { decodeUtf8 } from '../../shared/codec'
+import { isBun } from '../../shared/runtime'
+
+const TAG_NULL = 0
+const TAG_FALSE = 1
+const TAG_TRUE = 2
+const TAG_NUMBER = 3
+const TAG_STRING = 4
+const TAG_ARRAY_START = 5
+const TAG_OBJECT_START = 6
+const TAG_ARRAY_END = 7
+const TAG_OBJECT_END = 8
+const TAG_KEY = 9
+
+// Hoisted `bun:ffi` codec. The generic `decodeUtf8` (src/shared/codec.ts) does
+// a `require('bun:ffi')` on EVERY call, which is fine for the few strings the
+// ingress path decodes per request but not for a string table with thousands
+// of entries (the 5k-row fixture decodes ~5k unique strings). Resolve the
+// codec ONCE and reuse it; the Node fallback just delegates to the codec.
+let bunFfiCodec: typeof import('bun:ffi') | null | undefined
+
+function fastDecodeUtf8(bytes: Uint8Array): string {
+  if (bytes.byteLength === 0) return ''
+  if (bunFfiCodec === undefined) {
+    bunFfiCodec = null
+    if (isBun()) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        bunFfiCodec = require('bun:ffi') as typeof import('bun:ffi')
+      } catch {
+        bunFfiCodec = null
+      }
+    }
+  }
+  if (bunFfiCodec) {
+    return new bunFfiCodec.CString(bunFfiCodec.ptr(bytes), 0, bytes.byteLength).toString()
+  }
+  // Node fallback — only reachable if the FFI transport isn't live (this
+  // decoder is Bun-only in practice), so reuse the codec's TextDecoder branch.
+  return decodeUtf8(bytes)
+}
+
+/**
+ * Decode a packed token stream (from `ffi.jsonParsePacked`) into a JS value.
+ *
+ * Stream layout (all integers little-endian):
+ * `[u32 strCount]{[u32 len][utf8 bytes]}... [u32 treeLen][tree]` — a
+ * deduplicated string table followed by a single value encoded as a
+ * start/end-marker token stream:
+ * `0=null 1=false 2=true 3=number(f64 LE) 4=string(u32 table idx)
+ * 5=array start 6=object start 7=array end 8=object end
+ * 9=object key(u32 table idx)`.
+ * Object body: `6, (9, keyIdx, value)*, 8`.
+ *
+ * The result is deep-equal to what `JSON.parse` produces — numbers are emitted
+ * as f64 (JS number semantics) and duplicate object keys are last-wins.
+ *
+ * @param bytes - The packed stream from `ffi.jsonParsePacked`.
+ * @returns The parsed JS value.
+ *
+ * @example
+ * ```ts
+ * decodeJsonPacked(ffi.jsonParsePacked(enc.encode('{"a":1}'))) // { a: 1 }
+ * ```
+ */
+export function decodeJsonPacked(bytes: Uint8Array): unknown {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let p = 0
+  const u32 = (): number => {
+    const v = view.getUint32(p, true)
+    p += 4
+    return v
+  }
+
+  // Deduplicated string table — each unique string decoded exactly once.
+  const strCount = u32()
+  const strings = new Array<string>(strCount)
+  for (let i = 0; i < strCount; i++) {
+    const n = u32()
+    strings[i] = fastDecodeUtf8(bytes.subarray(p, p + n))
+    p += n
+  }
+
+  const treeLen = u32()
+  const end = p + treeLen
+
+  // Iterative decode with an explicit container stack (no recursion).
+  let root: unknown
+  // frame: { isObj, arr, obj, key } — for arrays values push into `arr`; for
+  // objects the pending `key` (set by TAG_KEY) receives the next value.
+  interface JsonFrame {
+    isObj: boolean
+    arr: unknown[]
+    obj: Record<string, unknown>
+    key: string
+  }
+  const frames: JsonFrame[] = []
+
+  const popFrame = (): JsonFrame => {
+    const f = frames.pop()
+    if (f === undefined) throw new Error('json parse: malformed packed stream')
+    return f
+  }
+
+  const attach = (v: unknown): void => {
+    const f = frames[frames.length - 1]
+    if (f === undefined) {
+      root = v
+      return
+    }
+    if (f.isObj) f.obj[f.key] = v
+    else f.arr.push(v)
+  }
+
+  while (p < end) {
+    // Tag byte — guaranteed in-bounds (p < end <= bytes.length).
+    const t = view.getUint8(p)
+    p += 1
+    switch (t) {
+      case TAG_NULL:
+        attach(null)
+        break
+      case TAG_FALSE:
+        attach(false)
+        break
+      case TAG_TRUE:
+        attach(true)
+        break
+      case TAG_NUMBER: {
+        const v = view.getFloat64(p, true)
+        p += 8
+        attach(v)
+        break
+      }
+      case TAG_STRING:
+        attach(strings[u32()] as string)
+        break
+      case TAG_ARRAY_START:
+        frames.push({ isObj: false, arr: [], obj: {}, key: '' })
+        break
+      case TAG_OBJECT_START:
+        frames.push({ isObj: true, arr: [], obj: {}, key: '' })
+        break
+      case TAG_ARRAY_END:
+        attach(popFrame().arr)
+        break
+      case TAG_OBJECT_END:
+        attach(popFrame().obj)
+        break
+      case TAG_KEY: {
+        const f = frames[frames.length - 1] as JsonFrame
+        f.key = strings[u32()] as string
+        break
+      }
+      default:
+        throw new Error('json parse: malformed packed token')
+    }
+  }
+
+  if (p !== end || frames.length !== 0) {
+    throw new Error('json parse: malformed packed stream')
+  }
+  return root
+}

package/src/rust-ffi/scalar/json.ts

@@ -1,36 +1,52 @@
 // src/rust-ffi/scalar/json.ts — JSON scalar methods.
 //
 // Mirrors rust/json/*: validate, DOM parse, id-sum and RFC 6902 patch.
+//
+// Runtime dispatch is centralized in the adapter (`ctx.runtime`): the native
+// call comes from `transport.ffi` / `transport.resolve` (bun:ffi first, napi
+// fallback) — no inline `getBunFFI()`.
 
-import { getBunFFI } from '../../native/ffi'
-import type { RustClientContext } from '../context'
+import { type RustClientContext, resolveNative } from '../context'
 import { asBigInt } from '../options'
+import { decodeJsonPacked } from './json-packed'
 
 /** JSON scalar methods (`Pick<RustScalar, ...>`). */
 export function buildJson(ctx: RustClientContext) {
   const { addon } = ctx
+  const { transport } = ctx.runtime
 
   return {
     jsonValid(input: Uint8Array): boolean {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.jsonValid(input)
-      return addon.jsonValid(input)
+      return resolveNative(ctx, 'jsonValid')(input) as boolean
     },
     jsonParse(input: Uint8Array): unknown {
+      // FFI-first STRUCTURAL parse: the C side parses once with sonic-rs and
+      // emits a packed token stream (all strings in ONE blob, referenced by
+      // char offsets); the JS decoder slices the blob with NO second JSON text
+      // parse. (The old cstring path re-serialized to text and re-parsed it —
+      // measured ~3.92x slower than Bun's JSON.parse on the 5k-row fixture.)
+      // Invalid JSON → growExact throws (napi parity).
+      //
+      // Deliberately NOT delegated to JSON.parse despite the ~2x loss: the
+      // native path throws on lone-surrogate escapes (`"\ude80"`) — a pinned,
+      // reviewed contract (json-packed-roundtrip.test.ts) — while JSON.parse
+      // accepts them. Delegating would diverge Bun from Node on that input.
+      const f = transport.ffi
+      if (f) {
+        return decodeJsonPacked(f.jsonParsePacked(input))
+      }
       return addon.jsonParse(input)
     },
     jsonSumIds(input: Uint8Array): bigint {
       // The C ABI returns a packed [u8 ok][i64 sum LE] output, so a legit
       // zero-sum and invalid input are unambiguous — no napi re-dispatch.
-      const ffi = getBunFFI()
-      if (ffi) return ffi.jsonSumIds(input)
-      return asBigInt(addon.jsonSumIds(input) as unknown)
+      return asBigInt(resolveNative(ctx, 'jsonSumIds')(input) as unknown)
     },
-    jsonPatch(doc: Uint8Array, patch: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) {
+    jsonPatch(doc: Uint8Array, patch: Uint8Array): Uint8Array | string {
+      const f = transport.ffi
+      if (f) {
         try {
-          return ffi.jsonPatch(doc, patch)
+          return f.jsonPatch(doc, patch)
         } catch {
           // The C ABI's 0 is ambiguous (too-small buffer vs a real error) and
           // carries no message. Re-dispatch to napi for exact error semantics:

package/src/rust-ffi/scalar/payload.ts

@@ -2,15 +2,75 @@
 //
 // Mirrors rust/payload/*: gzip/brotli compress, multipart parse, WebSocket
 // frame codec and SSE event framing.
+//
+// Runtime dispatch is centralized in the adapter (`ctx.runtime`): the Bun
+// gzipCompress delegation comes from `builtins.has(op)` and the native call
+// from `transport.ffi` / `transport.resolve` (bun:ffi first, napi fallback) —
+// no inline `isBun()` / `getBunFFI()`.
 
 import type { MultipartPart, WsFrame } from '../../native'
-import { getBunFFI } from '../../native/ffi'
-import { isBun } from '../../shared/runtime'
-import type { RustClientContext } from '../context'
+import { decoder } from '../../shared/bytes'
+import { writeInto } from '../into'
+import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
+
+/** Read an unsigned little-endian u32 at `off`. */
+function u32LE(b: Uint8Array, off: number): number {
+  return (
+    ((b[off] ?? 0) |
+      ((b[off + 1] ?? 0) << 8) |
+      ((b[off + 2] ?? 0) << 16) |
+      ((b[off + 3] ?? 0) << 24)) >>>
+    0
+  )
+}
+
+/**
+ * Unpack the `parts_to_packed` layout (`[u32 count]{[u32 name_len][name]
+ * [u8 has_filename][u32 filename_len][filename][u8 has_ct][u32 ct_len][ct]
+ * [u32 data_len][data]}`) into the object shape. Slices `data` by copy so the
+ * caller owns it (napi parity).
+ */
+function unpackMultipart(packed: Uint8Array): MultipartPart[] {
+  const count = u32LE(packed, 0)
+  let off = 4
+  const out: MultipartPart[] = []
+  for (let i = 0; i < count; i++) {
+    const nameLen = u32LE(packed, off)
+    off += 4
+    const name = decoder.decode(packed.subarray(off, off + nameLen))
+    off += nameLen
+    const hasFilename = packed[off] ?? 0
+    off += 1
+    const filenameLen = u32LE(packed, off)
+    off += 4
+    const filename =
+      hasFilename === 1 ? decoder.decode(packed.subarray(off, off + filenameLen)) : null
+    off += filenameLen
+    const hasCt = packed[off] ?? 0
+    off += 1
+    const ctLen = u32LE(packed, off)
+    off += 4
+    const contentType = hasCt === 1 ? decoder.decode(packed.subarray(off, off + ctLen)) : null
+    off += ctLen
+    const dataLen = u32LE(packed, off)
+    off += 4
+    const data = packed.subarray(off, off + dataLen).slice()
+    off += dataLen
+    out.push({ name, filename, contentType, data })
+  }
+  return out
+}
 
 /** Output / streaming scalar methods (`Pick<RustScalar, ...>`). */
 export function buildPayload(ctx: RustClientContext) {
   const { addon } = ctx
+  const { builtins, transport } = ctx.runtime
+  // Hoist the immutable per-runtime builtin-delegation decision into a
+  // bind-time flag (BUILTIN_OPS is a module constant — never mutated) so the
+  // hot path reads a property instead of a `Set.has`.
+  const HAS = { gzipCompress: builtins.has('gzipCompress') }
+  // Lazy-memoized ffi surface: binds on first call, single local read after.
+  const ffi = memoizeFfi(transport)
 
   return {
     gzipCompress(data: Uint8Array, level?: number | null): Uint8Array {
@@ -18,46 +78,62 @@ export function buildPayload(ctx: RustClientContext) {
       // faster than the rust+FFI crossing (decision matrix). Emits valid gzip
       // (decompression-parity with the addon — only the header OS byte
       // differs: 0xFF vs 0x03). `gzipCompressInto` (pooled) stays native.
-      if (isBun()) {
-        const opts = level != null ? ({ level } as Parameters<typeof Bun.gzipSync>[1]) : undefined
-        return Bun.gzipSync(data as unknown as Uint8Array<ArrayBuffer>, opts)
-      }
-      const ffi = getBunFFI()
-      if (ffi) return ffi.gzipCompress(data, level ?? undefined)
+      if (HAS.gzipCompress) return builtins.gzipCompress(data, level)
+      const f = ffi()
+      if (f) return f.gzipCompress(data, level ?? undefined)
       return addon.gzipCompress(data, level ?? null)
     },
     gzipCompressInto(data: Uint8Array, output: Uint8Array, level?: number | null): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.gzipCompressInto(data, output, level ?? undefined)
-      const bytes = addon.gzipCompress(data, level ?? null)
-      if (output.length < bytes.length) throw new Error('gzip compress: output buffer too small')
-      output.set(bytes)
-      return bytes.length
+      const f = ffi()
+      if (f) return f.gzipCompressInto(data, output, level ?? undefined)
+      return writeInto('gzip compress', output, addon.gzipCompress(data, level ?? null))
     },
     gzipDecompress(data: Uint8Array, maxDecompressed?: number | null): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.gzipDecompress(data, maxDecompressed ?? undefined)
+      const f = ffi()
+      if (f) return f.gzipDecompress(data, maxDecompressed ?? undefined)
       return addon.gzipDecompress(data, maxDecompressed ?? null)
     },
+    gzipDecompressInto(
+      data: Uint8Array,
+      output: Uint8Array,
+      maxDecompressed?: number | null,
+    ): number {
+      // Pooled sibling — caller-owned output buffer (the C ABI streams into
+      // it via the `_into` core; keeps the 64 MiB decompression-bomb cap).
+      const f = ffi()
+      if (f) return f.gzipDecompressInto(data, output, maxDecompressed ?? undefined)
+      return writeInto('gzip decompress', output, addon.gzipDecompress(data, maxDecompressed ?? null))
+    },
     brotliCompress(data: Uint8Array, quality?: number | null): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.brotliCompress(data, quality ?? undefined)
+      const f = ffi()
+      if (f) return f.brotliCompress(data, quality ?? undefined)
       return addon.brotliCompress(data, quality ?? null)
     },
     brotliCompressInto(data: Uint8Array, output: Uint8Array, quality?: number | null): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.brotliCompressInto(data, output, quality ?? undefined)
-      const bytes = addon.brotliCompress(data, quality ?? null)
-      if (output.length < bytes.length) throw new Error('brotli compress: output buffer too small')
-      output.set(bytes)
-      return bytes.length
+      const f = ffi()
+      if (f) return f.brotliCompressInto(data, output, quality ?? undefined)
+      return writeInto('brotli compress', output, addon.brotliCompress(data, quality ?? null))
     },
     brotliDecompress(data: Uint8Array, maxDecompressed?: number | null): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.brotliDecompress(data, maxDecompressed ?? undefined)
+      const f = ffi()
+      if (f) return f.brotliDecompress(data, maxDecompressed ?? undefined)
       return addon.brotliDecompress(data, maxDecompressed ?? null)
     },
+    brotliDecompressInto(
+      data: Uint8Array,
+      output: Uint8Array,
+      maxDecompressed?: number | null,
+    ): number {
+      // Pooled sibling — caller-owned output buffer (keeps the 64 MiB cap).
+      const f = ffi()
+      if (f) return f.brotliDecompressInto(data, output, maxDecompressed ?? undefined)
+      return writeInto('brotli decompress', output, addon.brotliDecompress(data, maxDecompressed ?? null))
+    },
     multipartParse(body: Uint8Array, boundary: Uint8Array): MultipartPart[] {
+      // FFI-first: packed parts (castrum_multipart_parse_packed) → unpack to
+      // the object shape. napi keeps its object path.
+      const f = ffi()
+      if (f) return unpackMultipart(f.multipartParsePacked(body, boundary))
       // Normalize napi `Option<String>` (undefined) → null and expose the
       // camelCase `contentType` key (napi renames `content_type` to camelCase).
       return addon.multipartParse(body, boundary).map((p) => ({
@@ -68,15 +144,18 @@ export function buildPayload(ctx: RustClientContext) {
       }))
     },
     multipartParsePacked(body: Uint8Array, boundary: Uint8Array): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.multipartParsePacked(body, boundary)
       // Zero-copy packed sibling — no JS objects per part (see native types).
-      return addon.multipartParsePacked(body, boundary)
+      return resolveNative(ctx, 'multipartParsePacked')(body, boundary) as Uint8Array
+    },
+    multipartParsePackedInto(body: Uint8Array, boundary: Uint8Array, output: Uint8Array): number {
+      // Pooled sibling — caller-owned output buffer (the napi addon has no
+      // packed `Into` for multipart, so copy via the allocating call there).
+      const f = ffi()
+      if (f) return f.multipartParsePackedInto(body, boundary, output)
+      return writeInto('multipart parse', output, addon.multipartParsePacked(body, boundary))
     },
     wsFrameEncode(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean): Uint8Array {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.wsFrameEncode(opcode, payload, mask, fin)
-      return addon.wsFrameEncode(opcode, payload, mask, fin)
+      return resolveNative(ctx, 'wsFrameEncode')(opcode, payload, mask, fin) as Uint8Array
     },
     wsFrameEncodeInto(
       opcode: number,
@@ -85,18 +164,15 @@ export function buildPayload(ctx: RustClientContext) {
       fin: boolean,
       output: Uint8Array,
     ): number {
-      const ffi = getBunFFI()
-      if (ffi) return ffi.wsFrameEncodeInto(opcode, payload, mask, fin, output)
-      const bytes = addon.wsFrameEncode(opcode, payload, mask, fin)
-      if (output.length < bytes.length) throw new Error('ws frame encode: output buffer too small')
-      output.set(bytes)
-      return bytes.length
+      const f = ffi()
+      if (f) return f.wsFrameEncodeInto(opcode, payload, mask, fin, output)
+      return writeInto('ws frame encode', output, addon.wsFrameEncode(opcode, payload, mask, fin))
     },
     wsFrameDecode(data: Uint8Array): WsFrame | null {
-      const ffi = getBunFFI()
-      if (ffi) {
+      const f = ffi()
+      if (f) {
         // C ABI returns packed [flags][opcode][u32 len][payload]; decode here.
-        const packed = ffi.wsFrameDecodePacked(data)
+        const packed = f.wsFrameDecodePacked(data)
         if (packed === null) return null
         const payloadLen =
           ((packed[2] ?? 0) |
@@ -112,13 +188,54 @@ export function buildPayload(ctx: RustClientContext) {
       }
       return addon.wsFrameDecode(data)
     },
+    wsFrameDecodePackedInto(data: Uint8Array, output: Uint8Array): number | null {
+      // Pooled sibling — caller-owned output buffer sized ≥ data.length + 6
+      // (6-byte header + payload). null = malformed frame. The napi addon has
+      // no packed decode, so that path re-packs the decoded object instead.
+      const f = ffi()
+      if (f) return f.wsFrameDecodePackedInto(data, output)
+      const frame = addon.wsFrameDecode(data)
+      if (frame === null) return null
+      const need = 6 + frame.payload.length
+      if (output.length < need) throw new Error('ws frame decode: output buffer too small')
+      output[0] = frame.fin ? 1 : 0
+      output[1] = frame.opcode
+      output[2] = frame.payload.length & 0xff
+      output[3] = (frame.payload.length >> 8) & 0xff
+      output[4] = (frame.payload.length >> 16) & 0xff
+      output[5] = (frame.payload.length >> 24) & 0xff
+      output.set(frame.payload, 6)
+      return need
+    },
     sseEncodeEvent(
       event: string | null,
       data: Uint8Array,
       id: string | null,
       retry: number | null,
     ): Uint8Array {
+      // FFI-first: the C-ABI `castrum_sse_encode_into` encodes directly into a
+      // caller buffer (no napi crossing / String args). napi fallback mirrors
+      // the Option semantics (null → line omitted).
+      const f = ffi()
+      if (f) return f.sseEncodeEvent(event, data, id, retry)
       return addon.sseEncodeEvent(event ?? null, data, id ?? null, retry ?? null)
     },
+    sseEncodeEventInto(
+      event: string | null,
+      data: Uint8Array,
+      id: string | null,
+      retry: number | null,
+      output: Uint8Array,
+    ): number {
+      // Pooled sibling — caller-owned output buffer (no per-call alloc). The
+      // napi addon has no `_into` variant, so that path re-encodes into the
+      // buffer via the allocating call.
+      const f = ffi()
+      if (f) return f.sseEncodeEventInto(event, data, id, retry, output)
+      const bytes = addon.sseEncodeEvent(event ?? null, data, id ?? null, retry ?? null)
+      if (output.length < bytes.length) throw new Error('sse encode: output buffer too small')
+      output.set(bytes)
+      return bytes.length
+    },
   }
 }

package/src/rust-ffi/text.ts

@@ -2,10 +2,14 @@
 //
 // `rust.text.*` is the ergonomic string API over the byte-level native
 // functions. Pure wrappers: encode input, call native, decode output.
+//
+// Runtime dispatch is centralized in the adapter (`ctx.runtime`): the Bun
+// built-in delegations (urlEncode/urlDecode) come from `builtins.has(op)` and
+// the native call from `transport.ffi` / `transport.resolve` (bun:ffi first,
+// napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
 import { decoder, encoder } from '../shared/bytes'
-import { isBun } from '../shared/runtime'
-import { resolveNative, type RustClientContext } from './context'
+import { type RustClientContext, resolveNative } from './context'
 
 /** String-oriented FFI namespace. */
 export interface RustText {
@@ -49,6 +53,7 @@ export interface RustText {
 
 /** Build the `text` namespace for a client context. */
 export function buildText(ctx: RustClientContext): RustText {
+  const { builtins, transport } = ctx.runtime
   // String memo: the byte path already caches the native bytes; this avoids the
   // encode → native lookup → slice → decode round-trip for repeated extension
   // strings (the common case) — 0 allocations on a cache hit.
@@ -58,7 +63,13 @@ export function buildText(ctx: RustClientContext): RustText {
     mimeFromExtension(ext) {
       let mime = mimeStrCache.get(ext)
       if (mime === undefined) {
-        mime = decoder.decode(ctx.cachedMime(encoder.encode(ext)))
+        // FFI-first: `cstring` ARG + cstring MIME return (native transfer both
+        // ways — the engine transcodes the extension in-engine, no JS encode).
+        // napi keeps the memoized-bytes path (cachedMime → decode).
+        const f = transport.ffi
+        mime = f
+          ? (f.mimeFromExtension(ext) ?? 'application/octet-stream')
+          : decoder.decode(ctx.cachedMime(encoder.encode(ext)))
         mimeStrCache.set(ext, mime)
       }
       return mime
@@ -67,28 +78,43 @@ export function buildText(ctx: RustClientContext): RustText {
       // Bun's native encodeURIComponent beats the rust+FFI/NAPI string crossing
       // (~4x, measured) with byte-for-byte parity (RFC 3986 unreserved set) —
       // see docs/bun-builtins-decision-matrix.md.
-      if (isBun()) return encodeURIComponent(input)
+      if (builtins.has('urlEncode')) return builtins.urlEncodeStr(input)
       return resolveNative(ctx, 'urlEncodeStr')(input) as string
     },
     urlDecode(input) {
       // decodeURIComponent matches the rust decoder on valid input and also
       // throws on malformed/invalid UTF-8 (URIError, an Error subclass).
-      if (isBun()) return decodeURIComponent(input)
+      if (builtins.has('urlDecode')) return builtins.urlDecodeStr(input)
       return resolveNative(ctx, 'urlDecodeStr')(input) as string
     },
     wsAcceptKey(key) {
+      // FFI-first: `cstring` ARG + cstring return (native transfer both ways —
+      // the engine transcodes the key in-engine, no JS encode). napi keeps the
+      // encode/decode path.
+      const f = transport.ffi
+      if (f) return f.wsAcceptKey(key)
       return decoder.decode(resolveNative(ctx, 'wsAcceptKey')(encoder.encode(key)) as Uint8Array)
     },
     validateEmail(input) {
+      // FFI-first: `cstring` ARG (the engine transcodes the string in-engine —
+      // no JS encode). napi fallback keeps the encode path.
+      const f = transport.ffi
+      if (f) return f.validateEmail(input)
       return resolveNative(ctx, 'validateEmail')(encoder.encode(input)) as boolean
     },
     validateUuid(input) {
+      const f = transport.ffi
+      if (f) return f.validateUuid(input)
       return resolveNative(ctx, 'validateUuid')(encoder.encode(input)) as boolean
     },
     validateIpv4(input) {
+      const f = transport.ffi
+      if (f) return f.validateIpv4(input)
       return resolveNative(ctx, 'validateIpv4')(encoder.encode(input)) as boolean
     },
     validateIpv6(input) {
+      const f = transport.ffi
+      if (f) return f.validateIpv6(input)
       return resolveNative(ctx, 'validateIpv6')(encoder.encode(input)) as boolean
     },
   }