Skip to main content

qualia_core_db/q42/asset_envelope/
codec.rs

1//! Deterministic binary codec for [`Q42AssetEnvelope`].
2
3use super::envelope::{
4    AssetRoutingLane, AssetSensitivity, ChunkSpec, Q42AssetEnvelope, RecordCounts,
5    ToolchainVersions, UpstreamRelease, ASSET_ENVELOPE_VERSION, MAX_ENVELOPE_BYTES,
6};
7use super::error::AssetEnvelopeError;
8use super::licence::{
9    LicenceClass, LicenceObligations, LicencePolicy, RedistributionClass, UseClass,
10};
11
12pub const ASSET_ENVELOPE_MAGIC: [u8; 8] = *b"Q42AST\0\0";
13
14fn write_u16(buf: &mut Vec<u8>, value: u16) {
15    buf.extend_from_slice(&value.to_le_bytes());
16}
17
18fn write_u32(buf: &mut Vec<u8>, value: u32) {
19    buf.extend_from_slice(&value.to_le_bytes());
20}
21
22fn write_u64(buf: &mut Vec<u8>, value: u64) {
23    buf.extend_from_slice(&value.to_le_bytes());
24}
25
26fn write_str(buf: &mut Vec<u8>, value: &str) -> Result<(), AssetEnvelopeError> {
27    let bytes = value.as_bytes();
28    let len = u16::try_from(bytes.len()).map_err(|_| AssetEnvelopeError::Oversize)?;
29    write_u16(buf, len);
30    buf.extend_from_slice(bytes);
31    Ok(())
32}
33
34fn write_str_list(buf: &mut Vec<u8>, values: &[String]) -> Result<(), AssetEnvelopeError> {
35    let len = u16::try_from(values.len()).map_err(|_| AssetEnvelopeError::Oversize)?;
36    write_u16(buf, len);
37    for value in values {
38        write_str(buf, value)?;
39    }
40    Ok(())
41}
42
43fn read_u16(bytes: &[u8], cursor: &mut usize) -> Result<u16, AssetEnvelopeError> {
44    if *cursor + 2 > bytes.len() {
45        return Err(AssetEnvelopeError::Truncated);
46    }
47    let value = u16::from_le_bytes(bytes[*cursor..*cursor + 2].try_into().unwrap());
48    *cursor += 2;
49    Ok(value)
50}
51
52fn read_u32(bytes: &[u8], cursor: &mut usize) -> Result<u32, AssetEnvelopeError> {
53    if *cursor + 4 > bytes.len() {
54        return Err(AssetEnvelopeError::Truncated);
55    }
56    let value = u32::from_le_bytes(bytes[*cursor..*cursor + 4].try_into().unwrap());
57    *cursor += 4;
58    Ok(value)
59}
60
61fn read_u64(bytes: &[u8], cursor: &mut usize) -> Result<u64, AssetEnvelopeError> {
62    if *cursor + 8 > bytes.len() {
63        return Err(AssetEnvelopeError::Truncated);
64    }
65    let value = u64::from_le_bytes(bytes[*cursor..*cursor + 8].try_into().unwrap());
66    *cursor += 8;
67    Ok(value)
68}
69
70fn read_bytes32(bytes: &[u8], cursor: &mut usize) -> Result<[u8; 32], AssetEnvelopeError> {
71    if *cursor + 32 > bytes.len() {
72        return Err(AssetEnvelopeError::Truncated);
73    }
74    let mut out = [0u8; 32];
75    out.copy_from_slice(&bytes[*cursor..*cursor + 32]);
76    *cursor += 32;
77    Ok(out)
78}
79
80fn read_str(bytes: &[u8], cursor: &mut usize) -> Result<String, AssetEnvelopeError> {
81    let len = read_u16(bytes, cursor)? as usize;
82    if *cursor + len > bytes.len() {
83        return Err(AssetEnvelopeError::Truncated);
84    }
85    let slice = &bytes[*cursor..*cursor + len];
86    *cursor += len;
87    std::str::from_utf8(slice)
88        .map(|s| s.to_string())
89        .map_err(|_| AssetEnvelopeError::InvalidUtf8)
90}
91
92fn read_str_list(bytes: &[u8], cursor: &mut usize) -> Result<Vec<String>, AssetEnvelopeError> {
93    let count = read_u16(bytes, cursor)? as usize;
94    let mut out = Vec::with_capacity(count);
95    for _ in 0..count {
96        out.push(read_str(bytes, cursor)?);
97    }
98    Ok(out)
99}
100
101impl Q42AssetEnvelope {
102    /// Deterministic little-endian encode. Fails if validation or size budget fails.
103    pub fn encode(&self) -> Result<Vec<u8>, AssetEnvelopeError> {
104        self.validate()?;
105        let mut buf = Vec::with_capacity(512);
106        buf.extend_from_slice(&ASSET_ENVELOPE_MAGIC);
107        write_u16(&mut buf, ASSET_ENVELOPE_VERSION);
108        write_u16(&mut buf, 0); // reserved
109        write_str(&mut buf, &self.asset_id)?;
110        write_str(&mut buf, &self.upstream.source_name)?;
111        write_str(&mut buf, &self.upstream.release_id)?;
112        write_str(&mut buf, &self.upstream.source_url)?;
113        write_u64(&mut buf, self.upstream.retrieved_unix);
114        write_u64(&mut buf, self.upstream.byte_length);
115        buf.extend_from_slice(&self.upstream.sha256);
116        buf.push(self.licence.class as u8);
117        buf.push(self.licence.use_class as u8);
118        buf.push(self.licence.redistribution as u8);
119        buf.push(0); // pad
120        write_u16(&mut buf, self.licence.obligations.0);
121        write_str(&mut buf, &self.licence.terms_url)?;
122        write_str(&mut buf, &self.licence.attribution)?;
123        write_str(&mut buf, &self.toolchain.parser_version)?;
124        write_str(&mut buf, &self.toolchain.mapping_version)?;
125        write_str(&mut buf, &self.raw_format)?;
126        write_str(&mut buf, &self.media_type)?;
127        write_u64(&mut buf, self.counts.source);
128        write_u64(&mut buf, self.counts.accepted);
129        write_u64(&mut buf, self.counts.quarantined);
130        write_str_list(&mut buf, &self.rejection_reasons)?;
131        write_str_list(&mut buf, &self.identifier_namespaces)?;
132        write_str(&mut buf, &self.cross_reference_policy)?;
133        write_str(&mut buf, &self.evidence_grade)?;
134        write_str(&mut buf, &self.citation)?;
135        write_str(&mut buf, &self.curation_status)?;
136        buf.push(self.sensitivity as u8);
137        buf.push(self.routing_lane as u8);
138        write_u16(&mut buf, 0); // pad
139        write_str_list(&mut buf, &self.derived_from)?;
140        write_str(&mut buf, &self.shacl_profile)?;
141        write_str(&mut buf, &self.validation_report)?;
142        let chunk_len =
143            u16::try_from(self.chunk_plan.len()).map_err(|_| AssetEnvelopeError::Oversize)?;
144        write_u16(&mut buf, chunk_len);
145        for chunk in &self.chunk_plan {
146            write_u32(&mut buf, chunk.index);
147            write_u64(&mut buf, chunk.byte_budget);
148            write_u64(&mut buf, chunk.record_budget);
149        }
150        if buf.len() > MAX_ENVELOPE_BYTES {
151            return Err(AssetEnvelopeError::Oversize);
152        }
153        Ok(buf)
154    }
155
156    /// Decode and re-validate.
157    pub fn decode(bytes: &[u8]) -> Result<Self, AssetEnvelopeError> {
158        if bytes.len() < 12 {
159            return Err(AssetEnvelopeError::Truncated);
160        }
161        if bytes.len() > MAX_ENVELOPE_BYTES {
162            return Err(AssetEnvelopeError::Oversize);
163        }
164        if bytes[0..8] != ASSET_ENVELOPE_MAGIC {
165            return Err(AssetEnvelopeError::InvalidMagic);
166        }
167        let mut cursor = 8;
168        let version = read_u16(bytes, &mut cursor)?;
169        if version != ASSET_ENVELOPE_VERSION {
170            return Err(AssetEnvelopeError::UnsupportedVersion);
171        }
172        let _reserved = read_u16(bytes, &mut cursor)?;
173        let asset_id = read_str(bytes, &mut cursor)?;
174        let upstream = UpstreamRelease {
175            source_name: read_str(bytes, &mut cursor)?,
176            release_id: read_str(bytes, &mut cursor)?,
177            source_url: read_str(bytes, &mut cursor)?,
178            retrieved_unix: read_u64(bytes, &mut cursor)?,
179            byte_length: read_u64(bytes, &mut cursor)?,
180            sha256: read_bytes32(bytes, &mut cursor)?,
181        };
182        if cursor + 4 > bytes.len() {
183            return Err(AssetEnvelopeError::Truncated);
184        }
185        let class = LicenceClass::from_u8(bytes[cursor]);
186        let use_class = UseClass::from_u8(bytes[cursor + 1]);
187        let redistribution = RedistributionClass::from_u8(bytes[cursor + 2]);
188        cursor += 4;
189        let obligations = LicenceObligations(read_u16(bytes, &mut cursor)?);
190        let terms_url = read_str(bytes, &mut cursor)?;
191        let attribution = read_str(bytes, &mut cursor)?;
192        // Reconstruct via try_new so Unknown fails closed even if wire was tampered.
193        let mut licence =
194            LicencePolicy::try_new(class, use_class, redistribution, terms_url, attribution)?;
195        // Preserve exact obligation bitfield from the wire (union may have added flags).
196        licence.obligations = obligations;
197        let toolchain = ToolchainVersions {
198            parser_version: read_str(bytes, &mut cursor)?,
199            mapping_version: read_str(bytes, &mut cursor)?,
200        };
201        let raw_format = read_str(bytes, &mut cursor)?;
202        let media_type = read_str(bytes, &mut cursor)?;
203        let counts = RecordCounts {
204            source: read_u64(bytes, &mut cursor)?,
205            accepted: read_u64(bytes, &mut cursor)?,
206            quarantined: read_u64(bytes, &mut cursor)?,
207        };
208        let rejection_reasons = read_str_list(bytes, &mut cursor)?;
209        let identifier_namespaces = read_str_list(bytes, &mut cursor)?;
210        let cross_reference_policy = read_str(bytes, &mut cursor)?;
211        let evidence_grade = read_str(bytes, &mut cursor)?;
212        let citation = read_str(bytes, &mut cursor)?;
213        let curation_status = read_str(bytes, &mut cursor)?;
214        if cursor + 4 > bytes.len() {
215            return Err(AssetEnvelopeError::Truncated);
216        }
217        let sensitivity = AssetSensitivity::from_u8(bytes[cursor])?;
218        let routing_lane = AssetRoutingLane::from_u8(bytes[cursor + 1])?;
219        cursor += 4;
220        let derived_from = read_str_list(bytes, &mut cursor)?;
221        let shacl_profile = read_str(bytes, &mut cursor)?;
222        let validation_report = read_str(bytes, &mut cursor)?;
223        let chunk_count = read_u16(bytes, &mut cursor)? as usize;
224        let mut chunk_plan = Vec::with_capacity(chunk_count);
225        for _ in 0..chunk_count {
226            chunk_plan.push(ChunkSpec {
227                index: read_u32(bytes, &mut cursor)?,
228                byte_budget: read_u64(bytes, &mut cursor)?,
229                record_budget: read_u64(bytes, &mut cursor)?,
230            });
231        }
232        if cursor != bytes.len() {
233            return Err(AssetEnvelopeError::Truncated);
234        }
235        let envelope = Self {
236            asset_id,
237            upstream,
238            licence,
239            toolchain,
240            raw_format,
241            media_type,
242            counts,
243            rejection_reasons,
244            identifier_namespaces,
245            cross_reference_policy,
246            evidence_grade,
247            citation,
248            curation_status,
249            sensitivity,
250            routing_lane,
251            derived_from,
252            shacl_profile,
253            validation_report,
254            chunk_plan,
255        };
256        envelope.validate()?;
257        Ok(envelope)
258    }
259
260    /// Deterministic digest of the encoded envelope bytes (not the payload).
261    pub fn envelope_digest(&self) -> Result<[u8; 32], AssetEnvelopeError> {
262        let encoded = self.encode()?;
263        Ok(super::envelope::sha256_of(&encoded))
264    }
265}