docs/MACHINE_CODE.md

Machine runtime guide

The Python VM, CPython bytecode utilities, x86 code generator, and native assembly are separate execution layers.

Source	Responsibility
vm_executor.py	Stack VM, opcodes, assembler, debugger, in-memory WORM log
binary_ir.py	Binary intermediate representation
bytecode_assembler.py	CPython bytecode assembly; version-sensitive
marshal_codec.py	Python marshal/code-object encoding
machine_code_gen.py	x86-64 generation utilities
ctypes_bridge.py	Native interop
native/asm/	NASM runtime and kernel sources
native/dispatcher/	C IPC dispatcher and Makefile

Local example: stack arithmetic

Run this from a file in the repository root:

from src.runtime.machine.vm_executor import SovereignVM, VMInstruction, VMOpcode

program = [
    VMInstruction(VMOpcode.PUSH, 2),
    VMInstruction(VMOpcode.PUSH, 3),
    VMInstruction(VMOpcode.ADD),
    VMInstruction(VMOpcode.HALT),
]
vm = SovereignVM(program)
result = vm.run(max_steps=10)
assert result == 5
print(result)

run(max_steps=...) returns the top of the stack and raises VMError when the step budget is exhausted. get_stack(), get_registers(), and stats() expose inspection data.

This example executes Python VM instructions. It does not compile or execute NASM, CUDA, or generated x86 machine code.

Validation

tests/stress_test_no_drift.py exercises deterministic VM and routing operations. Read its assertions and backend selection before interpreting its output. A repeated arithmetic result is not evidence of deterministic external model inference.

Native builds require their own assembler/compiler, OS/ABI compatibility, and tests. Inspect build.sh and the dispatcher Makefile before running them. CPython bytecode formats depend on the interpreter version; success under one version does not establish portability.