Welcome to The Koru Book

This isn't like traditional programming tutorials. Instead of static examples, you're looking at living documentation — every page is backed by a real test that actually runs.

When you see a ✓, that means the code actually compiles and runs correctly. When you see ✗, you're looking at something we're still working on. This is documentation that can never drift from reality because it IS reality.

That said, tests can go cold. A ✓ means the test passed when last run — not that every example is perfectly idiomatic or complete. Koru is under active development.

The Zen of Koru

The atom is the event. Functions are just events that forgot how to branch.

Branches are how decisions actually work. Flows are how things actually happen.

What you don't write can't break. What you don't hide can't surprise.

What you don't promise can't fail. Fail loudly, fix honestly.

Model reality, not abstractions. Let patterns emerge from events.

Complex behavior from simple rules. The AST is the program.

Zero cost at runtime. All magic at compile time. The boundary dissolves.

We built this together. Human vision, AI capability.

🟢

Working Features

Green tests (✓) are ready to learn from today

🔴

In Progress

Red tests (✗) are features we're currently building

🔵

Coming Soon

Blue tests (○) are planned features on the horizon

Suggested Learning Path

1. Start with Core Language — Learn the fundamentals of events and procs

2. Move to Control Flow — Understand how Koru programs flow with labels and continuations

3. Explore Advanced Topics — Event taps, phantom types, metacircular compilation

The Koru Book

Learn Koru through working examples. Every lesson is a real test from the compiler's regression suite.

Tests: 928
✓ 745 passing
✗ 92 failing
○ 53 planned

core language / basic syntax

22/22

core language / events flows

18/18

core language / literals

7/7

core language / type system

0/19

core language / control flow

28/30

module system / imports

16/16

module system / namespaces

2/2

module system / packages

1/1

module system / file layout

13/15

parser

8/8

compiler features / parser

81/86

compiler features / compilation

14/14

compiler features / flow checker

5/6

compiler features / codegen

1/1

compiler features / emitter

5/5

compiler features / std library

3/3

compiler features / template engine

7/7

compiler features / subflow

1/1

syntax / struct constructors

2/2

advanced features / comptime

52/60

advanced features / stdlib

45/54

advanced features / keyword

5/5

advanced features / phantom types

65/76

advanced features / obligation stress

8/17

advanced features / obligation matrix

5/6

The permutation matrix of Koru's phantom-obligation discharge system — the

advanced features / type system

0/5

advanced features / auto proc

3/3

advanced features / pattern branches

3/4

advanced features / subflows

9/13

advanced features / optional branches

9/10

advanced features / taps observers

5/7

advanced features / interceptors

0/4

advanced features / phantom types

1/1

advanced features / variants

8/13

advanced features / templating

2/4

advanced features / kernel

20/24

advanced features / testing

10/10

control flow

5/6

runtime features

43/45

runtime features / budgeted interpreter

6/7

runtime features / purity checking

8/9

runtime features / performance

0/20

runtime features / coordination

6/11

runtime features / runtime

31/36

runtime features / resource bridge

2/2

integration testing / negative tests

34/36

integration testing / negative tests / 020 parse errors

1/1

integration testing / negative tests / 034 type errors

1/1

integration testing / bug reproduction

4/4

integration testing / validation

7/7

stdlib / string

13/14

stdlib / fmt

2/2

stdlib / io

3/4

stdlib / regex

10/10

stdlib / switch

4/4

stdlib / fs

6/6

stdlib / collections

14/16

nesting sweep

24/30

event globbing

4/10

challenges

1/1

aoc 2015

10/44

examples showcase

1/1

examples showcase / language shootout

21/22

How This Works

Every page in this book is backed by a real test in the Koru compiler's regression suite. When you see a ✓, that means the code actually compiles and runs correctly. When you see ✗, you're looking at something we're still working on.

This is living documentation — it can never drift from reality because it IS reality. The tests run on every commit.