1use 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
12pub struct AdmittedEnvelope<'a> {
18 view: StructuralView<'a>,
19 limits: ProfileLimits,
20}
21
22impl<'a> AdmittedEnvelope<'a> {
23 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 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 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 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 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#[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 pub const fn is_signal_waveform_entry(self) -> bool {
377 matches!(self, Self::PcmPreservation | Self::StftPreservation)
378 }
379}
380
381#[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 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