Skip to main content

qualia_core_db/render/portal_qac/
retained.rs

1use super::{provenance_role_str, Error, Limits, Metadata, PcmWindow, StftWindow};
2use crate::audio::qac::signal;
3use crate::q42::{
4    field_envelope::{Family, StructuralView},
5    field_semantics::{field, NodeState, Scratch},
6};
7use std::{mem::size_of, ops::Range};
8
9/// Owns exactly the admitted source. No self-reference or unchecked view constructor.
10/// One selected entry is admitted together with all supported document entries.
11/// Re-selecting requires a new cold admission; windows only borrow admitted bytes.
12pub struct RetainedQac {
13    source: Box<[u8]>,
14    payload: Range<usize>,
15    metadata: Metadata,
16    limits: Limits,
17}
18impl RetainedQac {
19    pub fn open(source: Box<[u8]>, selected_entry: u32, limits: Limits) -> Result<Self, Error> {
20        if source.len() as u64 > limits.envelope.file_bytes || source.len() > limits.memory_bytes {
21            return Err(Error::Limit);
22        }
23        let view = StructuralView::open(&source, Family::QacV1Candidate, limits.envelope)?;
24        if selected_entry == 0 || selected_entry > view.entry_count() {
25            return Err(Error::Index);
26        }
27        let entry = view.entry(selected_entry)?;
28        if ![0x100, 0x101].contains(&entry.mode()) {
29            return Err(Error::Unsupported);
30        }
31        let blocks = view.blocks().count();
32        let scratch_bytes = blocks
33            .checked_add(view.entry_count() as usize)
34            .and_then(|n| n.checked_mul(size_of::<NodeState>()))
35            .ok_or(Error::Overflow)?;
36        // Every copied string originates in metadata; allow six complete metadata
37        // copies conservatively, plus fixed owned state and transient graph scratch.
38        let memory = source
39            .len()
40            .checked_add(scratch_bytes)
41            .and_then(|n| n.checked_add(view.metadata_bytes().len().checked_mul(6)?))
42            .and_then(|n| n.checked_add(size_of::<Self>()))
43            .ok_or(Error::Overflow)?;
44        if memory > limits.memory_bytes {
45            return Err(Error::Limit);
46        }
47        if view.entry_count() > limits.signal.entries {
48            return Err(Error::Limit);
49        }
50        let mut metadata_scratch = vec![NodeState::default(); blocks];
51        let mut entry_scratch = vec![NodeState::default(); view.entry_count() as usize];
52        let selected = signal::admit(
53            &view,
54            selected_entry,
55            &mut Scratch {
56                metadata: &mut metadata_scratch,
57                entries: &mut entry_scratch,
58            },
59            limits.shared,
60            limits.signal,
61        )?;
62        let start = usize::try_from(entry.payload_offset()).map_err(|_| Error::Overflow)?;
63        let length = usize::try_from(entry.stored_bytes()).map_err(|_| Error::Overflow)?;
64        let end = start.checked_add(length).ok_or(Error::Overflow)?;
65        let payload = source.get(start..end).ok_or(Error::Invariant)?;
66        if payload.len() != selected.as_bytes().len()
67            || payload.as_ptr() != selected.as_bytes().as_ptr()
68        {
69            return Err(Error::Invariant);
70        }
71        let descriptor = view
72            .blocks()
73            .find(|b| b.id() == entry.descriptor_id())
74            .ok_or(Error::Invariant)?;
75        let provenance_id = u32::from_le_bytes(
76            field(descriptor, 3)
77                .ok_or(Error::Invariant)?
78                .value()
79                .try_into()
80                .map_err(|_| Error::Invariant)?,
81        );
82        let provenance = view
83            .blocks()
84            .find(|b| b.id() == provenance_id)
85            .ok_or(Error::Invariant)?;
86        let role_code = u32::from_le_bytes(
87            field(provenance, 1)
88                .ok_or(Error::Invariant)?
89                .value()
90                .try_into()
91                .map_err(|_| Error::Invariant)?,
92        );
93        let epistemic_role = provenance_role_str(role_code).ok_or(Error::Invariant)?;
94        let model = field(descriptor, 12).ok_or(Error::Invariant)?;
95        let metadata = Metadata {
96            selected_entry,
97            descriptor_id: entry.descriptor_id(),
98            clock_id: u32::from_le_bytes(
99                field(descriptor, 1)
100                    .ok_or(Error::Invariant)?
101                    .value()
102                    .try_into()
103                    .map_err(|_| Error::Invariant)?,
104            ),
105            provenance_id,
106            epistemic_role,
107            stream_id: selected.stream_id(),
108            frame_id: selected.frame_id(),
109            mode: selected.mode(),
110            scalar: selected.scalar(),
111            channels: selected.channels(),
112            bins: selected.bins(),
113            records: selected.records(),
114            timing: selected.timing().ok_or(Error::Invariant)?,
115            transform: selected.transform(),
116            window_coefficients_le: selected.window_coefficients_le().map(Into::into),
117            channel_order: selected.channel_order().into(),
118            purpose: selected.purpose().into(),
119            relation: selected.relation().into(),
120            quantity: selected.quantity().into(),
121            units: selected.units().into(),
122            model_uri: std::str::from_utf8(model.value())
123                .map_err(|_| Error::Invariant)?
124                .into(),
125            units_per_stored_sample: selected.units_per_stored_sample(),
126            stored_offset: selected.stored_offset(),
127            index_digest: view
128                .index_digest()
129                .try_into()
130                .map_err(|_| Error::Invariant)?,
131        };
132        Ok(Self {
133            source,
134            payload: start..end,
135            metadata,
136            limits,
137        })
138    }
139    pub fn source_bytes(&self) -> &[u8] {
140        &self.source
141    }
142    pub fn selected_payload_bytes(&self) -> &[u8] {
143        &self.source[self.payload.clone()]
144    }
145    pub fn metadata(&self) -> &Metadata {
146        &self.metadata
147    }
148    pub fn time_at(&self, record: u64) -> Result<signal::ExactTime, Error> {
149        if record >= self.metadata.records {
150            return Err(Error::Index);
151        }
152        Ok(self.metadata.timing.time_at(record)?)
153    }
154    pub fn pcm_window(&self, start: u64, count: u64, channel: u32) -> Result<PcmWindow<'_>, Error> {
155        if self.metadata.mode != 0x100 {
156            return Err(Error::Unsupported);
157        }
158        Ok(PcmWindow {
159            inner: self.window(start, count, channel)?,
160        })
161    }
162    pub fn stft_window(
163        &self,
164        start: u64,
165        count: u64,
166        channel: u32,
167    ) -> Result<StftWindow<'_>, Error> {
168        if self.metadata.mode != 0x101 {
169            return Err(Error::Unsupported);
170        }
171        Ok(StftWindow {
172            inner: self.window(start, count, channel)?,
173        })
174    }
175    fn window(
176        &self,
177        start: u64,
178        count: u64,
179        channel: u32,
180    ) -> Result<super::window::Window<'_>, Error> {
181        if channel >= self.metadata.channels
182            || start > self.metadata.records
183            || count > self.metadata.records - start
184        {
185            return Err(Error::Index);
186        }
187        let samples = count
188            .checked_mul(u64::from(self.metadata.bins))
189            .ok_or(Error::Overflow)?;
190        if count > self.limits.window_records || samples > self.limits.window_samples {
191            return Err(Error::Limit);
192        }
193        let stride = u64::from(self.metadata.channels)
194            .checked_mul(self.metadata.bins.into())
195            .and_then(|n| n.checked_mul(self.metadata.scalar.bytes().into()))
196            .ok_or(Error::Overflow)?;
197        let begin = usize::try_from(start.checked_mul(stride).ok_or(Error::Overflow)?)
198            .map_err(|_| Error::Overflow)?;
199        let n = usize::try_from(count.checked_mul(stride).ok_or(Error::Overflow)?)
200            .map_err(|_| Error::Overflow)?;
201        let bytes = self
202            .selected_payload_bytes()
203            .get(begin..begin.checked_add(n).ok_or(Error::Overflow)?)
204            .ok_or(Error::Invariant)?;
205        Ok(super::window::Window {
206            bytes,
207            metadata: &self.metadata,
208            start,
209            count,
210            channel,
211        })
212    }
213}