# Kinds of Execution Engines

> Find the implementation, supported procedures, and comparison data for each execution method.

Canonical page: https://www.lispex.com/v1.20/en/docs/reference/runtime-backends

Version check: this file describes v1.20. Fetch https://www.lispex.com/version.json before treating it as the current manual.

Compare Lispex implementations to investigate differences in results, output, and diagnostics.
Use the implementation table to choose a comparison for your program.
These implementations are called runtime implementations.

Native 1.20.0 includes the Rust interpreter and Rust VM.
LIL and LIT comparisons require the separately installed runners described below.
For ordinary rule execution, start with [Run Lispex in Your Application](/en/docs/guides/choosing-runtime).

## Choose the comparison

| Task                                             | Input                            | Required products                       |
| ------------------------------------------------ | -------------------------------- | --------------------------------------- |
| Compare source interpreters with `compare`       | Source and the selected backends | Native and installed LIL or LIT runners |
| Compare tree and bytecode with `compare-engines` | Source                           | Native                                  |

Use the [comparison reference](/en/docs/reference/backend-observation-matrix) to choose the report and read its outcome.
[Bytecode and Deployment](/en/docs/guides/verified-bytecode) covers saving and running bytecode.

## Run the same source with two engines

Save this complete program as `answer.lspx`.

```lispex
(+ 20 22)
```

Run it with the default Rust interpreter.

```sh
lispex answer.lspx
```

**Output**

```text
42
```

Now select the Rust virtual machine, or VM. A VM executes prepared instructions called bytecode.

```sh
lispex run --backend rust --engine vm answer.lspx
```

**Output**

```text
42
```

Both commands exit with status `0` and create no files.
For the VM command, Native builds and checks the bytecode before executing it.
The default engine is `tree`, the interpreter that evaluates the source's syntax tree.

<a id="interpreter-implementations" />

## Source interpreters

LIL is a Lispex interpreter written in Lispex.
It implements its own reader, normalization, and evaluation while running on the Rust interpreter.
Its Native and WASM forms use the same LIL source.

LIT is a Lispex interpreter written in Topaz.

| Implementation   | Procedure entries               | Availability                                                 |
| ---------------- | ------------------------------- | ------------------------------------------------------------ |
| Rust interpreter | 205/205                         | Included in Native, npm, and ordinary browser evaluation     |
| LIL              | 205/205                         | Requires an installed runner and its backend registry entry  |
| LIT              | See the versioned records below | Requires a Topaz-owned runner and its backend registry entry |

Native reports installed products through `lispex backends --json`.
A missing runner is reported as unavailable.
An explicit LIL or LIT request keeps that selection and reports a failure if the product cannot run.

### Read LIT support by contract version

| Record                                 | Supported procedure entries | Meaning                                                                     |
| -------------------------------------- | --------------------------- | --------------------------------------------------------------------------- |
| Initial LIT implementation record      | 84/205                      | The remaining 121 entries reported their unsupported status                 |
| Later Topaz implementation contract v7 | 205/205                     | The contract's `current` count, with `status: complete`                     |
| Lispex consumer contract v2            | 204/205                     | The consumer's recorded baseline, with `status: implementation-in-progress` |

These records describe different stages and consumers.
The v7 baseline still contains 84, while its current count is 205.
Installing Native does not install the LIT runner or synchronize these contracts.
Each count refers to entries in the 205-row built-in procedure registry, whose entries carry `profile-required`.
For a comparison, read the capability result of the exact installed runner.

<a id="what-each-engine-executes" />
<a id="core-ir-and-bytecode" />

## Bytecode implementations

Rust VM (`lispex-rust-vm/v1`) is included in Native.
It runs bytecode produced by the Rust source frontend and Core IR compiler.

Core IR is an intermediate representation that resolves name references.
Native converts the complete current language profile to the prescribed `lispex.core-ir/v1` format and validates it.
Inspection shows variable cells, captured variables, tail positions, requirements, source locations, and identifiers.

The compiler converts validated Core IR to `lispex.bytecode/v1`.
The verifier checks the bytecode before creating VM state.
Rust VM implements all 205 built-in procedure entries.
The 18 entries that call user procedures use iterative VM state machines to manage those calls.

<a id="comparing-executions-and-using-vouch" />

## Read results and resource usage

Comparison reports record results, resource usage, and source and producer information in separate fields.
The selected execution method keeps its own error and resource status.
Reports are written atomically to a new path.

Read semantic differences separately from resource differences.
Semantic observations include status, primary code, message, output, values, warnings, and diagnostics.

| Compared products     | Comparable resource observations |
| --------------------- | -------------------------------- |
| Rust tree and Rust VM | Output bytes and completed roots |

The tree interpreter uses its own depth model.
Source-interpreter comparisons check the resource outcome and require all five usage fields to be present.
They retain each implementation's usage counts separately when comparing outcomes.
Procedure support counts and resource usage counters answer different questions.
Use the [resource reference](/en/docs/manual/determinism-resources) for counter definitions.

### Identifying the product in a comparison

| Recorded information       | What it identifies                                                   |
| -------------------------- | -------------------------------------------------------------------- |
| Runtime implementation     | Interpreter family and versioned execution method                    |
| Invocation                 | Reproducible command or framed request protocol                      |
| Artifact identifier        | Exact executable, WASM, and connecting-code bytes                    |
| Source and producer record | Declared source and how the product was built                        |
| Resource profile           | Named limits and reported usage counters                             |
| Compared cases             | Exact input collection, interpreter family, target, and host variant |

These fields let you determine which product and execution conditions produced a comparison.
[Bytecode and Rust VM](/en/docs/reference/bytecode-vm) describes the instruction format and execution details.

## Read earlier comparison records

The historical comparison record covers 144 named cases.
It identifies the Rust, LIL, and LIT executables used, their resource profiles, results, and reruns.
Those cases describe the inputs that were executed.
The procedure tables describe implementation coverage against a different denominator.

Keep the original report with its input, catalog, products, and version-matched tools.
See [Compare Engine Results](/en/docs/reference/backend-observation-matrix) for the historical record's scope.

## Related product features

For application calls, [the evaluator reference](/en/docs/reference/bounded-evaluator) describes the separate decision and full-profile evaluators.
For trusted-source evaluation and fixed comparisons from an editor, see [Native MCP](/en/docs/reference/mcp).

### Compiled Lispex Vouch

Compiled Lispex Vouch uses the Rust VM.
Native creates a source-bound `lispex.vouch-compiled-artifact/v1` file and authenticates the request.
It derives Core IR and bytecode again from the exact source selected by the recipient.
It records current tree and Meaning agreement, compares the verified Rust VM result, and passes the result to the local gate.

## Interactive output across products

Native, npm, public WASM, and the Playground use the same interactive output rules.
They read the entire source and expand shorthand into core forms before evaluation.
They then display explicit output and each successful form's value in order.

| Completion             | Output and status                                                |
| ---------------------- | ---------------------------------------------------------------- |
| Success                | Output and values, status `0`                                    |
| Ordinary runtime error | Output already produced by earlier forms is retained, status `1` |
| Resource limit reached | Empty output, one resource diagnostic, status `2`                |

Browser results expose `output`, `diagnostics`, `ok`, and `exit_status`.
[Input, Output, and Permissions](/en/docs/manual/io-capabilities) shows the output behavior.

Native also supplies formatting and the local MCP authoring service.
VS Code and Open VSX extensions delegate Format Document to the installed Native binary.
MCP uses local standard input and output for language reference, the procedure registry, trusted-source evaluation, diagnostics, and fixed engine comparisons.
Its evaluator applies declared byte and time limits.
See the [CLI reference](/en/docs/reference/cli) for commands and results.