π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
vecdb: add store orchestration and writer lock
laurenspriem0076850c99bf
diff --git a/rust/crates/ml/src/vecdb/arena.rs b/rust/crates/ml/src/vecdb/arena.rsindex 944cafd7f2..221b368983 100644--- a/rust/crates/ml/src/vecdb/arena.rs+++ b/rust/crates/ml/src/vecdb/arena.rs@@ -17,7 +17,6 @@ pub(crate) enum UpsertOutcome {ReplacedInPlace(u32),}-#[allow(dead_code)]impl UpsertOutcome {pub(crate) fn slot(self) -> u32 {match self {@@ -52,7 +51,6 @@ pub(crate) struct VectorArena {live_count: usize,}-#[allow(dead_code)]impl VectorArena {pub(crate) fn new(dims: usize) -> Result<Self, VecDbError> {if dims == 0 || !dims.is_multiple_of(LANE_WIDTH) {diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rsindex fede71ade8..aad2c5aab1 100644--- a/rust/crates/ml/src/vecdb/graph.rs+++ b/rust/crates/ml/src/vecdb/graph.rs@@ -111,7 +111,6 @@ impl Default for Graph {}}-#[allow(dead_code)]impl Graph {pub(crate) fn new() -> Self {Self {@@ -472,7 +471,6 @@ impl QueryContext<'_> {}}-#[allow(dead_code)]pub(crate) fn search(graph: Option<&Graph>,arena: &VectorArena,diff --git a/rust/crates/ml/src/vecdb/lock.rs b/rust/crates/ml/src/vecdb/lock.rsindex 8b13789179..69837f7f13 100644--- a/rust/crates/ml/src/vecdb/lock.rs+++ b/rust/crates/ml/src/vecdb/lock.rs@@ -1 +1,132 @@+use std::fs::File;+use std::path::Path;+use super::VecDbError;++pub(crate) fn lock_exclusive(file: &File, path: &Path) -> Result<(), VecDbError> {+ if try_lock(file) {+ return Ok(());+ }+ let error = std::io::Error::last_os_error();+ if error.raw_os_error() == Some(WOULD_BLOCK_CODE) {+ return Err(VecDbError::Locked(path.to_path_buf()));+ }+ Err(VecDbError::Io {+ path: path.to_path_buf(),+ source: error,+ })+}++#[cfg(unix)]+const WOULD_BLOCK_CODE: i32 = libc::EWOULDBLOCK;++#[cfg(unix)]+fn try_lock(file: &File) -> bool {+ use std::os::fd::AsRawFd;++ unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) == 0 }+}++#[cfg(windows)]+const WOULD_BLOCK_CODE: i32 = windows_sys::Win32::Foundation::ERROR_LOCK_VIOLATION as i32;++#[cfg(windows)]+const LOCK_BYTE_OFFSET: u64 = u64::MAX - 1;++#[cfg(windows)]+fn try_lock(file: &File) -> bool {+ use std::os::windows::io::AsRawHandle;++ use windows_sys::Win32::Storage::FileSystem::{+ LOCKFILE_EXCLUSIVE_LOCK, LOCKFILE_FAIL_IMMEDIATELY, LockFileEx,+ };+ use windows_sys::Win32::System::IO::OVERLAPPED;++ let mut overlapped: OVERLAPPED = unsafe { std::mem::zeroed() };+ overlapped.Anonymous.Anonymous.Offset = LOCK_BYTE_OFFSET as u32;+ overlapped.Anonymous.Anonymous.OffsetHigh = (LOCK_BYTE_OFFSET >> 32) as u32;+ unsafe {+ LockFileEx(+ file.as_raw_handle(),+ LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY,+ 0,+ 1,+ 0,+ &mut overlapped,+ ) != 0+ }+}++#[cfg(test)]+mod tests {+ use std::fs::File;+ use std::path::Path;++ use tempfile::TempDir;++ use super::*;++ fn open_rw(path: &Path) -> File {+ File::options()+ .read(true)+ .write(true)+ .create(true)+ .truncate(false)+ .open(path)+ .unwrap()+ }++ #[test]+ fn locks_a_fresh_file() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("log");+ let file = open_rw(&path);+ assert!(lock_exclusive(&file, &path).is_ok());+ }++ #[test]+ fn second_handle_on_the_same_path_conflicts() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("log");+ let holder = open_rw(&path);+ lock_exclusive(&holder, &path).unwrap();+ let contender = open_rw(&path);+ let error = lock_exclusive(&contender, &path).unwrap_err();+ assert!(matches!(error, VecDbError::Locked(locked) if locked == path));+ }++ #[test]+ fn closing_the_holding_handle_releases_the_lock() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("log");+ let holder = open_rw(&path);+ lock_exclusive(&holder, &path).unwrap();+ drop(holder);+ let successor = open_rw(&path);+ assert!(lock_exclusive(&successor, &path).is_ok());+ }++ #[test]+ fn held_lock_does_not_block_reads_or_copies_through_other_handles() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("log");+ std::fs::write(&path, b"payload").unwrap();+ let holder = open_rw(&path);+ lock_exclusive(&holder, &path).unwrap();+ assert_eq!(std::fs::read(&path).unwrap(), b"payload");+ let copy_path = dir.path().join("copy");+ std::fs::copy(&path, ©_path).unwrap();+ assert_eq!(std::fs::read(©_path).unwrap(), b"payload");+ }++ #[test]+ fn distinct_paths_do_not_conflict() {+ let dir = TempDir::new().unwrap();+ let first_path = dir.path().join("first");+ let second_path = dir.path().join("second");+ let first = open_rw(&first_path);+ let second = open_rw(&second_path);+ lock_exclusive(&first, &first_path).unwrap();+ assert!(lock_exclusive(&second, &second_path).is_ok());+ }+}diff --git a/rust/crates/ml/src/vecdb/log.rs b/rust/crates/ml/src/vecdb/log.rsindex 4551c9a1b8..25cff11ae1 100644--- a/rust/crates/ml/src/vecdb/log.rs+++ b/rust/crates/ml/src/vecdb/log.rs@@ -22,14 +22,12 @@ const ENCODE_FLUSH_BYTES: usize = 64 * 1024;static GENERATION_COUNTER: AtomicU64 = AtomicU64::new(0);#[derive(Debug, Clone, Copy)]-#[allow(dead_code)]pub(crate) enum LogEntry<'a> {Add { key: &'a str, vector: &'a [f32] },Tombstone { key: &'a str },}#[derive(Debug, Clone, PartialEq)]-#[allow(dead_code)]pub(crate) enum LogRecord {Add { key: String, vector: Vec<f32> },Tombstone { key: String },@@ -45,7 +43,6 @@ pub(crate) struct Log {encode_buffer: Vec<u8>,}-#[allow(dead_code)]impl Log {pub(crate) fn create(path: &Path, dims: usize) -> Result<Self, VecDbError> {validate_dims(dims)?;@@ -216,7 +213,6 @@ pub(crate) struct LogScanner<'a> {done: bool,}-#[allow(dead_code)]impl LogScanner<'_> {pub(crate) fn next_record(&mut self) -> Result<Option<(LogRecord, u64)>, VecDbError> {if self.done {@@ -430,7 +426,6 @@ fn splitmix64(state: &mut u64) -> u64 {mixed ^ (mixed >> 31)}-#[allow(dead_code)]pub(crate) fn remove_stale_temp_sibling(path: &Path) -> Result<(), VecDbError> {let temp_path = temp_sibling_path(path);match std::fs::remove_file(&temp_path) {diff --git a/rust/crates/ml/src/vecdb/mod.rs b/rust/crates/ml/src/vecdb/mod.rsindex db79699ca4..b0e8e6ad7d 100644--- a/rust/crates/ml/src/vecdb/mod.rs+++ b/rust/crates/ml/src/vecdb/mod.rs@@ -10,8 +10,7 @@ mod log;mod snapshot;mod store;-#[allow(unused_imports)]-pub(crate) use graph::{Graph, GraphNodeParts, search};+pub use store::{Stats, VecDb};#[derive(Debug, Clone, Default)]pub struct SearchParams {@@ -43,6 +42,8 @@ pub enum VecDbError {ReadOnly,#[error("invalid key: {0}")]InvalidKey(String),+ #[error("invalid vector: {0}")]+ InvalidVector(String),#[error("dimension mismatch: expected {expected}, got {actual}")]DimensionMismatch { expected: usize, actual: usize },#[error("invalid dimensions {0}: must be a nonzero multiple of 8")]diff --git a/rust/crates/ml/src/vecdb/snapshot.rs b/rust/crates/ml/src/vecdb/snapshot.rsindex e369b55a75..87c74d22c0 100644--- a/rust/crates/ml/src/vecdb/snapshot.rs+++ b/rust/crates/ml/src/vecdb/snapshot.rs@@ -13,19 +13,16 @@ 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],@@ -40,7 +37,6 @@ pub(crate) fn write_snapshot(})}-#[allow(dead_code)]pub(crate) fn load_snapshot(log_path: &Path,expected_generation: [u8; 16],@@ -64,7 +60,6 @@ pub(crate) fn load_snapshot(}}-#[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))diff --git a/rust/crates/ml/src/vecdb/store.rs b/rust/crates/ml/src/vecdb/store.rsindex 8b13789179..91ae458ed2 100644--- a/rust/crates/ml/src/vecdb/store.rs+++ b/rust/crates/ml/src/vecdb/store.rs@@ -1 +1,1501 @@+use std::collections::HashSet;+use std::fs::File;+use std::io::ErrorKind;+use std::path::{Path, PathBuf};+use std::time::{Duration, Instant};+use super::arena::{UpsertOutcome, VECTORS_PER_CHUNK, VectorArena, validate_key};+use super::graph::{Graph, search as graph_search};+use super::lock::lock_exclusive;+use super::log::{Log, LogEntry, LogRecord, remove_stale_temp_sibling};+use super::snapshot::{load_snapshot, remove_snapshot, snapshot_path, write_snapshot};+use super::{Match, SearchParams, VecDbError};++const SNAPSHOT_HARD_CAP: usize = 5000;+const SNAPSHOT_QUIET_THRESHOLD: usize = 1000;+const SNAPSHOT_QUIET_GAP: Duration = Duration::from_secs(10);+const COMPACTION_MIN_DEAD_RECORDS: u64 = 64;+const COMPACTION_DEAD_RATIO: u64 = 10;+const COMPACTION_BATCH_SIZE: usize = 1000;++#[derive(Debug, Clone, PartialEq, Eq)]+pub struct Stats {+ pub live_count: usize,+ pub dead_count: usize,+ pub dims: usize,+ pub log_bytes: u64,+ pub records_since_snapshot: usize,+ pub approximate_memory_bytes: usize,+}++pub struct VecDb {+ path: PathBuf,+ arena: VectorArena,+ graph: Graph,+ total_records: u64,+ mode: Mode,+}++enum Mode {+ Writer(WriterState),+ ReadOnly { log_bytes: u64 },+}++struct WriterState {+ log: Log,+ mutations_since_snapshot: usize,+ last_write: Option<Instant>,+}++impl VecDb {+ pub fn open(path: &Path, dims: usize) -> Result<Self, VecDbError> {+ let file = match Log::create(path, dims) {+ Ok(created) => created.into_file(),+ Err(VecDbError::Io { source, .. }) if source.kind() == ErrorKind::AlreadyExists => {+ File::options()+ .read(true)+ .write(true)+ .open(path)+ .map_err(|source| io_error(path, source))?+ }+ Err(error) => return Err(error),+ };+ lock_exclusive(&file, path)?;+ let mut log = Log::open(file, path, dims)?;+ remove_stale_temp_sibling(path)?;+ let snapshot_present = std::fs::metadata(snapshot_path(path)).is_ok();+ let replayed = replay(&mut log, dims)?;+ if replayed.recoverable_end < log.current_end_offset() {+ log.truncate_to(replayed.recoverable_end)?;+ }+ let snapshot_stale = if replayed.used_snapshot {+ replayed.tail_records > 0+ } else {+ replayed.total_records > 0 || snapshot_present+ };+ let mut db = Self {+ path: path.to_path_buf(),+ arena: replayed.arena,+ graph: replayed.graph,+ total_records: replayed.total_records,+ mode: Mode::Writer(WriterState {+ log,+ mutations_since_snapshot: 0,+ last_write: None,+ }),+ };+ if snapshot_stale {+ db.write_snapshot_now()?;+ }+ Ok(db)+ }++ pub fn open_read_only(path: &Path, dims: usize) -> Result<Self, VecDbError> {+ let file = match File::open(path) {+ Ok(file) => file,+ Err(error) if error.kind() == ErrorKind::NotFound => {+ return Ok(Self {+ path: path.to_path_buf(),+ arena: VectorArena::new(dims)?,+ graph: Graph::new(),+ total_records: 0,+ mode: Mode::ReadOnly { log_bytes: 0 },+ });+ }+ Err(source) => return Err(io_error(path, source)),+ };+ let mut log = Log::open(file, path, dims)?;+ let replayed = replay(&mut log, dims)?;+ drop(log);+ Ok(Self {+ path: path.to_path_buf(),+ arena: replayed.arena,+ graph: replayed.graph,+ total_records: replayed.total_records,+ mode: Mode::ReadOnly {+ log_bytes: replayed.recoverable_end,+ },+ })+ }++ pub fn add(&mut self, key: &str, vector: &[f32]) -> Result<(), VecDbError> {+ let now = Instant::now();+ self.writer_state()?;+ self.validate_entry(key, vector)?;+ self.writer_state()?+ .log+ .append(&[LogEntry::Add { key, vector }])?;+ let outcome = self.arena.upsert(key, vector)?;+ apply_outcome(&mut self.graph, &self.arena, outcome);+ self.record_mutations(1, now)+ }++ pub fn bulk_add(&mut self, entries: &[(String, Vec<f32>)]) -> Result<(), VecDbError> {+ let now = Instant::now();+ self.writer_state()?;+ if entries.is_empty() {+ return Ok(());+ }+ for (key, vector) in entries {+ self.validate_entry(key, vector)?;+ }+ let records: Vec<LogEntry<'_>> = entries+ .iter()+ .map(|(key, vector)| LogEntry::Add { key, vector })+ .collect();+ self.writer_state()?.log.append(&records)?;+ for (key, vector) in entries {+ let outcome = self.arena.upsert(key, vector)?;+ apply_outcome(&mut self.graph, &self.arena, outcome);+ }+ self.record_mutations(entries.len(), now)+ }++ pub fn remove(&mut self, key: &str) -> Result<bool, VecDbError> {+ let now = Instant::now();+ self.writer_state()?;+ if self.arena.slot_of_key(key).is_none() {+ return Ok(false);+ }+ self.writer_state()?+ .log+ .append(&[LogEntry::Tombstone { key }])?;+ self.arena.remove(key);+ self.record_mutations(1, now)?;+ Ok(true)+ }++ pub fn bulk_remove(&mut self, keys: &[String]) -> Result<usize, VecDbError> {+ let now = Instant::now();+ self.writer_state()?;+ let mut scheduled: Vec<&str> = Vec::new();+ let mut seen: HashSet<&str> = HashSet::new();+ for key in keys {+ if self.arena.slot_of_key(key).is_some() && seen.insert(key.as_str()) {+ scheduled.push(key);+ }+ }+ if scheduled.is_empty() {+ return Ok(0);+ }+ let records: Vec<LogEntry<'_>> = scheduled+ .iter()+ .map(|key| LogEntry::Tombstone { key })+ .collect();+ self.writer_state()?.log.append(&records)?;+ for key in &scheduled {+ self.arena.remove(key);+ }+ let count = scheduled.len();+ self.record_mutations(count, now)?;+ Ok(count)+ }++ pub fn contains(&self, key: &str) -> bool {+ self.arena.slot_of_key(key).is_some()+ }++ pub fn get(&self, key: &str) -> Option<Vec<f32>> {+ let slot = self.arena.slot_of_key(key)?;+ Some(self.arena.vector_values(slot))+ }++ pub fn search(&self, query: &[f32], params: &SearchParams) -> Result<Vec<Match>, VecDbError> {+ if params.limit.is_none() && params.max_distance.is_none() {+ return Err(VecDbError::UnboundedSearch);+ }+ if let Some(max_distance) = params.max_distance+ && (!max_distance.is_finite() || max_distance < 0.0)+ {+ return Ok(Vec::new());+ }+ let packed = self.arena.pack_query(query)?;+ let allowed_slots: Option<HashSet<u32>> = params.allowed_keys.as_ref().map(|keys| {+ keys.iter()+ .filter_map(|key| self.arena.slot_of_key(key))+ .collect()+ });+ Ok(graph_search(+ Some(&self.graph),+ &self.arena,+ &packed,+ params,+ allowed_slots.as_ref(),+ ))+ }++ pub fn flush(&mut self) -> Result<(), VecDbError> {+ let state = self.writer_state()?;+ if state.mutations_since_snapshot == 0 {+ return Ok(());+ }+ self.write_snapshot_now()+ }++ pub fn reset(&mut self) -> Result<(), VecDbError> {+ self.writer_state()?;+ let dims = self.arena.dims();+ let Mode::Writer(old_state) =+ std::mem::replace(&mut self.mode, Mode::ReadOnly { log_bytes: 0 })+ else {+ return Err(VecDbError::ReadOnly);+ };+ drop(old_state);+ remove_if_present(&self.path)?;+ remove_snapshot(&self.path)?;+ remove_stale_temp_sibling(&self.path)?;+ let file = Log::create(&self.path, dims)?.into_file();+ lock_exclusive(&file, &self.path)?;+ let log = Log::open(file, &self.path, dims)?;+ self.arena = VectorArena::new(dims)?;+ self.graph = Graph::new();+ self.total_records = 0;+ self.mode = Mode::Writer(WriterState {+ log,+ mutations_since_snapshot: 0,+ last_write: None,+ });+ Ok(())+ }++ pub fn delete(self) -> Result<(), VecDbError> {+ let Mode::Writer(state) = self.mode else {+ return Err(VecDbError::ReadOnly);+ };+ drop(state);+ remove_if_present(&self.path)?;+ remove_snapshot(&self.path)?;+ remove_stale_temp_sibling(&self.path)?;+ Ok(())+ }++ pub fn stats(&self) -> Stats {+ let live_count = self.arena.live_count();+ let (log_bytes, records_since_snapshot) = match &self.mode {+ Mode::Writer(state) => (+ state.log.current_end_offset(),+ state.mutations_since_snapshot,+ ),+ Mode::ReadOnly { log_bytes } => (*log_bytes, 0),+ };+ Stats {+ live_count,+ dead_count: self.total_records.saturating_sub(live_count as u64) as usize,+ dims: self.arena.dims(),+ log_bytes,+ records_since_snapshot,+ approximate_memory_bytes: self.approximate_memory_bytes(),+ }+ }++ pub fn len(&self) -> usize {+ self.arena.live_count()+ }++ pub fn is_empty(&self) -> bool {+ self.arena.is_empty()+ }++ fn writer_state(&mut self) -> Result<&mut WriterState, VecDbError> {+ match &mut self.mode {+ Mode::Writer(state) => Ok(state),+ Mode::ReadOnly { .. } => Err(VecDbError::ReadOnly),+ }+ }++ fn validate_entry(&self, key: &str, vector: &[f32]) -> Result<(), VecDbError> {+ validate_key(key)?;+ if vector.len() != self.arena.dims() {+ return Err(VecDbError::DimensionMismatch {+ expected: self.arena.dims(),+ actual: vector.len(),+ });+ }+ if let Some(index) = vector.iter().position(|value| !value.is_finite()) {+ return Err(VecDbError::InvalidVector(format!(+ "component {index} of the vector for key {key:?} is not finite"+ )));+ }+ Ok(())+ }++ fn record_mutations(&mut self, count: usize, now: Instant) -> Result<(), VecDbError> {+ self.total_records += count as u64;+ let live = self.arena.live_count() as u64;+ let total = self.total_records;+ let Mode::Writer(state) = &mut self.mode else {+ return Err(VecDbError::ReadOnly);+ };+ state.mutations_since_snapshot += count;+ let quiet = state+ .last_write+ .is_some_and(|previous| now.duration_since(previous) >= SNAPSHOT_QUIET_GAP);+ state.last_write = Some(now);+ let mutations = state.mutations_since_snapshot;+ let dead = total.saturating_sub(live);+ if dead >= COMPACTION_MIN_DEAD_RECORDS+ && dead.saturating_mul(COMPACTION_DEAD_RATIO) >= total+ {+ return self.compact();+ }+ if mutations >= SNAPSHOT_HARD_CAP || (mutations >= SNAPSHOT_QUIET_THRESHOLD && quiet) {+ return self.write_snapshot_now();+ }+ Ok(())+ }++ fn write_snapshot_now(&mut self) -> Result<(), VecDbError> {+ let graph = &self.graph;+ let Mode::Writer(state) = &mut self.mode else {+ return Err(VecDbError::ReadOnly);+ };+ write_snapshot(+ state.log.path(),+ state.log.generation(),+ state.log.current_end_offset(),+ graph,+ )?;+ state.mutations_since_snapshot = 0;+ Ok(())+ }++ fn compact(&mut self) -> Result<(), VecDbError> {+ let Mode::Writer(state) = &mut self.mode else {+ return Err(VecDbError::ReadOnly);+ };+ let dims = state.log.dims();+ let (mut temp_log, temp_path) = Log::create_temp_sibling(state.log.path(), dims)?;+ let mut compacted = VectorArena::new(dims)?;+ if let Err(error) = stage_live_entries(&self.arena, &mut compacted, &mut temp_log) {+ drop(temp_log);+ let _ = std::fs::remove_file(&temp_path);+ return Err(error);+ }+ let temp_file = temp_log.into_file();+ if let Err(source) = temp_file.sync_all() {+ drop(temp_file);+ let _ = std::fs::remove_file(&temp_path);+ return Err(io_error(&temp_path, source));+ }+ drop(temp_file);+ let last_write = state.last_write;+ let Mode::Writer(old_state) =+ std::mem::replace(&mut self.mode, Mode::ReadOnly { log_bytes: 0 })+ else {+ return Err(VecDbError::ReadOnly);+ };+ drop(old_state);+ std::fs::rename(&temp_path, &self.path).map_err(|source| io_error(&self.path, source))?;+ let file = File::options()+ .read(true)+ .write(true)+ .open(&self.path)+ .map_err(|source| io_error(&self.path, source))?;+ lock_exclusive(&file, &self.path)?;+ let log = Log::open(file, &self.path, dims)?;+ self.arena = compacted;+ self.graph = Graph::rebuild(&self.arena);+ self.total_records = self.arena.live_count() as u64;+ self.mode = Mode::Writer(WriterState {+ log,+ mutations_since_snapshot: 0,+ last_write,+ });+ self.write_snapshot_now()+ }++ fn approximate_memory_bytes(&self) -> usize {+ let vector_bytes = self.arena.slot_count().div_ceil(VECTORS_PER_CHUNK)+ * VECTORS_PER_CHUNK+ * self.arena.dims()+ * size_of::<f32>();+ let key_bytes: usize = self+ .arena+ .live_slots()+ .filter_map(|slot| self.arena.key_of_slot(slot))+ .map(|key| 2 * (key.len() + 48))+ .sum();+ let free_list_bytes = self.arena.dead_count() * size_of::<u32>();+ let graph_bytes: usize = self+ .graph+ .slots()+ .map(|slot| {+ let level = self.graph.level_of(slot).unwrap_or(0);+ 48 + (0..=level)+ .map(|layer| 24 + size_of_val(self.graph.neighbors_of(slot, layer)))+ .sum::<usize>()+ })+ .sum();+ vector_bytes + key_bytes + free_list_bytes + graph_bytes+ }+}++struct ReplayedState {+ arena: VectorArena,+ graph: Graph,+ total_records: u64,+ recoverable_end: u64,+ used_snapshot: bool,+ tail_records: u64,+}++fn replay(log: &mut Log, dims: usize) -> Result<ReplayedState, VecDbError> {+ let snapshot = load_snapshot(log.path(), log.generation(), log.current_end_offset());+ let covered = snapshot+ .as_ref()+ .map_or(u64::MAX, |loaded| loaded.covered_log_offset);+ let mut arena = VectorArena::new(dims)?;+ let mut tail_outcomes: Vec<UpsertOutcome> = Vec::new();+ let mut tail_records = 0u64;+ let mut total_records = 0u64;+ let mut covered_slot_count: Option<usize> = None;+ let recoverable_end;+ {+ let mut scanner = log.scan()?;+ while let Some((record, offset)) = scanner.next_record()? {+ total_records += 1;+ let in_tail = offset >= covered;+ if in_tail {+ covered_slot_count.get_or_insert(arena.slot_count());+ tail_records += 1;+ }+ match record {+ LogRecord::Add { key, vector } => {+ let outcome = arena.upsert(&key, &vector)?;+ if in_tail {+ tail_outcomes.push(outcome);+ }+ }+ LogRecord::Tombstone { key } => {+ arena.remove(&key);+ }+ }+ }+ recoverable_end = scanner.recoverable_end();+ }+ let (graph, used_snapshot) = match snapshot {+ Some(loaded) if loaded.covered_log_offset <= recoverable_end => {+ let snapshot_slots = covered_slot_count.unwrap_or(arena.slot_count());+ match Graph::from_parts(loaded.entry_point, loaded.parts, snapshot_slots) {+ Ok(mut graph) => {+ for outcome in tail_outcomes {+ apply_outcome(&mut graph, &arena, outcome);+ }+ (graph, true)+ }+ Err(error) => {+ log::debug!("discarding snapshot for {}: {error}", log.path().display());+ (Graph::rebuild(&arena), false)+ }+ }+ }+ _ => (Graph::rebuild(&arena), false),+ };+ Ok(ReplayedState {+ arena,+ graph,+ total_records,+ recoverable_end,+ used_snapshot,+ tail_records,+ })+}++fn apply_outcome(graph: &mut Graph, arena: &VectorArena, outcome: UpsertOutcome) {+ match outcome {+ UpsertOutcome::NewSlot(slot) => graph.insert(slot, arena),+ UpsertOutcome::RecycledSlot(_) | UpsertOutcome::ReplacedInPlace(_) => {+ graph.reinsert(outcome.slot(), arena);+ }+ }+}++fn stage_live_entries(+ source: &VectorArena,+ target: &mut VectorArena,+ log: &mut Log,+) -> Result<(), VecDbError> {+ let mut batch: Vec<(String, Vec<f32>)> = Vec::with_capacity(COMPACTION_BATCH_SIZE);+ for slot in source.live_slots() {+ let Some(key) = source.key_of_slot(slot) else {+ continue;+ };+ batch.push((key.to_string(), source.vector_values(slot)));+ if batch.len() == COMPACTION_BATCH_SIZE {+ flush_stage_batch(&mut batch, target, log)?;+ }+ }+ flush_stage_batch(&mut batch, target, log)+}++fn flush_stage_batch(+ batch: &mut Vec<(String, Vec<f32>)>,+ target: &mut VectorArena,+ log: &mut Log,+) -> Result<(), VecDbError> {+ if batch.is_empty() {+ return Ok(());+ }+ let records: Vec<LogEntry<'_>> = batch+ .iter()+ .map(|(key, vector)| LogEntry::Add { key, vector })+ .collect();+ log.append(&records)?;+ for (key, vector) in batch.drain(..) {+ target.upsert(&key, &vector)?;+ }+ Ok(())+}++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 io_error(path: &Path, source: std::io::Error) -> VecDbError {+ VecDbError::Io {+ path: path.to_path_buf(),+ source,+ }+}++#[cfg(test)]+mod tests {+ use std::fs;++ use tempfile::TempDir;++ use super::*;++ const DIMS: usize = 16;+ const ADD_RECORD_LEN: u64 = 3 + 5 + (DIMS as u64) * 4 + 4;+ const TOMBSTONE_RECORD_LEN: u64 = 3 + 5 + 4;++ 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 basis_vector(axis: usize) -> Vec<f32> {+ let mut values = vec![0.0; DIMS];+ values[axis] = 1.0;+ values+ }++ fn negated(values: &[f32]) -> Vec<f32> {+ values.iter().map(|value| -value).collect()+ }++ fn bulk_entries(start: usize, count: usize, seed: u64) -> Vec<(String, Vec<f32>)> {+ (start..start + count)+ .map(|index| {+ (+ format!("key-{index}"),+ seeded_unit_vector(seed + index as u64, DIMS),+ )+ })+ .collect()+ }++ fn limit_params(limit: usize) -> SearchParams {+ SearchParams {+ limit: Some(limit),+ ..SearchParams::default()+ }+ }++ fn open_writer(path: &Path) -> VecDb {+ VecDb::open(path, DIMS).unwrap()+ }++ fn generation_of(path: &Path) -> [u8; 16] {+ fs::read(path).unwrap()[12..28].try_into().unwrap()+ }++ fn temp_sibling(path: &Path) -> PathBuf {+ PathBuf::from(format!("{}.tmp", path.display()))+ }++ fn snapshot_exists(path: &Path) -> bool {+ snapshot_path(path).exists()+ }++ fn writer(db: &mut VecDb) -> &mut WriterState {+ match &mut db.mode {+ Mode::Writer(state) => state,+ Mode::ReadOnly { .. } => panic!("expected a writer instance"),+ }+ }++ fn assert_own_nearest(db: &VecDb, key: &str, vector: &[f32]) {+ let matches = db.search(vector, &limit_params(1)).unwrap();+ assert_eq!(matches[0].key, key);+ assert!(matches[0].distance.abs() < 1.0e-3);+ }++ fn search_shapes(allowed: Vec<String>) -> Vec<SearchParams> {+ vec![+ SearchParams {+ limit: Some(8),+ ..SearchParams::default()+ },+ SearchParams {+ limit: Some(8),+ exact: true,+ ..SearchParams::default()+ },+ SearchParams {+ max_distance: Some(1.05),+ ..SearchParams::default()+ },+ SearchParams {+ max_distance: Some(1.05),+ exact: true,+ ..SearchParams::default()+ },+ SearchParams {+ limit: Some(4),+ max_distance: Some(1.2),+ ..SearchParams::default()+ },+ SearchParams {+ limit: Some(4),+ max_distance: Some(1.2),+ exact: true,+ ..SearchParams::default()+ },+ SearchParams {+ limit: Some(6),+ allowed_keys: Some(allowed.clone()),+ ..SearchParams::default()+ },+ SearchParams {+ limit: None,+ max_distance: Some(1.5),+ exact: true,+ allowed_keys: Some(allowed),+ },+ ]+ }++ #[test]+ fn lifecycle_round_trip_preserves_search_results() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let probe = seeded_unit_vector(777, DIMS);+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 150, 100)).unwrap();+ db.add("probe", &probe).unwrap();+ assert_eq!(db.len(), 151);+ assert!(!db.is_empty());+ assert!(db.contains("probe"));+ assert!(db.contains("key-42"));+ assert!(!db.contains("key-999"));+ assert_eq!(db.get("probe").unwrap(), probe);+ assert_eq!(db.get("key-7").unwrap(), seeded_unit_vector(107, DIMS));+ assert!(db.get("missing").is_none());+ let stats = db.stats();+ assert_eq!(stats.live_count, 151);+ assert_eq!(stats.dead_count, 0);+ assert_eq!(stats.dims, DIMS);+ assert_eq!(stats.records_since_snapshot, 151);+ assert!(stats.log_bytes > 32);+ assert!(stats.approximate_memory_bytes > 151 * DIMS * 4);+ let allowed = vec![+ "probe".to_string(),+ "key-3".to_string(),+ "key-77".to_string(),+ "absent".to_string(),+ ];+ let queries = [probe.clone(), seeded_unit_vector(555, DIMS)];+ let shapes = search_shapes(allowed);+ let mut expected = Vec::new();+ for query in &queries {+ for shape in &shapes {+ expected.push(db.search(query, shape).unwrap());+ }+ }+ assert!(expected.iter().any(|matches| !matches.is_empty()));+ assert_eq!(db.search(&probe, &limit_params(1)).unwrap()[0].key, "probe");+ db.flush().unwrap();+ assert_eq!(db.stats().records_since_snapshot, 0);+ drop(db);+ let read_only = VecDb::open_read_only(&path, DIMS).unwrap();+ let reopened = open_writer(&path);+ let mut index = 0;+ for query in &queries {+ for shape in &search_shapes(vec![+ "probe".to_string(),+ "key-3".to_string(),+ "key-77".to_string(),+ "absent".to_string(),+ ]) {+ assert_eq!(reopened.search(query, shape).unwrap(), expected[index]);+ assert_eq!(read_only.search(query, shape).unwrap(), expected[index]);+ index += 1;+ }+ }+ assert_eq!(reopened.len(), 151);+ assert_eq!(read_only.len(), 151);+ }++ #[test]+ fn search_parameter_validation() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 5, 10)).unwrap();+ let query = seeded_unit_vector(1, DIMS);+ assert!(matches!(+ db.search(&query, &SearchParams::default()),+ Err(VecDbError::UnboundedSearch)+ ));+ for bad_distance in [f32::NAN, f32::INFINITY, -0.5] {+ let params = SearchParams {+ limit: Some(3),+ max_distance: Some(bad_distance),+ ..SearchParams::default()+ };+ assert!(db.search(&query, ¶ms).unwrap().is_empty());+ }+ assert!(matches!(+ db.search(&seeded_unit_vector(1, 8), &limit_params(3)),+ Err(VecDbError::DimensionMismatch {+ expected: DIMS,+ actual: 8+ })+ ));+ assert!(db.search(&query, &limit_params(0)).unwrap().is_empty());+ let empty_filter = SearchParams {+ limit: Some(3),+ allowed_keys: Some(Vec::new()),+ ..SearchParams::default()+ };+ assert!(db.search(&query, &empty_filter).unwrap().is_empty());+ let missing_filter = SearchParams {+ limit: Some(3),+ allowed_keys: Some(vec!["nope".to_string(), "nada".to_string()]),+ ..SearchParams::default()+ };+ assert!(db.search(&query, &missing_filter).unwrap().is_empty());+ let empty_db = open_writer(&dir.path().join("empty"));+ assert!(+ empty_db+ .search(&query, &limit_params(3))+ .unwrap()+ .is_empty()+ );+ }++ #[test]+ fn acknowledged_writes_survive_drop_without_flush() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ for index in 0..4 {+ db.add(+ &format!("solo-{index}"),+ &seeded_unit_vector(index as u64, DIMS),+ )+ .unwrap();+ }+ db.bulk_add(&bulk_entries(0, 6, 40)).unwrap();+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 10);+ for index in 0..4u64 {+ assert_eq!(+ reopened.get(&format!("solo-{index}")).unwrap(),+ seeded_unit_vector(index, DIMS)+ );+ }+ assert_own_nearest(&reopened, "key-2", &seeded_unit_vector(42, DIMS));+ assert_own_nearest(&reopened, "solo-3", &seeded_unit_vector(3, DIMS));+ }++ #[test]+ fn log_copy_taken_mid_session_opens_with_all_acknowledged_writes() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let copy = dir.path().join("copy");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 6, 60)).unwrap();+ fs::copy(&path, ©).unwrap();+ let copied = open_writer(©);+ assert_eq!(copied.len(), 6);+ for index in 0..6 {+ assert_eq!(+ copied.get(&format!("key-{index}")).unwrap(),+ seeded_unit_vector(60 + index as u64, DIMS)+ );+ }+ db.add("late", &seeded_unit_vector(999, DIMS)).unwrap();+ assert!(db.contains("late"));+ assert!(!copied.contains("late"));+ }++ #[test]+ fn torn_tail_garbage_is_truncated_and_data_survives() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 4, 20)).unwrap();+ drop(db);+ let clean_len = fs::metadata(&path).unwrap().len();+ let mut bytes = fs::read(&path).unwrap();+ bytes.extend_from_slice(&[0xFF; 41]);+ fs::write(&path, &bytes).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 4);+ assert_own_nearest(&reopened, "key-1", &seeded_unit_vector(21, DIMS));+ drop(reopened);+ assert_eq!(fs::metadata(&path).unwrap().len(), clean_len);+ }++ #[test]+ fn torn_tail_partial_record_is_truncated_and_data_survives() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 4, 30)).unwrap();+ db.flush().unwrap();+ drop(db);+ let clean_len = fs::metadata(&path).unwrap().len();+ let mut bytes = fs::read(&path).unwrap();+ bytes.extend_from_slice(&[1, 6, 0, b'a', b'b']);+ fs::write(&path, &bytes).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 4);+ assert!(reopened.contains("key-3"));+ drop(reopened);+ assert_eq!(fs::metadata(&path).unwrap().len(), clean_len);+ }++ #[test]+ fn deleted_snapshot_recovers_by_rebuild() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 8, 50)).unwrap();+ db.flush().unwrap();+ drop(db);+ fs::remove_file(snapshot_path(&path)).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 8);+ assert_own_nearest(&reopened, "key-5", &seeded_unit_vector(55, DIMS));+ assert!(snapshot_exists(&path));+ }++ #[test]+ fn snapshot_from_an_older_generation_is_discarded() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 3, 70)).unwrap();+ db.flush().unwrap();+ drop(db);+ let stale_snapshot = fs::read(snapshot_path(&path)).unwrap();+ fs::remove_file(&path).unwrap();+ let mut db = open_writer(&path);+ assert!(db.is_empty());+ db.add("fresh", &seeded_unit_vector(1, DIMS)).unwrap();+ drop(db);+ fs::write(snapshot_path(&path), &stale_snapshot).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 1);+ assert!(reopened.contains("fresh"));+ assert!(!reopened.contains("key-0"));+ assert_own_nearest(&reopened, "fresh", &seeded_unit_vector(1, DIMS));+ }++ #[test]+ fn snapshot_claiming_offset_beyond_log_end_is_discarded() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 5, 80)).unwrap();+ db.flush().unwrap();+ drop(db);+ let bytes = fs::read(&path).unwrap();+ fs::write(&path, &bytes[..bytes.len() - ADD_RECORD_LEN as usize]).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 4);+ assert!(reopened.contains("key-3"));+ assert!(!reopened.contains("key-4"));+ assert_own_nearest(&reopened, "key-0", &seeded_unit_vector(80, DIMS));+ }++ #[test]+ fn corrupted_snapshot_bytes_are_discarded() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 5, 90)).unwrap();+ db.flush().unwrap();+ drop(db);+ let mut bytes = fs::read(snapshot_path(&path)).unwrap();+ bytes[20] ^= 0x5A;+ fs::write(snapshot_path(&path), &bytes).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 5);+ assert_own_nearest(&reopened, "key-4", &seeded_unit_vector(94, DIMS));+ }++ #[test]+ fn stale_compaction_temp_files_are_removed_at_open() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 5, 110)).unwrap();+ db.flush().unwrap();+ drop(db);+ fs::write(temp_sibling(&path), [0xAB; 100]).unwrap();+ let db = open_writer(&path);+ assert!(!temp_sibling(&path).exists());+ assert_eq!(db.len(), 5);+ drop(db);+ fs::copy(&path, temp_sibling(&path)).unwrap();+ let db = open_writer(&path);+ assert!(!temp_sibling(&path).exists());+ assert_eq!(db.len(), 5);+ assert!(db.contains("key-2"));+ }++ #[test]+ fn second_writer_is_locked_out() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 3, 120)).unwrap();+ let Err(error) = VecDb::open(&path, DIMS) else {+ panic!("second writer must not open");+ };+ assert!(matches!(error, VecDbError::Locked(locked) if locked == path));+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 3);+ }++ #[test]+ fn read_only_opens_alongside_a_writer() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 3, 130)).unwrap();+ let read_only = VecDb::open_read_only(&path, DIMS).unwrap();+ assert_eq!(read_only.len(), 3);+ assert!(read_only.contains("key-1"));+ db.add("later", &seeded_unit_vector(9, DIMS)).unwrap();+ assert!(!read_only.contains("later"));+ }++ #[test]+ fn read_only_open_of_missing_file_is_empty() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("absent");+ let db = VecDb::open_read_only(&path, DIMS).unwrap();+ assert_eq!(db.len(), 0);+ assert!(db.is_empty());+ assert!(!db.contains("anything"));+ assert!(db.get("anything").is_none());+ assert!(+ db.search(&seeded_unit_vector(1, DIMS), &limit_params(3))+ .unwrap()+ .is_empty()+ );+ assert_eq!(+ db.stats(),+ Stats {+ live_count: 0,+ dead_count: 0,+ dims: DIMS,+ log_bytes: 0,+ records_since_snapshot: 0,+ approximate_memory_bytes: 0,+ }+ );+ assert!(!path.exists());+ assert!(!snapshot_exists(&path));+ }++ #[test]+ fn read_only_instance_rejects_writes() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.add("kept", &seeded_unit_vector(3, DIMS)).unwrap();+ drop(db);+ let mut read_only = VecDb::open_read_only(&path, DIMS).unwrap();+ let vector = seeded_unit_vector(4, DIMS);+ assert!(matches!(+ read_only.add("x", &vector),+ Err(VecDbError::ReadOnly)+ ));+ assert!(matches!(+ read_only.bulk_add(&bulk_entries(0, 2, 5)),+ Err(VecDbError::ReadOnly)+ ));+ assert!(matches!(read_only.bulk_add(&[]), Err(VecDbError::ReadOnly)));+ assert!(matches!(+ read_only.remove("kept"),+ Err(VecDbError::ReadOnly)+ ));+ assert!(matches!(+ read_only.bulk_remove(&["kept".to_string()]),+ Err(VecDbError::ReadOnly)+ ));+ assert!(matches!(read_only.flush(), Err(VecDbError::ReadOnly)));+ assert!(matches!(read_only.reset(), Err(VecDbError::ReadOnly)));+ assert!(read_only.contains("kept"));+ assert!(matches!(read_only.delete(), Err(VecDbError::ReadOnly)));+ assert!(path.exists());+ }++ #[test]+ fn read_only_view_stays_point_in_time_while_writer_compacts() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 100, 140)).unwrap();+ let generation_before = generation_of(&path);+ let read_only = VecDb::open_read_only(&path, DIMS).unwrap();+ assert_eq!(read_only.len(), 100);+ for index in 0..32 {+ assert!(db.remove(&format!("key-{index}")).unwrap());+ }+ assert_ne!(generation_of(&path), generation_before);+ assert_eq!(db.len(), 68);+ assert_eq!(db.stats().dead_count, 0);+ db.add("fresh", &seeded_unit_vector(7, DIMS)).unwrap();+ assert_own_nearest(&db, "key-50", &seeded_unit_vector(190, DIMS));+ assert_eq!(read_only.len(), 100);+ assert!(read_only.contains("key-5"));+ assert!(!read_only.contains("fresh"));+ assert_own_nearest(&read_only, "key-5", &seeded_unit_vector(145, DIMS));+ drop(db);+ let fresh_view = VecDb::open_read_only(&path, DIMS).unwrap();+ assert_eq!(fresh_view.len(), 69);+ assert!(!fresh_view.contains("key-5"));+ assert!(fresh_view.contains("fresh"));+ }++ #[test]+ fn upsert_changes_search_position_across_reopen() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.add("near", &basis_vector(0)).unwrap();+ for axis in 1..11 {+ db.add(&format!("other-{axis}"), &basis_vector(axis))+ .unwrap();+ }+ let query = basis_vector(0);+ assert_own_nearest(&db, "near", &query);+ db.add("near", &negated(&basis_vector(0))).unwrap();+ assert_eq!(db.len(), 11);+ assert_eq!(db.get("near").unwrap(), negated(&basis_vector(0)));+ let checks = |db: &VecDb| {+ assert_ne!(db.search(&query, &limit_params(1)).unwrap()[0].key, "near");+ let exact = SearchParams {+ limit: Some(1),+ exact: true,+ ..SearchParams::default()+ };+ assert_ne!(db.search(&query, &exact).unwrap()[0].key, "near");+ let threshold = SearchParams {+ max_distance: Some(1.5),+ ..SearchParams::default()+ };+ let within = db.search(&query, &threshold).unwrap();+ assert_eq!(within.len(), 10);+ assert!(within.iter().all(|found| found.key != "near"));+ };+ checks(&db);+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.get("near").unwrap(), negated(&basis_vector(0)));+ checks(&reopened);+ }++ #[test]+ fn removed_keys_are_hidden_everywhere_and_can_be_readded() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ for axis in 0..10 {+ db.add(&format!("key-{axis}"), &basis_vector(axis)).unwrap();+ }+ let query = basis_vector(4);+ assert_own_nearest(&db, "key-4", &query);+ assert!(db.remove("key-4").unwrap());+ assert!(!db.remove("key-4").unwrap());+ assert_eq!(db.len(), 9);+ assert!(!db.contains("key-4"));+ assert!(db.get("key-4").is_none());+ assert_eq!(db.stats().dead_count, 2);+ assert_ne!(db.search(&query, &limit_params(1)).unwrap()[0].key, "key-4");+ let exact_all = SearchParams {+ limit: Some(10),+ exact: true,+ ..SearchParams::default()+ };+ let exact = db.search(&query, &exact_all).unwrap();+ assert_eq!(exact.len(), 9);+ assert!(exact.iter().all(|found| found.key != "key-4"));+ let threshold = SearchParams {+ max_distance: Some(0.5),+ ..SearchParams::default()+ };+ assert!(db.search(&query, &threshold).unwrap().is_empty());+ let filtered = SearchParams {+ limit: Some(5),+ allowed_keys: Some(vec!["key-4".to_string()]),+ ..SearchParams::default()+ };+ assert!(db.search(&query, &filtered).unwrap().is_empty());+ db.add("key-4", &basis_vector(4)).unwrap();+ assert_eq!(db.len(), 10);+ assert_own_nearest(&db, "key-4", &query);+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 10);+ assert_own_nearest(&reopened, "key-4", &query);+ }++ #[test]+ fn bulk_remove_counts_only_present_keys_and_absent_remove_does_no_io() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 5, 150)).unwrap();+ let log_bytes = db.stats().log_bytes;+ assert!(!db.remove("missing").unwrap());+ assert_eq!(db.stats().log_bytes, log_bytes);+ let removals = vec![+ "key-1".to_string(),+ "key-1".to_string(),+ "key-3".to_string(),+ "nope".to_string(),+ ];+ assert_eq!(db.bulk_remove(&removals).unwrap(), 2);+ assert_eq!(db.len(), 3);+ assert!(!db.contains("key-1"));+ assert!(!db.contains("key-3"));+ assert_eq!(db.stats().log_bytes, log_bytes + 2 * TOMBSTONE_RECORD_LEN);+ assert_eq!(db.bulk_remove(&[]).unwrap(), 0);+ db.bulk_add(&[]).unwrap();+ assert_eq!(db.stats().log_bytes, log_bytes + 2 * TOMBSTONE_RECORD_LEN);+ }++ #[test]+ fn quiet_gap_snapshot_needs_a_thousand_mutations() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.add("seed", &seeded_unit_vector(1, DIMS)).unwrap();+ writer(&mut db).mutations_since_snapshot = 998;+ db.record_mutations(1, Instant::now() + Duration::from_secs(30))+ .unwrap();+ assert_eq!(writer(&mut db).mutations_since_snapshot, 999);+ assert!(!snapshot_exists(&path));+ db.record_mutations(1, Instant::now() + Duration::from_secs(60))+ .unwrap();+ assert_eq!(writer(&mut db).mutations_since_snapshot, 0);+ assert!(snapshot_exists(&path));+ }++ #[test]+ fn thousand_mutations_without_quiet_gap_do_not_snapshot() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.add("seed", &seeded_unit_vector(1, DIMS)).unwrap();+ writer(&mut db).mutations_since_snapshot = 999;+ db.record_mutations(1, Instant::now()).unwrap();+ assert_eq!(writer(&mut db).mutations_since_snapshot, 1000);+ assert!(!snapshot_exists(&path));+ }++ #[test]+ fn hard_cap_snapshots_regardless_of_gap() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.add("seed", &seeded_unit_vector(1, DIMS)).unwrap();+ writer(&mut db).mutations_since_snapshot = 4999;+ db.record_mutations(1, Instant::now()).unwrap();+ assert_eq!(writer(&mut db).mutations_since_snapshot, 0);+ assert!(snapshot_exists(&path));+ }++ #[test]+ fn flush_snapshots_pending_mutations_and_resets() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 2, 160)).unwrap();+ assert!(!snapshot_exists(&path));+ assert_eq!(db.stats().records_since_snapshot, 2);+ db.flush().unwrap();+ assert!(snapshot_exists(&path));+ assert_eq!(db.stats().records_since_snapshot, 0);+ fs::remove_file(snapshot_path(&path)).unwrap();+ db.flush().unwrap();+ assert!(!snapshot_exists(&path));+ }++ #[test]+ fn open_after_tail_replay_writes_a_fresh_snapshot() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 3, 170)).unwrap();+ drop(db);+ assert!(!snapshot_exists(&path));+ drop(open_writer(&path));+ assert!(snapshot_exists(&path));+ let log_len = fs::metadata(&path).unwrap().len();+ let loaded = load_snapshot(&path, generation_of(&path), log_len).unwrap();+ assert_eq!(loaded.covered_log_offset, log_len);+ let snapshot_bytes = fs::read(snapshot_path(&path)).unwrap();+ drop(open_writer(&path));+ assert_eq!(fs::read(snapshot_path(&path)).unwrap(), snapshot_bytes);+ }++ #[test]+ fn compaction_rewrites_log_and_preserves_live_data() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 120, 1000)).unwrap();+ let generation_before = generation_of(&path);+ for index in 0..40u64 {+ db.add(+ &format!("key-{index}"),+ &seeded_unit_vector(5000 + index, DIMS),+ )+ .unwrap();+ }+ assert_eq!(generation_of(&path), generation_before);+ assert_eq!(db.stats().dead_count, 40);+ let log_bytes_before = db.stats().log_bytes;+ let removals: Vec<String> = (90..120).map(|index| format!("key-{index}")).collect();+ assert_eq!(db.bulk_remove(&removals).unwrap(), 30);+ let stats = db.stats();+ assert_eq!(stats.live_count, 90);+ assert_eq!(stats.dead_count, 0);+ assert_eq!(stats.records_since_snapshot, 0);+ assert!(stats.log_bytes < log_bytes_before);+ assert_ne!(generation_of(&path), generation_before);+ let loaded = load_snapshot(&path, generation_of(&path), stats.log_bytes).unwrap();+ assert_eq!(loaded.covered_log_offset, stats.log_bytes);+ let live_vector = |index: u64| {+ if index < 40 {+ seeded_unit_vector(5000 + index, DIMS)+ } else {+ seeded_unit_vector(1000 + index, DIMS)+ }+ };+ let verify = |db: &VecDb| {+ assert_eq!(db.len(), 90);+ for index in 90..120 {+ assert!(!db.contains(&format!("key-{index}")));+ }+ for index in 0..90u64 {+ assert_own_nearest(db, &format!("key-{index}"), &live_vector(index));+ }+ };+ verify(&db);+ let query = seeded_unit_vector(31337, DIMS);+ let approx_before = db.search(&query, &limit_params(10)).unwrap();+ drop(db);+ let reopened = open_writer(&path);+ verify(&reopened);+ assert_eq!(+ reopened.search(&query, &limit_params(10)).unwrap(),+ approx_before+ );+ drop(reopened);+ fs::remove_file(snapshot_path(&path)).unwrap();+ let replayed = open_writer(&path);+ verify(&replayed);+ }++ #[test]+ fn compaction_streams_multiple_batches() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 1100, 3000)).unwrap();+ let generation_before = generation_of(&path);+ let removals: Vec<String> = (0..58).map(|index| format!("key-{index}")).collect();+ assert_eq!(db.bulk_remove(&removals).unwrap(), 58);+ assert_ne!(generation_of(&path), generation_before);+ let stats = db.stats();+ assert_eq!(stats.live_count, 1042);+ assert_eq!(stats.dead_count, 0);+ for index in (58..1100u64).step_by(97) {+ assert_own_nearest(+ &db,+ &format!("key-{index}"),+ &seeded_unit_vector(3000 + index, DIMS),+ );+ }+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 1042);+ assert!(!reopened.contains("key-0"));+ assert!(reopened.contains("key-58"));+ }++ #[test]+ fn stale_snapshot_left_by_interrupted_compaction_is_discarded_on_open() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 120, 210)).unwrap();+ db.flush().unwrap();+ let stale_snapshot = fs::read(snapshot_path(&path)).unwrap();+ let removals: Vec<String> = (0..64).map(|index| format!("key-{index}")).collect();+ assert_eq!(db.bulk_remove(&removals).unwrap(), 64);+ assert_eq!(db.stats().dead_count, 0);+ drop(db);+ fs::write(snapshot_path(&path), &stale_snapshot).unwrap();+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 56);+ for index in 64..120u64 {+ assert_eq!(+ reopened.get(&format!("key-{index}")).unwrap(),+ seeded_unit_vector(210 + index, DIMS)+ );+ }+ assert_own_nearest(&reopened, "key-100", &seeded_unit_vector(310, DIMS));+ let stats = reopened.stats();+ assert_eq!(stats.dead_count, 0);+ let loaded = load_snapshot(&path, generation_of(&path), stats.log_bytes).unwrap();+ assert_eq!(loaded.covered_log_offset, stats.log_bytes);+ assert_ne!(fs::read(snapshot_path(&path)).unwrap(), stale_snapshot);+ }++ #[test]+ fn open_of_a_short_file_fails_clean_without_altering_it() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let partial = [0x45u8, 0x56, 0x44, 0x42, 0x01, 0x00, 0x00];+ fs::write(&path, partial).unwrap();+ assert!(matches!(+ VecDb::open(&path, DIMS),+ Err(VecDbError::Corrupt(_))+ ));+ assert_eq!(fs::read(&path).unwrap(), partial);+ assert!(matches!(+ VecDb::open_read_only(&path, DIMS),+ Err(VecDbError::Corrupt(_))+ ));+ assert_eq!(fs::read(&path).unwrap(), partial);+ assert!(!snapshot_exists(&path));+ }++ #[test]+ fn reset_empties_the_db_and_keeps_it_usable() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 20, 180)).unwrap();+ db.flush().unwrap();+ let generation_before = generation_of(&path);+ db.reset().unwrap();+ assert!(db.is_empty());+ assert!(!snapshot_exists(&path));+ assert_ne!(generation_of(&path), generation_before);+ assert_eq!(fs::metadata(&path).unwrap().len(), 32);+ assert_eq!(+ db.stats(),+ Stats {+ live_count: 0,+ dead_count: 0,+ dims: DIMS,+ log_bytes: 32,+ records_since_snapshot: 0,+ approximate_memory_bytes: 0,+ }+ );+ db.add("again", &seeded_unit_vector(2, DIMS)).unwrap();+ assert_own_nearest(&db, "again", &seeded_unit_vector(2, DIMS));+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 1);+ assert!(reopened.contains("again"));+ assert!(!reopened.contains("key-0"));+ }++ #[test]+ fn delete_removes_all_files() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.bulk_add(&bulk_entries(0, 5, 190)).unwrap();+ db.flush().unwrap();+ fs::write(temp_sibling(&path), [7u8; 10]).unwrap();+ assert!(path.exists());+ assert!(snapshot_exists(&path));+ db.delete().unwrap();+ assert!(!path.exists());+ assert!(!snapshot_exists(&path));+ assert!(!temp_sibling(&path).exists());+ }++ #[test]+ fn non_finite_vectors_are_rejected_without_partial_state() {+ let dir = TempDir::new().unwrap();+ let path = dir.path().join("db");+ let mut db = open_writer(&path);+ db.add("key-0", &seeded_unit_vector(0, DIMS)).unwrap();+ let log_bytes = db.stats().log_bytes;+ for bad_value in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] {+ let mut bad = seeded_unit_vector(9, DIMS);+ bad[3] = bad_value;+ assert!(matches!(+ db.add("bad", &bad),+ Err(VecDbError::InvalidVector(_))+ ));+ assert!(!db.contains("bad"));+ }+ let mut infected = bulk_entries(10, 3, 200);+ infected[1].1[0] = f32::INFINITY;+ assert!(matches!(+ db.bulk_add(&infected),+ Err(VecDbError::InvalidVector(_))+ ));+ assert_eq!(db.len(), 1);+ assert!(!db.contains("key-10"));+ assert!(!db.contains("key-12"));+ assert_eq!(db.stats().log_bytes, log_bytes);+ drop(db);+ let reopened = open_writer(&path);+ assert_eq!(reopened.len(), 1);+ assert!(reopened.contains("key-0"));+ assert!(!reopened.contains("bad"));+ }+}