Skip to main content

candela_vm/
artifact.rs

1//! Bytecode artifact format (`.cdlb`) and the VM-only load/run API.
2//!
3//! This mirrors an AOT model: the full `candela` toolchain (compiler + VM)
4//! compiles a `.cdl` source to a compact, self-contained bytecode artifact
5//! ([`ProgramImage`] serialized via [`serialize_image`]), and the VM-only
6//! `candela-vm` binary loads it ([`load_program`]) and runs it
7//! ([`RuntimeProgram::run`]) WITHOUT the parser, compiler, or REPL.
8//!
9//! An embedding host gets the same two halves the `Engine`/`Program` pair
10//! gives it, minus the compiler: it supplies a [`HostRegistry`] at load so the
11//! artifact's `host` functions bind to Rust closures, and it invokes script
12//! functions by name through [`RuntimeProgram::call`], which runs a trampoline
13//! the compiler emitted at build time.
14//!
15//! The on-disk format is: a 4-byte magic (`CDLB`), a 1-byte format version, then
16//! a `postcard`-encoded [`ProgramImage`]. `postcard` was chosen over `bincode`
17//! because it is `no_std`/`alloc`-friendly and its varint encoding keeps the
18//! artifact small; it also pulls in the least code, which matters for the
19//! `candela-vm` binary-size budget.
20//!
21//! [`ProgramImage`] carries `pub` fields so the `candela` crate's `build`
22//! subcommand can populate it from a fresh compile; everything needed to LOAD
23//! and RUN it lives here.
24
25use crate::attributes::Attribute;
26use crate::attributes::AttributeTable;
27use crate::data::Data;
28use crate::embed::HostBindError;
29use crate::embed::HostDispatch;
30use crate::embed::HostRegistry;
31use crate::embed::Value;
32use crate::embed::describe_value;
33use crate::embed::marshal_args;
34use crate::embed::unmarshal_value;
35use crate::embed::value_matches_type;
36use crate::errors::Diagnostic;
37use crate::errors::ErrorCtx;
38use crate::errors::RuntimeError;
39use crate::instr::Instr;
40use crate::rt::DataType;
41use crate::rt::DynamicLibFn;
42use crate::rt::EnumType;
43use crate::rt::EnumVariant;
44use crate::rt::GcStats;
45use crate::rt::HostFnSig;
46use crate::rt::InstrSrc;
47use crate::rt::LibraryOrigin;
48use crate::rt::Pools;
49use crate::rt::Source;
50use crate::rt::Span;
51use crate::rt::Struct;
52#[cfg(not(target_arch = "wasm32"))]
53use crate::rt::TargetOs;
54#[cfg(not(target_arch = "wasm32"))]
55use crate::rt::resolve_library_filename;
56use crate::vm;
57use crate::vm::CandelaMap;
58use crate::vm::MapPool;
59use crate::vm::ObjectPool;
60use crate::vm::Pool;
61use crate::vm::RegisterFile;
62use crate::vm::StringPool;
63use serde::Deserialize;
64use serde::Serialize;
65use smol_strc::SmolStr;
66use std::collections::HashMap;
67
68/// The pair of words a value is recorded as. See [`Data::into_words`].
69pub type DataWords = (u64, i64);
70
71/// 4-byte artifact magic, so a non-`.cdlb` file fails cleanly.
72const MAGIC: [u8; 4] = *b"CDLB";
73/// Bumped whenever the serialized shape changes, so a mismatched artifact is
74/// rejected instead of mis-decoded. Version 2 added the dynamic-library and
75/// host-function recipe tables (`dyn_lib_fns`/`host_fns`). Version 3 added the
76/// native-enum type table (`enums`) and the `CloneEnum` instruction. Version 4
77/// added the map/json/any library functions (`Keys`/`Values`/`JsonParse`/
78/// `JsonStringify` and the `is_*`/`as_*` value ops). Version 5 added the export
79/// table (`exports`), the call trampolines that back
80/// [`RuntimeProgram::call`]. Version 6 added the `MapRemove` instruction and
81/// the origin of each dynamic-library recipe, which says whether its spec is
82/// the program's own or a path into the standard library's `libs` directory.
83/// Version 7 widened `int` to 64 bits, so every recorded value carries a
84/// second word. Version 8 added the cell instructions a captured variable is
85/// read and written through. Version 9 added the indirect call, which dispatches
86/// on the function a value carries. Version 10 added the instruction that
87/// builds a function value, which tells a function from the list it is built
88/// as wherever one becomes text. Version 11 added the string comparison and
89/// bitwise instructions, which sit among the existing ones and so renumber the
90/// instructions after them, and gave the order of each map's recorded pairs a
91/// meaning: a map is walked in the order its keys went in, so the pair list is
92/// the program's order and an artifact from before the change cannot supply it.
93/// Version 12 added the loop step and the add-a-constant instructions, which
94/// sit among the existing ones and so renumber the instructions after them.
95/// Version 13 added the move chain and the add-to-a-float-field instructions,
96/// which renumber the instructions after them the same way. Version 14 added
97/// the machine code sections ([`ProgramImage::native`]) and the function table
98/// that follows the image ([`FunctionTable`]). Version 15 added the type test
99/// `is` compiles to for a struct, an enum, a function, a union or a collection,
100/// and the nested type codes that check what a list or a map holds. Version 16
101/// added the event entry ([`ProgramImage::event_entry`]) and the instructions
102/// `std/event` and the new `std/fs` functions compile to. Version 17 added the
103/// attribute table ([`ProgramImage::attributes`]).
104const FORMAT_VERSION: u8 = 17;
105
106/// Serializable mirror of a compiled program's runtime state.
107///
108/// A dedicated DTO keeps `serde` off the hot runtime types: `Data` becomes its
109/// pair of raw words, `SmolStr` becomes `String`, maps become key/value pairs.
110/// Only [`Instr`], [`Span`], and [`DataType`] carry `serde` derives directly.
111/// Fields are `pub` so the compiler front-end can build an image from a fresh
112/// compile.
113#[derive(Serialize, Deserialize)]
114pub struct ProgramImage {
115    pub instructions: Vec<Instr>,
116    pub registers: Vec<DataWords>,
117    pub objs: Vec<Vec<DataWords>>,
118    pub maps: Vec<Vec<(DataWords, DataWords)>>,
119    pub strings: Vec<String>,
120    pub instr_src: Vec<InstrSrcImage>,
121    /// The registers each recursive call site saves across its call, indexed by
122    /// the call-site id its `SaveFrame` carries.
123    pub callsite_registers: Vec<Vec<u16>>,
124    pub structs: Vec<StructImage>,
125    pub enums: Vec<EnumImage>,
126    pub sources: Vec<SourceImage>,
127    pub allocated_arg_count: u64,
128    pub allocated_call_depth: u64,
129    /// Recipe for each dynamic-library binding, in `DynamicLibFn` id order. The
130    /// artifact stores only the logical library name, symbol, and marshalling
131    /// signature, never the shared object's bytes, so the VM re-opens the
132    /// library and re-binds the symbol by name at load time (see
133    /// [`resolve_library_filename`]).
134    pub dyn_lib_fns: Vec<DynLibFnImage>,
135    /// Recipe for each `host` function declared by the program, in host-fn id
136    /// order. The [`HostRegistry`] handed to [`load_program`] supplies the
137    /// closure behind each one; an unregistered name is a load error.
138    pub host_fns: Vec<HostFnImage>,
139    /// One entry per host-callable function, each with the call trampoline the
140    /// compiler emitted for it at build time. This is what lets the VM invoke a
141    /// script function by name with no compiler present.
142    pub exports: Vec<ExportImage>,
143    /// The trampoline the runtime runs event handlers through: `std/event`'s
144    /// `dispatch`, taking a budget and whether to wait. Present when the
145    /// program imports `std/event`.
146    pub event_entry: Option<ExportImage>,
147    /// Machine code for some of the program's functions, one section per
148    /// machine it was built for. The VM runs the first section this machine
149    /// can run and the bytecode for everything else; a program whose sections
150    /// all name another machine runs on bytecode alone. The bytecode stays
151    /// complete either way.
152    pub native: Vec<NativeImage>,
153    /// Every attribute a `host` block declares that the program's scripts
154    /// wrote on a function or a struct, as the compiler checked it.
155    pub attributes: Vec<Attribute>,
156}
157
158/// Machine code `candela build` generated for one kind of machine, and what
159/// the VM needs to know to run it.
160///
161/// The code has no relocations left: calls between its functions were
162/// resolved when it was laid out, and it reaches the VM only through the
163/// context the VM passes in. Loading it is a copy into memory the VM then
164/// makes executable, and a rewrite of the calls it covers.
165#[derive(Serialize, Deserialize, Clone, Debug)]
166pub struct NativeImage {
167    /// The version of the contract between the code and the VM: the context
168    /// layout, the helper functions, and the layout of a value. A VM that
169    /// speaks another version runs bytecode.
170    pub abi: u32,
171    pub arch: NativeArch,
172    /// The operating system the calling convention is that of.
173    pub os: NativeOs,
174    /// Instruction set extensions the code uses beyond the architecture's
175    /// baseline, by the names Rust's feature detection uses. The VM checks
176    /// each one on the machine it runs on.
177    pub cpu_features: Vec<String>,
178    /// Where the object pool's per-object vector keeps its size, buffer
179    /// pointer and length, as the build measured it. The code reads objects
180    /// through that layout, so the VM checks it against its own.
181    pub object_layout: [u8; 3],
182    /// The most stack one of the functions takes per call, in bytes. The VM
183    /// sizes how deep native recursion may go from it before a call carries
184    /// on in the interpreter.
185    pub frame_bytes: u32,
186    /// The functions the section holds.
187    pub functions: Vec<NativeFunctionImage>,
188    /// The function that stands in for `main`, when `main` itself was
189    /// compiled.
190    pub main: Option<u32>,
191    /// The call instructions the VM rewrites to call into the section.
192    pub sites: Vec<NativeSiteImage>,
193    pub code: Vec<u8>,
194}
195
196/// An architecture machine code is built for.
197#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
198pub enum NativeArch {
199    X86_64,
200    Aarch64,
201}
202
203/// An operating system whose calling convention machine code follows.
204#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
205pub enum NativeOs {
206    Linux,
207    MacOs,
208    Windows,
209}
210
211/// One function in a [`NativeImage`].
212#[derive(Serialize, Deserialize, Clone, Debug)]
213pub struct NativeFunctionImage {
214    /// The instruction its bytecode starts at.
215    pub loc: u32,
216    /// Where its entry point starts in the section's code.
217    pub offset: u32,
218    /// Whether it returns a value.
219    pub returns: bool,
220}
221
222/// A call instruction the VM points at a native function once it loads.
223#[derive(Serialize, Deserialize, Clone, Copy, Debug)]
224pub struct NativeSiteImage {
225    /// The instruction, a `CallFunc` or a `CallFuncRecursive`.
226    pub at: u32,
227    /// Its callee, by index into [`NativeImage::functions`].
228    pub function: u32,
229}
230
231/// What the compiler knows about each function of a program, written after
232/// the [`ProgramImage`] in a `.cdlb`.
233///
234/// It is what code generation reads instead of working types out of the
235/// bytecode: where each function starts, which registers its parameters
236/// arrive in, and the type of every value each instruction writes. The VM
237/// never reads it.
238#[derive(Serialize, Deserialize, Clone, Debug, Default)]
239pub struct FunctionTable {
240    pub functions: Vec<FunctionImage>,
241}
242
243/// One compiled function in a [`FunctionTable`]: `main`, or one
244/// specialisation of a declared function or closure.
245#[derive(Serialize, Deserialize, Clone, Debug)]
246pub struct FunctionImage {
247    /// The name the function was declared with; `main` for the program's
248    /// entry.
249    pub name: String,
250    /// The instruction the body starts at.
251    pub entry: u32,
252    /// The register each parameter arrives in, in declaration order.
253    pub params: Vec<u16>,
254    /// The type of each parameter.
255    pub param_types: Vec<DataType>,
256    /// What the function returns: `Null` for nothing.
257    pub returns: DataType,
258    /// The register a closure reads its captured environment from.
259    pub env: Option<u16>,
260    /// Whether a call through a function value can reach it.
261    pub indirect: bool,
262    /// The type of the value each instruction of the body writes into each
263    /// register it writes, in instruction order.
264    pub defs: Vec<DefImage>,
265}
266
267/// The type of one value an instruction writes.
268#[derive(Serialize, Deserialize, Clone, Debug)]
269pub struct DefImage {
270    /// The instruction.
271    pub at: u32,
272    /// The register it writes.
273    pub reg: u16,
274    /// The type of what it writes there. `Unknown` where the compiler cannot
275    /// tell, such as an element of a list built from a literal.
276    pub ty: DataType,
277}
278
279/// Serializable recipe for one dynamic-library binding: enough to re-open the
280/// library and re-resolve the symbol by name at load, with no embedded bytes.
281#[derive(Serialize, Deserialize)]
282pub struct DynLibFnImage {
283    /// Logical library name (`z`, `sqlite3`) or path. A program's own binding
284    /// records it exactly as the source `dylib "..."` block wrote it; a
285    /// standard-library one records it relative to the `libs` directory.
286    pub library: String,
287    /// The C symbol resolved within `library`.
288    pub symbol: String,
289    /// `[ return_type, arg_types... ]`, driving the rebuilt libffi CIF.
290    pub types: Vec<DataType>,
291    /// Which search `library` is resolved through at load.
292    pub origin: LibraryOrigin,
293}
294
295/// Serializable recipe for one `host` function: its fully-qualified name and
296/// marshalling signature, so an embedding runtime can re-bind it by name.
297#[derive(Serialize, Deserialize)]
298pub struct HostFnImage {
299    pub namespace: String,
300    pub name: String,
301    /// `[ return_type, arg_types... ]`.
302    pub types: Vec<DataType>,
303    pub variadic: bool,
304}
305
306impl From<&HostFnImage> for HostFnSig {
307    fn from(image: &HostFnImage) -> Self {
308        Self {
309            types: image.types.clone().into_boxed_slice(),
310            namespace: SmolStr::from(image.namespace.as_str()),
311            name: SmolStr::from(image.name.as_str()),
312            variadic: image.variadic,
313        }
314    }
315}
316
317/// One host-callable function, with the call trampoline `candela build`
318/// compiled for it.
319///
320/// The compiler specialises the function for its declared parameter types and
321/// lays down a short instruction run that moves the parameter registers into
322/// place, calls the specialisation, and halts. Invoking it is then a matter of
323/// writing marshalled arguments into `arg_registers` and executing from
324/// `entry`; the result is left in `ret_register`.
325#[derive(Serialize, Deserialize)]
326pub struct ExportImage {
327    /// The name the function is called by, as written in the source.
328    pub name: String,
329    /// Instruction index the trampoline starts at.
330    pub entry: u64,
331    /// The register holding each parameter, in declaration order.
332    pub arg_registers: Vec<u16>,
333    /// The declared type of each parameter, checked against the host's
334    /// arguments before the call runs.
335    pub arg_types: Vec<DataType>,
336    /// The register the trampoline leaves the result in. Register 0 is the null
337    /// sink, which is what a function returning nothing lands on.
338    pub ret_register: u16,
339}
340
341#[derive(Serialize, Deserialize)]
342pub struct InstrSrcImage {
343    pub instr: Instr,
344    pub span: Span,
345    pub file_id: u16,
346}
347
348#[derive(Serialize, Deserialize)]
349pub struct StructImage {
350    pub name: String,
351    pub fields: Vec<(String, DataType, Span)>,
352    pub id: u16,
353    pub name_span: Span,
354}
355
356#[derive(Serialize, Deserialize)]
357pub struct EnumImage {
358    pub name: String,
359    pub variants: Vec<EnumVariantImage>,
360    pub id: u16,
361    pub name_span: Span,
362}
363
364#[derive(Serialize, Deserialize)]
365pub struct EnumVariantImage {
366    pub name: String,
367    pub payload: Vec<DataType>,
368    pub name_span: Span,
369}
370
371#[derive(Serialize, Deserialize)]
372pub struct SourceImage {
373    pub filename: String,
374    pub contents: String,
375}
376
377/// The registers a call read its arguments from and left its result in.
378struct ExportRegisters {
379    arg_registers: Box<[u16]>,
380    ret_register: u16,
381}
382
383/// Whether a host value reaches a script function by reference, so a call
384/// can hand back what the function did to it.
385#[must_use]
386pub fn passed_by_reference(value: &Value) -> bool {
387    matches!(
388        value,
389        Value::Array(_) | Value::Map(_) | Value::Struct { .. }
390    )
391}
392
393/// One host-callable function in a loaded program: where its trampoline starts,
394/// which registers its parameters live in, and what it leaves the result in.
395struct Export {
396    entry: usize,
397    arg_registers: Box<[u16]>,
398    arg_types: Box<[DataType]>,
399    ret_register: u16,
400}
401
402impl From<ExportImage> for Export {
403    fn from(e: ExportImage) -> Self {
404        Self {
405            entry: e.entry as usize,
406            arg_registers: e.arg_registers.into_boxed_slice(),
407            arg_types: e.arg_types.into_boxed_slice(),
408            ret_register: e.ret_register,
409        }
410    }
411}
412
413/// A loaded, ready-to-run program image with owned runtime state.
414///
415/// Produced by [`load_program`] from `.cdlb` bytes. [`Self::run`] executes it
416/// exactly as the full `candela` binary runs a freshly compiled program, and
417/// [`Self::call`] invokes an exported function by name. Registers and heap
418/// pools stay resident between calls, so state one call establishes is visible
419/// to the next.
420pub struct RuntimeProgram {
421    instructions: Vec<Instr>,
422    registers: Vec<Data>,
423    pools: Pools,
424    instr_src: Vec<InstrSrc>,
425    callsite_registers: Vec<Vec<u16>>,
426    dyn_lib_fns: Vec<DynamicLibFn>,
427    host_sigs: Vec<HostFnSig>,
428    host_dispatch: Vec<HostDispatch>,
429    exports: HashMap<String, Export>,
430    /// Where the event dispatcher's trampoline starts, when there is one.
431    event_entry: Option<Export>,
432    structs: Vec<Struct>,
433    enums: Vec<EnumType>,
434    sources: Vec<Source>,
435    allocated_arg_count: usize,
436    allocated_call_depth: usize,
437    /// The program's machine code, when its artifact carries some this
438    /// machine runs.
439    native: Option<crate::native::NativeCode>,
440    /// The attributes its scripts wrote.
441    attributes: Vec<Attribute>,
442}
443
444impl RuntimeProgram {
445    /// Loads the first of `sections` this machine can run, and points the
446    /// calls it covers at it. Without one the program runs on bytecode.
447    fn load_native(&mut self, sections: &[NativeImage]) {
448        if sections.is_empty() {
449            return;
450        }
451        #[cfg(not(target_arch = "wasm32"))]
452        let dylibs = self
453            .dyn_lib_fns
454            .iter()
455            .map(|f| f.ptr.as_ptr().cast::<u8>())
456            .collect();
457        #[cfg(target_arch = "wasm32")]
458        let dylibs = Vec::new();
459        self.native = crate::native::load(sections, &mut self.instructions, dylibs);
460    }
461
462    /// How many of the program's functions run as machine code on this
463    /// machine: zero when its artifact carries none this machine runs.
464    #[must_use]
465    pub fn native_functions(&self) -> usize {
466        self.native.as_ref().map_or(0, |n| n.functions.len())
467    }
468
469    /// Runs the program's `main` to completion.
470    ///
471    /// A runtime error prints its report and ends the process, matching the
472    /// full `candela <file.cdl>` path exactly. A
473    /// host that wants the error as a value instead runs this inside
474    /// [`collect_diagnostic`](crate::collect_diagnostic).
475    pub fn run(&mut self) {
476        let err_ctx = ErrorCtx {
477            instr_src: &self.instr_src,
478            sources: &self.sources,
479        };
480        let mut register_file = RegisterFile(std::mem::take(&mut self.registers));
481        let result = vm::execute(
482            &self.instructions,
483            &mut register_file,
484            &mut self.pools,
485            &err_ctx,
486            &self.callsite_registers,
487            &self.dyn_lib_fns,
488            &self.structs,
489            &self.enums,
490            self.allocated_arg_count,
491            self.allocated_call_depth,
492            &self.host_sigs,
493            &self.host_dispatch,
494            0,
495            self.native.as_ref(),
496        );
497        self.registers = std::mem::take(&mut register_file.0);
498        if let Err(error) = result {
499            error.report(&err_ctx);
500        }
501        // Work `main` started may still be running: keep running its handlers
502        // until nothing is held and nothing is queued.
503        if self.event_entry.is_some()
504            && let Err(error) = self.run_events(-1, true)
505        {
506            let err_ctx = ErrorCtx {
507                instr_src: &self.instr_src,
508                sources: &self.sources,
509            };
510            error.report(&err_ctx);
511        }
512    }
513
514    /// Runs the handlers of events that have arrived for this program, at
515    /// most `budget` of them, and answers how many ran. Never waits.
516    ///
517    /// A host that runs its own loop calls this from it, on the thread the
518    /// program runs on, after the waker it set with
519    /// [`set_event_waker`](crate::set_event_waker) said something arrived. A
520    /// program that does not import `std/event` has no handlers, and the
521    /// answer is always 0.
522    ///
523    /// # Errors
524    ///
525    /// Returns [`CallError::Runtime`] when a handler raised an error no `try`
526    /// caught. The events behind it stay queued for the next call.
527    pub fn dispatch_events(&mut self, budget: u32) -> Result<usize, CallError> {
528        if self.event_entry.is_none() {
529            return Ok(0);
530        }
531        self.run_events(i64::from(budget), false).map_err(|error| {
532            CallError::Runtime(error.diagnostic(&ErrorCtx {
533                instr_src: &self.instr_src,
534                sources: &self.sources,
535            }))
536        })
537    }
538
539    /// Runs the event entry with `budget` and `wait`, answering how many
540    /// handlers ran.
541    fn run_events(&mut self, budget: i64, wait: bool) -> Result<usize, RuntimeError> {
542        let Some(entry) = &self.event_entry else {
543            return Ok(0);
544        };
545        let (start, ret) = (entry.entry, entry.ret_register as usize);
546        self.registers[entry.arg_registers[0] as usize] = Data::int(budget);
547        self.registers[entry.arg_registers[1] as usize] = Data::from(wait);
548        self.execute_raw(start)?;
549        Ok(self.registers[ret].as_int().max(0) as usize)
550    }
551
552    /// Invokes the exported function `name` with `args`, returning its value
553    /// (or [`Value::Null`] for a function that returns nothing).
554    ///
555    /// The call runs the trampoline the compiler emitted for the function at
556    /// build time, against the resident register and heap state, so globals a
557    /// previous call or `main` established remain visible. Arguments are
558    /// checked against the declared parameter types before anything runs.
559    ///
560    /// # Errors
561    ///
562    /// Returns a [`CallError`] if the artifact exports no such function, if the
563    /// arguments disagree with the declared signature, or if the call raises a
564    /// runtime error.
565    pub fn call(&mut self, name: &str, args: &[Value]) -> Result<Value, CallError> {
566        let export = self.run_export(name, args)?;
567        Ok(self.read_register(export.ret_register))
568    }
569
570    /// [`Self::call`], handing back what the function left in each argument it
571    /// was passed by reference.
572    ///
573    /// A list, a map and a struct reach a script function by reference, so
574    /// what the function writes into one is written into the value the call
575    /// passed. Once the call returns, every argument that is one of those is
576    /// replaced with its final value; every other argument is left as it was.
577    /// This is how a host passes data in, lets the script change it, and reads
578    /// the result back in one call.
579    ///
580    /// # Errors
581    ///
582    /// As [`Self::call`]. An argument is only replaced once the call has run
583    /// without an error.
584    pub fn call_in_out(&mut self, name: &str, args: &mut [Value]) -> Result<Value, CallError> {
585        let export = self.run_export(name, args)?;
586        for (arg, &register) in args.iter_mut().zip(export.arg_registers.iter()) {
587            if passed_by_reference(arg) {
588                *arg = self.read_register(register);
589            }
590        }
591        Ok(self.read_register(export.ret_register))
592    }
593
594    /// Checks `args` against the export `name`, marshals them into its
595    /// argument registers and runs its trampoline, answering the registers it
596    /// read its arguments from and left its result in.
597    fn run_export(&mut self, name: &str, args: &[Value]) -> Result<ExportRegisters, CallError> {
598        let export = self
599            .exports
600            .get(name)
601            .ok_or_else(|| CallError::UnknownFunction(name.to_owned()))?;
602
603        if export.arg_registers.len() != args.len() {
604            return Err(CallError::ArgCount {
605                function: name.to_owned(),
606                expected: export.arg_registers.len(),
607                found: args.len(),
608            });
609        }
610        for (idx, (arg, declared)) in args.iter().zip(export.arg_types.iter()).enumerate() {
611            if !value_matches_type(arg, declared, &self.structs) {
612                return Err(CallError::ArgType {
613                    function: name.to_owned(),
614                    index: idx + 1,
615                    expected: AttributeTable::new(Vec::new(), &self.structs, &self.enums)
616                        .type_name(declared),
617                    found: describe_value(arg),
618                });
619            }
620        }
621
622        let entry = export.entry;
623        let registers = ExportRegisters {
624            arg_registers: export.arg_registers.clone(),
625            ret_register: export.ret_register,
626        };
627        marshal_args(
628            args,
629            &registers.arg_registers,
630            &mut self.registers,
631            &mut self.pools,
632            &self.structs,
633        );
634
635        self.execute_from(entry)?;
636        Ok(registers)
637    }
638
639    /// The value register `register` holds, read back into a host [`Value`].
640    fn read_register(&self, register: u16) -> Value {
641        unmarshal_value(
642            self.registers[register as usize],
643            &self.pools.objs,
644            &self.pools.maps,
645            &self.pools.strings,
646            &self.structs,
647            &self.enums,
648        )
649    }
650
651    /// Every attribute the program's scripts wrote, with the struct and enum
652    /// tables the types in it refer to.
653    #[must_use]
654    pub fn attributes(&self) -> AttributeTable {
655        AttributeTable::new(self.attributes.clone(), &self.structs, &self.enums)
656    }
657
658    /// Does up to about `budget` units of garbage collection while the
659    /// program is idle, and answers whether no collection work is left.
660    ///
661    /// Call it between calls into the program, where the host would otherwise
662    /// wait, such as between frames. It carries on a collection already under
663    /// way, or begins one when the heap has grown enough since the last; on a
664    /// heap that has not, it does nothing and answers `true`. A unit is about
665    /// one object traced or one freed slot, never a length of time, so the
666    /// same calls do the same work on every machine. `collect(u32::MAX)` runs
667    /// a whole collection. Beginning a collection reads every root at once
668    /// whatever the budget.
669    ///
670    /// Once a host has called this, allocations leave more of the work to it
671    /// and begin a collection themselves only when the heap has grown further.
672    pub fn collect(&mut self, budget: u32) -> bool {
673        self.pools.collect(&self.registers, budget)
674    }
675
676    /// What the collector has done over this program's heap, and how large
677    /// the heap is. See [`GcStats`].
678    #[must_use]
679    pub fn gc_stats(&self) -> GcStats {
680        self.pools.gc_stats()
681    }
682
683    /// The names of every function this artifact exports, in no particular
684    /// order.
685    pub fn exports(&self) -> impl Iterator<Item = &str> {
686        self.exports.keys().map(String::as_str)
687    }
688
689    /// Runs the VM against the resident state starting at instruction `start`,
690    /// capturing any runtime error as a [`Diagnostic`].
691    fn execute_from(&mut self, start: usize) -> Result<(), Diagnostic> {
692        self.execute_raw(start).map_err(|error| {
693            error.diagnostic(&ErrorCtx {
694                instr_src: &self.instr_src,
695                sources: &self.sources,
696            })
697        })
698    }
699
700    /// Runs the VM against the resident state starting at instruction `start`.
701    fn execute_raw(&mut self, start: usize) -> Result<(), RuntimeError> {
702        let err_ctx = ErrorCtx {
703            instr_src: &self.instr_src,
704            sources: &self.sources,
705        };
706
707        // Move the register file out so the VM can borrow it mutably, then
708        // reclaim it (register state must persist across calls).
709        let mut register_file = RegisterFile(std::mem::take(&mut self.registers));
710
711        // An error comes back as a value, so a call sets up no unwind and
712        // leaves the process panic hook alone.
713        let result = vm::execute(
714            &self.instructions,
715            &mut register_file,
716            &mut self.pools,
717            &err_ctx,
718            &self.callsite_registers,
719            &self.dyn_lib_fns,
720            &self.structs,
721            &self.enums,
722            self.allocated_arg_count,
723            self.allocated_call_depth,
724            &self.host_sigs,
725            &self.host_dispatch,
726            start,
727            self.native.as_ref(),
728        );
729
730        self.registers = std::mem::take(&mut register_file.0);
731        result
732    }
733}
734
735/// Why a [`RuntimeProgram::call`] did not produce a value.
736#[derive(Debug)]
737pub enum CallError {
738    /// The artifact exports no function under this name.
739    UnknownFunction(String),
740    /// The call passed a different number of arguments than the function
741    /// declares.
742    ArgCount {
743        function: String,
744        expected: usize,
745        found: usize,
746    },
747    /// An argument does not match the parameter type it was passed for.
748    /// `index` is 1-based.
749    ArgType {
750        function: String,
751        index: usize,
752        expected: String,
753        found: String,
754    },
755    /// The call ran and raised a runtime error.
756    Runtime(Diagnostic),
757}
758
759impl From<Diagnostic> for CallError {
760    fn from(diagnostic: Diagnostic) -> Self {
761        Self::Runtime(diagnostic)
762    }
763}
764
765impl std::fmt::Display for CallError {
766    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
767        match self {
768            Self::UnknownFunction(name) => write!(
769                f,
770                "this artifact exports no function named '{name}'; only functions defined in the file it was built from, with every parameter annotated, are callable by name"
771            ),
772            Self::ArgCount {
773                function,
774                expected,
775                found,
776            } => write!(
777                f,
778                "'{function}' takes {expected} argument(s) but the call passed {found}"
779            ),
780            Self::ArgType {
781                function,
782                index,
783                expected,
784                found,
785            } => write!(
786                f,
787                "argument {index} of '{function}' is declared '{expected}' but the call passed a {found}"
788            ),
789            Self::Runtime(diagnostic) => f.write_str(&diagnostic.message),
790        }
791    }
792}
793
794impl std::error::Error for CallError {}
795
796impl RuntimeProgram {
797    /// Reconstructs a runnable program from a decoded [`ProgramImage`].
798    ///
799    /// This is where a `.cdlb`'s dynamic-library and host recipes are turned
800    /// back into live bindings: each `dylib` symbol is re-resolved through the
801    /// OS loader by logical name (never from embedded bytes), and each `host`
802    /// function is bound to the closure `hosts` registered under the same name,
803    /// with its signature checked against the recorded declaration.
804    ///
805    /// # Errors
806    ///
807    /// Returns [`LoadError`] if a referenced library cannot be opened, a symbol
808    /// cannot be resolved, or a declared `host` function is unregistered or
809    /// bound to a closure of a different shape.
810    fn from_image(img: ProgramImage, hosts: &HostRegistry) -> Result<Self, LoadError> {
811        let objs: ObjectPool = Pool(
812            img.objs
813                .into_iter()
814                .map(|v| {
815                    v.into_iter()
816                        .map(|(boxed, int)| Data::from_words(boxed, int))
817                        .collect()
818                })
819                .collect(),
820        );
821        let maps: MapPool = Pool(
822            img.maps
823                .into_iter()
824                .map(|pairs| {
825                    let mut m = CandelaMap::default();
826                    for ((k_boxed, k_int), (v_boxed, v_int)) in pairs {
827                        m.insert(
828                            Data::from_words(k_boxed, k_int),
829                            Data::from_words(v_boxed, v_int),
830                        );
831                    }
832                    m
833                })
834                .collect(),
835        );
836        let strings = StringPool::from_strings(img.strings);
837
838        let structs = structs_from_images(img.structs);
839        let enums = enums_from_images(img.enums);
840
841        // `host` functions need a host-supplied closure to dispatch to. Bind
842        // them all before anything runs, so an unbound call is impossible once
843        // the program is loaded.
844        let host_sigs: Vec<HostFnSig> = img.host_fns.iter().map(HostFnSig::from).collect();
845        let host_dispatch = hosts.bind(&host_sigs, &structs)?;
846
847        let dyn_lib_fns = resolve_dyn_lib_fns(&img.dyn_lib_fns, &structs)?;
848
849        let exports = img
850            .exports
851            .into_iter()
852            .map(|e| (e.name.clone(), Export::from(e)))
853            .collect();
854        let event_entry = img.event_entry.map(Export::from);
855
856        Ok(Self {
857            instructions: img.instructions,
858            registers: img
859                .registers
860                .into_iter()
861                .map(|(boxed, int)| Data::from_words(boxed, int))
862                .collect(),
863            pools: Pools::new(objs, maps, strings),
864            instr_src: img
865                .instr_src
866                .into_iter()
867                .map(|s| InstrSrc {
868                    instr: s.instr,
869                    span: s.span,
870                    file_id: s.file_id,
871                })
872                .collect(),
873            callsite_registers: img.callsite_registers,
874            dyn_lib_fns,
875            host_sigs,
876            host_dispatch,
877            exports,
878            event_entry,
879            structs,
880            enums,
881            sources: img
882                .sources
883                .into_iter()
884                .map(|s| Source {
885                    filename: SmolStr::from(s.filename),
886                    contents: s.contents,
887                })
888                .collect(),
889            allocated_arg_count: img.allocated_arg_count as usize,
890            allocated_call_depth: img.allocated_call_depth as usize,
891            native: None,
892            attributes: img.attributes,
893        })
894    }
895}
896
897/// The runtime struct table a `.cdlb` recorded.
898fn structs_from_images(images: Vec<StructImage>) -> Vec<Struct> {
899    images
900        .into_iter()
901        .map(|s| Struct {
902            name: SmolStr::from(s.name),
903            fields: s
904                .fields
905                .into_iter()
906                .map(|(n, t, sp)| (SmolStr::from(n), t, sp))
907                .collect::<Vec<_>>()
908                .into_boxed_slice(),
909            id: s.id,
910            name_span: s.name_span,
911        })
912        .collect()
913}
914
915/// The runtime enum table a `.cdlb` recorded.
916fn enums_from_images(images: Vec<EnumImage>) -> Vec<EnumType> {
917    images
918        .into_iter()
919        .map(|e| EnumType {
920            name: SmolStr::from(e.name),
921            variants: e
922                .variants
923                .into_iter()
924                .map(|v| EnumVariant {
925                    name: SmolStr::from(v.name),
926                    payload: v.payload.into_boxed_slice(),
927                    name_span: v.name_span,
928                })
929                .collect::<Vec<_>>()
930                .into_boxed_slice(),
931            id: e.id,
932            name_span: e.name_span,
933        })
934        .collect()
935}
936
937/// Re-opens each referenced dynamic library through the OS loader and rebuilds a
938/// live [`DynamicLibFn`] (libffi CIF + code pointer) for every recorded symbol.
939///
940/// Libraries are opened once and shared across their symbols. The logical name
941/// is mapped to this platform's filename convention via
942/// [`resolve_library_filename`], so an artifact built on one OS resolves the
943/// right file on another. The directories a host named with
944/// [`set_dylib_dirs`](crate::rt::set_dylib_dirs) are searched before the
945/// loader's own paths, which is how an application ships its libraries in a
946/// directory of its own. A recipe the standard library owns is searched for
947/// under the toolchain's `libs` directory as well, so an artifact that imports
948/// `std/math` runs from any working directory.
949#[cfg(not(target_arch = "wasm32"))]
950fn resolve_dyn_lib_fns(
951    recipes: &[DynLibFnImage],
952    structs: &[Struct],
953) -> Result<Vec<DynamicLibFn>, LoadError> {
954    use crate::rt::open_library;
955    use libloading::Library;
956    use std::rc::Rc;
957
958    // Keyed by origin as well as filename: the same relative path means one
959    // file under the toolchain's `libs` and another beside the program.
960    let mut libs: HashMap<(LibraryOrigin, String), Rc<Library>> = HashMap::default();
961    let mut out: Vec<DynamicLibFn> = Vec::with_capacity(recipes.len());
962
963    for recipe in recipes {
964        let filename = resolve_library_filename(&recipe.library, TargetOs::CURRENT);
965        let key = (recipe.origin, filename.clone());
966        let lib = if let Some(lib) = libs.get(&key) {
967            Rc::clone(lib)
968        } else {
969            let lib = Rc::new(open_library(&filename, recipe.origin).map_err(|e| {
970                LoadError::LibraryOpen {
971                    spec: recipe.library.clone(),
972                    filename: filename.clone(),
973                    message: e,
974                }
975            })?);
976            // A library that posts events gets the runtime's table before
977            // the program can call into it.
978            crate::events::init_library(&lib);
979            libs.insert(key, Rc::clone(&lib));
980            lib
981        };
982
983        let ptr = unsafe {
984            let sym = lib
985                .get::<*const ()>(recipe.symbol.as_bytes())
986                .map_err(|_| LoadError::SymbolNotFound {
987                    library: recipe.library.clone(),
988                    symbol: recipe.symbol.clone(),
989                })?;
990            libffi::middle::CodePtr(sym.try_as_raw_ptr().ok_or_else(|| {
991                LoadError::SymbolNotFound {
992                    library: recipe.library.clone(),
993                    symbol: recipe.symbol.clone(),
994                }
995            })?)
996        };
997
998        // types[0] is the return type; types[1..] are the argument types.
999        let (return_type, arg_types) = recipe.types.split_first().unwrap_or((&DataType::Null, &[]));
1000        let cif = libffi::middle::Cif::new(
1001            arg_types.iter().map(|t| t.to_c_type(structs)),
1002            return_type.to_c_type(structs),
1003        );
1004
1005        out.push(DynamicLibFn {
1006            types: recipe.types.clone().into_boxed_slice(),
1007            library: SmolStr::from(recipe.library.as_str()),
1008            origin: recipe.origin,
1009            symbol: SmolStr::from(recipe.symbol.as_str()),
1010            _lib: lib,
1011            ptr,
1012            cif,
1013        });
1014    }
1015
1016    Ok(out)
1017}
1018
1019/// On targets without the FFI backend (wasm) no library loads. A binding the
1020/// standard library owns resolves to the runtime's own function for it; any
1021/// other refuses the load rather than silently dropping the binding.
1022#[cfg(target_arch = "wasm32")]
1023fn resolve_dyn_lib_fns(
1024    recipes: &[DynLibFnImage],
1025    _structs: &[Struct],
1026) -> Result<Vec<DynamicLibFn>, LoadError> {
1027    recipes
1028        .iter()
1029        .map(|recipe| {
1030            let intrinsic = match recipe.origin {
1031                LibraryOrigin::StandardLibrary => {
1032                    crate::intrinsics::lookup(&recipe.library, &recipe.symbol)
1033                }
1034                LibraryOrigin::Program => None,
1035            };
1036            let Some(intrinsic) = intrinsic else {
1037                return Err(LoadError::LibraryOpen {
1038                    spec: recipe.library.clone(),
1039                    filename: recipe.library.clone(),
1040                    message: String::from("dynamic libraries are not supported on this target"),
1041                });
1042            };
1043            Ok(DynamicLibFn {
1044                types: recipe.types.clone().into_boxed_slice(),
1045                library: SmolStr::from(recipe.library.as_str()),
1046                origin: recipe.origin,
1047                symbol: SmolStr::from(recipe.symbol.as_str()),
1048                intrinsic,
1049            })
1050        })
1051        .collect()
1052}
1053
1054/// Why a `.cdlb` artifact could not be loaded.
1055#[derive(Debug)]
1056pub enum LoadError {
1057    /// The magic header is missing (not a `.cdlb` file).
1058    BadMagic,
1059    /// The file is shorter than the fixed header.
1060    Truncated,
1061    /// The artifact's format version is not understood by this runtime.
1062    UnsupportedVersion(u8),
1063    /// The `postcard` body failed to decode.
1064    Decode(postcard::Error),
1065    /// A referenced dynamic library could not be opened by the OS loader.
1066    LibraryOpen {
1067        /// Logical name/path as written in the source.
1068        spec: String,
1069        /// The platform filename it mapped to at load.
1070        filename: String,
1071        /// The loader's error text.
1072        message: String,
1073    },
1074    /// A symbol declared by a `dylib` block was not found in its library.
1075    SymbolNotFound { library: String, symbol: String },
1076    /// The artifact's `host` functions could not be bound to the registry the
1077    /// load was given.
1078    HostBinding(HostBindError),
1079}
1080
1081impl From<HostBindError> for LoadError {
1082    fn from(error: HostBindError) -> Self {
1083        Self::HostBinding(error)
1084    }
1085}
1086
1087impl std::fmt::Display for LoadError {
1088    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1089        match self {
1090            Self::BadMagic => write!(f, "not a candela bytecode artifact (bad magic header)"),
1091            Self::Truncated => write!(f, "truncated candela bytecode artifact"),
1092            Self::UnsupportedVersion(v) => write!(
1093                f,
1094                "unsupported .cdlb format version {v} (this runtime understands version {FORMAT_VERSION})"
1095            ),
1096            Self::Decode(e) => write!(f, "failed to decode .cdlb body: {e}"),
1097            Self::LibraryOpen {
1098                spec,
1099                filename,
1100                message,
1101            } => write!(
1102                f,
1103                "cannot open dynamic library '{spec}' (resolved to '{filename}') referenced by this artifact: {message}"
1104            ),
1105            Self::SymbolNotFound { library, symbol } => write!(
1106                f,
1107                "dynamic library '{library}' does not export the symbol '{symbol}' this artifact needs"
1108            ),
1109            Self::HostBinding(error) => write!(f, "{error}"),
1110        }
1111    }
1112}
1113
1114impl std::error::Error for LoadError {}
1115
1116/// Loads a `.cdlb` bytecode artifact into a runnable [`RuntimeProgram`].
1117///
1118/// `hosts` supplies the Rust closures the artifact's `host` blocks bind to.
1119/// Pass an empty [`HostRegistry`] for a program that declares none; a program
1120/// that declares one it does not cover fails to load, naming what is missing.
1121///
1122/// # Errors
1123///
1124/// Returns a [`LoadError`] if the magic/version header is wrong, the body fails
1125/// to decode, a dynamic library cannot be re-bound, or a `host` function cannot
1126/// be bound to the registry.
1127pub fn load_program(bytes: &[u8], hosts: &HostRegistry) -> Result<RuntimeProgram, LoadError> {
1128    if bytes.len() < 5 {
1129        return Err(LoadError::Truncated);
1130    }
1131    if bytes[0..4] != MAGIC {
1132        return Err(LoadError::BadMagic);
1133    }
1134    let version = bytes[4];
1135    if version != FORMAT_VERSION {
1136        return Err(LoadError::UnsupportedVersion(version));
1137    }
1138    // The function table follows the image, and the VM has no use for it.
1139    let (mut img, _table): (ProgramImage, &[u8]) =
1140        postcard::take_from_bytes(&bytes[5..]).map_err(LoadError::Decode)?;
1141    let sections = std::mem::take(&mut img.native);
1142    #[allow(unused_mut)]
1143    let mut program = RuntimeProgram::from_image(img, hosts)?;
1144    program.load_native(&sections);
1145    Ok(program)
1146}
1147
1148/// Serializes a [`ProgramImage`] to `.cdlb` bytes (magic + version + body),
1149/// followed by the function table when there is one.
1150///
1151/// # Errors
1152///
1153/// Returns the serialization error as a string if the `postcard` body cannot be
1154/// encoded.
1155pub fn serialize_image(
1156    image: &ProgramImage,
1157    functions: Option<&FunctionTable>,
1158) -> Result<Vec<u8>, String> {
1159    let mut bytes = Vec::new();
1160    bytes.extend_from_slice(&MAGIC);
1161    bytes.push(FORMAT_VERSION);
1162    let body = postcard::to_allocvec(image).map_err(|e| e.to_string())?;
1163    bytes.extend_from_slice(&body);
1164    if let Some(functions) = functions {
1165        let table = postcard::to_allocvec(functions).map_err(|e| e.to_string())?;
1166        bytes.extend_from_slice(&table);
1167    }
1168    Ok(bytes)
1169}
1170
1171/// Reads a `.cdlb` back into its image and the function table that follows
1172/// it, for a tool that works on the program rather than runs it. The table
1173/// is `None` for an artifact written without one.
1174///
1175/// # Errors
1176///
1177/// Returns a [`LoadError`] if the header is wrong or either part fails to
1178/// decode.
1179pub fn read_artifact(bytes: &[u8]) -> Result<(ProgramImage, Option<FunctionTable>), LoadError> {
1180    if bytes.len() < 5 {
1181        return Err(LoadError::Truncated);
1182    }
1183    if bytes[0..4] != MAGIC {
1184        return Err(LoadError::BadMagic);
1185    }
1186    if bytes[4] != FORMAT_VERSION {
1187        return Err(LoadError::UnsupportedVersion(bytes[4]));
1188    }
1189    let (image, rest): (ProgramImage, &[u8]) =
1190        postcard::take_from_bytes(&bytes[5..]).map_err(LoadError::Decode)?;
1191    if rest.is_empty() {
1192        return Ok((image, None));
1193    }
1194    let table: FunctionTable = postcard::from_bytes(rest).map_err(LoadError::Decode)?;
1195    Ok((image, Some(table)))
1196}
1197
1198/// Reads the attribute table out of a `.cdlb` without loading the program:
1199/// no library is opened and no `host` function is bound, so a build tool or
1200/// an editor lists what a program declares with nothing registered.
1201///
1202/// # Errors
1203///
1204/// Returns a [`LoadError`] if the header is wrong or the image fails to
1205/// decode.
1206pub fn read_attributes(bytes: &[u8]) -> Result<AttributeTable, LoadError> {
1207    let (image, _) = read_artifact(bytes)?;
1208    let structs = structs_from_images(image.structs);
1209    let enums = enums_from_images(image.enums);
1210    Ok(AttributeTable::new(image.attributes, &structs, &enums))
1211}