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. It does not evaluate the rule. The JSON report 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 is useful for review and deterministic comparison, but the report is not a replacement artifact and cannot be executed.

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. It does not turn a Core IR inspection report into executable input.

Core IR and Meaning Graph are different

A Meaning Graph is an older, narrower record of what a program means, and it covers only the checked subset of the language. lispex lower still emits the older csk.meaning-graph/v0 graph. Keep using it with eval-graph and diff-receipt where those workflows call for it. The core-ir family covers the complete current profile and records resolved cells, captures, and tail positions. It does not change or silently migrate Meaning Graph receipts.

Choose the right product

Core IR and bytecode commands are available in the Native product. npm, the public WebAssembly build, and the Playground do not accept Core IR or bytecode bytes and do not provide a JavaScript reader or a virtual machine. Use those products for their documented source, image, and Vouch capabilities.

A common mistake

A matching hash or valid artifact proves integrity and that the bytes are in the one accepted form, not who produced the source, whether the rule is trustworthy, which request was intended, or whether a decision was executed. Core IR cannot issue a Vouch envelope, satisfy trust policy, bind source and input, re-execute a request, or grant a gate 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