Skip to main content

qualia_core_db/audio/qac/signal/
view.rs

1use super::samples::finite;
2use super::*;
3use crate::audio::qac::metadata::{
4    self as meta, OriginBasis, SignalRegistry, Transform, TransformKind,
5};
6use crate::q42::{
7    field_envelope::{Block, Entry, Family, StructuralView},
8    field_semantics::{self as sem, Context},
9};
10#[derive(Clone, Copy, Debug)]
11pub struct SignalView<'a> {
12    pub(super) payload: &'a [u8],
13    pub(super) mode: u16,
14    pub(super) scalar: Scalar,
15    pub(super) channels: u32,
16    pub(super) bins: u32,
17    pub(super) records: u64,
18    pub(super) stream_id: u32,
19    pub(super) frame_id: u32,
20    pub(super) timing: Option<Timing>,
21    pub(super) transform: Option<Transform>,
22    pub(super) window_coefficients_le: Option<&'a [u8]>,
23    pub(super) channel_order: &'a str,
24    pub(super) purpose: &'a str,
25    pub(super) relation: &'a str,
26    pub(super) quantity: &'a str,
27    pub(super) units: &'a str,
28    pub(super) units_per_stored_sample: f64,
29    pub(super) stored_offset: f64,
30}
31fn extension<'a>(d: Block<'a>, schema: u16, ctx: &Context<'_, 'a>) -> Result<Block<'a>, Error> {
32    let mut found = None;
33    for raw in meta::get(d, 18)?.value().chunks_exact(4) {
34        let block = ctx.block(u32::from_le_bytes(raw.try_into().unwrap()))?;
35        if block.schema_type() == schema {
36            if found.is_some() {
37                return Err(Error::Profile);
38            }
39            found = Some(block);
40        }
41    }
42    found.ok_or(Error::Profile)
43}
44fn labels(s: &str, n: u32, ctx: &Context<'_, '_>) -> Result<(), Error> {
45    ctx.charge_work(
46        (s.len() as u64)
47            .checked_mul(u64::from(n) + 1)
48            .ok_or(Error::Overflow)?,
49    )?;
50    let mut count = 0u32;
51    for (i, label) in s.split(',').enumerate() {
52        if label.is_empty() || label.trim() != label || s.split(',').take(i).any(|old| old == label)
53        {
54            return Err(Error::Profile);
55        }
56        count = count.checked_add(1).ok_or(Error::Overflow)?;
57    }
58    if count != n {
59        return Err(Error::Shape);
60    }
61    Ok(())
62}
63fn inspect<'a>(
64    index: u32,
65    e: Entry<'a>,
66    payload: &'a [u8],
67    ctx: &Context<'_, 'a>,
68) -> Result<SignalView<'a>, Error> {
69    if e.revision() != 1 || ![0x100, 0x101, 0x104].contains(&e.mode()) {
70        return Err(Error::Unsupported);
71    }
72    let d = ctx.require_schema(e.descriptor_id(), 3)?;
73    for key in [9, 10, 11, 18] {
74        if meta::get(d, key)?.flags() & 1 == 0 {
75            return Err(Error::Profile);
76        }
77    }
78    let model = meta::text(d, 12)?;
79    let scalar = Scalar::from_code(meta::u32v(d, 11)?)?;
80    let channels = meta::u32v(d, 9)?;
81    if channels == 0 {
82        return Err(Error::Shape);
83    }
84    let shape = extension(d, 205, ctx)?;
85    if shape.revision() != 1 || meta::text(shape, 1)? != model || meta::text(shape, 2)? != "1" {
86        return Err(Error::Profile);
87    }
88    let dimensions = meta::get(shape, 14)?.value();
89    let n = dimensions.len() / 8;
90    let dim = |i: usize| u64::from_le_bytes(dimensions[i * 8..i * 8 + 8].try_into().unwrap());
91    let quantity = meta::text(d, 7)?;
92    let units = meta::text(d, 8)?;
93    let layout = meta::text(d, 10)?;
94    let mut result = SignalView {
95        payload,
96        mode: e.mode(),
97        scalar,
98        channels,
99        bins: 1,
100        records: e.record_count(),
101        stream_id: e.stream_id(),
102        frame_id: e.frame_id(),
103        timing: None,
104        transform: None,
105        window_coefficients_le: None,
106        channel_order: "",
107        purpose: "",
108        relation: "",
109        quantity,
110        units,
111        units_per_stored_sample: 1.0,
112        stored_offset: 0.0,
113    };
114    if e.mode() == 0x104 {
115        if model != "urn:qualia:qac:opaque-original:1"
116            || quantity != "original_bytes"
117            || units != "1"
118            || scalar != Scalar::U8
119            || channels != 1
120            || layout != "byte"
121            || n != 1
122            || dim(0) != e.record_count()
123            || e.flags() & 2 != 0
124            || sem::field(d, 5).is_some()
125            || sem::field(d, 6).is_some()
126            || meta::text(shape, 15)? != "byte"
127        {
128            return Err(Error::Profile);
129        }
130    } else {
131        if e.flags() & 2 == 0 || e.time_count() != e.record_count() {
132            return Err(Error::Clock);
133        }
134        let clock = ctx.require_schema(meta::u32v(d, 1)?, 1)?;
135        result.timing = Some(Timing {
136            scale: meta::u32v(clock, 1)?,
137            epoch_seconds: meta::u64v(clock, 2)? as i64,
138            epoch_nanoseconds: meta::u32v(clock, 3)?,
139            ticks: Rate::new(meta::u64v(clock, 4)?, meta::u64v(clock, 5)?)?,
140            samples: Rate::new(meta::u64v(d, 13)?, meta::u64v(d, 14)?)?,
141            start_tick: e.start_tick(),
142        });
143        let encoding = extension(d, 210, ctx)?;
144        result.channel_order = meta::text(encoding, 1)?;
145        labels(result.channel_order, channels, ctx)?;
146        result.purpose = meta::text(encoding, 4)?;
147        result.relation = meta::text(encoding, 5)?;
148        result.units_per_stored_sample = meta::f64v(encoding, 2)?;
149        result.stored_offset = meta::f64v(encoding, 3)?;
150        match result.relation {
151            "digital-unrelated-to-pressure" => {
152                if units != "1"
153                    || ![
154                        "digital_sample",
155                        "complex_digital_spectrum",
156                        "magnitude_digital_spectrum",
157                    ]
158                    .contains(&quantity)
159                {
160                    return Err(Error::Unit);
161                }
162            }
163            "raw-counts" => {
164                if quantity != "raw_sample_count"
165                    || units != "1"
166                    || ![Scalar::I16, Scalar::I24, Scalar::I32].contains(&scalar)
167                {
168                    return Err(Error::Unit);
169                }
170            }
171            "physical-base-units" => {
172                if units != "Pa"
173                    || ![
174                        "pressure",
175                        "complex_pressure_spectrum",
176                        "magnitude_pressure_spectrum",
177                    ]
178                    .contains(&quantity)
179                {
180                    return Err(Error::Unit);
181                }
182            }
183            _ => return Err(Error::Profile),
184        }
185        if sem::field(d, 6).is_some() && result.relation != "raw-counts" {
186            let lineage = ctx.require_schema(meta::u32v(d, 6)?, 202)?;
187            if meta::text(lineage, 2)? != units {
188                return Err(Error::Unit);
189            }
190        }
191        if n < 2 || dim(0) != e.record_count() || dim(1) != u64::from(channels) {
192            return Err(Error::Shape);
193        }
194        if e.mode() == 0x100 {
195            if n != 2
196                || model != "urn:qualia:qac:pcm-preservation:1"
197                || layout != "time-channel"
198                || matches!(scalar, Scalar::ComplexF32 | Scalar::U8)
199                || sem::field(d, 5).is_some()
200                || !["digital_sample", "raw_sample_count", "pressure"].contains(&quantity)
201            {
202                return Err(Error::Profile);
203            }
204            if meta::text(shape, 15)? != "sample" {
205                return Err(Error::Profile);
206            }
207        } else {
208            if n != 3
209                || model != "urn:qualia:qac:stft-preservation:1"
210                || layout != "frame-channel-bin"
211            {
212                return Err(Error::Profile);
213            }
214            let transform_block = ctx.require_schema(meta::u32v(d, 5)?, 201)?;
215            let t = Transform::from_block(transform_block)?;
216            if dim(2) != u64::from(t.bins) {
217                return Err(Error::Shape);
218            }
219            result.bins = t.bins;
220            result.window_coefficients_le = sem::field(transform_block, 16).map(|f| f.value());
221            match t.kind {
222                TransformKind::Complex => {
223                    if scalar != Scalar::ComplexF32
224                        || result.stored_offset != 0.0
225                        || !["complex_digital_spectrum", "complex_pressure_spectrum"]
226                            .contains(&quantity)
227                        || meta::text(shape, 15)? != "real,imag"
228                    {
229                        return Err(Error::Profile);
230                    }
231                }
232                TransformKind::Magnitude => {
233                    if scalar != Scalar::F32
234                        || !["magnitude_digital_spectrum", "magnitude_pressure_spectrum"]
235                            .contains(&quantity)
236                        || meta::text(shape, 15)? != "magnitude"
237                    {
238                        return Err(Error::Profile);
239                    }
240                }
241            }
242            let timing = result.timing.unwrap();
243            if timing.samples != t.input_rate.divided_by(t.hop)? {
244                return Err(Error::Clock);
245            }
246            match t.origin_basis {
247                OriginBasis::EpochSampleGrid => {
248                    let left = i128::from(e.start_tick())
249                        .checked_mul(timing.ticks.denominator.into())
250                        .and_then(|x| x.checked_mul(t.input_rate.numerator.into()))
251                        .ok_or(Error::Overflow)?;
252                    let right = i128::from(t.origin_samples)
253                        .checked_mul(t.input_rate.denominator.into())
254                        .and_then(|x| x.checked_mul(timing.ticks.numerator.into()))
255                        .ok_or(Error::Overflow)?;
256                    if left != right {
257                        return Err(Error::Clock);
258                    }
259                }
260                OriginBasis::SourceEntryFirstSample => {
261                    if t.origin_samples != 0 {
262                        return Err(Error::Clock);
263                    }
264                    let sources = sem::field(d, 17).ok_or(Error::Profile)?;
265                    if sources.flags() & 1 == 0
266                        || sources.type_tag() != 9
267                        || sources.element_count() != 1
268                        || sources.value().len() != 4
269                    {
270                        return Err(Error::Profile);
271                    }
272                    let src_idx = u32::from_le_bytes(sources.value().try_into().unwrap());
273                    if src_idx == index {
274                        return Err(Error::Profile);
275                    }
276                    let src_entry = ctx.entry(src_idx)?;
277                    if src_entry.mode() != 0x100
278                        || src_entry.revision() != 1
279                        || src_entry.flags() & 2 == 0
280                    {
281                        return Err(Error::Profile);
282                    }
283                    if src_entry.start_tick() != e.start_tick()
284                        || u64::from(t.fft_size) > src_entry.record_count()
285                    {
286                        return Err(Error::Clock);
287                    }
288                    let covered = result
289                        .records
290                        .checked_sub(1)
291                        .and_then(|r| r.checked_mul(u64::from(t.hop)))
292                        .and_then(|n| n.checked_add(u64::from(t.fft_size)))
293                        .ok_or(Error::Overflow)?;
294                    if covered > src_entry.record_count() {
295                        return Err(Error::Shape);
296                    }
297                    let src_d = ctx.require_schema(src_entry.descriptor_id(), 3)?;
298                    if meta::u32v(src_d, 1)? != meta::u32v(d, 1)?
299                        || meta::u32v(src_d, 9)? != channels
300                        || meta::text(src_d, 8)? != units
301                        || Rate::new(meta::u64v(src_d, 13)?, meta::u64v(src_d, 14)?)?
302                            != t.input_rate
303                    {
304                        return Err(Error::Clock);
305                    }
306                    let src_enc = extension(src_d, 210, ctx)?;
307                    if meta::text(src_enc, 1)? != result.channel_order
308                        || meta::text(src_enc, 5)? != result.relation
309                    {
310                        return Err(Error::Profile);
311                    }
312                }
313            }
314            if meta::text(transform_block, 12)? != result.channel_order {
315                return Err(Error::Clock);
316            }
317            result.transform = Some(t);
318        }
319        result.time_at(result.records - 1)?;
320    }
321    let stride = channels
322        .checked_mul(result.bins)
323        .and_then(|n| n.checked_mul(scalar.bytes()))
324        .ok_or(Error::Overflow)?;
325    if stride != e.stride()
326        || result
327            .records
328            .checked_mul(stride.into())
329            .ok_or(Error::Overflow)?
330            != e.decoded_bytes()
331    {
332        return Err(Error::Shape);
333    }
334    Ok(result)
335}
336// Conservative rejection-only preflight, before shared validity/reference work can
337// touch payloads. The structural index is already checked; all semantics follow.
338fn preflight(view: &StructuralView<'_>, limits: Limits, work: &mut u64) -> Result<(), Error> {
339    let mut samples = 0u64;
340    let mut bytes = 0u64;
341    for index in 1..=view.entry_count() {
342        let e = view.entry(index)?;
343        if ![0x100, 0x101, 0x104].contains(&e.mode()) {
344            return Err(Error::Unsupported);
345        }
346        let mut descriptor = None;
347        for b in view.blocks() {
348            *work = work.checked_sub(1).ok_or(Error::Limit)?;
349            if b.id() == e.descriptor_id() {
350                descriptor = Some(b);
351                break;
352            }
353        }
354        let d = descriptor.ok_or(Error::Profile)?;
355        if d.schema_type() != 3 || d.revision() != 1 {
356            return Err(Error::Profile);
357        }
358        let field_scan_work = (d.fields().count() as u64)
359            .checked_mul(2)
360            .ok_or(Error::Overflow)?;
361        *work = work.checked_sub(field_scan_work).ok_or(Error::Limit)?;
362        let f = meta::get(d, 11)?;
363        if f.type_tag() != 1 || f.element_count() != 1 || f.value().len() != 4 {
364            return Err(Error::Scalar);
365        }
366        let width = u64::from(Scalar::from_code(meta::u32v(d, 11)?)?.bytes());
367        if e.decoded_bytes() % width != 0 {
368            return Err(Error::Shape);
369        }
370        samples = samples
371            .checked_add(e.decoded_bytes() / width)
372            .ok_or(Error::Overflow)?;
373        bytes = bytes.checked_add(e.stored_bytes()).ok_or(Error::Overflow)?;
374        if samples > limits.samples || bytes > limits.payload_bytes {
375            return Err(Error::Limit);
376        }
377    }
378    Ok(())
379}
380fn validate_payload(signal: SignalView<'_>) -> Result<(), Error> {
381    finite(signal.scalar, signal.payload)?;
382    if signal
383        .transform
384        .is_some_and(|t| t.kind == TransformKind::Magnitude)
385        && signal
386            .payload
387            .chunks_exact(4)
388            .any(|b| f32::from_le_bytes(b.try_into().unwrap()) < 0.0)
389    {
390        return Err(Error::Profile);
391    }
392    Ok(())
393}
394/// Check every supported entry, reference, shape and whole payload; return one
395/// immutable signal view. Unknown profiles remain available through archival
396/// storage. Scalar/byte budgets are checked before payload hashing or scanning.
397pub fn admit<'a>(
398    view: &StructuralView<'a>,
399    selected: u32,
400    scratch: &mut sem::Scratch<'_>,
401    shared_limits: sem::Limits,
402    limits: Limits,
403) -> Result<SignalView<'a>, Error> {
404    if view.family() != Family::QacV1Candidate {
405        return Err(Error::Unsupported);
406    }
407    if selected == 0 || selected > view.entry_count() {
408        return Err(Error::Index);
409    }
410    if view.entry_count() > limits.entries {
411        return Err(Error::Limit);
412    }
413    let mut work = limits.work;
414    preflight(view, limits, &mut work)?;
415    let admission = sem::admit_shared(view, &SignalRegistry, scratch, shared_limits)?;
416    let ctx = &admission.context;
417    let mut samples = 0u64;
418    let mut chosen = None;
419    for index in 1..=view.entry_count() {
420        let e = ctx.entry(index)?;
421        // Validate typed descriptor/shape/stride before processing any numeric bytes.
422        let mut signal = inspect(index, e, &[], ctx)?;
423        samples = samples
424            .checked_add(e.decoded_bytes() / u64::from(signal.scalar.bytes()))
425            .ok_or(Error::Overflow)?;
426        if samples > limits.samples {
427            return Err(Error::Limit);
428        }
429        work = work
430            .checked_sub(e.stored_bytes().checked_mul(2).ok_or(Error::Overflow)?)
431            .ok_or(Error::Limit)?;
432        ctx.charge_work(e.stored_bytes())?;
433        signal.payload = view.verify_chunk(index)?;
434        validate_payload(signal)?;
435        if index == selected {
436            chosen = Some(signal)
437        }
438    }
439    chosen.ok_or(Error::Index)
440}