VM y Bytecode

La VM de Achronyme es un intérprete de bytecode basado en registros. Ejecuta archivos .achb compilados usando una pila de tamaño fijo de 65,536 slots de Value.

Arquitectura

Fuente (.ach)
    │
    ▼
Compilador de Bytecode → Prototipos de función + bytecode
    │
    ▼
Serializador → archivo binario .achb
    │
    ▼
Cargador → heap + pila + frames de la VM
    │
    ▼
Intérprete → Ejecución basada en registros

Estructura de la VM

VM {
    heap: Heap,              // arenas tipadas + GC
    stack: [Value; 65536],   // pila de registros de tamaño fijo
    frames: Vec<CallFrame>,  // pila de llamadas
    globals: Vec<GlobalEntry>,  // variables globales
    natives: Vec<NativeObj>,    // 23 funciones integradas
    open_upvalues: lista enlazada, // variables de pila capturadas
    stress_mode: bool,          // forzar GC en cada ciclo
}

Frames de Llamada

Cada llamada a función apila un CallFrame:

CallFrame {
    closure: u32,   // handle a Closure en el heap
    ip: usize,      // puntero de instrucción
    base: usize,    // offset base en la pila
    dest_reg: usize, // dónde almacenar valor de retorno
}

El registro R[i] en el frame actual mapea a stack[frame.base + i].

Representación de Valores

Los valores son enteros de 64 bits etiquetados — sin boxing para tipos comunes:

Bits 63..60 = etiqueta de 4 bits
Bits 59..0  = payload de 60 bits

Etiquetas

Etiqueta	Nombre	Payload
0	INT	entero con signo i60 (en línea)
1	NIL	—
2	FALSE	—
3	TRUE	—
4	STRING	handle u32 → arena de strings
5	LIST	handle u32 → arena de listas
6	MAP	handle u32 → arena de mapas
7	FUNCTION	handle u32 → arena de funciones
8	FIELD	handle u32 → arena de campos (BN254)
9	PROOF	handle u32 → arena de pruebas
10	NATIVE	handle u32 → tabla de nativos
11	CLOSURE	handle u32 → arena de closures
12	ITER	handle u32 → arena de iteradores

Los enteros (etiqueta 0) son el tipo de valor más común — usar la etiqueta 0 significa que no se necesita enmascaramiento para el caso común.

Rango de enteros: -2^59 a 2^59 - 1 (576,460,752,303,423,487). El desbordamiento genera IntegerOverflow.

Codificación de Instrucciones

Cada instrucción es un u32 en uno de dos formatos:

Formato ABC

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

Usado para instrucciones de 3 operandos como Add R[A] = R[B] + R[C].

Formato ABx

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

Usado para instrucciones con un operando de 16 bits, como LoadConst R[A] = K[Bx] o Jump IP = Bx.

Opcodes

Constantes y Movimientos

Opcode	Código	Formato	Descripción
LoadConst	0	ABx	R[A] = K[Bx] — cargar del pool de constantes
LoadTrue	1	A	R[A] = true
LoadFalse	2	A	R[A] = false
LoadNil	3	A	R[A] = nil
Move	5	AB	R[A] = R[B]

Aritmética

Opcode	Código	Formato	Descripción
Add	10	ABC	R[A] = R[B] + R[C]
Sub	11	ABC	R[A] = R[B] - R[C]
Mul	12	ABC	R[A] = R[B] * R[C]
Div	13	ABC	R[A] = R[B] / R[C]
Mod	14	ABC	R[A] = R[B] % R[C]
Pow	15	ABC	R[A] = R[B] ^ R[C]
Neg	16	AB	R[A] = -R[B]

Comparación y Lógica

Opcode	Código	Formato	Descripción
Eq	20	ABC	R[A] = R[B] == R[C]
Lt	21	ABC	R[A] = R[B] < R[C]
Gt	22	ABC	R[A] = R[B] > R[C]
NotEq	23	ABC	R[A] = R[B] != R[C]
Le	24	ABC	R[A] = R[B] <= R[C]
Ge	25	ABC	R[A] = R[B] >= R[C]
LogNot	26	AB	R[A] = !R[B]

Closures y Upvalues

Opcode	Código	Formato	Descripción
GetUpvalue	34	AB	R[A] = Upvalue[B]
SetUpvalue	35	AB	Upvalue[B] = R[A]
CloseUpvalue	36	A	Cerrar upvalue en slot de pila A

Funciones

Opcode	Código	Formato	Descripción
Return	54	A	Retornar R[A] del frame actual
Call	55	ABC	R[A] = Call(R[B], R[B+1]..R[B+C-1])
Closure	56	ABx	R[A] = Closure(K[Bx])

Flujo de Control

Opcode	Código	Formato	Descripción
Jump	60	Bx	IP = Bx
JumpIfFalse	61	ABx	Si !R[A] entonces IP = Bx
GetIter	65	AB	R[A] = Iterator(R[B])
ForIter	66	ABx	Siguiente elemento o saltar a Bx

Globales

Opcode	Código	Formato	Descripción
DefGlobalVar	98	ABx	Definir global mutable
DefGlobalLet	99	ABx	Definir global inmutable
GetGlobal	100	ABx	R[A] = Global[K[Bx]]
SetGlobal	101	ABx	Global[K[Bx]] = R[A]
Print	102	A	Imprimir R[A]

Estructuras de Datos

Opcode	Código	Formato	Descripción
BuildList	150	ABC	R[A] = [R[B]..R[B+C-1]]
BuildMap	151	ABC	R[A] = {R[B]:R[B+1], ...}
GetIndex	152	ABC	R[A] = R[B][R[C]]
SetIndex	153	ABC	R[A][R[B]] = R[C]

ZK

Opcode	Código	Formato	Descripción
Prove	160	—	Compilar + verificar circuito ZK

Especiales

Opcode	Código	Descripción
Nop	255	Sin operación

Objetos de Función

Cada función compilada produce un struct Function en el heap:

Function {
    name: String,        // para depuración
    arity: u8,           // conteo de parámetros
    max_slots: u16,      // uso pico de registros
    chunk: Vec<u32>,     // instrucciones de bytecode
    constants: Vec<Value>, // pool de constantes
    upvalue_info: Vec<u8>, // pares [is_local, index]
    line_info: Vec<u32>, // número de línea por instrucción
}

El vector line_info es paralelo a chunk — cada instrucción tiene un número de línea fuente para reporte de errores.

Formato Binario (.achb)

El formato de archivo .achb (versión 9):

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

Global Strings:
    count (u32 LE)
    por cada uno: length (u32 LE) + bytes UTF-8

Global Constants:
    count (u32 LE)
    por cada uno: tag (u8) + payload
        INT (0):    i64 LE
        STRING (1): handle u32 LE
        FIELD (8):  4 × u64 LE (limbs Montgomery)
        NIL (255):  (sin payload)

Prototypes:
    count (u32 LE)
    por cada uno:
        name_len (u32 LE) + bytes del nombre
        arity (u8)
        max_slots (u16 LE)
        const_count (u32 LE) + constantes
        upvalue_count (u32 LE) + info de upvalue
        bytecode_len (u32 LE) + instrucciones (u32 LE cada una)

Main Bytecode:
    instruction_count (u32 LE)
    instrucciones (u32 LE cada una)

El formato es compatible con el módulo loader de la VM, que deserializa en objetos del heap.

Disposición de Variables Globales

Índice: 0..22       23..
        Nativos     Globales de usuario

Los primeros 23 slots (0–22) están reservados para funciones nativas. Las globales definidas por el usuario comienzan en el índice 23 (USER_GLOBAL_START).

Archivos Fuente

Componente	Archivo
Opcodes	vm/src/opcode.rs
Intérprete VM	vm/src/machine/vm.rs
Frames de llamada	vm/src/machine/frame.rs
Despacho de nativos	vm/src/specs.rs
Codificación de valores	memory/src/value.rs
Struct Function	memory/src/heap.rs
Compilador de bytecode	compiler/src/codegen.rs
Compilador de funciones	compiler/src/function_compiler.rs
Serializador binario	cli/src/commands/compile.rs
Cargador binario	vm/src/loader.rs