velesdb-core 5.0.0

//! Crash-simulation tests for `save_sidecars` / `load_sidecars` atomicity
//! (issue #617).
//!
//! `save_sidecars` writes the sidecar files sequentially
//! (`native_mappings.bin`, `native_meta.bin`). Each individual file uses
//! atomic write-tmp-fsync-rename, but the multi-file sequence itself is not
//! atomic. A crash between two renames leaves the on-disk state
//! inconsistent, which can silently corrupt search or panic at load time.
//!
//! To detect a crashed save we stamp every sidecar with a monotonic
//! `generation: u64`. `meta` (written last) is the authoritative commit
//! point. Any file with a stale generation is proof of an incomplete
//! prior save, and `load_sidecars` must reject the database with
//! `io::ErrorKind::InvalidData` rather than silently return a torn state.
//!
//! Vector data lives inside the graph dump since PERF1 (the legacy
//! `native_vectors.bin` duplicate is no longer written). Databases written
//! by older binaries still carry that file: its generation stamp must keep
//! participating in the consistency check (payload discarded), and
//! `save_sidecars` must delete it.
//!
//! These tests simulate the crashed states by manually rewriting the
//! sidecar files with mismatched generations, no real crash is needed.
//! Backward-compat cases (legacy DBs without the generation counter)
//! must keep loading unchanged.
//!
//! NOTE: this module is an internal `#[cfg(test)]` sibling of
//! [`super::persistence`], which means every `pub(crate)` helper in
//! `persistence.rs` is reachable from here.

use super::persistence::{
    self, load_sidecars, save_sidecars, HnswMappingsData, HnswMeta, HnswVectorsData,
};
use super::sharded_mappings::ShardedMappings;
use crate::distance::DistanceMetric;
use crate::StorageMode;
use std::collections::HashMap;
use std::path::Path;
use tempfile::TempDir;

// -----------------------------------------------------------------------
// Helpers
// -----------------------------------------------------------------------

/// Vector-slot count of the (virtual) graph matching [`build_mappings`]:
/// indices {0, 1} must resolve, so the graph store holds 2 slots.
const GRAPH_COUNT: usize = 2;

/// Builds a minimal `HnswMeta` for the atomicity tests.
fn build_meta(generation: u64) -> HnswMeta {
    HnswMeta {
        dimension: 4,
        metric: DistanceMetric::Cosine,
        enable_vector_storage: true,
        storage_mode: StorageMode::Full,
        generation,
    }
}

/// Builds a populated `ShardedMappings` containing two id→idx pairs.
fn build_mappings() -> ShardedMappings {
    let mut id_to_idx = HashMap::new();
    id_to_idx.insert(1_u64, 0_usize);
    id_to_idx.insert(2_u64, 1_usize);
    let mut idx_to_id = HashMap::new();
    idx_to_id.insert(0_usize, 1_u64);
    idx_to_id.insert(1_usize, 2_u64);
    ShardedMappings::from_parts(id_to_idx, idx_to_id, 2)
}

/// Builds the legacy vectors payload (two 4-d vectors) as written by
/// pre-PERF1 binaries into `native_vectors.bin`.
fn build_legacy_vectors(generation: u64) -> HnswVectorsData {
    HnswVectorsData {
        vectors: vec![
            (0_usize, vec![1.0_f32, 0.0, 0.0, 0.0]),
            (1_usize, vec![0.0_f32, 1.0, 0.0, 0.0]),
        ],
        generation,
    }
}

/// Writes the legacy 4-tuple meta format (v1.7.2+, without the generation
/// field) directly via postcard, bypassing `save_meta` so the file ends
/// up at a real pre-fix format.
fn write_legacy_4tuple_meta(path: &Path, meta: &HnswMeta) -> std::io::Result<()> {
    let metric_u8 = meta.metric as u8;
    let storage_mode_u8 = match meta.storage_mode {
        StorageMode::Full => 0u8,
        StorageMode::SQ8 => 1,
        StorageMode::Binary => 2,
        StorageMode::ProductQuantization => 3,
        StorageMode::RaBitQ => 4,
    };
    let bytes = postcard::to_allocvec(&(
        meta.dimension,
        metric_u8,
        meta.enable_vector_storage,
        storage_mode_u8,
    ))
    .map_err(std::io::Error::other)?;
    std::fs::write(path.join("native_meta.bin"), bytes)
}

/// Writes the legacy 3-tuple meta format (pre-v1.7.2, without storage mode
/// or generation) directly via postcard.
fn write_legacy_3tuple_meta(path: &Path, meta: &HnswMeta) -> std::io::Result<()> {
    let metric_u8 = meta.metric as u8;
    let bytes = postcard::to_allocvec(&(meta.dimension, metric_u8, meta.enable_vector_storage))
        .map_err(std::io::Error::other)?;
    std::fs::write(path.join("native_meta.bin"), bytes)
}

/// Writes the legacy 3-tuple mappings format (pre-generation) directly.
fn write_legacy_3tuple_mappings(path: &Path, data: &HnswMappingsData) -> std::io::Result<()> {
    let bytes = postcard::to_allocvec(&(&data.id_to_idx, &data.idx_to_id, data.next_idx))
        .map_err(std::io::Error::other)?;
    std::fs::write(path.join("native_mappings.bin"), bytes)
}

/// Writes the legacy plain-`Vec` vectors format (pre-generation) directly.
fn write_legacy_plain_vectors(path: &Path, data: &HnswVectorsData) -> std::io::Result<()> {
    let bytes = postcard::to_allocvec(&data.vectors).map_err(std::io::Error::other)?;
    std::fs::write(path.join("native_vectors.bin"), bytes)
}

/// Returns the `HnswMappingsData` in the same shape `save_sidecars` expects.
fn mappings_data(mappings: &ShardedMappings, generation: u64) -> HnswMappingsData {
    let (id_to_idx, idx_to_id, next_idx) = mappings.as_parts();
    HnswMappingsData {
        id_to_idx,
        idx_to_id,
        next_idx,
        generation,
    }
}

// -----------------------------------------------------------------------
// Test 1 — save_sidecars stamps a monotonically increasing generation
// -----------------------------------------------------------------------

#[test]
fn test_save_sidecars_stamps_monotonic_generation() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();
    let meta = build_meta(0);

    for expected in 1..=3_u64 {
        let new_gen = persistence::next_generation(path).expect("test: next_generation");
        assert_eq!(new_gen, expected);
        save_sidecars(path, &mappings, &meta, new_gen).expect("test: save");
    }

    let loaded_meta = persistence::load_meta(path).expect("test: load meta");
    assert_eq!(
        loaded_meta.generation, 3,
        "meta generation should be bumped once per save"
    );

    let loaded_mappings = persistence::load_mappings(path).expect("test: load mappings");
    assert_eq!(
        loaded_mappings.generation, 3,
        "mappings generation must match meta"
    );

    // PERF1: the vectors duplicate is no longer written.
    assert!(
        !path.join("native_vectors.bin").exists(),
        "save_sidecars must not write the legacy vectors file"
    );
}

// -----------------------------------------------------------------------
// Test 2 — load_sidecars detects stale mappings
// -----------------------------------------------------------------------

#[test]
fn test_load_sidecars_detects_stale_mappings() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Simulate a save at generation 4 (all artefacts consistent).
    let meta_4 = build_meta(4);
    persistence::save_graph_generation(path, 4).expect("test: graph gen 4");
    persistence::save_mappings(path, &mappings_data(&mappings, 4)).expect("test: save mappings 4");
    persistence::save_meta(path, &meta_4).expect("test: save meta 4");

    // Now simulate a crash at generation 5 that only rewrote mappings.
    persistence::save_mappings(path, &mappings_data(&mappings, 5)).expect("test: save mappings 5");

    let loaded_meta = persistence::load_meta(path).expect("test: reload meta");
    let err = load_sidecars(path, &loaded_meta, GRAPH_COUNT)
        .expect_err("test: stale mappings must trigger InvalidData");
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string().contains("mappings generation"),
        "error should mention mappings generation, got: {err}"
    );
}

// -----------------------------------------------------------------------
// Test 3 — load_sidecars detects a stale LEGACY vectors file
// -----------------------------------------------------------------------

#[test]
fn test_load_sidecars_detects_stale_legacy_vectors() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Consistent legacy state at generation 4 (graph + mappings + vectors + meta).
    persistence::save_graph_generation(path, 4).expect("test: graph gen 4");
    persistence::save_mappings(path, &mappings_data(&mappings, 4)).expect("test: save mappings 4");
    persistence::save_vectors(path, &build_legacy_vectors(4)).expect("test: save vectors 4");
    persistence::save_meta(path, &build_meta(4)).expect("test: save meta 4");

    // Simulate an old-binary crash at generation 5 that rewrote
    // graph + mappings + meta, leaving the legacy vectors file at gen 4.
    persistence::save_graph_generation(path, 5).expect("test: graph gen 5");
    persistence::save_mappings(path, &mappings_data(&mappings, 5)).expect("test: save mappings 5");
    persistence::save_meta(path, &build_meta(5)).expect("test: save meta 5");

    let loaded_meta = persistence::load_meta(path).expect("test: reload meta");
    let err = load_sidecars(path, &loaded_meta, GRAPH_COUNT)
        .expect_err("test: stale legacy vectors must trigger InvalidData");
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string().contains("vectors generation"),
        "error should mention vectors generation, got: {err}"
    );
}

// -----------------------------------------------------------------------
// Test 4 — load_sidecars detects mappings newer than meta
// -----------------------------------------------------------------------

#[test]
fn test_load_sidecars_detects_newer_mappings_than_meta() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Meta is older (gen 5) than mappings (gen 10) — `meta` is authoritative.
    // Graph marker aligned with meta to isolate the mappings check.
    persistence::save_graph_generation(path, 5).expect("test: graph gen 5");
    persistence::save_mappings(path, &mappings_data(&mappings, 10))
        .expect("test: save mappings 10");
    persistence::save_meta(path, &build_meta(5)).expect("test: save meta 5");

    let loaded_meta = persistence::load_meta(path).expect("test: reload meta");
    let err = load_sidecars(path, &loaded_meta, GRAPH_COUNT)
        .expect_err("test: newer mappings than meta must trigger InvalidData");
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string().contains("mappings generation"),
        "error should mention mappings generation, got: {err}"
    );
}

// -----------------------------------------------------------------------
// Test 5 — backward compat: legacy 4-tuple meta + plain sidecars load
// -----------------------------------------------------------------------

#[test]
fn test_backward_compat_legacy_meta_without_generation_loads() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Pretend the database was written by a pre-fix binary: legacy 4-tuple
    // meta (v1.7.2+ storage mode, no generation), legacy 3-tuple mappings,
    // plain-Vec vectors.
    let meta = build_meta(0); // generation ignored by legacy writer
    write_legacy_4tuple_meta(path, &meta).expect("test: legacy meta");
    write_legacy_3tuple_mappings(path, &mappings_data(&mappings, 0))
        .expect("test: legacy mappings");
    write_legacy_plain_vectors(path, &build_legacy_vectors(0)).expect("test: legacy vectors");

    let loaded_meta = persistence::load_meta(path).expect("test: legacy meta loads");
    assert_eq!(
        loaded_meta.generation, 0,
        "legacy meta must default to generation 0"
    );

    let loaded =
        load_sidecars(path, &loaded_meta, GRAPH_COUNT).expect("test: legacy sidecars load");
    assert_eq!(loaded.len(), 2, "both legacy mappings must load");
    assert!(
        loaded_meta.enable_vector_storage,
        "enable_vector_storage must round-trip from meta"
    );
}

// -----------------------------------------------------------------------
// Test 6 — backward compat: pre-v1.7.2 3-tuple meta + legacy sidecars load
// -----------------------------------------------------------------------

#[test]
fn test_backward_compat_legacy_3tuple_meta_loads() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Pre-v1.7.2 meta: only (dim, metric, enable_vs) — no storage_mode, no
    // generation. Paired with legacy 3-tuple mappings + plain vectors.
    let meta = build_meta(0);
    write_legacy_3tuple_meta(path, &meta).expect("test: 3-tuple meta");
    write_legacy_3tuple_mappings(path, &mappings_data(&mappings, 0))
        .expect("test: legacy mappings");
    write_legacy_plain_vectors(path, &build_legacy_vectors(0)).expect("test: legacy vectors");

    let loaded_meta = persistence::load_meta(path).expect("test: 3-tuple meta loads");
    assert_eq!(
        loaded_meta.generation, 0,
        "3-tuple meta must default to generation 0"
    );
    assert_eq!(
        loaded_meta.storage_mode,
        StorageMode::Full,
        "3-tuple meta must default storage_mode to Full"
    );

    let loaded_mappings =
        load_sidecars(path, &loaded_meta, GRAPH_COUNT).expect("test: legacy sidecars load cleanly");
    assert!(
        loaded_meta.enable_vector_storage,
        "vector storage must round-trip from legacy 3-tuple meta"
    );
    let (id_to_idx, _, next_idx) = loaded_mappings.as_parts();
    assert_eq!(
        id_to_idx.len(),
        2,
        "both legacy mappings must survive the 3-tuple round-trip"
    );
    assert_eq!(next_idx, 2, "next_idx must round-trip from legacy mappings");
}

// -----------------------------------------------------------------------
// Test 7 — existing DB at generation 7 → save → load → generation 8,
// and the stale legacy vectors file is deleted by the save
// -----------------------------------------------------------------------

#[test]
fn test_save_then_load_roundtrip_gen_bumped_and_legacy_file_removed() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Prime the directory with a consistent legacy state at generation 7
    // (including the old vectors duplicate).
    persistence::save_mappings(path, &mappings_data(&mappings, 7)).expect("test: seed mappings");
    persistence::save_vectors(path, &build_legacy_vectors(7)).expect("test: seed vectors");
    persistence::save_meta(path, &build_meta(7)).expect("test: seed meta");
    assert!(path.join("native_vectors.bin").exists());

    // Callers are expected to compute `next_generation(path)` and pass it
    // explicitly; this must read the current on-disk generation and bump to 8.
    let meta_in = build_meta(0); // caller-provided generation ignored
    let new_gen = persistence::next_generation(path).expect("test: next_generation");
    assert_eq!(new_gen, 8, "next_generation must bump from 7 to 8");
    // Production callers stamp the graph marker with the same generation
    // before writing the sidecars — mirror that sequence.
    persistence::save_graph_generation(path, new_gen).expect("test: graph gen 8");
    save_sidecars(path, &mappings, &meta_in, new_gen).expect("test: save bumps gen");

    let loaded_meta = persistence::load_meta(path).expect("test: reload meta");
    assert_eq!(
        loaded_meta.generation, 8,
        "save_sidecars must bump to next generation"
    );

    // PERF1: the stale legacy duplicate must be gone (it would otherwise
    // fail the next load's generation check with its gen-7 stamp).
    assert!(
        !path.join("native_vectors.bin").exists(),
        "save_sidecars must delete a stale legacy vectors file"
    );

    // And the reload passes the consistency check.
    load_sidecars(path, &loaded_meta, GRAPH_COUNT).expect("test: reload after cleanup");
}

// -----------------------------------------------------------------------
// Test 8 — fresh directory: first save starts at generation 1
// -----------------------------------------------------------------------

#[test]
fn test_save_when_no_prior_state_starts_at_gen_1() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Fresh directory, no prior meta. Caller passes generation=0 (ignored).
    let meta_in = build_meta(0);
    let new_gen = persistence::next_generation(path).expect("test: next_generation");
    assert_eq!(
        new_gen, 1,
        "next_generation on a fresh directory must return 1"
    );
    save_sidecars(path, &mappings, &meta_in, new_gen).expect("test: first save");

    let loaded_meta = persistence::load_meta(path).expect("test: reload meta");
    assert_eq!(
        loaded_meta.generation, 1,
        "first save on a fresh directory must land at generation 1"
    );
}

// -----------------------------------------------------------------------
// Test 9 (Devin follow-up) — load_sidecars detects stale HNSW graph
// -----------------------------------------------------------------------

#[test]
fn test_load_sidecars_detects_stale_graph_generation() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();

    // Consistent state at generation 4 across all artefacts.
    persistence::save_graph_generation(path, 4).expect("test: graph gen 4");
    persistence::save_mappings(path, &mappings_data(&mappings, 4)).expect("test: save mappings 4");
    persistence::save_meta(path, &build_meta(4)).expect("test: save meta 4");

    // Simulate a crash after the graph dump (new graph + new marker at gen=5)
    // but BEFORE any sidecar was rewritten — mappings / meta still at gen=4.
    persistence::save_graph_generation(path, 5).expect("test: graph gen 5 only");

    let loaded_meta = persistence::load_meta(path).expect("test: reload meta");
    let err = load_sidecars(path, &loaded_meta, GRAPH_COUNT)
        .expect_err("test: stale graph must trigger InvalidData");
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string().contains("graph generation"),
        "error should mention graph generation, got: {err}"
    );
}

// -----------------------------------------------------------------------
// Test 10 (Devin follow-up) — backward compat without graph marker
// -----------------------------------------------------------------------

#[test]
fn test_backward_compat_no_graph_generation_marker_loads_as_zero() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();

    // Fresh directory: no native_hnsw.gen exists → must read as 0 rather
    // than surfacing a NotFound error. This is what makes legacy DBs (all
    // sidecars at gen=0 by backward-compat default) pass the atomicity
    // check trivially.
    let observed = persistence::load_graph_generation(path)
        .expect("test: missing graph marker must not be an error");
    assert_eq!(
        observed, 0,
        "missing native_hnsw.gen must be treated as generation 0"
    );
}

// -----------------------------------------------------------------------
// Test 11 (Devin follow-up) — save_graph_generation round-trip
// -----------------------------------------------------------------------

#[test]
fn test_save_graph_generation_roundtrip() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();

    persistence::save_graph_generation(path, 42).expect("test: save marker");
    let observed = persistence::load_graph_generation(path).expect("test: reload marker");
    assert_eq!(observed, 42, "graph generation marker must round-trip");

    // Overwriting with a larger generation also round-trips (atomic_write
    // handles replacement).
    persistence::save_graph_generation(path, 9999).expect("test: overwrite marker");
    let observed = persistence::load_graph_generation(path).expect("test: reload marker 2");
    assert_eq!(observed, 9999, "overwritten marker must round-trip");
}

// -----------------------------------------------------------------------
// Test 12 (Devin follow-up #2) — corrupted meta must abort next save,
// not silently reset generation to 1
// -----------------------------------------------------------------------

#[test]
fn test_next_generation_propagates_corrupted_meta_error() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();

    // Write garbage bytes that postcard cannot parse as any of the 3/4/5
    // tuple shapes accepted by `load_meta`.
    std::fs::write(path.join("native_meta.bin"), [0xFF_u8; 32]).expect("test: seed corrupted meta");

    let result = persistence::next_generation(path);
    assert!(
        result.is_err(),
        "corrupted meta must propagate, not silently reset to gen 1 (got {result:?})"
    );

    // Missing meta (fresh directory) must NOT be an error — it is the
    // legitimate "start at generation 1" case.
    let fresh = TempDir::new().expect("test: fresh dir");
    let gen =
        persistence::next_generation(fresh.path()).expect("test: missing meta is not an error");
    assert_eq!(
        gen, 1,
        "missing meta must yield generation 1, not propagate NotFound"
    );
}

// -----------------------------------------------------------------------
// Regression tests (#894): reject corrupt sidecar payloads on load so that
// a malformed legacy vectors file or a broken id<->idx bijection cannot
// reach the SIMD distance kernels or resolve a result to an out-of-range
// index.
// -----------------------------------------------------------------------

/// Writes a consistent generation-4 baseline (graph marker + mappings +
/// meta) so that the generation checks in `load_sidecars` pass and the
/// content validation is what decides accept/reject.
fn seed_consistent_gen4(path: &Path, mappings: &ShardedMappings) {
    persistence::save_graph_generation(path, 4).expect("test: graph gen 4");
    persistence::save_mappings(path, &mappings_data(mappings, 4)).expect("test: save mappings 4");
    persistence::save_meta(path, &build_meta(4)).expect("test: save meta 4");
}

#[test]
fn test_load_sidecars_rejects_wrong_legacy_vector_dimension() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();
    seed_consistent_gen4(path, &mappings);

    // Legacy vectors file at the SAME generation (4) with a wrong-dimension
    // payload: meta declares dimension 4, this vector has length 3. Even
    // though the payload is discarded (PERF1), a malformed file proves
    // corruption and must still be rejected.
    let bad = HnswVectorsData {
        vectors: vec![
            (0_usize, vec![1.0_f32, 2.0, 3.0]),
            (1_usize, vec![0.0_f32; 4]),
        ],
        generation: 4,
    };
    persistence::save_vectors(path, &bad).expect("test: write bad legacy vectors");

    let meta = persistence::load_meta(path).expect("test: reload meta");
    let err = load_sidecars(path, &meta, GRAPH_COUNT)
        .expect_err("test: wrong dimension must be rejected");
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string().contains("dimension"),
        "error should mention dimension, got: {err}"
    );
}

/// Seeds a consistent gen-4 baseline, overwrites the mappings sidecar at the
/// same generation with a single corrupt `id -> idx` pair (so the content
/// validation, not the generation check, decides), then runs `load_sidecars`
/// against a 2-slot graph and returns the resulting error.
fn load_with_corrupt_single_mapping(id: u64, idx: usize, mapped_back: u64) -> std::io::Error {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    seed_consistent_gen4(path, &build_mappings());

    let mut id_to_idx = HashMap::new();
    id_to_idx.insert(id, idx);
    let mut idx_to_id = HashMap::new();
    idx_to_id.insert(idx, mapped_back);
    let bad = HnswMappingsData {
        id_to_idx,
        idx_to_id,
        next_idx: 2,
        generation: 4,
    };
    persistence::save_mappings(path, &bad).expect("test: overwrite mappings");

    let meta = persistence::load_meta(path).expect("test: reload meta");
    load_sidecars(path, &meta, GRAPH_COUNT).expect_err("test: corrupt mapping must be rejected")
}

#[test]
fn test_load_sidecars_rejects_index_beyond_vector_count() {
    // Internal index 99 is absent from the graph's vector store (2 slots);
    // id_to_idx/idx_to_id agree but the index is dangling.
    let err = load_with_corrupt_single_mapping(1, 99, 1);
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string()
            .contains("absent from the loaded vector store"),
        "error should flag the absent index, got: {err}"
    );
}

#[test]
fn test_load_sidecars_rejects_dangling_index_within_next_idx() {
    // The mapping's idx (5) is VALID against the file's own self-reported
    // `next_idx` (6) — the file's own bound would accept it — but the loaded
    // graph store only has 2 slots. The external graph bound must reject
    // this dangling index.
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    seed_consistent_gen4(path, &build_mappings());

    let mut id_to_idx = HashMap::new();
    id_to_idx.insert(1_u64, 5_usize);
    let mut idx_to_id = HashMap::new();
    idx_to_id.insert(5_usize, 1_u64);
    let bad = HnswMappingsData {
        id_to_idx,
        idx_to_id,
        next_idx: 6, // > idx, so the file's own bound would pass
        generation: 4,
    };
    persistence::save_mappings(path, &bad).expect("test: overwrite mappings");

    let meta = persistence::load_meta(path).expect("test: reload meta");
    let err =
        load_sidecars(path, &meta, GRAPH_COUNT).expect_err("test: dangling index must be rejected");
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string()
            .contains("absent from the loaded vector store"),
        "error should flag the absent index, got: {err}"
    );
}

#[test]
fn test_load_sidecars_accepts_sparse_index_beyond_live_count() {
    // Regression for the #908 review: internal indices are sparse and
    // monotonic (never reused after an upsert/delete), so a live mapping
    // legitimately sits at an index >= the live mapping count. Here only 2
    // ids are mapped, at indices {0, 5}, but the graph store has 6 slots
    // (4 tombstones). A `idx < live_count` bound would WRONGLY reject the
    // valid, previously-saved index 5; the graph slot count must accept it.
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();

    let mut id_to_idx = HashMap::new();
    id_to_idx.insert(1_u64, 0_usize);
    id_to_idx.insert(2_u64, 5_usize);
    let mut idx_to_id = HashMap::new();
    idx_to_id.insert(0_usize, 1_u64);
    idx_to_id.insert(5_usize, 2_u64);
    let mappings = ShardedMappings::from_parts(id_to_idx, idx_to_id, 6);
    seed_consistent_gen4(path, &mappings);

    let meta = persistence::load_meta(path).expect("test: reload meta");
    let loaded = load_sidecars(path, &meta, 6).expect("test: sparse-but-valid index must load");
    assert_eq!(
        loaded.get_id(5),
        Some(2_u64),
        "id 2 must resolve via sparse idx 5"
    );
}

#[test]
fn test_load_sidecars_rejects_broken_bijection() {
    // idx 0 is in range but idx_to_id maps it back to a different id (7 != 1).
    let err = load_with_corrupt_single_mapping(1, 0, 7);
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
    assert!(
        err.to_string().contains("bijection"),
        "error should mention bijection, got: {err}"
    );
}

#[test]
fn test_load_sidecars_accepts_valid_sidecars() {
    // Regression guard: the content validation must not reject genuine data.
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    let mappings = build_mappings();
    seed_consistent_gen4(path, &mappings);

    let meta = persistence::load_meta(path).expect("test: reload meta");
    let loaded_mappings =
        load_sidecars(path, &meta, GRAPH_COUNT).expect("test: valid sidecars must load");
    assert!(
        meta.enable_vector_storage,
        "vector storage should remain enabled"
    );
    let (id_to_idx, _, next_idx) = loaded_mappings.as_parts();
    assert_eq!(id_to_idx.len(), 2);
    assert_eq!(next_idx, 2);
}

// -----------------------------------------------------------------------
// PERF1 — corrupted legacy vectors payload is rejected (not silently
// skipped just because the payload is discarded)
// -----------------------------------------------------------------------

#[test]
fn test_load_sidecars_rejects_garbage_legacy_vectors_file() {
    let dir = TempDir::new().expect("test: temp dir");
    let path = dir.path();
    seed_consistent_gen4(path, &build_mappings());

    // Bytes that postcard cannot parse as either vectors format.
    std::fs::write(path.join("native_vectors.bin"), [0xFF_u8; 16])
        .expect("test: write garbage vectors");

    let meta = persistence::load_meta(path).expect("test: reload meta");
    let err = load_sidecars(path, &meta, GRAPH_COUNT)
        .expect_err("test: garbage legacy vectors must be rejected");
    assert_ne!(err.kind(), std::io::ErrorKind::NotFound);
}