Module opcode 

Constants

ADD

Pop b, pop a, push a + b.

BUFFER_APPEND_SEP_UNLESS_FIRST

Append separator only when buffer is non-empty. Pop sep, pop buf → push buf. No-op for the first append, so the synthesized __buffered loop body can place the separator before each element uniformly.

BUFFER_APPEND_STR

Append the bytes of a string to a buffer. Pop str, pop buf → push buf (same handle). The String pointed to by buf.handle is mutated in place via String::push_str.

BUFFER_FINALIZE

Drain a buffer into an arena OBJ_STRING. Pop buf → push string. Frees the underlying vm.buffer_pool slot; the handle becomes invalid.

BUFFER_NEW

Allocate a fresh String buffer. Pop cap_hint:i64 → push handle:Int(buffer_idx).

CALL_BUILTIN

Call a builtin service function.

CALL_BUILTIN_OWNED

Like CALL_BUILTIN but with owned-argument bitmask from reuse analysis. Builtins receiving owned args can mutate in-place instead of cloning.

CALL_KNOWN

Call a known function by id. Args already on stack.

CALL_KNOWN_OWNED

Like CALL_KNOWN but with owned-argument bitmask from reuse analysis.

CALL_LEAF

Frameless call to a leaf+thin+args-only function. No CallFrame is pushed — just saves (fn_id, ip) in the dispatch loop, sets bp to the args already on stack, and jumps to the target. On RETURN, restores the caller’s state directly. Format: fn_id:u16, argc:u8 (same as CALL_KNOWN).

CALL_PAR

Parallel function calls for independent products (?! / !). Pops N callable values plus their args from the stack, dispatches them via the same callable resolution rules as CALL_VALUE, then builds the result tuple. Enters/exits replay group around parallel dispatch.

CALL_VALUE

Call a function value on the stack (under args).

CONCAT

Pop b, pop a, push str(a) ++ str(b).

DIV

Pop b, pop a, push a / b.

DUP

Duplicate the top value.

EQ

Pop b, pop a, push a == b.

EXTRACT_FIELD

Peek top (record/variant), push fields[field_idx] (non-destructive).

EXTRACT_TUPLE_ITEM

Peek top tuple, push items[item_idx] (non-destructive).

GT

Pop b, pop a, push a > b.

JUMP

Unconditional relative jump: ip += offset.

JUMP_IF_FALSE

Pop top, if falsy: ip += offset.

LIST_CONS

Pop tail, pop head, push Cons(head, tail).

LIST_HEAD_TAIL

Pop cons cell, push tail then push head.

LIST_LEN

Pop list, push its length as Int.

LIST_NEW

Pop count items, build cons list from them (first item = head), push list.

LIST_NIL

Push Nil (empty cons list).

LIST_PREPEND

Pop list, pop value, push prepended list.

LOAD_CONST

Push constants[idx] onto the operand stack.

LOAD_FALSE

Push NanValue::FALSE.

LOAD_GLOBAL

Push globals[idx] onto the operand stack.

LOAD_LOCAL

Push stack[bp + slot] onto the operand stack.

LOAD_LOCAL_2

Push two locals in one dispatch. Format: slot_a:u8, slot_b:u8.

LOAD_LOCAL_CONST

Push one local + one constant in one dispatch. Format: slot:u8, const_idx:u16.

LOAD_TRUE

Push NanValue::TRUE.

LOAD_UNIT

Push NanValue::UNIT.

LT

Pop b, pop a, push a < b.

MATCH_CONS

Peek top: if Nil (not a cons), ip += fail_offset.

MATCH_DISPATCH

Unified prefix/exact dispatch on NanValue bits.

MATCH_DISPATCH_CONST

Like MATCH_DISPATCH but every entry carries an inline result instead of a jump offset. When an entry matches, the result is pushed directly onto the stack and the match body is skipped entirely.

MATCH_FAIL

Non-exhaustive match error at source line.

MATCH_NIL

Peek top: if not Nil, ip += fail_offset.

MATCH_TAG

Peek top: if NaN tag != expected, ip += fail_offset.

MATCH_TUPLE

Peek top: if not a tuple of count items, ip += fail_offset.

MATCH_UNWRAP

Peek top: if not wrapper of kind, ip += fail_offset. If matches, replace top with inner value (unwrap in-place). kind: 0=Ok, 1=Err, 2=Some.

MATCH_VARIANT

Peek top (must be variant): if variant_id != expected, ip += fail_offset.

MOD

Pop b, pop a, push a % b.

MOVE_LOCAL

Push stack[bp + slot] and clear the slot (move semantics). Used for last-use variables: caller releases sole ownership so callees and builtins see refcount=1 and can mutate in-place.

MUL

Pop b, pop a, push a * b.

NEG

Pop a, push -a.

NOP

No-op, used as padding after superinstruction fusion.

NOT

Pop a, push !a (boolean not).

POP

Discard the top value.

PROPAGATE_ERR

Propagate Result.Err to caller or unwrap Result.Ok in place.

RECORD_GET

Pop record, push fields[field_idx] (compile-time resolved index).

RECORD_GET_NAMED

Pop record, lookup field by interned field symbol, push value.

RECORD_NEW

Pop count field values, push a new record with type_id.

RECORD_UPDATE

Update selected fields on a record, preserving the rest from the base value. Stack: […, base_record, update_0, …, update_n-1] -> […, updated_record]

RETURN

Return top of stack to caller.

STORE_GLOBAL

Pop top and store into globals[idx].

STORE_LOCAL

Pop top and store into stack[bp + slot].

SUB

Pop b, pop a, push a - b.

TAIL_CALL_KNOWN

Mutual tail-call to a known function: reuse frame, switch target.

TAIL_CALL_SELF

Self tail-call: reuse current frame with new args.

TAIL_CALL_SELF_THIN

Tail-call self for thin frames: no arena finalization needed. The compiler emits this instead of TAIL_CALL_SELF when the function is known to be “thin” (no heap allocations within the frame). Skips finalize_frame_locals_for_tail_call entirely — just copies args in-place and resets ip.

TUPLE_NEW

Pop count items, build a tuple from them, push tuple.

UNWRAP_OR

Inline Option.withDefault: pop default, pop option → push inner or default. Stack: [option, default] → [result] If option is Some → push unwrapped inner value. If option is None → push default.

UNWRAP_RESULT_OR

Inline Result.withDefault: pop default, pop result → push inner or default. Stack: [result, default] → [value] If result is Ok → push unwrapped inner value. If result is Err → push default.

VARIANT_NEW

Pop count field values, push a new variant.

VECTOR_GET

Inline Vector.get: pop index, pop vector → push Option (Some/None). Stack: [vector, index] → [option]

VECTOR_GET_OR

Fused Vector.get + Option.withDefault: pop default, pop index, pop vector → push value. Stack: [vector, index, default] → [value] Combines CALL_BUILTIN(Vector.get) + LOAD_CONST + UNWRAP_OR into one opcode.

VECTOR_SET

Inline Vector.set: pop value, pop index, pop vector → push Option. Stack: [vector, index, value] → [option_vector]

VECTOR_SET_OR_KEEP

Fused Vector.set + Option.withDefault(vec): pop value, pop index, pop vector → push vector. Stack: [vector, index, value] → [vector]

WRAP

Pop value, push wrapped value. kind: 0=Ok, 1=Err, 2=Some.

Functions

opcode_name

Opcode name for debug/disassembly.

opcode_operand_width

Operand byte width after the opcode byte. Single source of truth — all bytecode traversal functions must use this.