docs/test(v3): float review follow-ups — dyadic fixture invariant, NaN caveat, order tripwire

- eql-scalars: correct the FLOAT4_FIXTURES comment — the values are dyadic
  rationals (n/2^k), not 'powers of two and halves'; add a keep-it-dyadic
  warning so a non-f32-exact fixture (e.g. 0.1) can't silently desync the oracle.
- eql-types: document NaN/-0.0/+-Inf special-value behaviour on the float8
  module (and point float4 at it) — NaN is never rejected server-side, so the
  caller-facing 'reject NaN client-side' guidance lives next to the types.
- float_special: add nan_order_position_is_deterministic_and_total, a tripwire
  locking the total+deterministic order the Block-ORE index relies on (without
  pinning NaN's unspecified direction).
- Drop the dangling reference to the removed U-001 upgrade note.

Author: tobyhede

crates/eql-scalars/src/lib.rs

@@ -507,8 +507,12 @@ pub const TEXT: ScalarSpec = ScalarSpec {
 
 /// `float4` fixture plaintexts — IEEE-754 strings parsed into `f32` in the SQLx
 /// harness (the catalog stays zero-dep). EVERY value is exactly representable in
-/// f32 (powers of two and halves), so the `real` round-trip is lossless and the
-/// f32→f64 widening before encryption is exact. The three pivots MUST be present
+/// f32 — each is a dyadic rational `n/2^k` (e.g. `2.25 = 9/4`, `0.25 = 1/4`,
+/// `1024 = 2^10`), the value class `real` stores losslessly — so the `real`
+/// round-trip is lossless and the f32→f64 widening before encryption is exact.
+/// Keep new fixtures dyadic: a value like `0.1` is NOT f32-exact, and the
+/// oracle's expected order (parsed `f32`) would then disagree with the value the
+/// `real` column actually rounds to. The three pivots MUST be present
 /// verbatim: `"-inf"` (min_pivot), `"0"` (origin/mid), `"inf"` (max_pivot).
 /// NaN and `-0.0` are deliberately excluded (see the `float_special` suite).
 /// Distinctness is enforced by `Fixture::Float` (above) and its guard test.

crates/eql-types/src/v3/float4.rs

@@ -8,6 +8,10 @@
 //! wire shape here is identical to [`crate::v3::float8`] — an 8-block `ob` term
 //! (`f64::ENCODED_LEN == 8`, same as `int8`). `float4` vs `float8` is purely a
 //! Postgres-surface distinction (column type, domain name).
+//!
+//! Special-value behaviour (`-0.0`, `±Inf`, and the **NaN is not rejected
+//! server-side — reject it client-side** caveat) is identical to `float8`; see
+//! [`crate::v3::float8`] for the full note.
 
 use schemars::{schema::RootSchema, schema_for};
 

crates/eql-types/src/v3/float8.rs

@@ -7,6 +7,20 @@
 //! (`Plaintext::Float`), so the wire shape is identical to
 //! [`crate::v3::float4`] — an 8-block `ob` term (`f64::ENCODED_LEN == 8`, same
 //! as `int8`).
+//!
+//! ## Special values (caller-facing)
+//!
+//! `-0.0` canonicalizes to `+0.0` (equal under `=`, IEEE-consistent) and
+//! `±Inf` order correctly (`-Inf < finite < +Inf`). **NaN is unordered and
+//! unspecified in the encoder**: it can be encrypted, stored, and pass the
+//! domain CHECK, but it carries **no comparison guarantee** and does NOT follow
+//! IEEE semantics (where NaN compares false against everything). The domain
+//! CHECK validates only the envelope — it cannot inspect the ciphertext — so a
+//! NaN payload is never rejected server-side. **Reject NaN client-side before
+//! encryption** if your column must not contain it; otherwise a NaN row sorts
+//! at an arbitrary (but deterministic) position in an encrypted range scan
+//! rather than being excluded the way native Postgres `double precision` would.
+//! See the `float_special` regression suite for the locked behaviour.
 
 use schemars::{schema::RootSchema, schema_for};
 

tests/sqlx/tests/encrypted_domain/float_special.rs

@@ -130,3 +130,56 @@ async fn infinities_order_correctly() -> Result<()> {
     assert!(ord_cmp(&pool, &p[0], "<", &p[2]).await?, "-Inf < +Inf");
     Ok(())
 }
+
+#[tokio::test]
+async fn nan_order_position_is_deterministic_and_total() -> Result<()> {
+    // TRIPWIRE for encoder drift — NOT a direction guarantee.
+    //
+    // NaN is "unordered and unspecified" by design, so we deliberately do NOT
+    // pin WHERE NaN sorts relative to finite / ±Inf values (that position is an
+    // encoder artifact and may change). But the Block-ORE index the `_ord`
+    // domain rides on requires a *total, deterministic* order: the same
+    // plaintext must always land at the same position, and every pair must
+    // resolve to exactly one of `<` / `=` / `>`. If a future encoder change
+    // makes NaN's position non-deterministic (same bits, different sort slot ->
+    // btree corruption) or non-total (a comparison that follows IEEE and returns
+    // false both ways), this fails loudly. The NaN==NaN equality artifact is
+    // locked separately in `two_encryptions_of_same_nan_bits_compare_equal`;
+    // this guards the ORDER side of the same deterministic-terms property.
+    let pool = setup().await?;
+    // Two independent encryptions of canonical NaN, plus a spread of references.
+    let p = encrypt_specials(&[
+        F8(f64::NAN),          // 0: NaN (encryption A)
+        F8(f64::NAN),          // 1: NaN (encryption B)
+        F8(f64::NEG_INFINITY), // 2
+        F8(0.0),               // 3
+        F8(f64::INFINITY),     // 4
+    ])
+    .await?;
+    let (nan_a, nan_b) = (&p[0], &p[1]);
+
+    for (label, r) in [("-Inf", &p[2]), ("0", &p[3]), ("+Inf", &p[4])] {
+        let lt = ord_cmp(&pool, nan_a, "<", r).await?;
+        let eq = ord_cmp(&pool, nan_a, "=", r).await?;
+        let gt = ord_cmp(&pool, nan_a, ">", r).await?;
+        // Totality: exactly one of < = > holds (NaN is NOT IEEE-incomparable here).
+        assert_eq!(
+            [lt, eq, gt].iter().filter(|b| **b).count(),
+            1,
+            "NaN vs {label} is not a total order: (<, =, >) = ({lt}, {eq}, {gt})"
+        );
+        // Determinism: a second independent NaN encryption lands identically.
+        let (lt_b, eq_b, gt_b) = (
+            ord_cmp(&pool, nan_b, "<", r).await?,
+            ord_cmp(&pool, nan_b, "=", r).await?,
+            ord_cmp(&pool, nan_b, ">", r).await?,
+        );
+        assert_eq!(
+            (lt, eq, gt),
+            (lt_b, eq_b, gt_b),
+            "NaN's order position vs {label} is not stable across re-encryption \
+             (deterministic index terms broken)"
+        );
+    }
+    Ok(())
+}