castrum 0.9.4 → 0.9.6

package/rust/util/bytes.rs

@@ -145,33 +145,55 @@ pub fn decode_percent_at(src: &[u8], i: usize) -> Option<(u8, usize)> {
 
 // ── Form-component decoding ────────────────────────────────────────
 
-/// Decode failure modes for [`decode_form_component_into`].
+/// Decode failure modes for the form-component decoders.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FormDecodeError {
-    /// Malformed `%XX` sequence (truncated or a non-hex digit).
+    /// Malformed `%XX` (truncated / non-hex digit) or a decoded byte sequence
+    /// that is not valid UTF-8 — exactly what JS's `decodeURIComponent` throws
+    /// `URIError` on. Reported by [`decode_form_component_strict_into`]; the
+    /// lenient [`decode_form_component_into`] answers with the RAW component
+    /// instead (JS's `catch` arm).
     Malformed,
     /// `out` cannot hold the decoded result.
     BufferTooSmall,
 }
 
-/// URL-decode a form component (`+` → space, `%XX` → byte) into `out`,
-/// returning the number of bytes written.
+/// SIMD-accelerated UTF-8 validation (the crate `http::url_codec` already uses,
+/// so the whole HTTP surface validates with the same implementation).
+#[inline]
+fn is_valid_utf8(bytes: &[u8]) -> bool {
+    simdutf8::basic::from_utf8(bytes).is_ok()
+}
+
+/// THE form-component decoder: `+` → space, `%XX` → byte, bulk-copying plain
+/// runs between them, and validating the result's UTF-8 shape.
+///
+/// This is the single place URL-form decoding happens. Its callers differ only
+/// in their FAILURE ARM:
 ///
-/// The decoded length never exceeds `src.len()` (each input byte maps to at
-/// most one output byte). Callers that pre-size `out` to `src.len()` can never
-/// observe [`FormDecodeError::BufferTooSmall`]; callers that pass the remaining
-/// tail of a larger buffer get a precise capacity check against the ACTUAL
-/// decoded length (a `%XX` sequence shrinks 3 input bytes to 1, so a buffer
-/// sized to the decoded form succeeds).
+/// * [`decode_form_component_into`] — lenient, JS `decodeURIComponent`
+///   semantics: `try { decodeURIComponent(s.replace(/\+/g, " ")) } catch { return s }`.
+///   Used by the packed pair parsers (query/form) and the native route stack,
+///   which must answer exactly like the pure-TS fallback.
+/// * [`decode_form_component_strict_into`] — `Malformed` is a real error, for
+///   callers that map a bad component to a 400 (query → JSON).
 ///
-/// Single shared implementation for `query_parser::write_decoded_form_component`
-/// (length-prefixed slice writer) and `json_ser::decode_query_component`
-/// (Vec appender) — the wire decode loop lives in exactly one place.
+/// Keeping one core means the two can never drift apart again — which is how
+/// the packed parser ended up erroring on input the JS fallback happily
+/// returned raw.
+///
+/// `Malformed` is exactly the set JS rejects: a truncated/non-hex `%XX`, and a
+/// decoded sequence that is not valid UTF-8 (overlong encodings, surrogate
+/// halves and > U+10FFFF fail `simdutf8` and `decodeURIComponent` alike).
+///
+/// The decoded length never exceeds `src.len()`, so a caller that sizes `out`
+/// to the input can only observe [`FormDecodeError::BufferTooSmall`] when it
+/// passed a smaller tail of a larger buffer.
 #[inline]
-pub fn decode_form_component_into(
-    src: &[u8],
-    out: &mut [u8],
-) -> std::result::Result<usize, FormDecodeError> {
+fn decode_form_core(src: &[u8], out: &mut [u8]) -> std::result::Result<usize, FormDecodeError> {
+    // Nothing to decode at all (the overwhelming majority of components): a
+    // verbatim copy. No UTF-8 check — an undecoded component is passed through
+    // byte-for-byte, exactly like the JS fallback's `indexOf` early return.
     if memchr::memchr2(b'+', b'%', src).is_none() {
         if out.len() < src.len() {
             return Err(FormDecodeError::BufferTooSmall);
@@ -187,6 +209,9 @@ pub fn decode_form_component_into(
     // input bytes to 1), preserving the existing semantics.
     let mut i = 0usize;
     let mut written = 0usize;
+    // ASCII output is trivially valid UTF-8, so the validator is only paid when
+    // a high byte actually reaches the result (same discipline as `url_codec`).
+    let mut saw_high = false;
     while i < src.len() {
         match memchr::memchr2(b'+', b'%', &src[i..]) {
             Some(rel) => {
@@ -196,6 +221,7 @@ pub fn decode_form_component_into(
                     return Err(FormDecodeError::BufferTooSmall);
                 }
                 out[written..written + run.len()].copy_from_slice(run);
+                saw_high |= !run.is_ascii();
                 written += run.len();
                 i = run_end;
 
@@ -212,6 +238,7 @@ pub fn decode_form_component_into(
                     return Err(FormDecodeError::BufferTooSmall);
                 }
                 out[written] = b;
+                saw_high |= b >= 0x80;
                 written += 1;
                 i = next;
             }
@@ -221,51 +248,136 @@ pub fn decode_form_component_into(
                     return Err(FormDecodeError::BufferTooSmall);
                 }
                 out[written..written + run.len()].copy_from_slice(run);
+                saw_high |= !run.is_ascii();
                 written += run.len();
                 i = src.len();
             }
         }
     }
+    if saw_high && !is_valid_utf8(&out[..written]) {
+        return Err(FormDecodeError::Malformed);
+    }
     Ok(written)
 }
 
-/// Compute the decoded length of `src` WITHOUT writing (mirror of
-/// [`decode_form_component_into`], minus the output). Used by the C-ABI
-/// "needed-size" convention: when a packed/JSON writer hits a too-small output
-/// buffer, the caller runs this exact-size pass ONCE (only on the rare miss)
-/// and reports the required size so the JS wrapper can `growExact` and retry —
-/// no doubling re-run loop, no 9×/8× pre-size.
+/// Copy `src` verbatim into `out` — the raw fallback of the lenient contract.
+#[inline]
+fn write_raw_component(src: &[u8], out: &mut [u8]) -> std::result::Result<usize, FormDecodeError> {
+    if out.len() < src.len() {
+        return Err(FormDecodeError::BufferTooSmall);
+    }
+    out[..src.len()].copy_from_slice(src);
+    Ok(src.len())
+}
+
+/// URL-decode a form component (`+` → space, `%XX` → byte) into `out` with
+/// **JS `decodeURIComponent` fallback semantics**, returning bytes written.
 ///
-/// Same `Malformed` signal on a bad `%XX`, so a caller can disambiguate a
-/// too-small buffer from a real parse error.
+/// Per COMPONENT (name and value decode independently):
+///
+/// 1. no `%` and no `+` → copied verbatim;
+/// 2. otherwise `+` → space and `%XX` → byte;
+/// 3. a malformed escape (truncated or non-hex) → the WHOLE component is
+///    returned RAW — note `+` stays `+`, because JS's `catch` returns the
+///    string it was given, before the `+` replacement;
+/// 4. a decoded sequence that is not valid UTF-8 → the whole component RAW.
+///
+/// That is `try { decodeURIComponent(s.replace(/\+/g, " ")) } catch { return s }`
+/// — the pure-TS fallback swallows the `URIError` and the native path must too,
+/// or a single bad escape turns a public request into a 500 (and a divergent
+/// parse) instead of a raw field.
 #[inline]
-pub fn decode_form_component_len(src: &[u8]) -> std::result::Result<usize, FormDecodeError> {
+pub fn decode_form_component_into(
+    src: &[u8],
+    out: &mut [u8],
+) -> std::result::Result<usize, FormDecodeError> {
+    match decode_form_core(src, out) {
+        Ok(written) => Ok(written),
+        Err(FormDecodeError::Malformed) => write_raw_component(src, out),
+        Err(e) => Err(e),
+    }
+}
+
+/// Compute the decoded length of `src` WITHOUT writing — the exact-size pass for
+/// the C-ABI "needed size" convention (run ONCE on a buffer miss, so the caller
+/// can `growExact` and retry instead of a doubling loop).
+///
+/// Reports [`FormDecodeError::Malformed`] exactly when the writer would (the
+/// raw fallback reports `src.len()`), so the reported size and the written size
+/// can never disagree — a mismatch would make the caller's grow-and-retry loop
+/// spin forever.
+///
+/// One conservative case is deliberate: when the decoded output contains a
+/// non-ASCII byte, the result MAY be invalid UTF-8 and the writer would then
+/// emit the raw component (longer than the decoded form), so `src.len()` is
+/// reported. Over-reporting only costs the caller a few buffer bytes (the C fn
+/// still returns the true written length); under-reporting would hang.
+#[inline]
+pub fn decode_form_component_len(src: &[u8]) -> usize {
     if memchr::memchr2(b'+', b'%', src).is_none() {
-        return Ok(src.len());
+        return src.len();
     }
     let mut i = 0usize;
     let mut written = 0usize;
+    let mut saw_high = false;
     while i < src.len() {
         match memchr::memchr2(b'+', b'%', &src[i..]) {
             Some(rel) => {
+                let run_end = i + rel;
                 written += rel;
-                i += rel;
-                let next = match src[i] {
-                    b'+' => i + 1,
-                    _ => decode_percent_at(src, i)
-                        .map(|(_, next)| next)
-                        .ok_or(FormDecodeError::Malformed)?,
-                };
-                written += 1;
-                i = next;
+                saw_high |= !src[i..run_end].is_ascii();
+                i = run_end;
+                match src[i] {
+                    b'+' => {
+                        written += 1;
+                        i += 1;
+                    }
+                    _ => match decode_percent_at(src, i) {
+                        Some((byte, next)) => {
+                            written += 1;
+                            saw_high |= byte >= 0x80;
+                            i = next;
+                        }
+                        // Malformed → the writer emits the raw component, so
+                        // the raw length is the exact answer here.
+                        None => return src.len(),
+                    },
+                }
             }
             None => {
                 written += src.len() - i;
+                saw_high |= !src[i..].is_ascii();
                 i = src.len();
             }
         }
     }
-    Ok(written)
+    if saw_high {
+        src.len()
+    } else {
+        written
+    }
+}
+
+/// Decode a form component into a reusable scratch buffer, returning the
+/// decoded bytes — or `src` itself when nothing needed decoding. The shared
+/// entry point for Vec-based callers (the native route stack); the returned
+/// slice borrows either `src` or `scratch`, so it is valid only until the next
+/// call with the same scratch.
+#[inline]
+pub fn decode_form_component_scratch<'a>(src: &'a [u8], scratch: &'a mut Vec<u8>) -> &'a [u8] {
+    // Fast path: nothing to decode (the overwhelming majority of segments).
+    if memchr::memchr2(b'+', b'%', src).is_none() {
+        return src;
+    }
+    if scratch.len() < src.len() {
+        scratch.resize(src.len(), 0);
+    }
+    match decode_form_component_into(src, scratch.as_mut_slice()) {
+        Ok(n) => &scratch[..n],
+        // Unreachable: the buffer is input-sized, and the decoded length never
+        // exceeds the input.
+        Err(_) => src,
+    }
 }
 
 // ── Whitespace + cookie splitting ──────────────────────────────────
@@ -350,23 +462,98 @@ mod tests {
         assert_eq!(decode(b"%41%42"), b"AB");
         assert_eq!(decode(b"q=%E2%9C%93"), b"q=\xE2\x9C\x93");
         assert_eq!(decode(b"%2B"), b"+");
+        // A NUL is a legal decode target (U+0000), not an error.
+        assert_eq!(decode(b"%00"), b"\x00");
+        assert_eq!(decode(b"%2f"), b"/");
     }
 
     #[test]
-    fn decode_form_malformed_percent() {
-        let mut out = [0u8; 8];
-        assert_eq!(
-            decode_form_component_into(b"%ZZ", &mut out),
-            Err(FormDecodeError::Malformed)
-        );
-        assert_eq!(
-            decode_form_component_into(b"%4", &mut out),
-            Err(FormDecodeError::Malformed)
-        );
-        assert_eq!(
-            decode_form_component_into(b"x%", &mut out),
-            Err(FormDecodeError::Malformed)
-        );
+    fn decode_form_decodeuri_semantics_table() {
+        // The contract is `try { decodeURIComponent(s.replace(/\+/g," ")) }
+        // catch { return s }` — verified against Bun's `decodeURIComponent`.
+        let cases: &[(&[u8], &[u8])] = &[
+            // (input, JS result)
+            (b"a=%C3", b"a=%C3"), // truncated multibyte → URIError → raw
+            (b"a=%2", b"a=%2"),   // truncated escape → raw
+            (b"a=%", b"a=%"),     // dangling % → raw
+            (b"a=%2G", b"a=%2G"), // non-hex digit → raw
+            (b"a=%FF", b"a=%FF"), // invalid UTF-8 byte → raw
+            (b"a=%ED%A0%80", b"a=%ED%A0%80"), // surrogate half → raw
+            (b"a=%C0%80", b"a=%C0%80"), // overlong encoding → raw
+            (b"a=%F4%90%80%80", b"a=%F4%90%80%80"), // > U+10FFFF → raw
+            (b"bad=%ZZ", b"bad=%ZZ"), // non-hex → raw
+            (b"100%", b"100%"),   // trailing % → raw
+            // The whole component goes raw — including a '+' that the decode
+            // would otherwise have turned into a space (the JS catch returns
+            // the string it was given, before the replace).
+            (b"a+b=%ZZ", b"a+b=%ZZ"),
+            (b"a+b=%20", b"a b= "),   // valid → decoded
+            (b"%C3%A9", b"\xC3\xA9"), // valid multibyte → decoded
+        ];
+        for (input, expected) in cases {
+            assert_eq!(
+                decode(input).as_slice(),
+                *expected,
+                "lenient decode of {:?}",
+                core::str::from_utf8(input).unwrap_or("<non-utf8>")
+            );
+        }
+    }
+
+    #[test]
+    fn decode_form_needed_size_matches_written_size() {
+        // The C-ABI "needed size" pass must equal what the writer produces for
+        // EVERY input — a mismatch would spin the caller's grow-and-retry loop.
+        // It may only over-report (never under-report) when the decoded form
+        // could be invalid UTF-8.
+        let cases: &[&[u8]] = &[
+            b"",
+            b"a",
+            b"a=1&b=2",
+            b"%ZZ",
+            b"a=%C3",
+            b"a=%FF",
+            b"a=%ED%A0%80",
+            b"q=hello+world",
+            b"u=%E2%9C%93",
+            b"\xFF\xFE", // non-UTF-8 passthrough
+            b"a=%E2%9C%93&b%ZZ=1",
+            b"x%",
+        ];
+        for src in cases {
+            let mut out = vec![0u8; src.len() + 16];
+            let written = decode_form_component_into(src, &mut out).unwrap();
+            let reported = decode_form_component_len(src);
+            assert!(
+                reported >= written,
+                "reported {reported} < written {written} for {:?}",
+                core::str::from_utf8(src).unwrap_or("<non-utf8>")
+            );
+            // An exact-size buffer must succeed and agree with the report.
+            let mut exact = vec![0u8; reported];
+            assert_eq!(
+                decode_form_component_into(src, &mut exact).unwrap(),
+                written,
+                "exact-size decode disagreed for {:?}",
+                core::str::from_utf8(src).unwrap_or("<non-utf8>")
+            );
+        }
+    }
+
+    #[test]
+    fn decode_form_scratch_matches_slice_decoder() {
+        let mut scratch: Vec<u8> = Vec::new();
+        for input in [
+            &b"plain"[..],
+            b"a+b",
+            b"a=%20b",
+            b"%ZZ",
+            b"%C3",
+            b"a=%E2%9C%93",
+        ] {
+            let via_scratch = decode_form_component_scratch(input, &mut scratch).to_vec();
+            assert_eq!(via_scratch.as_slice(), decode(input).as_slice());
+        }
     }
 
     #[test]

package/src/ingress/health.ts

@@ -49,10 +49,9 @@ export function readinessHandler(check?: () => boolean | Promise<boolean>) {
       return ok
         ? jsonResponse(200, { status: 'ready' })
         : jsonResponse(503, { status: 'not_ready' })
-    } catch (err) {
+    } catch (_err) {
       return jsonResponse(503, {
         status: 'not_ready',
-        error: err instanceof Error ? err.message : String(err),
       })
     }
   }

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

@@ -9,7 +9,7 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { SELFTEST_HEX, SELFTEST_JSON } from '../constants'
 import type { BunFFI, Raw3, Raw4, Raw5, Raw6, Raw8, Raw9, Raw10, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { allocOut, argon2PhcLength, cstr, flag, growExact, writeOrThrow } from './util'
+import { allocOut, argon2PhcLength, cstr, flag, growExact, hasNul, writeOrThrow } from './util'
 
 /**
  * Build the codec/crypto/auth methods of the BunFFI surface. `ctx` is
@@ -182,10 +182,14 @@ export function buildCodecs(
     },
     urlEncodeInto,
 
-    validateEmail: (input) => Number(validateEmail(input)) === 1,
-    validateUuid: (input) => Number(validateUuid(input)) === 1,
-    validateIpv4: (input) => Number(validateIpv4(input)) === 1,
-    validateIpv6: (input) => Number(validateIpv6(input)) === 1,
+    // Verdict guards: the `cstring` form would truncate at an embedded NUL, so
+    // `"a@b.com\0<script>"` would be reported VALID — a verdict callers act on.
+    // No address / UUID / IP contains U+0000, so short-circuit without an FFI
+    // call (one `indexOf` scan, far cheaper than the encode fallback).
+    validateEmail: (input) => !hasNul(input) && Number(validateEmail(input)) === 1,
+    validateUuid: (input) => !hasNul(input) && Number(validateUuid(input)) === 1,
+    validateIpv4: (input) => !hasNul(input) && Number(validateIpv4(input)) === 1,
+    validateIpv6: (input) => !hasNul(input) && Number(validateIpv6(input)) === 1,
     // Byte-input validators: `(ptr,len)` — zero transcode (no CString decode
     // + engine re-encode like the cstring-ARG string forms above).
     validateEmailBytes: (input) => Number(oneArg(validateEmailBytes, input)) === 1,
@@ -212,12 +216,30 @@ export function buildCodecs(
       return w
     },
     // Zero-copy text path: cstring ARG in (engine-transcoded), cstring return
-    // out (engine-cloned) — the JS side does zero encode AND zero decode.
-    regexEscapeStr: (input) => regexEscapeStrRaw(input),
+    // out (engine-cloned) — the JS side does zero encode AND zero decode. A NUL
+    // would truncate the INPUT, so that case routes to the `(ptr,len)` sibling
+    // (exact length) instead of returning a silently shortened string.
+    regexEscapeStr: (input) => {
+      if (!hasNul(input)) return regexEscapeStrRaw(input)
+      const bytes = encodeUtf8(input)
+      const escaped = growExact(
+        (out) => Number(regexEscapeRaw(bytes, lenOrView(bytes), out, lenOrView(out))),
+        16,
+        1 << 20,
+        'regex escape: output buffer too small',
+      )
+      return decodeUtf8(escaped)
+    },
     hexValidateBatchStr(ids, width, output) {
       if (width === 0 || width > 4096) {
         throw new Error('hex validate batch: width must be 1..=4096')
       }
+      // A NUL in the joined ids would truncate the line list, so a bad id could
+      // pass as its own prefix. Fall back to the byte form (exact length).
+      if (hasNul(ids)) {
+        const bytes = encodeUtf8(ids)
+        return Number(hexBatchRaw(bytes, lenOrView(bytes), width >>> 0, output, lenOrView(output)))
+      }
       const w = Number(hexBatchStrRaw(ids, width >>> 0, output, lenOrView(output)))
       return w
     },

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

@@ -117,6 +117,14 @@ export function buildCompress(
       }
       return w
     },
+    /**
+     * gzip ISIZE probe → uncompressed size for a single-member stream, or `0`
+     * when unknown. Used to PRE-SIZE a destination buffer for the zero-copy
+     * task path (one pass, no intermediate buffer, no retry in the common case).
+     */
+    gzipIsize(data) {
+      return Number(gzipIsize(data, lenOrView(data)))
+    },
     brotliCompress(data, quality = 5) {
       // Same cap rationale as gzipCompress (streaming core); growExact for
       // incompressible data.

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

@@ -10,7 +10,7 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { EMPTY_VIEW } from '../constants'
 import type { BunFFI, Raw2, Raw3, Raw4, Raw5, Raw6, Raw7, Raw8, Raw12, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { cstr, growExact, unpackRateCheck } from './util'
+import { cstr, growExact, hasNul, unpackRateCheck } from './util'
 
 /**
  * Build the opaque-handle methods of the BunFFI surface. `ctx` is destructured
@@ -144,10 +144,15 @@ export function buildInstances(
       return Number(schemaValidatorValidateRaw(inner, doc, lenOrView(doc))) === 1
     },
     queryValidate(inner, qs) {
-      // `qs` is a cstring ARG — engine-transcoded (zero JS encode).
+      // `qs` is a cstring ARG — engine-transcoded (zero JS encode). A raw NUL is
+      // not a valid query byte, and it would TRUNCATE the arg so only a prefix
+      // got validated: a gate that says "this query passed" must not be foolable.
+      if (hasNul(qs)) return false
       return Number(queryValidateSym(inner, qs)) === 1
     },
     cookieValidate(inner, header) {
+      // Same contract as `queryValidate`: a NUL would validate only a prefix.
+      if (hasNul(header)) return false
       return Number(cookieValidateSym(inner, header)) === 1
     },
     sessionSeal(id, dataJson, expSecs, secret) {

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

@@ -9,6 +9,18 @@
 import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import type { BunFFI, Raw0, Raw3, Raw4, Raw5 } from '../types'
 import type { BuildCtx } from './util'
+import { hasNul } from './util'
+
+/**
+ * Declare-time NUL guard: a metric NAME or label-key set containing `U+0000`
+ * would be truncated by the `cstring` arg, silently colliding two series. This
+ * runs once at declaration, so failing fast costs nothing on the hot path.
+ */
+function throwIfNul(value: string, what: string): void {
+  if (hasNul(value)) {
+    throw new Error(`metrics: ${what} must not contain a NUL character (U+0000)`)
+  }
+}
 
 /**
  * Sentinel returned by the declare fns (`u32::MAX`) on invalid input — fits
@@ -59,12 +71,18 @@ export function buildMetrics(
       return h
     },
     metricsCounter(handle, name, labelKeys) {
+      throwIfNul(name, 'counter name')
+      throwIfNul(labelKeys, 'counter label keys')
       return declareOrThrow(metricsCounterRaw(handle, name, labelKeys), `counter "${name}"`)
     },
     metricsGauge(handle, name, labelKeys) {
+      throwIfNul(name, 'gauge name')
+      throwIfNul(labelKeys, 'gauge label keys')
       return declareOrThrow(metricsGaugeRaw(handle, name, labelKeys), `gauge "${name}"`)
     },
     metricsHistogram(handle, name, labelKeys, bucketsCsv) {
+      throwIfNul(name, 'histogram name')
+      throwIfNul(labelKeys, 'histogram label keys')
       return declareOrThrow(
         metricsHistogramRaw(handle, name, labelKeys, bucketsCsv),
         `histogram "${name}"`,
@@ -79,9 +97,14 @@ export function buildMetrics(
     },
     metricsRecordStr(handle, series, values, amount) {
       // `values` is the JOINED `\x1f` string — engine-transcoded (zero encode).
+      // Label values come from user data, so a NUL would truncate the join and
+      // silently record the WRONG series (the native side rejects a NUL value,
+      // but only if it ever sees it). Fail loudly and say why.
+      throwIfNul(values, 'label values')
       return Number(metricsRecordStrRaw(handle, series, values, amount)) === 1
     },
     metricsGaugeSetStr(handle, series, values, value) {
+      throwIfNul(values, 'label values')
       return Number(metricsGaugeSetStrRaw(handle, series, values, value)) === 1
     },
     metricsRender(handle, output) {

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