Native and npm CLI Commands

How to reason about it

• Native lispex mcp serve exposes the exact installed language reference, size- and time-capped trusted-source Rust-tree authoring evaluation, and diagnostic lookup over local stdio. It is not an adversarial-source sandbox, and it does not deterministically count total work or total allocation. It accepts no path, network address, or route option and provides no discovery, fallback, source retention, or Vouch authority. Timeout or worker termination yields no decision or portable receipt.
• lispex [FILE|-] evaluates source. receipt records the native execution envelope, and 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, and comments, pragmas, tokens, and literal spellings stay exact.
• Native core-ir build turns exact source into resolved lispex.core-ir/v1 in its one fixed byte form. core-ir validate strictly reads and re-encodes it, and core-ir inspect adds a readable normalized projection. All three are non-executing and integrity-only, which means they say the bytes are intact and say nothing more. Existing lower remains the separate Meaning Graph command.
• Native bytecode build accepts strict Core IR and writes lispex.bytecode/v1 in its one fixed byte form. inspect and validate strictly read it without executing, and 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, and 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, and aot run never compiles. The source-free macOS ARM64 product and every result never fall back and are execution-material-only.
• routes install --route topaz-vm|aot-compiler --target TARGET --catalog C --catalog-sha256 H --archive A --out O verifies one exact local catalog fixed down to the byte, together with a stored-ZIP archive, then creates a new path-free installation. It performs no network access, registration, route selection, or fallback.
• routes fetch --route topaz-vm|aot-compiler --target TARGET --out O selects only an exact target from the catalog embedded in Native, performs one size-limited HTTPS acquisition, validates the exact archive and staged Topaz product, and creates the same path-free installation. There is no URL override, redirect, retry, registration, route selection, or fallback. The current official catalog contains the exact Topaz VM and AOT compiler companions only for aarch64-apple-darwin.
• routes inventory [--topaz-vm TVM] [--aot-product AOT], routes lock --route ROUTE --out LOCK, and routes doctor --selection LOCK diagnose and pin Native routes without discovery or fallback. The lock file records the one way of running you chose, so a later run cannot quietly use another.
• routes measure --topaz-vm TVM --aot-product AOT --receipt R --measurement M --samples 1..9 SOURCE keeps fixed-form comparison evidence separate from host-bound route timings.
• routes run --selection LOCK [--topaz-vm TVM|--aot-product AOT] SOURCE revalidates and executes only the locked route, returning one lispex.route-run-result/v1.
• 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, which is 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, and 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, and 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 and source flags, and a new output, then use policy check on the exact bytes. Success emits no stdout. Exit 2 is usage, 3 is failure of input, output, a resource limit, or publication, 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, which are 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 within the image size limit 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 rewrite literal values into one fixed spelling and does not execute the program. 2/4, 1.00, and comments retain their spelling. Malformed source is reported before stdout or file replacement. Formatting is Native-only, and the editor extension never falls back to npm, WebAssembly, 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 or resource failures exit 2. Named artifact or input I/O, size-limited ingress, or named output or 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, inspection of the one fixed form, or exact derivation validation succeeded. Invalid source, profile, container, or bytecode, and derivation mismatch, exit 1. Duplicate, missing, conflicting, or unknown flags exit 2 before artifact work. Size-limited input and output and no-clobber publication failures exit 3. Build never overwrites an existing output. Inspect does not check source derivation, so use validate with the exact source for recovery. --compiled-artifact without --reexecute is usage exit 2.

Keep going

Choosing Where to Run matches a product surface to a deployment task, and the bytecode and Core IR references define the artifacts these commands read and write.

Bytecode and Rust VM · Core IR Contract · Choosing Where to Run