Playground
(Lispex)
KOENRU

Install an Optional Extra Engine

Fetch an exact official Topaz virtual machine or ahead-of-time compiler companion, or install a reviewed local 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 interpreter that reads your source directly. It remains the default, the semantic reference, and the way back when something else fails. Install a companion only when you deliberately need the exact Topaz virtual machine or an admitted Topaz compiler that builds ahead of time.

Fetch an official companion

Native contains an exact, immutable route catalog. The current catalog has two macOS ARM64 entries. They are the Topaz 5.11 virtual machine and the exact Topaz 5.11 compiler that Lispex uses to build ahead of time. 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, the one accepted 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 a product compiled ahead of time.

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 lispex.route-catalog/v1 file in its one accepted form, together with 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 hash, archive hash 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 hash with the hash delivered alongside your exact catalog. The command reads local files only. On success it prints the same receipt that it writes here.

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

installation.json is a lispex.route-installation/v1 receipt in its one accepted form. 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 ahead-of-time 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 both a complete admitted installed product and a complete build check. Linux, Windows, and macOS Intel compiler cells are absent. A compiler companion does not include Rust, a linker, a platform development kit, 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 lock and diagnose it. A lock is a small file that records which installed product you chose, and it records no filesystem path.

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 compiled product, take an inventory of both optional engines 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 four-way comparison under fixed limits, 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 virtual machine installation or the finished compiled product. Supply its new absolute root to routes doctor and routes run, and 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, measurement under fixed limits, locked execution, and relocation together.

What the archive is allowed to contain

Lispex accepts only one uncompressed stored-ZIP shape, fixed down to the byte. 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 hash 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 byte-form contract was rejected, and exit 3 means local input and output, a resource bound, or no-clobber publication failed. A failure does not try another entry, target, version, path, or way of running.

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 be used as Vouch evidence or to reach a decision gate. The receipt records automatic_fallback:false. That is a boundary, not a request to try a different engine.

Keep going

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

Choosing Where to Run · Native CLI · Build a Product Compiled Ahead of Time