Skip to main content

qualia_core_db/gguf_bridge/qwen35/ftw/
admission.rs

1//! Cold admission with an explicit exporter contract and a reviewed artifact receipt.
2use super::{
3    attention,
4    weights::{self, Nvfp4Projection},
5    LayerPlan, Plan, Profile,
6};
7use crate::inference::moe::ftw_loader::FtwModelPackage;
8use etalon_model::inference::{
9    qwen_attention::{QkNorm, Qwen35AttentionGeometry},
10    qwen_roles::{Qwen35Geometry, Qwen35Packing},
11    TensorInfo,
12};
13use serde_json::Value;
14use sha2::{Digest, Sha256};
15use std::io::Read;
16use std::{path::Path, sync::Arc};
17
18/// Reviewed FreeToken mixed-FP8 exporter: global Q,K,V,Z / B,A blocks;
19/// per-head Q,gate; ordinary RMSNorm +1 folded, gated RMSNorm unchanged.
20/// Source: FreeToken qwen3_5_moe/{weight,gdn,attention}.py. See receipt below.
21#[derive(Clone, Copy, Debug)]
22pub enum ExportContract {
23    FreeTokenQwen35MixedFp8V1,
24}
25
26// This receipt selects semantics, not a model path. Unknown exports require an
27// explicit reviewed contract; matching architecture names never grant admission.
28// Reviewed converter SHA256:
29// weight.py 90f6bafdcf91c52cfbd19de517ea71f7c2642f30672a56e595dd6f49c499cd0a
30// gdn.py 3fe0d06a3ba3aeb65b53bcfbadfddf20ddcd15664820214a91f3c6d10cabc630
31// attention.py d2de35ac0acb47e126d9e793611502bcf12ba920fda95b0918879f1b500804db
32const RECEIPT: [(&str, &str); 3] = [
33    (
34        "freetoken_weight.json",
35        "79bb256dc54229377986d1863f91cb123b43d7d015cc7418ddbf580aa8c9249d",
36    ),
37    (
38        "config.json",
39        "58aefa1c9eff7989f431d748f2ddec39446cb1fd2a69acc46e285c6a37b0cecc",
40    ),
41    (
42        "hf_quant_config.json",
43        "75fe7cc8d5836b58734e05ee67423a4ce91d602aaad45c8173a1b7597cd57663",
44    ),
45];
46const CONFIG_LIMIT: usize = 2 * 1024 * 1024;
47
48fn bounded_read(path: &Path, budget: usize) -> Result<Vec<u8>, String> {
49    let len = usize::try_from(std::fs::metadata(path).map_err(|e| e.to_string())?.len())
50        .map_err(|_| "Qwen metadata size overflow")?;
51    if len > CONFIG_LIMIT || len > budget {
52        return Err("Qwen metadata budget exhausted".into());
53    }
54    let mut file = std::fs::File::open(path).map_err(|e| e.to_string())?;
55    let mut bytes = vec![0; len];
56    file.read_exact(&mut bytes).map_err(|e| e.to_string())?;
57    if file.read(&mut [0]).map_err(|e| e.to_string())? != 0 {
58        return Err("Qwen metadata changed while reading".into());
59    }
60    Ok(bytes)
61}
62
63pub fn admit_known(
64    pkg: Arc<FtwModelPackage>,
65    dir: &Path,
66    max_context: usize,
67    byte_budget: usize,
68) -> Result<Arc<Plan>, String> {
69    let mut verified_config = None;
70    for (name, expected) in RECEIPT {
71        let bytes = bounded_read(&dir.join(name), byte_budget)?;
72        let digest = Sha256::digest(&bytes);
73        let mut encoded = [0u8; 64];
74        for (index, &byte) in digest.iter().enumerate() {
75            encoded[index * 2] = b"0123456789abcdef"[(byte >> 4) as usize];
76            encoded[index * 2 + 1] = b"0123456789abcdef"[(byte & 15) as usize];
77        }
78        if encoded != expected.as_bytes() {
79            return Err(format!("Qwen exporter receipt mismatch: {name}"));
80        }
81        if name == "freetoken_weight.json" {
82            let manifest: crate::inference::moe::ftw_loader::FtwManifest =
83                serde_json::from_slice(&bytes).map_err(|e| e.to_string())?;
84            if manifest.format != pkg.manifest.format
85                || manifest.version != pkg.manifest.version
86                || manifest.quant_format != pkg.manifest.quant_format
87                || manifest.expert_bank_num_layers != pkg.manifest.expert_bank_num_layers
88                || manifest.total_bytes != pkg.manifest.total_bytes
89                || manifest.tensors.len() != pkg.manifest.tensors.len()
90                || manifest.shards.len() != pkg.manifest.shards.len()
91                || manifest
92                    .tensors
93                    .iter()
94                    .zip(&pkg.manifest.tensors)
95                    .any(|(a, b)| {
96                        a.name != b.name
97                            || a.kind != b.kind
98                            || a.dtype != b.dtype
99                            || a.shape != b.shape
100                            || a.nbytes != b.nbytes
101                            || a.global_off != b.global_off
102                    })
103                || manifest
104                    .shards
105                    .iter()
106                    .zip(&pkg.manifest.shards)
107                    .any(|(a, b)| {
108                        a.file != b.file || a.global_off != b.global_off || a.nbytes != b.nbytes
109                    })
110            {
111                return Err("Qwen receipt does not describe retained package".into());
112            }
113        }
114        if name == "config.json" {
115            verified_config = Some(bytes);
116        }
117    }
118    admit_config(
119        pkg,
120        &verified_config.ok_or("Qwen receipt missing config")?,
121        max_context,
122        byte_budget,
123        ExportContract::FreeTokenQwen35MixedFp8V1,
124    )
125}
126
127fn number(v: &Value, key: &str) -> Result<usize, String> {
128    usize::try_from(
129        v[key]
130            .as_u64()
131            .ok_or_else(|| format!("Qwen missing integer {key}"))?,
132    )
133    .map_err(|_| format!("Qwen integer overflow {key}"))
134}
135fn tensor(pkg: &FtwModelPackage, name: &str, shape: &[u64]) -> Result<TensorInfo, String> {
136    let entry = weights::entry(pkg, name).map_err(|e| format!("Qwen {name}: {e:?}"))?;
137    if entry.shape != shape || !matches!(entry.dtype.as_str(), "bfloat16" | "float16" | "float32") {
138        return Err(format!("Qwen scalar tensor shape/encoding {name}"));
139    }
140    let count = shape
141        .iter()
142        .try_fold(1u64, |n, &d| n.checked_mul(d))
143        .ok_or("Qwen tensor size overflow")?;
144    let bytes = count
145        .checked_mul(if entry.dtype == "float32" { 4 } else { 2 })
146        .ok_or("Qwen tensor byte overflow")?;
147    if bytes != entry.nbytes
148        || pkg
149            .fetch_by_global_offset(
150                entry.global_off,
151                usize::try_from(bytes).map_err(|_| "Qwen tensor byte overflow")?,
152            )
153            .is_none()
154    {
155        return Err(format!("Qwen tensor bounds {name}"));
156    }
157    let mut dims = [0; 4];
158    for (slot, &size) in dims.iter_mut().zip(shape.iter().rev()) {
159        *slot = size;
160    }
161    Ok(TensorInfo {
162        dims,
163        n_dims: shape.len() as u32,
164        byte_offset: entry.global_off,
165        ggml_type: match entry.dtype.as_str() {
166            "bfloat16" => crate::ggml_quants::GGML_TYPE_BF16,
167            "float16" => crate::ggml_quants::GGML_TYPE_F16,
168            _ => crate::ggml_quants::GGML_TYPE_F32,
169        },
170    })
171}
172
173pub fn admit(
174    pkg: Arc<FtwModelPackage>,
175    dir: &Path,
176    max_context: usize,
177    byte_budget: usize,
178    _contract: ExportContract,
179) -> Result<Arc<Plan>, String> {
180    let bytes = bounded_read(&dir.join("config.json"), byte_budget)?;
181    admit_config(pkg, &bytes, max_context, byte_budget, _contract)
182}
183
184fn admit_config(
185    pkg: Arc<FtwModelPackage>,
186    bytes: &[u8],
187    max_context: usize,
188    byte_budget: usize,
189    _contract: ExportContract,
190) -> Result<Arc<Plan>, String> {
191    let config: Value = serde_json::from_slice(&bytes).map_err(|e| e.to_string())?;
192    if config["model_type"] != "qwen3_5_moe"
193        || config["architectures"] != serde_json::json!(["Qwen3_5MoeForConditionalGeneration"])
194    {
195        return Err("Qwen architecture contract mismatch".into());
196    }
197    let c = &config["text_config"];
198    // The reviewed FreeToken MoE implementation unconditionally renormalizes
199    // selected softmax weights. An explicitly conflicting config is refused.
200    if c["model_type"] != "qwen3_5_moe_text"
201        || c["attention_bias"] != false
202        || c["attn_output_gate"] != true
203        || c["hidden_act"] != "silu"
204        || (!c["norm_topk_prob"].is_null() && c["norm_topk_prob"] != true)
205    {
206        return Err("Qwen text execution contract mismatch".into());
207    }
208    let h = pkg.tensor_index.hyperparams;
209    let hidden = number(c, "hidden_size")?;
210    let layers = number(c, "num_hidden_layers")?;
211    let vocab = number(c, "vocab_size")?;
212    let experts = number(c, "num_experts")?;
213    let topk = number(c, "num_experts_per_tok")?;
214    let intermediate = number(c, "moe_intermediate_size")?;
215    if hidden != h.n_embd as usize
216        || layers != h.n_layer as usize
217        || layers > 1024
218        || experts != 256
219        || topk == 0
220        || topk > 8
221        || hidden > 16384
222        || intermediate == 0
223        || intermediate > 8192
224        || intermediate % 16 != 0
225        || intermediate != number(c, "shared_expert_intermediate_size")?
226        || max_context == 0
227        || max_context > number(c, "max_position_embeddings")?
228    {
229        return Err("Qwen geometry mismatch".into());
230    }
231    let epsilon = c["rms_norm_eps"].as_f64().ok_or("Qwen missing epsilon")? as f32;
232    if !epsilon.is_finite() || epsilon <= 0.0 {
233        return Err("Qwen invalid epsilon".into());
234    }
235    let rope = &c["rope_parameters"];
236    if rope["rope_type"] != "default" || rope["mrope_interleaved"] != true {
237        return Err("Qwen unsupported rotary contract".into());
238    }
239    let head_dim = number(c, "head_dim")?;
240    if head_dim != h.effective_head_dim() as usize || head_dim > 1024 {
241        return Err("Qwen head dimension config/index mismatch".into());
242    }
243    let partial = rope["partial_rotary_factor"]
244        .as_f64()
245        .ok_or("Qwen missing rotary fraction")?;
246    let theta = rope["rope_theta"]
247        .as_f64()
248        .ok_or("Qwen missing rotary base")?;
249    let rotary = (head_dim as f64) * partial;
250    if !theta.is_finite()
251        || theta <= 0.0
252        || !rotary.is_finite()
253        || rotary.fract() != 0.0
254        || rotary <= 0.0
255        || rotary > head_dim as f64
256        || rotary as usize % 2 != 0
257    {
258        return Err("Qwen invalid rotary geometry".into());
259    }
260    let attention_geometry = Qwen35AttentionGeometry {
261        hidden,
262        query_heads: number(c, "num_attention_heads")?,
263        kv_heads: number(c, "num_key_value_heads")?,
264        head_dim,
265        rotary_dim: rotary as usize,
266    };
267    attention_geometry
268        .validate()
269        .map_err(|e| format!("Qwen attention geometry {e:?}"))?;
270    let linear_geometry = Qwen35Geometry::from_hyperparams(h.into())
271        .map_err(|e| format!("Qwen linear geometry {e:?}"))?;
272    if linear_geometry.key_heads != number(c, "linear_num_key_heads")?
273        || linear_geometry.value_heads != number(c, "linear_num_value_heads")?
274        || linear_geometry.key_dim != number(c, "linear_key_head_dim")?
275        || linear_geometry.value_dim != number(c, "linear_value_head_dim")?
276        || linear_geometry.kernel != number(c, "linear_conv_kernel_dim")?
277    {
278        return Err("Qwen recurrent config/index mismatch".into());
279    }
280    let metadata = layers
281        .checked_mul(std::mem::size_of::<LayerPlan>())
282        .and_then(|n| n.checked_add(std::mem::size_of::<Plan>()))
283        .and_then(|n| n.checked_add((rotary as usize / 2) * 4))
284        .and_then(|n| n.checked_add(pkg.prepared_metadata_bytes()?))
285        .ok_or("Qwen plan budget overflow")?;
286    if metadata > byte_budget {
287        return Err("Qwen plan budget exhausted".into());
288    }
289    let profile = Profile {
290        hidden,
291        layers,
292        vocab,
293        intermediate,
294        experts,
295        topk,
296        max_context,
297        epsilon,
298        linear_geometry,
299        attention_geometry,
300        rotary_inv_freq: (0..rotary as usize / 2)
301            .map(|i| (1.0 / theta.powf((2 * i) as f64 / rotary)) as f32)
302            .collect(),
303        packing: Qwen35Packing::FusedGlobal,
304        ordinary_norm: QkNorm::FoldedMultiplier,
305    };
306    let kinds = c["layer_types"]
307        .as_array()
308        .ok_or("Qwen missing explicit layer schedule")?;
309    if kinds.len() != layers {
310        return Err("Qwen layer schedule mismatch".into());
311    }
312    let mut plans = Vec::with_capacity(layers);
313    for (layer, kind) in kinds.iter().enumerate() {
314        let is_linear = match kind.as_str() {
315            Some("linear_attention") => true,
316            Some("full_attention") => false,
317            _ => return Err("Qwen unsupported layer kind".into()),
318        };
319        let base = format!("model.layers.{layer}");
320        let attention = attention::resolve(&pkg, &profile, layer, is_linear)?;
321        let plan = LayerPlan {
322            attention,
323            input_norm: tensor(
324                &pkg,
325                &format!("{base}.input_layernorm.weight"),
326                &[hidden as u64],
327            )?,
328            post_norm: tensor(
329                &pkg,
330                &format!("{base}.post_attention_layernorm.weight"),
331                &[hidden as u64],
332            )?,
333            router: tensor(
334                &pkg,
335                &format!("{base}.mlp.gate.weight"),
336                &[experts as u64, hidden as u64],
337            )?,
338            shared_gate: tensor(
339                &pkg,
340                &format!("{base}.mlp.shared_expert_gate.weight"),
341                &[1, hidden as u64],
342            )?,
343            shared_up: Nvfp4Projection::admit(
344                &pkg,
345                &format!("{base}.mlp.shared_expert.gate_up_proj"),
346                2 * intermediate,
347                hidden,
348            )
349            .map_err(|e| format!("Qwen shared gate/up {e:?}"))?,
350            shared_down: Nvfp4Projection::admit(
351                &pkg,
352                &format!("{base}.mlp.shared_expert.down_proj"),
353                hidden,
354                intermediate,
355            )
356            .map_err(|e| format!("Qwen shared down {e:?}"))?,
357        };
358        for (name, dtype, shape, expected) in [
359            (
360                "gate_up_packed",
361                "uint8",
362                vec![
363                    experts as u64,
364                    (2 * intermediate) as u64,
365                    (hidden / 2) as u64,
366                ],
367                experts * intermediate * hidden,
368            ),
369            (
370                "gate_up_scale",
371                "float8_e4m3fn",
372                vec![
373                    experts as u64,
374                    (2 * intermediate) as u64,
375                    (hidden / 16) as u64,
376                ],
377                experts * 2 * intermediate * hidden / 16,
378            ),
379            (
380                "gate_up_global",
381                "float16",
382                vec![experts as u64, (2 * intermediate) as u64],
383                experts * 2 * intermediate * 2,
384            ),
385            (
386                "down_packed",
387                "uint8",
388                vec![experts as u64, hidden as u64, (intermediate / 2) as u64],
389                experts * hidden * intermediate / 2,
390            ),
391            (
392                "down_scale",
393                "float8_e4m3fn",
394                vec![experts as u64, hidden as u64, (intermediate / 16) as u64],
395                experts * hidden * intermediate / 16,
396            ),
397            (
398                "down_global",
399                "float16",
400                vec![experts as u64, hidden as u64],
401                experts * hidden * 2,
402            ),
403        ] {
404            let name = format!("{name}#L{layer:05}");
405            let bank =
406                weights::entry(&pkg, &name).map_err(|e| format!("Qwen bank {name}: {e:?}"))?;
407            if bank.dtype != dtype || bank.shape != shape || bank.nbytes != expected as u64 {
408                return Err(format!("Qwen bank encoding/shape {name}"));
409            }
410        }
411        for expert in 0..experts {
412            let data = pkg
413                .get_expert_data(layer as u16, expert as u16)
414                .ok_or("Qwen missing expert bank")?;
415            if data.gate_up_packed.len() != 2 * intermediate * hidden / 2
416                || data.gate_up_scale.len() != 2 * intermediate * hidden / 16
417                || data.gate_up_global.len() != 2 * intermediate * 2
418                || data.down_packed.len() != hidden * intermediate / 2
419                || data.down_scale.len() != hidden * intermediate / 16
420                || data.down_global.len() != hidden * 2
421            {
422                return Err("Qwen expert bank shape mismatch".into());
423            }
424        }
425        plans.push(plan);
426    }
427    let output = Nvfp4Projection::admit(&pkg, "lm_head", vocab, hidden)
428        .map_err(|e| format!("Qwen output {e:?}"))?;
429    let final_norm = tensor(&pkg, "model.norm.weight", &[hidden as u64])?;
430    let embedding = tensor(
431        &pkg,
432        "model.embed_tokens.weight",
433        &[vocab as u64, hidden as u64],
434    )?;
435    Ok(Arc::new(Plan {
436        pkg,
437        profile,
438        layers: plans,
439        output,
440        final_norm,
441        embedding,
442        reserved_bytes: metadata,
443    }))
444}