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:
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!(