Skip to main content

qualia_audio/models/loader/
weight_file.rs

1//! Minimal P64-style learned-head weight blob format + bounded parser (AU-LEARNED).
2//!
3//! This is the on-disk container every learned audio head loads from. It is deliberately tiny
4//! and self-describing: a magic tag, a format version, a small `dims` shape vector, and a flat
5//! `f32` payload. Real weights are gated on the principal (HA1 corpus / HA6 model); the format
6//! here lets us (a) round-trip a synthetic/test blob and (b) fail closed when a blob is absent
7//! or malformed. Parsing is **cold** (a `Vec` is allowed); inference over the parsed blob is the
8//! hot, caller-buffered path and lives in the head modules.
9//!
10//! Wire layout (all little-endian):
11//! ```text
12//!   magic   : u32   = "QP64"
13//!   version : u32
14//!   ndims   : u32   (<= MAX_DIMS)
15//!   dims    : [u32; ndims]
16//!   ndata   : u32   (<= MAX_DATA)
17//!   data    : [f32; ndata]
18//! ```
19//! The parser requires the byte slice to end exactly after `data` — trailing bytes are rejected,
20//! so a truncated or padded blob cannot be silently accepted.
21
22use crate::types::AudioError;
23
24/// Blob magic: `QP64` little-endian.
25pub const WEIGHT_MAGIC: u32 = u32::from_le_bytes([b'Q', b'P', b'6', b'4']);
26/// Current blob format version.
27pub const WEIGHT_VERSION: u32 = 1;
28/// Upper bound on `dims` length (bounds parsing; a shape vector is always tiny).
29pub const MAX_DIMS: usize = 8;
30/// Upper bound on `data` length in `f32` elements (~4M floats = 16 MiB; bounds parsing).
31pub const MAX_DATA: usize = 1 << 22;
32
33/// A parsed learned-head weight blob. Cold-path owned (`Vec`); heads borrow it during inference.
34#[derive(Debug, Clone, PartialEq)]
35pub struct WeightBlob {
36    pub magic: u32,
37    pub version: u32,
38    /// Logical tensor shape(s) — interpretation is head-specific (e.g. `[classes, features]`).
39    pub dims: Vec<u32>,
40    /// Flat weight payload (row-major per head convention).
41    pub data: Vec<f32>,
42}
43
44impl WeightBlob {
45    /// Product of `dims` (saturating). Heads use this to validate `data` length against shape.
46    pub fn dim_product(&self) -> usize {
47        self.dims
48            .iter()
49            .fold(1usize, |acc, &d| acc.saturating_mul(d as usize))
50    }
51}
52
53#[inline]
54fn read_u32(bytes: &[u8], off: usize) -> Result<u32, AudioError> {
55    let end = off.checked_add(4).ok_or(AudioError::MalformedAudio)?;
56    let slice = bytes.get(off..end).ok_or(AudioError::MalformedAudio)?;
57    Ok(u32::from_le_bytes([slice[0], slice[1], slice[2], slice[3]]))
58}
59
60/// Parse a weight blob from bytes. Bounded and strict: unknown magic → `BackendUnavailable`
61/// (treated as "no usable weights" so the head fails closed); any structural problem
62/// (short read, oversized counts, trailing bytes) → `MalformedAudio`. Never partially accepts.
63pub fn parse_weight_blob(bytes: &[u8]) -> Result<WeightBlob, AudioError> {
64    let magic = read_u32(bytes, 0)?;
65    if magic != WEIGHT_MAGIC {
66        return Err(AudioError::BackendUnavailable);
67    }
68    let version = read_u32(bytes, 4)?;
69    if version != WEIGHT_VERSION {
70        return Err(AudioError::BackendUnavailable);
71    }
72
73    let ndims = read_u32(bytes, 8)? as usize;
74    if ndims > MAX_DIMS {
75        return Err(AudioError::MalformedAudio);
76    }
77    let mut dims = Vec::with_capacity(ndims);
78    let mut off = 12;
79    for _ in 0..ndims {
80        dims.push(read_u32(bytes, off)?);
81        off += 4;
82    }
83
84    let ndata = read_u32(bytes, off)? as usize;
85    off += 4;
86    if ndata > MAX_DATA {
87        return Err(AudioError::MalformedAudio);
88    }
89    let data_bytes = ndata.checked_mul(4).ok_or(AudioError::MalformedAudio)?;
90    let data_end = off
91        .checked_add(data_bytes)
92        .ok_or(AudioError::MalformedAudio)?;
93    // Strict: the blob must end exactly after `data` (no truncation, no trailing padding).
94    if data_end != bytes.len() {
95        return Err(AudioError::MalformedAudio);
96    }
97    let mut data = Vec::with_capacity(ndata);
98    let mut d = off;
99    for _ in 0..ndata {
100        let w = f32::from_le_bytes([bytes[d], bytes[d + 1], bytes[d + 2], bytes[d + 3]]);
101        data.push(w);
102        d += 4;
103    }
104
105    Ok(WeightBlob {
106        magic,
107        version,
108        dims,
109        data,
110    })
111}
112
113/// Serialize a weight blob (cold path — tests and fixture generation). Inverse of
114/// [`parse_weight_blob`].
115pub fn write_weight_blob(blob: &WeightBlob) -> Vec<u8> {
116    let mut v = Vec::with_capacity(16 + blob.dims.len() * 4 + blob.data.len() * 4);
117    v.extend_from_slice(&blob.magic.to_le_bytes());
118    v.extend_from_slice(&blob.version.to_le_bytes());
119    v.extend_from_slice(&(blob.dims.len() as u32).to_le_bytes());
120    for &d in &blob.dims {
121        v.extend_from_slice(&d.to_le_bytes());
122    }
123    v.extend_from_slice(&(blob.data.len() as u32).to_le_bytes());
124    for &f in &blob.data {
125        v.extend_from_slice(&f.to_le_bytes());
126    }
127    v
128}
129
130/// Convenience: build a well-formed blob with the current magic/version.
131pub fn make_blob(dims: Vec<u32>, data: Vec<f32>) -> WeightBlob {
132    WeightBlob {
133        magic: WEIGHT_MAGIC,
134        version: WEIGHT_VERSION,
135        dims,
136        data,
137    }
138}
139
140#[cfg(test)]
141mod tests {
142    use super::*;
143
144    #[test]
145    fn round_trips() {
146        let blob = make_blob(vec![2, 3], vec![0.1, -0.2, 0.3, 0.4, -0.5, 0.6]);
147        let bytes = write_weight_blob(&blob);
148        let back = parse_weight_blob(&bytes).expect("parse");
149        assert_eq!(back, blob);
150        assert_eq!(back.dim_product(), 6);
151    }
152
153    #[test]
154    fn empty_data_ok() {
155        let blob = make_blob(vec![], vec![]);
156        let bytes = write_weight_blob(&blob);
157        let back = parse_weight_blob(&bytes).expect("parse");
158        assert_eq!(back, blob);
159        assert_eq!(back.dim_product(), 1);
160    }
161
162    #[test]
163    fn bad_magic_is_backend_unavailable() {
164        let mut bytes = write_weight_blob(&make_blob(vec![1], vec![1.0]));
165        bytes[0] ^= 0xFF;
166        assert_eq!(
167            parse_weight_blob(&bytes),
168            Err(AudioError::BackendUnavailable)
169        );
170    }
171
172    #[test]
173    fn wrong_version_is_backend_unavailable() {
174        let mut blob = make_blob(vec![1], vec![1.0]);
175        blob.version = 999;
176        let bytes = write_weight_blob(&blob);
177        assert_eq!(
178            parse_weight_blob(&bytes),
179            Err(AudioError::BackendUnavailable)
180        );
181    }
182
183    #[test]
184    fn truncated_is_malformed() {
185        let bytes = write_weight_blob(&make_blob(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]));
186        let short = &bytes[..bytes.len() - 3];
187        assert_eq!(parse_weight_blob(short), Err(AudioError::MalformedAudio));
188    }
189
190    #[test]
191    fn trailing_bytes_rejected() {
192        let mut bytes = write_weight_blob(&make_blob(vec![1], vec![1.0]));
193        bytes.push(0);
194        assert_eq!(parse_weight_blob(&bytes), Err(AudioError::MalformedAudio));
195    }
196
197    #[test]
198    fn oversized_ndims_rejected() {
199        // magic, version, ndims = huge
200        let mut bytes = Vec::new();
201        bytes.extend_from_slice(&WEIGHT_MAGIC.to_le_bytes());
202        bytes.extend_from_slice(&WEIGHT_VERSION.to_le_bytes());
203        bytes.extend_from_slice(&(MAX_DIMS as u32 + 1).to_le_bytes());
204        assert_eq!(parse_weight_blob(&bytes), Err(AudioError::MalformedAudio));
205    }
206
207    #[test]
208    fn empty_input_malformed() {
209        assert_eq!(parse_weight_blob(&[]), Err(AudioError::MalformedAudio));
210    }
211}