Skip to content

armgit / ente

Public Imported from GitHub
0

πŸ’š End-to-end encrypted cloud for everything.

vecdb: add graph snapshot sidecar

laurenspriem73e45618df46
diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rs
index a26a14c2c1..fede71ade8 100644
--- a/rust/crates/ml/src/vecdb/graph.rs
+++ b/rust/crates/ml/src/vecdb/graph.rs
@@ -132,9 +132,16 @@ impl Graph {
pub(crate) fn from_parts(
entry_point: Option<u32>,
parts: Vec<GraphNodeParts>,
+ slot_count: usize,
) -> Result<Self, VecDbError> {
let mut slots: HashSet<u32> = HashSet::with_capacity(parts.len());
for part in &parts {
+ if part.slot as usize >= slot_count {
+ return Err(VecDbError::Corrupt(format!(
+ "graph node {} is beyond the {slot_count} arena slots",
+ part.slot
+ )));
+ }
if part.neighbors.len() != part.level as usize + 1 {
return Err(VecDbError::Corrupt(format!(
"graph node {} level {} has {} adjacency lists",
@@ -1499,7 +1506,7 @@ mod tests {
let (arena, graph) = build_fixture(300, 16, 0x8000_0000);
let parts = graph_parts(&graph);
assert_eq!(parts.len(), graph.node_count());
- let rebuilt = Graph::from_parts(graph.entry_point(), parts).unwrap();
+ let rebuilt = Graph::from_parts(graph.entry_point(), parts, arena.slot_count()).unwrap();
assert_identical_graphs(&rebuilt, &graph);
let query = arena
.pack_query(&seeded_unit_vector(0x8111_0000, 16))
@@ -1528,16 +1535,17 @@ mod tests {
level,
neighbors,
};
- assert!(Graph::from_parts(None, Vec::new()).is_ok());
- assert!(Graph::from_parts(Some(0), vec![node(0, 0, vec![Vec::new()])]).is_ok());
- assert!(Graph::from_parts(Some(0), vec![node(0, 1, vec![Vec::new()])]).is_err());
- assert!(Graph::from_parts(Some(0), vec![node(0, 0, vec![vec![9]])]).is_err());
- assert!(Graph::from_parts(None, vec![node(0, 0, vec![Vec::new()])]).is_err());
- assert!(Graph::from_parts(Some(5), vec![node(0, 0, vec![Vec::new()])]).is_err());
+ assert!(Graph::from_parts(None, Vec::new(), 0).is_ok());
+ assert!(Graph::from_parts(Some(0), vec![node(0, 0, vec![Vec::new()])], 1).is_ok());
+ assert!(Graph::from_parts(Some(0), vec![node(0, 1, vec![Vec::new()])], 1).is_err());
+ assert!(Graph::from_parts(Some(0), vec![node(0, 0, vec![vec![9]])], 10).is_err());
+ assert!(Graph::from_parts(None, vec![node(0, 0, vec![Vec::new()])], 1).is_err());
+ assert!(Graph::from_parts(Some(5), vec![node(0, 0, vec![Vec::new()])], 6).is_err());
assert!(
Graph::from_parts(
Some(0),
- vec![node(0, 0, vec![Vec::new()]), node(0, 0, vec![Vec::new()])]
+ vec![node(0, 0, vec![Vec::new()]), node(0, 0, vec![Vec::new()])],
+ 1
)
.is_err()
);
@@ -1547,12 +1555,32 @@ mod tests {
vec![
node(0, 0, vec![vec![1]]),
node(1, 1, vec![vec![0], Vec::new()])
- ]
+ ],
+ 2
)
.is_ok()
);
}
+ #[test]
+ fn from_parts_rejects_slots_beyond_the_arena() {
+ let node = |slot: u32, level: u8, neighbors: Vec<Vec<u32>>| GraphNodeParts {
+ slot,
+ level,
+ neighbors,
+ };
+ assert!(Graph::from_parts(Some(0), vec![node(0, 0, vec![Vec::new()])], 0).is_err());
+ assert!(Graph::from_parts(Some(2), vec![node(2, 0, vec![Vec::new()])], 2).is_err());
+ assert!(
+ Graph::from_parts(
+ Some(u32::MAX - 1),
+ vec![node(u32::MAX - 1, 0, vec![Vec::new()])],
+ 3
+ )
+ .is_err()
+ );
+ }
+
#[test]
fn from_parts_tolerates_stale_edges_to_shrunken_levels() {
let node = |slot: u32, level: u8, neighbors: Vec<Vec<u32>>| GraphNodeParts {
@@ -1567,6 +1595,7 @@ mod tests {
node(1, 1, vec![vec![0, 2], vec![0]]),
node(2, 0, vec![vec![1]]),
],
+ 3,
)
.unwrap();
let mut arena = VectorArena::new(8).unwrap();
@@ -1589,6 +1618,109 @@ mod tests {
assert_eq!(keys(&found), ["c", "b", "a"]);
}
+ #[test]
+ fn tolerated_self_edges_duplicates_and_overfull_lists_stay_safe() {
+ let dims = 16;
+ let mut arena = build_arena(40, dims, 0x00E0_0000);
+ let parts: Vec<GraphNodeParts> = (0..40u32)
+ .map(|slot| GraphNodeParts {
+ slot,
+ level: 0,
+ neighbors: vec![if slot == 0 {
+ (0..40).collect()
+ } else {
+ vec![0, 0, slot, 0]
+ }],
+ })
+ .collect();
+ let graph = Graph::from_parts(Some(0), parts, arena.slot_count()).unwrap();
+ assert!(graph.neighbors_of(0, 0).len() > neighbor_cap(0));
+ let query = arena
+ .pack_query(&seeded_unit_vector(0x00E1_0000, dims))
+ .unwrap();
+ let reference = reference_ranking(&arena, &query, None);
+ let top = search(
+ Some(&graph),
+ &arena,
+ &query,
+ &params(Some(10), None, false),
+ None,
+ );
+ for (hit, &(distance, slot)) in top.iter().zip(&reference) {
+ assert_eq!(hit.key, arena.key_of_slot(slot).unwrap());
+ assert_eq!(hit.distance, distance);
+ }
+ let everything = search(
+ Some(&graph),
+ &arena,
+ &query,
+ &params(None, Some(2.5), false),
+ None,
+ );
+ assert_eq!(everything.len(), 40);
+ let mut graph = graph;
+ apply_upsert(
+ &mut arena,
+ &mut graph,
+ "fresh",
+ &seeded_unit_vector(0x00E2_0000, dims),
+ );
+ let fresh_query = arena
+ .pack_query(&seeded_unit_vector(0x00E2_0000, dims))
+ .unwrap();
+ let found = search(
+ Some(&graph),
+ &arena,
+ &fresh_query,
+ &params(Some(1), None, false),
+ None,
+ );
+ assert_eq!(keys(&found), ["fresh"]);
+ let all = search(
+ Some(&graph),
+ &arena,
+ &fresh_query,
+ &params(None, Some(2.5), false),
+ None,
+ );
+ assert_sorted(&all);
+ assert!(all.len() <= 41);
+ assert!(all.iter().any(|hit| hit.key == "fresh"));
+ }
+
+ #[test]
+ fn entry_point_below_the_top_level_still_reaches_every_node() {
+ let node = |slot: u32, level: u8, neighbors: Vec<Vec<u32>>| GraphNodeParts {
+ slot,
+ level,
+ neighbors,
+ };
+ let graph = Graph::from_parts(
+ Some(1),
+ vec![
+ node(0, 2, vec![vec![1, 2], vec![2], vec![2]]),
+ node(1, 0, vec![vec![0]]),
+ node(2, 2, vec![vec![0], vec![0], vec![0]]),
+ ],
+ 3,
+ )
+ .unwrap();
+ let mut arena = VectorArena::new(8).unwrap();
+ arena.upsert("a", &axis_vector(8, 0)).unwrap();
+ arena.upsert("b", &axis_vector(8, 1)).unwrap();
+ arena.upsert("c", &axis_vector(8, 2)).unwrap();
+ let query = arena.pack_query(&axis_vector(8, 2)).unwrap();
+ let found = search(
+ Some(&graph),
+ &arena,
+ &query,
+ &params(Some(3), None, false),
+ None,
+ );
+ assert_eq!(found.len(), 3);
+ assert_eq!(found[0].key, "c");
+ }
+
#[test]
fn repeated_reinserts_shrink_levels_yet_keep_every_node_reachable() {
let (mut arena, mut graph) = build_fixture(600, 16, 0xB000_0000);
@@ -1604,7 +1736,9 @@ mod tests {
graph.reinsert(victim, &arena);
stale_seen |= stale_downward_edge_exists(&graph);
assert_graph_invariants(&graph);
- let reloaded = Graph::from_parts(graph.entry_point(), graph_parts(&graph)).unwrap();
+ let reloaded =
+ Graph::from_parts(graph.entry_point(), graph_parts(&graph), arena.slot_count())
+ .unwrap();
assert_identical_graphs(&reloaded, &graph);
let query = arena.pack_query(&vector).unwrap();
let top = search(
@@ -1625,7 +1759,9 @@ mod tests {
assert_eq!(everything.len(), 600);
}
assert!(stale_seen);
- let rebuilt = Graph::from_parts(graph.entry_point(), graph_parts(&graph)).unwrap();
+ let rebuilt =
+ Graph::from_parts(graph.entry_point(), graph_parts(&graph), arena.slot_count())
+ .unwrap();
assert_identical_graphs(&rebuilt, &graph);
let query = arena
.pack_query(&seeded_unit_vector(0xB200_0000, 16))
@@ -1691,7 +1827,9 @@ mod tests {
let (arena, graph) = (&primary.0, &primary.1);
assert_graph_invariants(graph);
assert_eq!(arena.live_count(), live.len());
- let reloaded = Graph::from_parts(graph.entry_point(), graph_parts(graph)).unwrap();
+ let reloaded =
+ Graph::from_parts(graph.entry_point(), graph_parts(graph), arena.slot_count())
+ .unwrap();
assert_identical_graphs(&reloaded, graph);
for _ in 0..3 {
let query_vector = seeded_unit_vector(splitmix64(&mut state), dims);
@@ -1774,7 +1912,8 @@ mod tests {
}
assert_identical_graphs(&primary.1, &shadow.1);
let (arena, graph) = (&primary.0, &primary.1);
- let rebuilt = Graph::from_parts(graph.entry_point(), graph_parts(graph)).unwrap();
+ let rebuilt =
+ Graph::from_parts(graph.entry_point(), graph_parts(graph), arena.slot_count()).unwrap();
assert_identical_graphs(&rebuilt, graph);
let query = arena
.pack_query(&seeded_unit_vector(0xC900_0000, dims))
diff --git a/rust/crates/ml/src/vecdb/snapshot.rs b/rust/crates/ml/src/vecdb/snapshot.rs
index 8b13789179..e369b55a75 100644
--- a/rust/crates/ml/src/vecdb/snapshot.rs
+++ b/rust/crates/ml/src/vecdb/snapshot.rs
@@ -1 +1,810 @@
+use std::fs::File;
+use std::io::{ErrorKind, Write};
+use std::path::{Path, PathBuf};
+use super::VecDbError;
+use super::graph::{Graph, GraphNodeParts};
+
+const MAGIC: [u8; 4] = *b"EVDG";
+const FORMAT_VERSION: u16 = 1;
+const NO_ENTRY_POINT: u32 = u32::MAX;
+const CRC_LEN: usize = 4;
+const FIXED_PREFIX_LEN: usize = 39;
+const MIN_SNAPSHOT_LEN: usize = FIXED_PREFIX_LEN + CRC_LEN;
+const MIN_NODE_LEN: usize = 7;
+
+#[allow(dead_code)]
+pub(crate) struct LoadedSnapshot {
+ pub(crate) covered_log_offset: u64,
+ pub(crate) entry_point: Option<u32>,
+ pub(crate) parts: Vec<GraphNodeParts>,
+}
+
+#[allow(dead_code)]
+pub(crate) fn snapshot_path(log_path: &Path) -> PathBuf {
+ append_suffix(log_path, ".graph")
+}
+
+#[allow(dead_code)]
+pub(crate) fn write_snapshot(
+ log_path: &Path,
+ generation: [u8; 16],
+ covered_log_offset: u64,
+ graph: &Graph,
+) -> Result<(), VecDbError> {
+ let bytes = encode_snapshot(&generation, covered_log_offset, graph);
+ let target = snapshot_path(log_path);
+ let temp = temp_snapshot_path(log_path);
+ write_and_swap(&bytes, &temp, &target).inspect_err(|_| {
+ let _ = std::fs::remove_file(&temp);
+ })
+}
+
+#[allow(dead_code)]
+pub(crate) fn load_snapshot(
+ log_path: &Path,
+ expected_generation: [u8; 16],
+ log_end_offset: u64,
+) -> Option<LoadedSnapshot> {
+ let path = snapshot_path(log_path);
+ let bytes = match std::fs::read(&path) {
+ Ok(bytes) => bytes,
+ Err(error) if error.kind() == ErrorKind::NotFound => return None,
+ Err(error) => {
+ log::debug!("discarding snapshot {}: {error}", path.display());
+ return None;
+ }
+ };
+ match decode_snapshot(&bytes, &expected_generation, log_end_offset) {
+ Ok(loaded) => Some(loaded),
+ Err(reason) => {
+ log::debug!("discarding snapshot {}: {reason}", path.display());
+ None
+ }
+ }
+}
+
+#[allow(dead_code)]
+pub(crate) fn remove_snapshot(log_path: &Path) -> Result<(), VecDbError> {
+ remove_if_present(&snapshot_path(log_path))?;
+ remove_if_present(&temp_snapshot_path(log_path))
+}
+
+fn encode_snapshot(generation: &[u8; 16], covered_log_offset: u64, graph: &Graph) -> Vec<u8> {
+ let mut bytes = Vec::new();
+ bytes.extend_from_slice(&MAGIC);
+ bytes.extend_from_slice(&FORMAT_VERSION.to_le_bytes());
+ bytes.extend_from_slice(generation);
+ bytes.extend_from_slice(&covered_log_offset.to_le_bytes());
+ let entry_marker = graph.entry_point().unwrap_or(NO_ENTRY_POINT);
+ bytes.extend_from_slice(&entry_marker.to_le_bytes());
+ let top_level = graph
+ .entry_point()
+ .and_then(|slot| graph.level_of(slot))
+ .unwrap_or(0);
+ bytes.push(top_level);
+ bytes.extend_from_slice(&(graph.node_count() as u32).to_le_bytes());
+ for slot in graph.slots() {
+ let level = graph.level_of(slot).unwrap_or(0);
+ bytes.extend_from_slice(&slot.to_le_bytes());
+ bytes.push(level);
+ for layer in 0..=level {
+ let neighbors = graph.neighbors_of(slot, layer);
+ bytes.extend_from_slice(&(neighbors.len() as u16).to_le_bytes());
+ for &neighbor in neighbors {
+ bytes.extend_from_slice(&neighbor.to_le_bytes());
+ }
+ }
+ }
+ let crc = crc32fast::hash(&bytes[MAGIC.len()..]);
+ bytes.extend_from_slice(&crc.to_le_bytes());
+ bytes
+}
+
+fn decode_snapshot(
+ bytes: &[u8],
+ expected_generation: &[u8; 16],
+ log_end_offset: u64,
+) -> Result<LoadedSnapshot, String> {
+ if bytes.len() < MIN_SNAPSHOT_LEN {
+ return Err(format!(
+ "{} bytes is shorter than the {MIN_SNAPSHOT_LEN}-byte minimum",
+ bytes.len()
+ ));
+ }
+ if bytes[0..4] != MAGIC {
+ return Err(format!("bad magic {:02x?}", &bytes[0..4]));
+ }
+ let body_end = bytes.len() - CRC_LEN;
+ let stored_crc = u32::from_le_bytes([
+ bytes[body_end],
+ bytes[body_end + 1],
+ bytes[body_end + 2],
+ bytes[body_end + 3],
+ ]);
+ let computed_crc = crc32fast::hash(&bytes[MAGIC.len()..body_end]);
+ if stored_crc != computed_crc {
+ return Err(format!(
+ "crc mismatch: stored {stored_crc:08x}, computed {computed_crc:08x}"
+ ));
+ }
+ let mut reader = BodyReader {
+ bytes: &bytes[..body_end],
+ position: MAGIC.len(),
+ };
+ let version = reader.read_u16().ok_or("truncated header")?;
+ if version != FORMAT_VERSION {
+ return Err(format!("unsupported snapshot format version {version}"));
+ }
+ let generation: [u8; 16] = reader
+ .take(16)
+ .and_then(|slice| slice.try_into().ok())
+ .ok_or("truncated header")?;
+ if generation != *expected_generation {
+ return Err("generation does not match the log".to_string());
+ }
+ let covered_log_offset = reader.read_u64().ok_or("truncated header")?;
+ if covered_log_offset > log_end_offset {
+ return Err(format!(
+ "covered offset {covered_log_offset} is past the log end {log_end_offset}"
+ ));
+ }
+ let entry_marker = reader.read_u32().ok_or("truncated header")?;
+ let top_level = reader.read_u8().ok_or("truncated header")?;
+ let node_count = reader.read_u32().ok_or("truncated header")? as usize;
+ let mut parts = Vec::with_capacity(node_count.min(reader.remaining() / MIN_NODE_LEN));
+ for _ in 0..node_count {
+ let slot = reader.read_u32().ok_or("truncated node")?;
+ let level = reader.read_u8().ok_or("truncated node")?;
+ let mut neighbors = Vec::with_capacity(level as usize + 1);
+ for _ in 0..=level {
+ let count = reader.read_u16().ok_or("truncated neighbor list")? as usize;
+ let raw = reader
+ .take(count * size_of::<u32>())
+ .ok_or("truncated neighbor list")?;
+ neighbors.push(
+ raw.as_chunks::<4>()
+ .0
+ .iter()
+ .map(|chunk| u32::from_le_bytes(*chunk))
+ .collect(),
+ );
+ }
+ parts.push(GraphNodeParts {
+ slot,
+ level,
+ neighbors,
+ });
+ }
+ if !reader.is_exhausted() {
+ return Err(format!(
+ "{} unparsed bytes after {node_count} nodes",
+ reader.remaining()
+ ));
+ }
+ let entry_point = (entry_marker != NO_ENTRY_POINT).then_some(entry_marker);
+ if entry_point.is_none() != parts.is_empty() {
+ return Err(format!(
+ "entry point marker {entry_marker:08x} disagrees with node count {node_count}"
+ ));
+ }
+ let max_level = parts.iter().map(|part| part.level).max().unwrap_or(0);
+ if top_level != max_level {
+ return Err(format!(
+ "top level {top_level} disagrees with the nodes' max level {max_level}"
+ ));
+ }
+ Ok(LoadedSnapshot {
+ covered_log_offset,
+ entry_point,
+ parts,
+ })
+}
+
+struct BodyReader<'a> {
+ bytes: &'a [u8],
+ position: usize,
+}
+
+impl<'a> BodyReader<'a> {
+ fn take(&mut self, len: usize) -> Option<&'a [u8]> {
+ let end = self.position.checked_add(len)?;
+ if end > self.bytes.len() {
+ return None;
+ }
+ let slice = &self.bytes[self.position..end];
+ self.position = end;
+ Some(slice)
+ }
+
+ fn read_u8(&mut self) -> Option<u8> {
+ Some(self.take(1)?[0])
+ }
+
+ fn read_u16(&mut self) -> Option<u16> {
+ self.take(2)?.try_into().ok().map(u16::from_le_bytes)
+ }
+
+ fn read_u32(&mut self) -> Option<u32> {
+ self.take(4)?.try_into().ok().map(u32::from_le_bytes)
+ }
+
+ fn read_u64(&mut self) -> Option<u64> {
+ self.take(8)?.try_into().ok().map(u64::from_le_bytes)
+ }
+
+ fn remaining(&self) -> usize {
+ self.bytes.len() - self.position
+ }
+
+ fn is_exhausted(&self) -> bool {
+ self.position == self.bytes.len()
+ }
+}
+
+fn write_and_swap(bytes: &[u8], temp: &Path, target: &Path) -> Result<(), VecDbError> {
+ let mut file = File::create(temp).map_err(|source| io_error(temp, source))?;
+ file.write_all(bytes)
+ .map_err(|source| io_error(temp, source))?;
+ file.sync_all().map_err(|source| io_error(temp, source))?;
+ drop(file);
+ rename_over(temp, target)?;
+ sync_parent_dir_best_effort(target);
+ Ok(())
+}
+
+fn rename_over(temp: &Path, target: &Path) -> Result<(), VecDbError> {
+ match std::fs::rename(temp, target) {
+ Ok(()) => Ok(()),
+ #[cfg(windows)]
+ Err(_) => {
+ let _ = std::fs::remove_file(target);
+ std::fs::rename(temp, target).map_err(|source| io_error(temp, source))
+ }
+ #[cfg(not(windows))]
+ Err(source) => Err(io_error(temp, source)),
+ }
+}
+
+fn remove_if_present(path: &Path) -> Result<(), VecDbError> {
+ match std::fs::remove_file(path) {
+ Ok(()) => Ok(()),
+ Err(error) if error.kind() == ErrorKind::NotFound => Ok(()),
+ Err(source) => Err(io_error(path, source)),
+ }
+}
+
+fn temp_snapshot_path(log_path: &Path) -> PathBuf {
+ append_suffix(log_path, ".graph.tmp")
+}
+
+fn append_suffix(path: &Path, suffix: &str) -> PathBuf {
+ let mut extended = path.as_os_str().to_os_string();
+ extended.push(suffix);
+ PathBuf::from(extended)
+}
+
+fn io_error(path: &Path, source: std::io::Error) -> VecDbError {
+ VecDbError::Io {
+ path: path.to_path_buf(),
+ source,
+ }
+}
+
+#[cfg(unix)]
+fn sync_parent_dir_best_effort(path: &Path) {
+ let parent = match path.parent() {
+ Some(parent) if !parent.as_os_str().is_empty() => parent,
+ _ => Path::new("."),
+ };
+ let _ = File::open(parent).and_then(|dir| dir.sync_all());
+}
+
+#[cfg(not(unix))]
+fn sync_parent_dir_best_effort(_path: &Path) {}
+
+#[cfg(test)]
+mod tests {
+ use tempfile::TempDir;
+
+ use super::super::SearchParams;
+ use super::super::arena::{UpsertOutcome, VectorArena};
+ use super::super::graph::search;
+ use super::*;
+
+ const GOLDEN: [u8; 86] = [
+ 0x45, 0x56, 0x44, 0x47, 0x01, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
+ 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x2c, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x01, 0x00, 0x00, 0x00, 0x01, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
+ 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x02, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x02, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00,
+ 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0x00, 0x64, 0xa1, 0xbc, 0xba,
+ ];
+
+ fn golden_generation() -> [u8; 16] {
+ std::array::from_fn(|index| index as u8)
+ }
+
+ fn golden_graph() -> Graph {
+ Graph::from_parts(
+ Some(1),
+ vec![
+ GraphNodeParts {
+ slot: 0,
+ level: 0,
+ neighbors: vec![vec![1]],
+ },
+ GraphNodeParts {
+ slot: 1,
+ level: 1,
+ neighbors: vec![vec![0, 2], vec![0]],
+ },
+ GraphNodeParts {
+ slot: 2,
+ level: 0,
+ neighbors: vec![vec![1]],
+ },
+ ],
+ 3,
+ )
+ .unwrap()
+ }
+
+ fn load_golden(log_path: &Path) -> Option<LoadedSnapshot> {
+ load_snapshot(log_path, golden_generation(), 300)
+ }
+
+ fn refresh_crc(bytes: &mut [u8]) {
+ let body_end = bytes.len() - CRC_LEN;
+ let crc = crc32fast::hash(&bytes[MAGIC.len()..body_end]);
+ bytes[body_end..].copy_from_slice(&crc.to_le_bytes());
+ }
+
+ fn assert_discarded(mutate: impl FnOnce(&mut Vec<u8>)) {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ let mut bytes = GOLDEN.to_vec();
+ mutate(&mut bytes);
+ std::fs::write(snapshot_path(&log_path), &bytes).unwrap();
+ assert!(load_golden(&log_path).is_none());
+ }
+
+ fn splitmix64(state: &mut u64) -> u64 {
+ *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+ let mut z = *state;
+ z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+ z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+ z ^ (z >> 31)
+ }
+
+ fn seeded_unit_vector(seed: u64, dims: usize) -> Vec<f32> {
+ let mut state = seed;
+ let mut values: Vec<f32> = (0..dims)
+ .map(|_| {
+ let unit = (splitmix64(&mut state) >> 40) as f32 / (1u64 << 24) as f32;
+ unit * 2.0 - 1.0
+ })
+ .collect();
+ let norm = values.iter().map(|value| value * value).sum::<f32>().sqrt();
+ for value in &mut values {
+ *value /= norm;
+ }
+ values
+ }
+
+ fn build_arena(count: usize, dims: usize, seed: u64) -> VectorArena {
+ let mut arena = VectorArena::new(dims).unwrap();
+ for index in 0..count {
+ arena
+ .upsert(
+ &format!("key-{index}"),
+ &seeded_unit_vector(seed + index as u64, dims),
+ )
+ .unwrap();
+ }
+ arena
+ }
+
+ fn stale_downward_edge_exists(graph: &Graph) -> bool {
+ graph.slots().any(|slot| {
+ let level = graph.level_of(slot).unwrap();
+ (0..=level).any(|layer| {
+ graph
+ .neighbors_of(slot, layer)
+ .iter()
+ .any(|&neighbor| graph.level_of(neighbor).unwrap() < layer)
+ })
+ })
+ }
+
+ fn assert_identical_graphs(first: &Graph, second: &Graph) {
+ assert_eq!(first.entry_point(), second.entry_point());
+ assert_eq!(
+ first.slots().collect::<Vec<_>>(),
+ second.slots().collect::<Vec<_>>()
+ );
+ for slot in first.slots() {
+ assert_eq!(first.level_of(slot), second.level_of(slot));
+ let level = first.level_of(slot).unwrap();
+ for layer in 0..=level {
+ assert_eq!(
+ first.neighbors_of(slot, layer),
+ second.neighbors_of(slot, layer)
+ );
+ }
+ }
+ }
+
+ fn churned_fixture(dims: usize) -> (VectorArena, Graph) {
+ let mut arena = build_arena(600, dims, 0x00A1_0000);
+ let mut graph = Graph::rebuild(&arena);
+ for index in [3, 41, 87, 150, 199] {
+ arena.remove(&format!("key-{index}")).unwrap();
+ }
+ let mut stale_seen = false;
+ for round in 0..40u64 {
+ let victim = graph
+ .entry_point()
+ .filter(|&slot| arena.is_alive(slot))
+ .unwrap_or_else(|| arena.live_slots().next().unwrap());
+ let key = arena.key_of_slot(victim).unwrap().to_string();
+ let outcome = arena
+ .upsert(&key, &seeded_unit_vector(0x00A2_0000 + round, dims))
+ .unwrap();
+ graph.reinsert(outcome.slot(), &arena);
+ stale_seen |= stale_downward_edge_exists(&graph);
+ }
+ let outcome = arena
+ .upsert("recycled", &seeded_unit_vector(0x00A3_0000, dims))
+ .unwrap();
+ assert!(matches!(outcome, UpsertOutcome::RecycledSlot(_)));
+ graph.reinsert(outcome.slot(), &arena);
+ assert!(stale_seen);
+ (arena, graph)
+ }
+
+ fn params(limit: Option<usize>, max_distance: Option<f32>) -> SearchParams {
+ SearchParams {
+ limit,
+ max_distance,
+ exact: false,
+ allowed_keys: None,
+ }
+ }
+
+ #[test]
+ fn snapshot_path_appends_the_graph_extension() {
+ assert_eq!(
+ snapshot_path(Path::new("/a/vectors")),
+ Path::new("/a/vectors.graph")
+ );
+ assert_eq!(
+ snapshot_path(Path::new("/a/vectors.db")),
+ Path::new("/a/vectors.db.graph")
+ );
+ assert_eq!(
+ temp_snapshot_path(Path::new("/a/vectors.db")),
+ Path::new("/a/vectors.db.graph.tmp")
+ );
+ }
+
+ #[test]
+ fn golden_bytes_pin_format_v1() {
+ let dir = TempDir::new().unwrap();
+ let written_path = dir.path().join("written");
+ write_snapshot(&written_path, golden_generation(), 300, &golden_graph()).unwrap();
+ assert_eq!(std::fs::read(snapshot_path(&written_path)).unwrap(), GOLDEN);
+ let literal_path = dir.path().join("literal");
+ std::fs::write(snapshot_path(&literal_path), GOLDEN).unwrap();
+ let loaded = load_golden(&literal_path).unwrap();
+ assert_eq!(loaded.covered_log_offset, 300);
+ assert_eq!(loaded.entry_point, Some(1));
+ assert_eq!(loaded.parts.len(), 3);
+ let expected: [(u32, u8, Vec<Vec<u32>>); 3] = [
+ (0, 0, vec![vec![1]]),
+ (1, 1, vec![vec![0, 2], vec![0]]),
+ (2, 0, vec![vec![1]]),
+ ];
+ for (part, (slot, level, neighbors)) in loaded.parts.iter().zip(&expected) {
+ assert_eq!(part.slot, *slot);
+ assert_eq!(part.level, *level);
+ assert_eq!(&part.neighbors, neighbors);
+ }
+ let rebuilt = Graph::from_parts(loaded.entry_point, loaded.parts, 3).unwrap();
+ assert_identical_graphs(&rebuilt, &golden_graph());
+ }
+
+ #[test]
+ fn roundtrip_reconstructs_identical_graph_and_results() {
+ let dims = 16;
+ let (arena, graph) = churned_fixture(dims);
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ let generation = [7u8; 16];
+ write_snapshot(&log_path, generation, 4096, &graph).unwrap();
+ assert!(!temp_snapshot_path(&log_path).exists());
+ let loaded = load_snapshot(&log_path, generation, 4096).unwrap();
+ assert_eq!(loaded.covered_log_offset, 4096);
+ assert_eq!(loaded.entry_point, graph.entry_point());
+ let rebuilt =
+ Graph::from_parts(loaded.entry_point, loaded.parts, arena.slot_count()).unwrap();
+ assert_identical_graphs(&rebuilt, &graph);
+ for seed in 0..6u64 {
+ let query = arena
+ .pack_query(&seeded_unit_vector(0x00A4_0000 + seed, dims))
+ .unwrap();
+ for search_params in [
+ params(Some(10), None),
+ params(None, Some(0.9)),
+ params(Some(3), Some(1.2)),
+ ] {
+ let original = search(Some(&graph), &arena, &query, &search_params, None);
+ let reconstructed = search(Some(&rebuilt), &arena, &query, &search_params, None);
+ assert_eq!(original, reconstructed);
+ assert!(!original.is_empty());
+ }
+ }
+ }
+
+ #[test]
+ fn empty_graph_round_trips() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ write_snapshot(&log_path, [3u8; 16], 32, &Graph::new()).unwrap();
+ assert_eq!(
+ std::fs::read(snapshot_path(&log_path)).unwrap().len(),
+ MIN_SNAPSHOT_LEN
+ );
+ let loaded = load_snapshot(&log_path, [3u8; 16], 32).unwrap();
+ assert_eq!(loaded.covered_log_offset, 32);
+ assert_eq!(loaded.entry_point, None);
+ assert!(loaded.parts.is_empty());
+ let rebuilt = Graph::from_parts(loaded.entry_point, loaded.parts, 0).unwrap();
+ assert_eq!(rebuilt.entry_point(), None);
+ assert_eq!(rebuilt.node_count(), 0);
+ }
+
+ #[test]
+ fn identical_graphs_serialize_to_identical_bytes() {
+ let dims = 16;
+ let arena = build_arena(150, dims, 0x00B1_0000);
+ let first = Graph::rebuild(&arena);
+ let second = Graph::rebuild(&arena);
+ let dir = TempDir::new().unwrap();
+ let first_path = dir.path().join("first");
+ let second_path = dir.path().join("second");
+ write_snapshot(&first_path, [5u8; 16], 777, &first).unwrap();
+ write_snapshot(&second_path, [5u8; 16], 777, &second).unwrap();
+ let first_bytes = std::fs::read(snapshot_path(&first_path)).unwrap();
+ let second_bytes = std::fs::read(snapshot_path(&second_path)).unwrap();
+ assert_eq!(first_bytes, second_bytes);
+ }
+
+ #[test]
+ fn missing_snapshot_loads_none() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ assert!(load_golden(&log_path).is_none());
+ }
+
+ #[test]
+ fn every_truncation_loads_none() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ let path = snapshot_path(&log_path);
+ for cut in 0..GOLDEN.len() {
+ std::fs::write(&path, &GOLDEN[..cut]).unwrap();
+ assert!(load_golden(&log_path).is_none(), "cut at {cut} parsed");
+ }
+ std::fs::write(&path, GOLDEN).unwrap();
+ assert!(load_golden(&log_path).is_some());
+ }
+
+ #[test]
+ fn fuzzed_bytes_never_panic_decode_from_parts_or_search() {
+ let dims = 8;
+ let arena = build_arena(3, dims, 0x00F0_0000);
+ let query = arena
+ .pack_query(&seeded_unit_vector(0x00F1_0000, dims))
+ .unwrap();
+ let generation = golden_generation();
+ let mut decoded = 0usize;
+ let mut searched = 0usize;
+ let mut exercise = |bytes: &[u8]| {
+ let Ok(loaded) = decode_snapshot(bytes, &generation, 300) else {
+ return;
+ };
+ decoded += 1;
+ let Ok(graph) = Graph::from_parts(loaded.entry_point, loaded.parts, arena.slot_count())
+ else {
+ return;
+ };
+ for search_params in [params(Some(2), None), params(None, Some(2.5))] {
+ let found = search(Some(&graph), &arena, &query, &search_params, None);
+ assert!(found.len() <= 3);
+ }
+ searched += 1;
+ };
+ exercise(&GOLDEN);
+ let mut state = 0x00F2_0000u64;
+ for round in 0..4000u64 {
+ let mut bytes = GOLDEN.to_vec();
+ let flips = 1 + (splitmix64(&mut state) % 4) as usize;
+ for _ in 0..flips {
+ let index = (splitmix64(&mut state) as usize) % bytes.len();
+ bytes[index] ^= (splitmix64(&mut state) % 255 + 1) as u8;
+ }
+ if round % 2 == 0 {
+ refresh_crc(&mut bytes);
+ }
+ exercise(&bytes);
+ }
+ for _ in 0..2000u64 {
+ let len = (splitmix64(&mut state) % 160) as usize;
+ let bytes: Vec<u8> = (0..len).map(|_| splitmix64(&mut state) as u8).collect();
+ exercise(&bytes);
+ }
+ assert!(decoded >= 1);
+ assert!(searched >= 1);
+ }
+
+ #[test]
+ fn forged_out_of_range_slot_is_rejected_by_from_parts() {
+ let slot = u32::MAX - 1;
+ let mut bytes = Vec::new();
+ bytes.extend_from_slice(&MAGIC);
+ bytes.extend_from_slice(&FORMAT_VERSION.to_le_bytes());
+ bytes.extend_from_slice(&golden_generation());
+ bytes.extend_from_slice(&300u64.to_le_bytes());
+ bytes.extend_from_slice(&slot.to_le_bytes());
+ bytes.push(0);
+ bytes.extend_from_slice(&1u32.to_le_bytes());
+ bytes.extend_from_slice(&slot.to_le_bytes());
+ bytes.push(0);
+ bytes.extend_from_slice(&0u16.to_le_bytes());
+ let crc = crc32fast::hash(&bytes[MAGIC.len()..]);
+ bytes.extend_from_slice(&crc.to_le_bytes());
+ let loaded = decode_snapshot(&bytes, &golden_generation(), 300).unwrap();
+ assert_eq!(loaded.entry_point, Some(slot));
+ assert!(Graph::from_parts(loaded.entry_point, loaded.parts, 3).is_err());
+ }
+
+ #[test]
+ fn bad_magic_is_discarded() {
+ assert_discarded(|bytes| bytes[0] = b'X');
+ }
+
+ #[test]
+ fn bad_version_is_discarded() {
+ assert_discarded(|bytes| {
+ bytes[4..6].copy_from_slice(&2u16.to_le_bytes());
+ refresh_crc(bytes);
+ });
+ }
+
+ #[test]
+ fn generation_mismatch_is_discarded() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ std::fs::write(snapshot_path(&log_path), GOLDEN).unwrap();
+ assert!(load_snapshot(&log_path, [9u8; 16], 300).is_none());
+ assert!(load_golden(&log_path).is_some());
+ }
+
+ #[test]
+ fn covered_offset_beyond_log_end_is_discarded() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ std::fs::write(snapshot_path(&log_path), GOLDEN).unwrap();
+ assert!(load_snapshot(&log_path, golden_generation(), 299).is_none());
+ assert!(load_snapshot(&log_path, golden_generation(), 300).is_some());
+ assert!(load_snapshot(&log_path, golden_generation(), 301).is_some());
+ }
+
+ #[test]
+ fn flipped_body_byte_is_discarded() {
+ assert_discarded(|bytes| bytes[57] ^= 0x01);
+ }
+
+ #[test]
+ fn trailing_garbage_is_discarded() {
+ assert_discarded(|bytes| bytes.extend_from_slice(&[0x5A; 5]));
+ assert_discarded(|bytes| {
+ let crc_start = bytes.len() - CRC_LEN;
+ bytes.splice(crc_start..crc_start, [0u8; 4]);
+ refresh_crc(bytes);
+ });
+ }
+
+ #[test]
+ fn wrong_node_count_is_discarded() {
+ assert_discarded(|bytes| {
+ bytes[35] = 4;
+ refresh_crc(bytes);
+ });
+ assert_discarded(|bytes| {
+ bytes[35] = 2;
+ refresh_crc(bytes);
+ });
+ }
+
+ #[test]
+ fn oversized_neighbor_count_is_discarded() {
+ assert_discarded(|bytes| {
+ bytes[44..46].copy_from_slice(&u16::MAX.to_le_bytes());
+ refresh_crc(bytes);
+ });
+ }
+
+ #[test]
+ fn wrong_top_level_is_discarded() {
+ assert_discarded(|bytes| {
+ bytes[34] = 0;
+ refresh_crc(bytes);
+ });
+ assert_discarded(|bytes| {
+ bytes[34] = 2;
+ refresh_crc(bytes);
+ });
+ }
+
+ #[test]
+ fn entry_marker_inconsistencies_are_discarded() {
+ assert_discarded(|bytes| {
+ bytes[30..34].copy_from_slice(&NO_ENTRY_POINT.to_le_bytes());
+ refresh_crc(bytes);
+ });
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ write_snapshot(&log_path, golden_generation(), 300, &Graph::new()).unwrap();
+ let path = snapshot_path(&log_path);
+ let mut bytes = std::fs::read(&path).unwrap();
+ bytes[30..34].copy_from_slice(&0u32.to_le_bytes());
+ refresh_crc(&mut bytes);
+ std::fs::write(&path, &bytes).unwrap();
+ assert!(load_golden(&log_path).is_none());
+ }
+
+ #[test]
+ fn failed_write_leaves_no_temp_file() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ std::fs::create_dir(snapshot_path(&log_path)).unwrap();
+ let error = write_snapshot(&log_path, [1u8; 16], 0, &Graph::new()).unwrap_err();
+ assert!(matches!(error, VecDbError::Io { .. }));
+ assert!(!temp_snapshot_path(&log_path).exists());
+ assert!(snapshot_path(&log_path).is_dir());
+ let orphan_path = dir.path().join("absent").join("log");
+ assert!(write_snapshot(&orphan_path, [1u8; 16], 0, &Graph::new()).is_err());
+ assert!(!temp_snapshot_path(&orphan_path).exists());
+ assert!(!snapshot_path(&orphan_path).exists());
+ }
+
+ #[test]
+ fn rewrite_replaces_the_previous_snapshot() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ let generation = golden_generation();
+ write_snapshot(&log_path, generation, 100, &golden_graph()).unwrap();
+ write_snapshot(&log_path, generation, 999, &golden_graph()).unwrap();
+ assert!(!temp_snapshot_path(&log_path).exists());
+ let loaded = load_snapshot(&log_path, generation, 1000).unwrap();
+ assert_eq!(loaded.covered_log_offset, 999);
+ assert_eq!(loaded.parts.len(), 3);
+ }
+
+ #[test]
+ fn remove_snapshot_deletes_both_files_and_tolerates_absence() {
+ let dir = TempDir::new().unwrap();
+ let log_path = dir.path().join("log");
+ remove_snapshot(&log_path).unwrap();
+ write_snapshot(&log_path, [2u8; 16], 0, &Graph::new()).unwrap();
+ std::fs::write(temp_snapshot_path(&log_path), b"leftover").unwrap();
+ assert!(snapshot_path(&log_path).exists());
+ assert!(temp_snapshot_path(&log_path).exists());
+ remove_snapshot(&log_path).unwrap();
+ assert!(!snapshot_path(&log_path).exists());
+ assert!(!temp_snapshot_path(&log_path).exists());
+ remove_snapshot(&log_path).unwrap();
+ }
+}