feat(payload): improve BoundedProbability ergonomics for adoption

lading_payload/src/common/config.rs

@@ -2,7 +2,7 @@
 
 use rand::{RngExt, distr::uniform::SampleUniform};
 use serde::Deserialize;
-use std::{cmp, fmt};
+use std::{cmp, fmt, hash};
 
 /// Range expression for configuration
 #[derive(Debug, Deserialize, serde::Serialize, Clone, PartialEq, Copy)]
@@ -89,7 +89,7 @@ where
 /// equal to `+0.0` under IEEE-754 numeric ordering.
 const NEG_ZERO_AS_BITS: u32 = 0x8000_0000;
 
-/// Error returned when a value cannot be turned into a [`Probability`].
+/// Error returned when a value cannot be turned into a [`BoundedProbability`].
 #[derive(Debug, thiserror::Error, Clone, Copy)]
 pub enum ProbabilityError {
     /// Value is [`f32::NAN`], [`f32::INFINITY`], or [`f32::NEG_INFINITY`].
@@ -147,42 +147,95 @@ pub enum ProbabilityError {
 ///   before storage. This canonical-bit-pattern guarantee is what makes hashing
 ///   on `value.to_bits()` consistent with numeric equality.
 ///
+/// Two type aliases are provided for the bounds that actually occur in lading
+/// payload configuration today; callers should prefer them over spelling the
+/// bit pattern at the use site. Define additional aliases as new bounds appear.
+///
 /// # Example
 ///
 /// ```
-/// use lading_payload::common::config::Probability;
+/// use lading_payload::common::config::{BoundedProbability, Probability};
 ///
-/// type AtLeastHalf = Probability<{ f32::to_bits(0.5) }>;
-/// let p = AtLeastHalf::try_new(0.75).expect("0.75 is in [0.5, 1.0]");
+/// // For the common `[0.0, 1.0]` case, use the `Probability` alias.
+/// let p = Probability::try_new(0.75).expect("0.75 is in [0.0, 1.0]");
 /// assert_eq!(p.get(), 0.75);
+///
+/// // For other lower bounds, parameterize `BoundedProbability` directly.
+/// type AtLeastHalf = BoundedProbability<{ f32::to_bits(0.5) }>;
+/// let q = AtLeastHalf::try_new(0.75).expect("0.75 is in [0.5, 1.0]");
+/// assert_eq!(q.get(), 0.75);
 /// ```
 #[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
 #[serde(into = "f32", try_from = "f32")]
-pub struct Probability<const MIN_AS_BITS: u32> {
+pub struct BoundedProbability<const MIN_AS_BITS: u32> {
     value: f32,
 }
 
-impl<const MIN_AS_BITS: u32> TryFrom<f32> for Probability<MIN_AS_BITS> {
+/// A probability in the closed unit interval `[0.0, 1.0]`. The most common bound.
+pub type Probability = BoundedProbability<{ f32::to_bits(0.0) }>;
+
+/// A probability or ratio in `[0.1, 1.0]`. Use for fields that must avoid
+/// extreme low values.
+pub type AtLeastOneTenth = BoundedProbability<{ f32::to_bits(0.1) }>;
+
+/// A probability or ratio in `[0.01, 1.0]`. Use for fields such as
+/// `unique_tag_ratio` that must avoid extreme low values but admit
+/// in-the-wild values below `0.1`.
+pub type AtLeastOneHundredth = BoundedProbability<{ f32::to_bits(0.01) }>;
+
+impl<const MIN_AS_BITS: u32> TryFrom<f32> for BoundedProbability<MIN_AS_BITS> {
     type Error = ProbabilityError;
 
     fn try_from(value: f32) -> Result<Self, Self::Error> {
         Self::try_new(value)
     }
 }
 
-impl<const MIN_AS_BITS: u32> From<Probability<MIN_AS_BITS>> for f32 {
-    fn from(p: Probability<MIN_AS_BITS>) -> Self {
+impl<const MIN_AS_BITS: u32> From<BoundedProbability<MIN_AS_BITS>> for f32 {
+    fn from(p: BoundedProbability<MIN_AS_BITS>) -> Self {
         p.value
     }
 }
 
-impl<const MIN_AS_BITS: u32> fmt::Display for Probability<MIN_AS_BITS> {
+impl<const MIN_AS_BITS: u32> fmt::Display for BoundedProbability<MIN_AS_BITS> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         fmt::Display::fmt(&self.value, f)
     }
 }
 
-impl<const MIN_AS_BITS: u32> Probability<MIN_AS_BITS> {
+// `Eq`, `Ord`, and `Hash` are sound because [`Self::try_new`] rejects NaN and
+// normalizes `-0.0` to `+0.0`, so every value in the valid range has a unique
+// bit pattern and an unambiguous numeric ordering. `Hash` works on the `u32`
+// bit pattern because `f32: !Hash`; the `Eq`/`Hash` contract is preserved
+// because numerically equal valid values share a bit pattern.
+
+impl<const MIN_AS_BITS: u32> PartialEq for BoundedProbability<MIN_AS_BITS> {
+    fn eq(&self, other: &Self) -> bool {
+        self.value == other.value
+    }
+}
+
+impl<const MIN_AS_BITS: u32> Eq for BoundedProbability<MIN_AS_BITS> {}
+
+impl<const MIN_AS_BITS: u32> Ord for BoundedProbability<MIN_AS_BITS> {
+    fn cmp(&self, other: &Self) -> cmp::Ordering {
+        self.value.total_cmp(&other.value)
+    }
+}
+
+impl<const MIN_AS_BITS: u32> PartialOrd for BoundedProbability<MIN_AS_BITS> {
+    fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl<const MIN_AS_BITS: u32> hash::Hash for BoundedProbability<MIN_AS_BITS> {
+    fn hash<H: hash::Hasher>(&self, state: &mut H) {
+        self.value.to_bits().hash(state);
+    }
+}
+
+impl<const MIN_AS_BITS: u32> BoundedProbability<MIN_AS_BITS> {
     /// The lower bound decoded from `MIN_AS_BITS`.
     ///
     /// The `assert!`s here run at const-evaluation time for every
@@ -208,7 +261,7 @@ impl<const MIN_AS_BITS: u32> Probability<MIN_AS_BITS> {
     /// `[MIN, +1.0]` and is not [`f32::NAN`], [`f32::INFINITY`], or
     /// [`f32::NEG_INFINITY`]. A `-0.0` input is normalized to `+0.0`.
     ///
-    /// This is a `const fn`, so callers can build a [`Probability`] in a
+    /// This is a `const fn`, so callers can build a [`BoundedProbability`] in a
     /// `const` context by matching on the returned [`Result`]; the validation
     /// then runs at compile time.
     ///
@@ -243,16 +296,49 @@ impl<const MIN_AS_BITS: u32> Probability<MIN_AS_BITS> {
     pub const fn get(&self) -> f32 {
         self.value
     }
+
+    /// Sample a Bernoulli trial with success probability `self.get()`.
+    ///
+    /// Returns `true` with probability `self.get()` and `false` otherwise.
+    /// The f32 <-> f64 conversion is exact for every f32 in `[+0.0, +1.0]`, so
+    /// the success probability is preserved bit-for-bit.
+    #[must_use]
+    pub fn sample_bernoulli<R>(&self, rng: &mut R) -> bool
+    where
+        R: rand::Rng + ?Sized,
+    {
+        rng.random_bool(f64::from(self.value))
+    }
+}
+
+/// Generate a uniformly-distributed-over-bit-patterns value in `[MIN, +1.0]`
+/// by sampling a `u32` in `[MIN_AS_BITS, f32::to_bits(+1.0)]` and decoding it.
+///
+/// This works because the f32 <-> u32 ordering (documented on the type) is
+/// monotonic for non-negative finite values, so every bit pattern in that
+/// range decodes to a valid stored value. `-0.0`'s bit pattern is
+/// `0x8000_0000`, far above `f32::to_bits(+1.0) = 0x3f80_0000`, so it can
+/// never be generated.
+#[cfg(feature = "arbitrary")]
+impl<'a, const MIN_AS_BITS: u32> arbitrary::Arbitrary<'a> for BoundedProbability<MIN_AS_BITS> {
+    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
+        let bits = u.int_in_range(MIN_AS_BITS..=f32::to_bits(Self::MAX))?;
+        let value = f32::from_bits(bits);
+        // Routing through `try_new` fires the per-monomorphization const-eval
+        // bound check on `Self::MIN` and forwards any future invariant added
+        // to the constructor. The `expect` is safe by the argument above.
+        Ok(Self::try_new(value).expect("bits in [MIN_AS_BITS, MAX_AS_BITS] always valid"))
+    }
 }
 
 #[cfg(test)]
 mod probability_tests {
-    use super::{NEG_ZERO_AS_BITS, Probability, ProbabilityError};
+    use super::{BoundedProbability, NEG_ZERO_AS_BITS, ProbabilityError};
     use proptest::prelude::*;
 
-    type ZeroOrMore = Probability<{ f32::to_bits(0.0) }>;
-    type AtLeastHalf = Probability<{ f32::to_bits(0.5) }>;
-    type AtLeastOne = Probability<{ f32::to_bits(1.0) }>;
+    type ZeroOrMore = BoundedProbability<{ f32::to_bits(0.0) }>;
+    type AtLeastHalf = BoundedProbability<{ f32::to_bits(0.5) }>;
+    type AtLeastOne = BoundedProbability<{ f32::to_bits(1.0) }>;
 
     // ===== Unit tests: constants =====
 
@@ -308,6 +394,38 @@ mod probability_tests {
         }
     }
 
+    // ===== Unit tests: ordering / equality / hashing =====
+
+    #[test]
+    fn equality_holds_for_same_bit_pattern() {
+        let a = AtLeastHalf::try_new(0.75).expect("valid");
+        let b = AtLeastHalf::try_new(0.75).expect("valid");
+        let c = AtLeastHalf::try_new(0.875).expect("valid");
+        assert_eq!(a, b);
+        assert_ne!(a, c);
+    }
+
+    #[test]
+    fn ordering_matches_numeric_ordering() {
+        let half = AtLeastHalf::try_new(0.5).expect("valid");
+        let three_quarters = AtLeastHalf::try_new(0.75).expect("valid");
+        let one = AtLeastHalf::try_new(1.0).expect("valid");
+        assert!(half < three_quarters);
+        assert!(three_quarters < one);
+        assert!(half < one);
+    }
+
+    #[test]
+    fn hash_agrees_with_eq() {
+        use std::collections::HashSet;
+        let mut set = HashSet::new();
+        set.insert(AtLeastHalf::try_new(0.75).expect("valid"));
+        // Re-inserting the equivalent value must hit the existing entry.
+        assert!(!set.insert(AtLeastHalf::try_new(0.75).expect("valid")));
+        assert!(set.insert(AtLeastHalf::try_new(0.875).expect("valid")));
+        assert_eq!(set.len(), 2);
+    }
+
     // ===== Unit tests: wire-format pins =====
 
     #[test]
@@ -359,48 +477,55 @@ mod probability_tests {
     // ===== Property-test helpers (generic over MIN_AS_BITS) =====
 
     fn check_accepts_in_range<const MIN_AS_BITS: u32>(v: f32) {
-        let p = Probability::<MIN_AS_BITS>::try_new(v).expect("v should be valid by construction");
+        let p = BoundedProbability::<MIN_AS_BITS>::try_new(v)
+            .expect("v should be valid by construction");
         assert_eq!(p.get().to_bits(), v.to_bits());
     }
 
     fn check_rejects_below_min<const MIN_AS_BITS: u32>(v: f32) {
-        let err = Probability::<MIN_AS_BITS>::try_new(v).expect_err("v should be below MIN");
+        let err = BoundedProbability::<MIN_AS_BITS>::try_new(v).expect_err("v should be below MIN");
         match err {
             ProbabilityError::BelowMin { min, value } => {
-                assert_eq!(min.to_bits(), Probability::<MIN_AS_BITS>::MIN.to_bits());
+                assert_eq!(
+                    min.to_bits(),
+                    BoundedProbability::<MIN_AS_BITS>::MIN.to_bits()
+                );
                 assert_eq!(value.to_bits(), v.to_bits());
             }
             other => panic!("expected BelowMin, got {other:?}"),
         }
     }
 
     fn check_display_matches<const MIN_AS_BITS: u32>(v: f32) {
-        let p = Probability::<MIN_AS_BITS>::try_new(v).expect("valid v");
+        let p = BoundedProbability::<MIN_AS_BITS>::try_new(v).expect("valid v");
         assert_eq!(format!("{p}"), format!("{v}"));
     }
 
     fn check_display_precision<const MIN_AS_BITS: u32>(v: f32, n: usize) {
-        let p = Probability::<MIN_AS_BITS>::try_new(v).expect("valid v");
+        let p = BoundedProbability::<MIN_AS_BITS>::try_new(v).expect("valid v");
         assert_eq!(format!("{p:.n$}"), format!("{v:.n$}"));
     }
 
     fn check_serde_json_round_trip<const MIN_AS_BITS: u32>(v: f32) {
-        let p = Probability::<MIN_AS_BITS>::try_new(v).expect("valid v");
+        let p = BoundedProbability::<MIN_AS_BITS>::try_new(v).expect("valid v");
         let json = serde_json::to_string(&p).expect("serialize");
-        let back: Probability<MIN_AS_BITS> = serde_json::from_str(&json).expect("deserialize");
+        let back: BoundedProbability<MIN_AS_BITS> =
+            serde_json::from_str(&json).expect("deserialize");
         assert_eq!(back.get().to_bits(), v.to_bits());
     }
 
     fn check_serde_yaml_round_trip<const MIN_AS_BITS: u32>(v: f32) {
-        let p = Probability::<MIN_AS_BITS>::try_new(v).expect("valid v");
+        let p = BoundedProbability::<MIN_AS_BITS>::try_new(v).expect("valid v");
         let yaml = serde_yaml::to_string(&p).expect("serialize");
-        let back: Probability<MIN_AS_BITS> = serde_yaml::from_str(&yaml).expect("deserialize");
+        let back: BoundedProbability<MIN_AS_BITS> =
+            serde_yaml::from_str(&yaml).expect("deserialize");
         assert_eq!(back.get().to_bits(), v.to_bits());
     }
 
     fn check_serde_json_rejects_below_min<const MIN_AS_BITS: u32>(v: f32) {
         let json = serde_json::to_string(&v).expect("serialize raw f32");
-        let err = serde_json::from_str::<Probability<MIN_AS_BITS>>(&json).expect_err("v < MIN");
+        let err =
+            serde_json::from_str::<BoundedProbability<MIN_AS_BITS>>(&json).expect_err("v < MIN");
         assert!(
             err.to_string().contains("below lower bound"),
             "unexpected error: {err}"
@@ -409,7 +534,8 @@ mod probability_tests {
 
     fn check_serde_yaml_rejects_below_min<const MIN_AS_BITS: u32>(v: f32) {
         let yaml = serde_yaml::to_string(&v).expect("serialize raw f32");
-        let err = serde_yaml::from_str::<Probability<MIN_AS_BITS>>(&yaml).expect_err("v < MIN");
+        let err =
+            serde_yaml::from_str::<BoundedProbability<MIN_AS_BITS>>(&yaml).expect_err("v < MIN");
         assert!(
             err.to_string().contains("below lower bound"),
             "unexpected error: {err}"
@@ -474,6 +600,23 @@ mod probability_tests {
         }
     }
 
+    // ===== Property tests: ordering agrees with f32 PartialOrd =====
+
+    proptest! {
+        #[test]
+        fn ord_matches_f32_partial_cmp(
+            a in valid_value_strategy(ZeroOrMore::MIN),
+            b in valid_value_strategy(ZeroOrMore::MIN),
+        ) {
+            let pa = ZeroOrMore::try_new(a).expect("valid");
+            let pb = ZeroOrMore::try_new(b).expect("valid");
+            prop_assert_eq!(
+                pa.cmp(&pb),
+                a.partial_cmp(&b).expect("no NaN in valid range")
+            );
+        }
+    }
+
     // ===== Property tests: Display =====
 
     proptest! {
@@ -634,4 +777,74 @@ mod probability_tests {
             );
         }
     }
+
+    // ===== Property tests: Arbitrary impl (feature = "arbitrary") =====
+
+    #[cfg(feature = "arbitrary")]
+    fn check_arbitrary_produces_valid<const MIN_AS_BITS: u32>(bytes: &[u8]) {
+        use arbitrary::{Arbitrary, Unstructured};
+        let mut u = Unstructured::new(bytes);
+        // `int_in_range` can fail with `NotEnoughData` on short inputs; that's
+        // fine -- we only need to check that any `Ok` value is valid.
+        if let Ok(p) = BoundedProbability::<MIN_AS_BITS>::arbitrary(&mut u) {
+            let v = p.get();
+            assert!(v.is_finite());
+            assert_ne!(v.to_bits(), NEG_ZERO_AS_BITS);
+            assert!(v >= BoundedProbability::<MIN_AS_BITS>::MIN);
+            assert!(v <= BoundedProbability::<MIN_AS_BITS>::MAX);
+        }
+    }
+
+    #[cfg(feature = "arbitrary")]
+    proptest! {
+        #[test]
+        fn arbitrary_produces_valid_zero_or_more(
+            bytes in prop::collection::vec(any::<u8>(), 4..32),
+        ) {
+            check_arbitrary_produces_valid::<{ f32::to_bits(0.0) }>(&bytes);
+        }
+
+        #[test]
+        fn arbitrary_produces_valid_at_least_half(
+            bytes in prop::collection::vec(any::<u8>(), 4..32),
+        ) {
+            check_arbitrary_produces_valid::<{ f32::to_bits(0.5) }>(&bytes);
+        }
+
+        #[test]
+        fn arbitrary_produces_valid_at_least_one(
+            bytes in prop::collection::vec(any::<u8>(), 4..32),
+        ) {
+            check_arbitrary_produces_valid::<{ f32::to_bits(1.0) }>(&bytes);
+        }
+    }
+
+    // ===== Property tests: sample_bernoulli =====
+    //
+    // The degenerate `p = 0.0` and `p = 1.0` cases together pin both the
+    // wiring (no inversion of P(true) vs P(false)) and the absence of a
+    // panic from `random_bool`. A statistical test on intermediate values
+    // would only re-test `rand::Rng::random_bool`, so it is omitted.
+
+    proptest! {
+        #[test]
+        fn bernoulli_at_zero_never_succeeds(seed: u64) {
+            use rand::{SeedableRng, rngs::SmallRng};
+            let p = ZeroOrMore::try_new(0.0).expect("0.0 in [0, 1]");
+            let mut rng = SmallRng::seed_from_u64(seed);
+            for _ in 0..1024 {
+                prop_assert!(!p.sample_bernoulli(&mut rng));
+            }
+        }
+
+        #[test]
+        fn bernoulli_at_one_always_succeeds(seed: u64) {
+            use rand::{SeedableRng, rngs::SmallRng};
+            let p = AtLeastOne::try_new(1.0).expect("1.0 in [1, 1]");
+            let mut rng = SmallRng::seed_from_u64(seed);
+            for _ in 0..1024 {
+                prop_assert!(p.sample_bernoulli(&mut rng));
+            }
+        }
+    }
 }