Skip to main content

tufazip_prior/
archive.rs

1use std::collections::{BTreeMap, BTreeSet};
2use std::fs::File;
3use std::io::{BufReader, BufWriter, Read, Write};
4use std::path::Path;
5
6use half::f16;
7use serde::{Deserialize, Serialize};
8use sha2::{Digest, Sha256};
9
10use crate::error::PriorError;
11
12/// Version of the `QPI1`/`QPR1`/`LRA1`/`QLA1` binary archive format.
13pub const ARCHIVE_VERSION: u32 = 1;
14
15/// Four-byte archive magic identifier.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
17pub enum ArchiveMagic {
18    /// Quantized prior initialization archive (`QPI1`).
19    Qpi1,
20    /// Quantized prior runtime archive (`QPR1`).
21    Qpr1,
22    /// Low-rank adapter archive (`LRA1`).
23    Lra1,
24    /// Quantized low-rank adapter archive (`QLA1`).
25    Qla1,
26}
27
28impl ArchiveMagic {
29    /// Parses a 4-byte magic prefix.
30    ///
31    /// # Errors
32    ///
33    /// Returns [`PriorError::UnknownMagic`] if `bytes` is not recognized.
34    pub fn from_bytes(bytes: [u8; 4]) -> Result<Self, PriorError> {
35        match &bytes {
36            b"QPI1" => Ok(Self::Qpi1),
37            b"QPR1" => Ok(Self::Qpr1),
38            b"LRA1" => Ok(Self::Lra1),
39            b"QLA1" => Ok(Self::Qla1),
40            _ => Err(PriorError::UnknownMagic(bytes)),
41        }
42    }
43
44    /// Returns the 4-byte ASCII representation of this magic header.
45    #[must_use]
46    pub const fn as_bytes(self) -> &'static [u8; 4] {
47        match self {
48            Self::Qpi1 => b"QPI1",
49            Self::Qpr1 => b"QPR1",
50            Self::Lra1 => b"LRA1",
51            Self::Qla1 => b"QLA1",
52        }
53    }
54
55    /// Returns the ASCII string representation (e.g. `"QPI1"`).
56    #[must_use]
57    pub const fn as_str(self) -> &'static str {
58        match self {
59            Self::Qpi1 => "QPI1",
60            Self::Qpr1 => "QPR1",
61            Self::Lra1 => "LRA1",
62            Self::Qla1 => "QLA1",
63        }
64    }
65}
66
67/// Supported per-tensor quantization bit widths.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
69#[repr(u8)]
70pub enum BitWidth {
71    /// 1-bit binary sign quantization (`{-1, +1} * row_scale`).
72    B1 = 1,
73    /// 2-bit symmetric quantization (`code - 1`).
74    B2 = 2,
75    /// 4-bit symmetric quantization (`code - 7`).
76    B4 = 4,
77    /// 8-bit symmetric quantization (`code - 127`).
78    B8 = 8,
79    /// Unscaled IEEE 754 float16 storage.
80    B16 = 16,
81}
82
83impl BitWidth {
84    /// Converts a raw integer bit width to [`BitWidth`].
85    ///
86    /// # Errors
87    ///
88    /// Returns [`PriorError::UnsupportedBitWidth`] for unsupported values.
89    pub fn from_u8(name: &str, bits: u8) -> Result<Self, PriorError> {
90        match bits {
91            1 => Ok(Self::B1),
92            2 => Ok(Self::B2),
93            4 => Ok(Self::B4),
94            8 => Ok(Self::B8),
95            16 => Ok(Self::B16),
96            _ => Err(PriorError::UnsupportedBitWidth {
97                name: name.to_owned(),
98                bits,
99            }),
100        }
101    }
102
103    /// Returns the numeric bit width (`1`, `2`, `4`, `8`, or `16`).
104    #[must_use]
105    pub const fn bits(self) -> u8 {
106        self as u8
107    }
108}
109
110/// Prior initialization expansion strategy recorded in `QPI1` metadata.
111#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
112#[serde(rename_all = "kebab-case")]
113pub enum InitializationKind {
114    /// Evenly spaces source blocks into a deeper model, zeroing inserted residual outputs.
115    DepthGrowth,
116    /// Unties a recurrent loop schedule into distinct physical blocks.
117    LoopUntying,
118}
119
120/// Architectural geometry used to verify source/target compatibility for `QPI1` priors.
121#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
122pub struct TransformerGeometry {
123    /// Vocabulary token count.
124    pub vocab_size: usize,
125    /// Number of physical transformer blocks.
126    pub n_layer: usize,
127    /// Hidden state width.
128    pub d_model: usize,
129    /// Number of attention heads.
130    pub n_head: usize,
131    /// SwiGLU intermediate dimension.
132    pub d_inner: usize,
133    /// Maximum context window length.
134    pub ctx_len: usize,
135    /// Whether input and output embeddings share weights.
136    pub tie_embeddings: bool,
137    /// Attention positional mechanism (`"rope"` or `"learned_relative"`).
138    pub position_type: String,
139    /// Whether per-head QK RMSNorm is active.
140    pub qk_norm: bool,
141    /// Block normalization style (`"peri"` or `"post"`).
142    pub norm_style: String,
143}
144
145impl TransformerGeometry {
146    /// Compares all fields except `n_layer`, returning the first mismatched field name.
147    #[must_use]
148    pub fn mismatch_excluding_n_layer(&self, other: &Self) -> Option<&'static str> {
149        if self.vocab_size != other.vocab_size {
150            Some("vocab_size")
151        } else if self.d_model != other.d_model {
152            Some("d_model")
153        } else if self.n_head != other.n_head {
154            Some("n_head")
155        } else if self.d_inner != other.d_inner {
156            Some("d_inner")
157        } else if self.ctx_len != other.ctx_len {
158            Some("ctx_len")
159        } else if self.tie_embeddings != other.tie_embeddings {
160            Some("tie_embeddings")
161        } else if self.position_type != other.position_type {
162            Some("position_type")
163        } else if self.qk_norm != other.qk_norm {
164            Some("qk_norm")
165        } else if self.norm_style != other.norm_style {
166            Some("norm_style")
167        } else {
168            None
169        }
170    }
171}
172
173/// Initialization metadata stored inside `QPI1` archives.
174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175pub struct InitializationMeta {
176    /// Expansion strategy (`"depth-growth"` or `"loop-untying"`).
177    pub kind: InitializationKind,
178    /// Geometry of the source model weights stored in the archive.
179    pub source_geometry: TransformerGeometry,
180    /// Target model geometry the archive was calibrated for.
181    pub target_geometry: TransformerGeometry,
182    /// Canonical block mapping (for `depth-growth`).
183    #[serde(default, skip_serializing_if = "Option::is_none")]
184    pub block_mapping: Option<Vec<usize>>,
185    /// Recurrent loop block schedule (for `loop-untying`).
186    #[serde(default, skip_serializing_if = "Option::is_none")]
187    pub block_schedule: Option<Vec<usize>>,
188    /// Deterministic initialization seed pinned by the prior.
189    pub initialization_seed: u64,
190    /// SHA-256 hex digest of the vocabulary file pinned by the prior.
191    pub vocab_sha256: String,
192    /// Optional SHA-256 digest of the source training checkpoint.
193    #[serde(default, skip_serializing_if = "Option::is_none")]
194    pub source_checkpoint_sha256: Option<String>,
195}
196
197/// Metadata header for a single tensor stored in an archive.
198#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
199pub struct TensorEntryMeta {
200    /// Canonical parameter name.
201    pub name: String,
202    /// Tensor dimensions.
203    pub shape: Vec<usize>,
204    /// Quantization bit width (`1`, `2`, `4`, `8`, or `16`).
205    pub bits: u8,
206    /// Number of float16 row/tensor scales (`0` when `bits == 16`).
207    pub scale_count: usize,
208    /// Byte length of the serialized scale section (`scale_count * 2`).
209    pub scale_bytes: usize,
210    /// Scale storage dtype (typically `"float16"`).
211    #[serde(default, skip_serializing_if = "Option::is_none")]
212    pub scale_dtype: Option<String>,
213    /// Byte length of the packed quantized values.
214    pub value_bytes: usize,
215}
216
217/// Top-level JSON metadata header inside a tensor archive.
218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219pub struct ArchiveMetadata {
220    /// Archive format version (must be `1`).
221    pub version: u32,
222    /// Optional quantization policy label (e.g. `"uniform1"`).
223    #[serde(default, skip_serializing_if = "Option::is_none")]
224    pub policy: Option<String>,
225    /// Optional depth-growth or loop-untying initialization metadata.
226    #[serde(default, skip_serializing_if = "Option::is_none")]
227    pub initialization: Option<InitializationMeta>,
228    /// Ordered list of packed tensor payloads following the JSON header.
229    pub entries: Vec<TensorEntryMeta>,
230}
231
232/// Dequantized float32 tensor decoded from an archive.
233#[derive(Debug, Clone, PartialEq)]
234pub struct DequantizedTensor {
235    /// Tensor shape dimensions.
236    pub shape: Vec<usize>,
237    /// Row-major dequantized `f32` elements.
238    pub data: Vec<f32>,
239}
240
241/// Complete decoded quantized prior archive.
242#[derive(Debug, Clone, PartialEq)]
243pub struct PriorArchive {
244    /// Four-byte magic kind.
245    pub magic: ArchiveMagic,
246    /// Total file size on disk in bytes.
247    pub archive_bytes: u64,
248    /// SHA-256 hex digest of the raw archive file.
249    pub archive_sha256: String,
250    /// Parsed archive JSON metadata.
251    pub metadata: ArchiveMetadata,
252    /// Dequantized `f32` tensors keyed by parameter name.
253    pub tensors: BTreeMap<String, DequantizedTensor>,
254}
255
256/// Validated plan for applying a `QPI1` prior to a target `Transformer`.
257#[derive(Debug, Clone, PartialEq, Eq)]
258pub struct PriorPlan {
259    /// Size of the archive file in bytes.
260    pub archive_bytes: u64,
261    /// SHA-256 hex digest of the archive file.
262    pub archive_sha256: String,
263    /// SHA-256 hex digest of the pinned vocabulary file.
264    pub vocab_sha256: String,
265    /// Initialization strategy used by the prior.
266    pub initialization_kind: InitializationKind,
267    /// Number of physical blocks stored in the archive.
268    pub source_depth: usize,
269    /// Effective block mapping (`Vec<usize>`) recorded for diagnostics.
270    pub block_mapping: Vec<usize>,
271    /// Recurrent block schedule if `loop-untying`.
272    pub block_schedule: Option<Vec<usize>>,
273    /// Map from target block index to archive source block index.
274    pub target_sources: BTreeMap<usize, usize>,
275    /// Root (non-block) parameter names verified present in both prior and target.
276    pub root_names: Vec<String>,
277    /// Per-block suffix names (after `"blocks.{i}."`).
278    pub block_suffixes: Vec<String>,
279    /// Unmapped target block indices whose residual output projections must be zeroed (`depth-growth`).
280    pub zero_unmapped_targets: Vec<usize>,
281    /// Optional quantization policy name.
282    pub policy: Option<String>,
283}
284
285/// Computes the canonical byte size for packing `num_values` elements at `bits`.
286#[must_use]
287pub fn packed_byte_len(num_values: usize, bits: BitWidth) -> usize {
288    let b = usize::from(bits.bits());
289    if b == 16 {
290        num_values * 2
291    } else {
292        (num_values * b).div_ceil(8)
293    }
294}
295
296fn read_exact_or_truncated<R: Read>(
297    reader: &mut R,
298    buf: &mut [u8],
299    what: &str,
300) -> Result<(), PriorError> {
301    let mut read = 0usize;
302    while read < buf.len() {
303        match reader.read(&mut buf[read..]) {
304            Ok(0) => return Err(PriorError::Truncated(what.to_owned())),
305            Ok(n) => read += n,
306            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
307            Err(e) => return Err(e.into()),
308        }
309    }
310    Ok(())
311}
312
313fn decode_f16_le_slice(bytes: &[u8]) -> Vec<f32> {
314    bytes
315        .chunks_exact(2)
316        .map(|pair| f16::from_le_bytes([pair[0], pair[1]]).to_f32())
317        .collect()
318}
319
320fn unpack_and_dequantize(
321    value_payload: &[u8],
322    scales: &[f32],
323    count: usize,
324    bits: BitWidth,
325) -> Vec<f32> {
326    let bits_u8 = bits.bits();
327    let mut out = vec![0.0f32; count];
328    let scale_count = scales.len().max(1);
329    let row_stride = count / scale_count;
330
331    if bits == BitWidth::B8 {
332        for (idx, (&raw, dst)) in value_payload
333            .iter()
334            .take(count)
335            .zip(out.iter_mut())
336            .enumerate()
337        {
338            let signed = i32::from(raw) - 127;
339            let scale = scales[idx / row_stride];
340            *dst = (signed as f32) * scale;
341        }
342        return out;
343    }
344
345    let per_byte = 8usize / usize::from(bits_u8);
346    let mask = (1u8 << bits_u8) - 1;
347    let offset = if bits == BitWidth::B1 {
348        0i32
349    } else {
350        (1i32 << (bits_u8 - 1)) - 1
351    };
352
353    for (idx, dst) in out.iter_mut().enumerate() {
354        let byte = value_payload[idx / per_byte];
355        let shift = (idx % per_byte) * usize::from(bits_u8);
356        let code = (byte >> shift) & mask;
357        let signed = if bits == BitWidth::B1 {
358            i32::from(code) * 2 - 1
359        } else {
360            i32::from(code) - offset
361        };
362        *dst = (signed as f32) * scales[idx / row_stride];
363    }
364
365    out
366}
367
368/// Computes the lowercase hex SHA-256 digest of a file on disk.
369///
370/// # Errors
371///
372/// Returns [`PriorError::Io`] if opening or reading `path` fails.
373pub fn sha256_file(path: impl AsRef<Path>) -> Result<String, PriorError> {
374    let file = File::open(path)?;
375    let mut reader = BufReader::with_capacity(1024 * 1024, file);
376    let mut hasher = Sha256::new();
377    let mut buf = vec![0u8; 1024 * 1024];
378    loop {
379        let n = reader.read(&mut buf)?;
380        if n == 0 {
381            break;
382        }
383        hasher.update(&buf[..n]);
384    }
385    Ok(hex::encode(hasher.finalize()))
386}
387
388/// Reads and dequantizes a `QPI1`/`QPR1`/`LRA1`/`QLA1` archive into `f32` tensors.
389///
390/// # Errors
391///
392/// Returns [`PriorError`] if the file cannot be read, the magic/version/metadata is invalid,
393/// any payload is truncated, or trailing bytes remain.
394pub fn read_archive(path: impl AsRef<Path>) -> Result<PriorArchive, PriorError> {
395    let path = path.as_ref();
396    let archive_bytes = std::fs::metadata(path)?.len();
397    let archive_sha256 = sha256_file(path)?;
398
399    let file = File::open(path)?;
400    let mut reader = BufReader::with_capacity(1024 * 1024, file);
401
402    let mut magic_buf = [0u8; 4];
403    read_exact_or_truncated(&mut reader, &mut magic_buf, "archive magic")?;
404    let magic = ArchiveMagic::from_bytes(magic_buf)?;
405
406    let mut len_buf = [0u8; 8];
407    read_exact_or_truncated(&mut reader, &mut len_buf, "metadata length")?;
408    let metadata_len = u64::from_le_bytes(len_buf);
409    if metadata_len > 64 * 1024 * 1024 {
410        return Err(PriorError::InvalidMetadata(format!(
411            "metadata length {metadata_len} exceeds 64 MiB safety limit"
412        )));
413    }
414    let mut metadata_payload = vec![0u8; metadata_len as usize];
415    read_exact_or_truncated(&mut reader, &mut metadata_payload, "archive metadata")?;
416    let metadata: ArchiveMetadata = serde_json::from_slice(&metadata_payload)?;
417    if metadata.version != ARCHIVE_VERSION {
418        return Err(PriorError::UnsupportedVersion(metadata.version));
419    }
420
421    let mut tensors = BTreeMap::new();
422    for entry in &metadata.entries {
423        if entry.name.is_empty() {
424            return Err(PriorError::InvalidMetadata(
425                "archive tensor name must be a non-empty string".to_owned(),
426            ));
427        }
428        if tensors.contains_key(&entry.name) {
429            return Err(PriorError::DuplicateTensor(entry.name.clone()));
430        }
431        if entry.shape.is_empty() || entry.shape.contains(&0) {
432            return Err(PriorError::InvalidShape {
433                name: entry.name.clone(),
434                shape: entry.shape.clone(),
435            });
436        }
437        let count = entry.shape.iter().try_fold(1usize, |acc, &d| {
438            acc.checked_mul(d).ok_or_else(|| PriorError::InvalidShape {
439                name: entry.name.clone(),
440                shape: entry.shape.clone(),
441            })
442        })?;
443        let bits = BitWidth::from_u8(&entry.name, entry.bits)?;
444        let expected_value_bytes = packed_byte_len(count, bits);
445        if entry.value_bytes != expected_value_bytes {
446            return Err(PriorError::SizeMismatch {
447                name: entry.name.clone(),
448                detail: format!(
449                    "expected value_bytes={expected_value_bytes}, found {}",
450                    entry.value_bytes
451                ),
452            });
453        }
454
455        let expected_scale_count = if bits == BitWidth::B16 {
456            0
457        } else if entry.shape.len() >= 2 {
458            entry.shape[0]
459        } else {
460            1
461        };
462        if entry.scale_count != expected_scale_count {
463            return Err(PriorError::SizeMismatch {
464                name: entry.name.clone(),
465                detail: format!(
466                    "expected scale_count={expected_scale_count}, found {}",
467                    entry.scale_count
468                ),
469            });
470        }
471        if entry.scale_bytes != expected_scale_count * 2 {
472            return Err(PriorError::SizeMismatch {
473                name: entry.name.clone(),
474                detail: format!(
475                    "expected scale_bytes={}, found {}",
476                    expected_scale_count * 2,
477                    entry.scale_bytes
478                ),
479            });
480        }
481
482        let data = if bits == BitWidth::B16 {
483            let mut payload = vec![0u8; entry.value_bytes];
484            read_exact_or_truncated(&mut reader, &mut payload, &entry.name)?;
485            decode_f16_le_slice(&payload)
486        } else {
487            let mut scale_payload = vec![0u8; entry.scale_bytes];
488            read_exact_or_truncated(
489                &mut reader,
490                &mut scale_payload,
491                &format!("scales for {}", entry.name),
492            )?;
493            let scales = decode_f16_le_slice(&scale_payload);
494
495            let mut value_payload = vec![0u8; entry.value_bytes];
496            read_exact_or_truncated(
497                &mut reader,
498                &mut value_payload,
499                &format!("values for {}", entry.name),
500            )?;
501            unpack_and_dequantize(&value_payload, &scales, count, bits)
502        };
503
504        tensors.insert(
505            entry.name.clone(),
506            DequantizedTensor {
507                shape: entry.shape.clone(),
508                data,
509            },
510        );
511    }
512
513    let mut trailing = [0u8; 1];
514    if reader.read(&mut trailing)? != 0 {
515        return Err(PriorError::TrailingBytes);
516    }
517
518    Ok(PriorArchive {
519        magic,
520        archive_bytes,
521        archive_sha256,
522        metadata,
523        tensors,
524    })
525}
526
527/// Writes quantized tensors into a `QPI1`/`QPR1`/`LRA1`/`QLA1` binary archive.
528///
529/// Used primarily for testing and creating quantized prior checkpoints.
530///
531/// # Errors
532///
533/// Returns [`PriorError`] on invalid shapes/counts or I/O failures.
534pub fn write_archive(
535    path: impl AsRef<Path>,
536    magic: ArchiveMagic,
537    policy: Option<String>,
538    initialization: Option<InitializationMeta>,
539    tensors: &[(&str, &[usize], &[f32], BitWidth)],
540) -> Result<(), PriorError> {
541    let mut entries = Vec::with_capacity(tensors.len());
542    let mut payloads: Vec<(Vec<u8>, Vec<u8>)> = Vec::with_capacity(tensors.len());
543    let mut seen = BTreeSet::new();
544
545    for &(name, shape, data, bits) in tensors {
546        if name.is_empty() {
547            return Err(PriorError::InvalidMetadata(
548                "archive tensor name must be non-empty".to_owned(),
549            ));
550        }
551        if !seen.insert(name) {
552            return Err(PriorError::DuplicateTensor(name.to_owned()));
553        }
554        if shape.is_empty() || shape.contains(&0) {
555            return Err(PriorError::InvalidShape {
556                name: name.to_owned(),
557                shape: shape.to_vec(),
558            });
559        }
560        let count: usize = shape.iter().product();
561        if data.len() != count {
562            return Err(PriorError::SizeMismatch {
563                name: name.to_owned(),
564                detail: format!("data length {} != product of shape {count}", data.len()),
565            });
566        }
567        let value_bytes = packed_byte_len(count, bits);
568        let scale_count = if bits == BitWidth::B16 {
569            0
570        } else if shape.len() >= 2 {
571            shape[0]
572        } else {
573            1
574        };
575        let scale_bytes = scale_count * 2;
576        let scale_dtype = if bits == BitWidth::B16 {
577            None
578        } else {
579            Some("float16".to_owned())
580        };
581
582        entries.push(TensorEntryMeta {
583            name: name.to_owned(),
584            shape: shape.to_vec(),
585            bits: bits.bits(),
586            scale_count,
587            scale_bytes,
588            scale_dtype,
589            value_bytes,
590        });
591
592        if bits == BitWidth::B16 {
593            let mut val_bytes = Vec::with_capacity(value_bytes);
594            for &v in data {
595                val_bytes.extend_from_slice(&f16::from_f32(v).to_le_bytes());
596            }
597            payloads.push((Vec::new(), val_bytes));
598        } else {
599            let row_stride = count / scale_count;
600            let mut scale_buf = Vec::with_capacity(scale_bytes);
601            let mut scales_f32 = Vec::with_capacity(scale_count);
602            let max_code_mag: i32 = match bits {
603                BitWidth::B1 => 1,
604                BitWidth::B2 => 1,
605                BitWidth::B4 => 7,
606                BitWidth::B8 => 127,
607                BitWidth::B16 => unreachable!(),
608            };
609
610            for row in 0..scale_count {
611                let row_slice = &data[row * row_stride..(row + 1) * row_stride];
612                let max_abs = row_slice
613                    .iter()
614                    .copied()
615                    .map(f32::abs)
616                    .fold(0.0f32, f32::max);
617                let raw_scale = if max_abs == 0.0 {
618                    1.0f32
619                } else {
620                    max_abs / (max_code_mag as f32)
621                };
622                let scale_f16 = f16::from_f32(raw_scale);
623                scale_buf.extend_from_slice(&scale_f16.to_le_bytes());
624                scales_f32.push(scale_f16.to_f32());
625            }
626
627            let bits_u8 = bits.bits();
628            let per_byte = 8usize / usize::from(bits_u8);
629            let mut val_buf = vec![0u8; value_bytes];
630            for (idx, &v) in data.iter().enumerate() {
631                let scale = scales_f32[idx / row_stride];
632                let code: u8 = if bits == BitWidth::B1 {
633                    if v >= 0.0 {
634                        1
635                    } else {
636                        0
637                    }
638                } else {
639                    let q = if scale == 0.0 {
640                        0
641                    } else {
642                        (v / scale).round_ties_even() as i32
643                    };
644                    let clamped = q.clamp(-max_code_mag, max_code_mag);
645                    (clamped + max_code_mag) as u8
646                };
647                let byte_idx = idx / per_byte;
648                let shift = (idx % per_byte) * usize::from(bits_u8);
649                val_buf[byte_idx] |= code << shift;
650            }
651            payloads.push((scale_buf, val_buf));
652        }
653    }
654
655    let meta = ArchiveMetadata {
656        version: ARCHIVE_VERSION,
657        policy,
658        initialization,
659        entries,
660    };
661    let meta_json = serde_json::to_vec(&meta)?;
662
663    let file = File::create(path)?;
664    let mut writer = BufWriter::new(file);
665    writer.write_all(magic.as_bytes())?;
666    writer.write_all(&(meta_json.len() as u64).to_le_bytes())?;
667    writer.write_all(&meta_json)?;
668    for (scales, values) in payloads {
669        writer.write_all(&scales)?;
670        writer.write_all(&values)?;
671    }
672    writer.flush()?;
673    Ok(())
674}
675
676/// Computes the canonical even placement of `source_depth` blocks inside `target_depth`.
677///
678/// # Errors
679///
680/// Returns [`PriorError::Validation`] if `source_depth == 0` or `source_depth > target_depth`.
681pub fn depth_block_mapping(
682    source_depth: usize,
683    target_depth: usize,
684) -> Result<Vec<usize>, PriorError> {
685    if source_depth < 1 || source_depth > target_depth {
686        return Err(PriorError::Validation(format!(
687            "source_depth ({source_depth}) must be between 1 and target_depth ({target_depth})"
688        )));
689    }
690    Ok((0..source_depth)
691        .map(|i| i * target_depth / source_depth)
692        .collect())
693}
694
695/// Parses a comma-separated recurrent-depth block schedule string.
696///
697/// # Errors
698///
699/// Returns [`PriorError::Validation`] if the schedule is empty, contains non-integers,
700/// exceeds `n_layer`, or fails to use every physical block `0..n_layer`.
701pub fn parse_block_schedule(spec: &str, n_layer: usize) -> Result<Vec<usize>, PriorError> {
702    if spec.trim().is_empty() {
703        return Err(PriorError::Validation(
704            "block_schedule cannot be empty".to_owned(),
705        ));
706    }
707    let schedule: Vec<usize> = spec
708        .split(',')
709        .map(|part| {
710            part.trim().parse::<usize>().map_err(|_| {
711                PriorError::Validation(format!(
712                    "block_schedule must contain comma-separated non-negative integers, got {spec:?}"
713                ))
714            })
715        })
716        .collect::<Result<_, _>>()?;
717    validate_block_schedule(&schedule, n_layer)?;
718    Ok(schedule)
719}
720
721/// Validates that a block schedule covers every physical layer index `0..n_layer`.
722///
723/// # Errors
724///
725/// Returns [`PriorError::Validation`] if `schedule` is empty, out of range, or omits a block.
726pub fn validate_block_schedule(schedule: &[usize], n_layer: usize) -> Result<(), PriorError> {
727    if schedule.is_empty() {
728        return Err(PriorError::Validation(
729            "block_schedule cannot be empty".to_owned(),
730        ));
731    }
732    let mut seen = vec![false; n_layer];
733    for &idx in schedule {
734        if idx >= n_layer {
735            return Err(PriorError::Validation(format!(
736                "block_schedule index {idx} is outside n_layer ({n_layer})"
737            )));
738        }
739        seen[idx] = true;
740    }
741    if seen.iter().any(|&present| !present) {
742        return Err(PriorError::Validation(
743            "block_schedule must use every physical block".to_owned(),
744        ));
745    }
746    Ok(())
747}
748
749/// Validates a loaded `QPI1` prior archive against the target model geometry, vocabulary, and seed.
750///
751/// Mirrors `load_depth_prior` validation in `nn.py` without loading tensors into an ML backend.
752///
753/// # Errors
754///
755/// Returns [`PriorError`] if any magic, geometry, vocab SHA-256, seed, tensor set, or shape
756/// verification fails.
757pub fn plan_depth_prior(
758    archive: &PriorArchive,
759    vocab_path: impl AsRef<Path>,
760    expected_geometry: &TransformerGeometry,
761    seed: u64,
762    expected_target_shapes: &BTreeMap<String, Vec<usize>>,
763) -> Result<PriorPlan, PriorError> {
764    if archive.magic != ArchiveMagic::Qpi1 {
765        return Err(PriorError::Validation(
766            "initial prior requires a QPI1 archive".to_owned(),
767        ));
768    }
769    let init = archive.metadata.initialization.as_ref().ok_or_else(|| {
770        PriorError::Validation("QPI1 archive lacks initialization metadata".to_owned())
771    })?;
772    if &init.target_geometry != expected_geometry {
773        return Err(PriorError::Validation(
774            "prior target geometry differs from invocation geometry".to_owned(),
775        ));
776    }
777    if let Some(field) = init
778        .source_geometry
779        .mismatch_excluding_n_layer(expected_geometry)
780    {
781        return Err(PriorError::Validation(format!(
782            "prior source geometry differs at {field}"
783        )));
784    }
785    let source_depth = init.source_geometry.n_layer;
786    let target_depth = expected_geometry.n_layer;
787
788    let (block_mapping, block_schedule, target_sources) = match init.kind {
789        InitializationKind::DepthGrowth => {
790            let mapping = depth_block_mapping(source_depth, target_depth)?;
791            if init.block_mapping.as_deref() != Some(mapping.as_slice()) {
792                return Err(PriorError::Validation(
793                    "prior block mapping is not the canonical depth mapping".to_owned(),
794                ));
795            }
796            let target_sources = mapping
797                .iter()
798                .enumerate()
799                .map(|(source_idx, &target_idx)| (target_idx, source_idx))
800                .collect::<BTreeMap<_, _>>();
801            (mapping, None, target_sources)
802        }
803        InitializationKind::LoopUntying => {
804            let schedule = init.block_schedule.as_ref().ok_or_else(|| {
805                PriorError::Validation("loop prior lacks a block_schedule".to_owned())
806            })?;
807            validate_block_schedule(schedule, source_depth)?;
808            if schedule.len() != target_depth {
809                return Err(PriorError::Validation(format!(
810                    "loop prior schedule length ({}) differs from target depth ({target_depth})",
811                    schedule.len()
812                )));
813            }
814            let target_sources = schedule
815                .iter()
816                .enumerate()
817                .map(|(target_idx, &source_idx)| (target_idx, source_idx))
818                .collect::<BTreeMap<_, _>>();
819            (schedule.clone(), Some(schedule.clone()), target_sources)
820        }
821    };
822
823    if init.initialization_seed != seed {
824        return Err(PriorError::Validation(format!(
825            "prior initialization seed ({}) differs from configured seed ({seed})",
826            init.initialization_seed
827        )));
828    }
829    let vocab_sha256 = sha256_file(vocab_path)?;
830    if init.vocab_sha256 != vocab_sha256 {
831        return Err(PriorError::Validation(format!(
832            "prior vocabulary digest ({}) differs from vocab_file ({vocab_sha256})",
833            init.vocab_sha256
834        )));
835    }
836
837    let mut root_names = Vec::new();
838    let mut block_suffixes = Vec::new();
839    for name in expected_target_shapes.keys() {
840        if !name.starts_with("blocks.") {
841            root_names.push(name.clone());
842        } else if let Some(suffix) = name.strip_prefix("blocks.0.") {
843            block_suffixes.push(suffix.to_owned());
844        }
845    }
846
847    let mut expected_source_names = BTreeSet::new();
848    for name in &root_names {
849        expected_source_names.insert(name.clone());
850    }
851    for source_idx in 0..source_depth {
852        for suffix in &block_suffixes {
853            expected_source_names.insert(format!("blocks.{source_idx}.{suffix}"));
854        }
855    }
856
857    let actual_source_names: BTreeSet<String> = archive.tensors.keys().cloned().collect();
858    if actual_source_names != expected_source_names {
859        let missing: Vec<_> = expected_source_names
860            .difference(&actual_source_names)
861            .cloned()
862            .collect();
863        let extra: Vec<_> = actual_source_names
864            .difference(&expected_source_names)
865            .cloned()
866            .collect();
867        return Err(PriorError::Validation(format!(
868            "prior tensor set mismatch: missing={missing:?} extra={extra:?}"
869        )));
870    }
871
872    for name in &root_names {
873        let src = &archive.tensors[name];
874        let dst_shape = &expected_target_shapes[name];
875        if &src.shape != dst_shape {
876            return Err(PriorError::Validation(format!(
877                "prior tensor shape differs for {name}: {:?} vs {:?}",
878                src.shape, dst_shape
879            )));
880        }
881    }
882    for (&target_idx, &source_idx) in &target_sources {
883        for suffix in &block_suffixes {
884            let source_name = format!("blocks.{source_idx}.{suffix}");
885            let target_name = format!("blocks.{target_idx}.{suffix}");
886            let src = &archive.tensors[&source_name];
887            let dst_shape = &expected_target_shapes[&target_name];
888            if &src.shape != dst_shape {
889                return Err(PriorError::Validation(format!(
890                    "prior tensor shape differs for {source_name}: {:?} vs {:?}",
891                    src.shape, dst_shape
892                )));
893            }
894        }
895    }
896
897    let zero_unmapped_targets = if init.kind == InitializationKind::DepthGrowth {
898        (0..target_depth)
899            .filter(|idx| !target_sources.contains_key(idx))
900            .collect()
901    } else {
902        Vec::new()
903    };
904
905    Ok(PriorPlan {
906        archive_bytes: archive.archive_bytes,
907        archive_sha256: archive.archive_sha256.clone(),
908        vocab_sha256,
909        initialization_kind: init.kind,
910        source_depth,
911        block_mapping,
912        block_schedule,
913        target_sources,
914        root_names,
915        block_suffixes,
916        zero_unmapped_targets,
917        policy: archive.metadata.policy.clone(),
918    })
919}
920
921#[cfg(test)]
922mod tests {
923    use std::path::PathBuf;
924
925    use super::*;
926
927    #[test]
928    fn pack_unpack_roundtrip_all_bit_widths() {
929        let tmp = tempfile::NamedTempFile::new().unwrap();
930        let vec_1d: Vec<f32> = vec![-2.0, -0.5, 0.0, 0.75, 2.0, 1.25];
931        let mat_2d_b1: Vec<f32> = vec![-0.8, 0.8, -0.4, 0.4, 1.5, -1.5, 1.2, -1.2];
932        let mat_2d_b2: Vec<f32> = vec![-1.0, 0.0, 1.0, -0.9, 0.0, 0.9];
933        let mat_2d_b4: Vec<f32> = (-7..=7).map(|x| x as f32 * 0.25).chain([0.0]).collect();
934        let mat_2d_b8: Vec<f32> = (0..16).map(|i| (i as f32 - 8.0) * 0.1).collect();
935
936        write_archive(
937            tmp.path(),
938            ArchiveMagic::Qpr1,
939            Some("test".to_owned()),
940            None,
941            &[
942                ("t16", &[6], &vec_1d, BitWidth::B16),
943                ("t1", &[2, 4], &mat_2d_b1, BitWidth::B1),
944                ("t2", &[2, 3], &mat_2d_b2, BitWidth::B2),
945                ("t4", &[2, 8], &mat_2d_b4, BitWidth::B4),
946                ("t8", &[2, 8], &mat_2d_b8, BitWidth::B8),
947            ],
948        )
949        .unwrap();
950
951        let archive = read_archive(tmp.path()).unwrap();
952        assert_eq!(archive.magic, ArchiveMagic::Qpr1);
953        assert_eq!(archive.tensors.len(), 5);
954
955        // Verify 16-bit precision
956        for (got, want) in archive.tensors["t16"].data.iter().zip(&vec_1d) {
957            assert!((got - want).abs() < 1e-2);
958        }
959        // Verify 1-bit sign reconstruction
960        let t1 = &archive.tensors["t1"].data;
961        assert!(t1[0] < 0.0 && t1[1] > 0.0 && (t1[0].abs() - 0.8).abs() < 0.02);
962        assert!(t1[4] > 0.0 && t1[5] < 0.0 && (t1[4].abs() - 1.5).abs() < 0.02);
963        // Verify 8-bit reconstruction accuracy
964        for (got, want) in archive.tensors["t8"].data.iter().zip(&mat_2d_b8) {
965            assert!((got - want).abs() < 0.02, "got={got} want={want}");
966        }
967    }
968
969    #[test]
970    fn real_weights_bin_and_enwik9_voc_validate() {
971        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../assets");
972        let weights_path = root.join("weights.bin");
973        let voc_path = root.join("enwik9.voc");
974
975        let archive = read_archive(&weights_path).expect("assets/weights.bin should load");
976        assert_eq!(archive.magic, ArchiveMagic::Qpi1);
977        assert_eq!(archive.archive_bytes, 4_334_741);
978        assert_eq!(
979            archive.archive_sha256,
980            "e94c089f8eb985a87307dca3a7702385fcaccd14d95743811f8788f7da24448d"
981        );
982        assert_eq!(archive.metadata.policy.as_deref(), Some("uniform1"));
983        assert_eq!(archive.tensors.len(), 26);
984
985        for (name, tensor) in &archive.tensors {
986            assert!(
987                tensor.data.iter().all(|v| v.is_finite()),
988                "non-finite value in {name}"
989            );
990        }
991
992        let mut expected_shapes = BTreeMap::new();
993        expected_shapes.insert("tok_emb.weight".to_owned(), vec![4097, 1024]);
994        expected_shapes.insert("emb_norm.weight".to_owned(), vec![1024]);
995        expected_shapes.insert("norm.weight".to_owned(), vec![1024]);
996        expected_shapes.insert("head.weight".to_owned(), vec![4097, 1024]);
997        for layer in 0..12 {
998            let p = format!("blocks.{layer}");
999            expected_shapes.insert(format!("{p}.attn_pre_norm.weight"), vec![1024]);
1000            expected_shapes.insert(format!("{p}.attn.qkv.weight"), vec![3072, 1024]);
1001            expected_shapes.insert(format!("{p}.attn.q_norm.weight"), vec![128]);
1002            expected_shapes.insert(format!("{p}.attn.k_norm.weight"), vec![128]);
1003            expected_shapes.insert(format!("{p}.attn.proj.weight"), vec![1024, 1024]);
1004            expected_shapes.insert(format!("{p}.attn_post_norm.weight"), vec![1024]);
1005            expected_shapes.insert(format!("{p}.ffn_pre_norm.weight"), vec![1024]);
1006            expected_shapes.insert(format!("{p}.ffn.gate.weight"), vec![2816, 1024]);
1007            expected_shapes.insert(format!("{p}.ffn.up.weight"), vec![2816, 1024]);
1008            expected_shapes.insert(format!("{p}.ffn.down.weight"), vec![1024, 2816]);
1009            expected_shapes.insert(format!("{p}.ffn_post_norm.weight"), vec![1024]);
1010        }
1011
1012        let geom = TransformerGeometry {
1013            vocab_size: 4097,
1014            n_layer: 12,
1015            d_model: 1024,
1016            n_head: 8,
1017            d_inner: 2816,
1018            ctx_len: 192,
1019            tie_embeddings: false,
1020            position_type: "rope".to_owned(),
1021            qk_norm: true,
1022            norm_style: "peri".to_owned(),
1023        };
1024
1025        let plan = plan_depth_prior(&archive, &voc_path, &geom, 1111, &expected_shapes).unwrap();
1026        assert_eq!(plan.initialization_kind, InitializationKind::LoopUntying);
1027        assert_eq!(plan.source_depth, 2);
1028        assert_eq!(plan.block_mapping, vec![0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1]);
1029        assert!(plan.zero_unmapped_targets.is_empty());
1030    }
1031
1032    #[test]
1033    fn depth_mapping_and_schedule_helpers() {
1034        assert_eq!(depth_block_mapping(2, 6).unwrap(), vec![0, 3]);
1035        assert_eq!(depth_block_mapping(3, 6).unwrap(), vec![0, 2, 4]);
1036        assert!(depth_block_mapping(0, 6).is_err());
1037        assert!(depth_block_mapping(7, 6).is_err());
1038
1039        assert_eq!(
1040            parse_block_schedule("0,1,0,1", 2).unwrap(),
1041            vec![0, 1, 0, 1]
1042        );
1043        assert!(parse_block_schedule("", 2).is_err());
1044        assert!(parse_block_schedule("0,0", 2).is_err());
1045        assert!(parse_block_schedule("0,2", 2).is_err());
1046    }
1047}