Choosing Where to Run

How to reason about it

• Use the Playground for zero-install evaluation, the public WebAssembly build for browser embedding, npm for Node evaluation plus authenticated Vouch verify, inspect, and replay, and Native for signed issuance, current verifier re-execution, and the local decision gate.
• Pin package or binary identity in automation rather than relying on a mutable latest channel.
• Test the resource profile you deploy. Equal language semantics do not imply equal recursion ceilings.
• Native and npm expose the same exact identities, the same policy create and check commands, and the same raw, unpinned, and pinned authentication through shared Rust. Native alone can issue and consume request-bound evidence for re-execution or a gate. The public WebAssembly build and the Playground expose no Vouch identity, authentication, or policy tooling.
• Use Native or npm for named-path Lispex Image commands. Use the Playground for a zero-install, browser-local workflow to create, open, preview, recover, download, and run an image, or embed the public WebAssembly image API directly. These choices share one Rust codec and add no Vouch authority.
• Native can use a proved image throughout the Vouch chain. npm can derive the same source identity, create the same policy, and emit the same authentication report from an image, but still cannot issue, re-execute, gate, or turn a saved report into evidence. The public WebAssembly build and the Playground perform local image operations without Vouch authentication.
• Use Native when you need to build, strictly validate, or inspect Core IR in its one accepted form. These commands expose resolved meaning without executing it. npm, the public WebAssembly build, and the Playground do not accept Core IR bytes.
• Use Native when you need a bytecode artifact in its one accepted form or an explicit --engine vm run. Tree remains the default Rust engine, and a requested virtual machine failure never falls back. No other product reads or runs bytecode.
• On Native macOS ARM64, use --engine topaz --topaz-vm ROOT only when you deliberately want the exact separately installed Topaz 5.11 virtual machine. Use compare-vms for explicit differential evidence. That extra engine is not bundled, discovered, available on other platforms, or admitted into Vouch.
• On Native macOS ARM64, use lispex aot when you want an executable with no source inside it, produced from deterministic readable Topaz. You must pass the exact installed Topaz compiler and Rust tool directory at build time. Installed products run without either source tree and never fall back to a virtual machine or to the tree run.
• Use Native compare-routes after building the matching compiled product when you need one no-clobber diagnostic receipt covering the tree run, the Rust virtual machine, the Topaz virtual machine, and the product compiled ahead of time. It derives the request once, rejects mismatched products before execution, and reports semantic and comparable-resource differences separately.
• Use Native vouch compiled only when an existing request-bound Vouch flow must additionally require exact source-derived artifact integrity and current agreement from the Rust virtual machine. It is explicit and never replaces source pins, authentication, or the agreement between the tree run and the meaning record.

Check a Native installation before choosing

Start with the compatible tree run. When you intentionally use another Native way of running a program, make the choice inspectable.

On macOS ARM64, Native can acquire its exact official Topaz virtual machine or ahead-of-time compiler companion with lispex routes fetch. If a provider gave you a separate exact local catalog and archive, use offline lispex routes install. Both paths write a receipt without a filesystem path beside the closed product root, and neither registers nor selects it. Follow Install an Optional Extra Engine.

lispex routes inventory
lispex routes inventory --topaz-vm /absolute/topaz-vm \
  --aot-product /absolute/aot-product
lispex routes lock --route rust-vm --out route.json
lispex routes doctor --selection route.json

inventory never searches PATH, a repository copy, the environment, or the network. It reports the tree run and the Rust virtual machine as built in, and reports each external engine as not-supplied, ready, or invalid. lock writes one no-clobber lispex.route-selection/v1 file in its one accepted form. The lock contains identities but no filesystem path, so doctor requires the external product's absolute path again. These documents select or diagnose execution only. They cannot become Vouch evidence or a gate grant.

For a local measurement under fixed limits, provide both exact external products and keep the semantic receipt separate from timing.

lispex routes measure \
  --topaz-vm /absolute/topaz-vm \
  --aot-product /absolute/aot-product \
  --receipt comparison.json \
  --measurement timing.json \
  --samples 3 \
  --input input.datum \
  rule.lspx

The nanosecond samples belong to that host and run. They help compare local cost, but they are not a language-equivalence, security, or cross-machine performance claim.

To execute a locked choice, pass the lock and the source. External products still need their absolute path.

lispex routes run --selection route.json rule.lspx
lispex routes run --selection topaz.json \
  --topaz-vm /absolute/topaz-vm \
  --input input.datum \
  rule.lspx

Tree remains the compatible default, the reference, and the way back when something else fails. It needs no advanced product workflow, is available through the ordinary Rust product journey, and had the lowest startup cost in the maintained local sample. Use the Rust virtual machine for verified bytecode and explicit machine accounting. Choose the Topaz virtual machine or the compiled product only for their named differential or deployment purpose.

Runtime capabilities

A common mistake

None of the Native, npm, WebAssembly, or Playground Rust products is an independent backend witness. The Rust tree run and the Rust virtual machine share one lineage. The Topaz virtual machine is a structurally separate source implementation, but its executable is compiled by Topaz Rust Stage 0, so agreement is still limited evidence rather than proof. The four-way comparison discloses this shared and separate lineage instead of turning agreement into proof. Unavailable commands and a failed request must not be simulated or silently downgraded.

Keep going

Once you have picked a product, follow the learning path, or go on to building a product compiled ahead of time and running verified bytecode.

Learning Path · Build a Product Compiled Ahead of Time · Run Verified Bytecode