Where Your Program Runs

Result: name the four execution routes, explain which one you have been using all along, and predict what happens when a requested route is not available.

What you need to know: how to run a .lspx file. The First Program lesson covers that. Nothing on this page requires installing anything new.

You have been using a route all along

Every time you ran a program like this

lispex rule.lspx

you used the tree interpreter. It is built into the ordinary Lispex product, written in Rust, and it walks your source directly. It is the default, the semantic reference, and the recovery route. If you never touch another route, you are not missing anything. The language is complete on this route alone.

The four routes

The same program can run four ways.

1. Tree. The built-in reference interpreter. Reads your source and evaluates it directly. Always present, no setup.
2. Rust VM. Also built in. Runs a canonical bytecode artifact that Native builds and validates from your source. You ask for it explicitly with --engine vm.
3. Topaz VM. An exact, separately installed Topaz 5.11 virtual machine on macOS ARM64. It is not built into the Native binary. You install it separately and pass its absolute product location when a command needs it.
4. AOT. A source-free executable built ahead of time from your program. Building one requires the exact installed Topaz compiler and a Rust tool directory. The installed product then runs without any source tree.

A route is an implementation of the same Lispex language, not a dialect. The routes are designed to preserve the same meaning. Comparison commands check whether their observations agree for one exact request; one agreement is not a proof that every program behaves identically everywhere.

Two honesty rules

Two rules make the routes trustworthy, and both are easy to state.

No discovery during execution. Execution, inventory, diagnosis, and comparison commands do not search your PATH, checkout, environment, or the network. An external route participates only when you provide its exact location. The separate routes fetch command can acquire one exact official companion, but fetching neither selects nor runs it.

No fallback. If you request a route and it fails or is missing, the run stops with an error. It never quietly switches to another route. A result labelled Topaz VM was produced by the Topaz VM or not produced at all.

The two rules protect the same thing. When a run succeeds, you know exactly which route produced the answer.

Checking that routes agree

After installing the exact Topaz VM and building a matching AOT product, Native can run all four routes for one exact request and write one no-clobber diagnostic receipt.

lispex compare-routes \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product \
  --aot-product /absolute/products/rule-aot \
  --receipt route-comparison.json \
  rule.lspx

This command requires both exact external products. A missing or mismatched product fails instead of shrinking the comparison to whichever routes happen to be available. The receipt reports the four observations. Agreement is evidence for that source, input, product set, and resource boundary. It is not a proof that the routes are equivalent everywhere, and the receipt never claims otherwise.

Try this

Suppose a teammate's script requests the Topaz VM route, and the machine it runs on has no Topaz VM installed. Predict what happens before opening the answer.

Ready to move on when

You can name the four routes, say which one runs with no setup, and state both honesty rules in your own words.

When you want to choose a route for real work, continue with Choosing a Runtime Surface. When you want to install a companion, follow Install an Optional Native Route.