Struct Module 

pub struct Module {
    pub chunks: Vec<Chunk>,
    pub native_names: Vec<String>,
    pub entry_point: Option<usize>,
    pub data_layout: Option<DataLayout>,
    pub word_bits_log2: u8,
    pub addr_bits_log2: u8,
    pub float_bits_log2: u8,
    pub wcet_cycles: u32,
    pub wcmu_bytes: u32,
}

A compiled Keleusma module.

Fields

chunks: Vec<Chunk>

Compiled function chunks.

native_names: Vec<String>

Declared native function names (from use declarations).

entry_point: Option<usize>

Entry point chunk index (the main function).

data_layout: Option<DataLayout>

Data segment layout. If present, defines persistent slots that survive across RESET boundaries.

word_bits_log2: u8

Word size required by this bytecode, encoded as the base-2 exponent. Actual width in bits is 1 << word_bits_log2. The runtime accepts the bytecode when the recorded value is at most the runtime’s RUNTIME_WORD_BITS_LOG2. The VM masks integer arithmetic to the declared width using sign-extending shift. Mirrored in the framing header for fast pre-decode rejection.

addr_bits_log2: u8

Address size required by this bytecode, encoded as the base-2 exponent. Actual width in bits is 1 << addr_bits_log2. The runtime accepts the bytecode when the recorded value is at most the runtime’s RUNTIME_ADDRESS_BITS_LOG2. Mirrored in the framing header for fast pre-decode rejection.

float_bits_log2: u8

Floating-point width required by this bytecode, encoded as the base-2 exponent. Actual width in bits is 1 << float_bits_log2. The runtime accepts the bytecode when the recorded value is at most the runtime’s RUNTIME_FLOAT_BITS_LOG2. The current runtime uses f64 exclusively (exponent 6); narrower or wider floats are reserved for future portability work tracked under B10. Mirrored in the framing header for fast pre-decode rejection.

wcet_cycles: u32

Declared worst-case execution time per Stream-to-Reset slice, in pipelined cycles. Producer’s claim about the maximum cycles the script consumes between two yield boundaries.

• 0 means auto: the producer did not declare a value; the runtime computes the bound at load time through its own verifier pass.
• u32::MAX means overflow: the producer attempted to compute the bound but the result exceeds the field’s range. Programs declaring u32::MAX are rejected at the safe constructor Vm::new because no representable bound exists.
• Any other value is the producer’s bound. The safe runtime accepts the value as-is; trust skip applies to declared values just as it does to arena capacity.

Mirrored in the framing header for inspection without body decode.

wcmu_bytes: u32

Declared worst-case memory usage per Stream-to-Reset slice, in bytes. Same 0/u32::MAX conventions as Module::wcet_cycles. Total of stack and heap regions. Mirrored in the framing header.

Implementations

impl Module

pub fn to_bytes(&self) -> Result<Vec<u8>, LoadError>

Serialize the module to a self-describing byte vector.

The output begins with the twelve-byte header (magic, version, total length, word size, address size), then the module body in postcard wire format, then a four-byte little-endian CRC-32 trailer. The CRC covers the entire framed range. The algebraic self-inclusion residue of the CRC parameterization makes the trailer part of the checksummed range.

All multi-byte integer fields in the framing are stored in little-endian order. Postcard stores its own multi-byte values in little-endian or as varints. The wire format is therefore identical bytes regardless of producer or consumer host endianness.

Returns LoadError::Codec if postcard rejects any field. The Module type is composed entirely of types that postcard supports, so encode failures are not expected in practice and indicate corruption of the runtime data.

Examples found in repository

examples/regenerate_zero_copy_bytecode.rs (line 34)

fn main() {
    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    let source_path = manifest_dir.join("examples").join("zero_copy_demo.kel");
    let binary_path = manifest_dir.join("examples").join("zero_copy_demo.kel.bin");

    let source = fs::read_to_string(&source_path).expect("read source");
    let tokens = tokenize(&source).expect("lex");
    let program = parse(&tokens).expect("parse");
    let module = compile(&program).expect("compile");
    let bytes = module.to_bytes().expect("encode");

    fs::write(&binary_path, &bytes).expect("write binary");
    println!("wrote {} ({} bytes)", binary_path.display(), bytes.len());
}

pub fn from_bytes(bytes: &[u8]) -> Result<Self, LoadError>

Deserialize a module from a self-describing byte slice.

Validation order is truncation, magic, length, CRC residue, version, word size, address size, and body decode. The slice is truncated to the recorded length before the CRC check so that bytecode embedded in a larger buffer is supported. Trailing bytes after the recorded length are ignored.

The CRC is checked before the version, word size, and address size because a corrupted byte in any of those fields would otherwise be reported as a mismatch rather than the more accurate BadChecksum.

Does not run structural verification or resource bounds checks. Pass the result to crate::vm::Vm::new for full verification or to crate::vm::Vm::new_unchecked for trust-based skipping of the bounds checks.

pub fn access_bytes(bytes: &[u8]) -> Result<&ArchivedModule, LoadError>

Validate framing and return a borrowed archived view of the module.

Performs the same framing checks as Module::from_bytes (magic, length, CRC residue, version, word size, address size) and then runs rkyv::access on the body to obtain a &'a ArchivedModule without deserialization.

The body must be 8-byte aligned within the slice. Because the header is sixteen bytes, the body is 8-byte aligned within the slice when the slice base itself is 8-byte aligned. Hosts that compute or load bytecode into an rkyv::util::AlignedVec or a static buffer with #[repr(align(8))] satisfy this requirement. Bytecode placed by the linker into a section that aligns to at least 8 bytes also satisfies it.

Returns LoadError::Codec with an alignment message when the body is not aligned, or when the rkyv structural validator rejects the body. Returns the other LoadError variants for header validation failures.

pub fn view_bytes(bytes: &[u8]) -> Result<Module, LoadError>

Deserialize a module from an aligned byte slice without the AlignedVec copy step that Module::from_bytes performs.

Validates the framing through Module::access_bytes and then calls rkyv::deserialize on the validated archived form. Returns an owned Module for compatibility with the existing execution path. The wire-format validation runs in place against the input slice. The deserialization step still allocates the owned form.

True zero-copy execution against &ArchivedModule is recorded as the next iteration of P10. Path B requires lifetime-parameterizing the Vm and rewriting the execution loop to read from &ArchivedModule. The current view path delivers in-place validation and is the architectural foundation for Phase 2.

Requires the body to be 8-byte aligned. See Module::access_bytes for the alignment contract.

Trait Implementations

impl Archive for Module

where Vec<Chunk>: Archive, Vec<String>: Archive, Option<usize>: Archive, Option<DataLayout>: Archive, u8: Archive, u32: Archive,

const COPY_OPTIMIZATION: CopyOptimization<Self>

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

type Archived = ArchivedModule

The archived representation of this type.

type Resolver = ModuleResolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Creates the archived version of this value at the given position and writes it to the given output.

impl Clone for Module

fn clone(&self) -> Module

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Module

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<__D: Fallible + ?Sized> Deserialize<Module, __D> for Archived<Module>

where Vec<Chunk>: Archive, <Vec<Chunk> as Archive>::Archived: Deserialize<Vec<Chunk>, __D>, Vec<String>: Archive, <Vec<String> as Archive>::Archived: Deserialize<Vec<String>, __D>, Option<usize>: Archive, <Option<usize> as Archive>::Archived: Deserialize<Option<usize>, __D>, Option<DataLayout>: Archive, <Option<DataLayout> as Archive>::Archived: Deserialize<Option<DataLayout>, __D>, u8: Archive, <u8 as Archive>::Archived: Deserialize<u8, __D>, u32: Archive, <u32 as Archive>::Archived: Deserialize<u32, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<Module, <__D as Fallible>::Error>

Deserializes using the given deserializer

impl<__S: Fallible + ?Sized> Serialize<__S> for Module

where Vec<Chunk>: Serialize<__S>, Vec<String>: Serialize<__S>, Option<usize>: Serialize<__S>, Option<DataLayout>: Serialize<__S>, u8: Serialize<__S>, u32: Serialize<__S>,

fn serialize( &self, serializer: &mut __S, ) -> Result<<Self as Archive>::Resolver, <__S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.