castrum 0.9.4 → 0.9.7

package/rust/ingress/native_route.rs

@@ -26,7 +26,6 @@
 // `parseQuery` + a cookie pair section iff `parseCookies`. Pair sections are
 // `[count u32] { [nameLen u32][name][valueLen u32][value] }`.
 
-use std::borrow::Cow;
 use std::sync::Arc;
 
 use super::packed::{read_section, read_u32_at};
@@ -254,28 +253,30 @@ impl NativeRoute {
             }
         }
 
-        // ── Parse + size the pair sections ──────────────────────────
-        let mut query_size = 0usize;
-        let mut cookie_size = 0usize;
-        let mut query_valid = false;
-        let mut cookie_valid = false;
+        // ── Assemble the result in ONE streaming pass ───────────────
+        // Pair sections are decoded + written as they are walked. The old
+        // shape sized them first and walked again, which decoded every escaped
+        // segment TWICE and allocated twice per segment in BOTH passes.
+        // The reused `scratch` holds the decoded bytes of one segment at a time.
+        let mut scratch: Vec<u8> = Vec::new();
+        let mut w = ResultWriter::new(out, RESULT_HEADER_LEN);
+        let mut query_capped = false;
+        let mut cookie_capped = false;
         if self.parse_query {
-            let over = query.len() > self.max_query_bytes;
-            let (size, capped) = query_section_size(query, self.max_pairs);
-            query_size = size;
-            query_valid = !over && !capped;
+            query_capped = write_query_section(&mut w, &mut scratch, query, self.max_pairs);
         }
         if self.parse_cookies {
-            let over = cookie.len() > self.max_cookie_bytes;
-            let (size, capped) = cookie_section_size(cookie, self.max_pairs);
-            cookie_size = size;
-            cookie_valid = !over && !capped;
+            cookie_capped = write_cookie_section(&mut w, cookie, self.max_pairs);
         }
         // validateQuery/validateCookies without a schema are no-ops (the parse
-        // VALID bit above is the verdict); with a schema, compile would have
-        // rejected the descriptor → the caller fell back to JS.
-
-        // ── Assemble the result ─────────────────────────────────────
+        // VALID bit is the verdict); with a schema, compile would have rejected
+        // the descriptor → the caller fell back to JS. A section that is not
+        // parsed never reports VALID.
+        let query_valid = self.parse_query && !query_capped && query.len() <= self.max_query_bytes;
+        let cookie_valid =
+            self.parse_cookies && !cookie_capped && cookie.len() <= self.max_cookie_bytes;
+
+        // ── Verdict flags + header (committed LAST) ─────────────────
         let mut result_flags: u32 = 0;
         if error_code == 0 {
             result_flags |= ROUTE_RESULT_FLAG_OK;
@@ -292,25 +293,10 @@ impl NativeRoute {
         if body_valid {
             result_flags |= ROUTE_RESULT_FLAG_BODY_VALID;
         }
-
-        let required = 8 + query_size + cookie_size;
-        if out.len() < required {
-            return Ok(required); // needed-size: report the exact size, write nothing
-        }
-
-        let mut w = 0usize;
-        // NOTE: pass the FULL `out` slice (not `&mut out[w..]`) — `w` is the
-        // absolute write position, so re-slicing would double-apply the offset
-        // and scatter the header across the buffer.
-        write_u32(out, &mut w, result_flags);
-        write_u32(out, &mut w, error_code);
-        if self.parse_query {
-            write_query_section(out, &mut w, query, self.max_pairs);
-        }
-        if self.parse_cookies {
-            write_cookie_section(out, &mut w, cookie, self.max_pairs);
-        }
-        Ok(w)
+        let mut header = [0u8; RESULT_HEADER_LEN];
+        header[..4].copy_from_slice(&result_flags.to_le_bytes());
+        header[4..].copy_from_slice(&error_code.to_le_bytes());
+        Ok(w.commit(header))
     }
 }
 
@@ -347,143 +333,148 @@ fn query_pairs(query: &[u8]) -> impl Iterator<Item = Pair<'_>> + '_ {
 /// LENIENT segment decode (matches JS `decodeSegment`): `+` → space, `%XX` →
 /// byte, result must be valid UTF-8; on ANY failure the WHOLE original segment
 /// is returned unchanged (with `+` AND `%` intact — the JS catch returns `s`).
-fn decode_segment_lenient(seg: &[u8]) -> Cow<'_, [u8]> {
-    if memchr::memchr2(b'+', b'%', seg).is_none() {
-        return Cow::Borrowed(seg);
-    }
-    let mut replaced = Vec::with_capacity(seg.len());
-    for &b in seg {
-        replaced.push(if b == b'+' { b' ' } else { b });
-    }
-    match decode_percent_utf8(&replaced) {
-        Some(decoded) => Cow::Owned(decoded),
-        None => Cow::Borrowed(seg),
-    }
+///
+/// Decodes into a caller-provided `scratch` (reused across every segment and
+/// pair of the call) so the hot path NEVER allocates per segment — the old
+/// implementation built `Vec::with_capacity` for the `+` replacement AND
+/// another for the percent decode, i.e. two allocations per escaped segment,
+/// twice per call (size pass + write pass).
+///
+/// The slice returned borrows either `seg` (fast path / lenient fallback) or
+/// `scratch`; it is valid only until the next call with the same scratch.
+#[inline]
+fn decode_segment_scratch<'a>(seg: &'a [u8], scratch: &'a mut Vec<u8>) -> &'a [u8] {
+    // Semantics live in ONE place (`util::bytes`) so the route stack and the
+    // packed pair parsers can never disagree: `+` → space, `%XX` → byte, and a
+    // malformed escape or an invalid-UTF-8 result falls back to the WHOLE
+    // original segment (JS `try { decodeURIComponent(...) } catch { return s }`).
+    crate::util::bytes::decode_form_component_scratch(seg, scratch)
 }
 
-/// The decoded byte length of `seg` under the lenient rules (the original
-/// length when decoding fails — the segment is passed through raw).
-#[inline]
-fn decode_segment_len(seg: &[u8]) -> usize {
-    decode_segment_lenient(seg).len()
+// ── Streaming result writer (ONE pass, zero per-segment alloc) ─────
+
+/// Bytes reserved at the head of the result for the `[flags u32][error u32]`
+/// verdict header.
+const RESULT_HEADER_LEN: usize = 8;
+
+/// Streaming result writer: appends bytes while tracking the EXACT required
+/// size, so a single pass produces both the packed result AND the needed-size
+/// answer. The previous shape walked every pair section TWICE (a sizing pass
+/// and a write pass), decoding every escaped segment in both.
+///
+/// Once the caller's buffer proves too small the writer stops copying (and
+/// stops patching) but KEEPS counting `needed`, so the needed-size convention
+/// still reports the exact size from the same pass. The verdict header is
+/// committed LAST, so a too-small buffer is left untouched — the contract
+/// `run()`'s callers rely on.
+struct ResultWriter<'a> {
+    out: &'a mut [u8],
+    pos: usize,
+    needed: usize,
+    full: bool,
 }
 
-/// Percent-decode `input` (which has already had `+`→space applied) and
-/// validate the result is well-formed UTF-8. Returns `None` on a malformed
-/// `%XX` OR invalid UTF-8 (both throw in `decodeURIComponent`).
-fn decode_percent_utf8(input: &[u8]) -> Option<Vec<u8>> {
-    let mut out = Vec::with_capacity(input.len());
-    let mut i = 0usize;
-    while i < input.len() {
-        match input[i] {
-            b'%' => {
-                if i + 2 >= input.len() {
-                    return None;
-                }
-                let hi = hex_val(input[i + 1])?;
-                let lo = hex_val(input[i + 2])?;
-                out.push((hi << 4) | lo);
-                i += 3;
-            }
-            b => {
-                out.push(b);
-                i += 1;
+impl<'a> ResultWriter<'a> {
+    #[inline]
+    fn new(out: &'a mut [u8], header_len: usize) -> Self {
+        Self {
+            full: out.len() < header_len,
+            out,
+            pos: header_len,
+            needed: header_len,
+        }
+    }
+
+    /// Append `bytes`, tracking the required size even after the buffer is full.
+    #[inline]
+    fn bytes(&mut self, bytes: &[u8]) {
+        self.needed += bytes.len();
+        if !self.full {
+            let end = self.pos + bytes.len();
+            if end <= self.out.len() {
+                self.out[self.pos..end].copy_from_slice(bytes);
+                self.pos = end;
+            } else {
+                self.full = true;
             }
         }
     }
-    std::str::from_utf8(&out).ok()?;
-    Some(out)
-}
 
-/// Hex digit → nibble (None for non-hex).
-#[inline]
-fn hex_val(b: u8) -> Option<u8> {
-    match b {
-        b'0'..=b'9' => Some(b - b'0'),
-        b'a'..=b'f' => Some(b - b'a' + 10),
-        b'A'..=b'F' => Some(b - b'A' + 10),
-        _ => None,
+    #[inline]
+    fn u32(&mut self, value: u32) {
+        self.bytes(&value.to_le_bytes());
     }
-}
 
-// ── Pair-section size + write (two passes, zero alloc) ────────────
+    /// Append `[u32 len][bytes]` — the pair-section element layout.
+    #[inline]
+    fn len_prefixed(&mut self, bytes: &[u8]) {
+        self.u32(bytes.len() as u32);
+        self.bytes(bytes);
+    }
 
-/// Size pass over decoded query pairs (name/value both lenient-decoded).
-fn query_section_size(query: &[u8], max_pairs: usize) -> (usize, bool) {
-    let mut size = 4usize;
-    let mut capped = false;
-    for (count, pair) in query_pairs(query).enumerate() {
-        if max_pairs > 0 && count >= max_pairs {
-            capped = true;
-            break;
+    /// Patch a previously reserved u32 (the section pair count) in place.
+    #[inline]
+    fn patch_u32(&mut self, at: usize, value: u32) {
+        if !self.full && at + 4 <= self.out.len() {
+            self.out[at..at + 4].copy_from_slice(&value.to_le_bytes());
         }
-        size += 4 + decode_segment_len(pair.name) + 4 + decode_segment_len(pair.value);
     }
-    (size, capped)
-}
 
-/// Size pass over raw cookie pairs (no URL-decoding).
-fn cookie_section_size(cookie: &[u8], max_pairs: usize) -> (usize, bool) {
-    let mut size = 4usize;
-    let mut capped = false;
-    for (count, (name, value)) in cookie_pairs(cookie).enumerate() {
-        if max_pairs > 0 && count >= max_pairs {
-            capped = true;
-            break;
+    /// Commit the verdict header and return the bytes written — or, when the
+    /// buffer was too small, the EXACT required size (nothing committed).
+    #[inline]
+    fn commit(self, header: [u8; RESULT_HEADER_LEN]) -> usize {
+        if self.full || self.needed > self.out.len() {
+            return self.needed;
         }
-        size += 4 + name.len() + 4 + value.len();
+        self.out[..RESULT_HEADER_LEN].copy_from_slice(&header);
+        self.pos
     }
-    (size, capped)
 }
 
-/// Write a decoded segment as `[u32 len][bytes]` into `out` at `pos`.
-#[inline]
-fn write_segment(out: &mut [u8], pos: &mut usize, seg: &[u8]) {
-    let len = seg.len();
-    out[*pos..*pos + 4].copy_from_slice(&(len as u32).to_le_bytes());
-    *pos += 4;
-    out[*pos..*pos + len].copy_from_slice(seg);
-    *pos += len;
-}
-
-/// Write the query pair section (lenient-decoded names/values).
-fn write_query_section(out: &mut [u8], pos: &mut usize, query: &[u8], max_pairs: usize) {
-    let count_pos = *pos;
-    write_u32(out, pos, 0); // count placeholder
+/// Write the query pair section (lenient-decoded names/values) in ONE pass.
+/// Returns `true` when `max_pairs` capped the section (→ not valid).
+fn write_query_section(
+    w: &mut ResultWriter<'_>,
+    scratch: &mut Vec<u8>,
+    query: &[u8],
+    max_pairs: usize,
+) -> bool {
+    let count_pos = w.pos;
+    w.u32(0); // count placeholder, patched below
     let mut count = 0usize;
+    let mut capped = false;
     for pair in query_pairs(query) {
         if max_pairs > 0 && count >= max_pairs {
+            capped = true;
             break;
         }
-        write_segment(out, pos, &decode_segment_lenient(pair.name));
-        write_segment(out, pos, &decode_segment_lenient(pair.value));
+        w.len_prefixed(decode_segment_scratch(pair.name, scratch));
+        w.len_prefixed(decode_segment_scratch(pair.value, scratch));
         count += 1;
     }
-    out[count_pos..count_pos + 4].copy_from_slice(&(count as u32).to_le_bytes());
+    w.patch_u32(count_pos, count as u32);
+    capped
 }
 
-/// Write the cookie pair section (raw trimmed/unquoted names/values).
-fn write_cookie_section(out: &mut [u8], pos: &mut usize, cookie: &[u8], max_pairs: usize) {
-    let count_pos = *pos;
-    write_u32(out, pos, 0); // count placeholder
+/// Write the cookie pair section (raw trimmed/unquoted names/values) in ONE pass.
+/// Returns `true` when `max_pairs` capped the section (→ not valid).
+fn write_cookie_section(w: &mut ResultWriter<'_>, cookie: &[u8], max_pairs: usize) -> bool {
+    let count_pos = w.pos;
+    w.u32(0); // count placeholder, patched below
     let mut count = 0usize;
+    let mut capped = false;
     for (name, value) in cookie_pairs(cookie) {
         if max_pairs > 0 && count >= max_pairs {
+            capped = true;
             break;
         }
-        write_segment(out, pos, name);
-        write_segment(out, pos, value);
+        w.len_prefixed(name);
+        w.len_prefixed(value);
         count += 1;
     }
-    out[count_pos..count_pos + 4].copy_from_slice(&(count as u32).to_le_bytes());
-}
-
-/// Write a u32 LE into `out` at `pos`, advancing `pos`. Caller guarantees
-/// capacity (sizes are pre-computed).
-#[inline]
-fn write_u32(out: &mut [u8], pos: &mut usize, value: u32) {
-    out[*pos..*pos + 4].copy_from_slice(&value.to_le_bytes());
-    *pos += 4;
+    w.patch_u32(count_pos, count as u32);
+    capped
 }
 
 // ── napi boundary: the `Route` class (Node/fallback transport) ─────

package/rust/ingress/pipeline.rs

@@ -486,9 +486,9 @@ impl IngressInner {
                     self.limits.max_pairs,
                 ) {
                     Ok(written) => written as u32,
-                    Err(crate::json::json_ser::QueryJsonError::Malformed) => {
-                        return Err(Error::from_reason("query parse failed"))
-                    }
+                    // A malformed `%XX` is NOT an error: the decoder returns the
+                    // raw component, exactly like the JS `decodeURIComponent`
+                    // fallback (this used to 400 where JS answers 200).
                     Err(crate::json::json_ser::QueryJsonError::BufferTooSmall) => {
                         truncated = true;
                         0

package/rust/ingress/tests.rs

@@ -547,9 +547,10 @@ fn truncated_multibyte_query_escaped() {
         parse_query: true,
         ..base_inner()
     };
-    // `%E2%9C` decodes to 2 bytes of a 3-byte sequence → invalid UTF-8. The
-    // JSON writer must escape every byte as `\u00XX` (not emit invalid UTF-8),
-    // and the length accounting must match (6 bytes per byte).
+    // `%E2%9C` is a truncated 3-byte sequence: `decodeURIComponent` throws, so
+    // the component is returned RAW ("%E2%9C") — the same thing the JS
+    // fallback does — and the request is NOT rejected. The JSON writer then
+    // sees plain ASCII and the length accounting is the raw length.
     let input = packed_input(0, "/api?q=%E2%9C".as_bytes(), b"127.0.0.1", b"rid");
     let mut out = vec![0u8; 4096];
     inner.handle_packed(&input, b"", &mut out).unwrap();
@@ -562,5 +563,5 @@ fn truncated_multibyte_query_escaped() {
         out[OUT_QUERY_JSON_LEN + 3],
     ]) as usize;
     let query_json = &out[OUT_DATA_START..OUT_DATA_START + query_len];
-    assert_eq!(query_json, br#"{"q":"\u00e2\u009c"}"#);
+    assert_eq!(query_json, br#"{"q":"%E2%9C"}"#);
 }

package/rust/json/json_ser.rs

@@ -416,15 +416,18 @@ pub fn packed_pairs_to_json_into_slice(
 /// same split the old packed pipeline had between its parse and write steps).
 #[derive(Debug, PartialEq, Eq)]
 pub enum QueryJsonError {
-    Malformed,
     BufferTooSmall,
 }
 
 /// Decode a single URL-form component (`+` → space, `%XX` → byte) into `out`.
 ///
-/// Shared decoder with `query_parser::write_decoded_form_component` (this one
-/// appends to a `Vec` rather than writing a length-prefixed slice); errors on
-/// malformed `%XX`.
+/// Uses the LENIENT arm of the shared decoder — the same one the packed pair
+/// parsers use — so a malformed escape or an invalid-UTF-8 escape yields the RAW
+/// component exactly like the pure-TS fallback. (This used to be a strict arm
+/// that rejected malformed `%XX`, which made the native pipeline answer 400
+/// where the JS path returns the raw value.) Bytes that are invalid UTF-8 in the
+/// INPUT still reach the JSON writer verbatim; the escaping below keeps the
+/// output valid JSON.
 #[inline]
 fn decode_query_component(
     src: &[u8],
@@ -432,12 +435,8 @@ fn decode_query_component(
 ) -> std::result::Result<(), QueryJsonError> {
     let start = out.len();
     out.resize(start + src.len(), 0);
-    let written = crate::util::bytes::decode_form_component_into(src, &mut out[start..]).map_err(
-        |e| match e {
-            crate::util::bytes::FormDecodeError::Malformed => QueryJsonError::Malformed,
-            crate::util::bytes::FormDecodeError::BufferTooSmall => QueryJsonError::BufferTooSmall,
-        },
-    )?;
+    let written = crate::util::bytes::decode_form_component_into(src, &mut out[start..])
+        .map_err(|_| QueryJsonError::BufferTooSmall)?;
     out.truncate(start + written);
     Ok(())
 }
@@ -864,7 +863,10 @@ mod tests {
                         "query={raw:?}"
                     );
                 }
-                (Err(_), Err(QueryJsonError::Malformed)) => {} // both reject malformed %XX
+                // Both paths share the lenient decoder now, so a malformed
+                // `%XX` produces the SAME raw component on both sides (the
+                // `Err` arm that used to allow "both reject" is gone with the
+                // strict contract).
                 (other, _) => {
                     panic!("mismatched outcome for query={raw:?}: {other:?} vs {direct:?}")
                 }

package/rust/lib.rs

@@ -59,6 +59,7 @@ pub mod json;
 pub mod metrics;
 pub mod payload;
 pub mod selection;
+pub mod task;
 pub mod util;
 
 // ── Unit tests (cargo test) ───────────────────────────────────────

package/rust/task/completion.rs

@@ -0,0 +1,119 @@
+// rust/task/completion.rs — the completion ring + batched doorbell.
+//
+// THE performance-critical piece. A pooled native thread never returns to JS
+// directly; it pushes a `Completion` here and (at most once per batch) calls a
+// single thread-safe trampoline so the JS thread can drain everything in ONE
+// `castrum_task_drain` call. That amortizes the ~666 ns/crossing threadsafe
+// callback over a whole batch instead of paying it per task.
+//
+// PACKED DRAIN LAYOUT (`out`):
+//   [u32 count LE]
+//   repeat count: [u64 id LE][u32 status][u32 len][len bytes]
+//
+// Needed-size convention (repo-wide): when `out` is too small the EXACT
+// required byte count is returned and nothing is consumed, so JS allocates
+// once and retries once. `0` means "nothing pending".
+//
+// NOTE (2026-09-11): a pointer-based zero-copy variant was prototyped and
+// REVERTED — Bun 1.4.2's `toArrayBuffer` deallocator hook segfaults (see
+// docs/RND-CONCURRENCY.md §7a). Zero-copy will instead pre-allocate the
+// destination in JS and have the pool thread write into it directly.
+
+use parking_lot::Mutex;
+use std::collections::VecDeque;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::OnceLock;
+
+/// One finished task. `status`: 0 = ok, 1 = error, 2 = cancelled. `body` is
+/// the result bytes, or the UTF-8 error message when `status != 0`.
+pub struct Completion {
+    pub id: u64,
+    pub status: u32,
+    pub body: Vec<u8>,
+}
+
+/// Completions waiting to be drained. Lazily initialised WITH capacity so a
+/// burst (hundreds of tasks finishing together) does not pay repeated VecDeque
+/// growth reallocations on the worker threads.
+static RING: OnceLock<Mutex<VecDeque<Completion>>> = OnceLock::new();
+
+/// One burst's worth of entries before the first realloc.
+const RING_CAPACITY: usize = 256;
+
+fn ring() -> &'static Mutex<VecDeque<Completion>> {
+    RING.get_or_init(|| Mutex::new(VecDeque::with_capacity(RING_CAPACITY)))
+}
+/// `true` while a doorbell call is outstanding, so N completions in a burst
+/// wake JS once, not N times.
+static ARMED: AtomicBool = AtomicBool::new(false);
+/// Address of the thread-safe trampoline (`JSCallback({threadsafe:true}).ptr`).
+static DOORBELL: AtomicUsize = AtomicUsize::new(0);
+
+/// Register the doorbell trampoline. `0` disables it (poll-only mode).
+pub fn set_doorbell(cb: usize) {
+    DOORBELL.store(cb, Ordering::Release);
+}
+
+/// Push a completion and ring the doorbell at most once per armed window.
+///
+/// The ring lock is released BEFORE the trampoline is called: the JS callback
+/// re-enters `drain`, which locks the ring again — holding it here would
+/// deadlock the process.
+pub fn push(c: Completion) {
+    let should_ring = {
+        let mut q = ring().lock();
+        q.push_back(c);
+        !ARMED.swap(true, Ordering::AcqRel)
+    };
+    if should_ring {
+        let p = DOORBELL.load(Ordering::Acquire);
+        if p != 0 {
+            // SAFETY: `p` is a live `JSCallback` thread-safe trampoline whose
+            // JS owner is held for the process lifetime by the task runtime.
+            let f: extern "C" fn() = unsafe { std::mem::transmute(p) };
+            f();
+        }
+    }
+}
+
+/// Drain every pending completion into `out`. Returns bytes written, `0` when
+/// nothing is pending, or the exact required size when `out` is too small.
+pub fn drain(out: &mut [u8]) -> usize {
+    // Disarm FIRST so a completion pushed while we drain re-arms and rings the
+    // bell instead of being stranded (see the module note).
+    ARMED.store(false, Ordering::Release);
+    let mut q = ring().lock();
+    if q.is_empty() {
+        return 0;
+    }
+    let mut needed = 4usize;
+    for c in q.iter() {
+        needed += 16 + c.body.len();
+    }
+    if out.len() < needed {
+        return needed;
+    }
+    out[0..4].copy_from_slice(&(q.len() as u32).to_le_bytes());
+    let mut off = 4usize;
+    for c in q.iter() {
+        out[off..off + 8].copy_from_slice(&c.id.to_le_bytes());
+        out[off + 8..off + 12].copy_from_slice(&c.status.to_le_bytes());
+        out[off + 12..off + 16].copy_from_slice(&(c.body.len() as u32).to_le_bytes());
+        out[off + 16..off + 16 + c.body.len()].copy_from_slice(&c.body);
+        off += 16 + c.body.len();
+    }
+    q.clear();
+    needed
+}
+
+/// Completions waiting to be drained.
+pub fn pending() -> u32 {
+    ring().lock().len() as u32
+}
+
+/// Drop every pending completion (shutdown / test isolation). Bodies already
+/// handed to JS by `drain_ptrs` are owned by JS and are NOT freed here.
+pub fn clear() {
+    ring().lock().clear();
+    ARMED.store(false, Ordering::Release);
+}

package/rust/task/mod.rs

@@ -0,0 +1,65 @@
+// rust/task — off-thread task runtime ("castrum Tasks").
+//
+// A Bun-first answer to synchronous FFI: any CPU-bound native op that would
+// otherwise freeze the JS thread is submitted as a task, runs on a dedicated
+// pool thread (NOT the rayon batch pool), and resolves a JS promise through a
+// BATCHED completion doorbell. See docs/RND-CONCURRENCY.md for the design and
+// the measured Bun concurrency costs.
+//
+//   runtime.rs     pool lifecycle (once-per-process) + admission
+//   completion.rs  result ring + batched thread-safe doorbell (the fast path)
+//   ops.rs         op dispatch table + cancellation + panic containment
+//   tests.rs       pool/ring/cancel/panic/doorbell unit tests
+//
+// Safety contract (identical to the rest of the C-ABI surface): every task body
+// runs under `catch_unwind`; no `Mutex` is held across the doorbell call; the
+// pool owns every input buffer after `submit` returns.
+
+pub mod completion;
+pub mod ops;
+pub mod runtime;
+
+#[cfg(test)]
+mod tests;
+
+pub use completion::{drain, pending, set_doorbell};
+pub use ops::{mark_cancelled, STATUS_CANCELLED, STATUS_ERROR, STATUS_OK};
+pub use runtime::{init, shutdown, threads};
+
+/// Submit one task op with packed `args`, completing under `id`.
+///
+/// The pool auto-starts (default worker count) on first use, so callers do not
+/// have to sequence `init` before `submit`. `args` is moved onto the worker.
+pub fn submit_op(op: u32, args: Vec<u8>, id: u64) -> bool {
+    runtime::submit(move || ops::execute_guarded(op, &args, id))
+}
+
+/// Submit one zero-copy task op: the pool thread writes its result DIRECTLY
+/// into the caller's `out` buffer, and the completion body is the 8-byte LE
+/// written length instead of the data. This removes the last full-size copy and
+/// its allocation from the JS thread (see docs/RND-CONCURRENCY.md §7a).
+///
+/// # Safety
+/// `out` must point to a buffer of at least `out_cap` bytes that stays alive
+/// and is not touched by JS until the completion for `id` is drained.
+pub fn submit_op_into(op: u32, args: Vec<u8>, id: u64, out: usize, out_cap: usize) -> bool {
+    runtime::submit(move || unsafe {
+        ops::execute_into_guarded(op, &args, id, out as *mut u8, out_cap)
+    })
+}
+
+/// Submit one task whose PAYLOAD is read IN PLACE from the caller's buffer
+/// (zero-copy INPUT): only the `hdr` header bytes are copied, so a large
+/// argument never crosses the boundary. Without this, offloading a large
+/// op pays a full-size copy on the JS thread — measured to make
+/// `gzipCompress` of 24 MiB SLOWER than the synchronous built-in it replaces
+/// (18.6 ms / 11.7 ms stall vs 5.6 ms), which is the opposite of the point.
+///
+/// # Safety
+/// `data`/`data_len` must describe a readable region that stays alive and
+/// unmodified until the completion for `id` is drained.
+pub fn submit_slice_op(op: u32, hdr: Vec<u8>, data: usize, data_len: usize, id: u64) -> bool {
+    runtime::submit(move || unsafe {
+        ops::execute_slice_guarded(op, &hdr, data as *const u8, data_len, id)
+    })
+}