Skip to main content

qualia_core_db/q42/emf_profiles/
field_writer.rs

1//! Caller-owned staging followed by one atomic final publication copy.
2use super::super::field_envelope::{EntryInput, EnvelopeInput, Family, Limits as StorageLimits};
3use super::*;
4#[derive(Clone, Copy, Debug)]
5pub struct FieldClock {
6    pub scale: u32,
7    pub epoch_seconds: i64,
8    pub epoch_nanoseconds: u32,
9    pub ticks_per_second_num: u64,
10    pub ticks_per_second_den: u64,
11}
12#[derive(Clone, Copy, Debug)]
13pub struct FieldFrame {
14    pub origin_m: [f64; 3],
15    pub rotation_xyzw: [f64; 4],
16    pub grid: Option<GridSpec>,
17}
18#[derive(Clone, Copy, Debug)]
19pub struct FieldProvenance<'a> {
20    pub role: u32,
21    pub algorithm: Option<&'a str>,
22    pub algorithm_version: Option<&'a str>,
23    pub lineage: Option<&'a str>,
24}
25/// Exact current128-byte records, borrowed immutably. encode_field_samples packs
26/// original f64 observations separately when a producer starts from native data.
27#[derive(Clone, Copy, Debug)]
28pub struct FieldChunkInput<'a> {
29    pub stream_id: u32,
30    pub start_tick: i64,
31    pub time_count: u64,
32    pub spatial_key: Option<u64>,
33    pub payload: &'a [u8],
34}
35#[derive(Clone, Copy, Debug)]
36pub struct FieldDocument<'a> {
37    pub clock: FieldClock,
38    pub frame: FieldFrame,
39    pub provenance: FieldProvenance<'a>,
40    pub temporal_step_ticks: Option<i64>,
41    pub chunks: &'a [FieldChunkInput<'a>],
42    pub align_payloads_to_4096: bool,
43}
44#[derive(Clone, Copy, Debug)]
45pub struct FieldWriteLimits {
46    pub storage: StorageLimits,
47    pub profiles: Limits,
48    pub total_payload_work: u64,
49}
50impl Default for FieldWriteLimits {
51    fn default() -> Self {
52        Self {
53            storage: StorageLimits::default(),
54            profiles: Limits::default(),
55            total_payload_work: 512 << 20,
56        }
57    }
58}
59/// Planning/storage fields borrow caller metadata/entry arenas and immutable source
60/// payloads. No reference to mutable payload staging escapes this prepare step.
61pub struct PreparedField<'m, 'e, 's> {
62    metadata: &'m [u8],
63    entries: &'e [EntryInput<'s>],
64    flags: u32,
65    limits: FieldWriteLimits,
66}
67/// Initialize caller-owned entry slots; raw encoding rejects these until prepare fills them.
68pub fn field_entry_slot<'a>() -> EntryInput<'a> {
69    EntryInput {
70        mode: 0,
71        revision: 1,
72        flags: 0,
73        stream_id: 0,
74        frame_id: 2,
75        start_tick: 0,
76        time_count: 0,
77        spatial_key: 0,
78        record_count: 0,
79        stride: 128,
80        codec: 0,
81        descriptor_id: 5,
82        payload: &[],
83    }
84}
85pub fn field_metadata_len(
86    document: &FieldDocument<'_>,
87    limits: FieldWriteLimits,
88) -> Result<usize, Error> {
89    super::field_metadata::with_metadata(document, |input| {
90        input.encoded_len(limits.storage).map_err(Error::Storage)
91    })
92}
93pub fn prepare_field_document<'m, 'e, 's>(
94    document: &FieldDocument<'s>,
95    metadata: &'m mut [u8],
96    entry_slots: &'e mut [EntryInput<'s>],
97    limits: FieldWriteLimits,
98) -> Result<PreparedField<'m, 'e, 's>, Error> {
99    if document.chunks.is_empty() {
100        return Err(Error::Shape);
101    }
102    if document.chunks.len() > entry_slots.len() {
103        return Err(Error::Limit);
104    }
105    if document.chunks.len() as u64 > u64::from(limits.storage.entries) {
106        return Err(Error::Limit);
107    }
108    let mut payload_work = 0u64;
109    for chunk in document.chunks {
110        if chunk.payload.is_empty()
111            || chunk.payload.len() % 128 != 0
112            || chunk.spatial_key.is_some() != document.frame.grid.is_some()
113        {
114            return Err(Error::Shape);
115        }
116        if chunk.payload.len() as u64 / 128 > limits.profiles.records {
117            return Err(Error::Limit);
118        }
119        payload_work = payload_work
120            .checked_add(
121                (chunk.payload.len() as u64)
122                    .checked_mul(2)
123                    .ok_or(Error::Overflow)?,
124            )
125            .ok_or(Error::Overflow)?;
126    }
127    if payload_work > limits.total_payload_work {
128        return Err(Error::Limit);
129    }
130    let metadata = super::field_metadata::with_metadata(document, |input| {
131        input
132            .encode_into(metadata, limits.storage)
133            .map_err(Error::Storage)
134    })?;
135    let entries = &mut entry_slots[..document.chunks.len()];
136    for (slot, chunk) in entries.iter_mut().zip(document.chunks) {
137        *slot = EntryInput {
138            mode: 0,
139            revision: 1,
140            flags: if document.temporal_step_ticks.is_some() {
141                2
142            } else {
143                0
144            } | if chunk.spatial_key.is_some() { 4 } else { 0 },
145            stream_id: chunk.stream_id,
146            frame_id: 2,
147            start_tick: chunk.start_tick,
148            time_count: chunk.time_count,
149            spatial_key: chunk.spatial_key.unwrap_or(0),
150            record_count: chunk.payload.len() as u64 / 128,
151            stride: 128,
152            codec: 0,
153            descriptor_id: 5,
154            payload: chunk.payload,
155        };
156    }
157    let prepared = PreparedField {
158        metadata,
159        entries,
160        flags: u32::from(document.align_payloads_to_4096),
161        limits,
162    };
163    prepared.encoded_len()?;
164    Ok(prepared)
165}
166impl PreparedField<'_, '_, '_> {
167    fn envelope(&self) -> EnvelopeInput<'_> {
168        EnvelopeInput {
169            family: Family::EmfV4Candidate,
170            flags: self.flags,
171            metadata: self.metadata,
172            entries: self.entries,
173        }
174    }
175    pub fn encoded_len(&self) -> Result<usize, Error> {
176        self.envelope()
177            .encoded_len(self.limits.storage)
178            .map_err(Error::Storage)
179    }
180    /// Staging may change on error; the ENTIRE final output remains unchanged.
181    /// All source chunks are immutable; every selected chunk is verified/admitted
182    /// before the one final copy. Any extra output tail is retained on success.
183    pub fn encode_into<'out>(
184        &self,
185        staging: &mut [u8],
186        output: &'out mut [u8],
187        scratch: &mut Scratch<'_>,
188    ) -> Result<&'out mut [u8], Error> {
189        let len = self.encoded_len()?;
190        if output.len() < len {
191            return Err(Error::Storage(super::super::field_envelope::Error::Extent));
192        }
193        let staged = self
194            .envelope()
195            .encode_into(staging, self.limits.storage)
196            .map_err(Error::Storage)?;
197        let view = StructuralView::open(staged, Family::EmfV4Candidate, self.limits.storage)
198            .map_err(Error::Storage)?;
199        let admitted = semantics::admit_shared(
200            &view,
201            &ProfileRegistry,
202            scratch,
203            self.limits.profiles.shared,
204        )
205        .map_err(shared_error)?;
206        for index in 1..=view.entry_count() {
207            super::chunk::admit_with_context(
208                &view,
209                &admitted.context,
210                index,
211                self.limits.profiles,
212            )?;
213        }
214        output[..len].copy_from_slice(staged);
215        Ok(&mut output[..len])
216    }
217}
218/// Native observations; no guessed carrier, constitutive law, flux or confidence.
219#[derive(Clone, Copy, Debug, PartialEq)]
220pub struct FieldSample {
221    pub electric_v_per_m: [f64; 3],
222    pub magnetic_tesla: [f64; 3],
223    pub position_m: [f64; 3],
224    pub tick: i64,
225    pub carrier_hz: Option<f64>,
226    pub stored_poynting_w_per_m2: Option<[f64; 3]>,
227    pub confidence: Option<f32>,
228}
229pub fn encode_field_samples<'out>(
230    samples: &[FieldSample],
231    output: &'out mut [u8],
232    limits: Limits,
233) -> Result<&'out mut [u8], Error> {
234    if samples.is_empty() {
235        return Err(Error::Shape);
236    }
237    if samples.len() as u64 > limits.records {
238        return Err(Error::Limit);
239    }
240    let bytes = samples.len().checked_mul(128).ok_or(Error::Overflow)?;
241    if (bytes as u64).checked_mul(2).ok_or(Error::Overflow)? > limits.payload_work {
242        return Err(Error::Limit);
243    }
244    if output.len() < bytes {
245        return Err(Error::Storage(super::super::field_envelope::Error::Extent));
246    }
247    for sample in samples {
248        let mut record = [0; 128];
249        pack(sample, &mut record);
250        super::records::field_record(&record, true, sample.tick)?;
251    }
252    for (sample, record) in samples.iter().zip(output[..bytes].chunks_exact_mut(128)) {
253        pack(sample, record);
254    }
255    Ok(&mut output[..bytes])
256}
257fn pack(sample: &FieldSample, record: &mut [u8]) {
258    record.fill(0);
259    for (start, values) in [
260        (0, &sample.electric_v_per_m),
261        (24, &sample.magnetic_tesla),
262        (48, &sample.position_m),
263    ] {
264        for (axis, value) in values.iter().enumerate() {
265            record[start + axis * 8..start + axis * 8 + 8].copy_from_slice(&value.to_le_bytes());
266        }
267    }
268    record[72..80].copy_from_slice(&sample.tick.to_le_bytes());
269    let mut flags = 0u32;
270    if let Some(carrier) = sample.carrier_hz {
271        flags |= 1;
272        record[80..88].copy_from_slice(&carrier.to_le_bytes());
273    }
274    if let Some(flux) = sample.stored_poynting_w_per_m2 {
275        flags |= 4;
276        for (axis, value) in flux.iter().enumerate() {
277            record[96 + axis * 8..104 + axis * 8].copy_from_slice(&value.to_le_bytes());
278        }
279    }
280    if let Some(confidence) = sample.confidence {
281        flags |= 8;
282        record[124..128].copy_from_slice(&confidence.to_le_bytes());
283    }
284    record[120..124].copy_from_slice(&flags.to_le_bytes());
285}