Document VM Architecture and Opcodes

[mseminatore]

Issue: Document VM Architecture and Opcodes

Priority

🟡 Medium

Description

The VM implementation lacks documentation for:

• Bytecode format and encoding
• Opcode semantics and stack effects
• GC algorithm details (mark-sweep phases)
• Object representation and tagging scheme
• Memory layout of heap objects

This makes it difficult to:

• Understand code generation from parser
• Debug bytecode execution issues
• Extend with new opcodes
• Verify GC correctness

Proposed Implementation

1. Add comprehensive vm.h header comments:

   /**
    * VM Architecture
    * ===============
    * Stack-based bytecode VM with mark-sweep garbage collection.
    * 
    * Object Representation:
    * - Small integers: tagged pointers (bottom 2 bits = 01)
    * - Booleans: tagged pointers (bottom 2 bits = 10)
    * - Heap objects: aligned pointers (bottom 2 bits = 00)
    * 
    * Stack Layout:
    * - Fixed size VM_STACK_SIZE (1024 elements)
    * - Grows upward from stack[0]
    * - sp points to next free slot
    */

2. Document each opcode with stack effects:

   enum {
       OP_HALT,        // [] -> [] - Stop execution
       OP_PUSH,        // [] -> [obj] - Push next code word as object
       OP_POP,         // [obj] -> [] - Discard top of stack
       OP_NUM,         // [] -> [num] - Push next word as tagged number
       OP_CALL,        // [proc arg1 ... argN] -> [result] - Call function
       // ... etc
   };

3. Document GC algorithm in vm.c:

   /**
    * Garbage Collection: Mark and Sweep
    * ===================================
    * 
    * Mark Phase:
    * 1. Mark all objects reachable from roots:
    *    - VM stack entries
    *    - Global variable table
    *    - Current code chunk
    * 2. Use gray stack for iterative marking (avoid recursion)
    * 
    * Sweep Phase:
    * 1. Walk all allocated objects
    * 2. Free unmarked objects
    * 3. Unmark marked objects for next cycle
    * 
    * Triggers:
    * - bytesAllocated exceeds nextGC threshold
    * - VM_STRESS_GC: collect on every allocation (debug only)
    */

4. Create docs/vm-architecture.md with diagrams:

   • Object memory layout
   • Stack frame structure
   • Bytecode encoding examples
   • GC object graph example

5. Add inline comments for complex code:

   • Pointer tagging/untagging operations
   • Environment chain traversal
   • Symbol table hash function

Testing & Acceptance Criteria

• Every opcode documented with stack effect notation
• Object tagging scheme fully explained
• GC algorithm described with examples
• docs/vm-architecture.md created with diagrams
• Code comments added to 10+ complex functions
• New developer can understand bytecode from docs
• VM debugging guide added to documentation
• Examples of reading disassembled bytecode