Method new

nodedb-codec/src/vector_quant/layout.rs:158–211

Construct from an explicit header, packed-bit slice, and sparse outlier list. `outliers` is a slice of `(dim_index, value)` pairs. The `outlier_bitmask` in `header` must have exactly one bit set for each entry in `outliers`, and bits must correspond to entries in ascending `dim_index` order (i.e. popcnt-dense order). # Errors Returns [`CodecError::LayoutError`] if: - `outliers.len()` does not

(
        header: QuantHeader,
        packed_bits: &[u8],
        outliers: &[(u32, f32)],
    )

    /// - `outliers.len()` does not match `popcnt(header.outlier_bitmask)`.
    /// - Any `dim_index` in `outliers` is ≥ 64 (bitmask only covers 64 dims).
    pub fn new(
        header: QuantHeader,
        packed_bits: &[u8],
        outliers: &[(u32, f32)],
    ) -> Result<Self, CodecError> {
        let expected_outlier_count = header.outlier_bitmask.count_ones() as usize;
        if outliers.len() != expected_outlier_count {
            return Err(CodecError::LayoutError {
                detail: format!(
                    "outlier count mismatch: bitmask has {} bits set but {} outliers provided",
                    expected_outlier_count,
                    outliers.len()
                ),
            });
        }
        for &(dim_idx, _) in outliers {
            if dim_idx >= 64 {
                return Err(CodecError::LayoutError {
                    detail: format!("outlier dim_index {dim_idx} exceeds bitmask capacity of 64"),
                });
            }
        }

        let header_bytes = core::mem::size_of::<QuantHeader>();
        let outlier_bytes = outliers.len() * OUTLIER_ENTRY_BYTES;
        let raw = header_bytes + packed_bits.len() + outlier_bytes;
        let total = round_up_128(raw);

        let mut buf = vec![0u8; total];

        // Write header via raw copy (QuantHeader is repr(C), no padding issues).
        let header_src = unsafe {
            core::slice::from_raw_parts(&header as *const QuantHeader as *const u8, header_bytes)
        };
        buf[..header_bytes].copy_from_slice(header_src);

        // Write packed bits.
        let pb_start = header_bytes;
        let pb_end = pb_start + packed_bits.len();
        buf[pb_start..pb_end].copy_from_slice(packed_bits);

        // Write outlier payload: each entry is u32 dim_index || f32 value (LE).
        let mut off = pb_end;
        for &(dim_idx, value) in outliers {
            buf[off..off + 4].copy_from_slice(&dim_idx.to_le_bytes());
            buf[off + 4..off + 8].copy_from_slice(&value.to_le_bytes());
            off += OUTLIER_ENTRY_BYTES;
        }

        Ok(Self {
            buf,
            packed_bits_len: packed_bits.len(),
        })
    }

    // ── Accessors ────────────────────────────────────────────────────────────