Run Verified Bytecode

Use the Native CLI. Lispex VM runs compiled and verified Lispex bytecode. The Core IR guide explains the intermediate file used below.

Prepare the source and input

Save the complete rule as heading-core.lspx.

(define (place-heading lines-left)
  (if (< lines-left 2) 'next-page 'keep))

(place-heading input)

Save the input value as request.lspx.

1

The command supplies this value to input. Core IR and bytecode record the requirement as explicit-input.

Create the two files

lispex core-ir build --source heading-core.lspx --out heading-core.lpxir
lispex bytecode build --ir heading-core.lpxir --out heading-core.lpxbc

Both commands exit 0 and print JSON reports with execution: "not-run". The first writes heading-core.lpxir. The second reads it and writes heading-core.lpxbc. Use new destination paths. An existing destination file makes the command exit 3. If you already followed the Core IR guide, reuse its .lpxir and run only the second command.

The first report has core_ir_build: "lispex.core-ir-build/v1". The second has bytecode_build: "lispex.bytecode-build/v1". These reports describe the saved files.

Inspect and validate

lispex bytecode inspect --bytecode heading-core.lpxbc
lispex bytecode validate --bytecode heading-core.lpxbc

Both commands exit 0. inspect prints a JSON report containing the following values.

The report also lists source, Core IR, and bytecode identifiers, instruction counts by kind, and source positions. All 22 instructions have a source position. validate prints a report with bytecode_validation: "lispex.bytecode-validation/v1" and valid: true.

Run with the input

lispex bytecode run --bytecode heading-core.lpxbc --input request.lspx

next-page

The command exits 0. One remaining line is less than two, so the result is next-page. Native validates the entire bytecode file before creating VM state or using the input.

For this example, omitting --input produces E300 for the unbound variable input and exits 1. Supplying input to bytecode with no input requirement exits 2. The reference lists the verification rules and limits.

A single standard-input stream can carry either bytecode or the input value. This command exits 2 and prints the diagnostic below to stderr.

lispex bytecode run --bytecode - --input -

lispex bytecode run: bytecode and input cannot both read stdin

Use a named file for one of them.

Run directly from source

For source execution and engine comparison, save this self-contained variant as rule.lspx. It supplies 1 inside the program and prints the decision with display and newline.

(define (place-heading lines-left)
  (if (< lines-left 2) 'next-page 'keep))
(display (place-heading 1))
(newline)

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

Each command prints next-page followed by a newline and exits 0. tree is the default Lispex engine. vm compiles and verifies the program in memory before execution.

An explicit vm selection keeps compilation, verification, resource, and execution failures on that engine. It does not retry through tree. The --engine option works only with --backend rust. Combining it with an external backend registry is a usage error and exits 2. See the engine reference for current execution methods.

Read an engine comparison

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

Native creates tree-vm.json, prints this summary, and exits 0.

{
  "all_agree": true,
  "receipt": "tree-vm.json",
  "schema": "lispex.compare-engines-summary/v1",
  "semantic_mismatch_axes": []
}

Both engines record next-page\n in stdout and complete successfully. all_agree: true means the checked semantic results agree. The empty semantic_mismatch_axes array lists no differences.

Open tree-vm.json to read observations.tree, observations.vm, and semantic_mismatch_axes. The report also records source, Core IR, and bytecode identifiers, VM resource measurements, and fallback counts. Native writes the complete report to a new path in one step. If tree-vm.json already exists, the command exits 3 and leaves it unchanged. This JSON is a comparison report. Pass the .lpxbc file to the VM.

Continue with Lispex Vouch

The bytecode reference describes the verifier checks and the Lispex VM comparison.

Lispex Vouch accepts source in csk.checked-profile/v1 for its compiled container. The heading placement source above does not follow that profile, and vouch compiled build rejects it with exit 1. Follow the separate Vouch example in the reference to prepare a compatible source and container.