Runtime Architecture

Overview

ilusm achieves pure self-hosting through a layered bootstrap process:

• Native bootstrap - A small compiled loader runs bytecode; stage‑0 C sources are maintainer-only and are not part of the public language bundle (Download).
• Self-Hosted Compiler - Complete compiler written in ilusm (lib/backend/compiler.ilu)
• Self-Hosted VM - Full virtual machine written in ilusm (lib/backend/ilusm_vm.ilu)

The goal: ilusm compiling ilusm running on ilusm, with only a thin native layer beneath the Ilusm sources you can read in lib/.

Bytecode Design

ilusm compiles to a compact bytecode format designed for efficient execution:

Instruction Format

Each instruction is a single byte opcode with optional operands:

[opcode] [operand1] [operand2] ...

Core Opcodes

Opcode	Name	Description
0x01	PUSH	Push constant onto stack
0x02	POP	Pop value from stack
0x03	ADD	Pop two values, push sum
0x04	SUB	Pop two values, push difference
0x05	MUL	Pop two values, push product
0x06	DIV	Pop two values, push quotient
0x07	PRINT	Pop value, output to stdout
0x08	JUMP	Unconditional jump to address
0x09	JUMP_IF	Conditional jump based on stack value
0x0A	CALL	Function call with arguments
0x0B	RET	Return from function
0x0C	HALT	Stop execution

Constants Pool

String literals and large numbers are stored in a constants pool section and referenced by index in instructions.

Virtual Machine

Stack Architecture

The VM uses a stack-based execution model:

• Operand stack for expression evaluation
• Call stack for function calls and returns
• Maximum stack depth configurable at runtime

Execution Loop

while (pc < code_length) {
    opcode = code[pc++];
    switch (opcode) {
        case OP_PUSH:
            stack_push(read_constant());
            break;
        case OP_ADD:
            b = stack_pop();
            a = stack_pop();
            stack_push(a + b);
            break;
        // ... other opcodes
    }
}

Error Handling

Runtime errors generate stack traces with:

• Function call chain
• Program counter positions
• Local variable values (when available)

Memory Management

Garbage collection and heap policy

Ilusm does not publish a single GC algorithm, pause budget, or baseline RSS that applies to every install. The running process combines a native bootstrap (binary-only for end users-no stage‑0 .c in the public tarball) with Ilusm bytecode and syscalls; how objects are retained and reclaimed is therefore an implementation detail of that stack, not a language-level constant you can read off a spec table.

For what you can depend on in code: the language has values, lists, objects, and strings; the runtime and lib/runtime/ sources describe how a conforming host is expected to cooperate. Ilusm-side heap helpers (for example in lib/runtime/mem_heap.ilu) may evolve; embedders can replace behavior-see comments there and the host contract.

Conceptual layout

Typical VM designs separate operand stack, call frames, heap-allocated values, constants, and bytecode. Exact layout and whether the host uses tracing GC, refcounting, malloc pools, or something else is host-specific-measure the ilusm process if you need numbers.

+------------------+
| Stack / frames   |
+------------------+
| Heap (values)    |
+------------------+
| Constants pool   |
+------------------+
| Bytecode         |
+------------------+

Arena-style use in Ilusm

For batch allocation patterns in Ilusm source, the stdlib includes modules such as arena and arn; they only help where the host exposes the right hooks. See also Performance → Memory and GC.

Host Interface

The runtime interfaces with the host system through well-defined syscalls:

Syscall Categories

• File System - __sys_read_file, __sys_write_file
• Network - __http_get, __http_post
• Process - __sys_run_command, __sys_get_env
• Crypto - __buf_new, __cry_hash
• JSON - __json_encode, __json_decode

Host Implementation

ilusm is designed to be self-hosting. The Python host is a temporary development aid:

• ilusm-min - C bootstrap for initial language features
• Self-hosted VM - Complete VM written in ilusm (lib/backend/ilusm_vm.ilu)
• Self-hosted compiler - Full compiler in ilusm (lib/backend/compiler.ilu)

The goal is pure self-hosting: ilusm compiling ilusm running on ilusm. Python is only used during development.

Bootstrap Process

ilusm bootstraps from minimal C to complete self-hosting:

Stage 1: Native bootstrap

1. A minimal stage‑0 seed is compiled from C; releases ship a binary entrypoint (see self-hosting).
2. That loader runs Ilusm bytecode (including the toolchain in ilusm.ilbc when present).
3. End users receive the installed executable, not the stage‑0 source.

Stage 2: Self-Hosting Bootstrap

1. Use C ilusm-vm to run lib/frontend/lex.ilu (lexer in ilusm)
2. Run lib/frontend/prs.ilu (parser in ilusm)
3. Execute lib/backend/compiler.ilu (compiler in ilusm)
4. Bootstrap lib/backend/ilusm_vm.ilu (full VM in ilusm)

Stage 3: Pure Self-Hosting

1. ilusm compiler compiles ilusm source
2. ilusm VM executes ilusm bytecode
3. Complete language self-sufficiency achieved

Verification

Bootstrap verification tests:

• tests/smoke_vm.ilu - C bootstrap functionality
• tests/core.ilu - Complete self-hosted language suite

Goal: Pure self-hosting - ilusm compiling ilusm running on ilusm.

Performance and memory numbers

Fixed timings, “base” RSS, instruction/sec, and GC pause claims were removed from this page-they read like guarantees and implied everyone could verify them against published C, which is not how the public bundle works. Treat memory and GC as measure on your install (see Performance).