1use sha2::{Digest, Sha256};
67
68pub const KV_COMPAT_FORMAT_VERSION: u32 = 3;
85
86pub const KV_BLOCK_SIZE_DEFAULT: usize = 256;
92
93#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
105pub struct WeightIdentity {
106 pub base_revision: String,
115 pub adapter_generation: u64,
120}
121
122impl WeightIdentity {
123 pub fn base_only(base_revision: impl Into<String>) -> Self {
125 Self {
126 base_revision: base_revision.into(),
127 adapter_generation: 0,
128 }
129 }
130
131 pub fn with_adapter(mut self, generation: u64) -> Self {
133 self.adapter_generation = generation;
134 self
135 }
136}
137
138#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
142pub struct MoeRouting {
143 pub is_moe: bool,
145 pub num_experts: usize,
147 pub num_experts_per_tok: usize,
149 pub moe_intermediate_size: usize,
151 pub shared_expert_intermediate_size: usize,
153}
154
155#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
166pub enum KvDtype {
167 Float64,
168 Float32,
169 Float16,
170 #[default]
171 BFloat16,
172 Other(String),
174}
175
176impl KvDtype {
177 pub fn from_name(s: &str) -> Self {
180 let n = s.trim().to_ascii_lowercase();
181 match n.as_str() {
182 "float64" | "double" | "f64" => KvDtype::Float64,
183 "float32" | "float" | "f32" => KvDtype::Float32,
184 "float16" | "half" | "fp16" | "f16" => KvDtype::Float16,
185 "bfloat16" | "bf16" => KvDtype::BFloat16,
186 other => KvDtype::Other(other.to_owned()),
187 }
188 }
189
190 pub fn as_canonical_str(&self) -> &str {
193 match self {
194 KvDtype::Float64 => "float64",
195 KvDtype::Float32 => "float32",
196 KvDtype::Float16 => "float16",
197 KvDtype::BFloat16 => "bfloat16",
198 KvDtype::Other(s) => s.as_str(),
199 }
200 }
201}
202
203impl std::fmt::Display for KvDtype {
204 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
205 f.write_str(self.as_canonical_str())
206 }
207}
208
209#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
215pub enum KvQuantMode {
216 #[default]
218 None,
219 Int8,
221 Nf4,
223 Fp4,
225}
226
227impl KvQuantMode {
228 pub fn as_canonical_str(&self) -> &'static str {
230 match self {
231 KvQuantMode::None => "none",
232 KvQuantMode::Int8 => "int8",
233 KvQuantMode::Nf4 => "nf4",
234 KvQuantMode::Fp4 => "fp4",
235 }
236 }
237}
238
239impl std::fmt::Display for KvQuantMode {
240 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
241 f.write_str(self.as_canonical_str())
242 }
243}
244
245#[derive(Clone, Debug, PartialEq, Eq, Hash)]
248pub struct RopeScalingFp {
249 pub rope_type: String,
251 pub factor_bits: u32,
253}
254
255impl RopeScalingFp {
256 pub fn new(rope_type: &str, factor: f32) -> Self {
258 Self {
259 rope_type: rope_type.trim().to_ascii_lowercase(),
260 factor_bits: factor.to_bits(),
261 }
262 }
263
264 pub fn factor(&self) -> f32 {
266 f32::from_bits(self.factor_bits)
267 }
268}
269
270#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
285pub struct KvCompatDescriptor {
286 pub format_version: u32,
288
289 pub weights: WeightIdentity,
291
292 pub model_name: String,
294 pub architecture: String,
296 pub model_version: u32,
298
299 pub num_hidden_layers: usize,
301 pub num_attention_heads: usize,
302 pub num_key_value_heads: usize,
303 pub head_dim: usize,
304 pub hidden_size: usize,
305
306 pub use_qk_norm: bool,
310 pub partial_rotary_factor_bits: Option<u32>,
314 pub layer_types: Vec<String>,
319 pub linear_key_head_dim: usize,
323 pub linear_value_head_dim: usize,
324 pub linear_num_key_heads: usize,
325 pub linear_num_value_heads: usize,
326 pub linear_conv_kernel_dim: usize,
327
328 pub rms_norm_eps_bits: u32,
333 pub layer_norm_eps_bits: Option<u32>,
336 pub hidden_activation: String,
340 pub scale_embeddings: bool,
343 pub query_pre_attn_scalar_bits: Option<u32>,
346 pub moe: MoeRouting,
348 pub sliding_window: Option<usize>,
351 pub rope_local_base_freq_bits: Option<u32>,
354
355 pub rope_theta_bits: u32,
358 pub rope_scaling: Option<RopeScalingFp>,
360 pub max_position_embeddings: usize,
362
363 pub dtype: KvDtype,
366 pub kv_quant: KvQuantMode,
368 pub block_size: usize,
370 pub max_context: usize,
372
373 pub vocab_size: usize,
375 pub tokenizer_hash: Option<String>,
377}
378
379impl KvCompatDescriptor {
380 pub fn rope_theta(&self) -> f32 {
382 f32::from_bits(self.rope_theta_bits)
383 }
384
385 pub fn set_rope_theta(&mut self, theta: f32) {
387 self.rope_theta_bits = theta.to_bits();
388 }
389
390 pub fn partial_rotary_factor(&self) -> Option<f32> {
392 self.partial_rotary_factor_bits.map(f32::from_bits)
393 }
394
395 pub fn set_partial_rotary_factor(&mut self, factor: Option<f32>) {
397 self.partial_rotary_factor_bits = factor.map(f32::to_bits);
398 }
399
400 pub fn set_rms_norm_eps(&mut self, eps: f32) {
402 self.rms_norm_eps_bits = eps.to_bits();
403 }
404
405 pub fn set_layer_norm_eps(&mut self, eps: Option<f32>) {
407 self.layer_norm_eps_bits = eps.map(f32::to_bits);
408 }
409
410 pub fn set_query_pre_attn_scalar(&mut self, scalar: Option<f32>) {
412 self.query_pre_attn_scalar_bits = scalar.map(f32::to_bits);
413 }
414
415 pub fn set_rope_local_base_freq(&mut self, freq: Option<f32>) {
417 self.rope_local_base_freq_bits = freq.map(f32::to_bits);
418 }
419
420 pub fn is_authoritatively_complete(&self) -> bool {
427 !self.weights.base_revision.is_empty() && self.tokenizer_hash.is_some()
428 }
429
430 pub fn set_tokenizer(&mut self, vocab_size: usize, hash: impl Into<Option<String>>) {
435 self.vocab_size = vocab_size;
436 self.tokenizer_hash = hash.into();
437 }
438
439 pub fn fingerprint(&self) -> KvCompatFingerprint {
441 KvCompatFingerprint::of(self)
442 }
443
444 pub fn check_against(&self, observed: &KvCompatDescriptor) -> Result<(), KvCompatMismatch> {
449 check_compatibility(self, observed)
450 }
451
452 fn write_canonical(&self, hash: &mut Sha256) {
459 put_u32(hash, self.format_version);
460
461 put_str(hash, &self.weights.base_revision);
462 put_u64(hash, self.weights.adapter_generation);
463
464 put_str(hash, &self.model_name);
465 put_str(hash, &self.architecture);
466 put_u32(hash, self.model_version);
467
468 put_usize(hash, self.num_hidden_layers);
469 put_usize(hash, self.num_attention_heads);
470 put_usize(hash, self.num_key_value_heads);
471 put_usize(hash, self.head_dim);
472 put_usize(hash, self.hidden_size);
473
474 put_bool(hash, self.use_qk_norm);
476 put_opt_u32(hash, self.partial_rotary_factor_bits);
477 put_str_vec(hash, &self.layer_types);
478 put_usize(hash, self.linear_key_head_dim);
479 put_usize(hash, self.linear_value_head_dim);
480 put_usize(hash, self.linear_num_key_heads);
481 put_usize(hash, self.linear_num_value_heads);
482 put_usize(hash, self.linear_conv_kernel_dim);
483
484 put_u32(hash, self.rms_norm_eps_bits);
486 put_opt_u32(hash, self.layer_norm_eps_bits);
487 put_str(hash, &canon_str(&self.hidden_activation));
488 put_bool(hash, self.scale_embeddings);
489 put_opt_u32(hash, self.query_pre_attn_scalar_bits);
490 put_bool(hash, self.moe.is_moe);
491 put_usize(hash, self.moe.num_experts);
492 put_usize(hash, self.moe.num_experts_per_tok);
493 put_usize(hash, self.moe.moe_intermediate_size);
494 put_usize(hash, self.moe.shared_expert_intermediate_size);
495 put_opt_usize(hash, self.sliding_window);
496 put_opt_u32(hash, self.rope_local_base_freq_bits);
497
498 put_u32(hash, self.rope_theta_bits);
499 match &self.rope_scaling {
500 Some(rs) => {
501 hash.update([1u8]);
502 put_str(hash, &rs.rope_type);
503 put_u32(hash, rs.factor_bits);
504 }
505 None => hash.update([0u8]),
506 }
507 put_usize(hash, self.max_position_embeddings);
508
509 put_str(hash, self.dtype.as_canonical_str());
510 put_str(hash, self.kv_quant.as_canonical_str());
511 put_usize(hash, self.block_size);
512 put_usize(hash, self.max_context);
513
514 put_usize(hash, self.vocab_size);
515 put_opt_str(hash, self.tokenizer_hash.as_deref());
516 }
517}
518
519#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
529pub struct KvCompatFingerprint([u8; 32]);
530
531impl KvCompatFingerprint {
532 pub fn of(desc: &KvCompatDescriptor) -> Self {
534 let mut hash = Sha256::new();
535 desc.write_canonical(&mut hash);
536 let digest = hash.finalize();
537 let mut out = [0u8; 32];
540 out.copy_from_slice(&digest);
541 Self(out)
542 }
543
544 pub fn as_bytes(&self) -> &[u8; 32] {
546 &self.0
547 }
548
549 pub fn to_hex(&self) -> String {
551 hex::encode(self.0)
552 }
553
554 pub fn is_compatible_with(&self, expected: &KvCompatFingerprint) -> bool {
557 self.0 == expected.0
558 }
559}
560
561impl std::fmt::Display for KvCompatFingerprint {
562 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
563 f.write_str(&self.to_hex())
564 }
565}
566
567impl std::fmt::Debug for KvCompatFingerprint {
568 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
569 write!(f, "KvCompatFingerprint({})", self.to_hex())
570 }
571}
572
573#[derive(Clone, Debug, PartialEq, Eq)]
580pub enum KvCompatMismatch {
581 FormatVersion {
582 expected: u32,
583 observed: u32,
584 },
585 Weights {
586 expected: WeightIdentity,
587 observed: WeightIdentity,
588 },
589 ModelName {
590 expected: String,
591 observed: String,
592 },
593 Architecture {
594 expected: String,
595 observed: String,
596 },
597 ModelVersion {
598 expected: u32,
599 observed: u32,
600 },
601 Geometry {
602 field: &'static str,
603 expected: usize,
604 observed: usize,
605 },
606 UseQkNorm {
607 expected: bool,
608 observed: bool,
609 },
610 PartialRotaryFactor {
611 expected_bits: Option<u32>,
612 observed_bits: Option<u32>,
613 },
614 LayerTypes {
615 expected: Vec<String>,
616 observed: Vec<String>,
617 },
618 RmsNormEps {
620 expected_bits: u32,
621 observed_bits: u32,
622 },
623 LayerNormEps {
624 expected_bits: Option<u32>,
625 observed_bits: Option<u32>,
626 },
627 HiddenActivation {
628 expected: String,
629 observed: String,
630 },
631 ScaleEmbeddings {
632 expected: bool,
633 observed: bool,
634 },
635 QueryPreAttnScalar {
636 expected_bits: Option<u32>,
637 observed_bits: Option<u32>,
638 },
639 MoeRouting {
640 expected: MoeRouting,
641 observed: MoeRouting,
642 },
643 SlidingWindow {
644 expected: Option<usize>,
645 observed: Option<usize>,
646 },
647 RopeLocalBaseFreq {
648 expected_bits: Option<u32>,
649 observed_bits: Option<u32>,
650 },
651 RopeTheta {
652 expected_bits: u32,
653 observed_bits: u32,
654 },
655 RopeScaling {
656 expected: Option<RopeScalingFp>,
657 observed: Option<RopeScalingFp>,
658 },
659 MaxPositionEmbeddings {
660 expected: usize,
661 observed: usize,
662 },
663 Dtype {
664 expected: KvDtype,
665 observed: KvDtype,
666 },
667 KvQuant {
668 expected: KvQuantMode,
669 observed: KvQuantMode,
670 },
671 BlockSize {
672 expected: usize,
673 observed: usize,
674 },
675 MaxContext {
676 expected: usize,
677 observed: usize,
678 },
679 VocabSize {
680 expected: usize,
681 observed: usize,
682 },
683 TokenizerHash {
684 expected: Option<String>,
685 observed: Option<String>,
686 },
687}
688
689impl std::fmt::Display for KvCompatMismatch {
690 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
691 match self {
692 KvCompatMismatch::FormatVersion { expected, observed } => write!(
693 f,
694 "KV compat mismatch: format_version (expected {expected}, observed {observed})"
695 ),
696 KvCompatMismatch::Weights { expected, observed } => write!(
697 f,
698 "KV compat mismatch: effective weights (expected {expected:?}, observed {observed:?})"
699 ),
700 KvCompatMismatch::ModelName { expected, observed } => write!(
701 f,
702 "KV compat mismatch: model name (expected {expected:?}, observed {observed:?})"
703 ),
704 KvCompatMismatch::Architecture { expected, observed } => write!(
705 f,
706 "KV compat mismatch: architecture (expected {expected:?}, observed {observed:?})"
707 ),
708 KvCompatMismatch::ModelVersion { expected, observed } => write!(
709 f,
710 "KV compat mismatch: model version (expected {expected}, observed {observed})"
711 ),
712 KvCompatMismatch::Geometry {
713 field,
714 expected,
715 observed,
716 } => write!(
717 f,
718 "KV compat mismatch: geometry field {field:?} (expected {expected}, observed {observed})"
719 ),
720 KvCompatMismatch::UseQkNorm { expected, observed } => write!(
721 f,
722 "KV compat mismatch: use_qk_norm (expected {expected}, observed {observed})"
723 ),
724 KvCompatMismatch::PartialRotaryFactor {
725 expected_bits,
726 observed_bits,
727 } => write!(
728 f,
729 "KV compat mismatch: partial_rotary_factor (expected bits {expected_bits:?}, observed bits {observed_bits:?})"
730 ),
731 KvCompatMismatch::LayerTypes { expected, observed } => write!(
732 f,
733 "KV compat mismatch: layer_types (expected {expected:?}, observed {observed:?})"
734 ),
735 KvCompatMismatch::RmsNormEps {
736 expected_bits,
737 observed_bits,
738 } => write!(
739 f,
740 "KV compat mismatch: rms_norm_eps (expected bits {expected_bits:#x}, observed bits {observed_bits:#x})"
741 ),
742 KvCompatMismatch::LayerNormEps {
743 expected_bits,
744 observed_bits,
745 } => write!(
746 f,
747 "KV compat mismatch: layer_norm_eps (expected bits {expected_bits:?}, observed bits {observed_bits:?})"
748 ),
749 KvCompatMismatch::HiddenActivation { expected, observed } => write!(
750 f,
751 "KV compat mismatch: hidden_activation (expected {expected:?}, observed {observed:?})"
752 ),
753 KvCompatMismatch::ScaleEmbeddings { expected, observed } => write!(
754 f,
755 "KV compat mismatch: scale_embeddings (expected {expected}, observed {observed})"
756 ),
757 KvCompatMismatch::QueryPreAttnScalar {
758 expected_bits,
759 observed_bits,
760 } => write!(
761 f,
762 "KV compat mismatch: query_pre_attn_scalar (expected bits {expected_bits:?}, observed bits {observed_bits:?})"
763 ),
764 KvCompatMismatch::MoeRouting { expected, observed } => write!(
765 f,
766 "KV compat mismatch: moe routing (expected {expected:?}, observed {observed:?})"
767 ),
768 KvCompatMismatch::SlidingWindow { expected, observed } => write!(
769 f,
770 "KV compat mismatch: sliding_window (expected {expected:?}, observed {observed:?})"
771 ),
772 KvCompatMismatch::RopeLocalBaseFreq {
773 expected_bits,
774 observed_bits,
775 } => write!(
776 f,
777 "KV compat mismatch: rope_local_base_freq (expected bits {expected_bits:?}, observed bits {observed_bits:?})"
778 ),
779 KvCompatMismatch::RopeTheta {
780 expected_bits,
781 observed_bits,
782 } => write!(
783 f,
784 "KV compat mismatch: rope_theta (expected bits {expected_bits:#x}, observed {observed_bits:#x})"
785 ),
786 KvCompatMismatch::RopeScaling { expected, observed } => write!(
787 f,
788 "KV compat mismatch: rope_scaling (expected {expected:?}, observed {observed:?})"
789 ),
790 KvCompatMismatch::MaxPositionEmbeddings { expected, observed } => write!(
791 f,
792 "KV compat mismatch: max_position_embeddings (expected {expected}, observed {observed})"
793 ),
794 KvCompatMismatch::Dtype { expected, observed } => write!(
795 f,
796 "KV compat mismatch: dtype (expected {expected}, observed {observed})"
797 ),
798 KvCompatMismatch::KvQuant { expected, observed } => write!(
799 f,
800 "KV compat mismatch: kv quant mode (expected {expected}, observed {observed})"
801 ),
802 KvCompatMismatch::BlockSize { expected, observed } => write!(
803 f,
804 "KV compat mismatch: block_size (expected {expected}, observed {observed})"
805 ),
806 KvCompatMismatch::MaxContext { expected, observed } => write!(
807 f,
808 "KV compat mismatch: max_context (expected {expected}, observed {observed})"
809 ),
810 KvCompatMismatch::VocabSize { expected, observed } => write!(
811 f,
812 "KV compat mismatch: vocab_size (expected {expected}, observed {observed})"
813 ),
814 KvCompatMismatch::TokenizerHash { expected, observed } => write!(
815 f,
816 "KV compat mismatch: tokenizer_hash (expected {expected:?}, observed {observed:?})"
817 ),
818 }
819 }
820}
821
822impl std::error::Error for KvCompatMismatch {}
823
824pub fn check_compatibility(
837 expected: &KvCompatDescriptor,
838 observed: &KvCompatDescriptor,
839) -> Result<(), KvCompatMismatch> {
840 if expected.format_version != observed.format_version {
841 return Err(KvCompatMismatch::FormatVersion {
842 expected: expected.format_version,
843 observed: observed.format_version,
844 });
845 }
846 if expected.weights != observed.weights {
847 return Err(KvCompatMismatch::Weights {
848 expected: expected.weights.clone(),
849 observed: observed.weights.clone(),
850 });
851 }
852 if expected.model_name != observed.model_name {
853 return Err(KvCompatMismatch::ModelName {
854 expected: expected.model_name.clone(),
855 observed: observed.model_name.clone(),
856 });
857 }
858 if expected.architecture != observed.architecture {
859 return Err(KvCompatMismatch::Architecture {
860 expected: expected.architecture.clone(),
861 observed: observed.architecture.clone(),
862 });
863 }
864 if expected.model_version != observed.model_version {
865 return Err(KvCompatMismatch::ModelVersion {
866 expected: expected.model_version,
867 observed: observed.model_version,
868 });
869 }
870 if expected.num_hidden_layers != observed.num_hidden_layers {
872 return Err(geometry(
873 "num_hidden_layers",
874 expected.num_hidden_layers,
875 observed.num_hidden_layers,
876 ));
877 }
878 if expected.num_attention_heads != observed.num_attention_heads {
879 return Err(geometry(
880 "num_attention_heads",
881 expected.num_attention_heads,
882 observed.num_attention_heads,
883 ));
884 }
885 if expected.num_key_value_heads != observed.num_key_value_heads {
886 return Err(geometry(
887 "num_key_value_heads",
888 expected.num_key_value_heads,
889 observed.num_key_value_heads,
890 ));
891 }
892 if expected.head_dim != observed.head_dim {
893 return Err(geometry("head_dim", expected.head_dim, observed.head_dim));
894 }
895 if expected.hidden_size != observed.hidden_size {
896 return Err(geometry(
897 "hidden_size",
898 expected.hidden_size,
899 observed.hidden_size,
900 ));
901 }
902 if expected.use_qk_norm != observed.use_qk_norm {
904 return Err(KvCompatMismatch::UseQkNorm {
905 expected: expected.use_qk_norm,
906 observed: observed.use_qk_norm,
907 });
908 }
909 if expected.partial_rotary_factor_bits != observed.partial_rotary_factor_bits {
910 return Err(KvCompatMismatch::PartialRotaryFactor {
911 expected_bits: expected.partial_rotary_factor_bits,
912 observed_bits: observed.partial_rotary_factor_bits,
913 });
914 }
915 {
920 let exp_lt = canonical_layer_types(&expected.layer_types);
921 let obs_lt = canonical_layer_types(&observed.layer_types);
922 if exp_lt != obs_lt {
923 return Err(KvCompatMismatch::LayerTypes {
924 expected: exp_lt,
925 observed: obs_lt,
926 });
927 }
928 }
929 if expected.linear_key_head_dim != observed.linear_key_head_dim {
930 return Err(geometry(
931 "linear_key_head_dim",
932 expected.linear_key_head_dim,
933 observed.linear_key_head_dim,
934 ));
935 }
936 if expected.linear_value_head_dim != observed.linear_value_head_dim {
937 return Err(geometry(
938 "linear_value_head_dim",
939 expected.linear_value_head_dim,
940 observed.linear_value_head_dim,
941 ));
942 }
943 if expected.linear_num_key_heads != observed.linear_num_key_heads {
944 return Err(geometry(
945 "linear_num_key_heads",
946 expected.linear_num_key_heads,
947 observed.linear_num_key_heads,
948 ));
949 }
950 if expected.linear_num_value_heads != observed.linear_num_value_heads {
951 return Err(geometry(
952 "linear_num_value_heads",
953 expected.linear_num_value_heads,
954 observed.linear_num_value_heads,
955 ));
956 }
957 if expected.linear_conv_kernel_dim != observed.linear_conv_kernel_dim {
958 return Err(geometry(
959 "linear_conv_kernel_dim",
960 expected.linear_conv_kernel_dim,
961 observed.linear_conv_kernel_dim,
962 ));
963 }
964 if expected.rms_norm_eps_bits != observed.rms_norm_eps_bits {
967 return Err(KvCompatMismatch::RmsNormEps {
968 expected_bits: expected.rms_norm_eps_bits,
969 observed_bits: observed.rms_norm_eps_bits,
970 });
971 }
972 if expected.layer_norm_eps_bits != observed.layer_norm_eps_bits {
973 return Err(KvCompatMismatch::LayerNormEps {
974 expected_bits: expected.layer_norm_eps_bits,
975 observed_bits: observed.layer_norm_eps_bits,
976 });
977 }
978 if canon_str(&expected.hidden_activation) != canon_str(&observed.hidden_activation) {
979 return Err(KvCompatMismatch::HiddenActivation {
980 expected: canon_str(&expected.hidden_activation),
981 observed: canon_str(&observed.hidden_activation),
982 });
983 }
984 if expected.scale_embeddings != observed.scale_embeddings {
985 return Err(KvCompatMismatch::ScaleEmbeddings {
986 expected: expected.scale_embeddings,
987 observed: observed.scale_embeddings,
988 });
989 }
990 if expected.query_pre_attn_scalar_bits != observed.query_pre_attn_scalar_bits {
991 return Err(KvCompatMismatch::QueryPreAttnScalar {
992 expected_bits: expected.query_pre_attn_scalar_bits,
993 observed_bits: observed.query_pre_attn_scalar_bits,
994 });
995 }
996 if expected.moe != observed.moe {
997 return Err(KvCompatMismatch::MoeRouting {
998 expected: expected.moe.clone(),
999 observed: observed.moe.clone(),
1000 });
1001 }
1002 if expected.sliding_window != observed.sliding_window {
1003 return Err(KvCompatMismatch::SlidingWindow {
1004 expected: expected.sliding_window,
1005 observed: observed.sliding_window,
1006 });
1007 }
1008 if expected.rope_local_base_freq_bits != observed.rope_local_base_freq_bits {
1009 return Err(KvCompatMismatch::RopeLocalBaseFreq {
1010 expected_bits: expected.rope_local_base_freq_bits,
1011 observed_bits: observed.rope_local_base_freq_bits,
1012 });
1013 }
1014 if expected.rope_theta_bits != observed.rope_theta_bits {
1015 return Err(KvCompatMismatch::RopeTheta {
1016 expected_bits: expected.rope_theta_bits,
1017 observed_bits: observed.rope_theta_bits,
1018 });
1019 }
1020 if expected.rope_scaling != observed.rope_scaling {
1021 return Err(KvCompatMismatch::RopeScaling {
1022 expected: expected.rope_scaling.clone(),
1023 observed: observed.rope_scaling.clone(),
1024 });
1025 }
1026 if expected.max_position_embeddings != observed.max_position_embeddings {
1027 return Err(KvCompatMismatch::MaxPositionEmbeddings {
1028 expected: expected.max_position_embeddings,
1029 observed: observed.max_position_embeddings,
1030 });
1031 }
1032 if expected.dtype != observed.dtype {
1033 return Err(KvCompatMismatch::Dtype {
1034 expected: expected.dtype.clone(),
1035 observed: observed.dtype.clone(),
1036 });
1037 }
1038 if expected.kv_quant != observed.kv_quant {
1039 return Err(KvCompatMismatch::KvQuant {
1040 expected: expected.kv_quant,
1041 observed: observed.kv_quant,
1042 });
1043 }
1044 if expected.block_size != observed.block_size {
1045 return Err(KvCompatMismatch::BlockSize {
1046 expected: expected.block_size,
1047 observed: observed.block_size,
1048 });
1049 }
1050 if expected.max_context != observed.max_context {
1051 return Err(KvCompatMismatch::MaxContext {
1052 expected: expected.max_context,
1053 observed: observed.max_context,
1054 });
1055 }
1056 if expected.vocab_size != observed.vocab_size {
1057 return Err(KvCompatMismatch::VocabSize {
1058 expected: expected.vocab_size,
1059 observed: observed.vocab_size,
1060 });
1061 }
1062 if expected.tokenizer_hash != observed.tokenizer_hash {
1063 return Err(KvCompatMismatch::TokenizerHash {
1064 expected: expected.tokenizer_hash.clone(),
1065 observed: observed.tokenizer_hash.clone(),
1066 });
1067 }
1068 Ok(())
1069}
1070
1071fn geometry(field: &'static str, expected: usize, observed: usize) -> KvCompatMismatch {
1072 KvCompatMismatch::Geometry {
1073 field,
1074 expected,
1075 observed,
1076 }
1077}
1078
1079#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1087pub enum CacheReuseDecision {
1088 Reuse,
1091 StampFresh,
1095 DiscardAndRecompute,
1100}
1101
1102pub fn decide_cache_reuse(
1119 expected: Option<&KvCompatFingerprint>,
1120 stored: Option<&KvCompatFingerprint>,
1121 cache_is_empty: bool,
1122) -> CacheReuseDecision {
1123 match (expected, stored) {
1124 (Some(exp), Some(stored)) if exp == stored => CacheReuseDecision::Reuse,
1125 (Some(_), None) if cache_is_empty => CacheReuseDecision::StampFresh,
1126 _ => CacheReuseDecision::DiscardAndRecompute,
1127 }
1128}
1129
1130#[inline]
1135fn put_u32(hash: &mut Sha256, v: u32) {
1136 hash.update(v.to_le_bytes());
1137}
1138
1139#[inline]
1140fn put_opt_u32(hash: &mut Sha256, v: Option<u32>) {
1141 match v {
1142 Some(x) => {
1143 hash.update([1u8]);
1144 put_u32(hash, x);
1145 }
1146 None => hash.update([0u8]),
1147 }
1148}
1149
1150#[inline]
1151fn put_bool(hash: &mut Sha256, v: bool) {
1152 hash.update([if v { 1u8 } else { 0u8 }]);
1153}
1154
1155#[inline]
1156fn put_u64(hash: &mut Sha256, v: u64) {
1157 hash.update(v.to_le_bytes());
1158}
1159
1160#[inline]
1161fn put_usize(hash: &mut Sha256, v: usize) {
1162 hash.update((v as u64).to_le_bytes());
1165}
1166
1167#[inline]
1168fn put_opt_usize(hash: &mut Sha256, v: Option<usize>) {
1169 match v {
1170 Some(x) => {
1171 hash.update([1u8]);
1172 put_usize(hash, x);
1173 }
1174 None => hash.update([0u8]),
1175 }
1176}
1177
1178#[inline]
1179fn put_str(hash: &mut Sha256, s: &str) {
1180 put_u64(hash, s.len() as u64);
1181 hash.update(s.as_bytes());
1182}
1183
1184#[inline]
1185fn put_opt_str(hash: &mut Sha256, s: Option<&str>) {
1186 match s {
1187 Some(s) => {
1188 hash.update([1u8]);
1189 put_str(hash, s);
1190 }
1191 None => hash.update([0u8]),
1192 }
1193}
1194
1195#[inline]
1199fn canon_str(s: &str) -> String {
1200 s.trim().to_ascii_lowercase()
1201}
1202
1203fn canonical_layer_types(v: &[String]) -> Vec<String> {
1207 v.iter().map(|s| canon_str(s)).collect()
1208}
1209
1210#[inline]
1213fn put_str_vec(hash: &mut Sha256, v: &[String]) {
1214 put_u64(hash, v.len() as u64);
1215 for s in v {
1216 put_str(hash, &canon_str(s));
1217 }
1218}
1219
1220pub fn shard_content_digest(bytes: &[u8]) -> [u8; 32] {
1233 let mut h = Sha256::new();
1234 h.update(bytes);
1235 let mut out = [0u8; 32];
1236 out.copy_from_slice(h.finalize().as_slice());
1237 out
1238}
1239
1240pub(crate) fn base_weight_digest_from_shards(shards: &[(String, [u8; 32])]) -> String {
1247 let mut h = Sha256::new();
1248 put_u64(&mut h, shards.len() as u64);
1249 for (name, digest) in shards {
1250 put_str(&mut h, name);
1251 h.update(digest);
1252 }
1253 hex::encode(h.finalize())
1254}
1255
1256#[cfg(test)]
1257#[allow(clippy::unwrap_used)]
1258mod tests {
1259 use super::*;
1260
1261 fn baseline() -> KvCompatDescriptor {
1264 KvCompatDescriptor {
1265 format_version: KV_COMPAT_FORMAT_VERSION,
1266 weights: WeightIdentity::base_only("sha256:my-model-weights"),
1267 model_name: "my-model".to_owned(),
1268 architecture: "llama".to_owned(),
1269 model_version: 1,
1270 num_hidden_layers: 32,
1271 num_attention_heads: 32,
1272 num_key_value_heads: 8,
1273 head_dim: 128,
1274 hidden_size: 4096,
1275 use_qk_norm: false,
1277 partial_rotary_factor_bits: None,
1278 layer_types: Vec::new(),
1279 linear_key_head_dim: 0,
1280 linear_value_head_dim: 0,
1281 linear_num_key_heads: 0,
1282 linear_num_value_heads: 0,
1283 linear_conv_kernel_dim: 0,
1284 rms_norm_eps_bits: 1e-5f32.to_bits(),
1287 layer_norm_eps_bits: None,
1288 hidden_activation: "silu".to_owned(),
1289 scale_embeddings: false,
1290 query_pre_attn_scalar_bits: None,
1291 moe: MoeRouting::default(),
1292 sliding_window: None,
1293 rope_local_base_freq_bits: None,
1294 rope_theta_bits: 10_000.0f32.to_bits(),
1295 rope_scaling: None,
1296 max_position_embeddings: 4096,
1297 dtype: KvDtype::BFloat16,
1298 kv_quant: KvQuantMode::None,
1299 block_size: KV_BLOCK_SIZE_DEFAULT,
1300 max_context: 4096,
1301 vocab_size: 32_000,
1302 tokenizer_hash: Some("deadbeef".to_owned()),
1303 }
1304 }
1305
1306 fn set_linear_dim(d: &mut KvCompatDescriptor, field: &str, val: usize) {
1308 match field {
1309 "linear_key_head_dim" => d.linear_key_head_dim = val,
1310 "linear_value_head_dim" => d.linear_value_head_dim = val,
1311 "linear_num_key_heads" => d.linear_num_key_heads = val,
1312 "linear_num_value_heads" => d.linear_num_value_heads = val,
1313 "linear_conv_kernel_dim" => d.linear_conv_kernel_dim = val,
1314 _ => panic!("unknown linear dim field {field}"),
1315 }
1316 }
1317
1318 #[test]
1319 fn default_block_size_tracks_kv_cache_block_size() {
1320 assert_eq!(KV_BLOCK_SIZE_DEFAULT, crate::runtime::kv_cache::BLOCK_SIZE);
1323 }
1324
1325 #[test]
1326 fn fingerprint_is_deterministic() {
1327 let a = baseline().fingerprint();
1328 let b = baseline().fingerprint();
1329 assert_eq!(a, b, "identical descriptors must hash identically");
1330 assert_eq!(a.to_hex(), b.to_hex());
1331 assert_eq!(a.as_bytes().len(), 32);
1332 }
1333
1334 #[test]
1335 fn fingerprint_is_clone_stable() {
1336 let d = baseline();
1337 assert_eq!(d.fingerprint(), d.clone().fingerprint());
1338 }
1339
1340 fn assert_field_diverges(
1343 label: &str,
1344 mutator: impl FnOnce(&mut KvCompatDescriptor),
1345 expected_mismatch: Option<KvCompatMismatch>,
1346 ) {
1347 let base_fp = baseline().fingerprint();
1348 let mut d = baseline();
1349 mutator(&mut d);
1350 let divergent_fp = d.fingerprint();
1351 assert_ne!(
1352 base_fp, divergent_fp,
1353 "{label}: flipping the field must change the fingerprint"
1354 );
1355 if let Some(expected) = expected_mismatch {
1356 let observed = baseline();
1357 let reason = check_compatibility(&d, &observed).err().unwrap_or_else(|| {
1358 panic!("{label}: expected a mismatch but descriptors compared equal")
1359 });
1360 assert_eq!(
1361 reason, expected,
1362 "{label}: mismatch variant/reason did not match expectation"
1363 );
1364 }
1365 }
1366
1367 #[test]
1368 fn every_authoritative_field_participates() {
1369 assert_field_diverges(
1371 "weights.base_revision",
1372 |d| d.weights.base_revision = "other-model".into(),
1373 Some(KvCompatMismatch::Weights {
1374 expected: WeightIdentity::base_only("other-model"),
1375 observed: WeightIdentity::base_only("sha256:my-model-weights"),
1376 }),
1377 );
1378 assert_field_diverges(
1379 "weights.adapter_generation",
1380 |d| d.weights.adapter_generation = 7,
1381 Some(KvCompatMismatch::Weights {
1382 expected: WeightIdentity::base_only("sha256:my-model-weights").with_adapter(7),
1383 observed: WeightIdentity::base_only("sha256:my-model-weights"),
1384 }),
1385 );
1386 assert_field_diverges("model_name", |d| d.model_name = "other".into(), None);
1388 assert_field_diverges("architecture", |d| d.architecture = "qwen2".into(), None);
1389 assert_field_diverges("model_version", |d| d.model_version = 2, None);
1390 assert_field_diverges(
1392 "num_hidden_layers",
1393 |d| d.num_hidden_layers = 24,
1394 Some(geometry("num_hidden_layers", 24, 32)),
1395 );
1396 assert_field_diverges(
1397 "num_attention_heads",
1398 |d| d.num_attention_heads = 16,
1399 Some(geometry("num_attention_heads", 16, 32)),
1400 );
1401 assert_field_diverges(
1402 "num_key_value_heads",
1403 |d| d.num_key_value_heads = 4,
1404 Some(geometry("num_key_value_heads", 4, 8)),
1405 );
1406 assert_field_diverges(
1407 "head_dim",
1408 |d| d.head_dim = 64,
1409 Some(geometry("head_dim", 64, 128)),
1410 );
1411 assert_field_diverges(
1412 "hidden_size",
1413 |d| d.hidden_size = 2048,
1414 Some(geometry("hidden_size", 2048, 4096)),
1415 );
1416 assert_field_diverges(
1418 "use_qk_norm",
1419 |d| d.use_qk_norm = true,
1420 Some(KvCompatMismatch::UseQkNorm {
1421 expected: true,
1422 observed: false,
1423 }),
1424 );
1425 assert_field_diverges(
1426 "partial_rotary_factor",
1427 |d| d.set_partial_rotary_factor(Some(0.25)),
1428 Some(KvCompatMismatch::PartialRotaryFactor {
1429 expected_bits: Some(0.25f32.to_bits()),
1430 observed_bits: None,
1431 }),
1432 );
1433 assert_field_diverges(
1434 "partial_rotary_factor None->Some spelling",
1435 |d| d.set_partial_rotary_factor(Some(1.0)),
1436 Some(KvCompatMismatch::PartialRotaryFactor {
1437 expected_bits: Some(1.0f32.to_bits()),
1438 observed_bits: None,
1439 }),
1440 );
1441 assert_field_diverges(
1442 "layer_types",
1443 |d| d.layer_types = vec!["global".to_owned(), "local".to_owned()],
1444 Some(KvCompatMismatch::LayerTypes {
1445 expected: vec!["global".to_owned(), "local".to_owned()],
1446 observed: Vec::new(),
1447 }),
1448 );
1449 {
1452 let mut d = baseline();
1453 let fp0 = d.fingerprint();
1454 d.layer_types = vec!["GLOBAL".to_owned(), "Local".to_owned()];
1455 let mut d2 = baseline();
1456 d2.layer_types = vec!["global".to_owned(), "local".to_owned()];
1457 assert_eq!(
1458 d.fingerprint(),
1459 d2.fingerprint(),
1460 "layer_types casing must canonicalize before hashing"
1461 );
1462 assert!(
1465 check_compatibility(&d, &d2).is_ok(),
1466 "layer_types casing alias must be policy-compatible, not just hash-equal"
1467 );
1468 assert_ne!(fp0, d.fingerprint(), "non-empty layer layout must diverge");
1469 }
1470 for (field, val) in [
1471 ("linear_key_head_dim", 512usize),
1472 ("linear_value_head_dim", 256usize),
1473 ("linear_num_key_heads", 8usize),
1474 ("linear_num_value_heads", 8usize),
1475 ("linear_conv_kernel_dim", 4usize),
1476 ] {
1477 let mut d = baseline();
1478 set_linear_dim(&mut d, field, val);
1479 let divergent_fp = d.fingerprint();
1480 assert_ne!(
1481 baseline().fingerprint(),
1482 divergent_fp,
1483 "{field}: changing the linear dim must change the fingerprint"
1484 );
1485 assert_eq!(
1486 check_compatibility(&d, &baseline()).unwrap_err(),
1487 geometry(field, val, 0),
1488 "{field}: mismatch variant"
1489 );
1490 }
1491 assert_field_diverges(
1494 "rms_norm_eps",
1495 |d| d.set_rms_norm_eps(1e-6),
1496 Some(KvCompatMismatch::RmsNormEps {
1497 expected_bits: 1e-6f32.to_bits(),
1498 observed_bits: 1e-5f32.to_bits(),
1499 }),
1500 );
1501 assert_field_diverges(
1502 "layer_norm_eps",
1503 |d| d.set_layer_norm_eps(Some(1e-5)),
1504 Some(KvCompatMismatch::LayerNormEps {
1505 expected_bits: Some(1e-5f32.to_bits()),
1506 observed_bits: None,
1507 }),
1508 );
1509 assert_field_diverges(
1510 "hidden_activation",
1511 |d| d.hidden_activation = "gelu_pytorch_tanh".into(),
1512 Some(KvCompatMismatch::HiddenActivation {
1513 expected: "gelu_pytorch_tanh".into(),
1514 observed: "silu".into(),
1515 }),
1516 );
1517 {
1521 let mut d = baseline();
1522 d.hidden_activation = " SiLU ".into();
1523 assert_eq!(
1524 d.fingerprint(),
1525 baseline().fingerprint(),
1526 "hidden_activation casing/whitespace must canonicalize"
1527 );
1528 assert!(check_compatibility(&d, &baseline()).is_ok());
1529 }
1530 assert_field_diverges(
1531 "scale_embeddings",
1532 |d| d.scale_embeddings = true,
1533 Some(KvCompatMismatch::ScaleEmbeddings {
1534 expected: true,
1535 observed: false,
1536 }),
1537 );
1538 assert_field_diverges(
1539 "query_pre_attn_scalar",
1540 |d| d.set_query_pre_attn_scalar(Some(256.0)),
1541 Some(KvCompatMismatch::QueryPreAttnScalar {
1542 expected_bits: Some(256.0f32.to_bits()),
1543 observed_bits: None,
1544 }),
1545 );
1546 {
1549 let mut d = baseline();
1550 d.moe.is_moe = true;
1551 assert_ne!(
1552 baseline().fingerprint(),
1553 d.fingerprint(),
1554 "moe.is_moe: setting MoE must change the fingerprint"
1555 );
1556 assert_eq!(
1557 check_compatibility(&d, &baseline()).unwrap_err(),
1558 KvCompatMismatch::MoeRouting {
1559 expected: d.moe.clone(),
1560 observed: baseline().moe,
1561 },
1562 "moe.is_moe: mismatch variant"
1563 );
1564 }
1565 for (field, val) in [
1566 ("num_experts", 64usize),
1567 ("num_experts_per_tok", 8usize),
1568 ("moe_intermediate_size", 2048usize),
1569 ("shared_expert_intermediate_size", 1024usize),
1570 ] {
1571 let mut d = baseline();
1572 match field {
1573 "num_experts" => d.moe.num_experts = val,
1574 "num_experts_per_tok" => d.moe.num_experts_per_tok = val,
1575 "moe_intermediate_size" => d.moe.moe_intermediate_size = val,
1576 "shared_expert_intermediate_size" => d.moe.shared_expert_intermediate_size = val,
1577 _ => unreachable!(),
1578 }
1579 let divergent_fp = d.fingerprint();
1580 assert_ne!(
1581 baseline().fingerprint(),
1582 divergent_fp,
1583 "{field}: MoE routing change must change the fingerprint"
1584 );
1585 assert_eq!(
1586 check_compatibility(&d, &baseline()).unwrap_err(),
1587 KvCompatMismatch::MoeRouting {
1588 expected: d.moe.clone(),
1589 observed: baseline().moe,
1590 },
1591 "{field}: MoE mismatch variant"
1592 );
1593 }
1594 assert_field_diverges(
1595 "sliding_window",
1596 |d| d.sliding_window = Some(1024),
1597 Some(KvCompatMismatch::SlidingWindow {
1598 expected: Some(1024),
1599 observed: None,
1600 }),
1601 );
1602 assert_field_diverges(
1603 "rope_local_base_freq",
1604 |d| d.set_rope_local_base_freq(Some(10_000.0)),
1605 Some(KvCompatMismatch::RopeLocalBaseFreq {
1606 expected_bits: Some(10_000.0f32.to_bits()),
1607 observed_bits: None,
1608 }),
1609 );
1610 assert_field_diverges(
1612 "rope_theta",
1613 |d| d.set_rope_theta(1_000_000.0),
1614 Some(KvCompatMismatch::RopeTheta {
1615 expected_bits: 1_000_000.0f32.to_bits(),
1616 observed_bits: 10_000.0f32.to_bits(),
1617 }),
1618 );
1619 assert_field_diverges(
1620 "rope_scaling presence",
1621 |d| d.rope_scaling = Some(RopeScalingFp::new("linear", 2.0)),
1622 None,
1623 );
1624 assert_field_diverges(
1625 "rope_scaling factor",
1626 |d| {
1627 d.rope_scaling = Some(RopeScalingFp::new("linear", 2.0));
1628 d.rope_scaling = Some(RopeScalingFp::new("linear", 4.0));
1629 },
1630 None,
1631 );
1632 assert_field_diverges(
1633 "max_position_embeddings",
1634 |d| d.max_position_embeddings = 8192,
1635 None,
1636 );
1637 assert_field_diverges(
1639 "dtype",
1640 |d| d.dtype = KvDtype::Float16,
1641 Some(KvCompatMismatch::Dtype {
1642 expected: KvDtype::Float16,
1643 observed: KvDtype::BFloat16,
1644 }),
1645 );
1646 assert_field_diverges(
1647 "kv_quant",
1648 |d| d.kv_quant = KvQuantMode::Int8,
1649 Some(KvCompatMismatch::KvQuant {
1650 expected: KvQuantMode::Int8,
1651 observed: KvQuantMode::None,
1652 }),
1653 );
1654 assert_field_diverges(
1655 "block_size",
1656 |d| d.block_size = 128,
1657 Some(KvCompatMismatch::BlockSize {
1658 expected: 128,
1659 observed: 256,
1660 }),
1661 );
1662 assert_field_diverges(
1663 "max_context",
1664 |d| d.max_context = 2048,
1665 Some(KvCompatMismatch::MaxContext {
1666 expected: 2048,
1667 observed: 4096,
1668 }),
1669 );
1670 assert_field_diverges(
1672 "vocab_size",
1673 |d| d.vocab_size = 64_000,
1674 Some(KvCompatMismatch::VocabSize {
1675 expected: 64_000,
1676 observed: 32_000,
1677 }),
1678 );
1679 assert_field_diverges(
1680 "tokenizer_hash",
1681 |d| d.tokenizer_hash = Some("cafebabe".into()),
1682 Some(KvCompatMismatch::TokenizerHash {
1683 expected: Some("cafebabe".into()),
1684 observed: Some("deadbeef".into()),
1685 }),
1686 );
1687 assert_field_diverges("tokenizer_hash absent", |d| d.tokenizer_hash = None, None);
1688 }
1689
1690 #[test]
1691 fn format_version_bump_is_hard_reject() {
1692 let mut observed = baseline();
1693 observed.format_version = 0; assert_eq!(
1695 check_compatibility(&baseline(), &observed),
1696 Err(KvCompatMismatch::FormatVersion {
1697 expected: KV_COMPAT_FORMAT_VERSION,
1698 observed: 0,
1699 })
1700 );
1701 }
1702
1703 #[test]
1704 fn equal_descriptors_are_compatible() {
1705 assert!(check_compatibility(&baseline(), &baseline()).is_ok());
1706 assert!(baseline().check_against(&baseline()).is_ok());
1707 }
1708
1709 #[test]
1710 fn fingerprint_equality_implies_descriptor_compatibility() {
1711 let a = baseline();
1714 let b = baseline();
1715 assert!(a.fingerprint().is_compatible_with(&b.fingerprint()));
1716
1717 let mut c = baseline();
1718 c.kv_quant = KvQuantMode::Nf4;
1719 assert!(!a.fingerprint().is_compatible_with(&c.fingerprint()));
1720 assert!(check_compatibility(&a, &c).is_err());
1721 }
1722
1723 #[test]
1724 fn kvdtype_is_case_and_alias_insensitive() {
1725 assert_eq!(KvDtype::from_name("BFLOAT16"), KvDtype::BFloat16);
1726 assert_eq!(KvDtype::from_name(" bf16 "), KvDtype::BFloat16);
1727 assert_eq!(KvDtype::from_name("float16"), KvDtype::Float16);
1728 assert_eq!(KvDtype::from_name("FP16"), KvDtype::Float16);
1729 assert_eq!(KvDtype::from_name("float32"), KvDtype::Float32);
1730 let mut d1 = baseline();
1732 let mut d2 = baseline();
1733 d1.dtype = KvDtype::from_name("BFLOAT16");
1734 d2.dtype = KvDtype::from_name("bfloat16");
1735 assert_eq!(d1.fingerprint(), d2.fingerprint());
1736 }
1737
1738 #[test]
1739 fn rope_scaling_canonicalizes_case() {
1740 assert_eq!(
1741 RopeScalingFp::new("Linear", 2.0),
1742 RopeScalingFp::new("linear", 2.0)
1743 );
1744 assert_ne!(
1746 RopeScalingFp::new("linear", 2.0),
1747 RopeScalingFp::new("linear", 4.0)
1748 );
1749 }
1750
1751 #[test]
1752 fn kvquant_canonical_strs_are_distinct() {
1753 let modes = [
1754 KvQuantMode::None,
1755 KvQuantMode::Int8,
1756 KvQuantMode::Nf4,
1757 KvQuantMode::Fp4,
1758 ];
1759 let strs: Vec<&str> = modes.iter().map(KvQuantMode::as_canonical_str).collect();
1760 let unique: std::collections::HashSet<&str> = strs.iter().copied().collect();
1761 assert_eq!(unique.len(), modes.len(), "quant mode names must be unique");
1762 }
1763
1764 #[test]
1765 fn canonical_framing_disambiguates_concatenations() {
1766 let mut h1 = Sha256::new();
1768 put_str(&mut h1, "ab");
1769 put_str(&mut h1, "c");
1770 let mut h2 = Sha256::new();
1771 put_str(&mut h2, "a");
1772 put_str(&mut h2, "bc");
1773 assert_ne!(
1774 h1.finalize().as_slice(),
1775 h2.finalize().as_slice(),
1776 "framing must prevent concatenation collisions"
1777 );
1778 }
1779
1780 #[test]
1781 fn mismatch_reasons_are_displayable() {
1782 let cases = [
1783 KvCompatMismatch::FormatVersion {
1784 expected: 1,
1785 observed: 0,
1786 },
1787 KvCompatMismatch::Weights {
1788 expected: WeightIdentity::base_only("a"),
1789 observed: WeightIdentity::base_only("b"),
1790 },
1791 KvCompatMismatch::Geometry {
1792 field: "head_dim",
1793 expected: 128,
1794 observed: 64,
1795 },
1796 KvCompatMismatch::Dtype {
1797 expected: KvDtype::BFloat16,
1798 observed: KvDtype::Float16,
1799 },
1800 KvCompatMismatch::KvQuant {
1801 expected: KvQuantMode::None,
1802 observed: KvQuantMode::Int8,
1803 },
1804 ];
1805 for c in cases {
1806 let s = format!("{c}");
1807 assert!(
1808 s.contains("KV compat mismatch"),
1809 "display missing prefix: {s}"
1810 );
1811 }
1812 }
1813
1814 #[test]
1815 fn weight_identity_with_adapter() {
1816 let w = WeightIdentity::base_only("m").with_adapter(3);
1817 assert_eq!(w.adapter_generation, 3);
1818 assert_eq!(w.base_revision, "m");
1819 let mut d = baseline();
1821 let fp0 = d.fingerprint();
1822 d.weights = WeightIdentity::base_only("sha256:my-model-weights").with_adapter(1);
1823 assert_ne!(fp0, d.fingerprint());
1824 }
1825
1826 #[test]
1830 fn golden_digest_is_pinned() {
1831 let fp = baseline().fingerprint();
1832 let hex = fp.to_hex();
1833 let expected = "2c1658e12b2935e6444e0503c35b9e36b3f2e941614d9078b445776eae5cc55c";
1834 assert_eq!(
1835 hex, expected,
1836 "KV-compat golden digest drifted; computed = {hex}. \
1837 If the canonical encoding changed intentionally, bump \
1838 KV_COMPAT_FORMAT_VERSION and update this pinned value."
1839 );
1840 }
1841
1842 #[test]
1845 fn base_revision_content_diverges() {
1846 let mut a = baseline();
1847 let mut b = baseline();
1848 a.weights.base_revision = "sha256:snapshot-A".into();
1849 b.weights.base_revision = "sha256:snapshot-B".into();
1850 assert_ne!(
1851 a.fingerprint(),
1852 b.fingerprint(),
1853 "different base-weight content must produce different fingerprints"
1854 );
1855 let mut c = baseline();
1857 c.weights.base_revision = "sha256:snapshot-A".into();
1858 assert_eq!(a.fingerprint(), c.fingerprint());
1859 }
1860
1861 fn digested(shards: &[(&str, &[u8])]) -> Vec<(String, [u8; 32])> {
1870 shards
1871 .iter()
1872 .map(|(n, b)| ((*n).to_owned(), shard_content_digest(b)))
1873 .collect()
1874 }
1875
1876 #[test]
1877 fn shard_content_digest_is_deterministic_and_distinct() {
1878 let a = b"hello weights";
1879 let b = b"hello weights!";
1880 assert_eq!(shard_content_digest(a), shard_content_digest(a));
1882 assert_ne!(shard_content_digest(a), shard_content_digest(b));
1884 assert_eq!(shard_content_digest(a).len(), 32);
1886 }
1887
1888 #[test]
1889 fn base_weight_digest_is_stable() {
1890 let s = digested(&[
1891 ("model-00001-of-00002.safetensors", b"AAA"),
1892 ("model-00002-of-00002.safetensors", b"BBB"),
1893 ]);
1894 assert_eq!(
1896 base_weight_digest_from_shards(&s),
1897 base_weight_digest_from_shards(&s)
1898 );
1899 }
1900
1901 #[test]
1905 fn base_weight_digest_same_basename_different_bytes_diverge() {
1906 let names = [
1907 "model-00001-of-00002.safetensors",
1908 "model-00002-of-00002.safetensors",
1909 ];
1910 let a = digested(&[(names[0], b"content-A"), (names[1], b"content-B")]);
1911 let b = digested(&[(names[0], b"content-A!"), (names[1], b"content-B")]);
1912 assert_ne!(
1913 base_weight_digest_from_shards(&a),
1914 base_weight_digest_from_shards(&b),
1915 "different shard content must produce a different digest"
1916 );
1917 }
1918
1919 #[test]
1923 fn base_weight_digest_shard_boundary_disambiguates() {
1924 let two = digested(&[
1925 ("model-00001-of-00002.safetensors", b"PART-ONE-"),
1926 ("model-00002-of-00002.safetensors", b"PART-TWO"),
1927 ]);
1928 let one = digested(&[("model.safetensors", b"PART-ONE-PART-TWO")]);
1929 assert_ne!(
1930 base_weight_digest_from_shards(&two),
1931 base_weight_digest_from_shards(&one),
1932 "shard segmentation must not be ambiguous in the digest"
1933 );
1934 }
1935
1936 #[test]
1939 fn base_weight_digest_shard_count_participates() {
1940 let two = digested(&[("a-00001.safetensors", b"X"), ("a-00002.safetensors", b"X")]);
1942 let one = digested(&[("a.safetensors", b"X")]);
1943 assert_ne!(
1944 base_weight_digest_from_shards(&two),
1945 base_weight_digest_from_shards(&one)
1946 );
1947 }
1948
1949 #[test]
1952 fn base_weight_digest_filename_participates() {
1953 let a = digested(&[("model-00001.safetensors", b"X")]);
1954 let b = digested(&[("model-00002.safetensors", b"X")]);
1955 assert_ne!(
1956 base_weight_digest_from_shards(&a),
1957 base_weight_digest_from_shards(&b),
1958 "shard filename must participate in the digest"
1959 );
1960 }
1961
1962 #[test]
1963 fn authority_completeness_gate() {
1964 assert!(baseline().is_authoritatively_complete());
1966
1967 let mut no_base = baseline();
1969 no_base.weights.base_revision.clear();
1970 assert!(!no_base.is_authoritatively_complete());
1971
1972 let mut no_tok = baseline();
1974 no_tok.tokenizer_hash = None;
1975 assert!(!no_tok.is_authoritatively_complete());
1976 }
1977
1978 #[test]
1979 fn decide_cache_reuse_is_fail_closed() {
1980 use CacheReuseDecision::*;
1981 let exp = baseline().fingerprint();
1982 let other = {
1983 let mut d = baseline();
1984 d.kv_quant = KvQuantMode::Int8;
1985 d.fingerprint()
1986 };
1987
1988 assert_eq!(decide_cache_reuse(Some(&exp), Some(&exp), false), Reuse);
1990 assert_eq!(decide_cache_reuse(Some(&exp), Some(&exp), true), Reuse);
1991
1992 assert_eq!(
1994 decide_cache_reuse(Some(&exp), Some(&other), false),
1995 DiscardAndRecompute
1996 );
1997
1998 assert_eq!(decide_cache_reuse(Some(&exp), None, true), StampFresh);
2000
2001 assert_eq!(
2003 decide_cache_reuse(Some(&exp), None, false),
2004 DiscardAndRecompute
2005 );
2006
2007 assert_eq!(decide_cache_reuse(None, None, true), DiscardAndRecompute);
2010 assert_eq!(
2011 decide_cache_reuse(None, Some(&exp), false),
2012 DiscardAndRecompute
2013 );
2014 assert_eq!(
2015 decide_cache_reuse(None, Some(&exp), true),
2016 DiscardAndRecompute
2017 );
2018 }
2019}