Skip to main content

hara_hta/
lib.rs

1//! Dependency-free canonical HTA0 codec for portable Hara ABI values.
2//!
3//! `hara-hta` deliberately operates on [`hara_abi::Value`] rather than the
4//! executable runtime value graph. It is suitable for native providers,
5//! package tooling, embedding hosts, and durable state boundaries that need
6//! canonical Hara bytes without linking the VM, Wasmtime, or host services.
7
8pub mod view;
9
10use hara_abi::{ExceptionProvenance, ExceptionSite, ImmutableValue as Value, Value as AbiValue};
11use std::collections::BTreeMap;
12
13pub const MAGIC: &[u8; 4] = b"HTA0";
14pub const MAX_FRAME_BYTES: usize = 64 * 1024 * 1024;
15pub const MAX_NESTING_DEPTH: usize = 256;
16
17const NIL: u8 = 0;
18const FALSE: u8 = 1;
19const TRUE: u8 = 2;
20const I64: u8 = 3;
21const STRING: u8 = 4;
22const BYTES: u8 = 5;
23const KEYWORD: u8 = 6;
24const SYMBOL: u8 = 7;
25const LIST: u8 = 8;
26const VECTOR: u8 = 9;
27const SET: u8 = 10;
28const MAP: u8 = 11;
29const HANDLE: u8 = 12;
30const NAMESPACE: u8 = 13;
31const VAR: u8 = 14;
32const F64: u8 = 15;
33const ATOM: u8 = 16;
34const ARRAY: u8 = 17;
35const OBJECT: u8 = 18;
36const CHARACTER: u8 = 19;
37const BIG_INTEGER: u8 = 20;
38const REGEX: u8 = 22;
39const TUPLE: u8 = 23;
40const MAP_ENTRY: u8 = 38;
41const CONS: u8 = 24;
42const QUEUE: u8 = 25;
43const ORDERED_MAP: u8 = 26;
44const SORTED_MAP: u8 = 27;
45const TRIE: u8 = 28;
46const ORDERED_SET: u8 = 29;
47const SORTED_SET: u8 = 30;
48const TAGGED: u8 = 31;
49const EXCEPTION_INFO: u8 = 32;
50const STRUCT: u8 = 33;
51const POINTER: u8 = 34;
52const VAR_REF: u8 = 35;
53
54fn provenance_value(provenance: &ExceptionProvenance) -> Value {
55    let mut fields = BTreeMap::new();
56    fields.insert(
57        "ex/created-at".into(),
58        provenance
59            .created_at
60            .as_ref()
61            .map(site_value)
62            .unwrap_or(Value::Nil),
63    );
64    fields.insert(
65        "ex/throws".into(),
66        Value::Vector(provenance.throws.iter().map(site_value).collect()),
67    );
68    Value::Record(fields)
69}
70
71fn site_value(site: &ExceptionSite) -> Value {
72    let mut fields = BTreeMap::new();
73    fields.insert(
74        "namespace".into(),
75        site.namespace
76            .clone()
77            .map(Value::String)
78            .unwrap_or(Value::Nil),
79    );
80    fields.insert(
81        "resource".into(),
82        site.resource
83            .clone()
84            .map(Value::String)
85            .unwrap_or(Value::Nil),
86    );
87    fields.insert("line".into(), Value::Integer(site.line as i64));
88    fields.insert("column".into(), Value::Integer(site.column as i64));
89    Value::Record(fields)
90}
91
92fn decode_provenance(value: Value) -> Result<ExceptionProvenance, String> {
93    let Value::Record(fields) = value else {
94        return Err("hta/value-malformed: invalid exception provenance".into());
95    };
96    if fields.len() != 2
97        || !fields.contains_key("ex/created-at")
98        || !fields.contains_key("ex/throws")
99    {
100        return Err("hta/value-malformed: invalid exception provenance fields".into());
101    }
102    let created_at = match fields.get("ex/created-at").expect("checked above") {
103        Value::Nil => None,
104        value => Some(decode_site(value)?),
105    };
106    let Value::Vector(throws) = fields.get("ex/throws").expect("checked above") else {
107        return Err("hta/value-malformed: invalid exception throws provenance".into());
108    };
109    Ok(ExceptionProvenance {
110        created_at,
111        throws: throws.iter().map(decode_site).collect::<Result<_, _>>()?,
112    })
113}
114
115fn decode_site(value: &Value) -> Result<ExceptionSite, String> {
116    let Value::Record(fields) = value else {
117        return Err("hta/value-malformed: invalid exception provenance site".into());
118    };
119    if fields.len() != 4
120        || !fields.contains_key("namespace")
121        || !fields.contains_key("resource")
122        || !fields.contains_key("line")
123        || !fields.contains_key("column")
124    {
125        return Err("hta/value-malformed: invalid exception provenance site".into());
126    }
127    let optional_string = |name: &str| match fields.get(name).expect("checked above") {
128        Value::Nil => Ok(None),
129        Value::String(value) => Ok(Some(value.clone())),
130        _ => Err(format!(
131            "hta/value-malformed: invalid exception provenance {name}"
132        )),
133    };
134    let nonnegative = |name: &str| match fields.get(name).expect("checked above") {
135        Value::Integer(value) if *value >= 0 => Ok(*value as u64),
136        _ => Err(format!(
137            "hta/value-malformed: invalid exception provenance {name}"
138        )),
139    };
140    Ok(ExceptionSite {
141        namespace: optional_string("namespace")?,
142        resource: optional_string("resource")?,
143        line: nonnegative("line")?,
144        column: nonnegative("column")?,
145    })
146}
147
148/// Encode one portable value as an exact canonical HTA0 frame.
149pub fn encode_immutable(value: &Value) -> Result<Vec<u8>, String> {
150    let mut output = Vec::with_capacity(128);
151    write(&mut output, MAGIC)?;
152    encode_value(value, 0, &mut output)?;
153    Ok(output)
154}
155
156/// Decode one exact canonical HTA0 frame into a portable value.
157///
158/// Runtime-only wire tags such as symbols, lists, sets, handles, namespaces,
159/// vars, atoms, arrays, objects, characters, big integers, and regex values
160/// fail closed. HTA maps decode only when every key is a unique keyword, which
161/// maps directly to [`Value::Record`].
162pub fn decode_immutable(bytes: &[u8]) -> Result<Value, String> {
163    if bytes.len() > MAX_FRAME_BYTES {
164        return Err(format!(
165            "hta/frame-too-large: {} exceeds {} bytes",
166            bytes.len(),
167            MAX_FRAME_BYTES
168        ));
169    }
170    if !bytes.starts_with(MAGIC) {
171        return Err("hta/frame-invalid: expected HTA0 magic".into());
172    }
173    let mut reader = Reader {
174        bytes: &bytes[MAGIC.len()..],
175        cursor: 0,
176    };
177    let value = reader.value(0)?;
178    if reader.cursor != reader.bytes.len() {
179        return Err("hta/frame-invalid: trailing bytes".into());
180    }
181    Ok(value)
182}
183
184/// Decode one portable HTA0 value only when the supplied bytes are bounded and
185/// already use the exact canonical encoding produced by [`encode`].
186///
187/// This is the generic provider boundary for small values. It deliberately does
188/// not read an object, compute a digest, select a provider, or interpret an
189/// application schema. Callers must verify immutable-object identity separately.
190pub fn decode_immutable_canonical(bytes: &[u8], max_bytes: usize) -> Result<Value, String> {
191    if max_bytes == 0 || max_bytes > MAX_FRAME_BYTES {
192        return Err(format!(
193            "hta/maximum-invalid: requested maximum must be between 1 and {MAX_FRAME_BYTES} bytes"
194        ));
195    }
196    if bytes.len() > max_bytes {
197        return Err(format!(
198            "hta/frame-too-large: {} exceeds requested maximum {} bytes",
199            bytes.len(),
200            max_bytes
201        ));
202    }
203
204    let value = decode_immutable(bytes)?;
205    let canonical = encode_immutable(&value)?;
206    if canonical != bytes {
207        return Err("hta/frame-noncanonical: decoded value has different canonical bytes".into());
208    }
209    Ok(value)
210}
211
212/// Encode the stable provider ABI subset using the full immutable codec.
213pub fn encode(value: &AbiValue) -> Result<Vec<u8>, String> {
214    encode_immutable(&abi_to_immutable(value)?)
215}
216
217/// Decode only values representable by the stable provider ABI subset.
218pub fn decode(bytes: &[u8]) -> Result<AbiValue, String> {
219    immutable_to_abi(decode_immutable(bytes)?)
220}
221
222pub fn decode_canonical(bytes: &[u8], max_bytes: usize) -> Result<AbiValue, String> {
223    immutable_to_abi(decode_immutable_canonical(bytes, max_bytes)?)
224}
225
226pub(crate) fn canonical_big_integer(value: &str) -> Result<Value, String> {
227    let (negative, digits) = match value.strip_prefix('-') {
228        Some(digits) => (true, digits),
229        None => (false, value),
230    };
231    if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
232        return Err("hta/value-malformed: invalid big integer".into());
233    }
234    let digits = digits.trim_start_matches('0');
235    let digits = if digits.is_empty() { "0" } else { digits };
236    let canonical = if negative && digits != "0" {
237        format!("-{digits}")
238    } else {
239        digits.to_owned()
240    };
241    match canonical.parse::<i64>() {
242        Ok(value) => Ok(Value::Integer(value)),
243        Err(_) => Ok(Value::BigInteger(canonical)),
244    }
245}
246
247pub(crate) fn validate_canonical_big_integer(value: &str) -> Result<(), String> {
248    match canonical_big_integer(value)? {
249        Value::BigInteger(canonical) if canonical == value => Ok(()),
250        Value::BigInteger(_) => {
251            Err("hta/value-noncanonical: big integer text is not canonical".into())
252        }
253        Value::Integer(_) => {
254            Err("hta/value-noncanonical: signed 64-bit integers use the i64 tag".into())
255        }
256        _ => unreachable!("canonical big integer returned a non-integer value"),
257    }
258}
259
260fn abi_to_immutable(value: &AbiValue) -> Result<Value, String> {
261    Ok(match value {
262        AbiValue::Nil => Value::Nil,
263        AbiValue::Boolean(value) => Value::Boolean(*value),
264        AbiValue::String(value) => Value::String(value.clone()),
265        AbiValue::Integer(value) => Value::Integer(*value),
266        AbiValue::BigInteger(value) => canonical_big_integer(value)?,
267        AbiValue::Float(value) => {
268            if !value.is_finite() {
269                return Err("hta/non-finite number".into());
270            }
271            Value::Float(*value)
272        }
273        AbiValue::Bytes(value) => Value::Bytes(value.clone()),
274        AbiValue::Keyword(value) => Value::Keyword(value.clone()),
275        AbiValue::Vector(values) => Value::Vector(
276            values
277                .iter()
278                .map(abi_to_immutable)
279                .collect::<Result<Vec<_>, _>>()?,
280        ),
281        AbiValue::Record(values) => Value::Record(
282            values
283                .iter()
284                .map(|(key, value)| Ok((key.clone(), abi_to_immutable(value)?)))
285                .collect::<Result<_, String>>()?,
286        ),
287    })
288}
289
290fn immutable_to_abi(value: Value) -> Result<AbiValue, String> {
291    Ok(match value {
292        Value::Nil => AbiValue::Nil,
293        Value::Boolean(value) => AbiValue::Boolean(value),
294        Value::String(value) => AbiValue::String(value),
295        Value::Integer(value) => AbiValue::Integer(value),
296        Value::BigInteger(value) => match canonical_big_integer(&value)? {
297            Value::Integer(value) => AbiValue::Integer(value),
298            Value::BigInteger(value) => AbiValue::BigInteger(value),
299            _ => unreachable!("canonical big integer returned a non-integer value"),
300        },
301        Value::Float(value) => {
302            if !value.is_finite() {
303                return Err("hta/non-finite number".into());
304            }
305            AbiValue::Float(value)
306        }
307        Value::Bytes(value) => AbiValue::Bytes(value),
308        Value::Keyword(value) => AbiValue::Keyword(value),
309        Value::Vector(values) => AbiValue::Vector(
310            values
311                .into_iter()
312                .map(immutable_to_abi)
313                .collect::<Result<Vec<_>, _>>()?,
314        ),
315        Value::Record(values) => AbiValue::Record(
316            values
317                .into_iter()
318                .map(|(key, value)| Ok((key, immutable_to_abi(value)?)))
319                .collect::<Result<_, String>>()?,
320        ),
321        value => {
322            return Err(format!(
323                "hta/value-unsupported: immutable value is outside the provider ABI: {value:?}"
324            ))
325        }
326    })
327}
328
329fn encode_value(value: &Value, depth: usize, output: &mut Vec<u8>) -> Result<(), String> {
330    if depth > MAX_NESTING_DEPTH {
331        return Err("hta/value-too-deep".into());
332    }
333    match value {
334        Value::Nil => push(output, NIL),
335        Value::Boolean(false) => push(output, FALSE),
336        Value::Boolean(true) => push(output, TRUE),
337        Value::Integer(value) => {
338            push(output, I64)?;
339            write(output, &value.to_be_bytes())
340        }
341        Value::Float(value) => {
342            if !value.is_finite() {
343                return Err("hta/non-finite number".into());
344            }
345            push(output, F64)?;
346            write(output, &value.to_bits().to_be_bytes())
347        }
348        Value::Character(value) => {
349            push(output, CHARACTER)?;
350            write(output, &u32::from(*value).to_be_bytes())
351        }
352        Value::BigInteger(value) => match canonical_big_integer(value)? {
353            Value::Integer(value) => {
354                push(output, I64)?;
355                write(output, &value.to_be_bytes())
356            }
357            Value::BigInteger(value) => write_sized(output, BIG_INTEGER, value.as_bytes()),
358            _ => unreachable!("canonical big integer returned a non-integer value"),
359        },
360        Value::String(value) => write_sized(output, STRING, value.as_bytes()),
361        Value::Bytes(value) => write_sized(output, BYTES, value),
362        Value::Keyword(value) => write_sized(output, KEYWORD, value.as_bytes()),
363        Value::Regex(value) => write_sized(output, REGEX, value.as_bytes()),
364        Value::Symbol(value) => write_sized(output, SYMBOL, value.as_bytes()),
365        Value::List(values) => encode_sequence(LIST, values, depth, output),
366        Value::Vector(values) => encode_sequence(VECTOR, values, depth, output),
367        Value::MapEntry(values) => encode_map_entry(values, depth, output),
368        Value::Tuple(values) => encode_sequence(VECTOR, values, depth, output),
369        Value::Cons(values) => encode_sequence(CONS, values, depth, output),
370        Value::Queue(values) => encode_sequence(QUEUE, values, depth, output),
371        Value::Set(values) => encode_unordered_sequence(SET, values, depth, output),
372        Value::OrderedSet(values) => encode_sequence(ORDERED_SET, values, depth, output),
373        Value::SortedSet(values) => encode_unordered_sequence(SORTED_SET, values, depth, output),
374        Value::Map(values) => encode_map(MAP, values, depth, output, true),
375        Value::OrderedMap(values) => encode_map(ORDERED_MAP, values, depth, output, false),
376        Value::SortedMap(values) => encode_map(SORTED_MAP, values, depth, output, false),
377        Value::Trie(values) => {
378            let entries = values
379                .iter()
380                .map(|(key, value)| (Value::String(key.clone()), value.clone()))
381                .collect::<Vec<_>>();
382            encode_map(TRIE, &entries, depth, output, false)
383        }
384        Value::Record(values) => encode_record(values, depth, output),
385        Value::Tagged { tag, form } => {
386            push(output, TAGGED)?;
387            encode_value(&Value::Symbol(tag.clone()), depth + 1, output)?;
388            encode_value(form, depth + 1, output)
389        }
390        Value::ExceptionInfo {
391            message,
392            data,
393            cause,
394            provenance,
395        } => {
396            if !matches!(data.as_ref(), Value::Map(_) | Value::Record(_)) {
397                return Err("hta/value-invalid: exception data must be a map".into());
398            }
399            if cause
400                .as_ref()
401                .is_some_and(|cause| !matches!(cause.as_ref(), Value::ExceptionInfo { .. }))
402            {
403                return Err("hta/value-invalid: exception cause must be an Exception".into());
404            }
405            push(output, EXCEPTION_INFO)?;
406            encode_value(&Value::String(message.clone()), depth + 1, output)?;
407            encode_value(data, depth + 1, output)?;
408            encode_value(cause.as_deref().unwrap_or(&Value::Nil), depth + 1, output)?;
409            encode_value(&provenance_value(provenance), depth + 1, output)
410        }
411        Value::Struct {
412            name,
413            fields,
414            values,
415        } => {
416            if fields.len() != values.len() {
417                return Err("hta/value-invalid: struct arity mismatch".into());
418            }
419            push(output, STRUCT)?;
420            encode_value(&Value::String(name.clone()), depth + 1, output)?;
421            encode_value(
422                &Value::Vector(fields.iter().cloned().map(Value::String).collect()),
423                depth + 1,
424                output,
425            )?;
426            encode_value(&Value::Vector(values.clone()), depth + 1, output)
427        }
428        Value::Pointer { context, fields } => {
429            push(output, POINTER)?;
430            encode_value(&Value::Keyword(context.clone()), depth + 1, output)?;
431            encode_record(fields, depth + 1, output)
432        }
433        Value::VarRef(symbol) => {
434            push(output, VAR_REF)?;
435            encode_value(&Value::Symbol(symbol.clone()), depth + 1, output)
436        }
437    }
438}
439
440fn encode_sequence(
441    tag: u8,
442    values: &[Value],
443    depth: usize,
444    output: &mut Vec<u8>,
445) -> Result<(), String> {
446    push(output, tag)?;
447    write_len(output, values.len())?;
448    for value in values {
449        encode_value(value, depth + 1, output)?;
450    }
451    Ok(())
452}
453
454fn encode_map_entry(values: &[Value], depth: usize, output: &mut Vec<u8>) -> Result<(), String> {
455    if values.len() != 2 {
456        return Err("hta/value-invalid: map entry must contain two values".into());
457    }
458    encode_sequence(MAP_ENTRY, values, depth, output)
459}
460
461fn encode_unordered_sequence(
462    tag: u8,
463    values: &[Value],
464    depth: usize,
465    output: &mut Vec<u8>,
466) -> Result<(), String> {
467    let mut encoded = Vec::with_capacity(values.len());
468    for value in values {
469        let mut bytes = Vec::new();
470        encode_value(value, depth + 1, &mut bytes)?;
471        encoded.push(bytes);
472    }
473    encoded.sort();
474    encoded.dedup();
475    push(output, tag)?;
476    write_len(output, encoded.len())?;
477    for value in encoded {
478        write(output, &value)?;
479    }
480    Ok(())
481}
482
483fn encode_map(
484    tag: u8,
485    values: &[(Value, Value)],
486    depth: usize,
487    output: &mut Vec<u8>,
488    canonical_order: bool,
489) -> Result<(), String> {
490    let mut entries = Vec::with_capacity(values.len());
491    for (key, value) in values {
492        let mut key_bytes = Vec::new();
493        encode_value(key, depth + 1, &mut key_bytes)?;
494        let mut value_bytes = Vec::new();
495        encode_value(value, depth + 1, &mut value_bytes)?;
496        entries.push((key_bytes, value_bytes));
497    }
498    if canonical_order {
499        entries.sort_by(|left, right| left.0.cmp(&right.0));
500    }
501    for pair in entries.windows(2) {
502        if pair[0].0 == pair[1].0 {
503            return Err("hta/value-invalid: duplicate map key".into());
504        }
505    }
506    push(output, tag)?;
507    write_len(output, entries.len())?;
508    for (key, value) in entries {
509        write(output, &key)?;
510        write(output, &value)?;
511    }
512    Ok(())
513}
514
515fn encode_record(
516    values: &BTreeMap<String, Value>,
517    depth: usize,
518    output: &mut Vec<u8>,
519) -> Result<(), String> {
520    push(output, MAP)?;
521    write_len(output, values.len())?;
522
523    let mut entries = Vec::with_capacity(values.len());
524    for (key, value) in values {
525        let mut key_bytes = Vec::with_capacity(key.len() + 5);
526        encode_value(&Value::Keyword(key.clone()), depth + 1, &mut key_bytes)?;
527        let mut value_bytes = Vec::new();
528        encode_value(value, depth + 1, &mut value_bytes)?;
529        entries.push((key_bytes, value_bytes));
530    }
531    entries.sort_by(|left, right| left.0.cmp(&right.0));
532    for (key, value) in entries {
533        write(output, &key)?;
534        write(output, &value)?;
535    }
536    Ok(())
537}
538
539fn write_sized(output: &mut Vec<u8>, tag: u8, bytes: &[u8]) -> Result<(), String> {
540    push(output, tag)?;
541    write_len(output, bytes.len())?;
542    write(output, bytes)
543}
544
545fn write_len(output: &mut Vec<u8>, len: usize) -> Result<(), String> {
546    let len = u32::try_from(len)
547        .map_err(|_| "hta/value-too-large: container or scalar length exceeds u32".to_string())?;
548    write(output, &len.to_be_bytes())
549}
550
551fn push(output: &mut Vec<u8>, byte: u8) -> Result<(), String> {
552    write(output, &[byte])
553}
554
555fn write(output: &mut Vec<u8>, bytes: &[u8]) -> Result<(), String> {
556    let next = output
557        .len()
558        .checked_add(bytes.len())
559        .ok_or_else(|| "hta/frame-too-large: length overflow".to_string())?;
560    if next > MAX_FRAME_BYTES {
561        return Err(format!(
562            "hta/frame-too-large: encoded frame exceeds {} bytes",
563            MAX_FRAME_BYTES
564        ));
565    }
566    output.extend_from_slice(bytes);
567    Ok(())
568}
569
570struct Reader<'a> {
571    bytes: &'a [u8],
572    cursor: usize,
573}
574
575impl Reader<'_> {
576    fn value(&mut self, depth: usize) -> Result<Value, String> {
577        if depth > MAX_NESTING_DEPTH {
578            return Err("hta/value-too-deep".into());
579        }
580        match self.byte()? {
581            NIL => Ok(Value::Nil),
582            FALSE => Ok(Value::Boolean(false)),
583            TRUE => Ok(Value::Boolean(true)),
584            I64 => Ok(Value::Integer(i64::from_be_bytes(
585                self.take(8)?.try_into().expect("eight bytes"),
586            ))),
587            F64 => {
588                let value = f64::from_bits(u64::from_be_bytes(
589                    self.take(8)?.try_into().expect("eight bytes"),
590                ));
591                if !value.is_finite() {
592                    return Err("hta/non-finite number".into());
593                }
594                Ok(Value::Float(value))
595            }
596            CHARACTER => {
597                let scalar = u32::from_be_bytes(self.take(4)?.try_into().expect("four bytes"));
598                char::from_u32(scalar)
599                    .map(Value::Character)
600                    .ok_or_else(|| "hta/value-malformed: invalid character scalar".into())
601            }
602            STRING => Ok(Value::String(self.text()?)),
603            BYTES => Ok(Value::Bytes(self.sized()?.to_vec())),
604            KEYWORD => Ok(Value::Keyword(self.text()?)),
605            SYMBOL => Ok(Value::Symbol(self.text()?)),
606            BIG_INTEGER => canonical_big_integer(&self.text()?),
607            REGEX => Ok(Value::Regex(self.text()?)),
608            LIST => self.sequence(depth).map(Value::List),
609            VECTOR => self.vector(depth),
610            TUPLE => self.sequence(depth).map(Value::Tuple),
611            MAP_ENTRY => {
612                let values = self.sequence(depth)?;
613                if values.len() != 2 {
614                    return Err("hta/value-malformed: map entry must contain two values".into());
615                }
616                Ok(Value::MapEntry(values))
617            }
618            CONS => {
619                let values = self.sequence(depth)?;
620                if values.is_empty() {
621                    Err("hta/value-malformed: empty cons".into())
622                } else {
623                    Ok(Value::Cons(values))
624                }
625            }
626            QUEUE => self.sequence(depth).map(Value::Queue),
627            SET => self.sequence(depth).map(Value::Set),
628            ORDERED_SET => self.sequence(depth).map(Value::OrderedSet),
629            SORTED_SET => self.sequence(depth).map(Value::SortedSet),
630            MAP => self.map(depth, MAP),
631            ORDERED_MAP => self.map(depth, ORDERED_MAP),
632            SORTED_MAP => self.map(depth, SORTED_MAP),
633            TRIE => self.trie(depth),
634            TAGGED => {
635                let Value::Symbol(tag) = self.value(depth + 1)? else {
636                    return Err("hta/value-malformed: invalid tagged literal tag".into());
637                };
638                Ok(Value::Tagged {
639                    tag,
640                    form: Box::new(self.value(depth + 1)?),
641                })
642            }
643            EXCEPTION_INFO => {
644                let Value::String(message) = self.value(depth + 1)? else {
645                    return Err("hta/value-malformed: invalid exception message".into());
646                };
647                let data = Box::new(self.value(depth + 1)?);
648                let cause = match self.value(depth + 1)? {
649                    Value::Nil => None,
650                    value @ Value::ExceptionInfo { .. } => Some(Box::new(value)),
651                    _ => return Err("hta/value-malformed: invalid exception cause".into()),
652                };
653                if !matches!(data.as_ref(), Value::Map(_) | Value::Record(_)) {
654                    return Err("hta/value-malformed: invalid exception data".into());
655                }
656                let provenance = decode_provenance(self.value(depth + 1)?)?;
657                Ok(Value::ExceptionInfo {
658                    message,
659                    data,
660                    cause,
661                    provenance,
662                })
663            }
664            STRUCT => self.structure(depth),
665            POINTER => {
666                let Value::Keyword(context) = self.value(depth + 1)? else {
667                    return Err("hta/value-malformed: invalid pointer context".into());
668                };
669                let Value::Record(fields) = self.value(depth + 1)? else {
670                    return Err("hta/value-malformed: invalid pointer fields".into());
671                };
672                Ok(Value::Pointer { context, fields })
673            }
674            VAR_REF => {
675                let Value::Symbol(symbol) = self.value(depth + 1)? else {
676                    return Err("hta/value-malformed: invalid Var reference".into());
677                };
678                Ok(Value::VarRef(symbol))
679            }
680            tag @ (HANDLE | NAMESPACE | VAR | ATOM | ARRAY | OBJECT) => Err(format!(
681                "hta/value-unsupported: runtime wire tag {tag} is not portable"
682            )),
683            tag => Err(format!("hta/value-malformed: unknown tag {tag}")),
684        }
685    }
686
687    fn vector(&mut self, depth: usize) -> Result<Value, String> {
688        self.sequence(depth).map(Value::Vector)
689    }
690
691    fn sequence(&mut self, depth: usize) -> Result<Vec<Value>, String> {
692        let len = self.len()?;
693        if len > self.remaining() {
694            return Err("hta/value-malformed: impossible sequence length".into());
695        }
696        let mut values = Vec::with_capacity(len);
697        for _ in 0..len {
698            values.push(self.value(depth + 1)?);
699        }
700        Ok(values)
701    }
702
703    fn entries(&mut self, depth: usize) -> Result<Vec<(Value, Value)>, String> {
704        let len = self.len()?;
705        if len > self.remaining() / 2 {
706            return Err("hta/value-malformed: impossible map length".into());
707        }
708        let mut values = Vec::with_capacity(len);
709        for _ in 0..len {
710            values.push((self.value(depth + 1)?, self.value(depth + 1)?));
711        }
712        Ok(values)
713    }
714
715    fn map(&mut self, depth: usize, tag: u8) -> Result<Value, String> {
716        let entries = self.entries(depth)?;
717        if tag == MAP
718            && entries
719                .iter()
720                .all(|(key, _)| matches!(key, Value::Keyword(_)))
721        {
722            let mut record = BTreeMap::new();
723            for (key, value) in entries {
724                let Value::Keyword(key) = key else {
725                    unreachable!()
726                };
727                if record.insert(key.clone(), value).is_some() {
728                    return Err(format!(
729                        "hta/value-malformed: duplicate portable record key :{key}"
730                    ));
731                }
732            }
733            return Ok(Value::Record(record));
734        }
735        match tag {
736            MAP => Ok(Value::Map(entries)),
737            ORDERED_MAP => Ok(Value::OrderedMap(entries)),
738            SORTED_MAP => Ok(Value::SortedMap(entries)),
739            _ => unreachable!(),
740        }
741    }
742
743    fn trie(&mut self, depth: usize) -> Result<Value, String> {
744        self.entries(depth)?
745            .into_iter()
746            .map(|(key, value)| match key {
747                Value::String(key) => Ok((key, value)),
748                _ => Err("hta/value-malformed: invalid trie key".into()),
749            })
750            .collect::<Result<Vec<_>, String>>()
751            .map(Value::Trie)
752    }
753
754    fn structure(&mut self, depth: usize) -> Result<Value, String> {
755        let Value::String(name) = self.value(depth + 1)? else {
756            return Err("hta/value-malformed: invalid struct name".into());
757        };
758        let Value::Vector(field_values) = self.value(depth + 1)? else {
759            return Err("hta/value-malformed: invalid struct fields".into());
760        };
761        let fields = field_values
762            .into_iter()
763            .map(|value| match value {
764                Value::String(value) => Ok(value),
765                _ => Err("hta/value-malformed: invalid struct field".into()),
766            })
767            .collect::<Result<Vec<_>, String>>()?;
768        let Value::Vector(values) = self.value(depth + 1)? else {
769            return Err("hta/value-malformed: invalid struct values".into());
770        };
771        if fields.len() != values.len() {
772            return Err("hta/value-malformed: struct arity mismatch".into());
773        }
774        Ok(Value::Struct {
775            name,
776            fields,
777            values,
778        })
779    }
780
781    fn text(&mut self) -> Result<String, String> {
782        String::from_utf8(self.sized()?.to_vec())
783            .map_err(|_| "hta/value-malformed: invalid UTF-8".into())
784    }
785
786    fn sized(&mut self) -> Result<&[u8], String> {
787        let len = self.len()?;
788        self.take(len)
789    }
790
791    fn len(&mut self) -> Result<usize, String> {
792        Ok(u32::from_be_bytes(self.take(4)?.try_into().expect("four bytes")) as usize)
793    }
794
795    fn byte(&mut self) -> Result<u8, String> {
796        Ok(self.take(1)?[0])
797    }
798
799    fn take(&mut self, size: usize) -> Result<&[u8], String> {
800        let end = self
801            .cursor
802            .checked_add(size)
803            .ok_or_else(|| "hta/value-malformed: length overflow".to_string())?;
804        if end > self.bytes.len() {
805            return Err("hta/value-malformed: truncated value".into());
806        }
807        let output = &self.bytes[self.cursor..end];
808        self.cursor = end;
809        Ok(output)
810    }
811
812    fn remaining(&self) -> usize {
813        self.bytes.len() - self.cursor
814    }
815}
816
817#[cfg(test)]
818mod tests {
819    use super::*;
820
821    fn encode(value: &Value) -> Result<Vec<u8>, String> {
822        encode_immutable(value)
823    }
824
825    fn decode(bytes: &[u8]) -> Result<Value, String> {
826        decode_immutable(bytes)
827    }
828
829    fn decode_canonical(bytes: &[u8], max_bytes: usize) -> Result<Value, String> {
830        decode_immutable_canonical(bytes, max_bytes)
831    }
832
833    fn record(entries: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
834        Value::Record(
835            entries
836                .into_iter()
837                .map(|(key, value)| (key.to_owned(), value))
838                .collect(),
839        )
840    }
841
842    #[test]
843    fn canonical_portable_round_trip() {
844        let value = record([
845            ("a", Value::Vector(vec![Value::Boolean(true), Value::Nil])),
846            ("b", Value::Integer(2)),
847            ("big", Value::BigInteger("9223372036854775808".into())),
848            ("bytes", Value::Bytes(vec![0, 1, 255])),
849            ("float", Value::Float(0.28)),
850            ("keyword", Value::Keyword("profile.primary".into())),
851        ]);
852        let encoded = encode(&value).unwrap();
853        assert_eq!(decode(&encoded).unwrap(), value);
854        assert_eq!(encode(&decode(&encoded).unwrap()).unwrap(), encoded);
855        assert_eq!(decode_canonical(&encoded, encoded.len()).unwrap(), value);
856    }
857
858    #[test]
859    fn immutable_hara_values_and_references_round_trip() {
860        let values = vec![
861            Value::Symbol("tool.lint/lint-source".into()),
862            Value::Character('雪'),
863            Value::BigInteger("123456789012345678901234567890".into()),
864            Value::Regex("^[a-z]+$".into()),
865            Value::List(vec![Value::Integer(1), Value::Integer(2)]),
866            Value::MapEntry(vec![Value::Integer(1), Value::Integer(2)]),
867            Value::Queue(vec![Value::Integer(1), Value::Integer(2)]),
868            Value::Set(vec![Value::Keyword("a".into()), Value::Keyword("b".into())]),
869            Value::Map(vec![(Value::String("answer".into()), Value::Integer(42))]),
870            Value::Tagged {
871                tag: "demo/value".into(),
872                form: Box::new(Value::Integer(42)),
873            },
874            Value::Pointer {
875                context: "kernel".into(),
876                fields: [("id".into(), Value::String("ROOT".into()))]
877                    .into_iter()
878                    .collect(),
879            },
880            Value::VarRef("user/answer".into()),
881        ];
882        for value in values {
883            assert_eq!(decode(&encode(&value).unwrap()).unwrap(), value);
884        }
885    }
886
887    #[test]
888    fn compact_tuples_use_the_vector_wire_identity_and_map_entries_are_distinct() {
889        let tuple = Value::Tuple(vec![Value::Integer(1), Value::Integer(2)]);
890        let encoded = encode(&tuple).unwrap();
891        assert_eq!(encoded[4], VECTOR);
892        assert_eq!(
893            decode(&encoded).unwrap(),
894            Value::Vector(vec![Value::Integer(1), Value::Integer(2)])
895        );
896
897        let mut legacy = encoded;
898        legacy[4] = TUPLE;
899        assert_eq!(decode(&legacy).unwrap(), tuple);
900
901        let entry = Value::MapEntry(vec![Value::Keyword("key".into()), Value::Integer(42)]);
902        let encoded_entry = encode(&entry).unwrap();
903        assert_eq!(encoded_entry[4], MAP_ENTRY);
904        assert_eq!(decode(&encoded_entry).unwrap(), entry);
905    }
906
907    #[test]
908    fn records_are_canonical_independent_of_construction_order() {
909        let first = record([("z", Value::Integer(1)), ("a", Value::Integer(2))]);
910        let second = record([("a", Value::Integer(2)), ("z", Value::Integer(1))]);
911        assert_eq!(encode(&first).unwrap(), encode(&second).unwrap());
912    }
913
914    #[test]
915    fn canonical_decode_rejects_noncanonical_map_order() {
916        let mut bytes = MAGIC.to_vec();
917        bytes.extend_from_slice(&[MAP, 0, 0, 0, 2]);
918        bytes.extend_from_slice(&[KEYWORD, 0, 0, 0, 2, b'a', b'a', NIL]);
919        bytes.extend_from_slice(&[KEYWORD, 0, 0, 0, 1, b'z', TRUE]);
920
921        assert!(decode(&bytes).is_ok());
922        assert!(decode_canonical(&bytes, bytes.len())
923            .unwrap_err()
924            .contains("frame-noncanonical"));
925    }
926
927    #[test]
928    fn canonical_decode_enforces_the_requested_maximum() {
929        let bytes = encode(&Value::Nil).unwrap();
930        assert_eq!(decode_canonical(&bytes, bytes.len()).unwrap(), Value::Nil);
931        assert!(decode_canonical(&bytes, bytes.len() - 1)
932            .unwrap_err()
933            .contains("requested maximum"));
934        assert!(decode_canonical(&bytes, 0)
935            .unwrap_err()
936            .contains("maximum-invalid"));
937        assert!(decode_canonical(&bytes, MAX_FRAME_BYTES + 1)
938            .unwrap_err()
939            .contains("maximum-invalid"));
940    }
941
942    #[test]
943    fn floats_preserve_ieee_754_bits() {
944        for value in [0.28, -0.0] {
945            let decoded = decode(&encode(&Value::Float(value)).unwrap()).unwrap();
946            let Value::Float(decoded) = decoded else {
947                panic!("float value")
948            };
949            assert_eq!(decoded.to_bits(), value.to_bits());
950        }
951        for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
952            assert!(encode(&Value::Float(value)).is_err());
953        }
954    }
955
956    #[test]
957    fn general_maps_accept_non_keyword_keys_and_records_reject_duplicates() {
958        let mut non_keyword = MAGIC.to_vec();
959        non_keyword.extend_from_slice(&[MAP, 0, 0, 0, 1]);
960        non_keyword.extend_from_slice(&[STRING, 0, 0, 0, 1, b'a', NIL]);
961        assert_eq!(
962            decode(&non_keyword).unwrap(),
963            Value::Map(vec![(Value::String("a".into()), Value::Nil)])
964        );
965
966        let mut duplicate = MAGIC.to_vec();
967        duplicate.extend_from_slice(&[MAP, 0, 0, 0, 2]);
968        for value in [NIL, TRUE] {
969            duplicate.extend_from_slice(&[KEYWORD, 0, 0, 0, 1, b'a', value]);
970        }
971        assert!(decode(&duplicate)
972            .unwrap_err()
973            .contains("duplicate portable record key :a"));
974    }
975
976    #[test]
977    fn runtime_only_tags_fail_closed() {
978        for tag in [HANDLE, NAMESPACE, VAR, ATOM, ARRAY, OBJECT] {
979            let bytes = [MAGIC.as_slice(), &[tag]].concat();
980            assert!(decode(&bytes).unwrap_err().contains("runtime wire tag"));
981            assert!(decode_canonical(&bytes, bytes.len())
982                .unwrap_err()
983                .contains("runtime wire tag"));
984        }
985    }
986
987    #[test]
988    fn retired_decimal_tag_fails_closed() {
989        let bytes = [MAGIC.as_slice(), &[21]].concat();
990        assert!(decode(&bytes).unwrap_err().contains("unknown tag 21"));
991        assert!(decode_canonical(&bytes, bytes.len())
992            .unwrap_err()
993            .contains("unknown tag 21"));
994    }
995
996    #[test]
997    fn frame_shape_and_lengths_are_bounded() {
998        assert!(decode(b"not-hta")
999            .unwrap_err()
1000            .contains("expected HTA0 magic"));
1001
1002        let trailing = [MAGIC.as_slice(), &[NIL, NIL]].concat();
1003        assert!(decode(&trailing).unwrap_err().contains("trailing bytes"));
1004
1005        let mut impossible = MAGIC.to_vec();
1006        impossible.extend_from_slice(&[VECTOR, 0xff, 0xff, 0xff, 0xff]);
1007        assert!(decode(&impossible)
1008            .unwrap_err()
1009            .contains("impossible sequence length"));
1010    }
1011
1012    #[test]
1013    fn nesting_depth_is_bounded_on_encode_and_decode() {
1014        let mut value = Value::Nil;
1015        for _ in 0..=MAX_NESTING_DEPTH {
1016            value = Value::Vector(vec![value]);
1017        }
1018        assert!(encode(&value).unwrap_err().contains("value-too-deep"));
1019
1020        let mut bytes = MAGIC.to_vec();
1021        for _ in 0..=MAX_NESTING_DEPTH {
1022            bytes.extend_from_slice(&[VECTOR, 0, 0, 0, 1]);
1023        }
1024        bytes.push(NIL);
1025        assert!(decode(&bytes).unwrap_err().contains("value-too-deep"));
1026    }
1027}