lean-ctx-protocol 0.6.0

Open wire contracts for lean-ctx: events, observations, assignments, evidence gaps.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! Savings attribution and value-share settlement contracts.

use crate::MoneyV1;
use serde::{Deserialize, Serialize};

/// Attributed, evidence-backed savings for one customer billing period.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SavingsAttribution {
    pub customer_id: String,
    pub period: String,
    pub baseline_cost: MoneyV1,
    pub treatment_cost: MoneyV1,
    pub proven_savings: MoneyV1,
    pub share_percentage: u16,
}

/// Lifecycle state of a value-share settlement.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SettlementStatus {
    NoSettlement,
    Pending,
    Settled,
    Disputed,
}

/// Result of calculating a value-share settlement.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SettlementRecord {
    pub attribution: SavingsAttribution,
    pub invoice_amount: MoneyV1,
    pub settlement_status: SettlementStatus,
}

/// Extension point for Enterprise billing implementations such as `VerifiedValueShare`.
pub trait ValueShareContract {
    /// Calculate the settlement owed for a savings attribution.
    fn calculate_share(&self, attribution: SavingsAttribution) -> SettlementRecord;
}

/// OSS value-share calculator that never produces a billable settlement.
#[derive(Debug, Default, Clone, Copy)]
pub struct LocalValueShare;

impl ValueShareContract for LocalValueShare {
    fn calculate_share(&self, attribution: SavingsAttribution) -> SettlementRecord {
        let invoice_amount = MoneyV1 {
            currency: attribution.proven_savings.currency.clone(),
            coefficient: 0,
            scale: attribution.proven_savings.scale,
        };
        SettlementRecord {
            attribution,
            invoice_amount,
            settlement_status: SettlementStatus::NoSettlement,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn attribution() -> SavingsAttribution {
        SavingsAttribution {
            customer_id: "customer-1".to_owned(),
            period: "2026-08".to_owned(),
            baseline_cost: MoneyV1 {
                currency: "USD".to_owned(),
                coefficient: 10_000,
                scale: 4,
            },
            treatment_cost: MoneyV1 {
                currency: "USD".to_owned(),
                coefficient: 5_000,
                scale: 4,
            },
            proven_savings: MoneyV1 {
                currency: "USD".to_owned(),
                coefficient: 5_000,
                scale: 4,
            },
            share_percentage: 200,
        }
    }

    #[test]
    fn local_value_share_returns_zero_settlement() {
        let settlement = LocalValueShare.calculate_share(attribution());
        assert_eq!(settlement.invoice_amount.coefficient, 0);
        assert_eq!(settlement.settlement_status, SettlementStatus::NoSettlement);
    }

    #[test]
    fn contract_is_object_safe() {
        let value_share: &dyn ValueShareContract = &LocalValueShare;
        assert_eq!(
            value_share
                .calculate_share(attribution())
                .invoice_amount
                .coefficient,
            0
        );
    }
}