[Th-Shivam]

Summary

Fixes #824.

Index::add_documents() previously resized and mutated the index files before all embeddings in a batch had been normalized successfully. If a later embedding was a zero vector, the call failed after partially committing earlier documents. Subsequent insertions could then return incorrect content/vectors, and the successful later insertion could disappear after reopening.

This change stages FP16 conversion and normalization for the complete batch before resizing or mutating persistent index state.

Changes

• Normalize all batch embeddings before file mutation.
• Reuse staged normalized embeddings during the write phase.
• Add regressions for:
  • valid embedding followed by zero vector
  • zero vector followed by valid embedding
  • unchanged files after rejection
  • rejected IDs remaining absent
  • subsequent insertion correctness
  • persistence across close/reopen

Validation

• Existing index tests: 8/8 passed before the change.
• Regression tests failed on the old implementation.
• Full index suite after the fix: 10/10 passed.
• GCC and Clang targeted builds passed.
• ASan/UBSan targeted regression run passed.
• Reproduction now keeps index.bin and data.bin unchanged after rejection.
• A later valid insertion returns its own content/vector before and after reopening.

The full ARM64 CMake/inference build was not available in the x86-64 validation environment.

Files changed

• cactus-engine/src/index.cpp
• cactus-engine/tests/test_index.cpp

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Th-Shivam]

@HenryNdubuaku @ncylich @jakmro

Whenever you have some time, could you please review this PR?

This PR fixes #824 by staging FP16 conversion and embedding normalization before mutating the mmap-backed index files. It also adds regression coverage for both batch orderings, rejected IDs, file integrity, subsequent insertions, vector correctness, and persistence after reopening.

If any changes are required, please let me know and I will update the PR accordingly. Thank you!