byteflow/vm/
fault.rs

1use std::fmt;
2
3/// Anything that can go wrong *inside* a running Flow's VM.
4///
5/// A `Fault` is never a Rust panic — panics are reserved for genuine host
6/// bugs and are caught at the worker boundary (see
7/// `byteflow-scheduler::worker::run_worker`) precisely so that one Flow's
8/// bug (division by zero, a corrupt jump target that slipped past the
9/// verifier, an out-of-range register) can never take down a worker thread,
10/// let alone the whole runtime. A `Fault` instead becomes
11/// `FlowState::Failed` and is handed to the Flow's supervisor, which
12/// decides whether to restart it (design notes §15-16).
13#[derive(Clone, Debug, PartialEq)]
14pub enum Fault {
15    DivideByZero,
16    RegisterOutOfRange { reg: u8, frame_size: u8 },
17    BadConstant { index: u32, pool_size: u32 },
18    BadFunction { index: u32, table_size: u32 },
19    BadOpcodeByte(u8),
20    /// Function call nesting exceeded `Vm::MAX_CALL_DEPTH`. Bytecode has no
21    /// native stack overflow (frames are heap-allocated `Vec<Value>`s), so
22    /// this is a deliberate, checked limit rather than a segfault.
23    CallStackOverflow { depth: usize },
24    TypeMismatch { expected: &'static str, got: &'static str },
25    /// `CallNative` referenced a slot outside the runtime's registered
26    /// native function table (design notes §30-31). Distinct from
27    /// `BadFunction`, which is about the *bytecode* function table baked
28    /// into the chunk — natives are supplied by the embedder at `Vm`
29    /// construction time and can't be range-checked by
30    /// `crate::bytecode::verify`, which has no visibility into them.
31    BadNative { index: u32, table_size: u32 },
32    /// A native function returned an error (host-side failure — I/O,
33    /// invalid argument the Rust side rejected, capability denied, etc).
34    /// The message is native-function-defined.
35    NativeError(String),
36    /// Explicit `Trap` opcode, e.g. an assertion emitted by a compiler.
37    Explicit(i32),
38    /// Broken VM invariant (e.g. empty frame stack while running). Category D
39    /// in the error model — surfaced as a Flow fault, never as `unwrap`.
40    Invariant(&'static str),
41}
42
43impl fmt::Display for Fault {
44    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
45        match self {
46            Fault::DivideByZero => write!(f, "division by zero"),
47            Fault::RegisterOutOfRange { reg, frame_size } => {
48                write!(f, "register r{reg} out of range (frame has {frame_size} registers)")
49            }
50            Fault::BadConstant { index, pool_size } => {
51                write!(f, "constant index {index} out of range (pool size {pool_size})")
52            }
53            Fault::BadFunction { index, table_size } => {
54                write!(f, "function index {index} out of range (table size {table_size})")
55            }
56            Fault::BadOpcodeByte(b) => write!(f, "unknown opcode byte 0x{b:02X}"),
57            Fault::CallStackOverflow { depth } => write!(f, "call stack overflow at depth {depth}"),
58            Fault::TypeMismatch { expected, got } => {
59                write!(f, "type mismatch: expected {expected}, got {got}")
60            }
61            Fault::BadNative { index, table_size } => {
62                write!(f, "native function index {index} out of range (table size {table_size})")
63            }
64            Fault::NativeError(msg) => write!(f, "native function error: {msg}"),
65            Fault::Explicit(code) => write!(f, "explicit trap (code {code})"),
66            Fault::Invariant(msg) => write!(f, "vm invariant broken: {msg}"),
67        }
68    }
69}
70
71impl std::error::Error for Fault {}
byteflow/vm/fault.rs

byteflow/vm/
fault.rs
