lispex

The Lispex npm CLI runs the Rust reference interpreter through WebAssembly and provides exact Lispex Images, offline receipt workflows, policy tools, and authenticated Lispex Vouch verification. The browser Playground and npm use the same reference runtime.

Install

npm install -g lispex
lispex --version

The package includes @lispex/sicp as a separate runtime dependency. Select the SICP profile explicitly.

lispex sicp run exercise.scm
cat exercise.scm | lispex sicp run -

The unqualified lispex run command uses the Lispex core profile.

Run Lispex

lispex run hello.lspx
lispex hello.lspx
echo '(+ 1 2 3)' | lispex

The CLI reads, normalizes, and evaluates every top-level form through the WebAssembly reference interpreter. It returns the same values, stdout, warnings, diagnostics, arbitrary-precision integers, continuations, multiple-values behavior, and numeric semantics as the browser runtime.

Product roles

| Product | Runtime and tools | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | npm CLI | source execution, SICP, exact images, structural receipt verification, replay, identity and policy tools, Vouch authentication and inspection | | Native | npm capabilities plus formatting, MCP authoring, Meaning Graph, Core IR, verified bytecode and VMs, receipt and evidence issuance, current re-execution, and the local gate | | Playground | interactive source and image workflows in the browser |

Install a Native release from lispex.com/downloads for fmt, Core IR, bytecode, VM, installed Topaz routes, issuance, re-execution, and gate commands.

Lispex Images

The npm package uses the same Rust image codec as Native.

lispex image encode --source rule.lspx --out rule.lspx.png
lispex image inspect --image rule.lspx.png
lispex image decode --image rule.lspx.png --out recovered.lspx
lispex run --image rule.lspx.png

The JavaScript host owns named-path I/O and atomic publication. Rust owns the PNG and ZIP grammar, canonicality, integrity, parity, commitments, recovery, and exact regeneration checks. Native connects recovered source to the full Vouch chain; npm connects it to identity, policy, authentication, inspection, and replay.

Receipts and replay

lispex verify receipts/refund.json --source rules/refund.lspx
lispex replay gallery --against 1.19.0
lispex vouch inspect receipts/refund.json
lispex vouch replay gallery --against 1.19.0

verify checks the receipt schema, hashes, and optional exact source identity. replay compares a decision corpus with a version or receipt baseline. Both run offline.

Identity and policy

Native and npm call the same Rust identity and policy implementation.

lispex key inspect --public-key issuer.spki.der
lispex vouch key-id --public-key issuer.spki.der
lispex vouch engine-id --executable /exact/path/to/lispex
lispex vouch source-id --source rule.lspx
lispex vouch source-id --source-image rule.lspx.png
lispex vouch input-id --input request.checked.json

lispex vouch policy create \
  --public-key issuer.spki.der \
  --engine-sha256 sha256:<reviewed-engine-digest> \
  --source-image rule.lspx.png \
  --out policy.json

lispex vouch policy check --trust-policy policy.json

Identity commands produce domain-separated identifiers for exact key, engine, source, and input bytes. Policy creation uses recipient-supplied keys, engines, and source allowlists and atomically publishes canonical policy bytes. The recipient owns the mapping from those identifiers to organizations, custody, and accepted actions.

Authenticate Vouch evidence

lispex vouch verify \
  --envelope envelope.dsse.json \
  --trust-policy policy.json \
  --source-image rule.lspx.png \
  --input input.json \
  --profile csk.checked-profile/v1 \
  --report-out authenticated.json

Bundle verification can authenticate the signed context carried by one canonical bundle or pin it to separately supplied source and input snapshots.

lispex vouch verify \
  --bundle vouch-input-bundle.json \
  --trust-policy policy.json \
  --profile csk.checked-profile/v1 \
  --report-out authenticated.json

lispex vouch verify \
  --bundle vouch-input-bundle.json \
  --trust-policy policy.json \
  --source-image rule.lspx.png \
  --input input.json \
  --profile csk.checked-profile/v1 \
  --report-out pinned.json

Raw and bundle verification use the same Rust parser, verifier, canonical report bytes, and error order in Native and npm. A v1 trust policy selects accepted public keys, engine identities, profiles, and source identities.

Native adds vouch issue, vouch verify --reexecute, and vouch gate. Re-execution records current tree and Meaning agreement for the exact external request. The local gate consumes that current evidence, and the host application consumes the gate result and owns the external action.

Exit status

• Exit 0 means the requested operation succeeded.
• Exit 10 on authenticated Vouch verification means authentication succeeded and diagnostic promotion was withheld.
• Exit 1 reports evaluation, validation, or authentication rejection.
• Exit 2 reports command usage.
• Exit 3 reports input/output, resource, or named-report publication errors.

Diagnostics use the same E3xx and W3xx codes and rendering as the Playground. Named outputs are published atomically to a new path.

License

This npm package is distributed under Apache-2.0. Lispex source files, inputs, application output, and Vouch records remain under the terms selected by their owners. Repository licensing is stated in the repository source notice.