Compile a Rule to an Intermediate Form

The Native CLI provides the Core IR commands in this guide. Core IR is a resolved intermediate representation. It records which variable each name refers to before execution.

Save the source

Save the complete program as heading-core.lspx.

(define (place-heading lines-left)
  (if (< lines-left 2) 'next-page 'keep))

(place-heading input)

The rule returns next-page when fewer than two lines remain below the heading and keep otherwise. The caller supplies the line count as input. Building Core IR records this requirement without running the rule.

Build the Core IR file

lispex core-ir build --source heading-core.lspx --out heading-core.lpxir

The command creates heading-core.lpxir and prints a JSON build report. It exits 0. The destination must be a new path. If the file already exists, the command exits 3 and leaves that file unchanged.

These fields are an excerpt from the report.

{
  "authority": "integrity-only",
  "core_ir_build": "lispex.core-ir-build/v1",
  "execution": "not-run"
}

The report also contains source and file identifiers, the language profile, and table counts. The compiler writes the lispex.core-ir/v1 file separately from this report.

Read the names and source positions

lispex core-ir inspect --ir heading-core.lpxir

The command exits 0 and prints an inspection report. This excerpt shows the names and the two top-level expressions.

{
  "execution": "not-run",
  "globals": [
    {
      "id": 0,
      "initial_primitive": {
        "id": 6,
        "name": "<"
      },
      "name": "<"
    },
    {
      "id": 1,
      "initial_primitive": null,
      "name": "input"
    },
    {
      "id": 2,
      "initial_primitive": null,
      "name": "place-heading"
    }
  ],
  "requirements": [
    "explicit-input"
  ],
  "roots": [
    {
      "column": 1,
      "index": 0,
      "line": 1,
      "normalized_core": "(define place-heading (lambda (lines-left) (if (< lines-left (quote 2)) (quote next-page) (quote keep))))"
    },
    {
      "column": 1,
      "index": 1,
      "line": 4,
      "normalized_core": "(place-heading input)"
    }
  ]
}

place-heading refers to global cell 2. The < cell starts with built-in procedure ID 6. input uses cell 1 and adds the explicit-input requirement.

The first expression becomes a definition containing lambda. The second remains (place-heading input), at line 4, column 1. A root is one top-level expression. The report counts 2 roots, 12 expression nodes, 1 parameter binding, and 1 function.

The full report includes artifact.source_sha256 and artifact.core_ir_sha256. They identify the exact source bytes and the complete Core IR file. Changing source whitespace can change these identifiers even when the rule returns the same value.

Validate the saved file

lispex core-ir validate --ir heading-core.lpxir

The command exits 0. Its report includes the following fields.

{
  "core_ir_validation": "lispex.core-ir-validation/v1",
  "valid": true
}

Validation checks the size and count limits, the JSON shape, and the schema, profile, and builtin registry identifiers. It also checks source positions, references, and tail-call positions. It checks captures too, which are outer variable cells used by a function. The reader accepts one prescribed byte representation and rejects a file whose field order or whitespace has changed.

Pass the file to the compiler

Use heading-core.lpxir as the input to bytecode build. The bytecode guide continues with the same source, adds request.lspx, and runs the result.

To use standard streams, set --source - or --out -. With --out -, stdout contains only Core IR bytes and diagnostics go to stderr. Save those bytes directly, without adding a JSON report or changing their encoding.

Related formats

Native can also produce a Meaning Graph from Core IR. The Core IR reference explains the v0 and v1 commands and their formats.

Lispex Vouch builds its own compiled container from exact source. A Vouch check also uses issuer authentication, recipient policy, the exact input, and a current execution result. The bytecode reference describes the source rules and commands for that container.