Playground
(Lispex)
KOENRU

Install an Optional Native Route

Fetch an exact official Topaz VM or AOT compiler companion, or install a reviewed local route archive, without discovery, fallback, or Vouch authority.

Start with the ordinary runtime

You do not need a companion to run Lispex:

SH
lispex rule.lspx

This uses the built-in Rust tree interpreter. It remains the default, semantic reference, and recovery route. Install a companion only when you deliberately need the exact Topaz VM or an admitted Topaz AOT compiler.

Fetch an official companion

Native contains an exact, immutable route catalog. The current catalog has two macOS ARM64 entries: the Topaz 5.11 VM and the exact Topaz 5.11 compiler used by Lispex AOT. Choose a new absolute destination:

SH
lispex routes fetch \
  --route topaz-vm \
  --target aarch64-apple-darwin \
  --out /absolute/tools/lispex-topaz-vm

The command accepts no URL, mirror, channel, version, registry, or catalog override. It follows no redirect and checks the response length, SHA-256, canonical stored-ZIP shape, every installed file, and the closed Topaz product identity before publishing the destination. An unsupported target fails before network access.

Fetching does not register or select the route. Continue at Use the product explicitly and pass /absolute/tools/lispex-topaz-vm/product yourself.

Fetch the compiler companion separately when you intend to build an AOT product:

SH
lispex routes fetch \
  --route aot-compiler \
  --target aarch64-apple-darwin \
  --out /absolute/tools/lispex-aot-compiler

Its closed product contains the exact compiler and release manifest, not a Rust toolchain. aot build still requires both the installed compiler executable and a caller-selected absolute Rust tool directory:

SH
lispex aot build \
  --source rule.lspx \
  --topaz-compiler /absolute/tools/lispex-aot-compiler/product/bin/topaz-bin \
  --rust-tool-bin /absolute/rust/bin \
  --out /absolute/products/rule-aot

Install a handed-off archive offline

Obtain these two immutable local files from the same provider handoff:

  • a canonical lispex.route-catalog/v1 file and its exact SHA-256;
  • the stored-ZIP archive named by the exact route and target entry.

The catalog is a closed allowlist. It names the provider product, language mode, manifest digest, archive digest and length, and every installed file. Lispex does not search a checkout, PATH, a package registry, the network, or another catalog.

Install one exact entry

Choose a new absolute destination that does not exist:

SH
lispex routes install \
  --route topaz-vm \
  --target aarch64-apple-darwin \
  --catalog /absolute/handoff/routes.json \
  --catalog-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --archive /absolute/handoff/topaz-vm-aarch64-apple-darwin.zip \
  --out /absolute/tools/lispex-topaz-vm

Replace the sample digest with the digest delivered alongside your exact catalog. The command reads local files only. On success it prints the same canonical receipt written to:

/absolute/tools/lispex-topaz-vm/
├── installation.json
└── product/

installation.json is a canonical lispex.route-installation/v1 receipt. It contains no absolute path or timestamp, so moving the unchanged directory preserves its identity. The product/ directory remains closed for the existing exact product validator.

For an admitted AOT compiler archive, change --route:

SH
lispex routes install \
  --route aot-compiler \
  --target aarch64-apple-darwin \
  --catalog /absolute/handoff/routes.json \
  --catalog-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --archive /absolute/handoff/lispex-topaz-aot-compiler-aarch64-apple-darwin.zip \
  --out /absolute/tools/lispex-aot-compiler

Only the macOS ARM64 compiler has a complete admitted installed-product and AOT build court. Linux, Windows, and macOS Intel compiler cells are absent. An AOT compiler companion does not include Rust, a linker, an SDK, or system libraries, and Lispex never substitutes another target.

Use the product explicitly

Installation never registers a route or changes the default. Supply the closed product root again:

SH
lispex routes inventory \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product

You can then create a path-free lock and diagnose it:

SH
lispex routes lock \
  --route topaz-vm \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product \
  --out topaz-route.json

lispex routes doctor \
  --selection topaz-route.json \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product

If you relocate the installation, pass the new absolute product/ path. Neither the lock nor the installation receipt remembers a filesystem path.

Run the complete installed journey

After building the AOT product, inventory both optional routes and create one lock for each:

SH
lispex routes inventory \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product \
  --aot-product /absolute/products/rule-aot

lispex routes lock --route aot \
  --aot-product /absolute/products/rule-aot \
  --out aot-route.json

Use routes measure --samples 1 for one bounded four-route comparison, then execute only the chosen lock:

SH
lispex routes run \
  --selection aot-route.json \
  --aot-product /absolute/products/rule-aot \
  --input input.datum \
  rule.lspx

You can move the VM installation or finished AOT product. Supply its new absolute root to routes doctor and routes run; do not rewrite the lock. Doctor revalidates the bytes at that root, while the unchanged lock proves that selection identity never depended on its former path. The maintained portable route journey shows fetch, build, inventory, locks, doctor, bounded measurement, locked execution, and relocation together.

What the archive is allowed to contain

Lispex accepts only one canonical, uncompressed stored-ZIP shape. It rejects compression, Zip64, descriptors, encryption, timestamps, extras, comments, directories, duplicate or unsorted names, path traversal, absolute paths, backslashes, symbolic links, special files, excess files or bytes, and every digest mismatch. It writes through a private sibling stage and publishes only to a destination that still does not exist.

Exit 2 means command usage is wrong, exit 1 means an identity or canonical contract was rejected, and exit 3 means local I/O, a resource bound, or no-clobber publication failed. A failure does not try another entry, target, version, path, or execution route.

Security boundary

A valid catalog and installation receipt establish exact byte integrity for installation. They do not establish that the provider is trustworthy, the program is correct, the route agrees with Rust, or an external action is authorized. Catalogs, archives, receipts, manifests, and route results cannot enter Vouch evidence or a decision gate. The canonical receipt records automatic_fallback:false; this is a boundary, not a request to try a different route.

Keep going

Use the runtime chooser for the simple default and the route doctor before any locked advanced execution.

Choosing a Runtime · Native CLI · Topaz AOT