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