Bytecode & VM

Runtime as a contract

• VM behavior must be deterministic and fully specified
• execution = decode -> dispatch -> mutate machine state
• one mutable value store (operand stack) with explicit invariants

State model

• Global state: stack, frame stack, function set
• Frame state: ip, active instruction list, current scope chain
• ip starts at 0, then increments before each dispatch

Critical VM invariants

• ip is always in frame bounds
• stack never underflows
• CALL and JUMP never leave machine in inconsistent state
• exactly one value is returned per function frame

Scope behavior

• DEFINE_VAR: mutable current scope binding
• DEFINE_CONST: immutable current scope binding
• LOAD: search outward through scope chain
• STORE: mutate nearest mutable binding only
• ENTER_SCOPE/EXIT_SCOPE: make lifetime explicit

Stack + op order

• binary ops pop rhs first, then lhs
• lhs op rhs pushed back
• wrong pop order causes silent semantic bugs

Function call protocol

• CALL n pops args right-to-left
• open callee frame and bind params
• explicit RETURN sends one value
• missing return = implicit nil

Branching semantics

• JUMP is absolute
• JUMP_IF_FALSE pops one value; jumps if value is false or nil
• everything else is truthy

Error classes to teach clearly

• undefined name
• const reassignment
• bad arity / bad callee
• arithmetic/type mismatch
• division by zero
• invalid jump target
• stack underflow

Debug friendliness

• optional trace mode: ip + opcode + stack depth + scope depth
• trace should not mutate execution behavior

Why this matters for compilers

• VM is the last executor: bugs here invalidate all earlier stages
• fixed runtime contract makes later optimizations and serialization safe

Extension path

• bytecode persistence format
• compiler validation/lint mode
• register-based execution backend
• deterministic VM golden tests