castrum 0.9.3 → 0.9.4

package/rust/json/mod.rs

@@ -0,0 +1,19 @@
+//! JSON & schema (zero-DOM validate/sum + DOM parse + fast schema engine).
+//
+//   - json_ops.rs       zero-DOM validate/sum + DOM parse
+//   - json_ser.rs       zero-alloc JSON escaping + cookie/query → JSON writers
+//   - patch/            RFC 6902 JSON patch (pointer/ops/engine/api)
+//   - json_schema.rs    SchemaValidator napi class (fast + fallback)
+//   - napi_marshal.rs   sonic_rs::Value → JS marshaling + sonic values_equal
+//                       (serde_json::Value DOM swap; jsonschema-compatible
+//                       equality for fast_schema enum/const/uniqueItems)
+//   - fast_schema/      zero-DOM JSON Schema fast path (compiles the common
+//                       keyword subset into a FastNode AST; unsupported
+//                       keywords fall back to the jsonschema crate DOM path)
+
+pub mod fast_schema;
+pub mod json_ops;
+pub mod json_schema;
+pub mod json_ser;
+pub mod napi_marshal;
+pub mod patch;

package/rust/json/napi_marshal.rs

@@ -0,0 +1,318 @@
+//! sonic-rs → JS value marshaling + jsonschema-compatible equality.
+//!
+//! `serde_json::Value` DOMs are being replaced with `sonic_rs::Value` (compact
+//! 16-byte tagged nodes, borrowed/inline strings, zero per-key heap `String`)
+//! across the crate. The napi `serde-json` feature only marshals
+//! `serde_json::Value` to JS, so this module supplies the hand-written
+//! equivalent for `sonic_rs::Value`:
+//!
+//! - [`sonic_value_to_js`] walks a `sonic_rs::Value` directly into a JS value
+//!   (no `serde_json::Value` intermediate, no generic serde trait dispatch).
+//!   Number handling is byte-parity with the napi `serde-json` `ToNapiValue
+//!   for serde_json::Number`: `PosInt` u64 ≤ u32::MAX → **Number**, larger →
+//!   **BigInt**; `NegInt` i64 within ±2^53-1 → **Number**, outside → **BigInt**;
+//!   `Float` → **Number** (see [`sonic_number_to_js`]).
+//! - [`sonic_values_equal`] replicates jsonschema's `cmp::equal` (exact
+//!   cross-type numeric equality via `num_cmp`, insertion-order object keys)
+//!   for the fast_schema enum/const/uniqueItems paths.
+//!
+//! This module is napi-type-laden by design (it bridges to JS); pure numeric /
+//! equality logic stays in the small private fns below and is unit-tested.
+
+use napi::bindgen_prelude::{
+    BigInt, Env, FromNapiValue, Null, Object, Result, ToNapiValue, Unknown,
+};
+use sonic_rs::JsonNumberTrait;
+
+/// Wrap a `ToNapiValue` as an unconstrained-lifetime `Unknown`.
+///
+/// `Unknown<'env>` cannot borrow from the `Env` function parameter (that local
+/// borrow can't escape the call), so we build the raw `napi_value` and re-wrap
+/// via `Unknown::from_napi_value(env.raw(), …)` — the raw `napi_env`/`napi_value`
+/// are Copy pointers rooted by the caller's handle scope, so the `'static`
+/// phantom is nominal (the same pattern napi-rs uses for
+/// `#[napi] fn(env: Env) -> Result<Unknown>`).
+#[inline]
+fn to_unknown(env: &Env, v: impl ToNapiValue) -> Result<Unknown<'static>> {
+    // Safety: `env.raw()` is a valid napi_env for the call, and `v`'s JS value
+    // is rooted in the caller's handle scope.
+    let raw = unsafe { ToNapiValue::to_napi_value(env.raw(), v) }?;
+    // Safety: same env + the just-created value are valid.
+    unsafe { Unknown::from_napi_value(env.raw(), raw) }
+}
+
+/// Marshal a `sonic_rs::Value` into a JS value.
+///
+/// The returned JS value is fully independent of `value` (napi builds new
+/// primitives/containers), so `value` may borrow from a caller buffer that is
+/// released after the call.
+pub(crate) fn sonic_value_to_js(env: &Env, value: &sonic_rs::Value) -> Result<Unknown<'static>> {
+    match value.as_ref() {
+        sonic_rs::value::ValueRef::Null => to_unknown(env, Null),
+        sonic_rs::value::ValueRef::Bool(b) => to_unknown(env, b),
+        sonic_rs::value::ValueRef::Number(n) => sonic_number_to_js(env, &n),
+        sonic_rs::value::ValueRef::String(s) => to_unknown(env, env.create_string(s)?),
+        sonic_rs::value::ValueRef::Array(arr) => {
+            let mut out = env.create_array(arr.len() as u32)?;
+            for (i, item) in arr.into_iter().enumerate() {
+                out.set(i as u32, sonic_value_to_js(env, item)?)?;
+            }
+            to_unknown(env, out)
+        }
+        sonic_rs::value::ValueRef::Object(obj) => {
+            let mut out = Object::new(env)?;
+            for (k, v) in obj.iter() {
+                out.set(k, sonic_value_to_js(env, v)?)?;
+            }
+            to_unknown(env, out)
+        }
+    }
+}
+
+/// Marshal a sonic `Number` to JS with **exact** parity to the napi
+/// `serde-json` `ToNapiValue for serde_json::Number` (the behavior the old
+/// `serde_json::Value` returns produced):
+/// - PosInt (u64): `> u32::MAX` → **BigInt**, else → **Number** (the napi
+///   serde-json impl routes u64 ≤ u32::MAX through `u32::to_napi_value`).
+/// - NegInt (i64): outside ±2^53-1 (`MAX_SAFE_INT`) → **BigInt**, else →
+///   **Number**.
+/// - Float: **Number**.
+///
+/// `as_u64` is checked first so `PosInt` mirrors serde_json's u64-backed
+/// `Number` (a positive integer that also fits i64 must still take the u64
+/// branch — e.g. `3_000_000_000` is BigInt in serde_json, not Number).
+fn sonic_number_to_js(env: &Env, n: &sonic_rs::Number) -> Result<Unknown<'static>> {
+    const MAX_SAFE_INT: i64 = 9007199254740991; // 2^53 - 1 (napi `napi6` guard)
+    if let Some(u) = n.as_u64() {
+        if u > u32::MAX as u64 {
+            to_unknown(env, BigInt::from(u))
+        } else {
+            to_unknown(env, u as u32)
+        }
+    } else if let Some(i) = n.as_i64() {
+        if !(-MAX_SAFE_INT..=MAX_SAFE_INT).contains(&i) {
+            to_unknown(env, BigInt::from(i))
+        } else {
+            to_unknown(env, i)
+        }
+    } else if let Some(f) = n.as_f64() {
+        to_unknown(env, f)
+    } else {
+        // Unreachable for a parsed JSON number (all three are mutually
+        // exhaustive over PosInt/NegInt/Float); defensive fallback.
+        to_unknown(env, Null)
+    }
+}
+
+/// JSON value equality replicating jsonschema's `cmp::equal` (exact across
+/// u64/i64/f64 via `num_cmp`, insertion-order object keys). This is the sonic
+/// `Value` twin of the serde_json `values_equal` in fast_schema/validate.rs —
+/// keep the two semantically identical (the fast path must stay byte-parity
+/// with the jsonschema crate).
+pub(crate) fn sonic_values_equal(a: &sonic_rs::Value, b: &sonic_rs::Value) -> bool {
+    use sonic_rs::value::ValueRef;
+    match (a.as_ref(), b.as_ref()) {
+        (ValueRef::Null, ValueRef::Null) => true,
+        (ValueRef::Bool(x), ValueRef::Bool(y)) => x == y,
+        (ValueRef::Number(x), ValueRef::Number(y)) => sonic_numbers_equal(&x, &y),
+        (ValueRef::String(x), ValueRef::String(y)) => x == y,
+        (ValueRef::Array(x), ValueRef::Array(y)) => {
+            x.len() == y.len()
+                && x.iter()
+                    .zip(y.iter())
+                    .all(|(a, b)| sonic_values_equal(a, b))
+        }
+        (ValueRef::Object(x), ValueRef::Object(y)) => {
+            // Insertion-order comparison, replicating jsonschema's cmp::equal
+            // (key order is SIGNIFICANT in the crate's object equality).
+            x.len() == y.len()
+                && x.iter()
+                    .zip(y.iter())
+                    .all(|((ka, va), (kb, vb))| ka == kb && sonic_values_equal(va, vb))
+        }
+        _ => false,
+    }
+}
+
+/// Exact cross-representation number equality (num_cmp semantics, matching
+/// jsonschema's `equal_numbers` without arbitrary-precision).
+fn sonic_numbers_equal(a: &sonic_rs::Number, b: &sonic_rs::Number) -> bool {
+    use num_cmp::NumCmp;
+    if let Some(x) = a.as_u64() {
+        if let Some(y) = b.as_u64() {
+            return x == y;
+        }
+        if let Some(y) = b.as_i64() {
+            return y >= 0 && x == y as u64;
+        }
+        return x.num_eq(b.as_f64().unwrap_or(f64::NAN));
+    }
+    if let Some(x) = a.as_i64() {
+        if let Some(y) = b.as_i64() {
+            return x == y;
+        }
+        if let Some(y) = b.as_u64() {
+            return x >= 0 && y == x as u64;
+        }
+        return x.num_eq(b.as_f64().unwrap_or(f64::NAN));
+    }
+    if let Some(x) = a.as_f64() {
+        if let Some(y) = b.as_f64() {
+            return x == y;
+        }
+        if let Some(y) = b.as_u64() {
+            return x.num_eq(y);
+        }
+        if let Some(y) = b.as_i64() {
+            return x.num_eq(y);
+        }
+    }
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    /// Round-trip a serde_json Value through JSON bytes into a sonic Value.
+    fn to_sonic(sv: &serde_json::Value) -> sonic_rs::Value {
+        sonic_rs::from_slice::<sonic_rs::Value>(&serde_json::to_vec(sv).unwrap()).unwrap()
+    }
+
+    /// The serde_json reference implementation this port must match.
+    fn serde_values_equal(a: &serde_json::Value, b: &serde_json::Value) -> bool {
+        match (a, b) {
+            (serde_json::Value::Null, serde_json::Value::Null) => true,
+            (serde_json::Value::Bool(x), serde_json::Value::Bool(y)) => x == y,
+            (serde_json::Value::Number(x), serde_json::Value::Number(y)) => {
+                serde_numbers_equal(x, y)
+            }
+            (serde_json::Value::String(x), serde_json::Value::String(y)) => x == y,
+            (serde_json::Value::Array(x), serde_json::Value::Array(y)) => {
+                x.len() == y.len()
+                    && x.iter()
+                        .zip(y.iter())
+                        .all(|(a, b)| serde_values_equal(a, b))
+            }
+            (serde_json::Value::Object(x), serde_json::Value::Object(y)) => {
+                x.len() == y.len()
+                    && x.iter()
+                        .zip(y.iter())
+                        .all(|((ka, va), (kb, vb))| ka == kb && serde_values_equal(va, vb))
+            }
+            _ => false,
+        }
+    }
+
+    fn serde_numbers_equal(a: &serde_json::Number, b: &serde_json::Number) -> bool {
+        use num_cmp::NumCmp;
+        if let Some(x) = a.as_u64() {
+            if let Some(y) = b.as_u64() {
+                return x == y;
+            }
+            if let Some(y) = b.as_i64() {
+                return y >= 0 && x == y as u64;
+            }
+            return x.num_eq(b.as_f64().unwrap_or(f64::NAN));
+        }
+        if let Some(x) = a.as_i64() {
+            if let Some(y) = b.as_i64() {
+                return x == y;
+            }
+            if let Some(y) = b.as_u64() {
+                return x >= 0 && y == x as u64;
+            }
+            return x.num_eq(b.as_f64().unwrap_or(f64::NAN));
+        }
+        if let Some(x) = a.as_f64() {
+            if let Some(y) = b.as_f64() {
+                return x == y;
+            }
+            if let Some(y) = b.as_u64() {
+                return x.num_eq(y);
+            }
+            if let Some(y) = b.as_i64() {
+                return x.num_eq(y);
+            }
+        }
+        false
+    }
+
+    fn corpus() -> Vec<serde_json::Value> {
+        vec![
+            json!(null),
+            json!(true),
+            json!(false),
+            json!(0),
+            json!(1),
+            json!(-1),
+            json!(i64::MAX),
+            json!(i64::MIN),
+            json!(u64::MAX),
+            json!(1.5),
+            json!(-2.25),
+            json!(0.0),
+            json!(1e300),
+            json!(""),
+            json!("hello"),
+            json!("héllo wörld 😀"),
+            json!(r#"escaped "quotes" \n \u0041"#),
+            json!([]),
+            json!([1, "two", true, null, [3.5], {"k": "v"}]),
+            json!({"a": 1, "b": [1, 2, 3], "c": {"d": null, "e": "x"}}),
+        ]
+    }
+
+    #[test]
+    fn sonic_values_equal_matches_serde_reference() {
+        let c = corpus();
+        for a in &c {
+            for b in &c {
+                let sa = to_sonic(a);
+                let sb = to_sonic(b);
+                let sonic = sonic_values_equal(&sa, &sb);
+                let serde = serde_values_equal(a, b);
+                assert_eq!(
+                    sonic, serde,
+                    "mismatch: {a} vs {b} (sonic={sonic}, serde={serde})"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn numeric_cross_type_equality() {
+        // 1 == 1.0 across representations (jsonschema cmp::equal).
+        let one_int: serde_json::Value = json!(1);
+        let one_float: serde_json::Value = json!(1.0);
+        assert!(sonic_values_equal(
+            &to_sonic(&one_int),
+            &to_sonic(&one_float)
+        ));
+
+        // u64 that exceeds i64::MAX is NOT equal to its wrapped i64.
+        let big: serde_json::Value = json!(u64::MAX);
+        let neg: serde_json::Value = json!(-1);
+        assert!(!sonic_values_equal(&to_sonic(&big), &to_sonic(&neg)));
+
+        // Exact fractional equality (1.5 != 1.5000000000000001 differs).
+        let a: serde_json::Value = json!(1.5);
+        let b: serde_json::Value = json!(1.5000000000000002);
+        assert!(!sonic_values_equal(&to_sonic(&a), &to_sonic(&b)));
+
+        // String vs number never equal.
+        assert!(!sonic_values_equal(
+            &to_sonic(&json!("1")),
+            &to_sonic(&json!(1))
+        ));
+    }
+
+    #[test]
+    fn object_key_order_is_significant() {
+        let a = json!({"a": 1, "b": 2});
+        let b = json!({"b": 2, "a": 1});
+        assert!(sonic_values_equal(&to_sonic(&a), &to_sonic(&a)));
+        assert!(!sonic_values_equal(&to_sonic(&a), &to_sonic(&b)));
+    }
+}

package/rust/json/patch/api.rs

@@ -0,0 +1,60 @@
+// rust/json/patch/api.rs — napi boundary for RFC 6902 JSON Patch.
+//
+// Thin `#[napi]` wrappers over the pure core in `engine.rs` that map
+// `JsonPatchError` → napi `Error` with stable context.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::util::unpack;
+
+use super::engine::{apply_json_patch_bytes, run_json_patch_batch};
+
+/// Apply an RFC 6902 JSON Patch to a JSON document.
+///
+/// `doc` and `patch` are raw JSON byte buffers; the patched document is
+/// returned as JSON bytes. Throws on invalid JSON or an inapplicable patch.
+#[napi]
+pub fn json_patch(doc: Uint8Array, patch: Uint8Array) -> Result<Buffer> {
+    apply_json_patch_bytes(doc.as_ref(), patch.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Apply a batch of RFC 6902 patches (packed in → packed out).
+///
+/// `docs` and `patches` are packed buffers (`[u32 count] { [u32 len] [bytes] }`)
+/// of equal length, zipped per index. Returns packed results
+/// (`[u32 count] { [u32 len] [bytes] }`). **Fail-fast**: an invalid item aborts
+/// the whole batch with an index-bearing error — unlike the bitset-style batch
+/// helpers, silently dropping a patch would risk silent data loss.
+#[napi]
+pub fn json_patch_batch_packed(docs: Uint8Array, patches: Uint8Array) -> Result<Buffer> {
+    let doc_items = unpack(docs.as_ref()).map_err(|e| Error::from_reason(e.to_string()))?;
+    let patch_items = unpack(patches.as_ref()).map_err(|e| Error::from_reason(e.to_string()))?;
+
+    if doc_items.len() != patch_items.len() {
+        return Err(Error::from_reason(format!(
+            "json patch batch: docs count {} != patches count {}",
+            doc_items.len(),
+            patch_items.len()
+        )));
+    }
+
+    if doc_items.is_empty() {
+        // Packed empty result: `[u32 count = 0]`.
+        return Ok(Buffer::from(vec![0u8; 4]));
+    }
+
+    let results = run_json_patch_batch(&doc_items, &patch_items)
+        .map_err(|e| Error::from_reason(e.to_string()))?;
+
+    let body: usize = results.iter().map(|result| result.len() + 4).sum();
+    let mut out = Vec::with_capacity(4 + body);
+    out.extend_from_slice(&(results.len() as u32).to_le_bytes());
+    for result in &results {
+        out.extend_from_slice(&(result.len() as u32).to_le_bytes());
+        out.extend_from_slice(result);
+    }
+    Ok(Buffer::from(out))
+}

package/rust/json/patch/engine.rs

@@ -0,0 +1,153 @@
+// rust/json/patch/engine.rs — bounded RFC 6902 apply + parallel packed batch.
+//
+// The napi-free, unit-testable core: `apply_json_patch_bytes` (bounded scalar
+// apply) and `run_json_patch_batch` (serial/rayon batch). The op semantics
+// live in `ops.rs`; the napi boundary is in `api.rs`.
+
+use crate::util::{should_parallelize, total_bytes};
+
+use super::ops::{apply_patch, parse_patch};
+
+/// Maximum accepted size of a single JSON document or patch (defense in depth
+/// before parsing). Generous; only adversarial inputs trip it.
+const MAX_JSON_PATCH_INPUT: usize = 64 * 1024 * 1024;
+
+/// Maximum serialized output size. A result guard: an oversized (e.g.
+/// `copy`-amplified) result is rejected rather than returned to the caller.
+const MAX_JSON_PATCH_OUTPUT: usize = 128 * 1024 * 1024;
+
+/// JSON Patch errors, rendered with stable, human-readable context.
+#[derive(Debug)]
+pub enum JsonPatchError {
+    /// The document bytes are not valid JSON.
+    InvalidDoc(String),
+    /// The patch bytes are not a valid RFC 6902 patch document.
+    InvalidPatch(String),
+    /// The patch could not be applied (test mismatch, missing path, type clash).
+    ApplyFailed(String),
+    /// An input or the serialized output exceeded the bounded-size guard.
+    TooLarge(&'static str, usize),
+    /// Output serialization failed (cannot happen for a valid `Value`).
+    Serialize(String),
+    /// Batch item `index` failed to apply.
+    BatchItem {
+        index: usize,
+        source: Box<JsonPatchError>,
+    },
+}
+
+impl std::fmt::Display for JsonPatchError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::InvalidDoc(e) => write!(f, "json patch: invalid document: {e}"),
+            Self::InvalidPatch(e) => write!(f, "json patch: invalid patch: {e}"),
+            Self::ApplyFailed(e) => write!(f, "json patch: apply failed: {e}"),
+            Self::TooLarge(kind, n) => {
+                write!(f, "json patch: {kind} size {n} exceeds maximum")
+            }
+            Self::Serialize(e) => write!(f, "json patch: serialize failed: {e}"),
+            Self::BatchItem { index, source } => {
+                write!(f, "json patch batch: item {index} failed: {source}")
+            }
+        }
+    }
+}
+
+/// Apply `patch` to `doc` (RFC 6902) and return the serialized result.
+///
+/// Pure-Rust core — no napi types, fully unit-testable. Tests exercise the size
+/// guards via [`apply_json_patch_bytes_limited`] with small limits.
+pub fn apply_json_patch_bytes(
+    doc: &[u8],
+    patch: &[u8],
+) -> std::result::Result<Vec<u8>, JsonPatchError> {
+    apply_json_patch_bytes_limited(doc, patch, MAX_JSON_PATCH_INPUT, MAX_JSON_PATCH_OUTPUT)
+}
+
+pub(crate) fn apply_json_patch_bytes_limited(
+    doc: &[u8],
+    patch: &[u8],
+    max_input: usize,
+    max_output: usize,
+) -> std::result::Result<Vec<u8>, JsonPatchError> {
+    if doc.len() > max_input {
+        return Err(JsonPatchError::TooLarge("document", doc.len()));
+    }
+    if patch.len() > max_input {
+        return Err(JsonPatchError::TooLarge("patch", patch.len()));
+    }
+
+    let mut doc_val: sonic_rs::Value =
+        sonic_rs::from_slice(doc).map_err(|e| JsonPatchError::InvalidDoc(e.to_string()))?;
+
+    let ops = parse_patch(patch)?;
+    apply_patch(&mut doc_val, &ops).map_err(JsonPatchError::ApplyFailed)?;
+
+    // The overwhelmingly common case is an in-place field/array edit, which
+    // keeps the result ≈ the document size; grow only if the patch expands it.
+    // The output is then bounded as a *result guard*: the sonic DOM has
+    // already been (potentially `copy`-amplified), so refusing oversized
+    // output prevents handing a giant buffer back to the caller.
+    let mut out = Vec::with_capacity(doc.len().min(max_output));
+    sonic_rs::to_writer(&mut out, &doc_val)
+        .map_err(|e| JsonPatchError::Serialize(e.to_string()))?;
+
+    if out.len() > max_output {
+        return Err(JsonPatchError::TooLarge("output", out.len()));
+    }
+    Ok(out)
+}
+
+/// The first failure encountered while processing a batch.
+struct BatchFailure {
+    index: usize,
+    source: JsonPatchError,
+}
+
+/// Pure-Rust batch core: zip `docs` with `patches` and apply each pair.
+///
+/// Parallel via rayon when the workload justifies it; otherwise serial and
+/// deterministic (first error wins). Errors are index-bearing
+/// ([`JsonPatchError::BatchItem`]). Successful results are order-preserving.
+pub fn run_json_patch_batch(
+    docs: &[&[u8]],
+    patches: &[&[u8]],
+) -> std::result::Result<Vec<Vec<u8>>, JsonPatchError> {
+    debug_assert_eq!(docs.len(), patches.len());
+
+    if should_parallelize(docs.len(), total_bytes(docs)) {
+        use rayon::prelude::*;
+        let results: std::result::Result<Vec<Vec<u8>>, BatchFailure> = docs
+            .par_iter()
+            .zip(patches.par_iter())
+            .enumerate()
+            .map(
+                |(index, (doc, patch))| match apply_json_patch_bytes(doc, patch) {
+                    Ok(result) => Ok(result),
+                    Err(source) => Err(BatchFailure { index, source }),
+                },
+            )
+            .collect();
+        match results {
+            Ok(results) => Ok(results),
+            Err(BatchFailure { index, source }) => Err(JsonPatchError::BatchItem {
+                index,
+                source: Box::new(source),
+            }),
+        }
+    } else {
+        let mut results = Vec::with_capacity(docs.len());
+        for (index, (doc, patch)) in docs.iter().zip(patches.iter()).enumerate() {
+            match apply_json_patch_bytes(doc, patch) {
+                Ok(result) => results.push(result),
+                Err(source) => {
+                    return Err(JsonPatchError::BatchItem {
+                        index,
+                        source: Box::new(source),
+                    })
+                }
+            }
+        }
+        Ok(results)
+    }
+}

package/rust/json/patch/mod.rs

@@ -0,0 +1,47 @@
+//! RFC 6902 JSON Patch — bounded scalar apply + parallel packed batch.
+//!
+//! Pure-Rust core (`apply_json_patch_bytes`, `run_json_patch_batch`) is
+//! napi-free and unit-testable; the `#[napi]` entry points (`json_patch`,
+//! `json_patch_batch_packed`) are thin boundaries that map `JsonPatchError` →
+//! napi `Error` with stable context.
+//!
+//! Folder layout:
+//!   - `pointer.rs` — RFC 6901 JSON Pointer parsing (escape rules).
+//!   - `ops.rs`     — patch document parsing + RFC 6902 apply over sonic Value.
+//!   - `engine.rs`  — bounded scalar apply + serial/rayon packed batch.
+//!   - `api.rs`     — napi boundary.
+//!   - `tests.rs`   — unit tests.
+//!
+//! **Sonic engine**: the `json-patch` crate is hardwired to `serde_json::Value`
+//! (a per-key heap `String` DOM). This module implements RFC 6902 directly over
+//! `sonic_rs::Value` (compact tagged nodes, no per-key heap `String`), so the
+//! patch path no longer builds a `serde_json` DOM. RFC 6901 pointer escapes
+//! (`~0`→`~`, `~1`→`/`) are validated eagerly at patch parse (bad escapes →
+//! `InvalidPatch`, matching the crate's eager deserialization). The `test` op
+//! uses sonic's `Value ==`, which has serde_json-identical number semantics
+//! (`1 != 1.0`), preserving the crate's behavior.
+//!
+//! Hardening / efficiency notes:
+//! - **Bounded sizes** — inputs are capped (`MAX_JSON_PATCH_INPUT`) and the
+//!   result is capped (`MAX_JSON_PATCH_OUTPUT`). A malicious chain of
+//!   RFC 6902 `copy` ops duplicates subtrees and can grow the output
+//!   exponentially relative to the input; the cap refuses to hand such output
+//!   back to the caller.
+//! - **Capacity** — the common in-place field/array edit keeps the result ≈ the
+//!   document size, so serialization starts at `doc.len()` and grows only when
+//!   a patch genuinely expands the document (no 2× over-allocation for
+//!   `test`/`remove`-heavy patches).
+//! - **Scalability** — `json_patch_batch_packed` zips two packed buffers and
+//!   applies patches in parallel via rayon when the workload justifies it
+//!   (`should_parallelize`), staying serial and deterministic otherwise.
+
+mod api;
+mod engine;
+mod ops;
+mod pointer;
+
+#[cfg(test)]
+mod tests;
+
+pub use self::api::{json_patch, json_patch_batch_packed};
+pub use self::engine::{apply_json_patch_bytes, run_json_patch_batch, JsonPatchError};