liminal_protocol/algebra/
floor.rs

1use super::types::{FloorComputation, widen_u64};
2
3/// What a binding-fate floor measured earlier is allowed to install NOW.
4///
5/// A floor is measured at one moment and installed at another. Between them the
6/// frontier moves, so the measured value is a PROPOSAL and this is the verdict
7/// on it. Returned by [`admissible_installed_floor`].
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
9pub enum AdmissibleFloor {
10    /// Install exactly this floor. It is guaranteed to sit inside the interval
11    /// the installing enforcer accepts, so installing it cannot be refused.
12    Install(u128),
13    /// The current retained floor is already at or past what this measurement
14    /// could legally install, so the measured floor is SUBSUMED and installing
15    /// it would mean nothing. An explicit success with no effect — never a
16    /// refusal, and never an install that drives the floor backwards.
17    Subsumed,
18}
19
20/// Lowers a computed floor so it cannot cross the lowest retained marker.
21///
22/// ⚠ THIS LOWERS. [`floor_transition`]'s `cap_floor` argument RAISES: it is
23/// `max(base_result, cap_floor)`, a floor-**raiser** despite the name. Passing
24/// the lowest marker through `cap_floor` yields `max(base, marker)`, which
25/// still sits above the marker in exactly the poisoning case and would raise
26/// floors in cases that work today. The two are opposites; do not substitute
27/// one for the other.
28///
29/// The clamp target is the marker ITSELF, never `marker - 1`. The enforcers
30/// refuse on `record.delivery_seq < resulting_floor` — strictly below — so
31/// `resulting_floor == marker` is admissible, and it stays consistent
32/// downstream because floor installation retains markers `>= resulting_floor`,
33/// so a marker sitting exactly at the floor survives its own pin. Clamping to
34/// just below the marker is the defensive reflex and it silently destroys legal
35/// floor advances.
36///
37/// An empty marker set is the majority case and is answered explicitly rather
38/// than left to a guess about the minimum of an empty set: nothing pins the
39/// floor, so the computed floor passes through byte-identical.
40#[must_use]
41pub const fn marker_clamped_floor(
42    computed_floor: u128,
43    lowest_retained_marker_seq: Option<u64>,
44) -> u128 {
45    match lowest_retained_marker_seq {
46        Some(marker) => {
47            let marker = widen_u64(marker);
48            if computed_floor < marker {
49                computed_floor
50            } else {
51                marker
52            }
53        }
54        None => computed_floor,
55    }
56}
57
58/// Decides what an earlier-measured binding-fate floor may install against the
59/// frontier as it stands now.
60///
61/// The installing enforcer refuses on TWO conditions, and clamping downward
62/// against markers only bounds one of them: a floor clamped down can land BELOW
63/// the current retained floor and be refused for that instead — the same
64/// permanent refusal under a different name. So the admissible interval is
65///
66/// > `[retained_floor, min(lowest_retained_marker_seq, high_watermark + 1)]`
67///
68/// with **both ends read now, not at measurement time**: the upper end moves
69/// too, because it derives from the current high watermark.
70///
71/// Monotonicity is safe rather than assumed. Floor installation retains only
72/// markers `>= resulting_floor`, so the lowest retained marker is never below
73/// the retained floor, and the marker clamp can therefore never on its own
74/// drive a floor backwards. When the interval is nonetheless empty — which
75/// requires a frontier that has already broken that invariant — the answer is
76/// [`AdmissibleFloor::Subsumed`], i.e. install nothing, because installing
77/// anything would prune rows the frontier still owes.
78#[must_use]
79pub const fn admissible_installed_floor(
80    measured_floor: u128,
81    retained_floor: u128,
82    lowest_retained_marker_seq: Option<u64>,
83    high_watermark: u64,
84) -> AdmissibleFloor {
85    let retained_end = widen_u64(high_watermark) + 1;
86    let upper = marker_clamped_floor(retained_end, lowest_retained_marker_seq);
87    let target = if measured_floor < upper {
88        measured_floor
89    } else {
90        upper
91    };
92    if target < retained_floor {
93        AdmissibleFloor::Subsumed
94    } else {
95        AdmissibleFloor::Install(target)
96    }
97}
98
99/// Computes the participant physical-floor rule.
100///
101/// `minimum_member_cursor` is evaluated after membership changes. When it is
102/// `None`, the rule substitutes the candidate high watermark `H'` for `m`.
103/// Floors use `u128` so checked one-past-`u64::MAX` remains representable.
104#[must_use]
105pub const fn floor_transition(
106    current_floor: u128,
107    minimum_member_cursor: Option<u64>,
108    candidate_high_watermark: u64,
109    observer_progress: u64,
110    cap_floor: u128,
111) -> FloorComputation {
112    let member_cursor = match minimum_member_cursor {
113        Some(cursor) => cursor,
114        None => candidate_high_watermark,
115    };
116    let preferred_floor = if member_cursor < observer_progress {
117        widen_u64(member_cursor) + 1
118    } else {
119        widen_u64(observer_progress) + 1
120    };
121    let base_result = if current_floor > preferred_floor {
122        current_floor
123    } else {
124        preferred_floor
125    };
126    let resulting_floor = if base_result > cap_floor {
127        base_result
128    } else {
129        cap_floor
130    };
131
132    FloorComputation {
133        member_cursor,
134        preferred_floor,
135        resulting_floor,
136    }
137}
liminal_protocol/algebra/floor.rs

liminal_protocol/algebra/
floor.rs
