Struct AnnIndex 

pub struct AnnIndex { /* private fields */ }

A project-scoped, disk-persisted HNSW index. See the module docs for the overall approach.

Implementations

impl AnnIndex

pub async fn load_or_empty( project_hash: &str, dim: usize, ) -> Result<Self, CoreError>

Load from disk, or create an empty index if the on-disk files are missing / corrupt / dim-mismatched. Never errors — worst case the caller gets an empty index and retrieval falls through to the linear path.

pub async fn build_from_chunks( project_hash: &str, chunks: &[(String, Vec<f32>)], ) -> Result<Self, CoreError>

Construct a fresh index from a full slice of chunks. Used when no on-disk graph exists or when the caller wants to compact out tombstones. Swallows per-chunk dim mismatches (those rows are dropped) but never errors.

pub fn upsert(&mut self, chunk_id: &str, embedding: &[f32])

Upsert a single chunk. The previous entry (if any) is marked tombstoned so it won’t surface in future searches; the new embedding is appended to the graph with a fresh internal id.

A dim mismatch is silently ignored — the caller is the SQL upsert path which continues regardless, matching the “ANN never blocks rule writes” contract.

pub fn remove(&mut self, chunk_id: &str)

Mark a chunk as removed. The underlying HNSW entry is NOT physically deleted (hnsw_rs has no public remove API); instead we tombstone it so search skips it. Full reclamation happens on the next build_from_chunks.

pub fn search(&self, query: &[f32], top_k: usize) -> Vec<(String, f32)>

Search for top_k nearest chunks to the query. Returns (chunk_id, distance) pairs with smaller distance = more similar (DistCosine returns 1 - cos). An empty index, dim mismatch, empty query, or any internal error yields an empty result — the caller should interpret that as “use the linear scan”.

pub async fn save(&mut self) -> Result<(), CoreError>

Persist the index + sidecar to ~/.difflore/projects/{hash}/. A best-effort operation — directory-create and graph-dump errors bubble up so callers can log them, but the typical caller (upsert_rule_chunks) swallows the error. Sets dirty = false on success.

pub const fn is_dirty(&self) -> bool

Has the in-memory state diverged from disk? Callers can gate expensive save() calls on this.

pub fn live_size(&self) -> u32

Number of live (non-tombstoned) chunks in the index. Used by the trajectory emitter so the cloud dashboard can chart index growth.

pub fn total_size(&self) -> u32

Total chunk count including tombstones. Mostly for tests / diagnostics.

pub const fn dim(&self) -> usize

Dimensionality of the stored vectors. Zero means “unset” (empty index that has never been written to).