Module artifact 

Bytecode artifact format (.cdlb) and the VM-only load/run API.

This mirrors an AOT model: the full candela toolchain (compiler + VM) compiles a .cdl source to a compact, self-contained bytecode artifact (ProgramImage serialized via serialize_image), and the VM-only candela-vm binary loads it (load_program) and runs it (RuntimeProgram::run) WITHOUT the parser, compiler, or REPL.

An embedding host gets the same two halves the Engine/Program pair gives it, minus the compiler: it supplies a HostRegistry at load so the artifact’s host functions bind to Rust closures, and it invokes script functions by name through RuntimeProgram::call, which runs a trampoline the compiler emitted at build time.

The on-disk format is: a 4-byte magic (CDLB), a 1-byte format version, then a postcard-encoded ProgramImage. postcard was chosen over bincode because it is no_std/alloc-friendly and its varint encoding keeps the artifact small; it also pulls in the least code, which matters for the candela-vm binary-size budget.

ProgramImage carries pub fields so the candela crate’s build subcommand can populate it from a fresh compile; everything needed to LOAD and RUN it lives here.

Structs

DefImage

The type of one value an instruction writes.

DynLibFnImage

Serializable recipe for one dynamic-library binding: enough to re-open the library and re-resolve the symbol by name at load, with no embedded bytes.

EnumImage

EnumVariantImage

ExportImage

One host-callable function, with the call trampoline candela build compiled for it.

FunctionImage

One compiled function in a FunctionTable: main, or one specialisation of a declared function or closure.

FunctionTable

What the compiler knows about each function of a program, written after the ProgramImage in a .cdlb.

HostFnImage

Serializable recipe for one host function: its fully-qualified name and marshalling signature, so an embedding runtime can re-bind it by name.

InstrSrcImage

NativeFunctionImage

One function in a NativeImage.

NativeImage

Machine code candela build generated for one kind of machine, and what the VM needs to know to run it.

NativeSiteImage

A call instruction the VM points at a native function once it loads.

ProgramImage

Serializable mirror of a compiled program’s runtime state.

RuntimeProgram

A loaded, ready-to-run program image with owned runtime state.

SourceImage

StructImage

Enums

CallError

Why a RuntimeProgram::call did not produce a value.

LoadError

Why a .cdlb artifact could not be loaded.

NativeArch

An architecture machine code is built for.

NativeOs

An operating system whose calling convention machine code follows.

Functions

load_program

Loads a .cdlb bytecode artifact into a runnable RuntimeProgram.

read_artifact

Reads a .cdlb back into its image and the function table that follows it, for a tool that works on the program rather than runs it. The table is None for an artifact written without one.

serialize_image

Serializes a ProgramImage to .cdlb bytes (magic + version + body), followed by the function table when there is one.

Type Aliases

DataWords

The pair of words a value is recorded as. See Data::into_words.