TinyComputers.io (Posts about virtual machine)

A Stack-Based Bytecode VM for Lattice: 100 Opcodes, Serialization, and a Self-Hosted Compiler

A.C. Jokela — Fri, 20 Feb 2026 18:00:00 GMT

When I first wrote about Lattice's move from a tree-walking interpreter to a bytecode VM, the instruction set had 62 opcodes, concurrency primitives still delegated to the tree-walker, and programs couldn't be serialized. The VM was a foundation, correct and complete enough to become the default, but clearly a starting point.

That was ten versions ago. The bytecode VM now has 100 opcodes, compiles concurrency primitives into standalone sub-chunks with zero AST dependency at runtime, ships a binary serialization format for ahead-of-time compilation, includes an ephemeral bump arena for short-lived string temporaries, and (perhaps most satisfyingly) has a self-hosted compiler written entirely in Lattice that produces the same .latc bytecode files as the C implementation.

This post walks through what changed and why. The full technical treatment is available as a research paper; this is the practitioner's version.

Why Keep Going

The original bytecode VM solved the immediate problems: it eliminated recursive AST dispatch overhead and gave Lattice a single execution path for file execution, the REPL, and the WASM playground. But three issues remained.

First, OP_SCOPE and OP_SELECT (Lattice's structured concurrency opcodes) still stored AST node pointers in the constant pool and dropped into the tree-walking evaluator at runtime. This meant the AST had to stay alive during concurrent execution, which defeated one of the main motivations for having a bytecode VM in the first place.

Second, the AST dependency made serialization impossible. You can serialize bytecode to a file, but you can't easily serialize an arbitrary C pointer to an AST node. Programs had to be parsed and compiled on every run.

Third, the dispatch loop used a plain switch statement. Not a crisis, but computed goto dispatch is a well-known improvement for bytecode interpreters, and leaving it on the table felt unnecessary.

All three problems are solved now. Let me start with the instruction set, since everything else builds on it.

100 Opcodes

The instruction set grew from 62 to 100 opcodes, organized into 16 functional categories:

Category	Representative opcodes	Count
Stack manipulation	`CONSTANT`, `NIL`, `TRUE`, `FALSE`, `UNIT`, `POP`, `DUP`, `SWAP`	8
Arithmetic/logical	`ADD`, `SUB`, `MUL`, `DIV`, `MOD`, `NEG`, `NOT`	7
Bitwise	`BIT_AND`, `BIT_OR`, `BIT_XOR`, `BIT_NOT`, `LSHIFT`, `RSHIFT`	6
Comparison	`EQ`, `NEQ`, `LT`, `GT`, `LTEQ`, `GTEQ`	6
String	`CONCAT`	1
Variables	`GET/SET_LOCAL`, `GET/SET/DEFINE_GLOBAL`, `GET/SET_UPVALUE`, `CLOSE_UPVALUE`	8
Control flow	`JUMP`, `JUMP_IF_FALSE`, `JUMP_IF_TRUE`, `JUMP_IF_NOT_NIL`, `LOOP`	5
Functions	`CALL`, `CLOSURE`, `RETURN`	3
Iterators	`ITER_INIT`, `ITER_NEXT`	2
Data structures	`BUILD_ARRAY`, `INDEX`, `SET_INDEX`, `GET_FIELD`, `INVOKE`, etc.	15
Exceptions/defer	`PUSH_EXCEPTION_HANDLER`, `THROW`, `DEFER_PUSH`, `DEFER_RUN`, etc.	6
Phase system	`FREEZE`, `THAW`, `CLONE`, `MARK_FLUID`, `REACT`, `BOND`, `SEED`, etc.	14
Builtins/modules	`PRINT`, `IMPORT`	2
Concurrency	`SCOPE`, `SELECT`	2
Integer fast paths	`INC_LOCAL`, `DEC_LOCAL`, `ADD_INT`, `SUB_INT`, `LOAD_INT8`, etc.	8
Wide variants	`CONSTANT_16`, `GET_GLOBAL_16`, `SET_GLOBAL_16`, `DEFINE_GLOBAL_16`, `CLOSURE_16`	5
Special	`RESET_EPHEMERAL`, `HALT`	2
Total		100

The growth came from three directions: the integer fast-path opcodes (8 new), the wide constant variants (5 new), and the concurrency/arena opcodes. Let me explain each.

Integer Fast Paths

Tight loops like for i in 0..1000 spend most of their time incrementing a counter and comparing it to a bound. The generic OP_ADD has to check whether its operands are integers, floats, or strings (for concatenation), which adds branching overhead on every iteration.

The integer fast-path opcodes (OP_ADD_INT, OP_SUB_INT, OP_MUL_INT, OP_LT_INT, OP_LTEQ_INT) skip the type check entirely and operate directly on int64_t values. OP_INC_LOCAL and OP_DEC_LOCAL handle the i += 1 and i -= 1 patterns as single-byte instructions that modify the stack slot in place, no push or pop required.

OP_LOAD_INT8 encodes a signed byte directly in the instruction stream. The integer 42 becomes two bytes (OP_LOAD_INT8, 0x2A) instead of a three-byte OP_CONSTANT plus an eight-byte constant pool entry. Any integer in [-128, 127] gets this treatment.

Wide Constant Variants

The original instruction set used a single byte for constant pool indices, limiting each chunk to 256 constants. This is fine for most functions, but the self-hosted compiler (a 2,000-line Lattice program compiled as a single top-level script) blows past that limit easily.

OP_CONSTANT_16, OP_GET_GLOBAL_16, OP_SET_GLOBAL_16, OP_DEFINE_GLOBAL_16, and OP_CLOSURE_16 use two-byte big-endian indices, supporting up to 65,536 constants per chunk. The compiler automatically switches to wide variants when an index exceeds 255.

The Compiler

The bytecode compiler performs a single-pass walk over the AST. It maintains a chain of Compiler structs linked via enclosing pointers, one per function being compiled. Variable references resolve through three tiers: local (scan the current compiler's locals array), upvalue (recursively check enclosing compilers), and global (fall through to OP_GET_GLOBAL).

Three compilation modes handle different use cases. compile() is the standard file mode: it compiles all declarations and emits an implicit call to main() if one is defined. compile_module() is for imports, identical to compile() but skips the auto-call. compile_repl() preserves the last expression on the stack as the iteration's return value (displayed with => prefix) and keeps the known-enum table alive across REPL iterations so enum declarations persist.

The compiler implements several optimizations during code generation. Binary operations on literal operands are folded at compile time: 3 + 4 emits a single OP_LOAD_INT8 7 rather than two loads and an OP_ADD. The pattern x += 1 is detected and emitted as the single-byte OP_INC_LOCAL, which modifies the stack slot in place. And every statement is wrapped by compile_stmt_reset(), which appends OP_RESET_EPHEMERAL to trigger the ephemeral arena cleanup.

Computed Goto Dispatch

The dispatch loop now uses GCC/Clang's labels-as-values extension for computed goto:

#ifdef VM_USE_COMPUTED_GOTO
  static void *dispatch_table[] = {
    [OP_CONSTANT] = &&lbl_OP_CONSTANT,
    [OP_NIL]      = &&lbl_OP_NIL,
    // ... all 100 entries
  };
#endif

for (;;) {
    uint8_t op = READ_BYTE();
#ifdef VM_USE_COMPUTED_GOTO
    goto *dispatch_table[op];
#endif
    switch (op) {
        // ...
    }
}

Each opcode handler ends with a goto *dispatch_table[READ_BYTE()] rather than breaking back to the top of the loop. This eliminates the switch statement's bounds check and branch table indirection, replacing it with a single indirect jump. The CPU's branch predictor sees different jump sites for different opcodes, which improves prediction accuracy compared to a single switch that all opcodes funnel through.

On platforms without the extension, it falls back to a standard switch. The VM works correctly either way.

Pre-Compiled Concurrency

This is the change I'm most pleased with, because it solves the problem cleanly.

Lattice has three concurrency primitives: scope defines a concurrent region, spawn launches a task within that region, and select multiplexes over channels. In the tree-walker, these work by passing AST node pointers to spawned threads, which then evaluate the subtrees independently. The bytecode VM's original implementation did the same thing: OP_SCOPE stored an Expr* pointer in the constant pool and called the tree-walking evaluator at runtime.

The solution is to compile each concurrent body into a standalone Chunk at compile time. The compiler provides two helpers: compile_sub_body() for statement blocks and compile_sub_expr() for expressions. Each creates a fresh Compiler, compiles the code into a new chunk, emits OP_HALT, and stores the resulting chunk in the parent's constant pool as a VAL_CLOSURE constant.

OP_SCOPE uses variable-length encoding: a spawn count, a sync body chunk index, and one chunk index per spawn body. At runtime, the VM:

Exports locals to the global environment using the local_names debug table, so sub-chunks can access parent variables via OP_GET_GLOBAL
Runs the sync body (if present) via a recursive vm_run() call
Spawns threads for each spawn body, each running on a cloned VM
Joins all threads and propagates errors

OP_SELECT similarly encodes per-arm metadata: flags, channel expression chunk index, body chunk index, and binding name index. The VM evaluates channel expressions, polls for readiness, and executes the winning arm.

The key insight is that sub-chunks run as FUNC_SCRIPT without lexical access to the parent's locals. Since they can't use upvalues to reach into the parent frame, the VM exports the parent's live locals into the global environment before running any sub-chunk, using a pushed scope that gets popped after all sub-chunks complete. This is slightly more expensive than true lexical capture, but it keeps the sub-chunks completely self-contained: no AST, no parent frame dependency, fully serializable.

Bytecode Serialization

With AST dependency eliminated, serialization becomes straightforward. The .latc binary format starts with an 8-byte header:

[4C 41 54 43]  magic: "LATC"
[01 00]        format version: 1
[00 00]        reserved

The rest is a recursive chunk encoding: code length + bytecode bytes, line numbers for source mapping, typed constants (with a one-byte type tag for each), and local name debug info. Constants use seven type tags:

Tag	Type	Encoding
0	Int	8-byte signed LE
1	Float	8-byte IEEE 754
2	Bool	1 byte
3	String	length-prefixed (u32 + bytes)
4	Nil	no payload
5	Unit	no payload
6	Closure	param count + variadic flag + recursive sub-chunk

The Closure tag is what makes this recursive: a function constant contains its parameter metadata followed by a complete serialized sub-chunk. Nested functions serialize naturally to arbitrary depth.

The CLI integrates this cleanly:

# Compile to .latc
clat compile input.lat -o output.latc

# Run pre-compiled bytecode (auto-detects .latc suffix)
clat output.latc

# Or compile and run in one step (the default)
clat input.lat

Loading validates magic bytes, checks the format version, and uses a bounds-checking ByteReader that produces descriptive error messages for truncated or malformed inputs.

The Ephemeral Bump Arena

String concatenation is a common source of short-lived allocations. An expression like "hello " + name + "!" creates intermediate strings that are immediately consumed and discarded. In a language with deep-clone-on-read semantics, these temporaries add up.

The ephemeral bump arena is a simple optimization: string concatenation in OP_ADD and OP_CONCAT allocates into a bump arena (vm->ephemeral) instead of the general-purpose heap. These allocations are tagged with REGION_EPHEMERAL, and OP_RESET_EPHEMERAL (emitted by the compiler at every statement boundary) resets the arena in O(1), reclaiming all temporary strings at once.

The tricky part is escape analysis. If a temporary string gets assigned to a global variable, stored in an array, or passed to a compiled closure, it needs to be promoted out of the ephemeral arena before the arena is reset. The VM handles this at specific escape points: OP_DEFINE_GLOBAL, OP_CALL (for compiled closures), array.push, and OP_SET_INDEX_LOCAL. Each of these calls vm_promote_value(), which deep-clones the string to the regular heap if its region is ephemeral.

The arena uses a page-based allocator with 4 KB pages. Resetting doesn't free pages; it just moves the bump pointer back to zero, so subsequent allocations reuse the same memory without any malloc/free overhead. The full design and safety proof are covered in a companion paper.

Closures and the Storage Hack

The upvalue system hasn't changed architecturally since the first VM post; it's still the Lua-inspired open/closed model where ObjUpvalue structs start pointing into the stack and get closed (deep-cloned to the heap) when variables go out of scope. But the encoding grew to accommodate the wider instruction set.

OP_CLOSURE uses variable-length encoding: a constant pool index for the function's compiled chunk, an upvalue count, and then [is_local, index] byte pairs for each captured variable. OP_CLOSURE_16 uses a two-byte big-endian function index for chunks with more than 256 constants.

The storage hack (repurposing closure.body (NULL), closure.native_fn (Chunk pointer), closure.captured_env (ObjUpvalue** cast), and region_id (upvalue count)) remains unchanged. A sentinel value VM_NATIVE_MARKER distinguishes C-native functions from compiled closures:

#define VM_NATIVE_MARKER ((struct Expr **)(uintptr_t)0x1)

A closure with body == NULL and native_fn != NULL is either a C native (if default_values == VM_NATIVE_MARKER) or a compiled bytecode function (otherwise). This avoids adding VM-specific fields to the LatValue union, which matters when values are deep-cloned frequently.

The Self-Hosted Compiler

The file compiler/latc.lat is a bytecode compiler written entirely in Lattice, approximately 2,060 lines that read .lat source, produce bytecode, and write .latc files using the same binary format as the C implementation:

# Use the self-hosted compiler
clat compiler/latc.lat input.lat output.latc

# Run the result
clat output.latc

The architecture mirrors the C compiler: lexing via the built-in tokenize() function, a recursive-descent parser, single-pass code emission, and scope management with upvalue resolution. But Lattice's value semantics required some creative workarounds.

The biggest constraint is that structs and maps are pass-by-value. In C, the compiler uses a Compiler struct with mutable fields: local arrays, scope depth, a chunk pointer. In Lattice, passing a struct to a function creates a copy, so mutations in the callee don't propagate back. The self-hosted compiler works around this with parallel global arrays: code, constants, c_lines, local_names, local_depths, local_captured. Since array mutations via .push() and index assignment are in-place (via resolve_lvalue), global arrays work where structs don't.

Nested function compilation uses explicit save_compiler() / restore_compiler() functions that copy all global arrays to local temporaries and back. It's verbose but correct. The Buffer type (used for serialization output) is also pass-by-value, so a global ser_buf accumulates serialized bytes across function calls.

Other language constraints: no else if (requires else { if ... } or match), mandatory type annotations on function parameters (fn foo(a: any)), and test is a keyword so you can't use it as an identifier.

The self-hosted compiler currently handles expressions, variables, functions with closures, control flow (if/else, while, loop, for, break, continue, match), structs, enums, exceptions, defer, string interpolation, and imports. Not yet implemented: concurrency primitives and advanced phase operations (react, bond, seed). The bootstrapping chain is:

latc.lat → [C VM interprets] → output.latc → [C VM executes]

Full self-hosting (where latc.lat compiles itself) requires adding concurrency support and closing the remaining feature gaps.

The VM Execution Engine

The VM maintains a 4,096-slot value stack, a 256-frame call stack, an exception handler stack (64 entries), a defer stack (256 entries), a global environment, the open upvalue linked list, the ephemeral arena, and a module cache. A pre-allocated fast_args[16] buffer avoids heap allocation for most native function calls.

The OP_CALL instruction discriminates three callee types. Native C functions (marked with VM_NATIVE_MARKER) get the fast path: arguments are popped into fast_args, the C function pointer is invoked, and the return value is pushed. No call frame allocated. Compiled closures get the full treatment: the VM promotes ephemeral values in the current frame (so the callee's OP_RESET_EPHEMERAL doesn't invalidate the caller's temporaries), then pushes a new CallFrame with the instruction pointer at byte 0 of the callee's chunk. Callable structs look up a constructor-named field and dispatch accordingly.

Exception handling uses a handler stack. OP_PUSH_EXCEPTION_HANDLER records the current IP, chunk, call frame index, and stack top. When OP_THROW executes, the nearest handler is popped, the call frame and value stacks are unwound, the error value is pushed, and execution resumes at the handler's saved IP. Deferred blocks interact correctly: OP_DEFER_RUN executes all defer entries registered at or above the current frame before the frame is popped by OP_RETURN.

Iterators avoid closure allocation entirely. OP_ITER_INIT converts a range or array into an internal iterator occupying two stack slots (collection + cursor index). OP_ITER_NEXT advances the cursor, pushes the next element, or jumps to a specified offset when exhausted. The tree-walker used closure-based iterators for for loops; the bytecode version is simpler and avoids the allocation.

Ref<T>: The Escape Hatch from Value Semantics

Everything described so far operates in a world where values are deep-cloned on every read. Maps are pass-by-value. Structs are pass-by-value. Pass a collection to a function and the function gets its own copy; mutations don't propagate back. This is correct and eliminates aliasing bugs, but it creates a real problem: how do you share mutable state when you actually need to?

Ref<T> is the answer. It's a reference-counted shared mutable wrapper, the one type in Lattice that deliberately breaks value semantics:

struct LatRef {
    LatValue value;      // the wrapped inner value
    size_t   refcount;   // reference count
};

When a Ref is cloned (which happens on every variable read, like everything else), the VM bumps the refcount and copies the pointer. It does not deep-clone the inner value. Multiple copies of a Ref share the same underlying LatRef, so mutations through one are visible through all others. This is the explicit opt-in to reference semantics that the rest of the language avoids.

let r = Ref::new([1, 2, 3])
let r2 = r              // shallow copy — same LatRef
r.push(4)
print(r2.get())          // [1, 2, 3, 4] — shared state

The VM provides transparent proxying: OP_INDEX, OP_SET_INDEX, and OP_INVOKE all check for VAL_REF and delegate to the inner value. Indexing into a Ref<Array> indexes the inner array. Calling .push() on a Ref<Array> mutates the inner array directly. At the language level, a Ref mostly behaves like the value it wraps; you just get shared mutation instead of isolated copies.

Ref has its own methods (get()/deref() to clone the inner value out, set(v) to replace it, inner_type() to inspect the wrapped type) plus proxied methods for whatever the inner value supports (map set/get/keys, array push/pop, etc.).

The phase system applies to Refs too. Freezing a Ref blocks all mutation: set(), push(), index assignment all check obj->phase == VTAG_CRYSTAL and error with "cannot set on a frozen Ref." This makes frozen Refs safe to share across concurrent boundaries; they're immutable handles to immutable data.

This introduces a third memory management strategy alongside the dual-heap (mark-and-sweep for fluid values, arenas for crystal values) and the ephemeral bump arena. Refs use reference counting: ref_retain() on clone, ref_release() on free, with the inner value freed when the count hits zero. It's a deliberate trade-off: reference counting is simple and deterministic, and since Refs are the uncommon case (most Lattice code uses value semantics), the lack of cycle collection hasn't been an issue in practice.

Validation

The VM is validated by 815 tests covering every feature: arithmetic, closures, upvalues, phase transitions, exception handling, defer, iterators, data structures, concurrency, modules, bytecode serialization, and the self-hosted compiler.

All 815 tests pass under both normal compilation and AddressSanitizer builds (make asan), which dynamically checks for heap buffer overflows, use-after-free, stack buffer overflows, and memory leaks. For a VM with manual memory management, upvalue lifetime tracking, and an ephemeral arena that reclaims memory at statement boundaries, ASan validation is essential.

Both execution modes (bytecode VM (default) and tree-walker (--tree-walk)) share the same test suite and produce identical results:

make test                # bytecode VM: 815 passed
make test TREE_WALK=1    # tree-walker: 815 passed

Feature parity is complete:

Feature	Tree-walker	Bytecode VM
Phase system (freeze/thaw/clone/forge)	✓	✓
Closures with upvalues	✓	✓
Exception handling (try/catch/throw)	✓	✓
Defer blocks	✓	✓
Pattern matching	✓	✓
Structs with methods	✓	✓
Enums with payloads	✓	✓
Arrays, maps, tuples, sets, buffers	✓	✓
Iterators (for-in, ranges)	✓	✓
Module imports	✓	✓
Concurrency (scope/spawn/select)	✓	✓
Channels	✓	✓
Phase reactions/bonds/seeds	✓	✓
Contracts (require/ensure)	✓	✓
Variable tracking (history)	✓	✓
Bytecode serialization (.latc)	---	✓
Computed goto dispatch	---	✓
Ephemeral bump arena	---	✓
Specialized integer ops	---	✓

The last four rows are VM-only features that have no tree-walker equivalent.

What's Next

The VM is feature-complete but not performance-optimized. The obvious next steps are register allocation to reduce stack traffic, type-specialized dispatch paths guided by runtime profiling, tail call optimization for recursive patterns, and constant pool deduplication across compilation units. Further out, the bytecode provides a natural intermediate representation for JIT compilation.

On the self-hosting front, adding concurrency primitives to latc.lat would close the gap to full self-compilation, where the Lattice compiler compiles itself, producing a .latc file that can then compile other programs without the C implementation in the loop.

The full technical details (including encoding diagrams, the complete opcode listing, compilation walkthroughs, and references to related work in Lua, CPython, YARV, and WebAssembly) are in the research paper.

The source code is at github.com/ajokela/lattice, and the project site is at lattice-lang.org.

git clone https://github.com/ajokela/lattice.git
cd lattice && make
./clat

From Tree-Walker to Bytecode VM: Compiling Lattice

A.C. Jokela — Tue, 17 Feb 2026 18:00:00 GMT

Lattice is a programming language built around a crystallization-based phase system: values start as mutable "flux" and can be frozen into immutable "fix," with the runtime enforcing the transition and providing reactions, bonds, contracts, and temporal tracking around it. It's implemented in C with no external dependencies.

When I started building Lattice, a tree-walking interpreter was the obvious first move. You parse source into an AST, walk the nodes recursively, and evaluate as you go. It's straightforward, easy to debug, and lets you iterate on language semantics quickly without worrying about a second representation. Crafting Interpreters calls this approach "the simplest way to build an interpreter," and it's right.

But tree-walkers have well-known limitations. Every expression evaluation descends through function calls: eval_expr calling eval_binary calling eval_expr twice more. The overhead compounds. You're chasing pointers through heap-allocated AST nodes with poor cache locality. And the call stack of the host language (C, in Lattice's case) becomes tangled with the call stack of the guest language, making it harder to implement features like error recovery and coroutines cleanly.

Lattice v0.3.0 shipped a bytecode compiler and stack-based virtual machine alongside the tree-walker. In v0.3.1, the bytecode VM became the default for file execution, the interactive REPL, and the browser-based playground. The tree-walker is still available via --tree-walk, but the VM now handles everything. This post walks through the architecture of that VM, some design decisions that turned out to matter, and a mutation bug that only surfaces when you combine deep-clone-on-read semantics with in-place method dispatch.

Architecture Overview

The bytecode pipeline has three stages: lexing and parsing (shared with the tree-walker), compilation from AST to bytecode chunks, and execution on a stack-based VM. The compiler and VM together add about 8,200 lines of C to the codebase, bringing the total to around 33,000 lines.

A Chunk is the compilation unit: a dynamic array of bytecode instructions, a constant pool, and debug metadata mapping instructions back to source line numbers. The compiler walks the AST and emits bytes into a chunk. The VM reads bytes from the chunk and executes them against a value stack.

typedef struct {
    uint8_t  *code;          // bytecode array
    size_t    len, cap;
    LatValue *constants;     // constant pool
    size_t    const_len, const_cap;
    int      *lines;         // source line per instruction
    char    **local_names;   // slot → variable name (debug)
    size_t    local_name_cap;
} Chunk;

The VM itself is a for(;;) loop with a switch on the current opcode byte, the textbook approach. No computed gotos, no threaded dispatch, no JIT. Just a switch. On modern hardware with branch prediction, a well-organized switch over 62 opcodes is fast enough that the overhead is negligible compared to the cost of actual operations (string allocation, hash table lookups, deep cloning).

for (;;) {
    uint8_t op = READ_BYTE();
    switch (op) {
        case OP_CONSTANT: { ... }
        case OP_ADD:      { ... }
        case OP_CALL:     { ... }
        // 59 more cases
    }
}

The value stack holds 4,096 slots. The call frame stack holds 256 frames. Each CallFrame tracks its own instruction pointer, a base pointer into the value stack for its local variables, and an array of captured upvalues for closures. When you call a function, the VM pushes a new frame pointing at the callee's chunk. When the function returns, the frame pops and execution resumes in the caller.

The Instruction Set

Lattice's instruction set has 62 opcodes. Some are standard (OP_ADD, OP_JUMP_IF_FALSE, OP_RETURN). Others exist because of Lattice-specific semantics.

The phase system needs dedicated opcodes. OP_FREEZE pops a value, deep-clones it into a crystal region with VTAG_CRYSTAL tags, and pushes the frozen result. OP_THAW does the reverse. OP_MARK_FLUID sets the phase tag to VTAG_FLUID; this is what flux bindings emit after their initializer. OP_FREEZE_VAR and OP_THAW_VAR handle the case where freeze(x) targets a named variable and needs to write back the result, carrying extra operands to identify the variable's location (local slot, upvalue, or global name).

Phase reactions and bonds each have their own opcodes: OP_REACT, OP_UNREACT, OP_BOND, OP_UNBOND, OP_SEED, OP_UNSEED. These could theoretically be implemented as native function calls, but making them opcodes lets the compiler emit the variable name as a constant operand, and the VM needs the name to look up the correct reaction/bond registration in its tracking tables, and encoding it in the bytecode avoids a runtime string lookup.

Structured concurrency uses an interesting hybrid. OP_SCOPE and OP_SELECT each carry a constant-pool index that stores a pointer to the original AST Expr* node. When the VM hits one of these opcodes, it invokes the tree-walking evaluator on that subtree. This is a deliberate design choice; the concurrency primitives involve spawning threads and managing channels, which requires the evaluator's full environment machinery. Rather than reimplement all of that in the VM, the bytecode compiler punts to the tree-walker for these specific constructs. The rest of the program runs on the VM; only scope and select blocks briefly drop into interpretation.

Closures and Upvalues

Closures are where bytecode VMs get interesting, and Lattice follows the upvalue model that Lua pioneered and Crafting Interpreters popularized.

When a function is defined inside another function and references variables from the enclosing scope, those variables need to outlive their original stack frame. The solution is upvalues, indirection objects that start pointing into the stack and get "closed over" when the variable goes out of scope.

typedef struct ObjUpvalue {
    LatValue *location;        // points to stack slot or &closed
    LatValue  closed;          // holds value after scope exit
    struct ObjUpvalue *next;   // linked list for open upvalues
} ObjUpvalue;

While the enclosing function is still executing, location points directly at the stack slot. When the enclosing function returns, OP_CLOSE_UPVALUE copies the stack value into the closed field and repoints location to &closed. The closure doesn't know or care about the switch; it always dereferences location. This is why upvalues work: they're a level of indirection that transparently survives stack frame destruction.

The compiler resolves variable references in three stages: first it checks local scope (resolve_local), then upvalues (resolve_upvalue, which walks the compiler chain recursively), then falls back to globals via OP_GET_GLOBAL. The OP_CLOSURE instruction is followed by a series of (is_local, index) byte pairs, one per upvalue, telling the VM whether to capture from the current frame's stack or from the parent frame's upvalue array.

A concrete example makes this clearer. Consider a counter factory:

fn make_counter() {
    flux count = 0
    return |n| { count += n; count }
}

let c = make_counter()
print(c(5))   // 5
print(c(3))   // 8

When make_counter returns, its stack frame is destroyed, but count needs to survive, because the returned closure references it. During compilation, the compiler sees that the closure's body references count, which is local to the enclosing make_counter. It emits an (is_local=true, index=1) upvalue descriptor. At runtime, OP_CLOSURE calls capture_upvalue(), which either reuses an existing ObjUpvalue pointing at that stack slot or creates a new one. When make_counter returns, OP_CLOSE_UPVALUE copies the stack value of count into the upvalue's closed field and repoints location. The closure keeps working, oblivious to the frame being gone.

One implementation detail worth noting: Lattice stores the upvalue array by repurposing the closure's captured_env field (normally an Env* in the tree-walker) and the upvalue count in the region_id field. This avoids adding new fields to the LatValue union, which matters when values are deep-cloned frequently, since every field adds to the clone cost.

Compiling for the REPL

A REPL that runs on a bytecode VM needs different compilation from file execution. The difference is small but important.

In file mode, compile_module() compiles a complete program and terminates with OP_UNIT; OP_RETURN; the module returns unit, and any expression results along the way are discarded with OP_POP. This is the right behavior for scripts: you don't want every intermediate expression to accumulate on the stack.

In REPL mode, compile_repl() needs the opposite behavior for the last expression. When you type 42 at the REPL prompt, you want to see => 42. So if the last item in the compiled chunk is a bare expression statement, compile_repl() compiles the expression but skips the OP_POP, leaving the value on the stack. Then it emits OP_RETURN, and the VM receives the value as the chunk's return value.

bool last_is_expr = (prog->item_count > 0 &&
    prog->items[prog->item_count - 1].tag == ITEM_STMT &&
    prog->items[prog->item_count - 1].as.stmt->tag == STMT_EXPR);

if (last_is_expr)
    emit_byte(OP_RETURN, 0);       // value already on stack
else {
    emit_byte(OP_UNIT, 0);         // no expression — return unit
    emit_byte(OP_RETURN, 0);
}

For function definitions, struct declarations, and enum definitions, the result is unit, and the REPL silently suppresses the => output. This matches user expectations: defining a function shouldn't print anything. The effect in practice:

lattice> 42
=> 42
lattice> "hello" + " world"
=> "hello world"
lattice> flux x = 10
lattice> x * 2
=> 20
lattice> fn square(n: Int) -> Int { n * n }
lattice> square(7)
=> 49

Each line is independently compiled and executed on the persistent VM. Globals defined in one line (flux x = 10) are visible in subsequent lines because they're stored in the VM's environment, which persists across iterations. The Chunk for each line is freed after execution; constants that matter (like global variable values) have already been deep-cloned into the environment.

The other critical difference is enum persistence. compile_module() frees its known-enum registry after compilation, because the compiler is done. compile_repl() must not, because enums defined in REPL iteration N need to be visible in iteration N+1. The REPL calls compiler_free_known_enums() only on exit. The same lifetime concern applies to parsed programs; struct and function declarations store Expr* pointers that compiled chunks reference at runtime. The REPL accumulates all parsed programs in a dynamic array and frees them only when the session ends.

The Global Mutation Bug

This is the story I find most instructive, because it reveals a subtle interaction between two independently reasonable design decisions.

Lattice has deep-clone-on-read semantics. When you access a variable, the environment doesn't hand you a reference to the stored value; it hands you a fresh deep clone. This eliminates aliasing entirely: two variables never share underlying memory, passing a map to a function gives the function its own copy, and there's no way to create spooky action at a distance through shared mutable state.

bool env_get(const Env *env, const char *name, LatValue *out) {
    for (size_t i = env->count; i > 0; i--) {
        LatValue *v = lat_map_get(&env->scopes[i-1], name);
        if (v) {
            *out = value_deep_clone(v);  // always a fresh copy
            return true;
        }
    }
    return false;
}

This is expensive but correct. It gives Lattice pure value semantics without needing a borrow checker or persistent data structures.

The tree-walking evaluator handles in-place mutation (like array.push()) with a separate resolve_lvalue() mechanism that obtains a direct mutable pointer into the environment's storage, bypassing the deep clone. Push, pop, index assignment: these all go through resolve_lvalue and mutate the stored value directly.

The bytecode VM needed the same distinction. For local variables, this is straightforward: locals live on the value stack, and the VM has a direct pointer to them via frame->slots[slot]. I added OP_INVOKE_LOCAL, which takes a stack slot index as an operand and passes a pointer to vm_invoke_builtin():

case OP_INVOKE_LOCAL: {
    uint8_t slot = READ_BYTE();
    uint8_t method_idx = READ_BYTE();
    uint8_t arg_count = READ_BYTE();
    const char *method_name = frame->chunk->constants[method_idx].as.str_val;
    LatValue *obj = &frame->slots[slot];  // direct pointer

    if (vm_invoke_builtin(vm, obj, method_name, arg_count, local_var_name)) {
        // builtin mutated obj in-place — mutation persists
        break;
    }
    // ... fall through to closure/method dispatch
}

When .push() grows the array by reallocating obj->as.array.elems and incrementing obj->as.array.len, it's directly modifying the stack slot. The mutation persists because obj is the variable.

For globals, the situation is different. Globals live in the environment (a scope-chain of hash maps), and env_get() deep-clones. The generic OP_INVOKE opcode works by evaluating the receiver expression onto the stack (which, for a global variable, means emitting OP_GET_GLOBAL, which calls env_get(), which deep-clones) and then dispatching the method on the cloned value. After the builtin mutates the clone, OP_INVOKE pops and frees it. The mutation vanishes.

flux nums = [1, 2, 3]
nums.push(4)
print(nums)  // still [1, 2, 3] — the push mutated a clone

This is the kind of bug that's obvious in retrospect but invisible when you're implementing things one piece at a time. env_get() deep-cloning is correct. OP_INVOKE popping the receiver after dispatch is correct. Each piece behaves correctly in isolation. The bug emerges from their composition.

The fix is OP_INVOKE_GLOBAL, a new opcode that knows the receiver is a global variable and writes back after mutation:

case OP_INVOKE_GLOBAL: {
    uint8_t name_idx = READ_BYTE();
    uint8_t method_idx = READ_BYTE();
    uint8_t arg_count = READ_BYTE();
    const char *global_name = frame->chunk->constants[name_idx].as.str_val;
    const char *method_name = frame->chunk->constants[method_idx].as.str_val;

    LatValue obj_val;
    if (!env_get(vm->env, global_name, &obj_val)) {
        VM_ERROR("undefined variable '%s'", global_name); break;
    }

    if (vm_invoke_builtin(vm, &obj_val, method_name, arg_count, global_name)) {
        if (vm->error) { /* handle error */ }
        // Write back the mutated clone to the environment
        env_set(vm->env, global_name, obj_val);
        break;
    }
    // ... fall through for non-builtin methods
}

The compiler emits OP_INVOKE_GLOBAL when it sees a method call on an identifier that isn't a local variable or an upvalue:

case EXPR_METHOD_CALL: {
    if (e->as.method_call.object->tag == EXPR_IDENT) {
        int slot = resolve_local(current, e->as.method_call.object->as.str_val);
        if (slot >= 0) {
            // ... emit OP_INVOKE_LOCAL
        }
        int upvalue = resolve_upvalue(current, e->as.method_call.object->as.str_val);
        if (upvalue < 0) {
            // Not local, not upvalue — must be global
            // ... emit OP_INVOKE_GLOBAL
        }
    }
    // ... fall through to generic OP_INVOKE
}

This gives us three tiers of method dispatch: OP_INVOKE_LOCAL for locals (direct pointer, no clone), OP_INVOKE_GLOBAL for globals (clone + write-back), and OP_INVOKE for everything else (computed receivers like get_array().push(x), where there's nothing to write back to). With the fix:

flux nums = [1, 2, 3]
nums.push(4)
nums.push(5)
print(nums)  // [1, 2, 3, 4, 5] — mutations persist

All mutating builtins (push, pop, set, remove, insert, remove_at) now work correctly on global variables. The same pattern applies to maps, sets, and any other type with in-place methods.

The broader lesson is that deep-clone-on-read semantics create an impedance mismatch with in-place mutation. In a reference-based language, obj.push(x) just works; obj is a reference, and the mutation happens wherever the reference points. In a value-based language, you need to explicitly handle the write-back for every level of variable storage. The tree-walker's resolve_lvalue is one solution. The VM's tiered invoke opcodes are another. Both exist because of the same underlying tension.

The WASM Playground

Lattice's browser-based playground compiles the entire VM to WebAssembly via Emscripten. The WASM API exposes four functions: lat_init(), lat_run_line(), lat_is_complete(), and lat_destroy().

The playground runs the same bytecode VM as the native binary. Each line of input goes through the same pipeline: lex, parse, compile_repl(), vm_run(). The lat_is_complete() function checks bracket depth to determine whether the user is mid-expression, enabling multi-line input by waiting for balanced braces before compiling.

Previously the playground used the tree-walking evaluator, which meant code could behave differently in the browser than on the command line. Switching the WASM build to the bytecode VM eliminates that inconsistency; the playground, the REPL, and file execution all use the same compilation and execution path.

What Didn't Change

It's worth noting what the bytecode VM doesn't change about Lattice.

The value representation is identical. A LatValue is still a tagged union with a type tag, phase tag, and payload. Phase transitions still deep-clone data across heap regions. The dual-heap architecture (mark-and-sweep for fluid data, arena-based regions for crystal data) is unchanged. Global variables still live in a scope-chain environment.

The parser and AST are completely shared. The compiler reads the same Program structure that the tree-walker reads. A single set of test programs validates both execution paths, and all 771 tests pass on both.

The phase system compiles one-to-one. freeze() becomes OP_FREEZE. thaw() becomes OP_THAW. Bonds, reactions, seeds, pressure constraints: each has a corresponding opcode that does exactly what the tree-walker's evaluator function did, just driven by bytecode dispatch instead of recursive AST traversal.

Performance

I haven't done rigorous benchmarking, and I'm deliberately not making performance claims. The motivation for the bytecode VM wasn't speed; it was consistency (one execution path everywhere) and architectural cleanliness (the VM is easier to extend than the tree-walker's deeply nested switch statements).

That said, bytecode VMs are generally faster than tree-walkers for the structural reasons mentioned earlier: better cache locality (sequential byte array vs. pointer-chasing through AST nodes), less call overhead (one switch dispatch vs. recursive function calls), and a compact representation that fits more of the program in cache. Whether this matters for Lattice programs depends on the workload. For a language whose core runtime cost is dominated by deep cloning, the dispatch overhead is rarely the bottleneck.

Looking Forward

The VM is feature-complete but not optimized. There's no constant folding, no dead code elimination, no register allocation (it's a pure stack machine). The OP_SCOPE and OP_SELECT concurrency opcodes still delegate to the tree-walker. The dispatch loop is a plain switch rather than computed gotos.

These are all well-understood optimizations with clear implementation paths. The point of v0.3.1 is that the bytecode VM is now the default, passes all tests, and handles the full language surface including the phase system. Optimization is a separate project.

The source code is at github.com/ajokela/lattice, and you can try it in the browser at lattice-lang.web.app. The bytecode VM, compiler, REPL, and all 62 opcodes are in four files: compiler.c, vm.c, chunk.c, and opcode.c.

git clone https://github.com/ajokela/lattice.git
cd lattice && make
./clat

Recommended Resources

Crafting Interpreters by Robert Nystrom - The definitive guide to building interpreters and bytecode VMs, and a major influence on Lattice's upvalue implementation
Writing A Compiler In Go by Thorsten Ball - Practical companion covering bytecode compilation and stack-based VMs
Engineering a Compiler by Cooper & Torczon - Comprehensive treatment of compiler internals from front-end to optimization
Compilers: Principles, Techniques, and Tools by Aho, Lam, Sethi, Ullman - The classic Dragon Book covering parsing, code generation, and optimization theory