Run Verified Bytecode

Prepare a rule and an input

Save this as refund-window.lspx.

(define (decide days)
  (if (<= days 30) 'refund 'review))

(decide input)

Save the single input datum as request.lspx.

14

input is not a file or environment lookup. It is an explicit requirement recorded in Core IR and bytecode, then supplied by the command below.

Build Core IR, then bytecode

lispex core-ir build \
  --source refund-window.lspx \
  --out refund-window.lpxir

lispex bytecode build \
  --ir refund-window.lpxir \
  --out refund-window.lpxbc

The first command resolves names, cells, captures, tail positions, and source anchors without executing the rule. The second command lowers that Core IR to lispex.bytecode/v1, verifies the result, and writes a new binary artifact. Neither command overwrites an existing destination.

Inspect or validate before running

lispex bytecode inspect --bytecode refund-window.lpxbc
lispex bytecode validate --bytecode refund-window.lpxbc

inspect prints identities, table counts held under fixed limits, requirements, opcode counts, root anchors, and source-map coverage. validate is the quieter automation boundary. It strictly decodes, verifies, re-encodes, and accepts only the one byte representation the format allows.

Both commands establish canonical bytecode integrity. Signed distribution identifies the producer, application policy approves the rule, and Vouch binds the consumer request and current decision.

Run only after verification

lispex bytecode run \
  --bytecode refund-window.lpxbc \
  --input request.lspx

refund

The Native CLI verifies the complete artifact before it creates any virtual machine state. Malformed bytes fail before input use, output, primitive dispatch, or a single machine step. If the artifact declares input, omitting --input fails, and supplying input to an artifact that does not declare it also fails.

One stdin stream cannot carry both inputs. This call is rejected.

lispex bytecode run --bytecode - --input -

Use a named file for either the bytecode or the datum instead.

Run the same artifact in the Topaz virtual machine

Rust is built in and remains the default. On macOS ARM64, you can explicitly select the exact admitted Topaz 5.11 product.

lispex bytecode run \
  --engine topaz \
  --topaz-vm /absolute/path/to/aarch64-apple-darwin \
  --bytecode refund-window.lpxbc \
  --input request.lspx

The product root must be an absolute path to the separately installed lispex-topaz-vm/v1 product. Lispex checks its manifest, Topaz artifact, executable, wrapper, managed files, compiler/source lineage, target, resource contract, and zero-fallback declaration. It never searches PATH, a sibling checkout, the network, or an older installation. A missing, changed, timed-out, or malformed Topaz product is reported as a failure of that way of running, and Rust is not retried.

Select the virtual machine for source

For a self-contained source file, use the shorter form.

lispex run --backend rust --engine vm rule.lspx

tree remains the default.

lispex run --backend rust --engine tree rule.lspx

An explicit vm request never retries through tree. --engine belongs only to the Rust backend. Combining it with another backend such as LIL or LIT, or with an external backend registry, is a usage error.

Compare both Rust engines

lispex compare-engines \
  --receipt tree-vm.json \
  rule.lspx

The atomically published report records exact source, Core IR, and bytecode identities, both semantic observations, mismatch axes, virtual machine resource measurements, and the fallback count. The report identifies the shared Rust values and primitive leaves and serves as regression evidence for the named source and request.

To compare the two bytecode virtual machines instead, use this command.

lispex compare-vms \
  --topaz-vm /absolute/path/to/aarch64-apple-darwin \
  --receipt rust-topaz.json \
  rule.lspx

This derives bytecode once, runs Rust and Topaz explicitly, and compares status, output, values, warnings, diagnostics, resource observations, and completed roots. The report records both the structurally separate Topaz source and the Topaz Rust Stage 0 producer identity as differential route evidence.

When you have also built the matching product compiled ahead of time, compare every Native way of running it.

lispex compare-routes \
  --topaz-vm /absolute/path/to/aarch64-apple-darwin \
  --aot-product /absolute/path/to/refund-window-aot \
  --receipt four-routes.json \
  --input request.lspx \
  refund-window.lspx

The command uses one frontend result and one verified bytecode artifact for the tree run, the Rust virtual machine, the Topaz virtual machine, and the product compiled ahead of time. A mismatch in the source, the Core IR, or the bytecode rejects that compiled product before any of them runs. The receipt is published atomically and records semantic and comparable-resource mismatch axes separately and exposes every lineage and fallback counter. Vouch uses the source-bound compiled artifact described below.

Choose the right product

Native owns the bytecode reader, checker, and virtual machine. The other products own their source tree and Exact Image workflows.

Add verified bytecode to Vouch

A bytecode hash identifies exact bytes. Verification establishes structural admissibility under configured resource values, and local virtual-machine execution records the Native observation. Vouch adds issuer authentication, recipient policy, source and input binding, current tree and Meaning agreement, and the decision gate through a source-bound container.

When a consumer deliberately wants the virtual machine to agree in addition to the existing Vouch checks, Native builds a separate source-bound container.

lispex vouch compiled build \
  --source refund-window.lspx \
  --out refund-window.lpxvca

lispex vouch compiled validate \
  --artifact refund-window.lpxvca \
  --source refund-window.lspx

vouch verify --reexecute --compiled-artifact refund-window.lpxvca and vouch gate --compiled-artifact refund-window.lpxvca require the consumer's exact external source and input, trust policy, authentication, and current agreement between the tree run and the meaning record. Native re-derives the Core IR and bytecode from that source before running the verified virtual machine. The container, its hashes, inspection and validation output, and the machine result keep their distinct roles in the live Vouch workflow.

Keep going

Use the reference for the exact binary and verifier contract, or return to Core IR to inspect resolved meaning before compilation.

Bytecode and Rust virtual machine reference · Build a Product Compiled Ahead of Time · Native CLI