castrum 0.9.4 → 0.9.7

package/src/native/ffi/build/task.ts

@@ -0,0 +1,79 @@
+// src/native/ffi/build/task.ts — off-thread task runtime BunFFI methods.
+//
+// The thinnest possible binding: `rust/task/` owns the pool, the result ring,
+// and the batched doorbell. This file only adapts the `(ptr,len)` ABI pair
+// (probe-gated `buffer`/`buffer_length` vs explicit lengths) and converts the
+// `u64_fast` byte counts to numbers.
+//
+// See docs/RND-CONCURRENCY.md for the design and the measured costs.
+
+import type { BunFFI, Raw0, Raw2, Raw4, Raw6 } from '../types'
+import type { BuildCtx } from './util'
+
+/** Raw 1-arg C-ABI symbol signature (a lone scalar arg or a bare pointer). */
+type Raw1 = (a: unknown) => number | bigint
+
+/**
+ * Build the off-thread task-runtime methods of the BunFFI surface. `ctx`
+ * supplies the probe-gated length adapter (`lenOrView`).
+ */
+export function buildTask(
+  sym: Record<string, (...a: unknown[]) => unknown>,
+  ctx: BuildCtx,
+): Partial<BunFFI> {
+  const { lenOrView } = ctx
+
+  const init = sym.castrum_task_init as Raw1
+  const submit = sym.castrum_task_submit as Raw4
+  const submitOut = sym.castrum_task_submit_out as Raw6
+  const submitSlice = sym.castrum_task_submit_slice as Raw6
+  const drain = sym.castrum_task_drain as Raw2
+  const pending = sym.castrum_task_pending as Raw0
+  const cancel = sym.castrum_task_cancel as Raw1
+  const setDoorbell = sym.castrum_task_set_doorbell as Raw1
+  const shutdown = sym.castrum_task_shutdown as Raw0
+  const threads = sym.castrum_task_threads as Raw0
+
+  return {
+    taskInit: (n) => Number(init(n)),
+    // `args` is copied onto the worker by Rust, so the caller's pooled buffer
+    // may be released as soon as this returns.
+    taskSubmit: (op, args, taskId) => Number(submit(op, args, lenOrView(args), taskId)),
+    taskSubmitOut: (op, args, taskId, output) =>
+      Number(submitOut(op, args, lenOrView(args), taskId, output, lenOrView(output))),
+    // Zero-copy INPUT: the header is copied by Rust, the payload is read in
+    // place — which is why the runtime must hold a reference to `data` for the
+    // whole task (see `Deferred.keep` in src/task/runtime.ts).
+    taskSubmitSlice: (op, hdr, data, taskId) =>
+      Number(submitSlice(op, hdr, lenOrView(hdr), data, lenOrView(data), taskId)),
+    taskDrain: (output) => Number(drain(output, lenOrView(output))),
+    taskPending: () => Number(pending()),
+    taskCancel: (taskId) => Number(cancel(taskId)),
+    taskSetDoorbell: (ptr) => Number(setDoorbell(ptr)),
+    taskShutdown: () => Number(shutdown()),
+    taskThreads: () => Number(threads()),
+  }
+}
+
+/**
+ * Bind-time self-test for the task symbols. The pool is intentionally NOT
+ * started here (no threads at import time) and no completion is produced;
+ * the full submit→drain→doorbell path is exercised by `test/unit/task/`.
+ */
+export function selfTestTask(b: BunFFI): boolean {
+  try {
+    if (typeof b.taskPending() !== 'number') return false
+    if (typeof b.taskThreads() !== 'number' || b.taskThreads() < 0) return false
+    // `0` disables the doorbell — safe at bind time (nothing is in flight).
+    if (b.taskSetDoorbell(0) !== 1) return false
+    // An empty ring → 0; exercises the drain symbol without allocating anything.
+    if (typeof b.taskDrain(new Uint8Array(4)) !== 'number') return false
+    // NOT called: submitting here would start the pool threads at bind time.
+    // The full submit/submit_out path is exercised by test/unit/task/.
+    if (typeof b.taskSubmitOut !== 'function') return false
+    if (typeof b.taskSubmitSlice !== 'function') return false
+    return true
+  } catch {
+    return false
+  }
+}

package/src/native/ffi/build/util.ts

@@ -42,6 +42,24 @@ export interface BuildCtx {
 /** Coerce an optional boolean to the C `u8` flag (1/0). */
 export const flag = (v?: boolean): number => (v ? 1 : 0)
 
+/**
+ * Does this string contain a NUL (`U+0000`)?
+ *
+ * `bun:ffi` transcodes a JS string passed to a `cstring` ARG into a
+ * NUL-TERMINATED UTF-8 buffer, so an embedded NUL SILENTLY TRUNCATES the value
+ * on the native side (Bun's docs describe the transcode; the truncation is the
+ * C convention it inherits). That is fine when the string is developer-supplied
+ * config or NUL-free by construction — and it is a real bug when the callee
+ * answers with a VERDICT (validators, query/cookie gates, batch validators: a
+ * truncated prefix passes where the full input fails) or when the exact bytes
+ * are the result (`regexEscape`, metric label values).
+ *
+ * Guard contract for every `cstring` ARG reachable from user input: either
+ * reject/short-circuit on NUL, or route to the `(ptr, usize)` byte form which
+ * carries the exact length. `test/unit/native/cstring-nul.test.ts` pins this.
+ */
+export { hasNul } from '../../../shared/bytes'
+
 /**
  * Output-buffer allocation for the FFI wrappers. The native write fills
  * `[0, w)` and only `subarray(0, w)` escapes, so zero-initialization is pure

package/src/native/ffi/build.ts

@@ -16,6 +16,7 @@ import { buildCompress } from './build/compress'
 import { buildInstances } from './build/instances'
 import { buildMetrics } from './build/metrics'
 import { buildParse } from './build/parse'
+import { buildTask } from './build/task'
 import type { BuildCtx } from './build/util'
 import type { BunFFI } from './types'
 
@@ -92,5 +93,6 @@ export function build(
     ...buildParse(sym, ctx),
     ...buildInstances(sym, ctx),
     ...buildMetrics(sym, ctx),
+    ...buildTask(sym, ctx),
   } as BunFFI
 }

package/src/native/ffi/selftest.ts

@@ -15,6 +15,7 @@ import { selfTestCompress } from './build/compress'
 import { selfTestInstances } from './build/instances'
 import { selfTestMetrics } from './build/metrics'
 import { selfTestParse } from './build/parse'
+import { selfTestTask } from './build/task'
 import type { BunFFI } from './types'
 
 /** Verify every bound function against known-good results; false disables ffi. */
@@ -24,6 +25,7 @@ export function selfTest(b: BunFFI): boolean {
     selfTestCompress(b) &&
     selfTestParse(b) &&
     selfTestInstances(b) &&
-    selfTestMetrics(b)
+    selfTestMetrics(b) &&
+    selfTestTask(b)
   )
 }

package/src/native/ffi/types.ts

@@ -218,6 +218,12 @@ export interface BunFFI {
   gzipDecompress(data: Uint8Array, maxDecompressed?: number): Uint8Array
   /** gzip-decompress into `output`; returns bytes written (throws if too small). */
   gzipDecompressInto(data: Uint8Array, output: Uint8Array, maxDecompressed?: number): number
+  /**
+   * gzip ISIZE trailer probe → the uncompressed size for a single-member gzip
+   * stream, or `0` when unknown (invalid stream / multi-member). Used to
+   * PRE-SIZE a destination buffer for the zero-copy task path.
+   */
+  gzipIsize(data: Uint8Array): number
   /** brotli-compress into a fresh buffer (quality clamped 0..=11, default 5). */
   brotliCompress(data: Uint8Array, quality?: number): Uint8Array
   /** brotli-compress into `output`; returns bytes written (throws if too small). */
@@ -465,6 +471,23 @@ export interface BunFFI {
    * exact required size).
    */
   sessionOpen(token: string, secret: string, output: Uint8Array): number
+  /**
+   * Byte-arg `{@link sessionSeal}`: same envelope + wire format, inputs as
+   * bytes. Preferred for user-derived `id`/`dataJson`, because a `cstring` ARG
+   * is engine-transcoded (a per-arg cost) and SILENTLY TRUNCATES at an
+   * embedded `U+0000` before Rust sees it. `null` = failure.
+   */
+  sessionSealBytes(
+    id: Uint8Array,
+    dataJson: Uint8Array,
+    expSecs: number,
+    secret: Uint8Array,
+  ): string | null
+  /**
+   * Byte-arg `{@link sessionOpen}`: same output layout and needed-size
+   * convention, `token`/`secret` as bytes (exact length, no transcode).
+   */
+  sessionOpenBytes(token: Uint8Array, secret: Uint8Array, output: Uint8Array): number
 
   // ── Batch fixed-width hex validation / RegExp escaping ─────────────
   /**
@@ -488,6 +511,40 @@ export interface BunFFI {
    * cstring return out (engine-cloned — zero JS decode). `null` = failure.
    */
   regexEscapeStr(input: string): string | null
+
+  // ── Off-thread task runtime (castrum_task_*) ──────────────────────
+  /** Start the shared native task pool; 0 = started, 1 = already running. */
+  taskInit(threads: number): number
+  /** Submit a task op with packed `args` under `taskId`; 1 = accepted. */
+  taskSubmit(op: number, args: Uint8Array, taskId: number): number
+  /**
+   * Zero-copy submit: the op writes its result DIRECTLY into `output` on the
+   * pool thread. `output` must be a stable, caller-owned buffer that stays
+   * alive (and untouched) until the completion is drained — the runtime holds
+   * the reference. The completion body is the 8-byte LE written length.
+   */
+  taskSubmitOut(op: number, args: Uint8Array, taskId: number, output: Uint8Array): number
+  /**
+   * Zero-copy INPUT: only `hdr` is copied; `data` is read in place by the pool
+   * thread, so the caller must keep it alive (and untouched) until completion.
+   */
+  taskSubmitSlice(op: number, hdr: Uint8Array, data: Uint8Array, taskId: number): number
+  /**
+   * Drain finished tasks into `output` (packed `[u32 count][entry…]`).
+   * Returns bytes written, `0` when nothing is pending, or the EXACT required
+   * size when `output` is too small (nothing is consumed in that case).
+   */
+  taskDrain(output: Uint8Array): number
+  /** Finished-but-undrained completion count. */
+  taskPending(): number
+  /** Mark a task cancelled; 1 = newly marked, 0 = unknown/already finished. */
+  taskCancel(taskId: number): number
+  /** Register the thread-safe doorbell trampoline address (`0` disables it). */
+  taskSetDoorbell(ptr: number): number
+  /** Stop the task pool and drop pending completions. */
+  taskShutdown(): number
+  /** Configured task-pool worker count (0 before the pool starts). */
+  taskThreads(): number
 }
 
 /**

package/src/native/ffi.ts

@@ -34,7 +34,7 @@ import type { BunFFI, FfiMode } from './ffi/types'
 // Static import: loader.ts has no side effects (path resolution only — no
 // dlopen), so this adds zero import-time cost while letting `bind()` reuse the
 // exact same resolved `.node` path the napi fallback uses (the shared seam).
-import { getAddonPath } from './loader'
+import { getAddonPath, getAddonPathCandidates } from './loader'
 
 // Re-export the type surface so `import type { BunFFI } from '../native/ffi'`
 // keeps working (existing call sites).
@@ -49,6 +49,12 @@ let cached: BunFFI | null | undefined
  */
 let bufferAbiMode: 'buffer-pair' | 'ptr-len' | null = null
 
+/**
+ * The addon file the live `bun:ffi` binding was opened from, or `null` while
+ * unbound. Diagnostics only — a v3→baseline fallback is visible here.
+ */
+let boundAddonPath: string | null = null
+
 // ── Transport selection (CASTRUM_FFI_MODE) ───────────────────────
 
 function resolveFfiMode(): FfiMode {
@@ -96,6 +102,20 @@ export function ffiBufferMode(): 'buffer-pair' | 'ptr-len' | null {
   return bufferAbiMode
 }
 
+/**
+ * The addon file path the live `bun:ffi` binding was opened from, or `null`
+ * when the transport is unavailable (Node, `CASTRUM_FFI_MODE=napi`, or every
+ * candidate failed). Lazy — triggers the same one-time bind as
+ * {@link getBunFFI}. Use it to confirm WHICH artifact bound, e.g. when a stale
+ * v3 SIMD binary forced the baseline fallback.
+ */
+export function ffiAddonPath(): string | null {
+  if (cached === undefined) {
+    getBunFFI()
+  }
+  return boundAddonPath
+}
+
 /**
  * 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),
@@ -127,7 +147,7 @@ function probeBufferLength(dlopen: typeof import('bun:ffi')['dlopen'], path: str
   }
 }
 
-function bind(): BunFFI | null {
+function bind(forcedPath?: string, tried: string[] = []): BunFFI | null {
   bufferAbiMode = null // reset — the mode below is only valid for a live bind
   const mode = resolveFfiMode()
   if (!isBun()) {
@@ -143,12 +163,13 @@ function bind(): BunFFI | null {
   if (mode === 'napi') {
     return null
   }
+  // Resolve the SAME addon file napi uses (./loader.ts — statically imported
+  // above; it only resolves the path, it never dlopens the addon). On a retry,
+  // `forcedPath` is the next candidate from `getAddonPathCandidates()`.
+  const path = forcedPath ?? getAddonPath()
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { dlopen } = require('bun:ffi') as typeof import('bun:ffi')
-    // Resolve the SAME addon file napi uses (./loader.ts — statically imported
-    // above; it only resolves the path, it never dlopens the addon).
-    const path = getAddonPath()
 
     // Probe `buffer`/`buffer_length` (the engine reads ptr + len off the SAME
     // TypedArray at call time — an atomic snapshot) once; when supported we use
@@ -209,6 +230,14 @@ function bind(): BunFFI | null {
       // The `_bytes` siblings take a `(ptr,len)` pair — zero transcode when
       // the caller already holds bytes (a cstring arg would force a decode +
       // engine re-encode; docs/FFI_BUN_GUIDE.md §3 shape 4).
+      //
+      // SAFETY RULE for every `cstring` ARG added here: the transcode is
+      // NUL-TERMINATED, so an embedded U+0000 truncates the value in-engine. A
+      // verdict op bound this way can be fooled (`validateEmail` on
+      // 'a@b.com\0<script>' returned TRUE before the byte re-route). Either
+      // give the op a `_bytes` sibling and route byte callers to it, or guard
+      // the string form with `hasNul` — see docs/FFI_BUN_GUIDE.md §6.1,
+      // pinned by test/unit/native/cstring-nul.test.ts.
       castrum_validate_email: { args: ['cstring'], returns: 'u8' },
       castrum_validate_uuid: { args: ['cstring'], returns: 'u8' },
       castrum_validate_ipv4: { args: ['cstring'], returns: 'u8' },
@@ -547,6 +576,39 @@ function bind(): BunFFI | null {
         args: abi(['cstring', 'cstring', 'ptr', 'usize']),
         returns: U64_FAST,
       },
+      // Byte-arg siblings of the pair above: identical core and wire format,
+      // but every INPUT crosses as `(ptr,len)`. A `cstring` ARG costs the
+      // engine a transcode per arg AND silently truncates at an embedded
+      // U+0000 — reachable here because `id`/`data_json` are user-derived.
+      castrum_session_seal_bytes: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64', 'ptr', 'usize']),
+        returns: 'cstring',
+      },
+      castrum_session_open_bytes: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      // Off-thread task runtime: `submit` takes a packed `(ptr,len)` arg blob
+      // plus a JS-assigned id; `drain` writes the packed completion batch into
+      // a caller buffer (needed-size convention). `set_doorbell` takes the raw
+      // `JSCallback({threadsafe:true}).ptr` as a bare pointer (`abi` leaves a
+      // lone `ptr` untouched), so the pool can wake JS once per batch.
+      castrum_task_init: { args: ['u32'], returns: 'u32' },
+      castrum_task_submit: { args: abi(['u32', 'ptr', 'usize', 'usize']), returns: 'u32' },
+      castrum_task_submit_slice: {
+        args: abi(['u32', 'ptr', 'usize', 'ptr', 'usize', 'usize']),
+        returns: 'u32',
+      },
+      castrum_task_submit_out: {
+        args: abi(['u32', 'ptr', 'usize', 'usize', 'ptr', 'usize']),
+        returns: 'u32',
+      },
+      castrum_task_drain: { args: abi(['ptr', 'usize']), returns: U64_FAST },
+      castrum_task_pending: { args: [], returns: 'u32' },
+      castrum_task_cancel: { args: ['usize'], returns: 'u32' },
+      castrum_task_set_doorbell: { args: ['ptr'], returns: 'u32' },
+      castrum_task_shutdown: { args: [], returns: 'u32' },
+      castrum_task_threads: { args: [], returns: 'u32' },
       castrum_metrics_destroy: { args: ['usize'], returns: 'void' },
     })
 
@@ -557,20 +619,29 @@ function bind(): BunFFI | null {
       useBufferLength,
     )
     if (!selfTest(bindings)) {
-      if (mode === 'ffi') {
-        throw new Error(
-          'CASTRUM_FFI_MODE=ffi: the bun:ffi bind-time self-test failed, so the ' +
-            'primary transport cannot be trusted on this Bun/addon combination. ' +
-            'Unset CASTRUM_FFI_MODE (or use CASTRUM_FFI_MODE=auto) to fall back to napi.',
-        )
-      }
-      return null
+      throw new Error(`bun:ffi bind-time self-test failed on ${path}`)
     }
+    boundAddonPath = path
     return bindings
   } catch (err) {
+    bufferAbiMode = null
+    // The preferred artifact failed to dlopen/bind/self-test. The common cause
+    // is a STALE v3 SIMD binary (`castrum.linux-x64-v3-gnu.node`) that predates
+    // a newly added `castrum_*` symbol: dlopen fails, and without this walk the
+    // whole FFI transport would be disabled (every call silently downgraded to
+    // napi, and the task runtime silently made synchronous). Try the remaining
+    // existing candidates — the baseline binary — before giving up.
+    for (const next of getAddonPathCandidates()) {
+      if (next === path || tried.includes(next)) continue
+      const bound = bind(next, [...tried, path])
+      if (bound) return bound
+    }
     if (mode === 'ffi') {
       const cause = err instanceof Error ? `: ${err.message}` : ''
-      throw new Error(`CASTRUM_FFI_MODE=ffi: failed to bind bun:ffi${cause}`)
+      throw new Error(
+        `CASTRUM_FFI_MODE=ffi: failed to bind bun:ffi${cause} ` +
+          `(tried: ${[...tried, path].join(', ')})`,
+      )
     }
     return null
   }

package/src/native/loader.ts

@@ -67,15 +67,16 @@ export function supportsX8664V3(cpuinfo?: string): boolean {
  * @param arch `process.arch`
  * @param cpuinfo optional `/proc/cpuinfo` text (tests inject it; the real call
  *   omits it and reads the file lazily on linux/x64 only)
- * @returns the first existing candidate path (throws if none exists)
+ * @returns every candidate path, in preference order (v3 SIMD first on a
+ *   capable linux/x64 host, then the baseline names)
  */
-export function resolveAddonPathFrom(
+export function addonCandidatesFrom(
   envOverride: string | undefined,
   baseDir: string,
   platform: string,
   arch: string,
   cpuinfo?: string,
-): string {
+): string[] {
   // napi-rs artifact naming: castrum.<platform>-<arch>[-<libc>].node
   // e.g. linux-x64-gnu, linux-x64-musl, win32-x64-msvc, darwin-arm64.
   const libcVariants =
@@ -156,6 +157,22 @@ export function resolveAddonPathFrom(
     candidates.push(join(baseDir, '..', '..', 'target', 'release', name))
   }
 
+  return candidates
+}
+
+/**
+ * Resolve the addon path: the FIRST existing candidate from
+ * {@link addonCandidatesFrom} (v3 SIMD first on a capable linux/x64 host).
+ * Throws when nothing exists.
+ */
+export function resolveAddonPathFrom(
+  envOverride: string | undefined,
+  baseDir: string,
+  platform: string,
+  arch: string,
+  cpuinfo?: string,
+): string {
+  const candidates = addonCandidatesFrom(envOverride, baseDir, platform, arch, cpuinfo)
   for (const candidate of candidates) {
     if (existsSync(candidate)) {
       return candidate
@@ -169,6 +186,39 @@ export function resolveAddonPathFrom(
   )
 }
 
+/** Cached result of {@link getAddonPathCandidates} (existing files only). */
+let cachedCandidates: string[] | undefined
+
+/**
+ * Every EXISTING addon candidate, in preference order (v3 SIMD first on a
+ * capable linux/x64 host, then the baseline names).
+ *
+ * The bun:ffi binder walks this list so a stale or partial *preferred* artifact
+ * — e.g. a `castrum.linux-x64-v3-gnu.node` built before a newly added
+ * `castrum_*` symbol — falls back to the baseline binary instead of silently
+ * disabling the whole FFI transport (which would downgrade every native call to
+ * napi and make the off-thread task runtime run synchronously).
+ */
+export function getAddonPathCandidates(): string[] {
+  if (cachedCandidates) return cachedCandidates
+  const all = addonCandidatesFrom(
+    resolveEnvVar('CASTRUM_NATIVE_LIBRARY_PATH', ['NAPI_RS_NATIVE_LIBRARY_PATH']),
+    dirname(fileURLToPath(import.meta.url)),
+    process.platform,
+    process.arch,
+  )
+  const seen = new Set<string>()
+  const existing: string[] = []
+  for (const candidate of all) {
+    if (!seen.has(candidate) && existsSync(candidate)) {
+      seen.add(candidate)
+      existing.push(candidate)
+    }
+  }
+  cachedCandidates = existing
+  return existing
+}
+
 function resolveAddonPath(): string {
   return resolveAddonPathFrom(
     resolveEnvVar('CASTRUM_NATIVE_LIBRARY_PATH', ['NAPI_RS_NATIVE_LIBRARY_PATH']),

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

@@ -11,12 +11,19 @@
 
 import type { EncodingPrefResult, MediaTypeResult } from '../../native'
 import type { BunFFI } from '../../native/ffi'
-import { decoder } from '../../shared/bytes'
+import { decoder, hasNul } from '../../shared/bytes'
 import { decodeUtf8Fatal, decodeUtf8Range } from '../../shared/codec'
 import { packPairs } from '../../shared/packed'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 import { writeInto } from '../into'
 
+/**
+ * RFC 6455 `Sec-WebSocket-Accept` is always 28 chars. Reused across calls
+ * because the value is decoded to a string synchronously before returning —
+ * the same discipline as the other pooled scratches in this layer.
+ */
+const WS_ACCEPT_SCRATCH = new Uint8Array(64)
+
 // Mirror napi `url_decode`'s UTF-8 validation (rust/http/url_codec.rs): only
 // validate when a high byte is present (the ASCII fast path skips it — same as
 // Rust's saw_high check). On the Bun path the check is a native C-ABI probe
@@ -144,11 +151,22 @@ export function buildHttp(ctx: RustClientContext) {
 
   return {
     mimeFromExtension(ext: Uint8Array): Uint8Array | string {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call. napi keeps the memoized-bytes
-      // path (cachedMime).
+      // FFI-first. This op has no `*_bytes` sibling, so the bytes must be decoded
+      // for the `cstring` ARG — the decode is the price of the cstring form, not
+      // a speed trick (route new byte-shaped ops to a byte sibling instead; see
+      // docs/FFI_BUN_GUIDE.md §6.1). napi keeps the memoized-bytes path
+      // (cachedMime).
+      //
+      // A NUL would truncate the DECODED string native-side, so `.js\0evil`
+      // would resolve as `.js` — a Content-Type from a prefix. An extension
+      // containing a NUL is not an extension, so it takes the unknown sentinel
+      // (the guard is `indexOf` on an already-decoded string: ~4 ns).
       const f = ffi()
-      if (f) return f.mimeFromExtension(decoder.decode(ext)) ?? 'application/octet-stream'
+      if (f) {
+        const name = decoder.decode(ext)
+        if (hasNul(name)) return 'application/octet-stream'
+        return f.mimeFromExtension(name) ?? 'application/octet-stream'
+      }
       return ctx.cachedMime(ext)
     },
     urlEncode(input: Uint8Array): Uint8Array | string {
@@ -188,34 +206,54 @@ export function buildHttp(ctx: RustClientContext) {
       return n('urlDecodeInto')(input, output) as number
     },
     validateEmail(input: Uint8Array): boolean {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call — still faster than the old
-      // `(ptr,len)` view path (see bench:margin cstring scenario). napi
-      // fallback keeps the byte path.
+      // FFI-first. The bytes cross as a `buffer`/`buffer_length` pair (an atomic
+      // ptr+len snapshot, zero transcode) rather than being decoded to a JS
+      // string for the `cstring` ARG. Measured on Bun 1.4.2 over 400k calls:
+      // 101 ns vs 234 ns (email), 65 vs 164 (uuid), 31 vs 138 (ipv4) — and the
+      // byte form cannot truncate at an embedded NUL the way a cstring ARG
+      // does (a NUL byte used to make "a@b.com\0<script>" validate as TRUE).
       const f = ffi()
-      if (f) return f.validateEmail(decoder.decode(input))
+      if (f) return f.validateEmailBytes(input)
       return n('validateEmail')(input) as boolean
     },
     validateUuid(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateUuid(decoder.decode(input))
+      if (f) return f.validateUuidBytes(input)
       return n('validateUuid')(input) as boolean
     },
     validateIpv4(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateIpv4(decoder.decode(input))
+      if (f) return f.validateIpv4Bytes(input)
       return n('validateIpv4')(input) as boolean
     },
     validateIpv6(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateIpv6(decoder.decode(input))
+      if (f) return f.validateIpv6Bytes(input)
       return n('validateIpv6')(input) as boolean
     },
     wsAcceptKey(key: Uint8Array): Uint8Array | string {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call. napi fallback keeps the bytes.
+      // FFI-first: the `cstring` ARG + cstring return is the fast path (no JS
+      // encode, engine-cloned result) — end-to-end it measures ~367 ns, while
+      // routing every call through the byte sibling costs ~381 ns (the extra
+      // `subarray` + decode outweighs the transcode saved; measured over 300k
+      // calls on Bun 1.4.2 through THIS function, not the raw binding).
+      //
+      // Correctness rider: a NUL would truncate the `cstring` ARG, so the accept
+      // value would be computed for a PREFIX of the key — verified:
+      // `'dGhlIHNhbXBsZSBub25jZQ==\0junk'` returned exactly the value for the
+      // key WITHOUT the suffix. That case takes the byte sibling (exact length).
       const f = ffi()
-      if (f) return f.wsAcceptKey(decoder.decode(key))
+      if (f) {
+        const text = decoder.decode(key)
+        if (!hasNul(text)) return f.wsAcceptKey(text)
+        const w = f.wsAcceptKeyInto(key, WS_ACCEPT_SCRATCH)
+        if (w > 0 && w <= WS_ACCEPT_SCRATCH.length) {
+          return decoder.decode(WS_ACCEPT_SCRATCH.subarray(0, w))
+        }
+        // Unreachable for a live view (the native side writes 28 for any key);
+        // the napi path is byte-exact, so it can never resurrect truncation.
+        return n('wsAcceptKey')(key) as Uint8Array | string
+      }
       return n('wsAcceptKey')(key) as Uint8Array | string
     },
     wsAcceptKeyInto(key: Uint8Array, output: Uint8Array): number {

package/src/rust-ffi/text.ts

@@ -1,16 +1,27 @@
 // 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.
+// functions. MOST of it is FFI-first with `cstring` args/returns: the engine
+// transcodes a JS string in-call, so there is no JS-side encode at all (and
+// byte-arg ops are not involved). Encode/decode wrappers exist only for the
+// napi fallback and for ops with no cstring form — plus a NUL guard wherever a
+// `cstring` ARG could truncate a verdict or a byte-exact value
+// (docs/FFI_BUN_GUIDE.md §6.1).
 //
 // 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 { decoder, encoder, hasNul } from '../shared/bytes'
 import { type RustClientContext, resolveNative } from './context'
 
+/**
+ * Scratch for the byte-path `Sec-WebSocket-Accept` fallback (28 chars; the
+ * NUL case only). Decoded synchronously before returning, so reuse is safe.
+ */
+const WS_ACCEPT_OUT = new Uint8Array(64)
+
 /** String-oriented FFI namespace. */
 export interface RustText {
   /**
@@ -91,8 +102,19 @@ export function buildText(ctx: RustClientContext): RustText {
       // 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.
+      //
+      // Exception: a NUL would truncate the `cstring` ARG, so the accept value
+      // would be computed for a PREFIX of the key. Encode and take the byte path
+      // in that (practically unreachable) case: still a wrong key for a client
+      // that sent a NUL, but wrong for the bytes the caller actually passed.
       const f = transport.ffi
-      if (f) return f.wsAcceptKey(key)
+      if (f) {
+        if (!hasNul(key)) return f.wsAcceptKey(key)
+        const w = f.wsAcceptKeyInto(encoder.encode(key), WS_ACCEPT_OUT)
+        return w > 0 && w <= WS_ACCEPT_OUT.length
+          ? decoder.decode(WS_ACCEPT_OUT.subarray(0, w))
+          : ''
+      }
       return decoder.decode(resolveNative(ctx, 'wsAcceptKey')(encoder.encode(key)) as Uint8Array)
     },
     validateEmail(input) {

package/src/shared/bytes.ts

@@ -134,3 +134,22 @@ export function toPlainBuffer(bytes: Uint8Array): Uint8Array {
   copy.set(bytes)
   return copy
 }
+
+/**
+ * Does this string contain a NUL (`U+0000`)?
+ *
+ * `bun:ffi` transcodes a JS string passed to a `cstring` ARG into a
+ * NUL-TERMINATED UTF-8 buffer, so an embedded NUL SILENTLY TRUNCATES the value
+ * natively (Bun's docs describe the transcode; the truncation is the C
+ * convention it inherits). That is fine for developer-supplied config, and a
+ * real bug wherever the callee answers with a VERDICT (a truncated prefix
+ * passes where the full input fails) or where the exact bytes ARE the result.
+ *
+ * Cheap: one `indexOf` scan, ~4 ns for typical inputs.
+ *
+ * @param s - The string to check.
+ * @returns `true` when a NUL is present.
+ */
+export function hasNul(s: string): boolean {
+  return s.indexOf('\u0000') !== -1
+}