Skip to main content

qualia_core_db/bundle/
field_range_planner.rs

1//! Selective chunk-aligned range planning and arrived-chunk verification for `.emf` (v4 `Q42EMF64`)
2//! and `.qac` (v1 `qac\0\0\0\0\0`) entries embedded inside `.hmc` bundles.
3
4use std::ops::Range;
5use sha2::{Digest, Sha256};
6use crate::audio::qac::signal::{self, Limits as QacSignalLimits, SignalView};
7use crate::container_10d::crc32c::crc32c;
8use crate::q42::emf_profiles::{Limits as EmfProfileLimits, ProfileChunk, ProfileReader};
9use crate::q42::field_envelope::{self as env, DIRECTORY_BYTES, Family, HEADER_BYTES, INDEX_DOMAIN, Limits as EnvelopeLimits, StructuralView};
10use crate::q42::field_semantics::{Limits as SharedSemanticLimits, Scratch};
11use crate::sensing::acquisition::{self as acq, storage::{self as acq_storage, Document as AcquisitionDocument, Limits as AcquisitionLimits}};
12use super::format::{BundleEntry, SHA256_LEN};
13
14/// Errors returned during selective field range planning, arrived-chunk verification, or admission.
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub enum FieldRangeError {
17    PrefixTooShort, InvalidBundleDigest, InvalidFamilyMagic, UnsupportedVersion(u16),
18    HeaderCrcMismatch { expected: u32, got: u32 },
19    DirectoryEntryCrcMismatch { index: u32, expected: u32, got: u32 },
20    IndexCommitmentMismatch, InvalidHeaderFields, InvalidDirectoryEntry { index: u32 },
21    InvalidDirectoryOrder { index: u32 }, InvalidCompressionCodec { index: u32, codec: u16 },
22    OverlappingExtents { index: u32 }, ExtentMismatch, LimitExceeded, InvalidMetadataTlv,
23    EntryIndexOutOfBounds { index: u32, count: u32 },
24    TruncatedOrMismatchedRange { expected: u64, got: u64 },
25    MetadataCrcMismatch { expected: u32, got: u32 },
26    PayloadBlake3Mismatch, CrossContainerSubstitution,
27    CrossModeReinterpretation { expected: u16, got: u16 },
28    PartialRangeCannotClaimWholeVolume,
29    EmfAdmission(crate::q42::emf_profiles::Error),
30    QacAdmission(crate::audio::qac::signal::Error),
31    AcquisitionAdmission(crate::sensing::acquisition::storage::Error),
32}
33
34#[inline] fn u16le(b: &[u8], o: usize) -> u16 { u16::from_le_bytes([b[o], b[o + 1]]) }
35#[inline] fn u32le(b: &[u8], o: usize) -> u32 { u32::from_le_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]]) }
36#[inline] fn u64le(b: &[u8], o: usize) -> u64 { u64::from_le_bytes(b[o..o + 8].try_into().unwrap()) }
37#[inline] fn align_up(n: u64, a: u64) -> Result<u64, FieldRangeError> { Ok(n.checked_add(a - 1).ok_or(FieldRangeError::ExtentMismatch)? & !(a - 1)) }
38#[inline] fn block_crc32c_124(b: &[u8; 128]) -> u32 { let mut c = *b; c[124..128].fill(0); crc32c(&c) }
39
40fn validate_metadata_tlv(family: Family, mut bytes: &[u8], limits: EnvelopeLimits, req_desc: &[u32]) -> Result<(), FieldRangeError> {
41    env::EnvelopeInput { family, flags: 0, metadata: bytes, entries: &[] }
42        .encoded_len(limits)
43        .map_err(|e| if e == env::Error::Limit { FieldRangeError::LimitExceeded } else { FieldRangeError::InvalidMetadataTlv })?;
44    let mut found_schema3 = Vec::new();
45    while bytes.len() >= 16 {
46        if u16le(bytes, 4) == 3 && u16le(bytes, 6) == 1 { found_schema3.push(u32le(bytes, 0)); }
47        bytes = bytes.get(16 + ((u32le(bytes, 8) as usize + 7) & !7)..).ok_or(FieldRangeError::InvalidMetadataTlv)?;
48    }
49    if req_desc.iter().any(|req| !found_schema3.contains(req)) { return Err(FieldRangeError::InvalidMetadataTlv); }
50    Ok(())
51}
52
53fn row_to_entry_input<'a>(row: &[u8; 128], payload: &'a [u8]) -> env::EntryInput<'a> {
54    env::EntryInput {
55        mode: u16le(row, 0), revision: u16le(row, 2), flags: u32le(row, 4),
56        stream_id: u32le(row, 8), frame_id: u32le(row, 12), start_tick: u64le(row, 16) as i64,
57        time_count: u64le(row, 24), spatial_key: u64le(row, 32), record_count: u64le(row, 64),
58        stride: u32le(row, 72), codec: u16le(row, 76), descriptor_id: u32le(row, 112), payload,
59    }
60}
61
62/// Planned `.hmc` byte ranges and authenticated cryptographic commitments for one chunk entry.
63#[derive(Clone, Debug, PartialEq, Eq)]
64pub struct PlannedChunkRange {
65    pub bundle_key: String, pub bundle_offset: u64, pub bundle_length: u64,
66    pub family: Family, pub entry_index: u32, pub total_entry_count: u32,
67    pub mode: u16, pub entry_flags: u32, pub codec: u16, pub descriptor_id: u32,
68    pub data_offset: u64, pub data_length: u64, pub decoded_bytes: u64,
69    pub meta_offset: u64, pub meta_length: u64,
70    pub hmc_data_range: Range<u64>, pub hmc_meta_range: Range<u64>,
71    pub payload_blake3: [u8; 32], pub meta_crc32c: u32, pub entry_crc32c: u32, pub header_crc32c: u32,
72    pub parent_header_digest: [u8; 32], pub index_commitment: [u8; 32],
73    pub raw_header_bytes: [u8; HEADER_BYTES], pub raw_directory_entry_bytes: [u8; DIRECTORY_BYTES],
74}
75
76/// Selective chunk-aligned range planner for an `.emf` v4 or `.qac` v1 entry inside an `.hmc` bundle.
77#[derive(Clone, Debug)]
78pub struct FieldEntryRangePlan {
79    bundle_key: String, bundle_offset: u64, bundle_length: u64, bundle_sha256: [u8; SHA256_LEN],
80    family: Family, entry_count: u32, meta_offset: u64, meta_length: u64,
81    meta_crc32c: u32, header_crc32c: u32, parent_header_digest: [u8; 32], index_commitment: [u8; 32],
82    raw_header_bytes: [u8; HEADER_BYTES], directory_entries: Vec<[u8; DIRECTORY_BYTES]>,
83}
84
85impl FieldEntryRangePlan {
86    /// Validate header + directory + metadata prefix bytes for `entry` and build a range plan.
87    pub fn from_prefix(entry: &BundleEntry, prefix_bytes: &[u8], limits: EnvelopeLimits) -> Result<Self, FieldRangeError> {
88        let bundle_sha256: [u8; SHA256_LEN] = entry.sha256.as_slice().try_into().map_err(|_| FieldRangeError::InvalidBundleDigest)?;
89        entry.offset.checked_add(entry.length).ok_or(FieldRangeError::ExtentMismatch)?;
90        if prefix_bytes.len() < HEADER_BYTES { return Err(FieldRangeError::PrefixTooShort); }
91        let raw_header_bytes: [u8; HEADER_BYTES] = prefix_bytes[..HEADER_BYTES].try_into().unwrap();
92        let family = match &raw_header_bytes[..8] {
93            m if m == Family::EmfV4Candidate.magic() => Family::EmfV4Candidate,
94            m if m == Family::QacV1Candidate.magic() => Family::QacV1Candidate,
95            _ => return Err(FieldRangeError::InvalidFamilyMagic),
96        };
97        let version = u16le(&raw_header_bytes, 8);
98        if version != family.version() { return Err(FieldRangeError::UnsupportedVersion(version)); }
99        let (header_crc32c, got_hdr_crc) = (u32le(&raw_header_bytes, 124), block_crc32c_124(&raw_header_bytes));
100        if got_hdr_crc != header_crc32c { return Err(FieldRangeError::HeaderCrcMismatch { expected: header_crc32c, got: got_hdr_crc }); }
101        let (flags, file_bytes, entry_count) = (u32le(&raw_header_bytes, 12), u64le(&raw_header_bytes, 16), u32le(&raw_header_bytes, 32));
102        let (meta_offset, meta_length) = (u64le(&raw_header_bytes, 40), u64le(&raw_header_bytes, 48));
103        if u16le(&raw_header_bytes, 10) != 128 || flags & !1 != 0 || u64le(&raw_header_bytes, 24) != 128
104            || entry_count == 0 || u16le(&raw_header_bytes, 36) != 128 || u16le(&raw_header_bytes, 38) != 1
105            || raw_header_bytes[88..124].iter().any(|&b| b != 0)
106        {
107            return Err(FieldRangeError::InvalidHeaderFields);
108        }
109        if file_bytes != entry.length { return Err(FieldRangeError::ExtentMismatch); }
110        if file_bytes > limits.file_bytes || entry_count > limits.entries || meta_length > limits.metadata_bytes {
111            return Err(FieldRangeError::LimitExceeded);
112        }
113        let dir_len = u64::from(entry_count).checked_mul(128).ok_or(FieldRangeError::ExtentMismatch)?;
114        if meta_offset != 128u64.checked_add(dir_len).ok_or(FieldRangeError::ExtentMismatch)? { return Err(FieldRangeError::InvalidHeaderFields); }
115        let meta_end = meta_offset.checked_add(meta_length).ok_or(FieldRangeError::ExtentMismatch)?;
116        if (prefix_bytes.len() as u64) < meta_end { return Err(FieldRangeError::PrefixTooShort); }
117        let (dir_slice, meta_slice) = (&prefix_bytes[128..meta_offset as usize], &prefix_bytes[meta_offset as usize..meta_end as usize]);
118        let alignment = if flags & 1 != 0 { 4096u64 } else { 64u64 };
119        let mut next = align_up(meta_end, alignment)?;
120        if prefix_bytes.len() as u64 >= next && prefix_bytes[meta_end as usize..next as usize].iter().any(|&b| b != 0) {
121            return Err(FieldRangeError::ExtentMismatch);
122        }
123        let (mut directory_entries, mut required_descriptors) = (Vec::with_capacity(entry_count as usize), Vec::with_capacity(entry_count as usize));
124        let (mut prior_key, mut agg_decoded) = (None, 0u64);
125        for (idx0, row) in dir_slice.chunks_exact(128).enumerate() {
126            let (index, row_arr): (u32, [u8; 128]) = ((idx0 + 1) as u32, row.try_into().unwrap());
127            let (expected_crc, got_crc) = (u32le(&row_arr, 124), block_crc32c_124(&row_arr));
128            if got_crc != expected_crc { return Err(FieldRangeError::DirectoryEntryCrcMismatch { index, expected: expected_crc, got: got_crc }); }
129            let codec = u16le(&row_arr, 76);
130            if codec != 0 { return Err(FieldRangeError::InvalidCompressionCodec { index, codec }); }
131            let (eflags, stream_id, frame_id) = (u32le(&row_arr, 4), u32le(&row_arr, 8), u32le(&row_arr, 12));
132            let (start_tick, time_count, spatial_key) = (u64le(&row_arr, 16) as i64, u64le(&row_arr, 24), u64le(&row_arr, 32));
133            let (data_off, stored, decoded) = (u64le(&row_arr, 40), u64le(&row_arr, 48), u64le(&row_arr, 56));
134            let (records, stride, desc_id) = (u64le(&row_arr, 64), u32le(&row_arr, 72), u32le(&row_arr, 112));
135            if row_arr[78..80].iter().any(|&b| b != 0) || row_arr[116..124].iter().any(|&b| b != 0)
136                || eflags & !7 != 0 || desc_id == 0 || stride == 0 || records == 0
137                || (eflags & 2 == 0 && (start_tick != 0 || time_count != 0))
138                || (eflags & 2 != 0 && (time_count == 0 || stream_id == 0))
139                || (eflags & 4 == 0 && spatial_key != 0) || (eflags & 4 != 0 && frame_id == 0)
140            {
141                return Err(FieldRangeError::InvalidDirectoryEntry { index });
142            }
143            let key = (stream_id, start_tick, spatial_key, u16le(&row_arr, 0), desc_id);
144            if prior_key.is_some_and(|p| p >= key) { return Err(FieldRangeError::InvalidDirectoryOrder { index }); }
145            prior_key = Some(key);
146            let size = records.checked_mul(u64::from(stride)).ok_or(FieldRangeError::ExtentMismatch)?;
147            if stored != size || decoded != size { return Err(FieldRangeError::InvalidCompressionCodec { index, codec }); }
148            if data_off < next { return Err(FieldRangeError::OverlappingExtents { index }); }
149            if data_off != next { return Err(FieldRangeError::ExtentMismatch); }
150            agg_decoded = agg_decoded.checked_add(size).ok_or(FieldRangeError::ExtentMismatch)?;
151            if size > limits.chunk_bytes || agg_decoded > limits.aggregate_decoded_bytes { return Err(FieldRangeError::LimitExceeded); }
152            let end = next.checked_add(size).ok_or(FieldRangeError::ExtentMismatch)?;
153            next = align_up(end, alignment)?;
154            if prefix_bytes.len() as u64 >= next && prefix_bytes[end as usize..next as usize].iter().any(|&b| b != 0) {
155                return Err(FieldRangeError::InvalidCompressionCodec { index, codec });
156            }
157            required_descriptors.push(desc_id);
158            directory_entries.push(row_arr);
159        }
160        if next != file_bytes { return Err(FieldRangeError::ExtentMismatch); }
161        let mut root_header = raw_header_bytes;
162        root_header[56..88].fill(0);
163        root_header[124..128].fill(0);
164        let mut hasher = blake3::Hasher::new();
165        hasher.update(INDEX_DOMAIN).update(&root_header).update(dir_slice).update(meta_slice);
166        let index_commitment: [u8; 32] = raw_header_bytes[56..88].try_into().unwrap();
167        if *hasher.finalize().as_bytes() != index_commitment { return Err(FieldRangeError::IndexCommitmentMismatch); }
168        validate_metadata_tlv(family, meta_slice, limits, &required_descriptors)?;
169        Ok(Self {
170            bundle_key: entry.key.clone(), bundle_offset: entry.offset, bundle_length: entry.length,
171            bundle_sha256, family, entry_count, meta_offset, meta_length, meta_crc32c: crc32c(meta_slice),
172            header_crc32c, parent_header_digest: *blake3::hash(&raw_header_bytes).as_bytes(),
173            index_commitment, raw_header_bytes, directory_entries,
174        })
175    }
176
177    pub fn family(&self) -> Family { self.family }
178    pub fn entry_count(&self) -> u32 { self.entry_count }
179    pub fn parent_header_digest(&self) -> [u8; 32] { self.parent_header_digest }
180    pub fn index_commitment(&self) -> [u8; 32] { self.index_commitment }
181    pub fn hmc_meta_range(&self) -> Range<u64> { (self.bundle_offset + self.meta_offset)..(self.bundle_offset + self.meta_offset + self.meta_length) }
182
183    pub fn plan_chunk_range(&self, entry_index: u32) -> Result<PlannedChunkRange, FieldRangeError> {
184        if entry_index == 0 || entry_index > self.entry_count {
185            return Err(FieldRangeError::EntryIndexOutOfBounds { index: entry_index, count: self.entry_count });
186        }
187        let row = self.directory_entries[(entry_index - 1) as usize];
188        let (data_offset, data_length) = (u64le(&row, 40), u64le(&row, 48));
189        let hmc_data_start = self.bundle_offset.checked_add(data_offset).ok_or(FieldRangeError::ExtentMismatch)?;
190        let hmc_data_end = hmc_data_start.checked_add(data_length).ok_or(FieldRangeError::ExtentMismatch)?;
191        let hmc_meta_start = self.bundle_offset.checked_add(self.meta_offset).ok_or(FieldRangeError::ExtentMismatch)?;
192        let hmc_meta_end = hmc_meta_start.checked_add(self.meta_length).ok_or(FieldRangeError::ExtentMismatch)?;
193        Ok(PlannedChunkRange {
194            bundle_key: self.bundle_key.clone(), bundle_offset: self.bundle_offset, bundle_length: self.bundle_length,
195            family: self.family, entry_index, total_entry_count: self.entry_count, mode: u16le(&row, 0),
196            entry_flags: u32le(&row, 4), codec: u16le(&row, 76), descriptor_id: u32le(&row, 112),
197            data_offset, data_length, decoded_bytes: u64le(&row, 56), meta_offset: self.meta_offset,
198            meta_length: self.meta_length, hmc_data_range: hmc_data_start..hmc_data_end,
199            hmc_meta_range: hmc_meta_start..hmc_meta_end, payload_blake3: row[80..112].try_into().unwrap(),
200            meta_crc32c: self.meta_crc32c, entry_crc32c: u32le(&row, 124), header_crc32c: self.header_crc32c,
201            parent_header_digest: self.parent_header_digest, index_commitment: self.index_commitment,
202            raw_header_bytes: self.raw_header_bytes, raw_directory_entry_bytes: row,
203        })
204    }
205
206    pub fn plan_chunk_ranges(&self, indices: &[u32]) -> Result<Vec<PlannedChunkRange>, FieldRangeError> {
207        indices.iter().map(|&i| self.plan_chunk_range(i)).collect()
208    }
209
210    pub fn verify_arrived_chunk(&self, plan: &PlannedChunkRange, payload: &[u8], metadata: &[u8]) -> Result<VerifiedArrivedChunk, FieldRangeError> {
211        if plan.parent_header_digest != self.parent_header_digest || plan.index_commitment != self.index_commitment || plan.bundle_key != self.bundle_key {
212            return Err(FieldRangeError::CrossContainerSubstitution);
213        }
214        verify_arrived_field_chunk(plan, payload, metadata)
215    }
216
217    pub fn claim_whole_volume_receipt(&self, verified_chunks: &[VerifiedArrivedChunk], complete_entry_bytes: Option<&[u8]>) -> Result<[u8; SHA256_LEN], FieldRangeError> {
218        if verified_chunks.len() < self.entry_count as usize { return Err(FieldRangeError::PartialRangeCannotClaimWholeVolume); }
219        for idx in 1..=self.entry_count {
220            let Some(c) = verified_chunks.iter().find(|c| c.plan.entry_index == idx) else { return Err(FieldRangeError::PartialRangeCannotClaimWholeVolume); };
221            if c.plan.parent_header_digest != self.parent_header_digest { return Err(FieldRangeError::CrossContainerSubstitution); }
222        }
223        let Some(full_bytes) = complete_entry_bytes else { return Err(FieldRangeError::PartialRangeCannotClaimWholeVolume); };
224        if full_bytes.len() as u64 != self.bundle_length || Sha256::digest(full_bytes).as_slice() != self.bundle_sha256.as_slice() {
225            return Err(FieldRangeError::InvalidBundleDigest);
226        }
227        Ok(self.bundle_sha256)
228    }
229}
230
231/// A cryptographically verified arrived chunk and metadata TLV bound to its parent container.
232#[derive(Clone, Debug, PartialEq, Eq)]
233pub struct VerifiedArrivedChunk {
234    plan: PlannedChunkRange, payload: Vec<u8>, metadata: Vec<u8>, sparse_container_bytes: Vec<u8>,
235}
236
237/// Verify arrived chunk payload + metadata TLV bytes against the authenticated directory entry's
238/// `payload_blake3`, `meta_crc32c`, `entry_crc32c`, `mode`, `entry_flags`, and parent container
239/// header digest BEFORE any decode or admission.
240pub fn verify_arrived_field_chunk(plan: &PlannedChunkRange, arrived_payload: &[u8], arrived_metadata: &[u8]) -> Result<VerifiedArrivedChunk, FieldRangeError> {
241    if &plan.raw_header_bytes[..8] != plan.family.magic() || u16le(&plan.raw_header_bytes, 8) != plan.family.version() {
242        return Err(FieldRangeError::InvalidFamilyMagic);
243    }
244    let got_hdr_crc = block_crc32c_124(&plan.raw_header_bytes);
245    if got_hdr_crc != plan.header_crc32c || u32le(&plan.raw_header_bytes, 124) != plan.header_crc32c {
246        return Err(FieldRangeError::HeaderCrcMismatch { expected: plan.header_crc32c, got: got_hdr_crc });
247    }
248    if *blake3::hash(&plan.raw_header_bytes).as_bytes() != plan.parent_header_digest || plan.raw_header_bytes[56..88] != plan.index_commitment {
249        return Err(FieldRangeError::CrossContainerSubstitution);
250    }
251    let got_entry_crc = block_crc32c_124(&plan.raw_directory_entry_bytes);
252    if got_entry_crc != plan.entry_crc32c || u32le(&plan.raw_directory_entry_bytes, 124) != plan.entry_crc32c {
253        return Err(FieldRangeError::DirectoryEntryCrcMismatch { index: plan.entry_index, expected: plan.entry_crc32c, got: got_entry_crc });
254    }
255    let row = &plan.raw_directory_entry_bytes;
256    let row_mode = u16le(row, 0);
257    if row_mode != plan.mode { return Err(FieldRangeError::CrossModeReinterpretation { expected: row_mode, got: plan.mode }); }
258    let row_codec = u16le(row, 76);
259    if row_codec != 0 || plan.codec != 0 {
260        return Err(FieldRangeError::InvalidCompressionCodec { index: plan.entry_index, codec: plan.codec.max(row_codec) });
261    }
262    let expected_size = u64le(row, 64).checked_mul(u64::from(u32le(row, 72))).ok_or(FieldRangeError::ExtentMismatch)?;
263    if plan.data_length != expected_size || plan.decoded_bytes != expected_size {
264        return Err(FieldRangeError::InvalidCompressionCodec { index: plan.entry_index, codec: 0 });
265    }
266    if u32le(row, 4) != plan.entry_flags || plan.entry_flags & !7 != 0 || u64le(row, 40) != plan.data_offset
267        || u64le(row, 48) != plan.data_length || u64le(row, 56) != plan.decoded_bytes
268        || u32le(row, 112) != plan.descriptor_id || plan.descriptor_id == 0 || row[80..112] != plan.payload_blake3
269    {
270        return Err(FieldRangeError::InvalidDirectoryEntry { index: plan.entry_index });
271    }
272    if arrived_payload.len() as u64 != plan.data_length {
273        return Err(FieldRangeError::TruncatedOrMismatchedRange { expected: plan.data_length, got: arrived_payload.len() as u64 });
274    }
275    if arrived_metadata.len() as u64 != plan.meta_length {
276        return Err(FieldRangeError::TruncatedOrMismatchedRange { expected: plan.meta_length, got: arrived_metadata.len() as u64 });
277    }
278    let got_meta_crc = crc32c(arrived_metadata);
279    if got_meta_crc != plan.meta_crc32c { return Err(FieldRangeError::MetadataCrcMismatch { expected: plan.meta_crc32c, got: got_meta_crc }); }
280    validate_metadata_tlv(plan.family, arrived_metadata, EnvelopeLimits::default(), &[plan.descriptor_id])?;
281    if *blake3::hash(arrived_payload).as_bytes() != plan.payload_blake3 { return Err(FieldRangeError::PayloadBlake3Mismatch); }
282    let entry_input = row_to_entry_input(row, arrived_payload);
283    let env_input = env::EnvelopeInput {
284        family: plan.family, flags: u32le(&plan.raw_header_bytes, 12),
285        metadata: arrived_metadata, entries: std::slice::from_ref(&entry_input),
286    };
287    let env_len = env_input.encoded_len(EnvelopeLimits::default()).map_err(|_| FieldRangeError::ExtentMismatch)?;
288    let mut sparse_container_bytes = vec![0u8; env_len];
289    env_input.encode_into(&mut sparse_container_bytes, EnvelopeLimits::default()).map_err(|_| FieldRangeError::ExtentMismatch)?;
290    if plan.total_entry_count == 1 && sparse_container_bytes[56..88] != plan.index_commitment {
291        return Err(FieldRangeError::IndexCommitmentMismatch);
292    }
293    Ok(VerifiedArrivedChunk { plan: plan.clone(), payload: arrived_payload.to_vec(), metadata: arrived_metadata.to_vec(), sparse_container_bytes })
294}
295
296impl VerifiedArrivedChunk {
297    pub fn plan(&self) -> &PlannedChunkRange { &self.plan }
298    pub fn payload(&self) -> &[u8] { &self.payload }
299    pub fn metadata(&self) -> &[u8] { &self.metadata }
300    pub fn is_whole_volume_verified(&self) -> bool { false }
301    pub fn claim_whole_volume_receipt(&self) -> Result<[u8; SHA256_LEN], FieldRangeError> { Err(FieldRangeError::PartialRangeCannotClaimWholeVolume) }
302    pub fn require_mode(&self, expected_mode: u16) -> Result<(), FieldRangeError> {
303        if self.plan.mode != expected_mode { return Err(FieldRangeError::CrossModeReinterpretation { expected: expected_mode, got: self.plan.mode }); }
304        Ok(())
305    }
306
307    pub fn assemble_envelope_with_companions(&self, companions: &[&VerifiedArrivedChunk]) -> Result<Vec<u8>, FieldRangeError> {
308        if companions.is_empty() && self.plan.entry_index == 1 { return Ok(self.sparse_container_bytes.clone()); }
309        let mut all = vec![self];
310        for &c in companions {
311            if c.plan.parent_header_digest != self.plan.parent_header_digest || c.plan.index_commitment != self.plan.index_commitment || c.plan.family != self.plan.family {
312                return Err(FieldRangeError::CrossContainerSubstitution);
313            }
314            all.push(c);
315        }
316        all.sort_by_key(|c| c.plan.entry_index);
317        let inputs: Vec<env::EntryInput<'_>> = all.iter().map(|c| row_to_entry_input(&c.plan.raw_directory_entry_bytes, &c.payload)).collect();
318        let env_input = env::EnvelopeInput { family: self.plan.family, flags: u32le(&self.plan.raw_header_bytes, 12), metadata: &self.metadata, entries: &inputs };
319        let len = env_input.encoded_len(EnvelopeLimits::default()).map_err(|_| FieldRangeError::ExtentMismatch)?;
320        let mut out = vec![0u8; len];
321        env_input.encode_into(&mut out, EnvelopeLimits::default()).map_err(|_| FieldRangeError::ExtentMismatch)?;
322        Ok(out)
323    }
324
325    pub fn inspect_emf_profile<'a>(&'a self, scratch: &mut Scratch<'_>, limits: EmfProfileLimits, total_payload_work: u64) -> Result<ProfileChunk<'a>, FieldRangeError> {
326        if self.plan.family != Family::EmfV4Candidate { return Err(FieldRangeError::CrossModeReinterpretation { expected: self.plan.mode, got: self.plan.mode }); }
327        let view = StructuralView::open(&self.sparse_container_bytes, Family::EmfV4Candidate, EnvelopeLimits::default())
328            .map_err(|e| FieldRangeError::EmfAdmission(crate::q42::emf_profiles::Error::Storage(e)))?;
329        ProfileReader::open(&view, scratch, limits, total_payload_work).map_err(FieldRangeError::EmfAdmission)?.chunk(1).map_err(FieldRangeError::EmfAdmission)
330    }
331
332    pub fn inspect_qac_signal<'a>(&'a self, scratch: &mut Scratch<'_>, shared_limits: SharedSemanticLimits, limits: QacSignalLimits) -> Result<SignalView<'a>, FieldRangeError> {
333        if self.plan.family != Family::QacV1Candidate { return Err(FieldRangeError::CrossModeReinterpretation { expected: 0x0100, got: self.plan.mode }); }
334        let view = StructuralView::open(&self.sparse_container_bytes, Family::QacV1Candidate, EnvelopeLimits::default())
335            .map_err(|e| FieldRangeError::QacAdmission(signal::Error::Envelope(e)))?;
336        signal::admit(&view, 1, scratch, shared_limits, limits).map_err(FieldRangeError::QacAdmission)
337    }
338
339    pub fn inspect_acquisition_in_envelope<'a, 's>(
340        &self, assembled_envelope: &'a [u8], originals: &'s mut [Option<acq::Original<'a>>],
341        scratch: &mut Scratch<'_>, shared_limits: SharedSemanticLimits, limits: AcquisitionLimits,
342    ) -> Result<AcquisitionDocument<'a, 's>, FieldRangeError> {
343        self.require_mode(acq_storage::ORIGINAL_MODE)?;
344        let view = StructuralView::open(assembled_envelope, self.plan.family, EnvelopeLimits::default())
345            .map_err(|e| FieldRangeError::AcquisitionAdmission(acq_storage::Error::Envelope(e)))?;
346        acq_storage::admit(&view, self.plan.entry_index, originals, scratch, shared_limits, limits).map_err(FieldRangeError::AcquisitionAdmission)
347    }
348}
349
350#[cfg(test)]
351mod tests {
352    use super::*;
353    use crate::audio::qac::signal::{
354        writer::{
355            PcmDocument, PcmQuantity, PcmSamples, Provenance, ProvenanceRole, SignalRelation,
356            WriteBuffers, WriteOptions,
357        },
358        ExactTime, Rate, Timing,
359    };
360    use crate::bundle::BundleWriter;
361    use crate::q42::emf_profiles::{encode_field_samples, field_entry_slot, field_metadata_len, prepare_field_document, FieldChunkInput, FieldClock, FieldDocument, FieldFrame, FieldProvenance, FieldSample, FieldWriteLimits};
362    use crate::q42::field_semantics::NodeState;
363    use crate::sensing::SemanticId;
364
365    fn build_valid_emf_bytes(carrier_hz: f64) -> Vec<u8> {
366        let samples = [FieldSample { electric_v_per_m: [1.5, -0.5, 0.25], magnetic_tesla: [0.0, 5.0e-9, 0.0], position_m: [1.0, 2.0, 3.0], tick: 10, carrier_hz: Some(carrier_hz), stored_poynting_w_per_m2: None, confidence: Some(0.95) }];
367        let mut payload_buf = [0u8; 128];
368        let payload = encode_field_samples(&samples, &mut payload_buf, EmfProfileLimits::default()).unwrap();
369        let chunks = [FieldChunkInput { stream_id: 1, start_tick: 10, time_count: 1, spatial_key: None, payload }];
370        let doc = FieldDocument {
371            clock: FieldClock { scale: 1, epoch_seconds: 1_700_000_000, epoch_nanoseconds: 0, ticks_per_second_num: 1000, ticks_per_second_den: 1 },
372            frame: FieldFrame { origin_m: [0.0; 3], rotation_xyzw: [0.0, 0.0, 0.0, 1.0], grid: None },
373            provenance: FieldProvenance { role: 0, algorithm: Some("maxwell_probe"), algorithm_version: Some("1.0"), lineage: None },
374            temporal_step_ticks: Some(1), chunks: &chunks, align_payloads_to_4096: false,
375        };
376        let limits = FieldWriteLimits::default();
377        let (mut meta, mut slots) = (vec![0u8; field_metadata_len(&doc, limits).unwrap()], [field_entry_slot(); 1]);
378        let prep = prepare_field_document(&doc, &mut meta, &mut slots, limits).unwrap();
379        let len = prep.encoded_len().unwrap();
380        let (mut staging, mut out, mut m, mut e) = (vec![0u8; len], vec![0u8; len], [NodeState::default(); 64], [NodeState::default(); 16]);
381        prep.encode_into(&mut staging, &mut out, &mut Scratch { metadata: &mut m, entries: &mut e }).unwrap();
382        out
383    }
384
385    fn build_valid_qac_bytes(sample_val: f32) -> Vec<u8> {
386        let samples = [sample_val, -sample_val, 0.25, -0.25];
387        let rate = Rate::new(48_000, 1).unwrap();
388        let doc = PcmDocument {
389            samples: PcmSamples::F32(&samples), timing: Timing { scale: 1, epoch_seconds: 0, epoch_nanoseconds: 0, ticks: rate, samples: rate, start_tick: 0 },
390            stream_id: 1, channels: 1, channel_order: "mono", purpose: "test-pcm", quantity: PcmQuantity::Pressure, relation: SignalRelation::PhysicalBaseUnits,
391            units_per_stored_sample: 1.0, stored_offset: 0.0,
392            provenance: Provenance { role: ProvenanceRole::Measured, algorithm: None, algorithm_version: None, instrument_uri: Some("urn:qualia:mic:1"), lineage: None }, original: None,
393        };
394        let (mut meta, mut payload, mut staging, mut out) = (vec![0u8; 4096], vec![0u8; 4096], vec![0u8; 8192], vec![0u8; 8192]);
395        let (mut m, mut e) = ([NodeState::default(); 64], [NodeState::default(); 16]);
396        let n = doc.encode_into(WriteBuffers { metadata: &mut meta, payload: &mut payload, file: &mut staging }, &mut Scratch { metadata: &mut m, entries: &mut e }, &mut out, WriteOptions::default()).unwrap();
397        out.truncate(n);
398        out
399    }
400
401    fn build_acquisition_bytes(family: Family) -> Vec<u8> {
402        let (out_bytes, src_bytes) = ([0x10u8, 0x20, 0, 0, 0, 0, 0, 0, 0, 0x40], [1u8, 2, 3, 4, 5, 6, 7, 8]);
403        let (original, src_orig) = (acq::Original::admit(&out_bytes, 10).unwrap(), acq::Original::admit(&src_bytes, 8).unwrap());
404        let layout = acq::Layout { rank: 1, extents: [1, 0, 0, 0], strides: [8, 0, 0, 0], axes: [acq::Axis::Sample; 4], encoding: acq::Encoding::Shared(acq::Scalar::F64), byte_order: acq::ByteOrder::Little, components: acq::ComponentOrder::Scalar };
405        let ctx = acq::Context { quantity: acq::Quantity { kind: SemanticId::new(11).unwrap(), unit: SemanticId::new(12).unwrap() }, stage: acq::SampleStage::ReportedPhysical, sensor: SemanticId::new(13).unwrap(), geometry: None, calibration: None, uncertainty: None };
406        let axes = acq::SignalAxes { carrier: acq::Carrier::Unknown, baseband_hz: None, pulse_rate: None, complex_convention: None, phase_origin: None };
407        let tv = acq::TensorView::admit(original.region(2, 8).unwrap(), layout, ctx, None, axes).unwrap();
408        let (inputs, losses) = ([src_orig], [acq::Loss::Quantization]);
409        let link = acq::ArtifactLink { digest: [0x55; 32], identifier: SemanticId::new(99).unwrap() };
410        let deriv = Some(acq::Derivation::admit(original, &inputs, link, link, &losses, 8).unwrap());
411        let (mut meta, mut staging, mut out, mut m, mut e) = (vec![0u8; 16_384], vec![0u8; 65_536], vec![0u8; 65_536], [NodeState::default(); 256], [NodeState::default(); 128]);
412        let n = acq_storage::encode(acq_storage::Input { family, view: acq_storage::View::Tensor(tv), derivation: deriv }, &mut meta, &mut staging, &mut Scratch { metadata: &mut m, entries: &mut e }, &mut out, Default::default(), Default::default(), Default::default()).unwrap();
413        out.truncate(n);
414        out
415    }
416
417    #[test]
418    fn selective_hmc_range_planning_and_typed_emf_qac_verification() {
419        let (emf_bytes, qac_bytes) = (build_valid_emf_bytes(2.4e9), build_valid_qac_bytes(0.5));
420        let mut w = BundleWriter::new();
421        w.add_file("field.emf", "emf", emf_bytes.clone(), None).unwrap();
422        w.add_file("voice.qac", "qac", qac_bytes.clone(), None).unwrap();
423        let hmc = w.build().unwrap();
424        let reader = crate::bundle::BundleReader::parse(&hmc).unwrap();
425        let emf_plan = FieldEntryRangePlan::from_prefix(reader.entry("field.emf").unwrap(), &emf_bytes, EnvelopeLimits::default()).unwrap();
426        let c1 = emf_plan.plan_chunk_range(1).unwrap();
427        let verified_emf = emf_plan.verify_arrived_chunk(&c1, &hmc[c1.hmc_data_range.start as usize..c1.hmc_data_range.end as usize], &hmc[c1.hmc_meta_range.start as usize..c1.hmc_meta_range.end as usize]).unwrap();
428        assert!(!verified_emf.is_whole_volume_verified());
429        assert_eq!(verified_emf.claim_whole_volume_receipt(), Err(FieldRangeError::PartialRangeCannotClaimWholeVolume));
430        let (mut m, mut e) = ([NodeState::default(); 64], [NodeState::default(); 16]);
431        let chunk = verified_emf.inspect_emf_profile(&mut Scratch { metadata: &mut m, entries: &mut e }, EmfProfileLimits::default(), 1 << 20).unwrap();
432        assert_eq!(chunk.field(0).unwrap().unwrap().carrier_hz(), Some(2.4e9));
433        let qac_plan = FieldEntryRangePlan::from_prefix(reader.entry("voice.qac").unwrap(), &qac_bytes, EnvelopeLimits::default()).unwrap();
434        let qc1 = qac_plan.plan_chunk_range(1).unwrap();
435        let verified_qac = verify_arrived_field_chunk(&qc1, &hmc[qc1.hmc_data_range.start as usize..qc1.hmc_data_range.end as usize], &hmc[qc1.hmc_meta_range.start as usize..qc1.hmc_meta_range.end as usize]).unwrap();
436        let sig = verified_qac.inspect_qac_signal(&mut Scratch { metadata: &mut m, entries: &mut e }, SharedSemanticLimits::default(), QacSignalLimits::default()).unwrap();
437        assert_eq!(sig.records(), 4);
438        assert_eq!(sig.time_at(0).unwrap(), ExactTime { numerator: 0, denominator: 48_000 });
439    }
440
441    #[test]
442    fn mixed_domain_mode_0x0104_schema_6_and_7_inspection_on_arrived_chunks() {
443        for family in [Family::EmfV4Candidate, Family::QacV1Candidate] {
444            let acq_bytes = build_acquisition_bytes(family);
445            let mut w = BundleWriter::new();
446            w.add_file("sensor.bin", "acq", acq_bytes.clone(), None).unwrap();
447            let hmc = w.build().unwrap();
448            let reader = crate::bundle::BundleReader::parse(&hmc).unwrap();
449            let plan = FieldEntryRangePlan::from_prefix(reader.entry("sensor.bin").unwrap(), &acq_bytes, EnvelopeLimits::default()).unwrap();
450            let ranges = plan.plan_chunk_ranges(&[1, 2]).unwrap();
451            let meta = &hmc[ranges[0].hmc_meta_range.start as usize..ranges[0].hmc_meta_range.end as usize];
452            let v1 = plan.verify_arrived_chunk(&ranges[0], &hmc[ranges[0].hmc_data_range.start as usize..ranges[0].hmc_data_range.end as usize], meta).unwrap();
453            let v2 = plan.verify_arrived_chunk(&ranges[1], &hmc[ranges[1].hmc_data_range.start as usize..ranges[1].hmc_data_range.end as usize], meta).unwrap();
454            assert_eq!(plan.claim_whole_volume_receipt(std::slice::from_ref(&v1), Some(&acq_bytes)), Err(FieldRangeError::PartialRangeCannotClaimWholeVolume));
455            let assembled = v1.assemble_envelope_with_companions(&[&v2]).unwrap();
456            let (mut originals, mut m, mut e) = ([None; 8], [NodeState::default(); 256], [NodeState::default(); 128]);
457            let doc = v1.inspect_acquisition_in_envelope(&assembled, &mut originals, &mut Scratch { metadata: &mut m, entries: &mut e }, SharedSemanticLimits::default(), AcquisitionLimits::default()).unwrap();
458            let acq_storage::View::Tensor(tv) = doc.view else { panic!("expected tensor view") };
459            assert_eq!(tv.numeric([0, 0, 0, 0]).unwrap(), [2.0, 0.0]);
460            let lineage = doc.lineage.expect("Schema 7 derivation lineage present");
461            assert_eq!((lineage.output_entry(), lineage.input_entry(0).unwrap()), (1, 2));
462        }
463    }
464
465    #[test]
466    fn anti_substitution_tampering_and_codec_invariants_reject() {
467        let (emf_a, emf_b, qac_a) = (build_valid_emf_bytes(1.0e9), build_valid_emf_bytes(5.0e9), build_valid_qac_bytes(0.25));
468        let mut w = BundleWriter::new();
469        w.add_file("a.emf", "emf", emf_a.clone(), None).unwrap();
470        w.add_file("b.emf", "emf", emf_b.clone(), None).unwrap();
471        w.add_file("a.qac", "qac", qac_a.clone(), None).unwrap();
472        let hmc = w.build().unwrap();
473        let reader = crate::bundle::BundleReader::parse(&hmc).unwrap();
474        let plan_a = FieldEntryRangePlan::from_prefix(reader.entry("a.emf").unwrap(), &emf_a, Default::default()).unwrap();
475        let plan_b = FieldEntryRangePlan::from_prefix(reader.entry("b.emf").unwrap(), &emf_b, Default::default()).unwrap();
476        let plan_q = FieldEntryRangePlan::from_prefix(reader.entry("a.qac").unwrap(), &qac_a, Default::default()).unwrap();
477        let (ca, cb, cq) = (plan_a.plan_chunk_range(1).unwrap(), plan_b.plan_chunk_range(1).unwrap(), plan_q.plan_chunk_range(1).unwrap());
478        let (pay_a, meta_a, pay_b) = (&hmc[ca.hmc_data_range.start as usize..ca.hmc_data_range.end as usize], &hmc[ca.hmc_meta_range.start as usize..ca.hmc_meta_range.end as usize], &hmc[cb.hmc_data_range.start as usize..cb.hmc_data_range.end as usize]);
479        assert_eq!(plan_a.verify_arrived_chunk(&cb, pay_b, meta_a), Err(FieldRangeError::CrossContainerSubstitution));
480        assert_eq!(verify_arrived_field_chunk(&ca, pay_b, meta_a), Err(FieldRangeError::PayloadBlake3Mismatch));
481        let mut forged_mode = ca.clone();
482        forged_mode.mode = 0x0104;
483        assert_eq!(verify_arrived_field_chunk(&forged_mode, pay_a, meta_a), Err(FieldRangeError::CrossModeReinterpretation { expected: 0, got: 0x0104 }));
484        let va = verify_arrived_field_chunk(&ca, pay_a, meta_a).unwrap();
485        let vq = verify_arrived_field_chunk(&cq, &hmc[cq.hmc_data_range.start as usize..cq.hmc_data_range.end as usize], &hmc[cq.hmc_meta_range.start as usize..cq.hmc_meta_range.end as usize]).unwrap();
486        assert_eq!(va.assemble_envelope_with_companions(&[&vq]), Err(FieldRangeError::CrossContainerSubstitution));
487        let (mut bad_pay, mut bad_meta) = (pay_a.to_vec(), meta_a.to_vec());
488        bad_pay[0] ^= 1;
489        bad_meta[20] ^= 1;
490        assert_eq!(verify_arrived_field_chunk(&ca, &bad_pay, meta_a), Err(FieldRangeError::PayloadBlake3Mismatch));
491        assert!(matches!(verify_arrived_field_chunk(&ca, pay_a, &bad_meta), Err(FieldRangeError::MetadataCrcMismatch { .. })));
492        assert!(matches!(verify_arrived_field_chunk(&ca, &pay_a[..pay_a.len() - 1], meta_a), Err(FieldRangeError::TruncatedOrMismatchedRange { .. })));
493        let mut bad_codec = ca.clone();
494        bad_codec.decoded_bytes += 64;
495        assert_eq!(verify_arrived_field_chunk(&bad_codec, pay_a, meta_a), Err(FieldRangeError::InvalidCompressionCodec { index: 1, codec: 0 }));
496    }
497}