π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
vecdb: drop wide, auto-vectorized pure-std distance kernel
laurenspriem211994a78d2d
diff --git a/rust/Cargo.lock b/rust/Cargo.lockindex f07475e5be..df81838461 100644--- a/rust/Cargo.lock+++ b/rust/Cargo.lock@@ -2686,7 +2686,6 @@ dependencies = ["tokio","url","usearch",- "wide",][[package]]diff --git a/rust/crates/ml/Cargo.toml b/rust/crates/ml/Cargo.tomlindex 67de8babf3..63838602f8 100644--- a/rust/crates/ml/Cargo.toml+++ b/rust/crates/ml/Cargo.toml@@ -25,7 +25,6 @@ thiserror.workspace = true# The FRB photos bridge calls the SimSIMD symbol exported by usearch 2.21.x.# Newer usearch releases switched that implementation to numkong symbols.usearch = { version = "=2.21.4", optional = true }-wide = "0.7"# Cargokit sets ORT_LIB_PATH to Ente's verified iOS archive.[target.'cfg(target_os = "ios")'.dependencies]diff --git a/rust/crates/ml/docs/adr/0001-vecdb-durable-log-plus-derived-graph.md b/rust/crates/ml/docs/adr/0001-vecdb-durable-log-plus-derived-graph.mdindex b86f52fe01..54b1c53563 100644--- a/rust/crates/ml/docs/adr/0001-vecdb-durable-log-plus-derived-graph.md+++ b/rust/crates/ml/docs/adr/0001-vecdb-durable-log-plus-derived-graph.md@@ -17,6 +17,7 @@ We replaced usearch (C++ under the hood, broken on the napi desktop toolchain, r- Single metric (inner product on L2-normalized vectors, distance = 1 β dot) and single scalar (f32) are hardcoded; the file header carries scalar/metric tags and the distance kernel sits behind one internal seam so smaller scalars (f16/i8) can be added without a format break.- Keys are strings (non-empty UTF-8, β€ 256 bytes), not integers: file/face/cluster IDs are used directly, which clears the way to retire the four AUTOINCREMENT key-mapping tables the app kept in sqlite solely for usearch's u64 keys once vecdb replaces usearch. Internally keys are interned to u32 slots; the graph, arena, and log replay speak slots.- Vectors live on disk as raw little-endian f32 payloads in the framed log records, and in memory in a chunked, 32-byte-aligned arena (chunks of SIMD lanes; free-list slot reuse; growth never reallocates existing chunks). Memory-mapping the log was rejected: it breaks wasm compatibility, fights rename-based compaction on Windows, and framed records give no alignment guarantee.-- vecdb is layered as an IO-free core (graph, arena, SIMD kernels β wasm32-compatible) beneath a native-only storage layer (fs, fsync, locking). The writer lock is std file locking (`File::try_lock`) on the `<path>.lock` sidecar β no `libc`, no `windows-sys` β and is held continuously across compaction, so there is never an unlock window; locking the sidecar rather than the log keeps Windows whole-file lock semantics away from readers and log renames. vecdb's only dependency is `wide` (already in the tree); locking is std file locking and CRC32 is hand-rolled in-module, so vecdb adds zero new Cargo.lock entries.+- vecdb is layered as an IO-free core (graph, arena, distance kernel β wasm32-compatible) beneath a native-only storage layer (fs, fsync, locking). The writer lock is std file locking (`File::try_lock`) on the `<path>.lock` sidecar β no `libc`, no `windows-sys` β and is held continuously across compaction, so there is never an unlock window; locking the sidecar rather than the log keeps Windows whole-file lock semantics away from readers and log renames. vecdb has zero direct dependencies: locking is std file locking, CRC32 is hand-rolled in-module, and the distance kernel is pure std.+- SIMD comes from auto-vectorization by construction, not a SIMD crate: the dot product keeps 8 independent partial accumulators over 32-byte-aligned 8-float lanes and reduces them in a fixed sequential order. This loop shape is load-bearing β a single running sum cannot legally auto-vectorize because float addition is non-associative β and an A/B against an explicit-SIMD (`wide`) kernel measured it within ~10% on the exact-scan path on baseline NEON, parity elsewhere, with bit-identical results (same reduction order, pinned by the kernel tests). Do not collapse the accumulators.- usearch stays in the tree, feature-gated, while vecdb runs as a parallel engine for internal users; removal is a separate later decision.- Derived-state failures degrade instead of failing writes: snapshot and compaction errors are logged as warnings and never fail an acknowledged write, open never fails for snapshot reasons, and only an explicit `flush()` surfaces snapshot errors to the caller.diff --git a/rust/crates/ml/src/vecdb/arena.rs b/rust/crates/ml/src/vecdb/arena.rsindex 8c0d337c95..8c98b2aceb 100644--- a/rust/crates/ml/src/vecdb/arena.rs+++ b/rust/crates/ml/src/vecdb/arena.rs@@ -1,10 +1,8 @@use std::collections::HashMap;-use wide::f32x8;-use super::VecDbError;use super::kernel::{- F32Kernel, LANE_WIDTH, VectorKernel, pack_lanes, pack_lanes_into, unpack_lanes,+ F32Kernel, LANE_WIDTH, Lane, VectorKernel, pack_lanes, pack_lanes_into, unpack_lanes,};pub(crate) const VECTORS_PER_CHUNK: usize = 4096;@@ -33,7 +31,7 @@ pub(crate) fn validate_key(key: &str) -> Result<(), VecDbError> {pub(crate) struct VectorArena {dims: usize,lanes_per_vector: usize,- chunks: Vec<Vec<f32x8>>,+ chunks: Vec<Vec<Lane>>,keys_to_slots: HashMap<Box<str>, u32>,slots_to_keys: Vec<Box<str>>,alive: Vec<u64>,@@ -105,7 +103,7 @@ impl VectorArena {let slot = self.slots_to_keys.len() as u32;if slot as usize == self.chunks.len() * VECTORS_PER_CHUNK {self.chunks- .push(vec![f32x8::ZERO; VECTORS_PER_CHUNK * self.lanes_per_vector]);+ .push(vec![Lane::ZERO; VECTORS_PER_CHUNK * self.lanes_per_vector]);}if slot as usize / 64 == self.alive.len() {self.alive.push(0);@@ -148,7 +146,7 @@ impl VectorArena {(0..self.slots_to_keys.len() as u32).filter(|slot| self.is_alive(*slot))}- pub(crate) fn vector_lanes(&self, slot: u32) -> &[f32x8] {+ pub(crate) fn vector_lanes(&self, slot: u32) -> &[Lane] {let start = (slot as usize % VECTORS_PER_CHUNK) * self.lanes_per_vector;&self.chunks[slot as usize / VECTORS_PER_CHUNK][start..start + self.lanes_per_vector]}@@ -157,7 +155,7 @@ impl VectorArena {unpack_lanes(self.vector_lanes(slot))}- pub(crate) fn pack_query(&self, values: &[f32]) -> Result<Vec<f32x8>, VecDbError> {+ pub(crate) fn pack_query(&self, values: &[f32]) -> Result<Vec<Lane>, VecDbError> {if values.len() != self.dims {return Err(VecDbError::DimensionMismatch {expected: self.dims,@@ -171,11 +169,11 @@ impl VectorArena {F32Kernel::distance(self.vector_lanes(a), self.vector_lanes(b))}- pub(crate) fn distance_to_query(&self, query: &[f32x8], slot: u32) -> f32 {+ pub(crate) fn distance_to_query(&self, query: &[Lane], slot: u32) -> f32 {F32Kernel::distance(query, self.vector_lanes(slot))}- fn vector_lanes_mut(&mut self, slot: u32) -> &mut [f32x8] {+ fn vector_lanes_mut(&mut self, slot: u32) -> &mut [Lane] {let start = (slot as usize % VECTORS_PER_CHUNK) * self.lanes_per_vector;&mut self.chunks[slot as usize / VECTORS_PER_CHUNK][start..start + self.lanes_per_vector]}diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rsindex 53190fd980..b7c731a3e2 100644--- a/rust/crates/ml/src/vecdb/graph.rs+++ b/rust/crates/ml/src/vecdb/graph.rs@@ -1,10 +1,8 @@use std::cmp::{Ordering, Reverse};use std::collections::{BinaryHeap, HashSet};-use wide::f32x8;-use super::arena::VectorArena;-use super::kernel::splitmix64;+use super::kernel::{Lane, splitmix64};use super::{Match, SearchParams, VecDbError};const M: usize = 16;@@ -364,7 +362,7 @@ impl Graph {struct QueryContext<'a> {graph: &'a Graph,arena: &'a VectorArena,- query: &'a [f32x8],+ query: &'a [Lane],}impl QueryContext<'_> {@@ -461,7 +459,7 @@ impl QueryContext<'_> {pub(crate) fn search(graph: &Graph,arena: &VectorArena,- query: &[f32x8],+ query: &[Lane],params: &SearchParams,allowed_slots: Option<&HashSet<u32>>,) -> Vec<Match> {@@ -471,7 +469,7 @@ pub(crate) fn search(pub(crate) fn search_excluding(graph: &Graph,arena: &VectorArena,- query: &[f32x8],+ query: &[Lane],params: &SearchParams,allowed_slots: Option<&HashSet<u32>>,banned_slot: Option<u32>,@@ -520,7 +518,7 @@ pub(crate) fn search_excluding(}}-fn query_is_finite(query: &[f32x8]) -> bool {+fn query_is_finite(query: &[Lane]) -> bool {query.iter().all(|lane| lane.to_array().iter().all(|value| value.is_finite()))@@ -601,7 +599,7 @@ fn approx_threshold(fn brute_force(arena: &VectorArena,- query: &[f32x8],+ query: &[Lane],params: &SearchParams,allowed: Option<&HashSet<u32>>,banned: Option<u32>,@@ -818,7 +816,7 @@ mod tests {fn reference_ranking(arena: &VectorArena,- query: &[f32x8],+ query: &[Lane],allowed: Option<&HashSet<u32>>,) -> Vec<(f32, u32)> {let mut scored: Vec<(f32, u32)> = arenadiff --git a/rust/crates/ml/src/vecdb/kernel.rs b/rust/crates/ml/src/vecdb/kernel.rsindex 0efb74ce85..771b54e195 100644--- a/rust/crates/ml/src/vecdb/kernel.rs+++ b/rust/crates/ml/src/vecdb/kernel.rs@@ -1,7 +1,23 @@-use wide::f32x8;-pub(crate) const LANE_WIDTH: usize = 8;+#[repr(C, align(32))]+#[derive(Clone, Copy)]+pub(crate) struct Lane([f32; LANE_WIDTH]);++impl Lane {+ pub(crate) const ZERO: Self = Self([0.0; LANE_WIDTH]);++ pub(crate) fn to_array(self) -> [f32; LANE_WIDTH] {+ self.0+ }+}++impl From<[f32; LANE_WIDTH]> for Lane {+ fn from(values: [f32; LANE_WIDTH]) -> Self {+ Self(values)+ }+}+pub(crate) fn splitmix64(state: &mut u64) -> u64 {*state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);let mut mixed = *state;@@ -23,35 +39,37 @@ pub(crate) trait VectorKernel {pub(crate) struct F32Kernel;impl VectorKernel for F32Kernel {- type Lane = f32x8;+ type Lane = Lane;- fn dot(a: &[f32x8], b: &[f32x8]) -> f32 {+ fn dot(a: &[Lane], b: &[Lane]) -> f32 {debug_assert_eq!(a.len(), b.len());- let mut acc = f32x8::ZERO;+ let mut partials = [0.0f32; LANE_WIDTH];for (x, y) in a.iter().zip(b.iter()) {- acc += *x * *y;+ for (partial, (left, right)) in partials.iter_mut().zip(x.0.iter().zip(&y.0)) {+ *partial += left * right;+ }}- acc.to_array().iter().sum()+ partials.iter().sum()}}-pub(crate) fn pack_lanes(values: &[f32]) -> Vec<f32x8> {+pub(crate) fn pack_lanes(values: &[f32]) -> Vec<Lane> {debug_assert_eq!(values.len() % LANE_WIDTH, 0);- let mut lanes = vec![f32x8::ZERO; values.len() / LANE_WIDTH];+ let mut lanes = vec![Lane::ZERO; values.len() / LANE_WIDTH];pack_lanes_into(values, &mut lanes);lanes}-pub(crate) fn pack_lanes_into(values: &[f32], lanes: &mut [f32x8]) {+pub(crate) fn pack_lanes_into(values: &[f32], lanes: &mut [Lane]) {debug_assert_eq!(values.len(), lanes.len() * LANE_WIDTH);let (groups, remainder) = values.as_chunks::<LANE_WIDTH>();debug_assert!(remainder.is_empty());for (lane, group) in lanes.iter_mut().zip(groups) {- *lane = f32x8::from(*group);+ *lane = Lane::from(*group);}}-pub(crate) fn unpack_lanes(lanes: &[f32x8]) -> Vec<f32> {+pub(crate) fn unpack_lanes(lanes: &[Lane]) -> Vec<f32> {let mut values = Vec::with_capacity(lanes.len() * LANE_WIDTH);for lane in lanes {values.extend_from_slice(&lane.to_array());@@ -148,7 +166,7 @@ mod tests {#[test]fn packed_lanes_are_32_byte_aligned() {- assert_eq!(align_of::<f32x8>(), 32);+ assert_eq!(align_of::<Lane>(), 32);for dims in [128, 192, 512] {let lanes = pack_lanes(&seeded_values(5, dims));assert_eq!(lanes.as_ptr() as usize % 32, 0);