Skip to main content

qualia_core_db/audio/qac/profiles/
envelope.rs

1//! Zero-heap QAC v1 structural admission helpers, field extractors, and re-exported builder APIs.
2
3use crate::q42::{
4    field_envelope::{Block, Entry, Family, Field, StructuralView},
5    field_semantics as sem,
6};
7
8pub use super::builder::*;
9use super::registry::QacProfileRegistry;
10use super::types::*;
11
12// ---------------------------------------------------------------------------
13// Zero-heap admitted structural view & field extractors
14// ---------------------------------------------------------------------------
15
16/// Verified structural QAC v1 reader anchored to caller or bounded scratch.
17pub struct AdmittedEnvelope<'a> {
18    view: StructuralView<'a>,
19    limits: ProfileLimits,
20}
21
22impl<'a> AdmittedEnvelope<'a> {
23    /// Zero-heap admission into caller-owned scratch (`metadata` >= blocks, `entries` >= entry_count).
24    pub fn open<'s>(
25        bytes: &'a [u8],
26        scratch: &'s mut sem::Scratch<'_>,
27        limits: ProfileLimits,
28    ) -> Result<Self, ProfileError> {
29        let view = StructuralView::open(bytes, Family::QacV1Candidate, limits.envelope)?;
30        let _ = sem::admit_shared(&view, &QacProfileRegistry, scratch, limits.semantics)?;
31        Ok(Self { view, limits })
32    }
33
34    /// Cold bounded helper allocating `Vec<sem::NodeState>` capped by `limits`.
35    pub fn open_alloc(bytes: &'a [u8], limits: ProfileLimits) -> Result<Self, ProfileError> {
36        let view = StructuralView::open(bytes, Family::QacV1Candidate, limits.envelope)?;
37        let block_count = view.blocks().count();
38        let entry_count = view.entry_count() as usize;
39        let mut m = vec![sem::NodeState::default(); block_count];
40        let mut e = vec![sem::NodeState::default(); entry_count];
41        let mut scratch = sem::Scratch {
42            metadata: &mut m,
43            entries: &mut e,
44        };
45        let _ = sem::admit_shared(&view, &QacProfileRegistry, &mut scratch, limits.semantics)?;
46        Ok(Self { view, limits })
47    }
48
49    pub fn view(&self) -> &StructuralView<'a> {
50        &self.view
51    }
52
53    pub fn entry(&self, index: u32) -> Result<Entry<'a>, ProfileError> {
54        Ok(self.view.entry(index)?)
55    }
56
57    pub fn verify_chunk(&self, index: u32) -> Result<&'a [u8], ProfileError> {
58        let e = self.view.entry(index)?;
59        if e.record_count() > self.limits.max_records_per_chunk {
60            return Err(ProfileError::LimitExceeded);
61        }
62        Ok(self.view.verify_chunk(index)?)
63    }
64
65    pub fn block(&self, id: u32) -> Result<Block<'a>, ProfileError> {
66        self.view
67            .blocks()
68            .find(|b| b.id() == id)
69            .ok_or(ProfileError::Semantics(sem::Error::Reference))
70    }
71
72    pub fn descriptor_for_entry(&self, entry: Entry<'_>) -> Result<Block<'a>, ProfileError> {
73        let desc = self.block(entry.descriptor_id())?;
74        if desc.schema_type() != 3 {
75            return Err(ProfileError::Semantics(sem::Error::ReferenceSchema));
76        }
77        Ok(desc)
78    }
79
80    pub fn extension_block(
81        &self,
82        descriptor: Block<'_>,
83        schema_type: u16,
84    ) -> Result<Option<Block<'a>>, ProfileError> {
85        let Some(f) = descriptor.fields().find(|f| f.key() == 18) else {
86            return Ok(None);
87        };
88        for chunk in f.value().chunks_exact(4) {
89            let id = u32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]);
90            let blk = self.block(id)?;
91            if blk.schema_type() == schema_type {
92                return Ok(Some(blk));
93            }
94        }
95        Ok(None)
96    }
97
98    pub fn find_entry_indices_by_mode(&self, mode: u16) -> Vec<u32> {
99        let n = self.view.entry_count();
100        let mut out = Vec::new();
101        for idx in 1..=n {
102            if let Ok(e) = self.view.entry(idx) {
103                if e.mode() == mode {
104                    out.push(idx);
105                }
106            }
107        }
108        out
109    }
110
111    /// Reads optional validity mask (`key 16` -> `mode 0x0106`) and verifies whole-chunk digest.
112    pub fn read_validity_mask(&self, descriptor: Block<'_>, record_count: u64) -> Result<Option<&'a [u8]>, ProfileError> {
113        let Some(vm_field) = field_opt(descriptor, 16) else {
114            return Ok(None);
115        };
116        let mask_idx = field_u32(vm_field)?;
117        let mask_entry = self.entry(mask_idx)?;
118        if mask_entry.mode() != MODE_VALIDITY_MASK || mask_entry.stride() != 1 {
119            return Err(ProfileError::Semantics(sem::Error::Validity));
120        }
121        let bytes = self.verify_chunk(mask_idx)?;
122        if bytes.len() as u64 != record_count {
123            return Err(ProfileError::Semantics(sem::Error::Validity));
124        }
125        Ok(Some(bytes))
126    }
127
128    /// Validates descriptor tensor shape (`Schema 205` key 14), channels/scalar consistency,
129    /// and verifies whole chunk payload digest.
130    pub fn check_structured_entry(
131        &self,
132        entry_idx: u32,
133        expected_mode: u16,
134        expected_stride: u32,
135        require_medium: bool,
136        required_extension_schema: Option<u16>,
137    ) -> Result<(Entry<'a>, Block<'a>, &'a [u8], Option<&'a [u8]>), ProfileError> {
138        let e = self.entry(entry_idx)?;
139        if e.mode() != expected_mode {
140            return Err(ProfileError::InvalidMode(e.mode()));
141        }
142        if e.stride() != expected_stride {
143            return Err(ProfileError::InvalidStride {
144                expected: expected_stride,
145                actual: e.stride(),
146            });
147        }
148        let desc = self.descriptor_for_entry(e)?;
149        if require_medium && field_opt(desc, 4).is_none() {
150            return Err(ProfileError::MediumMissingOrUnknown("descriptor key 4 (medium) is required"));
151        }
152        // Mixed structured modes omit scalar (key 11) and channels (key 9).
153        if field_opt(desc, 9).is_some() || field_opt(desc, 11).is_some() {
154            return Err(ProfileError::InvalidMetadata("structured mode must omit scalar/channels"));
155        }
156        let grid_blk = self
157            .extension_block(desc, 205)?
158            .ok_or(ProfileError::MissingRequiredSchema(205))?;
159        let shape = field_u64_vec(field_req(grid_blk, 14)?)?;
160        let prod = checked_shape_product(&shape)?;
161        if prod != e.record_count() {
162            return Err(ProfileError::InvalidMetadata("tensor_shape product disagrees with record_count"));
163        }
164        if let Some(ext_schema) = required_extension_schema {
165            if self.extension_block(desc, ext_schema)?.is_none() {
166                return Err(ProfileError::MissingRequiredSchema(ext_schema));
167            }
168        }
169        let payload = self.verify_chunk(entry_idx)?;
170        let expected_bytes = e
171            .record_count()
172            .checked_mul(u64::from(expected_stride))
173            .ok_or(ProfileError::Overflow)?;
174        if payload.len() as u64 != expected_bytes {
175            return Err(ProfileError::InvalidPayloadLength);
176        }
177        let mask = self.read_validity_mask(desc, e.record_count())?;
178        Ok((e, desc, payload, mask))
179    }
180
181    pub fn read_clock(&self, id: u32) -> Result<ClockSpec, ProfileError> {
182        let b = self.block(id)?;
183        if b.schema_type() != 1 {
184            return Err(ProfileError::Semantics(sem::Error::ReferenceSchema));
185        }
186        let spec = ClockSpec {
187            scale: field_u32(field_req(b, 1)?)?,
188            epoch_seconds: field_i64(field_req(b, 2)?)?,
189            epoch_nanoseconds: field_u32(field_req(b, 3)?)?,
190            ticks_per_second: RationalRate::new(
191                field_u64(field_req(b, 4)?)?,
192                field_u64(field_req(b, 5)?)?,
193            )?,
194        };
195        spec.validate()?;
196        Ok(spec)
197    }
198
199    pub fn read_instant(&self, id: u32) -> Result<(InstantSpec, ClockSpec), ProfileError> {
200        let b = self.block(id)?;
201        if b.schema_type() != 5 {
202            return Err(ProfileError::Semantics(sem::Error::ReferenceSchema));
203        }
204        let clk_id = field_u32(field_req(b, 1)?)?;
205        let clk = self.read_clock(clk_id)?;
206        let inst = InstantSpec::new(
207            clk_id,
208            field_i64(field_req(b, 2)?)?,
209            field_u64(field_req(b, 3)?)?,
210            field_u64(field_req(b, 4)?)?,
211        )?;
212        Ok((inst, clk))
213    }
214
215    pub fn read_frame_quaternion(&self, id: u32) -> Result<QuaternionXyzw, ProfileError> {
216        let b = self.block(id)?;
217        if b.schema_type() != 2 {
218            return Err(ProfileError::Semantics(sem::Error::ReferenceSchema));
219        }
220        let f = field_req(b, 4)?;
221        let vals = field_f64_vec(f)?;
222        if vals.len() != 4 {
223            return Err(ProfileError::InvalidQuaternion);
224        }
225        QuaternionXyzw::from_xyzw([vals[0], vals[1], vals[2], vals[3]])
226    }
227}
228
229pub fn checked_shape_product(shape: &[u64]) -> Result<u64, ProfileError> {
230    if shape.is_empty() {
231        return Err(ProfileError::InvalidMetadata("empty tensor_shape"));
232    }
233    let mut prod = 1u64;
234    for &d in shape {
235        if d == 0 {
236            return Err(ProfileError::InvalidMetadata("zero tensor_shape axis"));
237        }
238        prod = prod.checked_mul(d).ok_or(ProfileError::Overflow)?;
239    }
240    Ok(prod)
241}
242
243pub fn field_opt<'a>(block: Block<'a>, key: u16) -> Option<Field<'a>> {
244    block.fields().find(|f| f.key() == key)
245}
246
247pub fn field_req<'a>(block: Block<'a>, key: u16) -> Result<Field<'a>, ProfileError> {
248    field_opt(block, key).ok_or(ProfileError::Semantics(sem::Error::MissingField))
249}
250
251pub fn field_str<'a>(f: Field<'a>) -> Result<&'a str, ProfileError> {
252    let s = std::str::from_utf8(f.value()).map_err(|_| ProfileError::InvalidMetadata("utf8"))?;
253    if has_control_chars(s) {
254        return Err(ProfileError::InvalidMetadata("control-char-in-identifier"));
255    }
256    Ok(s)
257}
258
259pub fn field_u32(f: Field<'_>) -> Result<u32, ProfileError> {
260    read_u32(f.value(), 0).map_err(|_| ProfileError::InvalidMetadata("u32"))
261}
262
263pub fn field_u64(f: Field<'_>) -> Result<u64, ProfileError> {
264    read_u64(f.value(), 0).map_err(|_| ProfileError::InvalidMetadata("u64"))
265}
266
267pub fn field_i64(f: Field<'_>) -> Result<i64, ProfileError> {
268    let b = f.value();
269    if b.len() != 8 {
270        return Err(ProfileError::InvalidMetadata("i64"));
271    }
272    Ok(i64::from_le_bytes([
273        b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7],
274    ]))
275}
276
277pub fn field_f64(f: Field<'_>) -> Result<f64, ProfileError> {
278    let b = f.value();
279    if b.len() != 8 {
280        return Err(ProfileError::InvalidMetadata("f64"));
281    }
282    let v = f64::from_le_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]);
283    require_finite_f64(v)
284}
285
286pub fn field_f64_vec(f: Field<'_>) -> Result<Vec<f64>, ProfileError> {
287    if f.value().len() % 8 != 0 {
288        return Err(ProfileError::InvalidMetadata("f64[]"));
289    }
290    let mut out = Vec::with_capacity(f.value().len() / 8);
291    for c in f.value().chunks_exact(8) {
292        let v = f64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7]]);
293        out.push(require_finite_f64(v)?);
294    }
295    Ok(out)
296}
297
298pub fn field_u64_vec(f: Field<'_>) -> Result<Vec<u64>, ProfileError> {
299    if f.value().len() % 8 != 0 {
300        return Err(ProfileError::InvalidMetadata("u64[]"));
301    }
302    Ok(f.value()
303        .chunks_exact(8)
304        .map(|c| u64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7]]))
305        .collect())
306}
307
308pub fn field_i64_vec(f: Field<'_>) -> Result<Vec<i64>, ProfileError> {
309    if f.value().len() % 8 != 0 {
310        return Err(ProfileError::InvalidMetadata("i64[]"));
311    }
312    Ok(f.value()
313        .chunks_exact(8)
314        .map(|c| i64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7]]))
315        .collect())
316}
317
318pub fn field_bytes32(f: Field<'_>) -> Result<[u8; 32], ProfileError> {
319    let b = f.value();
320    if b.len() != 32 {
321        return Err(ProfileError::InvalidMetadata("bytes[32]"));
322    }
323    let mut out = [0u8; 32];
324    out.copy_from_slice(b);
325    Ok(out)
326}
327
328// ---------------------------------------------------------------------------
329// Unified QAC v1 entry router (signal preservation + domain profiles)
330// ---------------------------------------------------------------------------
331
332/// Disambiguated QAC v1 entry kind across Schema 210 signal preservation (`0x0100`/`0x0101`/`0x0104`)
333/// and Q03-Q07 scientific domain profiles (`0x0000`/`0x0001`/`0x0003`/`0x0102`..=`0x0107`).
334#[derive(Debug, Clone, Copy, PartialEq, Eq)]
335pub enum AdmittedEntryKind {
336    PcmPreservation,
337    StftPreservation,
338    OpaqueSource,
339    PressureVelocity,
340    ElasticStressVelocity,
341    HoaSpatial,
342    HrirImpulse,
343    RayContribution,
344    ModalResonance,
345    PerceptualFeatures,
346    HapticSample,
347    UltrasoundSummary,
348    RawRfIq,
349    ValidityMask,
350    AuxiliaryArray,
351}
352
353impl AdmittedEntryKind {
354    pub const fn as_str(self) -> &'static str {
355        match self {
356            Self::PcmPreservation => "pcm-preservation",
357            Self::StftPreservation => "stft-preservation",
358            Self::OpaqueSource => "opaque-source",
359            Self::PressureVelocity => "pressure-velocity",
360            Self::ElasticStressVelocity => "elastic-stress-velocity",
361            Self::HoaSpatial => "hoa-spatial",
362            Self::HrirImpulse => "hrir-impulse",
363            Self::RayContribution => "ray-contribution",
364            Self::ModalResonance => "modal-resonance",
365            Self::PerceptualFeatures => "perceptual-features",
366            Self::HapticSample => "haptic-sample",
367            Self::UltrasoundSummary => "ultrasound-summary",
368            Self::RawRfIq => "raw-rf-iq",
369            Self::ValidityMask => "validity-mask",
370            Self::AuxiliaryArray => "auxiliary-array",
371        }
372    }
373
374    /// Only Schema 210 signal preservation entries (`0x0100`/`0x0101`) expose direct PCM/STFT
375    /// sample windows; domain profiles require explicit scientific synthesis outside storage.
376    pub const fn is_signal_waveform_entry(self) -> bool {
377        matches!(self, Self::PcmPreservation | Self::StftPreservation)
378    }
379}
380
381/// Verified QAC v1 entry metadata summary from `AdmittedEnvelope`.
382#[derive(Debug, Clone, Copy, PartialEq, Eq)]
383pub struct AdmittedEntrySummary<'a> {
384    pub kind: AdmittedEntryKind,
385    pub mode: u16,
386    pub quantity: &'a str,
387    pub units: &'a str,
388    pub purpose: &'a str,
389    pub model_uri: Option<&'a str>,
390    pub channels: Option<u32>,
391    pub has_validity_mask: bool,
392}
393
394impl<'a> AdmittedEnvelope<'a> {
395    /// Classifies and verifies an entry's descriptor + required extension block markers across
396    /// all QAC v1 modes (`0x0000`, `0x0001`, `0x0003`, `0x0100`..=`0x0107`) without touching raw sample playback.
397    pub fn inspect_entry_summary(
398        &self,
399        index: u32,
400    ) -> Result<AdmittedEntrySummary<'a>, ProfileError> {
401        let e = self.entry(index)?;
402        let desc = self.descriptor_for_entry(e)?;
403        let quantity = field_str(field_req(desc, 7)?)?;
404        let units = field_str(field_req(desc, 8)?)?;
405        let purpose = field_str(field_req(desc, 12)?)?;
406        let channels = field_opt(desc, 9).map(field_u32).transpose()?;
407        let has_validity_mask = field_opt(desc, 16).is_some();
408        let model_uri = self
409            .extension_block(desc, 205)?
410            .and_then(|b| field_opt(b, 1))
411            .map(field_str)
412            .transpose()?;
413
414        let kind = match e.mode() {
415            MODE_PRESSURE_VELOCITY => AdmittedEntryKind::PressureVelocity,
416            MODE_ELASTIC_STRESS_VELOCITY => AdmittedEntryKind::ElasticStressVelocity,
417            MODE_RAY_CONTRIBUTION => AdmittedEntryKind::RayContribution,
418            MODE_PCM_PRESERVATION => AdmittedEntryKind::PcmPreservation,
419            MODE_STFT_PRESERVATION => AdmittedEntryKind::StftPreservation,
420            MODE_HOA_SPATIAL => AdmittedEntryKind::HoaSpatial,
421            MODE_HRIR_IMPULSE => AdmittedEntryKind::HrirImpulse,
422            0x0104 => {
423                if self.extension_block(desc, 206)?.is_some() {
424                    AdmittedEntryKind::ModalResonance
425                } else if model_uri == Some("urn:qualia:qac:opaque-original:1") {
426                    AdmittedEntryKind::OpaqueSource
427                } else {
428                    return Err(ProfileError::InvalidMode(e.mode()));
429                }
430            }
431            0x0105 => {
432                if self.extension_block(desc, 203)?.is_some() {
433                    AdmittedEntryKind::PerceptualFeatures
434                } else if self.extension_block(desc, 208)?.is_some()
435                    || model_uri == Some("urn:qac:mode:0x0105:ultrasound-raw:v1")
436                {
437                    AdmittedEntryKind::RawRfIq
438                } else {
439                    return Err(ProfileError::InvalidMode(e.mode()));
440                }
441            }
442            0x0106 => {
443                if self.extension_block(desc, 207)?.is_some() {
444                    AdmittedEntryKind::HapticSample
445                } else if e.stride() == 1 {
446                    AdmittedEntryKind::ValidityMask
447                } else {
448                    return Err(ProfileError::InvalidMode(e.mode()));
449                }
450            }
451            0x0107 => {
452                if self.extension_block(desc, 208)?.is_some() {
453                    AdmittedEntryKind::UltrasoundSummary
454                } else {
455                    AdmittedEntryKind::AuxiliaryArray
456                }
457            }
458            other => return Err(ProfileError::InvalidMode(other)),
459        };
460
461        Ok(AdmittedEntrySummary {
462            kind,
463            mode: e.mode(),
464            quantity,
465            units,
466            purpose,
467            model_uri,
468            channels,
469            has_validity_mask,
470        })
471    }
472}
473