1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
//! Disk persistence for `vicinity` indexes.
//!
//! Two persistence paths are available:
//!
//! - **Simple** (`serde` feature): `save_to_writer` / `load_from_reader` on `HNSWIndex`.
//! JSON-based, one function call each way. Best for checkpoint/restore workflows.
//!
//! - **Segment** (`persistence` feature): Binary SoA format via `HNSWSegmentWriter` /
//! `HNSWSegmentReader`. Smaller on disk, cache-friendly layout.
//!
//! The `persistence` feature also brings WAL support via `durability`.
//!
//! # Format compatibility
//!
//! Segment metadata written by vicinity 0.7+ starts with an 8-byte magic
//! (`format::HNSW_SEGMENT_MAGIC`, `VCNHNSW\x01`) followed by a version number
//! (`format::FORMAT_VERSION`). The loader's contract:
//!
//! - Segments written by 0.6.x (no magic) load transparently via a legacy
//! v0 decode path.
//! - A version newer than the running crate supports is rejected with
//! [`PersistenceError::Format`]; old crates never silently misread new
//! files.
//! - Corrupt or truncated input returns [`PersistenceError`] (`Format` or
//! `Io`); load never panics and never constructs an index from garbage.
//! Size guards reject files claiming unreasonable dimensions, vector
//! counts, or neighbor counts.
//!
//! The simple JSON path makes the same error-not-panic promise: corrupt or
//! truncated JSON fails `load_from_reader` with a typed error, and structural
//! invariants are validated before the index is usable.
//!
//! See `docs/persistence.md` for the repo-level storage-mode contract across
//! HNSW, DiskANN, IVF, and streaming index families.
pub use PersistenceError;