lib

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

commit 3ef5f73f9b54e45df2f81b695cace0d950858b02
parent 63d23057a75e069ef809cb0f60ffb30620895602
Author: triesap <tyson@radroots.org>
Date:   Sat, 24 Oct 2026 16:21:54 +0000

domain: add exact physical stock pool values

- Bound ticks and explicit pool precision without implicit rounding or unit conversion.
- Validate conservation across all seven disjoint physical categories.
- Keep pool projections separate from authenticated stock authority and effects.
- Verify native, bare-metal, WASM and generated public API contracts.

Diffstat:
Mcontracts/api_baselines/radroots_domain.txt | 80+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mcontracts/architecture/decisions/shared_sdk_refactor.v1.json | 17+++++++++++++++++
Mcrates/domain/README.md | 11+++++++++++
Mcrates/domain/src/identifier.rs | 4++++
Mcrates/domain/src/lib.rs | 4+++-
Acrates/domain/src/stock.rs | 293+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Acrates/domain/tests/stock.rs | 254+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mtools/xtask/src/architecture/decision_package.rs | 15+++++++++++++++
8 files changed, 677 insertions(+), 1 deletion(-)

diff --git a/contracts/api_baselines/radroots_domain.txt b/contracts/api_baselines/radroots_domain.txt @@ -158,6 +158,72 @@ pub fn radroots_domain::listing::SaleUnit::package(&str, radroots_domain::Conten pub fn radroots_domain::listing::SaleUnit::package_unspecified(&str) -> core::result::Result<Self, radroots_domain::listing::ListingError> impl core::fmt::Debug for radroots_domain::listing::SaleUnit pub fn radroots_domain::listing::SaleUnit::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub mod radroots_domain::stock +#[non_exhaustive] pub enum radroots_domain::stock::StockError +pub radroots_domain::stock::StockError::ConservationViolation +pub radroots_domain::stock::StockError::FractionalCount +pub radroots_domain::stock::StockError::InvalidFormat +pub radroots_domain::stock::StockError::InvalidScale +pub radroots_domain::stock::StockError::OutOfRange +pub radroots_domain::stock::StockError::PrecisionLoss +pub radroots_domain::stock::StockError::Underflow +pub radroots_domain::stock::StockError::UnitMismatch +impl core::error::Error for radroots_domain::stock::StockError +impl core::fmt::Display for radroots_domain::stock::StockError +pub fn radroots_domain::stock::StockError::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub struct radroots_domain::stock::PhysicalBalances +pub radroots_domain::stock::PhysicalBalances::available: radroots_domain::stock::StockTicks +pub radroots_domain::stock::PhysicalBalances::committed_hold: radroots_domain::stock::StockTicks +pub radroots_domain::stock::PhysicalBalances::consumed: radroots_domain::stock::StockTicks +pub radroots_domain::stock::PhysicalBalances::physical_quarantine: radroots_domain::stock::StockTicks +pub radroots_domain::stock::PhysicalBalances::preparatory_hold: radroots_domain::stock::StockTicks +pub radroots_domain::stock::PhysicalBalances::removed: radroots_domain::stock::StockTicks +pub radroots_domain::stock::PhysicalBalances::waste: radroots_domain::stock::StockTicks +impl radroots_domain::stock::PhysicalBalances +pub const radroots_domain::stock::PhysicalBalances::ZERO: Self +impl core::fmt::Debug for radroots_domain::stock::PhysicalBalances +pub fn radroots_domain::stock::PhysicalBalances::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub struct radroots_domain::stock::PoolBalances +impl radroots_domain::stock::PoolBalances +pub const fn radroots_domain::stock::PoolBalances::introduced(self) -> radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::PoolBalances::new(radroots_domain::stock::StockTicks, radroots_domain::stock::PhysicalBalances) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub const fn radroots_domain::stock::PoolBalances::physical(self) -> radroots_domain::stock::PhysicalBalances +impl core::fmt::Debug for radroots_domain::stock::PoolBalances +pub fn radroots_domain::stock::PoolBalances::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub struct radroots_domain::stock::PoolSnapshot +impl radroots_domain::stock::PoolSnapshot +pub const fn radroots_domain::stock::PoolSnapshot::balances(self) -> radroots_domain::stock::PoolBalances +pub const fn radroots_domain::stock::PoolSnapshot::id(self) -> radroots_domain::PoolId +pub const fn radroots_domain::stock::PoolSnapshot::new(radroots_domain::PoolId, radroots_domain::stock::PoolUnit, radroots_domain::stock::PoolBalances, radroots_domain::Sequence) -> Self +pub const fn radroots_domain::stock::PoolSnapshot::unit(self) -> radroots_domain::stock::PoolUnit +pub const fn radroots_domain::stock::PoolSnapshot::version(self) -> radroots_domain::Sequence +impl core::fmt::Debug for radroots_domain::stock::PoolSnapshot +pub fn radroots_domain::stock::PoolSnapshot::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub struct radroots_domain::stock::PoolUnit +impl radroots_domain::stock::PoolUnit +pub const fn radroots_domain::stock::PoolUnit::new(radroots_domain::listing::MeasurementUnit, u8) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub const fn radroots_domain::stock::PoolUnit::scale(self) -> u8 +pub fn radroots_domain::stock::PoolUnit::ticks_for(self, radroots_domain::Quantity) -> core::result::Result<radroots_domain::stock::StockTicks, radroots_domain::stock::StockError> +pub const fn radroots_domain::stock::PoolUnit::unit(self) -> radroots_domain::listing::MeasurementUnit +pub struct radroots_domain::stock::StockTicks(_) +impl radroots_domain::stock::StockTicks +pub const radroots_domain::stock::StockTicks::MAX: Self +pub const radroots_domain::stock::StockTicks::ZERO: Self +pub fn radroots_domain::stock::StockTicks::checked_add(self, Self) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::StockTicks::checked_sub(self, Self) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub const fn radroots_domain::stock::StockTicks::get(self) -> u64 +pub const fn radroots_domain::stock::StockTicks::new(u64) -> core::result::Result<Self, radroots_domain::stock::StockError> +impl core::fmt::Debug for radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::StockTicks::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::fmt::Display for radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::StockTicks::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::str::traits::FromStr for radroots_domain::stock::StockTicks +pub type radroots_domain::stock::StockTicks::Err = radroots_domain::stock::StockError +pub fn radroots_domain::stock::StockTicks::from_str(&str) -> core::result::Result<Self, Self::Err> +impl serde_core::ser::Serialize for radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::StockTicks::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::stock::StockTicks +pub fn radroots_domain::stock::StockTicks::deserialize<D: serde_core::de::Deserializer<'de>>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> #[non_exhaustive] pub enum radroots_domain::ActorRole pub radroots_domain::ActorRole::Buyer pub radroots_domain::ActorRole::Coordinator @@ -881,6 +947,20 @@ impl serde_core::ser::Serialize for radroots_domain::OrderId pub fn radroots_domain::OrderId::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::OrderId pub fn radroots_domain::OrderId::deserialize<D: serde_core::de::Deserializer<'de>>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> +pub struct radroots_domain::PoolId(_) +impl radroots_domain::PoolId +pub const fn radroots_domain::PoolId::as_bytes(&self) -> &[u8; 32] +pub const fn radroots_domain::PoolId::from_bytes([u8; 32]) -> Self +pub const fn radroots_domain::PoolId::into_bytes(self) -> [u8; 32] +impl core::fmt::Display for radroots_domain::PoolId +pub fn radroots_domain::PoolId::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::str::traits::FromStr for radroots_domain::PoolId +pub type radroots_domain::PoolId::Err = radroots_domain::IdentifierError +pub fn radroots_domain::PoolId::from_str(&str) -> core::result::Result<Self, Self::Err> +impl serde_core::ser::Serialize for radroots_domain::PoolId +pub fn radroots_domain::PoolId::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::PoolId +pub fn radroots_domain::PoolId::deserialize<D: serde_core::de::Deserializer<'de>>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> pub struct radroots_domain::PositiveDecimal(_) impl radroots_domain::PositiveDecimal pub const fn radroots_domain::PositiveDecimal::amount(self) -> radroots_domain::Decimal diff --git a/contracts/architecture/decisions/shared_sdk_refactor.v1.json b/contracts/architecture/decisions/shared_sdk_refactor.v1.json @@ -515,6 +515,23 @@ "rounding": "half_even_once_per_net_line_then_checked_sum", "binding_numbers": "exact_decimal_or_integer_strings", "stock_ticks_max": 1000000000000000000, + "stock_scale_max": 6, + "stock_units": [ + "g", + "kg", + "mL", + "L", + "each" + ], + "stock_physical_categories": [ + "available", + "preparatory_hold", + "committed_hold", + "physical_quarantine", + "consumed", + "waste", + "removed" + ], "generation_max": 9223372036854775807 }, "limits": { diff --git a/crates/domain/README.md b/crates/domain/README.md @@ -42,6 +42,17 @@ authorization or stock. `Quantity` uses the existing measurement identity and exact decimal bounds. Conversions between g/kg and mL/L are explicit and reject precision loss; arithmetic requires matching units. `each` counts remain integral. + +`stock` supplies exact pool values for the durable-executor implementation. +`StockTicks` admits canonical integer strings from0 through10^18; JSON numbers +are rejected. `PoolUnit` requires an explicit physical unit and precision0–6, +with integral `each` counts. Quantity conversion rejects rounding and implicit +unit changes. `PoolBalances` checks the sum of available, preparatory hold, +committed hold, physical quarantine, consumed, waste and removed against +introduced stock. Released stock is a movement, and promises or deficits cannot +fill a physical balance. A `PoolSnapshot` retains a distinct pool ID and declared +revision. These data claims grant no write permission or stock authority. + `ContentMeasure` descriptors distinguish fixed, estimated and unspecified contents; estimates do not provide fixed conversions or stock backing. Existing sale options validate selected amounts against their minimum, increment and diff --git a/crates/domain/src/identifier.rs b/crates/domain/src/identifier.rs @@ -135,6 +135,10 @@ identifier!( ); identifier!(ExecutorId, "An exact 256-bit selected executor identifier."); identifier!( + PoolId, + "An exact 256-bit physical stock pool identifier, not authority." +); +identifier!( OperationId, "An exact 256-bit retained operation identifier." ); diff --git a/crates/domain/src/lib.rs b/crates/domain/src/lib.rs @@ -19,6 +19,8 @@ mod message; mod money; mod pricing; mod quantity; +/// Exact physical stock values; these are neither authority nor a stock store. +pub mod stock; mod time; mod variable_price; @@ -49,7 +51,7 @@ pub use fulfillment::{FulfillmentError, PrivateFulfillment}; pub use identifier::{ AgreementLineId, ApprovalIntentDigest, CheckpointDigest, CommandDigest, EnvelopeEventId, ExecutorId, FulfillmentGroupId, GrantId, IdentifierError, ListingOptionId, MessageId, - OperationId, OrderId, RecordId, RouteDigest, RumorEventId, SigningAttemptId, SourceId, + OperationId, OrderId, PoolId, RecordId, RouteDigest, RumorEventId, SigningAttemptId, SourceId, TermsDigest, ThreadId, TransactionId, WorkspaceId, }; pub use issuance::{FIRST_ISSUANCE_MAX_SECONDS, IssuanceWindow}; diff --git a/crates/domain/src/stock.rs b/crates/domain/src/stock.rs @@ -0,0 +1,293 @@ +//! Pure physical-stock values. A balanced snapshot proves no provenance, +//! availability, permission, selected executor or durable stock effect. + +use crate::{PoolId, Quantity, Sequence, listing::MeasurementUnit}; +use core::{fmt, str::FromStr}; + +/// A bounded, input-free stock value failure. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +#[non_exhaustive] +pub enum StockError { + /// Integer input is not a canonical unsigned decimal string. + InvalidFormat, + /// Ticks exceed the supported maximum, including checked addition. + OutOfRange, + /// Subtraction would produce a negative balance. + Underflow, + /// A pool scale exceeds six fractional decimal places. + InvalidScale, + /// Each-count pools cannot have fractional precision. + FractionalCount, + /// The declared quantity and pool use different units. + UnitMismatch, + /// The quantity cannot be represented by integral pool ticks. + PrecisionLoss, + /// The seven physical categories do not sum to introduced stock. + ConservationViolation, +} +impl fmt::Display for StockError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(match self { + Self::InvalidFormat => "stock ticks must be a canonical unsigned integer", + Self::OutOfRange => "stock ticks exceed the supported bound", + Self::Underflow => "stock balance would be negative", + Self::InvalidScale => "stock scale exceeds six decimal places", + Self::FractionalCount => "each-count stock requires integral precision", + Self::UnitMismatch => "stock quantity unit differs from pool unit", + Self::PrecisionLoss => "stock quantity cannot be represented by integral ticks", + Self::ConservationViolation => { + "physical stock categories do not conserve introduced stock" + } + }) + } +} +impl core::error::Error for StockError {} + +/// Exact integral pool ticks, including zero, bounded by10^18. +#[derive(Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)] +pub struct StockTicks(u64); +impl StockTicks { + /// Largest admitted physical balance in ticks. + pub const MAX: Self = Self(1_000_000_000_000_000_000); + /// Exact zero ticks. + pub const ZERO: Self = Self(0); + /// Validates an integral Rust input; this grants no stock authority. + pub const fn new(value: u64) -> Result<Self, StockError> { + if value > Self::MAX.0 { + return Err(StockError::OutOfRange); + } + Ok(Self(value)) + } + /// Returns the exact integer; foreign numeric boundaries use integer strings. + pub const fn get(self) -> u64 { + self.0 + } + /// Adds ticks without wrapping or exceeding the stock bound. + pub fn checked_add(self, other: Self) -> Result<Self, StockError> { + Self::new(self.0.checked_add(other.0).ok_or(StockError::OutOfRange)?) + } + /// Subtracts ticks without clamping a negative result to zero. + pub fn checked_sub(self, other: Self) -> Result<Self, StockError> { + Self::new(self.0.checked_sub(other.0).ok_or(StockError::Underflow)?) + } +} +impl FromStr for StockTicks { + type Err = StockError; + fn from_str(value: &str) -> Result<Self, Self::Err> { + if value.is_empty() + || value.len() > 19 + || !value.bytes().all(|v| v.is_ascii_digit()) + || (value.len() > 1 && value.starts_with('0')) + { + return Err(StockError::InvalidFormat); + } + Self::new(value.parse().map_err(|_| StockError::OutOfRange)?) + } +} +impl fmt::Display for StockTicks { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + self.0.fmt(f) + } +} +impl fmt::Debug for StockTicks { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("StockTicks(<redacted>)") + } +} +#[cfg(feature = "serde")] +impl serde::Serialize for StockTicks { + fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> { + serializer.collect_str(self) + } +} +#[cfg(feature = "serde")] +impl<'de> serde::Deserialize<'de> for StockTicks { + fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> { + struct Visitor; + impl serde::de::Visitor<'_> for Visitor { + type Value = StockTicks; + fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("bounded stock ticks as a canonical integer string") + } + fn visit_str<E: serde::de::Error>(self, value: &str) -> Result<StockTicks, E> { + value.parse().map_err(E::custom) + } + } + deserializer.deserialize_str(Visitor) + } +} + +/// One explicit physical unit and fractional precision for an entire pool. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct PoolUnit { + unit: MeasurementUnit, + scale: u8, +} +impl PoolUnit { + /// Admits precision0–6, with scale zero for each counts. + pub const fn new(unit: MeasurementUnit, scale: u8) -> Result<Self, StockError> { + if scale > 6 { + return Err(StockError::InvalidScale); + } + if matches!(unit, MeasurementUnit::Each) && scale != 0 { + return Err(StockError::FractionalCount); + } + Ok(Self { unit, scale }) + } + /// Returns the fixed pool unit, without converting another unit. + pub const fn unit(self) -> MeasurementUnit { + self.unit + } + /// Returns fractional decimal places represented by one tick. + pub const fn scale(self) -> u8 { + self.scale + } + /// Converts only an exactly matching declared unit and precision. Compatible + /// unit conversion must be requested explicitly on `Quantity` beforehand. + pub fn ticks_for(self, quantity: Quantity) -> Result<StockTicks, StockError> { + if quantity.unit() != self.unit { + return Err(StockError::UnitMismatch); + } + let amount = quantity.amount(); + let difference = self + .scale + .checked_sub(amount.scale()) + .ok_or(StockError::PrecisionLoss)?; + let factor = 10_u64.pow(u32::from(difference)); + StockTicks::new( + amount + .coefficient() + .checked_mul(factor) + .ok_or(StockError::OutOfRange)?, + ) + } +} + +/// Seven disjoint claimed balances. Validate their total with `PoolBalances`. +/// Released quantities are movements back to available, never an eighth balance. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct PhysicalBalances { + /// Unheld physical stock. + pub available: StockTicks, + /// Physical stock held before commitment issuance is resolved. + pub preparatory_hold: StockTicks, + /// Remaining physical backing of installed commitments. + pub committed_hold: StockTicks, + /// Physical backing retained under unresolved risk. + pub physical_quarantine: StockTicks, + /// Cumulative physical stock consumed by handover. + pub consumed: StockTicks, + /// Cumulative physically present stock moved to waste. + pub waste: StockTicks, + /// Cumulative physical stock explicitly removed. + pub removed: StockTicks, +} +impl PhysicalBalances { + /// All seven categories are empty. + pub const ZERO: Self = Self { + available: StockTicks::ZERO, + preparatory_hold: StockTicks::ZERO, + committed_hold: StockTicks::ZERO, + physical_quarantine: StockTicks::ZERO, + consumed: StockTicks::ZERO, + waste: StockTicks::ZERO, + removed: StockTicks::ZERO, + }; +} +impl fmt::Debug for PhysicalBalances { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("PhysicalBalances(<redacted>)") + } +} + +/// A conservation-checked physical balance claim, without authority or effects. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct PoolBalances { + introduced: StockTicks, + physical: PhysicalBalances, +} +impl PoolBalances { + /// Admits only an exact sum of the seven disjoint physical categories. + /// Future promises and obligation deficits cannot be counted as stock. + pub fn new(introduced: StockTicks, physical: PhysicalBalances) -> Result<Self, StockError> { + let values = [ + physical.available, + physical.preparatory_hold, + physical.committed_hold, + physical.physical_quarantine, + physical.consumed, + physical.waste, + physical.removed, + ]; + let sum = values + .into_iter() + .try_fold(StockTicks::ZERO, StockTicks::checked_add)?; + if sum != introduced { + return Err(StockError::ConservationViolation); + } + Ok(Self { + introduced, + physical, + }) + } + /// Returns cumulative introduced physical stock, including positive corrections. + pub const fn introduced(self) -> StockTicks { + self.introduced + } + /// Returns the seven conservation-checked balances. + pub const fn physical(self) -> PhysicalBalances { + self.physical + } +} +impl fmt::Debug for PoolBalances { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("PoolBalances(<redacted>)") + } +} + +/// A versioned claimed pool projection. Authentication and durable version +/// admission belong to the selected executor, never this value constructor. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct PoolSnapshot { + id: PoolId, + unit: PoolUnit, + balances: PoolBalances, + version: Sequence, +} +impl PoolSnapshot { + /// Combines already-validated values; version zero is an explicit genesis. + pub const fn new( + id: PoolId, + unit: PoolUnit, + balances: PoolBalances, + version: Sequence, + ) -> Self { + Self { + id, + unit, + balances, + version, + } + } + /// Returns the declared pool identity. + pub const fn id(self) -> PoolId { + self.id + } + /// Returns this pool's fixed unit/precision. + pub const fn unit(self) -> PoolUnit { + self.unit + } + /// Returns the validated physical balance claim. + pub const fn balances(self) -> PoolBalances { + self.balances + } + /// Returns the declared pool revision; this is not an authority generation. + pub const fn version(self) -> Sequence { + self.version + } +} +impl fmt::Debug for PoolSnapshot { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("PoolSnapshot(<redacted>)") + } +} diff --git a/crates/domain/tests/stock.rs b/crates/domain/tests/stock.rs @@ -0,0 +1,254 @@ +use radroots_domain::stock::{ + PhysicalBalances, PoolBalances, PoolSnapshot, PoolUnit, StockError, StockTicks, +}; +use radroots_domain::{Decimal, PoolId, Quantity, Sequence, listing::MeasurementUnit::*}; + +fn ticks(value: u64) -> StockTicks { + StockTicks::new(value).unwrap() +} + +#[test] +fn tick_bounds_and_canonical_integer_strings_never_round_or_wrap() { + for value in [ + 0, + 1, + 9_007_199_254_740_991, + 9_007_199_254_740_993, + StockTicks::MAX.get(), + ] { + let exact = ticks(value); + assert_eq!( + exact.to_string().parse::<StockTicks>().unwrap().get(), + value + ); + } + for value in [StockTicks::MAX.get() + 1, u64::MAX] { + assert_eq!(StockTicks::new(value), Err(StockError::OutOfRange)); + } + for value in [ + "", + "00", + "01", + "+1", + "-1", + "1.0", + "1e3", + " 1", + "1\n", + "1", + "١", + "10000000000000000000", + ] { + assert!(value.parse::<StockTicks>().is_err(), "{value:?}"); + } + assert_eq!( + "1000000000000000001".parse::<StockTicks>(), + Err(StockError::OutOfRange) + ); + assert_eq!( + StockTicks::MAX.checked_add(ticks(1)), + Err(StockError::OutOfRange) + ); + assert_eq!( + StockTicks::ZERO.checked_sub(ticks(1)), + Err(StockError::Underflow) + ); + assert_eq!( + StockTicks::MAX.checked_sub(StockTicks::MAX), + Ok(StockTicks::ZERO) + ); +} + +#[test] +fn every_physical_unit_has_explicit_precision_and_each_is_integral() { + for unit in [Gram, Kilogram, Millilitre, Litre, Each] { + for scale in 0..=6 { + let result = PoolUnit::new(unit, scale); + if unit == Each && scale != 0 { + assert_eq!(result, Err(StockError::FractionalCount)); + } else { + let value = result.unwrap(); + assert_eq!(value.unit(), unit); + assert_eq!(value.scale(), scale); + } + } + for scale in [7, u8::MAX] { + assert_eq!(PoolUnit::new(unit, scale), Err(StockError::InvalidScale)); + } + } +} + +#[test] +fn quantities_convert_to_integral_ticks_only_with_exact_explicit_pool_units() { + for unit in [Gram, Kilogram, Millilitre, Litre] { + for (amount, scale, expected) in [ + ("0", 0, 0), + ("1.25", 2, 125), + ("0.000001", 6, 1), + ("999999999999", 6, 999_999_999_999_000_000), + ] { + let quantity = Quantity::new(amount.parse().unwrap(), unit).unwrap(); + let pool = PoolUnit::new(unit, scale).unwrap(); + assert_eq!(pool.ticks_for(quantity).unwrap().get(), expected); + } + let quantity = Quantity::new("1.000001".parse().unwrap(), unit).unwrap(); + for scale in 0..6 { + assert_eq!( + PoolUnit::new(unit, scale).unwrap().ticks_for(quantity), + Err(StockError::PrecisionLoss) + ); + } + let quantity = Quantity::new(Decimal::ONE, unit).unwrap(); + for other in [Gram, Kilogram, Millilitre, Litre, Each] { + if other != unit { + assert_eq!( + PoolUnit::new(other, 0).unwrap().ticks_for(quantity), + Err(StockError::UnitMismatch) + ); + } + } + } + let kg = Quantity::new("1.25".parse().unwrap(), Kilogram).unwrap(); + let gram_pool = PoolUnit::new(Gram, 0).unwrap(); + assert_eq!(gram_pool.ticks_for(kg), Err(StockError::UnitMismatch)); + assert_eq!( + gram_pool.ticks_for(kg.convert(Gram).unwrap()).unwrap(), + ticks(1250) + ); + let each = Quantity::new("999999999999".parse().unwrap(), Each).unwrap(); + assert_eq!( + PoolUnit::new(Each, 0).unwrap().ticks_for(each).unwrap(), + ticks(999_999_999_999) + ); +} + +#[test] +fn every_category_is_counted_once_and_released_stock_is_a_movement() { + for position in 0..7 { + let mut physical = PhysicalBalances::ZERO; + let target = match position { + 0 => &mut physical.available, + 1 => &mut physical.preparatory_hold, + 2 => &mut physical.committed_hold, + 3 => &mut physical.physical_quarantine, + 4 => &mut physical.consumed, + 5 => &mut physical.waste, + 6 => &mut physical.removed, + _ => unreachable!(), + }; + *target = StockTicks::MAX; + let exact = PoolBalances::new(StockTicks::MAX, physical).unwrap(); + assert_eq!(exact.physical(), physical); + assert_eq!(exact.introduced(), StockTicks::MAX); + assert!(PoolBalances::new(ticks(StockTicks::MAX.get() - 1), physical).is_err()); + } + let before = PhysicalBalances { + available: ticks(70), + preparatory_hold: ticks(30), + ..PhysicalBalances::ZERO + }; + let after = PhysicalBalances { + available: ticks(100), + ..PhysicalBalances::ZERO + }; + assert!(PoolBalances::new(ticks(100), before).is_ok()); + assert!(PoolBalances::new(ticks(100), after).is_ok()); + // Treating the release as introduced stock would double count it. + assert_eq!( + PoolBalances::new(ticks(130), after), + Err(StockError::ConservationViolation) + ); +} + +#[test] +fn mixed_physical_categories_conserve_and_promises_or_deficits_cannot_fill_a_gap() { + let physical = PhysicalBalances { + available: ticks(1), + preparatory_hold: ticks(2), + committed_hold: ticks(3), + physical_quarantine: ticks(4), + consumed: ticks(5), + waste: ticks(6), + removed: ticks(7), + }; + let balances = PoolBalances::new(ticks(28), physical).unwrap(); + assert_eq!(balances.physical(), physical); + for introduced in [0, 27, 29] { + assert_eq!( + PoolBalances::new(ticks(introduced), physical), + Err(StockError::ConservationViolation) + ); + } + let over = PhysicalBalances { + available: StockTicks::MAX, + waste: StockTicks::MAX, + ..PhysicalBalances::ZERO + }; + assert_eq!( + PoolBalances::new(StockTicks::MAX, over), + Err(StockError::OutOfRange) + ); + assert_eq!( + PoolBalances::new(ticks(1), PhysicalBalances::ZERO), + Err(StockError::ConservationViolation) + ); +} + +#[test] +fn snapshots_keep_pool_identity_precision_and_declared_version_distinct() { + let id = PoolId::from_bytes([7; 32]); + let balances = PoolBalances::new( + ticks(5), + PhysicalBalances { + available: ticks(5), + ..PhysicalBalances::ZERO + }, + ) + .unwrap(); + let unit = PoolUnit::new(Kilogram, 3).unwrap(); + let version = Sequence::new(0).unwrap(); + let snapshot = PoolSnapshot::new(id, unit, balances, version); + assert_eq!(snapshot.id(), id); + assert_eq!(snapshot.unit(), unit); + assert_eq!(snapshot.balances(), balances); + assert_eq!(snapshot.version(), version); + assert!( + !format!( + "{snapshot:?} {balances:?} {:?} {:?}", + balances.physical(), + ticks(123456789) + ) + .contains("123456789") + ); +} + +#[cfg(feature = "serde")] +#[test] +fn foreign_tick_serialization_uses_exact_strings_and_rejects_json_numbers() { + for value in [ + StockTicks::ZERO, + ticks(9_007_199_254_740_993), + StockTicks::MAX, + ] { + let wire = serde_json::to_string(&value).unwrap(); + assert_eq!(wire, format!("\"{value}\"")); + assert_eq!(serde_json::from_str::<StockTicks>(&wire).unwrap(), value); + } + for value in [ + "0", + "9007199254740993", + "1.0", + "null", + "true", + "[]", + "{}", + "\"01\"", + "\"1e3\"", + "\"1000000000000000001\"", + ] { + assert!( + serde_json::from_str::<StockTicks>(value).is_err(), + "{value}" + ); + } +} diff --git a/tools/xtask/src/architecture/decision_package.rs b/tools/xtask/src/architecture/decision_package.rs @@ -149,6 +149,9 @@ struct Values { rounding: String, binding_numbers: String, stock_ticks_max: u64, + stock_scale_max: u8, + stock_units: Vec<String>, + stock_physical_categories: Vec<String>, generation_max: u64, } @@ -510,6 +513,18 @@ fn validate_values(v: &Values, limits: &BTreeMap<String, u64>) -> Result<(), Str && v.rounding == "half_even_once_per_net_line_then_checked_sum" && v.binding_numbers == "exact_decimal_or_integer_strings" && v.stock_ticks_max == 1_000_000_000_000_000_000 + && v.stock_scale_max == 6 + && v.stock_units == ["g", "kg", "mL", "L", "each"] + && v.stock_physical_categories + == [ + "available", + "preparatory_hold", + "committed_hold", + "physical_quarantine", + "consumed", + "waste", + "removed", + ] && v.generation_max == i64::MAX as u64, "exact economics, registry or binding value contract drift", )?;