hara_native/kernel/
halc.rs

1use super::Form;
2use num_bigint::BigInt;
3use num_traits::ToPrimitive;
4use sha2::{Digest, Sha256};
5use std::collections::{HashMap, HashSet};
6
7const MAGIC: &[u8] = b"HALC";
8const LEGACY_MAGIC: &[u8] = b"HIR\0";
9const FORMAT_VERSION: u16 = 1;
10const EXECUTABLE_FOUNDATION_FLAG: u16 = 1;
11const HASH_BYTES: usize = 32;
12const MAX_PAYLOAD_BYTES: usize = 64 * 1024 * 1024;
13const MAX_COLLECTION_ITEMS: i32 = 1_000_000;
14
15const NIL: u8 = 0;
16const FALSE: u8 = 1;
17const TRUE: u8 = 2;
18const LONG: u8 = 3;
19const DOUBLE: u8 = 4;
20const BIG_INTEGER: u8 = 5;
21const STRING: u8 = 6;
22const CHARACTER: u8 = 8;
23const SYMBOL: u8 = 9;
24const KEYWORD: u8 = 10;
25const LIST: u8 = 11;
26const VECTOR: u8 = 12;
27const MAP: u8 = 13;
28const SET: u8 = 14;
29const ORDERED_MAP: u8 = 15;
30const ORDERED_SET: u8 = 16;
31const REGEX: u8 = 17;
32
33#[derive(Debug, Clone)]
34pub struct HalcModule {
35    pub namespace: String,
36    pub resource: String,
37    pub source_hash: Vec<u8>,
38    pub forms: Vec<Form>,
39    pub schemas: HalcSchemaIndex,
40    pub origin: HalcOrigin,
41}
42
43/// The typed declarations recoverable from canonical HALC forms without
44/// evaluating the module. Keys are fully qualified Var names.
45#[derive(Debug, Clone, Default, PartialEq)]
46pub struct HalcSchemaIndex {
47    pub definitions: HashMap<String, Form>,
48    pub functions: HashMap<String, Form>,
49    pub definition_types: HashMap<String, super::SchemaType>,
50    pub function_types: HashMap<String, super::SchemaType>,
51}
52
53impl HalcSchemaIndex {
54    /// Resolves a function annotation through named-schema references while
55    /// preserving recursive graph edges as `Reference` nodes.
56    pub fn resolved_function_type(&self, qualified_var: &str) -> Option<&super::SchemaType> {
57        let schema = self.function_types.get(qualified_var)?;
58        match schema {
59            super::SchemaType::Reference(name) => self.definition_types.get(name).or(Some(schema)),
60            _ => Some(schema),
61        }
62    }
63}
64
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub enum HalcOrigin {
67    Halc,
68    LegacyHir,
69}
70
71pub fn decode_halc(bytes: &[u8]) -> Result<HalcModule, String> {
72    let (payload, origin) = decode_envelope(bytes)?;
73    let mut reader = ByteReader::new(&payload);
74    let namespace = reader.read_string()?;
75    let resource = reader.read_string()?;
76    let source_hash = reader.read_bytes(HASH_BYTES)?;
77    let form_count = reader.read_count()?;
78    let mut forms = Vec::with_capacity(form_count as usize);
79    for _ in 0..form_count {
80        forms.push(reader.read_value()?);
81    }
82    if !reader.is_empty() {
83        return Err("trailing payload bytes".into());
84    }
85    let forms = canonicalize_schema_references(&namespace, forms)?;
86    let schemas = build_schema_index(&namespace, &forms)?;
87    Ok(HalcModule {
88        namespace,
89        resource,
90        source_hash,
91        forms,
92        schemas,
93        origin,
94    })
95}
96
97fn decode_envelope(bytes: &[u8]) -> Result<(Vec<u8>, HalcOrigin), String> {
98    let mut reader = ByteReader::new(bytes);
99    let magic = reader.read_bytes(MAGIC.len())?;
100    let origin = if magic == MAGIC {
101        HalcOrigin::Halc
102    } else if magic == LEGACY_MAGIC {
103        HalcOrigin::LegacyHir
104    } else {
105        return Err("bad magic".into());
106    };
107    let version = reader.read_u16()?;
108    if version != FORMAT_VERSION {
109        return Err(format!("unsupported format version {version}"));
110    }
111    let flags = reader.read_u16()?;
112    if flags != EXECUTABLE_FOUNDATION_FLAG {
113        return Err(format!("unsupported flags {flags}"));
114    }
115    let payload_length = reader.read_u32()? as usize;
116    if payload_length > MAX_PAYLOAD_BYTES {
117        return Err(format!("invalid payload length {payload_length}"));
118    }
119    let expected_hash = reader.read_bytes(HASH_BYTES)?;
120    let payload = reader.read_bytes(payload_length)?;
121    if !reader.is_empty() {
122        return Err("trailing bytes".into());
123    }
124    let actual_hash = Sha256::digest(&payload);
125    if actual_hash[..] != expected_hash[..] {
126        return Err("payload checksum mismatch".into());
127    }
128    Ok((payload, origin))
129}
130
131struct ByteReader<'a> {
132    bytes: &'a [u8],
133    position: usize,
134}
135
136impl<'a> ByteReader<'a> {
137    fn new(bytes: &'a [u8]) -> Self {
138        Self { bytes, position: 0 }
139    }
140
141    fn is_empty(&self) -> bool {
142        self.position >= self.bytes.len()
143    }
144
145    fn remaining(&self) -> usize {
146        self.bytes.len().saturating_sub(self.position)
147    }
148
149    fn read_byte(&mut self) -> Result<u8, String> {
150        if self.position >= self.bytes.len() {
151            return Err("truncated artifact".into());
152        }
153        let byte = self.bytes[self.position];
154        self.position += 1;
155        Ok(byte)
156    }
157
158    fn read_bytes(&mut self, count: usize) -> Result<Vec<u8>, String> {
159        if self.remaining() < count {
160            return Err("truncated artifact".into());
161        }
162        let bytes = self.bytes[self.position..self.position + count].to_vec();
163        self.position += count;
164        Ok(bytes)
165    }
166
167    fn read_u16(&mut self) -> Result<u16, String> {
168        let bytes = self.read_bytes(2)?;
169        Ok(u16::from_be_bytes([bytes[0], bytes[1]]))
170    }
171
172    fn read_u32(&mut self) -> Result<u32, String> {
173        let bytes = self.read_bytes(4)?;
174        Ok(u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]))
175    }
176
177    fn read_i64(&mut self) -> Result<i64, String> {
178        let bytes = self.read_bytes(8)?;
179        Ok(i64::from_be_bytes([
180            bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
181        ]))
182    }
183
184    fn read_f64(&mut self) -> Result<f64, String> {
185        let bytes = self.read_bytes(8)?;
186        let value = f64::from_be_bytes([
187            bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
188        ]);
189        if !value.is_finite() {
190            return Err("non-finite number".into());
191        }
192        Ok(value)
193    }
194
195    fn read_string(&mut self) -> Result<String, String> {
196        let length = self.read_u32()? as usize;
197        if length > MAX_PAYLOAD_BYTES {
198            return Err(format!("invalid string length {length}"));
199        }
200        let bytes = self.read_bytes(length)?;
201        String::from_utf8(bytes).map_err(|_| "invalid UTF-8 in string".to_string())
202    }
203
204    fn read_nullable_string(&mut self) -> Result<Option<String>, String> {
205        let present = self.read_byte()? != 0;
206        if present {
207            Ok(Some(self.read_string()?))
208        } else {
209            Ok(None)
210        }
211    }
212
213    fn read_count(&mut self) -> Result<i32, String> {
214        let count = self.read_u32()? as i32;
215        if count < 0 || count > MAX_COLLECTION_ITEMS {
216            return Err(format!("invalid collection count {count}"));
217        }
218        Ok(count)
219    }
220
221    fn read_metadata(&mut self) -> Result<Option<Form>, String> {
222        let present = self.read_byte()? != 0;
223        if present {
224            Ok(Some(self.read_value()?))
225        } else {
226            Ok(None)
227        }
228    }
229
230    fn read_value(&mut self) -> Result<Form, String> {
231        let opcode = self.read_byte()?;
232        match opcode {
233            NIL => Ok(Form::Nil),
234            FALSE => Ok(Form::Bool(false)),
235            TRUE => Ok(Form::Bool(true)),
236            LONG => Ok(Form::Number(self.read_i64()?)),
237            DOUBLE => Ok(Form::Float(self.read_f64()?)),
238            BIG_INTEGER => {
239                let text = self.read_string()?;
240                let value = BigInt::parse_bytes(text.as_bytes(), 10)
241                    .ok_or_else(|| "invalid big integer".to_string())?;
242                Ok(match value.to_i64() {
243                    Some(value) => Form::Number(value),
244                    None => Form::BigInteger(value),
245                })
246            }
247            STRING => Ok(Form::String(self.read_string()?)),
248            CHARACTER => Ok(Form::Character(
249                char::from_u32(self.read_u32()?).ok_or("invalid character code point")?,
250            )),
251            SYMBOL => {
252                let namespace = self.read_nullable_string()?;
253                let name = self.read_string()?;
254                Ok(with_metadata(
255                    Form::Symbol(namespaced(namespace, name)),
256                    self.read_metadata()?,
257                ))
258            }
259            KEYWORD => {
260                let namespace = self.read_nullable_string()?;
261                let name = self.read_string()?;
262                Ok(with_metadata(
263                    Form::Keyword(namespaced(namespace, name)),
264                    self.read_metadata()?,
265                ))
266            }
267            LIST => {
268                let count = self.read_count()?;
269                let items = self.read_values(count)?;
270                Ok(with_metadata(Form::List(items), self.read_metadata()?))
271            }
272            VECTOR => {
273                let count = self.read_count()?;
274                let items = self.read_values(count)?;
275                Ok(with_metadata(Form::Vector(items), self.read_metadata()?))
276            }
277            MAP | ORDERED_MAP => {
278                let count = self.read_count()?;
279                let mut entries = Vec::with_capacity(count as usize);
280                for _ in 0..count {
281                    let key = self.read_value()?;
282                    let value = self.read_value()?;
283                    entries.push((key, value));
284                }
285                Ok(with_metadata(Form::Map(entries), self.read_metadata()?))
286            }
287            SET | ORDERED_SET => {
288                let count = self.read_count()?;
289                let items = self.read_values(count)?;
290                Ok(with_metadata(Form::Set(items), self.read_metadata()?))
291            }
292            REGEX => Ok(Form::Regex(self.read_string()?)),
293            _ => Err(format!("unknown value opcode {opcode}")),
294        }
295    }
296
297    fn read_values(&mut self, count: i32) -> Result<Vec<Form>, String> {
298        let mut values = Vec::with_capacity(count as usize);
299        for _ in 0..count {
300            values.push(self.read_value()?);
301        }
302        Ok(values)
303    }
304}
305
306fn with_metadata(value: Form, metadata: Option<Form>) -> Form {
307    match metadata {
308        Some(metadata) => Form::Metadata(Box::new(metadata), Box::new(value)),
309        None => value,
310    }
311}
312
313fn namespaced(namespace: Option<String>, name: String) -> String {
314    match namespace {
315        Some(ns) => format!("{ns}/{name}"),
316        None => name,
317    }
318}
319
320#[cfg(any(test, feature = "halc-encoder"))]
321fn write_string(output: &mut Vec<u8>, value: &str) {
322    output.extend_from_slice(&(value.len() as u32).to_be_bytes());
323    output.extend_from_slice(value.as_bytes());
324}
325
326#[cfg(any(test, feature = "halc-encoder"))]
327fn write_count(output: &mut Vec<u8>, count: i32) {
328    output.extend_from_slice(&count.to_be_bytes());
329}
330
331#[cfg(any(test, feature = "halc-encoder"))]
332fn write_namespaced(output: &mut Vec<u8>, symbol: &str) {
333    if let Some((ns, name)) = symbol.rsplit_once('/') {
334        output.push(1);
335        write_string(output, ns);
336        write_string(output, name);
337    } else {
338        output.push(0);
339        write_string(output, symbol);
340    }
341}
342
343#[cfg(any(test, feature = "halc-encoder"))]
344fn write_values(output: &mut Vec<u8>, values: &[Form]) {
345    write_count(output, values.len() as i32);
346    for value in values {
347        write_value(output, value);
348    }
349}
350
351#[cfg(any(test, feature = "halc-encoder"))]
352fn write_value(output: &mut Vec<u8>, form: &Form) {
353    match form {
354        Form::Metadata(metadata, value) => write_value_with_metadata(output, value, Some(metadata)),
355        _ => write_value_with_metadata(output, form, None),
356    }
357}
358
359#[cfg(any(test, feature = "halc-encoder"))]
360fn write_metadata(output: &mut Vec<u8>, metadata: Option<&Form>) {
361    match metadata {
362        Some(metadata) => {
363            output.push(1);
364            write_value(output, metadata);
365        }
366        None => output.push(0),
367    }
368}
369
370#[cfg(any(test, feature = "halc-encoder"))]
371fn write_value_with_metadata(output: &mut Vec<u8>, form: &Form, metadata: Option<&Form>) {
372    match form {
373        Form::Nil => output.push(NIL),
374        Form::Bool(false) => output.push(FALSE),
375        Form::Bool(true) => output.push(TRUE),
376        Form::Number(n) => {
377            output.push(LONG);
378            output.extend_from_slice(&n.to_be_bytes());
379        }
380        Form::Float(f) => {
381            assert!(f.is_finite(), "non-finite number");
382            output.push(DOUBLE);
383            output.extend_from_slice(&f.to_be_bytes());
384        }
385        Form::BigInteger(s) => {
386            output.push(BIG_INTEGER);
387            write_string(output, &s.to_string());
388        }
389        Form::String(s) => {
390            output.push(STRING);
391            write_string(output, s);
392        }
393        Form::Character(c) => {
394            output.push(CHARACTER);
395            output.extend_from_slice(&(*c as u32).to_be_bytes());
396        }
397        Form::Symbol(s) => {
398            output.push(SYMBOL);
399            write_namespaced(output, s);
400            write_metadata(output, metadata);
401        }
402        Form::Keyword(s) => {
403            output.push(KEYWORD);
404            write_namespaced(output, s);
405            write_metadata(output, metadata);
406        }
407        Form::List(items) => {
408            output.push(LIST);
409            write_values(output, items);
410            write_metadata(output, metadata);
411        }
412        Form::Vector(items) => {
413            output.push(VECTOR);
414            write_values(output, items);
415            write_metadata(output, metadata);
416        }
417        Form::Map(entries) => {
418            output.push(ORDERED_MAP);
419            write_count(output, entries.len() as i32);
420            for (key, value) in entries {
421                write_value(output, key);
422                write_value(output, value);
423            }
424            write_metadata(output, metadata);
425        }
426        Form::Set(items) => {
427            output.push(ORDERED_SET);
428            write_values(output, items);
429            write_metadata(output, metadata);
430        }
431        Form::Regex(s) => {
432            output.push(REGEX);
433            write_string(output, s);
434        }
435        Form::Tagged(_, _) | Form::Metadata(_, _) => {
436            panic!("test encoder does not support tagged/metadata forms")
437        }
438    }
439}
440
441/// Encodes a canonical HALC artifact from parsed forms.
442///
443/// This mirrors the v1 format used by `decode_halc` so that integration tests
444/// can construct artifacts without depending on an external encoder.
445#[cfg(any(test, feature = "halc-encoder"))]
446pub fn encode_halc_module(
447    namespace: &str,
448    resource: &str,
449    source: &str,
450    forms: Vec<Form>,
451) -> Result<Vec<u8>, String> {
452    let forms = canonicalize_schema_references(namespace, forms)?;
453    for form in &forms {
454        validate_finite_form(form)?;
455    }
456    build_schema_index(namespace, &forms)?;
457    let mut payload = Vec::new();
458    write_string(&mut payload, namespace);
459    write_string(&mut payload, resource);
460    payload.extend_from_slice(&Sha256::digest(source.as_bytes()));
461    write_count(&mut payload, forms.len() as i32);
462    for form in forms {
463        write_value(&mut payload, &form);
464    }
465    let mut artifact = Vec::new();
466    artifact.extend_from_slice(MAGIC);
467    artifact.extend_from_slice(&FORMAT_VERSION.to_be_bytes());
468    artifact.extend_from_slice(&EXECUTABLE_FOUNDATION_FLAG.to_be_bytes());
469    artifact.extend_from_slice(&(payload.len() as u32).to_be_bytes());
470    artifact.extend_from_slice(&Sha256::digest(&payload));
471    artifact.extend_from_slice(&payload);
472    Ok(artifact)
473}
474
475#[cfg(any(test, feature = "halc-encoder"))]
476fn validate_finite_form(form: &Form) -> Result<(), String> {
477    match form {
478        Form::Float(value) if !value.is_finite() => Err("non-finite number".into()),
479        Form::Tagged(_, value) => validate_finite_form(value),
480        Form::Metadata(metadata, value) => {
481            validate_finite_form(metadata)?;
482            validate_finite_form(value)
483        }
484        Form::Map(entries) => {
485            for (key, value) in entries {
486                validate_finite_form(key)?;
487                validate_finite_form(value)?;
488            }
489            Ok(())
490        }
491        Form::Set(values) | Form::Vector(values) | Form::List(values) => {
492            for value in values {
493                validate_finite_form(value)?;
494            }
495            Ok(())
496        }
497        _ => Ok(()),
498    }
499}
500
501fn canonicalize_schema_references(
502    namespace: &str,
503    mut forms: Vec<Form>,
504) -> Result<Vec<Form>, String> {
505    let definitions: HashSet<String> = forms
506        .iter()
507        .filter_map(|form| {
508            let Form::List(items) = form else { return None };
509            let Form::Symbol(operator) = items.first()? else {
510                return None;
511            };
512            if !matches!(
513                operator.as_str(),
514                "def" | "defn" | "defmacro" | "defstruct" | "declare"
515            ) {
516                return None;
517            }
518            binding_name(items.get(1)?).map(str::to_owned)
519        })
520        .collect();
521    let schema_values: HashMap<String, usize> = forms
522        .iter()
523        .enumerate()
524        .filter_map(|(index, form)| {
525            let Form::List(items) = form else { return None };
526            if !matches!(items.first(), Some(Form::Symbol(operator)) if operator == "def") {
527                return None;
528            }
529            binding_name(items.get(1)?).map(|name| (name.to_owned(), index))
530        })
531        .collect();
532    let aliases = module_aliases(&forms);
533    let mut schema_roots = Vec::new();
534
535    for form in &mut forms {
536        let Form::List(items) = form else { continue };
537        let Some(Form::Symbol(operator)) = items.first() else {
538            continue;
539        };
540        if operator != "defn" {
541            continue;
542        }
543        let Some(Form::Metadata(metadata, _)) = items.get_mut(1) else {
544            continue;
545        };
546        let Form::Map(entries) = metadata.as_mut() else {
547            continue;
548        };
549        let Some((_, schema)) = entries
550            .iter_mut()
551            .find(|(key, _)| matches!(key, Form::Keyword(name) if name == "schema"))
552        else {
553            continue;
554        };
555        let Form::List(reference) = schema else {
556            continue;
557        };
558        if reference.len() != 2
559            || !matches!(&reference[0], Form::Symbol(operator) if operator == "var")
560        {
561            continue;
562        }
563        let Form::Symbol(target) = &reference[1] else {
564            continue;
565        };
566        let (qualifier, local) = target
567            .rsplit_once('/')
568            .map_or((None, target.as_str()), |(qualifier, local)| {
569                (Some(qualifier), local)
570            });
571        let target_namespace = match qualifier {
572            None | Some("-") => namespace,
573            Some(qualifier) => aliases.get(qualifier).map_or(qualifier, String::as_str),
574        };
575        if target_namespace == namespace && !definitions.contains(local) {
576            return Err(format!("schema Var does not exist: {target}"));
577        }
578        if target_namespace == namespace {
579            schema_roots.push(local.to_owned());
580        }
581        reference[1] = Form::Symbol(format!("{target_namespace}/{local}"));
582    }
583
584    let mut visited = HashSet::new();
585    while let Some(schema_name) = schema_roots.pop() {
586        if !visited.insert(schema_name.clone()) {
587            continue;
588        }
589        let Some(index) = schema_values.get(&schema_name).copied() else {
590            continue;
591        };
592        let Form::List(definition) = &mut forms[index] else {
593            continue;
594        };
595        let Some(schema_value) = definition.get_mut(2) else {
596            continue;
597        };
598        canonicalize_nested_schema_references(
599            schema_value,
600            namespace,
601            &aliases,
602            &definitions,
603            &mut schema_roots,
604        )?;
605    }
606    Ok(forms)
607}
608
609fn canonicalize_nested_schema_references(
610    form: &mut Form,
611    namespace: &str,
612    aliases: &HashMap<String, String>,
613    definitions: &HashSet<String>,
614    local_references: &mut Vec<String>,
615) -> Result<(), String> {
616    if let Form::List(reference) = form {
617        if reference.len() == 2
618            && matches!(&reference[0], Form::Symbol(operator) if operator == "var")
619        {
620            let Form::Symbol(target) = &reference[1] else {
621                return Ok(());
622            };
623            let original = target.clone();
624            let (qualifier, local) = original
625                .rsplit_once('/')
626                .map_or((None, original.as_str()), |(qualifier, local)| {
627                    (Some(qualifier), local)
628                });
629            let target_namespace = match qualifier {
630                None | Some("-") => namespace,
631                Some(qualifier) => aliases.get(qualifier).map_or(qualifier, String::as_str),
632            };
633            if target_namespace == namespace {
634                if !definitions.contains(local) {
635                    return Err(format!("schema Var does not exist: {original}"));
636                }
637                local_references.push(local.to_owned());
638            }
639            reference[1] = Form::Symbol(format!("{target_namespace}/{local}"));
640            return Ok(());
641        }
642    }
643
644    match form {
645        Form::Tagged(_, value) => canonicalize_nested_schema_references(
646            value,
647            namespace,
648            aliases,
649            definitions,
650            local_references,
651        ),
652        Form::Metadata(metadata, value) => {
653            canonicalize_nested_schema_references(
654                metadata,
655                namespace,
656                aliases,
657                definitions,
658                local_references,
659            )?;
660            canonicalize_nested_schema_references(
661                value,
662                namespace,
663                aliases,
664                definitions,
665                local_references,
666            )
667        }
668        Form::Map(entries) => {
669            for (key, value) in entries {
670                canonicalize_nested_schema_references(
671                    key,
672                    namespace,
673                    aliases,
674                    definitions,
675                    local_references,
676                )?;
677                canonicalize_nested_schema_references(
678                    value,
679                    namespace,
680                    aliases,
681                    definitions,
682                    local_references,
683                )?;
684            }
685            Ok(())
686        }
687        Form::Set(values) | Form::Vector(values) | Form::List(values) => {
688            for value in values {
689                canonicalize_nested_schema_references(
690                    value,
691                    namespace,
692                    aliases,
693                    definitions,
694                    local_references,
695                )?;
696            }
697            Ok(())
698        }
699        _ => Ok(()),
700    }
701}
702
703fn binding_name(form: &Form) -> Option<&str> {
704    match form {
705        Form::Symbol(name) => Some(name),
706        Form::Metadata(_, value) => binding_name(value),
707        _ => None,
708    }
709}
710
711fn module_aliases(forms: &[Form]) -> HashMap<String, String> {
712    let mut aliases = HashMap::new();
713    for form in forms {
714        let Form::List(declaration) = form else {
715            continue;
716        };
717        if !matches!(declaration.first(), Some(Form::Symbol(operator)) if operator == "ns") {
718            continue;
719        }
720        for clause in declaration.iter().skip(2) {
721            let Form::List(clause) = clause else { continue };
722            if !matches!(clause.first(), Some(Form::Keyword(keyword)) if keyword == "require") {
723                continue;
724            }
725            for spec in clause.iter().skip(1) {
726                let Form::Vector(spec) = spec else { continue };
727                let Some(Form::Symbol(target)) = spec.first() else {
728                    continue;
729                };
730                for option in spec[1..].chunks(2) {
731                    if let [Form::Keyword(key), Form::Symbol(alias)] = option {
732                        if key == "as" {
733                            aliases.insert(alias.clone(), target.clone());
734                        }
735                    }
736                }
737            }
738        }
739    }
740    aliases
741}
742
743fn build_schema_index(namespace: &str, forms: &[Form]) -> Result<HalcSchemaIndex, String> {
744    let mut index = HalcSchemaIndex::default();
745    let mut values = HashMap::new();
746    let mut roots = Vec::new();
747
748    for form in forms {
749        let Form::List(items) = form else { continue };
750        let Some(Form::Symbol(operator)) = items.first() else {
751            continue;
752        };
753        let Some(name) = items.get(1).and_then(binding_name) else {
754            continue;
755        };
756        let qualified_name = format!("{namespace}/{name}");
757        if operator == "def" {
758            if let Some(value) = items.get(2) {
759                values.insert(name.to_owned(), value.clone());
760            }
761            continue;
762        }
763        if operator != "defn" {
764            continue;
765        }
766        let Some(Form::Metadata(metadata, _)) = items.get(1) else {
767            continue;
768        };
769        let Form::Map(entries) = metadata.as_ref() else {
770            continue;
771        };
772        let Some(schema) = entries.iter().find_map(|(key, value)| {
773            matches!(key, Form::Keyword(name) if name == "schema").then_some(value)
774        }) else {
775            continue;
776        };
777        index.functions.insert(qualified_name, schema.clone());
778        collect_local_schema_references(schema, namespace, &mut roots);
779    }
780
781    let mut visited = HashSet::new();
782    while let Some(name) = roots.pop() {
783        if !visited.insert(name.clone()) {
784            continue;
785        }
786        let Some(value) = values.get(&name) else {
787            continue;
788        };
789        index
790            .definitions
791            .insert(format!("{namespace}/{name}"), value.clone());
792        collect_local_schema_references(value, namespace, &mut roots);
793    }
794    for (name, schema) in &index.definitions {
795        index.definition_types.insert(
796            name.clone(),
797            super::normalize_schema(schema)
798                .map_err(|error| format!("invalid schema {name}: {error}"))?,
799        );
800    }
801    for (name, schema) in &index.functions {
802        index.function_types.insert(
803            name.clone(),
804            super::normalize_schema(schema)
805                .map_err(|error| format!("invalid function schema {name}: {error}"))?,
806        );
807    }
808    Ok(index)
809}
810
811fn collect_local_schema_references(form: &Form, namespace: &str, output: &mut Vec<String>) {
812    if let Form::List(reference) = form {
813        if reference.len() == 2
814            && matches!(&reference[0], Form::Symbol(operator) if operator == "var")
815        {
816            if let Form::Symbol(target) = &reference[1] {
817                if let Some((qualifier, local)) = target.rsplit_once('/') {
818                    if qualifier == namespace {
819                        output.push(local.to_owned());
820                    }
821                }
822            }
823            return;
824        }
825    }
826    match form {
827        Form::Tagged(_, value) => collect_local_schema_references(value, namespace, output),
828        Form::Metadata(metadata, value) => {
829            collect_local_schema_references(metadata, namespace, output);
830            collect_local_schema_references(value, namespace, output);
831        }
832        Form::Map(entries) => {
833            for (key, value) in entries {
834                collect_local_schema_references(key, namespace, output);
835                collect_local_schema_references(value, namespace, output);
836            }
837        }
838        Form::Set(values) | Form::Vector(values) | Form::List(values) => {
839            for value in values {
840                collect_local_schema_references(value, namespace, output);
841            }
842        }
843        _ => {}
844    }
845}
846
847#[cfg(test)]
848mod tests {
849    use super::*;
850    use crate::kernel::parse;
851
852    fn artifact_payload(forms: Vec<Form>) -> Vec<u8> {
853        encode_halc_module("demo.ns", "demo.hal", "", forms).unwrap()
854    }
855
856    #[test]
857    fn round_trips_primitive_values() {
858        let cases = [
859            "nil",
860            "true",
861            "false",
862            "42",
863            "-7",
864            "3.14",
865            "\"hello\"",
866            "\\x",
867            ":key",
868            ":ns/key",
869            "symbol",
870            "ns/symbol",
871        ];
872        for source in cases {
873            let original = parse(source).unwrap();
874            let bytes = artifact_payload(vec![original.clone()]);
875            let decoded = decode_halc(&bytes).unwrap();
876            assert_eq!(decoded.forms.len(), 1);
877            assert_eq!(decoded.forms[0], original, "{source}");
878        }
879    }
880
881    #[test]
882    fn round_trips_collections() {
883        let original = parse("(do {:a [1 2] :b #{3 4}})").unwrap();
884        let bytes = artifact_payload(vec![original.clone()]);
885        let decoded = decode_halc(&bytes).unwrap();
886        assert_eq!(decoded.forms.len(), 1);
887        assert_eq!(decoded.forms[0], original);
888    }
889
890    #[test]
891    fn schema_var_references_are_checked_and_namespace_canonicalized() {
892        let source = "(ns demo.schema) \
893                      (def Customer [:map [:id :int]]) \
894                      (defn ^{:schema #'-/Customer} customer-id [customer] customer)";
895        let bytes = encode_halc_module(
896            "demo.schema",
897            "demo/schema.hal",
898            source,
899            crate::kernel::parse_forms(source).unwrap(),
900        )
901        .unwrap();
902        let module = decode_halc(&bytes).unwrap();
903        let Form::List(definition) = &module.forms[2] else {
904            panic!("expected defn");
905        };
906        let Form::Metadata(metadata, _) = &definition[1] else {
907            panic!("expected definition metadata");
908        };
909        let Form::Map(metadata) = metadata.as_ref() else {
910            panic!("expected metadata map");
911        };
912        let schema = metadata
913            .iter()
914            .find_map(|(key, value)| {
915                matches!(key, Form::Keyword(name) if name == "schema").then_some(value)
916            })
917            .unwrap();
918        assert_eq!(
919            schema,
920            &Form::List(vec![
921                Form::Symbol("var".into()),
922                Form::Symbol("demo.schema/Customer".into()),
923            ])
924        );
925
926        let missing = "(ns demo.schema) \
927                       (defn ^{:schema #'MissingSchema} invalid [value] value)";
928        assert_eq!(
929            encode_halc_module(
930                "demo.schema",
931                "demo/schema.hal",
932                missing,
933                crate::kernel::parse_forms(missing).unwrap(),
934            )
935            .unwrap_err(),
936            "schema Var does not exist: MissingSchema"
937        );
938    }
939
940    #[test]
941    fn nested_schema_var_references_are_canonicalized_and_checked() {
942        let source = "(ns demo.schema) \
943                      (def Address [:map [:street :str]]) \
944                      (def Customer [:map [:address #'-/Address]]) \
945                      (defn ^{:schema #'Customer} save [customer] customer)";
946        let bytes = encode_halc_module(
947            "demo.schema",
948            "demo/schema.hal",
949            source,
950            crate::kernel::parse_forms(source).unwrap(),
951        )
952        .unwrap();
953        let module = decode_halc(&bytes).unwrap();
954        assert!(module.forms[2]
955            .to_string()
956            .contains("(var demo.schema/Address)"));
957        assert_eq!(module.schemas.functions.len(), 1);
958        assert!(module.schemas.functions.contains_key("demo.schema/save"));
959        assert_eq!(module.schemas.definitions.len(), 2);
960        assert!(module
961            .schemas
962            .definitions
963            .contains_key("demo.schema/Address"));
964        assert!(module
965            .schemas
966            .definitions
967            .contains_key("demo.schema/Customer"));
968        assert!(matches!(
969            module.schemas.resolved_function_type("demo.schema/save"),
970            Some(super::super::SchemaType::Map(fields)) if fields.len() == 1
971        ));
972
973        let missing = "(ns demo.schema) \
974                       (def Customer [:map [:address #'MissingAddress]]) \
975                       (defn ^{:schema #'Customer} save [customer] customer)";
976        assert_eq!(
977            encode_halc_module(
978                "demo.schema",
979                "demo/schema.hal",
980                missing,
981                crate::kernel::parse_forms(missing).unwrap(),
982            )
983            .unwrap_err(),
984            "schema Var does not exist: MissingAddress"
985        );
986
987        let recursive = "(ns demo.schema) \
988                         (def Node [:map [:children [:vector #'Node]]]) \
989                         (defn ^{:schema #'Node} walk [node] node)";
990        assert!(encode_halc_module(
991            "demo.schema",
992            "demo/schema.hal",
993            recursive,
994            crate::kernel::parse_forms(recursive).unwrap(),
995        )
996        .is_ok());
997
998        let malformed = "(ns demo.schema) \
999                         (def Customer [:map [:name]]) \
1000                         (defn ^{:schema #'Customer} save [customer] customer)";
1001        assert_eq!(
1002            encode_halc_module(
1003                "demo.schema",
1004                "demo/schema.hal",
1005                malformed,
1006                crate::kernel::parse_forms(malformed).unwrap(),
1007            )
1008            .unwrap_err(),
1009            "invalid schema demo.schema/Customer: :map schema fields must be [name type] or [name properties type]"
1010        );
1011    }
1012
1013    #[test]
1014    fn round_trips_metadata() {
1015        let original = parse("^:dynamic *value*").unwrap();
1016        let bytes = artifact_payload(vec![original.clone()]);
1017        let decoded = decode_halc(&bytes).unwrap();
1018        assert_eq!(decoded.forms, vec![original]);
1019    }
1020
1021    #[test]
1022    fn rejects_bad_magic() {
1023        let mut bytes = artifact_payload(vec![Form::Nil]);
1024        bytes[0] = 0;
1025        assert!(decode_halc(&bytes).unwrap_err().contains("bad magic"));
1026    }
1027
1028    #[test]
1029    fn rejects_checksum_mismatch() {
1030        let mut bytes = artifact_payload(vec![Form::Nil]);
1031        let last = bytes.len() - 1;
1032        bytes[last] = bytes[last].wrapping_add(1);
1033        assert!(decode_halc(&bytes).unwrap_err().contains("checksum"));
1034    }
1035
1036    #[test]
1037    fn decodes_the_truffle_portable_format_golden_artifact() {
1038        // This is the canonical v1 artifact emitted by Truffle's
1039        // HalcArtifactTest.goldenBytesLockThePortableFormat. Keep this test
1040        // independent of Rust's test-only encoder: it is the cross-runtime
1041        // compatibility boundary, rather than a Rust encoder/decoder
1042        // round-trip.
1043        let bytes = hex_bytes(concat!(
1044            "48414c43000100010000013f57211e103028689092d59627fbba64015c289acd1bc5b2e7be27ec53d8bf4c35",
1045            "00000001740000000174e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
1046            "0000001100010203000000000000002a044004000000000000050000001e313233343536373839303132",
1047            "333435363738393031323334353637383930060000000668c3a172c3a008000000780901000000056d792e6e73",
1048            "000000066d792d73796d000a00000000026b77000b00000002030000000000000001060000000161000c00000002",
1049            "030000000000000001060000000161000d00000002030000000000000001060000000161030000000000000002",
1050            "060000000162000e00000002030000000000000001030000000000000002000f00000002030000000000000002",
1051            "060000000162030000000000000001060000000161001000000002030000000000000002030000000000000001",
1052            "001100000003612b62",
1053        ));
1054
1055        let module = decode_halc(&bytes).unwrap();
1056        assert_eq!(module.origin, HalcOrigin::Halc);
1057        assert_eq!(module.namespace, "t");
1058        assert_eq!(module.resource, "t");
1059        assert_eq!(module.forms.len(), 17);
1060        assert_eq!(module.forms[0], Form::Nil);
1061        assert_eq!(module.forms[3], Form::Number(42));
1062        assert_eq!(module.forms[6], Form::String("hárà".into()));
1063        assert_eq!(module.forms[7], Form::Character('x'));
1064        assert_eq!(module.forms[8], Form::Symbol("my.ns/my-sym".into()));
1065        assert_eq!(module.forms[9], Form::Keyword("kw".into()));
1066        assert_eq!(module.forms[16], Form::Regex("a+b".into()));
1067    }
1068
1069    #[test]
1070    fn legacy_hir_magic_decodes_but_encoding_always_uses_halc_magic() {
1071        let halc = artifact_payload(vec![Form::Number(42)]);
1072        let mut legacy = halc.clone();
1073        legacy[..4].copy_from_slice(LEGACY_MAGIC);
1074
1075        assert_eq!(decode_halc(&legacy).unwrap().origin, HalcOrigin::LegacyHir);
1076        assert_eq!(&halc[..4], MAGIC);
1077    }
1078
1079    #[test]
1080    fn shared_cross_runtime_goldens_decode() {
1081        let complete = std::fs::read(crate::spec_registry::require(
1082            "01-lang/009-halc/draft/conformance/golden/complete.halc",
1083        ))
1084        .expect("complete HALC golden is readable");
1085        let legacy = std::fs::read(crate::spec_registry::require(
1086            "01-lang/009-halc/draft/conformance/golden/legacy-v1.hir",
1087        ))
1088        .expect("legacy HIR golden is readable");
1089        let current = decode_halc(&complete).unwrap();
1090        assert_eq!(current.origin, HalcOrigin::Halc);
1091        assert_eq!(current.namespace, "halc.conformance.complete");
1092        assert_eq!(current.resource, "conformance/complete.hal");
1093        assert_eq!(decode_halc(&legacy).unwrap().origin, HalcOrigin::LegacyHir);
1094    }
1095
1096    #[test]
1097    fn registry_golden_matches_rust_encoding() {
1098        let source_path = crate::spec_registry::require(
1099            "01-lang/009-halc/draft/conformance/complete.hal",
1100        );
1101        let source = std::fs::read_to_string(source_path).expect("HALC source is readable");
1102        let forms = crate::kernel::parse_forms(&source).expect("HALC source parses");
1103        let encoded = encode_halc_module(
1104            "halc.conformance.complete",
1105            "conformance/complete.hal",
1106            &source,
1107            forms,
1108        )
1109        .expect("HALC source encodes");
1110        let expected = std::fs::read(crate::spec_registry::require(
1111            "01-lang/009-halc/draft/conformance/golden/complete.halc",
1112        ))
1113        .expect("HALC golden is readable");
1114        assert_eq!(expected, encoded);
1115    }
1116
1117    fn hex_bytes(hex: &str) -> Vec<u8> {
1118        (0..hex.len())
1119            .step_by(2)
1120            .map(|index| u8::from_str_radix(&hex[index..index + 2], 16).unwrap())
1121            .collect()
1122    }
1123}
hara_native/kernel/halc.rs

hara_native/kernel/
halc.rs
