Skip to main content

hyprstream_inference/runtime/
kv_compat.rs

1//! KV-cache compatibility fingerprint and rejection policy.
2//!
3//! *Epic [#1276](https://github.com/hyprstream/hyprstream/issues/1276),
4//! issue [#1277](https://github.com/hyprstream/hyprstream/issues/1277).*
5//!
6//! KV states are a pure function of (a) the weights that produced them and
7//! (b) every model/runtime parameter that shapes the attention computation.
8//! Reusing KV produced under one configuration inside a request running under
9//! another is a silent correctness bug — the cached keys/values belong to a
10//! different function. This module defines the **authoritative identity** of
11//! that function as a versioned [`KvCompatDescriptor`], reduces it to a stable
12//! content-addressed [`KvCompatFingerprint`], and exposes a [`check_compatibility`]
13//! rejection policy: a cache whose descriptor differs in *any* authoritative
14//! field is rejected (its KV is discarded and recomputed).
15//!
16//! This is the foundational lane item — every later reusable/durable lookup
17//! (cross-session prefix index, snapshot codec, durable store) consumes the
18//! fingerprint defined here. The module deliberately owns **no** `tch`/Cap'n
19//! Proto dependency: it is pure data + hashing, so it is fully unit-testable
20//! without a loaded model. Boundary types (`KVQuantType`, `ModelConfig`) are
21//! converted into the self-contained enums below at the engine seam.
22//!
23//! ## What participates (authoritative inputs)
24//!
25//! Every field of [`KvCompatDescriptor`] is derived from the model/runtime state
26//! that actually produced the KV tensors — never from a human label:
27//!
28//! - **Effective weights** — base-weight **content digest** + adapter/delta
29//!   generation (the live `lora_generation` actually applied to the request).
30//! - **Model identity** — name, architecture (`model_type`), config version.
31//! - **Attention geometry** — layers, KV heads, attention heads, head dim,
32//!   hidden size (determines K/V tensor *shape*).
33//! - **Effective attention behavior** — QK-norm, partial-rotary dimension,
34//!   per-layer local/global layout (`layer_types`), and hybrid/linear-attention
35//!   dimensions (change K/V *values*, not just shape).
36//! - **Position encoding** — RoPE theta, RoPE scaling, max position embeddings
37//!   (determines K *values* post-RoPE).
38//! - **Compute dtype** — the dtype the model computes/stores K/V in.
39//! - **KV storage encoding** — quantization mode in effect.
40//! - **Block geometry** — `BLOCK_SIZE` for paged caches.
41//! - **Context cap** — the effective max context actually bounding the cache.
42//! - **Tokenizer identity** — vocab size + a digest of the tokenizer bytes
43//!   (cached token ids are only meaningful relative to one tokenizer).
44//! - **Format version** — the wire/layout version of the fingerprint itself.
45//!
46//! ## Authority and fail-closed reuse
47//!
48//! A descriptor is only usable to bless a cache when every authoritative axis is
49//! populated ([`KvCompatDescriptor::is_authoritatively_complete`]): the
50//! base-weight content digest and the tokenizer hash. If the loader cannot
51//! obtain the base digest, or tokenizer hashing fails, the engine declines to
52//! mint an expected identity and the cache boundary **fails closed** — KV is
53//! recomputed rather than reused under a guess ([`decide_cache_reuse`]). An
54//! unstamped but populated cache is likewise discarded, never silently adopted.
55//!
56//! ## Relation to TTT delta invalidation
57//!
58//! The registry's existing push-based [`invalidate_for_tenant`][crate::runtime::kv_cache::KVCacheRegistry::invalidate_for_tenant]
59//! clears a tenant's caches when that tenant's LoRA delta changes. The
60//! fingerprint is the complementary **pull-based** guard checked at reuse time;
61//! it does not replace the push path. The descriptor carries an
62//! `adapter_generation` slot that a live counter (issue #1260) will feed so the
63//! pull path also covers per-request delta changes; until then, delta staleness
64//! is handled by the push path, and the fingerprint covers every *other* axis.
65
66use sha2::{Digest, Sha256};
67
68/// Wire/layout format version of the compatibility fingerprint.
69///
70/// Bumped whenever the set of fields that participate in the fingerprint, or
71/// their canonical encoding, changes in a backward-incompatible way. A cache
72/// produced (or persisted) under an older format version is **never** reused —
73/// the rejection policy treats a format-version mismatch as a hard reject.
74///
75/// v3 adds the remaining behavior-affecting effective model configuration:
76/// RMS/LayerNorm epsilon, activation/embedding/attention scaling, MoE routing,
77/// and local-RoPE/sliding-window settings. Two runs with identical weight bytes
78/// and coarse geometry can still produce different KV when any of these differ,
79/// so they are authoritative for reuse.
80///
81/// v2 added `use_qk_norm`, partial rotary dimension, attention layer layout,
82/// and linear-attention dimensions (K/V-value-affecting fields below coarse
83/// geometry).
84pub const KV_COMPAT_FORMAT_VERSION: u32 = 3;
85
86/// Default tokens-per-block for paged KV storage.
87///
88/// This mirrors [`crate::runtime::kv_cache::BLOCK_SIZE`]; the two are asserted
89/// equal by a unit test so the const lives here without pulling the `tch`-backed
90/// `kv_cache` module into this module's dependency graph.
91pub const KV_BLOCK_SIZE_DEFAULT: usize = 256;
92
93// ===========================================================================
94// Effective-weights identity
95// ===========================================================================
96
97/// Authoritative identity of the effective weights (base + adapter/delta) that
98/// produced a cache's KV.
99///
100/// Two caches are reuse-compatible only if their KV was produced under the same
101/// effective weights. This is split from the structural descriptor so a weight
102/// change (e.g. loading/unloading an adapter) is a first-class mismatch reason
103/// distinct from a geometry or dtype change.
104#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
105pub struct WeightIdentity {
106    /// Authoritative identity of the base model weights — a content digest of
107    /// the weight shards actually resolved by the loader (today a SHA-256 over
108    /// the sorted `.safetensors` shard bytes; a git2db content OID when one is
109    /// associated with the loaded worktree, issue #1285). This is **never** a
110    /// human/path label: two snapshots sharing a basename but differing in
111    /// content diverge here. Empty when no authoritative digest could be
112    /// obtained, in which case the descriptor is treated as non-authoritative
113    /// and reuse fails closed (see [`KvCompatDescriptor::is_authoritatively_complete`]).
114    pub base_revision: String,
115    /// Adapter/delta generation active when the KV was produced. `0` means base
116    /// weights only (no adapter). Populated at the per-request reuse boundary
117    /// from the live `lora_generation` counter actually applied to the request,
118    /// so a re-adapted model is detected as incompatible (issue #1260).
119    pub adapter_generation: u64,
120}
121
122impl WeightIdentity {
123    /// Base weights only, no adapter (generation 0).
124    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    /// Effective weights = `base` plus an adapter/delta at `generation`.
132    pub fn with_adapter(mut self, generation: u64) -> Self {
133        self.adapter_generation = generation;
134        self
135    }
136}
137
138/// Mixture-of-experts routing configuration. Different routing changes which
139/// expert FFN each token traverses, and therefore the residual — and thus later
140/// K/V — feeding downstream attention. A dense model (the default) is all-zero.
141#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
142pub struct MoeRouting {
143    /// Whether this is a MoE model (e.g. `model_type` contains `"moe"`).
144    pub is_moe: bool,
145    /// Total number of experts.
146    pub num_experts: usize,
147    /// Experts activated per token (top-k routing).
148    pub num_experts_per_tok: usize,
149    /// Per-expert FFN intermediate size.
150    pub moe_intermediate_size: usize,
151    /// Shared-expert intermediate size (Qwen3.5 MoE), if any.
152    pub shared_expert_intermediate_size: usize,
153}
154
155// ===========================================================================
156// Scalar identity enums (own types, decoupled from codegen/tch)
157// ===========================================================================
158
159/// Compute dtype the model stores K/V in.
160///
161/// Owned by this module (rather than reusing `tch::Kind`) so the fingerprint's
162/// stability does not depend on the `tch` version, and so the module stays
163/// `tch`-free. Unrecognized dtypes fall through to [`KvDtype::Other`], keyed by
164/// a canonicalized name.
165#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
166pub enum KvDtype {
167    Float64,
168    Float32,
169    Float16,
170    #[default]
171    BFloat16,
172    /// Any other dtype, identified by its canonicalized (trimmed, lowercased) name.
173    Other(String),
174}
175
176impl KvDtype {
177    /// Parse a dtype from a HuggingFace `dtype`/`torch_dtype` string, case- and
178    /// alias-insensitive.
179    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    /// Canonical lowercase name used both for [`Display`](std::fmt::Display) and
191    /// as the hashed representation.
192    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/// KV-cache storage encoding / quantization mode.
210///
211/// Mirrors the Cap'n Proto `KVQuantType` (`none`/`int8`/`nf4`/`fp4`) but is
212/// owned here so the fingerprint is independent of schema codegen. Convert at
213/// the engine boundary with a `match`.
214#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
215pub enum KvQuantMode {
216    /// Full precision (FP16/BF16).
217    #[default]
218    None,
219    /// 8-bit integer quantization.
220    Int8,
221    /// 4-bit NormalFloat.
222    Nf4,
223    /// 4-bit FloatingPoint.
224    Fp4,
225}
226
227impl KvQuantMode {
228    /// Canonical lowercase name used for display and hashing.
229    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/// RoPE scaling config, with the factor canonicalized to its IEEE-754 bit
246/// pattern so the descriptor is byte-stable (no `f32` equality pitfalls).
247#[derive(Clone, Debug, PartialEq, Eq, Hash)]
248pub struct RopeScalingFp {
249    /// Canonicalized (trimmed, lowercased) RoPE type, e.g. `"linear"`.
250    pub rope_type: String,
251    /// `f32::to_bits` of the scaling factor.
252    pub factor_bits: u32,
253}
254
255impl RopeScalingFp {
256    /// Construct from a RoPE type string and a scaling factor.
257    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    /// The scaling factor, recovered from its bit pattern.
265    pub fn factor(&self) -> f32 {
266        f32::from_bits(self.factor_bits)
267    }
268}
269
270// ===========================================================================
271// Descriptor
272// ===========================================================================
273
274/// The complete set of authoritative inputs that determine whether KV states
275/// computed under one configuration can be reused under another.
276///
277/// Two caches are compatible **iff** their descriptors are equal in every
278/// field. [`KvCompatFingerprint`] is the content-addressed digest of a canonical
279/// serialization, so equality of fingerprints implies equality of descriptors
280/// (modulo the astronomically unlikely SHA-256 collision). The descriptor is
281/// `Clone + Eq + Hash` and small; the engine retains one (the "expected"
282/// identity of the loaded model) and caches store a [`KvCompatFingerprint`]
283/// stamped at first use.
284#[derive(Clone, Debug, PartialEq, Eq, Hash, Default)]
285pub struct KvCompatDescriptor {
286    /// Fingerprint format/layout version ([`KV_COMPAT_FORMAT_VERSION`]).
287    pub format_version: u32,
288
289    /// Effective weights (base + adapter/delta) identity.
290    pub weights: WeightIdentity,
291
292    /// Loaded model identity (path stem / name).
293    pub model_name: String,
294    /// HuggingFace `model_type` (e.g. `"llama"`, `"qwen2"`).
295    pub architecture: String,
296    /// Parsed config `version`.
297    pub model_version: u32,
298
299    // --- attention geometry (determines K/V tensor shape) ---
300    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    // --- effective attention behavior (changes K/V *values*, not just shape) ---
307    /// QK-norm applied to queries/keys (Gemma3, Qwen3 families). Off vs. on
308    /// normalizes K and changes every downstream value.
309    pub use_qk_norm: bool,
310    /// `f32::to_bits` of the partial-rotary factor. Determines `rotary_dim`
311    /// (`head_dim * factor`), i.e. how much of each key is rotated by RoPE —
312    /// a different factor rotates a different slice of K. `None` = full rotary.
313    pub partial_rotary_factor_bits: Option<u32>,
314    /// Per-layer attention type in layer order (e.g. `"global"`/`"local"`,
315    /// `"full_attention"`/`"linear_attention"`). The local/global layout and any
316    /// local-RoPE behavior change which tokens each layer attends to and thus its
317    /// K/V. Stored lowercased; canonicalized at hash time.
318    pub layer_types: Vec<String>,
319    /// Linear/hybrid-attention state dimensions (Qwen3.5 GatedDeltaNet etc.).
320    /// Non-zero on hybrid models; a different dimension changes the per-layer
321    /// recurrent state that feeds later K/V.
322    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    // --- effective model config (changes hidden states / downstream K/V) ---
329    /// `f32::to_bits` of `rms_norm_eps`. The RMS epsilon changes the normalized
330    /// inputs to Q/K and every layer's residual, so it changes all downstream
331    /// K/V. Stored as bits for byte-stable hashing (no `f32` equality pitfalls).
332    pub rms_norm_eps_bits: u32,
333    /// `f32::to_bits` of `layer_norm_eps` when the architecture uses LayerNorm
334    /// instead of RMSNorm. `None` when LayerNorm is not in effect.
335    pub layer_norm_eps_bits: Option<u32>,
336    /// Activation function (e.g. `"silu"`, `"gelu_pytorch_tanh"`). A different
337    /// activation changes every FFN output and thus the residual feeding later
338    /// K/V. Canonicalized (trimmed, lowercased) at construction.
339    pub hidden_activation: String,
340    /// Whether embeddings are scaled before entering the stack (changes all
341    /// layer inputs and therefore all K/V).
342    pub scale_embeddings: bool,
343    /// `f32::to_bits` of `query_pre_attn_scalar` (Gemma attention logit scale),
344    /// when set. Changes the attention scores and thus the per-layer output.
345    pub query_pre_attn_scalar_bits: Option<u32>,
346    /// MoE routing config. `is_moe == false` and all-zero for a dense model.
347    pub moe: MoeRouting,
348    /// Sliding-window size for local-attention layers (Gemma3), when set.
349    /// Changes which tokens each local layer attends to and thus its K/V.
350    pub sliding_window: Option<usize>,
351    /// `f32::to_bits` of `rope_local_base_freq` (the RoPE theta used in local
352    /// layers, Gemma3), when set. Changes local-layer post-RoPE key values.
353    pub rope_local_base_freq_bits: Option<u32>,
354
355    // --- position encoding (determines K values post-RoPE) ---
356    /// `f32::to_bits` of `rope_theta`.
357    pub rope_theta_bits: u32,
358    /// RoPE scaling, if any.
359    pub rope_scaling: Option<RopeScalingFp>,
360    /// Model's `max_position_embeddings`.
361    pub max_position_embeddings: usize,
362
363    // --- dtype + KV storage encoding ---
364    /// Compute dtype the model stores K/V in.
365    pub dtype: KvDtype,
366    /// KV storage encoding/quantization mode.
367    pub kv_quant: KvQuantMode,
368    /// Tokens per paged block (must match for paged caches).
369    pub block_size: usize,
370    /// Effective runtime context cap actually bounding the cache.
371    pub max_context: usize,
372
373    // --- tokenizer identity (cached token ids are per-tokenizer) ---
374    pub vocab_size: usize,
375    /// Hex digest of the tokenizer bytes, when known.
376    pub tokenizer_hash: Option<String>,
377}
378
379impl KvCompatDescriptor {
380    /// The RoPE theta, recovered from its bit pattern.
381    pub fn rope_theta(&self) -> f32 {
382        f32::from_bits(self.rope_theta_bits)
383    }
384
385    /// Set the RoPE theta from an `f32` (canonicalized to bits).
386    pub fn set_rope_theta(&mut self, theta: f32) {
387        self.rope_theta_bits = theta.to_bits();
388    }
389
390    /// The partial-rotary factor, recovered from its bit pattern (`None` = full rotary).
391    pub fn partial_rotary_factor(&self) -> Option<f32> {
392        self.partial_rotary_factor_bits.map(f32::from_bits)
393    }
394
395    /// Set the partial-rotary factor from an `f32` (canonicalized to bits).
396    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    /// Set the RMS norm epsilon from an `f32` (canonicalized to bits).
401    pub fn set_rms_norm_eps(&mut self, eps: f32) {
402        self.rms_norm_eps_bits = eps.to_bits();
403    }
404
405    /// Set the LayerNorm epsilon from an `f32`, or `None`.
406    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    /// Set the query pre-attention scalar from an `f32`, or `None`.
411    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    /// Set the local-RoPE base frequency from an `f32`, or `None`.
416    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    /// True iff every authoritative identity axis is populated.
421    ///
422    /// A descriptor missing the base-weight digest or the tokenizer identity was
423    /// built from a non-authoritative source and must **not** be used to bless a
424    /// cache for reuse: the engine treats a non-authoritative expected identity
425    /// as fail-closed (discard + recompute) rather than stamping a guess.
426    pub fn is_authoritatively_complete(&self) -> bool {
427        !self.weights.base_revision.is_empty() && self.tokenizer_hash.is_some()
428    }
429
430    /// Record the tokenizer identity (vocab size + digest of its bytes).
431    ///
432    /// Called by the engine once the tokenizer is loaded; the descriptor is
433    /// finalized before any generation reads its fingerprint.
434    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    /// Content-addressed fingerprint of this descriptor.
440    pub fn fingerprint(&self) -> KvCompatFingerprint {
441        KvCompatFingerprint::of(self)
442    }
443
444    /// Rejection policy against an observed (cache-side) descriptor.
445    ///
446    /// Returns the first differing field in a fixed order, or `Ok(())` if the
447    /// descriptors are fully compatible. See [`check_compatibility`].
448    pub fn check_against(&self, observed: &KvCompatDescriptor) -> Result<(), KvCompatMismatch> {
449        check_compatibility(self, observed)
450    }
451
452    /// Feed a canonical, byte-stable serialization of the descriptor into `hash`.
453    ///
454    /// Every variable-length field is length-prefixed and every `Option` is
455    /// tag-prefixed so distinct descriptors never collide (e.g. `"ab"+"c"` is
456    /// distinguishable from `"a"+"bc"`). Little-endian fixed widths for scalars.
457    /// This encoding is what makes persisted fingerprints portable across builds.
458    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        // Effective attention behavior.
475        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        // Effective model config (changes hidden states / downstream K/V).
485        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// ===========================================================================
520// Fingerprint
521// ===========================================================================
522
523/// Content-addressed digest (SHA-256) of a [`KvCompatDescriptor`].
524///
525/// This is what gets stamped on a cache and compared at reuse time — the hot
526/// path checks `cache_fp == expected_fp`, a 32-byte compare. Two caches are
527/// reuse-compatible iff their fingerprints are equal.
528#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
529pub struct KvCompatFingerprint([u8; 32]);
530
531impl KvCompatFingerprint {
532    /// Compute the fingerprint of a descriptor.
533    pub fn of(desc: &KvCompatDescriptor) -> Self {
534        let mut hash = Sha256::new();
535        desc.write_canonical(&mut hash);
536        let digest = hash.finalize();
537        // Copy rather than `.into()` so this is stable across generic-array
538        // versions (digest output is always exactly 32 bytes for SHA-256).
539        let mut out = [0u8; 32];
540        out.copy_from_slice(&digest);
541        Self(out)
542    }
543
544    /// The raw 32-byte digest.
545    pub fn as_bytes(&self) -> &[u8; 32] {
546        &self.0
547    }
548
549    /// Lowercase hex encoding of the digest.
550    pub fn to_hex(&self) -> String {
551        hex::encode(self.0)
552    }
553
554    /// True iff a cache carrying this fingerprint is reuse-compatible with a
555    /// request whose expected fingerprint is `expected`.
556    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// ===========================================================================
574// Rejection policy
575// ===========================================================================
576
577/// Why a cache was rejected for reuse, naming the first differing authoritative
578/// field in a fixed comparison order. Produced by [`check_compatibility`].
579#[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    /// Effective model config (changes hidden states / downstream K/V).
619    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
824/// **Rejection policy**: a cache whose descriptor differs in *any* authoritative
825/// field is rejected.
826///
827/// Compares `expected` (the current model/runtime identity) against `observed`
828/// (the descriptor under which a cache's KV was produced), field by field in a
829/// fixed order, returning the first mismatch. Returns `Ok(())` only when the
830/// descriptors are fully compatible.
831///
832/// At runtime the engine usually compares [`KvCompatFingerprint`]s (a 32-byte
833/// equality) rather than calling this; this function exists to produce a
834/// structured, human-readable rejection reason (for logs, metrics, and tests)
835/// and to pin the exact comparison contract the fingerprint must honor.
836pub 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    // Geometry: report the first diverging dimension.
871    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    // Effective attention behavior (changes K/V *values*, not just shape).
903    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    // `layer_types` is canonicalized (trimmed, lowercased) before hashing
916    // (`put_str_vec`), so compare the canonical forms here too — aliases like
917    // "GLOBAL"/"global" must be compatible in both the hot-path fingerprint and
918    // this structured policy (#1277 review, hot-path/policy equivalence).
919    {
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    // Effective model config — changes hidden states / downstream K/V even when
965    // coarse geometry is identical (#1277 review finding F3).
966    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// ===========================================================================
1080// Reuse decision (fail-closed policy at the cache boundary)
1081// ===========================================================================
1082
1083/// What to do with a cache encountered at the reuse boundary, produced by
1084/// [`decide_cache_reuse`]. The policy is **fail-closed**: it never blesses a
1085/// cache whose KV cannot be proven compatible with an authoritative identity.
1086#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1087pub enum CacheReuseDecision {
1088    /// Cache KV is provably compatible with an authoritative expected identity —
1089    /// reuse it as-is.
1090    Reuse,
1091    /// Cache is empty and carries no stamp, and an authoritative expected
1092    /// identity is available. Stamp it and keep the (empty) cache; prefill will
1093    /// populate it under that identity.
1094    StampFresh,
1095    /// The cache's KV cannot be proven compatible. This covers a stamp mismatch,
1096    /// an **unstamped but populated** cache (produced under an unknown identity),
1097    /// and the absence of any authoritative expected identity. Discard the KV and
1098    /// recompute; stamp with the authoritative identity if one is available.
1099    DiscardAndRecompute,
1100}
1101
1102/// Decide whether a cache may be reused, given the authoritative expected
1103/// identity (if any), the stamp currently on the cache (if any), and whether the
1104/// cache provably carries no KV.
1105///
1106/// Decision matrix (every non-`Reuse` outcome discards KV — fail-closed):
1107///
1108/// | expected | stored  | empty | decision              |
1109/// |----------|---------|-------|-----------------------|
1110/// | Some(e)  | Some(s) | *     | `e == s` ? Reuse : DiscardAndRecompute |
1111/// | Some(_)  | None    | true  | StampFresh            |
1112/// | Some(_)  | None    | false | DiscardAndRecompute   |
1113/// | None     | *       | *     | DiscardAndRecompute   |
1114///
1115/// The unstamped-but-populated and no-authoritative-identity rows are the
1116/// fail-closed guards: a cache we cannot authoritatively attribute is never
1117/// reused, only recomputed.
1118pub 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// ===========================================================================
1131// Canonical byte framing for stable hashing
1132// ===========================================================================
1133
1134#[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    // usize width is platform-dependent; hash it as a fixed u64 so fingerprints
1163    // are stable across 32-/64-bit builds.
1164    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/// Canonicalize a string identifier: trim and ASCII-lowercase. Used everywhere
1196/// a string participates in the fingerprint or the structured comparison so
1197/// aliases ("GLOBAL"/"global") cannot disagree between the two (#1277 review).
1198#[inline]
1199fn canon_str(s: &str) -> String {
1200    s.trim().to_ascii_lowercase()
1201}
1202
1203/// Canonicalized (trimmed, lowercased) copy of a `layer_types` sequence, in
1204/// order. Used by both the hash ([`put_str_vec`]) and the structured comparison
1205/// ([`check_compatibility`]) so they agree on casing/whitespace aliases.
1206fn canonical_layer_types(v: &[String]) -> Vec<String> {
1207    v.iter().map(|s| canon_str(s)).collect()
1208}
1209
1210/// Hash a `Vec<String>` as a length-prefixed sequence of canonicalized
1211/// (trimmed, lowercased) strings so layout casing/order changes are caught.
1212#[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
1220// ===========================================================================
1221// Authoritative base-weight content digest (#1277, finding F1)
1222// ===========================================================================
1223//
1224// The base-weight identity is a content digest over the *resolved* weight shards
1225// the loader actually builds tensors from — never a directory listing or a path
1226// label, and never a pointer stub. Two snapshots sharing a basename but
1227// differing in content diverge here. These pure helpers own the canonical
1228// framing; the engine seam (`TorchEngine::weights_content_digest`) resolves each
1229// shard's bytes (transparently resolving LFS/XET pointers) and feeds them here.
1230
1231/// SHA-256 of a single shard's resolved content bytes.
1232pub 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
1240/// Canonical base-weight digest over a shard set: the shard count, then for each
1241/// shard a length-prefixed filename and that shard's content digest. Emitting
1242/// the count and length-prefixing every name makes distinct shard segmentations
1243/// collide-resistant (shard A+B split at byte N cannot masquerade as a single
1244/// shard, nor can two shard sets of equal total bytes share a digest). Shards
1245/// must be supplied sorted by name for determinism.
1246pub(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    /// A representative, fully-populated descriptor used as the compatibility
1262    /// baseline in the tests below.
1263    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            // Plain Llama: no QK-norm, full rotary, uniform layers, no linear attn.
1276            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            // Effective model config (plain-Llama defaults; non-default below
1285            // diverge the fingerprint in every_authoritative_field_participates).
1286            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    /// Test helper: set one of the linear-attention dimensions by name.
1307    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        // Keeps this module's const in sync with the paged-KV block geometry
1321        // without importing the tch-backed kv_cache module here.
1322        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    /// Asserts that `mutator` produces a descriptor whose fingerprint differs
1341    /// from the baseline, and (when given) the expected mismatch variant.
1342    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        // Weight identity.
1370        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        // Model identity.
1387        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        // Geometry.
1391        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        // Effective attention behavior (changes K/V *values*, not just shape).
1417        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        // layer_types must be compared case-insensitively (canonicalized) — in
1450        // BOTH the fingerprint hash and the structured policy (#1277 MINOR).
1451        {
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            // Equal fingerprints must imply a compatible structured policy:
1463            // casing/whitespace aliases must NOT report a LayerTypes mismatch.
1464            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        // Effective model config — each demonstrably changes hidden states /
1492        // downstream K/V without changing coarse geometry (#1277 F3).
1493        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        // hidden_activation must canonicalize (casing/whitespace) in both the
1518        // hash and the policy — an alias must be compatible, a real change must
1519        // not.
1520        {
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        // MoE routing — each field individually diverges. `is_moe` (bool) and the
1547        // four usize routing fields are exercised separately.
1548        {
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        // Position encoding.
1611        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        // Dtype + encoding.
1638        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        // Tokenizer.
1671        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; // an older/persisted format
1694        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        // The hot path compares fingerprints; assert it agrees with the
1712        // structured policy for both compatible and divergent cases.
1713        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        // Two descriptors differing only by dtype *spelling* must hash equally.
1731        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        // Different factor -> different identity.
1745        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        // Length-prefixing must keep "ab"+"c" distinct from "a"+"bc".
1767        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        // Adapter generation changes the fingerprint.
1820        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    /// Golden digest: pins the exact canonical bytes of a fully-populated
1827    /// descriptor across builds/refactors. If this changes, it is an intentional
1828    /// format bump (`KV_COMPAT_FORMAT_VERSION`) — never a silent drift.
1829    #[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    /// Two weight snapshots sharing a basename but differing in *content* must
1843    /// diverge in base identity (the #1277 "authoritative, not a label" rule).
1844    #[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        // Same content → same fingerprint (stable).
1856        let mut c = baseline();
1857        c.weights.base_revision = "sha256:snapshot-A".into();
1858        assert_eq!(a.fingerprint(), c.fingerprint());
1859    }
1860
1861    // ---- base-weight content digest producer (#1277, finding F1) ----
1862    //
1863    // These exercise the pure framing/digest helpers that the engine seam feeds
1864    // with the *resolved* shard bytes. The fail-closed enumeration + pointer
1865    // resolution is covered by `torch_engine::tests::weights_content_digest_*`.
1866
1867    /// Helper: build a digested shard set (name + per-shard content digest) from
1868    /// raw bytes, mirroring what `TorchEngine::weights_content_digest` produces.
1869    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        // Deterministic.
1881        assert_eq!(shard_content_digest(a), shard_content_digest(a));
1882        // Distinct content → distinct digest.
1883        assert_ne!(shard_content_digest(a), shard_content_digest(b));
1884        // 32 bytes.
1885        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        // Same sorted input → identical digest.
1895        assert_eq!(
1896            base_weight_digest_from_shards(&s),
1897            base_weight_digest_from_shards(&s)
1898        );
1899    }
1900
1901    /// Same basenames, different content → different base-weight digest (the
1902    /// "authoritative, not a label" rule; two snapshots sharing a path stem but
1903    /// differing in bytes must diverge).
1904    #[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    /// Canonical framing must disambiguate shard boundaries: a single shard
1920    /// whose bytes are the concatenation of two others must NOT collide with the
1921    /// two-shard set, even though total bytes are equal.
1922    #[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    /// A different shard count alone (same content, split differently) must
1937    /// diverge — the count is part of the canonical frame.
1938    #[test]
1939    fn base_weight_digest_shard_count_participates() {
1940        // Two shards each carrying the same bytes vs one shard carrying them.
1941        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    /// Renaming a shard (same content, different filename) must diverge — the
1950    /// length-prefixed name is part of the frame.
1951    #[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        // Baseline is fully authoritative.
1965        assert!(baseline().is_authoritatively_complete());
1966
1967        // Missing base-weight digest → not authoritative (fail-closed).
1968        let mut no_base = baseline();
1969        no_base.weights.base_revision.clear();
1970        assert!(!no_base.is_authoritatively_complete());
1971
1972        // Missing tokenizer identity → not authoritative (fail-closed).
1973        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        // Authoritative + matching stamp → reuse.
1989        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        // Authoritative + mismatching stamp → discard.
1993        assert_eq!(
1994            decide_cache_reuse(Some(&exp), Some(&other), false),
1995            DiscardAndRecompute
1996        );
1997
1998        // Authoritative + empty unstamped → stamp fresh and reuse (empty) cache.
1999        assert_eq!(decide_cache_reuse(Some(&exp), None, true), StampFresh);
2000
2001        // Authoritative + POPULATED unstamped → fail-closed discard (the bug fix).
2002        assert_eq!(
2003            decide_cache_reuse(Some(&exp), None, false),
2004            DiscardAndRecompute
2005        );
2006
2007        // No authoritative identity at all → always discard, even on an empty
2008        // unstamped cache (nothing to bless) and even on a stamped cache.
2009        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}