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,
    pub aux_arena_bytes: u32,
    pub persistent_composite_bytes: u32,
    pub flags: u8,
    pub shared_data_bytes: u32,
    pub private_data_bytes: u32,
    pub schema_hash: u32,
    pub enum_layouts: Vec<EnumLayout>,
    pub signatures: Vec<ChunkSignature>,
    pub native_return_shapes: Vec<WireShape>,
}

A compiled Keleusma module.

V0.2.0 Phase 7c cut the on-the-wire serialization over to the section-partitioned wire format defined in crate::wire_format; the rkyv archive of the full Module is no longer produced or consumed. Module is the in-memory representation; serialization flows through Module::to_bytes -> module_to_wire_bytes and deserialization through module_from_wire_bytes -> Module. The Phase 8 publication readiness pass drops the rkyv derives.

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.

aux_arena_bytes: u32

Worst-case bytes the runtime needs for its own ephemeral tracking structures per Stream-to-Reset slice, beyond the script-value WCMU (B28 P3 item 5, Phase C).

These are the runtime’s per-instance bookkeeping lists — the opaque registry, and (as the relocation lands) the backing of boxed composite bodies — which the runtime allocates inside the arena (the top ephemeral region) and pre-sizes once, as the first allocations after each RESET, rather than growing during an iteration. The runtime reads this value to pre-size those lists, and auto_arena_capacity_for adds it to the arena size. It is a runtime-only figure: native code never observes it, and it is distinct from the native-WCMU attestation path. 0 means the module needs no such tracking memory. Carried in the framing header’s reserved word at offset 56.

persistent_composite_bytes: u32

Total bytes of persistent flat-composite body storage the private .data slots require in the arena’s persistent region (B28 P3 item 5, item 3a). A private data slot holding a flat composite (struct, tuple, enum, or an array element thereof) stores its body in this persistent pool so it survives RESET in place, rather than on the global heap. The value is the sum over private composite slots of each slot’s flat body size; 0 means no private slot holds a flat composite. The host adds this to the arena’s persistent capacity (required_persistent_capacity_for accounts for it). Carried in the framing header’s formerly-reserved word at offset 60; a 0 value leaves the header bytes identical to the prior reserved zero-fill, so existing bytecode without private composite slots is byte-unchanged.

flags: u8

Bit flags describing static properties of the module. Currently defined bits.

• 0x01 (FLAG_EPHEMERAL). The module is provably ephemeral: at every yield or return that crosses the host-VM boundary, no arena-resident value is observed, and at every resume or entry no value loaded from arena memory allocated prior to that resume or entry is read. Hosts that observe this bit may reuse a single arena across many modules of this kind, sized to the largest module’s WCMU.

Unused bits are reserved for future declarations and must be zero. The runtime treats any unrecognised bits as reserved and ignores them.

Mirrored in the framing header.

shared_data_bytes: u32

Flat byte length of this module’s shared data. Shared data is the host-owned buffer borrowed at each call, sized to this value and read or written through Vm::get_shared/Vm::set_shared (B28 item 2). Survives RESET in the host’s buffer. Mirrored in the framing header.

private_data_bytes: u32

Bytes of private data declared by this module. Private data lives in the arena’s persistent (.data) region and is not exposed through the host API. Survives RESET. The host sizes its arena’s persistent capacity to match this value before loading the module. Mirrored in the framing header.

schema_hash: u32

CRC-32 hash of the data-segment layout. Used by crate::vm::Vm::replace_module to reject hot swaps against incompatible schemas before any data is loaded. Computed from a canonical serialisation of each slot’s name and visibility in declaration order; see compute_schema_hash for the exact byte sequence. A module with no data layout reports zero. The check is strict by default; hosts that need to swap across incompatible schemas (different data declaration, same arena capacity) call crate::vm::Vm::replace_module_unchecked to bypass it.

enum_layouts: Vec<EnumLayout>

Per-enum-type layout descriptors (B37 / audit finding 25 follow-up). Lets the VM make an enum’s flat body type-driven: when flattening a boxed enum returned by an unsignatured native, it looks up the variant’s true discriminant and the padded-body size here rather than trusting the arena-less constructor’s hints. Empty for a module that declares no enums. See EnumLayout.

signatures: Vec<ChunkSignature>

Per-chunk signature descriptors for the typed operand-stack verifier pass (A.2.1 Phase 2b), parallel to Module::chunks by index. Seeds each chunk’s parameters, resume, and return, and lets a Call seed its result and check its arguments against the callee. Empty (or shorter than chunks) reproduces the unseeded behaviour: a chunk without an entry is checked with an all-Top signature. See ChunkSignature.

native_return_shapes: Vec<WireShape>

Return-value flat shape of each declared native, parallel to Module::native_names by index, so the typed verifier pass can seed a CallVerifiedNative/CallExternalNative result (A.2.1 native-result seeding). A native declared without a use ... -> R signature, or one whose return type does not resolve, records WireShape::Top and defers. Empty (or shorter than native_names) reproduces the unseeded behaviour.

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.

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<&ArchivedWireAuxBody, 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 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.