qualia_core_db/q42/p64_weight/
reader.rs

1//! Runtime **reader / loader**: `P64TensorIndex` (parse + integrity policy), weight/tokenizer/
2//! manifold access, GGUF-equivalent index synthesis for the hot path, GGUF round-trip validation,
3//! `IntegrityMode`, and the convert-layout recommender.
4
5use super::*;
6use crate::gguf_sharder::{GgufHyperparams, GgufTensorIndex, GgufTensorInfo};
7
8// CRC-32C (Castagnoli, reflected) — delegated to the shared
9// `container_10d::crc32c` module (P0.3 consolidation). The algorithm is
10// byte-identical to the previous in-line implementation; the p64 round-trip
11// tests verify the checksums are unchanged after delegation.
12use crate::container_10d::crc32c::crc32c;
13
14/// Runtime reader: parses a P64 container's header + manifest in microseconds. Tensor blobs
15/// stay in the caller's byte slice (zero-copy); only the small manifest is materialized. The
16/// `role`/`layer`/`blob_offset` fields map directly to the resident WebGPU weight arenas.
17#[derive(Clone)]
18pub struct P64TensorIndex {
19    pub header: P64WeightHeader,
20    pub hparams: P64HParams,
21    pub entries: Vec<P64TensorEntry>,
22}
23
24pub type Q42TensorIndex = P64TensorIndex;
25
26/// How thoroughly [`P64TensorIndex::from_p64`] verifies integrity.
27///
28/// Full tensor CRCs over a 360M–3B container dominate activate latency (toolkit probe:
29/// ~3 s after table CRC optim, previously ~42 s table-less). Convert and audit use
30/// [`IntegrityMode::Full`]; hot activate may use [`IntegrityMode::Metadata`] after a
31/// trusted convert wrote the container on this machine.
32#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
33pub enum IntegrityMode {
34    /// Metadata CRC + every tensor blob CRC (safest; slow on large models).
35    Full,
36    /// Metadata CRC only; still bounds-checks tensor ranges (**default activate**).
37    #[default]
38    Metadata,
39    /// Structure checks only — no CRC. Prefer only for tests / trusted mmap.
40    Structure,
41}
42
43impl IntegrityMode {
44    /// `QUALIA_P64_INTEGRITY=full|metadata|structure`.
45    ///
46    /// **Default is [`Metadata`]** (bounds + metadata CRC only): convert already sealed
47    /// per-tensor CRCs, and full re-scan dominated activate (~2.4 s → ~9 ms on SmolLM2).
48    /// Use `full` for audit / untrusted download; `structure` for tests only.
49    pub fn from_env() -> Self {
50        match std::env::var("QUALIA_P64_INTEGRITY")
51            .ok()
52            .as_deref()
53            .map(str::trim)
54            .map(|s| s.to_ascii_lowercase())
55            .as_deref()
56        {
57            Some("full") | Some("strict") | Some("all") => Self::Full,
58            Some("structure") | Some("struct") | Some("skip") | Some("none") => Self::Structure,
59            Some("metadata") | Some("meta") | Some("fast") | None => Self::Metadata,
60            Some(_) => Self::Metadata,
61        }
62    }
63}
64
65/// Recommend convert layout from source size (bytes on disk) and a VRAM headroom budget.
66///
67/// Heuristic:
68/// 1. **F16Expand** when Q4→f16 estimate (`source * 4`) fits under `vram * 0.55` and the
69///    4 GiB p64 offset cap — best decode path for small/mid models.
70/// 2. Else **Q4kSoa** for mid/large Q4 containers (SoA is ~11% larger than Q4_K; always
71///    under the f16 budget). Decode GEMV drops scale-unpack barriers.
72/// 3. Else **Verbatim**.
73pub fn recommend_convert_layout(source_bytes: u64, vram_budget_bytes: u64) -> P64ConvertLayout {
74    let est_f16 = source_bytes.saturating_mul(4);
75    let room = (vram_budget_bytes as f64 * 0.55) as u64;
76    if est_f16 > 0 && est_f16 < room && est_f16 < (4u64 << 30) {
77        P64ConvertLayout::F16Expand
78    } else if source_bytes > 256 * 1024 * 1024 {
79        // >256 MiB: almost certainly Q4-class weights where SoA pays off.
80        P64ConvertLayout::Q4kSoa
81    } else {
82        P64ConvertLayout::Verbatim
83    }
84}
85
86impl P64TensorIndex {
87    pub fn from_q42(data: &[u8]) -> Result<Self, String> {
88        Self::from_p64(data)
89    }
90    pub fn from_p64(data: &[u8]) -> Result<Self, String> {
91        Self::from_p64_with_integrity(data, IntegrityMode::from_env())
92    }
93
94    /// Parse a P64 container with an explicit integrity policy.
95    pub fn from_p64_with_integrity(data: &[u8], integrity: IntegrityMode) -> Result<Self, String> {
96        let header = P64WeightHeader::read_le(data)?;
97        if header.magic != P64_MAGIC {
98            return Err("p64: invalid magic".to_string());
99        }
100        if header.version != P64_VERSION {
101            return Err(format!("p64: unsupported version {}", header.version));
102        }
103        if header.flags & P64_FLAG_LITTLE_ENDIAN == 0 {
104            return Err("p64: non-little-endian container is unsupported".to_string());
105        }
106        let page = header.page_size as usize;
107        if page < 256 || !page.is_power_of_two() {
108            return Err("p64: invalid page size".to_string());
109        }
110        let hparams_start = header.hparams_offset as usize;
111        let hparams_end = hparams_start
112            .checked_add(64)
113            .ok_or("p64: hyperparameter offset overflow")?;
114        if hparams_end > data.len() {
115            return Err("p64: hyperparameters out of bounds".to_string());
116        }
117        let hparams = P64HParams::read_le(&data[hparams_start..hparams_end])?;
118
119        let tensor_count = header.tensor_count as usize;
120        let tensor_table_start = header.tensor_table_offset as usize;
121        let tensor_table_end = tensor_table_start
122            .checked_add(
123                tensor_count
124                    .checked_mul(P64_TENSOR_ENTRY_BYTES)
125                    .ok_or("p64: tensor table overflow")?,
126            )
127            .ok_or("p64: tensor table overflow")?;
128        let string_table_start = header.string_table_offset as usize;
129        let manifold_table_start = header.manifold_table_offset as usize;
130        let manifold_count = hparams
131            .n_layer
132            .checked_add(1)
133            .ok_or("p64: manifold count overflow")? as usize;
134        let manifold_table_end = manifold_table_start
135            .checked_add(
136                manifold_count
137                    .checked_mul(P64_MANIFOLD_ENTRY_BYTES)
138                    .ok_or("p64: manifold table overflow")?,
139            )
140            .ok_or("p64: manifold table overflow")?;
141        let tokenizer_start = header.tokenizer_offset as usize;
142        let checksum_start = header.checksum_offset as usize;
143        let checksum_end = checksum_start
144            .checked_add(
145                tensor_count
146                    .checked_add(1)
147                    .and_then(|count| count.checked_mul(4))
148                    .ok_or("p64: checksum table overflow")?,
149            )
150            .ok_or("p64: checksum table overflow")?;
151        if tensor_table_start < hparams_end
152            || tensor_table_end > string_table_start
153            || string_table_start > manifold_table_start
154            || manifold_table_end > tokenizer_start
155            || tokenizer_start > checksum_start
156            || checksum_end > data.len()
157        {
158            return Err("p64: metadata sections overlap or are out of bounds".to_string());
159        }
160        if manifold_table_start % 64 != 0 {
161            return Err("p64: manifold table is not cache-line aligned".to_string());
162        }
163        if !matches!(integrity, IntegrityMode::Structure) {
164            let stored_metadata_crc =
165                u32::from_le_bytes(data[checksum_start..checksum_start + 4].try_into().unwrap());
166            if crc32c(&data[..checksum_start]) != stored_metadata_crc {
167                return Err("p64: metadata CRC-32C mismatch".to_string());
168            }
169        }
170
171        let mut entries = Vec::with_capacity(tensor_count);
172        let mut cursor = header.tensor_table_offset as usize;
173        let blob_floor = align_up(checksum_end, page);
174        let mut previous_blob_end = blob_floor;
175        let mut previous_manifold_idx = None;
176        let layer_packed = header.flags & P64_FLAG_LAYER_PACK != 0;
177        let verify_tensor_crc = matches!(integrity, IntegrityMode::Full);
178        for tensor_index in 0..tensor_count {
179            if cursor + P64_TENSOR_ENTRY_BYTES > data.len() {
180                return Err("p64: truncated tensor table".to_string());
181            }
182            let bytes = &data[cursor..cursor + P64_TENSOR_ENTRY_BYTES];
183            let eu32 = |o: usize| u32::from_le_bytes(bytes[o..o + 4].try_into().unwrap());
184            let eu16 = |o: usize| u16::from_le_bytes(bytes[o..o + 2].try_into().unwrap());
185            let eu64 = |o: usize| u64::from_le_bytes(bytes[o..o + 8].try_into().unwrap());
186            let entry = P64TensorEntry {
187                name_offset: eu32(0),
188                role_id: eu16(4),
189                dtype: eu16(6),
190                manifold_idx: eu32(8),
191                rank: eu32(12),
192                dimensions: [eu32(16), eu32(20), eu32(24), eu32(28)],
193                blob_offset: eu32(32),
194                blob_size: eu32(36),
195                source_offset: eu64(40),
196                source_name_hash: eu64(48),
197                alt_dtype: eu16(56),
198                precision_views_mask: eu16(58),
199                alt_blob_offset: eu32(60),
200            };
201            if !(1..=4).contains(&entry.rank) {
202                return Err(format!("p64: tensor {tensor_index} has invalid rank"));
203            }
204            if entry.manifold_idx as usize >= manifold_count {
205                return Err(format!(
206                    "p64: tensor {tensor_index} has invalid manifold index"
207                ));
208            }
209            let name_start = string_table_start
210                .checked_add(entry.name_offset as usize)
211                .ok_or("p64: tensor name offset overflow")?;
212            if name_start >= manifold_table_start
213                || !data[name_start..manifold_table_start].contains(&0)
214            {
215                return Err(format!("p64: tensor {tensor_index} has invalid name"));
216            }
217            let blob_start = entry.blob_offset as usize;
218            let blob_end = blob_start
219                .checked_add(entry.blob_size as usize)
220                .ok_or("p64: tensor blob overflow")?;
221            let required_alignment = if layer_packed
222                && tensor_index > 0
223                && previous_manifold_idx == Some(entry.manifold_idx)
224            {
225                256
226            } else {
227                page
228            };
229            if blob_start % required_alignment != 0
230                || blob_start < previous_blob_end
231                || blob_end > data.len()
232            {
233                return Err(format!(
234                    "p64: tensor {tensor_index} is unaligned, overlapping, or out of bounds"
235                ));
236            }
237            if verify_tensor_crc {
238                let crc_start = checksum_start + 4 + tensor_index * 4;
239                let stored_crc =
240                    u32::from_le_bytes(data[crc_start..crc_start + 4].try_into().unwrap());
241                if crc32c(&data[blob_start..blob_end]) != stored_crc {
242                    return Err(format!("p64: tensor {tensor_index} CRC-32C mismatch"));
243                }
244            }
245            previous_blob_end = blob_end;
246            previous_manifold_idx = Some(entry.manifold_idx);
247            entries.push(entry);
248            cursor += P64_TENSOR_ENTRY_BYTES;
249        }
250        Ok(Self {
251            header,
252            hparams,
253            entries,
254        })
255    }
256
257    pub fn hyperparams(&self) -> GgufHyperparams {
258        GgufHyperparams {
259            n_layer: self.hparams.n_layer,
260            n_embd: self.hparams.n_embd,
261            n_head: self.hparams.n_head,
262            n_kv_head: self.hparams.n_kv_head,
263            rope_freq_base: self.hparams.rope_freq_base,
264            rope_scale: self.hparams.rope_scale,
265            head_dim: self.hparams.head_dim,
266            head_dim_swa: self.hparams.head_dim_swa,
267            sliding_window: self.hparams.sliding_window,
268            shared_kv_layers: self.hparams.shared_kv_layers,
269            logit_softcap: self.hparams.logit_softcap,
270            architecture: self.hparams.architecture,
271            arch_flags: self.hparams.arch_flags,
272        }
273    }
274
275    pub fn blob<'a>(&self, data: &'a [u8], entry: &P64TensorEntry) -> &'a [u8] {
276        let start = entry.blob_offset as usize;
277        &data[start..start + entry.blob_size as usize]
278    }
279
280    pub fn tokenizer_bytes<'a>(&self, data: &'a [u8]) -> &'a [u8] {
281        let start = self.header.tokenizer_offset as usize;
282        let end = self.header.checksum_offset as usize;
283        if start <= data.len() && end <= data.len() && start <= end {
284            &data[start..end]
285        } else {
286            &[]
287        }
288    }
289
290    pub fn manifold_coordinate(
291        &self,
292        data: &[u8],
293        index: u32,
294    ) -> Result<crate::modalities::manifold::ManifoldCoordinate10D, String> {
295        if index > self.hparams.n_layer {
296            return Err("p64: manifold index out of bounds".to_string());
297        }
298        let start = (self.header.manifold_table_offset as usize)
299            .checked_add(index as usize * P64_MANIFOLD_ENTRY_BYTES)
300            .ok_or("p64: manifold offset overflow")?;
301        let end = start + P64_MANIFOLD_ENTRY_BYTES;
302        if end > data.len() {
303            return Err("p64: manifold coordinate out of bounds".to_string());
304        }
305        crate::modalities::manifold::ManifoldCoordinate10D::from_p64_bytes(&data[start..end])
306    }
307
308    /// Build a GGUF-equivalent index for the existing inference hot path.
309    pub fn to_gguf_index(&self) -> GgufTensorIndex {
310        let mut named: Vec<(Vec<u8>, GgufTensorInfo)> = Vec::with_capacity(self.entries.len());
311        for entry in &self.entries {
312            let name = if entry.manifold_idx == self.hparams.n_layer {
313                match entry.role_id {
314                    P64_ROLE_TOKEN_EMBD => b"token_embd.weight".to_vec(),
315                    P64_ROLE_OUTPUT => b"output.weight".to_vec(),
316                    P64_ROLE_OUTPUT_NORM => b"output_norm.weight".to_vec(),
317                    _ => continue,
318                }
319            } else if let Some(suffix) = p64_role_suffix(entry.role_id) {
320                let mut buffer = [0u8; 96];
321                let length = crate::gguf_sharder::write_blk_tensor_name(
322                    entry.manifold_idx,
323                    suffix,
324                    &mut buffer,
325                );
326                buffer[..length].to_vec()
327            } else {
328                continue;
329            };
330            named.push((
331                name,
332                GgufTensorInfo {
333                    dims: entry.dimensions.map(u64::from),
334                    n_dims: entry.rank,
335                    ggml_type: entry.dtype as u32,
336                    byte_offset: entry.blob_offset as u64,
337                },
338            ));
339        }
340        let references: Vec<(&[u8], GgufTensorInfo)> = named
341            .iter()
342            .map(|(name, info)| (name.as_slice(), *info))
343            .collect();
344        GgufTensorIndex::from_components(&references, self.hyperparams(), 0)
345    }
346
347    /// Prove that a parsed P64 contains every GGUF tensor with identical shape,
348    /// type and bytes. This is a cold-path validation routine and intentionally
349    /// performs a complete byte comparison in addition to the stored CRCs.
350    pub fn validate_against_gguf(
351        &self,
352        p64_data: &[u8],
353        gguf_data: &[u8],
354    ) -> Result<P64RoundTripReport, String> {
355        let source = GgufTensorIndex::from_gguf(gguf_data);
356        if source.entries.len() != self.entries.len() {
357            return Err(format!(
358                "p64: tensor count differs (GGUF {}, P64 {})",
359                source.entries.len(),
360                self.entries.len()
361            ));
362        }
363        let source_data_start = source.tensor_data_start as usize;
364        let mut tensor_bytes = 0u64;
365        for (position, entry) in self.entries.iter().enumerate() {
366            let (source_name_hash, source_info) = source
367                .entries
368                .iter()
369                .find(|(_, info)| info.byte_offset == entry.source_offset)
370                .ok_or_else(|| format!("p64: tensor {position} source offset is missing"))?;
371            if *source_name_hash != entry.source_name_hash
372                || source_info.ggml_type != entry.dtype as u32
373                || source_info.n_dims != entry.rank
374                || source_info.dims != entry.dimensions.map(u64::from)
375            {
376                return Err(format!("p64: tensor {position} metadata differs from GGUF"));
377            }
378            let source_len = crate::ggml_quants::tensor_byte_len(source_info)
379                .ok_or_else(|| format!("p64: tensor {position} has unsupported source type"))?;
380            if source_len != entry.blob_size as usize {
381                return Err(format!("p64: tensor {position} byte length differs"));
382            }
383            let source_start = source_data_start + source_info.byte_offset as usize;
384            let source_end = source_start + source_len;
385            if source_end > gguf_data.len()
386                || self.blob(p64_data, entry) != &gguf_data[source_start..source_end]
387            {
388                return Err(format!("p64: tensor {position} bytes differ from GGUF"));
389            }
390            tensor_bytes += source_len as u64;
391        }
392        Ok(P64RoundTripReport {
393            tensor_count: self.entries.len(),
394            tensor_bytes,
395            manifold_count: self.hparams.n_layer as usize + 1,
396        })
397    }
398}
399
400#[derive(Clone, Copy, Debug, PartialEq, Eq)]
401pub struct P64RoundTripReport {
402    pub tensor_count: usize,
403    pub tensor_bytes: u64,
404    pub manifold_count: usize,
405}
qualia_core_db/q42/p64_weight/reader.rs

qualia_core_db/q42/p64_weight/
reader.rs
