Skip to content

Harden vec index: zero-vector guard, index-format version stamp, doctor/stats vec observability #226

Description

@edheltzel

Deferred hardening from the #217 review cycle (reviewer report findings 225-2, 225-7, 224-3-residual; see .agents/atlas/artifacts/2026-07-13-pr224-225-reviewer-report.md in local artifacts).

  1. Zero-vector guard (225-2): vec_normalize(zero) yields NaN → distance NULL sorts first → phantom top-1 hit with similarity 1.0. Pre-existing behavior (old cosine path identical), low reachability (requires a corrupt backfill row), but cheap to kill: skip zero-norm rows in reindexVec's SELECT and drop NULL/non-finite distances in knnSearch, plus one test.
  2. Index-format version stamp (225-7): the self-heal detects stale indexes by DDL substring (distance_metric=cosine). A stale pre-perf(search): indexed hybrid meets 100k SLO — normalized-L2 vec index + 2GB mmap #225 binary sharing RECALL_DB_PATH could refill the metric-less table with raw un-normalized blobs — counts match, ordering silently non-cosine. Stamp an index-format version (vec_meta table or user_version) and rebuild on mismatch instead of DDL sniffing.
  3. Doctor/stats vec observability: recall doctor has no vec checks — extension loaded, index row count vs embeddings count, index format version. A silently-degraded vec tier is currently invisible outside stderr logs (added in perf(search): indexed hybrid meets 100k SLO — normalized-L2 vec index + 2GB mmap #225).

Refs #217, #146.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions