Core IR Contract

Fixed identities

The registry gives each of the 205 executable builtin names one stable numeric ID. A hidden normalizer intrinsic uses its primitive ID directly. A source-visible builtin remains an ordinary mutable global cell initialized with that ID, so shadowing and top-level redefinition keep their current meaning.

From source to resolved meaning

exact source bytes
  → reader
  → hygienic normalized Core
  → binding and closure resolution
  → canonical Core IR bytes

The artifact removes shorthand syntax and records the following.

• lexical and global cell identities instead of name lookup
• fixed and rest parameters, let, letrec, internal definitions, and dynamically activated forwarding definition cells
• shared mutable closure captures, including transitive captures
• ordinary and tail calls without asking a consumer to infer tail position
• zero, one, and multiple-value contexts
• guard, exception, continuation, and dynamic-wind control boundaries
• canonical literal data and one-based source anchors
• explicit input requirements
• primitive-registry and cost-model identities

The audit projection reproduces the exact normalized Canonical Core bytes used before lowering and records preservation inside the Rust lineage. Other backends add their own implementation identities and execution observations.

One accepted encoding

The artifact is canonical UTF-8 JSON with fixed field order, tagged arrays, minimal non-negative decimal integers, exact Unicode strings, and exactly one final line feed. Globals, requirements, captures, bindings, and functions obey deterministic ordering and continuity laws.

Strict reading rejects duplicate, missing, unexpected, or reordered fields. It also rejects alternate number or datum spellings, unknown tags and IDs, broken references, captures, or tail positions, invalid source anchors, trailing bytes, and any artifact that does not re-encode byte for byte.

Limits are checked before table reads and allocation.

The source_sha256 field uses the existing domain-separated identity of the exact source bytes. core_ir_sha256 uses the domain-separated identity of the complete canonical artifact. Consumers use these contract fields directly for source and artifact identity.

Native command reports

• core-ir build emits lispex.core-ir-build/v1 when writing a named artifact. With --out -, it emits artifact bytes only.
• core-ir validate emits lispex.core-ir-validation/v1 after a strict read and re-encode.
• core-ir inspect emits lispex.core-ir-inspection/v1 with identities, counts, globals, requirements, and readable normalized roots.
• Usage errors exit 2, validation or source errors exit 1, and a run that reaches a declared resource limit or fails on input, output, or publication exits 3.

Native owns these three artifact commands. npm, public WebAssembly, and the Playground own source execution through the reference runtime.

Meaning Graph coexistence

Core IR owns name resolution, closure captures, tail positions, and the complete normalized profile. Option-free lower and diff-receipt retain the published name-level v0 contract. lower --graph-version v1 projects validated Core IR to resolved csk.meaning-graph/v1, eval-graph dispatches by graph tag, and meaning-diff writes the v1 Meaning comparison report. Native owns these v1 commands. Vouch derives Core IR again from authenticated exact source inside its compiled workflow.

Product role

Core IR is integrity-only compilation material. Canonical bytes, strict reading, inspection, and domain-separated identity establish the resolved artifact consumed by Meaning Graph, bytecode compilation, VM execution, and the source-bound compiled Vouch workflow. Recipient policy and current re-execution add authentication and decision context.

Keep going

Use the guide for a short command workflow or the runtime page to compare the places Lispex runs.

Building and Inspecting Core IR · Runtime and Backends