Module storage 

Vamana on-disk layout description.

No I/O code lives here. This module describes the byte layout that a future io_uring integration (in nodedb-wal) will read and write. Offset arithmetic is provided so callers can compute SSD byte positions for full-precision vector fetches without materialising any buffers.

File layout

Offset  Size   Field
------  ----   -----
     0     8   magic = b"NDBVAMAN"
     8     4   version: u32
    12     4   dim: u32
    16     4   r: u32  (max degree)
    20     4   alpha: f32
    24     8   num_nodes: u64
    32     8   entry: u64  (entry-point node index)
    40     8   adjacency_offset: u64  (byte offset to adjacency block)
    48     8   vectors_offset: u64    (byte offset to vectors block)
    56    …    reserved / padding to 64-byte header boundary

--- adjacency block (mmap-resident, hot path) ---
    [u32 × r × num_nodes]  neighbors, zero-padded when degree < r

--- vectors block (SSD-resident, io_uring fetch on demand) ---
    [f32 × dim × num_nodes]  full-precision FP32 vectors

The adjacency block fits in RAM alongside the compressed codec vectors. The vectors block is fetched on demand via io_uring at a fixed, computable offset (see vector_offset).

Structs

VamanaStorageLayout

Vamana on-disk layout descriptor.

Constants

HEADER_BYTES

Size of the fixed file header in bytes.

VAMANA_MAGIC

Magic bytes identifying a NodeDB Vamana index file.

VAMANA_VERSION

Current on-disk format version.

Functions

vector_offset

Return the byte offset of the full-precision vector for node idx.