herkos_runtime/
lib.rs

1//! `herkos-runtime` — Runtime library for herkos transpiled output.
2//!
3//! This crate is `#![no_std]` by default. It provides:
4//! - `IsolatedMemory<const MAX_PAGES: usize>` for Wasm linear memory
5//! - `WasmTrap` / `WasmResult<T>` for Wasm trap handling
6//! - Trait definitions for capability-based host imports (Phase 3+)
7
8#![no_std]
9
10#[cfg(feature = "alloc")]
11extern crate alloc;
12
13/// WebAssembly page size: 64 KiB per the Wasm specification.
14pub const PAGE_SIZE: usize = 65536;
15
16mod memory;
17pub use memory::IsolatedMemory;
18
19mod table;
20pub use table::{FuncRef, Table};
21
22mod module;
23pub use module::{LibraryModule, Module};
24
25mod ops;
26pub use ops::{
27    i32_div_s, i32_div_u, i32_rem_s, i32_rem_u, i32_trunc_f32_s, i32_trunc_f32_u, i32_trunc_f64_s,
28    i32_trunc_f64_u, i64_div_s, i64_div_u, i64_rem_s, i64_rem_u, i64_trunc_f32_s, i64_trunc_f32_u,
29    i64_trunc_f64_s, i64_trunc_f64_u,
30};
31
32/// Wasm execution errors — no panics, no unwinding.
33#[derive(Debug, Clone, Copy, PartialEq, Eq)]
34pub enum WasmTrap {
35    /// Memory access out of bounds.
36    OutOfBounds,
37    /// Integer division by zero.
38    DivisionByZero,
39    /// Integer overflow (e.g., `i32.trunc_f64_s` on out-of-range float).
40    IntegerOverflow,
41    /// Unreachable instruction executed.
42    Unreachable,
43    /// Indirect call type mismatch (`call_indirect` signature check).
44    IndirectCallTypeMismatch,
45    /// Table access out of bounds.
46    TableOutOfBounds,
47    /// Undefined element in table.
48    UndefinedElement,
49}
50
51/// Result type for Wasm operations — `Result<T, WasmTrap>`.
52pub type WasmResult<T> = Result<T, WasmTrap>;
53
54/// Errors that occur during module/memory/table construction.
55///
56/// These are programming errors in the transpiler, not runtime Wasm traps.
57#[derive(Debug, Clone, Copy, PartialEq, Eq)]
58pub enum ConstructionError {
59    /// Initial pages exceeds MAX_PAGES for memory.
60    MemoryInitialPagesExceedsMax { initial: usize, max: usize },
61    /// Initial size exceeds MAX_SIZE for table.
62    TableInitialSizeExceedsMax { initial: usize, max: usize },
63}
64
65impl From<ConstructionError> for WasmTrap {
66    fn from(_: ConstructionError) -> Self {
67        // Construction errors are programming errors, but we map them to
68        // OutOfBounds for compatibility with the error propagation chain.
69        WasmTrap::OutOfBounds
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76
77    #[test]
78    fn wasm_trap_is_copy() {
79        let trap = WasmTrap::OutOfBounds;
80        let trap2 = trap; // Copy
81        assert_eq!(trap, trap2);
82    }
83
84    #[test]
85    fn wasm_result_ok() {
86        let result: WasmResult<i32> = Ok(42);
87        assert!(result.is_ok());
88        assert_eq!(result, Ok(42));
89    }
90
91    #[test]
92    fn wasm_result_err() {
93        let result: WasmResult<i32> = Err(WasmTrap::DivisionByZero);
94        assert!(result.is_err());
95        assert_eq!(result, Err(WasmTrap::DivisionByZero));
96    }
97}
herkos_runtime/lib.rs

herkos_runtime/
lib.rs
