movements.rs (5780B)
1 //! Pure movement proposals; durable admission and original allocation proof are external. 2 use super::{PoolBalances, StockError, StockTicks}; 3 4 /// Physical backing held for an original operation or installed obligation. 5 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 6 pub enum HeldStockCategory { 7 /// Original preparation whose issuance is not resolved. 8 Preparatory, 9 /// Remaining backing of an installed commitment. 10 Committed, 11 /// Backing retained under unresolved signature or business risk. 12 Quarantined, 13 } 14 15 /// Depletion of genuinely present held stock, without deleting its obligation. 16 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 17 pub enum HeldStockLoss { 18 /// Move the physical quantity into cumulative waste. 19 Spoilage, 20 /// Move the physical quantity into cumulative removed stock. 21 Removal, 22 } 23 24 enum Destination { 25 Available, 26 Committed, 27 Quarantined, 28 Consumed, 29 Waste, 30 Removed, 31 } 32 33 impl PoolBalances { 34 /// Proposes release of authorized unconsumed committed backing. The executor 35 /// must prove the exact residual and bilateral authority and atomically 36 /// retain the release movement; a timeout or missing ACK proves neither. 37 pub fn release_committed(self, quantity: StockTicks) -> Result<Self, StockError> { 38 self.transfer_held( 39 HeldStockCategory::Committed, 40 Destination::Available, 41 quantity, 42 ) 43 } 44 45 /// Proposes physical consumption of original committed backing. Exactly-once 46 /// handover identity, authority, residual and version checks belong to the 47 /// atomic executor. Buyer receipts must never call this movement again. 48 pub fn consume_committed(self, quantity: StockTicks) -> Result<Self, StockError> { 49 self.transfer_held( 50 HeldStockCategory::Committed, 51 Destination::Consumed, 52 quantity, 53 ) 54 } 55 56 /// Proposes retention of preparatory backing under unresolved issuance risk. 57 /// Expiry cannot release it or establish nonissuance. 58 pub fn quarantine_preparatory(self, quantity: StockTicks) -> Result<Self, StockError> { 59 self.transfer_held( 60 HeldStockCategory::Preparatory, 61 Destination::Quarantined, 62 quantity, 63 ) 64 } 65 66 /// Proposes retention of installed backing under unresolved risk. Original 67 /// allocation and obligation linkage must survive the actual transaction. 68 pub fn quarantine_committed(self, quantity: StockTicks) -> Result<Self, StockError> { 69 self.transfer_held( 70 HeldStockCategory::Committed, 71 Destination::Quarantined, 72 quantity, 73 ) 74 } 75 76 /// Proposes restoration to committed backing after qualified reconciliation. 77 /// This value neither resolves unknown issuance nor authorizes a retry. 78 pub fn restore_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> { 79 self.transfer_held( 80 HeldStockCategory::Quarantined, 81 Destination::Committed, 82 quantity, 83 ) 84 } 85 86 /// Proposes a release after original nonissuance or authorized residual 87 /// resolution is proven. An expired lease, query or absent record is no proof. 88 pub fn release_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> { 89 self.transfer_held( 90 HeldStockCategory::Quarantined, 91 Destination::Available, 92 quantity, 93 ) 94 } 95 96 /// Proposes consumption after original handover evidence is reconciled. The 97 /// executor must install the same handover once, retaining its original claim. 98 pub fn consume_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> { 99 self.transfer_held( 100 HeldStockCategory::Quarantined, 101 Destination::Consumed, 102 quantity, 103 ) 104 } 105 106 /// Proposes depletion of actually present backing. It preserves lifetime 107 /// introduced stock and never releases capacity. The executor must retain 108 /// affected original claims and reconcile any outstanding obligation to a 109 /// deficit in the same transaction; this physical value cannot delete it. 110 pub fn deplete_held( 111 self, 112 category: HeldStockCategory, 113 loss: HeldStockLoss, 114 quantity: StockTicks, 115 ) -> Result<Self, StockError> { 116 let destination = match loss { 117 HeldStockLoss::Spoilage => Destination::Waste, 118 HeldStockLoss::Removal => Destination::Removed, 119 }; 120 self.transfer_held(category, destination, quantity) 121 } 122 123 fn transfer_held( 124 self, 125 category: HeldStockCategory, 126 destination: Destination, 127 quantity: StockTicks, 128 ) -> Result<Self, StockError> { 129 if quantity == StockTicks::ZERO { 130 return Err(StockError::ZeroMovement); 131 } 132 let mut physical = self.physical(); 133 let source = match category { 134 HeldStockCategory::Preparatory => &mut physical.preparatory_hold, 135 HeldStockCategory::Committed => &mut physical.committed_hold, 136 HeldStockCategory::Quarantined => &mut physical.physical_quarantine, 137 }; 138 *source = source.checked_sub(quantity)?; 139 let target = match destination { 140 Destination::Available => &mut physical.available, 141 Destination::Committed => &mut physical.committed_hold, 142 Destination::Quarantined => &mut physical.physical_quarantine, 143 Destination::Consumed => &mut physical.consumed, 144 Destination::Waste => &mut physical.waste, 145 Destination::Removed => &mut physical.removed, 146 }; 147 *target = target.checked_add(quantity)?; 148 Self::new(self.introduced(), physical) 149 } 150 }