Skip to main content

qualia_core_db/gguf_bridge/qwen35/
mod.rs

1//! Explicit developer/lab admission of one Qwen3.5 linear layer.
2//! This is not whole-model decode admission. Packing and ordinary norm storage
3//! are caller-selected source contracts; no exporter-version heuristic is used.
4#[cfg(not(target_arch = "wasm32"))]
5pub mod ftw;
6#[cfg(not(target_arch = "wasm32"))]
7pub(crate) mod gguf;
8mod source;
9#[cfg(test)]
10mod tests;
11
12use super::QTensorEngine;
13use etalon_inference::ordinary::qwen35::{self, Host, WorkspaceLayout, weights::CpuByteHost};
14use etalon_model::inference::{
15    TensorInfo,
16    qwen_roles::{Qwen35Packing, Qwen35Roles},
17};
18use source::RetainedBytes;
19
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub enum OrdinaryNorm {
22    /// HF checkpoint stores gamma minus one.
23    RawZeroCentered,
24    /// Exporter already added one to the checkpoint weight.
25    AlreadyFolded,
26}
27
28#[derive(Debug, Clone, Copy)]
29pub struct Profile {
30    pub packing: Qwen35Packing,
31    pub ordinary_norm: OrdinaryNorm,
32    pub epsilon: f32,
33}
34
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum Error {
37    MissingSource,
38    MissingNorm,
39    AmbiguousNorm,
40    Budget,
41    Execution(qwen35::Error),
42}
43impl From<qwen35::Error> for Error {
44    fn from(e: qwen35::Error) -> Self {
45        Self::Execution(e)
46    }
47}
48
49/// Cold owned execution buffers plus retained exact source owners. Dropping or
50/// replacing the engine cannot redirect these descriptors to another model.
51/// Only validated native prepared owners or explicit immutable leases enter.
52pub struct PreparedLinearLayer {
53    source: RetainedBytes,
54    roles: Qwen35Roles,
55    profile: Profile,
56    norm: Vec<f32>,
57    normalized: Vec<f32>,
58    history: Vec<f32>,
59    state: Vec<f32>,
60    workspace: Vec<f32>,
61    reserved_bytes: usize,
62}
63
64impl QTensorEngine {
65    /// Explicit CPU lab operation; does not grant native Webizen inference
66    /// permissions, install fallback policy, or admit the full architecture.
67    /// Budget covers newly owned buffers and this owner; payload is retained,
68    /// never copied. Existing source-loader memory is caller-owned separately.
69    pub fn prepare_qwen35_linear_layer(
70        &self,
71        layer: u32,
72        profile: Profile,
73        byte_budget: usize,
74    ) -> Result<PreparedLinearLayer, Error> {
75        let metadata = self.qwen35_metadata_reservation()?;
76        let available = byte_budget.checked_sub(metadata).ok_or(Error::Budget)?;
77        let mut prepared = self.prepare_qwen35_with_factory(layer, profile, available, || {
78            RetainedBytes::from_engine(self)
79        })?;
80        prepared.reserved_bytes += metadata;
81        Ok(prepared)
82    }
83
84    /// Explicit lab custody: independently selected full-file identities must
85    /// already have been verified by ModelLease. FTW leases use manifest order.
86    /// Monolithic GGUF/P64 leases must already be bound by native preparation;
87    /// this method never reparses an unbounded replacement directory.
88    /// Does not activate the model or allocate a full-model KV/recurrent arena.
89    pub fn prepare_qwen35_linear_from_leases(
90        &self,
91        layer: u32,
92        profile: Profile,
93        byte_budget: usize,
94        primary: std::sync::Arc<etalon_model_io::lease::ModelLease>,
95        shards: &[std::sync::Arc<etalon_model_io::lease::ModelLease>],
96    ) -> Result<PreparedLinearLayer, Error> {
97        let metadata = self.qwen35_metadata_reservation()?;
98        let available = byte_budget.checked_sub(metadata).ok_or(Error::Budget)?;
99        let mut prepared = self.prepare_qwen35_with_factory(layer, profile, available, || {
100            RetainedBytes::from_leases(self, primary, shards)
101        })?;
102        prepared.reserved_bytes += metadata;
103        Ok(prepared)
104    }
105
106    fn qwen35_metadata_reservation(&self) -> Result<usize, Error> {
107        let directory = self
108            .tensor_index_cache
109            .as_ref()
110            .ok_or(Error::MissingSource)?
111            .entries
112            .capacity()
113            .checked_mul(128)
114            .ok_or(Error::Budget)?;
115        self.ftw_package
116            .as_ref()
117            .map_or(Some(0), |p| p.prepared_metadata_bytes())
118            .ok_or(Error::Budget)?
119            .checked_add(directory)
120            .ok_or(Error::Budget)
121    }
122
123    #[cfg(test)]
124    fn prepare_qwen35_with_source(
125        &self,
126        layer: u32,
127        profile: Profile,
128        byte_budget: usize,
129        source: RetainedBytes,
130    ) -> Result<PreparedLinearLayer, Error> {
131        self.prepare_qwen35_with_factory(layer, profile, byte_budget, || Ok(source))
132    }
133
134    fn prepare_qwen35_with_factory(
135        &self,
136        layer: u32,
137        profile: Profile,
138        byte_budget: usize,
139        source: impl FnOnce() -> Result<RetainedBytes, Error>,
140    ) -> Result<PreparedLinearLayer, Error> {
141        let index = self
142            .tensor_index_cache
143            .as_ref()
144            .ok_or(Error::MissingSource)?;
145        if layer >= index.hyperparams.n_layer {
146            return Err(qwen35::Error::Shape.into());
147        }
148        let roles = Qwen35Roles::resolve(index, layer, profile.packing)
149            .map_err(|e| Error::Execution(qwen35::Error::Roles(e)))?;
150        let norm_info = ordinary_norm(index, layer)?;
151        let layout = WorkspaceLayout::checked(roles.geometry)?;
152        let hidden = roles.geometry.hidden;
153        if norm_info.n_dims != 1 || norm_info.dims[0] != hidden as u64 {
154            return Err(qwen35::Error::Shape.into());
155        }
156        if !profile.epsilon.is_finite() || profile.epsilon <= 0.0 {
157            return Err(qwen35::Error::Shape.into());
158        }
159        let floats = hidden
160            .checked_mul(2)
161            .and_then(|n| n.checked_add(layout.history))
162            .and_then(|n| n.checked_add(layout.recurrent))
163            .and_then(|n| n.checked_add(layout.floats))
164            .ok_or(Error::Budget)?;
165        let required = floats
166            .checked_mul(4)
167            .and_then(|n| n.checked_add(std::mem::size_of::<PreparedLinearLayer>()))
168            .ok_or(Error::Budget)?;
169        if required > byte_budget {
170            return Err(Error::Budget);
171        }
172        let source = source()?;
173        let host = CpuByteHost { source: &source };
174        let mut norm = vec![0.0; hidden];
175        host.read(&norm_info, &mut norm)?;
176        if !norm.iter().all(|v| v.is_finite()) {
177            return Err(qwen35::Error::Provider.into());
178        }
179        let mut prepared = PreparedLinearLayer {
180            source,
181            roles,
182            profile,
183            norm,
184            normalized: vec![0.0; hidden],
185            history: vec![0.0; layout.history],
186            state: vec![0.0; layout.recurrent],
187            workspace: vec![0.0; layout.floats],
188            reserved_bytes: required,
189        };
190        prepared.validate_weights(layout)?;
191        Ok(prepared)
192    }
193}
194
195impl PreparedLinearLayer {
196    fn validate_weights(&mut self, layout: WorkspaceLayout) -> Result<(), Error> {
197        use etalon_model::inference::qwen_roles::Qwen35Projections;
198        self.roles
199            .validate()
200            .map_err(|e| Error::Execution(qwen35::Error::Roles(e)))?;
201        let host = CpuByteHost {
202            source: &self.source,
203        };
204        let admitted = match &self.roles.projections {
205            Qwen35Projections::Separate { qkv, z, a, b } => {
206                [qkv, z, a, b].into_iter().all(|p| host.admits(p))
207            }
208            Qwen35Projections::Fused { qkvz, ba, .. } => {
209                [qkvz, ba].into_iter().all(|p| host.admits(p))
210            }
211        };
212        if !admitted || !host.admits(&self.roles.out) {
213            return Err(qwen35::Error::UnsupportedProjection.into());
214        }
215        let g = self.roles.geometry;
216        for (info, count) in [
217            (&self.roles.conv, layout.conv_weights),
218            (&self.roles.a_log, g.value_heads),
219            (&self.roles.dt_bias, g.value_heads),
220            (&self.roles.norm, g.value_dim),
221        ] {
222            let out = &mut self.workspace[..count];
223            out.fill(f32::NAN);
224            host.read(info, out)?;
225            if !out.iter().all(|v| v.is_finite()) {
226                return Err(qwen35::Error::Provider.into());
227            }
228        }
229        Ok(())
230    }
231    pub fn reserved_bytes(&self) -> usize {
232        self.reserved_bytes
233    }
234    pub fn roles(&self) -> &Qwen35Roles {
235        &self.roles
236    }
237    pub fn profile(&self) -> Profile {
238        self.profile
239    }
240    pub fn recurrent_state(&self) -> &[f32] {
241        &self.state
242    }
243    pub fn convolution_history(&self) -> &[f32] {
244        &self.history
245    }
246    pub fn reset(&mut self) {
247        self.history.fill(0.0);
248        self.state.fill(0.0);
249    }
250    /// One linear-attention residual step, with no per-step allocation. FFN,
251    /// full attention layers, tokenizer, sampling and policy remain outside.
252    /// On error hidden/history/recurrent state remain unchanged.
253    pub fn step(&mut self, hidden: &mut [f32]) -> Result<(), Error> {
254        if hidden.len() != self.norm.len() || !hidden.iter().all(|x| x.is_finite()) {
255            return Err(qwen35::Error::Shape.into());
256        }
257        qwen35::ordinary_rms_norm(
258            hidden,
259            &self.norm,
260            self.profile.ordinary_norm == OrdinaryNorm::RawZeroCentered,
261            self.profile.epsilon,
262            &mut self.normalized,
263        )?;
264        qwen35::execute_normalized(
265            &CpuByteHost {
266                source: &self.source,
267            },
268            &self.roles,
269            &self.normalized,
270            hidden,
271            &mut self.history,
272            &mut self.state,
273            self.profile.epsilon,
274            &mut self.workspace,
275        )?;
276        Ok(())
277    }
278}
279
280fn ordinary_norm(
281    index: &crate::gguf_sharder::GgufTensorIndex,
282    layer: u32,
283) -> Result<TensorInfo, Error> {
284    let mut found = None;
285    let mut name = [0u8; 128];
286    for writer in [
287        etalon_model::inference::write_hf_layer_tensor_name,
288        etalon_model::inference::write_blk_tensor_name,
289    ] {
290        let n = writer(layer, b"input_layernorm.weight", &mut name);
291        let hash = etalon_model::gguf::fnv1a64(&name[..n]);
292        for &(_, info) in index.entries.iter().filter(|(key, _)| *key == hash) {
293            if found.is_some_and(|old| old != info) {
294                return Err(Error::AmbiguousNorm);
295            }
296            found = Some(info);
297        }
298    }
299    found.ok_or(Error::MissingNorm)
300}