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 must reproduce the exact normalized Canonical Core bytes used before lowering. That is same-Rust preservation evidence, not an independent implementation or a proof of semantic equivalence.

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 any unlimited work begins.

The source_sha256 field is the existing domain-separated identity of the exact source bytes. core_ir_sha256 is the domain-separated identity of the complete canonical artifact. Neither should be replaced with a plain file hash or a hash of pretty inspection JSON.

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.

All three commands are Native-only and non-executing. npm, public WebAssembly, and the Playground offer no Core IR reader and no command that stands in for one.

Meaning Graph coexistence

Core IR is not csk.meaning-graph/v0 under a new name. Meaning Graph remains the name-level checked-subset format used by lower, eval-graph, and diff-receipt. Core IR covers the complete current normalized profile with resolved cells and closure facts. Existing Meaning Graph bytes, hashes, receipts, and claims are unchanged.

Authority boundary

Core IR is integrity-only compilation material, which says the bytes are intact and says nothing more. Canonical bytes, a valid reader result, an inspection report, or a matching hash do not establish authorship, provenance, trust, freshness, request intent, execution, correctness, or a decision grant. No Core IR command participates in Vouch, and no report can promote itself into Vouch evidence or gate authority.

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