Interface VectorCodec

nodedb-codec/src/vector_quant/codec.rs:101–150

The dual-phase quantization codec trait. `Quantized` is the on-disk / in-memory packed form (one per vector). `Query` is the prepared query — may be raw FP32, may be rotated, may hold a precomputed ADC LUT, depending on the codec. # Extensibility audit — future algorithms The following six algorithms can each be added as a new `impl VectorCodec` without changing the trait surface: TurboQuant**

/// `packed_bits` (the codec controls that region's layout entirely). No trait
/// change needed.
pub trait VectorCodec: Send + Sync {
    /// The packed quantized form. Must be convertible to a `UnifiedQuantizedVector`
    /// reference via `AsRef`.
    type Quantized: AsRef<UnifiedQuantizedVector>;

    /// The prepared query form (codec-specific).
    type Query;

    /// Encode a single FP32 vector into the codec's packed form.
    fn encode(&self, v: &[f32]) -> Self::Quantized;

    /// Prepare a query for distance computations against this codec.
    /// May rotate, normalize, build a LUT, etc.
    fn prepare_query(&self, q: &[f32]) -> Self::Query;

    /// Optional: precompute ADC lookup table for codecs that use one
    /// (PQ, IVF-PQ, TurboQuant). Returns `None` for codecs that don't
    /// (RaBitQ, BBQ, ternary, binary).
    fn adc_lut(&self, _q: &Self::Query) -> Option<AdcLut> {
        None
    }

    /// Optional: fit the codec's learned parameters on a set of training vectors.
    ///
    /// Called once before encoding begins, typically at index-build time. Codecs
    /// with no learnable parameters (binary sign-bit, ternary) can use the
    /// default no-op. Codecs with an SVD- or k-means-based fitting phase
    /// (ITQ3_S, OPQ, PQ, TurboQuant) override this to update their internal
    /// rotation matrices or codebooks.
    ///
    /// Returns `Ok(())` on success. The error type is `CodecError` so callers
    /// that drive training through a generic bound can propagate failures without
    /// knowing the concrete codec.
    ///
    /// The default implementation is a no-op and always returns `Ok(())`.
    #[allow(unused_variables)]
    fn train(&mut self, samples: &[&[f32]]) -> Result<(), crate::error::CodecError> {
        Ok(())
    }

    /// Fast symmetric distance — bitwise / heuristic. Used during HNSW
    /// upper-layer routing. Both arguments are quantized; no scalar
    /// correction; no outlier resolution. Hot path; must be inline-friendly.
    fn fast_symmetric_distance(&self, q: &Self::Quantized, v: &Self::Quantized) -> f32;

    /// Exact asymmetric distance — full ADC with scalar correction and
    /// sparse outlier resolution. Used at base-layer rerank only. Slower
    /// but high-fidelity.
    fn exact_asymmetric_distance(&self, q: &Self::Query, v: &Self::Quantized) -> f32;
}

#[cfg(test)]
mod tests {