commit d2bbf19bdbc5c465d2a9ea5194ce57488a48c68e
parent 8d2e9658c36af2266451b5165d2fb4da59653ac3
Author: triesap <tyson@radroots.org>
Date: Sun, 25 Oct 2026 01:29:15 +0000
domain: calculate exact preparatory stock transfers
- Transfer positive available ticks into proposed preparatory backing.
- Preserve lifetime introduced and every other physical category.
- Refuse unavailable quantities without borrowing held stock.
- Verify capacity, conservation, API and portable value checks.
Diffstat:
3 files changed, 85 insertions(+), 0 deletions(-)
diff --git a/contracts/api_baselines/radroots_domain.txt b/contracts/api_baselines/radroots_domain.txt
@@ -236,6 +236,7 @@ pub fn radroots_domain::stock::PhysicalBalances::deserialize<D: serde_core::de::
pub struct radroots_domain::stock::PoolBalances
impl radroots_domain::stock::PoolBalances
pub fn radroots_domain::stock::PoolBalances::correct_available(self, radroots_domain::stock::AvailableStockCorrection, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError>
+pub fn radroots_domain::stock::PoolBalances::hold_available(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError>
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
diff --git a/crates/domain/src/stock.rs b/crates/domain/src/stock.rs
@@ -254,6 +254,19 @@ impl PoolBalances {
pub const fn physical(self) -> PhysicalBalances {
self.physical
}
+ /// Proposes a positive transfer from available to preparatory backing.
+ /// Lifetime introduced and all other categories remain unchanged. This
+ /// value performs no reservation; the executor must atomically confirm its
+ /// authority, complete allocation, versions and order/operation fence.
+ pub fn hold_available(self, quantity: StockTicks) -> Result<Self, StockError> {
+ if quantity == StockTicks::ZERO {
+ return Err(StockError::ZeroMovement);
+ }
+ let mut physical = self.physical;
+ physical.available = physical.available.checked_sub(quantity)?;
+ physical.preparatory_hold = physical.preparatory_hold.checked_add(quantity)?;
+ Self::new(self.introduced, physical)
+ }
/// Proposes a nonzero, exact correction against available backing only.
/// Held or quarantined stock is never silently substituted for available
/// stock. Depleting it needs a separate obligation/deficit transition.
diff --git a/crates/domain/tests/stock.rs b/crates/domain/tests/stock.rs
@@ -8,6 +8,77 @@ fn ticks(value: u64) -> StockTicks {
}
#[test]
+fn proposed_holds_conserve_stock_and_cannot_borrow_other_physical_categories() {
+ let physical = PhysicalBalances {
+ available: ticks(30),
+ preparatory_hold: ticks(10),
+ committed_hold: ticks(20),
+ physical_quarantine: ticks(5),
+ consumed: ticks(15),
+ waste: ticks(10),
+ removed: ticks(10),
+ };
+ let original = PoolBalances::new(ticks(100), physical).unwrap();
+ let first = original.hold_available(ticks(10)).unwrap();
+ assert_eq!(first.introduced(), original.introduced());
+ assert_eq!(
+ first.physical(),
+ PhysicalBalances {
+ available: ticks(20),
+ preparatory_hold: ticks(20),
+ ..physical
+ }
+ );
+ let full = first.hold_available(ticks(20)).unwrap();
+ assert_eq!(full.introduced(), original.introduced());
+ assert_eq!(
+ full.physical(),
+ PhysicalBalances {
+ available: StockTicks::ZERO,
+ preparatory_hold: ticks(40),
+ ..physical
+ }
+ );
+ assert_eq!(
+ original.hold_available(ticks(31)),
+ Err(StockError::Underflow)
+ );
+ assert_eq!(full.hold_available(ticks(1)), Err(StockError::Underflow));
+ assert_eq!(
+ original.hold_available(StockTicks::ZERO),
+ Err(StockError::ZeroMovement)
+ );
+ assert_eq!(original.physical(), physical);
+}
+
+#[test]
+fn proposed_holds_reach_the_exact_supported_capacity_without_wrap_or_float() {
+ let original = PoolBalances::new(
+ StockTicks::MAX,
+ PhysicalBalances {
+ available: ticks(1),
+ preparatory_hold: ticks(StockTicks::MAX.get() - 1),
+ ..PhysicalBalances::ZERO
+ },
+ )
+ .unwrap();
+ assert_eq!(
+ original.hold_available(ticks(2)),
+ Err(StockError::Underflow)
+ );
+ let held = original.hold_available(ticks(1)).unwrap();
+ assert_eq!(held.introduced(), StockTicks::MAX);
+ assert_eq!(
+ held.physical(),
+ PhysicalBalances {
+ preparatory_hold: StockTicks::MAX,
+ ..PhysicalBalances::ZERO
+ }
+ );
+ assert_eq!(held.hold_available(ticks(1)), Err(StockError::Underflow));
+}
+
+#[test]
fn available_corrections_conserve_audited_totals_without_touching_backed_claims() {
use radroots_domain::stock::AvailableStockCorrection::{Add, Remove, Spoil};
let original = PoolBalances::new(