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}