Skip to main content

qualia_core_db/net/qdnf/resolve/qsr/
handover.rs

1//! Writer epoch handover and fencing (E07.7).
2//!
3//! Fence old admission, drain accepted writes, persist the boundary, then
4//! activate the successor. Two Active writers are Ambiguous; activate_new
5//! returns Conflict. Writes after fence are Unauthorized. Drain copies a
6//! bounded accepted-count so no acknowledged mutation is dropped.
7
8use super::cover::CoverInterval;
9use super::outcome::QsrOutcome;
10use super::traversal::{lookup_into, QsrSnapshot};
11use crate::net::qdnf::errors::QdnfError;
12use crate::net::qdnf::types::{Generation, StrongDigest};
13
14/// Maximum acknowledged mutations retained across drain/transfer.
15pub const ACCEPTED_CAP: u8 = 8;
16
17/// Writer generation state. Two Active owners become Ambiguous.
18#[repr(u8)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum WriterEpoch {
21    Active = 0,
22    Fenced = 1,
23    Draining = 2,
24    Transferred = 3,
25    Ambiguous = 4,
26}
27
28/// Old/new epoch pair plus fencing state and bounded accepted count.
29#[repr(C)]
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct Handover {
32    pub old: u64,
33    pub new: u64,
34    pub state: WriterEpoch,
35    accepted: u8,
36    transferred: u8,
37}
38
39impl Handover {
40    /// Old writer is Active. `new` is the intended successor epoch.
41    pub const fn start(old: u64, new: u64) -> Self {
42        Self {
43            old,
44            new,
45            state: WriterEpoch::Active,
46            accepted: 0,
47            transferred: 0,
48        }
49    }
50
51    /// Competing Active writers. Ownership is unavailable.
52    pub const fn ambiguous(old: u64, new: u64) -> Self {
53        Self {
54            old,
55            new,
56            state: WriterEpoch::Ambiguous,
57            accepted: 0,
58            transferred: 0,
59        }
60    }
61
62    #[inline]
63    /// `Handover::accepted_count`.
64    pub const fn accepted_count(&self) -> u8 {
65        self.accepted
66    }
67
68    #[inline]
69    /// `Handover::transferred_count`.
70    pub const fn transferred_count(&self) -> u8 {
71        self.transferred
72    }
73}
74
75/// Stop new write admission. Active → Fenced.
76pub fn fence_old(h: &mut Handover) {
77    if h.state == WriterEpoch::Active {
78        h.state = WriterEpoch::Fenced;
79    }
80}
81
82/// Finish admitted work. Fenced → Draining. Accepted count is retained.
83pub fn drain_accepted(h: &mut Handover) {
84    if h.state == WriterEpoch::Fenced {
85        h.state = WriterEpoch::Draining;
86    }
87}
88
89/// Commit the final accepted sequence. Draining → Transferred.
90/// Copies the bounded accepted-count; no acknowledged mutation is dropped.
91pub fn persist_boundary(h: &mut Handover) {
92    if h.state == WriterEpoch::Draining {
93        h.transferred = h.accepted;
94        h.state = WriterEpoch::Transferred;
95    }
96}
97
98/// Activate the successor. Transferred → Active.
99///
100/// Two Active writers (or Ambiguous) return Conflict. Incomplete cutover
101/// (Fenced/Draining) is unavailable.
102pub fn activate_new(h: &mut Handover) -> Result<(), QdnfError> {
103    match h.state {
104        WriterEpoch::Transferred => {
105            h.state = WriterEpoch::Active;
106            Ok(())
107        }
108        WriterEpoch::Active => {
109            h.state = WriterEpoch::Ambiguous;
110            Err(QdnfError::Conflict)
111        }
112        WriterEpoch::Ambiguous => Err(QdnfError::Conflict),
113        WriterEpoch::Fenced | WriterEpoch::Draining => Err(QdnfError::Incomplete),
114    }
115}
116
117/// New mutation admission. Only the single Active writer may accept writes.
118pub fn admit_write(h: &Handover) -> Result<(), QdnfError> {
119    match h.state {
120        WriterEpoch::Active => Ok(()),
121        WriterEpoch::Fenced | WriterEpoch::Draining | WriterEpoch::Transferred => {
122            Err(QdnfError::Unauthorized)
123        }
124        WriterEpoch::Ambiguous => Err(QdnfError::Conflict),
125    }
126}
127
128/// Acknowledge a mutation under the Active writer. Bounded by [`ACCEPTED_CAP`].
129pub fn accept_mutation(h: &mut Handover) -> Result<u8, QdnfError> {
130    admit_write(h)?;
131    if h.accepted >= ACCEPTED_CAP {
132        return Err(QdnfError::Capacity);
133    }
134    h.accepted = h.accepted + 1;
135    Ok(h.accepted)
136}
137
138/// Successor snapshot lookup after a completed transfer.
139///
140/// Transferred, or Active with a persisted boundary, may answer. Ambiguous
141/// ownership is Conflict. An incomplete cutover is Incomplete, not Found.
142pub fn lookup_via_handover(
143    h: &Handover,
144    snapshot: &QsrSnapshot,
145    key: &StrongDigest,
146    covers: &[CoverInterval],
147    required_generation: Generation,
148    out: &mut [StrongDigest],
149) -> Result<QsrOutcome, QdnfError> {
150    match h.state {
151        WriterEpoch::Transferred => {}
152        WriterEpoch::Active if h.transferred > 0 => {}
153        WriterEpoch::Ambiguous => return Ok(QsrOutcome::Conflict),
154        WriterEpoch::Fenced | WriterEpoch::Draining | WriterEpoch::Active => {
155            return Ok(QsrOutcome::Incomplete);
156        }
157    }
158    lookup_into(snapshot, key, covers, required_generation, out)
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164
165    #[test]
166    fn fence_rejects_writes() {
167        let mut h = Handover::start(1, 2);
168        assert_eq!(accept_mutation(&mut h), Ok(1));
169        fence_old(&mut h);
170        assert_eq!(h.state, WriterEpoch::Fenced);
171        assert_eq!(admit_write(&h), Err(QdnfError::Unauthorized));
172        assert_eq!(accept_mutation(&mut h), Err(QdnfError::Unauthorized));
173        assert_eq!(h.accepted_count(), 1);
174    }
175
176    #[test]
177    fn drain_retains_accepted_and_transfer_copies_count() {
178        let mut h = Handover::start(3, 4);
179        accept_mutation(&mut h).unwrap();
180        accept_mutation(&mut h).unwrap();
181        fence_old(&mut h);
182        drain_accepted(&mut h);
183        assert_eq!(h.state, WriterEpoch::Draining);
184        assert_eq!(h.accepted_count(), 2);
185        persist_boundary(&mut h);
186        assert_eq!(h.state, WriterEpoch::Transferred);
187        assert_eq!(h.transferred_count(), 2);
188        assert_eq!(h.transferred_count(), h.accepted_count());
189        assert_eq!(admit_write(&h), Err(QdnfError::Unauthorized));
190    }
191
192    #[test]
193    fn activate_after_transfer() {
194        let mut h = Handover::start(5, 6);
195        fence_old(&mut h);
196        drain_accepted(&mut h);
197        persist_boundary(&mut h);
198        assert_eq!(activate_new(&mut h), Ok(()));
199        assert_eq!(h.state, WriterEpoch::Active);
200        assert_eq!(accept_mutation(&mut h), Ok(1));
201    }
202
203    #[test]
204    fn ambiguous_two_active_writers_is_conflict() {
205        let mut h = Handover::start(7, 8);
206        assert_eq!(activate_new(&mut h), Err(QdnfError::Conflict));
207        assert_eq!(h.state, WriterEpoch::Ambiguous);
208        assert_eq!(activate_new(&mut h), Err(QdnfError::Conflict));
209        assert_eq!(admit_write(&h), Err(QdnfError::Conflict));
210    }
211
212    #[test]
213    fn constructed_ambiguous_is_conflict() {
214        let mut h = Handover::ambiguous(1, 2);
215        assert_eq!(h.state, WriterEpoch::Ambiguous);
216        assert_eq!(activate_new(&mut h), Err(QdnfError::Conflict));
217    }
218
219    #[test]
220    fn activate_before_transfer_is_incomplete() {
221        let mut h = Handover::start(1, 2);
222        fence_old(&mut h);
223        assert_eq!(activate_new(&mut h), Err(QdnfError::Incomplete));
224        drain_accepted(&mut h);
225        assert_eq!(activate_new(&mut h), Err(QdnfError::Incomplete));
226    }
227
228    #[test]
229    fn accepted_cap_is_bounded() {
230        let mut h = Handover::start(1, 2);
231        let mut i = 0u8;
232        while i < ACCEPTED_CAP {
233            accept_mutation(&mut h).unwrap();
234            i = i + 1;
235        }
236        assert_eq!(accept_mutation(&mut h), Err(QdnfError::Capacity));
237    }
238
239    #[test]
240    fn lookup_before_transfer_is_incomplete_not_found() {
241        let mut snap = QsrSnapshot::empty(Generation(1));
242        snap.insert(StrongDigest::ZERO, StrongDigest::ZERO).unwrap();
243        let covers = [CoverInterval { start: 0, end: 15 }];
244        let mut out = [StrongDigest::ZERO; 1];
245        let mut h = Handover::start(1, 2);
246        assert_eq!(
247            lookup_via_handover(
248                &h,
249                &snap,
250                &StrongDigest::ZERO,
251                &covers,
252                Generation(1),
253                &mut out
254            ),
255            Ok(QsrOutcome::Incomplete)
256        );
257        fence_old(&mut h);
258        drain_accepted(&mut h);
259        persist_boundary(&mut h);
260        assert_eq!(
261            lookup_via_handover(
262                &h,
263                &snap,
264                &StrongDigest::ZERO,
265                &covers,
266                Generation(1),
267                &mut out
268            ),
269            Ok(QsrOutcome::Found { count: 1 })
270        );
271    }
272}