castrum 0.7.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

@@ -0,0 +1,61 @@
+// 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 { 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 {
+      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.
+      return asBigInt(resolveNative(ctx, 'jsonSumIds')(input) as unknown)
+    },
+    jsonPatch(doc: Uint8Array, patch: Uint8Array): Uint8Array | string {
+      const f = transport.ffi
+      if (f) {
+        try {
+          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:
+          // it either succeeds (too-small case) or throws the contextual
+          // "invalid document"/"invalid patch"/"apply failed" message.
+          return addon.jsonPatch(doc, patch)
+        }
+      }
+      return addon.jsonPatch(doc, patch)
+    },
+  }
+}

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

@@ -0,0 +1,241 @@
+// src/rust-ffi/scalar/payload.ts — Output / streaming scalar methods.
+//
+// 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 { 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 {
+      // Optimal by default under Bun: `Bun.gzipSync` (native zlib) is ~2x
+      // 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 (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 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 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 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 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 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) => ({
+        name: p.name,
+        filename: p.filename ?? null,
+        contentType: p.contentType ?? null,
+        data: p.data,
+      }))
+    },
+    multipartParsePacked(body: Uint8Array, boundary: Uint8Array): Uint8Array {
+      // Zero-copy packed sibling — no JS objects per part (see native types).
+      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 {
+      return resolveNative(ctx, 'wsFrameEncode')(opcode, payload, mask, fin) as Uint8Array
+    },
+    wsFrameEncodeInto(
+      opcode: number,
+      payload: Uint8Array,
+      mask: boolean,
+      fin: boolean,
+      output: Uint8Array,
+    ): number {
+      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 f = ffi()
+      if (f) {
+        // C ABI returns packed [flags][opcode][u32 len][payload]; decode here.
+        const packed = f.wsFrameDecodePacked(data)
+        if (packed === null) return null
+        const payloadLen =
+          ((packed[2] ?? 0) |
+            ((packed[3] ?? 0) << 8) |
+            ((packed[4] ?? 0) << 16) |
+            ((packed[5] ?? 0) << 24)) >>>
+          0
+        return {
+          fin: (packed[0] ?? 0) === 1,
+          opcode: packed[1] ?? 0,
+          payload: packed.subarray(6, 6 + payloadLen),
+        }
+      }
+      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

@@ -0,0 +1,121 @@
+// src/rust-ffi/text.ts — String-oriented FFI namespace (text in → text out).
+//
+// `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 { type RustClientContext, resolveNative } from './context'
+
+/** String-oriented FFI namespace. */
+export interface RustText {
+  /**
+   * Resolve a lowercase file extension to a MIME type string (e.g. `"html"` →
+   * `"text/html"`). Unknown extensions return `"application/octet-stream"`.
+   * @param ext the file extension WITHOUT a leading dot, case-insensitive.
+   * @returns the MIME type for `ext`.
+   */
+  mimeFromExtension(ext: string): string
+  /**
+   * RFC 3986 percent-encode a string (the `encodeURIComponent` unreserved
+   * set). Under Bun this delegates to the native `encodeURIComponent` for
+   * ~4x speed with byte-for-byte parity.
+   * @param input the string to encode.
+   * @returns the percent-encoded string.
+   */
+  urlEncode(input: string): string
+  /**
+   * Percent-decode a string. Throws on malformed `%XX` or invalid UTF-8
+   * output (parity with `decodeURIComponent`, which is used under Bun).
+   * @param input the percent-encoded string to decode.
+   * @returns the decoded string.
+   */
+  urlDecode(input: string): string
+  /**
+   * Compute the RFC 6455 `Sec-WebSocket-Accept` value for a client key.
+   * @param key the base64 `Sec-WebSocket-Key` header value.
+   * @returns the 28-byte base64 accept value.
+   */
+  wsAcceptKey(key: string): string
+  /** @param input an email address. @returns whether it is RFC-valid. */
+  validateEmail(input: string): boolean
+  /** @param input a UUID string. @returns whether it is a valid (v1-v8) UUID. */
+  validateUuid(input: string): boolean
+  /** @param input an IPv4 address. @returns whether it is valid. */
+  validateIpv4(input: string): boolean
+  /** @param input an IPv6 address. @returns whether it is valid. */
+  validateIpv6(input: string): boolean
+}
+
+/** 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.
+  const mimeStrCache = new Map<string, string>()
+
+  return {
+    mimeFromExtension(ext) {
+      let mime = mimeStrCache.get(ext)
+      if (mime === undefined) {
+        // 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
+    },
+    urlEncode(input) {
+      // 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 (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 (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
+    },
+  }
+}