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 surface sugar and records:

• 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; and
• 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 ingress rejects duplicate, missing, unexpected, or reordered fields; 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 unbounded work:

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 strict read-and-replay.
• 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 bounded resource or input/output publication failures exit 3.

All three commands are Native-only and non-executing. npm, public WASM, and Playground expose no Core IR reader or facade.

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. 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 enters 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 product surfaces.

Building and Inspecting Core IR · Runtime and Backends