cipherstash-client 0.42.0

//! Searchable encryption for JSON values.
//!
//! This module implements the indexing scheme used by CipherStash for encrypted JSON
//! columns. Each leaf in a JSON document is flattened into a path/value pair, and
//! every path is tokenized with a keyed MAC so that paths and values can be matched
//! under encryption without revealing the underlying JSON.
//!
//! The resulting structures support three styles of query against an encrypted column:
//!
//! - **Containment** (`@>`): generate an [`SteQueryVec`] via [`JsonIndexer::query`] and
//!   compare it against a stored [`SteVec`].
//! - **Path projection** (`->`/`->>`): generate a [`TokenizedSelector`] via
//!   [`JsonIndexer::generate_selector`] to look up the ciphertext at a given JSON path.
//! - **Exact-match equality** (`=` on a value at a path): generate the
//!   value-inclusive [`TokenizedSelector`] via [`JsonIndexer::generate_value_selector`]
//!   (query op `SteVecValueSelector`); its presence in the stored `sv` is the match.
//!   This single-selector operation accepts scalar values only; objects and arrays
//!   use containment. High-precision decimal exactness is subject to the numeric
//!   caveat documented on [`JsonIndexer::generate_value_selector`].
//! - **Term comparison** (`<`, `<=`, `>`, `>=`): generate an [`EncryptedSteVecTerm`] via the
//!   `SteVecTerm` query op to compare a leaf value against a query value (uses OPE
//!   in the default `Compat` mode, ORE in `Standard` mode). The orderable encoding
//!   is deliberately lossy (f64 rounding, string collation), so it serves ordering,
//!   not equality.
//!
//! See [`JsonIndexer`] for the main entry point, and the [`ste_vec`] module for
//! the encrypted-document structure and its on-the-wire format (the
//! per-document key header, selector-derived entry nonces, and the value-entry
//! sentinel).

mod path_values;
mod prefix_mac;
mod ste_vec;

use path_values::{flatmap_json, PathValue};
// use path_values::{PathTargets, PathValue};
use prefix_mac::{Blake3PrefixMac, HmacSha256PrefixMac, NewPrefixMac, PrefixMac, UpdatePrefixMac};
use serde_json::Value;
use ste_vec::{
    priv_state::{
        dispatch_mode, tokenize_value_selector, OrderableTerm, TermBuilder, WithTermBuilder,
    },
    StePlaintextVec,
};
use zerokms_protocol::cipherstash_config::column;
use zerokms_protocol::cipherstash_config::column::{ArrayIndexMode, SteVecMode};

use super::{
    builder::StorageBuilder,
    indexer::{IndexerInit, Indexes, IndexesForQuery, QueryOp},
    IndexTerm, Plaintext, QueryBuilder, TryFromPlaintext,
};
use crate::{
    ejsonpath::Selector,
    encryption::{text::TokenFilter, EncryptionError},
    zerokms::IndexKey,
};

// Exports
pub use ste_vec::{
    is_value_entry_sentinel, EncryptedEntry, EncryptedSteVecTerm, SteQueryVec, SteVec,
    SteVecPendingEncryption, TokenizedSelector, VALUE_ENTRY_SENTINEL,
};

/// Configuration for a [`JsonIndexer`].
///
/// `JsonIndexerOptions` controls how a JSON document is tokenized and indexed.
/// It can be constructed directly, or derived from a column configuration via
/// `TryFrom<&column::IndexType>`.
#[derive(Default, Debug)]
pub struct JsonIndexerOptions {
    /// Domain-separation prefix mixed into the keyed MAC used to tokenize JSON
    /// paths and values.
    ///
    /// Two indexers with the same key but different prefixes will produce
    /// disjoint token spaces, so the prefix must match between the indexing
    /// side and the query side for results to be comparable. In practice this
    /// is set to a stable column identifier (e.g. `"cs_ste_vec_v1"`).
    pub prefix: String,
    /// Case-normalization filters applied to every string leaf before indexing.
    ///
    /// `Upcase` and `Downcase` are supported for intentionally
    /// case-insensitive JSON matching. `Stemmer` and `Stop` are lexical search
    /// filters and are rejected for JSON indexes because they change or remove
    /// JSON values rather than normalize their case.
    pub term_filters: Vec<TokenFilter>,
    /// Controls which selectors are emitted for array entries.
    ///
    /// See [`ArrayIndexMode`] — `ALL` emits item, positional, and wildcard
    /// selectors for each element; narrower modes (`ITEM`, `POSITION`,
    /// `WILDCARD`, `NONE`) reduce index size at the cost of which query
    /// shapes are supported.
    pub array_index_mode: ArrayIndexMode,
    /// Selects the STE-vec encoding scheme used by this indexer.
    ///
    /// See [`SteVecMode`] — the mode selects the orderable-term primitive:
    /// `Compat` (the default) uses OPE, `Standard` uses ORE. Selectors are
    /// always Blake3-keyed and term-side MACs are always HMAC-SHA256 in both
    /// modes. Indexes produced under different modes are not cross-comparable,
    /// so the indexing side and the query side must agree on the mode for
    /// results to match.
    pub mode: SteVecMode,
}

impl IndexerInit for JsonIndexer {
    type Args = JsonIndexerOptions;
    type Error = EncryptionError;

    fn try_init<A>(args: A) -> Result<Self, Self::Error>
    where
        Self::Args: TryFrom<A, Error = Self::Error>,
    {
        let args = JsonIndexerOptions::try_from(args)?;
        args.validate_term_filters()?;
        Ok(Self::new(args))
    }
}

impl<'k> Indexes<'k, Plaintext> for JsonIndexer {
    fn index(
        &self,
        mut builder: StorageBuilder<'k, Plaintext>,
    ) -> Result<StorageBuilder<'k, Plaintext>, EncryptionError> {
        let json = builder
            .plaintext()
            .clone_as_json()
            .ok_or(EncryptionError::IndexingError(
                "Failed to convert plaintext to JSON".to_string(),
            ))?;
        let index_key = builder.index_key();

        // TODO: consume value and builder together for the index method (should avoid the clone)
        let ste_vec_pending_encryption = self.index(json, index_key)?;
        builder.set_ste_vec(ste_vec_pending_encryption); // Probably should be try_add_ste_vec

        Ok(builder)
    }
}

impl<C> IndexesForQuery<Plaintext, C> for JsonIndexer {
    fn query_index(
        &self,
        builder: QueryBuilder<Plaintext, C>,
        op: QueryOp,
    ) -> Result<IndexTerm, EncryptionError> {
        self.validate_term_filters()?;
        let index_key = builder.index_key();
        match op {
            QueryOp::Default => {
                let json =
                    builder
                        .plaintext()
                        .clone_as_json()
                        .ok_or(EncryptionError::IndexingError(
                            "Failed to convert plaintext to JSON".to_string(),
                        ))?;
                self.query(json, index_key).map(IndexTerm::SteQueryVec)
            }
            QueryOp::SteVecSelector => {
                let path: String = String::try_from_plaintext(builder.plaintext().clone())?;
                let selector = Selector::parse(&path)?;
                let tokenized_selector = self.generate_selector(selector, index_key);
                Ok(IndexTerm::SteVecSelector(tokenized_selector))
            }
            QueryOp::SteVecValueSelector => {
                let json =
                    builder
                        .plaintext()
                        .clone_as_json()
                        .ok_or(EncryptionError::IndexingError(
                            "Failed to convert plaintext to JSON".to_string(),
                        ))?;
                let (path, value) = parse_value_selector_input(&json)?;
                let selector = Selector::parse(path)?;
                let tokenized_selector =
                    self.generate_value_selector(selector, value, index_key)?;
                Ok(IndexTerm::SteVecValueSelector(tokenized_selector))
            }
            QueryOp::SteVecTerm => self
                .generate_term(builder.plaintext(), index_key)
                .map(IndexTerm::SteVecTerm),
        }
    }
}

impl Default for JsonIndexer {
    fn default() -> Self {
        Self::new(Default::default())
    }
}

impl TryFrom<&column::IndexType> for JsonIndexerOptions {
    type Error = EncryptionError;

    fn try_from(value: &column::IndexType) -> Result<Self, Self::Error> {
        match value {
            column::IndexType::SteVec {
                prefix,
                term_filters,
                array_index_mode,
                mode,
            } => {
                let options = Self {
                    prefix: prefix.clone(),
                    term_filters: term_filters.iter().copied().map(From::from).collect(),
                    array_index_mode: *array_index_mode,
                    mode: *mode,
                };
                options.validate_term_filters()?;
                Ok(options)
            }
            _ => Err(EncryptionError::IndexingError(
                "JsonIndexerOptions can only be created from a SteVec index configuration"
                    .to_string(),
            )),
        }
    }
}

impl JsonIndexerOptions {
    fn validate_term_filters(&self) -> Result<(), EncryptionError> {
        validate_json_term_filters(&self.term_filters)
    }
}

fn validate_json_term_filters(term_filters: &[TokenFilter]) -> Result<(), EncryptionError> {
    if let Some(filter) = term_filters
        .iter()
        .find(|filter| matches!(filter, TokenFilter::Stemmer | TokenFilter::Stop))
    {
        return Err(EncryptionError::CreateIndexError(format!(
            "{filter:?} is not supported by JsonIndexer; Stemmer and Stop are lexical search filters and may only be used with a match index"
        )));
    }
    Ok(())
}

/// Indexer for searchable encryption of JSON documents.
///
/// A `JsonIndexer` flattens a JSON value into path/value pairs, applies any
/// configured case normalization, and produces an [`SteVecPendingEncryption`] ready
/// to be sealed with a data key. The same indexer (with the same key and
/// prefix) is used on the query side to produce [`SteQueryVec`],
/// [`TokenizedSelector`], and [`EncryptedSteVecTerm`] values that match the
/// stored index.
///
/// Construct one with [`JsonIndexer::new`] from [`JsonIndexerOptions`], or use
/// [`Default`] for an indexer with an empty prefix, no term filters, and
/// `ArrayIndexMode::ALL`.
pub struct JsonIndexer {
    prefix: Vec<u8>,
    term_filters: Vec<TokenFilter>,
    array_index_mode: ArrayIndexMode,
    mode: SteVecMode,
}

impl JsonIndexer {
    /// Create a new indexer from the given options.
    pub fn new(opts: JsonIndexerOptions) -> Self {
        Self {
            prefix: Vec::from(opts.prefix.as_bytes()),
            term_filters: opts.term_filters,
            array_index_mode: opts.array_index_mode,
            mode: opts.mode,
        }
    }

    fn validate_term_filters(&self) -> Result<(), EncryptionError> {
        validate_json_term_filters(&self.term_filters)
    }

    /// Generates an [`SteVecPendingEncryption`] from a JSON value.
    /// This represents the indexed form of the JSON, but with source plaintexts still present.
    /// This can then be encrypted into a final [`SteVec`] using a [`crate::zerokms::DataKeyWithTag`] with [`SteVecPendingEncryption::encrypt`].
    ///
    /// Once encrypted, the resulting [`SteVec`] can be stored in a database column or some other storage.
    ///
    /// # Example
    /// ```
    /// use cipherstash_client::encryption::{JsonIndexer, JsonIndexerOptions, SteVec};
    /// use cipherstash_client::zerokms::{DataKey, DataKeyWithTag, IndexKey};
    /// use zerokms_protocol::cipherstash_config::column::ArrayIndexMode;
    /// use serde_json::Value;
    ///
    /// let opts = JsonIndexerOptions {
    ///     prefix: "foo".to_string(),
    ///     term_filters: Vec::new(),
    ///     array_index_mode: ArrayIndexMode::ALL,
    ///     ..Default::default()
    /// };
    /// let indexer = JsonIndexer::new(opts);
    /// let index_key = IndexKey::from([0; 32]);
    /// let json = serde_json::json!({ "a": 1, "b": { "c": 2 } });
    /// let pending_encryption = indexer.index(json, &index_key).unwrap();
    ///
    /// // Encrypt the pending entries with a DataKeyWithTag
    /// // CAUTION: Always use a data key generated by Zerokms for production use.
    /// // Attempting to generate your own keys will result in invalid tags and decryption failures.
    /// let key = DataKey {
    ///     iv: [0; 16],
    ///     key: [0; 32],
    /// };
    /// let key_with_tag = DataKeyWithTag { key, tag: vec![0, 1, 2], decryption_policy: None };
    /// let ste_vec: SteVec<16> = pending_encryption
    ///     .encrypt(key_with_tag, "table/column", None)
    ///     .unwrap();
    /// ```
    ///
    pub fn index(
        &self,
        json: Value,
        index_key: &IndexKey,
    ) -> Result<SteVecPendingEncryption<16>, EncryptionError> {
        self.validate_term_filters()?;
        // Mode dispatch picks the orderable-term primitive (OPE for Compat,
        // ORE for Standard) via the TermBuilder type parameter. `dispatch_mode`
        // is the single runtime-mode -> TermBuilder site shared with
        // `generate_term`, so a column can never emit the wrong wire key for its
        // mode. Selectors are ALWAYS Blake3 and term-side MACs are ALWAYS
        // HMAC-SHA256 — these don't vary by mode.
        struct IndexWith<'a> {
            indexer: &'a JsonIndexer,
            json: Value,
            index_key: &'a IndexKey,
        }
        impl WithTermBuilder for IndexWith<'_> {
            type Output = Result<SteVecPendingEncryption<16>, EncryptionError>;
            fn call<TB: TermBuilder>(self) -> Self::Output {
                self.indexer.index_with::<TB>(self.json, self.index_key)
            }
        }
        dispatch_mode(
            self.mode,
            IndexWith {
                indexer: self,
                json,
                index_key,
            },
        )
    }

    fn index_with<TB>(
        &self,
        json: Value,
        index_key: &IndexKey,
    ) -> Result<SteVecPendingEncryption<16>, EncryptionError>
    where
        TB: TermBuilder,
    {
        let mut selector_macca = Blake3PrefixMac::new_prefix_mac(index_key, self.prefix.clone());
        let mut term_macca = HmacSha256PrefixMac::new_prefix_mac(index_key, self.prefix.clone());

        let processed = self.preprocess(json);
        let path_values = flatmap_json(&processed, self.array_index_mode, |path, value| {
            PathValue(path.to_vec(), value)
        });

        StePlaintextVec::from_iter(path_values)
            .index::<16, TB, _, _>(&mut selector_macca, &mut term_macca)
    }

    /// Applies configured case normalization to JSON string leaves recursively.
    ///
    /// Public indexing/query entry points validate that only `Upcase` and
    /// `Downcase` are configured before reaching this transformation.
    fn preprocess(&self, value: Value) -> Value {
        match value {
            Value::String(s) => {
                let mapped = self
                    .term_filters
                    .iter()
                    .try_fold(s, |val, filter| filter.process_single(val));

                // Supported JSON filters always return Some. Keep the fallback
                // defensive if a future filter is added without validation.
                mapped.map(Value::String).unwrap_or(Value::Null)
            }
            Value::Array(arr) => {
                let v: Vec<Value> = arr.into_iter().map(|v| self.preprocess(v)).collect();
                Value::Array(v)
            }
            Value::Object(obj) => {
                let m = obj
                    .into_iter()
                    .map(|(k, v)| (k, self.preprocess(v)))
                    .collect();
                Value::Object(m)
            }
            v => v,
        }
    }

    /// Generate an [`SteQueryVec`] from a JSON value.
    ///
    /// This is useful for building containment queries (e.g. `@>` operator in Postgres).
    /// For example, given an [`SteVec`] column `attrs`, an [`SteQueryVec`] generated from a plaintext JSON value.
    ///
    /// ```
    /// use cipherstash_client::encryption::{JsonIndexer, JsonIndexerOptions};
    /// use cipherstash_client::zerokms::IndexKey;
    /// use zerokms_protocol::cipherstash_config::column::ArrayIndexMode;
    ///
    /// let opts = JsonIndexerOptions {
    ///     prefix: "foo".to_string(),
    ///     term_filters: Vec::new(),
    ///     array_index_mode: ArrayIndexMode::ALL,
    ///     ..Default::default()
    /// };
    /// let indexer = JsonIndexer::new(opts);
    /// let index_key = IndexKey::from([0; 32]);
    /// let json = serde_json::json!({ "a": 1, "b": { "c": 2 } });
    /// let q = indexer.query(json, &index_key).unwrap();
    /// ```
    ///
    /// This can then be used in a query like:
    ///
    /// ```sql
    /// -- $1 is the query parameter, q
    /// -- Example: q = [["aaa...", "bbb..."], ["ccc...", "ddd..."]]
    /// SELECT * FROM table WHERE attrs @> $1;
    /// ```
    ///
    pub fn query(
        &self,
        json: Value,
        index_key: &IndexKey,
    ) -> Result<SteQueryVec<16>, EncryptionError> {
        self.index(json, index_key).map(SteQueryVec::from)
    }

    /// Generate a [`TokenizedSelector`] from a JSON path.
    /// This is useful for building queries that target specific paths in a JSON document.
    ///
    /// For example, given an [`SteVec`] column `attrs`, a [`TokenizedSelector`] generated from a JSON path.
    /// ```
    /// use cipherstash_client::encryption::{JsonIndexer, JsonIndexerOptions};
    /// use cipherstash_client::zerokms::IndexKey;
    /// use cipherstash_client::ejsonpath::Selector;
    /// use zerokms_protocol::cipherstash_config::column::ArrayIndexMode;
    ///
    /// let opts = JsonIndexerOptions { prefix: "foo".to_string(), term_filters: Vec::new(), array_index_mode: ArrayIndexMode::ALL, ..Default::default() };
    /// let indexer = JsonIndexer::new(opts);
    /// let index_key = IndexKey::from([0; 32]);
    /// let json = serde_json::json!({ "a": 1, "b": { "c": 2 } });
    /// let selector = Selector::parse("$.b.c").unwrap();
    /// let tokenized_selector = indexer.generate_selector(selector, &index_key);
    /// ```
    ///
    /// This can then be used in a query like:
    ///
    /// ```sql
    /// -- $1 is the tokenized selector
    /// -- Example: "4eb62fb72d75cb53a309b3b091923daf"
    /// SELECT jsonb_path_query(attrs, '$ ? (exists(@ ? (@[0] == $1)))[2]') FROM table;
    /// ```
    ///
    /// This is equivalent to the unencrypted query:
    ///
    /// ```sql
    /// SELECT attrs->'b'->'c' FROM table WHERE attrs->'b'->'c' IS NOT NULL;
    /// ```
    ///
    pub fn generate_selector(
        &self,
        selector: Selector,
        index_key: &IndexKey,
    ) -> TokenizedSelector<16> {
        // Selectors are ALWAYS produced via Blake3, regardless of SteVecMode.
        // The mode only controls the term-side primitive (ORE vs OPE for
        // orderable terms; both modes share HMAC for MAC terms). Distinguishing
        // selectors by mode would needlessly partition the token space.
        let mut macca = Blake3PrefixMac::new_prefix_mac(index_key, self.prefix.clone());
        selector.tokenize(&mut macca)
    }

    /// Build the **value-inclusive** [`TokenizedSelector`] for `value` at
    /// `selector` — the exact-match query operand. Its presence in a stored
    /// `sv` means "this exact value is at this path": storage emits the same
    /// selector for every node (see `ste_vec::priv_state::value_selector`),
    /// so the comparison is keyed-MAC equality per (path, scalar value), subject
    /// to the documented high-precision numeric caveat.
    ///
    /// Value-inclusive selectors are ALWAYS Blake3, like path selectors — the
    /// mode only controls the orderable term primitive.
    ///
    /// String values pass through the indexer's configured case normalization
    /// first — symmetric with storage, where entries are built from the
    /// preprocessed document — so a query for `"John"` against a
    /// `Downcase`-filtered column matches the stored `"john"` entry. Stemmer
    /// and Stop filters are rejected for JSON indexes because they alter JSON
    /// equality rather than normalize case.
    ///
    /// `value` must be a **scalar** (string, number, bool, or null). A single
    /// value selector is injective only for scalars: a container MACs only its
    /// structural tag (`MAP0{}` / `ARRY[]`) plus the path, so every object (or
    /// every array) at a path would collapse to one selector — a silent false
    /// positive on exact match. Objects and arrays are therefore rejected here;
    /// container matching goes through the flattened containment query
    /// ([`Self::query`]), not a single value selector.
    /// Numbers outside serde_json's exact integer representations currently
    /// canonicalize through `f64`; distinct high-precision PostgreSQL `numeric`
    /// values within one `f64` step can therefore over-match. Arbitrary-precision
    /// decimal canonicalization is not currently supported.
    pub fn generate_value_selector(
        &self,
        selector: Selector,
        value: &Value,
        index_key: &IndexKey,
    ) -> Result<TokenizedSelector<16>, EncryptionError> {
        self.validate_term_filters()?;
        if value.is_object() || value.is_array() {
            return Err(EncryptionError::InvalidValue(
                "SteVecValueSelector exact match requires a scalar value (string, \
                 number, bool, or null). Objects and arrays are not injective \
                 under a single value selector — use a containment query instead."
                    .to_string(),
            ));
        }
        let processed = self.preprocess(value.clone());
        let mut macca = Blake3PrefixMac::new_prefix_mac(index_key, self.prefix.clone());
        let path_token = selector.tokenize(&mut macca);
        Ok(tokenize_value_selector(&path_token, &processed, &mut macca))
    }

    /// Build an [`EncryptedSteVecTerm`] for a single plaintext leaf value.
    ///
    /// Used to construct the right-hand side of term-comparison queries
    /// (`=`, `<`, `>`) against a specific JSON path. The same prefix and
    /// index key must be used as for the stored index. The concrete
    /// [`EncryptedSteVecTerm`] variant is picked from `self.mode`: `Compat`
    /// yields `EncryptedSteVecTerm::Compat` (OPE), `Standard` yields
    /// `EncryptedSteVecTerm::Standard` (ORE).
    fn generate_term(
        &self,
        plaintext: &Plaintext,
        index_key: &IndexKey,
    ) -> Result<EncryptedSteVecTerm, EncryptionError> {
        // Term-side macca is ALWAYS HMAC-SHA256, regardless of mode. Mode only
        // chooses the orderable primitive (OPE for Compat, ORE for Standard),
        // routed through the same single `dispatch_mode` site as the storage
        // path — each builder can only construct its own matching
        // `EncryptedSteVecTerm` variant, so the term can never carry the wrong
        // wire key for the column's mode.
        let mut macca = HmacSha256PrefixMac::new_prefix_mac(index_key, self.prefix.clone());
        let term = OrderableTerm::try_from(plaintext)?;

        struct BuildOrderable<'a, M> {
            term: OrderableTerm,
            macca: &'a mut M,
        }
        impl<M> WithTermBuilder for BuildOrderable<'_, M>
        where
            M: PrefixMac + UpdatePrefixMac<&'static str>,
        {
            type Output = Result<EncryptedSteVecTerm, EncryptionError>;
            fn call<TB: TermBuilder>(self) -> Self::Output {
                TB::orderable_term(self.term, self.macca)
            }
        }
        dispatch_mode(
            self.mode,
            BuildOrderable {
                term,
                macca: &mut macca,
            },
        )
    }
}

/// Splits the `SteVecValueSelector` input `{"path": <jsonpath>, "value": <json>}`
/// into its parts. Exactly these two keys are required — a missing or extra
/// key is an error, so a malformed operand fails loudly instead of silently
/// tokenizing the wrong thing.
fn parse_value_selector_input(json: &Value) -> Result<(&str, &Value), EncryptionError> {
    let obj = json.as_object().filter(|o| o.len() == 2);
    match (
        obj.and_then(|o| o.get("path")).and_then(Value::as_str),
        obj.and_then(|o| o.get("value")),
    ) {
        (Some(path), Some(value)) => Ok((path, value)),
        _ => Err(EncryptionError::IndexingError(
            "SteVecValueSelector expects {\"path\": <jsonpath string>, \"value\": <json value>}"
                .to_string(),
        )),
    }
}

#[cfg(test)]
mod tests {
    use super::{
        ste_vec::{
            priv_state::OrderableTerm, EncryptedEntry, EncryptedSteVecTerm, QueryEntry,
            SteQueryVec, TokenizedSelector,
        },
        SteVec,
    };
    use crate::{
        ejsonpath::Selector,
        encryption::{text::TokenFilter, EncryptionError, Plaintext},
        zerokms::{decrypt, DataKeyWithTag, IndexKey, RecordWithNonce},
    };
    use serde_json::{json, Value};
    use zerokms_protocol::cipherstash_config::column::SteVecMode;

    /// Simulates the built in `jsonb_array_elements` function in Postgres when applied to an SteVec.
    fn simulated_jsonb_array_elements(
        ste_vec: SteVec<16>,
    ) -> impl Iterator<Item = EncryptedEntry<16>> {
        ste_vec.into_iter()
    }

    /// Simulates the built in `@>` operator in Postgres when applied to an SteVec and a query.
    ///
    /// Equivalent to:
    ///
    /// ```sql
    /// select '[[1,2,3],[4,5,6]]'::jsonb @> '[[1,2],[4,5]]'::jsonb;
    /// ```
    ///
    /// Where 1 and 4 are the selectors and 2 and 5 are the terms.
    fn simulated_contains(ste_vec: SteVec<16>, query: SteQueryVec<16>) -> bool {
        // All query entries must be contained in the ste_vec
        query.0.iter().all(|query_entry| {
            ste_vec
                .entries
                .iter()
                .any(|ste_entry| ste_entry.contains(query_entry))
        })
    }

    fn simulated_cs_ste_term_v1(
        ste_vec: SteVec<16>,
        selector: TokenizedSelector<16>,
    ) -> EncryptedSteVecTerm {
        simulated_jsonb_array_elements(ste_vec)
            .find(|entry| entry.tokenized_selector == selector)
            .expect("Selector not found in SteVec")
            .term
            .expect("entry at selector carries an orderable term")
    }

    fn simulated_cs_ste_value_v1(
        ste_vec: SteVec<16>,
        selector: TokenizedSelector<16>,
    ) -> RecordWithNonce {
        let header = ste_vec.header().clone();
        let entry = simulated_jsonb_array_elements(ste_vec)
            .find(|entry| entry.tokenized_selector == selector)
            .unwrap();
        header.record_with_selector(entry.ciphertext, entry.tokenized_selector.as_bytes())
    }

    /// Gets _all_ matching values for a given selector and returns as an array (which could be empty)
    fn simulated_cs_ste_values_v1(
        ste_vec: SteVec<16>,
        selector: TokenizedSelector<16>,
    ) -> Vec<RecordWithNonce> {
        let header = ste_vec.header().clone();
        simulated_jsonb_array_elements(ste_vec)
            .filter(|entry| entry.tokenized_selector == selector)
            .map(|entry| {
                header.record_with_selector(entry.ciphertext, entry.tokenized_selector.as_bytes())
            })
            .collect()
    }

    /// Converts the ste_vec into a list of query entries suitable for use in containment queries.
    ///
    /// ```sql
    /// SELECT * FROM table WHERE cs_ste_vec_v1(attrs) @> cs_ste_query_v1(stvec);
    /// ```
    fn simulated_cs_ste_query_v1(ste_vec: SteVec<16>) -> SteQueryVec<16> {
        SteQueryVec(
            simulated_jsonb_array_elements(ste_vec)
                .map(|entry| QueryEntry(entry.tokenized_selector, entry.term))
                .collect(),
        )
    }

    // -- Test helpers --
    use zerokms_protocol::cipherstash_config::column::ArrayIndexMode;

    fn gen_stevec(json: Value) -> SteVec<16> {
        gen_stevec_with_term_filters(json, Vec::new())
    }

    fn gen_value_selector(path: &str, value: Value) -> TokenizedSelector<16> {
        gen_value_selector_with_term_filters(path, value, Vec::new())
    }

    fn gen_value_selector_with_term_filters(
        path: &str,
        value: Value,
        term_filters: Vec<TokenFilter>,
    ) -> TokenizedSelector<16> {
        try_gen_value_selector_with_term_filters(path, value, term_filters).unwrap()
    }

    fn try_gen_value_selector_with_term_filters(
        path: &str,
        value: Value,
        term_filters: Vec<TokenFilter>,
    ) -> Result<TokenizedSelector<16>, EncryptionError> {
        let index_key = IndexKey::from([0; 32]);
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters,
            array_index_mode: ArrayIndexMode::ALL,
            ..Default::default()
        });
        indexer.generate_value_selector(Selector::parse(path).unwrap(), &value, &index_key)
    }

    fn gen_query(json: Value) -> super::SteQueryVec<16> {
        let index_key = IndexKey::from([0; 32]);
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters: Vec::new(),
            array_index_mode: ArrayIndexMode::ALL,
            ..Default::default()
        });
        indexer.query(json, &index_key).unwrap()
    }

    fn stored_selectors(ste_vec: &SteVec<16>) -> Vec<TokenizedSelector<16>> {
        ste_vec
            .entries
            .iter()
            .map(|e| e.tokenized_selector)
            .collect()
    }

    fn gen_stevec_with_term_filters(json: Value, term_filters: Vec<TokenFilter>) -> SteVec<16> {
        gen_stevec_with_options(json, term_filters, ArrayIndexMode::ALL)
    }

    fn gen_stevec_with_options(
        json: Value,
        term_filters: Vec<TokenFilter>,
        array_index_mode: ArrayIndexMode,
    ) -> SteVec<16> {
        let index_key = IndexKey::from([0; 32]);
        let data_key = DataKeyWithTag::default();

        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters,
            array_index_mode,
            ..Default::default()
        });
        indexer
            .index(json, &index_key)
            .expect("Failed to index JSON")
            .encrypt(data_key, "test/descriptor", None)
            .expect("Encryption failed")
    }

    fn gen_selector(selector: Selector) -> TokenizedSelector<16> {
        let index_key = IndexKey::from([0; 32]);
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters: Vec::new(),
            array_index_mode: ArrayIndexMode::ALL,
            ..Default::default()
        });
        indexer.generate_selector(selector, &index_key)
    }

    fn gen_selector_with_mode(selector: Selector, mode: SteVecMode) -> TokenizedSelector<16> {
        let index_key = IndexKey::from([0; 32]);
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters: Vec::new(),
            array_index_mode: ArrayIndexMode::ALL,
            mode,
        });
        indexer.generate_selector(selector, &index_key)
    }

    fn gen_term(plaintext: impl Into<Plaintext>) -> EncryptedSteVecTerm {
        let plaintext: Plaintext = plaintext.into();
        let index_key = IndexKey::from([0; 32]);
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters: Vec::new(),
            array_index_mode: ArrayIndexMode::ALL,
            ..Default::default()
        });
        indexer
            .generate_term(&plaintext, &index_key)
            .expect("Failed to generate term")
    }

    fn gen_term_with_mode(
        plaintext: impl Into<Plaintext>,
        mode: SteVecMode,
    ) -> EncryptedSteVecTerm {
        let plaintext: Plaintext = plaintext.into();
        let index_key = IndexKey::from([0; 32]);
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters: Vec::new(),
            array_index_mode: ArrayIndexMode::ALL,
            mode,
        });
        indexer
            .generate_term(&plaintext, &index_key)
            .expect("Failed to generate term")
    }

    fn gen_stevec_with_mode(json: Value, mode: SteVecMode) -> SteVec<16> {
        let index_key = IndexKey::from([0; 32]);
        let data_key = DataKeyWithTag::default();
        let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
            prefix: "cs_ste_vec_v1".to_string(),
            term_filters: Vec::new(),
            array_index_mode: ArrayIndexMode::ALL,
            mode,
        });
        indexer
            .index(json, &index_key)
            .expect("Failed to index JSON")
            .encrypt(data_key, "test/descriptor", None)
            .expect("Encryption failed")
    }

    fn decrypt_as_json(ciphertext: RecordWithNonce) -> Value {
        let decrypted = decrypt(ciphertext, Default::default()).expect("Decryption failed");
        let plaintext = Plaintext::from_slice(&decrypted).expect("Plaintext to be valid");
        plaintext.clone_as_json().expect("Plaintext to be JSON")
    }

    fn decrypt_vec_as_json(ciphertext: Vec<RecordWithNonce>) -> Vec<Value> {
        ciphertext.into_iter().map(decrypt_as_json).collect()
    }

    /// `foo->bar` when there is only one result
    fn stabby_single(json: &Value, path: &str) -> Value {
        let ste_vec = gen_stevec(json.clone());
        let ciphertext =
            simulated_cs_ste_value_v1(ste_vec, gen_selector(Selector::parse(path).unwrap()));
        decrypt_as_json(ciphertext)
    }

    /// `foo->bar` when there are multiple results
    fn stabby_collection(json: &Value, path: &str) -> Vec<Value> {
        let ste_vec = gen_stevec(json.clone());
        let ciphertexts =
            simulated_cs_ste_values_v1(ste_vec, gen_selector(Selector::parse(path).unwrap()));
        decrypt_vec_as_json(ciphertexts)
    }

    /// Like [stabby_single] but returns an [EncryptedTerm] instead of decrypting a value
    fn stabby_single_term(json: &Value, path: &str) -> EncryptedSteVecTerm {
        let ste_vec = gen_stevec(json.clone());
        simulated_cs_ste_term_v1(ste_vec, gen_selector(Selector::parse(path).unwrap()))
    }

    fn sample_json() -> Value {
        json!({
            "name": "John",
            "age": 30,
            "cars": [
                "Ford",
                "BMW",
                "Fiat",
                { "Tesla": "Model S" }
            ]
        })
    }

    #[test]
    fn test_stabby_arrow() {
        let json = sample_json();

        assert_eq!(
            stabby_single(&json, "$.cars"),
            json!([
                "Ford",
                "BMW",
                "Fiat",
                { "Tesla": "Model S" }
            ])
        );

        assert_eq!(stabby_single(&json, "$.name"), json!("John"));
        assert_eq!(stabby_single(&json, "$.age"), json!(30));
        assert_eq!(stabby_single(&json, "$.cars[*].Tesla"), json!("Model S"));
    }

    #[test]
    fn test_stabby_arrow_nested_array_elems() {
        let json = json!({
            "name": "John",
            "age": 30,
            "cars": [
                "Ford",
                "BMW",
                "Fiat",
                { "Tesla": "Model S" }
            ]
        });

        let results = stabby_collection(&json, "$.cars[*]");
        assert_eq!(results.len(), 4);

        assert_eq!(results[0], json!("Ford"));
        assert_eq!(results[1], json!("BMW"));
        assert_eq!(results[2], json!("Fiat"));
        assert_eq!(results[3], json!({ "Tesla": "Model S" }));
    }

    /// Return the whole JSON object
    #[test]
    fn test_stabby_arrow_root() {
        let json = sample_json();

        assert_eq!(stabby_single(&json, "$"), json);
    }

    #[test]
    fn test_stabby_arrow_nested_map() {
        let json = json!({
            "name": "John",
            "attrs": {
                "age": 30,
                "cars": [
                    "Ford",
                    "BMW",
                    "Fiat",
                    { "Tesla": "Model S" }
                ]
            }
        });

        assert_eq!(
            stabby_single(&json, "$.attrs"),
            json!({
                "age": 30,
                "cars": [
                    "Ford",
                    "BMW",
                    "Fiat",
                    { "Tesla": "Model S" }
                ]
            })
        );

        assert_eq!(stabby_single(&json, "$.attrs.age"), json!(30));

        assert_eq!(
            stabby_single(&json, "$.attrs.cars[*].Tesla"),
            json!("Model S")
        );
    }

    #[test]
    fn test_containment() -> Result<(), Box<dyn std::error::Error>> {
        let stored = gen_stevec(json!({
            "name": "John",
            "age": 30,
            "cars": [
                "Ford",
                "BMW",
                "Fiat",
                { "Tesla": "Model S" }
            ]
        }));

        let query_param = gen_stevec(json!({
            "cars": [
                "Ford",
                "BMW",
                "Fiat",
                { "Tesla": "Model S" }
            ]
        }));

        let query = simulated_cs_ste_query_v1(query_param);
        assert!(simulated_contains(stored, query));

        Ok(())
    }

    #[test]
    fn test_containment_nested_array() -> Result<(), Box<dyn std::error::Error>> {
        let stored = gen_stevec(json!({
            "top": {
                "nested": ["a", "b", "c"]
            }
        }));

        let query_param = gen_stevec(json!({
            "top": {
                "nested": ["a"]
            }
        }));

        let query = simulated_cs_ste_query_v1(query_param);
        assert!(simulated_contains(stored, query));

        Ok(())
    }

    #[test]
    fn test_wildcard_array() -> Result<(), Box<dyn std::error::Error>> {
        let stored = gen_stevec(json!({
            "ary": ["a", "b", "c"]
        }));

        let path = "$.ary";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary = hex::encode(selector.as_bytes());

        let path = "$.ary[1]";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary_idx = hex::encode(selector.as_bytes());

        let path = "$.ary[*]";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary_wld = hex::encode(selector.as_bytes());

        let path = "$.ary[@]";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary_itm = hex::encode(selector.as_bytes());

        let selectors = stored
            .entries
            .iter()
            .map(|e| hex::encode(e.tokenized_selector.as_bytes()))
            .collect::<Vec<String>>();

        // Contains three items with array selector
        let items = selectors.iter().filter(|s| **s == ary).count();
        assert_eq!(items, 1);

        let items = selectors.iter().filter(|s| **s == ary_idx).count();
        assert_eq!(items, 1);

        let items = selectors.iter().filter(|s| **s == ary_wld).count();
        assert_eq!(items, 3);

        let items = selectors.iter().filter(|s| **s == ary_itm).count();
        assert_eq!(items, 3);

        // THIS IS USEFUL FOR DEBUGGING
        // LEFT HERE FOR FUTURE SELF
        // for e in stored {
        //     let t = hex::encode(e.tokenized_selector.as_bytes());

        //     let ty = match t {
        //         a if a == ary => "ary",
        //         a if a == ary_wld => "ary_wld",
        //         a if a == ary_idx => "ary_idx",
        //         a if a == ary_itm => "ary_itm",
        //         _ => "other",
        //     };
        //     println!("{:?}/{:?}", ty, e.parent_is_array);
        // }

        Ok(())
    }

    #[test]
    fn test_object_array() -> Result<(), Box<dyn std::error::Error>> {
        let stored = gen_stevec(json!({
            "ary": ["a", {"b": 1}]
        }));

        let path = "$.ary";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary = hex::encode(selector.as_bytes());

        let path = "$.ary[1]";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary_idx = hex::encode(selector.as_bytes());

        let path = "$.ary[*]";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary_wld = hex::encode(selector.as_bytes());

        let path = "$.ary[@]";
        let selector = Selector::parse(path).unwrap();
        let selector = gen_selector(selector);
        let ary_itm = hex::encode(selector.as_bytes());

        // let selectors = stored
        //     .0
        //     .iter()
        //     .map(|e| hex::encode(e.tokenized_selector.as_bytes()))
        //     .collect::<Vec<String>>();

        // // Contains three items with array selector
        // let items = selectors.iter().filter(|s| **s == ary).count();
        // assert_eq!(items, 1);

        // let items = selectors.iter().filter(|s| **s == ary_idx).count();
        // assert_eq!(items, 1);

        // let items = selectors.iter().filter(|s| **s == ary_wld).count();
        // assert_eq!(items, 3);

        // let items = selectors.iter().filter(|s| **s == ary_itm).count();
        // assert_eq!(items, 3);

        // THIS IS USEFUL FOR DEBUGGING
        // LEFT HERE FOR FUTURE SELF
        for e in stored {
            let t = hex::encode(e.tokenized_selector.as_bytes());

            let ty = match t {
                a if a == ary => "ary",
                a if a == ary_wld => "ary_wld",
                a if a == ary_idx => "ary_idx",
                a if a == ary_itm => "ary_itm",
                _ => "other",
            };
            println!("{:?}/{:?}", ty, e.parent_is_array);
        }

        Ok(())
    }

    #[test]
    fn test_containment_only_top_level_key() -> Result<(), Box<dyn std::error::Error>> {
        let stored = gen_stevec(json!({
            "top": {
                "nested": ["a", "b", "c"]
            }
        }));

        let query_param = gen_stevec(json!({
            "top": {}
        }));

        let query = simulated_cs_ste_query_v1(query_param);
        assert!(simulated_contains(stored, query));

        Ok(())
    }

    /// Equivalent to:
    ///
    /// Simulates:
    ///
    /// ```sql
    /// SELECT * FROM table WHERE cs_ste_value_v1('$.name') = '<encrypted-value>';
    /// ```
    ///
    /// ```sql
    /// SELECT * FROM table WHERE attrs->'name' = 'John';
    /// ```
    #[test]
    fn test_stabby_arrow_term_compare_string() {
        let json = sample_json();

        assert_eq!(stabby_single_term(&json, "$.name"), gen_term("John"));
        assert_eq!(
            stabby_single_term(&json, "$.cars[*].Tesla"),
            gen_term("Model S")
        );

        // Not equal
        assert_ne!(stabby_single_term(&json, "$.name"), gen_term("Wrong"));
    }

    /// Equivalent to:
    /// JSON that has been pre-processed with a downcase filter on all string leaf nodes.
    #[test]
    fn test_stabby_arrow_term_compare_string_case_insensitive() {
        let json = json!({
            "name": "John",
            "b": [1, 2, 3]
        });
        let ste_vec = gen_stevec_with_term_filters(json, vec![TokenFilter::Downcase]);
        let test_term =
            simulated_cs_ste_term_v1(ste_vec, gen_selector(Selector::parse("$.name").unwrap()));
        // Matches lowercased term
        assert_eq!(test_term, gen_term("john"));

        // Does not match original case or other cases
        assert_ne!(test_term, gen_term("John"));
        assert_ne!(test_term, gen_term("JOHN"));
    }

    /// Equivalent to:
    ///
    /// Simulates:
    ///
    /// ```sql
    /// SELECT * FROM table WHERE cs_ste_value_v1('$.age') > '<encrypted-value>';
    /// ```
    ///
    /// ```sql
    /// SELECT * FROM table WHERE attrs->'age' > 10;
    /// ```
    #[test]
    fn test_stabby_arrow_term_compare_num() {
        let json = sample_json();

        // TODO: These tests only work for f64 values (not integers for some reason)
        assert!(stabby_single_term(&json, "$.age") > gen_term(10_f64));
        assert!(stabby_single_term(&json, "$.age") == gen_term(30_f64));
        assert!(stabby_single_term(&json, "$.age") < gen_term(40_f64));
    }

    /// Mirror of [`test_containment`] for `SteVecMode::Standard`: a query-side
    /// `SteVec` built from a subset of the stored document must round-trip
    /// through `simulated_cs_ste_query_v1` and report as contained. Exercises
    /// `Indexes` end-to-end in Standard mode.
    #[test]
    fn test_standard_containment_basic() {
        let stored = gen_stevec_with_mode(json!({"name": "John", "age": 30}), SteVecMode::Standard);
        let query_param = gen_stevec_with_mode(json!({"name": "John"}), SteVecMode::Standard);
        let query = simulated_cs_ste_query_v1(query_param);
        assert!(simulated_contains(stored, query));
    }

    /// Mirror of [`test_stabby_arrow`] for `SteVecMode::Standard`: looking up a
    /// path-encoded selector on the stored vector must return the leaf
    /// ciphertext that decrypts back to the original JSON value. Exercises
    /// `IndexesForQuery::SteVecSelector` in Standard mode.
    #[test]
    fn test_standard_stabby_arrow_selector_lookup() {
        let json = json!({"name": "John", "age": 30});
        let ste_vec = gen_stevec_with_mode(json.clone(), SteVecMode::Standard);

        let path = "$.name";
        let selector = gen_selector_with_mode(Selector::parse(path).unwrap(), SteVecMode::Standard);
        let ciphertext = simulated_cs_ste_value_v1(ste_vec, selector);
        assert_eq!(decrypt_as_json(ciphertext), json!("John"));
    }

    /// Mirror of [`test_stabby_arrow_term_compare_num`] for the default
    /// `SteVecMode::Compat` (OPE). The stored term at `$.age` is encoded via
    /// `OrderableTerm::build_compat` (numeric `u64` through CLLW OPE with a
    /// type-tag bit prepended to the plaintext); this test pins that the
    /// resulting lexicographic byte ordering of the `Ope` ciphertext preserves
    /// the numeric ordering of f64 plaintexts.
    #[test]
    fn test_compat_term_comparison_ordering() {
        let json = json!({"age": 30});
        let ste_vec = gen_stevec_with_mode(json.clone(), SteVecMode::Compat);
        let selector =
            gen_selector_with_mode(Selector::parse("$.age").unwrap(), SteVecMode::Compat);
        let term_at_path = simulated_cs_ste_term_v1(ste_vec, selector);

        // Compat::Ope ordering is lexicographic byte comparison of the
        // tagged-plaintext OPE ciphertext.
        assert!(term_at_path > gen_term_with_mode(10_f64, SteVecMode::Compat));
        assert!(term_at_path == gen_term_with_mode(30_f64, SteVecMode::Compat));
        assert!(term_at_path < gen_term_with_mode(40_f64, SteVecMode::Compat));
    }

    /// Domain-separation check for `Compat::Ope` on real indexer output: a
    /// numeric term and a string term must never compare equal, and every
    /// numeric term must sort strictly before every string term. This holds
    /// because `OrderableTerm` prepends a type-tag bit (`0` numeric, `1`
    /// string) to the plaintext bit stream before CLLW OPE — every numeric
    /// ciphertext therefore sorts below every string ciphertext, regardless
    /// of payload magnitude.
    #[test]
    fn test_compat_ope_number_and_string_domains_are_separated() {
        let numbers: Vec<EncryptedSteVecTerm> = [-1.0e300_f64, -1.0, 0.0, 30.0, 1.0e300]
            .into_iter()
            .map(gen_term)
            .collect();
        let strings: Vec<EncryptedSteVecTerm> = ["a", "John", "zzzzzzzz", "\u{0}", "\u{0}\u{0}"]
            .into_iter()
            .map(gen_term)
            .collect();

        for n in &numbers {
            for s in &strings {
                assert!(
                    n < s,
                    "every numeric Ope term must sort before every string Ope term"
                );
                assert_ne!(
                    n, s,
                    "numeric and string Ope terms must never compare equal"
                );
            }
        }
    }

    /// Hand-rolled f64 corpus exercising edges where the orderable encoding
    /// (sign-bit handling) is most likely to break: cross-sign pairs, exact
    /// zero, infinities, subnormals, and very large magnitudes. Quickcheck's
    /// random generator covers the middle of the distribution but is unlikely
    /// to hit these exact values often, so they're pinned explicitly.
    ///
    /// Exercises `Compat` mode (OPE). The contract under test is
    /// `partial_cmp` semantics: `+0.0` and `-0.0` are Equal (IEEE 754), and
    /// NaN is excluded. `total_cmp` would distinguish `+0.0` from `-0.0` at
    /// the bit level, but the orderable encoding intentionally collapses them
    /// — matching what range queries over numeric data want.
    #[test]
    fn test_compat_ope_preserves_f64_ordering_edge_cases() {
        let corpus: &[f64] = &[
            f64::NEG_INFINITY,
            f64::MIN,
            -1.0e300,
            -1.0,
            -f64::MIN_POSITIVE,
            -0.0,
            0.0,
            f64::MIN_POSITIVE,
            1.0,
            1.0e300,
            f64::MAX,
            f64::INFINITY,
        ];

        for (i, &a) in corpus.iter().enumerate() {
            for &b in &corpus[i..] {
                let ope_a = gen_term_with_mode(a, SteVecMode::Compat);
                let ope_b = gen_term_with_mode(b, SteVecMode::Compat);

                let original = a
                    .partial_cmp(&b)
                    .expect("non-NaN f64 partial_cmp is defined");
                let encrypted = ope_a
                    .partial_cmp(&ope_b)
                    .expect("Compat::Ope terms must be comparable");

                assert_eq!(
                    original, encrypted,
                    "OPE ordering disagrees with f64::partial_cmp for a={a}, b={b}: \
                     f64 says {original:?}, OPE says {encrypted:?}"
                );
            }
        }
    }

    quickcheck::quickcheck! {
        /// For every non-NaN f64 pair, `Compat`-mode OPE ciphertext
        /// order must agree with `f64::partial_cmp` on the originals. NaN is
        /// discarded because IEEE 754 doesn't define an order on it.
        fn prop_compat_ope_preserves_f64_ordering(a: f64, b: f64) -> quickcheck::TestResult {
            if a.is_nan() || b.is_nan() {
                return quickcheck::TestResult::discard();
            }
            let ope_a = gen_term_with_mode(a, SteVecMode::Compat);
            let ope_b = gen_term_with_mode(b, SteVecMode::Compat);
            let original = a
                .partial_cmp(&b)
                .expect("non-NaN f64 partial_cmp is defined");
            let encrypted = match ope_a.partial_cmp(&ope_b) {
                Some(o) => o,
                None => return quickcheck::TestResult::failed(),
            };
            quickcheck::TestResult::from_bool(original == encrypted)
        }
    }

    /// Every term emitted by `JsonIndexer` in `Compat` mode — both
    /// query-side terms produced by `generate_term` and stored terms produced
    /// by `index` — must be wrapped in the `EncryptedSteVecTerm::Compat`
    /// variant, and Compat orderable terms are OPE-based: numbers and strings
    /// both collapse into the single `Ope` variant, separated by a domain-tag
    /// byte. On-disk payloads and downstream EQL consumers depend on this
    /// invariant.
    #[test]
    fn test_json_indexer_emits_compat_term_variants() {
        // generate_term: f64 plaintext → Compat::Ope
        assert!(
            matches!(
                gen_term_with_mode(42_f64, SteVecMode::Compat),
                EncryptedSteVecTerm::Compat { .. }
            ),
            "expected Compat::Ope for f64 plaintext"
        );

        // generate_term: string plaintext → Compat::Ope
        assert!(
            matches!(
                gen_term_with_mode("hello", SteVecMode::Compat),
                EncryptedSteVecTerm::Compat { .. }
            ),
            "expected Compat::Ope for string plaintext"
        );

        // index: a JSON document covering every leaf kind. Every resulting
        // entry must use a Compat term, and we must observe both Compat
        // subvariants (Mac for bool/null/array/object/root, Ope for numbers
        // and strings).
        let ste_vec = gen_stevec_with_mode(
            json!({
                "string_leaf": "hello",
                "number_leaf": 42,
                "bool_leaf": true,
                "null_leaf": null,
                "array_leaf": ["a"],
                "object_leaf": { "k": "v" }
            }),
            SteVecMode::Compat,
        );

        let (mut saw_none, mut saw_ope) = (false, false);
        for entry in &ste_vec.entries {
            match &entry.term {
                None => saw_none = true,
                Some(EncryptedSteVecTerm::Compat { .. }) => saw_ope = true,
                Some(other) => {
                    panic!("indexed entry must use the Compat term variant, got {other:?}")
                }
            }
        }
        assert!(
            saw_none,
            "expected term-less entries (non-orderable path entries + all value entries)"
        );
        assert!(saw_ope, "expected at least one Compat::Ope entry");
    }

    /// Mirror of [`test_json_indexer_emits_compat_term_variants`] for `SteVecMode::Standard`.
    /// Every term emitted under Standard mode — both query-side terms produced
    /// by `generate_term` and stored terms produced by `index` — must be
    /// wrapped in the `EncryptedSteVecTerm::Standard` variant. Standard
    /// orderable terms are ORE-based: numbers and strings both collapse into
    /// the single `Ore` variant, so we must observe both Standard subvariants
    /// (term-less for bool/null/array/object/root and every value entry,
    /// `Ore` for numbers and strings)
    /// in a representative JSON document.
    #[test]
    fn test_json_indexer_emits_standard_term_variants() {
        // generate_term: f64 plaintext → Standard::Ore
        assert!(
            matches!(
                gen_term_with_mode(42_f64, SteVecMode::Standard),
                EncryptedSteVecTerm::Standard { .. }
            ),
            "expected Standard::Ore for f64 plaintext"
        );

        // generate_term: string plaintext → Standard::Ore
        assert!(
            matches!(
                gen_term_with_mode("hello", SteVecMode::Standard),
                EncryptedSteVecTerm::Standard { .. }
            ),
            "expected Standard::Ore for string plaintext"
        );

        let ste_vec = gen_stevec_with_mode(
            json!({
                "string_leaf": "hello",
                "number_leaf": 42,
                "bool_leaf": true,
                "null_leaf": null,
                "array_leaf": ["a"],
                "object_leaf": { "k": "v" }
            }),
            SteVecMode::Standard,
        );

        let (mut saw_none, mut saw_ore) = (false, false);
        for entry in &ste_vec.entries {
            match &entry.term {
                None => saw_none = true,
                Some(EncryptedSteVecTerm::Standard { .. }) => saw_ore = true,
                Some(other) => {
                    panic!("indexed entry must use the Standard term variant, got {other:?}")
                }
            }
        }
        assert!(
            saw_none,
            "expected term-less entries (non-orderable path entries + all value entries)"
        );
        assert!(saw_ore, "expected at least one Standard::Ore entry");
    }

    /// Exact-match via value selector: a stored document contains the value
    /// selector for exactly the (path, value) pairs it holds. This is the
    /// design's exact-equality promise — a keyed-MAC comparison, immune to the
    /// orderable encoding's losses (f64 rounding, string collation).
    #[test]
    fn test_value_selector_presence_is_exact_match() {
        let ste_vec = gen_stevec(json!({"a": 100, "name": "café", "big": 9007199254740993u64}));
        let stored = stored_selectors(&ste_vec);

        // Present: the exact values, and numeric equality across representations.
        assert!(stored.contains(&gen_value_selector("$.a", json!(100))));
        assert!(stored.contains(&gen_value_selector("$.a", json!(100.0))));
        assert!(stored.contains(&gen_value_selector("$.name", json!("café"))));
        assert!(stored.contains(&gen_value_selector("$.big", json!(9007199254740993u64))));

        // Absent: near-misses that the ORDERABLE encoding cannot distinguish
        // but the value selector must.
        assert!(!stored.contains(&gen_value_selector("$.name", json!("cafe"))));
        assert!(!stored.contains(&gen_value_selector("$.big", json!(9007199254740992u64))));
        // Type confusion and plain mismatches.
        assert!(!stored.contains(&gen_value_selector("$.a", json!("100"))));
        assert!(!stored.contains(&gen_value_selector("$.a", json!(101))));
        // Right value, wrong path.
        assert!(!stored.contains(&gen_value_selector("$.name", json!(100))));
    }

    /// Scalar bool and null values are exact-matchable through their tag-only
    /// value selectors — the replacement for the retired `hm` terms.
    #[test]
    fn test_value_selector_matches_bool_and_null() {
        let ste_vec = gen_stevec(json!({"flag": true, "gone": null}));
        let stored = stored_selectors(&ste_vec);

        assert!(stored.contains(&gen_value_selector("$.flag", json!(true))));
        assert!(!stored.contains(&gen_value_selector("$.flag", json!(false))));
        assert!(stored.contains(&gen_value_selector("$.gone", json!(null))));
    }

    /// A single value selector is exact-match only for scalars: a container
    /// MACs only its structural tag (`MAP0{}` / `ARRY[]`) plus the path, so
    /// `{"a":1}` and `{"b":2}` — and `[1]` and `[2]` — would collide. The
    /// exact-match query op therefore rejects objects and arrays outright
    /// (container matching goes through the flattened containment query). The
    /// storage side still emits the structural entries containment relies on;
    /// only the single-selector *query* path is restricted. (Regression for the
    /// AppSec review's High finding on container-selector collisions.)
    #[test]
    fn test_value_selector_rejects_containers() {
        for container in [json!({}), json!({"a": 1}), json!([]), json!([1, 2])] {
            let err =
                try_gen_value_selector_with_term_filters("$.x", container.clone(), Vec::new())
                    .unwrap_err();
            assert!(
                matches!(err, EncryptionError::InvalidValue(_)),
                "expected InvalidValue for container {container:?}, got {err:?}"
            );
        }
    }

    /// Lexical-analysis filters do not define JSON equality. Reject them for
    /// storage and exact-query operations instead of stemming values or
    /// representing removed stop words as JSON null.
    #[test]
    fn test_json_indexer_rejects_lexical_search_filters() {
        let index_key = IndexKey::from([0; 32]);
        for filter in [TokenFilter::Stemmer, TokenFilter::Stop] {
            let indexer = super::JsonIndexer::new(super::JsonIndexerOptions {
                prefix: "cs_ste_vec_v1".to_string(),
                term_filters: vec![filter],
                array_index_mode: ArrayIndexMode::ALL,
                ..Default::default()
            });

            let storage = indexer.index(json!({"x": "running"}), &index_key);
            assert!(
                matches!(storage, Err(EncryptionError::CreateIndexError(_))),
                "storage must reject lexical filter"
            );
            let exact = indexer.generate_value_selector(
                Selector::parse("$.x").unwrap(),
                &json!("running"),
                &index_key,
            );
            assert!(
                matches!(exact, Err(EncryptionError::CreateIndexError(_))),
                "exact query must reject lexical filter, got {exact:?}"
            );
        }
    }

    /// String values pass through the indexer's term filters before
    /// tokenization — symmetric with storage — so a differently-cased query
    /// still matches a `Downcase`-filtered column.
    #[test]
    fn test_value_selector_respects_term_filters() {
        let ste_vec =
            gen_stevec_with_term_filters(json!({"name": "John"}), vec![TokenFilter::Downcase]);
        let stored = stored_selectors(&ste_vec);

        let query = gen_value_selector_with_term_filters(
            "$.name",
            json!("JOHN"),
            vec![TokenFilter::Downcase],
        );
        assert!(stored.contains(&query));
        // Without the filter the selectors must NOT match (different bytes in).
        assert!(!stored.contains(&gen_value_selector("$.name", json!("JOHN"))));
    }

    /// Containment is exact end-to-end: the needle's value entries must be
    /// present in the stored document, so values the ORDERABLE encoding
    /// collates together no longer contain each other.
    #[test]
    fn test_containment_is_exact_for_collated_strings_and_rounded_numbers() {
        // Would have matched under term-based containment: "café" and "cafe"
        // share an `op` term, as do 2^53 and 2^53+1.
        let stored = gen_stevec(json!({"name": "cafe", "big": 9007199254740992u64}));
        assert!(!simulated_contains(
            gen_stevec(json!({"name": "cafe", "big": 9007199254740992u64})),
            gen_query(json!({"name": "café"}))
        ));
        assert!(!simulated_contains(
            gen_stevec(json!({"name": "cafe", "big": 9007199254740992u64})),
            gen_query(json!({"big": 9007199254740993u64}))
        ));
        // The genuine values still contain.
        assert!(simulated_contains(
            stored,
            gen_query(json!({"name": "cafe"}))
        ));
    }

    /// The `SteVecValueSelector` input parser accepts exactly
    /// `{"path", "value"}` and rejects everything else loudly.
    #[test]
    fn test_parse_value_selector_input() {
        let ok = json!({"path": "$.a", "value": 100});
        let (path, value) = super::parse_value_selector_input(&ok).unwrap();
        assert_eq!(path, "$.a");
        assert_eq!(value, &json!(100));

        for bad in [
            json!({"path": "$.a"}),
            json!({"value": 100}),
            json!({"path": "$.a", "value": 100, "extra": 1}),
            json!({"path": 42, "value": 100}),
            json!("$.a"),
            json!(null),
        ] {
            assert!(
                super::parse_value_selector_input(&bad).is_err(),
                "must reject {bad}"
            );
        }
    }

    /// Selectors — BOTH kinds, path and value-inclusive — are always Blake3
    /// and therefore mode-independent. Indexing the same document under
    /// Compat and Standard must produce identical selector SETS (the terms
    /// differ — OPE vs ORE — but the selector namespace must not partition by
    /// mode, or a query generated for one mode would silently miss data
    /// stored under the other).
    #[test]
    fn test_selector_sets_are_mode_independent() {
        let json = json!({"flag": true, "name": "John", "age": 30});
        let compat = gen_stevec_with_mode(json.clone(), SteVecMode::Compat);
        let standard = gen_stevec_with_mode(json, SteVecMode::Standard);

        let selectors = |ste_vec: SteVec<16>| -> Vec<[u8; 16]> {
            ste_vec
                .entries
                .iter()
                .map(|entry| entry.tokenized_selector.as_bytes())
                .collect()
        };

        assert_eq!(
            selectors(compat),
            selectors(standard),
            "selector sets (path + value) must be identical across modes"
        );
    }

    /// Selectors are mode-independent: both `Compat` and `Standard` produce
    /// Blake3-tokenized selectors. A regression here would re-introduce the
    /// mode dispatch in `generate_selector` and silently partition the token
    /// space, breaking query-side / index-side comparability across modes.
    #[test]
    fn test_selectors_are_mode_independent() {
        let selector = || Selector::parse("$.name").unwrap();
        let compat = gen_selector_with_mode(selector(), SteVecMode::Compat);
        let standard = gen_selector_with_mode(selector(), SteVecMode::Standard);
        assert_eq!(
            compat, standard,
            "selectors must be Blake3-keyed regardless of SteVecMode"
        );
    }

    /// Guards against a regression where the mode field stops reaching the
    /// leaf builders: indexing the same plaintext under the same mode must
    /// yield byte-identical terms.
    #[test]
    fn test_same_mode_same_input_is_deterministic() {
        let a = gen_term_with_mode("hello", SteVecMode::Compat);
        let b = gen_term_with_mode("hello", SteVecMode::Compat);
        assert_eq!(a, b);

        let c = gen_term_with_mode("hello", SteVecMode::Standard);
        let d = gen_term_with_mode("hello", SteVecMode::Standard);
        assert_eq!(c, d);
    }

    /// End-to-end wire-key invariant across the single `dispatch_mode` site:
    /// routing BOTH the storage path (`index`) and the query path
    /// (`generate_term`) through one runtime-mode -> `TermBuilder` dispatch
    /// guarantees a column can never emit the wrong wire key for its mode.
    /// Standard-mode orderable terms serialize under `oc` (CLLW-ORE) and never
    /// `op`; Compat-mode orderable terms serialize under `op` (CLLW-OPE) and
    /// never `oc`. MAC terms (`hm`) are shared and mode-independent. This locks
    /// the mode->wire-key mapping through the public surface so a transposed
    /// dispatch arm (a Standard column building a Compat term, or vice versa)
    /// would fail here.
    #[test]
    fn test_mode_determines_wire_key_end_to_end() {
        use serde_json::to_value;

        let doc = json!({
            "string_leaf": "hello",
            "number_leaf": 42,
            "bool_leaf": true
        });

        // --- Standard mode: orderable terms ride `oc`, never `op` ---
        // Query path (generate_term).
        let std_term = to_value(gen_term_with_mode(42_f64, SteVecMode::Standard)).unwrap();
        assert!(
            std_term.get("oc").is_some() && std_term.get("op").is_none(),
            "Standard generate_term must serialize under `oc`, got {std_term}"
        );

        // Storage path (index).
        let std_vec = gen_stevec_with_mode(doc.clone(), SteVecMode::Standard);
        let mut saw_oc = false;
        for entry in &std_vec.entries {
            let wire = to_value(entry).unwrap();
            assert!(
                wire.get("op").is_none(),
                "no Standard stored entry may carry `op`, got {wire}"
            );
            assert!(
                wire.get("hm").is_none(),
                "entries never carry `hm` (exact match is the value selector), got {wire}"
            );
            saw_oc |= wire.get("oc").is_some();
        }
        assert!(saw_oc, "at least one Standard stored entry must carry `oc`");

        // --- Compat mode: orderable terms ride `op`, never `oc` ---
        // Query path (generate_term).
        let compat_term = to_value(gen_term_with_mode(42_f64, SteVecMode::Compat)).unwrap();
        assert!(
            compat_term.get("op").is_some() && compat_term.get("oc").is_none(),
            "Compat generate_term must serialize under `op`, got {compat_term}"
        );

        // Storage path (index).
        let compat_vec = gen_stevec_with_mode(doc, SteVecMode::Compat);
        let mut saw_op = false;
        for entry in &compat_vec.entries {
            let wire = to_value(entry).unwrap();
            assert!(
                wire.get("oc").is_none(),
                "no Compat stored entry may carry `oc`, got {wire}"
            );
            assert!(
                wire.get("hm").is_none(),
                "entries never carry `hm` (exact match is the value selector), got {wire}"
            );
            saw_op |= wire.get("op").is_some();
        }
        assert!(saw_op, "at least one Compat stored entry must carry `op`");
    }

    /// The same plaintext under different modes must land in distinct outer
    /// `EncryptedSteVecTerm` variants and compare unequal.
    #[test]
    fn test_different_modes_produce_different_outer_variants() {
        let compat = gen_term_with_mode("hello", SteVecMode::Compat);
        let standard = gen_term_with_mode("hello", SteVecMode::Standard);

        assert!(matches!(compat, EncryptedSteVecTerm::Compat { .. }));
        assert!(matches!(standard, EncryptedSteVecTerm::Standard { .. }));
        // PartialEq across variants returns false.
        assert_ne!(compat, standard);
    }

    #[test]
    fn test_json_indexer_options_default_mode_is_compat() {
        use zerokms_protocol::cipherstash_config::column::SteVecMode;
        let opts = super::JsonIndexerOptions::default();
        assert_eq!(opts.mode, SteVecMode::Compat);
    }

    #[test]
    fn test_try_from_ste_vec_index_type_threads_mode_through() {
        use zerokms_protocol::cipherstash_config::column::{ArrayIndexMode, IndexType, SteVecMode};

        let it = IndexType::SteVec {
            prefix: "p".into(),
            term_filters: vec![],
            array_index_mode: ArrayIndexMode::default(),
            mode: SteVecMode::Standard,
        };
        let opts = super::JsonIndexerOptions::try_from(&it).unwrap();
        assert_eq!(opts.mode, SteVecMode::Standard);
    }

    #[test]
    fn test_try_from_ste_vec_rejects_lexical_search_filters() {
        use zerokms_protocol::cipherstash_config::column::{
            ArrayIndexMode, IndexType, SteVecMode, TokenFilter as ConfigTokenFilter,
        };

        for filter in [ConfigTokenFilter::Stemmer, ConfigTokenFilter::Stop] {
            let index_type = IndexType::SteVec {
                prefix: "p".into(),
                term_filters: vec![filter],
                array_index_mode: ArrayIndexMode::default(),
                mode: SteVecMode::Compat,
            };
            let result = super::JsonIndexerOptions::try_from(&index_type);
            assert!(
                matches!(result, Err(EncryptionError::CreateIndexError(_))),
                "SteVec config must reject lexical filter, got {result:?}"
            );
        }
    }

    #[test]
    fn test_root_record_as_object() {
        let json = json!({ "name": "John" });
        let ste_vec = gen_stevec(json.clone());
        let root = ste_vec.into_root_record_with_nonce().unwrap();

        assert_eq!(decrypt_as_json(root), json);
    }

    #[test]
    fn test_root_record_as_array() {
        let json = json!([1, 2, 3]);
        let ste_vec = gen_stevec(json.clone());
        let root = ste_vec.into_root_record_with_nonce().unwrap();

        assert_eq!(decrypt_as_json(root), json);
    }

    /// The envelope format's core security property: equal plaintexts at
    /// different (path, value) positions produce DIFFERENT ciphertexts. All
    /// entries share the document's one data key, so this is exactly what
    /// the selector-derived nonces buy — under the old IV-derived-nonce
    /// scheme, `$.a`'s and `$.b`'s path entries here (same value) and every
    /// value entry (same sentinel) collided byte-for-byte.
    #[test]
    fn test_selector_derived_nonces_break_intra_document_ciphertext_equality() {
        let ste_vec = gen_stevec(json!({ "a": "x", "b": "x" }));
        let total = ste_vec.entries.len();
        let mut cts: Vec<&Vec<u8>> = ste_vec.entries.iter().map(|e| &e.ciphertext).collect();
        cts.sort();
        cts.dedup();
        assert_eq!(cts.len(), total, "no two entries may share a ciphertext");
    }

    /// A value entry decrypts to the versioned sentinel: assertable on
    /// decrypt, and never parseable as a legal `Plaintext` (its variant byte
    /// is reserved).
    #[test]
    fn test_value_entry_decrypts_to_the_sentinel() {
        use super::ste_vec::is_value_entry_sentinel;

        let ste_vec = gen_stevec(json!({ "hello": "world" }));
        let header = ste_vec.header().clone();
        let value_selector = gen_value_selector("$.hello", json!("world"));
        let entry = ste_vec
            .entries
            .iter()
            .find(|e| e.tokenized_selector == value_selector)
            .expect("value entry present");

        let decrypted = decrypt(
            header.record_with_selector(
                entry.ciphertext.clone(),
                entry.tokenized_selector.as_bytes(),
            ),
            Default::default(),
        )
        .expect("value entry decrypts");

        assert!(is_value_entry_sentinel(&decrypted));
        assert!(
            Plaintext::from_slice(&decrypted).is_err(),
            "the sentinel must not parse as a legal Plaintext"
        );
    }

    /// The disambiguation the sentinel exists for: a GENUINE empty-string
    /// leaf's path entry decrypts to `""` while its value entry decrypts to
    /// the sentinel — under the old `Enc("")` scheme both had the same
    /// plaintext and a decryptor could not tell them apart.
    #[test]
    fn test_empty_string_leaf_is_distinguishable_from_value_entries() {
        use super::ste_vec::is_value_entry_sentinel;

        let ste_vec = gen_stevec(json!({ "a": "" }));
        let header = ste_vec.header().clone();
        let path_selector = gen_selector(Selector::parse("$.a").unwrap());

        let decrypt_entry = |selector: TokenizedSelector<16>| {
            let entry = ste_vec
                .entries
                .iter()
                .find(|e| e.tokenized_selector == selector)
                .expect("entry present");
            decrypt(
                header.record_with_selector(
                    entry.ciphertext.clone(),
                    entry.tokenized_selector.as_bytes(),
                ),
                Default::default(),
            )
            .expect("entry decrypts")
        };

        let leaf = decrypt_entry(path_selector);
        assert!(!is_value_entry_sentinel(&leaf));
        assert_eq!(
            Plaintext::from_slice(&leaf).expect("path entry holds a legal Plaintext"),
            Plaintext::from(json!(""))
        );

        let value = decrypt_entry(gen_value_selector("$.a", json!("")));
        assert!(is_value_entry_sentinel(&value));
    }

    /// The nonce is authenticated (GCM-SIV feeds it into the tag), and
    /// decrypt re-derives it from the stored selector — so grafting one
    /// entry's ciphertext onto another entry's selector fails. Under the
    /// shared-nonce scheme, ciphertexts were freely permutable within a
    /// document.
    #[test]
    fn test_ciphertext_selector_binding_rejects_within_document_grafts() {
        let ste_vec = gen_stevec(json!({ "a": 1, "b": 2 }));
        let header = ste_vec.header().clone();
        let donor = &ste_vec.entries[1];
        let target = &ste_vec.entries[2];
        assert_ne!(donor.tokenized_selector, target.tokenized_selector);

        let graft = header.record_with_selector(
            donor.ciphertext.clone(),
            target.tokenized_selector.as_bytes(),
        );
        assert!(
            decrypt(graft, Default::default()).is_err(),
            "a ciphertext under a foreign selector's nonce must not decrypt"
        );
    }

    /// The AEAD nonce only covers the first 12 selector bytes; the full 16-byte
    /// selector is additionally bound into the AAD. So a mutation to the last 4
    /// bytes of a stored selector — which leaves the nonce untouched — is still
    /// detected on decrypt. (Regression for the AppSec review's finding that
    /// only 96 of the selector's 128 bits were bound to the ciphertext.)
    #[test]
    fn test_selector_suffix_outside_the_nonce_is_authenticated() {
        let ste_vec = gen_stevec(json!({ "a": 1 }));
        let header = ste_vec.header().clone();
        let entry = &ste_vec.entries[1];
        let selector = entry.tokenized_selector.as_bytes();

        // Control: the untouched selector decrypts.
        assert!(decrypt(
            header.record_with_selector(entry.ciphertext.clone(), selector),
            Default::default(),
        )
        .is_ok());

        // Flip a byte OUTSIDE the 12-byte nonce prefix. The derived nonce is
        // unchanged, so only the AAD binding can catch the tamper.
        let mut mutated = selector;
        mutated[15] ^= 0xff;
        assert_eq!(
            mutated[..12],
            selector[..12],
            "the mutation must not touch the nonce prefix"
        );
        assert!(
            decrypt(
                header.record_with_selector(entry.ciphertext.clone(), mutated),
                Default::default(),
            )
            .is_err(),
            "mutating selector bytes outside the nonce prefix must fail decryption"
        );
    }

    #[test]
    fn test_array_entries() {
        let json = json!(["A", "B", "C",]);

        let ste_vec = gen_stevec(json.clone());

        // 10 nodes -> 10 path entries (traversal order, root first) followed
        // by 10 appended value entries.
        assert_eq!(20, ste_vec.entries.len());

        assert!(!ste_vec.entries[0].parent_is_array);
        assert!(ste_vec.entries[1].parent_is_array);
        assert!(ste_vec.entries[2].parent_is_array);
        assert!(!ste_vec.entries[3].parent_is_array);
        assert!(ste_vec.entries[4].parent_is_array);
        assert!(ste_vec.entries[5].parent_is_array);
        assert!(!ste_vec.entries[6].parent_is_array);

        // The appended half is the value entries: presence-only, term-less.
        assert!(ste_vec.entries[10..].iter().all(|e| e.term.is_none()));

        let json = json!({"a": [
            "A",
            "B",
            "C",
        ]});

        let ste_vec = gen_stevec(json.clone());

        // 11 nodes -> 22 entries (11 path + 11 value).
        assert_eq!(22, ste_vec.entries.len());

        assert!(!ste_vec.entries[0].parent_is_array);
        assert!(!ste_vec.entries[1].parent_is_array);
        assert!(ste_vec.entries[2].parent_is_array);
        assert!(ste_vec.entries[3].parent_is_array);
        assert!(ste_vec.entries[11..].iter().all(|e| e.term.is_none()));
    }

    #[test]
    fn test_array_index_mode_none() {
        let json = json!(["A", "B", "C"]);
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::NONE);

        // With NONE: root(1) = 1 node -> 2 entries (path + value)
        assert_eq!(2, ste_vec.entries.len());
    }

    #[test]
    fn test_array_index_mode_wildcard_only() {
        let json = json!(["A", "B", "C"]);
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::WILDCARD);

        // With WILDCARD: root(1) + 3 wildcard = 4 nodes -> 8 entries
        assert_eq!(8, ste_vec.entries.len());
    }

    #[test]
    fn test_array_index_mode_all_matches_original() {
        let json = json!(["A", "B", "C"]);
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::ALL);

        // With ALL: root(1) + 3*(item + position + wildcard) = 10 nodes -> 20 entries
        assert_eq!(20, ste_vec.entries.len());
    }

    #[test]
    fn test_nested_object_with_array_mode_none() {
        let json = json!({
            "name": "John",
            "cars": ["Ford", "BMW"]
        });
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::NONE);

        // With NONE: root(1) + name(1) + cars(1) = 3 nodes -> 6 entries
        assert_eq!(6, ste_vec.entries.len());
    }

    #[test]
    fn test_nested_object_with_array_mode_wildcard() {
        let json = json!({
            "name": "John",
            "cars": ["Ford", "BMW"]
        });
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::WILDCARD);

        // With WILDCARD: root(1) + name(1) + cars(1) + 2 wildcard = 5 nodes -> 10 entries
        assert_eq!(10, ste_vec.entries.len());
    }

    #[test]
    fn test_array_index_mode_item_only() {
        let json = json!(["A", "B", "C"]);
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::ITEM);
        // With ITEM: root(1) + 3 item = 4 nodes -> 8 entries
        assert_eq!(8, ste_vec.entries.len());
    }

    #[test]
    fn test_array_index_mode_position_only() {
        let json = json!(["A", "B", "C"]);
        let ste_vec = gen_stevec_with_options(json, vec![], ArrayIndexMode::POSITION);
        // With POSITION: root(1) + 3 position = 4 nodes -> 8 entries
        assert_eq!(8, ste_vec.entries.len());
    }

    #[test]
    fn test_orderable_term_rejects_non_orderable_plaintexts() {
        let rejected: Vec<Plaintext> = vec![
            Plaintext::Boolean(Some(true)),
            Plaintext::Json(Some(serde_json::json!({"x": 1}))),
            Plaintext::Int(None), // null
        ];

        for p in &rejected {
            let err = OrderableTerm::try_from(p).expect_err("OrderableTerm should reject");
            assert!(
                matches!(err, crate::encryption::EncryptionError::InvalidValue(_)),
                "expected InvalidValue for {p:?}, got {err}"
            );
        }
    }

    mod preprocessing {
        use super::super::JsonIndexer;
        use serde_json::json;

        #[test]
        fn test_downcase_filter() {
            let indexer = JsonIndexer::new(super::super::JsonIndexerOptions {
                prefix: "test".to_string(),
                term_filters: vec![super::TokenFilter::Downcase],
                array_index_mode: super::super::ArrayIndexMode::ALL,
                ..Default::default()
            });

            let input = json!({
                "Name": "John DOE",
                "Details": {
                    "City": "New York",
                    "Bio": "Loves Programming"
                },
                "Tags": ["Rust", "Encryption", "JSON"]
            });

            let expected = json!({
                "Name": "john doe",
                "Details": {
                    "City": "new york",
                    "Bio": "loves programming"
                },
                "Tags": ["rust", "encryption", "json"]
            });

            let processed = indexer.preprocess(input);
            assert_eq!(processed, expected);
        }
    }
}