Module nav 

2k: the vector navigation tier (FACT-02’s graph stage).

A newcomer’s map. The scan tier reads EVERY fingerprint per query – honest but linear. This tier gives each vector a handful of links to its most-similar vectors, forming a small-world web (the Vamana family, as in DiskANN); a query then WALKS: start at a central vector (the medoid), repeatedly move toward whichever known neighbour looks closest to the query, keep the best ef candidates, stop when no frontier candidate can beat the worst kept result. Hops ~ logarithmic; a million vectors answer in a few hundred row reads instead of a million.

Everything is ordinary rows (D4): (0x11, field, id) -> [norm][code] [links]. One web per FIELD – links are bare ids, so a shared keyspace would wire a 384-dim column’s vectors into an 8-dim column’s neighbourhoods and both walks would read the other’s rows as garbage. The 2-bit fingerprint rides IN the nav row, so one read per visited node yields both topology and ranking data. The exact tier (rescore) still ranks the survivors: approximation can miss, never misrank.

Freshness without an LSM: the fold records a WATERMARK as a fast path for the ordinary increasing-id tail. Vectors written at-or-below it get an explicit pending marker in the catalog. Queries merge both pending sets with the walk, and folds consume both, so arbitrary caller ids remain visible without an O(N) sweep. Deletes leave dangling links that walks skip (missing row = dead), healed at fold.

Constants

NAV_ALPHA

Pruning slack: a candidate is dropped if some kept neighbour is more than ALPHA closer to it than the candidate is to the node (Vamana’s robust prune – keeps links spread out instead of clustered). Applied as ALPHA^2 because we compare SQUARED L2 – alpha on squared distances is sqrt(alpha) on true ones, which quietly weakened the spread rule to 1.095 (recall 0.535 measured before the fix).

NAV_FOLD_CHECKPOINT_EVERY

The fold commits AND checkpoints every this-many inserts. A fold that commits once holds every neighbour-row rewrite of the whole batch in the WAL (~33 row images per insert: 15GB measured at 1M) – the WAL only truncates at a checkpoint, so the bound must checkpoint. Crash mid-fold is already safe at ANY boundary: the watermark rides each insert, so a reopened store simply resumes the fold above it.

NAV_L_BUILD

Build-time beam width (bigger = better graph, slower fold).

NAV_R

Max neighbours kept per node. DiskANN’s sweet spot region; the row stays ~0.8KB at 2-bit/2048-pad codes.

NAV_R_SLACK

Backlink lists may grow to this before being pruned back to NAV_R. Pruning on EVERY overflow re-read ~33 full vectors per neighbour per insert; letting lists run to 2R amortises that ~32x (Vamana batch builds do the same). The row decoder already accepts n <= 2R.