feat(binary): Add native binary vector storage with BinaryFlatIndex

[jsonMartin]

Summary

This PR implements RFC-004: Flat Index for Binary Vectors, adding native binary vector support to EdgeVec with a specialized BinaryFlatIndex optimized for semantic caching and insert-heavy workloads.

Key Features

• Native binary storage: StorageType::Binary(u32) - 32x memory reduction vs f32
• BinaryFlatIndex: O(1) insert, O(n) search with SIMD-accelerated Hamming distance
• WASM integration: Full JavaScript/TypeScript API with IndexType.binary(dimensions)
• Automatic quantization: f32 vectors auto-converted to binary via sign-bit quantization

Performance Characteristics

Operation	Complexity	Time (10K vectors)
Insert	O(1)	~1 μs
Search	O(n)	~1ms (SIMD)

Use Cases

• Semantic caching (insert-heavy, exact recall required)
• Datasets < 100K vectors
• When insert latency is critical (~1μs vs ~2ms for HNSW)

Files Changed

• src/flat/mod.rs - New BinaryFlatIndex implementation
• src/storage/mod.rs - Added StorageType::Binary(u32) variant
• src/wasm/mod.rs - WASM bindings for binary index creation and search
• src/error.rs - Added BinaryFlatIndexError to unified error hierarchy
• docs/rfcs/RFC_FLAT_INDEX.md - Design document

Relationship to FlatIndex (Week 40)

This PR complements the f32 FlatIndex added in Week 40 (upstream). The two serve different purposes:

Feature	BinaryFlatIndex (this PR)	FlatIndex (Week 40)
Storage	Native binary (u8)	f32 with optional BQ
Use case	Semantic caching	General flat search
Memory	32x reduction	4x with BQ

Both coexist via the IndexType enum.

Test plan

• All 1019 library tests pass
• cargo fmt --check passes
• cargo clippy -- -D warnings passes
• Hostile review completed - all findings addressed
• Integration tests for binary vector operations
• WASM tests for JS interop

[matte1782]

🎖️ HOSTILE_REVIEWER Verdict: APPROVED ✅

Hey @jsonMartin! Excellent work on this PR. The \ implementation is solid, well-tested, and follows EdgeVec standards.

---

✅ CI Failures: NOT Your Fault

The two failing checks () are not actual regressions. All benchmarks passed:

Benchmark	Result	vs Baseline
insert_1k	293ms	✅ 18% faster
search_10k	0.20ms	✅ 20% faster
quantization_encode	1.47μs	✅ 23% faster
hamming_distance	4.09ns	✅ 18% faster

The failure is a GitHub Actions permissions issue (HTTP 403) - the workflow can't post comments on PRs from forks because it lacks \ permission. We'll fix this on our end.

You don't need to do anything about this.

---

✅ Code Quality: Excellent

Aspect	Status	Notes
Error handling	✅	\ with thiserror
Memory safety	✅	Proper panic boundaries documented
Test coverage	✅	Comprehensive unit + integration tests
Performance	✅	O(1) insert, O(n) search as designed
WASM bindings	✅	Proper dimension validation
RFC documentation	✅	Accurately reflects implementation

---

💡 Optional Improvements (Non-Blocking)

These are suggestions for follow-up PRs, not required for this merge:

1. TypeScript return types: \ returns \ - could be typed as 2. Add to .d.ts: \ and \ methods for better IDE support

---

🏆 Summary

This is a high-quality contribution that adds valuable functionality to EdgeVec:

• 32x memory reduction with native binary storage
• ~1μs insert latency (vs ~2ms for HNSW)
• Clean API design with proper error handling

Ready to merge once CI permissions are fixed on our end. 🚀

Thanks for the excellent work!

---

Reviewed by: HOSTILE_REVIEWER protocol
Date: 2026-02-02
Verdict: APPROVED

[jsonMartin]

Thanks @matte1782! Finally got this shipped — January was unexpectedly a bit of a whirlwind 🤪

Hope your New Year’s off to a good start!