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
12pub const ARCHIVE_VERSION: u32 = 1;
14
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
17pub enum ArchiveMagic {
18 Qpi1,
20 Qpr1,
22 Lra1,
24 Qla1,
26}
27
28impl ArchiveMagic {
29 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 #[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 #[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#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
69#[repr(u8)]
70pub enum BitWidth {
71 B1 = 1,
73 B2 = 2,
75 B4 = 4,
77 B8 = 8,
79 B16 = 16,
81}
82
83impl BitWidth {
84 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 #[must_use]
105 pub const fn bits(self) -> u8 {
106 self as u8
107 }
108}
109
110#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
112#[serde(rename_all = "kebab-case")]
113pub enum InitializationKind {
114 DepthGrowth,
116 LoopUntying,
118}
119
120#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
122pub struct TransformerGeometry {
123 pub vocab_size: usize,
125 pub n_layer: usize,
127 pub d_model: usize,
129 pub n_head: usize,
131 pub d_inner: usize,
133 pub ctx_len: usize,
135 pub tie_embeddings: bool,
137 pub position_type: String,
139 pub qk_norm: bool,
141 pub norm_style: String,
143}
144
145impl TransformerGeometry {
146 #[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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175pub struct InitializationMeta {
176 pub kind: InitializationKind,
178 pub source_geometry: TransformerGeometry,
180 pub target_geometry: TransformerGeometry,
182 #[serde(default, skip_serializing_if = "Option::is_none")]
184 pub block_mapping: Option<Vec<usize>>,
185 #[serde(default, skip_serializing_if = "Option::is_none")]
187 pub block_schedule: Option<Vec<usize>>,
188 pub initialization_seed: u64,
190 pub vocab_sha256: String,
192 #[serde(default, skip_serializing_if = "Option::is_none")]
194 pub source_checkpoint_sha256: Option<String>,
195}
196
197#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
199pub struct TensorEntryMeta {
200 pub name: String,
202 pub shape: Vec<usize>,
204 pub bits: u8,
206 pub scale_count: usize,
208 pub scale_bytes: usize,
210 #[serde(default, skip_serializing_if = "Option::is_none")]
212 pub scale_dtype: Option<String>,
213 pub value_bytes: usize,
215}
216
217#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219pub struct ArchiveMetadata {
220 pub version: u32,
222 #[serde(default, skip_serializing_if = "Option::is_none")]
224 pub policy: Option<String>,
225 #[serde(default, skip_serializing_if = "Option::is_none")]
227 pub initialization: Option<InitializationMeta>,
228 pub entries: Vec<TensorEntryMeta>,
230}
231
232#[derive(Debug, Clone, PartialEq)]
234pub struct DequantizedTensor {
235 pub shape: Vec<usize>,
237 pub data: Vec<f32>,
239}
240
241#[derive(Debug, Clone, PartialEq)]
243pub struct PriorArchive {
244 pub magic: ArchiveMagic,
246 pub archive_bytes: u64,
248 pub archive_sha256: String,
250 pub metadata: ArchiveMetadata,
252 pub tensors: BTreeMap<String, DequantizedTensor>,
254}
255
256#[derive(Debug, Clone, PartialEq, Eq)]
258pub struct PriorPlan {
259 pub archive_bytes: u64,
261 pub archive_sha256: String,
263 pub vocab_sha256: String,
265 pub initialization_kind: InitializationKind,
267 pub source_depth: usize,
269 pub block_mapping: Vec<usize>,
271 pub block_schedule: Option<Vec<usize>>,
273 pub target_sources: BTreeMap<usize, usize>,
275 pub root_names: Vec<String>,
277 pub block_suffixes: Vec<String>,
279 pub zero_unmapped_targets: Vec<usize>,
281 pub policy: Option<String>,
283}
284
285#[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
368pub 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
388pub 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
527pub 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
676pub 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
695pub 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
721pub 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
749pub 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 for (got, want) in archive.tensors["t16"].data.iter().zip(&vec_1d) {
957 assert!((got - want).abs() < 1e-2);
958 }
959 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 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}