logline-core 0.1.1

The Conceptual Atom of Verifiable Action — LogLine Protocol implementation
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
124
125
126

#[cfg(not(feature = "std"))]
use alloc::string::String;
#[cfg(feature = "std")]
use std::string::String;

use crate::{Escalation, FailureHandling, LogLine, LogLineError, Outcome, Payload, Status, Verb};

/// Builder para construir um `LogLine` passo a passo.
///
/// Use `LogLine::builder()` para criar um novo builder. Todos os campos
/// obrigatórios devem ser fornecidos antes de chamar `build_draft()`.
///
/// # Exemplo
///
/// ```rust
/// use logline_core::*;
///
/// let line = LogLine::builder()
///     .who("did:ubl:alice")
///     .did(Verb::Transfer)
///     .this(Payload::Text("100 USD".into()))
///     .when(1_735_671_234)
///     .if_ok(Outcome { label: "transferred".into(), effects: vec!["emit_receipt".into()] })
///     .if_doubt(Escalation { label: "verify".into(), route_to: "auditor".into() })
///     .if_not(FailureHandling { label: "failed".into(), action: "compensate".into() })
///     .build_draft()?;
/// # Ok::<(), LogLineError>(())
/// ```
#[derive(Default)]
pub struct LogLineBuilder {
    who: Option<String>,
    did: Option<Verb>,
    this: Option<Payload>,
    when: Option<u64>,
    confirmed_by: Option<String>,
    if_ok: Option<Outcome>,
    if_doubt: Option<Escalation>,
    if_not: Option<FailureHandling>,
}

impl LogLineBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    /// Define o agente que executa a ação (DID futuro, ex: `did:ubl:...`).
    pub fn who(mut self, v: impl Into<String>) -> Self {
        self.who = Some(v.into());
        self
    }
    /// Define o verbo da ação (canônico ou custom).
    pub fn did(mut self, v: Verb) -> Self {
        self.did = Some(v);
        self
    }
    /// Define a carga útil da ação (payload).
    pub fn this(mut self, v: Payload) -> Self {
        self.this = Some(v);
        self
    }
    /// Define o timestamp Unix em nanosegundos.
    pub fn when(mut self, v: u64) -> Self {
        self.when = Some(v);
        self
    }
    /// Define a identidade que confirma a ação (opcional).
    ///
    /// Paper I: obrigatório para ações de Risk Level 3+ (L3+).
    pub fn confirmed_by(mut self, v: impl Into<String>) -> Self {
        self.confirmed_by = Some(v.into());
        self
    }
    /// Define a consequência positiva obrigatória (invariant).
    pub fn if_ok(mut self, v: Outcome) -> Self {
        self.if_ok = Some(v);
        self
    }
    /// Define a via de dúvida obrigatória (invariant).
    pub fn if_doubt(mut self, v: Escalation) -> Self {
        self.if_doubt = Some(v);
        self
    }
    /// Define o fallback/erro obrigatório (invariant).
    pub fn if_not(mut self, v: FailureHandling) -> Self {
        self.if_not = Some(v);
        self
    }

    /// Constrói um DRAFT válido (invariants obrigatórios presentes).
    ///
    /// Valida que todos os campos obrigatórios estão presentes e cria um `LogLine`
    /// com status `Draft`. Os invariants são verificados antes de retornar.
    ///
    /// # Erros
    ///
    /// - `LogLineError::MissingField` se algum campo obrigatório estiver faltando
    /// - `LogLineError::MissingInvariant` se algum invariant estiver faltando ou vazio
    ///
    /// # Campos obrigatórios
    ///
    /// - `who`: identidade do agente
    /// - `did`: verbo da ação
    /// - `when`: timestamp
    /// - `if_ok`: consequência positiva
    /// - `if_doubt`: via de dúvida
    /// - `if_not`: fallback/erro
    pub fn build_draft(self) -> Result<LogLine, LogLineError> {
        let line = LogLine {
            who: self.who.ok_or(LogLineError::MissingField("who"))?,
            did: self.did.ok_or(LogLineError::MissingField("did"))?,
            this: self.this.unwrap_or(Payload::None),
            when: self.when.ok_or(LogLineError::MissingField("when"))?,
            confirmed_by: self.confirmed_by,
            if_ok: self.if_ok.ok_or(LogLineError::MissingInvariant("if_ok"))?,
            if_doubt: self
                .if_doubt
                .ok_or(LogLineError::MissingInvariant("if_doubt"))?,
            if_not: self
                .if_not
                .ok_or(LogLineError::MissingInvariant("if_not"))?,
            status: Status::Draft,
        };
        line.verify_invariants()?;
        Ok(line)
    }
}