Skip to main content

Module vector_diskann

clawft_kernel

Module vector_diskann 

Source
Expand description

DiskANN-backed VectorBackend implementation.

When compiled with the diskann feature, this uses the real ruvector-diskann crate (Vamana graph + PQ + mmap persistence). Without it, a brute-force stub performs linear scans in memory.

§Feature/config mismatch (WEFT-656)

diskann is not part of clawft-kernel’s default feature set (see crates/clawft-kernel/Cargo.toml: diskann = ["ecc", "dep:ruvector-diskann"], not listed under default). If kernel_config.vector.backend selects DiskAnn or Hybrid but the binary was built without --features diskann, DiskAnnBackend silently falls back to the brute-force stub below: correctness is preserved (searches still return correct nearest neighbors), but recall quality and latency degrade from Vamana-graph ANN to an O(n) linear scan, with no visible signal by default.

Kernel::boot (boot.rs, BootPhase::Ecc) detects this mismatch at boot time by calling diskann_feature_status with cfg!(feature = "diskann"):

  • non-strict (default, vector.strict = false): boot emits a Warn-level crate::console::BootEvent naming the stub and how to fix it, then continues with the degraded stub.
  • strict (vector.strict = true): the same mismatch aborts boot with KernelError::Boot, so a misconfigured deployment fails loudly instead of silently running O(n) scans.

diskann_feature_status is a pure function (no I/O, no kernel/boot types) so the warn/fail decision is unit-testable without booting a kernel; see the feature_status_* tests below.

§Hardening features (Cognitum Seed WS1)

  • Epoch-based versioning: monotonic epoch bumped on every mutation.
  • Optimistic concurrency: insert_with_epoch rejects stale writes.
  • Soft-delete + compaction: tombstone records excluded from search.
  • Capacity limits: configurable max_vectors with StoreFull error.

Compiled only when the ecc feature is enabled.

Structs§

DiskAnnBackend
DiskANN vector backend.
DiskAnnConfig
DiskANN backend configuration.

Enums§

DiskAnnFeatureStatus
Outcome of reconciling a configured VectorBackendKind against whether the diskann cargo feature was actually compiled in.

Functions§

diskann_feature_status
Decide what should happen when configured_kind is booted in a build where feature_compiled tells whether the diskann cargo feature is present, honoring the vector.strict config knob.