Struct Embedding 

pub struct Embedding {
    pub id: Uuid,
    pub chunk_id: Uuid,
    pub vector: Vec<i16>,
    pub model_hash: [u8; 32],
    pub dim: u16,
    pub l2_norm: f32,
    pub embedding_version: u32,
}

An embedding vector derived from a chunk

Stores the vector in i16 format (quantized) for determinism and storage efficiency. The embedding ID is derived deterministically via BLAKE3-16 from chunk_id + model_hash.

Fields

id: Uuid

Unique identifier for this embedding (BLAKE3-16 of chunk_id || model_hash)

chunk_id: Uuid

Parent chunk ID

vector: Vec<i16>

The embedding vector (i16 quantized, scale = 32767)

model_hash: [u8; 32]

Hash of the model weights used to generate this embedding

dim: u16

Dimensionality of the vector

l2_norm: f32

Precomputed L2 norm of the quantized vector (for similarity computation) Per CP-001: stored for efficient cosine similarity without recomputation

embedding_version: u32

Version of the embedding generation process (default 0)

Implementations

impl Embedding

pub fn new( chunk_id: Uuid, vector_f32: &[f32], model_hash: [u8; 32], embedding_version: u32, ) -> Self

Create a new embedding from an f32 vector.

Per CP-010 §3.4-3.5:

1. Normalize f32 vector to unit length
2. Quantize to i16 with round_ties_even (scale = 32767)

The embedding ID is deterministic: BLAKE3-16(chunk_id || model_hash || embedding_version).

pub fn from_quantized( chunk_id: Uuid, vector: Vec<i16>, model_hash: [u8; 32], embedding_version: u32, ) -> Self

Create an embedding directly from pre-quantized i16 values.

Used when loading from storage where quantization already occurred.

pub fn from_quantized_with_norm( chunk_id: Uuid, vector: Vec<i16>, model_hash: [u8; 32], l2_norm: f32, embedding_version: u32, ) -> Self

Create an embedding from pre-quantized values with a precomputed L2 norm.

Used when loading from storage where the norm was already stored.

pub fn to_f32(&self) -> Vec<f32>

Convert the quantized vector back to f32 (approximate).

pub fn integer_dot_product(&self, other: &[i16]) -> i64

Compute integer dot product between this embedding and another i16 vector.

Per CP-003 §4.5: all similarity computations use integer math. Returns i64 to avoid overflow (1536 dims * 32767^2 fits in i64).

pub fn norm_squared(&self) -> i64

Compute the squared L2 norm of the quantized vector (integer).

This avoids sqrt and floating-point entirely.

pub fn norm_f32(&self) -> f32

Compute L2 norm as f32 (for display/diagnostics only, not canonical).

pub fn cosine_similarity(&self, other: &Embedding) -> f32

Compute cosine similarity using integer math.

Returns f32 for convenience, but the dot product and norms are computed entirely in integer arithmetic first.

Trait Implementations

impl Clone for Embedding

fn clone(&self) -> Embedding

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Embedding

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Embedding

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Embedding

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Embedding

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Embedding