lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

commit 0b0a3cb91c41b0d72d42182f368d85e021bba877
parent 661819f911f8bc90be28a11278c9163b81074b4a
Author: triesap <tyson@radroots.org>
Date:   Thu, 22 Oct 2026 16:09:44 +0000

domain: Validate bounded measurement pricing

- Require ordered positive measurement bounds and a feasible currency cap.
- Reuse exact half-even line arithmetic for same-unit final measurements.
- Refuse range, unit and cap violations with input-free typed errors.
- Verify portable features, API boundaries and unchanged coverage gates.

Diffstat:
Mcontracts/api_baselines/radroots_domain.txt | 16++++++++++++++++
Mcrates/domain/README.md | 8++++++++
Mcrates/domain/src/lib.rs | 2++
Mcrates/domain/src/pricing.rs | 14+++++++++++++-
Acrates/domain/src/variable_price.rs | 108+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Acrates/domain/tests/variable_price.rs | 274+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 421 insertions(+), 1 deletion(-)

diff --git a/contracts/api_baselines/radroots_domain.txt b/contracts/api_baselines/radroots_domain.txt @@ -194,9 +194,13 @@ impl core::fmt::Display for radroots_domain::MoneyError pub fn radroots_domain::MoneyError::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result #[non_exhaustive] pub enum radroots_domain::PricingError pub radroots_domain::PricingError::ArithmeticOutOfRange +pub radroots_domain::PricingError::CapExceeded pub radroots_domain::PricingError::InvalidDiscount pub radroots_domain::PricingError::InvalidLineCount +pub radroots_domain::PricingError::InvalidMeasurementRange pub radroots_domain::PricingError::InvalidTierOrder +pub radroots_domain::PricingError::MeasurementOutOfRange +pub radroots_domain::PricingError::MeasurementUnitMismatch pub radroots_domain::PricingError::Money(radroots_domain::MoneyError) pub radroots_domain::PricingError::TooManyTiers impl core::convert::From<radroots_domain::MoneyError> for radroots_domain::PricingError @@ -714,6 +718,18 @@ impl serde_core::ser::Serialize for radroots_domain::UnixSeconds pub fn radroots_domain::UnixSeconds::serialize<S: serde_core::ser::Serializer>(&self, S) -> core::result::Result<<S as serde_core::ser::Serializer>::Ok, <S as serde_core::ser::Serializer>::Error> impl<'de> serde_core::de::Deserialize<'de> for radroots_domain::UnixSeconds pub fn radroots_domain::UnixSeconds::deserialize<D: serde_core::de::Deserializer<'de>>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> +pub struct radroots_domain::VariableWeight +impl radroots_domain::VariableWeight +pub const fn radroots_domain::VariableWeight::basis(self) -> radroots_domain::PositiveDecimal +pub const fn radroots_domain::VariableWeight::maximum(self) -> radroots_domain::PositiveDecimal +pub const fn radroots_domain::VariableWeight::maximum_total(self) -> radroots_domain::Money +pub const fn radroots_domain::VariableWeight::measurement_unit(self) -> radroots_domain::listing::MeasurementUnit +pub const fn radroots_domain::VariableWeight::minimum(self) -> radroots_domain::PositiveDecimal +pub fn radroots_domain::VariableWeight::new(radroots_domain::listing::MeasurementUnit, radroots_domain::PositiveDecimal, radroots_domain::PositiveDecimal, radroots_domain::Money, radroots_domain::PositiveDecimal, radroots_domain::Money) -> core::result::Result<Self, radroots_domain::PricingError> +pub const fn radroots_domain::VariableWeight::rate(self) -> radroots_domain::Money +pub fn radroots_domain::VariableWeight::total_at(self, radroots_domain::Quantity) -> core::result::Result<radroots_domain::Money, radroots_domain::PricingError> +impl core::fmt::Debug for radroots_domain::VariableWeight +pub fn radroots_domain::VariableWeight::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result pub struct radroots_domain::WorkspaceId(_) impl radroots_domain::WorkspaceId pub const fn radroots_domain::WorkspaceId::as_bytes(&self) -> &[u8; 32] diff --git a/crates/domain/README.md b/crates/domain/README.md @@ -41,6 +41,14 @@ sale options validate selected amounts against their minimum, increment and integral package/count rules. Advertised supply establishes no quantity ceiling or actual availability. Complete listing/term integration remains separate. +`VariableWeight` retains a positive inclusive measurement range, exact rate and +basis, and an explicit same-currency maximum total. Its minimum is feasible +within the cap. Final measurements must use the declared unit, remain in range, +and recompute within the cap using the same half-even engine without a discount. +An in-range measurement can still exceed the cap and require refusal; this does +not amend the terms or consume stock. Offer/line scaling and installation remain +the responsibility of complete enclosing validated terms and execution. + Order, thread, workspace, executor and operation IDs have distinct Rust types. Each stores 32 bytes and uses exactly 64 lowercase hexadecimal characters in strings and JSON. Byte/string construction validates representation; generation diff --git a/crates/domain/src/lib.rs b/crates/domain/src/lib.rs @@ -16,6 +16,7 @@ mod message; mod money; mod pricing; mod quantity; +mod variable_price; /// The identity-owned validated participant key; no second key type is defined. pub use radroots_identity::PublicKey; @@ -42,3 +43,4 @@ pub use pricing::{ checked_order_total, }; pub use quantity::{ContentMeasure, Quantity, QuantityError}; +pub use variable_price::VariableWeight; diff --git a/crates/domain/src/pricing.rs b/crates/domain/src/pricing.rs @@ -192,7 +192,7 @@ pub fn checked_order_total( Ok(total) } -fn net_line_minor( +pub(crate) fn net_line_minor( rate: MinorAmount, amount: PositiveDecimal, basis: PositiveDecimal, @@ -249,6 +249,14 @@ pub enum PricingError { InvalidTierOrder, /// An aggregate has no lines or exceeds 32 lines. InvalidLineCount, + /// Measurement bounds are inverted or contain fractional each counts. + InvalidMeasurementRange, + /// The final measurement uses a different explicit unit. + MeasurementUnitMismatch, + /// A final measurement is outside the authorized inclusive range. + MeasurementOutOfRange, + /// The exact recomputed price exceeds the explicit monetary cap. + CapExceeded, /// A checked intermediate operation could not be represented. ArithmeticOutOfRange, /// The monetary bound or exact currency invariant was violated. @@ -268,6 +276,10 @@ impl fmt::Display for PricingError { Self::TooManyTiers => "too many price tiers", Self::InvalidTierOrder => "price thresholds must strictly increase", Self::InvalidLineCount => "invalid priced line count", + Self::InvalidMeasurementRange => "invalid measurement range", + Self::MeasurementUnitMismatch => "measurement unit differs from authorized unit", + Self::MeasurementOutOfRange => "measurement is outside authorized range", + Self::CapExceeded => "measurement price exceeds authorized cap", Self::ArithmeticOutOfRange => "pricing arithmetic exceeds supported bounds", Self::Money(error) => return error.fmt(f), }) diff --git a/crates/domain/src/variable_price.rs b/crates/domain/src/variable_price.rs @@ -0,0 +1,108 @@ +use crate::{ + DiscountBps, Money, MoneyError, PositiveDecimal, PricingError, Quantity, + listing::MeasurementUnit, pricing::net_line_minor, +}; +use core::fmt; + +/// Bounded measurement-price data, without agreement installation or stock. +/// The enclosing offer or agreement determines whether bounds describe one +/// sale unit or one complete line; this value performs no implicit scaling. +#[derive(Clone, Copy, Eq, PartialEq)] +#[cfg_attr(feature = "serde", derive(serde::Serialize))] +pub struct VariableWeight { + measurement_unit: MeasurementUnit, + minimum: PositiveDecimal, + maximum: PositiveDecimal, + rate: Money, + basis: PositiveDecimal, + maximum_total: Money, +} + +impl VariableWeight { + /// Checks inclusive positive bounds, count units, currency and a feasible cap. + /// The cap may restrict the range's more expensive measurements; the minimum + /// must remain admissible. Zero rate/cap are explicit, not quote-required. + pub fn new( + measurement_unit: MeasurementUnit, + minimum: PositiveDecimal, + maximum: PositiveDecimal, + rate: Money, + basis: PositiveDecimal, + maximum_total: Money, + ) -> Result<Self, PricingError> { + if minimum > maximum + || Quantity::new(minimum.amount(), measurement_unit).is_err() + || Quantity::new(maximum.amount(), measurement_unit).is_err() + { + return Err(PricingError::InvalidMeasurementRange); + } + if rate.currency() != maximum_total.currency() { + return Err(MoneyError::CurrencyMismatch.into()); + } + let value = Self { + measurement_unit, + minimum, + maximum, + rate, + basis, + maximum_total, + }; + value.total(minimum)?; + Ok(value) + } + + /// Returns the exact authorized measurement identity. + pub const fn measurement_unit(self) -> MeasurementUnit { + self.measurement_unit + } + /// Returns the inclusive positive lower bound. + pub const fn minimum(self) -> PositiveDecimal { + self.minimum + } + /// Returns the inclusive positive upper bound. + pub const fn maximum(self) -> PositiveDecimal { + self.maximum + } + /// Returns the exact currency/rate used for final measurement pricing. + pub const fn rate(self) -> Money { + self.rate + } + /// Returns the strictly positive measurement price basis. + pub const fn basis(self) -> PositiveDecimal { + self.basis + } + /// Returns the explicit monetary authorization ceiling. + pub const fn maximum_total(self) -> Money { + self.maximum_total + } + + /// Prices an exact same-unit in-range measurement and enforces the cap. + /// No implicit conversion, discount, amendment or physical consumption occurs. + pub fn total_at(self, measurement: Quantity) -> Result<Money, PricingError> { + if measurement.unit() != self.measurement_unit { + return Err(PricingError::MeasurementUnitMismatch); + } + if measurement.amount() < self.minimum.amount() + || measurement.amount() > self.maximum.amount() + { + return Err(PricingError::MeasurementOutOfRange); + } + let amount = PositiveDecimal::new(measurement.amount()) + .map_err(|_| PricingError::MeasurementOutOfRange)?; + self.total(amount) + } + + fn total(self, amount: PositiveDecimal) -> Result<Money, PricingError> { + let minor = net_line_minor(self.rate.minor(), amount, self.basis, DiscountBps::NONE)?; + if minor > self.maximum_total.minor() { + return Err(PricingError::CapExceeded); + } + Ok(Money::new(self.rate.currency(), minor)) + } +} + +impl fmt::Debug for VariableWeight { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("VariableWeight(<redacted>)") + } +} diff --git a/crates/domain/tests/variable_price.rs b/crates/domain/tests/variable_price.rs @@ -0,0 +1,274 @@ +use radroots_domain::listing::MeasurementUnit::{self, Each, Gram, Kilogram, Litre}; +use radroots_domain::{Money, MoneyError, PricingError, Quantity, VariableWeight}; +use std::error::Error; + +fn money(value: &str) -> Money { + Money::from_parts("CAD", value, 2).unwrap() +} +fn quantity(value: &str, unit: MeasurementUnit) -> Quantity { + Quantity::new(value.parse().unwrap(), unit).unwrap() +} +fn bounds(minimum: &str, maximum: &str, rate: &str, basis: &str, cap: &str) -> VariableWeight { + VariableWeight::new( + Kilogram, + minimum.parse().unwrap(), + maximum.parse().unwrap(), + money(rate), + basis.parse().unwrap(), + money(cap), + ) + .unwrap() +} + +#[test] +fn inclusive_measurement_bounds_recompute_exact_minor_prices_with_the_shared_rule() { + let value = bounds("0.8", "1.2", "325", "1", "400"); + assert_eq!(value.measurement_unit(), Kilogram); + assert_eq!(value.minimum().to_string(), "0.8"); + assert_eq!(value.maximum().to_string(), "1.2"); + assert_eq!(value.rate(), money("325")); + assert_eq!(value.basis().to_string(), "1"); + assert_eq!(value.maximum_total(), money("400")); + for (measurement, expected) in [ + ("0.8", "260"), + ("0.9", "292"), + ("0.98", "318"), + ("1.02", "332"), + ("1.2", "390"), + ] { + assert_eq!( + value.total_at(quantity(measurement, Kilogram)).unwrap(), + money(expected) + ); + } +} + +#[test] +fn final_measurements_cannot_silently_convert_units_or_extend_the_range() { + let value = bounds("0.8", "1.2", "325", "1", "400"); + for measurement in ["0", "0.799999", "1.200001", "999999999999"] { + assert_eq!( + value.total_at(quantity(measurement, Kilogram)), + Err(PricingError::MeasurementOutOfRange) + ); + } + for measurement in [ + quantity("800", Gram), + quantity("1", Litre), + quantity("1", Each), + ] { + assert_eq!( + value.total_at(measurement), + Err(PricingError::MeasurementUnitMismatch) + ); + } + assert_eq!( + value + .total_at(quantity("800", Gram).convert(Kilogram).unwrap()) + .unwrap(), + money("260") + ); +} + +#[test] +fn cap_and_physical_range_are_joint_constraints_without_implicit_amendment() { + let value = bounds("0.8", "1.2", "325", "1", "300"); + assert_eq!( + value.total_at(quantity("0.8", Kilogram)).unwrap(), + money("260") + ); + assert_eq!( + value.total_at(quantity("0.9", Kilogram)).unwrap(), + money("292") + ); + assert_eq!( + value.total_at(quantity("1", Kilogram)), + Err(PricingError::CapExceeded) + ); + assert_eq!( + value.total_at(quantity("1.2", Kilogram)), + Err(PricingError::CapExceeded) + ); + assert_eq!(value.maximum().to_string(), "1.2"); + assert_eq!(value.maximum_total(), money("300")); + assert_eq!( + VariableWeight::new( + Kilogram, + "0.8".parse().unwrap(), + "1.2".parse().unwrap(), + money("325"), + "1".parse().unwrap(), + money("259") + ), + Err(PricingError::CapExceeded) + ); + assert!( + VariableWeight::new( + Kilogram, + "0.8".parse().unwrap(), + "1.2".parse().unwrap(), + money("325"), + "1".parse().unwrap(), + money("260") + ) + .is_ok() + ); +} + +#[test] +fn constructors_validate_order_count_units_and_exact_currency_before_capture() { + assert_eq!( + VariableWeight::new( + Kilogram, + "1.2".parse().unwrap(), + "0.8".parse().unwrap(), + money("325"), + "1".parse().unwrap(), + money("400") + ), + Err(PricingError::InvalidMeasurementRange) + ); + for (minimum, maximum) in [("1.5", "3"), ("1", "3.5")] { + assert_eq!( + VariableWeight::new( + Each, + minimum.parse().unwrap(), + maximum.parse().unwrap(), + money("100"), + "1".parse().unwrap(), + money("400") + ), + Err(PricingError::InvalidMeasurementRange) + ); + } + let value = VariableWeight::new( + Each, + "2".parse().unwrap(), + "4".parse().unwrap(), + money("101"), + "2".parse().unwrap(), + money("202"), + ) + .unwrap(); + assert_eq!(value.total_at(quantity("3", Each)).unwrap(), money("152")); + assert_eq!(value.total_at(quantity("4", Each)).unwrap(), money("202")); + for cap in [ + Money::from_parts("USD", "400", 2).unwrap(), + Money::from_parts("JPY", "400", 0).unwrap(), + ] { + assert_eq!( + VariableWeight::new( + Kilogram, + "0.8".parse().unwrap(), + "1.2".parse().unwrap(), + money("325"), + "1".parse().unwrap(), + cap + ), + Err(PricingError::Money(MoneyError::CurrencyMismatch)) + ); + } + let exact = bounds("1", "1", "325", "1", "325"); + assert_eq!( + exact.total_at(quantity("1", Kilogram)).unwrap(), + money("325") + ); +} + +#[test] +fn free_and_large_exact_inputs_remain_bounded_without_float_or_zero_fallbacks() { + let free = bounds("0.000001", "999999999999", "0", "0.000001", "0"); + for amount in ["0.000001", "1", "999999999999"] { + assert_eq!( + free.total_at(quantity(amount, Kilogram)).unwrap(), + money("0") + ); + } + let maximum = bounds( + "1", + "999999999999", + "999999999999999", + "999999999999", + "999999999999999", + ); + assert_eq!( + maximum.total_at(quantity("1", Kilogram)).unwrap(), + money("1000") + ); + assert_eq!( + maximum + .total_at(quantity("999999999999", Kilogram)) + .unwrap(), + money("999999999999999") + ); + let over = bounds( + "0.000001", + "999999999999", + "999999999999999", + "1", + "999999999999999", + ); + assert_eq!( + over.total_at(quantity("999999999999", Kilogram)), + Err(PricingError::Money(MoneyError::MinorOutOfRange)) + ); + assert_eq!( + VariableWeight::new( + Kilogram, + "1".parse().unwrap(), + "2".parse().unwrap(), + money("999999999999999"), + "0.000001".parse().unwrap(), + money("999999999999999") + ), + Err(PricingError::Money(MoneyError::MinorOutOfRange)) + ); +} + +#[test] +fn currency_exponents_do_not_change_the_minor_unit_rounding_rule() { + for (code, exponent) in [("JPY", 0), ("CAD", 2), ("KWD", 3), ("CLF", 4)] { + let rate = Money::from_parts(code, "101", exponent).unwrap(); + let value = VariableWeight::new( + Gram, + "0.5".parse().unwrap(), + "1".parse().unwrap(), + rate, + "1".parse().unwrap(), + rate, + ) + .unwrap(); + assert_eq!( + value.total_at(quantity("0.5", Gram)).unwrap(), + Money::from_parts(code, "50", exponent).unwrap() + ); + } +} + +#[test] +fn measurement_diagnostics_redact_terms_and_keep_fixed_failure_messages() { + let value = bounds("0.8", "1.2", "928174615", "1", "999999999999999"); + let debug = format!("{value:?}"); + assert!(!debug.contains("928174615")); + assert!(!debug.contains("CAD")); + for error in [ + PricingError::InvalidMeasurementRange, + PricingError::MeasurementUnitMismatch, + PricingError::MeasurementOutOfRange, + PricingError::CapExceeded, + ] { + assert!(!error.to_string().is_empty()); + assert!(!error.to_string().contains("928174615")); + assert!(error.source().is_none()); + } +} + +#[cfg(feature = "serde")] +#[test] +fn serialization_retains_complete_exact_bounded_measurement_terms() { + let value = bounds("0.8", "1.2", "325", "1", "400"); + assert_eq!( + serde_json::to_value(value).unwrap(), + serde_json::json!({"measurement_unit":"kg","minimum":"0.8","maximum":"1.2","rate":{"currency":"CAD","minor":"325","exponent":2},"basis":"1","maximum_total":{"currency":"CAD","minor":"400","exponent":2}}) + ); +}