Architecture Decision Records
This directory records why Korrin is the way it is. Each file captures one decision — the context that forced it, the choice made, the consequences, and the alternatives rejected. The process itself is ADR 0000.
New ADRs use template.md. Every ADR must appear in the table
below; CI (crates/korrin/tests/adr.rs) enforces that, and that each ADR has the
required sections. README.md and template.md are exempt.
For what Korrin does (as opposed to why), see the specification.
Index
| # | Title | Status |
|---|---|---|
| 0000 | Architecture Decision Records: the process | Accepted |
| 0001 | Indentation defines blocks | Accepted |
| 0002 | Documentation is enforced by CI | Accepted |
| 0003 | Newlines terminate statements | Accepted |
| 0004 | A tree-walking interpreter first | Accepted |
| 0005 | Methods take an explicit self parameter | Accepted |
| 0006 | The Milestone 1 keyword set | Accepted |
| 0007 | INDENT / DEDENT tokenization, spaces only | Accepted |
| 0008 | Byte-offset spans, one diagnostic type, ariadne | Accepted |
| 0009 | Only nil and false are falsy | Accepted |
| 0010 | Numeric model: int/float split, / true division, checked overflow | Accepted |
| 0011 | Bare assignment, lexical block scope, nearest-binding rule | Accepted |
| 0012 | Cargo workspace: library plus thin CLI | Accepted |
| 0013 | Dependency policy | Accepted |
| 0014 | Built-in collection operations are free functions (M1) | Accepted — amended by 0016 |
| 0015 | String interpolation — every string, {expr} | Accepted |
| 0016 | Operations on built-in values are methods (amends 0014) | Accepted |
| 0017 | Exceptions for error handling (try / except / finally / raise) | Accepted |
| 0018 | The module system (import, module objects, _ privacy, cycles are errors) | Accepted |
| 0019 | Built-in modules and the first standard library (math) | Accepted |
| 0020 | The io module and standard-library principles | Accepted |
| 0021 | A Host trait decouples native functions from the execution engine | Accepted |
| 0022 | Names resolve lexically, not by runtime search (narrows 0011) | Accepted |
| 0023 | Closures capture variables, not scopes | Accepted |
| 0024 | The tree-walking interpreter is kept as a differential-testing oracle | Accepted |
| 0025 | finally is inlined at every exit the compiler can see | Accepted |
| 0026 | korrin-lsp's transport: lsp-server, no async runtime | Accepted |
| 0027 | Diagnostics: first-failing-stage only for v1 | Accepted |
| 0028 | Hover text is compiled from the specification, not read at runtime | Accepted |
| 0029 | Go-to-definition is a standalone scope walker, single-file for v1 | Accepted |
| 0030 | Node and TypeScript, scoped to the VS Code client only | Accepted |
| 0031 | Package distribution: git, no registry | Accepted |
| 0032 | Bare-name imports merge installed packages with built-ins | Accepted |
| 0033 | The korrin-pkg crate and its dependency tier | Accepted |
| 0034 | The community package index: a second static site | Accepted |
| 0035 | Native modules load by compile-time linking, not dynamic loading or WASM | Accepted |
| 0036 | Value::NativeObject: one opaque object type per module | Accepted |
| 0037 | The native-module rebuild mechanism | Accepted |
| 0038 | No auto-detect/re-exec for a project's native binary | Accepted |
Open questions
Decisions we know we need to make but have deliberately deferred. Each becomes a
Proposed ADR when work starts on it.
- Floor-division operator (
//). Only ifint(a / b)proves insufficient in practice. - Arbitrary-precision integers. Whether
intshould stop beingi64. - Multiple / typed
exceptclauses. Deferred; Korrin has no exception hierarchy to filter on yet (0017). - Per-file diagnostics for imported modules. Errors inside an imported
module currently surface at the
importsite as text; a caret into the imported file needs multi-file rendering (0018). Resolved: string interpolation (0015); methods on built-in types (0016, amending 0014); string indexing iss[i]for one character ands.slice(a, b)for a range; error handling is exceptions (0017); modules are path-resolved objects (0018) and the standard library rides the same mechanism (0019); packages are git repositories with no central registry, resolved through the same bare-importsyntax as built-ins (0031, 0032).