# The Aurora VM

Every program runs on Aurora, a bytecode VM written in C11. The VM is part of the `agentica` binary; bytecode files end in `.agcb`.

## From source to bytecode

The `agentica` binary has two parts. The front end (lexer, parser, module linker, checker, lowering), written in Agentica and compiled to bytecode itself, passes the checked program as bytecode in memory to the VM, which runs it in a new runtime of the same process. You can run the steps yourself (flags: [Command line](https://www.agentica-lang.com/agentica/cli/index.md#options)):

```sh
agentica compile file.agc -o file.agcb   # write bytecode
agentica run -- file.agcb                # run it; `run` must be the first word
```

Bytecode runs only on the VM of the same Agentica version.

## Inside the VM

- **Values.** Values never change in place; handles (tasks, channels, files, sockets, processes) hold the only mutable state.
- **Loader.** A `.agcb` file is untrusted. The loader checks all of it before anything runs (version, strings, indexes, registers, jump targets, a step check in every loop and every calling function). A file over 256 MiB is `agentica run: cannot read <file>`, any other bad file `agentica run: invalid bytecode: <reason>`; both exit with code 2.
- **Interpreter.** One loop runs instructions. Calls push frames on the task's own stack. A tail call (`return f(...)` to a user function) reuses the frame.
- **Tasks.** Tasks run in turns of 2000 steps on `--schedulers N` threads (one per logical core by default), so a busy loop does not starve the others.
- **I/O and waits.** A blocking call (file, socket, `Task.sleep`) parks only its own task. A print goes into a 64 KiB buffer per stream, so a slow reader stalls only the tasks that print. The end-of-run flush waits at most 30 s by default (`--flush-timeout`). A waiting `Channel.send` or `recv` parks its task until a value or a slot is ready. A timed `Task.await` waits on the task and a timer, and the first to wake decides.
- **JIT.** A JIT for x86-64 and arm64 (Linux and macOS), on by default ([`--jit`](https://www.agentica-lang.com/agentica/cli/index.md#options)), compiles hot functions with loops, and small functions without a loop that they call. Supported arithmetic, reads, text operations and jumps run as machine code. Other machines run the interpreter.
- **Limits.** Steps and memory have no limit unless you set `--max-steps` or `--max-heap` ([Options](https://www.agentica-lang.com/agentica/cli/index.md#options)). Calls nest at most 10,000 deep per task, then `RUNTIME-STACK-OVERFLOW` with the call stack (a repeated function on one line with its count). A tail call adds no depth.
- **Maps and lists.** `Map` is a persistent HAMT that keeps insertion order; `Map.put` copies only the path to its key. `List` is a persistent vector of 32 children per node plus a small tail: indexing takes at most four steps for a million items, n pushes cost O(n), and a list of only Ints or only Floats keeps 8 bytes per item. `take`, `drop` and `reverse` are O(n), `sort` O(n log n).
- **JSON.** A parsed object keeps each key once and encodes keys sorted, so `JSON.encode(JSON.parse(text))` is canonical.
- **Standard modules.** The `std/` modules are written in Agentica, embedded in the binary and linked into your bytecode like your own modules.

## What it is built on

Pinned git submodules in `vm/third_party/`, all built into the release binary, which needs no system library beyond the C library. A default Linux `make` links the system OpenSSL 3, libgc and zlib instead (see [Getting started](https://www.agentica-lang.com/agentica/getting-started/index.md)). The release archives ship the license notices in `licenses/`.

| Library | Purpose | License |
|---|---|---|
| Boehm GC (bdwgc) | Garbage collector for program values | Boehm-GC license (permissive) |
| yyjson | Reads JSON text for `JSON.parse` | MIT |
| libuv | Event loop, file and socket I/O, timers, processes and the thread pool | MIT, with BSD-2-Clause and ISC parts |
| OpenSSL 3.5 | TLS for `TLS.connect`, `TLS.listen` and HTTPS | Apache-2.0 |
| picohttpparser | Parses HTTP start lines and headers | MIT (dual MIT or Perl license) |
| libffi | Calls C functions of `extern` blocks (Linux, macOS and Windows x64) | MIT |
| zlib | DEFLATE, zlib and gzip codec for `Zlib` | zlib license |

The Unicode tables (case mapping, printing) are generated from the Unicode Character Database into the VM source, under the Unicode License v3.
