KIR (Karkain IR)
KIR is the Karkain-owned compiler intermediate representation. It is the first compiler component written entirely in Karkain, owned by the self-hosted compiler, and serialized as a deterministic text v1 format.
Ownership
The emitter lives in src/compiler/kir.kark (kirEmit and its
helpers). It is:
actual
.karksource compiled by the Karkain toolchain,invoked through the real compiler path (the self-hosted
kcc),gated by the Phase 120 test suite (
pkg/cli/phase120_kir_test.go),exercised end-to-end by
kcc kirand the CLIkarkain kir.
The Go repository only routes to it: pkg/cli/kir.go
(KCCKirCommand) is a thin gateway that runs the Go-side syntax
preflight, assembles the unit, and dispatches to the self-hosted engine.
There is no Go KIR emitter.
Interface
karkain kir <file.kark>
karkain kir --verify <file.kark>
kcc kir <file>
kcc verifykir <file>
The command parses the file with the self-hosted parser and renders the AST as KIR text. Parse errors surface before emission; success prints the KIR lines followed by a path-less confirmation:
[ok] kir text: N lines
--verify (Phase 121) runs the compiler-owned structural verifier
instead of dumping the text and prints a distinct verdict:
[ok] kir text: N lines
[ok] kir verify: N lines ok
Structural verification (Phase 121)
kirVerify in src/compiler/kir.kark checks every emitted line
against the KIR v1 structural contract:
the header line is exactly
KIR v1;the source line names exactly the file basename;
indentation is two spaces per depth level;
nesting depth never jumps forward by more than one level;
every statement line ends `` line: <decimal>`` except bare
blockintroducers and the unknown-node fallback (stmt <type>).
The verifier is written in Karkain using only language builtins and the in-tree user helpers — no Go front-end, external IR, or library participates in the proof. It runs in two places:
checkFile: the DEFAULT kcc check path executes it after the Phase 99 type checker — silent on success,error[K121]+ no[ok]on drift (the CLI maps that to exit 3);verifykir/karkain kir --verify: the standalone, deterministic command form.
This turns KIR from a CLI artifact (Phase 120) into an engine-internal
invariant: any future emitter-vs-contract drift becomes a hard, visible
error on every accepted check instead of silent divergence. With the
current emitter no valid source can fail the verifier — the point.
Determinism contract
KIR output is byte-identical across runs and sandboxes:
the header carries only the file basename (
source: <name>.kark) — never the sandbox path,the confirmation line is path-less,
every line is produced by a single
print, so identical input means identical bytes (enforced by the Phase 120ByteDeterminismgate).
Format (v1)
One line per statement at an indentation equal to the block depth (two
spaces per level). Expressions are fully parenthesized; empty
constructs render as _.
Construct |
KIR text |
|---|---|
Program |
|
Function |
|
Kernel |
|
Struct |
|
Enum |
|
Variable |
|
Return / Print |
|
Expression stmt |
|
Block |
|
If |
|
While |
|
For |
|
For-in |
|
Break / Continue |
|
Alloc / Free / GlobalId |
|
Binary / Unary |
|
Call |
|
Index / Member / Slice |
|
Literals |
|
Lambda / Closure |
|
Match |
|
Unknown |
|
Boundaries
KIR text never feeds the build/run backend yet. Phase 121 makes the emitter an engine-internal verified invariant on the default check path; consuming generated KIR as the input to code generation is tracked as a post-121 work item.
The self-hosted
kcc kirpath is the reference; there is no Go engine fallback forkarkain kir(--verifyincluded).Line numbers in the text are those produced by the self-hosted lexer/parser on the assembled unit; they are stable and deterministic for a given input but are not asserted as file-absolute in the gate.