Implementation architecture

This is the map for someone working on the Rust code. For why the pieces are shaped this way, follow the ADR links. For what the language does, see the spec.

The pipeline

source: &str
   │
   ▼
┌──────────┐   Vec<Token>        ┌──────────┐   ast::Module      ┌──────────┐
│  lexer   │ ──────────────────▶ │  parser  │ ────────────────▶ │ resolver │
└──────────┘   + INDENT/DEDENT   └──────────┘   (tree)           └──────────┘
                                                                      │
                                                          ResolvedModule (tree + scope info)
                                                                      │
                                                                      ▼
                                                                ┌─────────────┐
                                                                │ interpreter │ ──▶ Output
                                                                └─────────────┘

Every stage takes the previous stage's output and either produces the next artifact or a Vec<Diagnostic>. Nothing prints; the caller (korrin::run or the CLI) decides what to do with output and errors.

Modules in crates/korrin/src

Cross-cutting conventions

• Errors are values. A stage returns Result<T, Vec<Diagnostic>> (or accumulates into a sink). No panic! on user input, ever — panics are for internal invariant violations only.
• Control flow is a value too. return / break / continue are an interpreter::Signal enum threaded through Result, not Rust panic/catch and not exceptions. This keeps the interpreter honest and maps to a future VM. (ADR 0004)
• Spans everywhere. If you add an AST node, it carries a Span. If you raise a diagnostic, it has a primary label.
• The library never touches the terminal. No println!, no colour detection, no std::process::exit. That is korrin-cli's job. (ADR 0012)

How to…

• add a builtin: see adding-a-builtin.md.
• add a keyword: see adding-a-keyword.md.