liminal-protocol 0.2.0

Shared participant-lifecycle protocol types for liminal
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

use crate::wire::{
    AttachEnvelope, BindingEpoch, DeliverySeq, DetachEnvelope, EnrollmentEnvelope, LeaveEnvelope,
    ObserverBackpressure, ObserverBackpressureState, RecordAdmissionEnvelope,
};

/// Operations whose candidate floor is checked against hard observer retention.
///
/// The variants carry every operation-specific field required by the frozen
/// `ObserverBackpressure` register. Normal and marker acknowledgements are
/// deliberately absent because they can never return this outcome.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ObserverCheckedOperation {
    /// Participant enrollment.
    Enrollment(EnrollmentEnvelope),
    /// Credential attach or supersession.
    CredentialAttach(AttachEnvelope),
    /// Initial detach of the exact committed binding epoch.
    InitialDetach {
        /// Exact detach request envelope.
        request: DetachEnvelope,
        /// Binding epoch the detach would terminalize.
        committed_binding_epoch: BindingEpoch,
    },
    /// Terminal Leave.
    Leave {
        /// Exact Leave request envelope.
        request: LeaveEnvelope,
        /// Whether an earlier binding-terminal cell already exists.
        prior_terminal_cell_exists: bool,
    },
    /// Ordinary record admission.
    RecordAdmission(RecordAdmissionEnvelope),
}

/// Opaque proof that one protocol-computed candidate floor passed stage 11.
///
/// Construction is private. A consuming server can persist and commit the
/// exact checked values, but cannot create a permit without running the shared
/// protocol selector.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ObserverFloorPermit {
    observer_progress: DeliverySeq,
    cap_floor: u128,
}

impl ObserverFloorPermit {
    /// Returns the observer progress against which the floor was checked.
    #[must_use]
    pub const fn observer_progress(self) -> DeliverySeq {
        self.observer_progress
    }

    /// Returns the exact protocol-computed candidate capacity floor.
    #[must_use]
    pub const fn cap_floor(self) -> u128 {
        self.cap_floor
    }
}

/// Stage-11 observer hard-retention decision.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ObserverFloorDecision {
    /// `cap_floor <= observer_progress + 1`; commit may continue with this proof.
    Eligible(ObserverFloorPermit),
    /// The candidate would remove a sequence above hard observer progress.
    Respond(ObserverBackpressure),
}

/// Applies the observer hard-retention selector to a protocol-computed floor.
///
/// The comparison is widened before checked one-past progress is formed.
/// Equality passes. A strict excess returns the exact operation-specific
/// [`ObserverBackpressure`] with an initial refusal epoch equal to current
/// observer progress.
#[must_use]
pub fn check_observer_floor(
    operation: ObserverCheckedOperation,
    observer_progress: DeliverySeq,
    cap_floor: u128,
) -> ObserverFloorDecision {
    let observer_limit = u128::from(observer_progress) + 1;
    if cap_floor <= observer_limit {
        return ObserverFloorDecision::Eligible(ObserverFloorPermit {
            observer_progress,
            cap_floor,
        });
    }

    let state = ObserverBackpressureState::initial(observer_progress);
    let response = match operation {
        ObserverCheckedOperation::Enrollment(request) => {
            ObserverBackpressure::Enrollment { request, state }
        }
        ObserverCheckedOperation::CredentialAttach(request) => {
            ObserverBackpressure::CredentialAttach { request, state }
        }
        ObserverCheckedOperation::InitialDetach {
            request,
            committed_binding_epoch,
        } => ObserverBackpressure::Detach {
            request,
            committed_binding_epoch,
            state,
        },
        ObserverCheckedOperation::Leave {
            request,
            prior_terminal_cell_exists,
        } => ObserverBackpressure::Leave {
            request,
            state,
            prior_terminal_cell_exists,
        },
        ObserverCheckedOperation::RecordAdmission(request) => {
            ObserverBackpressure::RecordAdmission { request, state }
        }
    };
    ObserverFloorDecision::Respond(response)
}