lib

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

commit aec064e9d967cc3b912443743737234a21d11302
parent 280dbf50915dffe469487eb303d635369f3bc6b0
Author: triesap <tyson@radroots.org>
Date:   Thu, 29 Oct 2026 20:58:07 +0000

domain: reconcile held stock and obligation backing

- Add checked consumption, release, quarantine and held-loss value transitions.
- Keep deficits separate from physical capacity using a closed backing equation.
- Revalidate exact-string codecs and bind the prospective executor boundary.
- Verify stock regressions, no-std/WASM, consumer compilation and generated APIs.

Diffstat:
Mcontracts/api_baselines/radroots_domain.txt | 33+++++++++++++++++++++++++++++++++
Mcontracts/architecture/decisions/shared_sdk_refactor.v1.json | 12++++++++++++
Mcrates/domain/src/stock.rs | 11+++++++++--
Acrates/domain/src/stock/movements.rs | 150+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Acrates/domain/src/stock/obligation.rs | 111+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mcrates/domain/src/stock/serialization.rs | 28+++++++++++++++++++++++++++-
Acrates/domain/tests/stock_accounting.rs | 307+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mtools/xtask/src/architecture/decision_package.rs | 53+++++++++++++++++++++++++++++++++++++++++++++++++++++
8 files changed, 702 insertions(+), 3 deletions(-)

diff --git a/contracts/api_baselines/radroots_domain.txt b/contracts/api_baselines/radroots_domain.txt @@ -244,6 +244,13 @@ pub enum radroots_domain::stock::AvailableStockCorrection pub radroots_domain::stock::AvailableStockCorrection::Add pub radroots_domain::stock::AvailableStockCorrection::Remove pub radroots_domain::stock::AvailableStockCorrection::Spoil +pub enum radroots_domain::stock::HeldStockCategory +pub radroots_domain::stock::HeldStockCategory::Committed +pub radroots_domain::stock::HeldStockCategory::Preparatory +pub radroots_domain::stock::HeldStockCategory::Quarantined +pub enum radroots_domain::stock::HeldStockLoss +pub radroots_domain::stock::HeldStockLoss::Removal +pub radroots_domain::stock::HeldStockLoss::Spoilage #[non_exhaustive] pub enum radroots_domain::stock::MappingError pub radroots_domain::stock::MappingError::InvalidVersion pub radroots_domain::stock::MappingError::Quantity(radroots_domain::QuantityError) @@ -261,6 +268,7 @@ 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::ObligationMismatch pub radroots_domain::stock::StockError::OutOfRange pub radroots_domain::stock::StockError::PrecisionLoss pub radroots_domain::stock::StockError::Underflow @@ -280,6 +288,22 @@ pub const fn radroots_domain::stock::AllocationClaim::pool_id(self) -> radroots_ pub const fn radroots_domain::stock::AllocationClaim::quantity(self) -> radroots_domain::Quantity impl core::fmt::Debug for radroots_domain::stock::AllocationClaim pub fn radroots_domain::stock::AllocationClaim::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +pub struct radroots_domain::stock::ObligationBacking +impl radroots_domain::stock::ObligationBacking +pub const fn radroots_domain::stock::ObligationBacking::backed(self) -> radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::ObligationBacking::consume_backed(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub const fn radroots_domain::stock::ObligationBacking::deficit(self) -> radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::ObligationBacking::lose_backing(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::ObligationBacking::new(radroots_domain::stock::StockTicks, radroots_domain::stock::StockTicks, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::ObligationBacking::release_residual(self, radroots_domain::stock::StockTicks, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub const fn radroots_domain::stock::ObligationBacking::remaining(self) -> radroots_domain::stock::StockTicks +pub fn radroots_domain::stock::ObligationBacking::restore_backing(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +impl core::fmt::Debug for radroots_domain::stock::ObligationBacking +pub fn radroots_domain::stock::ObligationBacking::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl serde_core::ser::Serialize for radroots_domain::stock::ObligationBacking +pub fn radroots_domain::stock::ObligationBacking::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::ObligationBacking +pub fn radroots_domain::stock::ObligationBacking::deserialize<D: serde_core::de::Deserializer<'de>>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> pub struct radroots_domain::stock::OptionMappingKey impl radroots_domain::stock::OptionMappingKey pub const fn radroots_domain::stock::OptionMappingKey::listing(self) -> radroots_domain::listing::ListingCoordinate @@ -321,6 +345,15 @@ impl<'de> serde_core::de::Deserialize<'de> for radroots_domain::stock::PhysicalB pub fn radroots_domain::stock::PhysicalBalances::deserialize<D: serde_core::de::Deserializer<'de>>(D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> pub struct radroots_domain::stock::PoolBalances impl radroots_domain::stock::PoolBalances +pub fn radroots_domain::stock::PoolBalances::consume_committed(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::consume_quarantined(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::deplete_held(self, radroots_domain::stock::HeldStockCategory, radroots_domain::stock::HeldStockLoss, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::quarantine_committed(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::quarantine_preparatory(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::release_committed(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::release_quarantined(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +pub fn radroots_domain::stock::PoolBalances::restore_quarantined(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> +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 fn radroots_domain::stock::PoolBalances::install_preparatory(self, radroots_domain::stock::StockTicks) -> core::result::Result<Self, radroots_domain::stock::StockError> diff --git a/contracts/architecture/decisions/shared_sdk_refactor.v1.json b/contracts/architecture/decisions/shared_sdk_refactor.v1.json @@ -1086,6 +1086,18 @@ "delivery_attempts_per_target": 12, "first_issuance_seconds": 120 }, + "stock_accounting": { + "value_owner": "radroots_domain.stock", + "scope": "one_fixed_pool_unit", + "obligation_equation": "remaining = backed + deficit", + "ticks_max": 1000000000000000000, + "values_create_store_effects": false, + "deficit_counts_as_physical_stock": false, + "receipt_consumes_again": false, + "released_deficit_adds_available": false, + "loss_deletes_obligation": false, + "native_atomic_allocation_and_identity_required": true + }, "execution": { "ordinary_inventory_owner": { "owned_capture_method": "capture_stock_evidence", diff --git a/crates/domain/src/stock.rs b/crates/domain/src/stock.rs @@ -5,10 +5,14 @@ use crate::{PoolId, Quantity, Sequence, listing::MeasurementUnit}; use core::{fmt, str::FromStr}; mod allocation; mod mapping; +mod movements; +mod obligation; pub use allocation::{ AllocationClaim, AllocationPlanError, PoolHoldProposal, StockAllocation, plan_allocations, }; pub use mapping::{MappingError, OptionMappingKey, OptionPoolMapping}; +pub use movements::{HeldStockCategory, HeldStockLoss}; +pub use obligation::ObligationBacking; /// A bounded, input-free stock value failure. #[derive(Clone, Copy, Debug, Eq, PartialEq)] @@ -30,7 +34,9 @@ pub enum StockError { PrecisionLoss, /// The seven physical categories do not sum to introduced stock. ConservationViolation, - /// An audited physical movement cannot have zero quantity. + /// Backed remaining and deficit do not equal the remaining obligation. + ObligationMismatch, + /// An accounting movement cannot have zero quantity. ZeroMovement, } impl fmt::Display for StockError { @@ -46,7 +52,8 @@ impl fmt::Display for StockError { Self::ConservationViolation => { "physical stock categories do not conserve introduced stock" } - Self::ZeroMovement => "physical movement quantity must be positive", + Self::ObligationMismatch => "backing and deficit do not reconcile the obligation", + Self::ZeroMovement => "accounting movement quantity must be positive", }) } } diff --git a/crates/domain/src/stock/movements.rs b/crates/domain/src/stock/movements.rs @@ -0,0 +1,150 @@ +//! Pure movement proposals; durable admission and original allocation proof are external. +use super::{PoolBalances, StockError, StockTicks}; + +/// Physical backing held for an original operation or installed obligation. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum HeldStockCategory { + /// Original preparation whose issuance is not resolved. + Preparatory, + /// Remaining backing of an installed commitment. + Committed, + /// Backing retained under unresolved signature or business risk. + Quarantined, +} + +/// Depletion of genuinely present held stock, without deleting its obligation. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum HeldStockLoss { + /// Move the physical quantity into cumulative waste. + Spoilage, + /// Move the physical quantity into cumulative removed stock. + Removal, +} + +enum Destination { + Available, + Committed, + Quarantined, + Consumed, + Waste, + Removed, +} + +impl PoolBalances { + /// Proposes release of authorized unconsumed committed backing. The executor + /// must prove the exact residual and bilateral authority and atomically + /// retain the release movement; a timeout or missing ACK proves neither. + pub fn release_committed(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Committed, + Destination::Available, + quantity, + ) + } + + /// Proposes physical consumption of original committed backing. Exactly-once + /// handover identity, authority, residual and version checks belong to the + /// atomic executor. Buyer receipts must never call this movement again. + pub fn consume_committed(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Committed, + Destination::Consumed, + quantity, + ) + } + + /// Proposes retention of preparatory backing under unresolved issuance risk. + /// Expiry cannot release it or establish nonissuance. + pub fn quarantine_preparatory(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Preparatory, + Destination::Quarantined, + quantity, + ) + } + + /// Proposes retention of installed backing under unresolved risk. Original + /// allocation and obligation linkage must survive the actual transaction. + pub fn quarantine_committed(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Committed, + Destination::Quarantined, + quantity, + ) + } + + /// Proposes restoration to committed backing after qualified reconciliation. + /// This value neither resolves unknown issuance nor authorizes a retry. + pub fn restore_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Quarantined, + Destination::Committed, + quantity, + ) + } + + /// Proposes a release after original nonissuance or authorized residual + /// resolution is proven. An expired lease, query or absent record is no proof. + pub fn release_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Quarantined, + Destination::Available, + quantity, + ) + } + + /// Proposes consumption after original handover evidence is reconciled. The + /// executor must install the same handover once, retaining its original claim. + pub fn consume_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> { + self.transfer_held( + HeldStockCategory::Quarantined, + Destination::Consumed, + quantity, + ) + } + + /// Proposes depletion of actually present backing. It preserves lifetime + /// introduced stock and never releases capacity. The executor must retain + /// affected original claims and reconcile any outstanding obligation to a + /// deficit in the same transaction; this physical value cannot delete it. + pub fn deplete_held( + self, + category: HeldStockCategory, + loss: HeldStockLoss, + quantity: StockTicks, + ) -> Result<Self, StockError> { + let destination = match loss { + HeldStockLoss::Spoilage => Destination::Waste, + HeldStockLoss::Removal => Destination::Removed, + }; + self.transfer_held(category, destination, quantity) + } + + fn transfer_held( + self, + category: HeldStockCategory, + destination: Destination, + quantity: StockTicks, + ) -> Result<Self, StockError> { + if quantity == StockTicks::ZERO { + return Err(StockError::ZeroMovement); + } + let mut physical = self.physical(); + let source = match category { + HeldStockCategory::Preparatory => &mut physical.preparatory_hold, + HeldStockCategory::Committed => &mut physical.committed_hold, + HeldStockCategory::Quarantined => &mut physical.physical_quarantine, + }; + *source = source.checked_sub(quantity)?; + let target = match destination { + Destination::Available => &mut physical.available, + Destination::Committed => &mut physical.committed_hold, + Destination::Quarantined => &mut physical.physical_quarantine, + Destination::Consumed => &mut physical.consumed, + Destination::Waste => &mut physical.waste, + Destination::Removed => &mut physical.removed, + }; + *target = target.checked_add(quantity)?; + Self::new(self.introduced(), physical) + } +} diff --git a/crates/domain/src/stock/obligation.rs b/crates/domain/src/stock/obligation.rs @@ -0,0 +1,111 @@ +//! Outstanding obligations reconcile backing and deficits without creating stock. +use super::{StockError, StockTicks}; +use core::fmt; + +/// A checked remaining obligation in one fixed pool unit. Deficit is unbacked +/// obligation, never physical stock. Construction proves no original allocation, +/// permission, generation, causality or durable effect. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct ObligationBacking { + remaining: StockTicks, + backed: StockTicks, + deficit: StockTicks, +} + +impl ObligationBacking { + /// Requires exact remaining = backed + deficit within the stock tick bound. + /// Zero remaining is allowed only with zero backing and zero deficit. + pub fn new( + remaining: StockTicks, + backed: StockTicks, + deficit: StockTicks, + ) -> Result<Self, StockError> { + if backed.checked_add(deficit)? != remaining { + return Err(StockError::ObligationMismatch); + } + Ok(Self { + remaining, + backed, + deficit, + }) + } + + /// Exact outstanding quantity, independently of physical availability. + pub const fn remaining(self) -> StockTicks { + self.remaining + } + + /// Outstanding quantity claimed to have retained physical backing. + pub const fn backed(self) -> StockTicks { + self.backed + } + + /// Outstanding quantity whose physical backing is absent. + pub const fn deficit(self) -> StockTicks { + self.deficit + } + + /// Proposes loss of original physical backing while retaining the entire + /// obligation. The native executor must record the physical depletion and + /// this deficit atomically against the same original allocation/version. + pub fn lose_backing(self, quantity: StockTicks) -> Result<Self, StockError> { + positive(quantity)?; + Self::new( + self.remaining, + self.backed.checked_sub(quantity)?, + self.deficit.checked_add(quantity)?, + ) + } + + /// Proposes replacement backing for a known deficit. The executor must + /// actually hold that stock; this value cannot acquire physical capacity. + pub fn restore_backing(self, quantity: StockTicks) -> Result<Self, StockError> { + positive(quantity)?; + let deficit = self.deficit.checked_sub(quantity)?; + Self::new(self.remaining, self.backed.checked_add(quantity)?, deficit) + } + + /// Proposes fulfillment of backed residual only. The authoritative handover + /// transaction consumes its physical backing once. A buyer receipt changes + /// neither this obligation nor the physical balances a second time. + pub fn consume_backed(self, quantity: StockTicks) -> Result<Self, StockError> { + positive(quantity)?; + Self::new( + self.remaining.checked_sub(quantity)?, + self.backed.checked_sub(quantity)?, + self.deficit, + ) + } + + /// Proposes a nonempty authorized residual release with explicit backed and + /// deficit portions. Only the backed portion can return physical stock to + /// available. Bilateral authority, exact residual and durable identity are + /// checked by the executor, never inferred from this arithmetic. + pub fn release_residual( + self, + backed: StockTicks, + deficit: StockTicks, + ) -> Result<Self, StockError> { + let quantity = backed.checked_add(deficit)?; + positive(quantity)?; + Self::new( + self.remaining.checked_sub(quantity)?, + self.backed.checked_sub(backed)?, + self.deficit.checked_sub(deficit)?, + ) + } +} + +fn positive(quantity: StockTicks) -> Result<(), StockError> { + if quantity == StockTicks::ZERO { + Err(StockError::ZeroMovement) + } else { + Ok(()) + } +} + +impl fmt::Debug for ObligationBacking { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str("ObligationBacking(<private proposal>)") + } +} diff --git a/crates/domain/src/stock/serialization.rs b/crates/domain/src/stock/serialization.rs @@ -1,5 +1,7 @@ //! Closed value codecs. Successful decoding still proves no stock authority. -use super::{PhysicalBalances, PoolBalances, PoolSnapshot, PoolUnit, StockTicks}; +use super::{ + ObligationBacking, PhysicalBalances, PoolBalances, PoolSnapshot, PoolUnit, StockTicks, +}; use crate::{PoolId, Sequence, listing::MeasurementUnit}; use core::fmt; use serde::{Deserialize, Deserializer, Serialize, Serializer, de}; @@ -112,6 +114,30 @@ impl<'de> Deserialize<'de> for PoolBalances { } #[derive(Serialize, Deserialize)] #[serde(deny_unknown_fields)] +struct Backing { + remaining: StockTicks, + backed: StockTicks, + deficit: StockTicks, +} +impl Serialize for ObligationBacking { + fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> { + Backing { + remaining: self.remaining(), + backed: self.backed(), + deficit: self.deficit(), + } + .serialize(serializer) + } +} +impl<'de> Deserialize<'de> for ObligationBacking { + fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> { + let value: Backing = object(deserializer)?; + Self::new(value.remaining, value.backed, value.deficit).map_err(de::Error::custom) + } +} + +#[derive(Serialize, Deserialize)] +#[serde(deny_unknown_fields)] struct Snapshot { id: PoolId, unit: PoolUnit, diff --git a/crates/domain/tests/stock_accounting.rs b/crates/domain/tests/stock_accounting.rs @@ -0,0 +1,307 @@ +use radroots_domain::stock::{ + HeldStockCategory, HeldStockLoss, ObligationBacking, PhysicalBalances, PoolBalances, + StockError, StockTicks, +}; + +fn ticks(value: u64) -> StockTicks { + StockTicks::new(value).unwrap() +} + +fn total(physical: PhysicalBalances) -> u128 { + [ + physical.available, + physical.preparatory_hold, + physical.committed_hold, + physical.physical_quarantine, + physical.consumed, + physical.waste, + physical.removed, + ] + .into_iter() + .map(|quantity| u128::from(quantity.get())) + .sum() +} + +#[test] +fn shortage_handover_and_residual_release_never_convert_deficits_into_physical_stock() { + let physical = PoolBalances::new( + ticks(100), + PhysicalBalances { + available: ticks(20), + committed_hold: ticks(80), + ..PhysicalBalances::ZERO + }, + ) + .unwrap(); + let obligation = ObligationBacking::new(ticks(100), ticks(80), ticks(20)).unwrap(); + let depleted = physical + .deplete_held( + HeldStockCategory::Committed, + HeldStockLoss::Spoilage, + ticks(30), + ) + .unwrap(); + let shortage = obligation.lose_backing(ticks(30)).unwrap(); + assert_eq!(shortage.remaining(), ticks(100)); + assert_eq!(shortage.backed(), ticks(50)); + assert_eq!(shortage.deficit(), ticks(50)); + assert_eq!(depleted.physical().waste, ticks(30)); + assert_eq!(depleted.physical().available, ticks(20)); + + let delivered = depleted.consume_committed(ticks(20)).unwrap(); + let remaining = shortage.consume_backed(ticks(20)).unwrap(); + assert_eq!(remaining.remaining(), ticks(80)); + assert_eq!(remaining.backed(), ticks(30)); + assert_eq!(remaining.deficit(), ticks(50)); + assert_eq!(delivered.physical().consumed, ticks(20)); + assert_eq!( + delivered.release_committed(ticks(80)), + Err(StockError::Underflow) + ); + + let released = delivered.release_committed(ticks(30)).unwrap(); + let closed = remaining.release_residual(ticks(30), ticks(50)).unwrap(); + assert_eq!(closed.remaining(), StockTicks::ZERO); + assert_eq!(closed.backed(), StockTicks::ZERO); + assert_eq!(closed.deficit(), StockTicks::ZERO); + assert_eq!(released.physical().available, ticks(50)); + assert_eq!(released.physical().consumed, ticks(20)); + assert_eq!(released.physical().waste, ticks(30)); + assert_eq!(total(released.physical()), 100); + assert_eq!(physical.physical().committed_hold, ticks(80)); + assert_eq!(obligation.backed(), ticks(80)); +} + +#[test] +fn quarantine_stays_nonspendable_until_an_explicit_proposed_resolution() { + let original = PoolBalances::new( + ticks(10), + PhysicalBalances { + preparatory_hold: ticks(4), + committed_hold: ticks(6), + ..PhysicalBalances::ZERO + }, + ) + .unwrap(); + let held = original + .quarantine_preparatory(ticks(4)) + .unwrap() + .quarantine_committed(ticks(6)) + .unwrap(); + assert_eq!(held.physical().physical_quarantine, ticks(10)); + assert_eq!(held.physical().available, StockTicks::ZERO); + assert_eq!(held.consume_committed(ticks(1)), Err(StockError::Underflow)); + assert_eq!(held.hold_available(ticks(1)), Err(StockError::Underflow)); + + let reconciled = held + .restore_quarantined(ticks(3)) + .unwrap() + .consume_committed(ticks(3)) + .unwrap() + .consume_quarantined(ticks(2)) + .unwrap() + .release_quarantined(ticks(5)) + .unwrap(); + assert_eq!(reconciled.physical().available, ticks(5)); + assert_eq!(reconciled.physical().consumed, ticks(5)); + assert_eq!(reconciled.physical().physical_quarantine, StockTicks::ZERO); + assert_eq!(total(reconciled.physical()), 10); + assert_eq!(original.physical().committed_hold, ticks(6)); +} + +type Movement = fn(PoolBalances, StockTicks) -> Result<PoolBalances, StockError>; + +#[test] +fn every_held_transition_conserves_lifetime_stock_and_refuses_zero_or_overdrawn_sources() { + let movements: [(HeldStockCategory, Movement); 7] = [ + ( + HeldStockCategory::Committed, + PoolBalances::release_committed, + ), + ( + HeldStockCategory::Committed, + PoolBalances::consume_committed, + ), + ( + HeldStockCategory::Preparatory, + PoolBalances::quarantine_preparatory, + ), + ( + HeldStockCategory::Committed, + PoolBalances::quarantine_committed, + ), + ( + HeldStockCategory::Quarantined, + PoolBalances::restore_quarantined, + ), + ( + HeldStockCategory::Quarantined, + PoolBalances::release_quarantined, + ), + ( + HeldStockCategory::Quarantined, + PoolBalances::consume_quarantined, + ), + ]; + for seed in 0..=16 { + let physical = PhysicalBalances { + available: ticks(seed), + preparatory_hold: ticks(seed + 1), + committed_hold: ticks(seed + 2), + physical_quarantine: ticks(seed + 3), + consumed: ticks(seed + 4), + waste: ticks(seed + 5), + removed: ticks(seed + 6), + }; + let introduced = ticks(7 * seed + 21); + let original = PoolBalances::new(introduced, physical).unwrap(); + for (category, movement) in movements { + let source = match category { + HeldStockCategory::Preparatory => seed + 1, + HeldStockCategory::Committed => seed + 2, + HeldStockCategory::Quarantined => seed + 3, + }; + assert_eq!( + movement(original, StockTicks::ZERO), + Err(StockError::ZeroMovement) + ); + assert_eq!( + movement(original, ticks(source + 1)), + Err(StockError::Underflow) + ); + for quantity in [ticks(1), ticks(source)] { + let changed = movement(original, quantity).unwrap(); + assert_eq!(changed.introduced(), introduced); + assert_eq!(total(changed.physical()), u128::from(introduced.get())); + assert!(changed.physical().consumed >= physical.consumed); + assert_eq!(changed.physical().waste, physical.waste); + assert_eq!(changed.physical().removed, physical.removed); + } + for loss in [HeldStockLoss::Spoilage, HeldStockLoss::Removal] { + let changed = original + .deplete_held(category, loss, ticks(source)) + .unwrap(); + assert_eq!(changed.introduced(), introduced); + assert_eq!(total(changed.physical()), u128::from(introduced.get())); + assert_eq!(changed.physical().available, physical.available); + assert_eq!(changed.physical().consumed, physical.consumed); + assert_eq!( + original.deplete_held(category, loss, StockTicks::ZERO), + Err(StockError::ZeroMovement) + ); + assert_eq!( + original.deplete_held(category, loss, ticks(source + 1)), + Err(StockError::Underflow) + ); + } + } + assert_eq!(original.physical(), physical); + } +} + +#[test] +fn maximum_backing_can_be_consumed_released_or_lost_without_minting_capacity() { + let original = PoolBalances::new( + StockTicks::MAX, + PhysicalBalances { + committed_hold: StockTicks::MAX, + ..PhysicalBalances::ZERO + }, + ) + .unwrap(); + let consumed = original.consume_committed(StockTicks::MAX).unwrap(); + assert_eq!(consumed.physical().consumed, StockTicks::MAX); + assert_eq!(consumed.physical().available, StockTicks::ZERO); + assert_eq!( + consumed.consume_committed(ticks(1)), + Err(StockError::Underflow) + ); + let released = original.release_committed(StockTicks::MAX).unwrap(); + assert_eq!(released.physical().available, StockTicks::MAX); + assert_eq!(released.introduced(), StockTicks::MAX); + let quarantined = original.quarantine_committed(StockTicks::MAX).unwrap(); + assert_eq!( + quarantined.consume_quarantined(StockTicks::MAX).unwrap(), + consumed + ); + let lost = original + .deplete_held( + HeldStockCategory::Committed, + HeldStockLoss::Removal, + StockTicks::MAX, + ) + .unwrap(); + assert_eq!(lost.physical().removed, StockTicks::MAX); + assert_eq!(lost.physical().available, StockTicks::ZERO); + assert_eq!(total(lost.physical()), u128::from(StockTicks::MAX.get())); +} + +#[test] +fn obligation_bounds_never_clamp_deficits_or_consume_unbacked_quantities() { + assert_eq!( + ObligationBacking::new(ticks(3), ticks(1), ticks(1)), + Err(StockError::ObligationMismatch) + ); + assert_eq!( + ObligationBacking::new(StockTicks::MAX, StockTicks::MAX, ticks(1)), + Err(StockError::OutOfRange) + ); + let original = + ObligationBacking::new(StockTicks::MAX, StockTicks::MAX, StockTicks::ZERO).unwrap(); + let lost = original.lose_backing(StockTicks::MAX).unwrap(); + assert_eq!(lost.remaining(), StockTicks::MAX); + assert_eq!(lost.backed(), StockTicks::ZERO); + assert_eq!(lost.deficit(), StockTicks::MAX); + assert_eq!(lost.consume_backed(ticks(1)), Err(StockError::Underflow)); + assert_eq!( + original.restore_backing(ticks(1)), + Err(StockError::Underflow) + ); + assert_eq!(lost.restore_backing(StockTicks::MAX).unwrap(), original); + for proposal in [ + original.lose_backing(StockTicks::ZERO), + lost.restore_backing(StockTicks::ZERO), + original.consume_backed(StockTicks::ZERO), + original.release_residual(StockTicks::ZERO, StockTicks::ZERO), + ] { + assert_eq!(proposal, Err(StockError::ZeroMovement)); + } + let closed = lost + .release_residual(StockTicks::ZERO, StockTicks::MAX) + .unwrap(); + assert_eq!(closed.remaining(), StockTicks::ZERO); + assert_eq!( + closed.release_residual(StockTicks::ZERO, ticks(1)), + Err(StockError::Underflow) + ); + assert_eq!( + format!("{original:?}"), + "ObligationBacking(<private proposal>)" + ); +} + +#[cfg(feature = "serde")] +#[test] +fn backing_codec_uses_closed_exact_strings_and_revalidates_the_obligation_equation() { + let original = ObligationBacking::new(ticks(100), ticks(80), ticks(20)).unwrap(); + let raw = serde_json::to_string(&original).unwrap(); + assert_eq!(raw, r#"{"remaining":"100","backed":"80","deficit":"20"}"#); + assert_eq!( + serde_json::from_str::<ObligationBacking>(&raw).unwrap(), + original + ); + for bad in [ + r#"{"remaining":"100","backed":"80","deficit":"19"}"#, + r#"{"remaining":"100","backed":80,"deficit":"20"}"#, + r#"{"remaining":"100","backed":"080","deficit":"20"}"#, + r#"{"remaining":"100","backed":"80","deficit":"20","available":"20"}"#, + r#"{"remaining":"100","remaining":"100","backed":"80","deficit":"20"}"#, + r#"{"remaining":"100","backed":"80"}"#, + r#"["100","80","20"]"#, + ] { + assert!( + serde_json::from_str::<ObligationBacking>(bad).is_err(), + "{bad}" + ); + } +} diff --git a/tools/xtask/src/architecture/decision_package.rs b/tools/xtask/src/architecture/decision_package.rs @@ -33,6 +33,7 @@ struct Policy { packages: Vec<Package>, values: Values, limits: BTreeMap<String, u64>, + stock_accounting: StockAccounting, execution: Execution, protocol: Protocol, cutover: Cutover, @@ -41,6 +42,21 @@ struct Policy { #[derive(Deserialize)] #[serde(deny_unknown_fields)] +struct StockAccounting { + value_owner: String, + scope: String, + obligation_equation: String, + ticks_max: u64, + values_create_store_effects: bool, + deficit_counts_as_physical_stock: bool, + receipt_consumes_again: bool, + released_deficit_adds_available: bool, + loss_deletes_obligation: bool, + native_atomic_allocation_and_identity_required: bool, +} + +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] struct Toolchain { edition: String, stable: String, @@ -712,6 +728,20 @@ fn validate_bytes(raw: &[u8]) -> Result<(), String> { require(raw.len() <= MAX_BYTES, "source byte limit exceeded")?; let p: Policy = serde_json::from_slice(raw) .map_err(|_| "shared SDK contract: invalid closed JSON shape".to_owned())?; + let accounting = &p.stock_accounting; + require( + accounting.value_owner == "radroots_domain.stock" + && accounting.scope == "one_fixed_pool_unit" + && accounting.obligation_equation == "remaining = backed + deficit" + && accounting.ticks_max == 1_000_000_000_000_000_000 + && !accounting.values_create_store_effects + && !accounting.deficit_counts_as_physical_stock + && !accounting.receipt_consumes_again + && !accounting.released_deficit_adds_available + && !accounting.loss_deletes_obligation + && accounting.native_atomic_allocation_and_identity_required, + "stock accounting value or native effect authority drift", + )?; require( p.schema_version == 1 && p.contract_id == "radroots.shared_sdk.refactor.v1" @@ -1751,6 +1781,29 @@ mod tests { } #[test] + fn physical_accounting_cannot_mint_stock_erase_deficits_or_claim_native_effects() { + for (field, value) in [ + ("value_owner", json!("application")), + ("scope", json!("mixed_pool_units")), + ("obligation_equation", json!("remaining = backed")), + ("ticks_max", json!(1_000_000_000_000_000_001u64)), + ("values_create_store_effects", json!(true)), + ("deficit_counts_as_physical_stock", json!(true)), + ("receipt_consumes_again", json!(true)), + ("released_deficit_adds_available", json!(true)), + ("loss_deletes_obligation", json!(true)), + ( + "native_atomic_allocation_and_identity_required", + json!(false), + ), + ] { + assert!( + validate_bytes(&changed(&format!("/stock_accounting/{field}"), value)).is_err() + ); + } + } + + #[test] fn shared_consumers_cannot_silently_lose_buyer_or_seller_roles() { for host in ["cli", "browser", "generic_ffi"] { assert!(