lib

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

payload.rs (15593B)


      1 use super::{
      2     CommerceError,
      3     value::{check_lines, check_text},
      4 };
      5 use super::{FinalMeasurement, LineQuantity, Resolution};
      6 use crate::{
      7     AuthorityRef, FulfillmentGroupId, RecordId, Sequence, SourceId, Terms, TermsDigest,
      8     UnixSeconds, Window,
      9 };
     10 use alloc::{boxed::Box, string::String, vec::Vec};
     11 use core::fmt;
     12 use zeroize::Zeroizing;
     13 
     14 macro_rules! copy_getters {
     15     ($($field:ident:$ty:ty),+ $(,)?)=> { $(
     16         #[doc=concat!("Returns the explicit `",stringify!($field),"` claim without authenticating it.")]
     17         pub const fn $field(&self)->$ty { self.$field }
     18     )+ };
     19 }
     20 macro_rules! simple {
     21     ($name:ident,$doc:literal,{$($field:ident:$ty:ty),+ $(,)?})=> {
     22         #[doc=$doc]
     23         #[derive(Clone,Copy,Eq,PartialEq)]
     24         pub struct $name { $($field:$ty),+ }
     25         impl $name {
     26             /// Captures already validated representations; references remain claims.
     27             pub const fn new($($field:$ty),+)->Self { Self { $($field),+ } }
     28             copy_getters!($($field:$ty),+);
     29         }
     30     };
     31 }
     32 
     33 /// Complete seller quote data, without a hold, signature or buyer consent.
     34 #[derive(Clone, Eq, PartialEq)]
     35 pub struct TermsQuote {
     36     terms: Box<Terms>,
     37     expires_at: UnixSeconds,
     38     in_reply_to: Option<SourceId>,
     39 }
     40 impl TermsQuote {
     41     /// Captures complete values. Expiry actionability and any referenced chat or
     42     /// record require independent source/time admission; no clock is observed.
     43     pub fn new(terms: Terms, expires_at: UnixSeconds, in_reply_to: Option<SourceId>) -> Self {
     44         Self {
     45             terms: Box::new(terms),
     46             expires_at,
     47             in_reply_to,
     48         }
     49     }
     50     /// Explicitly borrows the complete private terms claim.
     51     pub const fn terms(&self) -> &Terms {
     52         &self.terms
     53     }
     54     copy_getters!(expires_at:UnixSeconds,in_reply_to:Option<SourceId>);
     55 }
     56 /// Complete buyer request data, without authentication or stock effects.
     57 #[derive(Clone, Eq, PartialEq)]
     58 pub struct TermsRequest {
     59     terms: Box<Terms>,
     60     expires_at: UnixSeconds,
     61     quote: Option<RecordId>,
     62 }
     63 impl TermsRequest {
     64     /// Captures complete terms and an explicit optional quote reference.
     65     pub fn new(terms: Terms, expires_at: UnixSeconds, quote: Option<RecordId>) -> Self {
     66         Self {
     67             terms: Box::new(terms),
     68             expires_at,
     69             quote,
     70         }
     71     }
     72     /// Explicitly borrows the complete private terms claim.
     73     pub const fn terms(&self) -> &Terms {
     74         &self.terms
     75     }
     76     copy_getters!(expires_at:UnixSeconds,quote:Option<RecordId>);
     77 }
     78 /// A typed record target and bounded private reason. Its enclosing variant
     79 /// identifies whether the target is a request, proposal or authorization.
     80 #[derive(Clone, Eq, PartialEq)]
     81 pub struct RecordReason {
     82     target: RecordId,
     83     reason: Zeroizing<String>,
     84 }
     85 impl RecordReason {
     86     /// Bounds exact reason text before copying; target family needs admission.
     87     pub fn new(target: RecordId, reason: &str) -> Result<Self, CommerceError> {
     88         check_text(reason, 1024)?;
     89         Ok(Self {
     90             target,
     91             reason: Zeroizing::new(reason.into()),
     92         })
     93     }
     94     copy_getters!(target:RecordId);
     95     /// Explicitly borrows the private reason, without terminal/display escaping.
     96     pub fn reason(&self) -> &str {
     97         &self.reason
     98     }
     99 }
    100 /// Complete proposed replacement terms, preserving the declared base reference.
    101 #[derive(Clone, Eq, PartialEq)]
    102 pub struct TermsProposal {
    103     base_agreement: Option<RecordId>,
    104     terms: Box<Terms>,
    105     expires_at: UnixSeconds,
    106     reason: Zeroizing<String>,
    107 }
    108 impl TermsProposal {
    109     /// Bounds private text before capture. Consent and base-head admission are separate.
    110     pub fn new(
    111         base_agreement: Option<RecordId>,
    112         terms: Terms,
    113         expires_at: UnixSeconds,
    114         reason: &str,
    115     ) -> Result<Self, CommerceError> {
    116         check_text(reason, 1024)?;
    117         Ok(Self {
    118             base_agreement,
    119             terms: Box::new(terms),
    120             expires_at,
    121             reason: Zeroizing::new(reason.into()),
    122         })
    123     }
    124     copy_getters!(base_agreement:Option<RecordId>,expires_at:UnixSeconds);
    125     /// Explicitly borrows complete private replacement terms.
    126     pub const fn terms(&self) -> &Terms {
    127         &self.terms
    128     }
    129     /// Explicitly borrows private proposal text.
    130     pub fn reason(&self) -> &str {
    131         &self.reason
    132     }
    133 }
    134 simple!(TermsAuthorization,"A proposal/terms commitment claim, not participant consent.",{
    135     proposal:RecordId,terms_digest:TermsDigest,expires_at:UnixSeconds
    136 });
    137 simple!(ProposalAuthorization,"A proposal/expiry claim whose counterparty must be independently verified.",{
    138     proposal:RecordId,expires_at:UnixSeconds
    139 });
    140 
    141 /// Seller commitment data, without authenticated authority or installation.
    142 #[derive(Clone, Copy, Eq, PartialEq)]
    143 pub struct AgreementCommitment {
    144     base_agreement: Option<RecordId>,
    145     authorization: RecordId,
    146     terms_digest: TermsDigest,
    147     authority: AuthorityRef,
    148     seller_sequence: Sequence,
    149 }
    150 impl AgreementCommitment {
    151     /// Requires a positive seller sequence; all source/authority evidence is separate.
    152     pub fn new(
    153         base_agreement: Option<RecordId>,
    154         authorization: RecordId,
    155         terms_digest: TermsDigest,
    156         authority: AuthorityRef,
    157         seller_sequence: Sequence,
    158     ) -> Result<Self, CommerceError> {
    159         positive(seller_sequence)?;
    160         Ok(Self {
    161             base_agreement,
    162             authorization,
    163             terms_digest,
    164             authority,
    165             seller_sequence,
    166         })
    167     }
    168     copy_getters!(base_agreement:Option<RecordId>,authorization:RecordId,terms_digest:TermsDigest,
    169         authority:AuthorityRef,seller_sequence:Sequence);
    170 }
    171 /// Serialized seller withdrawal-decision claim, without final race resolution.
    172 #[derive(Clone, Copy, Eq, PartialEq)]
    173 pub struct WithdrawalAcknowledgement {
    174     withdrawal: RecordId,
    175     seller_sequence: Sequence,
    176 }
    177 impl WithdrawalAcknowledgement {
    178     /// Requires a positive explicit seller decision sequence.
    179     pub fn new(withdrawal: RecordId, seller_sequence: Sequence) -> Result<Self, CommerceError> {
    180         positive(seller_sequence)?;
    181         Ok(Self {
    182             withdrawal,
    183             seller_sequence,
    184         })
    185     }
    186     copy_getters!(withdrawal:RecordId,seller_sequence:Sequence);
    187 }
    188 /// Bounded residual-cancellation proposal, without releasing any stock.
    189 #[derive(Clone, Eq, PartialEq)]
    190 pub struct CancellationProposal {
    191     agreement: RecordId,
    192     residual: Box<[LineQuantity]>,
    193     reason: Zeroizing<String>,
    194     expires_at: UnixSeconds,
    195 }
    196 impl CancellationProposal {
    197     /// Requires one through32 distinct line assertions and bounded private text.
    198     pub fn new(
    199         agreement: RecordId,
    200         residual: Vec<LineQuantity>,
    201         reason: &str,
    202         expires_at: UnixSeconds,
    203     ) -> Result<Self, CommerceError> {
    204         check_lines(&residual, 1)?;
    205         check_text(reason, 1024)?;
    206         Ok(Self {
    207             agreement,
    208             residual: residual.into_boxed_slice(),
    209             reason: Zeroizing::new(reason.into()),
    210             expires_at,
    211         })
    212     }
    213     copy_getters!(agreement:RecordId,expires_at:UnixSeconds);
    214     /// Borrows exact proposed residual assertions, without assuming current residual.
    215     pub fn residual(&self) -> &[LineQuantity] {
    216         &self.residual
    217     }
    218     /// Explicitly borrows the private cancellation reason.
    219     pub fn reason(&self) -> &str {
    220         &self.reason
    221     }
    222 }
    223 /// Complete seller residual-release claim; construction does not move stock.
    224 #[derive(Clone, Eq, PartialEq)]
    225 pub struct ResidualRelease {
    226     proposal: RecordId,
    227     authorization: RecordId,
    228     agreement: RecordId,
    229     residual: Box<[LineQuantity]>,
    230     authority: AuthorityRef,
    231     seller_sequence: Sequence,
    232 }
    233 impl ResidualRelease {
    234     /// Bounds line data and requires a positive seller decision sequence.
    235     pub fn new(
    236         proposal: RecordId,
    237         authorization: RecordId,
    238         agreement: RecordId,
    239         residual: Vec<LineQuantity>,
    240         authority: AuthorityRef,
    241         seller_sequence: Sequence,
    242     ) -> Result<Self, CommerceError> {
    243         check_lines(&residual, 1)?;
    244         positive(seller_sequence)?;
    245         Ok(Self {
    246             proposal,
    247             authorization,
    248             agreement,
    249             residual: residual.into_boxed_slice(),
    250             authority,
    251             seller_sequence,
    252         })
    253     }
    254     copy_getters!(proposal:RecordId,authorization:RecordId,agreement:RecordId,authority:AuthorityRef,seller_sequence:Sequence);
    255     /// Borrows the complete declared release quantities, pending state/consent checks.
    256     pub fn residual(&self) -> &[LineQuantity] {
    257         &self.residual
    258     }
    259 }
    260 /// A seller readiness assertion, without physical handover or buyer receipt.
    261 #[derive(Clone, Eq, PartialEq)]
    262 pub struct ReadinessClaim {
    263     agreement: RecordId,
    264     fulfillment_group: FulfillmentGroupId,
    265     lines: Box<[LineQuantity]>,
    266     window: Window,
    267 }
    268 impl ReadinessClaim {
    269     /// Bounds exact declared lines; agreement/group membership needs admission.
    270     pub fn new(
    271         agreement: RecordId,
    272         fulfillment_group: FulfillmentGroupId,
    273         lines: Vec<LineQuantity>,
    274         window: Window,
    275     ) -> Result<Self, CommerceError> {
    276         check_lines(&lines, 1)?;
    277         Ok(Self {
    278             agreement,
    279             fulfillment_group,
    280             lines: lines.into_boxed_slice(),
    281             window,
    282         })
    283     }
    284     copy_getters!(agreement:RecordId,fulfillment_group:FulfillmentGroupId,window:Window);
    285     /// Borrows complete asserted ready quantities.
    286     pub fn lines(&self) -> &[LineQuantity] {
    287         &self.lines
    288     }
    289 }
    290 /// A seller handover/measurement assertion; it is not physical truth or consumption.
    291 #[derive(Clone, Eq, PartialEq)]
    292 pub struct HandoverClaim {
    293     agreement: RecordId,
    294     fulfillment_group: FulfillmentGroupId,
    295     lines: Box<[LineQuantity]>,
    296     measurements: Box<[FinalMeasurement]>,
    297     occurred_at: UnixSeconds,
    298     authority: AuthorityRef,
    299     seller_sequence: Sequence,
    300 }
    301 impl HandoverClaim {
    302     /// Bounds line/measurement data, rejects duplicate or unrelated measurement
    303     /// line IDs and requires a positive seller decision sequence. Agreement
    304     /// unit/range/economic/cumulative admission remains mandatory and separate.
    305     pub fn new(
    306         agreement: RecordId,
    307         fulfillment_group: FulfillmentGroupId,
    308         lines: Vec<LineQuantity>,
    309         measurements: Vec<FinalMeasurement>,
    310         occurred_at: UnixSeconds,
    311         authority: AuthorityRef,
    312         seller_sequence: Sequence,
    313     ) -> Result<Self, CommerceError> {
    314         check_lines(&lines, 1)?;
    315         positive(seller_sequence)?;
    316         if measurements.len() > 32 {
    317             return Err(CommerceError::InvalidMeasurements);
    318         }
    319         for (index, measurement) in measurements.iter().enumerate() {
    320             if !lines
    321                 .iter()
    322                 .any(|line| line.line_id() == measurement.line_id())
    323                 || measurements[..index]
    324                     .iter()
    325                     .any(|prior| prior.line_id() == measurement.line_id())
    326             {
    327                 return Err(CommerceError::InvalidMeasurements);
    328             }
    329         }
    330         Ok(Self {
    331             agreement,
    332             fulfillment_group,
    333             lines: lines.into_boxed_slice(),
    334             measurements: measurements.into_boxed_slice(),
    335             occurred_at,
    336             authority,
    337             seller_sequence,
    338         })
    339     }
    340     copy_getters!(agreement:RecordId,fulfillment_group:FulfillmentGroupId,occurred_at:UnixSeconds,
    341         authority:AuthorityRef,seller_sequence:Sequence);
    342     /// Borrows complete seller quantity assertions.
    343     pub fn lines(&self) -> &[LineQuantity] {
    344         &self.lines
    345     }
    346     /// Borrows bounded final measurements, still requiring independent price/range checks.
    347     pub fn measurements(&self) -> &[FinalMeasurement] {
    348         &self.measurements
    349     }
    350 }
    351 /// A buyer's independent observation, without seller stock consumption.
    352 #[derive(Clone, Eq, PartialEq)]
    353 pub struct ReceiptObservation {
    354     handover: RecordId,
    355     lines: Box<[LineQuantity]>,
    356     supersedes: Option<RecordId>,
    357     occurred_at: UnixSeconds,
    358     note: Zeroizing<String>,
    359 }
    360 impl ReceiptObservation {
    361     /// Bounds exact observations and private text. Zero observation remains
    362     /// representable; it never becomes a positive movement or inferred release.
    363     pub fn new(
    364         handover: RecordId,
    365         lines: Vec<LineQuantity>,
    366         supersedes: Option<RecordId>,
    367         occurred_at: UnixSeconds,
    368         note: &str,
    369     ) -> Result<Self, CommerceError> {
    370         check_lines(&lines, 1)?;
    371         check_text(note, 1024)?;
    372         Ok(Self {
    373             handover,
    374             lines: lines.into_boxed_slice(),
    375             supersedes,
    376             occurred_at,
    377             note: Zeroizing::new(note.into()),
    378         })
    379     }
    380     copy_getters!(handover:RecordId,supersedes:Option<RecordId>,occurred_at:UnixSeconds);
    381     /// Borrows complete asserted observations; supersession is not accumulation.
    382     pub fn lines(&self) -> &[LineQuantity] {
    383         &self.lines
    384     }
    385     /// Explicitly borrows private receipt text.
    386     pub fn note(&self) -> &str {
    387         &self.note
    388     }
    389 }
    390 /// A complete proposed issue resolution, not mutual authorization or installation.
    391 #[derive(Clone, Eq, PartialEq)]
    392 pub struct ResolutionProposal {
    393     agreement: RecordId,
    394     resolution: Resolution,
    395     expires_at: UnixSeconds,
    396 }
    397 impl ResolutionProposal {
    398     /// Captures bounded resolution data and explicit source/time claims.
    399     pub const fn new(agreement: RecordId, resolution: Resolution, expires_at: UnixSeconds) -> Self {
    400         Self {
    401             agreement,
    402             resolution,
    403             expires_at,
    404         }
    405     }
    406     copy_getters!(agreement:RecordId,expires_at:UnixSeconds);
    407     /// Explicitly borrows complete private resolution data.
    408     pub const fn resolution(&self) -> &Resolution {
    409         &self.resolution
    410     }
    411 }
    412 /// A seller resolution-commitment claim, without installed effects.
    413 #[derive(Clone, Copy, Eq, PartialEq)]
    414 pub struct ResolutionCommitment {
    415     proposal: RecordId,
    416     authorization: RecordId,
    417     authority: AuthorityRef,
    418     seller_sequence: Sequence,
    419 }
    420 impl ResolutionCommitment {
    421     /// Requires a positive seller decision sequence; consent/authority need admission.
    422     pub fn new(
    423         proposal: RecordId,
    424         authorization: RecordId,
    425         authority: AuthorityRef,
    426         seller_sequence: Sequence,
    427     ) -> Result<Self, CommerceError> {
    428         positive(seller_sequence)?;
    429         Ok(Self {
    430             proposal,
    431             authorization,
    432             authority,
    433             seller_sequence,
    434         })
    435     }
    436     copy_getters!(proposal:RecordId,authorization:RecordId,authority:AuthorityRef,seller_sequence:Sequence);
    437 }
    438 fn positive(sequence: Sequence) -> Result<(), CommerceError> {
    439     if sequence.get() == 0 {
    440         return Err(CommerceError::InvalidSequence);
    441     }
    442     Ok(())
    443 }
    444 macro_rules! redacted {
    445     ($($name:ident),+)=> { $(impl fmt::Debug for $name {
    446         fn fmt(&self,f:&mut fmt::Formatter<'_>)->fmt::Result { f.write_str(concat!(stringify!($name),"(<redacted>)")) }
    447     })+ };
    448 }
    449 redacted!(
    450     TermsQuote,
    451     TermsRequest,
    452     RecordReason,
    453     TermsProposal,
    454     TermsAuthorization,
    455     ProposalAuthorization,
    456     AgreementCommitment,
    457     WithdrawalAcknowledgement,
    458     CancellationProposal,
    459     ResidualRelease,
    460     ReadinessClaim,
    461     HandoverClaim,
    462     ReceiptObservation,
    463     ResolutionProposal,
    464     ResolutionCommitment
    465 );