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: 1. actual ``.kark`` source compiled by the Karkain toolchain, 2. invoked through the real compiler path (the self-hosted ``kcc``), 3. gated by the Phase 120 test suite (``pkg/cli/phase120_kir_test.go``), 4. exercised end-to-end by ``kcc kir`` and the CLI ``karkain 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 karkain kir --verify kcc kir kcc verifykir 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: `` except bare ``block`` introducers and the unknown-node fallback (``stmt ``). 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: .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 120 ``ByteDeterminism`` gate). 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 ``_``. .. list-table:: :header-rows: 1 :widths: 18 82 * - Construct - KIR text * - Program - ``KIR v1`` / ``source: `` / ``import line: N`` / ``cimport ( bytes) line: N`` * - Function - ``func (params: a, b) line: N`` followed by the body depth+1 * - Kernel - ``kernel (params: a, b) line: N`` followed by the body * - Struct - ``struct (x:int, y:int) line: N`` * - Enum - ``enum (Red:, Green:i32) line: N`` * - Variable - ``var/let/const = line: N`` * - Return / Print - ``return [] line: N`` / ``print line: N`` * - Expression stmt - `` line: N`` * - Block - ``block`` followed by body depth+1 * - If - ``if line: N``, body depth+1, then ``else line: N``, body * - While - ``while line: N`` followed by body * - For - ``for ; ; line: N`` (``_`` when a clause is empty) * - For-in - ``forin in line: N`` followed by body * - Break / Continue - ``break line: N`` / ``continue line: N`` * - Alloc / Free / GlobalId - ``alloc line: N`` / ``free line: N`` / ``global_id line: N`` * - Binary / Unary - ``( l r)`` / ``( e)`` * - Call - ``(call ...)`` * - Index / Member / Slice - ``(index l i)`` / ``(member obj field)`` / ``(slice l s e)`` * - Literals - ``(array e ...)`` / ``(map k=v ...)`` / ``(struct Name f=v ...)`` / ``""`` / int / float / bool raw values * - Lambda / Closure - ``(lambda (params: ...) body=N)`` / ``(closure (params: ...) body=N)`` * - Match - ``(match ( line: N) ...)`` * - Unknown - ``(expr )`` / ``stmt `` (never silently dropped) 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 kir`` path is the reference; there is no Go engine fallback for ``karkain kir`` (``--verify`` included). - 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.