Skip to main content

memfork_core/
entry.rs

1//! Stored values and the operations that produce them (DESIGN §4.1, §4.2).
2
3use std::collections::BTreeMap;
4
5use bytes::Bytes;
6
7use crate::encode::Canonical;
8use crate::error::{Error, Result};
9
10/// Longest permitted key, in bytes (DESIGN §4.1).
11pub const MAX_KEY_BYTES: usize = 1024;
12
13/// Default importance for an entry that does not specify one (DESIGN §4.1).
14pub const DEFAULT_IMPORTANCE: f32 = 0.5;
15
16/// One stored record.
17///
18/// `value` is opaque bytes; JSON is a convention, not a requirement. The two
19/// sequence numbers are logical clock readings, never wall-clock time, so that
20/// a replay of the same operations reproduces the same entries byte for byte
21/// (DESIGN §3.6).
22#[derive(Debug, Clone, PartialEq)]
23pub struct Entry {
24    /// The opaque stored value.
25    pub value: Bytes,
26    /// Optional vector for [`crate::Db::search`]. Fixed dimension per database.
27    pub embedding: Option<Vec<f32>>,
28    /// Retention weight in `[0, 1]`: how hard eviction tries to keep this.
29    pub importance: f32,
30    /// The branch sequence number at which this key was first written.
31    pub created_seq: u64,
32    /// The branch sequence number at which this entry was last written.
33    pub last_access_seq: u64,
34    /// Expiry measured in commits on the branch holding the entry.
35    pub ttl_commits: Option<u64>,
36    /// Caller metadata. Ordered, so it encodes deterministically.
37    pub meta: BTreeMap<String, String>,
38}
39
40impl Entry {
41    /// Compare the caller-visible content of two entries.
42    ///
43    /// The logical clock fields are deliberately excluded: two branches that
44    /// wrote the same value at different sequence numbers have not made
45    /// conflicting changes (DESIGN §4.2).
46    pub fn content_eq(&self, other: &Entry) -> bool {
47        self.value == other.value
48            && self.embedding == other.embedding
49            && self.importance.to_bits() == other.importance.to_bits()
50            && self.ttl_commits == other.ttl_commits
51            && self.meta == other.meta
52    }
53}
54
55/// The caller-supplied half of a write: everything except the logical clock.
56#[derive(Debug, Clone, PartialEq)]
57pub struct Value {
58    /// The opaque stored value.
59    pub value: Bytes,
60    /// Optional vector for [`crate::Db::search`].
61    pub embedding: Option<Vec<f32>>,
62    /// Retention weight in `[0, 1]`.
63    pub importance: f32,
64    /// Expiry measured in commits on the branch holding the entry.
65    pub ttl_commits: Option<u64>,
66    /// Caller metadata.
67    pub meta: BTreeMap<String, String>,
68}
69
70impl Value {
71    /// A value with default importance and no embedding, TTL or metadata.
72    pub fn new(value: impl Into<Bytes>) -> Self {
73        Self {
74            value: value.into(),
75            embedding: None,
76            importance: DEFAULT_IMPORTANCE,
77            ttl_commits: None,
78            meta: BTreeMap::new(),
79        }
80    }
81
82    /// Attach an embedding.
83    #[must_use]
84    pub fn with_embedding(mut self, embedding: Vec<f32>) -> Self {
85        self.embedding = Some(embedding);
86        self
87    }
88
89    /// Set the retention weight.
90    #[must_use]
91    pub fn with_importance(mut self, importance: f32) -> Self {
92        self.importance = importance;
93        self
94    }
95
96    /// Set the commit-counted TTL.
97    #[must_use]
98    pub fn with_ttl_commits(mut self, ttl: u64) -> Self {
99        self.ttl_commits = Some(ttl);
100        self
101    }
102
103    /// Add one metadata pair.
104    #[must_use]
105    pub fn with_meta(mut self, k: impl Into<String>, v: impl Into<String>) -> Self {
106        self.meta.insert(k.into(), v.into());
107        self
108    }
109
110    pub(crate) fn validate(&self) -> Result<()> {
111        if !(0.0..=1.0).contains(&self.importance) {
112            return Err(Error::BadImportance(self.importance));
113        }
114        if let Some(e) = &self.embedding {
115            if e.is_empty() {
116                return Err(Error::EmptyEmbedding);
117            }
118        }
119        Ok(())
120    }
121
122    pub(crate) fn into_entry(self, seq: u64, created_seq: u64) -> Entry {
123        Entry {
124            value: self.value,
125            embedding: self.embedding,
126            importance: self.importance,
127            created_seq,
128            last_access_seq: seq,
129            ttl_commits: self.ttl_commits,
130            meta: self.meta,
131        }
132    }
133}
134
135impl From<&Entry> for Value {
136    fn from(e: &Entry) -> Self {
137        Value {
138            value: e.value.clone(),
139            embedding: e.embedding.clone(),
140            importance: e.importance,
141            ttl_commits: e.ttl_commits,
142            meta: e.meta.clone(),
143        }
144    }
145}
146
147/// Validate a key against the rules in DESIGN §4.1.
148pub fn validate_key(key: &str) -> Result<()> {
149    if key.is_empty() {
150        return Err(Error::EmptyKey);
151    }
152    if key.len() > MAX_KEY_BYTES {
153        return Err(Error::KeyTooLong(key.len()));
154    }
155    Ok(())
156}
157
158/// One change recorded in a commit. The `ops` of a commit are its change set
159/// and, taken together across history, the append-only event log (DESIGN §4.1).
160#[derive(Debug, Clone, PartialEq)]
161pub enum Op {
162    /// Write a key.
163    Put {
164        /// The key written.
165        key: String,
166        /// The value written.
167        value: Value,
168    },
169    /// Remove a key.
170    Delete {
171        /// The key removed.
172        key: String,
173    },
174    /// Remove a key to stay inside the memory budget (DESIGN §4.4).
175    ///
176    /// Recorded distinctly from [`Op::Delete`] so that eviction is visible in
177    /// the log and reversible by time travel.
178    Evict {
179        /// The key evicted.
180        key: String,
181    },
182}
183
184impl Op {
185    /// The key this operation applies to.
186    pub fn key(&self) -> &str {
187        match self {
188            Op::Put { key, .. } | Op::Delete { key } | Op::Evict { key } => key,
189        }
190    }
191
192    pub(crate) fn encode(&self, c: &mut Canonical) {
193        match self {
194            Op::Put { key, value } => {
195                c.u8(1).str(key);
196                c.bytes(&value.value);
197                c.opt_f32_slice(value.embedding.as_deref());
198                c.f32(value.importance);
199                c.opt_u64(value.ttl_commits);
200                c.u64(value.meta.len() as u64);
201                for (k, v) in &value.meta {
202                    c.str(k).str(v);
203                }
204            }
205            Op::Delete { key } => {
206                c.u8(2).str(key);
207            }
208            Op::Evict { key } => {
209                c.u8(3).str(key);
210            }
211        }
212    }
213}