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/src/abi.rs

@@ -465,8 +465,9 @@ pub unsafe extern "C" fn se_plan_check(plan_ptr: *const u8, plan_len: u32) -> u6
 /// term's codec-encoded object out. An operator the field does not answer
 /// is `STATUS_ENCODING` naming the field, as a mistyped value is, before
 /// the cipher is consulted; the refusals the typed path makes before a term
-/// exists (a range the wrong way round, match text that cuts no token or
-/// does not normalize) are `STATUS_TERM`, also before the cipher. The input
+/// exists (match text that cuts no token or does not normalize) are
+/// `STATUS_TERM`, also before the cipher. A range the wrong way round is
+/// not refused: it matches no row, as SQL's `BETWEEN` does. The input
 /// buffer is wiped in place.
 ///
 /// # Safety

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

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

languages/golang/encrypt/query.go

@@ -108,8 +108,9 @@ func (l Limit) FetchOr(page uint64) uint64 {
 // that answers the operator, and derives that index's term under the
 // field's context; for a field that names an EQL type it runs the type's
 // query. An operator the field does not answer, or one the engine does not
-// know, is [ErrEncoding] naming the field, as a mistyped value is; a range
-// the wrong way round, and match text that cuts no token, are [ErrTerm].
+// know, is [ErrEncoding] naming the field, as a mistyped value is; match
+// text that cuts no token is [ErrTerm]. A range the wrong way round is not
+// refused: it matches no row, as SQL's BETWEEN does.
 // No data key is minted. For generated code.
 func (cph *Cipher) QueryTerm(ctx context.Context, plan *record.Plan, field, operator string, input any) (QueryTerm, error) {
 	p, err := cph.queryPlan(plan, field)

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/0007-bindings-enter-through-a-plan-never-a-second-executor.md

@@ -228,9 +228,10 @@ orderings through an ORE index over an integer, or OPE when the field
 declares no ORE. A field that does not answer the operator is refused with
 the same shape of error as a mistyped field: an input error naming the field,
 with the reason `operator_not_answered` (or `unknown_operator`,
-`not_a_range`). The refusals the typed path makes before a term exists, a
-range the wrong way round and match text that cuts no token, are refused the
-same way here, before the cipher is consulted.
+`not_a_range`). The refusal the typed path makes before a term exists,
+match text that cuts no token, is made the same way here, before the cipher
+is consulted. A range the wrong way round is not refused on either path: it
+matches no row, as SQL's `BETWEEN` does.
 
 **The term comes back with its query domain.** The guest's
 `se_query_term(input, plan, field, operator, options)` returns one object:

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

@@ -178,8 +178,8 @@ and `Matches` take the plaintext the index is declared over
 so the plan is checked against `S` either way, and the chain derives one
 term per plaintext under the one label. `check` is where a query is refused
 before any term exists: a match index whose declared case disagrees with its
-`downcase` option, a `Between` whose bounds are the wrong way round, a match
-query with no tokens. `AtPath<Op>` takes a path and `Op`'s input, and gains
+`downcase` option, a match query with no tokens. A `Between` whose bounds
+are the wrong way round is not refused: it matches no row, as SQL's does. `AtPath<Op>` takes a path and `Op`'s input, and gains
 its shape with the JSON index.
 
 The bound tightens per operator, through `TermFor<Op>`: any `QueryTerm`
@@ -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

@@ -70,7 +70,6 @@
 use serde::{Serialize, Serializer};
 
 use super::WireBytes;
-use std::cmp::Ordering;
 use std::fmt;
 
 use stack_kms::DataKeySource;
@@ -585,19 +584,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)?;
         }
@@ -612,33 +607,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
@@ -730,10 +698,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>,
@@ -1417,9 +1386,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| Tree::Array(vec![Tree::UInt32(lo), Tree::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"),
@@ -1431,7 +1398,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(_))),
                 };
@@ -1912,8 +1878,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| {
@@ -1990,53 +1956,30 @@ 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 = [
-            (Tree::Int32(-1), Tree::Int32(1)),
-            (Tree::Int64(-1), Tree::Int64(1)),
-            (Tree::UInt32(1), Tree::UInt32(2)),
-            (Tree::UInt64(1), Tree::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(&Tree::UInt32(1)), &vf(&Tree::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 = Tree::Array(vec![Tree::Int64(65), Tree::Int64(18)]);
+        assert!(check_query(
+            &users(),
+            "score",
+            OpSpec::Between,
+            vf(&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]