Expand description
Single-file persistence format.
Layout (little-endian):
[magic "VECQ" u32][version u16][reserved u16]
[dim u32][seed u64][count u32]
[scales: count entries]
[codes: count * (padded/2) bytes]Version 1: scales stored as f32 (4 bytes each).
Version 1.1 (stored as 257): scales stored as f16 (2 bytes each).
Version 1.2 (stored as 258): the reserved u16 field carries the index’s
working_dim (Matryoshka truncation; 0 means working_dim == dim). Codes
and scales are laid out exactly like 1.1 — only the semantic of the
reserved field changes.
Version 1.3 (stored as 259): after the codes block, a keyed-slot table
restores the keyed API across reloads:
[keyed_entries u32][entries: slot u32 + key u64 each, slots in order]Version 1.4 (stored as 260): a residual-mode index (second-pass codes,
issue #23). After the codes block, two extra blocks appear — f16 residual
scales (count entries) and residual codes (count * padded/2 bytes) —
before the keyed-slot table.
Readers accept v1 through v1.5; writers emit 1.3 (plain 4-bit), 1.4 (residual), or 1.5 (plain 5/6-bit, issue #39). The seed is stored in the header so the random sign diagonal can be regenerated identically on any platform: identical file -> identical query results, bit for bit.