Skip to main content

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};
7pub use etalon_model::p64::convert::P64RoundTripReport;
8
9/// Runtime reader: parses a P64 container's header + manifest in microseconds. Tensor blobs
10/// stay in the caller's byte slice (zero-copy); only the small manifest is materialized. The
11/// `role`/`layer`/`blob_offset` fields map directly to the resident WebGPU weight arenas.
12#[derive(Clone)]
13pub struct P64TensorIndex {
14    pub header: P64WeightHeader,
15    pub hparams: P64HParams,
16    pub entries: Vec<P64TensorEntry>,
17}
18
19pub type Q42TensorIndex = P64TensorIndex;
20
21/// How thoroughly [`P64TensorIndex::from_p64`] verifies integrity.
22///
23/// Full tensor CRCs over a 360M–3B container dominate activate latency (toolkit probe:
24/// ~3 s after table CRC optim, previously ~42 s table-less). Convert and audit use
25/// [`IntegrityMode::Full`]; hot activate may use [`IntegrityMode::Metadata`] after a
26/// trusted convert wrote the container on this machine.
27#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
28pub enum IntegrityMode {
29    /// Metadata CRC + every tensor blob CRC (safest; slow on large models).
30    Full,
31    /// Metadata CRC only; still bounds-checks tensor ranges (**default activate**).
32    #[default]
33    Metadata,
34    /// Structure checks only — no CRC. Prefer only for tests / trusted mmap.
35    Structure,
36}
37
38impl IntegrityMode {
39    /// `QUALIA_P64_INTEGRITY=full|metadata|structure`.
40    ///
41    /// **Default is `Metadata()`** (bounds + metadata CRC only): convert already sealed
42    /// per-tensor CRCs, and full re-scan dominated activate (~2.4 s → ~9 ms on SmolLM2).
43    /// Use `full` for audit / untrusted download; `structure` for tests only.
44    pub fn from_env() -> Self {
45        match std::env::var("QUALIA_P64_INTEGRITY")
46            .ok()
47            .as_deref()
48            .map(str::trim)
49            .map(|s| s.to_ascii_lowercase())
50            .as_deref()
51        {
52            Some("full") | Some("strict") | Some("all") => Self::Full,
53            Some("structure") | Some("struct") | Some("skip") | Some("none") => Self::Structure,
54            Some("metadata") | Some("meta") | Some("fast") | None => Self::Metadata,
55            Some(_) => Self::Metadata,
56        }
57    }
58}
59
60/// Recommend convert layout from source size (bytes on disk) and a VRAM headroom budget.
61///
62/// Heuristic:
63/// 1. **F16Expand** when Q4→f16 estimate (`source * 4`) fits under `vram * 0.55` and the
64///    4 GiB p64 offset cap — best decode path for small/mid models.
65/// 2. Else **Q4kSoa** for mid/large Q4 containers (SoA is ~11% larger than Q4_K; always
66///    under the f16 budget). Decode GEMV drops scale-unpack barriers.
67/// 3. Else **Verbatim**.
68pub fn recommend_convert_layout(source_bytes: u64, vram_budget_bytes: u64) -> P64ConvertLayout {
69    let est_f16 = source_bytes.saturating_mul(4);
70    let room = (vram_budget_bytes as f64 * 0.55) as u64;
71    if est_f16 > 0 && est_f16 < room && est_f16 < (4u64 << 30) {
72        P64ConvertLayout::F16Expand
73    } else if source_bytes > 256 * 1024 * 1024 {
74        // >256 MiB: almost certainly Q4-class weights where SoA pays off.
75        P64ConvertLayout::Q4kSoa
76    } else {
77        P64ConvertLayout::Verbatim
78    }
79}
80
81impl P64TensorIndex {
82    /// Prepare the native inference directory while retaining authoritative P64 bytes.
83    /// Metadata extensions are explicit because the fixed v4 header has no recurrent/PLE fields.
84    pub fn prepare_native<'a>(
85        data: &'a [u8],
86        integrity: IntegrityMode,
87        budget: etalon_model::inference::ModelPreparationBudget,
88        metadata: Option<etalon_model::inference::ModelMetadata>,
89    ) -> Result<
90        etalon_model::inference::PreparedP64<'a, GgufHyperparams>,
91        etalon_model::inference::PrepareModelError,
92    > {
93        let integrity = match integrity {
94            IntegrityMode::Full => etalon_model::p64::IntegrityMode::Full,
95            IntegrityMode::Metadata => etalon_model::p64::IntegrityMode::Metadata,
96            IntegrityMode::Structure => etalon_model::p64::IntegrityMode::Structure,
97        };
98        etalon_model::inference::PreparedP64::parse(data, integrity, budget, metadata)
99    }
100
101    /// Parses a tensor index from a `.q42` volume blob; `Err` on malformed header/directory.
102    pub fn from_q42(data: &[u8]) -> Result<Self, String> {
103        Self::from_p64(data)
104    }
105    /// Parses a tensor index from raw `.p64` bytes.
106    pub fn from_p64(data: &[u8]) -> Result<Self, String> {
107        Self::from_p64_with_integrity(data, IntegrityMode::from_env())
108    }
109
110    /// Parse a P64 container with an explicit integrity policy.
111    pub fn from_p64_with_integrity(data: &[u8], integrity: IntegrityMode) -> Result<Self, String> {
112        super::etalon_adapter::parse_owned(data, integrity)
113    }
114
115    /// Model hyperparameters decoded from the index header.
116    pub fn hyperparams(&self) -> GgufHyperparams {
117        GgufHyperparams {
118            n_layer: self.hparams.n_layer,
119            n_embd: self.hparams.n_embd,
120            n_head: self.hparams.n_head,
121            n_kv_head: self.hparams.n_kv_head,
122            rope_freq_base: self.hparams.rope_freq_base,
123            rope_scale: self.hparams.rope_scale,
124            head_dim: self.hparams.head_dim,
125            head_dim_swa: self.hparams.head_dim_swa,
126            sliding_window: self.hparams.sliding_window,
127            shared_kv_layers: self.hparams.shared_kv_layers,
128            logit_softcap: self.hparams.logit_softcap,
129            ssm_conv_kernel: 0,
130            ssm_state_size: 0,
131            ssm_group_count: 0,
132            ssm_time_step_rank: 0,
133            ssm_inner_size: 0,
134            full_attention_interval: 0,
135            architecture: self.hparams.architecture,
136            arch_flags: self.hparams.arch_flags,
137            ..GgufHyperparams::default()
138        }
139    }
140
141    /// Zero-copy tensor byte slice for `entry` within `data`.
142    #[inline]
143    pub fn blob<'a>(&self, data: &'a [u8], entry: &P64TensorEntry) -> &'a [u8] {
144        entry.blob_slice(data).unwrap_or_else(|| {
145            let start = entry.blob_offset as usize;
146            &data[start..start + entry.blob_size as usize]
147        })
148    }
149
150    /// Zero-copy tokenizer blob within `data`.
151    #[inline]
152    pub fn tokenizer_bytes<'a>(&self, data: &'a [u8]) -> &'a [u8] {
153        self.header.tokenizer_slice(data)
154    }
155
156    /// Manifold coordinate for a tensor entry (bridges neutral 64B P64 record to Q42 `ManifoldCoordinate10D`).
157    pub fn manifold_coordinate(
158        &self,
159        data: &[u8],
160        index: u32,
161    ) -> Result<crate::modalities::manifold::ManifoldCoordinate10D, String> {
162        let record = self
163            .header
164            .manifold_record_slice(data, self.hparams.n_layer, index)?;
165        crate::modalities::manifold::ManifoldCoordinate10D::from_p64_bytes(record)
166    }
167
168    /// Build a GGUF-equivalent index for the existing inference hot path.
169    pub fn to_gguf_index(&self) -> GgufTensorIndex {
170        etalon_model::p64::convert::synthesize_gguf_index(
171            &self.entries,
172            self.hparams.n_layer,
173            self.hyperparams(),
174        )
175    }
176
177    /// Prove that a parsed P64 contains every GGUF tensor with identical shape,
178    /// type and bytes. This is a cold-path validation routine and intentionally
179    /// performs a complete byte comparison in addition to the stored CRCs.
180    pub fn validate_against_gguf(
181        &self,
182        p64_data: &[u8],
183        gguf_data: &[u8],
184    ) -> Result<P64RoundTripReport, String> {
185        etalon_model::p64::convert::validate_p64_against_gguf(
186            &self.entries,
187            self.hparams.n_layer,
188            p64_data,
189            gguf_data,
190        )
191    }
192}