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:
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",
)?;