Choosing Native, npm, WASM, or Playground

How to reason about it

• Use Playground for zero-install evaluation, public WASM 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, policy create/check, and raw/unpinned/pinned authentication through shared Rust. Native alone can issue and consume request-bound evidence for re-execution or gate; public WASM and 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 WASM 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 promote a report. Public WASM and Playground perform local image operations without Vouch authentication.
• Use Native when you need to build, strictly validate, or inspect canonical Core IR. These commands expose resolved meaning without executing it. npm, public WASM, and Playground do not accept Core IR bytes.
• Use Native when you need a canonical bytecode artifact or an explicit --engine vm run. Tree remains the default Rust engine, and a requested VM failure never falls back. No other product surface 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 VM. Use compare-vms for explicit differential evidence. The route is not bundled, discovered, available on other platforms, or admitted into Vouch.
• On Native macOS ARM64, use lispex aot when you want a source-free executable 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 VM or tree.
• Use Native compare-routes after building the matching AOT product when you need one no-clobber diagnostic receipt for tree, Rust VM, Topaz VM, and AOT. 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 Rust VM agreement. It is explicit and never replaces source pins, authentication, or tree/Meaning agreement.

Check a Native installation before choosing

Start with the compatible tree route. When you intentionally use another Native route, make the choice inspectable:

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 checkout, the environment, or the network. It reports tree and Rust VM as built in, and reports each external route as not-supplied, ready, or invalid. lock writes one canonical, no-clobber lispex.route-selection/v1 file. The lock contains identities but no filesystem path; doctor therefore 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 bounded local measurement, 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, reference, and recovery route: 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 Rust VM for verified bytecode and explicit machine accounting. Choose Topaz VM or AOT only for their named differential or deployment purpose.

Runtime capabilities

A common mistake

None of the Native, npm, WASM, or Playground Rust surfaces is an independent backend witness. Rust tree and Rust VM are same-lineage. The Topaz VM is a structurally separate source implementation, but its executable is compiled by Topaz Rust Stage 0; agreement is still bounded evidence rather than proof. The four-route court discloses this shared and separate lineage instead of turning agreement into proof. Unavailable commands and a requested route failure must not be simulated or silently downgraded.

Keep going

Once the workflow is comfortable, check the runtime chooser before moving it into a local tool or deployment.

Learning Path · Compile to Topaz AOT · Run Verified Bytecode