Spec

Kairo compiler specification

This directory specifies how the Kairo compiler implements the language: its pipeline, the contract of each pass, the invariants that hold between them, and the known limitations. What a Kairo program means is defined by the language reference; where the two disagree, the language reference states the intended behaviour and the disagreement is a defect.

The directory layout of the sources is in Compiler/README.txt.

Pipeline

source (.k)
  -> Lexing and preprocessing       Lexing.md
  -> Parsing                        Parsing.md
  -> Sema
       import resolution            Imports.md
       expansion, verification,
       name resolution              NameResolution.md
       type resolution, chain
       binding                      TypeResolution.md
       expression typing            ExprTyping.md
       semantic checks              SemanticChecks.md
       lowering                     Lowering.md
       monomorphization             Generics.md
  -> Codegen to C++ tokens          Codegen.md
  -> clang (in process)             Interop.md
  -> link (lld)                     Linking.md

The authoritative pass order and the cross-pass invariants are in Pipeline.md.

Documents

Front end

Document	Contents
Pipeline.md	Compilation phases, Sema pass order, phase barriers, invariants
Lexing.md	Source files, tokens, keywords, literals, preprocessor, macros
Parsing.md	Parser structure, disambiguation, error recovery, AST
Grammar.ebnf	The grammar in EBNF, generated from the tree-sitter grammar (the parser is the authority)

Semantic analysis

Document	Contents
Imports.md	Import forms, path resolution, overlays, re-exports, module pinning
NameResolution.md	Expansion, verification, name resolution, lookup rules
MemberLookup.md	Member lookup, extensions, inheritance
TypeResolution.md	Type resolution, redeclaration merging, late eval-if folding, chain binding
ExprTyping.md	Expression typing, conversions, overload resolution
SemanticChecks.md	The check passes and effect propagation
Ownership.md	Copy and move, move-only types, safe pointers
Generics.md	Instantiation model and registry, the monomorphization sync point
Interfaces.md	Conformance, interface algebra, associated types

Lowering

Document	Contents
Lowering.md	Lowering pass order and each pass
Nullables.md	T? from representation to C++
Panic.md	Panic model, effect sets, lowering, C++ exceptions
Eval.md	Compile-time evaluation
ScriptMode.md	Top-level statements and their desugaring
FormatStrings.md	f-string lowering and the runtime writer

Back end

Document	Contents
Codegen.md	EmitPlan, CXXSpell, InterfaceEmitter, EmitIR, templates
Witnesses.md	Calls through an interface bound
Interop.md	FFI imports, type mapping, clang integration, kcc
Linking.md	The linker driver, link jobs, sysroots
LibraryFormat.md	The .klib library format
ArchiveFormat.md	The KaTAR archive format

Driver, tooling and infrastructure

Document	Contents
Driver.md	Driver phases, flags, toolchain discovery, native inputs
IncrementalSema.md	Design: module records, declaration identity, dependency logging, the four Sema changes, phases and gate for incremental AST/Sema
LanguageServer.md	kals: server and worker processes, kairo_compile.json, the snapshot format, the compiler hooks it uses
Diagnostics.md	Diagnostic codes, the registry, rendering, clang diagnostics, fix-its
BuildSystem.md	build.py, staged trees, LLVM, release packaging
SelfHosting.md	Stages, bootstrap and the fixed-point proof, the migration rules
Portability.md	Targets, standards compliance, platform specifics
Performance.md	Benchmarks, parallel codegen, compile-time optimizations
TodoMarkers.md	The TODO(<CATEGORY>) marker kinds in the source and what resolving each means
Incremental.md	Incremental compilation: interface vs object keys, global invalidation, the cache record in each object (phase 2 not implemented)
Serialization.md	The serialized AST: one file's parsed tree as bytes, the format, what is rebuilt on read, the round-trip test flags

Language reference

The language reference is maintained on the website (https://www.kairolang.org/docs/language/) and mirrored read-only in Docs/. Spec documents refer to its pages by name; this table is the single place that maps a name to its file.

Page	File
primitives, conversion classes	primitives.mdx, conversion-lattice.mdx
variables	variables.mdx
pointers	pointers.mdx
unsafe	unsafe.mdx
structures	structures.mdx
classes, lifecycle	classes.mdx, classes-lifecycle.mdx
extends	extends.mdx
closures	closures.mdx
functions, parameter modes	functions-parameter-modes.mdx
requires, where	requires.mdx, where.mdx
nullables	nullables.mdx
panic	panic.mdx
C++ exceptions	c-cpp-exceptions.mdx
eval	eval.mdx
imports, modules, scripts	imports.mdx, modules.mdx (Scripts)
interfaces	interfaces.mdx, interfaces-requirements.mdx
generics	generics.mdx
ownership	ownership.mdx
C and C++ interop	c-cpp.mdx, c-cpp-*.mdx
C and C++ ABI	c-cpp-abi.mdx
diagnostics	diagnostics.mdx
macros	macros.mdx, macros-builtin.mdx

Former documents

Older text (tests, commit messages) cites the design notes this directory replaced. Their content now lives here:

Former document	Now
Compiler/Sema/RESOLUTION.md	Pipeline.md, with each pass in its own document; invariant numbers 1-19 are unchanged
Compiler/Sema/IMPORTS.md	Imports.md, Interop.md; its invariants 9-13 are Pipeline.md 20-26
Compiler/Codegen/CODEGEN.md	Codegen.md, Witnesses.md
Spec/lexer.md, Spec/keywords.md, Spec/errors.md, Spec/kairo.ebnf	Lexing.md, Diagnostics.md, Grammar.ebnf
Spec/KLIB.md, Extras/KaTAR/KatarDoc.md	LibraryFormat.md, ArchiveFormat.md

Conventions

• Paths are relative to the repository root.
• A section states what the code does today. Behaviour that is designed but not built is marked unimplemented in the sentence that describes it.
• Every fact has one home; other documents link to it.