Skip to main content

qualia_core_db/q42/emf_profiles/
extended_writer.rs

1//! Zero-heap canonical builder and envelope writer for all EMF profiles (0x0100..=0x0107 / 0..=7).
2//! Uses caller-supplied arenas only; preserves strict block-ID and TLV-key ascending ordering.
3
4#[path = "extended_writer_helpers.rs"]
5mod extended_writer_helpers;
6use extended_writer_helpers::*;
7
8use super::super::field_envelope::{
9    BlockInput, EntryInput, EnvelopeInput, Family, FieldInput, FieldValue as V, MetadataInput,
10};
11use super::dose_biofield::{BIOFIELD_MODEL_URI, BIOFIELD_PROFILE, DOSE_MODEL_URI, DOSE_PROFILE};
12use super::iq::{iq_record_stride, IQ_MODEL_URI, IQ_PROFILE};
13use super::mueller::{MUELLER_MODEL_URI, MUELLER_PROFILE};
14use super::yee::{YEE_MODEL_URI, YEE_PROFILE};
15use super::*;
16
17#[derive(Clone, Copy, Debug)]
18pub struct CalibrationSpec<'a> {
19    pub instrument_identifier: &'a str,
20    pub content_digest: [u8; 32],
21    pub quantity_unit: &'a str,
22    pub scale: f64,
23    pub offset: f64,
24    pub uncertainty: Option<(f64, &'a str)>,
25    pub validity_ticks: Option<[i64; 2]>,
26}
27
28#[derive(Clone, Copy, Debug)]
29pub struct ModelEvidenceSpec<'a> {
30    pub model_identifier_version: &'a str,
31    pub domain_applicability: &'a str,
32    pub parameter_source_digest: [u8; 32],
33    pub numerical_convention: &'a str,
34    pub epistemic_class: &'a str,
35    pub uncertainty: Option<&'a str>,
36    pub external_reference: Option<&'a str>,
37    pub qualification_receipt_id: Option<&'a str>,
38    pub particle_species: Option<&'a str>,
39    pub integration_ticks: Option<[i64; 2]>,
40    pub weighting_derating_model: Option<&'a str>,
41}
42
43#[derive(Clone, Copy, Debug)]
44pub struct ConstitutiveSpec<'a> {
45    pub model: &'a str,
46    pub epsilon_infinity_relative: f64,
47    pub mu_relative: f64,
48    pub conductivity_s_per_m: f64,
49    pub delta_epsilon: &'a [f64],
50    pub relaxation_time_s: &'a [f64],
51    pub resonance_rad_s: &'a [f64],
52    pub damping_s1: &'a [f64],
53}
54
55#[derive(Clone, Copy, Debug)]
56pub struct AcquisitionSpec<'a> {
57    pub sample_rate_num: u64,
58    pub sample_rate_den: u64,
59    pub signal_kind: &'a str,
60    pub unit: &'a str,
61    pub complex_convention: &'a str,
62    pub window: Option<&'a str>,
63    pub fft_size: Option<u32>,
64    pub hop: Option<u32>,
65    pub fft_normalization: Option<&'a str>,
66    pub carrier_hz: Option<f64>,
67    pub channel_count: Option<u32>,
68}
69
70#[derive(Clone, Copy, Debug)]
71pub struct BioContextSpec<'a> {
72    pub anatomical_ontology_version: &'a str,
73    pub anatomical_identifier: &'a str,
74    pub observation_type: &'a str,
75    pub consent_receipt_digest: Option<[u8; 32]>,
76}
77
78#[derive(Clone, Copy, Debug)]
79pub struct MaterialSpec<'a> {
80    pub container_digest: [u8; 32],
81    pub table_digest: [u8; 32],
82    pub table_epoch: u64,
83    pub table_schema_version: &'a str,
84    pub material_ids: &'a [u64],
85}
86
87#[derive(Clone, Copy, Debug)]
88pub struct SpectralAxisSpec<'a> {
89    pub axis: &'a str,
90    pub sample_semantics: &'a str,
91    pub physical_quantity: &'a str,
92    pub unit: &'a str,
93    pub coordinates: &'a [f64],
94    pub sigma_interpretation: &'a str,
95    pub sigma_bounds: Option<[f64; 2]>,
96}
97
98#[derive(Clone, Copy, Debug)]
99pub enum ExtendedModeSpec<'a> {
100    Field { carrier_hz_note: bool },
101    Ray { units: &'a str },
102    Yee {
103        constitutive: ConstitutiveSpec<'a>,
104        time_offset_num: &'a [i64],
105        time_offset_den: &'a [u64],
106        material: Option<MaterialSpec<'a>>,
107    },
108    Spectrum {
109        axis: SpectralAxisSpec<'a>,
110        bins: u32,
111        response_cal: Option<CalibrationSpec<'a>>,
112    },
113    Mueller {
114        evidence: ModelEvidenceSpec<'a>,
115        units: &'a str,
116        material: Option<MaterialSpec<'a>>,
117    },
118    Iq {
119        acquisition: AcquisitionSpec<'a>,
120        calibration: CalibrationSpec<'a>,
121        samples_per_packet: u32,
122    },
123    Dose {
124        evidence: ModelEvidenceSpec<'a>,
125        calibration: CalibrationSpec<'a>,
126        material: Option<MaterialSpec<'a>>,
127    },
128    Biofield {
129        bio: BioContextSpec<'a>,
130        evidence: ModelEvidenceSpec<'a>,
131        calibration: CalibrationSpec<'a>,
132    },
133}
134
135/// Encodes an extended single-chunk EMF v4 envelope into `output` via zero-heap staging
136/// and self-admits through `ProfileReader` before final atomic copy.
137#[allow(clippy::too_many_arguments)]
138pub fn write_extended_envelope<'out>(
139    clock: FieldClock,
140    frame: FieldFrame,
141    provenance: FieldProvenance<'_>,
142    mode_id: u16,
143    temporal_step_ticks: Option<i64>,
144    start_tick: i64,
145    time_count: u64,
146    spatial_key: Option<u64>,
147    record_count: u64,
148    payload: &[u8],
149    spec: &ExtendedModeSpec<'_>,
150    meta_buf: &mut [u8],
151    staging: &mut [u8],
152    output: &'out mut [u8],
153    scratch: &mut Scratch<'_>,
154    limits: FieldWriteLimits,
155) -> Result<&'out mut [u8], Error> {
156    if payload.is_empty() || record_count == 0 {
157        return Err(Error::Shape);
158    }
159    if temporal_step_ticks.is_some_and(|s| s <= 0) {
160        return Err(Error::Time);
161    }
162    let scale = [clock.scale];
163    let epoch = [clock.epoch_seconds];
164    let nanos = [clock.epoch_nanoseconds];
165    let cnum = [clock.ticks_per_second_num];
166    let cden = [clock.ticks_per_second_den];
167    let clock_fields = [
168        FieldInput { key: 1, flags: 1, value: V::U32(&scale) },
169        FieldInput { key: 2, flags: 1, value: V::I64(&epoch) },
170        FieldInput { key: 3, flags: 1, value: V::U32(&nanos) },
171        FieldInput { key: 4, flags: 1, value: V::U64(&cnum) },
172        FieldInput { key: 5, flags: 1, value: V::U64(&cden) },
173    ];
174
175    let zero32 = [0u32];
176    let mut frame_fields = [empty_f(); 7];
177    let mut fc = 0usize;
178    push(&mut frame_fields, &mut fc, 1, true, V::U32(&zero32));
179    push(&mut frame_fields, &mut fc, 3, true, V::F64(&frame.origin_m));
180    push(&mut frame_fields, &mut fc, 4, true, V::F64(&frame.rotation_xyzw));
181    let grid = frame.grid;
182    let dims = grid.map_or([1; 3], |g| g.dimensions);
183    let dims64 = dims.map(u64::from);
184    let bricks = grid.map_or([1; 3], |g| g.brick_dimensions);
185    let spacing = grid.map_or([1.0; 3], |g| g.spacing_m);
186    let indexing = grid.map_or(GridIndexing::Linear, |g| g.indexing);
187    let order = [indexing.order()];
188    let common_order = [indexing.common_order().unwrap_or(0)];
189    if let Some(g) = grid {
190        g.validate()?;
191        push(&mut frame_fields, &mut fc, 5, true, V::F64(&spacing));
192        push(&mut frame_fields, &mut fc, 6, true, V::U32(&dims));
193        if indexing.common_order().is_some() {
194            push(&mut frame_fields, &mut fc, 7, true, V::U32(&common_order));
195        }
196    }
197    push(&mut frame_fields, &mut fc, 8, true, V::Utf8("right-handed-X-forward-Y-left-Z-up"));
198
199    let mut prov_fields = [empty_f(); 4];
200    let mut pc = 0usize;
201    let role = [provenance.role];
202    push(&mut prov_fields, &mut pc, 1, true, V::U32(&role));
203    if let Some(s) = provenance.algorithm {
204        push(&mut prov_fields, &mut pc, 3, false, V::Utf8(s));
205    }
206    if let Some(s) = provenance.algorithm_version {
207        push(&mut prov_fields, &mut pc, 4, false, V::Utf8(s));
208    }
209    if let Some(s) = provenance.lineage {
210        push(&mut prov_fields, &mut pc, 7, false, V::Utf8(s));
211    }
212
213    let mode_u32 = [u32::from(mode_id)];
214    let step_i64 = [temporal_step_ticks.unwrap_or(0)];
215    let (rate_num, rate_den) = if let Some(s) = temporal_step_ticks {
216        let su = s as u64;
217        let g = gcd(clock.ticks_per_second_num, su);
218        let rn = clock.ticks_per_second_num / g;
219        let rd = u128::from(clock.ticks_per_second_den) * u128::from(su / g);
220        (rn, u64::try_from(rd).map_err(|_| Error::Time)?)
221    } else {
222        (0, 0)
223    };
224    let rn_arr = [rate_num];
225    let rd_arr = [rate_den];
226
227    let refs = ModeStaticRefs {
228        one32: [1],
229        two32: [2],
230        three32: [3],
231        four32: [4],
232        six32: [6],
233        seven32: [7],
234        eight32: [8],
235        nine32: [9],
236        consent_role: [4],
237    };
238
239    let mut scratch_scalars = ModeScratch::default();
240    let mut sub = SubBlocks::new();
241
242    let mut ext_fields = [empty_f(); 20];
243    let mut ec = 0usize;
244    push(&mut ext_fields, &mut ec, 1, true, V::U32(&mode_u32));
245    push(&mut ext_fields, &mut ec, 2, true, V::U32(&refs.one32));
246    push(&mut ext_fields, &mut ec, 3, true, V::MetadataRefs(&refs.one32));
247    push(&mut ext_fields, &mut ec, 4, true, V::MetadataRefs(&refs.two32));
248    push(&mut ext_fields, &mut ec, 5, true, V::MetadataRefs(&refs.three32));
249
250    let desc = populate_extended_mode(
251        spec,
252        indexing,
253        &dims64,
254        &bricks,
255        &order,
256        &step_i64,
257        &mut ext_fields,
258        &mut ec,
259        &mut sub,
260        &mut scratch_scalars,
261        &refs,
262    )?;
263
264    let mut desc_fields = [empty_f(); 10];
265    let mut dc = 0usize;
266    if temporal_step_ticks.is_some() {
267        push(&mut desc_fields, &mut dc, 1, true, V::MetadataRefs(&refs.one32));
268    }
269    push(&mut desc_fields, &mut dc, 2, false, V::MetadataRefs(&refs.two32));
270    push(&mut desc_fields, &mut dc, 3, true, V::MetadataRefs(&refs.three32));
271    push(&mut desc_fields, &mut dc, 7, true, V::Utf8(desc.quantity_str));
272    push(&mut desc_fields, &mut dc, 8, true, V::Utf8(desc.unit_str));
273    push(&mut desc_fields, &mut dc, 12, true, V::Utf8(desc.model_uri_str));
274    if temporal_step_ticks.is_some() {
275        push(&mut desc_fields, &mut dc, 13, true, V::U64(&rn_arr));
276        push(&mut desc_fields, &mut dc, 14, true, V::U64(&rd_arr));
277    }
278    push(&mut desc_fields, &mut dc, 18, true, V::MetadataRefs(&refs.four32));
279
280    let empty_block = BlockInput {
281        id: 0,
282        schema_type: 0,
283        revision: 1,
284        flags: 0,
285        fields: &[],
286    };
287    let mut blocks = [empty_block; 9];
288    blocks[0] = BlockInput { id: 1, schema_type: 1, revision: 1, flags: 1, fields: &clock_fields };
289    blocks[1] = BlockInput { id: 2, schema_type: 2, revision: 1, flags: 1, fields: &frame_fields[..fc] };
290    blocks[2] = BlockInput { id: 3, schema_type: 4, revision: 1, flags: 1, fields: &prov_fields[..pc] };
291    blocks[3] = BlockInput { id: 4, schema_type: 103, revision: 1, flags: 1, fields: &ext_fields[..ec] };
292    blocks[4] = BlockInput { id: 5, schema_type: 3, revision: 1, flags: 1, fields: &desc_fields[..dc] };
293    let mut bc = 5usize;
294    for (id, schema, len, fields) in [
295        (6u32, sub.s6_schema, sub.s6n, &sub.sub6[..]),
296        (7u32, sub.s7_schema, sub.s7n, &sub.sub7[..]),
297        (8u32, sub.s8_schema, sub.s8n, &sub.sub8[..]),
298        (9u32, sub.s9_schema, sub.s9n, &sub.sub9[..]),
299    ] {
300        if schema != 0 {
301            blocks[bc] = BlockInput {
302                id,
303                schema_type: schema,
304                revision: 1,
305                flags: 1,
306                fields: &fields[..len],
307            };
308            bc += 1;
309        }
310    }
311
312    let meta = MetadataInput {
313        blocks: &blocks[..bc],
314    }
315    .encode_into(meta_buf, limits.storage)
316    .map_err(Error::Storage)?;
317
318    let entry = [EntryInput {
319        mode: mode_id,
320        revision: 1,
321        flags: if temporal_step_ticks.is_some() { 2 } else { 0 }
322            | if spatial_key.is_some() { 4 } else { 0 },
323        stream_id: 1,
324        frame_id: 2,
325        start_tick,
326        time_count,
327        spatial_key: spatial_key.unwrap_or(0),
328        record_count,
329        stride: desc.stride_u32,
330        codec: 0,
331        descriptor_id: 5,
332        payload,
333    }];
334    let env = EnvelopeInput {
335        family: Family::EmfV4Candidate,
336        flags: 0,
337        metadata: meta,
338        entries: &entry,
339    };
340    let len = env.encoded_len(limits.storage).map_err(Error::Storage)?;
341    if output.len() < len {
342        return Err(Error::Storage(super::super::field_envelope::Error::Extent));
343    }
344    let staged = env.encode_into(staging, limits.storage).map_err(Error::Storage)?;
345    let view = StructuralView::open(staged, Family::EmfV4Candidate, limits.storage)
346        .map_err(Error::Storage)?;
347    let mut reader = ProfileReader::open(&view, scratch, limits.profiles, limits.total_payload_work)?;
348    let _ = reader.chunk(1)?;
349    output[..staged.len()].copy_from_slice(staged);
350    Ok(&mut output[..staged.len()])
351}