π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
vecdb: add graph snapshot sidecar
laurenspriem73e45618df46
diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rsindex 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,+ ¶ms(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,+ ¶ms(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,+ ¶ms(Some(1), None, false),+ None,+ );+ assert_eq!(keys(&found), ["fresh"]);+ let all = search(+ Some(&graph),+ &arena,+ &fresh_query,+ ¶ms(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,+ ¶ms(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.rsindex 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();+ }+}