Native and npm CLI Commands

How to reason about it

• lispex [FILE|-] evaluates source; receipt records the native execution envelope; lower and eval-graph operate on the checked subset.
• Native lispex fmt [FILE|-] writes deterministic formatted source to stdout. --check is silent and exits 0 when no change is needed or 1 when formatting would change bytes. --write safely replaces one regular named file. Validation happens first; comments, pragmas, tokens, and literal spellings stay exact.
• Native core-ir build turns exact source into canonical resolved lispex.core-ir/v1; core-ir validate strictly reads and re-encodes it; core-ir inspect adds a readable normalized projection. All three are non-executing and integrity-only. Existing lower remains the separate Meaning Graph command.
• Native bytecode build accepts strict Core IR and writes canonical lispex.bytecode/v1; inspect and validate strictly read it without executing; bytecode run verifies and executes it in lispex-rust-vm/v1. run --backend rust --engine vm is the in-memory source route, while tree remains the default. A VM error never retries through tree.
• Native vouch compiled build|inspect|validate creates, structurally checks, or exactly re-derives one .lpxvca from a separately named source or proved image. The three commands print JSON to stdout, never execute, and report authority: integrity-only. verify --reexecute --compiled-artifact and gate --compiled-artifact are the only opt-in execution consumers.
• compare-engines --receipt REPORT SOURCE runs both Rust engines, writes a no-clobber lispex.rust-engine-comparison/v1 report, and exits 1 when a semantic mismatch axis exists. It is same-lineage regression evidence, not an independent receipt or authority.
• bytecode run --engine topaz --topaz-vm ROOT selects only the exact separately installed macOS ARM64 Topaz 5.11 provider. compare-vms --topaz-vm ROOT --receipt REPORT SOURCE derives bytecode once and records both VM observations. Product, request, result, full-u64 resources, and fallback counters are checked; no Topaz failure retries another engine.
• Native aot build lowers exact source through Core IR and bytecode to readable Topaz, then requires absolute exact Topaz and Rust tool paths and a new output directory. aot inspect|validate never execute; aot run never compiles. The source-free macOS ARM64 product and every result are no-fallback and execution-material-only.
• compare-routes --topaz-vm TVM --aot-product AOT --receipt REPORT SOURCE derives one Core IR and bytecode request, proves the AOT product matches it, validates both installed Topaz products, and explicitly runs tree, Rust VM, Topaz VM, and AOT. Its no-clobber diagnostic receipt separates semantic mismatch axes from comparable resource axes and cannot enter Vouch.
• Native provides the full namespaced chain: vouch issue, flag-free vouch verify, vouch verify --reexecute, vouch gate --require-decision, and vouch inspect. npm provides authenticated flag-free vouch verify, structural vouch inspect, and corpus vouch replay; npm rejects issue, --reexecute, and gate before artifact I/O.
• For flag-free authenticated verify, exits are 0 for authenticated and diagnostic-promotion-eligible, 10 for authenticated but diagnostic-promotion-ineligible, 1 for rejection, 2 for usage before artifact I/O, and 3 for input/output or report-publication failure. Both 0 and 10 authenticate; neither grants authority.
• The flat npm lispex verify RECEIPT remains an unsigned structural compatibility command. It is not an alias for namespaced authenticated lispex vouch verify.
• A successful --reexecute report has authentication.status set to authenticated, reexecution.status set to execution-agreed, fixed observation_scope csk.vouch-complete-transcript/v0, and comparison.current_vs_signed set to agree.
• vouch gate requires all raw context paths plus --require-decision approve|deny|review|invalid-input and --report-out. Its csk.native-gate-report/v0 separates authentication, re-execution, and gate status and records the fixed basis csk.current-native-agreement/v0.
• File and stdin identities are recorded explicitly where an artifact contract requires them.
• Use lispex vouch policy create with one named SPKI file, repeated explicit engine/source flags, and a new output; then use policy check on the exact bytes. Success emits no stdout. Exit 2 is usage, 3 is I/O/resource/publication failure, and 1 is invalid configuration.
• For Native bundle authority, vouch verify --reexecute and vouch gate require both --source RULE and --input INPUT. Missing or partial pairs are usage exit 2 before any named artifact is opened. Flag-free vouch verify --bundle remains supported authentication-only behavior in Native and npm.
• Native and npm image commands use named paths: image encode --source SOURCE --out IMAGE, image inspect --image IMAGE, image decode --image IMAGE --out SOURCE, and run --image IMAGE. Encode requires .lspx.png for one page or .lspx-images.zip for a page set. Image usage errors exit 2, validation or suffix failures exit 1, and I/O, resource, or no-clobber publication failures exit 3.
• Where a Vouch command accepts source context, choose exactly one of --source RULE or --source-image IMAGE. A source image is read under the image bound and fully proved before recovered bytes enter identity, policy, issuance, authentication, request binding, re-execution, or gate evaluation.
• For pinned bundle verify, Native re-execution, and gate, --source-image IMAGE still requires the separately supplied --input INPUT. An unpinned bundle remains authentication-only and cannot reach execution or a grant.

Command boundaries

A common mistake

fmt does not canonicalize literal values and does not execute the program. 2/4, 1.00, comments, and ;! pragmas retain their spelling. Malformed source is reported before stdout or file replacement. Formatting is Native-only; the editor extension never falls back to npm, WASM, or the Playground.

For Core IR commands, exit 0 means the requested build or strict read succeeded, not that a rule ran. Usage errors exit 2, validation or source errors exit 1, and resource or input/output publication failures exit 3.

For bytecode, exit 0 means build/strict validation/inspection or execution succeeded. Invalid Core IR, malformed bytecode, invalid input, and ordinary runtime diagnostics exit 1; usage and engine/resource failures exit 2; named artifact/input I/O, bounded-ingress, or named output/report publication failures exit 3. A terminal write failure while emitting an execution result exits 2. Artifact stdout is byte-clean, named outputs never clobber, and bytecode plus input cannot both read stdin.

Topaz mode additionally requires an absolute product root and is available only for the admitted macOS ARM64 product. Provider identity, timeout, malformed result, resource, and mismatch failures exit visibly without running Rust, tree, LIL, LIT, or another Topaz installation. npm explicitly rejects core-ir, bytecode, aot, compare-engines, compare-vms, and compare-routes as Native-only commands instead of treating them as source filenames.

For vouch gate, exit 0 means a live grant matched the required decision; 10 means authentication succeeded but no grant was minted; 1 means authentication rejection; 2 means usage error; and 3 means I/O, execution, or report-publication failure. A report is diagnostic output and cannot be reused as gate input.

For vouch compiled, exit 0 means build, canonical inspection, or exact derivation validation succeeded. Invalid source/profile/container/bytecode or derivation mismatch exits 1; duplicate, missing, conflicting, or unknown flags exit 2 before artifact work; bounded input/output and no-clobber publication failures exit 3. Build never overwrites an existing output. Inspect does not check source derivation; use validate with the exact source for recovery. --compiled-artifact without --reexecute is usage exit 2.

Keep going

Use this page while writing code. For a guided explanation, return to the syntax map or the corresponding manual.

Bytecode and Rust VM · Core IR Contract · Choosing a Runtime Surface