Building and Inspecting Core IR

Build without running

Core IR is the intermediate form a program is translated into before anything runs it. Start with a source file such as refund-window.lspx.

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

The command reads and normalizes the exact source, resolves names to cells, marks tail calls, records closure captures, and writes lispex.core-ir/v1 bytes in the one accepted form. The JSON report records execution: "not-run" and names the source hash, Core IR hash, primitive-registry hash, semantic profile, and counts held under fixed limits.

The destination must be new. Lispex will not overwrite an existing artifact. In a pipeline, - means standard input or output.

cat refund-window.lspx |
  lispex core-ir build --source - --out - >refund-window.lpxir

When --out - is used, stdout contains only artifact bytes in that one accepted form. Diagnostics stay on stderr.

Validate before storing or comparing

lispex core-ir validate --ir refund-window.lpxir

Validation checks the byte limit, JSON shape, fixed schema/profile/registry identities, source anchors, resolved references, captures, tail positions, datum text in its one accepted form, ordering, and exact re-encoding. A harmless-looking whitespace or field-order change is rejected because one meaning artifact has one accepted byte representation.

Inspect the resolved meaning

lispex core-ir inspect --ir refund-window.lpxir

The inspection report includes the following.

source_sha256 for the exact input source bytes
core_ir_sha256 for the complete artifact
counts for globals, requirements, roots, nodes, bindings, and functions
resolved global cells and their initial primitive identities
required explicit host inputs
readable normalized-Core roots with source positions

The report says execution: "not-run" and authority: "integrity-only". Inspection supports review and deterministic comparison. The .lpxir artifact continues into bytecode compilation and execution.

Continue into verified bytecode

Core IR itself remains non-executable. When you need Native to run compiled bytecode instead, lower the strictly validated artifact.

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

The separate lispex.bytecode/v1 artifact has its own binary identity, checker, resource model, and Rust virtual machine. Its compiler consumes the .lpxir artifact while the inspection report remains a readable projection.

Core IR and Meaning Graph are different

Option-free lispex lower still emits the older name-level csk.meaning-graph/v0, and diff-receipt remains the frozen v0 receipt path. The explicit lower --graph-version v1 path instead projects validated Core IR into resolved csk.meaning-graph/v1; eval-graph selects v0 or v1 by tag, and meaning-diff emits csk.meaning-differential-report/v1. Core IR remains the single authority for resolved cells, captures, and tail positions. Projection preserves those identities directly. Native provides the v1 Meaning commands in v1.19, while Vouch continues through its compiled-artifact workflow.

Choose the right product

Core IR and bytecode commands are available in the Native product. npm, WebAssembly, and the Playground provide source evaluation, images, package APIs, and Vouch verification through their documented surfaces.

Product roles

A matching hash and valid artifact establish canonical Core IR integrity. Signed envelopes identify issuers, recipient policy records trust, request binding selects source and input, re-execution observes a current result, and the Vouch gate records the required local decision.

Keep going

Use the contract reference for the exact format and the CLI reference for automation and exit boundaries.

Run Verified Bytecode · Core IR Contract · Native CLI