feat(stack-encrypt)!: let an inverted Between range through, as SQL does

A `Between` whose low bound is above its high bound was refused with
`TermError::InvertedRange` before either term was derived. SQL's own
`BETWEEN` refuses nothing: `x BETWEEN 20 AND 10` is a valid query that
matches no row, and an encrypted range now behaves the same way. The
empty result leaks nothing and corrupts nothing, so a refusal bought
little.

It would also cost more than it buys once text and floats are ordered.
Judging their ranges correctly means reproducing, before encryption, the
order the index compares in: text by its fold, floats by their canonical
encoding. That order belongs to the ORE crates, not to this one.

So `TermError::InvertedRange` (code `stack_encrypt::inverted_range`)
goes, with the typed path's `lo > hi` check (and the `PartialOrd` bound
`op::Ordered` carried for it) and the data path's `integer_order`. The
variant is under [Unreleased] and never shipped.

Author: coderdan

languages/golang/encrypt/guest/tests/native_ops.rs

@@ -1562,13 +1562,6 @@ fn query_term_validation_refuses_what_the_query_op_refuses() {
             "between",
             STATUS_ENCODING,
         ),
-        (
-            "inverted range",
-            FfiValue::Array(vec![FfiValue::UInt32(65), FfiValue::UInt32(18)]),
-            "age",
-            "between",
-            STATUS_TERM,
-        ),
         ("no token", s("al"), "name", "matches", STATUS_TERM),
     ] {
         let input = encode(input);

languages/golang/encrypt/query_test.go

@@ -317,8 +317,9 @@ func TestAQueryTheFieldDoesNotAnswerIsRefused(t *testing.T) {
 			t.Fatalf("%s on %s: %v, want field %q and reason %q", tc.operator, tc.field, err, tc.field, tc.reason)
 		}
 	}
-	if _, err := cipher.QueryTerm(ctx, queryPlan, "age", "between", []any{uint32(65), uint32(18)}); !errors.Is(err, encrypt.ErrTerm) {
-		t.Fatalf("an inverted range: %v, want ErrTerm", err)
+	// An inverted range is not refused, as SQL's BETWEEN is not.
+	if _, err := cipher.QueryTerm(ctx, queryPlan, "age", "between", []any{uint32(65), uint32(18)}); err != nil {
+		t.Fatalf("an inverted range: %v", err)
 	}
 	if _, err := cipher.QueryTerm(ctx, queryPlan, "name", "matches", "al"); !errors.Is(err, encrypt.ErrTerm) {
 		t.Fatalf("text that cuts no token: %v, want ErrTerm", err)
@@ -499,9 +500,9 @@ func TestGeneratedQueriesAreTheRustFixtures(t *testing.T) {
 			t.Errorf("%s.Value() = %T %v", label, got, err)
 		}
 	}
-	// An inverted range is the typed path's refusal, from the engine.
-	if _, err := fields.Age.Between(ctx, cipher, 65, 18); !errors.Is(err, encrypt.ErrTerm) {
-		t.Errorf("an inverted range: %v, want ErrTerm", err)
+	// An inverted range is not refused, as SQL's BETWEEN is not.
+	if _, err := fields.Age.Between(ctx, cipher, 65, 18); err != nil {
+		t.Errorf("an inverted range: %v", err)
 	}
 }
 

packages/stack-encrypt/CHANGELOG.md

@@ -110,8 +110,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   for the value (`OreTerm`, `OpeTerm`); a range's is one `sem::RangeQuery`
   carrying both bounds' terms, read with `lo()` and `hi()`, so no statement
   can pair the low bound of one query with the high bound of another. A
-  range whose low bound is above its high bound is refused when the query
-  is awaited, before either term is derived (`TermError::InvertedRange`).
+  range whose low bound is above its high bound is not refused: as SQL's
+  `BETWEEN`, it matches nothing.
   What a query takes is the operator's `op::Arity` (`op::One` or
   `op::Pair`), and `op::Input` relates the value given to the plaintext the
   plan is checked against (ADR-0009, decision 7).

packages/stack-encrypt/docs/adr/0009-operators-select-the-index-and-a-query-term-is-not-the-stored-term.md

@@ -572,9 +572,12 @@ the ranked loop is worth packaging; it is deferred, not refused.
 
 `cipher.query(op::Between, &(lo, hi)).on(&plan)` produces one term,
 `sem::RangeQuery`, carrying the index's term for each bound (the ORE left
-ciphertexts, once block ORE lands), inclusive at both ends, and the client
-refuses `lo > hi` (`TermError::InvertedRange`) before either term is
-derived; `(v, v)` is one value. One call derives both bounds, under one
+ciphertexts, once block ORE lands), inclusive at both ends; `(v, v)` is one
+value. The client does not refuse `lo > hi`: as SQL's `BETWEEN`, such a
+range matches nothing. Judging it would mean reproducing, before
+encryption, the order the index compares in (text by its fold, floats by
+their canonical encoding), which belongs to the ORE crates. One call
+derives both bounds, under one
 context, so a caller cannot pair a bound from one column with a bound from
 another. The ordering operators are answered over the integer types and
 text (`op::Ordered`), by the ORE index by default and by OPE through

packages/stack-encrypt/src/codes.rs

@@ -81,7 +81,6 @@ mod tests {
             TermError::Ore(_) => TermError::Ore(cllw_ore::Error),
             TermError::InvalidOptions(_) => TermError::InvalidOptions("k out of range"),
             TermError::EmptyTermText => TermError::EmptyTermText,
-            TermError::InvertedRange => TermError::InvertedRange,
             TermError::NoEqualityTerm => TermError::NoEqualityTerm,
             TermError::NoOrderTerm => TermError::NoOrderTerm,
             TermError::Normalize(_) => {
@@ -396,7 +395,6 @@ mod tests {
                 json!({ "len": 3 }),
             ),
             (Box::new(TermError::EmptyTermText), json!({})),
-            (Box::new(TermError::InvertedRange), json!({})),
             (Box::new(TermError::NoEqualityTerm), json!({})),
             (Box::new(TermError::NoOrderTerm), json!({})),
             (

packages/stack-encrypt/src/dynamic/query.rs

@@ -65,7 +65,6 @@
 //! [`Probabilistic::verify`]: crate::op::Probabilistic::verify
 //! [`Probabilistic::target_limit`]: crate::op::Probabilistic::target_limit
 
-use std::cmp::Ordering;
 use std::fmt;
 
 use stack_kms::DataKeySource;
@@ -578,19 +577,15 @@ fn not_a_range(field: &str) -> Error {
 }
 
 /// The refusals the typed path makes when a query is awaited, before any
-/// term exists ([`Supports::check`](crate::op::Supports::check)): a range
-/// whose low bound is above its high bound, and match text the index
-/// cannot normalize or that cuts no token. The match index's own
-/// derivation refuses the last two again; asking here lets a binding
-/// refuse at its boundary.
+/// term exists ([`Supports::check`](crate::op::Supports::check)): match
+/// text the index cannot normalize or that cuts no token, and equality
+/// text the scheme cannot normalize. Each index's own derivation refuses
+/// these again; asking here lets a binding refuse at its boundary. A range
+/// whose low bound is above its high bound is not refused: as SQL's
+/// `BETWEEN`, it matches nothing.
 fn check_input(index: &IndexSpec, input: &Input) -> Result<(), Error> {
     let refused = |error: TermError| Error::Cipher(error.into());
     match (index, input) {
-        (_, Input::Pair(lo, hi)) => {
-            if integer_order(lo, hi) == Some(Ordering::Greater) {
-                return Err(refused(TermError::InvertedRange));
-            }
-        }
         (IndexSpec::Match(options), Input::One(value)) => {
             query_tokens(value, options).map(drop)?;
         }
@@ -605,33 +600,6 @@ fn check_input(index: &IndexSpec, input: &Input) -> Result<(), Error> {
     Ok(())
 }
 
-/// The order of two integers of one kind, or `None` for anything else.
-fn integer_order(lo: &ValueFrame, hi: &ValueFrame) -> Option<Ordering> {
-    let (lo_kind, lo) = integer_of(lo)?;
-    let (hi_kind, hi) = integer_of(hi)?;
-    (lo_kind == hi_kind).then(|| lo.cmp(&hi))
-}
-
-/// An integer scalar's kind and value, or `None` for anything else. The
-/// value is its sign and 128-bit two's-complement word (vitaminc's
-/// [`Int::sign_and_word`](vitaminc_aead::plaintext::Int::sign_and_word)),
-/// ordered negatives first, so one comparison covers every width from
-/// `i128::MIN` to `u128::MAX`.
-fn integer_of(value: &ValueFrame) -> Option<(ValueKind, (bool, u128))> {
-    let kind = value.kind()?;
-    let (negative, word) = value
-        .visit(OneScalar::new(
-            |ty: Option<Logical>, value: Physical<'_>| match (ty, value) {
-                (None, Physical::Int(int)) => Ok(int.sign_and_word()),
-                _ => Err(None),
-            },
-        ))
-        .ok()?;
-    // `!negative` so a negative sorts below every non-negative; within a
-    // sign the two's-complement words order as the values do.
-    Some((kind, (!negative, word)))
-}
-
 /// The tokens a match query of `value` keeps, under the index's options.
 ///
 /// # Errors
@@ -729,10 +697,11 @@ pub fn check_query(
 /// field does not answer ([`Reason::OperatorNotAnswered`]), an input that
 /// cannot be read as the field's kind ([`Reason::FieldType`]) and a
 /// `between` input that is not two values ([`Reason::NotARange`]).
-/// [`Error::Cipher`] for the query refusals the typed path makes: a range
-/// whose low bound is above its high ([`TermError::InvertedRange`]), and
-/// match text that cuts no token ([`TermError::EmptyTermText`]) or that
-/// the index cannot normalize ([`TermError::Normalize`]).
+/// [`Error::Cipher`] for the query refusals the typed path makes: match
+/// text that cuts no token ([`TermError::EmptyTermText`]), and text the
+/// index cannot normalize ([`TermError::Normalize`]). A range whose low
+/// bound is above its high bound is not refused: as SQL's `BETWEEN`, it
+/// matches nothing.
 /// [`Error::Target`] for what the resolver refuses.
 pub fn query_term<'a, K>(
     cipher: &'a KeysetCipher<'_, K>,
@@ -1092,7 +1061,7 @@ mod tests {
         keyset: &KeysetCipher<'_, FakeDataKeySource>,
         name: &str,
         operator: OpSpec,
-        input: FfiValue,
+        input: impl Encrypt,
     ) -> Result<QueryTerm, Error> {
         query_term(keyset, &users(), name, operator, input, &NoTargets)?
             .await
@@ -1437,9 +1406,7 @@ mod tests {
     async fn the_typed_paths_query_refusals_are_made_before_any_term() {
         let cipher = cipher().await;
         let keyset = cipher.default_keyset();
-        let pair = |lo, hi| FfiValue::Array(vec![FfiValue::UInt32(lo), FfiValue::UInt32(hi)]);
         let cases = [
-            ("age", OpSpec::Between, pair(65, 18), "inverted"),
             ("name", OpSpec::Matches, text("al"), "empty"),
             ("name", OpSpec::Matches, text("\u{0378}abc"), "normalize"),
             ("email", OpSpec::Eq, text("a\u{0378}bc"), "normalize"),
@@ -1451,7 +1418,6 @@ mod tests {
             ] {
                 let term = term_error(&error);
                 let expected = match what {
-                    "inverted" => matches!(term, Some(TermError::InvertedRange)),
                     "empty" => matches!(term, Some(TermError::EmptyTermText)),
                     _ => matches!(term, Some(TermError::Normalize(_))),
                 };
@@ -1927,8 +1893,8 @@ mod tests {
         ])
         .unwrap();
         assert!(
-            ask("huge", OpSpec::Between, inverted).await.is_err(),
-            "an inverted 128-bit range is refused"
+            ask("huge", OpSpec::Between, inverted).await.is_ok(),
+            "an inverted 128-bit range is not refused"
         );
 
         let stored = |value: &ValueFrame, name: &'static str| {
@@ -2003,53 +1969,23 @@ mod tests {
         );
     }
 
-    /// A range is refused the wrong way round for every integer kind a
-    /// field can declare, and two values of different kinds have no order
-    /// here: the input was read as one kind first.
-    #[test]
-    fn a_range_is_ordered_within_each_integer_kind() {
-        let cases = [
-            (FfiValue::Int32(-1), FfiValue::Int32(1)),
-            (FfiValue::Int64(-1), FfiValue::Int64(1)),
-            (FfiValue::UInt32(1), FfiValue::UInt32(2)),
-            (FfiValue::UInt64(1), FfiValue::UInt64(2)),
-        ];
-        for (lo, hi) in cases {
-            let (lo, hi) = (vf(&lo), vf(&hi));
-            assert_eq!(integer_order(&lo, &hi), Some(Ordering::Less));
-            assert_eq!(integer_order(&hi, &lo), Some(Ordering::Greater));
-            assert_eq!(integer_order(&lo, &lo), Some(Ordering::Equal));
-        }
-        assert_eq!(
-            integer_order(&vf(&FfiValue::UInt32(1)), &vf(&FfiValue::UInt64(2))),
-            None
-        );
-        assert_eq!(integer_order(&vf(&text("a")), &vf(&text("b"))), None);
-        // Every width, the 128-bit edges included: a `u128` above
-        // `i128::MAX` and a negative `i128` order as the numbers do.
-        let int = |int: vitaminc_aead::plaintext::Int| {
-            ValueFrame::of(vitaminc_aead::plaintext::Raw(
-                None,
-                vitaminc_aead::plaintext::Physical::Int(int),
-            ))
-            .expect("a value")
+    /// A range whose low bound is above its high bound is not refused, as
+    /// SQL's `BETWEEN` is not: it is checked, and its terms derived, like
+    /// any other range, and matches nothing.
+    #[tokio::test]
+    async fn an_inverted_range_is_a_query_like_any_other() {
+        let cipher = cipher().await;
+        let keyset = cipher.default_keyset();
+        // `score` declares OPE alone, whose terms compare as bytes.
+        let inverted = ValueFrame::of(vec![65i64, 18]).expect("a value");
+        assert!(check_query(&users(), "score", OpSpec::Between, &inverted, &NoTargets).is_ok());
+        let term = query(&keyset, "score", OpSpec::Between, &inverted)
+            .await
+            .expect("derived");
+        let Operand::Range { lo, hi } = term.operand() else {
+            panic!("a range");
         };
-        use vitaminc_aead::plaintext::Int;
-        for (lo, hi) in [
-            (Int::I8(-1), Int::I8(1)),
-            (Int::I16(-1), Int::I16(1)),
-            (Int::I128(i128::MIN), Int::I128(i128::MAX)),
-            (Int::I128(-1), Int::I128(0)),
-            (Int::U8(1), Int::U8(2)),
-            (Int::U16(1), Int::U16(2)),
-            (Int::U128(i128::MAX as u128), Int::U128(u128::MAX)),
-        ] {
-            let (lo, hi) = (int(lo), int(hi));
-            assert_eq!(integer_order(&lo, &hi), Some(Ordering::Less));
-            assert_eq!(integer_order(&hi, &lo), Some(Ordering::Greater));
-            assert_eq!(integer_order(&lo, &lo), Some(Ordering::Equal));
-        }
-        assert_eq!(integer_order(&int(Int::I8(1)), &int(Int::I16(2))), None);
+        assert!(lo > hi, "the bounds as given, and the terms in their order");
     }
 
     #[test]

packages/stack-encrypt/src/op/mod.rs

@@ -61,16 +61,15 @@
 //! plan is data, so there an index the field does not declare, or declares
 //! with other options, is refused when the query is awaited, before any
 //! key is requested. So is a match configuration whose [`MatchCase`]
-//! disagrees with its options, and so are the two query values the library
+//! disagrees with its options, and so is the one query value the library
 //! refuses: match text that cuts no token under the index's tokenizer,
-//! whose filter would match every row ([`TermError::EmptyTermText`]), and
-//! a `Between` whose low bound is above its high bound
-//! ([`TermError::InvertedRange`]). The stored side has no such refusal: a
-//! value with no tokens is stored as the empty filter, which no query
-//! matches.
+//! whose filter would match every row ([`TermError::EmptyTermText`]). The
+//! stored side has no such refusal: a value with no tokens is stored as
+//! the empty filter, which no query matches. A `Between` whose low bound is
+//! above its high bound is not refused either: as SQL's `BETWEEN`, it
+//! matches nothing.
 //!
 //! [`TermError::EmptyTermText`]: crate::sem::TermError::EmptyTermText
-//! [`TermError::InvertedRange`]: crate::sem::TermError::InvertedRange
 //! [`RangeQuery`]: crate::sem::RangeQuery
 //!
 //! The module is meant to be used by path (`op::Eq`): an imported `Eq`
@@ -88,7 +87,7 @@ pub use stats::{Limit, Stats, DEFAULT_CONFIDENCE, MAX_ROWS};
 
 use crate::sem::{
     CllwOpeEncrypt, CllwOreEncrypt, DefaultMatch, EqualityTerm, MatchConfig, MatchQuery,
-    MatchTerms, OpeTerm, OreTerm, QueryTokens, RangeQuery, TermError,
+    MatchTerms, OpeTerm, OreTerm, QueryTokens, RangeQuery,
 };
 use crate::target::{DeclaredContext, Equality, Index, Match, Ope, Ore, Owned, Pending};
 use crate::{Error, KeysetCipher, Label, NonEmpty, PlanError};
@@ -133,10 +132,9 @@ pub struct Gte;
 /// at both ends. It takes a [`Pair`], `cipher.query(op::Between, &(lo, hi))`,
 /// derives both bounds under one context, and sends them as one term
 /// ([`RangeQuery`]), so no statement can pair the
-/// low bound of one query with the high bound of another. A pair whose low
-/// bound is above its high bound is refused when the query is awaited
-/// ([`TermError::InvertedRange`]); one
-/// value is `(v, v)`.
+/// low bound of one query with the high bound of another. One value is
+/// `(v, v)`. A pair whose low bound is above its high bound is not
+/// refused: as SQL's `BETWEEN`, it matches nothing.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 pub struct Between;
 
@@ -347,16 +345,15 @@ impl<S: 'static> Input<Pair> for (S, S) {
 /// Text is not one: its order term is a catalog question (ADR-0009, ADR-0002),
 /// and an ordering on a text plan does not compile.
 ///
-/// Sealed: `Between` refuses an inverted range with the type's `PartialOrd`
-/// while the server compares ORE terms, so a type whose two orders could
-/// disagree (a newtype over folded text, say) must not be able to join. A
-/// type that meets every other bound is still refused:
+/// Sealed: a type joins only when the order its terms compare in is the
+/// one its operators promise, so a type whose terms could order otherwise
+/// (a newtype over folded text, say) must not be able to join. A type that
+/// meets every other bound is still refused:
 ///
 /// ```compile_fail
 /// # use cllw_ore::{CllwOpeEncrypt, CllwOreEncrypt, Error, Key};
 /// use stack_encrypt::op::Ordered;
 ///
-/// #[derive(PartialEq, PartialOrd)]
 /// struct Folded(u32);
 /// # impl CllwOreEncrypt for Folded {
 /// #     type Output = <u32 as CllwOreEncrypt>::Output;
@@ -380,7 +377,6 @@ impl<S: 'static> Input<Pair> for (S, S) {
 )]
 pub trait Ordered:
     sealed::Sealed
-    + PartialOrd
     + CllwOreEncrypt<Output: Send + 'static>
     + CllwOpeEncrypt<Output: Send + 'static>
     + Send
@@ -644,9 +640,8 @@ pub trait Supports<Op: Operator, In: Input<Op::Arity>>: Index<In::Plaintext> {
     /// Why this index cannot answer `Op` as configured, or for `input`, if
     /// it cannot: a match index whose [`MatchCase`] disagrees with its
     /// options ([`PlanError::MatchCase`]), a match query of text that cuts
-    /// no token ([`TermError::EmptyTermText`]), whose filter would match
-    /// every row, or a range whose low bound is above its high bound
-    /// ([`TermError::InvertedRange`]).
+    /// no token ([`TermError::EmptyTermText`](crate::sem::TermError::EmptyTermText)),
+    /// whose filter would match every row.
     /// Run when the query is awaited, before any key is requested; an
     /// index that refuses nothing returns `Ok(())`.
     fn check(&self, input: &In) -> Result<(), Error>;
@@ -744,12 +739,8 @@ macro_rules! orders {
         impl<S: Ordered> Supports<Between, (S, S)> for $index {
             type Query = RangeQuery<$term<S>>;
             type Verifier = ();
-            fn check(&self, (lo, hi): &(S, S)) -> Result<(), Error> {
-                if lo > hi {
-                    Err(TermError::InvertedRange.into())
-                } else {
-                    Ok(())
-                }
+            fn check(&self, _: &(S, S)) -> Result<(), Error> {
+                Ok(())
             }
             fn verifier(&self, _: &(S, S)) {}
             fn query((): (), (lo, hi): ($term<S>, $term<S>), _: QueryToken) -> Self::Query {
@@ -940,18 +931,15 @@ mod tests {
         arity::<AtPath<Between>, Pathed<Pair>>();
     }
 
-    /// The ordering operators default to ORE, and a range is refused only
-    /// when its bounds are the wrong way round: `(v, v)` is one value.
+    /// An ordering refuses no value: a range whose bounds are the wrong way
+    /// round matches nothing, as SQL's `BETWEEN` does.
     #[test]
-    fn a_range_is_checked_before_any_term_is_derived() {
+    fn an_ordering_refuses_no_value() {
         let ok = |pair: (u32, u32)| Supports::<Between, (u32, u32)>::check(&Ore, &pair).is_ok();
         assert!(ok((1, 2)));
         assert!(ok((2, 2)));
-        assert!(!ok((3, 2)));
-        assert!(matches!(
-            Supports::<Between, (i64, i64)>::check(&Ope, &(1, -1)),
-            Err(Error::Term(TermError::InvertedRange))
-        ));
+        assert!(ok((3, 2)));
+        assert!(Supports::<Between, (i64, i64)>::check(&Ope, &(1, -1)).is_ok());
         assert!(Supports::<Lt, u8>::check(&Ore, &7).is_ok());
         assert!(Supports::<Gte, i128>::check(&Ope, &-7).is_ok());
     }