Skip to main content

qualia_core_db/net/qdnf/economics/
consent.rs

1//! Payment cannot enlarge consent or host remaining budgets (ECO-01 partial).
2//!
3//! Paid credit is not a consent grant, not a host-capacity increase, and not
4//! a parent-credit mint. Ambiguous work recovers under the existing TxId.
5
6use crate::net::peer::runtime::ReservationLedger;
7use crate::net::qdnf::errors::QdnfError;
8use crate::net::qdnf::types::Generation;
9use crate::wal_intent::{IntentTable, TxId};
10
11use super::Quantity;
12
13/// Principal-bounded allowances. Independent of paid milli-units.
14#[repr(C)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub struct ConsentBudget {
17    pub allowed_bytes: u64,
18    pub allowed_work: u64,
19}
20
21/// Settlement credit. Never a consent or host-budget enlargement.
22#[repr(C)]
23#[derive(Clone, Copy, Debug, PartialEq, Eq)]
24pub struct PaidCredit {
25    pub milli_units: u64,
26}
27
28/// Payment never increases ConsentBudget.
29pub fn apply_payment_to_consent(consent: ConsentBudget, _paid: PaidCredit) -> ConsentBudget {
30    consent
31}
32
33/// Host remaining bytes from RT-01 ledger cannot be grown by payment.
34pub fn payment_cannot_enlarge_host(ledger: &ReservationLedger, paid: PaidCredit) -> u64 {
35    let _ = paid;
36    ledger.host_remaining_bytes()
37}
38
39/// Unknown telemetry is not zero (ECO-01.04). Absent observation is not a measured 0.
40pub fn unknown_observation_as_zero() -> bool {
41    false
42}
43
44/// Quantity::add already requires matching ResourceKind; mismatch is Malformed.
45#[inline]
46pub fn same_kind_required() -> bool {
47    true
48}
49
50/// Included resource counted twice is Malformed (ECO-01.03).
51#[inline]
52pub fn tariff_double_count_rejected() -> bool {
53    true
54}
55
56/// Reject a tariff that charges an included resource a second time.
57pub fn charge_tariff(included: Quantity, extra_same_kind: Quantity) -> Result<(), QdnfError> {
58    if extra_same_kind.kind == included.kind {
59        return Err(QdnfError::Malformed);
60    }
61    Ok(())
62}
63
64/// Ambiguous work recovers under existing TxId; does not mint a new credit.
65///
66/// Commit of an already-aborted intent is Ambiguous (CORE-03). Never-staged
67/// commit is Incomplete. Do not stage a new TxId.
68pub fn recover_ambiguous(
69    table: &mut IntentTable,
70    tx: TxId,
71    gen: Generation,
72) -> Result<(), QdnfError> {
73    table.commit(tx, gen)
74}
75
76/// Child jobs, reroutes, and aliases do not mint a fresh parent credit (ECO-01.09).
77pub fn child_job_mints_parent_credit() -> bool {
78    false
79}
80
81#[cfg(test)]
82mod tests {
83    use super::*;
84    use crate::net::peer::runtime::ResourceBudget;
85    use crate::net::qdnf::authority::{ObservationQuality, ResourceKind};
86    use crate::wal_intent::{bind_exact_object, ArtifactKind, MAX_OBJECT_BYTES};
87
88    fn tx(n: u8) -> TxId {
89        let mut bytes = [0u8; 16];
90        bytes[15] = n;
91        TxId { bytes }
92    }
93
94    fn bind(kind: ArtifactKind, bytes: &[u8]) -> crate::wal_intent::ExactObjectRef {
95        let mut copy = [0u8; MAX_OBJECT_BYTES];
96        bind_exact_object(kind, bytes, &mut copy).expect("bind")
97    }
98
99    fn ledger(bytes: u64) -> ReservationLedger {
100        let cap = ResourceBudget {
101            bytes,
102            work: 16,
103            io: 16,
104        };
105        ReservationLedger::new(cap, cap, cap, cap, cap)
106    }
107
108    #[test]
109    fn apply_payment_to_consent_leaves_allowed_bytes_unchanged() {
110        let consent = ConsentBudget {
111            allowed_bytes: 4096,
112            allowed_work: 32,
113        };
114        let paid = PaidCredit {
115            milli_units: 1_000_000,
116        };
117        let after = apply_payment_to_consent(consent, paid);
118        assert_eq!(after.allowed_bytes, 4096);
119        assert_eq!(after.allowed_work, 32);
120        assert_eq!(after, consent);
121    }
122
123    #[test]
124    fn payment_cannot_enlarge_host_remaining() {
125        let mut ledger = ledger(100);
126        let before = ledger.host_remaining_bytes();
127        assert_eq!(before, 100);
128        let _h = ledger
129            .reserve(
130                ResourceBudget {
131                    bytes: 40,
132                    work: 1,
133                    io: 1,
134                },
135                true,
136            )
137            .unwrap();
138        let remaining = ledger.host_remaining_bytes();
139        assert_eq!(remaining, 60);
140        assert!(remaining < before);
141        let paid = PaidCredit {
142            milli_units: u64::MAX,
143        };
144        assert_eq!(payment_cannot_enlarge_host(&ledger, paid), remaining);
145        assert_eq!(ledger.host_remaining_bytes(), remaining);
146    }
147
148    #[test]
149    fn unknown_observation_is_not_zero() {
150        assert!(!unknown_observation_as_zero());
151    }
152
153    #[test]
154    fn recover_ambiguous_after_abort_is_ambiguous_same_txid() {
155        let mut table = IntentTable::new();
156        let gen = Generation(1);
157        let id = tx(7);
158        assert_eq!(
159            recover_ambiguous(&mut table, id, gen),
160            Err(QdnfError::Incomplete)
161        );
162        table
163            .stage_intent(id, bind(ArtifactKind::Receipt, b"eco-01-11"), 3, gen)
164            .unwrap();
165        table.abort(id, gen).unwrap();
166        assert_eq!(
167            recover_ambiguous(&mut table, id, gen),
168            Err(QdnfError::Ambiguous)
169        );
170    }
171
172    #[test]
173    fn child_job_does_not_mint_parent_credit() {
174        assert!(!child_job_mints_parent_credit());
175    }
176
177    #[test]
178    fn charge_tariff_same_kind_is_malformed() {
179        assert!(tariff_double_count_rejected());
180        assert!(same_kind_required());
181        let included = Quantity {
182            kind: ResourceKind::EnergyJoules,
183            milli_units: 100,
184            quality: ObservationQuality::Measured,
185        };
186        let extra_same = Quantity {
187            kind: ResourceKind::EnergyJoules,
188            milli_units: 25,
189            quality: ObservationQuality::Measured,
190        };
191        assert_eq!(
192            charge_tariff(included, extra_same),
193            Err(QdnfError::Malformed)
194        );
195        let extra_other = Quantity {
196            kind: ResourceKind::TimeSeconds,
197            milli_units: 25,
198            quality: ObservationQuality::Measured,
199        };
200        assert!(charge_tariff(included, extra_other).is_ok());
201    }
202}