AtlasLang: Bytecode and the Stack Machine

Twenty-three opcodes, in five groups. PUSH a literal; LOAD slot *n* onto the stack; STORE pops into slot *n*. Arithmetic and comparison — ADD SUB MUL DIV MOD, EQ NE LT LE GT GE — each popping two and pushing one. Unary NEG and NOT. Control — JUMP to an absolute index, JUMPF which pops and jumps if false, CALL with an arity, and RETURN. And the odds and ends: PRINT, POP, HALT.

That is a stack machine. No instruction names a register, and no instruction needs to: operands come off the stack and results go back onto it. The consequence is that instructions are tiny — an opcode and at most one number — and there are more of them than a register machine would need, because every value makes a round trip through the stack. That trade is [[stack-vs-register-vm]], and it is the reason CPython, the JVM and WebAssembly are all stack machines while Lua and Dalvik are not.

Two design decisions are worth flagging because they are visible in the trace and confuse people otherwise. JUMPF exists but JUMPT does not, because a branch can always be arranged so the false case is the conditional one — one fewer opcode, one more constraint on the emitter. And jump targets are absolute instruction indices, not block labels, so the compiler emits a placeholder and patches it once the target's address is known. That patching pass is the reason a linear instruction format needs a fixup step and a graph representation does not.

The core of the translation is a single rule. A three-address instruction %d = a op b becomes three bytecode instructions: push a, push b, apply op. The operand stack replaces the destination register — the result is left on top rather than written anywhere named.

Except that AtlasLang then immediately writes it somewhere named. Every virtual register %d gets a synthetic local slot, so the actual emission is push, push, op, STORE into %d's slot — and every later use of %d becomes a LOAD from it. That is why the bytecode for print(1 + 2); is PUSH 1, PUSH 2, ADD, STORE 0, LOAD 0, PRINT, with a store immediately followed by a load of the same slot. A peephole pass would delete that pair in a moment; keeping it makes the correspondence between the IR and the bytecode exact and legible, which for a teaching implementation is worth more than six instructions.

The important claim is that this translation is *local*. Each IR instruction becomes a fixed short sequence, with no analysis and no lookahead, and the reason is that the IR already fixed an evaluation order. Emitting bytecode directly from the AST would mean deciding evaluation order during emission, which is possible but conflates two jobs — and it means there is no representation on which to have run an optimizer. That is the concrete argument for [[why-ir-exists]], and it is visible as the difference between two panels.

Bytecode is emitted from the pre-SSA IR, not from the optimized SSA. A phi node has no execution semantics — you cannot run a phi — so a real compiler leaves SSA before code generation, which is [[out-of-ssa]]. Here, leaving SSA is free: the pre-SSA form with its load/store slots is already exactly the shape a stack machine wants, because a stack machine's locals *are* named slots. The consequence to expect is that the Bytecode panel shows a different program from the Optimized SSA panel, and now you know why.

Below is the actual compilation and execution of let x = 4; print(x * 5);. Three slots: x for the user variable, and %0 and %1 for the two virtual registers the IR produced. Read the locals column and watch the round trips.

The pattern to notice is STORE immediately followed by LOAD of the same slot at instructions 1–2, 3–4 and 7–8. That is the virtual-register-to-slot mapping doing its work, and it is also the most obvious thing a peephole optimizer would remove — [[peephole-optimization]] in three instructions.

The other thing worth noticing is what the stack does. It never holds more than two values, because a stack machine's depth is the depth of the expression tree it is evaluating, not the number of live variables. That is a genuine property of the design: a program with a hundred locals and shallow expressions has a two-deep stack, which is why stack machines need no register allocator at all.

A CALL carries an arity. The VM pops that many arguments, pushes a new frame recording the callee, an instruction pointer, its own slot array, where to resume in the caller, and the stack depth to restore on return. RETURN pops a value, discards anything the callee left above its stack base, restores the caller's frame and pushes the result. That stack-base discipline is what stops a callee from leaking operands into its caller — and there is a test asserting exactly that, because a VM that leaks one value per call works fine until it does not.

Two limits are stated rather than hidden, because a simulator that conceals its limits teaches the wrong thing.

Integer arithmetic is JavaScript double arithmetic truncated toward zero. It does not wrap at 32 or 64 bits. AtlasLang therefore cannot demonstrate signed overflow, which is precisely where a real compiler's undefined-behavior reasoning lives — a C compiler may assume signed overflow does not occur and optimize on that assumption, and nothing here can show you that.

There is a step budget. A non-terminating program stops after 20,000 instructions with status steps-exhausted and an error saying so, rather than hanging the tab or reporting a plausible-looking number. Genuine non-termination is inexpressible here, which matters because it is the thing several static analyses in this domain are undecidable *about*.

The third limit is quieter: the trace is capped at 500 recorded steps while execution continues to the budget, so a loop running eight thousand times still finishes and prints, without producing a table nobody can read. The status field is the part to read; the trace is a sample.