castrum 0.9.4 → 0.9.7

package/rust/ffi/crypto.rs

@@ -625,6 +625,58 @@ pub unsafe extern "C" fn castrum_random_token_into(
 
 // ── Session envelope (fused JSON + HMAC) ────────────────────────────
 
+/// Shared tail of both seal entry points: `None` (empty id/secret, or a panic)
+/// → null pointer, otherwise clone the sealed token into the engine's
+/// per-thread cstring buffer. Extracted so the cstring and byte forms cannot
+/// diverge — the byte form exists only to change how the INPUTS cross.
+fn sealed_to_cstr(sealed: Option<Vec<u8>>) -> *const std::os::raw::c_char {
+    let Some(tok) = sealed else {
+        return std::ptr::null();
+    };
+    super::util::cstring_return(tok.len(), move |buf| {
+        if buf.len() < tok.len() {
+            return None;
+        }
+        buf[..tok.len()].copy_from_slice(&tok);
+        Some(tok.len())
+    })
+}
+
+/// Shared tail of both open entry points: pack the extracted envelope into the
+/// caller's buffer as `[u8 ok=1][i64 exp][u32 idLen][id][u32 dataLen][dataJson]`,
+/// or report the EXACT size required when `out_cap` is too small. `None` (bad
+/// signature / malformed envelope) → `0`. Never returns `0` on a valid call.
+///
+/// # Safety
+/// `out` must be valid for writes up to `out_cap`; the caller null-checks it.
+unsafe fn pack_open_result(
+    opened: Option<(i64, Vec<u8>, Vec<u8>)>,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    let Some((exp, id, data)) = opened else {
+        return 0;
+    };
+    // Layout size: 1 + 8 + 4+id + 4+data
+    let need = 1 + 8 + 4 + id.len() + 4 + data.len();
+    if need > out_cap {
+        return need;
+    }
+    let o = slice::from_raw_parts_mut(out, need);
+    o[0] = 1;
+    o[1..9].copy_from_slice(&exp.to_le_bytes());
+    let id_len = id.len() as u32;
+    o[9..13].copy_from_slice(&id_len.to_le_bytes());
+    let mut p = 13usize;
+    o[p..p + id.len()].copy_from_slice(&id);
+    p += id.len();
+    let d_len = data.len() as u32;
+    o[p..p + 4].copy_from_slice(&d_len.to_le_bytes());
+    p += 4;
+    o[p..p + data.len()].copy_from_slice(&data);
+    need
+}
+
 /// Seal a session envelope NATIVELY: build
 /// `{"id":"…","data":<data_json>,"exp":exp}` and HMAC-sign it into the
 /// `payload.<64-hex>` cookie token — ONE crossing replaces the JS
@@ -650,16 +702,7 @@ pub unsafe extern "C" fn castrum_session_seal(
         || crate::crypto::session::seal_core(id_b, data_b, exp_secs, sec_b),
         None,
     );
-    let Some(tok) = sealed else {
-        return std::ptr::null();
-    };
-    super::util::cstring_return(tok.len(), move |buf| {
-        if buf.len() < tok.len() {
-            return None;
-        }
-        buf[..tok.len()].copy_from_slice(&tok);
-        Some(tok.len())
-    })
+    sealed_to_cstr(sealed)
 }
 
 /// Open a sealed session token: verify the HMAC and extract the envelope in
@@ -684,25 +727,72 @@ pub unsafe extern "C" fn castrum_session_open(
     let tok = std::ffi::CStr::from_ptr(token).to_bytes();
     let sec = std::ffi::CStr::from_ptr(secret).to_bytes();
     let opened = panic_guard(|| crate::crypto::session::open_core(tok, sec), None);
-    let Some((exp, id, data)) = opened else {
+    pack_open_result(opened, out, out_cap)
+}
+
+/// Byte-arg sibling of `castrum_session_seal`: same core, same wire format, but
+/// every input crosses as `(ptr, len)` instead of a `cstring` ARG.
+///
+/// Per `docs/FFI_BUN_GUIDE.md` §6.1 there are two reasons, and only the second
+/// cannot be worked around:
+/// 1. a `cstring` ARG costs the engine a transcode into a call-scoped
+///    NUL-terminated buffer (~80ns per arg through the public surface vs ~37ns
+///    for the byte path);
+/// 2. an embedded `U+0000` SILENTLY TRUNCATES the value before Rust sees it.
+///    `id` and `data_json` are user-derived (the id is escaped by
+///    `seal_core`, which only makes sense if it may contain arbitrary bytes),
+///    so a session id carrying a NUL would be sealed under its truncated form.
+///    This form carries the exact length and cannot be truncated.
+///
+/// # Safety
+/// `id`/`data_json`/`secret` must be valid for reads of their stated lengths;
+/// null pointers are rejected (→ null).
+#[no_mangle]
+pub unsafe extern "C" fn castrum_session_seal_bytes(
+    id: *const u8,
+    id_len: usize,
+    data_json: *const u8,
+    data_len: usize,
+    exp_secs: i64,
+    secret: *const u8,
+    secret_len: usize,
+) -> *const std::os::raw::c_char {
+    if id.is_null() || data_json.is_null() || secret.is_null() {
+        return std::ptr::null();
+    }
+    let id_b = slice::from_raw_parts(id, id_len);
+    let data_b = slice::from_raw_parts(data_json, data_len);
+    let sec_b = slice::from_raw_parts(secret, secret_len);
+    let sealed = super::util::panic_guard(
+        || crate::crypto::session::seal_core(id_b, data_b, exp_secs, sec_b),
+        None,
+    );
+    sealed_to_cstr(sealed)
+}
+
+/// Byte-arg sibling of `castrum_session_open`: `token`/`secret` cross as
+/// `(ptr, len)`; the output layout and the needed-size convention are identical
+/// to `castrum_session_open` (`0` = bad signature / malformed). Saves the
+/// per-arg transcode and, unlike the `cstring` form, cannot be truncated by an
+/// embedded `U+0000` in the token.
+///
+/// # Safety
+/// `token`/`secret` must be valid for reads of their stated lengths; `out` must
+/// be valid for writes up to `out_cap`. Null pointers → 0.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_session_open_bytes(
+    token: *const u8,
+    token_len: usize,
+    secret: *const u8,
+    secret_len: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if token.is_null() || secret.is_null() || out.is_null() {
         return 0;
-    };
-    // Layout size: 1 + 8 + 4+id + 4+data
-    let need = 1 + 8 + 4 + id.len() + 4 + data.len();
-    if need > out_cap {
-        return need;
     }
-    let o = slice::from_raw_parts_mut(out, need);
-    o[0] = 1;
-    o[1..9].copy_from_slice(&exp.to_le_bytes());
-    let id_len = id.len() as u32;
-    o[9..13].copy_from_slice(&id_len.to_le_bytes());
-    let mut p = 13usize;
-    o[p..p + id.len()].copy_from_slice(&id);
-    p += id.len();
-    let d_len = data.len() as u32;
-    o[p..p + 4].copy_from_slice(&d_len.to_le_bytes());
-    p += 4;
-    o[p..p + data.len()].copy_from_slice(&data);
-    need
+    let tok = slice::from_raw_parts(token, token_len);
+    let sec = slice::from_raw_parts(secret, secret_len);
+    let opened = panic_guard(|| crate::crypto::session::open_core(tok, sec), None);
+    pack_open_result(opened, out, out_cap)
 }

package/rust/ffi/mod.rs

@@ -52,6 +52,7 @@ mod payload;
 mod probe;
 mod rate_limit;
 mod route;
+mod task;
 mod util;
 mod validators;
 

package/rust/ffi/task.rs

@@ -0,0 +1,172 @@
+// rust/ffi/task.rs — C-ABI exports for the off-thread task runtime.
+//
+// Eight symbols, all thin: the pool/ring/ops live in `rust/task/`. `submit`
+// COPIES the packed args onto the worker (the JS caller's pooled buffer is
+// released as soon as submit returns), and `drain` follows the repo-wide
+// needed-size convention so JS grows once and retries once.
+
+use std::slice;
+
+use super::util::panic_guard;
+use crate::task;
+
+/// Start the pool with `threads` workers (0 → runtime default).
+/// Returns `0` started, `1` already running, `2` internal error.
+#[no_mangle]
+pub extern "C" fn castrum_task_init(threads: u32) -> u32 {
+    panic_guard(|| task::init(Some(threads)), 2)
+}
+
+/// Submit `op` with `args_len` packed arg bytes, completing under `task_id`.
+/// Returns `1` accepted, `0` rejected (null args with a non-zero length).
+///
+/// # Safety
+/// `args` must be valid for reads of `args_len` bytes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_submit(
+    op: u32,
+    args: *const u8,
+    args_len: usize,
+    task_id: usize,
+) -> u32 {
+    if args.is_null() && args_len != 0 {
+        return 0;
+    }
+    let owned: Vec<u8> = if args_len == 0 {
+        Vec::new()
+    } else {
+        slice::from_raw_parts(args, args_len).to_vec()
+    };
+    u32::from(task::submit_op(op, owned, task_id as u64))
+}
+
+/// Drain finished tasks into `out` (packed `[u32 count][entry…]`).
+/// Returns bytes written, `0` when nothing is pending, or the EXACT required
+/// size when `out` is too small (nothing is consumed in that case).
+///
+/// # Safety
+/// `out` must be valid for writes of `out_cap` bytes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_drain(out: *mut u8, out_cap: usize) -> usize {
+    if out.is_null() {
+        return 0;
+    }
+    panic_guard(|| task::drain(slice::from_raw_parts_mut(out, out_cap)), 0)
+}
+
+/// Completions waiting to be drained.
+#[no_mangle]
+pub extern "C" fn castrum_task_pending() -> u32 {
+    task::pending()
+}
+
+/// Submit an op that writes its result DIRECTLY into `out` (zero-copy output):
+/// the completion body is the 8-byte LE written length, not the data, so JS
+/// resolves a view of the buffer it already owns. A too-small `out` completes
+/// with status 3 (TOO_SMALL) and the exact required size as the body; status 4
+/// (UNSUPPORTED) means the op has no `_into` form and the caller should fall
+/// back to `castrum_task_submit`.
+///
+/// Returns `1` accepted, `0` rejected.
+///
+/// # Safety
+/// `args` must be valid for reads of `args_len` bytes. `out` must be valid for
+/// writes of `out_cap` bytes and must stay alive (and untouched by JS) until the
+/// completion for `task_id` is drained.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_submit_out(
+    op: u32,
+    args: *const u8,
+    args_len: usize,
+    task_id: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> u32 {
+    if (args.is_null() && args_len != 0) || out.is_null() || out_cap == 0 {
+        return 0;
+    }
+    let owned: Vec<u8> = if args_len == 0 {
+        Vec::new()
+    } else {
+        slice::from_raw_parts(args, args_len).to_vec()
+    };
+    u32::from(task::submit_op_into(
+        op,
+        owned,
+        task_id as u64,
+        out as usize,
+        out_cap,
+    ))
+}
+
+/// Mark `task_id` cancelled. Returns `1` when newly marked, `0` otherwise.
+#[no_mangle]
+pub extern "C" fn castrum_task_cancel(task_id: usize) -> u32 {
+    u32::from(task::mark_cancelled(task_id as u64))
+}
+
+/// Submit an op whose PAYLOAD is read IN PLACE from the caller's buffer
+/// (zero-copy INPUT). Only the `hdr_len` header bytes are copied, so a large
+/// argument never crosses the boundary — without this, offloading a big
+/// compression costs a full-size copy on the JS thread and measured WORSE than
+/// the synchronous built-in (docs/RND-CONCURRENCY.md §7b).
+///
+/// Returns `1` accepted, `0` rejected.
+///
+/// # Safety
+/// `hdr` must be valid for reads of `hdr_len` bytes. `data` must be valid for
+/// reads of `data_len` bytes and must stay alive (and unmodified by JS) until
+/// the completion for `task_id` is drained.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_submit_slice(
+    op: u32,
+    hdr: *const u8,
+    hdr_len: usize,
+    data: *const u8,
+    data_len: usize,
+    task_id: usize,
+) -> u32 {
+    if (hdr.is_null() && hdr_len != 0) || (data.is_null() && data_len != 0) {
+        return 0;
+    }
+    // The header is small, so copying it keeps the caller free to reuse a
+    // scratch buffer; the payload is never copied.
+    let owned = if hdr_len == 0 {
+        Vec::new()
+    } else {
+        slice::from_raw_parts(hdr, hdr_len).to_vec()
+    };
+    u32::from(task::submit_slice_op(
+        op,
+        owned,
+        data as usize,
+        data_len,
+        task_id as u64,
+    ))
+}
+
+/// Register the thread-safe doorbell trampoline address (`0` disables it).
+/// Returns `1` on success.
+///
+/// # Safety
+/// `cb` must be a live `void()` C trampoline that is safe to call from any
+/// thread (a `bun:ffi` `JSCallback({ threadsafe: true }).ptr`).
+#[no_mangle]
+pub extern "C" fn castrum_task_set_doorbell(cb: *const std::os::raw::c_void) -> u32 {
+    task::set_doorbell(cb as usize);
+    1
+}
+
+/// Stop the pool and drop pending completions. Returns `0`.
+#[no_mangle]
+pub extern "C" fn castrum_task_shutdown() -> u32 {
+    task::shutdown();
+    task::completion::clear();
+    0
+}
+
+/// Configured pool worker count (0 before the pool starts).
+#[no_mangle]
+pub extern "C" fn castrum_task_threads() -> u32 {
+    task::threads()
+}

package/rust/ffi/tests.rs

@@ -2308,6 +2308,179 @@ fn wire_validate_and_session_c_abi() {
         unsafe { castrum_session_open(token, c"wrong".as_ptr(), buf.as_mut_ptr(), buf.len()) },
         0
     );
+
+    // ── Byte-arg siblings ──────────────────────────────────────────
+    // Copy the first token OUT of the shared per-thread CSTR_BUF before the
+    // next `cstring` return reuses it (that buffer is one-per-thread by design).
+    let token_str = unsafe { std::ffi::CStr::from_ptr(token) }
+        .to_string_lossy()
+        .into_owned();
+    let id = b"sess-9";
+    let data = b"{\"n\":1}";
+    let secret = b"sekrit";
+    let token_b = unsafe {
+        castrum_session_seal_bytes(
+            id.as_ptr(),
+            id.len(),
+            data.as_ptr(),
+            data.len(),
+            1_234_567,
+            secret.as_ptr(),
+            secret.len(),
+        )
+    };
+    assert!(!token_b.is_null());
+    // One shared core ⇒ byte-identical token. This is the parity guarantee that
+    // makes the byte form a drop-in for the cstring form.
+    let token_b_str = unsafe { std::ffi::CStr::from_ptr(token_b) }
+        .to_string_lossy()
+        .into_owned();
+    assert_eq!(token_b_str, token_str);
+
+    let tok_bytes = token_b_str.as_bytes();
+    let mut buf2 = [0u8; 256];
+    let w2 = unsafe {
+        castrum_session_open_bytes(
+            tok_bytes.as_ptr(),
+            tok_bytes.len(),
+            secret.as_ptr(),
+            secret.len(),
+            buf2.as_mut_ptr(),
+            buf2.len(),
+        )
+    };
+    assert_eq!(w2, w);
+    assert_eq!(buf2[..w2], buf[..w]);
+    // bad signature → 0
+    assert_eq!(
+        unsafe {
+            castrum_session_open_bytes(
+                tok_bytes.as_ptr(),
+                tok_bytes.len(),
+                b"wrong".as_ptr(),
+                5,
+                buf2.as_mut_ptr(),
+                buf2.len(),
+            )
+        },
+        0
+    );
+    // Too-small buffer → the EXACT required size, not 0 (needed-size rule).
+    assert_eq!(
+        unsafe {
+            castrum_session_open_bytes(
+                tok_bytes.as_ptr(),
+                tok_bytes.len(),
+                secret.as_ptr(),
+                secret.len(),
+                buf2.as_mut_ptr(),
+                4,
+            )
+        },
+        w2
+    );
+
+    // The reason this sibling exists: the cstring form TRUNCATES at an embedded
+    // NUL (the engine's transcode is NUL-terminated), so an id carrying one is
+    // sealed under its truncated form. The byte form carries the exact length.
+    //
+    // Each token is copied to a String IMMEDIATELY after its own call: both
+    // `cstring` returns write into ONE per-thread CSTR_BUF, so the earlier
+    // pointer is dead the moment the next call reuses it — the aliasing hazard
+    // `docs/FFI_BUN_GUIDE.md` documents. The assertions below also read the
+    // recovered `id` BYTES rather than the token's text, so they hold
+    // regardless of how the payload is wire-encoded.
+    let nul_id = b"sess-9\0extra";
+    let tp = unsafe {
+        castrum_session_seal(
+            nul_id.as_ptr() as *const std::os::raw::c_char,
+            c"{\"n\":1}".as_ptr(),
+            1_234_567,
+            c"sekrit".as_ptr(),
+        )
+    };
+    assert!(!tp.is_null());
+    let truncated_str = unsafe { std::ffi::CStr::from_ptr(tp) }
+        .to_string_lossy()
+        .into_owned();
+
+    let ep = unsafe {
+        castrum_session_seal_bytes(
+            nul_id.as_ptr(),
+            nul_id.len(),
+            data.as_ptr(),
+            data.len(),
+            1_234_567,
+            secret.as_ptr(),
+            secret.len(),
+        )
+    };
+    assert!(!ep.is_null());
+    let exact_str = unsafe { std::ffi::CStr::from_ptr(ep) }
+        .to_string_lossy()
+        .into_owned();
+
+    assert_ne!(
+        exact_str, truncated_str,
+        "byte form must not truncate at NUL"
+    );
+
+    // Open each token and read back the `id` from the packed layout
+    // (`[u8 ok][i64 exp][u32 idLen][id]…`) — the ground truth this change is
+    // about. NOTE: `seal_core` JSON-escapes the id but `open_core` returns the
+    // raw captured span, so an id needing escapes comes back escaped. That
+    // asymmetry is pre-existing; these assertions are written not to depend on
+    // it, only on the truncation itself.
+    let id_of = |tok: &str, out: &mut [u8; 256]| -> Vec<u8> {
+        let w = unsafe {
+            castrum_session_open_bytes(
+                tok.as_ptr(),
+                tok.len(),
+                secret.as_ptr(),
+                secret.len(),
+                out.as_mut_ptr(),
+                out.len(),
+            )
+        };
+        assert!(w > 13, "open of {tok:?} failed");
+        let id_len = u32::from_le_bytes([out[9], out[10], out[11], out[12]]) as usize;
+        out[13..13 + id_len].to_vec()
+    };
+    let mut scratch = [0u8; 256];
+    let truncated_id = id_of(&truncated_str, &mut scratch);
+    let exact_id = id_of(&exact_str, &mut scratch);
+    assert_eq!(truncated_id, b"sess-9");
+    // The byte form carries the exact length, so the id comes back WHOLE — and
+    // byte-exact, because `open_core` now decodes the id rather than returning
+    // the escaped span.
+    assert_eq!(exact_id, &nul_id[..]);
+
+    // Null pointers are rejected, never dereferenced.
+    assert!(unsafe {
+        castrum_session_seal_bytes(
+            std::ptr::null(),
+            0,
+            std::ptr::null(),
+            0,
+            0,
+            std::ptr::null(),
+            0,
+        )
+    }
+    .is_null());
+    assert_eq!(
+        unsafe {
+            castrum_session_open_bytes(
+                std::ptr::null(),
+                0,
+                secret.as_ptr(),
+                secret.len(),
+                buf2.as_mut_ptr(),
+                buf2.len(),
+            )
+        },
+        0
+    );
 }
 
 #[test]

package/rust/http/form.rs

@@ -108,8 +108,12 @@ mod tests {
     }
 
     #[test]
-    fn form_parse_rejects_malformed_percent() {
-        assert!(form_parse_packed_vec(b"a=%ZZ").is_err());
+    fn form_parse_malformed_percent_falls_back_to_raw() {
+        let packed = form_parse_packed_vec(b"a=%ZZ").unwrap();
+        assert_eq!(
+            crate::test_support::decode_packed_pairs(&packed),
+            vec![(b"a".to_vec(), b"%ZZ".to_vec())]
+        );
     }
 
     #[test]

package/rust/http/query_parser.rs

@@ -15,16 +15,14 @@ fn write_decoded_form_component(src: &[u8], out: &mut [u8], pos: &mut usize) ->
     // the remaining buffer against the ACTUAL decoded length (so a `%XX`-heavy
     // component only needs room for its decoded form, matching the pre-refactor
     // behavior where a buffer sized to the decoded length succeeds).
-    let written = crate::util::bytes::decode_form_component_into(src, &mut out[*pos..]).map_err(
-        |e| match e {
-            crate::util::bytes::FormDecodeError::Malformed => {
-                Error::from_reason("invalid %-encoding: malformed %XX sequence")
-            }
-            crate::util::bytes::FormDecodeError::BufferTooSmall => {
-                Error::from_reason("packed output: buffer too small")
-            }
-        },
-    )?;
+    //
+    // A malformed escape is NOT an error here: the shared decoder answers with
+    // the raw component, exactly like the pure-TS fallback
+    // (`decodeURIComponent` throws → `catch` returns the segment). The only
+    // error left is a too-small output buffer, which the C-ABI caller turns
+    // into the needed-size answer.
+    let written = crate::util::bytes::decode_form_component_into(src, &mut out[*pos..])
+        .map_err(|_| Error::from_reason("packed output: buffer too small"))?;
     *pos += written;
     let decoded_len = written as u32;
     out[len_pos..len_pos + 4].copy_from_slice(&decoded_len.to_le_bytes());
@@ -59,8 +57,9 @@ pub fn query_parse_packed_into_slice(input: &[u8], out: &mut [u8]) -> Result<usi
 /// Compute the EXACT packed output size for `input` WITHOUT writing — the
 /// "needed-size" pass for the C-ABI convention. Mirrors
 /// [`query_parse_packed_into_slice`]'s structure exactly (split on `&`, skip
-/// empty pairs, split at `=`), so the reported size is byte-exact and a
-/// malformed `%XX` still surfaces as `Err` (caller → `0`).
+/// empty pairs, split at `=`) AND its decoding, including the raw fallback for a
+/// malformed `%XX`: the reported size and the written size must never disagree,
+/// or the caller's grow-and-retry loop would never terminate.
 #[inline]
 pub fn query_parse_packed_size(input: &[u8]) -> Result<usize> {
     let mut size = 4usize; // count prefix
@@ -72,10 +71,8 @@ pub fn query_parse_packed_size(input: &[u8]) -> Result<usize> {
             Some(eq) => (&pair[..eq], &pair[eq + 1..]),
             None => (pair, &[][..]),
         };
-        size += 4 + crate::util::bytes::decode_form_component_len(key)
-            .map_err(|_| Error::from_reason("invalid %-encoding: malformed %XX sequence"))?;
-        size += 4 + crate::util::bytes::decode_form_component_len(value)
-            .map_err(|_| Error::from_reason("invalid %-encoding: malformed %XX sequence"))?;
+        size += 4 + crate::util::bytes::decode_form_component_len(key);
+        size += 4 + crate::util::bytes::decode_form_component_len(value);
     }
     Ok(size)
 }
@@ -139,8 +136,34 @@ mod tests {
     }
 
     #[test]
-    fn query_parse_invalid_percent_rejected() {
-        assert!(query_parse_packed_vec(b"a=%ZZ").is_err());
+    fn query_parse_malformed_percent_falls_back_to_raw() {
+        // JS: `try { decodeURIComponent(s.replace(/\+/g," ")) } catch { return s }`
+        // — applied PER COMPONENT, so name and value fail independently. Checked
+        // against Bun's `decodeURIComponent`:
+        //   "a=%ZZ"     → [["a", "%ZZ"]]
+        //   "a+b=%2"    → [["a b", "%2"]]      (`+` in the NAME still decodes)
+        //   "x=1+2%ZZ"  → [["x", "1+2%ZZ"]]    (raw keeps its `+`)
+        //   "a+b=%20"   → [["a b", " "]]
+        let packed = query_parse_packed_vec(b"a=%ZZ").unwrap();
+        assert_eq!(
+            decode_packed_pairs(&packed),
+            vec![(b"a".to_vec(), b"%ZZ".to_vec())]
+        );
+        let packed = query_parse_packed_vec(b"a+b=%2").unwrap();
+        assert_eq!(
+            decode_packed_pairs(&packed),
+            vec![(b"a b".to_vec(), b"%2".to_vec())]
+        );
+        let packed = query_parse_packed_vec(b"x=1+2%ZZ").unwrap();
+        assert_eq!(
+            decode_packed_pairs(&packed),
+            vec![(b"x".to_vec(), b"1+2%ZZ".to_vec())]
+        );
+        let packed = query_parse_packed_vec(b"a+b=%20").unwrap();
+        assert_eq!(
+            decode_packed_pairs(&packed),
+            vec![(b"a b".to_vec(), b" ".to_vec())]
+        );
     }
 
     #[test]
@@ -169,12 +192,20 @@ mod tests {
     }
 
     #[test]
-    fn query_parse_non_utf8_byte_passthrough() {
-        // `%FF` decodes to a raw 0xFF byte; the parser does not require valid
-        // UTF-8 in query values (callers must handle it when they do).
+    fn query_parse_non_utf8_escape_falls_back_to_raw() {
+        // `%FF` decodes to a byte that cannot appear in valid UTF-8, so JS's
+        // `decodeURIComponent` throws and the component is returned raw. The
+        // packed output must therefore hold the literal `%FF` text, NOT a 0xFF
+        // byte (which a JS caller could only read back lossily as U+FFFD).
         let packed = query_parse_packed_vec(b"a=%FF").unwrap();
         let pairs = decode_packed_pairs(&packed);
         assert_eq!(pairs.len(), 1);
-        assert_eq!(pairs[0], (b"a".to_vec(), vec![0xFF]));
+        assert_eq!(pairs[0], (b"a".to_vec(), b"%FF".to_vec()));
+        // A literal invalid byte with nothing to decode still passes through.
+        let packed = query_parse_packed_vec(b"a=\xFF").unwrap();
+        assert_eq!(
+            decode_packed_pairs(&packed),
+            vec![(b"a".to_vec(), b"\xFF".to_vec())]
+        );
     }
 }