Skip to main content

dive_core/
frontier_codec.rs

1//! Same-process frontier rows tied to one retained, append-only [`Store`].
2//!
3//! This transports opaque handles, including original receiver/history views.
4//! It is not a value encoding or checkpoint format. The enclosing frontier
5//! supplies record lengths, order and checksums; this codec checks its private
6//! lifetime token, row width, canonical identity and actual Store coordinates.
7//!
8//! # Example
9//!
10//! ```
11//! use std::sync::Arc;
12//! use dive_core::{Handle, Store, frontier_codec::FrontierCodec};
13//!
14//! let codec = FrontierCodec::new(Arc::new(Store::new(true)), 1)?;
15//! let bytes = codec.encode(&[Handle::TRUE], &[Handle::TRUE])?;
16//! let row = codec.decode(&bytes)?;
17//! assert_eq!(row.identity, [Handle::TRUE]);
18//! # Ok::<(), dive_core::Error>(())
19//! ```
20
21use std::sync::Arc;
22use std::sync::atomic::{AtomicU64, Ordering};
23
24use crate::node::flags;
25use crate::{Error, Handle, Store};
26
27const MAGIC: &[u8; 8] = b"DIVEHR01";
28const HEADER: usize = 24;
29static NEXT: AtomicU64 = AtomicU64::new(1);
30
31/// Two rows with different roles: mathematical identity and original evaluation.
32#[derive(Debug)]
33pub struct Rows {
34    /// Canonical mathematical state values used for frontier identity and replay.
35    pub identity: Vec<Handle>,
36    /// Actual original values, retaining receiver class and construction history.
37    pub original: Vec<Handle>,
38}
39
40/// A narrow frontier handle codec which keeps its live Store allocated.
41///
42/// Within a process, only the issuing instance decodes its unchanged rows.
43/// Another codec over the same Store does not recover them. There is no file
44/// import, restart or Store-compaction interface.
45#[derive(Debug)]
46pub struct FrontierCodec {
47    store: Arc<Store>,
48    token: u64,
49    variables: usize,
50}
51
52impl FrontierCodec {
53    /// Retains the Store and allocates a private, nonreused process lifetime token.
54    ///
55    /// # Errors
56    /// The process exhausted its codec tokens or a row cannot fit address space.
57    pub fn new(store: Arc<Store>, variables: usize) -> Result<Self, Error> {
58        variables
59            .checked_mul(16)
60            .and_then(|n| n.checked_add(HEADER))
61            .ok_or_else(|| invalid("row size overflow"))?;
62        let token = NEXT
63            .try_update(Ordering::Relaxed, Ordering::Relaxed, |n| n.checked_add(1))
64            .map_err(|_| invalid("process lifetime tokens exhausted"))?;
65        Ok(Self {
66            store,
67            token,
68            variables,
69        })
70    }
71
72    /// Encodes complete canonical and original rows without converting values.
73    ///
74    /// # Errors
75    /// Wrong widths, transient/unknown/lazy handles, a noncanonical identity,
76    /// poisoned Store, or allocation failure. No normalization is performed.
77    pub fn encode(&self, identity: &[Handle], original: &[Handle]) -> Result<Vec<u8>, Error> {
78        if self.store.poisoned() {
79            return Err(invalid("owning Store is poisoned"));
80        }
81        if identity.len() != self.variables || original.len() != self.variables {
82            return Err(invalid("row width differs from the owning plan"));
83        }
84        let mut bytes = Vec::new();
85        bytes
86            .try_reserve_exact(HEADER + self.variables * 16)
87            .map_err(|_| invalid("row allocation"))?;
88        bytes.extend_from_slice(MAGIC);
89        bytes.extend_from_slice(&self.token.to_le_bytes());
90        bytes.extend_from_slice(&(self.variables as u64).to_le_bytes());
91        for (canonical, row) in [(true, identity), (false, original)] {
92            for &handle in row {
93                self.checked(handle.bits(), canonical)?;
94                bytes.extend_from_slice(&handle.bits().to_le_bytes());
95            }
96        }
97        Ok(bytes)
98    }
99
100    /// Decodes a checked enclosing frontier record from this exact live owner.
101    ///
102    /// # Errors
103    /// Invalid version/token/width/length, unknown coordinates, transient/lazy
104    /// values, a noncanonical identity, poisoned Store or allocation failure.
105    pub fn decode(&self, bytes: &[u8]) -> Result<Rows, Error> {
106        if self.store.poisoned() {
107            return Err(invalid("owning Store is poisoned"));
108        }
109        if bytes.len() != HEADER + self.variables * 16
110            || bytes.get(..8) != Some(MAGIC.as_slice())
111            || word(&bytes[8..16]) != self.token
112            || word(&bytes[16..24]) != self.variables as u64
113        {
114            return Err(invalid("invalid format, owner, width or length"));
115        }
116        let mut rows = Rows {
117            identity: Vec::new(),
118            original: Vec::new(),
119        };
120        for (canonical, out, offset) in [
121            (true, &mut rows.identity, HEADER),
122            (false, &mut rows.original, HEADER + self.variables * 8),
123        ] {
124            out.try_reserve_exact(self.variables)
125                .map_err(|_| invalid("decoded row allocation"))?;
126            for chunk in bytes[offset..offset + self.variables * 8]
127                .as_chunks::<8>()
128                .0
129            {
130                out.push(self.checked(word(chunk), canonical)?);
131            }
132        }
133        Ok(rows)
134    }
135
136    fn checked(&self, bits: u64, canonical: bool) -> Result<Handle, Error> {
137        if self.store.poisoned() {
138            return Err(invalid("owning Store is poisoned"));
139        }
140        let handle = Handle(bits);
141        match bits & 7 {
142            0 => {}
143            1 if handle == Handle::FALSE || handle == Handle::TRUE => {}
144            2 | 3 => {
145                let id = u32::try_from(bits >> 3).map_err(|_| invalid("name id"))?;
146                if self.store.strings().text(id).is_none() {
147                    return Err(invalid("unknown name"));
148                }
149            }
150            4 => {
151                let view = self
152                    .store
153                    .retained_view(handle)
154                    .ok_or_else(|| invalid("unknown persistent coordinate"))?;
155                if view.is_lazy() || (canonical && view.flags & flags::VIEW != 0) {
156                    return Err(invalid("lazy value or noncanonical identity"));
157                }
158            }
159            _ => return Err(invalid("invalid, empty or transient handle")),
160        }
161        Ok(handle)
162    }
163}
164
165fn word(bytes: &[u8]) -> u64 {
166    let mut array = [0; 8];
167    array.copy_from_slice(bytes);
168    u64::from_le_bytes(array)
169}
170
171fn invalid(message: &str) -> Error {
172    Error::internal(format!("native frontier handle row: {message}"))
173}
174
175#[cfg(test)]
176#[allow(clippy::unwrap_used, reason = "live-Store codec controls")]
177mod tests {
178    use crate::Heap;
179
180    use super::*;
181
182    #[test]
183    fn rows_keep_genuine_tuple_views_across_arena_reset() {
184        let store = Arc::new(Store::new(true));
185        let mut heap = Heap::new(Arc::clone(&store), true, false);
186        let one = Handle::int(1).unwrap();
187        let two = Handle::int(2).unwrap();
188        let tuple = heap.tuple_literal(&[one, two]);
189        let raw = heap.tuple_literal(&[tuple]);
190        let identity = heap.intern(raw).unwrap();
191        let original = heap.intern_exact(raw).unwrap();
192        let codec = FrontierCodec::new(Arc::clone(&store), 1).unwrap();
193        let bytes = codec.encode(&[identity], &[original]).unwrap();
194        heap.reset();
195        let rows = codec.decode(&bytes).unwrap();
196        assert_eq!(rows.identity, [identity]);
197        assert_eq!(rows.original, [original]);
198        assert!(heap.view(rows.original[0]).is_tuple_literal());
199        assert!(!heap.view(rows.identity[0]).is_tuple_literal());
200        let weak = Arc::downgrade(&store);
201        drop(heap);
202        drop(store);
203        assert!(weak.upgrade().is_some(), "codec retains the actual Store");
204        assert!(codec.decode(&bytes).is_ok());
205    }
206
207    #[test]
208    fn wrong_owner_width_transients_and_corrupt_coordinates_refuse() {
209        let store = Arc::new(Store::new(true));
210        let codec = FrontierCodec::new(Arc::clone(&store), 1).unwrap();
211        let other = FrontierCodec::new(Arc::clone(&store), 1).unwrap();
212        let one = Handle::int(1).unwrap();
213        let bytes = codec.encode(&[one], &[one]).unwrap();
214        assert!(other.decode(&bytes).is_err());
215        for length in [0, 7, 8, 23, 24, bytes.len() - 1] {
216            assert!(codec.decode(&bytes[..length]).is_err());
217        }
218        for bits in [
219            Handle::EMPTY.bits(),
220            6,
221            17,
222            Handle::transient(0, 0).bits(),
223            Handle::persistent(0, 2, 1234).bits(),
224            Handle::string(44).bits(),
225        ] {
226            let mut bad = bytes.clone();
227            bad[HEADER..HEADER + 8].copy_from_slice(&bits.to_le_bytes());
228            assert!(codec.decode(&bad).is_err(), "{bits}");
229        }
230        let mut heap = Heap::new(store, true, false);
231        let tuple = heap.tuple_literal(&[one]);
232        assert!(codec.encode(&[tuple], &[tuple]).is_err());
233        let original = heap.intern_exact(tuple).unwrap();
234        assert!(codec.encode(&[original], &[original]).is_err());
235        assert!(codec.encode(&[], &[one]).is_err());
236        assert!(
237            !heap.store().poisoned(),
238            "bad file coordinates do not read a poison view"
239        );
240        let empty = FrontierCodec::new(Arc::clone(heap.store()), 0).unwrap();
241        let empty_bytes = empty.encode(&[], &[]).unwrap();
242        let _ = heap.view(Handle::persistent(0, 2, crate::handle::MAX_CLASS_INDEX));
243        assert!(empty.decode(&empty_bytes).is_err());
244        assert!(empty.encode(&[], &[]).is_err());
245    }
246}