| # Machine runtime guide |
|
|
| The Python VM, CPython bytecode utilities, x86 code generator, and native assembly are separate execution layers. |
|
|
| | Source | Responsibility | |
| |---|---| |
| | [vm_executor.py](../src/runtime/machine/vm_executor.py) | Stack VM, opcodes, assembler, debugger, in-memory WORM log | |
| | [binary_ir.py](../src/runtime/machine/binary_ir.py) | Binary intermediate representation | |
| | [bytecode_assembler.py](../src/runtime/machine/bytecode_assembler.py) | CPython bytecode assembly; version-sensitive | |
| | [marshal_codec.py](../src/runtime/machine/marshal_codec.py) | Python marshal/code-object encoding | |
| | [machine_code_gen.py](../src/runtime/machine/machine_code_gen.py) | x86-64 generation utilities | |
| | [ctypes_bridge.py](../src/runtime/machine/ctypes_bridge.py) | Native interop | |
| | [native/asm/](../native/asm/) | NASM runtime and kernel sources | |
| | [native/dispatcher/](../native/dispatcher/) | C IPC dispatcher and Makefile | |
|
|
| ## Local example: stack arithmetic |
|
|
| Run this from a file in the repository root: |
|
|
| ```python |
| 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](../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](../native/asm/build.sh) and the [dispatcher Makefile](../native/dispatcher/Makefile) before running them. CPython bytecode formats depend on the interpreter version; success under one version does not establish portability. |
|
|
