VM & Bytecode

Register-based virtual machine, opcodes, and binary format.

The Achronyme VM is a register-based bytecode interpreter. It executes compiled .achb files using a fixed-size stack of 65,536 Value slots.

Architecture

Source (.ach)
    │
    ▼
Bytecode Compiler → Function prototypes + bytecode
    │
    ▼
Serializer → .achb binary file
    │
    ▼
Loader → VM heap + stack + frames
    │
    ▼
Interpreter → Register-based execution

VM Structure

VM {
    heap: Heap,              // typed arenas + GC
    stack: [Value; 65536],   // fixed-size register stack
    frames: Vec<CallFrame>,  // call stack
    globals: Vec<GlobalEntry>,  // global variables
    natives: Vec<NativeObj>,    // 43 built-in functions
    open_upvalues: linked list, // captured stack variables
    stress_mode: bool,          // force GC every cycle
}

Call Frames

Each function call pushes a CallFrame:

CallFrame {
    closure: u32,   // handle to Closure on heap
    ip: usize,      // instruction pointer
    base: usize,    // base offset in stack
    dest_reg: usize, // where to store return value
}

Register R[i] in the current frame maps to stack[frame.base + i].

Value Representation

Values are tagged 64-bit integers — no boxing for common types:

Bits 63..60 = 4-bit tag
Bits 59..0  = 60-bit payload

Tags

Integers (tag 0) are the most common value type — using tag 0 means no masking is needed for the common case.

Integer range: -2^59 to 2^59 - 1 (576,460,752,303,423,487). Overflow raises IntegerOverflow.

Instruction Encoding

Each instruction is a u32 in one of two formats:

ABC Format

[opcode:8][A:8][B:8][C:8]

Used for 3-operand instructions like Add R[A] = R[B] + R[C].

ABx Format

[opcode:8][A:8][Bx:16]

Used for instructions with a 16-bit operand, like LoadConst R[A] = K[Bx] or Jump IP = Bx.

Opcodes

Constants & Moves

Arithmetic

Comparison & Logic

Closures & Upvalues

Functions

Control Flow

Globals

Data Structures

ZK

Special

Function Objects

Each compiled function produces a Function struct on the heap:

Function {
    name: String,        // for debugging
    arity: u8,           // parameter count
    max_slots: u16,      // peak register usage
    chunk: Vec<u32>,     // bytecode instructions
    constants: Vec<Value>, // constant pool
    upvalue_info: Vec<u8>, // [is_local, index] pairs
    line_info: Vec<u32>, // line number per instruction
}

The line_info vector is parallel to chunk — each instruction has a source line number for error reporting.

Binary Format (.achb)

The .achb file format (version 9):

Magic:    b"ACH\x09"          (4 bytes)
Metadata: max_slots (u16 LE)

Global Strings:
    count (u32 LE)
    for each: length (u32 LE) + UTF-8 bytes

Global Constants:
    count (u32 LE)
    for each: tag (u8) + payload
        INT (0):    i64 LE
        STRING (1): u32 LE handle
        FIELD (8):  4 × u64 LE (Montgomery limbs)
        NIL (255):  (no payload)

Prototypes:
    count (u32 LE)
    for each:
        name_len (u32 LE) + name bytes
        arity (u8)
        max_slots (u16 LE)
        const_count (u32 LE) + constants
        upvalue_count (u32 LE) + upvalue info
        bytecode_len (u32 LE) + instructions (u32 LE each)

Main Bytecode:
    instruction_count (u32 LE)
    instructions (u32 LE each)

The format is compatible with the VM’s loader module, which deserializes into heap objects.

Global Variable Layout

Index:  0..22       23..
        Natives     User globals

The first 23 slots (0–22) are reserved for native functions. User-defined globals start at index 23 (USER_GLOBAL_START).

Source Files