soul-base 0.1.0

Data contract primitives for the Soul platform (IDs, Subject, Scope, Consent, Envelope, ...).
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

#[cfg(feature = "schema")]
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::{
    evidence::EvidenceLevel,
    id::{CausationId, CorrelationId, Id},
    ownership::OwnershipLevel,
    scope::Consent,
    subject::Subject,
    time::Timestamp,
    trace::TraceContext,
};

#[derive(Clone, Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(JsonSchema))]
pub struct Envelope<T> {
    pub envelope_id: Id,
    pub produced_at: Timestamp,
    pub partition_key: String,
    #[serde(default)]
    pub causation_id: Option<CausationId>,
    #[serde(default)]
    pub correlation_id: Option<CorrelationId>,
    pub actor: Subject,
    #[serde(default)]
    pub consent: Option<Consent>,
    pub schema_ver: String,
    #[serde(default)]
    pub trace: Option<TraceContext>,
    pub payload: T,

    // Anchor fields — all optional/defaulted for backward compatibility
    /// Session/epoch/dispute context identifier
    #[serde(default)]
    pub context_id: Option<String>,
    /// Ownership level classification (L1-L4)
    #[serde(default)]
    pub ownership_level: Option<OwnershipLevel>,
    /// Evidence level (A/B)
    #[serde(default)]
    pub evidence_level: Option<EvidenceLevel>,
    /// Parent/related reference IDs
    #[serde(default)]
    pub refs: Vec<String>,
    /// Ordering guarantee within a partition
    #[serde(default)]
    pub sequence_number: Option<u64>,
}

impl<T> Envelope<T> {
    pub fn new(
        envelope_id: Id,
        produced_at: Timestamp,
        partition_key: String,
        actor: Subject,
        schema_ver: impl Into<String>,
        payload: T,
    ) -> Self {
        Self {
            envelope_id,
            produced_at,
            partition_key,
            causation_id: None,
            correlation_id: None,
            actor,
            consent: None,
            schema_ver: schema_ver.into(),
            trace: None,
            payload,
            context_id: None,
            ownership_level: None,
            evidence_level: None,
            refs: Vec::new(),
            sequence_number: None,
        }
    }

    pub fn with_correlation(mut self, correlation: CorrelationId) -> Self {
        self.correlation_id = Some(correlation);
        self
    }

    pub fn with_causation(mut self, causation: CausationId) -> Self {
        self.causation_id = Some(causation);
        self
    }

    pub fn with_consent(mut self, consent: Consent) -> Self {
        self.consent = Some(consent);
        self
    }

    pub fn with_trace(mut self, trace: TraceContext) -> Self {
        self.trace = Some(trace);
        self
    }

    pub fn with_context(mut self, context_id: impl Into<String>) -> Self {
        self.context_id = Some(context_id.into());
        self
    }

    pub fn with_ownership(mut self, level: OwnershipLevel) -> Self {
        self.ownership_level = Some(level);
        self
    }

    pub fn with_evidence(mut self, level: EvidenceLevel) -> Self {
        self.evidence_level = Some(level);
        self
    }

    pub fn with_refs(mut self, refs: Vec<String>) -> Self {
        self.refs = refs;
        self
    }

    pub fn with_sequence(mut self, seq: u64) -> Self {
        self.sequence_number = Some(seq);
        self
    }
}