Module vecpool 

The vector index: flat quantized-vector storage with a two-phase flat search.

Vectors are the fourth recall source. Storage is deliberately not an arena or a blob heap but one contiguous Vec<u8> of fixed-stride slots: flat search reads every live slot, so perfect locality matters more than sorted lookup. Slots are append-only; dead ones are dropped by maintain, never reused in place.

One slot, all little-endian, stride = 8 + 8·words + dim bytes where words = ceil(dim / 64):

off	size	field
0	4	fact — owning FactId
4	4	scale — f32 quantization scale
8	8·words	sig — sign signature, bit i set iff q[i] >= 0
8+8·words	dim	q — the i8 components

Quantization is symmetric i8 over the L2-normalized vector (scale = max|x/‖x‖| / 127, q = round((x/‖x‖) / scale)), so a quantized cosine is scale_a · scale_b · Σ qa·qb. It is a pure function of the input — journal replay re-quantizes and reproduces every slot byte for byte.

Search is two-phase: the sign signatures give a cheap Hamming prefilter (popcount over u64 words, SIMD-friendly), then only the best max(4·k, 64) candidates pay an exact quantized-cosine rescore. The counters feature counts those exact dot products — the deterministic cost metric the perf gate holds to min(candidates, live).

Structs

VecPool

Flat store of quantized vectors.

VecScratch

Reusable vector-search scratch, owned by the engine (the zero-alloc recall invariant: after warm-up a search allocates nothing).